@agentproto/runtime 4.0.0 → 5.1.0

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

@@ -185,12 +185,24 @@ interface DefaultsAdapterConfig {
     options?: Record<string, boolean | number | string>;
     auth?: DefaultsAdapterAuthConfig;
     contextContinuity?: ContextContinuityPolicy;
+    /** Capability bundle ids (`bundle_list`) auto-attached to spawns of this
+     *  adapter — unioned with the global `defaults.bundles`. See
+     *  {@link resolveBundleDefaults}. */
+    bundles?: string[];
+    /** Explicitly mount the daemon's own scoped `/mcp` for spawns of this
+     *  adapter — the only way an adapter outside `shouldInjectDaemonSelfMount`'s
+     *  allowlist (opencode, codex, gemini, …) gets it by default. Overridden
+     *  per-spawn by `agent_start.daemonMount`. */
+    daemonMount?: boolean;
 }
 /** Shape of `config.json`'s top-level `defaults` block. */
 interface SpawnDefaultsConfig {
     skills?: string[];
     options?: Record<string, boolean | number | string>;
     adapters?: Record<string, DefaultsAdapterConfig>;
+    /** Capability bundle ids auto-attached to every spawn — see
+     *  {@link DefaultsAdapterConfig.bundles} for the per-adapter union partner. */
+    bundles?: string[];
     contextContinuity?: ContextContinuityPolicy;
     /** Depth cutoff for the role-derived default (see `resolveRole` in
      *  `role.ts`) applied when an `agent_start` call omits `role`:

package/dist/user-presets.d.ts

@@ -40,6 +40,10 @@ interface UserPreset extends Partial<SessionConfig> {
      *  `SpawnAgentSessionInput.skills`. Omitted means the adapter/defaults
      *  decide. */
     skills?: string[];
+    /** Capability bundle ids (`bundle_list`) for a spawn from this preset — the
+     *  same axis as `SpawnAgentSessionInput.bundles`. Omitted means the
+     *  adapter/defaults decide. */
+    bundles?: string[];
     /** `agent_start.browser` for spawns from this preset. Ranks below the
      *  role's own default (see `resolveBrowserMode`). */
     browser?: SpawnBrowserMode;
@@ -79,6 +83,7 @@ declare const userPresetsFileSchema: z.ZodObject<{
         contextProfile: z.ZodOptional<z.ZodString>;
         cwd: z.ZodOptional<z.ZodString>;
         skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        bundles: z.ZodOptional<z.ZodArray<z.ZodString>>;
         browser: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"headless">, z.ZodLiteral<false>]>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;

package/dist/user-presets.mjs

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

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\"\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"]}
+{"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  /** Capability bundle ids (`bundle_list`) for a spawn from this preset — the\n   *  same axis as `SpawnAgentSessionInput.bundles`. Omitted means the\n   *  adapter/defaults decide. */\n  bundles?: 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  bundles: 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.