@agentproto/runtime 2.8.0 → 2.10.0

package/README.md

@@ -37,7 +37,7 @@ A per-boot bearer token is generated automatically and written into `<workspace>
 
 | Surface           | URL                                      | Notes                                                  |
 |-------------------|------------------------------------------|--------------------------------------------------------|
-| Health            | `GET /health`                            | Workspace + uptime — always public                     |
+| Health            | `GET /health`                            | Daemon status: workspace, uptime, `startedAt`, version, build identity (`sha`, `builtAt`, `source`), pid, node path, entry point — always public                     |
 | Events (SSE)      | `GET /events`                            | RuntimeEvents stream                                   |
 | MCP               | `POST /mcp` (Streamable HTTP)            | Stateless mode; per-request transport                  |
 | Conversations     | `GET /conversations` / `GET /conversations/<id>` | Markdown bodies                                |
@@ -51,6 +51,8 @@ A per-boot bearer token is generated automatically and written into `<workspace>
 | **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                              |
+| **Chat stream**   | `POST /sessions/:id/chat`                | Send a follow-up prompt + fan RAW transcript into the `ai` v6 UI message stream |
+| **Chat (create)** | `POST /sessions/chat`                    | Spawn a session + stream its first turn as chat (needs `resolveAgentAdapter`) |
 | Kill / forget / gc | `POST /sessions/:id/kill`, `DELETE /sessions/:id`, `POST /sessions/gc` | SIGTERM, drop from registry, bulk archive terminal sessions |
 
 ### MCP tool surface
@@ -77,6 +79,44 @@ The `/mcp` endpoint exposes the core toolset plus several opt-in / feature-gated
 - The optional `auth?: AuthOptions` field on `createGateway` is for the *tunnel* bearer (Cloudflare-fronted public surface), independent of the per-boot token. It gates `/mcp`, `/events`, `/conversations*`, and the heartbeat tick route, with a loopback bypass for requests that never crossed a tunnel (127.0.0.1/::1 with no `X-Forwarded-For`).
 - `agentproto serve` wires this from `daemon.authToken` in `~/.agentproto/config.json` (or `--auth-token`) when set, so the gateway can boot already gated with a stable token — no `remote_enable` call, and it survives restarts since it isn't held in memory. `RemoteController`'s `remote_enable` MCP tool is a separate, complementary mechanism: it always mints a fresh in-memory token and opens a Cloudflare quick tunnel, and takes precedence over `daemon.authToken` while active.
 
+## Worktree isolation policy
+
+`agent_start.worktree` isolation is decided by `worktrees.isolation` in
+`~/.agentproto/config.json` (or the `AGENTPROTO_WORKTREES_ISOLATION` env,
+which wins). Three modes — see `WorktreeIsolationMode` in
+[`config.ts`](./src/config.ts) and the decision matrix in
+[`worktree-isolation.ts`](./src/worktree-isolation.ts):
+
+- `"on-request"` (default) — isolates only when the caller explicitly passes
+  `worktree`.
+- `"always"` — every **root** (depth-0) spawn is provisioned into a fresh
+  `<worktrees.root>/<repo>/<slug>` worktree on branch `wt/<slug>` cut from
+  `origin/main`, whether or not the caller asked. A `cwd` outside any git
+  repo has nothing to isolate, so it spawns plain.
+- `"never"` — isolation is off; an explicit `worktree` request is rejected
+  loudly rather than silently ignored.
+
+**Depth-0 only.** A spawn made *through* an orchestrator's scoped sub-gateway
+(depth > 0 — including any `agent_start` a supervisor session issues itself,
+even with `attach: false`) always inherits its parent's working tree; the
+`always` policy never provisions a second worktree for it, and an explicit
+`worktree` request at depth > 0 is rejected (use `sandbox` for child
+isolation instead). To exercise `always` end-to-end you need a genuine root
+spawn — e.g. `agentproto sessions start <adapter> --cwd <repo>` from a shell,
+not an `agent_start` call made from inside another session.
+
+**Config key gotcha:** the field is nested — `{"worktrees": {"isolation":
+"always"}}` — NOT a top-level `worktreeIsolation` key. The loader
+(`loadWorktreeIsolation` / `loadConfig`) silently ignores unknown top-level
+keys, so a hand-edit that adds `worktreeIsolation` at the top level parses
+fine, `agentproto config show` will happily print it back, and the policy
+still silently resolves to the `"on-request"` default — no error, no spawn
+behaviour change. Verify with `agentproto sessions --json` after a root spawn
+and check the descriptor for `worktreePath`/`worktreeId`, not just the config
+file's contents. Config is re-read from disk on every spawn (no caching), so
+a fix to the key takes effect on the next `agent_start`/`sessions start` —
+no daemon restart needed.
+
 ## SessionsRegistry
 
 Exposed via `gateway.sessions`. Useful when you want to register externally-spawned children (e.g. tunnel-driven spawns) or programmatically attach without going through HTTP.
