[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M723DQGY2XG21CKBXW4WT1XZ":3,"skill-same:01M723DQGY2XG21CKBXW4WT1XZ":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},"01M723DQGY2XG21CKBXW4WT1XZ","define-the-agent-yaml",null,"Walk every field in `harbor.yaml` — REQUIRED (identity + llm), COMMON (planner \u002F memory \u002F state \u002F tools \u002F skills \u002F governance), ADVANCED (server \u002F telemetry \u002F artifacts \u002F events \u002F sessions \u002F tasks \u002F distributed). Use when editing the agent config beyond the scaffolded defaults.","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\u002Fdefine-the-agent-yaml\u002FSKILL.md",[],[],"2026-11-10 18:39:20",false,"---\nname: define-the-agent-yaml\ndescription: \"Walk every field in `harbor.yaml` — REQUIRED (identity + llm), COMMON (planner \u002F memory \u002F state \u002F tools \u002F skills \u002F governance), ADVANCED (server \u002F telemetry \u002F artifacts \u002F events \u002F sessions \u002F tasks \u002F distributed). Use when editing the agent config beyond the scaffolded defaults.\"\nlicense: Apache-2.0\nmetadata:\n  framework: harbor\n  surface: agent-yaml\n  verbs: \"validate\"\n---\n\n# Define the agent yaml\n\n`harbor.yaml` is the single declarative file Harbor's runtime reads at boot. It's tiered by importance — REQUIRED at the top (the binary won't boot without it), then COMMON (the knobs you'll edit most), then ADVANCED (every other lever). Every absent key gets a documented default; the only fields you MUST set are `identity` + `llm`.\n\nPair this skill with `harbor validate .\u002Fharbor.yaml` — the validator is the loudest, most file:line-precise feedback you'll get on a yaml mistake. Run it after every edit.\n\n## REQUIRED — identity + llm\n\n### `identity`\n\nThe identity block configures JWT verification — the Runtime's authentication boundary. Every Protocol call carries a JWT; identity decides what algorithm to trust and where to fetch the public key.\n\n```yaml\nidentity:\n  jwt_algorithms: [RS256]                      # allowlist: RS256\u002FRS384\u002FRS512\u002FES256\u002FES384\u002FES512\n  issuer: https:\u002F\u002Fissuer.example.com           # exact match against the JWT `iss` claim\n  audience: my-agent                           # exact match against the JWT `aud` claim\n  jwks_url: https:\u002F\u002Fissuer.example.com\u002F.well-known\u002Fjwks.json\n  jwks_max_stale: 1h                           # OPTIONAL — max age a cached JWKS snapshot is honored without a refresh (0\u002Fomit = 1h default)\n```\n\nFor local dev, the scaffold drops placeholders — these pass `harbor validate` but reject any real token. `harbor dev` mints its own ephemeral signing key and bypasses the issuer\u002Fjwks_url path entirely (see [`run-the-dev-loop`](..\u002Frun-the-dev-loop\u002FSKILL.md)). For production, point `issuer` + `jwks_url` at your real IdP. HS256 \u002F `none` are forbidden — the loader rejects them at boot. `jwks_max_stale` bounds how long the verifier keeps trusting a cached signing key when your IdP is unreachable: past this age it fails closed (rejects tokens) rather than serving a key your IdP may have revoked. Omit it (or set `0`) for the safe 1h default; a negative or below-1m value is rejected at boot. There is no way to disable the ceiling — it tunes, it does not remove. Pair a tight ceiling with overlapping IdP signing keys and short token TTLs.\n\n### `llm`\n\nPick exactly one provider block from the scaffolded examples. Bifrost (Harbor's LLM driver) speaks many providers under one wire surface; you swap providers by swapping the block, not by changing code.\n\n```yaml\nllm:\n  driver: bifrost                              # only driver shipped in V1.1\n  provider: openrouter\n  model: anthropic\u002Fclaude-haiku-4.5\n  api_key: env.OPENROUTER_API_KEY              # `env.NAME` resolves via os.Getenv\n  timeout: 60s\n  model_profiles:                              # effectively REQUIRED — one entry per model you use\n    anthropic\u002Fclaude-haiku-4.5:\n      context_window_tokens: 200000            # the runtime uses this for context-window budgeting\n```\n\n`model_profiles.\u003Cllm.model>.context_window_tokens` is what the runtime consults for context-window budgeting. There is no silent fallback: a model with no matching `model_profiles` entry hard-fails the FIRST LLM call with `ErrUnsupportedModel` (fail-loudly — the error names the missing `model_profiles[\u003Cmodel>]` key). Set a profile for every model you reference. See [`wire-the-llm-provider`](..\u002Fwire-the-llm-provider\u002FSKILL.md).\n\n## COMMON — planner, memory, state, tools, skills, governance\n\n### `planner`\n\nV1.1 ships one planner: `react`. The block tunes its budget and gives the planner extra domain guidance.\n\n```yaml\nplanner:\n  max_steps: 12                                # planner step tranche: steps per cycle before the run is\n                                               # parked for continuation — a typed constraints_conflict pause\n                                               # (cause max_steps_exceeded), never forced finalisation;\n                                               # 0 (default) = driver default (12)\n  extra_guidance: |\n    Voice\u002Ftone rules. Hard negatives. Safety notes.\n    Operator-supplied; injected into the planner's system prompt.\n  reasoning_replay: never                      # or `text` to round-trip the trace into the next turn\n```\n\n`max_steps` is a **continuable tranche**, not a termination knob. When a tranche of planner steps is consumed without a terminal Finish, the run is **parked** through the unified pause primitive — a typed `constraints_conflict` pause carrying `{cause: max_steps_exceeded, max_steps, steps_observed}` — instead of being forced to finalise. An authorised RESUME continues the SAME run with a fresh tranche (the tranche counter resets; the cumulative trajectory is untouched), so long-running work spans repeated cycles as ONE run (D-418); a fresh process cannot resume a parked run and answers the typed `ErrRestartUnavailable` (D-417). Zero (the default) resolves to the driver default (12) and never means unbounded; the planner-side per-tranche breaker ends the cycle with the typed `NoPath` Finish (`max_steps_exceeded`), and the runtime's outer `ErrMaxStepsExceeded` guard (default 64) remains the runaway backstop when tranche pausing is unavailable. See `docs\u002FCONFIG.md` › `planner.max_steps`.\n\nThe default ReAct prompt already tells the agent to respect developer\u002Foperator\nscope, prohibitions, approvals, and output rules supplied through `extra_guidance`.\nDefine the actual domain rules here; do not rely on an agent name to imply them.\nIt also requests brief progress prose alongside tool calls during multi-step work,\nnot private reasoning. For a silent\u002FJSON-only consumer, explicitly suppress\nprogress prose in trusted guidance. A custom base prompt replaces these defaults.\nPrompt instructions do not replace runtime permissions, tool restrictions, or\napprovals. See [`planner.extra_guidance`](..\u002F..\u002FCONFIG.md#plannerextra_guidance)\nfor the trust tiers, replacement behavior, and validation limits.\n\n### `memory`\n\nMulti-turn execution context. The default is cumulative `rolling_summary`;\nchoose `none` explicitly for stateless agents. All adapters share the execution\nowner, and the `state` configuration below determines durability.\n\n```yaml\nmemory:\n  driver: inmem                                # administrative adapter; persistence uses state\n  strategy: rolling_summary                    # or explicit `none`\n  recent_turns: 20                              # detailed tail, not checkpoint history\n  budget_tokens: 8000                          # working-input target, NOT an output limit\n```\n\nThe working-input compaction target is configured with `memory.budget_tokens`; the removed\n`planner.token_budget` is rejected, not silently translated. With\n`rolling_summary`, zero derives the target from the effective model's input\ncapacity and output reservation. A positive target also enables within-run\ncompaction for stateless agents. Fresh results remain protected, so this is a\nsoft working target, not permission to truncate evidence to fit.\n\nSeparately, `memory.summarizer.max_tokens` sets the compaction call's completion\nallowance (including provider reasoning), not the driving model's output limit.\nOmitted\u002Fzero preserves 2048; a positive deployment-specific value remains subject\nto governed model capacity. YAML or `HARBOR_MEMORY_SUMMARIZER_MAX_TOKENS` changes\nrequire a restart. See [the reference](..\u002F..\u002FCONFIG.md#memorysummarizermax_tokens).\n\n`memory.summarizer.max_calls` separately limits chronological calls per compaction\n(zero\u002Fomitted: 16); `HARBOR_MEMORY_SUMMARIZER_MAX_CALLS` is its environment override.\nIt is restart-required and never authorizes extra tool work or a partial summary.\nIncreasing it can increase time and spend. `recent_turns` remains configurable\nwith a default of 20 and no hardcoded 32-turn maximum. See\n[the maintenance allowance](..\u002F..\u002FCONFIG.md#memorysummarizermax_calls).\n\nOn the PR #779 cumulative-memory branch, `rolling_summary` also enables the\nshared served\u002Fembedded execution-context path. `recent_turns: 20` (or zero)\nbounds detailed history, not checkpoint age. The separate\n`sessions.retained_context_turns` and SDK activation option are removed.\nOmitted settings and newly scaffolded agents select this behavior. The old\npair-summary engine is removed; `truncation` and `memory.recovery_backlog_max`\nare rejected rather than enabling a second pipeline.\n\nThe WAL trap: `dsn: .\u002F...` inside the project directory triggers `harbor dev`'s fsnotify watcher and reboots the runtime in a loop. Default-drop the DSN at `\u002Ftmp\u002Fharbor-validation\u002Fmy-agent-memory.sqlite` or `~\u002F.harbor\u002Fmy-agent-memory.sqlite`. See [`run-the-dev-loop`](..\u002Frun-the-dev-loop\u002FSKILL.md) §3.\n\n### `state`\n\nDurable run\u002Ftask\u002Fsession state. The default `inmem` driver is process-local — runs disappear on restart. Flip to SQLite for single-node persistence, Postgres for multi-replica.\n\n```yaml\nstate:\n  driver: sqlite\n  dsn: \u002Ftmp\u002Fharbor-validation\u002Fmy-agent-state.sqlite   # WAL trap caveat applies\n```\n\n### `configuration_state` (optional)\n\nUse this when agent settings must survive restart but conversations must not.\nOmitting it keeps the existing shared `state` behavior. It accepts the same\n`driver`, secret `dsn` and PostgreSQL `migration_mode` as `state`; environment\noverrides are `HARBOR_CONFIGURATION_STATE_DRIVER`,\n`HARBOR_CONFIGURATION_STATE_DSN` and\n`HARBOR_CONFIGURATION_STATE_MIGRATION_MODE`.\n\nKeep `state.driver: inmem` and the other conversation stores ephemeral, then\nselect a persistent `configuration_state` driver. Agent revisions, lifecycle,\nconfiguration journals and explicitly saved session settings use that store;\nmessages, summaries and tool history do not. Do not claim that this disables\nindependently configured durable events, artifacts or external memory tools.\nApply PostgreSQL migrations on a direct endpoint before using `verify` with a\ntransaction pool. Switching stores requires an explicit configuration restore;\nthere is no automatic copying or recovery of lost in-memory settings.\n\n### `tools`\n\nThree sources: `built_in` (tools shipped in the harbor binary; opt-in by name), `mcp_servers` (MCP southbound subprocesses Harbor spawns at boot), and `http_manifests` (UTCP-style YAML manifests describing HTTP endpoints as tools, loaded at boot — see `docs\u002FCONFIG.md` › `tools.http_manifests`; `tools.entries[]` OAuth\u002Fapproval\u002Floading bindings apply to manifest tools by name like any other).\n\n```yaml\ntools:\n  built_in:\n    - clock.now\n    - text.echo\n  mcp_servers:\n    - name: weather\n      transport_mode: stdio                           # auto \u002F sse \u002F streamable_http \u002F stdio\n      command: [uvx, mcp-weather]                      # argv form; required for stdio\n      headers: { Authorization: \"Bearer ${env.WEATHER_TOKEN}\" }   # HTTP transports; redacted as secrets\n      keep_alive: 30s                                  # session-ping interval; 0 disables\n      policy:                                          # optional per-server tool reliability defaults\n        timeout_ms: 60000                              # per-attempt deadline (default 30000)\n        max_attempts: 4                                # total attempts incl. the first\n```\n\nThe planner discovers every MCP server's tools at boot — there's no per-server enable flag; listing the server registers its tools. Built-in tools live in the harbor binary — list `clock.now` to enable, omit to disable. MCP servers are external processes; see [`configure-memory-and-skills`](..\u002Fconfigure-memory-and-skills\u002FSKILL.md) for the skill-vs-tool axis.\n\n> **Southbound OAuth binding — the credential-sink allow-list is mandatory (D-300).** When an `mcp_servers[]` connection sets `oauth_provider: \u003Cname>` (a per-identity bearer injected per call), the named `tools.oauth_providers[]` entry MUST declare a non-empty `allowed_downstream_hosts` that lists the connection's host — the credential-plane invariant is that no admin-writable field determines where a credential is sent, so the sink set is boot-pinned. A bound provider with no allow-list, or a connection host that isn't listed, fails at **boot** (not at first call). See `docs\u002FCONFIG.md` › `tools.oauth_providers` and `tools.oauth_credential_brokers`.\n>\n> **Per-user credential injection for receiver-style servers (D-341).** A server that expects its credential handed to it DIRECTLY on each request — an arbitrary header, an `Authorization: Basic` value, or a `_meta` key — instead of pulling it via RFC 8693 uses an `mcp_servers[]` `injection:` mapping instead of `oauth_provider`. The runtime SOURCES the acting user's credential from the named broker per call (the SAME per-user broker-pull as `oauth_provider` — never held, never client-pushed) and INJECTS it in the declared, **non-secret** form: `provider` (a declared `tools.oauth_providers[]` broker) + `form: header|basic|meta` + the target key (`header:` \u002F `basic_username:` \u002F `meta_key:`). Only the pulled value is secret. It is **mutually exclusive** with `oauth_provider` \u002F `tool_oauth_providers` \u002F a static `Authorization` header (one auth mode per connection), the broker's `allowed_downstream_hosts` must list the connection host (fail-closed), and the target header \u002F `_meta` leaf key MUST be a redaction-covered credential key (a `-api-key` \u002F `-token` \u002F `-secret`-shaped segment) so the audit redactor always holds the injected value to `***`. A broker error fails the call loud (never an unauthenticated send). See `examples\u002Fharbor.yaml` › `tools.mcp_servers[].injection`.\n>\n> **`_meta` keys are PATHS, and two rules now fail at BOOT (D-362).** A dotted key nests: `injection.meta_key: vendor.api_key` writes `_meta.vendor.api_key`, and — as of v1.24 — a dotted `meta_annotations` key does the same instead of landing as one literal flat key. One `_meta` namespace, one meaning, whichever mechanism wrote into it. **A `harbor.yaml` that validated before can now fail to start**, because two constraints that previously existed only on the `agent_config.add_mcp_connection` wire path now apply at boot as well:\n>\n> - **A 16-segment depth cap on any declared `_meta` path**, `injection.meta_key` included. A boot-declared path deeper than the cap used to be accepted where the identical wire-declared one was refused; both now consult one constant. No shipped config nests past two segments.\n> - **No two declared `_meta` paths on one connection may collide** — be equal, or be a prefix of one another — across `meta_annotations` keys AND `injection.meta_key`. So `{vendor: x, vendor.id: y}` is refused, and so is a flat `vendor` annotation alongside `injection.meta_key: vendor.api_key`. That second shape previously discarded the operator's annotation silently at merge time and made the merged `_meta` depend on map iteration order.\n>\n> Also newly refused: a key whose whole value **or any dot-segment** is reserved (`tenant.foo` now fails; the whole-key check is retained, because it is the arm that sees the spec-reserved `io.modelcontextprotocol\u002F` namespace), and a path with an empty segment (`a..b`). Run `harbor validate` against your config before upgrading. See `docs\u002FCONFIG.md` › `tools.mcp_servers[].meta_annotations`.\n>\n> **Handing an MCP tool a large document by reference (D-359).** A remote tool that must READ something large — a stored CSV, an uploaded PDF, a prior tool's materialised result — should not be given it through the model's context. Declare the connection byte-eligible and map the parameters that carry artifact bytes:\n>\n> ```yaml\n> tools:\n>   mcp_servers:\n>     - name: docstore\n>       transport_mode: streamable_http\n>       url: https:\u002F\u002Fdocs.internal.example.com\u002Fmcp\n>       artifact_byte_eligible: true\n>       artifact_params:\n>         ingest_document: [content]     # server-side tool name -> parameter names\n> ```\n>\n> The model writes an artifact **id**; the runtime resolves it under the run's own `(tenant, user, session)` and writes the resolved bytes into the outbound call as RFC 4648 §4 standard base64. `artifact_params` REQUIRES `artifact_byte_eligible` (a mapping without it is refused, never silently ignored — the flag IS the containment boundary), both are **http-only** (refused on `stdio`, explicit or auto-selected from a command-only config), and each mapped parameter must be DECLARED and declared **string-typed** in the server's own discovered `inputSchema` — an absent or non-string parameter fails the attach loudly rather than the first call silently. One substituted value is bounded by `tools.mcp_artifact_egress_max_bytes` (default 8 MiB); an oversize artifact **fails loud rather than truncating**, because a half-delivered document is a corruption, not a bounded read. Every substitution emits `mcp.artifact_egressed` — ids, sizes and a `sha256:` digest, never the bytes — **fail-closed before the wire request**, so a substitution that could not be recorded does not happen. An optional mapped slot (a trailing `?`) is skipped when absent, `null`, or empty \u002F whitespace-only; a non-empty value still follows the strict resolver path. Two things to weigh before enabling 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 (no run, so no seated resolver — the call fails loud). It widens which SERVERS may receive a user's content, never which artifacts a run can reach. See `docs\u002FCONFIG.md` › `tools.mcp_servers[].artifact_byte_eligible` and `tools.mcp_artifact_egress_max_bytes`.\n\nFor long research runs, also list the session artifact helpers next to `artifact_fetch`: `artifact_search` (grep inside a stored text result), `artifact_list` (page and filter the session's artifacts, including earlier large tool results) and `artifact_note` (keep a short note on one; needs the event bus, which every assembled runtime has).\n\n`runtime.run_limits.{max_duration, max_tokens}` bounds every run (both optional; unset means no limit). Reaching a limit ends the run with one tool-free final answer and finish reason `limit_reached`, never a failure. A per-agent agent-config `run_limits` section replaces it and `start.run_limits` can only tighten it — see [`use-the-harbor-protocol`](..\u002Fuse-the-harbor-protocol\u002FSKILL.md#run-limits).\n\n`runtime.hooks.run_completion.{tool, timeout}` names a catalog tool that receives every run's transcript at completion — see `docs\u002FCONFIG.md` › Runtime. `runtime.naming.{auto, after_turns, repeat_every, max_repetitions, max_title_len, model}` is the opt-in, default-off **session auto-naming** fleet default: with it enabled, the runtime titles a session itself at each run's terminal boundary via one governed LLM call over a bounded transcript digest (`max_repetitions` is required `>= 1` whenever `repeat_every > 0` — no unlimited value). A per-agent agent-config `naming` section overrides this default; see `docs\u002FCONFIG.md` › Runtime.\n\n### `skills`\n\nSkills are token-savvy DB-backed playbooks the planner searches by name. Distinct from \"operator skills\" (the docs\u002Fskills\u002F directory you're reading right now) — these are *runtime* skills the planner consults during a reasoning turn.\n\n```yaml\nskills:\n  driver: localdb\n  dsn: .\u002Fmy-agent-skills.sqlite                # WAL trap caveat applies\n  directory:                                   # optional — the per-turn \u003Cskills_context> browse window\n    pinned: [triage-incident]                  # anchored first, declaration order\n    max_entries: 10                            # 0\u002Funset → planner.skills_context_max (default 5)\n    selection: pinned_then_recent              # the one wired value (pinned_then_top is rejected: not yet wired)\n```\n\nIngest skills with `harbor skill import \u003Cpath>` and remove them with `harbor skill rm \u003Cname>` — both operate on this block's store.\n\n> **Boot-declared agent skill packs (HA-66, v1.28).** `skills.boot_agent_packs`\n> loads node-local operator skills for the resolved boot\u002Fdefault agent at\n> boot. It REQUIRES a configured `skills.driver` + `skills.dsn` — a\n> declaration on an unconfigured skills block fails boot loud. Each entry\n> binds EXACTLY ONE `(tenant_id, agent_id)`: an exact tenant key and the\n> runtime-resolved boot agent (no wildcards, no tenant-wide application;\n> honored only when the effective agent resolves to the declared\n> `agent_id`). `directory` is the pack root, resolved **relative to the\n> config file's directory — never the process CWD**; each `include` entry is\n> one package directory containing exactly one case-sensitive top-level\n> regular UTF-8 `SKILL.md`, and the v1.28 contract is resource-free (no\n> auxiliary resource payloads ride alongside the skill body). Loading is\n> strict, eager, and immutable **before readiness**: symlinks \u002F hardlinks \u002F\n> special files \u002F traversal \u002F duplicates are rejected, the loaded set is\n> fixed for the process lifetime, and file changes take effect only on a\n> restart \u002F new runtime — never hot-reloaded. Boot packs stay node-local:\n> each node reloads them from its own files at boot, so a change on one node\n> never converges the others even over a shared Postgres skill store.\n> Boot-pack items compose with the agent's durable revision into ONE\n> operator tier (same canonical name + same content hash dedupes; differing\n> hashes fail loud; combined count capped at 256). Headless `RunOnce`\n> against a boot-pack agent is unsupported and fails loud. Full contract:\n> `docs\u002FCONFIG.md` › `skills.boot_agent_packs`.\n\n### `governance`\n\nPer-identity cost ceilings + rate limits + max-token caps, keyed by tier.\n\n> **Declared tiers are enforced.** A populated `identity_tiers` block\n> composes the enforcement subsystem at boot: the budget ceiling fails\n> over-budget calls with `ErrBudgetExceeded`, the token bucket with\n> `ErrRateLimited`, and the per-call cap with `ErrMaxTokensExceeded` — each\n> emitting a matching `governance.*` event you can watch on the events\n> stream. The same block drives the read-only `governance.posture` Protocol\n> surface.\n\n```yaml\ngovernance:\n  default_tier: free\n  identity_tiers:\n    free:\n      budget_ceiling_usd: 5.00                 # enforced cap per (tenant, user, session)\n      max_tokens: 4096                         # per-call MaxTokens cap\n      rate_limit:                              # token bucket per (identity, model)\n        capacity: 100000\n        refill_tokens: 50000\n        refill_interval: 1h\n```\n\nEmpty `identity_tiers: {}` = fully latent (the default).\n\n## ADVANCED — every other lever\n\nThe scaffold drops a commented summary of advanced defaults. The full reference is `docs\u002FCONFIG.md`. The blocks you most often touch:\n\n- **`server`**: `bind_addr` (default `127.0.0.1:8080` for `harbor serve`; `harbor dev` always binds `:18080`), `allowed_origins` (CORS allowlist for multi-process Console), `shutdown_grace_period` (drain timeout for hot reload).\n- **`telemetry`**: `log_format` (`json` \u002F `text`), `log_level` (`debug` \u002F `info` \u002F `warn` \u002F `error`), `service_name` (OTel resource).\n- **`observability`**: `rollups.{driver,dsn}` (HA-65) wires the durable observability rollup projection — empty block = unwired; `driver` `inmem` \u002F `sqlite` \u002F `postgres`, `dsn` required for `sqlite` \u002F `postgres`; restart-required.\n- **`artifacts`**: `driver` (`inmem` \u002F `fs` \u002F `sqlite` \u002F `postgres`), `heavy_output_threshold_bytes` (the LLM-edge context-leak guard, default 131072 \u002F 128 KiB — see RFC §6.5). It bounds what may enter a model's context window only; Console-facing Protocol replies (`pause.list`, `memory.get`\u002F`list`, the flow catalog, the `mcp.apps.*` reads) select inline-versus-reference at a pinned 32 KiB bound that does not track this key (D-358).\n- **`events`**: `driver` (`inmem` \u002F `durable`); events power the Console's live streaming. Durable persistence is NOT selected on `driver` — set `driver: durable` and then pick the backing store with `state_driver` (`sqlite` \u002F `postgres`) + `state_dsn`. With `driver: durable` and an empty `state_driver` the bus loudly degrades to best-effort in-memory (not durable across restart).\n- **`sessions`**: `idle_ttl` (default 24h), `hard_cap` (default 720h \u002F 30d), `sweep_interval`; `turns.{driver,dsn,retention}` (HA-64) wires the durable conversation-turn projection behind `sessions.turns.list` \u002F `.get` — empty block = unwired (the routes answer 501); `driver` `inmem` \u002F `sqlite` \u002F `postgres`, `dsn` required for `sqlite` \u002F `postgres`, `retention` 0 → the projection's documented default; restart-required.\n- **Postgres migration mode**: every Postgres-backed store block (`state`, `memory`, `artifacts`, `skills`, `sessions.turns`, `observability.rollups`) accepts `migration_mode: apply | verify`. Empty defaults to `apply`, which takes a session advisory lock and therefore uses a direct\u002Fsession-capable endpoint. After migrations have been applied separately, set the pooled DSN and `migration_mode: verify`; startup then reads the subsystem's namespaced `harbor_schema_migrations` and `harbor_store_identity` plus required physical schema, performs no DDL\u002Ftransaction\u002Fadvisory lock, and fails loud when identity, checksums, schema, or an embedded migration is missing or stale. Never point `apply` at a transaction pool.\n- **`pauseresume`**: `max_park_duration` (ceiling on how long a pause — HITL approval, tool OAuth — may stay parked before the runtime resumes it with the typed `timeout` decision and the run ends as a constraints-conflict; default `0` = never expire), `sweep_interval` (sweeper cadence, default 1m).\n- **`tasks`**: `driver` (`inprocess` or `durable`). `inprocess` (default) keeps task\u002Fgroup\u002Fpatch state in memory — a restart starts empty. `durable` persists those records through the `StateStore` so they survive a restart; on open it replays them and recovers any task left `running` by a crash to `failed` (code `runtime_restarted`). It reuses the runtime `StateStore`, so pair it with a durable `state.driver` (`sqlite` \u002F `postgres`) for cross-process survival; selecting `durable` with no store wired fails loudly at boot.\n- **`distributed`**: `bus_driver` (`loopback` or `durable`) + `remote_driver` (`loopback` only in V1.1; A2A wire is post-V1). `loopback` is in-process; `durable` persists every `BusEnvelope` through the `StateStore` and projects it onto the local event bus, with a poller for cross-instance fan-out + restart-replay (StateStore-backed — Postgres-as-queue on a shared Postgres store; tune with `bus_poll_interval`). NATS \u002F Redis Streams remain future drivers.\n\nObserved retention horizons are inspection data, not configured retention\npromises. `runtime.health` reads only the cached runtime-wide events horizon\nfor every caller. Inspect events, tasks and sessions together through the\nexplicit, audited `runtime.retention` call with verified `admin` authority;\n`console:fleet` and trust-mode callers cannot use it (D-490).\n\n## Validation — the loud loop\n\n```bash\nharbor validate .\u002Fharbor.yaml\n```\n\nFailure modes the validator catches:\n\n- **Required field missing** — `llm.driver`, `llm.provider`, `llm.model`, `identity.issuer`, etc.\n- **Type mismatches** — `memory.budget_tokens: \"8000\"` (string instead of int).\n- **Enum violations** — `memory.strategy: \"summary\"` (not one of `none` \u002F `rolling_summary`).\n- **Bound violations** — `governance.identity_tiers.free.budget_ceiling_usd: -1` (negative).\n- **Cross-field constraints** — `memory.driver: sqlite` without `memory.dsn`.\n\nEvery error carries the `file:line` of the offending key. Fix one, re-run, repeat until clean.\n\n## Common failure modes\n\n- **`harbor validate` says `unknown field \"X\"`.** Either a typo (check indentation — YAML is whitespace-sensitive) or the field belongs in a different block. Check `docs\u002FCONFIG.md` for the canonical block.\n- **`harbor dev` boots but every Protocol call returns 401.** Your `identity` block points at a real IdP but the JWKS isn't reachable. For local dev, use the dev-token flow (see [`run-the-dev-loop`](..\u002Frun-the-dev-loop\u002FSKILL.md)) — the issuer\u002Fjwks_url path is for production.\n- **`harbor dev` reboots in an infinite loop.** SQLite WAL trap — `dsn:` inside the project directory. Move it outside.\n- **A model swap fails the first call with `ErrUnsupportedModel`.** You forgot to add a `model_profiles.\u003Cmodel>.context_window_tokens` entry for the new model. There's no silent fallback — add the profile and the call succeeds.\n\n## See also\n\n- [`scaffold-a-harbor-agent`](..\u002Fscaffold-a-harbor-agent\u002FSKILL.md) — drops the tiered yaml in the first place.\n- [`wire-the-llm-provider`](..\u002Fwire-the-llm-provider\u002FSKILL.md) — the full provider matrix + the mock vs real posture.\n- [`configure-memory-and-skills`](..\u002Fconfigure-memory-and-skills\u002FSKILL.md) — the memory strategies + runtime skill catalog in depth.\n- [`validate-and-package`](..\u002Fvalidate-and-package\u002FSKILL.md) — preflight before shipping.\n- The full per-key reference: `docs\u002FCONFIG.md`.\n\nRemote tool brokers now default to verified tenant credential selection. Upgrade the\ncoordinator to the scoped response contract before deploying. An intentionally\ndeployment-wide legacy broker must explicitly declare `credential_scope: deployment`;\nsigned capability providers always remain tenant scoped. See `docs\u002FCONFIG.md`,\n“Tenant-scoped broker credential pulls”, for the request, response and migration.\n","# Define the agent yaml\n\n`harbor.yaml` is the single declarative file Harbor's runtime reads at boot. It's tiered by importance — REQUIRED at the top (the binary won't boot without it), then COMMON (the knobs you'll edit most), then ADVANCED (every other lever). Every absent key gets a documented default; the only fields you MUST set are `identity` + `llm`.\n\nPair this skill with `harbor validate .\u002Fharbor.yaml` — the validator is the loudest, most file:line-precise feedback you'll get on a yaml mistake. Run it after every edit.\n\n## REQUIRED — identity + llm\n\n### `identity`\n\nThe identity block configures JWT verification — the Runtime's authentication boundary. Every Protocol call carries a JWT; identity decides what algorithm to trust and where to fetch the public key.\n\n```yaml\nidentity:\n  jwt_algorithms: [RS256]                      # allowlist: RS256\u002FRS384\u002FRS512\u002FES256\u002FES384\u002FES512\n  issuer: https:\u002F\u002Fissuer.example.com           # exact match against the JWT `iss` claim\n  audience: my-agent                           # exact match against the JWT `aud` claim\n  jwks_url: https:\u002F\u002Fissuer.example.com\u002F.well-known\u002Fjwks.json\n  jwks_max_stale: 1h                           # OPTIONAL — max age a cached JWKS snapshot is honored without a refresh (0\u002Fomit = 1h default)\n```\n\nFor local dev, the scaffold drops placeholders — these pass `harbor validate` but reject any real token. `harbor dev` mints its own ephemeral signing key and bypasses the issuer\u002Fjwks_url path entirely (see [`run-the-dev-loop`](..\u002Frun-the-dev-loop\u002FSKILL.md)). For production, point `issuer` + `jwks_url` at your real IdP. HS256 \u002F `none` are forbidden — the loader rejects them at boot. `jwks_max_stale` bounds how long the verifier keeps trusting a cached signing key when your IdP is unreachable: past this age it fails closed (rejects tokens) rather than serving a key your IdP may have revoked. Omit it (or set `0`) for the safe 1h default; a negative or below-1m value is rejected at boot. There is no way to disable the ceiling — it tunes, it does not remove. Pair a tight ceiling with overlapping IdP signing keys and short token TTLs.\n\n### `llm`\n\nPick exactly one provider block from the scaffolded examples. Bifrost (Harbor's LLM driver) speaks many providers under one wire surface; you swap providers by swapping the block, not by changing code.\n\n```yaml\nllm:\n  driver: bifrost                              # only driver shipped in V1.1\n  provider: openrouter\n  model: anthropic\u002Fclaude-haiku-4.5\n  api_key: env.OPENROUTER_API_KEY              # `env.NAME` resolves via os.Getenv\n  timeout: 60s\n  model_profiles:                              # effectively REQUIRED — one entry per model you use\n    anthropic\u002Fclaude-haiku-4.5:\n      context_window_tokens: 200000            # the runtime uses this for context-window budgeting\n```\n\n`model_profiles.\u003Cllm.model>.context_window_tokens` is what the runtime consults for context-window budgeting. There is no silent fallback: a model with no matching `model_profiles` entry hard-fails the FIRST LLM call with `ErrUnsupportedModel` (fail-loudly — the error names the missing `model_profiles[\u003Cmodel>]` key). Set a profile for every model you reference. See [`wire-the-llm-provider`](..\u002Fwire-the-llm-provider\u002FSKILL.md).\n\n## COMMON — planner, memory, state, tools, skills, governance\n\n### `planner`\n\nV1.1 ships one planner: `react`. The block tunes its budget and gives the planner extra domain guidance.\n\n```yaml\nplanner:\n  max_steps: 12                                # planner step tranche: steps per cycle before the run is\n                                               # parked for continuation — a typed constraints_conflict pause\n                                               # (cause max_steps_exceeded), never forced finalisation;\n                                               # 0 (default) = driver default (12)\n  extra_guidance: |\n    Voice\u002Ftone rules. Hard negatives. Safety notes.\n    Operator-supplied; injected into the planner's system prompt.\n  reasoning_replay: never                      # or `text` to round-trip the trace into the next turn\n```\n\n`max_steps` is a **continuable tranche**, not a termination knob. When a tranche of planner steps is consumed without a terminal Finish, the run is **parked** through the unified pause primitive — a typed `constraints_conflict` pause carrying `{cause: max_steps_exceeded, max_steps, steps_observed}` — instead of being forced to finalise. An authorised RESUME continues the SAME run with a fresh tranche (the tranche counter resets; the cumulative trajectory is untouched), so long-running work spans repeated cycles as ONE run (D-418); a fresh process cannot resume a parked run and answers the typed `ErrRestartUnavailable` (D-417). Zero (the default) resolves to the driver default (12) and never means unbounded; the planner-side per-tranche breaker ends the cycle with the typed `NoPath` Finish (`max_steps_exceeded`), and the runtime's outer `ErrMaxStepsExceeded` guard (default 64) remains the runaway backstop when tranche pausing is unavailable. See `docs\u002FCONFIG.md` › `planner.max_steps`.\n\nThe default ReAct prompt already tells the agent to respect developer\u002Foperator\nscope, prohibitions, approvals, and output rules supplied through `extra_guidance`.\nDefine the actual domain rules here; do not rely on an agent name to imply them.\nIt also requests brief progress prose alongside tool calls during multi-step work,\nnot private reasoning. For a silent\u002FJSON-only consumer, explicitly suppress\nprogress prose in trusted guidance. A custom base prompt replaces these defaults.\nPrompt instructions do not replace runtime permissions, tool restrictions, or\napprovals. See [`planner.extra_guidance`](..\u002F..\u002FCONFIG.md#plannerextra_guidance)\nfor the trust tiers, replacement behavior, and validation limits.\n\n### `memory`\n\nMulti-turn execution context. The default is cumulative `rolling_summary`;\nchoose `none` explicitly for stateless agents. All adapters share the execution\nowner, and the `state` configuration below determines durability.\n\n```yaml\nmemory:\n  driver: inmem                                # administrative adapter; persistence uses state\n  strategy: rolling_summary                    # or explicit `none`\n  recent_turns: 20                              # detailed tail, not checkpoint history\n  budget_tokens: 8000                          # working-input target, NOT an output limit\n```\n\nThe working-input compaction target is configured with `memory.budget_tokens`; the removed\n`planner.token_budget` is rejected, not silently translated. With\n`rolling_summary`, zero derives the target from the effective model's input\ncapacity and output reservation. A positive target also enables within-run\ncompaction for stateless agents. Fresh results remain protected, so this is a\nsoft working target, not permission to truncate evidence to fit.\n\nSeparately, `memory.summarizer.max_tokens` sets the compaction call's completion\nallowance (including provider reasoning), not the driving model's output limit.\nOmitted\u002Fzero preserves 2048; a positive deployment-specific value remains subject\nto governed model capacity. YAML or `HARBOR_MEMORY_SUMMARIZER_MAX_TOKENS` changes\nrequire a restart. See [the reference](..\u002F..\u002FCONFIG.md#memorysummarizermax_tokens).\n\n`memory.summarizer.max_calls` separately limits chronological calls per compaction\n(zero\u002Fomitted: 16); `HARBOR_MEMORY_SUMMARIZER_MAX_CALLS` is its environment override.\nIt is restart-required and never authorizes extra tool work or a partial summary.\nIncreasing it can increase time and spend. `recent_turns` remains configurable\nwith a default of 20 and no hardcoded 32-turn maximum. See\n[the maintenance allowance](..\u002F..\u002FCONFIG.md#memorysummarizermax_calls).\n\nOn the PR #779 cumulative-memory branch, `rolling_summary` also enables the\nshared served\u002Fembedded execution-context path. `recent_turns: 20` (or zero)\nbounds detailed history, not checkpoint age. The separate\n`sessions.retained_context_turns` and SDK activation option are removed.\nOmitted settings and newly scaffolded agents select this behavior. The old\npair-summary engine is removed; `truncation` and `memory.recovery_backlog_max`\nare rejected rather than enabling a second pipeline.\n\nThe WAL trap: `dsn: .\u002F...` inside the project directory triggers `harbor dev`'s fsnotify watcher and reboots the runtime in a loop. Default-drop the DSN at `\u002Ftmp\u002Fharbor-validation\u002Fmy-agent-memory.sqlite` or `~\u002F.harbor\u002Fmy-agent-memory.sqlite`. See [`run-the-dev-loop`](..\u002Frun-the-dev-loop\u002FSKILL.md) §3.\n\n### `state`\n\nDurable run\u002Ftask\u002Fsession state. The default `inmem` driver is process-local — runs disappear on restart. Flip to SQLite for single-node persistence, Postgres for multi-replica.\n\n```yaml\nstate:\n  driver: sqlite\n  dsn: \u002Ftmp\u002Fharbor-validation\u002Fmy-agent-state.sqlite   # WAL trap caveat applies\n```\n\n### `configuration_state` (optional)\n\nUse this when agent settings must survive restart but conversations must not.\nOmitting it keeps the existing shared `state` behavior. It accepts the same\n`driver`, secret `dsn` and PostgreSQL `migration_mode` as `state`; environment\noverrides are `HARBOR_CONFIGURATION_STATE_DRIVER`,\n`HARBOR_CONFIGURATION_STATE_DSN` and\n`HARBOR_CONFIGURATION_STATE_MIGRATION_MODE`.\n\nKeep `state.driver: inmem` and the other conversation stores ephemeral, then\nselect a persistent `configuration_state` driver. Agent revisions, lifecycle,\nconfiguration journals and explicitly saved session settings use that store;\nmessages, summaries and tool history do not. Do not claim that this disables\nindependently configured durable events, artifacts or external memory tools.\nApply PostgreSQL migrations on a direct endpoint before using `verify` with a\ntransaction pool. Switching stores requires an explicit configuration restore;\nthere is no automatic copying or recovery of lost in-memory settings.\n\n### `tools`\n\nThree sources: `built_in` (tools shipped in the harbor binary; opt-in by name), `mcp_servers` (MCP southbound subprocesses Harbor spawns at boot), and `http_manifests` (UTCP-style YAML manifests describing HTTP endpoints as tools, loaded at boot — see `docs\u002FCONFIG.md` › `tools.http_manifests`; `tools.entries[]` OAuth\u002Fapproval\u002Floading bindings apply to manifest tools by name like any other).\n\n```yaml\ntools:\n  built_in:\n    - clock.now\n    - text.echo\n  mcp_servers:\n    - name: weather\n      transport_mode: stdio                           # auto \u002F sse \u002F streamable_http \u002F stdio\n      command: [uvx, mcp-weather]                      # argv form; required for stdio\n      headers: { Authorization: \"Bearer ${env.WEATHER_TOKEN}\" }   # HTTP transports; redacted as secrets\n      keep_alive: 30s                                  # session-ping interval; 0 disables\n      policy:                                          # optional per-server tool reliability defaults\n        timeout_ms: 60000                              # per-attempt deadline (default 30000)\n        max_attempts: 4                                # total attempts incl. the first\n```\n\nThe planner discovers every MCP server's tools at boot — there's no per-server enable flag; listing the server registers its tools. Built-in tools live in the harbor binary — list `clock.now` to enable, omit to disable. MCP servers are external processes; see [`configure-memory-and-skills`](..\u002Fconfigure-memory-and-skills\u002FSKILL.md) for the skill-vs-tool axis.\n\n> **Southbound OAuth binding — the credential-sink allow-list is mandatory (D-300).** When an `mcp_servers[]` connection sets `oauth_provider: \u003Cname>` (a per-identity bearer injected per call), the named `tools.oauth_providers[]` entry MUST declare a non-empty `allowed_downstream_hosts` that lists the connection's host — the credential-plane invariant is that no admin-writable field determines where a credential is sent, so the sink set is boot-pinned. A bound provider with no allow-list, or a connection host that isn't listed, fails at **boot** (not at first call). See `docs\u002FCONFIG.md` › `tools.oauth_providers` and `tools.oauth_credential_brokers`.\n>\n> **Per-user credential injection for receiver-style servers (D-341).** A server that expects its credential handed to it DIRECTLY on each request — an arbitrary header, an `Authorization: Basic` value, or a `_meta` key — instead of pulling it via RFC 8693 uses an `mcp_servers[]` `injection:` mapping instead of `oauth_provider`. The runtime SOURCES the acting user's credential from the named broker per call (the SAME per-user broker-pull as `oauth_provider` — never held, never client-pushed) and INJECTS it in the declared, **non-secret** form: `provider` (a declared `tools.oauth_providers[]` broker) + `form: header|basic|meta` + the target key (`header:` \u002F `basic_username:` \u002F `meta_key:`). Only the pulled value is secret. It is **mutually exclusive** with `oauth_provider` \u002F `tool_oauth_providers` \u002F a static `Authorization` header (one auth mode per connection), the broker's `allowed_downstream_hosts` must list the connection host (fail-closed), and the target header \u002F `_meta` leaf key MUST be a redaction-covered credential key (a `-api-key` \u002F `-token` \u002F `-secret`-shaped segment) so the audit redactor always holds the injected value to `***`. A broker error fails the call loud (never an unauthenticated send). See `examples\u002Fharbor.yaml` › `tools.mcp_servers[].injection`.\n>\n> **`_meta` keys are PATHS, and two rules now fail at BOOT (D-362).** A dotted key nests: `injection.meta_key: vendor.api_key` writes `_meta.vendor.api_key`, and — as of v1.24 — a dotted `meta_annotations` key does the same instead of landing as one literal flat key. One `_meta` namespace, one meaning, whichever mechanism wrote into it. **A `harbor.yaml` that validated before can now fail to start**, because two constraints that previously existed only on the `agent_config.add_mcp_connection` wire path now apply at boot as well:\n>\n> - **A 16-segment depth cap on any declared `_meta` path**, `injection.meta_key` included. A boot-declared path deeper than the cap used to be accepted where the identical wire-declared one was refused; both now consult one constant. No shipped config nests past two segments.\n> - **No two declared `_meta` paths on one connection may collide** — be equal, or be a prefix of one another — across `meta_annotations` keys AND `injection.meta_key`. So `{vendor: x, vendor.id: y}` is refused, and so is a flat `vendor` annotation alongside `injection.meta_key: vendor.api_key`. That second shape previously discarded the operator's annotation silently at merge time and made the merged `_meta` depend on map iteration order.\n>\n> Also newly refused: a key whose whole value **or any dot-segment** is reserved (`tenant.foo` now fails; the whole-key check is retained, because it is the arm that sees the spec-reserved `io.modelcontextprotocol\u002F` namespace), and a path with an empty segment (`a..b`). Run `harbor validate` against your config before upgrading. See `docs\u002FCONFIG.md` › `tools.mcp_servers[].meta_annotations`.\n>\n> **Handing an MCP tool a large document by reference (D-359).** A remote tool that must READ something large — a stored CSV, an uploaded PDF, a prior tool's materialised result — should not be given it through the model's context. Declare the connection byte-eligible and map the parameters that carry artifact bytes:\n>\n> ```yaml\n> tools:\n>   mcp_servers:\n>     - name: docstore\n>       transport_mode: streamable_http\n>       url: https:\u002F\u002Fdocs.internal.example.com\u002Fmcp\n>       artifact_byte_eligible: true\n>       artifact_params:\n>         ingest_document: [content]     # server-side tool name -> parameter names\n> ```\n>\n> The model writes an artifact **id**; the runtime resolves it under the run's own `(tenant, user, session)` and writes the resolved bytes into the outbound call as RFC 4648 §4 standard base64. `artifact_params` REQUIRES `artifact_byte_eligible` (a mapping without it is refused, never silently ignored — the flag IS the containment boundary), both are **http-only** (refused on `stdio`, explicit or auto-selected from a command-only config), and each mapped parameter must be DECLARED and declared **string-typed** in the server's own discovered `inputSchema` — an absent or non-string parameter fails the attach loudly rather than the first call silently. One substituted value is bounded by `tools.mcp_artifact_egress_max_bytes` (default 8 MiB); an oversize artifact **fails loud rather than truncating**, because a half-delivered document is a corruption, not a bounded read. Every substitution emits `mcp.artifact_egressed` — ids, sizes and a `sha256:` digest, never the bytes — **fail-closed before the wire request**, so a substitution that could not be recorded does not happen. An optional mapped slot (a trailing `?`) is skipped when absent, `null`, or empty \u002F whitespace-only; a non-empty value still follows the strict resolver path. Two things to weigh before enabling 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 (no run, so no seated resolver — the call fails loud). It widens which SERVERS may receive a user's content, never which artifacts a run can reach. See `docs\u002FCONFIG.md` › `tools.mcp_servers[].artifact_byte_eligible` and `tools.mcp_artifact_egress_max_bytes`.\n\nFor long research runs, also list the session artifact helpers next to `artifact_fetch`: `artifact_search` (grep inside a stored text result), `artifact_list` (page and filter the session's artifacts, including earlier large tool results) and `artifact_note` (keep a short note on one; needs the event bus, which every assembled runtime has).\n\n`runtime.run_limits.{max_duration, max_tokens}` bounds every run (both optional; unset means no limit). Reaching a limit ends the run with one tool-free final answer and finish reason `limit_reached`, never a failure. A per-agent agent-config `run_limits` section replaces it and `start.run_limits` can only tighten it — see [`use-the-harbor-protocol`](..\u002Fuse-the-harbor-protocol\u002FSKILL.md#run-limits).\n\n`runtime.hooks.run_completion.{tool, timeout}` names a catalog tool that receives every run's transcript at completion — see `docs\u002FCONFIG.md` › Runtime. `runtime.naming.{auto, after_turns, repeat_every, max_repetitions, max_title_len, model}` is the opt-in, default-off **session auto-naming** fleet default: with it enabled, the runtime titles a session itself at each run's terminal boundary via one governed LLM call over a bounded transcript digest (`max_repetitions` is required `>= 1` whenever `repeat_every > 0` — no unlimited value). A per-agent agent-config `naming` section overrides this default; see `docs\u002FCONFIG.md` › Runtime.\n\n### `skills`\n\nSkills are token-savvy DB-backed playbooks the planner searches by name. Distinct from \"operator skills\" (the docs\u002Fskills\u002F directory you're reading right now) — these are *runtime* skills the planner consults during a reasoning turn.\n\n```yaml\nskills:\n  driver: localdb\n  dsn: .\u002Fmy-agent-skills.sqlite                # WAL trap caveat applies\n  directory:                                   # optional — the per-turn \u003Cskills_context> browse window\n    pinned: [triage-incident]                  # anchored first, declaration order\n    max_entries: 10                            # 0\u002Funset → planner.skills_context_max (default 5)\n    selection: pinned_then_recent              # the one wired value (pinned_then_top is rejected: not yet wired)\n```\n\nIngest skills with `harbor skill import \u003Cpath>` and remove them with `harbor skill rm \u003Cname>` — both operate on this block's store.\n\n> **Boot-declared agent skill packs (HA-66, v1.28).** `skills.boot_agent_packs`\n> loads node-local operator skills for the resolved boot\u002Fdefault agent at\n> boot. It REQUIRES a configured `skills.driver` + `skills.dsn` — a\n> declaration on an unconfigured skills block fails boot loud. Each entry\n> binds EXACTLY ONE `(tenant_id, agent_id)`: an exact tenant key and the\n> runtime-resolved boot agent (no wildcards, no tenant-wide application;\n> honored only when the effective agent resolves to the declared\n> `agent_id`). `directory` is the pack root, resolved **relative to the\n> config file's directory — never the process CWD**; each `include` entry is\n> one package directory containing exactly one case-sensitive top-level\n> regular UTF-8 `SKILL.md`, and the v1.28 contract is resource-free (no\n> auxiliary resource payloads ride alongside the skill body). Loading is\n> strict, eager, and immutable **before readiness**: symlinks \u002F hardlinks \u002F\n> special files \u002F traversal \u002F duplicates are rejected, the loaded set is\n> fixed for the process lifetime, and file changes take effect only on a\n> restart \u002F new runtime — never hot-reloaded. Boot packs stay node-local:\n> each node reloads them from its own files at boot, so a change on one node\n> never converges the others even over a shared Postgres skill store.\n> Boot-pack items compose with the agent's durable revision into ONE\n> operator tier (same canonical name + same content hash dedupes; differing\n> hashes fail loud; combined count capped at 256). Headless `RunOnce`\n> against a boot-pack agent is unsupported and fails loud. Full contract:\n> `docs\u002FCONFIG.md` › `skills.boot_agent_packs`.\n\n### `governance`\n\nPer-identity cost ceilings + rate limits + max-token caps, keyed by tier.\n\n> **Declared tiers are enforced.** A populated `identity_tiers` block\n> composes the enforcement subsystem at boot: the budget ceiling fails\n> over-budget calls with `ErrBudgetExceeded`, the token bucket with\n> `ErrRateLimited`, and the per-call cap with `ErrMaxTokensExceeded` — each\n> emitting a matching `governance.*` event you can watch on the events\n> stream. The same block drives the read-only `governance.posture` Protocol\n> surface.\n\n```yaml\ngovernance:\n  default_tier: free\n  identity_tiers:\n    free:\n      budget_ceiling_usd: 5.00                 # enforced cap per (tenant, user, session)\n      max_tokens: 4096                         # per-call MaxTokens cap\n      rate_limit:                              # token bucket per (identity, model)\n        capacity: 100000\n        refill_tokens: 50000\n        refill_interval: 1h\n```\n\nEmpty `identity_tiers: {}` = fully latent (the default).\n\n## ADVANCED — every other lever\n\nThe scaffold drops a commented summary of advanced defaults. The full reference is `docs\u002FCONFIG.md`. The blocks you most often touch:\n\n- **`server`**: `bind_addr` (default `127.0.0.1:8080` for `harbor serve`; `harbor dev` always binds `:18080`), `allowed_origins` (CORS allowlist for multi-process Console), `shutdown_grace_period` (drain timeout for hot reload).\n- **`telemetry`**: `log_format` (`json` \u002F `text`), `log_level` (`debug` \u002F `info` \u002F `warn` \u002F `error`), `service_name` (OTel resource).\n- **`observability`**: `rollups.{driver,dsn}` (HA-65) wires the durable observability rollup projection — empty block = unwired; `driver` `inmem` \u002F `sqlite` \u002F `postgres`, `dsn` required for `sqlite` \u002F `postgres`; restart-required.\n- **`artifacts`**: `driver` (`inmem` \u002F `fs` \u002F `sqlite` \u002F `postgres`), `heavy_output_threshold_bytes` (the LLM-edge context-leak guard, default 131072 \u002F 128 KiB — see RFC §6.5). It bounds what may enter a model's context window only; Console-facing Protocol replies (`pause.list`, `memory.get`\u002F`list`, the flow catalog, the `mcp.apps.*` reads) select inline-versus-reference at a pinned 32 KiB bound that does not track this key (D-358).\n- **`events`**: `driver` (`inmem` \u002F `durable`); events power the Console's live streaming. Durable persistence is NOT selected on `driver` — set `driver: durable` and then pick the backing store with `state_driver` (`sqlite` \u002F `postgres`) + `state_dsn`. With `driver: durable` and an empty `state_driver` the bus loudly degrades to best-effort in-memory (not durable across restart).\n- **`sessions`**: `idle_ttl` (default 24h), `hard_cap` (default 720h \u002F 30d), `sweep_interval`; `turns.{driver,dsn,retention}` (HA-64) wires the durable conversation-turn projection behind `sessions.turns.list` \u002F `.get` — empty block = unwired (the routes answer 501); `driver` `inmem` \u002F `sqlite` \u002F `postgres`, `dsn` required for `sqlite` \u002F `postgres`, `retention` 0 → the projection's documented default; restart-required.\n- **Postgres migration mode**: every Postgres-backed store block (`state`, `memory`, `artifacts`, `skills`, `sessions.turns`, `observability.rollups`) accepts `migration_mode: apply | verify`. Empty defaults to `apply`, which takes a session advisory lock and therefore uses a direct\u002Fsession-capable endpoint. After migrations have been applied separately, set the pooled DSN and `migration_mode: verify`; startup then reads the subsystem's namespaced `harbor_schema_migrations` and `harbor_store_identity` plus required physical schema, performs no DDL\u002Ftransaction\u002Fadvisory lock, and fails loud when identity, checksums, schema, or an embedded migration is missing or stale. Never point `apply` at a transaction pool.\n- **`pauseresume`**: `max_park_duration` (ceiling on how long a pause — HITL approval, tool OAuth — may stay parked before the runtime resumes it with the typed `timeout` decision and the run ends as a constraints-conflict; default `0` = never expire), `sweep_interval` (sweeper cadence, default 1m).\n- **`tasks`**: `driver` (`inprocess` or `durable`). `inprocess` (default) keeps task\u002Fgroup\u002Fpatch state in memory — a restart starts empty. `durable` persists those records through the `StateStore` so they survive a restart; on open it replays them and recovers any task left `running` by a crash to `failed` (code `runtime_restarted`). It reuses the runtime `StateStore`, so pair it with a durable `state.driver` (`sqlite` \u002F `postgres`) for cross-process survival; selecting `durable` with no store wired fails loudly at boot.\n- **`distributed`**: `bus_driver` (`loopback` or `durable`) + `remote_driver` (`loopback` only in V1.1; A2A wire is post-V1). `loopback` is in-process; `durable` persists every `BusEnvelope` through the `StateStore` and projects it onto the local event bus, with a poller for cross-instance fan-out + restart-replay (StateStore-backed — Postgres-as-queue on a shared Postgres store; tune with `bus_poll_interval`). NATS \u002F Redis Streams remain future drivers.\n\nObserved retention horizons are inspection data, not configured retention\npromises. `runtime.health` reads only the cached runtime-wide events horizon\nfor every caller. Inspect events, tasks and sessions together through the\nexplicit, audited `runtime.retention` call with verified `admin` authority;\n`console:fleet` and trust-mode callers cannot use it (D-490).\n\n## Validation — the loud loop\n\n```bash\nharbor validate .\u002Fharbor.yaml\n```\n\nFailure modes the validator catches:\n\n- **Required field missing** — `llm.driver`, `llm.provider`, `llm.model`, `identity.issuer`, etc.\n- **Type mismatches** — `memory.budget_tokens: \"8000\"` (string instead of int).\n- **Enum violations** — `memory.strategy: \"summary\"` (not one of `none` \u002F `rolling_summary`).\n- **Bound violations** — `governance.identity_tiers.free.budget_ceiling_usd: -1` (negative).\n- **Cross-field constraints** — `memory.driver: sqlite` without `memory.dsn`.\n\nEvery error carries the `file:line` of the offending key. Fix one, re-run, repeat until clean.\n\n## Common failure modes\n\n- **`harbor validate` says `unknown field \"X\"`.** Either a typo (check indentation — YAML is whitespace-sensitive) or the field belongs in a different block. Check `docs\u002FCONFIG.md` for the canonical block.\n- **`harbor dev` boots but every Protocol call returns 401.** Your `identity` block points at a real IdP but the JWKS isn't reachable. For local dev, use the dev-token flow (see [`run-the-dev-loop`](..\u002Frun-the-dev-loop\u002FSKILL.md)) — the issuer\u002Fjwks_url path is for production.\n- **`harbor dev` reboots in an infinite loop.** SQLite WAL trap — `dsn:` inside the project directory. Move it outside.\n- **A model swap fails the first call with `ErrUnsupportedModel`.** You forgot to add a `model_profiles.\u003Cmodel>.context_window_tokens` entry for the new model. There's no silent fallback — add the profile and the call succeeds.\n\n## See also\n\n- [`scaffold-a-harbor-agent`](..\u002Fscaffold-a-harbor-agent\u002FSKILL.md) — drops the tiered yaml in the first place.\n- [`wire-the-llm-provider`](..\u002Fwire-the-llm-provider\u002FSKILL.md) — the full provider matrix + the mock vs real posture.\n- [`configure-memory-and-skills`](..\u002Fconfigure-memory-and-skills\u002FSKILL.md) — the memory strategies + runtime skill catalog in depth.\n- [`validate-and-package`](..\u002Fvalidate-and-package\u002FSKILL.md) — preflight before shipping.\n- The full per-key reference: `docs\u002FCONFIG.md`.\n\nRemote tool brokers now default to verified tenant credential selection. Upgrade the\ncoordinator to the scoped response contract before deploying. An intentionally\ndeployment-wide legacy broker must explicitly declare `credential_scope: deployment`;\nsigned capability providers always remain tenant scoped. See `docs\u002FCONFIG.md`,\n“Tenant-scoped broker credential pulls”, for the request, response and migration.\n",{"name":5,"license":15,"metadata":24,"description":7},{"verbs":25,"surface":26,"framework":27},"validate","agent-yaml","harbor","main","a8f52392f59534cd8a155ce9c0d3d25a3e62c9f0","docs\u002Fskills\u002Fdefine-the-agent-yaml",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 define-the-agent-yaml",{"tool":41,"command":42},"bunx","bunx skills add hurtener\u002FHarbor --skill define-the-agent-yaml",{"tool":44,"command":45},"pnpm","pnpm dlx skills add hurtener\u002FHarbor --skill define-the-agent-yaml","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fhurtener\u002FHarbor\u002Fblob\u002Fmain\u002Fdocs\u002Fskills\u002Fdefine-the-agent-yaml\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",[],[]]