@agentproto/runtime 3.6.1 → 4.1.0

package/dist/session-story.d.ts

@@ -26,6 +26,16 @@
 interface ExportedMessage {
     role: "user" | "assistant" | "tool" | "system";
     text?: string;
+    /** Set on a `user`-role message that is a typed inter-session message
+     *  (a `session-message` record) rather than the human: the daemon-attested
+     *  sender. Absent for a human prompt. */
+    from?: {
+        sessionId?: string;
+        label?: string;
+        relation: "child" | "parent" | "sibling" | "human" | "system";
+        kind: string;
+        messageId: string;
+    };
     reasoning?: string;
     toolName?: string;
     toolCalls?: {

package/dist/{spawn-defaults-CwI9Puwy.d.ts → spawn-defaults-CZj39Znq.d.ts}

@@ -1,5 +1,107 @@
+import { C as ContextContinuityPolicy, S as SpawnBrowserMode } from './context-continuity-Bn99UtVC.js';
 import { CatalogProvider } from '@agentproto/model-catalog';
-import { C as ContextContinuityPolicy } from './context-continuity-ib9_bVYM.js';
+
+/**
+ * Deferred/lazy MCP tool loading (harness-parity item 3).
+ *
+ * Motivation: a root `/mcp` session sees every tool the daemon registers —
+ * today that's 60+ tools across families (agent_*, session_*, policy_*,
+ * routine_*, workflow_*, terminal_*, command_*, file_*, directory_*,
+ * browser_*, tunnel_*, mcp_*, inbound_watcher_*) — all with full schemas,
+ * loaded upfront, whether or not the session ever touches most of them.
+ *
+ * NB: imported third-party MCP servers (`mcp_import`) do NOT have this
+ * problem — they're already proxied behind `mcp_imported_tool_list` /
+ * `mcp_imported_call` (session-tools.ts), a search-then-call pattern that
+ * never mounts an upstream server's tools directly. This module addresses
+ * the daemon's OWN gateway tools, the part of the surface still eager.
+ *
+ * ## Why this does NOT use the SDK's enable()/disable()
+ *
+ * `@modelcontextprotocol/sdk` 1.29.0's `server.tool(...)` returns a
+ * `RegisteredTool` with `.enable()`/`.disable()`, `tools/list` filters on
+ * `.enabled`, and the server auto-advertises `tools: { listChanged: true }`
+ * — a real, SDK-supported dynamic-registration mechanism. An earlier draft
+ * of this module used exactly that: register tools disabled, `.enable()`
+ * them from `tool_search`.
+ *
+ * It does not work here. `http-server.ts` documents (and a live daemon
+ * run confirmed): "MCP transport: stateless mode for v1 — each request is
+ * independent" — a FRESH `McpServer` is built via `mcpServerFactory()` for
+ * EVERY request, including `tools/call`. An `.enable()` mutation made
+ * during a `tool_search` call lives only on that call's own throwaway
+ * server instance; the very next `tools/call` for the newly-"enabled"
+ * tool gets a brand-new instance where it's disabled again, and fails
+ * with `Tool X disabled`. Confirmed by running exactly that sequence
+ * against a live gateway — the mutation never survives past the request
+ * that made it, so a real orchestrator would search successfully, read
+ * a schema, then have the follow-up call rejected. Worse than doing
+ * nothing: it looks like it works, right up until the second call.
+ *
+ * ## What this does instead
+ *
+ * Every tool stays fully registered AND enabled (`tools/call` always
+ * works for any tool name, deferred or not — the daemon is stateless
+ * regardless, so there is no session-scoped "have they earned the right
+ * to call this" state to enforce even if it were desirable). "Deferred"
+ * only means: excluded from the `tools/list` response, so a session
+ * doesn't pay the schema-loading token tax for tools it never asked
+ * about. The `tools/list` handler is overridden directly on the
+ * underlying low-level `Server` (`mcpServer.server.setRequestHandler` —
+ * the SDK's own documented escape hatch: "For advanced usage ... use the
+ * underlying Server instance") to return only the `alwaysOn` set plus
+ * `tool_search` itself; this is a pure per-request read, so it's
+ * naturally correct under statelessness — there's no history to lose.
+ * `tool_search` matches a keyword (or `select:name1,name2` for exact
+ * names) against a catalog of every OTHER registered tool and returns
+ * full JSON Schema for the hits directly in its own result text — the
+ * one channel that reliably survives the stateless boundary, since it's
+ * read from the SAME call that produced it.
+ *
+ * Opt-in and backward-compatible by construction: nothing calls this
+ * unless a host explicitly wires `deferredTools` into `createGateway` —
+ * see `index.ts`. Every existing daemon keeps registering (and exposing)
+ * everything eagerly, exactly as before.
+ *
+ * Both SDK registration entry points are intercepted — `server.tool(...)`
+ * AND `server.registerTool(...)` (the config-object overload; e.g.
+ * mcp-apps-adapter.ts's `agentproto_sessions` panel tool uses the latter,
+ * and would silently skip the catalog if only one were patched).
+ *
+ * Tools registered on the server BEFORE it's wrapped — e.g. `self_inspect`,
+ * added inside `@agentproto/mcp-server`'s `createMcpServer()` — are
+ * automatically excluded from `tools/list` too: the override only lists
+ * names present in `registry` (built from tools that passed through the
+ * proxy), so anything registered earlier is simply absent from that set,
+ * with no extra bookkeeping needed. They stay fully callable, same as
+ * every other tool here — the override only ever touches what `tools/list`
+ * shows.
+ */
+
+/**
+ * `~/.agentproto/config.json`'s `defaults.mcp.deferredTools` shape —
+ * `false`/absent (the default) keeps every daemon boot eager, byte-identical
+ * to pre-existing behaviour. `true` turns deferred tools on gateway-wide
+ * using the daemon's own default always-on set (see `DEFAULT_ALWAYS_ON_TOOLS`
+ * in index.ts). `{ alwaysOn }` turns it on with a custom always-on set
+ * instead of the default one.
+ */
+type DeferredToolsConfig = boolean | {
+    alwaysOn: string[];
+};
+/**
+ * Convert the config-file value (tri-state: off / on-with-default /
+ * on-with-custom-set) into the shape `CreateGatewayOptions.deferredTools`
+ * expects. Pure — no fs, easy to unit test independent of `loadConfig`.
+ * `undefined`/`false` ⇒ `undefined` (omit the key entirely, so
+ * `createGateway` never wraps `withDeferredTools` — today's eager
+ * behaviour). `true` ⇒ `{}` (deferred, `alwaysOn` left for the gateway's
+ * own `DEFAULT_ALWAYS_ON_TOOLS` fallback). `{ alwaysOn }` ⇒ passed through
+ * verbatim.
+ */
+declare function resolveDeferredToolsGatewayOption(config: DeferredToolsConfig | undefined): {
+    alwaysOn?: readonly string[];
+} | undefined;
 
 /**
  * Pure resolver for `~/.agentproto/config.json`'s `defaults` block —
@@ -25,6 +127,22 @@ import { C as ContextContinuityPolicy } from './context-continuity-ib9_bVYM.js';
  *     store — never read from the ambient shell env.
  */
 
+/**
+ * `defaults.mcp` block — daemon-wide MCP gateway policy, distinct from the
+ * per-adapter spawn defaults above (it's read once at daemon boot, not
+ * per-spawn — see `serve.ts`'s `createGateway({ deferredTools })` call).
+ */
+interface McpDefaultsConfig {
+    /** Gateway-wide deferred/lazy `tools/list` loading (harness-parity item
+     *  3 — see `deferred-tools.ts`). Default false/absent: every daemon boot
+     *  stays eager, byte-identical to pre-existing behaviour — turning this
+     *  on is a deliberate operator opt-in. Independent of the per-role
+     *  default (`RoleProfile.deferredTools`, on for `executor`) and the
+     *  per-spawn `agent_start.deferredTools` override, and independent of
+     *  the per-mount `?deferred=1|0` query override on `/mcp` — this is only
+     *  the BOOT-TIME default for connections that specify neither. */
+    deferredTools?: DeferredToolsConfig;
+}
 /**
  * Deterministic billing-auth config for one adapter slug (today, only
  * claude-code interprets it — see `AgentCliStartOptions.auth` in
@@ -95,6 +213,14 @@ interface SpawnDefaultsConfig {
      *  omits `trace`. Default false — sessions trace only when they opt in or
      *  this is on. See `filterSessionObserver` / `SpawnAgentInput.trace`. */
     langfuseTracing?: boolean;
+    /** Wake an idle agent session when one of its background tasks settles
+     *  (see `SessionsRegistryOptions.backgroundTaskWake`). On by default;
+     *  `{ enabled: false }` opts out. `graceMs` is how long the daemon waits
+     *  for the agent to wake ITSELF (Claude Code does) before prompting it. */
+    backgroundTaskWake?: {
+        enabled?: boolean;
+        graceMs?: number;
+    };
     /** 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). */
@@ -107,6 +233,24 @@ interface SpawnDefaultsConfig {
      *  EXPLICIT `interrupt` on the call (true OR false) always wins over this
      *  default. */
     agentPromptInterrupt?: boolean;
+    /** Inter-session messaging policy (AIP-46 §Session messages). */
+    messaging?: {
+        /** Let `message_send` / `message_reply` reach a sibling session (same
+         *  parent). Default false — only child↔parent. */
+        allowSiblings?: boolean;
+        /** Whether a SESSION sender may use urgency `interrupt` (cancel the
+         *  recipient's in-flight turn). Default "deny": downgraded to `steer`
+         *  and reported as such. Human (HTTP/CLI) senders always may. */
+        agentInterrupt?: "allow" | "deny";
+    };
+    /** Daemon-wide MCP gateway policy. See {@link McpDefaultsConfig}. */
+    mcp?: McpDefaultsConfig;
+    /** Spawn-shape defaults applied when neither the `agent_start` call, its
+     *  role nor its user preset says otherwise. */
+    spawn?: {
+        /** Default `agent_start.browser` (`"headless"` | `false`). Default off. */
+        browser?: SpawnBrowserMode;
+    };
 }
 interface ResolveSpawnDefaultsInput {
     /** Explicit-call `skills`. Undefined ⇒ caller expressed no preference,
@@ -433,4 +577,4 @@ interface DeclaredAdapterOption {
  */
 declare function normalizeSkillsOption(skills: string[], options: Record<string, boolean | number | string>, declaredOptions: readonly DeclaredAdapterOption[] | undefined): Record<string, boolean | number | string>;
 
-export { type AdapterAuthDescriptor as A, CLAUDE_CODE_OAUTH_SOURCE as C, type DeclaredAdapterOption as D, type ResolvedAuthSpec as R, type SpawnDefaultsConfig as S, type AuthEcho as a, AuthResolutionError as b, type CredentialSource as c, type DefaultsAdapterAuthConfig as d, type DefaultsAdapterConfig as e, type ResolveSubscriptionCredentialInput as f, type ResolvedSpawnAuthMaterial as g, type ResolvedSpawnDefaults as h, type SubscriptionCredentialResolution as i, SubscriptionSourceError as j, credentialFingerprint as k, resolveSpawnDefaults as l, resolveSubscriptionCredential as m, normalizeSkillsOption as n, resolveAuthSpec as r };
+export { type AdapterAuthDescriptor as A, CLAUDE_CODE_OAUTH_SOURCE as C, type DefaultsAdapterAuthConfig as D, type ResolvedAuthSpec as R, type SpawnDefaultsConfig as S, type DeclaredAdapterOption as a, type AuthEcho as b, AuthResolutionError as c, type CredentialSource as d, type DefaultsAdapterConfig as e, type DeferredToolsConfig as f, type ResolveSubscriptionCredentialInput as g, type ResolvedSpawnAuthMaterial as h, type ResolvedSpawnDefaults as i, type SubscriptionCredentialResolution as j, SubscriptionSourceError as k, credentialFingerprint as l, resolveDeferredToolsGatewayOption as m, normalizeSkillsOption as n, resolveSpawnDefaults as o, resolveSubscriptionCredential as p, resolveAuthSpec as r };

package/dist/user-presets.d.ts

@@ -1,7 +1,9 @@
 import { z } from 'zod';
-import { S as SessionConfig, R as RouteSpec, P as Posture, E as EffortLevel, C as ContextProfile } from './session-config-DbWP9RRj.js';
+import { S as SessionConfig, R as RouteSpec, P as Posture, E as EffortLevel, C as ContextProfile } from './session-config-ByfVeEQJ.js';
+import { S as SpawnBrowserMode } from './context-continuity-Bn99UtVC.js';
 import '@agentproto/auth';
-import './context-continuity-ib9_bVYM.js';
+import '@agentproto/acp';
+import '@agentproto/command-sandbox';
 
 /**
  * User-owned spawn presets.
@@ -38,6 +40,9 @@ interface UserPreset extends Partial<SessionConfig> {
      *  `SpawnAgentSessionInput.skills`. Omitted means the adapter/defaults
      *  decide. */
     skills?: string[];
+    /** `agent_start.browser` for spawns from this preset. Ranks below the
+     *  role's own default (see `resolveBrowserMode`). */
+    browser?: SpawnBrowserMode;
 }
 declare const userPresetsFileSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
@@ -74,6 +79,7 @@ declare const userPresetsFileSchema: z.ZodObject<{
         contextProfile: z.ZodOptional<z.ZodString>;
         cwd: z.ZodOptional<z.ZodString>;
         skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        browser: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"headless">, z.ZodLiteral<false>]>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 type UserPresetsFile = z.infer<typeof userPresetsFileSchema>;

package/dist/user-presets.mjs

@@ -29,7 +29,8 @@ var userPresetSchema = z.object({
   effort: effortSchema.optional(),
   contextProfile: z.string().min(1).optional(),
   cwd: z.string().min(1).optional(),
-  skills: z.array(z.string().min(1)).optional()
+  skills: z.array(z.string().min(1)).optional(),
+  browser: z.union([z.literal("headless"), z.literal(false)]).optional()
 });
 var userPresetsFileSchema = z.object({
   version: z.literal(1),

package/dist/user-presets.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/user-presets.ts"],"names":[],"mappings":"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","file":"user-presets.mjs","sourcesContent":["/**\n * User-owned spawn presets.\n *\n * This is deliberately separate from `preset-tools.ts`: provider presets are\n * static gateway definitions shipped by packages, while a UserPreset is a\n * private saved combination of the orthogonal session-config axes.\n */\n\nimport { mkdir, readFile, writeFile } from \"node:fs/promises\"\nimport { homedir } from \"node:os\"\nimport { join, resolve } from \"node:path\"\nimport { z } from \"zod\"\nimport type {\n  ContextProfile,\n  EffortLevel,\n  Posture,\n  RouteSpec,\n  SessionConfig,\n} from \"./session-config.js\"\n\nconst effortSchema = z.enum([\"low\", \"medium\", \"high\", \"xhigh\", \"max\", \"ultracode\"])\nconst postureSchema = z.union([\n  z.enum([\"default\", \"plan\", \"accept-edits\", \"bypass\", \"read-only\"]),\n  z.object({ harnessModeId: z.string().min(1) }),\n])\nconst routeSchema = z.object({\n  gateway: z.string().min(1),\n  baseUrl: z.string().url().optional(),\n})\n\n/** A reusable, user-scoped subset of the spawn/session config axes. */\nexport interface UserPreset extends Partial<SessionConfig> {\n  /** Stable machine-local id, e.g. `fast-deepseek`. */\n  id: string\n  /** Human-readable name shown by CLI and editor pickers. */\n  label: string\n  /** Adapter harness to use. Omitted means the caller selects one. */\n  adapter?: string\n  /** Canonical harness slug — alias for `adapter`. */\n  harness?: string\n  model?: string\n  route?: RouteSpec\n  access?: { profileRef?: string }\n  posture?: Posture\n  effort?: EffortLevel\n  contextProfile?: ContextProfile\n  /** Working directory the favorite pins to. When set, a spawn from this\n   *  preset lands here regardless of the caller's active folder — the axis\n   *  that makes a favorite fully location-pinned (true zero-input). Omitted\n   *  means the caller's cwd ladder resolves it as before. */\n  cwd?: string\n  /** Skills to preload for a spawn from this preset — the same axis as\n   *  `SpawnAgentSessionInput.skills`. Omitted means the adapter/defaults\n   *  decide. */\n  skills?: string[]\n}\n\nconst userPresetSchema = z.object({\n  id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),\n  label: z.string().min(1),\n  adapter: z.string().min(1).optional(),\n  harness: z.string().min(1).optional(),\n  model: z.string().min(1).optional(),\n  route: routeSchema.optional(),\n  access: z.object({ profileRef: z.string().min(1).optional() }).optional(),\n  posture: postureSchema.optional(),\n  effort: effortSchema.optional(),\n  contextProfile: z.string().min(1).optional(),\n  cwd: z.string().min(1).optional(),\n  skills: z.array(z.string().min(1)).optional(),\n}) satisfies z.ZodType<UserPreset>\n\nconst userPresetsFileSchema = z.object({\n  version: z.literal(1),\n  presets: z.array(userPresetSchema),\n})\n\nexport type UserPresetsFile = z.infer<typeof userPresetsFileSchema>\n\nfunction emptyFile(): UserPresetsFile {\n  return { version: 1, presets: [] }\n}\n\nexport function userPresetsPath(): string {\n  return resolve(homedir(), \".agentproto\", \"presets.json\")\n}\n\n/** Missing or malformed user config is treated as empty — a bad preset must\n * never prevent the daemon from starting. Writes always restore valid JSON. */\nexport async function loadUserPresets(): Promise<UserPresetsFile> {\n  try {\n    return userPresetsFileSchema.parse(JSON.parse(await readFile(userPresetsPath(), \"utf8\")))\n  } catch {\n    return emptyFile()\n  }\n}\n\nasync function writeUserPresets(file: UserPresetsFile): Promise<void> {\n  const dir = join(homedir(), \".agentproto\")\n  await mkdir(dir, { recursive: true })\n  await writeFile(userPresetsPath(), JSON.stringify(file, null, 2) + \"\\n\", {\n    encoding: \"utf8\",\n    mode: 0o600,\n  })\n}\n\nexport async function listUserPresets(): Promise<UserPreset[]> {\n  return (await loadUserPresets()).presets\n}\n\nexport async function getUserPreset(id: string): Promise<UserPreset | undefined> {\n  return (await loadUserPresets()).presets.find(preset => preset.id === id)\n}\n\n/** Add or replace a preset by id. The parser makes this the single validation\n * boundary for CLI, MCP and editor callers. */\nexport async function saveUserPreset(preset: UserPreset): Promise<void> {\n  const validated = userPresetSchema.parse(preset)\n  const file = await loadUserPresets()\n  const index = file.presets.findIndex(existing => existing.id === validated.id)\n  if (index === -1) file.presets.push(validated)\n  else file.presets[index] = validated\n  await writeUserPresets(file)\n}\n\nexport async function deleteUserPreset(id: string): Promise<boolean> {\n  const file = await loadUserPresets()\n  const index = file.presets.findIndex(preset => preset.id === id)\n  if (index === -1) return false\n  file.presets.splice(index, 1)\n  await writeUserPresets(file)\n  return true\n}\n"]}
+{"version":3,"sources":["../src/user-presets.ts"],"names":[],"mappings":"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","file":"user-presets.mjs","sourcesContent":["/**\n * User-owned spawn presets.\n *\n * This is deliberately separate from `preset-tools.ts`: provider presets are\n * static gateway definitions shipped by packages, while a UserPreset is a\n * private saved combination of the orthogonal session-config axes.\n */\n\nimport { mkdir, readFile, writeFile } from \"node:fs/promises\"\nimport { homedir } from \"node:os\"\nimport { join, resolve } from \"node:path\"\nimport { z } from \"zod\"\nimport type {\n  ContextProfile,\n  EffortLevel,\n  Posture,\n  RouteSpec,\n  SessionConfig,\n} from \"./session-config.js\"\nimport type { SpawnBrowserMode } from \"./browser-mount.js\"\n\nconst effortSchema = z.enum([\"low\", \"medium\", \"high\", \"xhigh\", \"max\", \"ultracode\"])\nconst postureSchema = z.union([\n  z.enum([\"default\", \"plan\", \"accept-edits\", \"bypass\", \"read-only\"]),\n  z.object({ harnessModeId: z.string().min(1) }),\n])\nconst routeSchema = z.object({\n  gateway: z.string().min(1),\n  baseUrl: z.string().url().optional(),\n})\n\n/** A reusable, user-scoped subset of the spawn/session config axes. */\nexport interface UserPreset extends Partial<SessionConfig> {\n  /** Stable machine-local id, e.g. `fast-deepseek`. */\n  id: string\n  /** Human-readable name shown by CLI and editor pickers. */\n  label: string\n  /** Adapter harness to use. Omitted means the caller selects one. */\n  adapter?: string\n  /** Canonical harness slug — alias for `adapter`. */\n  harness?: string\n  model?: string\n  route?: RouteSpec\n  access?: { profileRef?: string }\n  posture?: Posture\n  effort?: EffortLevel\n  contextProfile?: ContextProfile\n  /** Working directory the favorite pins to. When set, a spawn from this\n   *  preset lands here regardless of the caller's active folder — the axis\n   *  that makes a favorite fully location-pinned (true zero-input). Omitted\n   *  means the caller's cwd ladder resolves it as before. */\n  cwd?: string\n  /** Skills to preload for a spawn from this preset — the same axis as\n   *  `SpawnAgentSessionInput.skills`. Omitted means the adapter/defaults\n   *  decide. */\n  skills?: string[]\n  /** `agent_start.browser` for spawns from this preset. Ranks below the\n   *  role's own default (see `resolveBrowserMode`). */\n  browser?: SpawnBrowserMode\n}\n\nconst userPresetSchema = z.object({\n  id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),\n  label: z.string().min(1),\n  adapter: z.string().min(1).optional(),\n  harness: z.string().min(1).optional(),\n  model: z.string().min(1).optional(),\n  route: routeSchema.optional(),\n  access: z.object({ profileRef: z.string().min(1).optional() }).optional(),\n  posture: postureSchema.optional(),\n  effort: effortSchema.optional(),\n  contextProfile: z.string().min(1).optional(),\n  cwd: z.string().min(1).optional(),\n  skills: z.array(z.string().min(1)).optional(),\n  browser: z.union([z.literal(\"headless\"), z.literal(false)]).optional(),\n}) satisfies z.ZodType<UserPreset>\n\nconst userPresetsFileSchema = z.object({\n  version: z.literal(1),\n  presets: z.array(userPresetSchema),\n})\n\nexport type UserPresetsFile = z.infer<typeof userPresetsFileSchema>\n\nfunction emptyFile(): UserPresetsFile {\n  return { version: 1, presets: [] }\n}\n\nexport function userPresetsPath(): string {\n  return resolve(homedir(), \".agentproto\", \"presets.json\")\n}\n\n/** Missing or malformed user config is treated as empty — a bad preset must\n * never prevent the daemon from starting. Writes always restore valid JSON. */\nexport async function loadUserPresets(): Promise<UserPresetsFile> {\n  try {\n    return userPresetsFileSchema.parse(JSON.parse(await readFile(userPresetsPath(), \"utf8\")))\n  } catch {\n    return emptyFile()\n  }\n}\n\nasync function writeUserPresets(file: UserPresetsFile): Promise<void> {\n  const dir = join(homedir(), \".agentproto\")\n  await mkdir(dir, { recursive: true })\n  await writeFile(userPresetsPath(), JSON.stringify(file, null, 2) + \"\\n\", {\n    encoding: \"utf8\",\n    mode: 0o600,\n  })\n}\n\nexport async function listUserPresets(): Promise<UserPreset[]> {\n  return (await loadUserPresets()).presets\n}\n\nexport async function getUserPreset(id: string): Promise<UserPreset | undefined> {\n  return (await loadUserPresets()).presets.find(preset => preset.id === id)\n}\n\n/** Add or replace a preset by id. The parser makes this the single validation\n * boundary for CLI, MCP and editor callers. */\nexport async function saveUserPreset(preset: UserPreset): Promise<void> {\n  const validated = userPresetSchema.parse(preset)\n  const file = await loadUserPresets()\n  const index = file.presets.findIndex(existing => existing.id === validated.id)\n  if (index === -1) file.presets.push(validated)\n  else file.presets[index] = validated\n  await writeUserPresets(file)\n}\n\nexport async function deleteUserPreset(id: string): Promise<boolean> {\n  const file = await loadUserPresets()\n  const index = file.presets.findIndex(preset => preset.id === id)\n  if (index === -1) return false\n  file.presets.splice(index, 1)\n  await writeUserPresets(file)\n  return true\n}\n"]}

package/docs/TRANSMITTER.md

@@ -0,0 +1,356 @@
+# The agentpush ⇄ agentproto transmitter
+
+Bidirectional bridge between an imported agentpush MCP server (Telegram,
+etc.) and a live agentproto session: outbound sends can bind a contact to
+the session that sent them, and inbound replies from that contact then
+route straight into the SAME session — as a real user turn — instead of
+spawning a brand-new agent every time.
+
+## The model
+
+A single `TransmitterBindingStore` (`transmitter-bindings.ts`) maps
+
+```
+(alias, source, contactRef) -> { sessionId, mode, provider?, lastSeenTs }
+```
+
+- `alias` — the imported MCP alias (agentpush) or bot token alias (telegram).
+- `source` — the channel/phone/chat id the message is scoped to.
+- `contactRef` — the sender's id within that source.
+- `sessionId` — the agentproto session future inbound replies from this
+  contact should route into.
+- `mode` — the routing mode this binding was created under (`"route"` or
+  `"route-or-spawn"; see below).
+- `provider` — the outbound provider this binding was created through
+  (`"agentpush"`, `"telegram"`, etc.). Defaults to `"agentpush"` for
+  backward compatibility.
+
+One shared store instance is constructed in `index.ts` and injected into
+three places: the inbound poll watcher, the `transmit_message` tool, and
+the `POST /inbound` push route. Bindings persist (debounced JSON write) to
+`~/.agentproto/transmitter-bindings.json`, load-on-construct, and start
+empty on a missing/corrupt file rather than throwing.
+
+## Outbound provider abstraction
+
+`sendOutbound` in `outbound-adapters.ts` is the provider-agnostic send primitive.
+It mirrors `inbound-adapters.ts` on the read side: a single dispatch function
+that branches by `OutboundProvider` ("agentpush", "telegram", "whatsapp",
+"slack", "generic", "native"). Adding a new outbound dialect means adding a case
+to the switch in `sendOutbound` — the MCP tool and HTTP routes stay unchanged.
+
+## Outbound: `transmit_message`
+
+MCP tool that sends a message out through a provider-specific outbound channel
+and, by default, binds the recipient to the calling session:
+
+```json
+{
+  "provider": "agentpush",
+  "alias": "agentpush",
+  "source": "+33600000000",
+  "contact_ref": "alice",
+  "text": "your PR is ready for review",
+  "sessionId": "sess_abc123",
+  "bind": true
+}
+```
+
+- `provider` — optional, defaults to `"agentpush"`. Supported values:
+  `"agentpush"`, `"telegram"`, `"whatsapp"`, `"slack"`, `"generic"`, `"native"`.
+- `alias` — for `agentpush`, the imported MCP alias (required). For
+  `telegram`, the bot-token alias (defaults to `"default"`).
+- `source` — for `agentpush`, the channel/phone. For `telegram`, the chat id.
+- `contact_ref` — recipient id (`agentpush` contact_ref) or chat id (`telegram`).
+- `text` — message text. Optional when `attachments` is provided; at least one
+  of `text` or `attachments` is required.
+- `attachments` — optional array of local files to send as media:
+  ```json
+  {
+    "type": "photo",
+    "path": "/tmp/screenshot.png",
+    "caption": "optional caption"
+  }
+  ```
+  Supported types: `photo`, `document`, `video`, `audio`. Multiple attachments
+  are sent as an album/media group where the provider supports it.
+- `bind` defaults to `true` — on a successful send, upserts a binding
+  `(alias, source, contact_ref) -> sessionId` with `mode: "route-or-spawn"` and
+  the chosen `provider`. Pass `bind: false` to send without binding.
+- Returns `{ sent: boolean, bound: boolean, message_id?: string }` on success,
+  or `{ sent: false, bound: false, error: string, blocked_reason?: string,
+  suggestion?: string }` on failure. A send failure (`sent: false`) never
+  binds. `message_id` is the provider's own id for the sent message — pass it
+  to `check_delivery` to verify the send landed.
+- **agentpush never throws for a send it can't make** — it replies HTTP 200
+  with `status: "blocked"` (opt-out, expired session, unapproved template…)
+  or `status: "failed"`. `transmit_message` reads that status instead of
+  treating MCP transport success as delivery: a `blocked` or `failed` reply
+  is surfaced as `sent: false` with `blocked_reason`/`suggestion` (or
+  `error`) propagated, never as a false `sent: true`. Telegram gets the same
+  treatment for its own backward-compat case — an HTTP 200 body with
+  `ok: false` is also reported as `sent: false`, not `sent: true`.
+
+### Provider-specific behaviour
+
+**agentpush** calls the real `send_message` MCP tool on the imported alias:
+```json
+{
+  "to": { "channel": "<source>", "address": "<contact_ref>" },
+  "content": { "text": "<text>" }
+}
+```
+
+When `attachments` are provided, each file is first uploaded via
+`upload_media` (channel = `<source>`), then referenced by `providerMediaId`
+in `content.media`:
+```json
+{
+  "to": { "channel": "<source>", "address": "<contact_ref>" },
+  "content": {
+    "text": "<text>",
+    "media": [
+      { "type": "image", "providerMediaId": "<media_id>", "caption": "..." }
+    ]
+  }
+}
+```
+
+**telegram** POSTs directly to the Telegram Bot API. Text-only messages use
+`sendMessage`:
+```
+POST https://api.telegram.org/bot<token>/sendMessage
+{ "chat_id": "<source>", "text": "<text>" }
+```
+
+With one attachment, the matching method is used (`sendPhoto`,
+`sendDocument`, `sendVideo`, or `sendAudio`) with a `multipart/form-data`
+body. With several attachments, `sendMediaGroup` is used. The bot token is
+resolved from a `TelegramBotCredsStore` (configured separately via
+`telegram_bot_token_set`).
+
+### Telegram bot wiring recipe
+
+1. Create the bot with @BotFather and copy the token.
+2. Store the token in the daemon's credential store:
+   ```json
+   { "tool": "telegram_bot_token_set", "arguments": { "token": "..." } }
+   ```
+3. Create a provider-agnostic inbound endpoint:
+   ```json
+   {
+     "tool": "inbound_endpoint_create",
+     "arguments": {
+       "slug": "telegram-agentproto",
+       "provider": "telegram",
+       "alias": "default",
+       "mode": "route-or-spawn"
+     }
+   }
+   ```
+   The response includes the endpoint `secret`.
+4. Start the narrow public ingress proxy (see below) and get its public URL.
+5. Point Telegram's webhook at the proxy:
+   ```json
+   {
+     "tool": "telegram_bot_set_webhook",
+     "arguments": {
+       "url": "https://<proxy-public-url>/inbound/telegram-agentproto",
+       "secret_token": "<endpoint-secret>"
+     }
+   }
+   ```
+
+## Inbound routing modes
+
+Both the poll watcher (`inbound-watcher.ts`, `inbound_watcher_start`'s
+`mode` field) and `POST /inbound` share one decision function,
+`routeInboundMessage` (`inbound-router.ts`):
+
+| mode | binding exists, session alive | binding exists, session dead | no binding |
+|---|---|---|---|
+| `spawn` (poll watcher default) | *(ignored)* spawns a fresh agent | *(ignored)* spawns a fresh agent | spawns a fresh agent |
+| `route` | routes into it (`"routed"`) | resurrects it, then routes (`"restarted-routed"`) | skips (`"skipped"`) |
+| `route-or-spawn` (`POST /inbound` default) | routes into it (`"routed"`) | resurrects it, then routes (`"restarted-routed"`) | spawns a fresh agent if a spawn path is configured, else skips |
+
+"Resurrects" means: an agent-cli session that's no longer alive is
+restarted in place (same primitive `cron-scheduler.ts`'s `prompt-session`
+job uses — `restartAgentSession(..., { forceAgentResume: true })`), and the
+reply is delivered to the (possibly new) resulting session id. A session
+counts as alive unless it's missing entirely or its `processAlive` field
+is explicitly `false` — a pid-less ACP-native/remote session (no OS
+process to probe) is treated as alive, not dead.
+
+Every successful route into a bound session refreshes that binding's
+`lastSeenTs`.
+
+## `POST /inbound` — push ingress contract
+
+Bearer-gated exactly like the mutating `/sessions/*` routes (read the
+token from `<workspace>/.agentproto/runtime.json`):
+
+```
+POST /inbound
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "alias": "agentpush",
+  "source": "+33600000000",
+  "contact_ref": "alice",
+  "text": "sounds good, ship it",
+  "messages": [ /* optional: raw agentpush events, for the spawn-fallback template */ ],
+  "mode": "route-or-spawn"        // optional, default "route-or-spawn"
+}
+```
+
+Responses:
+
+- `200 { "action": "routed" | "spawned" | "restarted-routed" | "skipped", "sessionId"?: string }`
+- `400` — a required field (`alias`/`source`/`contact_ref`/`text`) is
+  missing, or `mode` isn't one of the three valid values.
+- `401` — missing/invalid bearer token.
+- `501` — the daemon wasn't wired with a `routeInboundMessage` handler
+  (i.e. `POST /inbound` isn't enabled on this host).
+
+Note: the daemon's own wiring never sets a `spawnForContact` for this
+route — an unauthenticated webhook payload carries no adapter/prompt
+template to spawn an agent with, so an unbound contact under
+`route-or-spawn` is `"skipped"` rather than spawning an arbitrary agent
+from push input. Only the poll watcher (which already has an
+`adapter`/`promptTemplate` configured via `inbound_watcher_start`) spawns.
+
+## Simulating an inbound message
+
+### 1. The sim script (no live daemon needed)
+
+`packages/runtime/scripts/simulate-inbound.mjs` composes the real wiring
+in-process — real `SessionsRegistry`, real `TransmitterBindingStore`, real
+`routeInboundMessage`, real `startHttpServer` — with one fake session
+double standing in for a real adapter, so you can see the whole path
+(HTTP → routing → the session actually receiving the turn) without an
+agentpush server, an adapter install, or a running daemon:
+
+```sh
+pnpm --filter @agentproto/runtime sim:inbound
+# or with overrides:
+pnpm --filter @agentproto/runtime sim:inbound -- --contact=bob --text="ping from bob"
+```
+
+Flags (or matching env vars `ALIAS`/`SOURCE`/`CONTACT`/`TEXT`/
+`SESSION_ID`/`PORT`/`TOKEN`): `--alias`, `--source`, `--contact`, `--text`,
+`--session-id`, `--port`, `--token`. It prints the HTTP status, the
+`{action, sessionId}` response, and the exact text the bound session
+received, then exits non-zero if either doesn't match expectations.
+
+### 2. `curl` against a live daemon
+
+Bind a contact first (via `transmit_message`, or by hand-seeding
+`~/.agentproto/transmitter-bindings.json`), then:
+
+```sh
+TOKEN=$(jq -r .token <workspace>/.agentproto/runtime.json)
+
+curl -sS -X POST "http://127.0.0.1:<port>/inbound" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "alias": "agentpush",
+    "source": "+33600000000",
+    "contact_ref": "alice",
+    "text": "sounds good, ship it"
+  }'
+```
+
+A `200` with `{"action":"routed","sessionId":"..."}` means the reply
+landed as a user turn in that session — check it with `agent_output` /
+`GET /sessions/:id/stream`.
+
+## Provider-agnostic inbound endpoints (`POST /inbound/:slug`)
+
+As an alternative to the single shared bearer-gated `POST /inbound`, the
+daemon now supports per-provider webhook endpoints:
+
+```
+POST /inbound/<slug>
+```
+
+Each endpoint is configured with dialect (`agentpush`, `telegram`,
+`whatsapp`, `slack`, `generic`, `native`), an imported MCP alias, an
+optional forced source, an optional webhook signing secret, and a routing
+mode. The MCP tools `inbound_endpoint_create`, `inbound_endpoint_list`,
+and `inbound_endpoint_delete` manage them. All endpoints are created via
+`createInboundEndpointStore()` in `createGateway()` and share the same
+`routeInboundMessage` router as the poll watcher and the legacy push route.
+
+### Signature verification
+
+When a secret is configured, the secret is REQUIRED and the bearer gate
+is bypassed, so a publicly exposed webhook endpoint is not accidentally
+opened by the loopback Origin allowlist.
+
+| provider | header | algorithm/format |
+|---|---|---|
+| `agentpush` | `X-Agentpush-Signature` | `sha256=<hex-hmac-sha256>` |
+| `telegram` | `X-Telegram-Bot-Api-Secret-Token` | exact secret, constant-time compare |
+| `whatsapp` | `X-Hub-Signature-256` | `sha256=<hex-hmac-sha256>` |
+| `slack` | `X-Slack-Signature` | Slack request signature v0 with replay window |
+| `generic` | `X-Agentproto-Signature` | `sha256=<hex-hmac-sha256>` |
+| `native` | n/a | uses the sessions bearer gate |
+
+### Normalized envelope
+
+After verification, the webhook JSON is normalized by `normalizeInbound()"
+(`inbound-adapters.ts`) into the same `InboundMessage` shape the rest of
+the transmitter expects:
+
+```json
+{
+  "alias": "<configured alias>",
+  "source": "<channel/phone/chat id>",
+  "contactRef": "<sender id>",
+  "text": "<message text>",
+  "messages": [ /* optional: raw provider event */ ]
+}
+```
+
+Provider-specific behaviour:
+
+- `agentpush` and `slack` support a `challenge` handshake; the challenge is
+  echoed as `{ "challenge": "..." }` and no session is touched.
+- `telegram` and `slack` ignore bot/self messages.
+- Missing text returns `200 { "action": "ignored", "reason": "no_text" }` so
+  webhook providers do not retry forever.
+
+### Deduplication
+
+Each endpoint keeps an in-memory FIFO of the last ~500 seen provider
+message ids via `markSeen()`. A duplicate returns `200 { "action":
+"duplicate" }`.
+
+### MCP tools
+
+```json
+{
+  "tool": "inbound_endpoint_create",
+  "arguments": {
+    "slug": "telegram-bot",
+    "provider": "telegram",
+    "alias": "agentpush",
+    "source": "@mybot",
+    "mode": "route-or-spawn",
+    "secret": "<optional>"
+  }
+}
+```
+
+`inbound_endpoint_list` returns endpoints without exposing the secret.
+`inbound_endpoint_delete` removes by slug.
+
+## Follow-up: agentpush-side wiring (not covered by this repo)
+
+This repo only adds the ingress endpoint. For the push path to actually
+fire in production, agentpush itself needs to be configured to `POST` a
+webhook payload to `<daemon-url>/inbound` (with the daemon's bearer
+token) whenever it receives an inbound message, instead of relying solely
+on `inbound_watcher_start`'s 5-second poll loop.