@agentproto/runtime 0.7.0 → 0.8.0

package/README.md

@@ -44,6 +44,7 @@ A per-boot bearer token is generated automatically and written into `<workspace>
 | Adapter discovery | `GET /adapters`                          | When `listAgentAdapters` is wired                      |
 | Sessions list     | `GET /sessions` / `GET /sessions/:id`    | id-or-name in `:id`                                   |
 | Agent spawn       | `POST /sessions/agent`                   | Long-lived ACP agent (needs `resolveAgentAdapter`)    |
+| Interrupt turn    | `POST /sessions/:id/interrupt`           | Cancel the in-flight turn; session stays alive        |
 | **PTY spawn**     | **`POST /sessions/terminal`**            | Needs `spawnPty` factory                              |
 | **PTY attach**    | **`WS /sessions/:id/pty`**               | JSON frames `{kind:data|input|resize|exit|ping|pong}`; multi-subscriber, min-size resize, ring-buffer replay |
 | SSE attach        | `GET /sessions/:id/stream`               | Line-by-line text events                              |

package/dist/config-BRKy_SAF.d.ts

@@ -0,0 +1,569 @@
+import { CatalogProvider } from '@agentproto/model-catalog';
+
+/**
+ * Pure resolver for `~/.agentproto/config.json`'s `defaults` block —
+ * computes the effective `skills` + `options` + `auth` for an `agent_start`
+ * spawn before adapter-specific normalization. No fs, no adapter I/O, so
+ * it's unit-testable in isolation from `session-spawn.ts` (which owns the
+ * fs read + the adapter-manifest lookup).
+ *
+ * Precedence (lowest → highest): global `defaults` < `defaults.adapters.
+ * <slug>` < the explicit `agent_start` call.
+ *   - `options`: shallow-merged maps, later (higher-precedence) keys win.
+ *   - `skills`: global ∪ per-adapter when the caller didn't pass `skills`
+ *     at all; an explicit `skills` (even `[]`) REPLACES the union rather
+ *     than merging into it — a deliberate exact set, mirroring how an
+ *     explicit `mcpServers: []` opts out of the hermes default in
+ *     `session-spawn.ts`.
+ *   - `auth`: surfaces the RAW billing-auth material (requested mode, both
+ *     candidate credentials, per-spawn provider pin, and the `explicit`
+ *     signal) so the descriptor-aware resolver ({@link resolveAuthSpec},
+ *     which also needs the adapter's provider/subscription descriptor +
+ *     providers.json) can decide the final mode, env var, scrub set, and
+ *     credential source. Credentials are named in config or the provider
+ *     store — never read from the ambient shell env.
+ */
+
+/**
+ * Deterministic billing-auth config for one adapter slug (today, only
+ * claude-code interprets it — see `AgentCliStartOptions.auth` in
+ * `@agentproto/driver-agent-cli`). EXPLICIT credential selection, not
+ * scrub-by-absence: `token`/`apiKey` are the actual secret values, named
+ * here (or supplied per-spawn) rather than inherited from the launching
+ * shell. Never logged; only a fingerprint (see {@link credentialFingerprint})
+ * is ever surfaced back to a caller.
+ */
+interface DefaultsAdapterAuthConfig {
+    /** `"subscription"` or `"api-key"`. Omitted ⇒ the resolver picks by
+     *  ordered preference (subscription first for adapters that support it —
+     *  see {@link resolveAuthSpec}), never a hardcoded default. */
+    mode?: "subscription" | "api-key";
+    /** The subscription bearer token for `"subscription"` mode — minted via
+     *  `claude setup-token` (bills the Max/Pro subscription, not API credits),
+     *  SET to the adapter's `authSubscription.setEnv`. */
+    token?: string;
+    /** Explicit API key for `"api-key"` mode, SET to `providerEnvVar(provider)`.
+     *  Wins over the `providers.json` store key for the same provider. */
+    apiKey?: string;
+    /** Per-spawn provider PIN — overrides the adapter's fixed provider and the
+     *  model-derived provider (the sharp edge for by-model routers whose config
+     *  routes a catalog-"anthropic" model elsewhere). A `CatalogProvider` id. */
+    provider?: CatalogProvider;
+}
+interface DefaultsAdapterConfig {
+    skills?: string[];
+    options?: Record<string, boolean | number | string>;
+    auth?: DefaultsAdapterAuthConfig;
+}
+/** Shape of `config.json`'s top-level `defaults` block. */
+interface SpawnDefaultsConfig {
+    skills?: string[];
+    options?: Record<string, boolean | number | string>;
+    adapters?: Record<string, DefaultsAdapterConfig>;
+    /** Depth cutoff for the role-derived default (see `resolveRole` in
+     *  `role.ts`) applied when an `agent_start` call omits `role`:
+     *  `depth < cutoff` → supervisor, `depth >= cutoff` → executor.
+     *  Default 1 (root spawns keep today's unrestricted behaviour; any
+     *  spawn made THROUGH an orchestrator defaults to executor). Tune
+     *  this up (e.g. to a large number) to restore the old permissive
+     *  behaviour for existing deep spawns wholesale. */
+    defaultRoleDepthCutoff?: number;
+    /** Trust-boundary cap on pack-carried roles (see `role-registry.ts`'s
+     *  `loadRoleRegistry`): a role pack whose `toolPolicy.delegation` is
+     *  `"allow"` at a level ABOVE this cap has it forced to `"deny"` —
+     *  the pack can still declare the intent, the daemon just refuses to
+     *  grant it. Lets an operator install third-party role packs without
+     *  trusting every one of them to self-grant delegation. Undefined
+     *  (default) ⇒ no cap, any pack-declared level may carry
+     *  `delegation: "allow"` (back-compat: #214 had no such knob). */
+    maxGrantableDelegation?: number;
+    /** Default per-session Langfuse tracing opt-in when an `agent_start` call
+     *  omits `trace`. Default false — sessions trace only when they opt in or
+     *  this is on. See `filterSessionObserver` / `SpawnAgentInput.trace`. */
+    langfuseTracing?: boolean;
+    /** Redactor slug applied to traced session content before it's sent to
+     *  Langfuse (see `@agentproto/redaction`'s registry). Default "secrets"
+     *  (deny-list by key + value-scan for secret shapes). */
+    traceRedactor?: string;
+}
+interface ResolveSpawnDefaultsInput {
+    /** Explicit-call `skills`. Undefined ⇒ caller expressed no preference,
+     *  fall through to the config union. Provided ⇒ replaces it outright. */
+    skills?: string[];
+    /** Explicit-call AIP-45 `options` map — wins per-key over both the
+     *  global and per-adapter config defaults. */
+    options?: Record<string, boolean | number | string>;
+    /** Explicit-call `agent_start.auth` override. `mode` wins over
+     *  `defaults.adapters.<slug>.auth.mode`; the credential field matching the
+     *  RESOLVED mode wins over the matching config field. Undefined ⇒ falls
+     *  through entirely to the per-adapter config default. */
+    auth?: DefaultsAdapterAuthConfig;
+}
+interface ResolvedSpawnDefaults {
+    skills: string[];
+    options: Record<string, boolean | number | string>;
+    /** RAW billing-auth material (config precedence applied) — fed to the
+     *  descriptor-aware {@link resolveAuthSpec}, which owns the final mode /
+     *  env / scrub / credential-source decision. Both candidate credentials
+     *  are surfaced (NOT collapsed to one), since the ordered-mode selection
+     *  needs to know which are available before it picks the mode. */
+    auth: ResolvedSpawnAuthMaterial;
+}
+interface ResolvedSpawnAuthMaterial {
+    /** Operator-requested mode (per-spawn > per-adapter config), or undefined
+     *  ⇒ let the resolver pick by ordered preference. */
+    requestedMode?: "subscription" | "api-key";
+    /** True when the operator explicitly configured `auth` (per-spawn OR in
+     *  `defaults.adapters.<slug>.auth`). The ONLY way to tell "set mode, no
+     *  key" (fail-fast) from "set nothing" (ambient) — both give no credential.
+     *  DECISION 5. */
+    explicit: boolean;
+    /** Subscription bearer token (per-spawn > config), if configured. */
+    subscriptionCredential?: string;
+    /** Explicit API key (per-spawn > config), if configured — distinct from the
+     *  providers.json store key the resolver fetches separately. */
+    apiKeyCredential?: string;
+    /** Per-spawn provider pin, if given. */
+    provider?: CatalogProvider;
+}
+declare function resolveSpawnDefaults(defaults: SpawnDefaultsConfig | undefined, adapterSlug: string, input: ResolveSpawnDefaultsInput): ResolvedSpawnDefaults;
+/**
+ * Derive a SAFE, non-secret fingerprint for a resolved auth credential —
+ * NEVER the raw value — for recording on the session descriptor / surfacing
+ * in `agentproto sessions --watch` and `agent_sessions_list` (the
+ * "verifiability" requirement: answer "what was used" without exposing the
+ * secret). Format: `<mode> · <shape-prefix>…<last4>` when the shape is known
+ * (e.g. `subscription · sk-ant-oat…3f9c`), else `<mode> · …<last4>`.
+ *
+ * The shape marker is matched from a PUBLIC key-prefix table (longest-match),
+ * not derived from `mode` — see {@link CREDENTIAL_FINGERPRINT_PREFIXES}. Only
+ * the matched prefix + the last 4 characters are ever surfaced, never the
+ * middle (mirrors GitHub's `ghp_…abcd` style).
+ */
+declare function credentialFingerprint(mode: "subscription" | "api-key", credential: string): string;
+/**
+ * The adapter's billing-auth capability, projected from its AIP-45 manifest
+ * (`provider` / `authEnforce` / `authSubscription`) by the host resolver. The
+ * runtime reads THIS, never the manifest directly — keeping the LLM-catalog
+ * coupling in the runtime and the driver mechanical.
+ */
+interface AdapterAuthDescriptor {
+    /** FIXED provider for a single-provider adapter; omitted for by-model
+     *  routers (provider then derives from the requested model). */
+    provider?: CatalogProvider;
+    /** Enforcement policy — `"always"` engages every spawn (claude-code's
+     *  #312 fail-fast); `"when-configured"` (default) only when `explicit`. */
+    authEnforce?: "always" | "when-configured";
+    /** Subscription (OAuth/bearer) support. Presence ⇒ the adapter supports
+     *  `"subscription"` mode. Mirrors the driver's `AgentCliAuthSubscription`. */
+    authSubscription?: {
+        setEnv: string;
+        conflictEnv?: string[];
+        unsetEnvAdd?: string[];
+    };
+}
+/** The fully-resolved spec the driver applies mechanically. Structurally
+ *  matches `@agentproto/driver-agent-cli`'s `ResolvedAuthSpec` (each package
+ *  owns its own copy; the object flows across the boundary by shape). */
+interface ResolvedAuthSpec {
+    mode: "subscription" | "api-key";
+    credential?: string;
+    setEnv: string;
+    unsetEnv: string[];
+    explicit: boolean;
+    enforce: "always" | "when-configured";
+    /** True when NEITHER subscription nor api-key had any credential
+     *  available and `mode` above is therefore an arbitrary fallback pick —
+     *  never true when `mode` came from an explicit request or an actually-
+     *  available credential. Optional (undefined ⇒ false) so existing
+     *  callers/fixtures that predate this field keep working unchanged.
+     *  Exists so a fail-fast message can enumerate BOTH auth paths instead of
+     *  presenting the fallback mode as though the user configured it — the
+     *  root cause of a zero-credential user being told to buy a subscription
+     *  they never asked for. */
+    neitherConfigured?: boolean;
+    /** Non-authenticating hint: true when `providers.json` HAS a key for the
+     *  resolved provider that is currently being ignored because auth isn't
+     *  explicitly configured (no `defaults.adapters.<slug>.auth` block — the
+     *  `explicit` gate above, PR #321). NEVER used to authenticate — set by
+     *  the caller (session-spawn.ts) as a read-only peek, purely so the
+     *  fail-fast message can say "you already have a key, it's just not
+     *  wired in" instead of staying silent about it. `resolveAuthSpec` itself
+     *  never sets this (it does no I/O). */
+    ignoredApiKeyInStore?: boolean;
+}
+/** Where the resolved credential came from — the observable billing axis
+ *  (DECISION 10②), never inferred. */
+type CredentialSource = "explicit-config" | "providers-store" | "none";
+/**
+ * The OBSERVABLE echo (DECISION 9③ / 10②) — recorded on the session
+ * descriptor so a verifier checks the RESOLUTION, never the model's
+ * self-report. Never carries the raw credential (only its fingerprint).
+ */
+interface AuthEcho {
+    provider: CatalogProvider;
+    authMode: "subscription" | "api-key";
+    credentialSource: CredentialSource;
+    setEnv: string;
+    fingerprint?: string;
+}
+/**
+ * Thrown when the operator requested a billing mode the adapter can't serve —
+ * today only `"subscription"` on an adapter with no `authSubscription`. A
+ * LOUD, distinct failure (DECISION 4②), never a silent downgrade to api-key.
+ */
+declare class AuthResolutionError extends Error {
+    readonly code = "unsupported_auth_mode";
+    constructor(message: string);
+}
+interface ResolveAuthSpecInput {
+    descriptor: AdapterAuthDescriptor;
+    /** `input.model ?? adapter default model` — for model-derived provider. */
+    model?: string;
+    /** Per-spawn provider pin (`input.auth.provider`). */
+    requestedProvider?: CatalogProvider;
+    /** Operator-requested mode; undefined ⇒ ordered preference. */
+    requestedMode?: "subscription" | "api-key";
+    /** Operator explicitly configured `auth` (DECISION 5). */
+    explicit: boolean;
+    /** Subscription bearer credential, if configured. */
+    subscriptionCredential?: string;
+    /** Explicit api-key credential from config, if configured. */
+    apiKeyConfigCredential?: string;
+    /** api-key credential from `providers.json` (fetched by the caller). */
+    apiKeyStoreCredential?: string;
+}
+/**
+ * THE billing-auth resolver (DECISIONS 4, 6, 9, 10). Pure: given the adapter
+ * descriptor + raw config material + (caller-fetched) store key, it decides
+ * the provider, the mode (ordered — subscription over api-key when a
+ * subscription credential is present; a requested-but-unsupported mode throws
+ * `unsupported_auth_mode`), the env var to SET, the derived SCRUB set, and the
+ * credential + its source. Returns the driver `spec` + the observable `echo`,
+ * or `undefined` when no provider resolves (⇒ ambient, no injection — never
+ * guess). NEVER falls back to a default provider/model. Fail-loud on a
+ * configured-but-missing credential is deferred to the driver's mechanical
+ * apply (it engages then throws `missing_auth_credential`), so the `explicit`
+ * / `enforce` signals are carried through on the spec.
+ */
+declare function resolveAuthSpec(input: ResolveAuthSpecInput): {
+    spec: ResolvedAuthSpec;
+    echo: AuthEcho;
+} | undefined;
+/** Manifest-declared AIP-45 option id + type, the minimum an adapter
+ *  resolver needs to expose for `normalizeSkillsOption` below. Mirrors
+ *  `AgentCliOption`'s `id`/`type` fields without importing
+ *  `@agentproto/driver-agent-cli` into the runtime package. */
+interface DeclaredAdapterOption {
+    id: string;
+    type: "boolean" | "integer" | "string" | "enum";
+}
+/**
+ * Fold the resolved `skills` list into `options.skills` using whatever
+ * shape the adapter's manifest declares for that option id (today, only
+ * `type: "string"` exists for a skills-shaped option — e.g. hermes'
+ * comma-joined `--skills a,b`). Adapters with no declared `skills` option
+ * (e.g. claude-code, which auto-discovers from `~/.claude/skills`) are a
+ * documented no-op — the effective skills list has nowhere to go, so it's
+ * dropped rather than guessing a flag the manifest didn't declare.
+ *
+ * An `options.skills` already present (from config defaults or the
+ * explicit call) is respected as-is and never overwritten here.
+ */
+declare function normalizeSkillsOption(skills: string[], options: Record<string, boolean | number | string>, declaredOptions: readonly DeclaredAdapterOption[] | undefined): Record<string, boolean | number | string>;
+
+/**
+ * `~/.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;
+}
+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;
+}
+/**
+ * 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;
+}
+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;
+}
+/**
+ * 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[];
+    };
+    /** 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;
+    /** 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>;
+/**
+ * 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 AdapterAuthDescriptor as A, type CredentialSource as C, type DeclaredAdapterOption as D, type FeaturesConfig as F, type PairingConfig as P, type ResolvedAuthSpec as R, type SpawnDefaultsConfig as S, type TerminalPreset as T, type WorktreeIsolationMode as W, type AuthEcho as a, AuthResolutionError as b, type DefaultsAdapterAuthConfig as c, type DefaultsAdapterConfig as d, type ResolvedSpawnAuthMaterial as e, type ResolvedSpawnDefaults as f, credentialFingerprint as g, resolveSpawnDefaults as h, type AcpAgentConfigEntry as i, type AgentprotoConfig as j, CONFIG_FILE_PATH as k, CONFIG_VERSION as l, type DaemonConfig as m, normalizeSkillsOption as n, type ProfileConfig as o, type TunnelConfig as p, type WorktreesConfig as q, resolveAuthSpec as r, getConfigKey as s, loadConfig as t, saveConfig as u, setConfigKey as v };