@guuey/agent-client 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/agent-client",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Client SDK for Guuey's agent runtime: the `useAgentInvoke` React hook + pure SSE helpers that speak the /agent/invoke streaming contract, plus the paginated thread-history read plane. Host adapters (storage / id / transport) are injected, so it runs on web (Next) and React Native alike.",
   "license": "MIT",
   "type": "module",
@@ -25,11 +25,17 @@
       "types": "./dist/react.d.ts",
       "import": "./dist/react.js",
       "default": "./dist/react.js"
+    },
+    "./transport": {
+      "react-native": "./src/transport.ts",
+      "types": "./dist/transport.d.ts",
+      "import": "./dist/transport.js",
+      "default": "./dist/transport.js"
     }
   },
   "dependencies": {
     "@silverprotocol/core": "0.4.1",
-    "@guuey/mcp-apps-host": "0.4.0"
+    "@guuey/mcp-apps-host": "0.5.0"
   },
   "peerDependencies": {
     "react": ">=18"

package/src/error-codes.ts

@@ -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. */
@@ -56,3 +63,27 @@ export 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 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",
+} as const;
+
+/** 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];

package/src/index.ts

@@ -8,6 +8,9 @@ export {
   type ParsedSseEvent,
 } from "./sse.js";
 export { dismissLinkPrompt } from "./link-prompt.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, type InvokeTurnEvent } from "./invoke-turn.js";
 export {
   createUiActionRelay,
   type CreateUiActionRelayOptions,
@@ -16,24 +19,41 @@ export {
   createWebAdapters,
   localStorageThreadStore,
   webGenerateId,
-  fetchStreamTransport,
   type CreateWebAdaptersOptions,
 } 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.
+// 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,
+  type FetchStreamTransportOptions,
+} 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,
   type SaturationRetryOptions,
+  type ColdStartRetryOptions,
 } 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, type AgentErrorCode } from "./error-codes.js";
+export {
+  AGENT_ERROR_CODES,
+  type AgentErrorCode,
+  CLIENT_ERROR_CODES,
+  type ClientErrorCode,
+} from "./error-codes.js";
 export {
   fetchThreadHistory,
   threadHistoryRowsToMessages,
@@ -50,7 +70,10 @@ export { ingestMessageFrame } from "./blocks.js";
 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.
+// `@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";
 export type { AgEvent, AgReduceResult, AgMessage, AgBlock } from "@silverprotocol/core";
 export type {
   AgentMessage,
@@ -65,6 +88,7 @@ export type {
   AgentInvokeHistoryAdapter,
   AgentInvokeStatus,
   HistoryLoadResult,
+  StallRecoveryOptions,
   UseAgentInvokeOptions,
   UseAgentInvokeReturn,
 } from "./types.js";

package/src/invoke-turn.ts

@@ -0,0 +1,187 @@
+/**
+ * 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 {
+  parseConsentRequest,
+  parseLinkRequest,
+  parseSseEvents,
+  reduceAssistantText,
+  stringField,
+} from "./sse.js";
+import { ingestMessageFrame } from "./blocks.js";
+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 function toInvokeUrl(endpointUrl: string): string {
+  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: InvokeRequest,
+  transport: InvokeTransport,
+): AsyncGenerator<InvokeTurnEvent> {
+  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/src/react.ts

@@ -6,7 +6,13 @@
  * 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";
 // The block-preserving transcript surfaces `AgReduceResult`; re-export it (and
 // `AgEvent`) here so `./react` consumers can type `reduceResult` without a
 // direct `@silverprotocol/core` import.

package/src/saturation-retry.ts

@@ -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.
  */
@@ -148,3 +157,91 @@ export function withSaturationRetry(
     yield* transport(req);
   };
 }
+
+/** 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>;
+}
+
+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: unknown): err is AgentResponseError {
+  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: InvokeTransport,
+  options: ColdStartRetryOptions = {},
+): InvokeTransport {
+  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: InvokeRequest): AsyncGenerator<string> {
+    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;
+      }
+    }
+  };
+}