profile-native-agent-runtimes

/home/avalon/.hermes/skills/autonomous-ai-agents/profile-native-agent-runtimes/SKILL.md · raw

Profile-Native Agent Runtimes

Use this skill when

A product database contains logical Hermes profiles, but execution still flows through one global agent transport.
One tenant needs a portfolio profile plus isolated business profiles.
Chat, scheduled reasoning, plugins, secrets, and product-side authorization must agree on one profile identity.
You are adding or reviewing Hermes multiplex API routing through /p/<profile>/....
You must prove that a runtime binding is operational and isolated before cutover.

This skill governs the execution boundary, not the product's domain model. Projects, reviews, jobs, commands, and business records remain owned by the product database; Hermes profiles identify reasoning operators and provenance.

Core invariant

thread or job
  → hermes_profile_id
  → freshly loaded profile row
  → exact opaque runtime_ref
  → trusted tenant API origin/key
  → /p/<profile-slug>/...
  → isolated profile home/session/secrets
  → profile-bound product capability
  → canonical domain command
  → project-owned state + profile provenance

If any arrow cannot be proven, enforcement must fail closed. Never route to a shared/global conductor as a recovery path.

Procedure

Reconstruct authority before editing. Trace profile schema, router, chat transport, job schema/claiming, plugin configuration, capability broker, audit provenance, and tier topology. Distinguish a profile record from a real runtime boundary.
Reuse Hermes's native multiplexer. Prefer one tenant Hermes API with profile-prefixed routes and profile homes over inventing a second supervisor or mutating process-global environment variables.
Define one versioned runtime contract. Planning, materialization, activation, chat, jobs, and appliance configuration must use the same contract and directory layout.
Keep runtime_ref opaque. It is server-issued identity, never a URL/path and never model-supplied authority. Compare it to the freshly loaded profile row on every dispatch boundary.
Materialize private roots. Make the tenant root API-only and suppress broad bundled skills. Make each profile home private and isolate sessions, memory, knowledge, cron, workspace, plugins, config, and secrets.
Bind connectors locally. Profile-local config and scoped secret lookup override hostile ambient values. Do not expose caller-selectable project authority when a business profile already determines the project.
Probe before activation. Through the exact profile prefix, require detailed health plus Caduceus toolset/tool and skill evidence. Activate transactionally only if status and runtime binding are unchanged; persist profile-attributed evidence.
Route the whole chat run. Session creation/resume, messages, history, run polling/events, streaming, and interruption must retain the same resolved runtime descriptor.
Own reasoning jobs by profile. Persist and verify hermes_profile_id plus project_id where applicable. Include profile identity in recurring-job deduplication. Portfolio work uses the portfolio profile; business work uses its owning business profile.
Derive product authority from the profile. Bind keys to hermes_profile_id, reload profile authority per request, require explicit capabilities, treat supplied project IDs only as consistency assertions, and use field-level grants for portfolio reads. Delegate portfolio business mutations to the owning business profile.
Prove isolation before cutover. Run disposable Normal and two-business Pro live HTTP canaries, then adversarial cross-profile resume/targeting, stale binding, revocation, restart, job, and rollback tests.
Integrate parallel work skeptically. Worker completion notices are not evidence. Inspect branches and diffs, rerun focused tests, reconcile duplicate contracts immediately, then run integrated and broad suites.

Security invariants

Customer profiles do not receive ambient host, Docker, SSH, unrestricted terminal/file, plugin administration, raw credentials, product source/database, or self-modification authority.
Business scope is immutable and server-derived.
Portfolio access is not an all-business wildcard: business reads require explicit grants and mutations execute under the owning business profile.
Capabilities remain private and never enter generated public manifests, model context, or logs.
Missing, inactive, paused, unhealthy, stale, contradictory, or revoked bindings deny before handler effects.
Legacy/shadow modes may preserve migration behavior only when explicitly configured and must never be presented as isolated execution.

Verification gates

Focused RED/GREEN tests for planning, permissions, readiness, activation, chat transport, plugin scope, Gate authorization, and profile-owned jobs.
Real Hermes plugin-loader smoke with temporary profile homes.
Exact-prefix HTTP assertions: no unprefixed/global agent endpoints in enforcement mode.
Normal canary: one persistent business profile and no portfolio runtime.
Pro canary: one portfolio plus at least two businesses with distinct session, secret, memory, cron, workspace, plugin, and job state.
Revocation, restart, and rollback of one profile leave its neighbor usable and unchanged.
git diff --check, focused surrounding suites, broad regression suite, and security/spec review before push or cutover.

Pitfalls

The router resolves runtime_ref, but chat discards it.
Manager and materializer encode different contracts or home layouts.
Profile project authority appears in ambient environment or model-facing config.
Plugin code reads process-global secrets under a multiplexed runtime.
Generic health passes without proving the required plugin/tool/skill surface.
Portfolio keys can mutate arbitrary business routes.
Recurring jobs deduplicate globally by kind and collapse separate business schedules.
A timed-out worker's partial patch is discarded without inspection, or a worker's green summary is trusted without rerunning tests.
Unit tests pass while no live two-business isolation canary exists.

Detailed reference

Read references/runtime-contract-pattern.md for concrete validation rules, filesystem/materialization guidance, activation logic, chat/job routing coverage, authorization design, and the complete TDD/canary sequence.