@guuey/agent-client 0.4.0 → 0.5.0

package/README.md

@@ -15,12 +15,13 @@ injected as adapters, so the same core runs on web (Next.js) and React Native.
 npm install @guuey/agent-client
 ```
 
-## Two entry points
+## Three entry points
 
-| Import                      | Contents                                                                           | React? |
-| --------------------------- | ---------------------------------------------------------------------------------- | ------ |
-| `@guuey/agent-client`       | SSE helpers, the thread-history reader, `createWebAdapters`, and all public types. | No     |
-| `@guuey/agent-client/react` | The `useAgentInvoke` hook (+ `applyHistoryResult`).                                | Yes    |
+| Import                          | Contents                                                                                             | React? |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------- | ------ |
+| `@guuey/agent-client`           | SSE helpers, `invokeTurn`, the thread-history reader, `createWebAdapters`, and all public types.     | No     |
+| `@guuey/agent-client/react`     | The `useAgentInvoke` hook (+ `applyHistoryResult`).                                                  | Yes    |
+| `@guuey/agent-client/transport` | Only the invoke transport + guest-identity pieces — zero `@guuey/mcp-apps-host` in the import graph. | No     |
 
 The root subpath is React-free — importing it never pulls React in. React is a
 **required peer** (`react >=18`) because the `./react` subpath needs it; if you
@@ -67,6 +68,39 @@ composer re-enables. The full vocabulary is documented at
 On React Native, supply your own adapters (AsyncStorage + an `expo/fetch`
 transport) in place of `createWebAdapters` — the hook's contract is identical.
 
+## Driving a turn without React
+
+`invokeTurn` is the same wire walk as the hook, as a pure async generator —
+for a Node harness, a game loop, or any host with its own turn state machine.
+Its event stream is also the observation channel: tool results arrive as
+typed `tool.done` AgEvents, so telemetry is a filter, not a callback API.
+
+```ts
+import { invokeTurn, toInvokeUrl, fetchStreamTransport } from "@guuey/agent-client";
+
+const req = {
+  url: toInvokeUrl(endpointUrl),
+  body: { input, clientMessageId: crypto.randomUUID() },
+  signal: controller.signal,
+};
+// `getBearer` is resolved per attempt — a retry re-reads a fresh token.
+const transport = (r) => fetchStreamTransport(r, null, null, { getBearer });
+
+for await (const ev of invokeTurn(req, transport)) {
+  if (ev.kind !== "message") continue;
+  for (const agEvent of ev.agEvents) {
+    if (agEvent.type === "tool.done") {
+      telemetry.record(agEvent.toolCallId, agEvent.outcome ?? "ok");
+    }
+  }
+  render(ev.assistantText); // full folded text — no delta bookkeeping
+}
+```
+
+The transport retries cold-start 503s (the post-redeploy window) and
+`POD_SATURATED` refusals by itself, never after the first streamed byte;
+tune or disable via its `coldStartRetry` option.
+
 ## React Native / Metro
 
 Both entry points declare a `react-native` export condition that points at the

package/dist/error-codes.d.ts

@@ -27,6 +27,13 @@ export declare const AGENT_ERROR_CODES: {
     readonly INVALID_REQUEST: "INVALID_REQUEST";
     /** The builder turned anonymous access off for this agent. */
     readonly GUEST_ACCESS_DISABLED: "GUEST_ACCESS_DISABLED";
+    /**
+     * The agent's own definition declares `auth: 'required'` and the caller is
+     * anonymous — sign in and retry with a bearer. The snapshot-declared twin of
+     * {@link AGENT_ERROR_CODES.GUEST_ACCESS_DISABLED} (the app-record runtime
+     * override); either gate can refuse.
+     */
+    readonly AUTH_REQUIRED: "AUTH_REQUIRED";
     /** The caller (or the app) is out of plan allowance — the upgrade prompt. */
     readonly QUOTA_EXCEEDED: "QUOTA_EXCEEDED";
     /** The app hit its builder-set managed spend cap. */
@@ -55,4 +62,26 @@ export declare const AGENT_ERROR_CODES: {
 };
 /** One of the pod's wire codes — see {@link AGENT_ERROR_CODES}. */
 export type AgentErrorCode = (typeof AGENT_ERROR_CODES)[keyof typeof AGENT_ERROR_CODES];
+/**
+ * CLIENT-originated failure codes — minted by THIS SDK, never by the pod.
+ *
+ * Deliberately a SEPARATE constant from {@link AGENT_ERROR_CODES}: that
+ * object is a transcribed mirror of the runtime's wire vocabulary, guarded by
+ * the runtime-side `agent-client-codes.sync.test.ts` — adding a code the pod
+ * never emits there would both break the sync guard and lie about the wire.
+ * These codes surface through the SAME `errorCode` channel (it is a plain
+ * `string` for exactly this kind of growth), so consumers branch the same
+ * way; the split exists so each vocabulary keeps one honest owner.
+ */
+export declare const CLIENT_ERROR_CODES: {
+    /**
+     * The SSE stream went byte-silent mid-turn and bounded history probes never
+     * found the finished reply (guuey#192's stall watchdog giving up). The turn
+     * is over (`status` returns to `ready`); a retry or a reload may still find
+     * the reply if the backend completes later.
+     */
+    readonly STREAM_STALLED: "STREAM_STALLED";
+};
+/** One of this SDK's client-originated codes — see {@link CLIENT_ERROR_CODES}. */
+export type ClientErrorCode = (typeof CLIENT_ERROR_CODES)[keyof typeof CLIENT_ERROR_CODES];
 //# sourceMappingURL=error-codes.d.ts.map

package/dist/error-codes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../src/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,iBAAiB;IAC5B,yDAAyD;;IAEzD,gDAAgD;;IAEhD,8DAA8D;;IAE9D,6EAA6E;;IAE7E,qDAAqD;;IAErD;;;;OAIG;;IAEH;;;;;OAKG;;IAEH,oFAAoF;;IAEpF,qDAAqD;;IAErD,iEAAiE;;IAEjE,gCAAgC;;CAExB,CAAC;AAEX,mEAAmE;AACnE,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC"}
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../src/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,iBAAiB;IAC5B,yDAAyD;;IAEzD,gDAAgD;;IAEhD,8DAA8D;;IAE9D;;;;;OAKG;;IAEH,6EAA6E;;IAE7E,qDAAqD;;IAErD;;;;OAIG;;IAEH;;;;;OAKG;;IAEH,oFAAoF;;IAEpF,qDAAqD;;IAErD,iEAAiE;;IAEjE,gCAAgC;;CAExB,CAAC;AAEX,mEAAmE;AACnE,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAExF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB;IAC7B;;;;;OAKG;;CAEK,CAAC;AAEX,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/error-codes.js

@@ -27,6 +27,13 @@ export const AGENT_ERROR_CODES = {
     INVALID_REQUEST: "INVALID_REQUEST",
     /** The builder turned anonymous access off for this agent. */
     GUEST_ACCESS_DISABLED: "GUEST_ACCESS_DISABLED",
+    /**
+     * The agent's own definition declares `auth: 'required'` and the caller is
+     * anonymous — sign in and retry with a bearer. The snapshot-declared twin of
+     * {@link AGENT_ERROR_CODES.GUEST_ACCESS_DISABLED} (the app-record runtime
+     * override); either gate can refuse.
+     */
+    AUTH_REQUIRED: "AUTH_REQUIRED",
     /** The caller (or the app) is out of plan allowance — the upgrade prompt. */
     QUOTA_EXCEEDED: "QUOTA_EXCEEDED",
     /** The app hit its builder-set managed spend cap. */
@@ -53,3 +60,23 @@ export const AGENT_ERROR_CODES = {
     /** Unclassified pod failure. */
     INTERNAL: "INTERNAL",
 };
+/**
+ * CLIENT-originated failure codes — minted by THIS SDK, never by the pod.
+ *
+ * Deliberately a SEPARATE constant from {@link AGENT_ERROR_CODES}: that
+ * object is a transcribed mirror of the runtime's wire vocabulary, guarded by
+ * the runtime-side `agent-client-codes.sync.test.ts` — adding a code the pod
+ * never emits there would both break the sync guard and lie about the wire.
+ * These codes surface through the SAME `errorCode` channel (it is a plain
+ * `string` for exactly this kind of growth), so consumers branch the same
+ * way; the split exists so each vocabulary keeps one honest owner.
+ */
+export const CLIENT_ERROR_CODES = {
+    /**
+     * The SSE stream went byte-silent mid-turn and bounded history probes never
+     * found the finished reply (guuey#192's stall watchdog giving up). The turn
+     * is over (`status` returns to `ready`); a retry or a reload may still find
+     * the reply if the backend completes later.
+     */
+    STREAM_STALLED: "STREAM_STALLED",
+};

package/dist/index.d.ts

@@ -1,12 +1,15 @@
 export { parseSseEvents, extractAssistantText, reduceAssistantText, stringField, parseConsentRequest, parseLinkRequest, type ParsedSseEvent, } from "./sse.js";
 export { dismissLinkPrompt } from "./link-prompt.js";
-export { createUiActionRelay, type CreateUiActionRelayOptions, createUiResourceReader, type CreateUiResourceReaderOptions, createWebAdapters, localStorageThreadStore, webGenerateId, fetchStreamTransport, type CreateWebAdaptersOptions, } from "./web-adapters.js";
-export { withSaturationRetry, parseRetryAfterSeconds, type SaturationRetryOptions, } from "./saturation-retry.js";
+export { invokeTurn, toInvokeUrl, type InvokeTurnEvent } from "./invoke-turn.js";
+export { createUiActionRelay, type CreateUiActionRelayOptions, createUiResourceReader, type CreateUiResourceReaderOptions, createWebAdapters, localStorageThreadStore, webGenerateId, type CreateWebAdaptersOptions, } from "./web-adapters.js";
+export { fetchStreamTransport, sendableGuestSecret, GUEST_HEADER, withActivityObserver, type FetchStreamTransportOptions, } from "./transport.js";
+export { withSaturationRetry, withColdStartRetry, parseRetryAfterSeconds, type SaturationRetryOptions, type ColdStartRetryOptions, } from "./saturation-retry.js";
 export { AgentResponseError } from "./errors.js";
-export { AGENT_ERROR_CODES, type AgentErrorCode } from "./error-codes.js";
+export { AGENT_ERROR_CODES, type AgentErrorCode, CLIENT_ERROR_CODES, type ClientErrorCode, } from "./error-codes.js";
 export { fetchThreadHistory, threadHistoryRowsToMessages, threadHistoryRowsToCards, HistoryUnauthorizedError, type ThreadHistoryRow, type ThreadHistoryFetchOptions, } from "./history.js";
 export { ingestMessageFrame } from "./blocks.js";
 export { sortHistoryCards, toolNameFor } from "./history.js";
+export { Reducer } from "@silverprotocol/core";
 export type { AgEvent, AgReduceResult, AgMessage, AgBlock } from "@silverprotocol/core";
-export type { AgentMessage, HistoryCard, ProfileConsentRequest, ProfileLinkRequest, ThreadIdStore, GenerateId, InvokeRequest, InvokeTransport, AgentInvokeAdapters, AgentInvokeHistoryAdapter, AgentInvokeStatus, HistoryLoadResult, UseAgentInvokeOptions, UseAgentInvokeReturn, } from "./types.js";
+export type { AgentMessage, HistoryCard, ProfileConsentRequest, ProfileLinkRequest, ThreadIdStore, GenerateId, InvokeRequest, InvokeTransport, AgentInvokeAdapters, AgentInvokeHistoryAdapter, AgentInvokeStatus, HistoryLoadResult, StallRecoveryOptions, UseAgentInvokeOptions, UseAgentInvokeReturn, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,cAAc,GACpB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,sBAAsB,EACtB,KAAK,6BAA6B,EAClC,iBAAiB,EACjB,uBAAuB,EACvB,aAAa,EACb,oBAAoB,EACpB,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAC;AAO3B,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,GAC/B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAKjD,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAI7D,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACxF,YAAY,EACV,YAAY,EACZ,WAAW,EACX,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,UAAU,EACV,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,cAAc,GACpB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,sBAAsB,EACtB,KAAK,6BAA6B,EAClC,iBAAiB,EACjB,uBAAuB,EACvB,aAAa,EACb,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,EACpB,KAAK,2BAA2B,GACjC,MAAM,gBAAgB,CAAC;AAOxB,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,EACnB,kBAAkB,EAClB,KAAK,eAAe,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,GAC/B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAKjD,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAM7D,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACxF,YAAY,EACV,YAAY,EACZ,WAAW,EACX,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,UAAU,EACV,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,17 +1,25 @@
 export { parseSseEvents, extractAssistantText, reduceAssistantText, stringField, parseConsentRequest, parseLinkRequest, } from "./sse.js";
 export { dismissLinkPrompt } from "./link-prompt.js";
-export { createUiActionRelay, createUiResourceReader, createWebAdapters, localStorageThreadStore, webGenerateId, fetchStreamTransport, } from "./web-adapters.js";
-// The `POD_SATURATED` single-retry wrapper, transport-agnostic: a host that
-// brings its own `fetch` (Portal's React-Native transport) wraps it to wear the
-// same semantics as the web transport instead of hand-rolling a second copy.
-// `parseRetryAfterSeconds` ships with it because filling
-// `AgentResponseError.retryAfterSeconds` the same way is what makes the wrapper
-// honour the pod's hint.
-export { withSaturationRetry, parseRetryAfterSeconds, } from "./saturation-retry.js";
+// One agent turn as a pure async generator — the wire walk `useAgentInvoke`
+// wraps, for hosts that drive their own turn state machine (guuey#186 G5).
+export { invokeTurn, toInvokeUrl } from "./invoke-turn.js";
+export { createUiActionRelay, createUiResourceReader, createWebAdapters, localStorageThreadStore, webGenerateId, } from "./web-adapters.js";
+// The invoke transport + guest-identity wire pieces, in their own
+// mcp-apps-host-free module. Consumers that want ONLY this graph (no
+// host-role card layer riding along) import `@guuey/agent-client/transport`
+// instead of the barrel — see that module's docblock (guuey#186 G2).
+export { fetchStreamTransport, sendableGuestSecret, GUEST_HEADER, withActivityObserver, } from "./transport.js";
+// The invoke-refusal retry wrappers, transport-agnostic: a host that brings
+// its own `fetch` (Portal's React-Native transport) wraps them to wear the
+// same semantics as the web transport instead of hand-rolling second copies.
+// `parseRetryAfterSeconds` ships with them because filling
+// `AgentResponseError.retryAfterSeconds` the same way is what makes the
+// wrappers honour the pod's hint.
+export { withSaturationRetry, withColdStartRetry, parseRetryAfterSeconds, } from "./saturation-retry.js";
 export { AgentResponseError } from "./errors.js";
 // The pod's wire-code vocabulary, mirrored — branch on these instead of
 // re-typing the string literals (see the module docblock for the sync guard).
-export { AGENT_ERROR_CODES } from "./error-codes.js";
+export { AGENT_ERROR_CODES, CLIENT_ERROR_CODES, } from "./error-codes.js";
 export { fetchThreadHistory, threadHistoryRowsToMessages, threadHistoryRowsToCards, HistoryUnauthorizedError, } from "./history.js";
 export { ingestMessageFrame } from "./blocks.js";
 // Pure block-walk / resource-narrowing helpers for a block-preserving renderer
@@ -19,3 +27,9 @@ export { ingestMessageFrame } from "./blocks.js";
 // Transcript labeling/ordering helpers (mount narrowing itself moved to
 // @guuey/mcp-apps-host — the SEP-1865 Host role package; import it directly).
 export { sortHistoryCards, toolNameFor } from "./history.js";
+// Re-export the AgJSON types the block-preserving transcript surfaces, so
+// consumers can name `reduceResult` / block types without a direct
+// `@silverprotocol/core` import — and the `Reducer` CLASS beside them, so a
+// host folding `invokeTurn`'s agEvents outside the hook builds its transcript
+// on the same terms (the types alone forced the direct dep back, guuey#186 G4).
+export { Reducer } from "@silverprotocol/core";

package/dist/invoke-turn.d.ts

@@ -0,0 +1,101 @@
+/**
+ * invokeTurn — one agent turn as a pure async generator (guuey#186 G5).
+ *
+ * The per-turn loop `useAgentInvoke` runs — SSE accumulate → event switch →
+ * cumulative text fold → AgJSON block ingest — used to exist only fused to
+ * React state inside the hook, so a host with its own turn state machine
+ * (a game loop, a native view model, a server-side driver) had to re-walk
+ * the wire switch by hand. This module IS that loop, wire-in / semantics-out
+ * and React-free: feed it the request and a transport, iterate
+ * {@link InvokeTurnEvent}s. The hook is a thin wrapper that maps each event
+ * onto its state setters — behaviour-identical, one walk of the switch,
+ * owned here.
+ *
+ * Turn-scoped by design: the generator owns the CUMULATIVE assistant text
+ * for this turn (every `message` event carries the full folded text so far,
+ * not a delta). Cross-turn state stays with the caller — notably the AgJSON
+ * `Reducer`, which folds an entire conversation: this generator yields each
+ * frame's validated `agEvents` and never touches a reducer.
+ *
+ * Transport failures (e.g. `AgentResponseError` on a pre-stream refusal)
+ * propagate out of iteration — catch around the `for await`, exactly as the
+ * hook does. Unknown SSE events yield nothing, matching the hook's silent
+ * fall-through, so new wire events are additive for every consumer.
+ */
+import type { AgEvent } from "@silverprotocol/core";
+import type { AgentInvokeStatus, InvokeRequest, InvokeTransport, ProfileConsentRequest, ProfileLinkRequest } from "./types.js";
+/**
+ * One semantic step of a turn. Field conventions:
+ *
+ * - `message.status` / `message.activeTool` are ABSENT (not null) when the
+ *   frame implies no change — apply them only when present, so an unknown
+ *   frame type leaves your state machine untouched (the hook's exact rule:
+ *   only `tool.start`/`tool.done` ever move `activeTool`, and a text frame
+ *   moving status to `responding` does NOT clear a lingering tool name).
+ * - `message.assistantText` is the full folded text of the turn so far —
+ *   render it as-is on every event; there is no delta bookkeeping to do.
+ * - `message.agEvents` are the frame's validated AgJSON events (empty for
+ *   bypass frames) — push them into your own cross-turn `Reducer` if you
+ *   keep a block-preserving transcript, ignore them otherwise.
+ */
+export type InvokeTurnEvent = {
+    kind: "session";
+    threadId: string | null;
+} | {
+    kind: "message";
+    status?: Extract<AgentInvokeStatus, "thinking" | "using-tool" | "responding">;
+    activeTool?: string | null;
+    assistantText: string;
+    agEvents: AgEvent[];
+} | {
+    kind: "error";
+    message: string;
+    code: string | null;
+} | {
+    kind: "profile-consent";
+    request: ProfileConsentRequest;
+} | {
+    kind: "profile-link";
+    request: ProfileLinkRequest;
+} | {
+    kind: "done";
+    stopReason: string | null;
+};
+/**
+ * Normalize an agent endpoint to its invoke URL (guuey#186 G3). Accepts BOTH
+ * shapes a consumer legitimately holds — a pod base (`https://host`) and the
+ * full invoke URL the deploy-controller records (`https://host/agent/invoke`)
+ * — and returns exactly one `/agent/invoke`, trailing slashes dropped. This
+ * is the single normalization `useAgentInvoke` applies to its `endpointUrl`;
+ * a host driving {@link invokeTurn} (or any raw transport) directly builds
+ * its request URL with the same call instead of re-implementing the rule.
+ */
+export declare function toInvokeUrl(endpointUrl: string): string;
+/**
+ * Drive one `/agent/invoke` turn over `transport`, yielding semantic events.
+ * Pure per-turn: no React, no storage, no retry policy (the transport owns
+ * saturation retry), no reducer — see the module docblock for what belongs
+ * to the caller.
+ *
+ * The event stream is also the OBSERVATION channel (guuey#186 Gap 4): there
+ * is deliberately no `onToolResult` callback API, because filtering the
+ * generator expresses it directly — every tool result arrives as a typed
+ * `tool.done` AgEvent on a `message` event, carrying `toolCallId`,
+ * `content`, `outcome` and `structuredContent`.
+ *
+ * @example Telemetry off the fold — observe tool results without touching
+ * the transcript path:
+ * ```ts
+ * for await (const ev of invokeTurn(req, transport)) {
+ *   if (ev.kind !== "message") continue;
+ *   for (const agEvent of ev.agEvents) {
+ *     if (agEvent.type === "tool.done") {
+ *       telemetry.record(agEvent.toolCallId, agEvent.outcome ?? "ok");
+ *     }
+ *   }
+ *   render(ev.assistantText); // the fold is untouched by the observation
+ * }
+ * ```
+ */
+export declare function invokeTurn(req: InvokeRequest, transport: InvokeTransport): AsyncGenerator<InvokeTurnEvent>;
+//# sourceMappingURL=invoke-turn.d.ts.map

