[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M723EKT6XDRQ2S3DME9R9564":3,"skill-same:01M723EKT6XDRQ2S3DME9R9564":49},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":28,"commitSha":29,"skillDirectory":30,"forksCount":31,"repositoryHtmlUrl":32,"repositoryHomepageUrl":6,"ownerHtmlUrl":33,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":34,"install":35,"resources":48},"01M723EKT6XDRQ2S3DME9R9564","use-the-harbor-protocol",null,"Build a chat UI (or any other client) against the Harbor Protocol directly — auth headers, the typed wire surface, events.subscribe SSE, the topology_snapshot capability, artifact upload. Use when shipping a frontend that talks to the runtime WITHOUT the bundled Console — a custom chatbot, a messaging bot, a TUI, an IDE plugin.","hurtener\u002FHarbor","hurtener","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F117486687?v=4","01M723BZXGKZDHCZ9JHRV24W4D","Santi Benvenuto","01M723BZY77XR795N9PK1BS4GX",6,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fhurtener\u002FHarbor\u002Fblob\u002Fmain\u002Fdocs\u002Fskills\u002Fuse-the-harbor-protocol\u002FSKILL.md",[],[],"2026-11-10 18:39:20",false,"---\nname: use-the-harbor-protocol\ndescription: \"Build a chat UI (or any other client) against the Harbor Protocol directly — auth headers, the typed wire surface, events.subscribe SSE, the topology_snapshot capability, artifact upload. Use when shipping a frontend that talks to the runtime WITHOUT the bundled Console — a custom chatbot, a messaging bot, a TUI, an IDE plugin.\"\nlicense: Apache-2.0\nmetadata:\n  framework: harbor\n  surface: protocol\n  verbs: \"\"\n---\n\n# Use the Harbor Protocol\n\n## Bounded execution and artifact bearers\n\nAn issuer can bind a Start request to an external operation with signed\n`execution_operation_id`, `execution_idempotency_key`, and\n`execution_start_sha256` claims. Sign the exact raw JSON body sent to\n`POST \u002Fv1\u002Fcontrol\u002Fstart`, set the same idempotency key in that body, and pin\n`session_reach` to the token's single session. Harbor rejects a changed body\nor session before admission and retains the opaque operation ID through task\nrecovery for downstream tool-token exchange. Tool arguments cannot set it.\n\nFor browser artifact transfer, issue a short-lived signed `artifact_transfer`\nobject with `mode`, `id`, and `max_bytes`, empty elevated scopes\u002Fagent reach,\nand one exact `session_reach`. `read` permits only `artifacts.get` for that\nreference when its full size fits the bound. `write` permits only\n`artifacts.put` into the named namespace, with `source: \"user_upload\"`, no\ntask scope, and a body within the bound. Write namespaces use ASCII letters,\ndigits, `_`, or `-` only. The normal identity check still\napplies; use the returned artifact reference in a later Start request. The\nbearer can be retried until JWT expiry; it does not enforce single use.\n\nAn admin with signed reach to an Agent can send its ID as\n`runtime.info.effective_agent_id`. A successful response carries\n`effective_run_completion` with `state: \"active\"` and the resolved tool and\ntimeout, or explicit `state: \"off\"`. Ordinary runtime posture omits that\nfield; absence on an older runtime is not an `off` answer. Go callers can use\n`protocolclient.RuntimeClient.RuntimeInfoForAgent(ctx, agentID)` for this\nrequest. `active` reports configuration; it does not probe tool connectivity.\n\n## MCP source ownership\n\nUse returned MCP source\u002Ftool IDs for new calls. Boot-configured infrastructure\nis shared, while runtime-added sources require the verified owning tenant and\ncurrent effective agent configuration; personal sources also require the user.\nAgent-owned sources can share a logical name across tenants and agents without\nsharing the same physical source ID. Historical agent source\u002FApp\u002Ftool references\nresolve only under the verified tenant and admitted effective agent, with fresh\nApp generation checks. A name never grants reach or selects a tenant.\n\nFor durable policy keys, use tool `logical_id` and MCP server `logical_name`;\nkeep physical `id`\u002F`name` for calls. Admin configuration discovery can request\n`view: \"configuration\"` on `tools.list` and `tools.describe`, always with an\n`agent_id` admitted by signed reach. This includes owned disabled tools and both\nloading modes. Default reads retain execution exposure, and configuration\nreads preserve tenant\u002Fuser\u002Fsource\u002Frevision\u002Fauth constraints. They never grant\npermission to execute a disabled tool.\n\nClients negotiate `tools_configuration_view_v1` before sending the configuration\nview selector. It is advertised only when the owned-source configuration backend\nis wired. An older runtime receives no selector; clients do not retry a refused\nconfiguration request by downgrading its view.\n\nConfiguration-view list responses and manifests carry an opaque `revision`\n(D-491). To revalidate a cached inventory cheaply, send the cached value as\n`if_revision` on page 1: a match answers `{revision, not_modified: true}` with\nno rows. Later pages ignore `if_revision`; compare each page's `revision` with\npage 1's and restart once on a mismatch. The revision covers structural row\nfields, including the row-level `side_effect` and `loading_mode` (so no\nper-tool `tools.describe` is needed for them), and excludes `oauth_status`,\n`approval_policy`, `last_used_at` and `display_modes`. `not_modified` speaks\nonly for the structural rows of the identical query; `if_revision` combined\nwith `filter.oauth_statuses` or `filter.approval_policies` is refused. Key a client cache by\nruntime, tenant, agent, acting user and filter. `tools.catalog.changed` is only\na hint to drop short-lived caches early; never rely on it for correctness.\nOnly send `if_revision` to a runtime whose release includes D-491 — older\nruntimes reject the unknown field.\n\n## Route-aware provider checks\n\nThe existing admin-scoped `llm.posture` provider `validate` and `discover`\noperations accept an optional opaque provider-route selector plus an effective\nAgent ID. The Agent must be in the caller's signed reach. A successful response\nechoes only route\u002Fconnection generations and readiness; credentials, endpoints,\nprovider bodies, and identity values are never returned. Omitting the route\nkeeps the runtime-default provider-catalog behavior.\n\n## Operator-managed agent packs\n\n### Same-runtime inspect and copy (Phase 267 \u002F D-456)\n\nThe additive admin methods `agent_config.agent_packs.inspect` and\n`agent_config.agent_packs.copy` operate only on registrations in the same\nruntime and verified tenant. They require the verified identity triple, the\n`admin` scope, and signed effective-agent reach to every addressed source and\ntarget agent. `agent_id` is registration metadata, not an isolation principal;\nthe request body cannot select a tenant, user, or authority.\n\n`POST \u002Fv1\u002Fagent_config\u002Fagent_packs\u002Finspect` returns a bounded, complete\nprojection of the addressed agent's operator pack. `boot_packs` and\n`revision_packs` retain their distinct complete bodies when both layers\ncontribute; `effective_packs` is the deterministic merged view. Every entry\nreports exact `source` (`boot`, `revision`, or effective `both`),\n`semantic_hash`, and boolean `editable`. The response also carries\n`composition_hash` and `boot_pack_set_hash` as canonical lowercase 64-character\nSHA-256 hexadecimal values, including empty-set values. Equal boot\u002Frevision content is\ndeduplicated only in `effective_packs`; a differing same-name pair fails\nclosed. Boot-owned entries remain read-only.\n\n`POST \u002Fv1\u002Fagent_config\u002Fagent_packs\u002Fcopy` accepts a bounded `pack_ids` array,\nincluding an empty array to remove untouched server-stamped copies from that\nsource during reconciliation. Omitted or `null` `pack_ids` is invalid; only an\nexplicit empty array authorizes removal. The request also carries\n`expected_source_composition_hash`,\n`expected_target_composition_hash`, and an opaque `idempotency_key`. The server\nrechecks the immutable source hash\u002Frevision and applies the authoritative\ntarget composition-hash CAS. All selected bodies are recorded in one\nall-or-nothing target revision; the response is bounded, echoes the exact\ntarget `composition_hash` and `boot_pack_set_hash` values (including\ndeterministic empty-set values), and never carries the pack body. An exact\nresponse-loss retry converges, a reused key with different\narguments fails, and equal selected content is a true no-op. A differing\nindependently authored target or an edited prior copy fails closed without\noverwriting another selected pack.\n\nCopy provenance is server-stamped in `origin_ref` with source agent and\nrevision (or boot source), selected pack ID, source semantic hash, operation\ndigest, and target binding; the durable operation record binds the sorted\nselection and both expected composition hashes. Reconciliation may update or\nremove only entries whose current hashes still equal their last-applied values\non the same lineage; edited targets remain intact and surface a bounded\nconflict. A boot source can be copied into an editable durable target, but the\nsource is never mutated.\nTarget changes continue through `agent_config.agent_packs.propose`, `.commit`,\nand `.remove`. There is no cross-runtime federation, portable catalog, or\ncapability grant through pack metadata. Use capability discovery and the typed\nerror response before invoking either route.\n\n## Same-runtime organization skill publications (HA-68 \u002F D-430)\n\nOrganization publications are a separate, additive Protocol surface from the\nper-agent pack verbs below. Administrators use\n`skills.publications.publish`, `.list`, `.get`, `.publish_successor`, and\n`.retire`; callers use `.available`, `.install`, `.update`, `.remove`, and\n`.references.list`. Every request still carries the verified identity triple.\nAdmin methods require the verified admin scope. Caller methods additionally\nrequire signed reach to the effective agent; the request body cannot choose a\ntenant, user, agent, or authority.\n\nThe publication is immutable and content-addressed. A successor or retirement\nuses the exact expected generation\u002Fhash, and idempotency keys replay the same\nbounded result. List\u002Fget\u002Freference\u002Freceipt responses are metadata-only: they\ncarry the publication and revision ids, generation, content hash, lifecycle\nstate, and same-runtime binding, never the skill body. The body is resolved\nonly by the authorized runtime composition path after rechecking identity,\nreach, active state, runtime id, generation, and hash. A retired, stale,\nforeign-runtime, or unreachable reference is a typed failure; there is no\nlatest-revision fallback or cross-runtime catalog.\n\nUse the generated [methods](..\u002F..\u002Fprotocol\u002Fmethods.md), [errors](..\u002F..\u002Fprotocol\u002Ferrors.md),\nand [types](..\u002F..\u002Fprotocol\u002Ftypes.md) pages as the wire reference. The\npublication domain and canonical wire registration may exist before a runtime\nadvertises the complete surface; a client must follow capability discovery and\nmust not claim the route is live until the transport\u002Fcomposition integration\ngate is present. See the Phase 250 plan for the exact acceptance matrix.\n\n### Publication reads and candidates (D-508)\n\nRuntimes that advertise `skill_reads` serve two body reads. `skills.publications.read`\n(`publication_id`, optional `revision_id`) returns the revision's structured\n`skill` and its canonical `SKILL.md` text as `document`: an admin reads any\nrevision of any publication in the tenant; any other verified caller reads only\nan active publication's current revision (exactly what `.available` lists), and\nanything else is `skill_publication_not_found`.\n\nRuntimes that advertise `skill_publication_candidates` serve a reviewed\nsubmission path. `skills.publications.candidates.submit` (`agent_id`, `name`,\noptional `target_publication_id` and `note`, `idempotency_key`) freezes the\ncaller's own personal skill on an Agent in signed reach into a pending\ncandidate; a skill with support files is refused with\n`candidate_support_files_unsupported` (publications carry no support files), and\na second pending candidate for the same name with `candidate_pending_exists`.\n`.list` shows an admin every candidate in the tenant and anyone else only their\nown; `.read` returns the frozen body to an admin or the submitter (otherwise\n`not_found`); `.withdraw` lets the submitter drop a pending one. Admins\n`.accept` with `mode` `new` (optional `name`) or `successor` (`publication_id`\nplus the publication's expected generation and content hash), or `.reject` with\na `decision_note`; both take the candidate's `expected_generation`. Acceptance\ngoes through the ordinary publication store, records the resulting publication,\nrevision and replaced content hash on the candidate, and is safe to retry: a\nretry, by the same or another admin, never publishes twice.\n\nThe admin-scoped `agent_config.agent_packs.list|upsert|remove|propose|commit`\nmethods manage a per-agent skill pack. Direct writes use the dedicated verbs;\n`agent_config.set_revision` rejects the pack section. Governed authoring requires\n`expected_content_hash` on both `propose` and `commit`; commit must send the\nopaque single-use `proposal_id`, exact `reviewed_hash`, and unchanged body. The\nserver-bound proposal receipt is not forgeable from the returned hash or\nprovenance string.\n\n### Personal skill export\n\n`agent_config.user.skills.export` (`POST \u002Fv1\u002Fagent_config\u002Fuser\u002Fskills\u002Fexport`)\naccepts `identity`, `agent_id`, and the canonical personal skill `name`. Like\n`user.skills.list`, it requires the verified caller and signed reach to an\nactive Agent, without an admin or `agent_config:user` scope. It exports only\nthat caller's durable user-scope package installed through reviewed import;\na same-name shared, foreign, or legacy upsert-only skill is never a fallback.\n\nThe response carries `artifact` (the normal `ArtifactRef`), `package_hash`,\n`name`, `size_bytes`, and `protocol_version`. Retrieve its bytes through\n`artifacts.get` or `artifacts.get_ref`. The ZIP has root `SKILL.md` and all\npackage support files and can enter the normal reviewed import flow. A\npackage installed from a single Markdown document exports in the same form. The\npackage hash identifies package content; the artifact SHA256 identifies the\nZIP bytes. Export writes only the caller-owned artifact, with no skill,\nmembership, or revision change. Missing installed packages, including legacy upsert-only rows, return\n`not_found`.\n\n### Personal skill read\n\n`agent_config.user.skills.read` (`POST \u002Fv1\u002Fagent_config\u002Fuser\u002Fskills\u002Fread`)\ntakes the same `identity`, `agent_id` and `name` as export and the same\nauthority. It returns the logical `skill`, its canonical `SKILL.md` text as\n`document` (the bytes export puts at the archive root), the `support_files`\nmanifest (`path`, `mime`, `size_bytes`) and `package_hash`. Set `support_path`\nto one manifest path to also get `support_file`: UTF-8 `text` for text-like\nmedia, cut at 256 KiB with `truncated: true`, or `binary: true` otherwise. A\nlegacy upsert-only skill reads as a rendered document with no support files.\nThe read changes nothing.\n\nTo install a complete `SKILL.md` package (with support files) into ONE Agent's\nshared pack, upload it with `artifacts.put`, then call the admin-scoped\n`agent_config.agent_packs.import_validate` (`agent_id`, `artifact_id`). It\nwrites nothing and returns the same review as the personal\n`agent_config.user.skills.import_validate`, an opaque `proposal_token` bound to\nyour identity, the Agent, the artifact and the package hash, and the\ncomposition witness `expected_content_hash`. `import_commit` echoes the token,\n`name`, `reviewed_package_hash` and witness; a moved witness is\n`revision_conflict`, an existing item of the same name needs `replace: true`,\nand a retry of the same token returns `replayed: true` without a second write.\nThe item then carries a read-only `package_hash`; its support files are\nruntime-owned Agent state for every caller with reach to the Agent. If a\ncommit fails after publishing, retry the same token to finish it. Packages no\nactive item references are released; `agent_packs.copy` refuses a\npackage-backed item. A package never grants tools.\n\nThe Harbor Protocol is the canonical event\u002Fstate contract between Runtime and any client. The bundled Console is one consumer; this skill walks the path for building your own. A working chatbot UI is achievable in a day on top of the Protocol — the wire is small, typed, and stable.\n\nThree properties make this practical:\n\n1. **A generated, drift-gated contract reference** — the published [Protocol adoption track](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002F) carries four pages (methods \u002F events \u002F errors \u002F types) emitted by `cmd\u002Fharbor-gen-protocol-docs` from the Go single sources and gated in CI by `make protocol-docs-gen-check`, plus an executed quickstart, five choreography guides, a worked build-a-client walkthrough, and the conformance-certification path. For typed TS wire shapes, vendor the generated external-client module `examples\u002Fprotocol-clients\u002Fevent-viewer-ts\u002Fharbor-protocol.gen.ts` (emitted by `cmd\u002Fharbor-protocol-ts-types`, drift-gated by `make protocol-ts-types-gen-check`); the Console's `protocol.ts` is the hand-maintained client when you also want the typed `HarborClient` (the FULL Console-`protocol.ts` *generator* stays deferred per D-132, name reserved).\n2. **Capability advertisement** — `runtime.info.capabilities` tells you at attach which Protocol surfaces this Runtime advertises (`task_control`, `events_subscribe`, `runtime_posture`, `topology_snapshot`, `state_snapshots`, `agent_config`). Your UI degrades gracefully on stripped-down runtimes.\n3. **Stable Protocol versioning** — breaking changes go through a deprecation window; same-major versions are compatible. Pin the major in your client; tolerate additive change. The full adopter contract is the published [versioning & compatibility choreography](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fversioning-and-compatibility).\n\nGo clients should use `github.com\u002Fhurtener\u002FHarbor\u002Fsdk\u002Fprotocolclient` rather\nthan reimplementing the HTTP and SSE layers below. Construct one client with an\ninjected `TokenSource`, then use `WithSession` for each conversation. The clones\nare immutable and safe to use concurrently; token discovery and reconnect\nbackoff remain application policy.\n\n```go\nclient, err := protocolclient.New(protocolclient.Connection{\n    BaseURL: \"http:\u002F\u002F127.0.0.1:18080\",\n    Token: protocolclient.StaticToken(token),\n    Identity: protocolclient.IdentityScope{\n        Tenant: \"dev\", User: \"dev\", Session: \"conversation-1\",\n    },\n})\nif err != nil {\n    return err\n}\n\ninfo, err := client.RuntimeInfo(ctx) \u002F\u002F validates Protocol-major compatibility\nstream, err := client.Subscribe(ctx, protocolclient.StreamOptions{\n    LastEventID: lastSeenSequence,\n})\nif err != nil {\n    return err\n}\ndefer stream.Close()\n```\n\nThe client resolves the token for every request, so a refreshing `TokenSource`\ncan replace an expired credential without rebuilding session clones. REST\nfailures are `*protocolclient.Error` values carrying both HTTP `Status` and the\ncanonical Protocol `Code`. `EventStream.Close` cancels and joins its reader;\ncallers own reconnect timing and pass the last frame's `ID` back as\n`StreamOptions.LastEventID`.\n\nThe Protocol is what makes Harbor headless. The Runtime never imports Console code; the Console never reads internal Runtime objects. Your UI sits in the same posture as the Console.\n\n## 1. The wire — base URL, auth, identity\n\nThis same wire surface is served by any production Harbor Protocol server — the stock `harbor serve` binary **or** an external Go binary built with `harbor scaffold --with-server` (which reaches the Protocol through the public `sdk\u002Fserver` facade; see [`scaffold-a-harbor-agent`](..\u002Fscaffold-a-harbor-agent\u002FSKILL.md)). Both enforce the identical JWKS auth posture below, so a client written against one drives the other unchanged.\n\nThe wire is **REST-per-method**: each Protocol method is its own route under `\u002Fv1\u002F`, you POST a flat JSON body, and you get a flat JSON response back — there is no JSON-RPC envelope. Every request carries:\n\n```http\nPOST \u002Fv1\u002Fcontrol\u002Fstart HTTP\u002F1.1\nHost: 127.0.0.1:18080\nContent-Type: application\u002Fjson\nAuthorization: Bearer \u003CJWT>\nX-Harbor-Tenant: \u003Ctenant_id>\nX-Harbor-User: \u003Cuser_id>\nX-Harbor-Session: \u003Csession_id>\n```\n\n- **Bearer JWT**: RS256\u002FRS384\u002FRS512\u002FES256\u002FES384\u002FES512 signed token. Issuer + audience match the Runtime's `identity:` block, exactly — `harbor serve` hard-rejects an `iss`\u002F`aud` mismatch with `401 auth_rejected`. For `harbor dev`, the ephemeral `HARBOR_DEV_TOKEN` (printed on stderr) is what you use — see [`run-the-dev-loop`](..\u002Frun-the-dev-loop\u002FSKILL.md). For **production** (`harbor serve` mints no token), obtain a JWT from your IdP or self-issue one — the full setup (OIDC app registration, the `(tenant, user, session)` + `scopes` claim mapping, the `iss`\u002F`aud` exact-match contract, and the no-IdP `harbor token` on-ramp) is the [production identity setup guide](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fproduction-identity-setup).\n- **`X-Harbor-Session`**: the per-request session selector (D-171). The connection JWT verifies the WHO (`tenant` + `user`) and the scopes; the **session is chosen per-conversation** by this header and may differ on every request — the connection token is a per-backend credential, not a single-session pin. A new session id is a new conversation (create-on-first-use on the first `start`). The token's `session` claim is a back-compat **default** used only when the header is absent. `X-Harbor-Tenant` \u002F `X-Harbor-User` can never widen the JWT-verified principal. Every storage call still filters by the full `(tenant, user, session)` triple — no cross-session leakage. Full Console contract: [`docs\u002Fnotes\u002Fsession-model-contract.md`](..\u002F..\u002Fnotes\u002Fsession-model-contract.md).\n  - **Optional `session_reach` claim (D-409).** A bearer minted with the signed `session_reach` claim is pinned to exactly those session IDs: the effective session — from this header, the SSE `?session=` projection, or the token `session` default — must be a member, or the request fails closed `403 {\"code\": \"scope_mismatch\"}` before any handler side effect. **Absent claim = this dynamic per-request selection is unchanged.** A coordinating client that must mint a session-specific bearer whose authority cannot be re-pointed at another session uses this claim; see [`configure-production-identity`](..\u002Fconfigure-production-identity\u002FSKILL.md) §2 for the claim shape.\n\nFor an in-flight text correction, `user_message` with a nonempty `message`\ninterrupts the planning attempt and re-plans with that text as user input.\nIt does not cancel the run or undo completed actions. Its acknowledgement is\nadmission, not proof that the correction has reached the model: follow\n`control.applied` and subsequent run events. New attachments belong on `start`.\nPending approval requests from the obsolete plan are withdrawn, not approved;\nqueued tool calls and further retries are refused. Already-started calls retain\ntheir outcomes. A required withdrawal failure stops the run explicitly.\nSee the [task-control choreography](..\u002F..\u002Fsite\u002Fprotocol\u002Ftask-control.md) for\nthe current execution boundaries and remaining release-acceptance work.\n\nRoutes group by surface family:\n\n- **Task control** — `start` plus the nine steering verbs (`cancel` \u002F `pause` \u002F `resume` \u002F `redirect` \u002F `inject_context` \u002F `approve` \u002F `reject` \u002F `prioritize` \u002F `user_message`) all POST to `POST \u002Fv1\u002Fcontrol\u002F{method}` (e.g. `\u002Fv1\u002Fcontrol\u002Fstart`, `\u002Fv1\u002Fcontrol\u002Fcancel`). The read-only posture methods (`runtime.info`, `topology.snapshot`) and `artifacts.put` share this route shape.\n- **Event stream** — `GET \u002Fv1\u002Fevents` (SSE; see §4).\n- **Read surfaces** group by family under their own prefix: `POST \u002Fv1\u002Ftasks\u002F{method}` (e.g. `\u002Fv1\u002Ftasks\u002Fget`), `POST \u002Fv1\u002Ftools\u002F{method}`, `POST \u002Fv1\u002Fsessions\u002F{method}`, `POST \u002Fv1\u002Fmemory\u002F{method}`, and so on.\n- **Admin control surfaces** are family-prefixed and gate on the verified `admin` scope claim (a non-admin caller gets `403 {\"code\": \"scope_mismatch\"}`). The governance tenant-default LLM overrides are here: `POST \u002Fv1\u002Fgovernance\u002Fset_tenant_overrides` sets a tenant's default model \u002F additive extra-instructions \u002F temperature \u002F max-tokens \u002F reasoning-effort live (no redeploy; applied to every session's next run), and `POST \u002Fv1\u002Fgovernance\u002Fget_tenant_overrides` reads them back. `POST \u002Fv1\u002Fgovernance\u002Frotate_key` rotates the LLM provider API key live (no redeploy; the swap is **immediate** — the next call uses the new key). The new key is a **secret**: send it on the request body only; the response + the `governance.key_rotated` event carry only a `sha256:` fingerprint, never the key. `POST \u002Fv1\u002Fgovernance\u002Fset_posture` writes the identity-tier policy table live (no redeploy) — the write sibling of the read-only `governance.posture`. It is a **FULL REPLACE** of the whole table (`{default_tier, identity_tiers: {\u003Ctier>: {budget_ceiling_usd, max_tokens, rate_limit: {capacity, refill_tokens, refill_interval_ms}}}}`), never a partial merge, and carries **no identity field** (authority is server-side). A submitted table that OMITS or zeroes a ceiling the current effective policy enforces — including a `default_tier` repoint whose new tier drops a dimension the old default enforced — is rejected fail-closed `400 {\"code\": \"invalid_request\"}` **before** any state write — never budget-widening. It gates on `admin` **ONLY** (a `console:fleet`-only token — the read's second gate — gets `403 {\"code\": \"scope_mismatch\"}`, so a leaked read-only fleet token cannot widen a budget). What you set is what the next `governance.posture` returns (round-trip); on a fully-latent runtime (no enforcement wrapper composed at boot) the response carries `enforcement_pending_restart: true` rather than a silent inert 200. (`governance.posture` \u002F `llm.posture` remain read-only posture methods.) The tenant default composes UNDER a per-session next-turn override — `POST \u002Fv1\u002Fruns\u002Fset_overrides` records a one-shot override (reasoning-effort \u002F temperature \u002F max-tokens \u002F `system_prompt_override` (a full prompt **replace**) \u002F `extra_instructions` (an **additive** guidance block) \u002F `model` (the session model swap)) for the caller's own session; the effective per-run value resolves **session › per-agent › tenant-wide baseline › config** (the session override wins, then the per-agent agent-config LLM-params layer below, then the tenant-wide baseline; the session slot is consumed once on the next run; the slot map is BOUNDED — a runtime holding 4096 unconsumed slots evicts the oldest-recorded one to admit a new session's, so an override recorded and then never followed by a message is not guaranteed to still be there much later. Record it immediately before the message it is for, which is the intended usage anyway). **`extra_instructions` is the ordinary caller's one-run personalization field (D-387):** it does not replace the admin-set tenant guidance and is not admin-gated. A blank value is a no-op; a nonblank value renders separately in an escaped `\u003Cuser_personalization>` block, survives `system_prompt_override`, and cannot forge or erase the operator-owned `\u003Cadditional_guidance>` section. Use it for preferences such as tone, format, or response style. Put retrieved or recalled content in `start.caller_memory`, whose fixed read-only wrapper is the data path. **The agent-config control plane** is the admin family `POST \u002Fv1\u002Fagent_config\u002F*`: it versions an agent's configuration as immutable, content-addressed revisions where the active config is a pointer to a revision — `set_revision` writes a new revision and advances the pointer, `list_revisions` returns the chain newest-first, `diff` compares two revisions, `rollback` repoints to an existing revision (never mutating it), and `get` reads the active one. Skills control is the first consumer: `POST \u002Fv1\u002Fagent_config\u002Fskills\u002Fupsert` \u002F `skills\u002Fdelete` \u002F `skills\u002Flist` manage an agent's skills, recording each membership change as a config revision (so skills inherit diff + rollback) and emitting `agent.config.revised` \u002F `agent.config.reverted`. Two NON-admin skill rungs sit below it, both **claim-free** (a valid identity is enough — a personal skill can never widen capability, because the capability filter is default-deny and the injection-time redactor scrubs any tool a skill names outside the run's allowed set): `POST \u002Fv1\u002Fagent_config\u002Fsession\u002Fskills\u002F{list,upsert,delete}` manage **ephemeral** personal skills (session-scoped, gone with the conversation), and `POST \u002Fv1\u002Fagent_config\u002Fuser\u002Fskills\u002F{list,upsert,delete}` manage **durable-by-default** personal skills (`user` names the durable STORAGE scope, keyed `(tenant, user)` with the session zeroed — the skill persists across ALL of that user's conversations and rides the driver for restart durability: in-memory ephemeral, sqlite\u002Fpostgres durable). The user rung's upsert\u002Fdelete record a durable membership revision (diff\u002Frollback parity) and the run-start projection keeps a durable user skill visible even when an admin pins a skills membership. `POST \u002Fv1\u002Fagent_config\u002Fset_prompt_layers` sets the agent's **layered system prompt** — an operator-owned `base` layer plus an optional `user` layer that composes *above* the base without replacing it (the composition order is the trust boundary; a `user`-only writer can extend guidance but never weaken the operator base). It replaces only the prompt-layer section (skills + tool exposure are preserved) and records a revision; at run start the durable base\u002Fuser resolve under the per-session `system_prompt_override` (which replaces the whole base+user spine for one message) and above the additive `extra_instructions`. `POST \u002Fv1\u002Fagent_config\u002Fset_llm_params` pins the agent's **per-agent LLM parameters** (`model` \u002F `temperature` \u002F `max_tokens` \u002F `reasoning_effort`) as a versioned section — a set `model` is validated against the configured `ModelProfiles` at set time (an unknown model is rejected, never persisted). It replaces only the LLM-params section (the prompt-layer + skills + tool-exposure + connection + hooks sections are preserved) and overrides the tenant-wide baseline per field for the agent's next run (resolution **session › per-agent › tenant-wide baseline › config**). `POST \u002Fv1\u002Fagent_config\u002Fset_tool_exposure` sets the agent's **MCP-exposure \u002F per-tool policy**: `paused_servers` (MCP source ids excluded next-run, live transport stays warm), `disabled_tools` (individually-excluded tools), and the runtime **loading-mode overrides** — `server_loading_modes` (per MCP source id, applies to TOOL-form descriptors only) and `tool_loading_modes` (exact per-tool name, unconditional), each valued `always`\u002F`deferred`; an unknown value is rejected `400 {\"code\": \"invalid_request\"}` **before** any revision is recorded. A `deferred` override hides the tool from the next run's prompt-time catalog while it stays `tool_search`-discoverable and dispatch-callable (the two-turn discovery cycle is untouched); a paused server \u002F disabled tool stays strictly stronger — hidden from BOTH the prompt and dispatch. Precedence: per-tool override > per-server override > the boot `tools.entries[].loading_mode` > the driver default. It replaces only the tool-exposure section (skills + prompt layers + connections + LLM params + hooks are preserved). The agent's **MCP connection set** is managed by `POST \u002Fv1\u002Fagent_config\u002Fadd_mcp_connection` (register a runtime-added MCP server as a new revision) and `POST \u002Fv1\u002Fagent_config\u002Fremove_mcp_connection` (drop a runtime-added descriptor, pruning that server's tool-exposure residue atomically and detaching it at the next run-start reconcile; a boot-declared yaml server or an unknown name is refused loud) — both ride the same revision machinery (diff \u002F rollback \u002F next-turn projection). **A declared connection is RE-ESTABLISHED at the next run start when the live runtime does not carry it** — after a process restart, or after a `rollback` to a revision that re-declares a previously-removed connection: the run-start reconcile attaches it under the same `(tenant, agent_id)` owner, through the same lifecycle the add verb drives, and emits `mcp.connection.reattached`. **The claim is scoped, and the bound matters to you.** A connection whose transport depended on the operator-supplied auth `headers` you sent to `add_mcp_connection` is NOT restart-survivable — those headers are secret and are never persisted in a revision, so the re-attach dials without them, a server that required one answers `401`, and you must re-run `add_mcp_connection` to supply them again. A connection bound by `oauth_provider` (a NAME, not a secret) IS re-established: the attach resolves the binding by name and touches no token at all, so a missing or expired consent does not block the re-attach — it surfaces later, on the first tool call, as the shipped `tool.auth_required` pause. Anything that could not be re-established is REPORTED rather than silently absent: `mcp.connection.reattach_failed` carries a stable class in its `state` field — `transport_failed` (retryable; the third party did not answer, and the header case above lands here), `stdio_not_allowed`, `injection_disabled`, `oauth_binding`, `owner_conflict`, `ambiguous_server_id` (none of which heal by re-dialling). Both events reuse the connection-lifecycle payload; the discriminator between a reconcile and an admin add is the author's `run_id` — EMPTY for an admin add, populated for a reconcile. A permanently-failing connection is re-dialled on a bounded backoff rather than at every run start, and the count of suppressed attempts rides the next emitted event. No new Protocol method: subscribe to the two event types, or correlate `agent_config.get`'s declared set against `mcp.servers.list`'s live one. The full-payload `set_revision` accepts the same `connections.servers[]` descriptors and holds them to the SAME shape rules `add_mcp_connection` enforces — transport\u002FURL\u002Fcommand coherence (`stdio` needs an argv `command` and no `url`; `http` needs a `url` and no `command`), a non-empty `name`, one auth mode per connection, no reserved `_meta` annotation key, and https-origin-only `oauth_discovery_allowed_origins` (which `stdio` must not carry at all). A malformed descriptor is rejected `400 {\"code\": \"invalid_request\"}` naming the offending `connections.servers[i]`, and the whole set is refused — nothing persisted, the active revision unchanged. A `stdio` descriptor also runs the same fail-closed command allowlist `add_mcp_connection` enforces: an un-allowlisted `command[0]` is refused `403 {\"code\": \"scope_mismatch\"}` at BOTH doors, and a deployment that declares no allowlist admits no `stdio` connection at all. A well-formed set round-trips its `oauth_discovery_allowed_origins` through `get` \u002F `list_revisions` \u002F `diff`, persisted in normalised form (trimmed name\u002FURL, de-duplicated origins) so both doors record identical bytes for the same input. **Artifact-byte egress (D-359):** a connection descriptor MAY additionally carry `artifact_byte_eligible: true` plus `artifact_params` (`{\u003Cserver-side tool name>: [\u003Cparameter names>]}`) — the declaration that this connection may receive **artifact BYTES**, with the runtime resolving an artifact id the model authored and writing the resolved content into the outbound tool-call body as RFC 4648 §4 standard base64, so a large document reaches the remote tool without transiting the model's context. `artifact_params` REQUIRES `artifact_byte_eligible` on the same connection (a mapping without it is rejected `400 {\"code\": \"invalid_request\"}`, never persisted inert — the flag IS the containment boundary), both are `http`-only (a `stdio` descriptor carrying either is refused on the same rule the other http-only fields use), and the mapping's shape runs the same shared validator at BOTH doors (non-empty tool name, at least one parameter, no empty or duplicate parameter name). Each mapped parameter is additionally validated at **attach** against the server's OWN discovered `inputSchema` — it must be declared there and declared string-typed — so Harbor never asserts an argument shape the server did not publish; a server that later changes its schema fails the next attach loudly rather than the next call silently. The declaration is persisted like every sibling field (round-trips through `get` \u002F `list_revisions` \u002F `diff` \u002F `rollback`, with parameters recorded sorted so both doors produce identical bytes). Unlike the inline `oauth` and `injection` descriptors it sits behind **NO boot opt-in**, and the reason is a plane distinction rather than an oversight: those gates exist because their fields determine where a CREDENTIAL is sent, whereas this determines where a user's own CONTENT is sent — a boundary a shared runtime already accepts by trusting its co-tenant admins (D-301), whose stated remedy is one runtime per tenant. It widens the RECIPIENT, never the reachable artifact SET: resolution runs through the dispatching run's own `(tenant, user, session)`, so a cross-tenant \u002F cross-user \u002F cross-session id answers not-found. Every substitution emits the canonical `mcp.artifact_egressed` event — artifact id, server, tool, parameter, byte count and a `sha256:` digest, **never the bytes** — **fail-closed before the wire request**, so a substitution that could not be recorded does not happen. One substituted value is bounded by `tools.mcp_artifact_egress_max_bytes` (default 8 MiB) and an oversize artifact **fails loud rather than truncating**. Two limits worth knowing before you enable it: artifact bytes are stored as authored (unredacted), so a byte-eligible connection can move whatever an artifact contains; and a byte-mapped parameter is **not reachable from an MCP App's tool callback** (`mcp.apps.call_tool` is browser-driven with no run behind it, so no resolver is seated and the call fails loud rather than being given a second, differently-scoped definition of reach). `POST \u002Fv1\u002Fagent_config\u002Fset_mcp_discovery_origins` (`{agent_id, name, allowed_origins[]}`, FULL-REPLACE) writes a runtime-added **http** connection's OAuth-discovery cross-origin allow-list — the origins the discovery walker may fetch authorization-server metadata from: it records a revision (carrying every sibling section forward) AND applies the allow-list to the live MCP registry so the very next discovery uses it; a revoke prunes the recorded requirement's now-unallowed authorization-server entries, and a rollback revokes the origin live through the owner-scoped run-start reconcile. Every origin runs the shared validator (https `scheme:\u002F\u002Fhost[:port]`, no path\u002FIP-literal), and the allowance is never an SSRF hole — a granted origin resolving private\u002Floopback is still refused at dial. An unknown name, a boot-declared (yaml) name, and a stdio connection each fail loud with a distinct typed error — the boot-declared refusal is a property of the NAME, so it fires even when your own active revision also declares a connection under it. The live half is **owner-scoped**: the allow-list is replaced on the connection your `(tenant, agent_id)` owns, and naming a connection another owner attached (or a boot-declared one) is refused `403 {\"code\": \"scope_mismatch\"}` with the accompanying revision rolled back — no observable effect. A name your revision declares but that is not attached yet is not an error: the response reports `applied_live: false` and the run-start reconcile applies the allowance once the server comes online. The agent's **Protocol-installed OAuth providers** are managed by `POST \u002Fv1\u002Fagent_config\u002Fset_oauth_provider` (install\u002Fupsert) and `POST \u002Fv1\u002Fagent_config\u002Fremove_oauth_provider` (uninstall). The install descriptor is **zero-URL by default** — `{name, driver: \"tokenexchange\", credential_source: \"remote\", credential_broker, scopes?}` — because no admin-writable field may determine where a credential is sent (D-300): the token endpoint, the credential-pull endpoint, the allowed downstream hosts, the audience, and the scope ceiling are all pinned at boot on the named `credential_broker` (a `tools.oauth_credential_brokers[]` entry). By default a write carrying a credential-sink field is rejected `400 {\"code\": \"invalid_request\"}`: `auth_url` \u002F `client_id_env` \u002F `client_secret_env` \u002F a raw `allowed_downstream_hosts` list are rejected **by name** (not on the wire struct, so the decode fails), and `token_url` \u002F `audience` are rejected by the fail-closed **wire-descriptor gate** (`tools.allow_wire_oauth_descriptor` is off — the default, all of production). An empty `credential_source`, an unknown broker, and a name colliding with a boot-declared provider each fail loud too. **Dev-gated full binding (D-340):** behind the boot-only opt-in `tools.allow_wire_oauth_descriptor` (config flag OR the `HARBOR_ALLOW_WIRE_OAUTH_DESCRIPTOR` env; effective posture is the OR, default off) the descriptor MAY instead carry the full binding over the wire — `{name, driver: \"tokenexchange\", credential_source: \"remote\", credential_broker, token_url, audience?, scopes?}` (still NAMING a boot-declared broker for the runtime's own credential custody) — so a coordinator can stand up a new OAuth-fronted MCP server at runtime; the same inline binding is available as an `oauth` object on `add_mcp_connection`'s connection descriptor. Even opted in the relaxation stays bounded: `allowed_downstream_hosts` is **DERIVED** from the connected server's own URL (never a wire field), the wire `token_url` dial faces the identical token-exchange SSRF backstop (private \u002F redirecting endpoints refused), and the runtime's OWN credential custody (the coordinator pull endpoint + service-token env name + org secret) stays 100% boot-declared on the named `credential_broker` — **no credential-source URL, env-var name, or secret ever rides the wire** (an earlier draft's wire `remote{}` credential-pull was removed as an exfil primitive). The opt-in is also a kill-switch — a wire provider is not rebuilt by the run-start reconcile once the opt-in is off. Do NOT enable in production. **Dev-gated per-user credential injection (D-346):** for a RECEIVER-STYLE MCP server (one that authenticates by RECEIVING its credential directly on each request rather than PULLING via RFC 8693), `add_mcp_connection`'s connection descriptor MAY instead carry an `injection` object — `{provider, form: \"header\"|\"basic\"|\"meta\", header?, basic_username?, meta_key?}` — that NAMES a boot-declared `tools.oauth_providers[]` broker and declares WHERE the per-user credential (still broker-pulled per acting user at call time) is placed on the outbound request. It is accepted ONLY behind the fail-closed boot opt-in `tools.allow_wire_injection` (config flag OR the `HARBOR_ALLOW_WIRE_INJECTION` env; effective posture is the OR, default off), a NEW opt-in INDEPENDENT of `allow_wire_oauth_descriptor` (enable either alone). With it off (all of production) a connection carrying any injection field is rejected `400 {\"code\": \"invalid_request\"}`. Only the NON-secret mapping rides the wire; the reachable sink is DERIVED from the connection's own URL + validated against the named broker's boot-declared `allowed_downstream_hosts` (never a wire field), every target key must be redaction-covered (the audit redactor holds the injected value to `***`), and it is mutually exclusive with the bearer `oauth_provider` \u002F inline `oauth` binding (one auth mode per connection). It is PERSISTED in the revision like every other descriptor field. Do NOT enable in production. The install records a revision AND installs the provider live (so a connection added moments later can bind it via its `oauth_provider` field with no restart); uninstall records a revision AND CLOSES the provider, so a still-bound connection's next call fails loud rather than degrading to an unauthenticated dial (deliberately breaking; confined to the owning agent by the owner-scoped run-start reconcile AND by a store-boundary owner check that refuses a cross-owner drop — defense in depth, so the store enforces owner-scoping independently of caller-side owner resolution). The agent's **Protocol-installed inference provider** (the LLM provider KEY, a distinct credential plane) is managed by `POST \u002Fv1\u002Fagent_config\u002Fset_llm_provider` — a SEPARATE admin write, never a relaxation of the OAuth verb. Its descriptor is **zero-URL** too — `{name, provider, credential_source: \"remote\", inference_broker, model_allow?}` — because no admin-writable field may determine where the key is sourced (D-300): the pull endpoint \u002F audience \u002F scope ceiling are pinned at boot on the named `inference_broker` (an `llm.inference_brokers[]` entry). A write carrying `credential_url` \u002F `token_url` \u002F `*_env` \u002F a secret is rejected `400 {\"code\": \"invalid_request\"}` **by name**; an empty `credential_source` (the forbidden env source) and an unknown broker each fail loud too. It is gated on the `admin` scope claim ONLY (a leaked read-only `console:fleet` token gets `403 {\"code\": \"scope_mismatch\"}` — a control write is a strictly more elevated tier than any read), and installs the binding live so the runtime's provider key is sourced from the coordinator broker at connect + refresh (uninstall closes the binding and fails subsequently-bound calls loud, never a silent no-op serving the old key). The versioned `hooks` section (the run-completion hook's durable home — `{run_completion: {tool, timeout_ms}}`) rides the same machinery with no dedicated verb: set it via `set_revision` (a negative `timeout_ms` is rejected at set time), read it on `get`, and `diff`\u002F`rollback` cover it like every other section; it resolves above the yaml `runtime.hooks` default at the agent's next run. The versioned `naming` section (session auto-naming's durable home — `{auto, after_turns, repeat_every, max_repetitions, max_title_len, model}`) likewise rides the same machinery with no dedicated verb: set it via `set_revision` (an invalid policy — a negative bound, an out-of-range `max_title_len`, or `repeat_every > 0` with `max_repetitions \u003C 1` since no unlimited value exists — is rejected `400 {\"code\": \"invalid_request\"}` at set time), read it on `get`, and `diff`\u002F`rollback` cover it; it resolves above the yaml `runtime.naming` default at the agent's next run — a PRESENT section is authoritative either way, so a bare `{\"naming\": {\"auto\": false}}` revision is an explicit per-agent opt-out that wins over a yaml-on fleet default — and, when active, titles the session at each run's terminal boundary (a failure emits `session.naming_failed` and never alters the run). Every edit applies on the agent's **next run** (next-turn projection — never mid-flight); an upsert that would overwrite a pack-origin skill is refused with `400 {\"code\": \"invalid_request\"}`, never silently.\n\n### Signed OAuth MCP capability registration\n\nAn operator-enabled runtime may expose the admin-only\n`agent_config.register_oauth_mcp_capability` write at\n`POST \u002Fv1\u002Fagent_config\u002Fregister_oauth_mcp_capability`. The request carries the\nverified identity\u002Fagent selector, provider and boot broker names, audience,\nscopes, one closed HTTP connection descriptor, and a boot-trusted asymmetric\n`authority_envelope`. The descriptor may include\n`artifact_byte_eligible` plus `artifact_params`; the applied revision echoed in\nthe response preserves those exact canonical fields.\n\nArtifact mappings are canonicalized once (trimmed method\u002Fparameter names and\nsorted parameter sets) and fail loud above any exact ceiling: 32 methods, 8\nparameters per method, 128 UTF-8 bytes per method or parameter name, or 8 KiB\nof canonical JSON. Required and signed request values must be canonically equal.\nA JTI is tenant-scoped and immutable: an exact retry converges on the original\npair, while any binding change is a replay conflict. Before publication Harbor\nalso checks each mapped method and parameter against the MCP server's discovered\nstring input schema. A rejected discovered mapping is durably compensated;\nrestart reconciliation completes its rollback before another signed operation\ncan take authority.\n\nA connection failure can retain an incomplete committed candidate behind the\nactivation fence. Retry the same signed JTI for a transient failure. To discard\nthat lifetime, the exact owner may use the existing\n`agent_config.remove_oauth_mcp_capability` method with the immutable candidate's\ncontent hash from `agent_config.list_revisions`, even when `agent_config.get`\nshows only prior or no-active state. A corrected, newly signed registration\nusing the same provider or connection name also compensates that owner's\nincomplete lifetime. Its `expected_content_hash` is checked against the logical\nactive revision before cleanup, and the replacement write retains its own CAS.\nCleanup ends at `preparation_rejected`, including after admitted\u002Fcompleted\nexpiry, so the discarded JTI cannot renew. Published lifetimes and foreign\nowners remain protected; an older rejected lifetime cannot remove a same-name\nreplacement. User-tier sibling methods preserve the same user ownership across\nsession changes. No new method or request field is required.\n\nBoth agent and user GET hide a pending candidate and return its prior revision\nor no-active state. Use that visible hash, or `-` for no-active, when correcting\na registration; a hidden candidate hash is a conflict. A lost revision\ncheckpoint is recoverable only when the physical candidate and exact pending\nfence prove the same claimed operation. If cleanup aborted the legacy fence\nbut its final operation checkpoint failed, an unrelated first registration\nreceives a retryable 409 until exact removal\u002Freconciliation finishes that\ncheckpoint. Retry the competing registration afterward. This prevents reuse\nfrom erasing the only durable cleanup proof.\n\nThe body is a flat JSON object — the method's request shape — with an `identity` object carrying the triple (or the headers above; the body's `identity` may be left empty when the headers supply it):\n\n```json\n{ \"identity\": { \"tenant\": \"dev\", \"user\": \"dev\", \"session\": \"dev\" }, \"query\": \"Hello, agent!\" }\n```\n\nThe response is the method's flat response shape directly — no `result` \u002F `error` wrapper. A failure is an HTTP status plus a `{\"code\": \"...\"}` envelope (e.g. `404 {\"code\": \"unknown_method\"}`).\n\nCORS is default-deny. For browser clients, your origin must be in the Runtime's `server.allowed_origins`. See [`run-the-dev-loop`](..\u002Frun-the-dev-loop\u002FSKILL.md) §2.\n\n## 2. The handshake — `runtime.info` first\n\nThe first call your client makes:\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fruntime.info\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {}}'\n```\n\nA real response from a dev Runtime:\n\n```json\n{\n  \"instance_id\": \"harbor-dev-192.168.1.7\",\n  \"display_name\": \"harbor dev\",\n  \"build_version\": \"v0.0.0-dev\",\n  \"build_commit\": \"dev\",\n  \"build_go_version\": \"go1.26.3\",\n  \"protocol_version\": \"0.1.0\",\n  \"capabilities\": [\"caller_memory\", \"events_subscribe\", \"runtime_posture\", \"task_control\"],\n  \"uptime_seconds\": 16,\n  \"wire_surface_digest\": \"sha256:\u003C64 hex — changes whenever the canonical wire surface does>\"\n}\n```\n\nThree things to read and act on:\n\n- `protocol_version` — the wire-contract version (distinct from `build_version`, the Runtime's own release). Same major ⇒ compatible; on a major mismatch, warn loudly or refuse.\n- `capabilities` — the advertised Protocol surfaces (the list above is one dev Runtime's; a differently-wired Runtime advertises a different subset, which is the whole point of reading it). Four are unconditional on any current build — `task_control`, `events_subscribe`, `runtime_posture` and `caller_memory` — and everything else depends on what the operator wired. Shape your UI on this list: a runtime that doesn't advertise `topology_snapshot` gets the topology panel disabled, not a crash. A method outside the Runtime's registry returns the canonical `404 {\"code\": \"unknown_method\"}` envelope — treat it (and 405 \u002F 501) as \"not served here, degrade\", the same SKIP posture Harbor's own smoke scripts encode.\n- `wire_surface_digest` — an opaque, stable `sha256:` fingerprint (elided above on purpose: a doc that pins a live digest is wrong at the next wire change) of the Runtime's canonical wire surface (the Protocol version + method \u002F error \u002F capability \u002F wire-type *names*; it deliberately excludes field shapes and event-type names). Stamp the digest your client was built against into the build, then compare it here at attach: equal ⇒ same surface; different ⇒ surface drift, surface it loudly; absent\u002Fempty ⇒ the Runtime predates digest support (an informational note, never a drift alarm). It is a coarse name-level early-warning, not a substitute for the field-level checks a client that vendors the wire manifest runs at build time.\n\n### 2a. Retention horizons — how far back this Runtime actually holds data\n\n`runtime.health` (POST `\u002Fv1\u002Fcontrol\u002Fruntime.health`) is a liveness read. For\nevery caller it returns subsystem readiness and only the events horizon, when\nwired, at `scope:\"runtime\"`. Polling it performs no stored reads, elevation or\naudit publication, including with `admin` or `console:fleet` authority.\n\nFor observed oldest-retained instants across `events`, `tasks` and `sessions`,\nexplicitly call `runtime.retention` (POST `\u002Fv1\u002Fcontrol\u002Fruntime.retention`) with a\nverified **`admin`** token and an empty `{}` request body. Its response is\n`{\"retention\":[...]}`; entries use the existing `RetentionHorizon` shape and\nall have `scope:\"runtime\"`. `console:fleet` alone, ordinary callers and\ntrust-mode callers receive `scope_mismatch`. A successful read emits exactly\none `audit.admin_scope_used` attributed to the verified actor; failure to emit\nthe audit returns a runtime error without a retention response.\n\nRead these horizons before a windowed history\u002Fenumeration read so a merged\n\"last N days\" view can mark incomplete coverage. An entry with\n`scope:\"runtime\"` and no `oldest_retained_at` means the surface is trustworthily\nempty. A missing entry means its reader is unwired, so completeness is\nunverifiable. Clients that previously used elevated `runtime.health` for task\nand session horizons must migrate to `runtime.retention` with admin authority\n(D-490). The Protocol version remains `0.1.0`.\n\n## 3. Starting a task — the chat-message equivalent\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fstart\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {}, \"query\": \"What'\\''s the weather in Madrid?\", \"input_artifact_ids\": []}'\n```\n\nThe request is the flat `StartRequest`: `identity` (the triple — empty here because the headers supply it), the `query` string, and the optional `input_artifact_ids`. There is no `foreground` field — every `start` mints a task and you observe it on the event stream.\n\nResponse is the flat `StartResponse`:\n\n```json\n{\n  \"task_id\": \"tsk_01HXYZ...\",\n  \"reused\": false,\n  \"protocol_version\": \"0.1.0\"\n}\n```\n\n`reused` is `true` only when you supplied an `idempotency_key` that matched an existing task; `protocol_version` lets you detect a version skew.\n\nFor a task that may use only selected tools, negotiate `run_scoped_tools_v1`\non `runtime.info`, then send `tool_allowlist` with physical catalog names on\n`control.start`. For example, `\"tool_allowlist\":[\"read_document\"]` permits\nthat tool if the current identity and agent configuration already authorize it.\nAn explicit `[]` closes tool access, while omission preserves ordinary tool\nvisibility. Check the response's `tool_allowlist_applied:true` acknowledgment;\nan older runtime may ignore an unknown request member. The restriction also\napplies to discovered tools and planner-spawned child tasks. A retry using the\nsame idempotency key must keep the exact list.\n\nTo make a task return a **schema-conforming answer**, add the optional `output_schema` field — a JSON-Schema document the runtime validates the task's terminal answer against. On success the completed task's envelope carries a validated `answer_payload` alongside the plain `answer` string, readable via `tasks.get`'s `result_inline` (and via a parent run's AwaitTask observation). An empty, non-compiling, or over-cap (64 KiB) schema is rejected at the edge with a `400 {\"code\": \"invalid_request\"}` envelope before any task spawns; a schema-invalid answer after the runtime's correction budget fails the task loud with the `output_invalid` error code — never a schemaless success. A schema-constrained task suppresses assistant token deltas on the event stream (a validate-and-retry loop cannot retract streamed tokens), so the answer arrives once, on completion. Omit the field for the default schemaless behaviour.\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fstart\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {}, \"query\": \"Classify the sentiment of: shipping delayed again.\",\n       \"output_schema\": {\"type\": \"object\", \"required\": [\"sentiment\"],\n                         \"properties\": {\"sentiment\": {\"type\": \"string\"}},\n                         \"additionalProperties\": false}}'\n```\n\nTo run under a **specific agent's configuration**, add the optional `agent_id` field (D-360). Omitting it binds the runtime's configured default exactly as before; naming one selects that agent's prompt layers, tool exposure, skills membership, LLM parameter overrides, completion hook and naming policy for this run.\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fstart\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {}, \"query\": \"Draft the release note.\", \"agent_id\": \"reporting-agent\"}'\n```\n\n**Keep that agent binding when you render an MCP App.** The runtime-authored\n`mcp.app_available` payload carries `AgentID` beside `ServerID` and\n`ResourceURI`; a nested `MCPAppRef` uses the JSON field `agent_id`. Treat this\nvalue as opaque host state and echo it as `agent_id` on\n`mcp.servers.resources`, `mcp.servers.read_resource`, and\n`mcp.apps.call_tool`. Never accept an agent id from inside the sandboxed App.\nHarbor resolves an omitted value to the runtime\ndefault for older clients, then applies the same signed `agent_reach` check\nbefore tenant-local resolution and credential\u002Fexposure use, so the echo is not\ntrusted authority. Successful `ui:\u002F\u002F` resource reads can include optional same-response\n`provider_origin` and `_meta.ui.csp.resourceDomains`. They describe the exact\nadmitted resource\u002Fprovider, not callback authority. Resource domains are bounded\ncanonical public HTTPS origins (32, 2048 bytes each, 8 KiB total); recognized\nmalformed\u002Funsupported declarations refuse the read. Missing metadata, stdio and\nnonpublic provider origins stay absent. Never infer origins from document HTML or\nfetch another server descriptor to widen CSP. Keep the sandbox and require a\nfresh available render admission before using declarations for passive assets;\nnever use them to permit scripts, connections or frames. Older runtimes omit\nthese optional fields, so preserve the restrictive fallback.\n\n`mcp.apps.tool_context` takes no agent id: its record is\nalready scoped to the verified tenant\u002Fuser\u002Fsession triple and it performs no\nagent-config or credential selection.\n\nA named agent is accepted when EITHER its id equals the runtime's configured default agent id, OR a config revision exists for your tenant under that id (write one with `agent_config.set_revision` — see §7). Anything else is refused with a `400 {\"code\": \"invalid_request\"}` envelope **before any task is created**, never quietly replaced by the default: a caller that named agent A, silently got agent B, and was told it succeeded is exactly the failure this rule prevents. The refusal is deliberately uninformative — an id belonging to another tenant and an id that never existed produce the identical error, so the edge cannot be probed for cross-tenant existence.\n\nTo contribute **content you already retrieved** — recalled conversation memory, a document your own store fetched, anything you want the model to consider without asserting it as instruction — add the optional `caller_memory` field (D-364). **This is the field to reach for, NOT `system_prompt_override`.**\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fstart\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {}, \"query\": \"Continue where we left off.\",\n       \"caller_memory\": {\"recalled\": [{\"user\": \"my order id is 4471\",\n                                       \"assistant\": \"noted, tracking it\"}]}}'\n```\n\nWhere it lands, and why that is the whole point. The value is composed into the run's `\u003Cread_only_external_memory>` prompt tier under the FIXED runtime-owned map key `caller_supplied`, beside whatever the runtime's own retrieval wrote there (`recalled_turns`) — **it composes, it never replaces**. You name no key, so you can never shadow a runtime key and a future runtime producer can never collide with you. That tier ships a five-line anti-prompt-injection preamble whose entire premise is that its contents are hostile, which is exactly why it is the position a caller may write.\n\nContrast with `runs.set_overrides`' `system_prompt_override` (described in §1 inside the \"Admin control surfaces\" bullet — **but note `runs.set_overrides` is itself NOT admin-gated**; it lives in that bullet because it composes with the admin governance overrides above it, and any caller who can set overrides for a session reaches it), which is what this field exists to divert you away from: that one **replaces the whole base+user prompt spine**, silently suppressing the operator's durable user layer, and seats your content in the **trusted** base position with no framing at all. It is the right tool for changing the agent's instructions and the wrong tool for supplying it with content.\n\n`extra_instructions` is the one-run personalization sibling on the same `runs.set_overrides` payload (D-387). It remains available to an ordinary authenticated session caller, but renders in a separate escaped `\u003Cuser_personalization>` section; it never joins or replaces the admin-set tenant `\u003Cadditional_guidance>` block. Use it for user-authored preferences such as tone, format, or response style. Retrieved documents, recalled text, and other external content still belong here, in `caller_memory`, because only this path supplies the fixed read-only\u002Funtrusted framing intended for data rather than instructions.\n\nThe rules, all enforced at the edge before any task is created:\n\n- Any JSON value — object, array, string, number.\n- **An explicit `\"caller_memory\": null` is REFUSED**, not treated as absent. Omit the field if you have nothing to send; a caller that believes its memory reached the model when it did not is the failure this refuses to hide.\n- Over **32 KiB** → `400 {\"code\": \"invalid_request\"}`, with a message that names `caller_memory`. No task is created. **That cap is a resource bound and a wire-size guard, not a security boundary** — it stops an oversized document reaching the token-budget guard and failing your whole run late. Do not read it as a limit on how much content you can put in front of the model: `query` is uncapped below the 64 KiB envelope and lands in the *unframed* conversation position, and `agent_config.session.set_user_prompt` needs no scope claim, takes a 1 MiB body, and lands *inside* the system prompt. What contains `caller_memory` is the tier it goes to, never its size.\n- **Negotiate before you rely on it.** Call `runtime.info` and check for `caller_memory` in `capabilities` — it is advertised UNCONDITIONALLY by every Runtime that has the field, so its **absence** is the signal, not its presence. A runtime that predates the field would **discard it and answer 200** — your run proceeds without the memory you sent, and nothing tells you. Current runtimes refuse an unknown member by name (see below), but that cannot help you against an older deployment; the capability can, because a build predating the field cannot advertise it.\n- It can never write the conversation-memory tier — that is a claim about the session's stored turns only the runtime makes.\n- Each admitting run emits `memory.caller_block_admitted` carrying `bytes` \u002F `tier` \u002F `key` and **no fragment of your content**, so an operator can audit that caller-asserted memory entered a run without the audit trail becoming a copy of it.\n\n**Unknown members are refused, never dropped.** Every Protocol request body is decoded strictly: a member no wire type declares comes back `400 {\"code\": \"invalid_request\"}` with the member **named** in the message (`json: unknown field \"…\"`). This is deliberate and it is how you discover a field a runtime does not support:\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fstart\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {}, \"query\": \"hi\", \"caller_memoryy\": {}}'\n# → 400 {\"code\":\"invalid_request\",\n#        \"message\":\"method \\\"start\\\": request body is not a valid StartRequest: json: unknown field \\\"caller_memoryy\\\"\"}\n```\n\nTwo consequences for your client: strip fields the runtime does not declare (typos and speculative fields are 400s, not no-ops), and remember that a **stray** member is refused even when a correctly-spelled sibling carries the same information — e.g. the `artifacts.*` methods scope by `scope`, and adding an `identity` object beside it is a 400.\n\n**What happens to it at rest.** The payload is stored on the task record, which the StateStore writes to disk. It goes through the **audit redactor** on the way in — the same one `query` and the task description take, so all three caller-controlled fields behave alike — and the redacted form is what both the store and the prompt see. Structure survives: the redactor walks the decoded JSON, so objects, arrays, numbers, booleans and `null` come back intact and only secret-shaped **keys** (`api_key` \u002F `password` \u002F `secret` \u002F `token` \u002F `cookie` \u002F `authorization`) and inline `Bearer …` \u002F `Basic …` **values** are replaced with `***`. Your idempotency key is unaffected — content identity is computed before redaction.\n\n**One thing Harbor does not do for you:** that redactor is a **pattern** redactor, not a sanitiser. It does not detect PII, it does not detect a credential that looks like ordinary prose, and it cannot make hostile text safe — the untrusted framing is the mitigation for the MODEL, and it is not redaction either. If you pipe third-party content through `caller_memory` without redacting it first, you still own that data-leakage path.\n\n**It selects configuration only.** The run's southbound tool provenance (`_meta.agent_id` on outbound MCP calls) and its RFC 8693 acting principal (`actor_token`) stay the runtime's boot-derived value — the acting principal is the runtime's own verified identity and is never client-supplied. `tasks.get` \u002F `tasks.list` reflect the selection on `task.agent_id`; an **absent** value means the caller named none and the run bound the runtime's configured default (\"defaulted\", not \"unknown\").\n\nFor multimodal input, upload artifacts FIRST (`artifacts.put`, see §6) and pass the returned IDs in `input_artifact_ids` (D-166). The per-MIME dispatch — image inline vs PDF\u002Faudio as ArtifactStub — happens inside the planner; your client just passes refs. To override how an attachment is handed to the model, add the optional `input_artifact_dispositions` map (Phase 84b — D-189), keyed by artifact id with values `ref` | `inline` | `provider_native` | `tool:\u003Cname>` (e.g. `{\"art_x\": \"tool:pdf.extract\"}` forces the named catalog tool). Your hint is the top precedence layer (hint > the agent's `multimodal.disposition` config map > the runtime default: image inline, everything else ref); an omitted map keeps today's behaviour. `tasks.get` reflects the hint on `input_artifacts[].disposition`, and the resolution (including degradations — e.g. an unknown `tool:\u003Cname>`) is observable as `task.input_disposition.resolved` events. A `provider_native` hint is honoured end-to-end (Phase 84c — D-190): the LLM driver uploads the attachment to the provider's file surface and the upload is observable as `llm.provider_file.uploaded` events (artifact ref, provider, modality, `file_id`).\n\n### 3a. Warming the next start — `prepare` (D-495)\n\nWhen your client knows a send is coming (the user opened the agent, picked it,\nor started typing), call `prepare` with the identity, `agent_id` and\n`provider_route` the next `start` will carry. It is admitted exactly like\n`start`, creates nothing, and answers `202` at once while the runtime runs the\nrun-start MCP reconcile and the credential-free route selection in the\nbackground:\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fprepare\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {\"tenant\": \"t\", \"user\": \"u\", \"session\": \"'\"$SESSION\"'\"}, \"agent_id\": \"support\"}'\n# → 202 {\"state\":\"scheduled\",\"protocol_version\":\"0.1.0\"}\n```\n\nA runtime without a reach-admission authority (no broker or shared KEK) answers\n`404`, as does one predating the method. `state` is `scheduled`, `in_flight`\n(already running for this tenant\u002Fuser\u002Fagent),\n`fresh` (completed within 90 s; nothing new started) or `busy` (workers\nsaturated; the hint was dropped). Calling it repeatedly is cheap. A `start`\nwithin 90 s whose inputs are unchanged skips its reconcile, and one arriving\nmid-preparation waits for it at most 10 s; otherwise the start behaves exactly\nas without `prepare`. Impersonation is refused and no outcome is reported back:\nwatch the runtime's `session.prepare` log line and the run's `turn.pre_model`\n`prepared` attribute.\n\n## 4. The events stream — SSE `events.subscribe`\n\nThe Protocol exposes events as Server-Sent Events:\n\n```http\nGET \u002Fv1\u002Fevents?access_token=\u003CJWT>\nAccept: text\u002Fevent-stream\nX-Harbor-Tenant: \u003Ctenant_id>\nX-Harbor-User: \u003Cuser_id>\nX-Harbor-Session: \u003Csession_id>\n```\n\nThe subscription is **identity-scoped** — it streams the whole session's events — so there is **no `task_id` query param**. A client that can set headers narrows server-side with the optional `X-Harbor-Run` (a task id) and the repeatable `X-Harbor-Event-Type` headers. A browser `EventSource` (which can't set custom headers) authenticates via the `?access_token=` query-param shim — same JWT, same identity triple, its `session` claim scoping the stream — and filters client-side on the event payload's task id. The query-param shim is documented in `internal\u002Fprotocol\u002Ftransports\u002Ftransports.go`.\n\nEach `data:` value is an event envelope, not a bare payload. For example,\na live assistant update has no SSE `id:` because its sequence is zero:\n\n```text\nevent: llm.completion.chunk\ndata: {\"type\":\"llm.completion.chunk\",\"sequence\":0,\"tenant\":\"dev\",\"user\":\"dev\",\"session\":\"dev\",\"run\":\"tsk_01HXYZ\",\"payload\":{\"TaskID\":\"tsk_01HXYZ\",\"RunID\":\"tsk_01HXYZ\",\"Kind\":\"content\",\"Delta\":\"I will compare the documents.\",\"Done\":false}}\n```\n\nThis example elides timestamps. A replayed copy has a positive `sequence` and\nmatching SSE `id:`. The runtime persists buffered chunks at completed planner\nsteps before tool execution, and seals\u002Fdrains the run before successful terminal\ncompletion. Persistence is not a second live fan-out. Restart replay requires\na durable event bus backed by a persistent StateStore.\n\nUse `payload.Kind` to keep `content` in the conversation and `reasoning` only in\nthe activity\u002Freasoning view. `payload.Done` ends one LLM response lane, not the\nwhole task. Tool-call preambles remain intermediate updates; the terminal\n`AnswerEnvelope` remains the final answer. Treat sequence-zero animation as\nprovisional: an unflushed tail can be lost on crash\u002Fcancellation\u002Fwrite failure.\nDo not append replayed history on top of that provisional text; reconstruct the\naffected run from retained events and respect explicit retention gaps.\n\n`sessions.turns.list\u002Fget` remains a consumer-safe projection, not the raw update\ntranscript. Recover historical intermediate text through authorized `state.history`\nor SSE replay; its newest `live_resume_seq` alone does not backfill older steps.\nSee [streaming semantics](..\u002F..\u002Fsite\u002Fprotocol\u002Fstreaming-semantics.md) for the\npersistence boundary and cursor choreography.\n\nGovernance emits its own canonical events on the same stream — subscribe with `X-Harbor-Event-Type: governance.failover` to observe LLM-provider failover. When a runtime is configured with a broker-pulled failover chain, each HOP the Harbor-orchestrated walk takes on a retryable provider error emits a `governance.failover` event carrying the run identity, the `from_provider` \u002F `to_provider`, the 1-based `hop_index`, the accumulated per-identity cost the re-run budget check gates against, and a bounded retryable-error class (never the raw provider error). Every hop is a Harbor event through audit + bus + cost — the provider SDK's native fallback array is deliberately unused (D-018) — and a hop whose re-run budget\u002Frate check trips fails the run loud rather than silently walking further down the chain. The full event catalogue (147 types) is the generated [events reference](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fevents).\n\n**A gotcha**: the event payload's task ID field is `payload.TaskID` (capital T) — match exactly when parsing in JS\u002FTS. Documented in the Console's chat panel handler; easy to miss when hand-rolling.\n\nFor a chat UI, you'd:\n\n1. Append a \"user turn\" bubble to the chat.\n2. POST `start`, get `task_id`.\n3. Open an SSE stream for that `task_id`.\n4. Group `llm.completion.chunk` by task\u002Frun, response boundary and `payload.Kind`; show only content in the conversation.\n5. Render `tool.invoked` \u002F `tool.result` as collapsed cards inside the assistant bubble.\n6. Close the bubble on `task.completed`.\n\n**Background-wake notifications (`notification.*`).** The runtime also\nsynthesises an operator-facing `notification.*` family onto the same\n`events.subscribe` stream (no separate method) — the conversational mirror of\nbackground work you'd otherwise miss. Each carries a human-readable\n`Summary` your UI renders inline (fall back to the bare event type when\nabsent). The wake classes:\n\n- `notification.task_completed` — a background task that opted in with\n  `NotifyOnComplete` finished.\n- `notification.task_group_resolved` — a parallel task group resolved\n  (with ref-shaped member-outcome counts).\n- `notification.task_group_cancelled` — a parallel task group was cancelled\n  **without the operator asking** (a fail-fast gate firing on a member\n  failure, or a cascade inherited from an ancestor cancel). This closes the\n  sibling asymmetry the resolved-group mirror opened: a batch's winners wake\n  the conversation while its unprompted-cancelled losers would otherwise\n  vanish silently. **Suppression rule:** a group cancel the operator drove\n  DIRECTLY produces NO notification (they already know) — the runtime keys\n  this on the cancel's typed origin, so you only ever receive this event for\n  an unprompted cancel worth surfacing.\n- `notification.task_failed` — a background task failed (suppressed for a\n  foreground turn's own failure, which the client surfaces itself).\n\nThese are additive event classes on the existing stream; a client that\ndoesn't recognise a `notification.*` type can ignore it. `ProtocolVersion`\nis unchanged.\n\n## 4a. Reopening a long session — `state.history`\n\n`events.subscribe` is the LIVE tail. To **reopen** a closed conversation you don't want to re-stream every event from sequence 1 — a 5 000-event session would flood the client before the newest turn renders. The `state.history` method (capability `state_snapshots`) is the bounded, **tail-first** windowed read of the same durable event stream:\n\n```http\nPOST \u002Fv1\u002Fstate\u002Fhistory\nAuthorization: Bearer \u003CJWT>\nContent-Type: application\u002Fjson\n\n{ \"session_id\": \"\u003Csession_id>\", \"before\": 0, \"limit\": 50 }\n```\n\n`before: 0` means \"from the tail\" (the newest retained events); `limit` is the window size K (default 50, max 200). The response is a page of flat events **oldest-first within the window**, plus the bounds and a scroll-up cursor:\n\n```json\n{\n  \"events\": [ { \"type\": \"...\", \"sequence\": 4951, \"occurred_at\": \"...\", \"payload\": {...}, \"artifacts\": [...] }, ... ],\n  \"head_sequence\": 1,\n  \"tail_sequence\": 5000,\n  \"next_cursor\": 4951,\n  \"has_more\": true,\n  \"truncated\": false\n}\n```\n\nTo **scroll up** (load one window older), pass the previous response's `next_cursor` back as `before`. When `next_cursor` is `0`, you've reached the retained head — no older events remain. Reduction of events → chat messages stays **on your client** (the same reducer you use for the live stream): the surface returns flat events, not pre-reduced turns.\n\nHeavy payloads (a large tool result offloaded above the heavy-output threshold) ride by a **routable** `StateArtifactRef` on `events[].artifacts[]` — a content-addressed `id` (+ `sha256`), never inline bytes. Resolve it the same way as any artifact: POST the `id` to `artifacts.get` (§6.1) — the byte read that works on every driver. `artifacts.get_ref` is the presigned-URL alternative, useful when the store can hand a large download off its own edge, but it answers `presign_unsupported`\u002F501 on the default inmem\u002Ffs stores, so reach for it only when you know your deployment runs an S3-compatible driver.\n\nIdentity rules: identity is mandatory (an incomplete triple is `identity_required`\u002F401); an unknown or cross-identity `session_id` is `not_found`\u002F404 (existence is never revealed across identities — never a 403); a cross-tenant read requires the verified `admin` scope claim.\n\n**Cross-session \u002F time-ranged historical read — `events.list`.** `state.history` is a **by-id** read (one session). When you want the raw events across a **time window** — possibly across sessions, for a fleet observability view — use `events.list` (`POST \u002Fv1\u002Fevents\u002Flist`): the same wire `EventFilter` you pass to `events.subscribe`\u002F`events.aggregate` (identity axes + `since`\u002F`until` + `event_types`) plus the SAME tail-first paging grammar as `state.history`:\n\n```http\nPOST \u002Fv1\u002Fevents\u002Flist\nAuthorization: Bearer \u003CJWT>\nContent-Type: application\u002Fjson\n\n{ \"filter\": { \"since\": \"2026-07-04T00:00:00Z\" }, \"cursor\": 0, \"limit\": 50 }\n```\n\nRows are the **same flat `StateEvent` shape** `state.history` returns (heavy payloads by routable `StateArtifactRef`, never inline); `cursor: 0` reads from the tail and you scroll one page older by passing the response's `next_cursor` back as `cursor` (0 ⇒ the retained head). `truncated: true` is the honest retention-gap flag at the window edge (a best-effort in-memory ring evicted older rows; a `durable` driver serves complete windows unless the operator enabled audit retention, `events.retention.audit_max_age`, and the window reached rows it trimmed — only aged `audit.*` rows are ever trimmed). By default the read is scoped to your own verified triple; a **cross-tenant (fleet) widening** — a `filter.tenant_ids` naming a tenant other than yours — requires the verified `admin` **or** `console:fleet` scope (derived server-side from your session, never the body) and emits one `audit.admin_scope_used` per request. Same authz as the live\u002Faggregate feeds, so a `console:fleet` operator reads historically exactly what it can subscribe to.\n\n**Bucketed counts — `events.aggregate`.** For a time-bucketed count series (the Events-page sparkline) rather than the raw rows, `POST \u002Fv1\u002Fevents\u002Faggregate` takes the same `EventFilter` plus a `window` and a `bucket` (nanoseconds; `window % bucket == 0`) and returns `{ \"buckets\": [ { \"bucket_start\": \"...\", \"bucket_end\": \"...\", \"counts\": { \"tool.failed\": 3 } }, ... ], \"truncated\": false, \"protocol_version\": \"0.1.0\" }`. It works on EVERY driver — including the `durable` log — with the same authz as `events.list` (a cross-tenant filter needs the verified `admin`\u002F`console:fleet` scope, one `audit.admin_scope_used` per widened call). A window too wide to count in full comes back as **partial buckets with `truncated: true`** — uniformly across drivers, DATA not an error; a driver difference changes WHAT the method returns, never WHETHER it works, so there is no over-wide-window 400.\n\nBy default the grid is anchored at \"now\" — the buckets run `[now-window, now)`, so a `bucket_start` is NOT addressable twice (two polls a few seconds apart return two different boundary sets and nothing caches). Pass the OPTIONAL `anchor` (RFC-3339 UTC) to floor the boundaries onto the fixed grid `anchor + k*bucket` instead: two calls at two instants with the same `anchor` + `window` + `bucket` then share bucket coordinates, so a bucket is cacheable and re-requestable — pass the Unix epoch (`\"1970-01-01T00:00:00Z\"`) for a globally-shared grid identical across a runtime restart and across two fleet runtimes. One grid-edge caveat: with an anchor the LAST bucket's `bucket_end` is the grid boundary covering \"now\" (generally just AFTER now, by up to one bucket), so don't render it as \"up to this instant.\" The field is additive — omit it and you get the byte-identical clock-anchored series.\n\nWidening semantics (same for `events.aggregate` and `events.list`): you WIDEN by NAMING `filter.tenant_ids` (or another principal — a foreign\u002Fmulti user, a multi-session set). A widened read fans in across ALL users and sessions of the named tenant scope — the elided user\u002Fsession axes legitimately mean \"all\" within the tenant(s) you authorized, so a fleet read of `{\"filter\":{\"tenant_ids\":[\"t2\"]}}` returns every principal's counts in `t2`, not just your own. An ELIDED `tenant_ids` always stays YOUR OWN tenant, even for an admin (name-to-widen, matching `tasks.list` \u002F `agents.list`) — you never silently fan across every tenant. Every widened read is gated on the verified `admin`\u002F`console:fleet` scope (derived from your session, never the body) and emits one `audit.admin_scope_used`.\n\n**Per-tenant attribution — `by_tenant`.** An aggregate bucket is a bag of scalars (`{\"counts\": {\"tool.failed\": 3}}`) with NO tenant attribution, so — unlike a raw `events.list` row that carries its own tenant — you cannot verify a widened count against the `tenant_ids` you asked for; the runtime's honouring of the filter IS the whole tenant boundary. Set the OPTIONAL `by_tenant: true` on the `events.aggregate` body to get per-bucket attribution: each bucket gains a `counts_by_tenant` map (tenant → event-type → count) alongside `counts`, e.g. `{ \"counts\": {\"tool.failed\": 3}, \"counts_by_tenant\": {\"t-a\": {\"tool.failed\": 2}, \"t-b\": {\"tool.failed\": 1}} }`. It is returned ONLY on an admin-widened read (the same verified `admin`\u002F`console:fleet` scope, derived server-side); on any other read the flag is IGNORED and `counts_by_tenant` is absent — the flag never elevates a read and never widens what is counted (fail-closed). The keys are a subset of the tenants you named, and per bucket `Σ_tenant counts_by_tenant[tenant][type] == counts[type]`, so you can independently reconcile the breakdown against the totals and confirm no tenant outside your entitled set appeared. Additive — omit `by_tenant` and the response is byte-identical to before. `ProtocolVersion` stays `0.1.0`.\n\n**Fleet enumeration (admin-widened `tasks.list` \u002F `agents.list`).** By default both list methods project only your own `(tenant, user, session)` triple — a synthetic observer session sees nothing. A coordinator control plane rendering a fleet-wide Tasks board \u002F Agents catalog widens the read with an additive `filter.tenant_ids` selector: `POST \u002Fv1\u002Ftasks\u002Flist` (or `\u002Fv1\u002Fagents\u002Flist`) with `{\"filter\": {\"tenant_ids\": [\"tenant-a\", \"tenant-b\"]}}` enumerates every task \u002F agent across ALL sessions of the named tenants. Widening rides the SAME verified `admin` scope claim (no new \"fleet\" scope) — a `tenant_ids` request without it fails LOUD with `403 {\"code\": \"scope_mismatch\"}`, never a silent narrowing to own scope. Every widened row carries full per-`identity` `{tenant,user,session}` attribution, and every widened call emits an `audit.admin_scope_used` event. Cross-RUNTIME federation stays coordinator-side over these per-runtime reads (the same division as `sessions.list` \u002F `events.subscribe`). One `agents.list`-specific row to know about: every actively-serving runtime returns its **default agent** — the boot-configured agent it serves through, never registered as a fleet entity — as a first-class row marked `is_default: true` (well-known `agent_id`, `agents.get` resolves it, the `Active` metric counts it). On a narrow read it carries your own triple; on a widened read one such row appears per named tenant, attributed by tenant only. So a fleet catalog reads \"one agent, not enumerable this way\" instead of an empty page — but there is NO control surface over it: a `agents.pause`\u002F`.drain`\u002Fetc. against the well-known id fails `404` (`agent_not_found`), because the runtime's own process is not a fleet-controllable member. A real registration reusing the well-known id suppresses the synthetic row (real data wins; never a duplicate id).\n\n## 4b. Erasing a session — `sessions.delete`\n\nTo satisfy a data-lifecycle \u002F right-to-erasure request, `sessions.delete` (capability `session_lifecycle`) **deletes a whole session and cascades deletion of its scoped State, Memory, and Artifacts**. It is **own-session-only** — you erase solely your own verified `(tenant, user, session)`; there is no admin \u002F cross-tenant path. The route is `POST \u002Fv1\u002Fsessions\u002Fdelete`:\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fsessions\u002Fdelete\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {\"tenant\": \"dev\", \"user\": \"dev\", \"session\": \"'$SESSION'\"}}'\n# → 200 {\"session_id\":\"...\",\"deleted\":true,\"state_records_deleted\":N,\"artifacts_deleted\":M,\"memory_purged\":true}\n```\n\nThe response carries non-sensitive deletion telemetry only — never erased content. The bytes are **hard-deleted** (not tombstoned); the only durable trace is a redacted, content-free `session.erased` audit event written under your observability scope (so a follow-up `state.history` for the erased session returns empty). Rules: identity is mandatory (`identity_required`\u002F401, which a body identity mismatching your verified triple also hits); a session with a **RUNNING task is refused** `session_running`\u002F409 with **no store touched** — wait for the task to finish (or cancel it) and retry; an absent session is `not_found`\u002F404. Check `runtime.info.capabilities` for `session_lifecycle` before calling — a runtime that did not wire an eraser does not advertise it and answers a 404 at the route.\n\n## 4c. Naming a session — `sessions.set_title`\n\nSessions display as raw ids until you give one a human-readable **title**: `sessions.set_title` sets (non-empty `title`) or clears (empty `title`) the `Title` field on the session record (D-288). Unlike `sessions.delete`, the write scope is your whole verified `(tenant, user)`, not just your own connecting session — `session_id` is a **dedicated field** that may name a **sibling** session you own, so a Console-style \"rename any of my sessions from the list\" flow needs no elevation. The route is `POST \u002Fv1\u002Fsessions\u002Fset_title`:\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fsessions\u002Fset_title\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {\"tenant\": \"dev\", \"user\": \"dev\", \"session\": \"'$SESSION'\"}, \"session_id\": \"'$SESSION'\", \"title\": \"Q3 onboarding chat\"}'\n# → 200 {\"session_id\":\"...\",\"title\":\"Q3 onboarding chat\",\"title_source\":\"manual\"}\n```\n\nThe verb **always** writes `title_source: \"manual\"` — `auto` provenance is not expressible over the wire, so a title you set here can never be silently overwritten by a later auto-namer (that's the internal-only producer behind Phase 158). An empty `title` clears both fields back to unset. Titles are single-line and bounded to 200 runes: a title with a newline\u002Fcontrol character, or over the limit, is rejected `invalid_request`\u002F400 — **never a silent clamp**. Rules: identity is mandatory (`identity_required`\u002F401, same body-identity-mismatch check as `sessions.delete`); a `session_id` you don't own (wrong tenant\u002Fuser, or simply unknown) is `not_found`\u002F404 — existence is never revealed across identities; renaming a **closed** session is fine (it's metadata on a historical conversation), renaming an **erased** one is `not_found` (the record is gone). The title itself never rides an event, log, or audit payload — `session.title_changed` carries only `{session_id, source}`, so a subscriber that wants the text re-reads `sessions.list` \u002F `sessions.inspect`, both of which now project `title` \u002F `title_source` on every row.\n\n**Session counters are TRUTHFUL, and honest about their own limits (D-309).** Every `sessions.list` \u002F `sessions.inspect` row carries six per-session counters populated at the runtime source: `tasks_count`, `events_count`, `total_cost_cents`, `total_tokens`, `has_pending_intervention`, `has_failed_task`. `events_count` counts durable\u002Freplayable events only; transient Sequence-0 live completion frames are excluded. So `filter.cost_above_cents`, `filter.has_failed_task`, `filter.has_intervention`, and `sort: \"cost_desc\"` narrow \u002F order on REAL data — \"show my sessions over $5\" returns the expensive ones, not an empty page. When a session's per-scan bound is hit, the row carries `counters_partial: true`: its cost \u002F tokens \u002F events counts are then an **honest lower bound** (render them with a \"≥\"), and a `cost_desc` ordering over such a row is non-authoritative — never a silent undercount. The two agent fields take the opposite tack: there is **no single-valued session→agent binding** in V1 (a session may run several agents), so `agent_id` \u002F `agent_name` are **nullable and omitted** rather than a fabricated value, and `filter.agent_ids` fails **loud** with `invalid_request`\u002F400 rather than returning a believable-but-false empty page. The multi-field `query` search is never failed whole for touching the empty agent fields — it still matches `session_id` \u002F `user_id`, so id \u002F user search keeps working.\n\n**The same \"no facet over an unpopulated field\" rule now holds across `tasks` \u002F `flows` \u002F `memory` \u002F `tools`, mechanically (D-313, extends D-309).** A build-time projection-completeness gate (`internal\u002Fprotocol\u002Fprojectioncheck`) fails the build if any read surface ships a filter \u002F sort \u002F aggregate over a wire field its projector never assigns — so the false-absence bug can't be reintroduced. What this means on the wire:\n\n- **`tasks.list`** — `has_pending_approval` is populated from the pause\u002Fapproval registry, so `filter.has_pending_approval=true` narrows to tasks actually blocked on a HITL gate (not an empty page). `background_acknowledged` is `omitempty` (elided when false — never a fabricated known-false).\n- **`flows.list` \u002F `flows.get`** — `budget_consumption.tokens_used` is summed per run (symmetric with `cost_usd_used`), truthful wherever a run is recorded.\n- **`memory.list` \u002F `memory.health`** — `has_ttl_expiring` and the two `expiring_in_1h` aggregate fields remain **removed** from the wire; `filter.agent_ids` loud-rejects with `invalid_request`\u002F400 (memory records carry no producer identity), never a false-empty page. Cumulative `rolling_summary` items now report their original source `expires_at`; inspection does not renew retention or expose unsettled journals.\n- **`tools.list` \u002F `tools.metrics` \u002F `tools.content_stats`** — a runtime that advertises the `tool_annotations` capability (negotiate via `Accepts(tool_annotations)`) serves REAL per-tool annotations: `filter.oauth_statuses` \u002F `filter.approval_policies` narrow to real rows, the annotator-backed aggregates (`active` \u002F `pending_approval` \u002F `awaiting_oauth`) carry real counts (no `aggregates_partial`), `tools.metrics` returns real error-rate gauges + invocation\u002Ffailure counts over the window, and `tools.content_stats` returns a real result-size histogram (D-314). The admin `tools.set_approval_policy` \u002F `tools.revoke_oauth` methods persist through `tools\u002Fapproval` \u002F `tools\u002Fauth` with audit (they no longer return `admin_unsupported`). A runtime that does NOT advertise `tool_annotations` (a headless catalog stack) loud-rejects `filter.oauth_statuses` \u002F `filter.approval_policies` with `invalid_request` and returns `aggregates_partial: true` with those counters zeroed — render them \"unavailable,\" never a real-looking 0; only `aggregates.total` is authoritative in that state.\n\nThe `owner` field in a `tools.*` catalog row is the logical configured MCP\nsource name. A user-scoped runtime may keep an opaque physical source key in\nits internal catalog so two users can attach the same connection; that key is\nnot a client-side naming contract and is never reconstructed from a suffix or\nhash. The row's `id` and `name` remain the physical catalog keys needed for\nthe exact `tools.get` \u002F `tools.describe` request, while a runtime without a\nlogical-source projection may honestly return the raw source identifier.\n\n### Cumulative memory inspection and administration (D-477)\n\nFor `rolling_summary`, `memory.list`, `memory.get` and `memory.strategy_trace`\nread the same checkpoint, bounded recent tail and retained evidence as execution.\nKeys identify immutable sources, not row positions or the viewer's run. A source\nkey survives raw-turn rollover while its evidence remains retained. Inspecting\nan expired source returns absence, not an extended lifetime. Token counts in the\nstrategy trace are estimates of projected memory, not provider usage.\n\nThe existing `memory.put` and `memory.delete` admin gates remain mandatory.\nPut records a redacted conversation note, never tool-result or action authority;\nif the detailed tail is full it reports capacity instead of evicting context.\nDelete removes that source conditionally, invalidates an affected checkpoint,\nand fences active admissions in that session so a late decision or settlement\ncannot restore erased material. It does not cancel an external action already\nin progress or erase an independently owned transcript. Other sessions remain\nunaffected.\n\n**Current migration limitation:** large expiring values cannot yet be exported\nthrough `memory.get`'s artifact arm: that path refuses the read rather than\ncreating a private copy without source-bound expiry\u002Fdeletion. This is not a\nsuccessful detail read or completed release acceptance. Small values, metadata\nlisting and source-key deletion remain available. Existing execution result-ref\nretrieval is a separate path with its own current-source checks.\n\n## 4d. Reopening a chat — durable turns and the two-read open (v1.28)\n\n`state.history` (above) is still the raw-event drill-down. To **reopen a\nchat** — render the current conversation from durable data — the v1.28\nsurface gives you a dedicated projection instead of reconstructing turns\nfrom forensic events:\n\n- **Lifecycle-only session read (HA-63 \u002F D-424).** `sessions.list` \u002F\n  `sessions.inspect` accept an additive `projection: \"lifecycle\"` selector:\n  session id, status, title\u002Fsource, authoritative timestamps, duration where\n  derivable, and the honestly representable agent id — with ZERO counter\n  enrichment (work bounded by page size before and after restart). Counter\n  fields use the closed availability state `current | partial |\n  not_requested | unavailable`; the lifecycle shape marks them\n  `not_requested` (never merely absent, never zero-as-not-computed). A\n  counter filter\u002Fsort (`cost_above_cents`, `cost_desc`, …) paired with the\n  lifecycle selector fails `invalid_request` — it never silently switches to\n  the expensive projection. The full projection remains the default when the\n  selector is omitted.\n- **Durable turn pages (HA-64 \u002F D-425).** `sessions.turns.list` returns one\n  newest-first keyset page of the caller's exact session's root foreground\n  turns (opaque `older_cursor`, `limit` default 20 \u002F max 50) with\n  renderable answer (inline or by artifact reference, or\n  `empty`\u002F`evicted`\u002F`unavailable`), consumer-safe reasoning, ordered tool\n  Activity (never arguments\u002Fresults), usage, intervention metadata\n  (bounded durable pause class \u002F reason \u002F lifecycle \u002F availability — never\n  a pause\u002Fresume\u002Fapproval action token; actionability is computed from the\n  verified caller's tier, and callers act through `pause.list` plus the\n  control\u002Fsteering verbs), and ordered durable MCP App references.\n  `sessions.turns.get` is the one\n  `(session, task)` terminal reconciliation read. Both are exact-session:\n  a foreign session answers typed `not_found` (non-oracular).\n- **Content-free usage read.** A consumer that needs only durable lifecycle\n  and usage facts may call `sessions.turns.get` with `projection: \"usage\"`.\n  The exact-session response is structurally limited to turn\u002Ftask\u002Fsession\u002F\n  agent identifiers, lifecycle and timing, and the canonical usage rollup\n  (per-measure `unavailable`, `exact`, or `estimated` states plus an optional\n  reported model). It does not include\n  conversation text, answers, reasoning, activity, attachments, apps, pause\n  state, runtime run identity, user\u002Ftenant identity, or terminal messages.\n  It uses the same durable turn index as the normal reconciliation read; no\n  poller, receipt, or privileged administrative scope is involved.\n- **Page-before-subscribe live handoff.** Chat open is two reads — one\n  `projection: \"lifecycle\"` inspect plus one `sessions.turns.list` page —\n  then the SSE subscription: open the EventSource with the page's\n  `live_resume_seq` as the initial `resume_seq` (`GET \u002Fv1\u002Fevents?resume_seq=…`),\n  so the server replays events strictly newer than the snapshot through the\n  existing bounded replay path; a browser reconnect's `Last-Event-ID` header\n  takes precedence. One terminal event for a rendered running\u002Fpaused turn\n  triggers exactly one `sessions.turns.get`, which replaces the bubble with\n  the sealed row. On page retry, rebuild the live membership from a freshly\n  read `sessions.turns.list` (never duplicate bubbles or re-admit a terminal\n  row).\n- **Administrative observability (HA-65 \u002F D-426).** The one bounded\n  administrative query is `observability.query` (`POST \u002Fv1\u002Fobservability\u002F\n  query`): mandatory time window, a closed `group_by` set (tenant \u002F user \u002F\n  session \u002F model), existing source-backed measures only (successful\n  completions, exact cost, tokens, latency count\u002Fsum\u002Fmin\u002Fmax, task\n  completed\u002Ffailed\u002Fcancelled), fixed UTC minute buckets (may coarsen), and a\n  mandatory freshness block (`current` \u002F `catching_up` \u002F `unavailable` +\n  watermark) on every response — never zero as a substitute for\n  unavailable. Widening to other tenants\u002Fusers requires the verified\n  `admin`\u002F`console:fleet` scope and emits one `audit.admin_scope_used`.\n- **User-skill package import (HA-61 \u002F D-422).** A caller may install a\n  reviewed `SKILL.md` package as a durable personal skill through\n  `agent_config.user.skills.import_validate` (returns a bounded opaque\n  sealed `proposal_token` plus the normalized review\u002Fhashes\u002Fexpiry — it\n  performs ZERO writes) and `agent_config.user.skills.import_commit` (echo\n  the token and reviewed hashes; the runtime reauthenticates and\n  revalidates, forces your scope + the effective agent, and installs the\n  package in one conditional write). A stale\u002Fforeign\u002Fexpired token answers\n  the typed `skill_import_proposal_*` refusal; `replace: true` is required\n  to replace an existing package.\n- **Draft-only skill authoring (HA-62 \u002F D-423).** `skill_create_draft` is an\n  ordinary runtime tool (absent from the model-visible catalog until an\n  operator enables it per agent through the ordinary tool policy) that turns a\n  bounded `{intent, feedback?}` into ONE caller-scoped immutable `SKILL.md`\n  draft artifact — an artifact ref plus its versioned `package_hash`, a\n  bounded summary\u002Fwarnings, and an explicit `state: \"draft\"` \u002F\n  `installed: false`. It persists exactly that one immutable caller-scoped\n  ArtifactStore draft and has zero skill-install\u002Fconfig\u002Fpack\u002Fmembership\u002F\n  authority mutation: no approval path, no skill-store upsert,\n  membership\u002Frevision write, or operator-pack proposal\u002Fpublication; identity\n  comes exclusively from the run context (`persist`\u002F`publish`-shaped input is\n  rejected), and declared required tools are metadata only. Installing a draft\n  is the LATER explicit HA-61 path: `agent_config.user.skills.import_validate`\n  the artifact ref, review, then `import_commit` — the runtime reauthenticates\n  and revalidates before the one conditional install.\n- **Composition preview (HA-66 \u002F D-427).** `agent_config.composition.preview`\n  (`POST \u002Fv1\u002Fagent_config\u002Fcomposition\u002Fpreview`, claim-free for your own\n  triple) reports the effective skill composition a run would compose for\n  the named agent: per-item `boot|revision|both` provenance, the\n  per-package semantic hash, and the deterministic `boot_pack_set_hash`.\n  The same strict resolver feeds boot preflight, run, and preview — the\n  preview never mutates.\n\n## 5. Pause + steer + resume\n\nThe unified pause\u002Fresume primitive (RFC §3.3) is one wire choreography for every cause — HITL approval, tool-side OAuth, operator pause. The steering verbs share one route shape, `POST \u002Fv1\u002Fcontrol\u002F{method}`, with the run id and your steering scope in the body's `identity`:\n\n```bash\n# park the run at the next planner-step boundary\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fpause\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {\"run\": \"'$TASK_ID'\", \"scope\": \"owner_user\"}}'\n\n# feed it context while parked, then wake it\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Finject_context\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {\"run\": \"'$TASK_ID'\", \"scope\": \"session_user\"}, \"payload\": {\"note\": \"Actually, make it Barcelona.\"}}'\n\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fresume\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {\"run\": \"'$TASK_ID'\", \"scope\": \"owner_user\"}}'\n```\n\nThe `200 {\"accepted\": true, …}` means *enqueued*; the effect is narrated on the event stream — `pause.requested` when the run parks, `pause.resumed` (with a typed `Decision` of `approve` \u002F `reject` \u002F `resume` \u002F `timeout`) when it wakes. The planner sees injected context on its next step.\n\nFor HITL: an approval-gated tool emits `tool.approval_requested` with a pause token; your UI routes the human verdict through `POST \u002Fv1\u002Fcontrol\u002Fapprove` or `\u002Freject` with `\"payload\": {\"token\": \"\u003Cpause-token>\", \"reason\": \"…\"}`. `POST \u002Fv1\u002Fpause\u002Flist` is the snapshot of everything currently awaiting a human — reconcile against it on every (re)attach; it is authoritative across Runtime restarts. The full wire choreography (including the OAuth callback leg and `DecisionTimeout` reaps) is the published [pause-model choreography](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fpause-model).\n\nThe \"steer vs queue\" UI choice in [`drive-the-playground`](..\u002Fdrive-the-playground\u002FSKILL.md) §3 maps directly to \"POST `\u002Fv1\u002Fcontrol\u002Fpause` + inject + resume\" vs \"wait for `task.completed` then POST a new `start`\".\n\n## 6. Artifact upload — multimodal input\n\nFor images \u002F PDFs \u002F audio uploads from your UI, `artifacts.put` is a control-surface method: POST the bytes (base64-encoded inline on the request leg) and you get back a reference, never an echo of the body:\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fartifacts.put\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"scope\": {\"tenant\": \"dev\", \"user\": \"dev\", \"session\": \"dev\"},\n    \"bytes\": \"'\"$(base64 \u003C report.pdf)\"'\",\n    \"opts\": {\"mime_type\": \"application\u002Fpdf\", \"filename\": \"report.pdf\"}\n  }'\n```\n\nResponse carries the canonical `ref`:\n\n```json\n{\n  \"ref\": {\n    \"id\": \"art_01H...\",\n    \"mime_type\": \"application\u002Fpdf\",\n    \"size_bytes\": 142853,\n    \"filename\": \"report.pdf\"\n  },\n  \"protocol_version\": \"0.1.0\"\n}\n```\n\nPass `ref.id` in `start`'s `input_artifact_ids`. The upload bytes ride the request leg only (base64-inline, bounded by the Runtime's max request size — an oversize body is rejected with `request_too_large`); the response is a reference, and bytes never reach the LLM edge inline.\n\n### 6.1 Reading an artifact's bytes back — `artifacts.get`\n\n`artifacts.get` is the read that works everywhere. It resolves through the artifact store's mandatory `Get`, so **every** driver serves it — including the `inmem` default a fresh `harbor dev` boots on. (`artifacts.get_ref` is not an alternative to it so much as an optimisation: it returns a presigned URL, which only an S3-compatible store can mint, and answers `presign_unsupported`\u002F501 everywhere else.)\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fartifacts.get\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"scope\": {\"tenant\": \"dev\", \"user\": \"dev\", \"session\": \"dev\"},\n    \"id\": \"'\"$REF_ID\"'\",\n    \"offset\": 0,\n    \"max_bytes\": 65536\n  }'\n```\n\n```json\n{\n  \"ref\": { \"id\": \"art_01H...\", \"mime_type\": \"text\u002Fcsv\", \"size_bytes\": 4194304 },\n  \"content\": \"\u003Cbase64>\",\n  \"offset\": 0,\n  \"returned_bytes\": 65536,\n  \"total_size_bytes\": 4194304,\n  \"truncated\": true,\n  \"protocol_version\": \"0.1.0\"\n}\n```\n\n**The response is always truthful about its own bound.** `total_size_bytes` is the artifact's full size, `returned_bytes` is what this call gave you, and `truncated` says whether anything follows the window — so a bounded read is never mistakable for a complete one.\n\n**To page a large artifact**, re-call with `offset` advanced to the previous `offset + returned_bytes`, while `truncated` is `true`. Windows are **byte** ranges, not lines or rows, so a window can begin and end mid-line and splitting is your job.\n\n**Three things can bound one read** and they all report through those same fields: your own `max_bytes`, the deployment's `artifacts.fetch_default_max_bytes` (applied when you name none — 64 KiB by default), and its `artifacts.fetch_hard_max_bytes` ceiling (1 MiB by default). Asking for more than the ceiling is **not an error** — you are served at the ceiling and `truncated` tells you so, because you have no way to discover the ceiling before asking. A NEGATIVE `offset` or `max_bytes` *is* rejected with `invalid_request`; it is not an omission the Runtime can resolve for you.\n\n**The ceiling bounds one read, not a sequence.** It is not a budget over repeated calls — aggregate consumption is the governance layer's concern (cost ceilings and rate limits).\n\nIdentity rules match the rest of the artifact surface: the full triple is mandatory, an id your scope does not hold answers `not_found`\u002F404 identically to one that never existed (existence is never revealed across identities), and a `scope` naming a tenant other than your verified one is refused `scope_mismatch`\u002F403 — **no admin claim widens this method**, because it hands over content rather than metadata.\n\nInside a run, the model reaches an artifact through the `artifact_fetch` builtin, which takes the same `offset` \u002F `max_bytes` and answers the same `offset` \u002F `returned_bytes` \u002F `total_size_bytes` \u002F `truncated` field set under the same operator-configured ceiling.\n\n**They are not the same read, and the difference is the point.** `artifacts.get` returns `content` as `[]byte` (base64 on the wire), so it is **byte-exact for every MIME at every offset** — a PDF, an image, a zip. `artifact_fetch` returns `content` as a JSON **string**, so it is a TEXT read: it tests the window for UTF-8 admissibility and **refuses one it cannot return intact** rather than letting JSON encoding rewrite invalid bytes to `U+FFFD` and hand the model corruption at a length the response contradicts. A refusal still carries `ref` \u002F `mime` \u002F `size_bytes` \u002F `total_size_bytes`, leaves `content` empty, and zeroes the windowing fields. The gate is content-driven, not MIME-driven — a text artifact carrying one invalid byte mid-window refuses too, rather than dropping it silently. `artifact_fetch` also trims partial runes at both window edges and reports the `offset` where content actually begins, and floors its effective `max_bytes` at 4; `artifacts.get` does neither, because it has no reason to.\n\nSo: reach for `artifacts.get` when you want the bytes. `artifact_fetch` is the model's text-recovery path; binary content reaches a tool through an artifact-reference parameter, not through the model.\n\n## 7. Topology snapshot — render the runtime's wiring\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Ftopology.snapshot\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {}}'\n```\n\nResponse is a graph of components + edges — Bifrost, tool catalog (with per-tool nodes), memory driver, state driver, artifact store, event bus, skill catalog. The Console's Topology page is one consumer; your custom dashboard could be another.\n\nThe capability is `topology.snapshot: true` (V1.1 phase 84a).\n\n## 8. Typed wire shapes — where they actually come from\n\nThree trustworthy sources, none of which is hand-rolling:\n\n- **Vendor the generated external-client TS module (TypeScript clients — start here).** `cmd\u002Fharbor-protocol-ts-types` emits `examples\u002Fprotocol-clients\u002Fevent-viewer-ts\u002Fharbor-protocol.gen.ts` — a self-contained, dependency-free module of TypeScript `interface`s for every canonical wire type plus `HarborMethod` \u002F `HarborErrorCode` \u002F `HarborEventType` string-union types and the pinned `PROTOCOL_VERSION` \u002F `WIRE_SURFACE_DIGEST` constants. Copy that one file into your client and write your transport against it. Regenerate \u002F re-vendor with `make protocol-ts-types-gen`; it is drift-gated by `make protocol-ts-types-gen-check`. The worked `event-viewer-ts` client consumes it against the dev runtime. This module carries **types only, no client logic** — it is distinct from the Console's hand-maintained `protocol.ts` (which carries the typed `HarborClient`), and the FULL Console-`protocol.ts` generator remains deferred (D-132); the `cmd\u002Fharbor-gen-protocol-ts` name stays reserved for it.\n- **The generated contract reference** — [the generated types page](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Ftypes) catalogues every canonical wire struct field-by-field with the snake_case JSON keys, generated by `cmd\u002Fharbor-gen-protocol-docs` from the Go single sources and drift-gated by `make protocol-docs-gen-check`. Read it (or transcribe from it) when you want the field-level reference; when the wire changes, the page changes in the same PR by construction.\n- **Vendor the Console's client module** — copy `web\u002Fconsole\u002Fsrc\u002Flib\u002Fprotocol.ts` into your TS client when you also want the typed `HarborClient` transport (not just the types). It is **hand-maintained** in lockstep with the Go wire types (the full TS-client *generator* is deferred per D-132 \u002F issue #179), kept honest by the Console's CI. License is Apache-2.0; attribution required.\n- **Import the curated Go client facade** — Go applications import `github.com\u002Fhurtener\u002FHarbor\u002Fsdk\u002Fprotocolclient`. It exposes only the supported typed methods, generic JSON call core, typed errors, and SSE stream; it does not wholesale re-export Runtime internals or every Protocol method.\n\nHand-rolling the types from scratch is fine for a quick prototype but you'll drift. Anchor any client you intend to maintain on the generated module or the generated reference.\n\n### 8a. Reading a downstream scope shortfall\n\nWhen an MCP-backed tool call is refused downstream with a `403` + `WWW-Authenticate: Bearer error=\"insufficient_scope\"` (RFC 6750 §3.1), the shortfall surfaces as **structured data on the two surfaces you already read** — never an opaque error string:\n\n- **On the tool-result error path** — the `tool.failed` event's `ScopeShortfall` field carries `downstream_resource`, `required_scopes`, `granted_scopes`, the verbatim `www_authenticate` header, and `origin`. It is set only when the challenge is explicitly marked `insufficient_scope`; an unmarked 403 stays an opaque failure. The runtime classifies the shortfall as **permanent** (it never retries a shortfall retrying cannot fix).\n- **On the MCP connection view** — `mcp.servers.get` returns `MCPServerView.last_scope_shortfall` (`MCPScopeShortfallView`) recording the last observed shortfall on that connection — visible even to a reader who never made the offending call. It rides the DETAIL read only (like `oauth_requirement`), not the hot list row.\n\nBoth are **report-only**: the runtime never auto-escalates, re-consents, or widens a binding on a shortfall. The operator acts on it via the boot-declared `oauth_provider` \u002F `tool_oauth_providers` bindings (which bind a distinct provider per MCP-side entry — a tool call by tool name, a resource read \u002F subscribe by resource URI, and a prompt get by prompt name — for a server fronting several downstream audiences).\n\n**Typed MCP failure classification survives replay (HA-54 \u002F D-410).** When an\nMCP server marks a `CallToolResult` `IsError: true` with the namespaced\n`harbor.error` classification (`{error: {class, message}}` on `_meta` or in\n`structuredContent`), the runtime lowers it to a typed failure — one of\n`invalid_argument` \u002F `validation` \u002F `authorization` \u002F `not_found` \u002F `conflict`\n\u002F `tool_domain` \u002F `transient` \u002F `provider_unavailable`, with a bounded\nmessage — and projects it onto permanent-vs-retryable policy: the\ndeterministic classes invoke exactly once (a `conflict` such as a\n`revision_conflict` is permanent for the unchanged invocation and carries the\ncurrent revision in its bounded message for reread\u002Fretry), while a retryable\nprovider\u002Ftransport failure uses the configured budget. The classified\nobservation SURVIVES the runloop's step recording into the actual next ReAct\nprompt: the typed class, retry-policy outcome, bounded message, and retained\nbounded result content render as fields, and a generic `Step.Error` never\nmasks them. Raw tool arguments are redacted on every failed-replay shape — no\nraw args, secrets, or unbounded provider output reach the observation or the\nprompt. For providers without the Harbor extension, an `IsError` result's\ntop-level `structuredContent.code` has a closed compatibility mapping:\n`invalid_argument` → `invalid_argument`, `validation_failed` → `validation`,\n`forbidden_scope` \u002F `scope_blocked` \u002F `scope_mismatch` → `authorization`,\n`not_found` → `not_found`, and `document_too_large` → `tool_domain`.\nThese deterministic codes stop after one invocation. The error message is the\ncode followed by the provider's bounded text content, so its repair detail\nreaches the planner; the text never affects the class. The original structured\ncontent, including any document outline, remains available; oversized-document\nfailures also tell the planner to read a smaller section or reduce the\nprovider's read-size limits instead of repeating the same full read. A valid\nnamespaced classification takes precedence. Unknown codes, nested codes,\n`retryable: true`, malformed retryability, and malformed explicit Harbor\ncontracts retain the transient fallback; no prose is parsed.\nA legacy unclassified `IsError` keeps the generic safe fallback: its\nlowered text is preserved, policy treats it as transient, and the generic\nrender remains. The terminal projection is observable on the stream as\n`tool.failed` (`ErrorClass` \u002F `ErrorMessage` \u002F `Attempts`) and\n`tool.policy_exhausted` (`LastClass` \u002F `LastError`), which agree with what the\nplanner observed.\n\n**Downstream HTTP authentication and session recovery.** For signed receiver\nbindings with `authenticate_preparation` enabled and injected header or Basic\ncredentials, an MCP server's HTTP 401 or 403 does not terminate Harbor's shared\nstreamable HTTP session. A later call resolves its own credential again. A call\nretries once through a replacement session only when the SDK confirms that a\nclosed connection rejected it before dispatch. A missing session is repaired\nfor later calls without replaying a tool call, since an in-flight call may\nalready have executed; only read-only operations may replay once. Other\ntransport errors do not trigger this recovery. Harbor never silently falls back to an\nunauthenticated request. At the MCP Protocol edge,\n`downstream_mcp_unauthorized` uses HTTP 424 (Failed Dependency), requiring\ncredential intervention, while `downstream_mcp_transport_failed` uses HTTP\n502. Both have fixed summaries that exclude upstream endpoints, response\nbodies, headers and credentials. They identify downstream failures, so do not\nrefresh the Harbor connection JWT or mark the Runtime disconnected because of\nthese codes. Resolve a credential refusal before retrying; back off for an\nunavailable server. A transport failure alone does not establish whether a\nside-effecting operation is safe to replay.\n\n### 8b. What an MCP connection admin write can reach\n\nThe per-server `mcp.servers.*` admin verbs gate on the `admin` scope claim, and the write ones additionally land only where your own identity reaches:\n\n- `mcp.servers.set_raw_html_trust` (the per-server raw-HTML posture a rendered MCP App is given) is **tenant-scoped**. It applies to a connection your own tenant owns, or to a boot-declared (yaml) server, which is deployment-global infrastructure every session already sees. Naming a connection another tenant attached is refused `404 {\"code\": \"not_found\"}` — the same answer you get for a name nobody registered, so the refusal tells you nothing about what other tenants have attached. The scope comes from your verified identity, not from anything on the request body.\n- `agent_config.set_mcp_discovery_origins` is **owner-scoped** to your `(tenant, agent_id)` and refuses `403 {\"code\": \"scope_mismatch\"}` — see §8's account of that verb. The two differ because that door carries an `agent_id` and this one does not.\n- A write whose audit event cannot be emitted is **reverted**, not left applied: you get `500 {\"code\": \"runtime_error\"}` naming the reverted-not-applied case, and the previous value stands.\n\nBoot-declared servers stay visible to every session. Tenant-owned sources require current signed agent reach and selection in the owning configuration; personal sources also require the owning user. The source-addressed `refresh_discovery` \u002F `probe` calls use the exact returned server ID and carry that admitted registration's owner agent into credentialed discovery. An existing effective-agent selection must agree; neither the admin scope nor a boot invoking-agent attribution substitutes for signed reach or current configuration.\n\n### 8c. Not clobbering another writer — `expected_content_hash`\n\nEvery `agent_config.*` spine write is **last-writer-wins by default**. If you read a config, edit it, and write it back, any change another writer made in between is silently reverted and you are told `200`. That window is seconds to minutes for a human editing in the Console, and however long your agent takes to compose a config.\n\nTo close it, send the **expected-revision token**. `agent_config.get` returns both `revision_id` and `content_hash` on the active revision; pass that `content_hash` back as `expected_content_hash` on your write:\n\n```jsonc\n\u002F\u002F 1. read\nPOST \u002Fv1\u002Fagent_config\u002Fget     → { \"revision\": { \"revision_id\": \"01J…\", \"content_hash\": \"9f2c…\" }, \"set\": true }\n\n\u002F\u002F 2. write under the base you read\nPOST \u002Fv1\u002Fagent_config\u002Fset_revision\n{ \"agent_id\": \"support-bot\",\n  \"payload\": { \u002F* … your edit … *\u002F },\n  \"expected_content_hash\": \"9f2c…\" }\n```\n\n- **Matching** → the write proceeds exactly as an unconditional write would.\n- **Not matching**, or **a hash sent when no active revision exists** → `409 {\"code\": \"revision_conflict\"}`, and **nothing is persisted**: no revision, no active-pointer move, no `agent.config.revised` event.\n- **Omitted** (the default) → byte-for-byte the unconditional behaviour that has always shipped. Nothing you have today changes.\n\n**The first write needs its own token.** When `agent_config.get` answers `{\"set\": false}` the agent has no config yet and there is no `content_hash` to echo back. Send the reserved value `\"-\"`:\n\n```jsonc\nPOST \u002Fv1\u002Fagent_config\u002Fget     → { \"set\": false }          \u002F\u002F no hash exists\n\nPOST \u002Fv1\u002Fagent_config\u002Fset_extra_system_blocks\n{ \"agent_id\": \"support-bot\",\n  \"extra_system_blocks\": { \"blocks\": [ \u002F* your block *\u002F ] },\n  \"expected_content_hash\": \"-\" }                          \u002F\u002F \"I expect there to be none\"\n```\n\nIt succeeds only while the agent has no active revision, and returns `409 {\"code\": \"revision_conflict\"}` the moment one exists. **Send it — do not omit the token on a first write.** Omitting it is an unconditional write, so two contributors composing onto a fresh agent both succeed and the second silently reverts the first. A real content hash is always 64 lowercase hex characters, so `\"-\"` can never collide with one.\n\n**`add_mcp_connection` prepares before it publishes.** The expected hash is checked under the owner lock before any dial or provider preparation. After that check, Harbor may dial, authenticate, handshake, and discover into a private preparation, but the provider, catalog entries, live registration, and `online` state remain unpublished until the desired revision is durable. A `409` therefore closes only unpublished resources and leaves the exact prior live connection intact. Activation stages the registry reversibly and makes the catalog swap the dispatch boundary; a collision restores both. If a write reports failure, an exact pointer re-read distinguishes a confirmed landing from not-landed or unreadable state—there is no unconditional detach fallback. Inline OAuth uses an installation receipt, so rollback can remove only the provider this call installed.\n\nIt is available on all **seventeen** spine-writing doors — `set_revision`, `rollback`, `skills.upsert`, `skills.delete`, `set_tool_exposure`, `set_prompt_layers`, `set_extra_system_blocks`, `set_llm_params`, `add_mcp_connection`, `remove_mcp_connection`, `set_mcp_discovery_origins`, `set_oauth_provider`, `remove_oauth_provider`, and the four `user.*` twins (`user.set_revision`, `user.rollback`, `user.skills.upsert`, `user.skills.delete`). It is **not** on `set_llm_provider` (which installs a provider and writes no revision) or on the `agent_config.session.*` verbs (which write the ephemeral session overlay, not the durable spine).\n\n**Read your token from the tier you are about to write.** The examples above use `agent_config.get`, which reads the AGENT tier — correct for the thirteen admin doors. The four `user.*` twins write the USER tier, and its hash comes from **`agent_config.user.get`**. They are separate revision spines: a hash read from `agent_config.get` will never match a `user.*` write, so passing one there is a guaranteed `409` every time.\n\n**Recovering from a conflict.** Re-read `agent_config.get` for the current `revision_id` + `content_hash`, call `agent_config.diff` with `from_revision` = the id you originally read and `to_revision` = the current id to see what moved, re-apply your edit on top, and resubmit with the fresh hash. One extra round trip on a rare path.\n\n**Why a content hash and not a revision id.** `rollback` repoints the active pointer without necessarily changing the content. If the token were a revision id, an operator restoring exactly the content you read would be reported to you as a conflict — a false positive on the recovery path. The token tracks the value you computed against, which is what you actually depend on.\n\n**Know the authority before you rely on it.** The refusal is exact across\nRuntime processes sharing any shipped StateStore driver. Publication rechecks\nthe active-pointer EventID through the triad-wide `StateStore.SaveIf` predicate;\nthe agent-config service's per-owner write lock only reduces same-process\ncontention. This does not make a token an exclusive lock: a concurrent writer\nthat omits the token remains an unconditional last writer by design.\n\nTwo more things worth knowing:\n\n- **The token constrains only the writer that supplies it.** A concurrent writer that omits it can still overwrite you, by design — the token is a precondition on your write, never a lock on the agent. Exclusivity requires every writer of that agent's config to participate.\n- **It is a precondition, never an authority.** It is compared strictly after the identity and scope gates and can only ever cause a write to be *refused*. A valid token never buys a caller a write it could not otherwise make.\n\n### 8d. Retiring an agent-config identity is terminal — `agent_config.retire`\n\n`agent_config.retire` is an **admin-only**, owner-scoped lifecycle operation. It replaces the active agent-config pointer with a durable tombstone; it does not delete immutable revision history. Supply a non-empty `operation_id` and the active `expected_content_hash` (or `\"-\"` when there has never been an active revision). A same-operation retry is valid only when it repeats that exact original expectation; a different operation or expectation returns `409 {\"code\":\"agent_retirement_conflict\"}`.\n\nAfter retirement, all active\u002Fcurrent config reads and durable writes, plus every `agent_config.session.*` overlay write, fail with `409 {\"code\":\"agent_retired\"}`. `agent_config.list_revisions` and `agent_config.diff` remain available for immutable-history audit. To recover status or resume cleanup after a timeout or restart, repeat `agent_config.retire` with the exact same `operation_id` and original `expected_content_hash`; that replay returns the durable status and continues any pending cleanup, while either value changing is a conflict. Operators should watch the canonical `agent_config.retirement.started`, `.progress`, and `.completed` events; event payloads expose only the hashed operation identifier and cleanup counts, never config contents.\n\nD-401 signed OAuth MCP pairs are retired through their existing durable paired-removal receipt even when the original authority has expired, been revoked, or can no longer be verified after key rotation. The retirement status may expose a `signed_oauth_mcp_pair` cleanup class whose resource is hashes only; it never exposes the URL, JWT\u002FJTI, credentials, or stored owner subject. A close failure leaves the retirement incomplete and retryable with the same retirement operation.\n\nFor a signed receiver capability that requires credentials during initialize or\ndiscovery, sign `connection.injection.authenticate_preparation: true` inside the\nauthority envelope and submit the identical descriptor. Initialize, each list,\nrefresh, and reattachment use the verified acting identity and fail before any\nrequest on missing or failed credentials. Header and Basic injection support HTTP\npreparation; meta injection requires streamable HTTP. An unsigned connection write\ncannot enable this setting. Omitted or false preserves existing preparation.\n\nAn agent may carry more than one signed OAuth MCP capability. Revision payloads\nproject the first pair in `signed_oauth_mcp_pair` and additional providers in\nthe `signed_oauth_mcp_pairs` object keyed by `provider_name`; clients should\nread both as one set. To remove one pair from a multi-pair revision, send that\nprovider name with the revision's `expected_content_hash`. Omitting\n`provider_name` works only when the named revision contains exactly one pair.\nRegistration, restart recovery, removal, and retirement remain independent per\npair, so removing one capability does not disconnect its siblings.\n\nRetirement does **not** deregister the Runtime fleet agent. `agents.deregister` remains a separate fleet lifecycle action with separate authorization and audit semantics.\n\n### 8e. Contributing ONE prompt block without owning the whole prompt — `extra_system_blocks`\n\nIf two independent capabilities each want to add a paragraph to an agent's system prompt, the layered prompt does not help: `prompt_layers.base` and `prompt_layers.user` are ONE string each, so the second contributor has to know — and re-send — the first's text, and removing one contribution means re-deriving the composition from prose.\n\n`POST \u002Fv1\u002Fagent_config\u002Fset_extra_system_blocks` gives that composition a NAMED, ORDERED carrier:\n\n```jsonc\nPOST \u002Fv1\u002Fagent_config\u002Fset_extra_system_blocks\n{ \"agent_id\": \"support-bot\",\n  \"extra_system_blocks\": { \"blocks\": [\n      { \"name\": \"billing-policy\", \"body\": \"Never quote a refund amount; hand off to billing.\" },\n      { \"name\": \"tone\",          \"body\": \"Answer in \u003C=3 sentences.\" }\n  ] },\n  \"expected_content_hash\": \"9f2c…\" }\n```\n\n- **Order is the render order.** The array order is what the model sees, it is part of the revision's `content_hash`, and a pure re-ordering is a real new revision that `agent_config.diff` reports as `extra_system_blocks.reordered: true`. (Contrast `skills.names` and `oauth_providers`, whose orders are canonicalised by sorting.)\n- **It is a WHOLE-SECTION desired-state replace**, like every sibling section. There are deliberately no per-block verbs — a block is one element of an ordered composition, so a per-item upsert has no well-defined insertion position. **To add or remove exactly your own block: `agent_config.get` → append or drop your entry BY NAME → write the full list back with the read revision's `content_hash` as `expected_content_hash` (§8c), or `\"-\"` when the read answered `{\"set\": false}`.** Without a token you can silently delete a sibling contributor's block; with it you get `409 {\"code\": \"revision_conflict\"}` and retry.\n- **Names are unique and match `[A-Za-z0-9._-]{1,64}`.** A duplicate or malformed name is refused `400 {\"code\": \"invalid_request\"}`, naming the offender and (for a duplicate) both positions, and nothing is persisted. Uniqueness is what makes remove-by-name well defined.\n- **Bodies render VERBATIM** — unescaped, in declared order, each behind a plain-text `[name]` label, inside the existing operator-owned `\u003Cadditional_guidance>` section. They compose below the runtime's baked guidance and above the admin-set tenant guidance, and they **survive a session `system_prompt_override`** (which replaces only the base+user spine). The ordinary caller's one-run `extra_instructions` value is separate: it renders escaped in `\u003Cuser_personalization>` and never joins these blocks.\n- **The verb is admin-scoped, and that tier IS the trust boundary.** Blocks are unescaped because only the admin tier — the same tier that writes `prompt_layers.base`, which is already verbatim and strictly more powerful — can write them. **Therefore: never put user-authored or model-authored text in a block.** Recalled conversation content belongs in `start.caller_memory`, which lands in the untrusted-framed memory tier; user instructions belong in `prompt_layers.user`, which IS escaped precisely because a claim-free session path can write it.\n- **The `[name]` label is legibility, not a security boundary.** It helps a human reading a transcript tell contributions apart. To the model, two blocks from two capabilities are one contiguous run of trusted guidance.\n- Omitting the section entirely leaves the composed prompt byte-identical to an agent that never had one. Every sibling section (prompt layers, skills, tool exposure, connections, OAuth providers, LLM params, hooks, naming) is carried forward across a block write, and vice versa.\n\n## 9. A minimal client (TS, ~30 LoC)\n\n```typescript\nconst baseUrl = \"http:\u002F\u002F127.0.0.1:18080\";\nconst token = \"\u003CHARBOR_DEV_TOKEN>\";\nconst identity = { tenant: \"dev\", user: \"dev\", session: \"dev\" };\n\n\u002F\u002F One REST call per method: POST \u002Fv1\u002F\u003Cfamily>\u002F\u003Cmethod>, flat body in, flat body out.\nasync function call\u003CT>(route: string, body: object): Promise\u003CT> {\n  const res = await fetch(`${baseUrl}${route}`, {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application\u002Fjson\",\n      \"Authorization\": `Bearer ${token}`,\n      \"X-Harbor-Tenant\": identity.tenant,\n      \"X-Harbor-User\": identity.user,\n      \"X-Harbor-Session\": identity.session,\n    },\n    body: JSON.stringify(body),\n  });\n  if (!res.ok) {\n    const err = await res.json().catch(() => ({ code: `http_${res.status}` }));\n    throw new Error(err.code ?? `http_${res.status}`);\n  }\n  return res.json() as Promise\u003CT>;\n}\n\nconst info = await call(\"\u002Fv1\u002Fcontrol\u002Fruntime.info\", { identity: {} });\nconsole.log(\"connected to harbor\", info);\n\nconst { task_id } = await call\u003C{ task_id: string }>(\"\u002Fv1\u002Fcontrol\u002Fstart\", { identity: {}, query: \"Hello!\" });\n\n\u002F\u002F The stream is session-scoped (no task_id query param), so filter client-side.\nconst sse = new EventSource(`${baseUrl}\u002Fv1\u002Fevents?access_token=${encodeURIComponent(token)}`);\nsse.addEventListener(\"llm.completion.chunk\", (e) => {\n  const data = JSON.parse(e.data);\n  const chunk = data.payload;\n  if (chunk.TaskID === task_id && chunk.Kind === \"content\") {\n    process.stdout.write(chunk.Delta); \u002F\u002F Provisional animation, not the final answer.\n  }\n});\nsse.addEventListener(\"task.completed\", (e) => {\n  if (JSON.parse(e.data).payload.TaskID === task_id) sse.close();\n});\n```\n\nThis fragment demonstrates live content routing only. A production chat client\nalso needs the restart\u002Fhistory choreography above, response-boundary grouping,\nfailed\u002Fcancelled terminal handling, and final-answer reconciliation; it must not\ntreat concatenated progress text as the final answer.\n\n## Common failure modes\n\n- **Every call returns 401.** Token expired (24h TTL) or rotated (`harbor dev` restarted). Re-fetch token, retry.\n- **CORS preflight fails.** Your origin isn't in `server.allowed_origins`. Add it to the yaml + restart Runtime.\n- **SSE stream opens but no events.** The `payload.TaskID` capital-T gotcha — your handler is reading `payload.task_id` (lowercase). Fix the case.\n- **A control call returns `404 {\"code\": \"unknown_method\"}` or 405\u002F501.** This runtime doesn't serve that surface. Call `runtime.info` first, branch on `capabilities`, and degrade the feature instead of crashing (the [versioning & compatibility contract](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fversioning-and-compatibility)).\n- **Artifact upload returns 413 Payload Too Large.** The request body exceeded the Runtime's `protocol.max_request_bytes` (default 4 MiB) — the canonical `{\"code\": \"request_too_large\"}` envelope. Chunk uploads aren't supported in V1.1; raise `protocol.max_request_bytes` in the Runtime's `harbor.yaml` if you need larger inline uploads.\n- **An agent-config write returns `409 {\"code\": \"revision_conflict\"}`.** You sent an `expected_content_hash` and another writer moved the base between your read and your write. Nothing was persisted. Re-read `agent_config.get`, re-apply your edit on the current content, and resubmit with the fresh hash — see §8c. (You also get this code when you send a *hash* and the agent has **no** active revision — send the reserved `\"-\"` for that case — and when you send `\"-\"` and a revision already exists.)\n- **Topology snapshot rejected.** This Runtime doesn't advertise the `topology_snapshot` capability — check `runtime.info.capabilities` before enabling the panel.\n- **The Console reads internal Runtime objects.** It doesn't — that would be a CLAUDE.md §13 violation. If you suspect leakage, file a bug; the Console reads only what's documented as a Protocol surface.\n\n## See also\n\n- **The Protocol adoption track** — [the published quickstart + generated reference + choreographies](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002F): the adopter-facing contract docs this skill's recipes sit on top of. Start there for any client you intend to maintain. The track is complete: five choreographies (including [the pause model](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fpause-model) and [versioning & compatibility](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fversioning-and-compatibility)), the worked [build-a-client guide](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fbuild-a-client) (its ~150-line SDK-free event viewer ships at `examples\u002Fprotocol-clients\u002Fevent-viewer\u002F`), and the [conformance-certification path](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fconformance-certification).\n- [`run-the-dev-loop`](..\u002Frun-the-dev-loop\u002FSKILL.md) — boot the Runtime + grab the dev token first.\n- [`drive-the-playground`](..\u002Fdrive-the-playground\u002FSKILL.md) — the Console's chat UI; same Protocol underneath.\n- [`observe-with-the-console`](..\u002Fobserve-with-the-console\u002FSKILL.md) — every Console page maps 1:1 to a Protocol method.\n- The wire types: `internal\u002Fprotocol\u002Ftypes\u002F`.\n- The methods registry: `internal\u002Fprotocol\u002Fmethods\u002Fmethods.go`.\n- The error codes: `internal\u002Fprotocol\u002Ferrors\u002Ferrors.go`.\n- The public Go client: `sdk\u002Fprotocolclient`.\n- The docs generator: `cmd\u002Fharbor-gen-protocol-docs\u002F` (D-209). The external-client TS wire-type generator: `cmd\u002Fharbor-protocol-ts-types\u002F` (D-269) → `examples\u002Fprotocol-clients\u002Fevent-viewer-ts\u002Fharbor-protocol.gen.ts`. The FULL Console-`protocol.ts` TS-client generator remains deferred (D-132 \u002F issue #179, name `cmd\u002Fharbor-gen-protocol-ts` reserved); `protocol.ts` is hand-maintained.\n- RFC §5 — Harbor Protocol design.\n\nFor shared-runtime broker custody, require the runtime.info capability\n`tenant_scoped_broker_credentials_v1`; its absence means tenant-selected broker\nclient credentials are unsupported. This describes the runtime pull implementation,\nnot proof that a particular coordinator endpoint or grant is ready.\n\n### Configure the agent's working-input budget\n\nNegotiate `agent_config_memory_v1` on `runtime.info` before writing\n`agent_config.set_revision.payload.memory.budget_tokens`. This admin-only,\nnonnegative token target uses the existing revision\u002FCAS\u002Fdiff\u002Frollback surface.\nAn absent memory section inherits runtime YAML; explicit zero requests automatic\nmodel sizing. Preserve writable sibling sections and use the active revision's\ncontent hash as `expected_content_hash`. The next run freezes the new target;\nin-flight runs keep their original budget. It is not an output-token limit or\na cap on stored exact evidence. An unwired compactor is a loud refusal, not an\naccepted but ineffective configuration. Embedded callers continue using YAML\nor the equivalent configuration object.\n\n### Send model and thinking with Start\n\nFor a run-specific selection, use `llm_settings` on `control.start` instead of\npairing `runs.set_overrides` with a later Start. Negotiate\n`run_llm_settings_v1` when supporting older runtimes. Example request members:\n\n```json\n{\"llm_settings\":{\"model\":\"configured-model\",\"reasoning_effort\":\"high\",\"max_tokens\":2048}}\n```\n\nFor an external model, omit `llm_settings.model` and include the existing opaque\n`provider_route` beside `llm_settings` on Start. Never supply both model sources.\nSettings are copied into the accepted task; concurrent selections cannot replace\nthem. Exact retries reuse the task; changing settings under the same idempotency\nkey conflicts. A present bundle skips the legacy next-message slot. Omitted\nfields use runtime\u002Fagent defaults, an empty reasoning value requests provider\ndefaults, and `off` disables thinking. No preference is saved and no restart is\nneeded. Governance and selected-model support remain authoritative.\n\n### Run limits\n\nNegotiate `run_limits_v1` on `runtime.info`. A run can be bounded by maximum\nactive duration (time waiting on a pause is not counted) and maximum cumulative\nprompt plus completion tokens; each is optional and unset means no limit.\n\n- Runtime default: `runtime.run_limits.{max_duration, max_tokens}` in YAML.\n- Per agent: `agent_config.set_revision.payload.run_limits` with\n  `max_duration_seconds` and\u002For `max_tokens` (positive integers). A present\n  section replaces the runtime default; an omitted field means no limit for\n  that dimension, so `{\"run_limits\":{}}` removes both. Preserve sibling\n  sections and use `expected_content_hash` as for any revision. The\n  `agent_config.diff` response carries `run_limits` only when it changed.\n- Per run: `control.start` accepts\n  `{\"run_limits\":{\"max_duration_seconds\":600,\"max_tokens\":200000}}`, which can\n  only tighten the effective limit, never loosen or remove it. It is part of\n  Start's idempotency identity.\n\nWhen a run reaches a limit it emits `run.limit_reached` (payload `Limit` —\n`max_duration` or `max_tokens` — plus the configured values, elapsed time,\ntokens used and step count), makes one bounded call without tools that states\nwhat was done and what remains, and completes normally: `task.completed` with\n`result_inline.finish_reason` set to `limit_reached` and the partial answer.\nA limit never produces `task.failed`. A run with an output schema that stops at\na limit completes without `answer_payload`; check `finish_reason` before\nreading it. Show the person that the limit was\nreached and let them continue in the next message.\n\n### Session artifact tools\n\nWhen the runtime lists them in `tools.built_in`, the model can call\n`artifact_search` (grep inside a stored text artifact; each match carries\n`line`, `byte_offset` for `artifact_fetch`, and context), `artifact_list`\n(newest-first, filter by `source` — `user_upload`, `tool`, `other` — by\nproducing `tool` or by filename text, with `cursor` pagination) and\n`artifact_note` (add, replace or clear a note of at most 1024 bytes). A note\nchange publishes `artifacts.note_set` with the artifact id and note size, never\nthe note text. All three resolve on the session's isolation triple.\n\nFor `artifact_list`, use `{}` for the first unfiltered page. Omit unused fields\nor use empty strings for unused string fields (blank strings also mean unset);\ndo not send `null`. The only nonempty `source` values are `user_upload`, `tool`\nand `other`; omit `source` to include all origins. Send `limit` as a JSON integer,\nnot a quoted number: omitted or nonpositive values use 20, and values above 50\nare capped at 50. To continue, copy the returned `next_cursor` string exactly\ninto `cursor`. A cursor is neither a page number nor an artifact ref. Invalid\nJSON types or unknown argument names fail validation before the tool runs;\ninvalid source values and cursor strings return a field-specific `error`.\n\n## Broker-bound manual App operations (candidate)\n\nTrusted host integrations may use the optional `app_operation` selector on\n`mcp.servers.read_resource` and `mcp.apps.call_tool`, as specified in\n[App operation v1](..\u002F..\u002Fcontracts\u002Fapp-operation-v1.md). The selector is not\npermission or a bearer. Keep it and runtime credentials outside the frame.\nCallbacks still require fresh render admission; the broker must acknowledge the\nexact binding and current policy. Unsupported brokers refuse. This candidate\nrequires external integration acceptance before activation and does not alter\nordinary credential caching or authorize a chat\u002Fplanner fallback.\n","# Use the Harbor Protocol\n\n## Bounded execution and artifact bearers\n\nAn issuer can bind a Start request to an external operation with signed\n`execution_operation_id`, `execution_idempotency_key`, and\n`execution_start_sha256` claims. Sign the exact raw JSON body sent to\n`POST \u002Fv1\u002Fcontrol\u002Fstart`, set the same idempotency key in that body, and pin\n`session_reach` to the token's single session. Harbor rejects a changed body\nor session before admission and retains the opaque operation ID through task\nrecovery for downstream tool-token exchange. Tool arguments cannot set it.\n\nFor browser artifact transfer, issue a short-lived signed `artifact_transfer`\nobject with `mode`, `id`, and `max_bytes`, empty elevated scopes\u002Fagent reach,\nand one exact `session_reach`. `read` permits only `artifacts.get` for that\nreference when its full size fits the bound. `write` permits only\n`artifacts.put` into the named namespace, with `source: \"user_upload\"`, no\ntask scope, and a body within the bound. Write namespaces use ASCII letters,\ndigits, `_`, or `-` only. The normal identity check still\napplies; use the returned artifact reference in a later Start request. The\nbearer can be retried until JWT expiry; it does not enforce single use.\n\nAn admin with signed reach to an Agent can send its ID as\n`runtime.info.effective_agent_id`. A successful response carries\n`effective_run_completion` with `state: \"active\"` and the resolved tool and\ntimeout, or explicit `state: \"off\"`. Ordinary runtime posture omits that\nfield; absence on an older runtime is not an `off` answer. Go callers can use\n`protocolclient.RuntimeClient.RuntimeInfoForAgent(ctx, agentID)` for this\nrequest. `active` reports configuration; it does not probe tool connectivity.\n\n## MCP source ownership\n\nUse returned MCP source\u002Ftool IDs for new calls. Boot-configured infrastructure\nis shared, while runtime-added sources require the verified owning tenant and\ncurrent effective agent configuration; personal sources also require the user.\nAgent-owned sources can share a logical name across tenants and agents without\nsharing the same physical source ID. Historical agent source\u002FApp\u002Ftool references\nresolve only under the verified tenant and admitted effective agent, with fresh\nApp generation checks. A name never grants reach or selects a tenant.\n\nFor durable policy keys, use tool `logical_id` and MCP server `logical_name`;\nkeep physical `id`\u002F`name` for calls. Admin configuration discovery can request\n`view: \"configuration\"` on `tools.list` and `tools.describe`, always with an\n`agent_id` admitted by signed reach. This includes owned disabled tools and both\nloading modes. Default reads retain execution exposure, and configuration\nreads preserve tenant\u002Fuser\u002Fsource\u002Frevision\u002Fauth constraints. They never grant\npermission to execute a disabled tool.\n\nClients negotiate `tools_configuration_view_v1` before sending the configuration\nview selector. It is advertised only when the owned-source configuration backend\nis wired. An older runtime receives no selector; clients do not retry a refused\nconfiguration request by downgrading its view.\n\nConfiguration-view list responses and manifests carry an opaque `revision`\n(D-491). To revalidate a cached inventory cheaply, send the cached value as\n`if_revision` on page 1: a match answers `{revision, not_modified: true}` with\nno rows. Later pages ignore `if_revision`; compare each page's `revision` with\npage 1's and restart once on a mismatch. The revision covers structural row\nfields, including the row-level `side_effect` and `loading_mode` (so no\nper-tool `tools.describe` is needed for them), and excludes `oauth_status`,\n`approval_policy`, `last_used_at` and `display_modes`. `not_modified` speaks\nonly for the structural rows of the identical query; `if_revision` combined\nwith `filter.oauth_statuses` or `filter.approval_policies` is refused. Key a client cache by\nruntime, tenant, agent, acting user and filter. `tools.catalog.changed` is only\na hint to drop short-lived caches early; never rely on it for correctness.\nOnly send `if_revision` to a runtime whose release includes D-491 — older\nruntimes reject the unknown field.\n\n## Route-aware provider checks\n\nThe existing admin-scoped `llm.posture` provider `validate` and `discover`\noperations accept an optional opaque provider-route selector plus an effective\nAgent ID. The Agent must be in the caller's signed reach. A successful response\nechoes only route\u002Fconnection generations and readiness; credentials, endpoints,\nprovider bodies, and identity values are never returned. Omitting the route\nkeeps the runtime-default provider-catalog behavior.\n\n## Operator-managed agent packs\n\n### Same-runtime inspect and copy (Phase 267 \u002F D-456)\n\nThe additive admin methods `agent_config.agent_packs.inspect` and\n`agent_config.agent_packs.copy` operate only on registrations in the same\nruntime and verified tenant. They require the verified identity triple, the\n`admin` scope, and signed effective-agent reach to every addressed source and\ntarget agent. `agent_id` is registration metadata, not an isolation principal;\nthe request body cannot select a tenant, user, or authority.\n\n`POST \u002Fv1\u002Fagent_config\u002Fagent_packs\u002Finspect` returns a bounded, complete\nprojection of the addressed agent's operator pack. `boot_packs` and\n`revision_packs` retain their distinct complete bodies when both layers\ncontribute; `effective_packs` is the deterministic merged view. Every entry\nreports exact `source` (`boot`, `revision`, or effective `both`),\n`semantic_hash`, and boolean `editable`. The response also carries\n`composition_hash` and `boot_pack_set_hash` as canonical lowercase 64-character\nSHA-256 hexadecimal values, including empty-set values. Equal boot\u002Frevision content is\ndeduplicated only in `effective_packs`; a differing same-name pair fails\nclosed. Boot-owned entries remain read-only.\n\n`POST \u002Fv1\u002Fagent_config\u002Fagent_packs\u002Fcopy` accepts a bounded `pack_ids` array,\nincluding an empty array to remove untouched server-stamped copies from that\nsource during reconciliation. Omitted or `null` `pack_ids` is invalid; only an\nexplicit empty array authorizes removal. The request also carries\n`expected_source_composition_hash`,\n`expected_target_composition_hash`, and an opaque `idempotency_key`. The server\nrechecks the immutable source hash\u002Frevision and applies the authoritative\ntarget composition-hash CAS. All selected bodies are recorded in one\nall-or-nothing target revision; the response is bounded, echoes the exact\ntarget `composition_hash` and `boot_pack_set_hash` values (including\ndeterministic empty-set values), and never carries the pack body. An exact\nresponse-loss retry converges, a reused key with different\narguments fails, and equal selected content is a true no-op. A differing\nindependently authored target or an edited prior copy fails closed without\noverwriting another selected pack.\n\nCopy provenance is server-stamped in `origin_ref` with source agent and\nrevision (or boot source), selected pack ID, source semantic hash, operation\ndigest, and target binding; the durable operation record binds the sorted\nselection and both expected composition hashes. Reconciliation may update or\nremove only entries whose current hashes still equal their last-applied values\non the same lineage; edited targets remain intact and surface a bounded\nconflict. A boot source can be copied into an editable durable target, but the\nsource is never mutated.\nTarget changes continue through `agent_config.agent_packs.propose`, `.commit`,\nand `.remove`. There is no cross-runtime federation, portable catalog, or\ncapability grant through pack metadata. Use capability discovery and the typed\nerror response before invoking either route.\n\n## Same-runtime organization skill publications (HA-68 \u002F D-430)\n\nOrganization publications are a separate, additive Protocol surface from the\nper-agent pack verbs below. Administrators use\n`skills.publications.publish`, `.list`, `.get`, `.publish_successor`, and\n`.retire`; callers use `.available`, `.install`, `.update`, `.remove`, and\n`.references.list`. Every request still carries the verified identity triple.\nAdmin methods require the verified admin scope. Caller methods additionally\nrequire signed reach to the effective agent; the request body cannot choose a\ntenant, user, agent, or authority.\n\nThe publication is immutable and content-addressed. A successor or retirement\nuses the exact expected generation\u002Fhash, and idempotency keys replay the same\nbounded result. List\u002Fget\u002Freference\u002Freceipt responses are metadata-only: they\ncarry the publication and revision ids, generation, content hash, lifecycle\nstate, and same-runtime binding, never the skill body. The body is resolved\nonly by the authorized runtime composition path after rechecking identity,\nreach, active state, runtime id, generation, and hash. A retired, stale,\nforeign-runtime, or unreachable reference is a typed failure; there is no\nlatest-revision fallback or cross-runtime catalog.\n\nUse the generated [methods](..\u002F..\u002Fprotocol\u002Fmethods.md), [errors](..\u002F..\u002Fprotocol\u002Ferrors.md),\nand [types](..\u002F..\u002Fprotocol\u002Ftypes.md) pages as the wire reference. The\npublication domain and canonical wire registration may exist before a runtime\nadvertises the complete surface; a client must follow capability discovery and\nmust not claim the route is live until the transport\u002Fcomposition integration\ngate is present. See the Phase 250 plan for the exact acceptance matrix.\n\n### Publication reads and candidates (D-508)\n\nRuntimes that advertise `skill_reads` serve two body reads. `skills.publications.read`\n(`publication_id`, optional `revision_id`) returns the revision's structured\n`skill` and its canonical `SKILL.md` text as `document`: an admin reads any\nrevision of any publication in the tenant; any other verified caller reads only\nan active publication's current revision (exactly what `.available` lists), and\nanything else is `skill_publication_not_found`.\n\nRuntimes that advertise `skill_publication_candidates` serve a reviewed\nsubmission path. `skills.publications.candidates.submit` (`agent_id`, `name`,\noptional `target_publication_id` and `note`, `idempotency_key`) freezes the\ncaller's own personal skill on an Agent in signed reach into a pending\ncandidate; a skill with support files is refused with\n`candidate_support_files_unsupported` (publications carry no support files), and\na second pending candidate for the same name with `candidate_pending_exists`.\n`.list` shows an admin every candidate in the tenant and anyone else only their\nown; `.read` returns the frozen body to an admin or the submitter (otherwise\n`not_found`); `.withdraw` lets the submitter drop a pending one. Admins\n`.accept` with `mode` `new` (optional `name`) or `successor` (`publication_id`\nplus the publication's expected generation and content hash), or `.reject` with\na `decision_note`; both take the candidate's `expected_generation`. Acceptance\ngoes through the ordinary publication store, records the resulting publication,\nrevision and replaced content hash on the candidate, and is safe to retry: a\nretry, by the same or another admin, never publishes twice.\n\nThe admin-scoped `agent_config.agent_packs.list|upsert|remove|propose|commit`\nmethods manage a per-agent skill pack. Direct writes use the dedicated verbs;\n`agent_config.set_revision` rejects the pack section. Governed authoring requires\n`expected_content_hash` on both `propose` and `commit`; commit must send the\nopaque single-use `proposal_id`, exact `reviewed_hash`, and unchanged body. The\nserver-bound proposal receipt is not forgeable from the returned hash or\nprovenance string.\n\n### Personal skill export\n\n`agent_config.user.skills.export` (`POST \u002Fv1\u002Fagent_config\u002Fuser\u002Fskills\u002Fexport`)\naccepts `identity`, `agent_id`, and the canonical personal skill `name`. Like\n`user.skills.list`, it requires the verified caller and signed reach to an\nactive Agent, without an admin or `agent_config:user` scope. It exports only\nthat caller's durable user-scope package installed through reviewed import;\na same-name shared, foreign, or legacy upsert-only skill is never a fallback.\n\nThe response carries `artifact` (the normal `ArtifactRef`), `package_hash`,\n`name`, `size_bytes`, and `protocol_version`. Retrieve its bytes through\n`artifacts.get` or `artifacts.get_ref`. The ZIP has root `SKILL.md` and all\npackage support files and can enter the normal reviewed import flow. A\npackage installed from a single Markdown document exports in the same form. The\npackage hash identifies package content; the artifact SHA256 identifies the\nZIP bytes. Export writes only the caller-owned artifact, with no skill,\nmembership, or revision change. Missing installed packages, including legacy upsert-only rows, return\n`not_found`.\n\n### Personal skill read\n\n`agent_config.user.skills.read` (`POST \u002Fv1\u002Fagent_config\u002Fuser\u002Fskills\u002Fread`)\ntakes the same `identity`, `agent_id` and `name` as export and the same\nauthority. It returns the logical `skill`, its canonical `SKILL.md` text as\n`document` (the bytes export puts at the archive root), the `support_files`\nmanifest (`path`, `mime`, `size_bytes`) and `package_hash`. Set `support_path`\nto one manifest path to also get `support_file`: UTF-8 `text` for text-like\nmedia, cut at 256 KiB with `truncated: true`, or `binary: true` otherwise. A\nlegacy upsert-only skill reads as a rendered document with no support files.\nThe read changes nothing.\n\nTo install a complete `SKILL.md` package (with support files) into ONE Agent's\nshared pack, upload it with `artifacts.put`, then call the admin-scoped\n`agent_config.agent_packs.import_validate` (`agent_id`, `artifact_id`). It\nwrites nothing and returns the same review as the personal\n`agent_config.user.skills.import_validate`, an opaque `proposal_token` bound to\nyour identity, the Agent, the artifact and the package hash, and the\ncomposition witness `expected_content_hash`. `import_commit` echoes the token,\n`name`, `reviewed_package_hash` and witness; a moved witness is\n`revision_conflict`, an existing item of the same name needs `replace: true`,\nand a retry of the same token returns `replayed: true` without a second write.\nThe item then carries a read-only `package_hash`; its support files are\nruntime-owned Agent state for every caller with reach to the Agent. If a\ncommit fails after publishing, retry the same token to finish it. Packages no\nactive item references are released; `agent_packs.copy` refuses a\npackage-backed item. A package never grants tools.\n\nThe Harbor Protocol is the canonical event\u002Fstate contract between Runtime and any client. The bundled Console is one consumer; this skill walks the path for building your own. A working chatbot UI is achievable in a day on top of the Protocol — the wire is small, typed, and stable.\n\nThree properties make this practical:\n\n1. **A generated, drift-gated contract reference** — the published [Protocol adoption track](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002F) carries four pages (methods \u002F events \u002F errors \u002F types) emitted by `cmd\u002Fharbor-gen-protocol-docs` from the Go single sources and gated in CI by `make protocol-docs-gen-check`, plus an executed quickstart, five choreography guides, a worked build-a-client walkthrough, and the conformance-certification path. For typed TS wire shapes, vendor the generated external-client module `examples\u002Fprotocol-clients\u002Fevent-viewer-ts\u002Fharbor-protocol.gen.ts` (emitted by `cmd\u002Fharbor-protocol-ts-types`, drift-gated by `make protocol-ts-types-gen-check`); the Console's `protocol.ts` is the hand-maintained client when you also want the typed `HarborClient` (the FULL Console-`protocol.ts` *generator* stays deferred per D-132, name reserved).\n2. **Capability advertisement** — `runtime.info.capabilities` tells you at attach which Protocol surfaces this Runtime advertises (`task_control`, `events_subscribe`, `runtime_posture`, `topology_snapshot`, `state_snapshots`, `agent_config`). Your UI degrades gracefully on stripped-down runtimes.\n3. **Stable Protocol versioning** — breaking changes go through a deprecation window; same-major versions are compatible. Pin the major in your client; tolerate additive change. The full adopter contract is the published [versioning & compatibility choreography](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fversioning-and-compatibility).\n\nGo clients should use `github.com\u002Fhurtener\u002FHarbor\u002Fsdk\u002Fprotocolclient` rather\nthan reimplementing the HTTP and SSE layers below. Construct one client with an\ninjected `TokenSource`, then use `WithSession` for each conversation. The clones\nare immutable and safe to use concurrently; token discovery and reconnect\nbackoff remain application policy.\n\n```go\nclient, err := protocolclient.New(protocolclient.Connection{\n    BaseURL: \"http:\u002F\u002F127.0.0.1:18080\",\n    Token: protocolclient.StaticToken(token),\n    Identity: protocolclient.IdentityScope{\n        Tenant: \"dev\", User: \"dev\", Session: \"conversation-1\",\n    },\n})\nif err != nil {\n    return err\n}\n\ninfo, err := client.RuntimeInfo(ctx) \u002F\u002F validates Protocol-major compatibility\nstream, err := client.Subscribe(ctx, protocolclient.StreamOptions{\n    LastEventID: lastSeenSequence,\n})\nif err != nil {\n    return err\n}\ndefer stream.Close()\n```\n\nThe client resolves the token for every request, so a refreshing `TokenSource`\ncan replace an expired credential without rebuilding session clones. REST\nfailures are `*protocolclient.Error` values carrying both HTTP `Status` and the\ncanonical Protocol `Code`. `EventStream.Close` cancels and joins its reader;\ncallers own reconnect timing and pass the last frame's `ID` back as\n`StreamOptions.LastEventID`.\n\nThe Protocol is what makes Harbor headless. The Runtime never imports Console code; the Console never reads internal Runtime objects. Your UI sits in the same posture as the Console.\n\n## 1. The wire — base URL, auth, identity\n\nThis same wire surface is served by any production Harbor Protocol server — the stock `harbor serve` binary **or** an external Go binary built with `harbor scaffold --with-server` (which reaches the Protocol through the public `sdk\u002Fserver` facade; see [`scaffold-a-harbor-agent`](..\u002Fscaffold-a-harbor-agent\u002FSKILL.md)). Both enforce the identical JWKS auth posture below, so a client written against one drives the other unchanged.\n\nThe wire is **REST-per-method**: each Protocol method is its own route under `\u002Fv1\u002F`, you POST a flat JSON body, and you get a flat JSON response back — there is no JSON-RPC envelope. Every request carries:\n\n```http\nPOST \u002Fv1\u002Fcontrol\u002Fstart HTTP\u002F1.1\nHost: 127.0.0.1:18080\nContent-Type: application\u002Fjson\nAuthorization: Bearer \u003CJWT>\nX-Harbor-Tenant: \u003Ctenant_id>\nX-Harbor-User: \u003Cuser_id>\nX-Harbor-Session: \u003Csession_id>\n```\n\n- **Bearer JWT**: RS256\u002FRS384\u002FRS512\u002FES256\u002FES384\u002FES512 signed token. Issuer + audience match the Runtime's `identity:` block, exactly — `harbor serve` hard-rejects an `iss`\u002F`aud` mismatch with `401 auth_rejected`. For `harbor dev`, the ephemeral `HARBOR_DEV_TOKEN` (printed on stderr) is what you use — see [`run-the-dev-loop`](..\u002Frun-the-dev-loop\u002FSKILL.md). For **production** (`harbor serve` mints no token), obtain a JWT from your IdP or self-issue one — the full setup (OIDC app registration, the `(tenant, user, session)` + `scopes` claim mapping, the `iss`\u002F`aud` exact-match contract, and the no-IdP `harbor token` on-ramp) is the [production identity setup guide](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fproduction-identity-setup).\n- **`X-Harbor-Session`**: the per-request session selector (D-171). The connection JWT verifies the WHO (`tenant` + `user`) and the scopes; the **session is chosen per-conversation** by this header and may differ on every request — the connection token is a per-backend credential, not a single-session pin. A new session id is a new conversation (create-on-first-use on the first `start`). The token's `session` claim is a back-compat **default** used only when the header is absent. `X-Harbor-Tenant` \u002F `X-Harbor-User` can never widen the JWT-verified principal. Every storage call still filters by the full `(tenant, user, session)` triple — no cross-session leakage. Full Console contract: [`docs\u002Fnotes\u002Fsession-model-contract.md`](..\u002F..\u002Fnotes\u002Fsession-model-contract.md).\n  - **Optional `session_reach` claim (D-409).** A bearer minted with the signed `session_reach` claim is pinned to exactly those session IDs: the effective session — from this header, the SSE `?session=` projection, or the token `session` default — must be a member, or the request fails closed `403 {\"code\": \"scope_mismatch\"}` before any handler side effect. **Absent claim = this dynamic per-request selection is unchanged.** A coordinating client that must mint a session-specific bearer whose authority cannot be re-pointed at another session uses this claim; see [`configure-production-identity`](..\u002Fconfigure-production-identity\u002FSKILL.md) §2 for the claim shape.\n\nFor an in-flight text correction, `user_message` with a nonempty `message`\ninterrupts the planning attempt and re-plans with that text as user input.\nIt does not cancel the run or undo completed actions. Its acknowledgement is\nadmission, not proof that the correction has reached the model: follow\n`control.applied` and subsequent run events. New attachments belong on `start`.\nPending approval requests from the obsolete plan are withdrawn, not approved;\nqueued tool calls and further retries are refused. Already-started calls retain\ntheir outcomes. A required withdrawal failure stops the run explicitly.\nSee the [task-control choreography](..\u002F..\u002Fsite\u002Fprotocol\u002Ftask-control.md) for\nthe current execution boundaries and remaining release-acceptance work.\n\nRoutes group by surface family:\n\n- **Task control** — `start` plus the nine steering verbs (`cancel` \u002F `pause` \u002F `resume` \u002F `redirect` \u002F `inject_context` \u002F `approve` \u002F `reject` \u002F `prioritize` \u002F `user_message`) all POST to `POST \u002Fv1\u002Fcontrol\u002F{method}` (e.g. `\u002Fv1\u002Fcontrol\u002Fstart`, `\u002Fv1\u002Fcontrol\u002Fcancel`). The read-only posture methods (`runtime.info`, `topology.snapshot`) and `artifacts.put` share this route shape.\n- **Event stream** — `GET \u002Fv1\u002Fevents` (SSE; see §4).\n- **Read surfaces** group by family under their own prefix: `POST \u002Fv1\u002Ftasks\u002F{method}` (e.g. `\u002Fv1\u002Ftasks\u002Fget`), `POST \u002Fv1\u002Ftools\u002F{method}`, `POST \u002Fv1\u002Fsessions\u002F{method}`, `POST \u002Fv1\u002Fmemory\u002F{method}`, and so on.\n- **Admin control surfaces** are family-prefixed and gate on the verified `admin` scope claim (a non-admin caller gets `403 {\"code\": \"scope_mismatch\"}`). The governance tenant-default LLM overrides are here: `POST \u002Fv1\u002Fgovernance\u002Fset_tenant_overrides` sets a tenant's default model \u002F additive extra-instructions \u002F temperature \u002F max-tokens \u002F reasoning-effort live (no redeploy; applied to every session's next run), and `POST \u002Fv1\u002Fgovernance\u002Fget_tenant_overrides` reads them back. `POST \u002Fv1\u002Fgovernance\u002Frotate_key` rotates the LLM provider API key live (no redeploy; the swap is **immediate** — the next call uses the new key). The new key is a **secret**: send it on the request body only; the response + the `governance.key_rotated` event carry only a `sha256:` fingerprint, never the key. `POST \u002Fv1\u002Fgovernance\u002Fset_posture` writes the identity-tier policy table live (no redeploy) — the write sibling of the read-only `governance.posture`. It is a **FULL REPLACE** of the whole table (`{default_tier, identity_tiers: {\u003Ctier>: {budget_ceiling_usd, max_tokens, rate_limit: {capacity, refill_tokens, refill_interval_ms}}}}`), never a partial merge, and carries **no identity field** (authority is server-side). A submitted table that OMITS or zeroes a ceiling the current effective policy enforces — including a `default_tier` repoint whose new tier drops a dimension the old default enforced — is rejected fail-closed `400 {\"code\": \"invalid_request\"}` **before** any state write — never budget-widening. It gates on `admin` **ONLY** (a `console:fleet`-only token — the read's second gate — gets `403 {\"code\": \"scope_mismatch\"}`, so a leaked read-only fleet token cannot widen a budget). What you set is what the next `governance.posture` returns (round-trip); on a fully-latent runtime (no enforcement wrapper composed at boot) the response carries `enforcement_pending_restart: true` rather than a silent inert 200. (`governance.posture` \u002F `llm.posture` remain read-only posture methods.) The tenant default composes UNDER a per-session next-turn override — `POST \u002Fv1\u002Fruns\u002Fset_overrides` records a one-shot override (reasoning-effort \u002F temperature \u002F max-tokens \u002F `system_prompt_override` (a full prompt **replace**) \u002F `extra_instructions` (an **additive** guidance block) \u002F `model` (the session model swap)) for the caller's own session; the effective per-run value resolves **session › per-agent › tenant-wide baseline › config** (the session override wins, then the per-agent agent-config LLM-params layer below, then the tenant-wide baseline; the session slot is consumed once on the next run; the slot map is BOUNDED — a runtime holding 4096 unconsumed slots evicts the oldest-recorded one to admit a new session's, so an override recorded and then never followed by a message is not guaranteed to still be there much later. Record it immediately before the message it is for, which is the intended usage anyway). **`extra_instructions` is the ordinary caller's one-run personalization field (D-387):** it does not replace the admin-set tenant guidance and is not admin-gated. A blank value is a no-op; a nonblank value renders separately in an escaped `\u003Cuser_personalization>` block, survives `system_prompt_override`, and cannot forge or erase the operator-owned `\u003Cadditional_guidance>` section. Use it for preferences such as tone, format, or response style. Put retrieved or recalled content in `start.caller_memory`, whose fixed read-only wrapper is the data path. **The agent-config control plane** is the admin family `POST \u002Fv1\u002Fagent_config\u002F*`: it versions an agent's configuration as immutable, content-addressed revisions where the active config is a pointer to a revision — `set_revision` writes a new revision and advances the pointer, `list_revisions` returns the chain newest-first, `diff` compares two revisions, `rollback` repoints to an existing revision (never mutating it), and `get` reads the active one. Skills control is the first consumer: `POST \u002Fv1\u002Fagent_config\u002Fskills\u002Fupsert` \u002F `skills\u002Fdelete` \u002F `skills\u002Flist` manage an agent's skills, recording each membership change as a config revision (so skills inherit diff + rollback) and emitting `agent.config.revised` \u002F `agent.config.reverted`. Two NON-admin skill rungs sit below it, both **claim-free** (a valid identity is enough — a personal skill can never widen capability, because the capability filter is default-deny and the injection-time redactor scrubs any tool a skill names outside the run's allowed set): `POST \u002Fv1\u002Fagent_config\u002Fsession\u002Fskills\u002F{list,upsert,delete}` manage **ephemeral** personal skills (session-scoped, gone with the conversation), and `POST \u002Fv1\u002Fagent_config\u002Fuser\u002Fskills\u002F{list,upsert,delete}` manage **durable-by-default** personal skills (`user` names the durable STORAGE scope, keyed `(tenant, user)` with the session zeroed — the skill persists across ALL of that user's conversations and rides the driver for restart durability: in-memory ephemeral, sqlite\u002Fpostgres durable). The user rung's upsert\u002Fdelete record a durable membership revision (diff\u002Frollback parity) and the run-start projection keeps a durable user skill visible even when an admin pins a skills membership. `POST \u002Fv1\u002Fagent_config\u002Fset_prompt_layers` sets the agent's **layered system prompt** — an operator-owned `base` layer plus an optional `user` layer that composes *above* the base without replacing it (the composition order is the trust boundary; a `user`-only writer can extend guidance but never weaken the operator base). It replaces only the prompt-layer section (skills + tool exposure are preserved) and records a revision; at run start the durable base\u002Fuser resolve under the per-session `system_prompt_override` (which replaces the whole base+user spine for one message) and above the additive `extra_instructions`. `POST \u002Fv1\u002Fagent_config\u002Fset_llm_params` pins the agent's **per-agent LLM parameters** (`model` \u002F `temperature` \u002F `max_tokens` \u002F `reasoning_effort`) as a versioned section — a set `model` is validated against the configured `ModelProfiles` at set time (an unknown model is rejected, never persisted). It replaces only the LLM-params section (the prompt-layer + skills + tool-exposure + connection + hooks sections are preserved) and overrides the tenant-wide baseline per field for the agent's next run (resolution **session › per-agent › tenant-wide baseline › config**). `POST \u002Fv1\u002Fagent_config\u002Fset_tool_exposure` sets the agent's **MCP-exposure \u002F per-tool policy**: `paused_servers` (MCP source ids excluded next-run, live transport stays warm), `disabled_tools` (individually-excluded tools), and the runtime **loading-mode overrides** — `server_loading_modes` (per MCP source id, applies to TOOL-form descriptors only) and `tool_loading_modes` (exact per-tool name, unconditional), each valued `always`\u002F`deferred`; an unknown value is rejected `400 {\"code\": \"invalid_request\"}` **before** any revision is recorded. A `deferred` override hides the tool from the next run's prompt-time catalog while it stays `tool_search`-discoverable and dispatch-callable (the two-turn discovery cycle is untouched); a paused server \u002F disabled tool stays strictly stronger — hidden from BOTH the prompt and dispatch. Precedence: per-tool override > per-server override > the boot `tools.entries[].loading_mode` > the driver default. It replaces only the tool-exposure section (skills + prompt layers + connections + LLM params + hooks are preserved). The agent's **MCP connection set** is managed by `POST \u002Fv1\u002Fagent_config\u002Fadd_mcp_connection` (register a runtime-added MCP server as a new revision) and `POST \u002Fv1\u002Fagent_config\u002Fremove_mcp_connection` (drop a runtime-added descriptor, pruning that server's tool-exposure residue atomically and detaching it at the next run-start reconcile; a boot-declared yaml server or an unknown name is refused loud) — both ride the same revision machinery (diff \u002F rollback \u002F next-turn projection). **A declared connection is RE-ESTABLISHED at the next run start when the live runtime does not carry it** — after a process restart, or after a `rollback` to a revision that re-declares a previously-removed connection: the run-start reconcile attaches it under the same `(tenant, agent_id)` owner, through the same lifecycle the add verb drives, and emits `mcp.connection.reattached`. **The claim is scoped, and the bound matters to you.** A connection whose transport depended on the operator-supplied auth `headers` you sent to `add_mcp_connection` is NOT restart-survivable — those headers are secret and are never persisted in a revision, so the re-attach dials without them, a server that required one answers `401`, and you must re-run `add_mcp_connection` to supply them again. A connection bound by `oauth_provider` (a NAME, not a secret) IS re-established: the attach resolves the binding by name and touches no token at all, so a missing or expired consent does not block the re-attach — it surfaces later, on the first tool call, as the shipped `tool.auth_required` pause. Anything that could not be re-established is REPORTED rather than silently absent: `mcp.connection.reattach_failed` carries a stable class in its `state` field — `transport_failed` (retryable; the third party did not answer, and the header case above lands here), `stdio_not_allowed`, `injection_disabled`, `oauth_binding`, `owner_conflict`, `ambiguous_server_id` (none of which heal by re-dialling). Both events reuse the connection-lifecycle payload; the discriminator between a reconcile and an admin add is the author's `run_id` — EMPTY for an admin add, populated for a reconcile. A permanently-failing connection is re-dialled on a bounded backoff rather than at every run start, and the count of suppressed attempts rides the next emitted event. No new Protocol method: subscribe to the two event types, or correlate `agent_config.get`'s declared set against `mcp.servers.list`'s live one. The full-payload `set_revision` accepts the same `connections.servers[]` descriptors and holds them to the SAME shape rules `add_mcp_connection` enforces — transport\u002FURL\u002Fcommand coherence (`stdio` needs an argv `command` and no `url`; `http` needs a `url` and no `command`), a non-empty `name`, one auth mode per connection, no reserved `_meta` annotation key, and https-origin-only `oauth_discovery_allowed_origins` (which `stdio` must not carry at all). A malformed descriptor is rejected `400 {\"code\": \"invalid_request\"}` naming the offending `connections.servers[i]`, and the whole set is refused — nothing persisted, the active revision unchanged. A `stdio` descriptor also runs the same fail-closed command allowlist `add_mcp_connection` enforces: an un-allowlisted `command[0]` is refused `403 {\"code\": \"scope_mismatch\"}` at BOTH doors, and a deployment that declares no allowlist admits no `stdio` connection at all. A well-formed set round-trips its `oauth_discovery_allowed_origins` through `get` \u002F `list_revisions` \u002F `diff`, persisted in normalised form (trimmed name\u002FURL, de-duplicated origins) so both doors record identical bytes for the same input. **Artifact-byte egress (D-359):** a connection descriptor MAY additionally carry `artifact_byte_eligible: true` plus `artifact_params` (`{\u003Cserver-side tool name>: [\u003Cparameter names>]}`) — the declaration that this connection may receive **artifact BYTES**, with the runtime resolving an artifact id the model authored and writing the resolved content into the outbound tool-call body as RFC 4648 §4 standard base64, so a large document reaches the remote tool without transiting the model's context. `artifact_params` REQUIRES `artifact_byte_eligible` on the same connection (a mapping without it is rejected `400 {\"code\": \"invalid_request\"}`, never persisted inert — the flag IS the containment boundary), both are `http`-only (a `stdio` descriptor carrying either is refused on the same rule the other http-only fields use), and the mapping's shape runs the same shared validator at BOTH doors (non-empty tool name, at least one parameter, no empty or duplicate parameter name). Each mapped parameter is additionally validated at **attach** against the server's OWN discovered `inputSchema` — it must be declared there and declared string-typed — so Harbor never asserts an argument shape the server did not publish; a server that later changes its schema fails the next attach loudly rather than the next call silently. The declaration is persisted like every sibling field (round-trips through `get` \u002F `list_revisions` \u002F `diff` \u002F `rollback`, with parameters recorded sorted so both doors produce identical bytes). Unlike the inline `oauth` and `injection` descriptors it sits behind **NO boot opt-in**, and the reason is a plane distinction rather than an oversight: those gates exist because their fields determine where a CREDENTIAL is sent, whereas this determines where a user's own CONTENT is sent — a boundary a shared runtime already accepts by trusting its co-tenant admins (D-301), whose stated remedy is one runtime per tenant. It widens the RECIPIENT, never the reachable artifact SET: resolution runs through the dispatching run's own `(tenant, user, session)`, so a cross-tenant \u002F cross-user \u002F cross-session id answers not-found. Every substitution emits the canonical `mcp.artifact_egressed` event — artifact id, server, tool, parameter, byte count and a `sha256:` digest, **never the bytes** — **fail-closed before the wire request**, so a substitution that could not be recorded does not happen. One substituted value is bounded by `tools.mcp_artifact_egress_max_bytes` (default 8 MiB) and an oversize artifact **fails loud rather than truncating**. Two limits worth knowing before you enable it: artifact bytes are stored as authored (unredacted), so a byte-eligible connection can move whatever an artifact contains; and a byte-mapped parameter is **not reachable from an MCP App's tool callback** (`mcp.apps.call_tool` is browser-driven with no run behind it, so no resolver is seated and the call fails loud rather than being given a second, differently-scoped definition of reach). `POST \u002Fv1\u002Fagent_config\u002Fset_mcp_discovery_origins` (`{agent_id, name, allowed_origins[]}`, FULL-REPLACE) writes a runtime-added **http** connection's OAuth-discovery cross-origin allow-list — the origins the discovery walker may fetch authorization-server metadata from: it records a revision (carrying every sibling section forward) AND applies the allow-list to the live MCP registry so the very next discovery uses it; a revoke prunes the recorded requirement's now-unallowed authorization-server entries, and a rollback revokes the origin live through the owner-scoped run-start reconcile. Every origin runs the shared validator (https `scheme:\u002F\u002Fhost[:port]`, no path\u002FIP-literal), and the allowance is never an SSRF hole — a granted origin resolving private\u002Floopback is still refused at dial. An unknown name, a boot-declared (yaml) name, and a stdio connection each fail loud with a distinct typed error — the boot-declared refusal is a property of the NAME, so it fires even when your own active revision also declares a connection under it. The live half is **owner-scoped**: the allow-list is replaced on the connection your `(tenant, agent_id)` owns, and naming a connection another owner attached (or a boot-declared one) is refused `403 {\"code\": \"scope_mismatch\"}` with the accompanying revision rolled back — no observable effect. A name your revision declares but that is not attached yet is not an error: the response reports `applied_live: false` and the run-start reconcile applies the allowance once the server comes online. The agent's **Protocol-installed OAuth providers** are managed by `POST \u002Fv1\u002Fagent_config\u002Fset_oauth_provider` (install\u002Fupsert) and `POST \u002Fv1\u002Fagent_config\u002Fremove_oauth_provider` (uninstall). The install descriptor is **zero-URL by default** — `{name, driver: \"tokenexchange\", credential_source: \"remote\", credential_broker, scopes?}` — because no admin-writable field may determine where a credential is sent (D-300): the token endpoint, the credential-pull endpoint, the allowed downstream hosts, the audience, and the scope ceiling are all pinned at boot on the named `credential_broker` (a `tools.oauth_credential_brokers[]` entry). By default a write carrying a credential-sink field is rejected `400 {\"code\": \"invalid_request\"}`: `auth_url` \u002F `client_id_env` \u002F `client_secret_env` \u002F a raw `allowed_downstream_hosts` list are rejected **by name** (not on the wire struct, so the decode fails), and `token_url` \u002F `audience` are rejected by the fail-closed **wire-descriptor gate** (`tools.allow_wire_oauth_descriptor` is off — the default, all of production). An empty `credential_source`, an unknown broker, and a name colliding with a boot-declared provider each fail loud too. **Dev-gated full binding (D-340):** behind the boot-only opt-in `tools.allow_wire_oauth_descriptor` (config flag OR the `HARBOR_ALLOW_WIRE_OAUTH_DESCRIPTOR` env; effective posture is the OR, default off) the descriptor MAY instead carry the full binding over the wire — `{name, driver: \"tokenexchange\", credential_source: \"remote\", credential_broker, token_url, audience?, scopes?}` (still NAMING a boot-declared broker for the runtime's own credential custody) — so a coordinator can stand up a new OAuth-fronted MCP server at runtime; the same inline binding is available as an `oauth` object on `add_mcp_connection`'s connection descriptor. Even opted in the relaxation stays bounded: `allowed_downstream_hosts` is **DERIVED** from the connected server's own URL (never a wire field), the wire `token_url` dial faces the identical token-exchange SSRF backstop (private \u002F redirecting endpoints refused), and the runtime's OWN credential custody (the coordinator pull endpoint + service-token env name + org secret) stays 100% boot-declared on the named `credential_broker` — **no credential-source URL, env-var name, or secret ever rides the wire** (an earlier draft's wire `remote{}` credential-pull was removed as an exfil primitive). The opt-in is also a kill-switch — a wire provider is not rebuilt by the run-start reconcile once the opt-in is off. Do NOT enable in production. **Dev-gated per-user credential injection (D-346):** for a RECEIVER-STYLE MCP server (one that authenticates by RECEIVING its credential directly on each request rather than PULLING via RFC 8693), `add_mcp_connection`'s connection descriptor MAY instead carry an `injection` object — `{provider, form: \"header\"|\"basic\"|\"meta\", header?, basic_username?, meta_key?}` — that NAMES a boot-declared `tools.oauth_providers[]` broker and declares WHERE the per-user credential (still broker-pulled per acting user at call time) is placed on the outbound request. It is accepted ONLY behind the fail-closed boot opt-in `tools.allow_wire_injection` (config flag OR the `HARBOR_ALLOW_WIRE_INJECTION` env; effective posture is the OR, default off), a NEW opt-in INDEPENDENT of `allow_wire_oauth_descriptor` (enable either alone). With it off (all of production) a connection carrying any injection field is rejected `400 {\"code\": \"invalid_request\"}`. Only the NON-secret mapping rides the wire; the reachable sink is DERIVED from the connection's own URL + validated against the named broker's boot-declared `allowed_downstream_hosts` (never a wire field), every target key must be redaction-covered (the audit redactor holds the injected value to `***`), and it is mutually exclusive with the bearer `oauth_provider` \u002F inline `oauth` binding (one auth mode per connection). It is PERSISTED in the revision like every other descriptor field. Do NOT enable in production. The install records a revision AND installs the provider live (so a connection added moments later can bind it via its `oauth_provider` field with no restart); uninstall records a revision AND CLOSES the provider, so a still-bound connection's next call fails loud rather than degrading to an unauthenticated dial (deliberately breaking; confined to the owning agent by the owner-scoped run-start reconcile AND by a store-boundary owner check that refuses a cross-owner drop — defense in depth, so the store enforces owner-scoping independently of caller-side owner resolution). The agent's **Protocol-installed inference provider** (the LLM provider KEY, a distinct credential plane) is managed by `POST \u002Fv1\u002Fagent_config\u002Fset_llm_provider` — a SEPARATE admin write, never a relaxation of the OAuth verb. Its descriptor is **zero-URL** too — `{name, provider, credential_source: \"remote\", inference_broker, model_allow?}` — because no admin-writable field may determine where the key is sourced (D-300): the pull endpoint \u002F audience \u002F scope ceiling are pinned at boot on the named `inference_broker` (an `llm.inference_brokers[]` entry). A write carrying `credential_url` \u002F `token_url` \u002F `*_env` \u002F a secret is rejected `400 {\"code\": \"invalid_request\"}` **by name**; an empty `credential_source` (the forbidden env source) and an unknown broker each fail loud too. It is gated on the `admin` scope claim ONLY (a leaked read-only `console:fleet` token gets `403 {\"code\": \"scope_mismatch\"}` — a control write is a strictly more elevated tier than any read), and installs the binding live so the runtime's provider key is sourced from the coordinator broker at connect + refresh (uninstall closes the binding and fails subsequently-bound calls loud, never a silent no-op serving the old key). The versioned `hooks` section (the run-completion hook's durable home — `{run_completion: {tool, timeout_ms}}`) rides the same machinery with no dedicated verb: set it via `set_revision` (a negative `timeout_ms` is rejected at set time), read it on `get`, and `diff`\u002F`rollback` cover it like every other section; it resolves above the yaml `runtime.hooks` default at the agent's next run. The versioned `naming` section (session auto-naming's durable home — `{auto, after_turns, repeat_every, max_repetitions, max_title_len, model}`) likewise rides the same machinery with no dedicated verb: set it via `set_revision` (an invalid policy — a negative bound, an out-of-range `max_title_len`, or `repeat_every > 0` with `max_repetitions \u003C 1` since no unlimited value exists — is rejected `400 {\"code\": \"invalid_request\"}` at set time), read it on `get`, and `diff`\u002F`rollback` cover it; it resolves above the yaml `runtime.naming` default at the agent's next run — a PRESENT section is authoritative either way, so a bare `{\"naming\": {\"auto\": false}}` revision is an explicit per-agent opt-out that wins over a yaml-on fleet default — and, when active, titles the session at each run's terminal boundary (a failure emits `session.naming_failed` and never alters the run). Every edit applies on the agent's **next run** (next-turn projection — never mid-flight); an upsert that would overwrite a pack-origin skill is refused with `400 {\"code\": \"invalid_request\"}`, never silently.\n\n### Signed OAuth MCP capability registration\n\nAn operator-enabled runtime may expose the admin-only\n`agent_config.register_oauth_mcp_capability` write at\n`POST \u002Fv1\u002Fagent_config\u002Fregister_oauth_mcp_capability`. The request carries the\nverified identity\u002Fagent selector, provider and boot broker names, audience,\nscopes, one closed HTTP connection descriptor, and a boot-trusted asymmetric\n`authority_envelope`. The descriptor may include\n`artifact_byte_eligible` plus `artifact_params`; the applied revision echoed in\nthe response preserves those exact canonical fields.\n\nArtifact mappings are canonicalized once (trimmed method\u002Fparameter names and\nsorted parameter sets) and fail loud above any exact ceiling: 32 methods, 8\nparameters per method, 128 UTF-8 bytes per method or parameter name, or 8 KiB\nof canonical JSON. Required and signed request values must be canonically equal.\nA JTI is tenant-scoped and immutable: an exact retry converges on the original\npair, while any binding change is a replay conflict. Before publication Harbor\nalso checks each mapped method and parameter against the MCP server's discovered\nstring input schema. A rejected discovered mapping is durably compensated;\nrestart reconciliation completes its rollback before another signed operation\ncan take authority.\n\nA connection failure can retain an incomplete committed candidate behind the\nactivation fence. Retry the same signed JTI for a transient failure. To discard\nthat lifetime, the exact owner may use the existing\n`agent_config.remove_oauth_mcp_capability` method with the immutable candidate's\ncontent hash from `agent_config.list_revisions`, even when `agent_config.get`\nshows only prior or no-active state. A corrected, newly signed registration\nusing the same provider or connection name also compensates that owner's\nincomplete lifetime. Its `expected_content_hash` is checked against the logical\nactive revision before cleanup, and the replacement write retains its own CAS.\nCleanup ends at `preparation_rejected`, including after admitted\u002Fcompleted\nexpiry, so the discarded JTI cannot renew. Published lifetimes and foreign\nowners remain protected; an older rejected lifetime cannot remove a same-name\nreplacement. User-tier sibling methods preserve the same user ownership across\nsession changes. No new method or request field is required.\n\nBoth agent and user GET hide a pending candidate and return its prior revision\nor no-active state. Use that visible hash, or `-` for no-active, when correcting\na registration; a hidden candidate hash is a conflict. A lost revision\ncheckpoint is recoverable only when the physical candidate and exact pending\nfence prove the same claimed operation. If cleanup aborted the legacy fence\nbut its final operation checkpoint failed, an unrelated first registration\nreceives a retryable 409 until exact removal\u002Freconciliation finishes that\ncheckpoint. Retry the competing registration afterward. This prevents reuse\nfrom erasing the only durable cleanup proof.\n\nThe body is a flat JSON object — the method's request shape — with an `identity` object carrying the triple (or the headers above; the body's `identity` may be left empty when the headers supply it):\n\n```json\n{ \"identity\": { \"tenant\": \"dev\", \"user\": \"dev\", \"session\": \"dev\" }, \"query\": \"Hello, agent!\" }\n```\n\nThe response is the method's flat response shape directly — no `result` \u002F `error` wrapper. A failure is an HTTP status plus a `{\"code\": \"...\"}` envelope (e.g. `404 {\"code\": \"unknown_method\"}`).\n\nCORS is default-deny. For browser clients, your origin must be in the Runtime's `server.allowed_origins`. See [`run-the-dev-loop`](..\u002Frun-the-dev-loop\u002FSKILL.md) §2.\n\n## 2. The handshake — `runtime.info` first\n\nThe first call your client makes:\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fruntime.info\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {}}'\n```\n\nA real response from a dev Runtime:\n\n```json\n{\n  \"instance_id\": \"harbor-dev-192.168.1.7\",\n  \"display_name\": \"harbor dev\",\n  \"build_version\": \"v0.0.0-dev\",\n  \"build_commit\": \"dev\",\n  \"build_go_version\": \"go1.26.3\",\n  \"protocol_version\": \"0.1.0\",\n  \"capabilities\": [\"caller_memory\", \"events_subscribe\", \"runtime_posture\", \"task_control\"],\n  \"uptime_seconds\": 16,\n  \"wire_surface_digest\": \"sha256:\u003C64 hex — changes whenever the canonical wire surface does>\"\n}\n```\n\nThree things to read and act on:\n\n- `protocol_version` — the wire-contract version (distinct from `build_version`, the Runtime's own release). Same major ⇒ compatible; on a major mismatch, warn loudly or refuse.\n- `capabilities` — the advertised Protocol surfaces (the list above is one dev Runtime's; a differently-wired Runtime advertises a different subset, which is the whole point of reading it). Four are unconditional on any current build — `task_control`, `events_subscribe`, `runtime_posture` and `caller_memory` — and everything else depends on what the operator wired. Shape your UI on this list: a runtime that doesn't advertise `topology_snapshot` gets the topology panel disabled, not a crash. A method outside the Runtime's registry returns the canonical `404 {\"code\": \"unknown_method\"}` envelope — treat it (and 405 \u002F 501) as \"not served here, degrade\", the same SKIP posture Harbor's own smoke scripts encode.\n- `wire_surface_digest` — an opaque, stable `sha256:` fingerprint (elided above on purpose: a doc that pins a live digest is wrong at the next wire change) of the Runtime's canonical wire surface (the Protocol version + method \u002F error \u002F capability \u002F wire-type *names*; it deliberately excludes field shapes and event-type names). Stamp the digest your client was built against into the build, then compare it here at attach: equal ⇒ same surface; different ⇒ surface drift, surface it loudly; absent\u002Fempty ⇒ the Runtime predates digest support (an informational note, never a drift alarm). It is a coarse name-level early-warning, not a substitute for the field-level checks a client that vendors the wire manifest runs at build time.\n\n### 2a. Retention horizons — how far back this Runtime actually holds data\n\n`runtime.health` (POST `\u002Fv1\u002Fcontrol\u002Fruntime.health`) is a liveness read. For\nevery caller it returns subsystem readiness and only the events horizon, when\nwired, at `scope:\"runtime\"`. Polling it performs no stored reads, elevation or\naudit publication, including with `admin` or `console:fleet` authority.\n\nFor observed oldest-retained instants across `events`, `tasks` and `sessions`,\nexplicitly call `runtime.retention` (POST `\u002Fv1\u002Fcontrol\u002Fruntime.retention`) with a\nverified **`admin`** token and an empty `{}` request body. Its response is\n`{\"retention\":[...]}`; entries use the existing `RetentionHorizon` shape and\nall have `scope:\"runtime\"`. `console:fleet` alone, ordinary callers and\ntrust-mode callers receive `scope_mismatch`. A successful read emits exactly\none `audit.admin_scope_used` attributed to the verified actor; failure to emit\nthe audit returns a runtime error without a retention response.\n\nRead these horizons before a windowed history\u002Fenumeration read so a merged\n\"last N days\" view can mark incomplete coverage. An entry with\n`scope:\"runtime\"` and no `oldest_retained_at` means the surface is trustworthily\nempty. A missing entry means its reader is unwired, so completeness is\nunverifiable. Clients that previously used elevated `runtime.health` for task\nand session horizons must migrate to `runtime.retention` with admin authority\n(D-490). The Protocol version remains `0.1.0`.\n\n## 3. Starting a task — the chat-message equivalent\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fstart\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {}, \"query\": \"What'\\''s the weather in Madrid?\", \"input_artifact_ids\": []}'\n```\n\nThe request is the flat `StartRequest`: `identity` (the triple — empty here because the headers supply it), the `query` string, and the optional `input_artifact_ids`. There is no `foreground` field — every `start` mints a task and you observe it on the event stream.\n\nResponse is the flat `StartResponse`:\n\n```json\n{\n  \"task_id\": \"tsk_01HXYZ...\",\n  \"reused\": false,\n  \"protocol_version\": \"0.1.0\"\n}\n```\n\n`reused` is `true` only when you supplied an `idempotency_key` that matched an existing task; `protocol_version` lets you detect a version skew.\n\nFor a task that may use only selected tools, negotiate `run_scoped_tools_v1`\non `runtime.info`, then send `tool_allowlist` with physical catalog names on\n`control.start`. For example, `\"tool_allowlist\":[\"read_document\"]` permits\nthat tool if the current identity and agent configuration already authorize it.\nAn explicit `[]` closes tool access, while omission preserves ordinary tool\nvisibility. Check the response's `tool_allowlist_applied:true` acknowledgment;\nan older runtime may ignore an unknown request member. The restriction also\napplies to discovered tools and planner-spawned child tasks. A retry using the\nsame idempotency key must keep the exact list.\n\nTo make a task return a **schema-conforming answer**, add the optional `output_schema` field — a JSON-Schema document the runtime validates the task's terminal answer against. On success the completed task's envelope carries a validated `answer_payload` alongside the plain `answer` string, readable via `tasks.get`'s `result_inline` (and via a parent run's AwaitTask observation). An empty, non-compiling, or over-cap (64 KiB) schema is rejected at the edge with a `400 {\"code\": \"invalid_request\"}` envelope before any task spawns; a schema-invalid answer after the runtime's correction budget fails the task loud with the `output_invalid` error code — never a schemaless success. A schema-constrained task suppresses assistant token deltas on the event stream (a validate-and-retry loop cannot retract streamed tokens), so the answer arrives once, on completion. Omit the field for the default schemaless behaviour.\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fstart\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {}, \"query\": \"Classify the sentiment of: shipping delayed again.\",\n       \"output_schema\": {\"type\": \"object\", \"required\": [\"sentiment\"],\n                         \"properties\": {\"sentiment\": {\"type\": \"string\"}},\n                         \"additionalProperties\": false}}'\n```\n\nTo run under a **specific agent's configuration**, add the optional `agent_id` field (D-360). Omitting it binds the runtime's configured default exactly as before; naming one selects that agent's prompt layers, tool exposure, skills membership, LLM parameter overrides, completion hook and naming policy for this run.\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fstart\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {}, \"query\": \"Draft the release note.\", \"agent_id\": \"reporting-agent\"}'\n```\n\n**Keep that agent binding when you render an MCP App.** The runtime-authored\n`mcp.app_available` payload carries `AgentID` beside `ServerID` and\n`ResourceURI`; a nested `MCPAppRef` uses the JSON field `agent_id`. Treat this\nvalue as opaque host state and echo it as `agent_id` on\n`mcp.servers.resources`, `mcp.servers.read_resource`, and\n`mcp.apps.call_tool`. Never accept an agent id from inside the sandboxed App.\nHarbor resolves an omitted value to the runtime\ndefault for older clients, then applies the same signed `agent_reach` check\nbefore tenant-local resolution and credential\u002Fexposure use, so the echo is not\ntrusted authority. Successful `ui:\u002F\u002F` resource reads can include optional same-response\n`provider_origin` and `_meta.ui.csp.resourceDomains`. They describe the exact\nadmitted resource\u002Fprovider, not callback authority. Resource domains are bounded\ncanonical public HTTPS origins (32, 2048 bytes each, 8 KiB total); recognized\nmalformed\u002Funsupported declarations refuse the read. Missing metadata, stdio and\nnonpublic provider origins stay absent. Never infer origins from document HTML or\nfetch another server descriptor to widen CSP. Keep the sandbox and require a\nfresh available render admission before using declarations for passive assets;\nnever use them to permit scripts, connections or frames. Older runtimes omit\nthese optional fields, so preserve the restrictive fallback.\n\n`mcp.apps.tool_context` takes no agent id: its record is\nalready scoped to the verified tenant\u002Fuser\u002Fsession triple and it performs no\nagent-config or credential selection.\n\nA named agent is accepted when EITHER its id equals the runtime's configured default agent id, OR a config revision exists for your tenant under that id (write one with `agent_config.set_revision` — see §7). Anything else is refused with a `400 {\"code\": \"invalid_request\"}` envelope **before any task is created**, never quietly replaced by the default: a caller that named agent A, silently got agent B, and was told it succeeded is exactly the failure this rule prevents. The refusal is deliberately uninformative — an id belonging to another tenant and an id that never existed produce the identical error, so the edge cannot be probed for cross-tenant existence.\n\nTo contribute **content you already retrieved** — recalled conversation memory, a document your own store fetched, anything you want the model to consider without asserting it as instruction — add the optional `caller_memory` field (D-364). **This is the field to reach for, NOT `system_prompt_override`.**\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fstart\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {}, \"query\": \"Continue where we left off.\",\n       \"caller_memory\": {\"recalled\": [{\"user\": \"my order id is 4471\",\n                                       \"assistant\": \"noted, tracking it\"}]}}'\n```\n\nWhere it lands, and why that is the whole point. The value is composed into the run's `\u003Cread_only_external_memory>` prompt tier under the FIXED runtime-owned map key `caller_supplied`, beside whatever the runtime's own retrieval wrote there (`recalled_turns`) — **it composes, it never replaces**. You name no key, so you can never shadow a runtime key and a future runtime producer can never collide with you. That tier ships a five-line anti-prompt-injection preamble whose entire premise is that its contents are hostile, which is exactly why it is the position a caller may write.\n\nContrast with `runs.set_overrides`' `system_prompt_override` (described in §1 inside the \"Admin control surfaces\" bullet — **but note `runs.set_overrides` is itself NOT admin-gated**; it lives in that bullet because it composes with the admin governance overrides above it, and any caller who can set overrides for a session reaches it), which is what this field exists to divert you away from: that one **replaces the whole base+user prompt spine**, silently suppressing the operator's durable user layer, and seats your content in the **trusted** base position with no framing at all. It is the right tool for changing the agent's instructions and the wrong tool for supplying it with content.\n\n`extra_instructions` is the one-run personalization sibling on the same `runs.set_overrides` payload (D-387). It remains available to an ordinary authenticated session caller, but renders in a separate escaped `\u003Cuser_personalization>` section; it never joins or replaces the admin-set tenant `\u003Cadditional_guidance>` block. Use it for user-authored preferences such as tone, format, or response style. Retrieved documents, recalled text, and other external content still belong here, in `caller_memory`, because only this path supplies the fixed read-only\u002Funtrusted framing intended for data rather than instructions.\n\nThe rules, all enforced at the edge before any task is created:\n\n- Any JSON value — object, array, string, number.\n- **An explicit `\"caller_memory\": null` is REFUSED**, not treated as absent. Omit the field if you have nothing to send; a caller that believes its memory reached the model when it did not is the failure this refuses to hide.\n- Over **32 KiB** → `400 {\"code\": \"invalid_request\"}`, with a message that names `caller_memory`. No task is created. **That cap is a resource bound and a wire-size guard, not a security boundary** — it stops an oversized document reaching the token-budget guard and failing your whole run late. Do not read it as a limit on how much content you can put in front of the model: `query` is uncapped below the 64 KiB envelope and lands in the *unframed* conversation position, and `agent_config.session.set_user_prompt` needs no scope claim, takes a 1 MiB body, and lands *inside* the system prompt. What contains `caller_memory` is the tier it goes to, never its size.\n- **Negotiate before you rely on it.** Call `runtime.info` and check for `caller_memory` in `capabilities` — it is advertised UNCONDITIONALLY by every Runtime that has the field, so its **absence** is the signal, not its presence. A runtime that predates the field would **discard it and answer 200** — your run proceeds without the memory you sent, and nothing tells you. Current runtimes refuse an unknown member by name (see below), but that cannot help you against an older deployment; the capability can, because a build predating the field cannot advertise it.\n- It can never write the conversation-memory tier — that is a claim about the session's stored turns only the runtime makes.\n- Each admitting run emits `memory.caller_block_admitted` carrying `bytes` \u002F `tier` \u002F `key` and **no fragment of your content**, so an operator can audit that caller-asserted memory entered a run without the audit trail becoming a copy of it.\n\n**Unknown members are refused, never dropped.** Every Protocol request body is decoded strictly: a member no wire type declares comes back `400 {\"code\": \"invalid_request\"}` with the member **named** in the message (`json: unknown field \"…\"`). This is deliberate and it is how you discover a field a runtime does not support:\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fstart\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {}, \"query\": \"hi\", \"caller_memoryy\": {}}'\n# → 400 {\"code\":\"invalid_request\",\n#        \"message\":\"method \\\"start\\\": request body is not a valid StartRequest: json: unknown field \\\"caller_memoryy\\\"\"}\n```\n\nTwo consequences for your client: strip fields the runtime does not declare (typos and speculative fields are 400s, not no-ops), and remember that a **stray** member is refused even when a correctly-spelled sibling carries the same information — e.g. the `artifacts.*` methods scope by `scope`, and adding an `identity` object beside it is a 400.\n\n**What happens to it at rest.** The payload is stored on the task record, which the StateStore writes to disk. It goes through the **audit redactor** on the way in — the same one `query` and the task description take, so all three caller-controlled fields behave alike — and the redacted form is what both the store and the prompt see. Structure survives: the redactor walks the decoded JSON, so objects, arrays, numbers, booleans and `null` come back intact and only secret-shaped **keys** (`api_key` \u002F `password` \u002F `secret` \u002F `token` \u002F `cookie` \u002F `authorization`) and inline `Bearer …` \u002F `Basic …` **values** are replaced with `***`. Your idempotency key is unaffected — content identity is computed before redaction.\n\n**One thing Harbor does not do for you:** that redactor is a **pattern** redactor, not a sanitiser. It does not detect PII, it does not detect a credential that looks like ordinary prose, and it cannot make hostile text safe — the untrusted framing is the mitigation for the MODEL, and it is not redaction either. If you pipe third-party content through `caller_memory` without redacting it first, you still own that data-leakage path.\n\n**It selects configuration only.** The run's southbound tool provenance (`_meta.agent_id` on outbound MCP calls) and its RFC 8693 acting principal (`actor_token`) stay the runtime's boot-derived value — the acting principal is the runtime's own verified identity and is never client-supplied. `tasks.get` \u002F `tasks.list` reflect the selection on `task.agent_id`; an **absent** value means the caller named none and the run bound the runtime's configured default (\"defaulted\", not \"unknown\").\n\nFor multimodal input, upload artifacts FIRST (`artifacts.put`, see §6) and pass the returned IDs in `input_artifact_ids` (D-166). The per-MIME dispatch — image inline vs PDF\u002Faudio as ArtifactStub — happens inside the planner; your client just passes refs. To override how an attachment is handed to the model, add the optional `input_artifact_dispositions` map (Phase 84b — D-189), keyed by artifact id with values `ref` | `inline` | `provider_native` | `tool:\u003Cname>` (e.g. `{\"art_x\": \"tool:pdf.extract\"}` forces the named catalog tool). Your hint is the top precedence layer (hint > the agent's `multimodal.disposition` config map > the runtime default: image inline, everything else ref); an omitted map keeps today's behaviour. `tasks.get` reflects the hint on `input_artifacts[].disposition`, and the resolution (including degradations — e.g. an unknown `tool:\u003Cname>`) is observable as `task.input_disposition.resolved` events. A `provider_native` hint is honoured end-to-end (Phase 84c — D-190): the LLM driver uploads the attachment to the provider's file surface and the upload is observable as `llm.provider_file.uploaded` events (artifact ref, provider, modality, `file_id`).\n\n### 3a. Warming the next start — `prepare` (D-495)\n\nWhen your client knows a send is coming (the user opened the agent, picked it,\nor started typing), call `prepare` with the identity, `agent_id` and\n`provider_route` the next `start` will carry. It is admitted exactly like\n`start`, creates nothing, and answers `202` at once while the runtime runs the\nrun-start MCP reconcile and the credential-free route selection in the\nbackground:\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fprepare\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {\"tenant\": \"t\", \"user\": \"u\", \"session\": \"'\"$SESSION\"'\"}, \"agent_id\": \"support\"}'\n# → 202 {\"state\":\"scheduled\",\"protocol_version\":\"0.1.0\"}\n```\n\nA runtime without a reach-admission authority (no broker or shared KEK) answers\n`404`, as does one predating the method. `state` is `scheduled`, `in_flight`\n(already running for this tenant\u002Fuser\u002Fagent),\n`fresh` (completed within 90 s; nothing new started) or `busy` (workers\nsaturated; the hint was dropped). Calling it repeatedly is cheap. A `start`\nwithin 90 s whose inputs are unchanged skips its reconcile, and one arriving\nmid-preparation waits for it at most 10 s; otherwise the start behaves exactly\nas without `prepare`. Impersonation is refused and no outcome is reported back:\nwatch the runtime's `session.prepare` log line and the run's `turn.pre_model`\n`prepared` attribute.\n\n## 4. The events stream — SSE `events.subscribe`\n\nThe Protocol exposes events as Server-Sent Events:\n\n```http\nGET \u002Fv1\u002Fevents?access_token=\u003CJWT>\nAccept: text\u002Fevent-stream\nX-Harbor-Tenant: \u003Ctenant_id>\nX-Harbor-User: \u003Cuser_id>\nX-Harbor-Session: \u003Csession_id>\n```\n\nThe subscription is **identity-scoped** — it streams the whole session's events — so there is **no `task_id` query param**. A client that can set headers narrows server-side with the optional `X-Harbor-Run` (a task id) and the repeatable `X-Harbor-Event-Type` headers. A browser `EventSource` (which can't set custom headers) authenticates via the `?access_token=` query-param shim — same JWT, same identity triple, its `session` claim scoping the stream — and filters client-side on the event payload's task id. The query-param shim is documented in `internal\u002Fprotocol\u002Ftransports\u002Ftransports.go`.\n\nEach `data:` value is an event envelope, not a bare payload. For example,\na live assistant update has no SSE `id:` because its sequence is zero:\n\n```text\nevent: llm.completion.chunk\ndata: {\"type\":\"llm.completion.chunk\",\"sequence\":0,\"tenant\":\"dev\",\"user\":\"dev\",\"session\":\"dev\",\"run\":\"tsk_01HXYZ\",\"payload\":{\"TaskID\":\"tsk_01HXYZ\",\"RunID\":\"tsk_01HXYZ\",\"Kind\":\"content\",\"Delta\":\"I will compare the documents.\",\"Done\":false}}\n```\n\nThis example elides timestamps. A replayed copy has a positive `sequence` and\nmatching SSE `id:`. The runtime persists buffered chunks at completed planner\nsteps before tool execution, and seals\u002Fdrains the run before successful terminal\ncompletion. Persistence is not a second live fan-out. Restart replay requires\na durable event bus backed by a persistent StateStore.\n\nUse `payload.Kind` to keep `content` in the conversation and `reasoning` only in\nthe activity\u002Freasoning view. `payload.Done` ends one LLM response lane, not the\nwhole task. Tool-call preambles remain intermediate updates; the terminal\n`AnswerEnvelope` remains the final answer. Treat sequence-zero animation as\nprovisional: an unflushed tail can be lost on crash\u002Fcancellation\u002Fwrite failure.\nDo not append replayed history on top of that provisional text; reconstruct the\naffected run from retained events and respect explicit retention gaps.\n\n`sessions.turns.list\u002Fget` remains a consumer-safe projection, not the raw update\ntranscript. Recover historical intermediate text through authorized `state.history`\nor SSE replay; its newest `live_resume_seq` alone does not backfill older steps.\nSee [streaming semantics](..\u002F..\u002Fsite\u002Fprotocol\u002Fstreaming-semantics.md) for the\npersistence boundary and cursor choreography.\n\nGovernance emits its own canonical events on the same stream — subscribe with `X-Harbor-Event-Type: governance.failover` to observe LLM-provider failover. When a runtime is configured with a broker-pulled failover chain, each HOP the Harbor-orchestrated walk takes on a retryable provider error emits a `governance.failover` event carrying the run identity, the `from_provider` \u002F `to_provider`, the 1-based `hop_index`, the accumulated per-identity cost the re-run budget check gates against, and a bounded retryable-error class (never the raw provider error). Every hop is a Harbor event through audit + bus + cost — the provider SDK's native fallback array is deliberately unused (D-018) — and a hop whose re-run budget\u002Frate check trips fails the run loud rather than silently walking further down the chain. The full event catalogue (147 types) is the generated [events reference](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fevents).\n\n**A gotcha**: the event payload's task ID field is `payload.TaskID` (capital T) — match exactly when parsing in JS\u002FTS. Documented in the Console's chat panel handler; easy to miss when hand-rolling.\n\nFor a chat UI, you'd:\n\n1. Append a \"user turn\" bubble to the chat.\n2. POST `start`, get `task_id`.\n3. Open an SSE stream for that `task_id`.\n4. Group `llm.completion.chunk` by task\u002Frun, response boundary and `payload.Kind`; show only content in the conversation.\n5. Render `tool.invoked` \u002F `tool.result` as collapsed cards inside the assistant bubble.\n6. Close the bubble on `task.completed`.\n\n**Background-wake notifications (`notification.*`).** The runtime also\nsynthesises an operator-facing `notification.*` family onto the same\n`events.subscribe` stream (no separate method) — the conversational mirror of\nbackground work you'd otherwise miss. Each carries a human-readable\n`Summary` your UI renders inline (fall back to the bare event type when\nabsent). The wake classes:\n\n- `notification.task_completed` — a background task that opted in with\n  `NotifyOnComplete` finished.\n- `notification.task_group_resolved` — a parallel task group resolved\n  (with ref-shaped member-outcome counts).\n- `notification.task_group_cancelled` — a parallel task group was cancelled\n  **without the operator asking** (a fail-fast gate firing on a member\n  failure, or a cascade inherited from an ancestor cancel). This closes the\n  sibling asymmetry the resolved-group mirror opened: a batch's winners wake\n  the conversation while its unprompted-cancelled losers would otherwise\n  vanish silently. **Suppression rule:** a group cancel the operator drove\n  DIRECTLY produces NO notification (they already know) — the runtime keys\n  this on the cancel's typed origin, so you only ever receive this event for\n  an unprompted cancel worth surfacing.\n- `notification.task_failed` — a background task failed (suppressed for a\n  foreground turn's own failure, which the client surfaces itself).\n\nThese are additive event classes on the existing stream; a client that\ndoesn't recognise a `notification.*` type can ignore it. `ProtocolVersion`\nis unchanged.\n\n## 4a. Reopening a long session — `state.history`\n\n`events.subscribe` is the LIVE tail. To **reopen** a closed conversation you don't want to re-stream every event from sequence 1 — a 5 000-event session would flood the client before the newest turn renders. The `state.history` method (capability `state_snapshots`) is the bounded, **tail-first** windowed read of the same durable event stream:\n\n```http\nPOST \u002Fv1\u002Fstate\u002Fhistory\nAuthorization: Bearer \u003CJWT>\nContent-Type: application\u002Fjson\n\n{ \"session_id\": \"\u003Csession_id>\", \"before\": 0, \"limit\": 50 }\n```\n\n`before: 0` means \"from the tail\" (the newest retained events); `limit` is the window size K (default 50, max 200). The response is a page of flat events **oldest-first within the window**, plus the bounds and a scroll-up cursor:\n\n```json\n{\n  \"events\": [ { \"type\": \"...\", \"sequence\": 4951, \"occurred_at\": \"...\", \"payload\": {...}, \"artifacts\": [...] }, ... ],\n  \"head_sequence\": 1,\n  \"tail_sequence\": 5000,\n  \"next_cursor\": 4951,\n  \"has_more\": true,\n  \"truncated\": false\n}\n```\n\nTo **scroll up** (load one window older), pass the previous response's `next_cursor` back as `before`. When `next_cursor` is `0`, you've reached the retained head — no older events remain. Reduction of events → chat messages stays **on your client** (the same reducer you use for the live stream): the surface returns flat events, not pre-reduced turns.\n\nHeavy payloads (a large tool result offloaded above the heavy-output threshold) ride by a **routable** `StateArtifactRef` on `events[].artifacts[]` — a content-addressed `id` (+ `sha256`), never inline bytes. Resolve it the same way as any artifact: POST the `id` to `artifacts.get` (§6.1) — the byte read that works on every driver. `artifacts.get_ref` is the presigned-URL alternative, useful when the store can hand a large download off its own edge, but it answers `presign_unsupported`\u002F501 on the default inmem\u002Ffs stores, so reach for it only when you know your deployment runs an S3-compatible driver.\n\nIdentity rules: identity is mandatory (an incomplete triple is `identity_required`\u002F401); an unknown or cross-identity `session_id` is `not_found`\u002F404 (existence is never revealed across identities — never a 403); a cross-tenant read requires the verified `admin` scope claim.\n\n**Cross-session \u002F time-ranged historical read — `events.list`.** `state.history` is a **by-id** read (one session). When you want the raw events across a **time window** — possibly across sessions, for a fleet observability view — use `events.list` (`POST \u002Fv1\u002Fevents\u002Flist`): the same wire `EventFilter` you pass to `events.subscribe`\u002F`events.aggregate` (identity axes + `since`\u002F`until` + `event_types`) plus the SAME tail-first paging grammar as `state.history`:\n\n```http\nPOST \u002Fv1\u002Fevents\u002Flist\nAuthorization: Bearer \u003CJWT>\nContent-Type: application\u002Fjson\n\n{ \"filter\": { \"since\": \"2026-07-04T00:00:00Z\" }, \"cursor\": 0, \"limit\": 50 }\n```\n\nRows are the **same flat `StateEvent` shape** `state.history` returns (heavy payloads by routable `StateArtifactRef`, never inline); `cursor: 0` reads from the tail and you scroll one page older by passing the response's `next_cursor` back as `cursor` (0 ⇒ the retained head). `truncated: true` is the honest retention-gap flag at the window edge (a best-effort in-memory ring evicted older rows; a `durable` driver serves complete windows unless the operator enabled audit retention, `events.retention.audit_max_age`, and the window reached rows it trimmed — only aged `audit.*` rows are ever trimmed). By default the read is scoped to your own verified triple; a **cross-tenant (fleet) widening** — a `filter.tenant_ids` naming a tenant other than yours — requires the verified `admin` **or** `console:fleet` scope (derived server-side from your session, never the body) and emits one `audit.admin_scope_used` per request. Same authz as the live\u002Faggregate feeds, so a `console:fleet` operator reads historically exactly what it can subscribe to.\n\n**Bucketed counts — `events.aggregate`.** For a time-bucketed count series (the Events-page sparkline) rather than the raw rows, `POST \u002Fv1\u002Fevents\u002Faggregate` takes the same `EventFilter` plus a `window` and a `bucket` (nanoseconds; `window % bucket == 0`) and returns `{ \"buckets\": [ { \"bucket_start\": \"...\", \"bucket_end\": \"...\", \"counts\": { \"tool.failed\": 3 } }, ... ], \"truncated\": false, \"protocol_version\": \"0.1.0\" }`. It works on EVERY driver — including the `durable` log — with the same authz as `events.list` (a cross-tenant filter needs the verified `admin`\u002F`console:fleet` scope, one `audit.admin_scope_used` per widened call). A window too wide to count in full comes back as **partial buckets with `truncated: true`** — uniformly across drivers, DATA not an error; a driver difference changes WHAT the method returns, never WHETHER it works, so there is no over-wide-window 400.\n\nBy default the grid is anchored at \"now\" — the buckets run `[now-window, now)`, so a `bucket_start` is NOT addressable twice (two polls a few seconds apart return two different boundary sets and nothing caches). Pass the OPTIONAL `anchor` (RFC-3339 UTC) to floor the boundaries onto the fixed grid `anchor + k*bucket` instead: two calls at two instants with the same `anchor` + `window` + `bucket` then share bucket coordinates, so a bucket is cacheable and re-requestable — pass the Unix epoch (`\"1970-01-01T00:00:00Z\"`) for a globally-shared grid identical across a runtime restart and across two fleet runtimes. One grid-edge caveat: with an anchor the LAST bucket's `bucket_end` is the grid boundary covering \"now\" (generally just AFTER now, by up to one bucket), so don't render it as \"up to this instant.\" The field is additive — omit it and you get the byte-identical clock-anchored series.\n\nWidening semantics (same for `events.aggregate` and `events.list`): you WIDEN by NAMING `filter.tenant_ids` (or another principal — a foreign\u002Fmulti user, a multi-session set). A widened read fans in across ALL users and sessions of the named tenant scope — the elided user\u002Fsession axes legitimately mean \"all\" within the tenant(s) you authorized, so a fleet read of `{\"filter\":{\"tenant_ids\":[\"t2\"]}}` returns every principal's counts in `t2`, not just your own. An ELIDED `tenant_ids` always stays YOUR OWN tenant, even for an admin (name-to-widen, matching `tasks.list` \u002F `agents.list`) — you never silently fan across every tenant. Every widened read is gated on the verified `admin`\u002F`console:fleet` scope (derived from your session, never the body) and emits one `audit.admin_scope_used`.\n\n**Per-tenant attribution — `by_tenant`.** An aggregate bucket is a bag of scalars (`{\"counts\": {\"tool.failed\": 3}}`) with NO tenant attribution, so — unlike a raw `events.list` row that carries its own tenant — you cannot verify a widened count against the `tenant_ids` you asked for; the runtime's honouring of the filter IS the whole tenant boundary. Set the OPTIONAL `by_tenant: true` on the `events.aggregate` body to get per-bucket attribution: each bucket gains a `counts_by_tenant` map (tenant → event-type → count) alongside `counts`, e.g. `{ \"counts\": {\"tool.failed\": 3}, \"counts_by_tenant\": {\"t-a\": {\"tool.failed\": 2}, \"t-b\": {\"tool.failed\": 1}} }`. It is returned ONLY on an admin-widened read (the same verified `admin`\u002F`console:fleet` scope, derived server-side); on any other read the flag is IGNORED and `counts_by_tenant` is absent — the flag never elevates a read and never widens what is counted (fail-closed). The keys are a subset of the tenants you named, and per bucket `Σ_tenant counts_by_tenant[tenant][type] == counts[type]`, so you can independently reconcile the breakdown against the totals and confirm no tenant outside your entitled set appeared. Additive — omit `by_tenant` and the response is byte-identical to before. `ProtocolVersion` stays `0.1.0`.\n\n**Fleet enumeration (admin-widened `tasks.list` \u002F `agents.list`).** By default both list methods project only your own `(tenant, user, session)` triple — a synthetic observer session sees nothing. A coordinator control plane rendering a fleet-wide Tasks board \u002F Agents catalog widens the read with an additive `filter.tenant_ids` selector: `POST \u002Fv1\u002Ftasks\u002Flist` (or `\u002Fv1\u002Fagents\u002Flist`) with `{\"filter\": {\"tenant_ids\": [\"tenant-a\", \"tenant-b\"]}}` enumerates every task \u002F agent across ALL sessions of the named tenants. Widening rides the SAME verified `admin` scope claim (no new \"fleet\" scope) — a `tenant_ids` request without it fails LOUD with `403 {\"code\": \"scope_mismatch\"}`, never a silent narrowing to own scope. Every widened row carries full per-`identity` `{tenant,user,session}` attribution, and every widened call emits an `audit.admin_scope_used` event. Cross-RUNTIME federation stays coordinator-side over these per-runtime reads (the same division as `sessions.list` \u002F `events.subscribe`). One `agents.list`-specific row to know about: every actively-serving runtime returns its **default agent** — the boot-configured agent it serves through, never registered as a fleet entity — as a first-class row marked `is_default: true` (well-known `agent_id`, `agents.get` resolves it, the `Active` metric counts it). On a narrow read it carries your own triple; on a widened read one such row appears per named tenant, attributed by tenant only. So a fleet catalog reads \"one agent, not enumerable this way\" instead of an empty page — but there is NO control surface over it: a `agents.pause`\u002F`.drain`\u002Fetc. against the well-known id fails `404` (`agent_not_found`), because the runtime's own process is not a fleet-controllable member. A real registration reusing the well-known id suppresses the synthetic row (real data wins; never a duplicate id).\n\n## 4b. Erasing a session — `sessions.delete`\n\nTo satisfy a data-lifecycle \u002F right-to-erasure request, `sessions.delete` (capability `session_lifecycle`) **deletes a whole session and cascades deletion of its scoped State, Memory, and Artifacts**. It is **own-session-only** — you erase solely your own verified `(tenant, user, session)`; there is no admin \u002F cross-tenant path. The route is `POST \u002Fv1\u002Fsessions\u002Fdelete`:\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fsessions\u002Fdelete\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {\"tenant\": \"dev\", \"user\": \"dev\", \"session\": \"'$SESSION'\"}}'\n# → 200 {\"session_id\":\"...\",\"deleted\":true,\"state_records_deleted\":N,\"artifacts_deleted\":M,\"memory_purged\":true}\n```\n\nThe response carries non-sensitive deletion telemetry only — never erased content. The bytes are **hard-deleted** (not tombstoned); the only durable trace is a redacted, content-free `session.erased` audit event written under your observability scope (so a follow-up `state.history` for the erased session returns empty). Rules: identity is mandatory (`identity_required`\u002F401, which a body identity mismatching your verified triple also hits); a session with a **RUNNING task is refused** `session_running`\u002F409 with **no store touched** — wait for the task to finish (or cancel it) and retry; an absent session is `not_found`\u002F404. Check `runtime.info.capabilities` for `session_lifecycle` before calling — a runtime that did not wire an eraser does not advertise it and answers a 404 at the route.\n\n## 4c. Naming a session — `sessions.set_title`\n\nSessions display as raw ids until you give one a human-readable **title**: `sessions.set_title` sets (non-empty `title`) or clears (empty `title`) the `Title` field on the session record (D-288). Unlike `sessions.delete`, the write scope is your whole verified `(tenant, user)`, not just your own connecting session — `session_id` is a **dedicated field** that may name a **sibling** session you own, so a Console-style \"rename any of my sessions from the list\" flow needs no elevation. The route is `POST \u002Fv1\u002Fsessions\u002Fset_title`:\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fsessions\u002Fset_title\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {\"tenant\": \"dev\", \"user\": \"dev\", \"session\": \"'$SESSION'\"}, \"session_id\": \"'$SESSION'\", \"title\": \"Q3 onboarding chat\"}'\n# → 200 {\"session_id\":\"...\",\"title\":\"Q3 onboarding chat\",\"title_source\":\"manual\"}\n```\n\nThe verb **always** writes `title_source: \"manual\"` — `auto` provenance is not expressible over the wire, so a title you set here can never be silently overwritten by a later auto-namer (that's the internal-only producer behind Phase 158). An empty `title` clears both fields back to unset. Titles are single-line and bounded to 200 runes: a title with a newline\u002Fcontrol character, or over the limit, is rejected `invalid_request`\u002F400 — **never a silent clamp**. Rules: identity is mandatory (`identity_required`\u002F401, same body-identity-mismatch check as `sessions.delete`); a `session_id` you don't own (wrong tenant\u002Fuser, or simply unknown) is `not_found`\u002F404 — existence is never revealed across identities; renaming a **closed** session is fine (it's metadata on a historical conversation), renaming an **erased** one is `not_found` (the record is gone). The title itself never rides an event, log, or audit payload — `session.title_changed` carries only `{session_id, source}`, so a subscriber that wants the text re-reads `sessions.list` \u002F `sessions.inspect`, both of which now project `title` \u002F `title_source` on every row.\n\n**Session counters are TRUTHFUL, and honest about their own limits (D-309).** Every `sessions.list` \u002F `sessions.inspect` row carries six per-session counters populated at the runtime source: `tasks_count`, `events_count`, `total_cost_cents`, `total_tokens`, `has_pending_intervention`, `has_failed_task`. `events_count` counts durable\u002Freplayable events only; transient Sequence-0 live completion frames are excluded. So `filter.cost_above_cents`, `filter.has_failed_task`, `filter.has_intervention`, and `sort: \"cost_desc\"` narrow \u002F order on REAL data — \"show my sessions over $5\" returns the expensive ones, not an empty page. When a session's per-scan bound is hit, the row carries `counters_partial: true`: its cost \u002F tokens \u002F events counts are then an **honest lower bound** (render them with a \"≥\"), and a `cost_desc` ordering over such a row is non-authoritative — never a silent undercount. The two agent fields take the opposite tack: there is **no single-valued session→agent binding** in V1 (a session may run several agents), so `agent_id` \u002F `agent_name` are **nullable and omitted** rather than a fabricated value, and `filter.agent_ids` fails **loud** with `invalid_request`\u002F400 rather than returning a believable-but-false empty page. The multi-field `query` search is never failed whole for touching the empty agent fields — it still matches `session_id` \u002F `user_id`, so id \u002F user search keeps working.\n\n**The same \"no facet over an unpopulated field\" rule now holds across `tasks` \u002F `flows` \u002F `memory` \u002F `tools`, mechanically (D-313, extends D-309).** A build-time projection-completeness gate (`internal\u002Fprotocol\u002Fprojectioncheck`) fails the build if any read surface ships a filter \u002F sort \u002F aggregate over a wire field its projector never assigns — so the false-absence bug can't be reintroduced. What this means on the wire:\n\n- **`tasks.list`** — `has_pending_approval` is populated from the pause\u002Fapproval registry, so `filter.has_pending_approval=true` narrows to tasks actually blocked on a HITL gate (not an empty page). `background_acknowledged` is `omitempty` (elided when false — never a fabricated known-false).\n- **`flows.list` \u002F `flows.get`** — `budget_consumption.tokens_used` is summed per run (symmetric with `cost_usd_used`), truthful wherever a run is recorded.\n- **`memory.list` \u002F `memory.health`** — `has_ttl_expiring` and the two `expiring_in_1h` aggregate fields remain **removed** from the wire; `filter.agent_ids` loud-rejects with `invalid_request`\u002F400 (memory records carry no producer identity), never a false-empty page. Cumulative `rolling_summary` items now report their original source `expires_at`; inspection does not renew retention or expose unsettled journals.\n- **`tools.list` \u002F `tools.metrics` \u002F `tools.content_stats`** — a runtime that advertises the `tool_annotations` capability (negotiate via `Accepts(tool_annotations)`) serves REAL per-tool annotations: `filter.oauth_statuses` \u002F `filter.approval_policies` narrow to real rows, the annotator-backed aggregates (`active` \u002F `pending_approval` \u002F `awaiting_oauth`) carry real counts (no `aggregates_partial`), `tools.metrics` returns real error-rate gauges + invocation\u002Ffailure counts over the window, and `tools.content_stats` returns a real result-size histogram (D-314). The admin `tools.set_approval_policy` \u002F `tools.revoke_oauth` methods persist through `tools\u002Fapproval` \u002F `tools\u002Fauth` with audit (they no longer return `admin_unsupported`). A runtime that does NOT advertise `tool_annotations` (a headless catalog stack) loud-rejects `filter.oauth_statuses` \u002F `filter.approval_policies` with `invalid_request` and returns `aggregates_partial: true` with those counters zeroed — render them \"unavailable,\" never a real-looking 0; only `aggregates.total` is authoritative in that state.\n\nThe `owner` field in a `tools.*` catalog row is the logical configured MCP\nsource name. A user-scoped runtime may keep an opaque physical source key in\nits internal catalog so two users can attach the same connection; that key is\nnot a client-side naming contract and is never reconstructed from a suffix or\nhash. The row's `id` and `name` remain the physical catalog keys needed for\nthe exact `tools.get` \u002F `tools.describe` request, while a runtime without a\nlogical-source projection may honestly return the raw source identifier.\n\n### Cumulative memory inspection and administration (D-477)\n\nFor `rolling_summary`, `memory.list`, `memory.get` and `memory.strategy_trace`\nread the same checkpoint, bounded recent tail and retained evidence as execution.\nKeys identify immutable sources, not row positions or the viewer's run. A source\nkey survives raw-turn rollover while its evidence remains retained. Inspecting\nan expired source returns absence, not an extended lifetime. Token counts in the\nstrategy trace are estimates of projected memory, not provider usage.\n\nThe existing `memory.put` and `memory.delete` admin gates remain mandatory.\nPut records a redacted conversation note, never tool-result or action authority;\nif the detailed tail is full it reports capacity instead of evicting context.\nDelete removes that source conditionally, invalidates an affected checkpoint,\nand fences active admissions in that session so a late decision or settlement\ncannot restore erased material. It does not cancel an external action already\nin progress or erase an independently owned transcript. Other sessions remain\nunaffected.\n\n**Current migration limitation:** large expiring values cannot yet be exported\nthrough `memory.get`'s artifact arm: that path refuses the read rather than\ncreating a private copy without source-bound expiry\u002Fdeletion. This is not a\nsuccessful detail read or completed release acceptance. Small values, metadata\nlisting and source-key deletion remain available. Existing execution result-ref\nretrieval is a separate path with its own current-source checks.\n\n## 4d. Reopening a chat — durable turns and the two-read open (v1.28)\n\n`state.history` (above) is still the raw-event drill-down. To **reopen a\nchat** — render the current conversation from durable data — the v1.28\nsurface gives you a dedicated projection instead of reconstructing turns\nfrom forensic events:\n\n- **Lifecycle-only session read (HA-63 \u002F D-424).** `sessions.list` \u002F\n  `sessions.inspect` accept an additive `projection: \"lifecycle\"` selector:\n  session id, status, title\u002Fsource, authoritative timestamps, duration where\n  derivable, and the honestly representable agent id — with ZERO counter\n  enrichment (work bounded by page size before and after restart). Counter\n  fields use the closed availability state `current | partial |\n  not_requested | unavailable`; the lifecycle shape marks them\n  `not_requested` (never merely absent, never zero-as-not-computed). A\n  counter filter\u002Fsort (`cost_above_cents`, `cost_desc`, …) paired with the\n  lifecycle selector fails `invalid_request` — it never silently switches to\n  the expensive projection. The full projection remains the default when the\n  selector is omitted.\n- **Durable turn pages (HA-64 \u002F D-425).** `sessions.turns.list` returns one\n  newest-first keyset page of the caller's exact session's root foreground\n  turns (opaque `older_cursor`, `limit` default 20 \u002F max 50) with\n  renderable answer (inline or by artifact reference, or\n  `empty`\u002F`evicted`\u002F`unavailable`), consumer-safe reasoning, ordered tool\n  Activity (never arguments\u002Fresults), usage, intervention metadata\n  (bounded durable pause class \u002F reason \u002F lifecycle \u002F availability — never\n  a pause\u002Fresume\u002Fapproval action token; actionability is computed from the\n  verified caller's tier, and callers act through `pause.list` plus the\n  control\u002Fsteering verbs), and ordered durable MCP App references.\n  `sessions.turns.get` is the one\n  `(session, task)` terminal reconciliation read. Both are exact-session:\n  a foreign session answers typed `not_found` (non-oracular).\n- **Content-free usage read.** A consumer that needs only durable lifecycle\n  and usage facts may call `sessions.turns.get` with `projection: \"usage\"`.\n  The exact-session response is structurally limited to turn\u002Ftask\u002Fsession\u002F\n  agent identifiers, lifecycle and timing, and the canonical usage rollup\n  (per-measure `unavailable`, `exact`, or `estimated` states plus an optional\n  reported model). It does not include\n  conversation text, answers, reasoning, activity, attachments, apps, pause\n  state, runtime run identity, user\u002Ftenant identity, or terminal messages.\n  It uses the same durable turn index as the normal reconciliation read; no\n  poller, receipt, or privileged administrative scope is involved.\n- **Page-before-subscribe live handoff.** Chat open is two reads — one\n  `projection: \"lifecycle\"` inspect plus one `sessions.turns.list` page —\n  then the SSE subscription: open the EventSource with the page's\n  `live_resume_seq` as the initial `resume_seq` (`GET \u002Fv1\u002Fevents?resume_seq=…`),\n  so the server replays events strictly newer than the snapshot through the\n  existing bounded replay path; a browser reconnect's `Last-Event-ID` header\n  takes precedence. One terminal event for a rendered running\u002Fpaused turn\n  triggers exactly one `sessions.turns.get`, which replaces the bubble with\n  the sealed row. On page retry, rebuild the live membership from a freshly\n  read `sessions.turns.list` (never duplicate bubbles or re-admit a terminal\n  row).\n- **Administrative observability (HA-65 \u002F D-426).** The one bounded\n  administrative query is `observability.query` (`POST \u002Fv1\u002Fobservability\u002F\n  query`): mandatory time window, a closed `group_by` set (tenant \u002F user \u002F\n  session \u002F model), existing source-backed measures only (successful\n  completions, exact cost, tokens, latency count\u002Fsum\u002Fmin\u002Fmax, task\n  completed\u002Ffailed\u002Fcancelled), fixed UTC minute buckets (may coarsen), and a\n  mandatory freshness block (`current` \u002F `catching_up` \u002F `unavailable` +\n  watermark) on every response — never zero as a substitute for\n  unavailable. Widening to other tenants\u002Fusers requires the verified\n  `admin`\u002F`console:fleet` scope and emits one `audit.admin_scope_used`.\n- **User-skill package import (HA-61 \u002F D-422).** A caller may install a\n  reviewed `SKILL.md` package as a durable personal skill through\n  `agent_config.user.skills.import_validate` (returns a bounded opaque\n  sealed `proposal_token` plus the normalized review\u002Fhashes\u002Fexpiry — it\n  performs ZERO writes) and `agent_config.user.skills.import_commit` (echo\n  the token and reviewed hashes; the runtime reauthenticates and\n  revalidates, forces your scope + the effective agent, and installs the\n  package in one conditional write). A stale\u002Fforeign\u002Fexpired token answers\n  the typed `skill_import_proposal_*` refusal; `replace: true` is required\n  to replace an existing package.\n- **Draft-only skill authoring (HA-62 \u002F D-423).** `skill_create_draft` is an\n  ordinary runtime tool (absent from the model-visible catalog until an\n  operator enables it per agent through the ordinary tool policy) that turns a\n  bounded `{intent, feedback?}` into ONE caller-scoped immutable `SKILL.md`\n  draft artifact — an artifact ref plus its versioned `package_hash`, a\n  bounded summary\u002Fwarnings, and an explicit `state: \"draft\"` \u002F\n  `installed: false`. It persists exactly that one immutable caller-scoped\n  ArtifactStore draft and has zero skill-install\u002Fconfig\u002Fpack\u002Fmembership\u002F\n  authority mutation: no approval path, no skill-store upsert,\n  membership\u002Frevision write, or operator-pack proposal\u002Fpublication; identity\n  comes exclusively from the run context (`persist`\u002F`publish`-shaped input is\n  rejected), and declared required tools are metadata only. Installing a draft\n  is the LATER explicit HA-61 path: `agent_config.user.skills.import_validate`\n  the artifact ref, review, then `import_commit` — the runtime reauthenticates\n  and revalidates before the one conditional install.\n- **Composition preview (HA-66 \u002F D-427).** `agent_config.composition.preview`\n  (`POST \u002Fv1\u002Fagent_config\u002Fcomposition\u002Fpreview`, claim-free for your own\n  triple) reports the effective skill composition a run would compose for\n  the named agent: per-item `boot|revision|both` provenance, the\n  per-package semantic hash, and the deterministic `boot_pack_set_hash`.\n  The same strict resolver feeds boot preflight, run, and preview — the\n  preview never mutates.\n\n## 5. Pause + steer + resume\n\nThe unified pause\u002Fresume primitive (RFC §3.3) is one wire choreography for every cause — HITL approval, tool-side OAuth, operator pause. The steering verbs share one route shape, `POST \u002Fv1\u002Fcontrol\u002F{method}`, with the run id and your steering scope in the body's `identity`:\n\n```bash\n# park the run at the next planner-step boundary\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fpause\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {\"run\": \"'$TASK_ID'\", \"scope\": \"owner_user\"}}'\n\n# feed it context while parked, then wake it\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Finject_context\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {\"run\": \"'$TASK_ID'\", \"scope\": \"session_user\"}, \"payload\": {\"note\": \"Actually, make it Barcelona.\"}}'\n\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fresume\" \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {\"run\": \"'$TASK_ID'\", \"scope\": \"owner_user\"}}'\n```\n\nThe `200 {\"accepted\": true, …}` means *enqueued*; the effect is narrated on the event stream — `pause.requested` when the run parks, `pause.resumed` (with a typed `Decision` of `approve` \u002F `reject` \u002F `resume` \u002F `timeout`) when it wakes. The planner sees injected context on its next step.\n\nFor HITL: an approval-gated tool emits `tool.approval_requested` with a pause token; your UI routes the human verdict through `POST \u002Fv1\u002Fcontrol\u002Fapprove` or `\u002Freject` with `\"payload\": {\"token\": \"\u003Cpause-token>\", \"reason\": \"…\"}`. `POST \u002Fv1\u002Fpause\u002Flist` is the snapshot of everything currently awaiting a human — reconcile against it on every (re)attach; it is authoritative across Runtime restarts. The full wire choreography (including the OAuth callback leg and `DecisionTimeout` reaps) is the published [pause-model choreography](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fpause-model).\n\nThe \"steer vs queue\" UI choice in [`drive-the-playground`](..\u002Fdrive-the-playground\u002FSKILL.md) §3 maps directly to \"POST `\u002Fv1\u002Fcontrol\u002Fpause` + inject + resume\" vs \"wait for `task.completed` then POST a new `start`\".\n\n## 6. Artifact upload — multimodal input\n\nFor images \u002F PDFs \u002F audio uploads from your UI, `artifacts.put` is a control-surface method: POST the bytes (base64-encoded inline on the request leg) and you get back a reference, never an echo of the body:\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fartifacts.put\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"scope\": {\"tenant\": \"dev\", \"user\": \"dev\", \"session\": \"dev\"},\n    \"bytes\": \"'\"$(base64 \u003C report.pdf)\"'\",\n    \"opts\": {\"mime_type\": \"application\u002Fpdf\", \"filename\": \"report.pdf\"}\n  }'\n```\n\nResponse carries the canonical `ref`:\n\n```json\n{\n  \"ref\": {\n    \"id\": \"art_01H...\",\n    \"mime_type\": \"application\u002Fpdf\",\n    \"size_bytes\": 142853,\n    \"filename\": \"report.pdf\"\n  },\n  \"protocol_version\": \"0.1.0\"\n}\n```\n\nPass `ref.id` in `start`'s `input_artifact_ids`. The upload bytes ride the request leg only (base64-inline, bounded by the Runtime's max request size — an oversize body is rejected with `request_too_large`); the response is a reference, and bytes never reach the LLM edge inline.\n\n### 6.1 Reading an artifact's bytes back — `artifacts.get`\n\n`artifacts.get` is the read that works everywhere. It resolves through the artifact store's mandatory `Get`, so **every** driver serves it — including the `inmem` default a fresh `harbor dev` boots on. (`artifacts.get_ref` is not an alternative to it so much as an optimisation: it returns a presigned URL, which only an S3-compatible store can mint, and answers `presign_unsupported`\u002F501 everywhere else.)\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Fartifacts.get\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"scope\": {\"tenant\": \"dev\", \"user\": \"dev\", \"session\": \"dev\"},\n    \"id\": \"'\"$REF_ID\"'\",\n    \"offset\": 0,\n    \"max_bytes\": 65536\n  }'\n```\n\n```json\n{\n  \"ref\": { \"id\": \"art_01H...\", \"mime_type\": \"text\u002Fcsv\", \"size_bytes\": 4194304 },\n  \"content\": \"\u003Cbase64>\",\n  \"offset\": 0,\n  \"returned_bytes\": 65536,\n  \"total_size_bytes\": 4194304,\n  \"truncated\": true,\n  \"protocol_version\": \"0.1.0\"\n}\n```\n\n**The response is always truthful about its own bound.** `total_size_bytes` is the artifact's full size, `returned_bytes` is what this call gave you, and `truncated` says whether anything follows the window — so a bounded read is never mistakable for a complete one.\n\n**To page a large artifact**, re-call with `offset` advanced to the previous `offset + returned_bytes`, while `truncated` is `true`. Windows are **byte** ranges, not lines or rows, so a window can begin and end mid-line and splitting is your job.\n\n**Three things can bound one read** and they all report through those same fields: your own `max_bytes`, the deployment's `artifacts.fetch_default_max_bytes` (applied when you name none — 64 KiB by default), and its `artifacts.fetch_hard_max_bytes` ceiling (1 MiB by default). Asking for more than the ceiling is **not an error** — you are served at the ceiling and `truncated` tells you so, because you have no way to discover the ceiling before asking. A NEGATIVE `offset` or `max_bytes` *is* rejected with `invalid_request`; it is not an omission the Runtime can resolve for you.\n\n**The ceiling bounds one read, not a sequence.** It is not a budget over repeated calls — aggregate consumption is the governance layer's concern (cost ceilings and rate limits).\n\nIdentity rules match the rest of the artifact surface: the full triple is mandatory, an id your scope does not hold answers `not_found`\u002F404 identically to one that never existed (existence is never revealed across identities), and a `scope` naming a tenant other than your verified one is refused `scope_mismatch`\u002F403 — **no admin claim widens this method**, because it hands over content rather than metadata.\n\nInside a run, the model reaches an artifact through the `artifact_fetch` builtin, which takes the same `offset` \u002F `max_bytes` and answers the same `offset` \u002F `returned_bytes` \u002F `total_size_bytes` \u002F `truncated` field set under the same operator-configured ceiling.\n\n**They are not the same read, and the difference is the point.** `artifacts.get` returns `content` as `[]byte` (base64 on the wire), so it is **byte-exact for every MIME at every offset** — a PDF, an image, a zip. `artifact_fetch` returns `content` as a JSON **string**, so it is a TEXT read: it tests the window for UTF-8 admissibility and **refuses one it cannot return intact** rather than letting JSON encoding rewrite invalid bytes to `U+FFFD` and hand the model corruption at a length the response contradicts. A refusal still carries `ref` \u002F `mime` \u002F `size_bytes` \u002F `total_size_bytes`, leaves `content` empty, and zeroes the windowing fields. The gate is content-driven, not MIME-driven — a text artifact carrying one invalid byte mid-window refuses too, rather than dropping it silently. `artifact_fetch` also trims partial runes at both window edges and reports the `offset` where content actually begins, and floors its effective `max_bytes` at 4; `artifacts.get` does neither, because it has no reason to.\n\nSo: reach for `artifacts.get` when you want the bytes. `artifact_fetch` is the model's text-recovery path; binary content reaches a tool through an artifact-reference parameter, not through the model.\n\n## 7. Topology snapshot — render the runtime's wiring\n\n```bash\ncurl -sS -X POST \"$HARBOR_BASE_URL\u002Fv1\u002Fcontrol\u002Ftopology.snapshot\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"X-Harbor-Session: $SESSION\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"identity\": {}}'\n```\n\nResponse is a graph of components + edges — Bifrost, tool catalog (with per-tool nodes), memory driver, state driver, artifact store, event bus, skill catalog. The Console's Topology page is one consumer; your custom dashboard could be another.\n\nThe capability is `topology.snapshot: true` (V1.1 phase 84a).\n\n## 8. Typed wire shapes — where they actually come from\n\nThree trustworthy sources, none of which is hand-rolling:\n\n- **Vendor the generated external-client TS module (TypeScript clients — start here).** `cmd\u002Fharbor-protocol-ts-types` emits `examples\u002Fprotocol-clients\u002Fevent-viewer-ts\u002Fharbor-protocol.gen.ts` — a self-contained, dependency-free module of TypeScript `interface`s for every canonical wire type plus `HarborMethod` \u002F `HarborErrorCode` \u002F `HarborEventType` string-union types and the pinned `PROTOCOL_VERSION` \u002F `WIRE_SURFACE_DIGEST` constants. Copy that one file into your client and write your transport against it. Regenerate \u002F re-vendor with `make protocol-ts-types-gen`; it is drift-gated by `make protocol-ts-types-gen-check`. The worked `event-viewer-ts` client consumes it against the dev runtime. This module carries **types only, no client logic** — it is distinct from the Console's hand-maintained `protocol.ts` (which carries the typed `HarborClient`), and the FULL Console-`protocol.ts` generator remains deferred (D-132); the `cmd\u002Fharbor-gen-protocol-ts` name stays reserved for it.\n- **The generated contract reference** — [the generated types page](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Ftypes) catalogues every canonical wire struct field-by-field with the snake_case JSON keys, generated by `cmd\u002Fharbor-gen-protocol-docs` from the Go single sources and drift-gated by `make protocol-docs-gen-check`. Read it (or transcribe from it) when you want the field-level reference; when the wire changes, the page changes in the same PR by construction.\n- **Vendor the Console's client module** — copy `web\u002Fconsole\u002Fsrc\u002Flib\u002Fprotocol.ts` into your TS client when you also want the typed `HarborClient` transport (not just the types). It is **hand-maintained** in lockstep with the Go wire types (the full TS-client *generator* is deferred per D-132 \u002F issue #179), kept honest by the Console's CI. License is Apache-2.0; attribution required.\n- **Import the curated Go client facade** — Go applications import `github.com\u002Fhurtener\u002FHarbor\u002Fsdk\u002Fprotocolclient`. It exposes only the supported typed methods, generic JSON call core, typed errors, and SSE stream; it does not wholesale re-export Runtime internals or every Protocol method.\n\nHand-rolling the types from scratch is fine for a quick prototype but you'll drift. Anchor any client you intend to maintain on the generated module or the generated reference.\n\n### 8a. Reading a downstream scope shortfall\n\nWhen an MCP-backed tool call is refused downstream with a `403` + `WWW-Authenticate: Bearer error=\"insufficient_scope\"` (RFC 6750 §3.1), the shortfall surfaces as **structured data on the two surfaces you already read** — never an opaque error string:\n\n- **On the tool-result error path** — the `tool.failed` event's `ScopeShortfall` field carries `downstream_resource`, `required_scopes`, `granted_scopes`, the verbatim `www_authenticate` header, and `origin`. It is set only when the challenge is explicitly marked `insufficient_scope`; an unmarked 403 stays an opaque failure. The runtime classifies the shortfall as **permanent** (it never retries a shortfall retrying cannot fix).\n- **On the MCP connection view** — `mcp.servers.get` returns `MCPServerView.last_scope_shortfall` (`MCPScopeShortfallView`) recording the last observed shortfall on that connection — visible even to a reader who never made the offending call. It rides the DETAIL read only (like `oauth_requirement`), not the hot list row.\n\nBoth are **report-only**: the runtime never auto-escalates, re-consents, or widens a binding on a shortfall. The operator acts on it via the boot-declared `oauth_provider` \u002F `tool_oauth_providers` bindings (which bind a distinct provider per MCP-side entry — a tool call by tool name, a resource read \u002F subscribe by resource URI, and a prompt get by prompt name — for a server fronting several downstream audiences).\n\n**Typed MCP failure classification survives replay (HA-54 \u002F D-410).** When an\nMCP server marks a `CallToolResult` `IsError: true` with the namespaced\n`harbor.error` classification (`{error: {class, message}}` on `_meta` or in\n`structuredContent`), the runtime lowers it to a typed failure — one of\n`invalid_argument` \u002F `validation` \u002F `authorization` \u002F `not_found` \u002F `conflict`\n\u002F `tool_domain` \u002F `transient` \u002F `provider_unavailable`, with a bounded\nmessage — and projects it onto permanent-vs-retryable policy: the\ndeterministic classes invoke exactly once (a `conflict` such as a\n`revision_conflict` is permanent for the unchanged invocation and carries the\ncurrent revision in its bounded message for reread\u002Fretry), while a retryable\nprovider\u002Ftransport failure uses the configured budget. The classified\nobservation SURVIVES the runloop's step recording into the actual next ReAct\nprompt: the typed class, retry-policy outcome, bounded message, and retained\nbounded result content render as fields, and a generic `Step.Error` never\nmasks them. Raw tool arguments are redacted on every failed-replay shape — no\nraw args, secrets, or unbounded provider output reach the observation or the\nprompt. For providers without the Harbor extension, an `IsError` result's\ntop-level `structuredContent.code` has a closed compatibility mapping:\n`invalid_argument` → `invalid_argument`, `validation_failed` → `validation`,\n`forbidden_scope` \u002F `scope_blocked` \u002F `scope_mismatch` → `authorization`,\n`not_found` → `not_found`, and `document_too_large` → `tool_domain`.\nThese deterministic codes stop after one invocation. The error message is the\ncode followed by the provider's bounded text content, so its repair detail\nreaches the planner; the text never affects the class. The original structured\ncontent, including any document outline, remains available; oversized-document\nfailures also tell the planner to read a smaller section or reduce the\nprovider's read-size limits instead of repeating the same full read. A valid\nnamespaced classification takes precedence. Unknown codes, nested codes,\n`retryable: true`, malformed retryability, and malformed explicit Harbor\ncontracts retain the transient fallback; no prose is parsed.\nA legacy unclassified `IsError` keeps the generic safe fallback: its\nlowered text is preserved, policy treats it as transient, and the generic\nrender remains. The terminal projection is observable on the stream as\n`tool.failed` (`ErrorClass` \u002F `ErrorMessage` \u002F `Attempts`) and\n`tool.policy_exhausted` (`LastClass` \u002F `LastError`), which agree with what the\nplanner observed.\n\n**Downstream HTTP authentication and session recovery.** For signed receiver\nbindings with `authenticate_preparation` enabled and injected header or Basic\ncredentials, an MCP server's HTTP 401 or 403 does not terminate Harbor's shared\nstreamable HTTP session. A later call resolves its own credential again. A call\nretries once through a replacement session only when the SDK confirms that a\nclosed connection rejected it before dispatch. A missing session is repaired\nfor later calls without replaying a tool call, since an in-flight call may\nalready have executed; only read-only operations may replay once. Other\ntransport errors do not trigger this recovery. Harbor never silently falls back to an\nunauthenticated request. At the MCP Protocol edge,\n`downstream_mcp_unauthorized` uses HTTP 424 (Failed Dependency), requiring\ncredential intervention, while `downstream_mcp_transport_failed` uses HTTP\n502. Both have fixed summaries that exclude upstream endpoints, response\nbodies, headers and credentials. They identify downstream failures, so do not\nrefresh the Harbor connection JWT or mark the Runtime disconnected because of\nthese codes. Resolve a credential refusal before retrying; back off for an\nunavailable server. A transport failure alone does not establish whether a\nside-effecting operation is safe to replay.\n\n### 8b. What an MCP connection admin write can reach\n\nThe per-server `mcp.servers.*` admin verbs gate on the `admin` scope claim, and the write ones additionally land only where your own identity reaches:\n\n- `mcp.servers.set_raw_html_trust` (the per-server raw-HTML posture a rendered MCP App is given) is **tenant-scoped**. It applies to a connection your own tenant owns, or to a boot-declared (yaml) server, which is deployment-global infrastructure every session already sees. Naming a connection another tenant attached is refused `404 {\"code\": \"not_found\"}` — the same answer you get for a name nobody registered, so the refusal tells you nothing about what other tenants have attached. The scope comes from your verified identity, not from anything on the request body.\n- `agent_config.set_mcp_discovery_origins` is **owner-scoped** to your `(tenant, agent_id)` and refuses `403 {\"code\": \"scope_mismatch\"}` — see §8's account of that verb. The two differ because that door carries an `agent_id` and this one does not.\n- A write whose audit event cannot be emitted is **reverted**, not left applied: you get `500 {\"code\": \"runtime_error\"}` naming the reverted-not-applied case, and the previous value stands.\n\nBoot-declared servers stay visible to every session. Tenant-owned sources require current signed agent reach and selection in the owning configuration; personal sources also require the owning user. The source-addressed `refresh_discovery` \u002F `probe` calls use the exact returned server ID and carry that admitted registration's owner agent into credentialed discovery. An existing effective-agent selection must agree; neither the admin scope nor a boot invoking-agent attribution substitutes for signed reach or current configuration.\n\n### 8c. Not clobbering another writer — `expected_content_hash`\n\nEvery `agent_config.*` spine write is **last-writer-wins by default**. If you read a config, edit it, and write it back, any change another writer made in between is silently reverted and you are told `200`. That window is seconds to minutes for a human editing in the Console, and however long your agent takes to compose a config.\n\nTo close it, send the **expected-revision token**. `agent_config.get` returns both `revision_id` and `content_hash` on the active revision; pass that `content_hash` back as `expected_content_hash` on your write:\n\n```jsonc\n\u002F\u002F 1. read\nPOST \u002Fv1\u002Fagent_config\u002Fget     → { \"revision\": { \"revision_id\": \"01J…\", \"content_hash\": \"9f2c…\" }, \"set\": true }\n\n\u002F\u002F 2. write under the base you read\nPOST \u002Fv1\u002Fagent_config\u002Fset_revision\n{ \"agent_id\": \"support-bot\",\n  \"payload\": { \u002F* … your edit … *\u002F },\n  \"expected_content_hash\": \"9f2c…\" }\n```\n\n- **Matching** → the write proceeds exactly as an unconditional write would.\n- **Not matching**, or **a hash sent when no active revision exists** → `409 {\"code\": \"revision_conflict\"}`, and **nothing is persisted**: no revision, no active-pointer move, no `agent.config.revised` event.\n- **Omitted** (the default) → byte-for-byte the unconditional behaviour that has always shipped. Nothing you have today changes.\n\n**The first write needs its own token.** When `agent_config.get` answers `{\"set\": false}` the agent has no config yet and there is no `content_hash` to echo back. Send the reserved value `\"-\"`:\n\n```jsonc\nPOST \u002Fv1\u002Fagent_config\u002Fget     → { \"set\": false }          \u002F\u002F no hash exists\n\nPOST \u002Fv1\u002Fagent_config\u002Fset_extra_system_blocks\n{ \"agent_id\": \"support-bot\",\n  \"extra_system_blocks\": { \"blocks\": [ \u002F* your block *\u002F ] },\n  \"expected_content_hash\": \"-\" }                          \u002F\u002F \"I expect there to be none\"\n```\n\nIt succeeds only while the agent has no active revision, and returns `409 {\"code\": \"revision_conflict\"}` the moment one exists. **Send it — do not omit the token on a first write.** Omitting it is an unconditional write, so two contributors composing onto a fresh agent both succeed and the second silently reverts the first. A real content hash is always 64 lowercase hex characters, so `\"-\"` can never collide with one.\n\n**`add_mcp_connection` prepares before it publishes.** The expected hash is checked under the owner lock before any dial or provider preparation. After that check, Harbor may dial, authenticate, handshake, and discover into a private preparation, but the provider, catalog entries, live registration, and `online` state remain unpublished until the desired revision is durable. A `409` therefore closes only unpublished resources and leaves the exact prior live connection intact. Activation stages the registry reversibly and makes the catalog swap the dispatch boundary; a collision restores both. If a write reports failure, an exact pointer re-read distinguishes a confirmed landing from not-landed or unreadable state—there is no unconditional detach fallback. Inline OAuth uses an installation receipt, so rollback can remove only the provider this call installed.\n\nIt is available on all **seventeen** spine-writing doors — `set_revision`, `rollback`, `skills.upsert`, `skills.delete`, `set_tool_exposure`, `set_prompt_layers`, `set_extra_system_blocks`, `set_llm_params`, `add_mcp_connection`, `remove_mcp_connection`, `set_mcp_discovery_origins`, `set_oauth_provider`, `remove_oauth_provider`, and the four `user.*` twins (`user.set_revision`, `user.rollback`, `user.skills.upsert`, `user.skills.delete`). It is **not** on `set_llm_provider` (which installs a provider and writes no revision) or on the `agent_config.session.*` verbs (which write the ephemeral session overlay, not the durable spine).\n\n**Read your token from the tier you are about to write.** The examples above use `agent_config.get`, which reads the AGENT tier — correct for the thirteen admin doors. The four `user.*` twins write the USER tier, and its hash comes from **`agent_config.user.get`**. They are separate revision spines: a hash read from `agent_config.get` will never match a `user.*` write, so passing one there is a guaranteed `409` every time.\n\n**Recovering from a conflict.** Re-read `agent_config.get` for the current `revision_id` + `content_hash`, call `agent_config.diff` with `from_revision` = the id you originally read and `to_revision` = the current id to see what moved, re-apply your edit on top, and resubmit with the fresh hash. One extra round trip on a rare path.\n\n**Why a content hash and not a revision id.** `rollback` repoints the active pointer without necessarily changing the content. If the token were a revision id, an operator restoring exactly the content you read would be reported to you as a conflict — a false positive on the recovery path. The token tracks the value you computed against, which is what you actually depend on.\n\n**Know the authority before you rely on it.** The refusal is exact across\nRuntime processes sharing any shipped StateStore driver. Publication rechecks\nthe active-pointer EventID through the triad-wide `StateStore.SaveIf` predicate;\nthe agent-config service's per-owner write lock only reduces same-process\ncontention. This does not make a token an exclusive lock: a concurrent writer\nthat omits the token remains an unconditional last writer by design.\n\nTwo more things worth knowing:\n\n- **The token constrains only the writer that supplies it.** A concurrent writer that omits it can still overwrite you, by design — the token is a precondition on your write, never a lock on the agent. Exclusivity requires every writer of that agent's config to participate.\n- **It is a precondition, never an authority.** It is compared strictly after the identity and scope gates and can only ever cause a write to be *refused*. A valid token never buys a caller a write it could not otherwise make.\n\n### 8d. Retiring an agent-config identity is terminal — `agent_config.retire`\n\n`agent_config.retire` is an **admin-only**, owner-scoped lifecycle operation. It replaces the active agent-config pointer with a durable tombstone; it does not delete immutable revision history. Supply a non-empty `operation_id` and the active `expected_content_hash` (or `\"-\"` when there has never been an active revision). A same-operation retry is valid only when it repeats that exact original expectation; a different operation or expectation returns `409 {\"code\":\"agent_retirement_conflict\"}`.\n\nAfter retirement, all active\u002Fcurrent config reads and durable writes, plus every `agent_config.session.*` overlay write, fail with `409 {\"code\":\"agent_retired\"}`. `agent_config.list_revisions` and `agent_config.diff` remain available for immutable-history audit. To recover status or resume cleanup after a timeout or restart, repeat `agent_config.retire` with the exact same `operation_id` and original `expected_content_hash`; that replay returns the durable status and continues any pending cleanup, while either value changing is a conflict. Operators should watch the canonical `agent_config.retirement.started`, `.progress`, and `.completed` events; event payloads expose only the hashed operation identifier and cleanup counts, never config contents.\n\nD-401 signed OAuth MCP pairs are retired through their existing durable paired-removal receipt even when the original authority has expired, been revoked, or can no longer be verified after key rotation. The retirement status may expose a `signed_oauth_mcp_pair` cleanup class whose resource is hashes only; it never exposes the URL, JWT\u002FJTI, credentials, or stored owner subject. A close failure leaves the retirement incomplete and retryable with the same retirement operation.\n\nFor a signed receiver capability that requires credentials during initialize or\ndiscovery, sign `connection.injection.authenticate_preparation: true` inside the\nauthority envelope and submit the identical descriptor. Initialize, each list,\nrefresh, and reattachment use the verified acting identity and fail before any\nrequest on missing or failed credentials. Header and Basic injection support HTTP\npreparation; meta injection requires streamable HTTP. An unsigned connection write\ncannot enable this setting. Omitted or false preserves existing preparation.\n\nAn agent may carry more than one signed OAuth MCP capability. Revision payloads\nproject the first pair in `signed_oauth_mcp_pair` and additional providers in\nthe `signed_oauth_mcp_pairs` object keyed by `provider_name`; clients should\nread both as one set. To remove one pair from a multi-pair revision, send that\nprovider name with the revision's `expected_content_hash`. Omitting\n`provider_name` works only when the named revision contains exactly one pair.\nRegistration, restart recovery, removal, and retirement remain independent per\npair, so removing one capability does not disconnect its siblings.\n\nRetirement does **not** deregister the Runtime fleet agent. `agents.deregister` remains a separate fleet lifecycle action with separate authorization and audit semantics.\n\n### 8e. Contributing ONE prompt block without owning the whole prompt — `extra_system_blocks`\n\nIf two independent capabilities each want to add a paragraph to an agent's system prompt, the layered prompt does not help: `prompt_layers.base` and `prompt_layers.user` are ONE string each, so the second contributor has to know — and re-send — the first's text, and removing one contribution means re-deriving the composition from prose.\n\n`POST \u002Fv1\u002Fagent_config\u002Fset_extra_system_blocks` gives that composition a NAMED, ORDERED carrier:\n\n```jsonc\nPOST \u002Fv1\u002Fagent_config\u002Fset_extra_system_blocks\n{ \"agent_id\": \"support-bot\",\n  \"extra_system_blocks\": { \"blocks\": [\n      { \"name\": \"billing-policy\", \"body\": \"Never quote a refund amount; hand off to billing.\" },\n      { \"name\": \"tone\",          \"body\": \"Answer in \u003C=3 sentences.\" }\n  ] },\n  \"expected_content_hash\": \"9f2c…\" }\n```\n\n- **Order is the render order.** The array order is what the model sees, it is part of the revision's `content_hash`, and a pure re-ordering is a real new revision that `agent_config.diff` reports as `extra_system_blocks.reordered: true`. (Contrast `skills.names` and `oauth_providers`, whose orders are canonicalised by sorting.)\n- **It is a WHOLE-SECTION desired-state replace**, like every sibling section. There are deliberately no per-block verbs — a block is one element of an ordered composition, so a per-item upsert has no well-defined insertion position. **To add or remove exactly your own block: `agent_config.get` → append or drop your entry BY NAME → write the full list back with the read revision's `content_hash` as `expected_content_hash` (§8c), or `\"-\"` when the read answered `{\"set\": false}`.** Without a token you can silently delete a sibling contributor's block; with it you get `409 {\"code\": \"revision_conflict\"}` and retry.\n- **Names are unique and match `[A-Za-z0-9._-]{1,64}`.** A duplicate or malformed name is refused `400 {\"code\": \"invalid_request\"}`, naming the offender and (for a duplicate) both positions, and nothing is persisted. Uniqueness is what makes remove-by-name well defined.\n- **Bodies render VERBATIM** — unescaped, in declared order, each behind a plain-text `[name]` label, inside the existing operator-owned `\u003Cadditional_guidance>` section. They compose below the runtime's baked guidance and above the admin-set tenant guidance, and they **survive a session `system_prompt_override`** (which replaces only the base+user spine). The ordinary caller's one-run `extra_instructions` value is separate: it renders escaped in `\u003Cuser_personalization>` and never joins these blocks.\n- **The verb is admin-scoped, and that tier IS the trust boundary.** Blocks are unescaped because only the admin tier — the same tier that writes `prompt_layers.base`, which is already verbatim and strictly more powerful — can write them. **Therefore: never put user-authored or model-authored text in a block.** Recalled conversation content belongs in `start.caller_memory`, which lands in the untrusted-framed memory tier; user instructions belong in `prompt_layers.user`, which IS escaped precisely because a claim-free session path can write it.\n- **The `[name]` label is legibility, not a security boundary.** It helps a human reading a transcript tell contributions apart. To the model, two blocks from two capabilities are one contiguous run of trusted guidance.\n- Omitting the section entirely leaves the composed prompt byte-identical to an agent that never had one. Every sibling section (prompt layers, skills, tool exposure, connections, OAuth providers, LLM params, hooks, naming) is carried forward across a block write, and vice versa.\n\n## 9. A minimal client (TS, ~30 LoC)\n\n```typescript\nconst baseUrl = \"http:\u002F\u002F127.0.0.1:18080\";\nconst token = \"\u003CHARBOR_DEV_TOKEN>\";\nconst identity = { tenant: \"dev\", user: \"dev\", session: \"dev\" };\n\n\u002F\u002F One REST call per method: POST \u002Fv1\u002F\u003Cfamily>\u002F\u003Cmethod>, flat body in, flat body out.\nasync function call\u003CT>(route: string, body: object): Promise\u003CT> {\n  const res = await fetch(`${baseUrl}${route}`, {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application\u002Fjson\",\n      \"Authorization\": `Bearer ${token}`,\n      \"X-Harbor-Tenant\": identity.tenant,\n      \"X-Harbor-User\": identity.user,\n      \"X-Harbor-Session\": identity.session,\n    },\n    body: JSON.stringify(body),\n  });\n  if (!res.ok) {\n    const err = await res.json().catch(() => ({ code: `http_${res.status}` }));\n    throw new Error(err.code ?? `http_${res.status}`);\n  }\n  return res.json() as Promise\u003CT>;\n}\n\nconst info = await call(\"\u002Fv1\u002Fcontrol\u002Fruntime.info\", { identity: {} });\nconsole.log(\"connected to harbor\", info);\n\nconst { task_id } = await call\u003C{ task_id: string }>(\"\u002Fv1\u002Fcontrol\u002Fstart\", { identity: {}, query: \"Hello!\" });\n\n\u002F\u002F The stream is session-scoped (no task_id query param), so filter client-side.\nconst sse = new EventSource(`${baseUrl}\u002Fv1\u002Fevents?access_token=${encodeURIComponent(token)}`);\nsse.addEventListener(\"llm.completion.chunk\", (e) => {\n  const data = JSON.parse(e.data);\n  const chunk = data.payload;\n  if (chunk.TaskID === task_id && chunk.Kind === \"content\") {\n    process.stdout.write(chunk.Delta); \u002F\u002F Provisional animation, not the final answer.\n  }\n});\nsse.addEventListener(\"task.completed\", (e) => {\n  if (JSON.parse(e.data).payload.TaskID === task_id) sse.close();\n});\n```\n\nThis fragment demonstrates live content routing only. A production chat client\nalso needs the restart\u002Fhistory choreography above, response-boundary grouping,\nfailed\u002Fcancelled terminal handling, and final-answer reconciliation; it must not\ntreat concatenated progress text as the final answer.\n\n## Common failure modes\n\n- **Every call returns 401.** Token expired (24h TTL) or rotated (`harbor dev` restarted). Re-fetch token, retry.\n- **CORS preflight fails.** Your origin isn't in `server.allowed_origins`. Add it to the yaml + restart Runtime.\n- **SSE stream opens but no events.** The `payload.TaskID` capital-T gotcha — your handler is reading `payload.task_id` (lowercase). Fix the case.\n- **A control call returns `404 {\"code\": \"unknown_method\"}` or 405\u002F501.** This runtime doesn't serve that surface. Call `runtime.info` first, branch on `capabilities`, and degrade the feature instead of crashing (the [versioning & compatibility contract](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fversioning-and-compatibility)).\n- **Artifact upload returns 413 Payload Too Large.** The request body exceeded the Runtime's `protocol.max_request_bytes` (default 4 MiB) — the canonical `{\"code\": \"request_too_large\"}` envelope. Chunk uploads aren't supported in V1.1; raise `protocol.max_request_bytes` in the Runtime's `harbor.yaml` if you need larger inline uploads.\n- **An agent-config write returns `409 {\"code\": \"revision_conflict\"}`.** You sent an `expected_content_hash` and another writer moved the base between your read and your write. Nothing was persisted. Re-read `agent_config.get`, re-apply your edit on the current content, and resubmit with the fresh hash — see §8c. (You also get this code when you send a *hash* and the agent has **no** active revision — send the reserved `\"-\"` for that case — and when you send `\"-\"` and a revision already exists.)\n- **Topology snapshot rejected.** This Runtime doesn't advertise the `topology_snapshot` capability — check `runtime.info.capabilities` before enabling the panel.\n- **The Console reads internal Runtime objects.** It doesn't — that would be a CLAUDE.md §13 violation. If you suspect leakage, file a bug; the Console reads only what's documented as a Protocol surface.\n\n## See also\n\n- **The Protocol adoption track** — [the published quickstart + generated reference + choreographies](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002F): the adopter-facing contract docs this skill's recipes sit on top of. Start there for any client you intend to maintain. The track is complete: five choreographies (including [the pause model](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fpause-model) and [versioning & compatibility](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fversioning-and-compatibility)), the worked [build-a-client guide](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fbuild-a-client) (its ~150-line SDK-free event viewer ships at `examples\u002Fprotocol-clients\u002Fevent-viewer\u002F`), and the [conformance-certification path](https:\u002F\u002Fhurtener.github.io\u002FHarbor\u002Fprotocol\u002Fconformance-certification).\n- [`run-the-dev-loop`](..\u002Frun-the-dev-loop\u002FSKILL.md) — boot the Runtime + grab the dev token first.\n- [`drive-the-playground`](..\u002Fdrive-the-playground\u002FSKILL.md) — the Console's chat UI; same Protocol underneath.\n- [`observe-with-the-console`](..\u002Fobserve-with-the-console\u002FSKILL.md) — every Console page maps 1:1 to a Protocol method.\n- The wire types: `internal\u002Fprotocol\u002Ftypes\u002F`.\n- The methods registry: `internal\u002Fprotocol\u002Fmethods\u002Fmethods.go`.\n- The error codes: `internal\u002Fprotocol\u002Ferrors\u002Ferrors.go`.\n- The public Go client: `sdk\u002Fprotocolclient`.\n- The docs generator: `cmd\u002Fharbor-gen-protocol-docs\u002F` (D-209). The external-client TS wire-type generator: `cmd\u002Fharbor-protocol-ts-types\u002F` (D-269) → `examples\u002Fprotocol-clients\u002Fevent-viewer-ts\u002Fharbor-protocol.gen.ts`. The FULL Console-`protocol.ts` TS-client generator remains deferred (D-132 \u002F issue #179, name `cmd\u002Fharbor-gen-protocol-ts` reserved); `protocol.ts` is hand-maintained.\n- RFC §5 — Harbor Protocol design.\n\nFor shared-runtime broker custody, require the runtime.info capability\n`tenant_scoped_broker_credentials_v1`; its absence means tenant-selected broker\nclient credentials are unsupported. This describes the runtime pull implementation,\nnot proof that a particular coordinator endpoint or grant is ready.\n\n### Configure the agent's working-input budget\n\nNegotiate `agent_config_memory_v1` on `runtime.info` before writing\n`agent_config.set_revision.payload.memory.budget_tokens`. This admin-only,\nnonnegative token target uses the existing revision\u002FCAS\u002Fdiff\u002Frollback surface.\nAn absent memory section inherits runtime YAML; explicit zero requests automatic\nmodel sizing. Preserve writable sibling sections and use the active revision's\ncontent hash as `expected_content_hash`. The next run freezes the new target;\nin-flight runs keep their original budget. It is not an output-token limit or\na cap on stored exact evidence. An unwired compactor is a loud refusal, not an\naccepted but ineffective configuration. Embedded callers continue using YAML\nor the equivalent configuration object.\n\n### Send model and thinking with Start\n\nFor a run-specific selection, use `llm_settings` on `control.start` instead of\npairing `runs.set_overrides` with a later Start. Negotiate\n`run_llm_settings_v1` when supporting older runtimes. Example request members:\n\n```json\n{\"llm_settings\":{\"model\":\"configured-model\",\"reasoning_effort\":\"high\",\"max_tokens\":2048}}\n```\n\nFor an external model, omit `llm_settings.model` and include the existing opaque\n`provider_route` beside `llm_settings` on Start. Never supply both model sources.\nSettings are copied into the accepted task; concurrent selections cannot replace\nthem. Exact retries reuse the task; changing settings under the same idempotency\nkey conflicts. A present bundle skips the legacy next-message slot. Omitted\nfields use runtime\u002Fagent defaults, an empty reasoning value requests provider\ndefaults, and `off` disables thinking. No preference is saved and no restart is\nneeded. Governance and selected-model support remain authoritative.\n\n### Run limits\n\nNegotiate `run_limits_v1` on `runtime.info`. A run can be bounded by maximum\nactive duration (time waiting on a pause is not counted) and maximum cumulative\nprompt plus completion tokens; each is optional and unset means no limit.\n\n- Runtime default: `runtime.run_limits.{max_duration, max_tokens}` in YAML.\n- Per agent: `agent_config.set_revision.payload.run_limits` with\n  `max_duration_seconds` and\u002For `max_tokens` (positive integers). A present\n  section replaces the runtime default; an omitted field means no limit for\n  that dimension, so `{\"run_limits\":{}}` removes both. Preserve sibling\n  sections and use `expected_content_hash` as for any revision. The\n  `agent_config.diff` response carries `run_limits` only when it changed.\n- Per run: `control.start` accepts\n  `{\"run_limits\":{\"max_duration_seconds\":600,\"max_tokens\":200000}}`, which can\n  only tighten the effective limit, never loosen or remove it. It is part of\n  Start's idempotency identity.\n\nWhen a run reaches a limit it emits `run.limit_reached` (payload `Limit` —\n`max_duration` or `max_tokens` — plus the configured values, elapsed time,\ntokens used and step count), makes one bounded call without tools that states\nwhat was done and what remains, and completes normally: `task.completed` with\n`result_inline.finish_reason` set to `limit_reached` and the partial answer.\nA limit never produces `task.failed`. A run with an output schema that stops at\na limit completes without `answer_payload`; check `finish_reason` before\nreading it. Show the person that the limit was\nreached and let them continue in the next message.\n\n### Session artifact tools\n\nWhen the runtime lists them in `tools.built_in`, the model can call\n`artifact_search` (grep inside a stored text artifact; each match carries\n`line`, `byte_offset` for `artifact_fetch`, and context), `artifact_list`\n(newest-first, filter by `source` — `user_upload`, `tool`, `other` — by\nproducing `tool` or by filename text, with `cursor` pagination) and\n`artifact_note` (add, replace or clear a note of at most 1024 bytes). A note\nchange publishes `artifacts.note_set` with the artifact id and note size, never\nthe note text. All three resolve on the session's isolation triple.\n\nFor `artifact_list`, use `{}` for the first unfiltered page. Omit unused fields\nor use empty strings for unused string fields (blank strings also mean unset);\ndo not send `null`. The only nonempty `source` values are `user_upload`, `tool`\nand `other`; omit `source` to include all origins. Send `limit` as a JSON integer,\nnot a quoted number: omitted or nonpositive values use 20, and values above 50\nare capped at 50. To continue, copy the returned `next_cursor` string exactly\ninto `cursor`. A cursor is neither a page number nor an artifact ref. Invalid\nJSON types or unknown argument names fail validation before the tool runs;\ninvalid source values and cursor strings return a field-specific `error`.\n\n## Broker-bound manual App operations (candidate)\n\nTrusted host integrations may use the optional `app_operation` selector on\n`mcp.servers.read_resource` and `mcp.apps.call_tool`, as specified in\n[App operation v1](..\u002F..\u002Fcontracts\u002Fapp-operation-v1.md). The selector is not\npermission or a bearer. Keep it and runtime credentials outside the frame.\nCallbacks still require fresh render admission; the broker must acknowledge the\nexact binding and current policy. Unsupported brokers refuse. This candidate\nrequires external integration acceptance before activation and does not alter\nordinary credential caching or authorize a chat\u002Fplanner fallback.\n",{"name":5,"license":15,"metadata":24,"description":7},{"verbs":25,"surface":26,"framework":27},"","protocol","harbor","main","d5e4bebc2516f8ae118156a73921760e3089c169","docs\u002Fskills\u002Fuse-the-harbor-protocol",1,"https:\u002F\u002Fgithub.com\u002Fhurtener\u002FHarbor","https:\u002F\u002Fgithub.com\u002Fhurtener","2026-11-15 04:22:13",{"source":8,"skillName":5,"commands":36,"prompt":46,"zipAvailable":47},[37,40,43],{"tool":38,"command":39},"npx","npx skills add hurtener\u002FHarbor --skill use-the-harbor-protocol",{"tool":41,"command":42},"bunx","bunx skills add hurtener\u002FHarbor --skill use-the-harbor-protocol",{"tool":44,"command":45},"pnpm","pnpm dlx skills add hurtener\u002FHarbor --skill use-the-harbor-protocol","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fhurtener\u002FHarbor\u002Fblob\u002Fmain\u002Fdocs\u002Fskills\u002Fuse-the-harbor-protocol\u002FSKILL.md",true,[],[50,57,64,71,78,85],{"skillNo":51,"name":52,"nameZh":6,"description":53,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":54,"categories":55,"keywords":56,"publishedAt":19},"01M723EVVMQQH8MFVBKTYMTW22","wire-the-llm-provider","Pick a real LLM provider and wire it through Bifrost — OpenRouter \u002F Anthropic \u002F OpenAI \u002F Azure \u002F NVIDIA NIM \u002F OpenAI-compatible endpoints. Use when configuring the `llm:` block beyond the scaffold default, swapping models, setting model_profiles, or using the dev-only mock escape hatch.","https:\u002F\u002Fgithub.com\u002Fhurtener\u002FHarbor\u002Fblob\u002Fmain\u002Fdocs\u002Fskills\u002Fwire-the-llm-provider\u002FSKILL.md",[],[],{"skillNo":58,"name":59,"nameZh":6,"description":60,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":61,"categories":62,"keywords":63,"publishedAt":19},"01M723ESCAV3DX4FSWHB9QRXDT","validate-and-package","Run `harbor validate` + `make preflight` + the per-phase smoke gates before shipping an agent. Use when packaging an agent for a non-dev environment — production deploy, share with a teammate, hand off to CI, or ship a release tag.","https:\u002F\u002Fgithub.com\u002Fhurtener\u002FHarbor\u002Fblob\u002Fmain\u002Fdocs\u002Fskills\u002Fvalidate-and-package\u002FSKILL.md",[],[],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M723E99VBZ6D9XCG10RPJMM1","scaffold-a-harbor-agent","Scaffold a new Harbor agent project with `harbor init` + `harbor scaffold`. Use when starting a fresh agent from zero — drops a tiered, commented `harbor.yaml`, the companion AGENTS.md \u002F CLAUDE.md \u002F README.md, and materialises the Go project so `harbor dev` boots a working runtime in under five minutes.","https:\u002F\u002Fgithub.com\u002Fhurtener\u002FHarbor\u002Fblob\u002Fmain\u002Fdocs\u002Fskills\u002Fscaffold-a-harbor-agent\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M723E52YP0JSH9R22APN4T5M","run-the-dev-loop","Use `harbor dev` + `harbor console` to run an agent locally with the Console attached. Use when iterating on a Harbor project — single-process or multi-process attach posture, the `HARBOR_DEV_TOKEN` handshake, hot reload on yaml changes, and which posture to pick when.","https:\u002F\u002Fgithub.com\u002Fhurtener\u002FHarbor\u002Fblob\u002Fmain\u002Fdocs\u002Fskills\u002Frun-the-dev-loop\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M723E1M9CF4V7ZMHAMA3GY2Y","observe-with-the-console","Tour the Console's observability pages — Overview, Live Runtime, Observability, Sessions, Tasks, Agents, Tools, Events, Background Jobs, Playground, Flows, Memory, MCP Connections, Artifacts, Settings. Use when debugging an agent's behavior, hunting a regression, or building intuition for what the runtime is actually doing under the hood.","https:\u002F\u002Fgithub.com\u002Fhurtener\u002FHarbor\u002Fblob\u002Fmain\u002Fdocs\u002Fskills\u002Fobserve-with-the-console\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M723DXYEMV4VWKM7A65BHR5E","drive-the-playground","Use the Console's Playground page to chat against your agent, attach files (images \u002F PDFs \u002F audio), and steer or queue input during a run. Use when validating the agent end-to-end interactively, the foreground\u002Fbackground task posture, image-vs-PDF MIME dispatch, and the playground's steering UI.","https:\u002F\u002Fgithub.com\u002Fhurtener\u002FHarbor\u002Fblob\u002Fmain\u002Fdocs\u002Fskills\u002Fdrive-the-playground\u002FSKILL.md",[],[]]