@agentproto/runtime 5.1.0 → 5.3.0

package/dist/config-DcESQDmZ.d.ts

@@ -0,0 +1,748 @@
+import { S as SpawnDefaultsConfig } from './spawn-defaults-Cp9SGZex.js';
+
+/**
+ * Model roles — ONE place to say "which model does role X use".
+ *
+ * A role is a dotted name for a job a model does inside agentproto
+ * (`review.small`, `review.large`, `review.pr`, `judge.session`, …).
+ * Consumers (the repo-maintenance workflow, the session-steward, agent
+ * manifests via `model: role:<name>`, and later the CI reviewer and the
+ * local push gate) ask for the ROLE instead of hard-coding a model id, so
+ * "use GLM for review" is one config edit, not five files in three formats.
+ *
+ * PRECEDENCE — the single definition (highest first):
+ *   1. `input`      an explicit workflow/run input (`reviewModelSmall`, …)
+ *   2. `workspace`  the repo's own `agentproto.json` → `models`
+ *   3. `daemon`     `~/.agentproto/config.json` → `models`
+ *   4. `default`    {@link DEFAULT_MODEL_ROLES} below — the only built-in table
+ *
+ * Every resolution reports which layer won (`source`). A layer value that is
+ * empty or not a string / `{ model }` object is skipped, never fatal.
+ *
+ * This file is pure (no I/O) so the config schema can import it without a
+ * cycle; the loaders + the `model_roles` MCP tool live in
+ * `model-roles-tools.ts`.
+ */
+/** Object form of a role value: a model id plus optional serving hints. */
+interface ModelRoleEntry {
+    model: string;
+    /** Router/gateway the model should be reached through (e.g. `openrouter`). */
+    route?: string;
+    /** Named auth profile to spawn the role's session with. */
+    profile?: string;
+}
+/** A role value as written in a config file: a bare model id, or an entry. */
+type ModelRoleValue = string | ModelRoleEntry;
+/** ROLE → value, the shape of the `models` block in every layer. */
+type ModelRolesConfig = Record<string, ModelRoleValue>;
+type ModelRoleSource = "input" | "workspace" | "daemon" | "default";
+/** The built-in defaults — the ONLY hard-coded model ids for these jobs. */
+declare const DEFAULT_MODEL_ROLES: Readonly<Record<string, string>>;
+/** Prefix an agent manifest's `model:` uses to reference a role. */
+declare const MODEL_ROLE_REF_PREFIX = "role:";
+interface ModelRoleContext {
+    /** Explicit per-run values keyed by role (layer 1). */
+    input?: Record<string, ModelRoleValue | undefined> | undefined;
+    /** The workspace/repo `models` block (layer 2). */
+    workspace?: Record<string, unknown> | undefined;
+    /** The daemon config `models` block (layer 3). */
+    daemon?: Record<string, unknown> | undefined;
+}
+interface ResolvedModelRole {
+    role: string;
+    model: string;
+    route?: string;
+    profile?: string;
+    source: ModelRoleSource;
+}
+/** `role:review.large` → `review.large`; undefined for a non-role string. */
+declare function parseModelRoleRef(ref: string): string | undefined;
+/**
+ * Resolve ONE role through the precedence chain. `undefined` only when no
+ * layer — including the built-in table — knows the role.
+ */
+declare function resolveModelRole(role: string, ctx?: ModelRoleContext): ResolvedModelRole | undefined;
+/**
+ * Every role in play — the built-in ones plus any a layer configures — each
+ * resolved with its source, sorted by role name. `roles` narrows the list
+ * (an unknown role with no value anywhere is simply omitted).
+ */
+declare function listModelRoles(ctx?: ModelRoleContext, roles?: readonly string[]): ResolvedModelRole[];
+
+/**
+ * `~/.agentproto/config.json` — single hand-editable JSON for the
+ * agentproto control plane's defaults. Sits alongside the existing
+ * surface files (workspaces.json, credentials.json, sessions.json):
+ *
+ *   workspaces.json     which directories are workspaces + which is active
+ *   credentials.json    tunnel host bearer tokens (mode 0600)
+ *   sessions.json       last-known snapshot of the registry (informational)
+ *   config.json         daemon defaults: port, bind, allowed origins,
+ *                       tunnel host, feature toggles
+ *
+ * Resolution order for every daemon knob is:
+ *   1. CLI flag (e.g. --port)
+ *   2. Env var (where one exists, e.g. AGENTPROTO_TOKEN)
+ *   3. config.json
+ *   4. Hardcoded default
+ *
+ * This means a user can call `agentproto config set daemon.port 18791`
+ * once and never re-pass `--port 18791` to `serve install` etc. CLI
+ * flags still win for one-off overrides.
+ *
+ * Schema is intentionally narrow + extensible — unknown keys are
+ * preserved on save (deep-merge), so a newer CLI writing a new
+ * field won't drop one an older CLI doesn't know about. No secrets
+ * here; credentials stay in credentials.json (mode 0600).
+ */
+
+declare const CONFIG_VERSION: 1;
+interface DaemonConfig {
+    /** Absolute path to the workspace the daemon binds to at boot. */
+    workspace?: string;
+    /** HTTP port. Default 18790. */
+    port?: number;
+    /** Bind addr. Default 127.0.0.1. */
+    bind?: string;
+    /** Trusted browser origins for mutating /sessions/* routes (in
+     *  addition to the hardcoded localhost defaults). */
+    allowedOrigins?: string[];
+    /** When true, the daemon does NOT auto-trust localhost-on-any-port.
+     *  Only origins explicitly listed in `allowedOrigins` are allowed.
+     *  Pair with a curated list (e.g. `["http://localhost:3000"]`) for
+     *  hardened setups. Default false. */
+    strictOrigins?: boolean;
+    /** Server label sent in tunnel hello frames. */
+    label?: string;
+    /** Bearer token gating the gateway at boot (`AuthOptions` with
+     *  `mode: "bearer"`). Unlike `remote_enable`'s ephemeral quick-tunnel
+     *  token, this one lives in config.json and survives daemon restarts.
+     *  Set via `agentproto config set daemon.authToken <token>` (e.g.
+     *  `$(openssl rand -hex 32)`). Unset ⇒ the gateway boots with
+     *  `mode: "none"` — fully open on loopback, same as today. */
+    authToken?: string;
+    /** Opt-in eager resume-on-boot (session-survivability plan §5
+     *  "Opt-in vs automatic", PR-4). When true, a daemon restart doesn't just
+     *  leave agent-cli sessions dead-but-lazy-resumable — the boot pass eagerly
+     *  re-spawns the eligible ones (those that died with
+     *  `endedReason: "daemon-restart"` and still pass `canResume`) IN PLACE,
+     *  restoring liveness without waiting for a prompt. Lazy resume-on-prompt is
+     *  always on regardless of this flag (it costs nothing until someone acts);
+     *  this flag only controls the *automatic* boot-time pass. Default false: a
+     *  box-wide restart should not silently relaunch every adapter (cost, spawn
+     *  storm, credential re-resolution), and default-off also keeps two daemons
+     *  sharing the workspace buckets from racing to resume the same rows. Set via
+     *  `agentproto config set daemon.resumeSessionsOnBoot true`. Surfaced in
+     *  `daemon_health` / `GET /health`. */
+    resumeSessionsOnBoot?: boolean;
+    /** Opt-in continue-on-boot (continue-interrupted). When true, right after
+     *  the eager resume pass, the boot sends a "the daemon restarted mid-turn,
+     *  check the state on disk and continue" prompt to every session the LAST
+     *  restart interrupted mid-turn (`interrupted: true`) that is resumable,
+     *  under the resume cap, idle, and whose resume didn't fail. Never loops: at
+     *  most one auto-continue per restart and `MAX_AUTO_CONTINUE_ATTEMPTS` in a
+     *  row without a successful turn-end. Default false — the interrupted prompt
+     *  itself is never auto-retried, and a continue prompt is still a prompt
+     *  (tokens, side effects), so it's opt-in. The manual
+     *  `session_continue_interrupted` verb works regardless. Set via
+     *  `agentproto config set daemon.continueInterruptedOnBoot true`. */
+    continueInterruptedOnBoot?: boolean;
+    /** Idle agent-session reaper (PR-6). When set to a positive number of
+     *  milliseconds, the daemon periodically retires agent-cli sessions that have
+     *  been idle (not busy, not awaiting input, `status:"running"`) longer than
+     *  this: it SIGTERMs the adapter child to free the process and flips the row
+     *  to `killed`/`endedReason:"idle-reaped"` — dead-but-lazy-resumable (a later
+     *  prompt revives it) and, critically, excluded from eager resume-on-boot
+     *  (#638 gates on `endedReason === "daemon-restart"`), so enabling this makes
+     *  eager resume safe: only genuinely-recent work survives a restart. Default
+     *  OFF (unset / 0 / negative ⇒ the reaper never runs). Resolution order
+     *  mirrors the module docblock: `AGENTPROTO_IDLE_REAP_AFTER_MS` env > this
+     *  field > off. Set via `agentproto config set daemon.idleReapAfterMs
+     *  <ms>`. Surfaced in `daemon_health` / `GET /health`. */
+    idleReapAfterMs?: number;
+    /** Crash-detect sweep interval in ms (crash-detect PR-1). Unlike
+     *  `idleReapAfterMs`, this is DEFAULT ON (non-destructive observability):
+     *  the daemon periodically probes every live agent-cli session's OS
+     *  process (`process.kill(pid, 0)`) and, when it's provably gone with no
+     *  exit event ever emitted for it, flips the row to
+     *  `error`/`endedReason:"crashed"` with a `lastError` string — surfacing a
+     *  death that would otherwise sit silently as `status:"running"` until the
+     *  next prompt's RPC throws (or forever, for a parked session with no next
+     *  prompt). Detects only; never restarts or notifies (later PRs). Set to a
+     *  non-positive value to disable the sweep entirely. Resolution order
+     *  mirrors `idleReapAfterMs`: `AGENTPROTO_CRASH_DETECT_INTERVAL_MS` env >
+     *  this field > the hardcoded default (30s). Set via `agentproto config
+     *  set daemon.crashDetectIntervalMs <ms>`. Surfaced in `daemon_health` /
+     *  `GET /health`. */
+    crashDetectIntervalMs?: number;
+    /** Restart-scheduler sweep interval in ms (restart-scheduler PR-2). OFF by
+     *  default (unset / 0 / negative ⇒ the sweep never runs), unlike
+     *  `crashDetectIntervalMs` — a positive value here only arms the periodic
+     *  sweep that EXECUTES an already-scheduled restart; it never opts a
+     *  session in by itself (that's the per-session `agent_start.restartPolicy`
+     *  field). Resolution order mirrors `idleReapAfterMs`:
+     *  `AGENTPROTO_RESTART_SWEEP_INTERVAL_MS` env > this field > off. Set via
+     *  `agentproto config set daemon.restartSweepIntervalMs <ms>`. Surfaced in
+     *  `daemon_health` / `GET /health`. */
+    restartSweepIntervalMs?: number;
+    /** Turn-liveness watchdog threshold in ms (turn-liveness-watchdog
+     *  chantier). Same shape as `crashDetectIntervalMs`: DEFAULT ON
+     *  (non-destructive observability). The daemon periodically sweeps every
+     *  BUSY agent-cli session and, for one that is mid-turn, NOT legitimately
+     *  `blockedOn` a subagent/command, and has had no adapter activity
+     *  (`lastActivityAt`) for longer than this threshold, stamps
+     *  `stalledSinceMs` on the descriptor and emits `session:stalled` —
+     *  surfacing a dead adapter stream (network drop, hung child — zero
+     *  frames mid-turn) that would otherwise sit indistinguishable from
+     *  healthy long work: `status:"running"`, `lastError:null`, no other
+     *  signal. Conservative by design: a session legitimately blocked on a
+     *  long tool call is NEVER a candidate, no matter how long it's silent —
+     *  see `stall-watchdog.ts`'s docblock for why. Detects only; never kills
+     *  or restarts (this is a later concern, if ever). Set to a non-positive
+     *  value to disable the sweep entirely. Resolution order mirrors
+     *  `idleReapAfterMs`: `AGENTPROTO_TURN_STALL_AFTER_MS` env > this field >
+     *  the hardcoded default (5 min). Set via `agentproto config set
+     *  daemon.turnStallAfterMs <ms>`. Surfaced in `daemon_health` /
+     *  `GET /health`. */
+    turnStallAfterMs?: number;
+}
+interface TitlerConfig {
+    /** Enable the daemon-side session titler. Default false. */
+    enabled?: boolean;
+    /** OpenRouter model id used to generate titles. Default
+     *  `z-ai/glm-5.2@openrouter`. Requires `OPENROUTER_API_KEY` in the
+     *  daemon's environment; without a key the titler falls back to the
+     *  local (first-prompt-line) title. */
+    model?: string;
+}
+interface CatalogSourceConfig {
+    /** HTTP(S) URL returning `{ entries: AppCatalogEntry[] }`. */
+    url: string;
+}
+interface CatalogConfig {
+    /** Remote app-catalog sources merged into `app_catalog`. When set, these
+     *  win over `sources` in `~/.agentproto/app-catalog.json`. */
+    sources?: CatalogSourceConfig[];
+}
+interface TunnelConfig {
+    /** Cloud WS URL. When set + autoconnect=true, `agentproto serve`
+     *  bootstraps with `--connect <host>`. */
+    host?: string;
+    /** apt_ daemon token to present at the tunnel upgrade. When set,
+     *  `agentproto serve` uses this BEFORE falling back to
+     *  credentials.json — handy in profiles where the token-per-host
+     *  mapping in credentials.json doesn't fit (e.g. host = tunnel URL
+     *  but credentials were minted against the api URL). */
+    token?: string;
+    /** Whether `agentproto daemon start` connects the tunnel by
+     *  default. v0 only — implementer can ignore until daemon needs it. */
+    autoconnect?: boolean;
+    /**
+     * Opt into end-to-end encryption of the outbound `serve --connect` tunnel
+     * (design: tunnel-e2e/v1). When true, the daemon negotiates a
+     * token-authenticated ephemeral handshake with the host and wraps the tunnel
+     * frames in an AEAD box, so even the trusted host loses plaintext visibility.
+     * The handshake authenticates both ends against the shared `tunnel.token`, so
+     * `token` MUST also be set. Fully backward-compatible: if the host doesn't
+     * advertise e2e (an older host), the daemon falls back to today's plaintext
+     * tunnel. Unset/false ⇒ plaintext, byte-identical to today. */
+    e2e?: boolean;
+}
+interface FeaturesConfig {
+    /** Hint that PTY is desired — informational; the daemon still
+     *  detects node-pty's presence at runtime. */
+    pty?: boolean;
+    /** Enable the local LLM Endpoint proxy sidecar (route registration,
+     *  MCP tools, child-process lifecycle). Default false — the endpoint is
+     *  an opt-in feature; when off, the `llm-endpoint` custom route is not
+     *  registered and the `llm_endpoint_*` MCP tools are not exposed. */
+    llmEndpoint?: boolean;
+    /** Expose this daemon's local inference endpoint(s) (the `llmEndpoint`
+     *  sidecar above) to paired controllers over a HOST-scoped pairing —
+     *  `GET /device-inference/v1/models` + `POST
+     *  /device-inference/v1/chat/completions` in http-server.ts. Default
+     *  false: even with `llmEndpoint` on, a plain remote-control pairing (or
+     *  `serve --connect`) never gets these routes regardless of this flag —
+     *  it also requires the pairing itself to be host-scoped (`pair offer
+     *  --host` + `devices add`). Toggle via `agentproto devices
+     *  share-inference on|off`. */
+    deviceInferenceShare?: boolean;
+    /** Opt this daemon in to being usable as an `agent_start({ sandbox:
+     *  "device:<name>" })` target (DEVICES-PLAN PR-D) — exposes
+     *  `/device-spawn/*` in http-server.ts, a self-proxy onto this daemon's
+     *  own `/mcp` + `/sessions/:id/events/stream`. Default false: even with
+     *  this on, only a HOST-scoped pairing (`pair offer --host` + `devices
+     *  add`) can reach the routes — a plain remote-control pairing never can,
+     *  whatever this is set to. Toggle via `agentproto devices allow-spawn
+     *  on|off`. */
+    deviceSpawnAllow?: boolean;
+}
+/**
+ * Policy for `agentproto worktree new` (PLAN.md §1.4 — config carries
+ * policy, never state; git itself is the authority for which worktrees
+ * exist). This is the fix for the sprawl the plan measured: 31 linked
+ * worktrees across 6 different parent directories, because there was no
+ * `worktree new` verb and therefore no convention to converge on.
+ */
+/**
+ * How the daemon isolates a freshly-spawned agent session into its own git
+ * worktree (`agent_start.worktree`):
+ *   - `"always"`      — every depth-0 spawn is provisioned into a worktree,
+ *                       whether or not the caller asked. A cwd that is not in
+ *                       a git repo has nothing to isolate, so it spawns plain.
+ *   - `"on-request"`  — isolate ONLY when the caller passes `worktree`. This
+ *                       is the default and the back-compatible behaviour:
+ *                       today's callers pass nothing and spawn exactly where
+ *                       they asked.
+ *   - `"never"`       — isolation is off; an explicit `worktree` field is
+ *                       REJECTED (loud, not silently ignored) so a caller
+ *                       never believes it got an isolated tree it didn't.
+ */
+type WorktreeIsolationMode = "always" | "on-request" | "never";
+interface WorktreesConfig {
+    /**
+     * Absolute path new worktrees are created under. Layout:
+     * `<root>/<repoName>/<slug>`. Resolution order (mirrors every other
+     * knob in this file, see the module docblock): `--root` flag >
+     * `AGENTPROTO_WORKTREES_ROOT` env > this field > the hardcoded default
+     * `~/.agentproto/worktrees`. The default is a real single root, not
+     * "unconfigured" — `worktree new` converges to one place with zero
+     * setup, which is the only way the sprawl actually stops (the 6 roots
+     * that exist today are 6 people each inventing a default by hand).
+     */
+    root?: string;
+    /**
+     * Policy for `agent_start.worktree` isolation. Resolution order mirrors
+     * the module docblock (there is no CLI flag — this is a daemon-side
+     * policy read at spawn, not a per-invocation flag):
+     * `AGENTPROTO_WORKTREES_ISOLATION` env > this field > the hardcoded
+     * default `"on-request"`. `"on-request"` is deliberately the default:
+     * any other would break back-compat by isolating callers that never
+     * asked (see `worktree-isolation.ts`).
+     */
+    isolation?: WorktreeIsolationMode;
+    /**
+     * Max worktree provisionings running their HEAVY phases (`cloneGlobs`,
+     * `depsCmd`, `copyGlobs`, the `worktree.setup` hooks) at once, daemon-wide.
+     * A burst of `agent_start({worktree})` spawns otherwise runs that many
+     * concurrent `pnpm install`s against one store on one disk (the 2026-09-28
+     * incident: load average 170, installs 3.5x slower). The rest wait in a
+     * FIFO queue, fair across spawning callers. `git worktree add` and the
+     * cheap prep stay unthrottled. Resolution order:
+     * `AGENTPROTO_WORKTREES_PROVISION_CONCURRENCY` env > this field > the
+     * default `2`. An integer >= 1; `0` means unlimited (the pre-queue
+     * behavior). Invalid values fall back to the default.
+     */
+    provisionConcurrency?: number;
+    /**
+     * Per-repo overrides of {@link provisionConcurrency}, additional to (never
+     * looser than) the global cap. Keys are an absolute repo-root path (`~/`
+     * expands) or a bare repo directory name; values as above. Example:
+     * `{ "agentik-studio": 1 }` serializes installs of that repo even when
+     * other repos may install two at a time.
+     */
+    provisionConcurrencyByRepo?: Record<string, number>;
+    /**
+     * Optional load guard: hold back starting a NEW heavy segment while the
+     * 1-minute load average exceeds `cores x provisionLoadFactor`. Unset / `0`
+     * = off (the default). Never blocks when nothing is running, so a loaded
+     * host cannot deadlock the queue.
+     */
+    provisionLoadFactor?: number;
+}
+/**
+ * Policy for `agent_start.attach` — whether a spawn AUTO-attaches to its
+ * calling session as parent lineage. `"always"` (the default) nests a
+ * spawned child under the session that spawned it whenever that identity is
+ * derivable (the trusted `?callerSessionId=` on the daemon self-ref URL, or
+ * an explicit `parentSessionId` hint), so a supervisor's executors stop
+ * landing as depth-0 orphans. `"on-request"` reverts to the pre-attach
+ * behaviour: auto-attribution is off, and a child nests only when the caller
+ * explicitly opts in (`attach: true` / `attach: { parent }` / an explicit
+ * `parentSessionId`). Either way a per-call `attach: false` forces an
+ * independent root, exactly as `worktree: false` opts out of isolation. See
+ * `spawn-attach.ts`.
+ */
+type SpawnAttachMode = "always" | "on-request";
+/**
+ * Policy for `agent_start`'s IMPLICIT dedupe — what happens when a caller
+ * spawns with NO `idempotencyKey` at all (see `spawn-dedupe.ts`):
+ *   - `"always"`      — the daemon DERIVES an implicit key from the spawn's
+ *                       `label` (required — see below) plus a hash of the
+ *                       initial `prompt`, and dedupes a same-adapter/cwd
+ *                       repeat against it exactly as an explicit key would.
+ *                       This is the default, mirroring `attach`'s own
+ *                       "opt-in-only guard is not a guard" precedent above.
+ *                       Deriving needs a `label` to produce anything at all
+ *                       — an unlabelled spawn is untouched, which is what
+ *                       keeps this safe for the fan-out pattern this repo
+ *                       exercises (several agents into one cwd with no
+ *                       shared label): see `spawn-dedupe.ts`'s docblock for
+ *                       the full false-dedup analysis, and PR #803's own
+ *                       no-opt-in label+cwd warning backstop in
+ *                       `session-spawn.ts`, which independently landed on
+ *                       the same label-is-the-signal boundary.
+ *   - `"on-request"`  — no implicit derivation; only an explicit
+ *                       `idempotencyKey` dedupes (today's behaviour,
+ *                       unchanged). A per-call `dedupe: true` still opts in
+ *                       under this policy, mirroring `attach: true`.
+ * Either way a per-call `dedupe: false` disables implicit derivation for
+ * that one spawn regardless of policy — the escape hatch, mirroring
+ * `attach: false` / `worktree: false`. An explicit `idempotencyKey` always
+ * wins over a derived one (derivation is only attempted when the caller
+ * supplied none).
+ */
+type SpawnDedupeMode = "always" | "on-request";
+interface SpawnConfig {
+    /**
+     * Attach policy for `agent_start`. Resolution order mirrors the module
+     * docblock (no CLI flag — a daemon-side policy read at spawn):
+     * `AGENTPROTO_SPAWN_ATTACH` env > this field > the hardcoded default
+     * `"always"`. Unlike `worktrees.isolation` (whose default preserves
+     * back-compat by NOT isolating), attach defaults ON: an orphaned executor
+     * is a bug, not a feature, and the auto-parent is descriptor-only lineage
+     * that never relaxes a privilege gate.
+     */
+    attach?: SpawnAttachMode;
+    /**
+     * Implicit-dedupe policy for `agent_start`. Resolution order mirrors
+     * `attach` above (no CLI flag — a daemon-side policy read at spawn):
+     * `AGENTPROTO_SPAWN_DEDUPE` env > this field > the hardcoded default
+     * `"always"`. See {@link SpawnDedupeMode} and `spawn-dedupe.ts` for the
+     * full reasoning: a retry-safety guard that only works when a caller
+     * remembers to ask for it (`idempotencyKey`) is not a guard — the same
+     * argument `attach` already settled for parent lineage.
+     */
+    dedupe?: SpawnDedupeMode;
+}
+/**
+ * Provenance policy — the opt-in `gh` PATH shim (`gh-provenance-shim.ts`).
+ * Off by default. When `wrapGh` is on, every agent session the daemon spawns
+ * gets a shim directory prepended to its PATH so that any `gh pr create` the
+ * session (or an adapter subprocess shelling out — claude-code, codex, …) runs
+ * has a deterministic `@agentproto-bot` provenance footer appended to the
+ * created PR's BODY, matching the footer the cloud runner stamps. The TOOL
+ * stamps, never the model; commit messages are never touched (the repo's
+ * hygiene-check forbids attribution there). Resolution order mirrors
+ * `spawn.attach`: `AGENTPROTO_PROVENANCE_WRAP_GH` env > this field > default
+ * `false`.
+ */
+interface ProvenanceConfig {
+    /** Enable the opt-in `gh` provenance PATH shim for spawned sessions. */
+    wrapGh?: boolean;
+}
+/**
+ * Approvals policy (`packages/runtime/src/approvals/`, E1a) — config for
+ * the `web_click` human decision channel. See `AIP-7-AMENDMENT.md` for the
+ * full channel design.
+ */
+interface ApprovalsConfig {
+    /**
+     * Origins allowed to decide a pending approval through `POST
+     * /approvals/:id/decision` (in addition to the daemon's own per-boot
+     * bearer token, which is ALWAYS required on that route regardless of
+     * this list). Default empty — `web_click` is OFF until at least one
+     * origin is configured. Lockout-shaped like `daemon.allowedOrigins`,
+     * but a SEPARATE list: the general browser-origin allowlist is not
+     * automatically trusted to decide approvals.
+     */
+    webOrigins?: string[];
+}
+/**
+ * Sentinel auto-link policy (AIP-60 §6, step 4) — whether a PR an executor
+ * session opens gets a sentinel created for it automatically.
+ */
+interface SentinelConfig {
+    /** Auto-watch a PR when a session opens one (`recordOpenedPr`, fed by
+     *  `command_execute`'s stamper and both `pr-provenance-reconciler.ts`
+     *  lanes). When unset, the daemon defaults to `true` only when the
+     *  `local-gh` provider is available (i.e. `gh auth status` succeeds) —
+     *  otherwise `false`, logged once. Explicitly setting this always wins
+     *  over that probe. Per-spawn opt-out: `agent_start.sentinel: false`. */
+    autoWatchPrs?: boolean;
+}
+/**
+ * Review-primitive host policy (`@agentproto/review` + `review-runner.ts`).
+ */
+interface ReviewConfig {
+    /** The owner identity attestation signatures claim (`attestor.signature.
+     *  principal`) — see `review-signing.ts`'s `resolvePrincipal`. When unset,
+     *  the daemon falls back to `git config user.email` of the reviewed repo,
+     *  then a host-derived value; this never blocks signing, it only lets an
+     *  operator pin one identity across every repo the daemon reviews. */
+    principal?: string;
+}
+/**
+ * Session-presence policy — how the dashboard triages a session into its
+ * `running` / `tending` / `attention` / `quiet` presence state (see
+ * `session-presence.ts`). Optional block on `AgentprotoConfig.sessions`.
+ */
+interface SessionsConfig {
+    /**
+     * How long (seconds) a session stays shown as `running` after its last
+     * turn ends, before it settles into `attention`/`quiet`. The grace window
+     * is measured from the session's most recent `lastActivityAt` — ANY new
+     * event resets it — so a session that just answered does not read as
+     * "quiet" the instant its turn finishes, but something that went idle long
+     * ago, with nothing waiting on it, settles grey. Resolution order mirrors
+     * every other knob in this file (module docblock): env var
+     * `AGENTPROTO_SESSIONS_ATTENTION_DELAY_SEC` > this field > the hardcoded
+     * default `60`. Absent ⇒ 60s.
+     */
+    attentionDelaySec?: number;
+    /**
+     * Root directory the daemon stores per-session transcripts under — each
+     * session's `events.jsonl` lands at `<eventsDir>/<sessionId>/events.jsonl`
+     * (and a terminal session's `terminal.jsonl` alongside it). Every
+     * reader/writer (transcript writer, `/sessions/:id/events` HTTP routes,
+     * exports, tool-call/usage logs) resolves through this single knob.
+     * Resolution order mirrors every other knob in this file: relative paths
+     * resolve against the home directory. Absent ⇒ the hardcoded default
+     * `~/.agentproto/sessions` — zero behaviour change out of the box. A
+     * change requires a daemon restart to take effect (and existing sessions'
+     * transcripts do NOT move).
+     */
+    eventsDir?: string;
+}
+/**
+ * Policy for the daemon's own AGENTS.md resolution + injection (WP-R2) —
+ * how a spawned session's initial prompt carries the repo's `AGENTS.md`
+ * (see `agents-md.ts`). The daemon resolves the nearest `AGENTS.md` walking
+ * up from the session's `cwd`, bounded by that repo's git toplevel, and
+ * injects one AGENTS.md block after the role disposition whenever the spawn
+ * carries a prompt.
+ */
+interface AgentsMdConfig {
+    /**
+     * Inline-vs-pointer threshold in KiB. A resolved AGENTS.md whose byte size
+     * is STRICTLY LESS than `inlineMaxKb` KiB is inlined in full into the
+     * spawn's initial prompt, clearly delimited; `>=` the threshold is injected
+     * as a short pointer telling the agent to read the file before its first
+     * tool call instead. An absent AGENTS.md (nothing found up the walk) injects
+     * nothing but is still reported on the descriptor via
+     * `SessionDescriptor.agentsMdMode === "absent"`. Resolution order mirrors
+     * the module docblock (no CLI flag, and no env override — not part of the
+     * approved design): this field > the hardcoded default `8` (KiB).
+     */
+    inlineMaxKb?: number;
+}
+interface PairingConfig {
+    /** Rendezvous broker WS URL (ws:// or wss://) used by `pair offer` and by
+     *  autoconnect on boot. When unset, `pair offer` requires an explicit
+     *  `--rendezvous`. Mirrors `tunnel.host`. */
+    rendezvous?: string;
+    /** Whether the daemon opens standing rendezvous connections for every
+     *  persisted pairing on boot (so a paired client can reconnect anytime).
+     *  Mirrors `tunnel.autoconnect`. Default true when a rendezvous is set. */
+    autoconnect?: boolean;
+    /** Web pair page for `pair offer --qr` (the offer rides in its fragment).
+     *  A template with `{fp}` in the HOSTNAME, filled with the daemon
+     *  fingerprint (one origin per daemon), or a plain http(s) URL (one shared
+     *  origin). Unset → `https://{fp}.agentproto.cloud/pair`. `--pair-page`
+     *  overrides it. */
+    pairPage?: string;
+}
+/**
+ * A user-defined generic ACP agent — the config-file half of
+ * `AcpAgentSpec` (the slug is the record key in `acpAgents`, so it's
+ * omitted here). Any CLI that already speaks the Agent Client Protocol
+ * can be wired with zero code by declaring one of these under
+ * `acpAgents.<slug>` in `~/.agentproto/config.json`; the CLI's
+ * `acpHandleFromSpec` mints a runnable `AgentCliHandle` from it at
+ * resolve time (see `packages/cli/src/registry/acp-generic.ts`). Kept
+ * in this package (not the CLI's) so `config.ts` stays the single
+ * source of truth for the config surface without a cli→runtime→cli
+ * import cycle — the CLI's `AcpAgentSpec` extends this shape.
+ */
+interface AcpAgentConfigEntry {
+    /** Display name. Defaults to the slug when omitted. */
+    name?: string;
+    /** One-line description surfaced in `agentproto acp ls`. */
+    description?: string;
+    /** Executable to spawn, e.g. "gemini". */
+    bin: string;
+    /** Extra argv appended after `bin`, e.g. ["--experimental-acp"]. */
+    bin_args?: string[];
+    /** Extra environment variables for the spawned process. */
+    env?: Record<string, string>;
+    /** Flag the CLI uses to receive the working directory, if it needs
+     *  one passed explicitly (most ACP agents take cwd over the wire). */
+    cwd_flag?: string;
+    /** When true, advertise resumable + native-resume continuation. */
+    resumable?: boolean;
+    /** Known model ids for the agent (informational + validation hints). */
+    models?: {
+        default?: string;
+        allowed?: string[];
+    };
+    /** Billing endpoint this CLI's own auth bills (e.g. "mistral",
+     *  "moonshot", "google") — the provider whose wallet/auth-profile the
+     *  agent consumes. Lets clients link the harness to that provider's
+     *  wallets even when no model list is declared. Unset when the CLI's
+     *  billing target isn't a single known endpoint. */
+    provider?: string;
+    /** Shown when `bin` is missing from PATH (how to install the CLI). */
+    install_hint?: string;
+}
+/**
+ * Per-environment connection bundle. A profile overrides specific
+ * fields of the top-level `daemon` / `tunnel` / `features` blocks
+ * when selected via `--profile <name>` (or the top-level
+ * `activeProfile` setting). Missing fields fall through to the
+ * top-level config, so a profile only needs to declare what's
+ * different — typically just `tunnel.host` + `tunnel.token`.
+ *
+ * Example:
+ *   {
+ *     "daemon": { "workspace": "/code", "port": 18790 },
+ *     "activeProfile": "local",
+ *     "profiles": {
+ *       "local": { "tunnel": { "host": "ws://localhost:3200/connect",
+ *                              "token": "apt_local", "autoconnect": true } },
+ *       "prod":  { "tunnel": { "host": "wss://tunnel.guilde.work/connect",
+ *                              "token": "apt_prod",  "autoconnect": true },
+ *                  "daemon": { "port": 18791 } }
+ *     }
+ *   }
+ *
+ * Sandbox daemons generate per-sandbox profile entries at provision
+ * time so the daemon inside the sandbox boots with
+ * `agentproto serve --profile sandbox-<id>` and no extra plumbing.
+ */
+interface ProfileConfig {
+    daemon?: DaemonConfig;
+    tunnel?: TunnelConfig;
+    features?: FeaturesConfig;
+}
+/**
+ * A user-defined named terminal/TUI preset stored in
+ * `~/.agentproto/config.json` under `terminalPresets`. Presets keep
+ * local launch recipes (argv, env, cwd, name/label) out of shared
+ * adapter manifests — e.g. pointing a Claude Code TUI at a local
+ * LLM gateway without retyping proxy env vars every spawn.
+ */
+interface TerminalPreset {
+    /** Command + args to spawn. When provided, `sessions terminal` can
+     *  be used without `-- <argv...>`. */
+    argv?: string[];
+    /** Extra environment variables layered on top of the daemon's
+     *  inherited process.env. Values MUST be strings. */
+    env?: Record<string, string>;
+    /** Working directory for the PTY session. Relative paths are
+     *  resolved against the current working directory at CLI time. */
+    cwd?: string;
+    /** Workspace slug used for cwd fallback when `cwd` is omitted. */
+    workspace?: string;
+    /** Stable session name passed to the registry (`name` field). */
+    name?: string;
+    /** Human-readable label surfaced in session listings. */
+    label?: string;
+}
+interface AgentprotoConfig {
+    version?: number;
+    daemon?: DaemonConfig;
+    tunnel?: TunnelConfig;
+    features?: FeaturesConfig;
+    /** E2E daemon-pairing defaults (rendezvous URL + autoconnect). */
+    pairing?: PairingConfig;
+    /** Where `agentproto worktree new` creates worktrees. See
+     *  {@link WorktreesConfig}. */
+    worktrees?: WorktreesConfig;
+    /** Spawn-time policy (`agent_start`). See {@link SpawnConfig}. */
+    spawn?: SpawnConfig;
+    /** Session-presence policy for the dashboard. See {@link SessionsConfig}. */
+    sessions?: SessionsConfig;
+    /** Provenance policy — the opt-in `gh` PATH shim. See {@link ProvenanceConfig}. */
+    provenance?: ProvenanceConfig;
+    /** Approvals policy — the `web_click` origin allowlist. See {@link ApprovalsConfig}. */
+    approvals?: ApprovalsConfig;
+    /** Sentinel auto-link policy. See {@link SentinelConfig}. */
+    sentinel?: SentinelConfig;
+    /** Review-primitive host policy. See {@link ReviewConfig}. */
+    review?: ReviewConfig;
+    /** Daemon-side AGENTS.md resolution/injection policy. See {@link AgentsMdConfig}. */
+    agentsMd?: AgentsMdConfig;
+    /** Model roles: ROLE → model id (or `{ model, route?, profile? }`), the
+     *  one place reviewer/judge models are configured. Layer 3 of the
+     *  precedence documented in `model-roles.ts` (input > workspace
+     *  `agentproto.json` > this > built-in default). Role names contain dots,
+     *  so `getConfigKey`/`setConfigKey` treat everything after `models.` as
+     *  ONE key (`models.review.pr` → `models["review.pr"]`). */
+    models?: ModelRolesConfig;
+    /** Daemon-side session titler (`session-titler.ts`). DEFAULT OFF — when
+     *  `enabled` is not explicitly true the titler is a complete no-op and
+     *  nothing renames anything. When on, at the end of the FIRST completed
+     *  turn of a `kind:"agent-cli"` session whose label is still a spawn
+     *  default (`chat-starter`, `chat-starter-autoprompt`, `agentproto`, empty,
+     *  or equal to the derived title), the daemon generates a short prosaic
+     *  title (4-8 words) from the first turn's transcript and renames the
+     *  session via the same write path as `session_rename`. Generation tries
+     *  OpenRouter (`model`, default `z-ai/glm-5.2@openrouter`, needs
+     *  `OPENROUTER_API_KEY`) and falls back locally (first line of the first
+     *  user prompt, 6 whole words) on any failure. A user-created label is
+     *  NEVER overwritten, and a session is titled at most once. */
+    titler?: TitlerConfig;
+    /** App catalog settings (`app-catalog.ts`). See {@link CatalogConfig}. */
+    catalog?: CatalogConfig;
+    /** Named connection profiles. See `ProfileConfig` for the merge
+     *  semantics — a profile's fields shallow-override the top-level
+     *  defaults for the selected run. */
+    profiles?: Record<string, ProfileConfig>;
+    /** Profile name to use when `--profile` isn't passed. When unset,
+     *  the top-level `daemon` / `tunnel` blocks are used directly. */
+    activeProfile?: string;
+    /** Default `skills` + `options` auto-applied to every `agent_start`
+     *  spawn — global and per-adapter. See `resolveSpawnDefaults` in
+     *  `spawn-defaults.ts` for the merge precedence with an explicit call.
+     *  Absent ⇒ current behaviour exactly (no regression). */
+    defaults?: SpawnDefaultsConfig;
+    /** User-defined generic ACP agents, keyed by adapter slug. Each entry
+     *  is minted into a runnable handle by the CLI's `acpHandleFromSpec`
+     *  when `resolveAdapter(slug)` finds no npm adapter package. User
+     *  entries shadow the curated `ACP_CATALOG` on slug collision. */
+    acpAgents?: Record<string, AcpAgentConfigEntry>;
+    /** User-defined named terminal/TUI presets. Local-only; never
+     *  packaged in shared adapter manifests or defaults. */
+    terminalPresets?: Record<string, TerminalPreset>;
+    /** Unknown keys preserved across save round-trips. */
+    [unknown: string]: unknown;
+}
+declare const CONFIG_FILE_PATH: () => string;
+/**
+ * Load config.json. Returns an empty object (NOT null) when the file
+ * is missing, malformed, or unreadable — callers can `cfg.daemon?.port`
+ * safely without null-guards. Errors during a malformed-read are
+ * logged once so the user notices the file is broken without the
+ * daemon refusing to boot.
+ */
+declare function loadConfig(path?: string): Promise<AgentprotoConfig>;
+/**
+ * Write config.json atomically (tmp + rename) so a concurrent
+ * `agentproto config edit` can't half-truncate the file. Writes
+ * `next` AS-IS — callers are expected to pass the full desired
+ * state (loaded the existing config, mutated, passed it back).
+ *
+ * Earlier versions deep-merged with the on-disk file, but that made
+ * deletions impossible: `setConfigKey(cfg, "x", undefined)` would
+ * remove the key from memory, then the deep-merge would silently
+ * re-add it from disk. The current design trusts the caller's
+ * snapshot and uses atomic rename for crash safety.
+ */
+declare function saveConfig(next: AgentprotoConfig, path?: string): Promise<void>;
+/** Split a dotted key into path segments. `models.<role>` is the one
+ *  exception: role names are themselves dotted (`review.pr`), so everything
+ *  after `models.` is a single segment. */
+declare function splitConfigPath(dotted: string): string[];
+/**
+ * Read a dot-notation key (`daemon.port`) out of a config. Returns
+ * `undefined` when any segment is missing.
+ */
+declare function getConfigKey(cfg: AgentprotoConfig, dotted: string): unknown;
+/**
+ * Set a dot-notation key in a config. Returns a new object — does
+ * NOT mutate. Creates intermediate objects as needed. Setting
+ * `value: undefined` is treated as a delete.
+ */
+declare function setConfigKey(cfg: AgentprotoConfig, dotted: string, value: unknown): AgentprotoConfig;
+
+export { type ApprovalsConfig as A, loadConfig as B, type CatalogConfig as C, type DaemonConfig as D, saveConfig as E, type FeaturesConfig as F, setConfigKey as G, splitConfigPath as H, MODEL_ROLE_REF_PREFIX as M, type PairingConfig as P, type ResolvedModelRole as R, type SpawnConfig as S, type TunnelConfig as T, type WorktreesConfig as W, type SessionsConfig as a, type ProvenanceConfig as b, type AgentsMdConfig as c, type TitlerConfig as d, type ProfileConfig as e, type AcpAgentConfigEntry as f, type TerminalPreset as g, type WorktreeIsolationMode as h, type SpawnAttachMode as i, type SpawnDedupeMode as j, DEFAULT_MODEL_ROLES as k, type ModelRoleContext as l, type ModelRoleEntry as m, type ModelRoleSource as n, type ModelRoleValue as o, type ModelRolesConfig as p, listModelRoles as q, parseModelRoleRef as r, resolveModelRole as s, type AgentprotoConfig as t, CONFIG_FILE_PATH as u, CONFIG_VERSION as v, type CatalogSourceConfig as w, type ReviewConfig as x, type SentinelConfig as y, getConfigKey as z };