package/dist/invoke-turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke-turn.d.ts","sourceRoot":"","sources":["../src/invoke-turn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AASpD,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC5C;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,EAAE,UAAU,GAAG,YAAY,GAAG,YAAY,CAAC,CAAC;IAC9E,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB,GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,qBAAqB,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAEhD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAuB,UAAU,CAC/B,GAAG,EAAE,aAAa,EAClB,SAAS,EAAE,eAAe,GACzB,cAAc,CAAC,eAAe,CAAC,CA0EjC"}

package/dist/invoke-turn.js

@@ -0,0 +1,124 @@
+import { parseConsentRequest, parseLinkRequest, parseSseEvents, reduceAssistantText, stringField, } from "./sse.js";
+import { ingestMessageFrame } from "./blocks.js";
+/**
+ * Normalize an agent endpoint to its invoke URL (guuey#186 G3). Accepts BOTH
+ * shapes a consumer legitimately holds — a pod base (`https://host`) and the
+ * full invoke URL the deploy-controller records (`https://host/agent/invoke`)
+ * — and returns exactly one `/agent/invoke`, trailing slashes dropped. This
+ * is the single normalization `useAgentInvoke` applies to its `endpointUrl`;
+ * a host driving {@link invokeTurn} (or any raw transport) directly builds
+ * its request URL with the same call instead of re-implementing the rule.
+ */
+export function toInvokeUrl(endpointUrl) {
+    const base = endpointUrl.replace(/\/+$/, "");
+    return base.endsWith("/agent/invoke") ? base : `${base}/agent/invoke`;
+}
+/**
+ * Drive one `/agent/invoke` turn over `transport`, yielding semantic events.
+ * Pure per-turn: no React, no storage, no retry policy (the transport owns
+ * saturation retry), no reducer — see the module docblock for what belongs
+ * to the caller.
+ *
+ * The event stream is also the OBSERVATION channel (guuey#186 Gap 4): there
+ * is deliberately no `onToolResult` callback API, because filtering the
+ * generator expresses it directly — every tool result arrives as a typed
+ * `tool.done` AgEvent on a `message` event, carrying `toolCallId`,
+ * `content`, `outcome` and `structuredContent`.
+ *
+ * @example Telemetry off the fold — observe tool results without touching
+ * the transcript path:
+ * ```ts
+ * for await (const ev of invokeTurn(req, transport)) {
+ *   if (ev.kind !== "message") continue;
+ *   for (const agEvent of ev.agEvents) {
+ *     if (agEvent.type === "tool.done") {
+ *       telemetry.record(agEvent.toolCallId, agEvent.outcome ?? "ok");
+ *     }
+ *   }
+ *   render(ev.assistantText); // the fold is untouched by the observation
+ * }
+ * ```
+ */
+export async function* invokeTurn(req, transport) {
+    let assistantText = "";
+    let buffer = "";
+    for await (const chunk of transport(req)) {
+        buffer += chunk;
+        const { events, rest } = parseSseEvents(buffer);
+        buffer = rest;
+        for (const ev of events) {
+            if (ev.event === "session") {
+                // The pod is awake and the turn is admitted (this frame arrives
+                // within ~1s of a warm pod; a cold scale-to-zero start is exactly
+                // the long wait before it).
+                yield { kind: "session", threadId: stringField(ev.data, "threadId") ?? null };
+            }
+            else if (ev.event === "message") {
+                // Status derivation (guuey#91) — read the frame's `type` before the
+                // text fold. Silver frames announce tools + text explicitly; bypass
+                // frames ('text' / 'assistant' SDKMessages) only ever carry
+                // assistant text, so they map to 'responding'. Unknown types
+                // deliberately imply no status change.
+                const frameType = stringField(ev.data, "type");
+                assistantText = reduceAssistantText(assistantText, ev.data);
+                // Only VALID AgEvents surface (bypass frames ingest to []) — the
+                // caller's reducer, if any, advances on these alone.
+                const agEvents = ingestMessageFrame(ev.data);
+                if (frameType === "tool.start") {
+                    yield {
+                        kind: "message",
+                        status: "using-tool",
+                        activeTool: stringField(ev.data, "name") ?? null,
+                        assistantText,
+                        agEvents,
+                    };
+                }
+                else if (frameType === "tool.done") {
+                    yield { kind: "message", status: "thinking", activeTool: null, assistantText, agEvents };
+                }
+                else if (frameType === "text.start" ||
+                    frameType === "text.delta" ||
+                    frameType === "text" ||
+                    frameType === "assistant") {
+                    yield { kind: "message", status: "responding", assistantText, agEvents };
+                }
+                else {
+                    yield { kind: "message", assistantText, agEvents };
+                }
+            }
+            else if (ev.event === "error") {
+                // In-band failure frame — one of the two channels that carry the
+                // pod's wire code (the other is the pre-stream refusal thrown by the
+                // transport). A frame without a `code` yields null rather than
+                // leaving a previous turn's code standing beside a new message.
+                yield {
+                    kind: "error",
+                    message: stringField(ev.data, "message") ?? "agent error",
+                    code: stringField(ev.data, "code") ?? null,
+                };
+            }
+            else if (ev.event === "profile-consent-needed") {
+                // Cross-app profile consent ask (T6). Only a well-formed payload
+                // yields; a malformed one is dropped, leaving any prior valid
+                // request untouched (never clobbered to null).
+                const parsed = parseConsentRequest(ev.data);
+                if (parsed)
+                    yield { kind: "profile-consent", request: parsed };
+            }
+            else if (ev.event === "profile-link-needed") {
+                // Cross-app profile LINK invite (linkcoh T3) for an unlinked byo
+                // caller. Same drop-if-malformed contract as consent above.
+                const parsed = parseLinkRequest(ev.data);
+                if (parsed)
+                    yield { kind: "profile-link", request: parsed };
+            }
+            else if (ev.event === "done") {
+                // The stream closes after this frame; yielded so a host can read the
+                // pod's stop reason without private wire knowledge.
+                yield { kind: "done", stopReason: stringField(ev.data, "stopReason") ?? null };
+            }
+            // Any other (unknown) event falls through silently — additive wire
+            // events never disturb a consumer.
+        }
+    }
+}