@@ -104,6 +144,52 @@ handle?.detach()
 
 Other methods: `spawn` (raw `child_process.spawn`), `spawnAgent` (ACP), `register` (adopt an external `ChildProcess`), `attach` (SSE-style line subscription), `kill`, `forget`, `findByIdOrName`, `writeTerminalInput`, `readTerminalOutput`, `shutdown`. See [`sessions.ts`](./src/sessions.ts) for the typed surface.
 
+## Chat routes — `POST /sessions/:id/chat` and `POST /sessions/chat`
+
+The chat routes turn a daemon session into an AI-SDK v6 "UI message stream": they enqueue a user prompt on the session and fan the daemon's RAW transcript records (`events.jsonl`, the shapes `@agentproto/transcript-fixtures` documents) into a stream of `UIMessageChunk` objects — the protocol `ai`'s `createUIMessageStreamResponse` emits (`data: <JSON chunk>\n\n` SSE frames + `x-vercel-ai-ui-message-stream: v1`). The mapping is the pure `createTranscriptToUiMapper(sessionId)` from [`chat-stream.ts`](./src/chat-stream.ts); the background replay + live subscribe use the same `deliverRecordsExactlyOnce` machinery as `/sessions/:id/events/stream`, so a client sees no duplicate and no hole.
+
+### Route contract
+
+**`POST /sessions/:id/chat`** — enqueue a follow-up turn on an EXISTING session and stream its output.
+
+- Method / path: `POST /sessions/:id/chat` (id-or-name, like `/sessions/:id/events`).
+- Body (JSON): `{ "prompt": string, "interrupt"?: boolean, "source"?: string }`. `prompt` (non-empty) is required; `interrupt: true` cancels a mid-turn and redirects the same session (mirrors the MCP `agent_prompt` tool); `source` overrides the recorded provenance (default `http:chat`).
+- Response: 200 with `Content-Type: text/event-stream`, header `x-vercel-ai-ui-message-stream: v1`, body a sequence of `data: <UIMessageChunk JSON>` frames ending in `data: [DONE]`. Adverse outcomes fail before any stream byte: `400` for a missing/invalid `prompt`, `404` for an unresolvable session, `409 {error:"session_not_alive"}` for a dead session, `409 {error:"prompt_rejected"}` when a busy session refused the prompt without `interrupt` (this is exactly the admission error `enqueuePrompt` throws).
+
+**`POST /sessions/chat`** — create-and-chat variant. It REUSES the exact `/sessions/agent` spawn core: the same `spawnAgentSession` function and the same shared body→args mapper (`buildSpawnSessionHttpArgs`, kept in `http-server.ts` so the two surfaces can't drift from each other or from the MCP `agent_start` tool). Body is the `/sessions/agent` spawn fields (e.g. `adapter`, `cwd`, `workspaceSlug`, `orchestrator`, …) **plus a required `prompt`** (the opening user message). On success it does NOT return a 201 descriptor like `/sessions/agent` — it immediately bleeds the session's first turn into the chat stream above. Requires the host-injected `resolveAgentAdapter` (otherwise `501`).
+
+Why not a second, lighter spawn path? Because the spawn surface (orchestrator / mcpServers / worktree / access / presets / …) is genuinely large and already validated in one place; duplicating a slice of it here would create two divergent spawn contracts. Sharing `spawnAgentSession` + `buildSpawnSessionHttpArgs` means `/sessions/chat` inherits every fix to either by construction. The cost is that `/sessions/chat` accepts the same (wide) body as `/sessions/agent`; callers wanting a minimal contract should use `/sessions/agent` (to create) then `/sessions/:id/chat` (to stream follow-ups).
+
+### Record → `UIMessageChunk` mapping
+
+Replayed in `seq` order, each RAW record maps as follows (see `chat-stream.ts` for the authoritative switch, under conformance test):
+
+| RAW kind | Emitted chunk(s) |
+|---|---|
+| `user-prompt` | none (echo of the user's input, not assistant output) |
+| `thought` | `reasoning-start` (once per run) + `reasoning-delta` (per fragment) + `reasoning-end` at the segment boundary |
+| `text-delta` | `text-start` (once per run) + `text-delta` (per fragment) + `text-end` at the boundary |
+| `tool-call` | `tool-input-available {toolCallId, toolName, input: arguments}` (`isUpdate` re-emits with the fresh snapshot) |
+| `tool-result` | `tool-output-available {toolCallId, output: result}` (RAW `result`, unwrapped) — or `tool-output-error {toolCallId, errorText}` when `isError` |
+| `tool-call-record` | none — DELIBERATE skip (bookkeeping that duplicates `tool-call` + `tool-result`) |
+| `permission-resolved` | custom data part `data-tool-call-approval` (CONDITION 4, below) |
+| `turn-end` | `finish` (`finishReason: "stop"` for `reason: "turn-complete"`; omitted when nothing maps cleanly) |
+| any other kind | `{type:"error", errorText:"unhandled transcript record kind: <kind>"}` + a server-side `console.error` (CONDITION 2 — never a silent swallow) |
+
+### Custom data part: `data-tool-call-approval`
+
+A resolved permission decision (`permission-resolved` records) travels as a custom data part:
+
+```json
+{"type":"data-tool-call-approval","data":{"toolCallId":"call_fixture_01","decision":"allow","optionId":"once"}}
+```
+
+We use a `data-*` custom part rather than the `ai` v6 native `tool-approval-request` chunk (which has `approvalId`/`signature`) because the latter models a PENDING approval request (before execution), whereas our transcript only ever contains the already-RESOLVED final decision (`permission-resolved`). The `tool-call-approval` name is aligned with Mastra's `tool-call-approval` vocabulary for future consistency, not with the native chunk, which does not match our data. The generic data-part type in `ai` v6 is `DataUIMessageChunk` = `{ type: \`data-${NAME}\`, id?, data, transient? }`, so `data-tool-call-approval` is a first-class protocol citizen.
+
+### Known gap — pending approval requests do NOT flow through this route yet
+
+Only `permission-resolved` (the final decision) transits the chat stream today. PENDING permission requests (the same class of thing `ai` models as `tool-approval-request`, and Mastra as `tool-call-approval`) are **not** yet surfaced by this route — there is no per-turn "request is waiting for a human" event in this stream. That is a known gap, out of scope for this work package, not an oversight; closing it (emitting a pending-approval data part when the daemon holds on a permission) is future work.
+
 ## License
 
 MIT — see [LICENSE](../../LICENSE).

package/dist/catalog-models.d.ts

@@ -1,5 +1,5 @@
 import { AuthProfile } from '@agentproto/auth';
-import { A as AdapterAuthDescriptor } from './spawn-defaults-DVgmfxWo.js';
+import { A as AdapterAuthDescriptor } from './spawn-defaults-DUnTfwVK.js';
 import { R as RouteSpec } from './session-config-DbWP9RRj.js';
 import '@agentproto/model-catalog';
 import './context-continuity-ib9_bVYM.js';
@@ -90,6 +90,14 @@ interface CatalogRoute {
     ref: string;
     baseUrl: string | null;
     pricing: CatalogPricing | null;
+    /** Human-readable max input tokens (e.g. `"1M"`, `"200k"`), from the
+     *  live-synced CONTEXT_WINDOWS table (`resolveContextWindow`); null when
+     *  no synced provider carries this id. Consumers wanting the raw integer
+     *  can re-resolve via `resolveContextWindow(ref product)` or parse. */
+    contextWindow: string | null;
+    /** Human-readable max output tokens (same source/format), null when the
+     *  source doesn't publish a completion cap for this id. */
+    maxOutput: string | null;
     runnable: boolean;
     eligibleProfiles: string[];
     adapterModes: string[];
@@ -237,6 +245,58 @@ interface ModelWalletEligibility {
  * guard only REJECTS; it never substitutes a wallet the operator didn't name.
  */
 declare function checkModelWalletEligibility(model: string, walletRoute: string): ModelWalletEligibility;
+/** Verdict of the spawn-time adapter-capability guard
+ *  ({@link checkModelAdapterEligibility}). */
+interface ModelAdapterEligibility {
+    ok: boolean;
+    /** Other installed adapters whose catalog row already curates this exact
+     *  model on this exact route — the actionable set to re-spawn onto. Empty
+     *  when `ok`, or when NO installed adapter (this one included) curates the
+     *  combination — nobody has proven it reachable at all, so this guard has
+     *  nothing to reject on. */
+    compatibleAdapters: string[];
+}
+/**
+ * Adapter-capability spawn guard: the money-safety guard above
+ * ({@link checkModelWalletEligibility}) proves the resolved ROUTE can bill
+ * `model`; it says nothing about whether THIS adapter's own manifest can
+ * actually reach it there. A fixed hand-curated client (claude-code's ACP
+ * wrapper validates every model id against its own live selector and 404s on
+ * anything it doesn't recognize) can be routeSelection:"free" — genuinely able
+ * to reach several gateways — while still only supporting a small, explicitly
+ * vetted model list on each one. A pass-through client (opencode/mastracode/
+ * hermes/jcode, routeSelection:"derived-from-model") instead auto-derives a
+ * broad curated list straight from the pricing catalog, so it ends up
+ * supporting far more of a gateway's models without needing a per-model
+ * allowlist maintained by hand.
+ *
+ * Takes the SAME `CatalogModelsResponse` shape `buildCatalogModels` (and
+ * therefore `catalog_models`) produces — reusing that exact join, never a
+ * parallel per-adapter table — and looks up whether `adapterSlug` is among
+ * the resolved (vendor, product, route) row's `adapters`.
+ *
+ * `ok:true` when EITHER no installed adapter's catalog row covers this exact
+ * model+route (nobody has proven it servable at all — the same never-reject-
+ * an-unknown-combination stance {@link checkModelWalletEligibility} takes), OR
+ * `adapterSlug` is already among the row's adapters. `ok:false` only when the
+ * row exists and excludes `adapterSlug` — a proven "wrong client for this
+ * model" mismatch, with the row's other adapters (if any) as the actionable
+ * alternative.
+ */
+declare function checkModelAdapterEligibility(catalog: CatalogModelsResponse, adapterSlug: string, model: string, route: string): ModelAdapterEligibility;
+/**
+ * The actionable fail-fast message for {@link checkModelAdapterEligibility} —
+ * names the adapters that DO already curate the model on this route (when any
+ * do) so the operator can re-spawn without opening the catalog by hand. Never
+ * auto-switches adapters for the operator; only rejects.
+ */
+declare function modelAdapterIncompatibleMessage(opts: {
+    prefix: string;
+    adapter: string;
+    model: string;
+    route: string;
+    compatibleAdapters: string[];
+}): string;
 /**
  * The actionable fail-fast message shared by both spawn paths (session-spawn +
  * session-restart-core) so they never drift. Names the wallet that couldn't
@@ -252,4 +312,4 @@ declare function modelWalletIneligibleMessage(opts: {
     suggestedRoutes: string[];
 }): string;
 
-export { type BuildCatalogModelsInput, type CatalogAdapterInput, type CatalogAdapterModelInput, type CatalogModelsQuery, type CatalogModelsResponse, type CatalogPricing, type CatalogProduct, type CatalogRoute, type CatalogRouteSummary, type CatalogVendor, type ModelWalletEligibility, RouteSpec, buildCatalogModels, checkModelWalletEligibility, modelWalletIneligibleMessage, modelWithRoute, reconcileModelRoute, resolveEffectiveRoute, serviceableModelRoutes, suggestModelSlugs };
+export { type BuildCatalogModelsInput, type CatalogAdapterInput, type CatalogAdapterModelInput, type CatalogModelsQuery, type CatalogModelsResponse, type CatalogPricing, type CatalogProduct, type CatalogRoute, type CatalogRouteSummary, type CatalogVendor, type ModelAdapterEligibility, type ModelWalletEligibility, RouteSpec, buildCatalogModels, checkModelAdapterEligibility, checkModelWalletEligibility, modelAdapterIncompatibleMessage, modelWalletIneligibleMessage, modelWithRoute, reconcileModelRoute, resolveEffectiveRoute, serviceableModelRoutes, suggestModelSlugs };

package/dist/catalog-models.mjs

@@ -1,13 +1,41 @@
 import { eligibleProfiles } from '@agentproto/auth';
 import { tryParseModelRef, formatModelRef, resolveLlmModelRoute } from '@agentproto/model-catalog/route-identity';
-import { getModelProvider, resolvePricingExact, LLM_PRICING_CATALOG, MODEL_ALIASES } from '@agentproto/model-catalog/llm';
+import { resolveContextWindow, formatTokens, getModelProvider, resolvePricingExact, LLM_PRICING_CATALOG, MODEL_ALIASES } from '@agentproto/model-catalog/llm';
 import { getAnthropicGatewayPreset } from '@agentproto/provider-presets';
+import * as providers_store_star from '@agentproto/providers-store';
 
 /**
  * @agentproto/runtime v0.1.0-alpha
  * Long-running gateway: MCP server + HTTP transport + HEARTBEAT autonomy + conversation persistence over a workspace dir.
  */
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget);
+
+// src/providers-store.ts
+var providers_store_exports = {};
+__reExport(providers_store_exports, providers_store_star);
 
+// src/spawn-defaults.ts
+function subscriptionSurfaceFor(sub, endpoint) {
+  if (sub === void 0) return void 0;
+  if (!Array.isArray(sub)) {
+    return sub.provider === void 0 || endpoint === void 0 || sub.provider === endpoint ? sub : void 0;
+  }
+  return sub.find((s) => s.provider !== void 0 && s.provider === endpoint) ?? sub.find((s) => s.provider === void 0);
+}
+
+// src/catalog-models.ts
 var WIDENING_ROUTES = ["openrouter", "requesty", "huggingface"];
 var VENDOR_COMPATIBILITY_ROUTES = {
   xai: ["xai", "xai-anthropic"]
@@ -73,10 +101,11 @@ function resolveModelId(id) {
     pricing: null
   };
 }
-function methodsForDirect(descriptor) {
+function methodsForDirect(descriptor, endpoint) {
   const methods = [];
-  if (descriptor?.authSubscription || descriptor?.modelDerivedApiKey)
+  if (subscriptionSurfaceFor(descriptor?.authSubscription, endpoint) !== void 0) {
     methods.push("oauth-bearer");
+  }
   if (descriptor?.provider || descriptor?.modelDerivedApiKey) methods.push("api-key");
   return methods;
 }
@@ -89,7 +118,7 @@ function curatedContributions(adapters) {
     for (const model of adapter.models) {
       const resolved = resolveModelId(model.id);
       const route = model.mode ?? model.provider ?? resolved.directRoute;
-      const methods = isDirectRoute(route, model.mode, resolved) ? methodsForDirect(adapter.authDescriptor) : ["api-key"];
+      const methods = isDirectRoute(route, model.mode, resolved) ? methodsForDirect(adapter.authDescriptor, route) : ["api-key"];
       out.push({
         vendor: resolved.vendor,
         product: resolved.product,
@@ -259,11 +288,19 @@ function buildCatalogModels(input) {
     ) : [];
     const runnable = eligible.length > 0;
     if (query.runnableOnly && !runnable) continue;
+    const ctx = resolveContextWindow(row.product);
     const route = {
       route: row.route,
       ref: row.ref,
       baseUrl: row.baseUrl,
       pricing: row.pricing,
+      // Live-synced context window (max input) + max output, when a synced
+      // provider (Anthropic/Groq/xAI/Moonshot/Mistral/Google) carries this
+      // id — null otherwise. All CONTEXT_WINDOWS providers get this, not
+      // only Anthropic. Formatted for display (`1M`/`200k`); consumers
+      // needing the raw integer resolve it themselves.
+      contextWindow: formatTokens(ctx?.contextWindow),
+      maxOutput: formatTokens(ctx?.maxOutput),
       runnable,
       eligibleProfiles: eligible.map((p) => p.id),
       adapterModes: row.adapterModes,
@@ -375,6 +412,17 @@ function checkModelWalletEligibility(model, walletRoute) {
   }
   return { ok: false, suggestedRoutes: serviceable.filter((r) => r !== walletRoute) };
 }
+function checkModelAdapterEligibility(catalog, adapterSlug, model, route) {
+  const target = resolveModelId(model);
+  const routeEntry = catalog.vendors.find((v) => v.vendor === target.vendor)?.products.find((p) => p.product === target.product)?.routes.find((r) => r.route === route);
+  if (!routeEntry) return { ok: true, compatibleAdapters: [] };
+  if (routeEntry.adapters.includes(adapterSlug)) return { ok: true, compatibleAdapters: [] };
+  return { ok: false, compatibleAdapters: routeEntry.adapters };
+}
+function modelAdapterIncompatibleMessage(opts) {
+  const alternative = opts.compatibleAdapters.length > 0 ? `Adapters that already support it on "${opts.route}": ${opts.compatibleAdapters.map((a) => `"${a}"`).join(", ")} \u2014 re-spawn with one of those instead.` : `No installed adapter currently supports it on "${opts.route}" either \u2014 check \`catalog_models\` for a route this model IS servable on.`;
+  return `${opts.prefix}: adapter "${opts.adapter}" does not declare support for model "${opts.model}" on route "${opts.route}" and would 404/reject upstream even though that route can bill it. ${alternative} This guard only rejects; it never switches adapters for you.`;
+}
 function modelWalletIneligibleMessage(opts) {
   const wallet = opts.walletMode ? `"${opts.walletRoute}" ${opts.walletMode} wallet` : `"${opts.walletRoute}" wallet`;
   const primary = opts.suggestedRoutes[0] ?? "a gateway route";
@@ -382,6 +430,6 @@ function modelWalletIneligibleMessage(opts) {
   return `${opts.prefix}: model "${opts.model}" is not serviceable on the resolved ${wallet} (adapter "${opts.adapter}") and would 404 upstream. This model bills route "${primary}"${also} \u2014 re-spawn on it: set route.gateway="${primary}" with an eligible "${primary}" api-key profile (access.profileRef). This guard only rejects; it never switches wallets for you.`;
 }
 
-export { buildCatalogModels, checkModelWalletEligibility, modelWalletIneligibleMessage, modelWithRoute, reconcileModelRoute, resolveEffectiveRoute, serviceableModelRoutes, suggestModelSlugs };
+export { buildCatalogModels, checkModelAdapterEligibility, checkModelWalletEligibility, modelAdapterIncompatibleMessage, modelWalletIneligibleMessage, modelWithRoute, reconcileModelRoute, resolveEffectiveRoute, serviceableModelRoutes, suggestModelSlugs };
 //# sourceMappingURL=catalog-models.mjs.map
 //# sourceMappingURL=catalog-models.mjs.map