package/dist/react.d.ts

@@ -6,6 +6,6 @@
  * history reader, and the web adapters). Consumers that only need those never
  * import React at all; consumers that render chat import the hook from here.
  */
-export { useAgentInvoke, applyHistoryResult, type HistoryApplication } from "./useAgentInvoke.js";
+export { useAgentInvoke, applyHistoryResult, type HistoryApplication, stallProbeDecision, STALL_RECOVERY_DEFAULTS, } from "./useAgentInvoke.js";
 export type { AgEvent, AgReduceResult } from "@silverprotocol/core";
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAIlG,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAI7B,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/react.js

@@ -6,4 +6,4 @@
  * history reader, and the web adapters). Consumers that only need those never
  * import React at all; consumers that render chat import the hook from here.
  */
-export { useAgentInvoke, applyHistoryResult } from "./useAgentInvoke.js";
+export { useAgentInvoke, applyHistoryResult, stallProbeDecision, STALL_RECOVERY_DEFAULTS, } from "./useAgentInvoke.js";

package/dist/saturation-retry.d.ts

@@ -57,4 +57,45 @@ export interface SaturationRetryOptions {
  * replaying a token that may have expired during the wait.
  */
 export declare function withSaturationRetry(transport: InvokeTransport, options?: SaturationRetryOptions): InvokeTransport;
+/** Options for {@link withColdStartRetry}. */
+export interface ColdStartRetryOptions {
+    /**
+     * Retries after the initial attempt (`0` disables the wrapper's behaviour
+     * entirely). Default 3 — a small, bounded budget: the point is parity with
+     * guuey's first-party embeds during the ordinary post-redeploy window, not
+     * riding out an outage. Raise it for an unattended harness that would
+     * rather wait than fail.
+     */
+    attempts?: number;
+    /**
+     * First wait in ms; each subsequent wait doubles, capped at
+     * {@link maxDelayMs}. Default 2000 → 2s / 4s / 8s for the default budget.
+     */
+    baseDelayMs?: number;
+    /** Ceiling on any single wait (hinted or computed), in ms. Default 10000. */
+    maxDelayMs?: number;
+    /** The wait itself — injectable so tests drive the retry without timers. */
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+}
+/**
+ * Wrap an invoke transport with a bounded retry on cold-start 503s
+ * (guuey#186 Gap 3 — parity with first-party embeds, which already carry
+ * this behaviour; SDK consumers were eating the raw 503 window instead).
+ *
+ * Matches ONLY {@link isColdStartRefusal} — an envelope-less 503 — and
+ * retries up to `attempts` times with doubling, capped backoff (honouring a
+ * `Retry-After` hint when the response carried one). Exhaustion propagates
+ * the final refusal untouched.
+ *
+ * Nothing is retried once a chunk has been yielded: a stream that dies
+ * MID-turn is never silently re-POSTed — the turn may have had side effects
+ * and the consumer already saw partial output. Same `yielded` guard as
+ * {@link withSaturationRetry}, same reasoning. An abort during a wait
+ * surfaces the refusal that caused the wait.
+ *
+ * Like the saturation wrapper, the retry is invisible to `useAgentInvoke`
+ * (the turn stays in `connecting`), and the wrapped transport is re-invoked
+ * from scratch so per-attempt identity resolution re-runs.
+ */
+export declare function withColdStartRetry(transport: InvokeTransport, options?: ColdStartRetryOptions): InvokeTransport;
 //# sourceMappingURL=saturation-retry.d.ts.map

package/dist/saturation-retry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"saturation-retry.d.ts","sourceRoot":"","sources":["../src/saturation-retry.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,YAAY,CAAC;AAiBjE;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAMhF;AA4BD,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,eAAe,EAC1B,OAAO,GAAE,sBAA2B,GACnC,eAAe,CAqBjB"}
+{"version":3,"file":"saturation-retry.d.ts","sourceRoot":"","sources":["../src/saturation-retry.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,YAAY,CAAC;AAiBjE;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAMhF;AA4BD,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,eAAe,EAC1B,OAAO,GAAE,sBAA2B,GACnC,eAAe,CAqBjB;AAED,8CAA8C;AAC9C,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAkBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,eAAe,EAC1B,OAAO,GAAE,qBAA0B,GAClC,eAAe,CA0BjB"}

package/dist/saturation-retry.js

@@ -1,15 +1,24 @@
 /**
- * The single `POD_SATURATED` auto-retry, as a transport-agnostic wrapper.
+ * The invoke-refusal retry wrappers, transport-agnostic: the single
+ * `POD_SATURATED` auto-retry ({@link withSaturationRetry}) and the bounded
+ * cold-start 503 retry ({@link withColdStartRetry}).
  *
- * Its own module — rather than living inside `./web-adapters.ts`, where it was
- * born — because the behaviour is a property of the POD's refusal vocabulary,
- * not of `fetch`. Every host that speaks `/agent/invoke` wants it, including
- * the ones that cannot import the web adapter bundle: Portal's React-Native
- * transport wraps its own `fetch` call with {@link withSaturationRetry} the
+ * Their own module — rather than living inside `./web-adapters.ts`, where the
+ * first was born — because the behaviour is a property of the platform's
+ * refusal vocabulary, not of `fetch`. Every host that speaks `/agent/invoke`
+ * wants them, including the ones that cannot import the web adapter bundle:
+ * Portal's React-Native transport wraps its own `fetch` call with these the
  * same way `fetchStreamTransport` wraps its browser streaming reader, so the
  * two wear byte-identical retry semantics instead of two hand-written copies
  * that drift.
  *
+ * The two wrappers are DELIBERATELY distinct code paths: saturation retry is
+ * driven by the pod's structured refusal envelope (`code: POD_SATURATED`),
+ * while the cold-start retry matches only an envelope-LESS 503 — the raw
+ * infra answer (ingress with no ready pod) during the post-redeploy window,
+ * which by definition carries no wire code. They share the backoff machinery,
+ * never the predicate.
+ *
  * This module imports only `./types.js`, `./errors.js` and `./error-codes.js`
  * — all pure — so pulling it in costs a React-Native build nothing.
  */
@@ -133,3 +142,66 @@ export function withSaturationRetry(transport, options = {}) {
         yield* transport(req);
     };
 }
+const COLD_START_DEFAULT_ATTEMPTS = 3;
+const COLD_START_BASE_DELAY_MS = 2_000;
+const COLD_START_MAX_DELAY_MS = 10_000;
+/**
+ * Is this failure the cold-start refusal shape? An envelope-less 503: the
+ * status came from infra (no ready pod behind the route — the ~30–60s window
+ * after a redeploy), so there is no wire `code`. A 503 that DOES carry a code
+ * is the pod itself refusing (`POD_SATURATED`, `DRAINING`) and belongs to
+ * {@link withSaturationRetry}'s policy — including its deliberate decision NOT
+ * to retry `DRAINING` — never to this wrapper.
+ */
+function isColdStartRefusal(err) {
+    return err instanceof AgentResponseError && err.status === 503 && err.code === undefined;
+}
+/**
+ * Wrap an invoke transport with a bounded retry on cold-start 503s
+ * (guuey#186 Gap 3 — parity with first-party embeds, which already carry
+ * this behaviour; SDK consumers were eating the raw 503 window instead).
+ *
+ * Matches ONLY {@link isColdStartRefusal} — an envelope-less 503 — and
+ * retries up to `attempts` times with doubling, capped backoff (honouring a
+ * `Retry-After` hint when the response carried one). Exhaustion propagates
+ * the final refusal untouched.
+ *
+ * Nothing is retried once a chunk has been yielded: a stream that dies
+ * MID-turn is never silently re-POSTed — the turn may have had side effects
+ * and the consumer already saw partial output. Same `yielded` guard as
+ * {@link withSaturationRetry}, same reasoning. An abort during a wait
+ * surfaces the refusal that caused the wait.
+ *
+ * Like the saturation wrapper, the retry is invisible to `useAgentInvoke`
+ * (the turn stays in `connecting`), and the wrapped transport is re-invoked
+ * from scratch so per-attempt identity resolution re-runs.
+ */
+export function withColdStartRetry(transport, options = {}) {
+    const attempts = options.attempts ?? COLD_START_DEFAULT_ATTEMPTS;
+    const baseDelayMs = options.baseDelayMs ?? COLD_START_BASE_DELAY_MS;
+    const maxDelayMs = options.maxDelayMs ?? COLD_START_MAX_DELAY_MS;
+    const sleep = options.sleep ?? delay;
+    return async function* retrying(req) {
+        let yielded = false;
+        for (let attempt = 0;; attempt++) {
+            try {
+                for await (const chunk of transport(req)) {
+                    yielded = true;
+                    yield chunk;
+                }
+                return;
+            }
+            catch (err) {
+                if (!isColdStartRefusal(err) || yielded || attempt >= attempts)
+                    throw err;
+                const hintedMs = err.retryAfterSeconds !== undefined ? err.retryAfterSeconds * 1000 : undefined;
+                const waitMs = Math.min(hintedMs ?? baseDelayMs * 2 ** attempt, maxDelayMs);
+                await sleep(waitMs, req.signal);
+                // Aborted mid-wait: surface the refusal that caused the wait rather
+                // than spending a request that `fetch` would reject on the signal.
+                if (req.signal.aborted)
+                    throw err;
+            }
+        }
+    };
+}