@guuey/agent-client 0.3.1 → 0.5.0

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";
+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

@@ -0,0 +1,247 @@
+/**
+ * The invoke-refusal retry wrappers, transport-agnostic: the single
+ * `POD_SATURATED` auto-retry ({@link withSaturationRetry}) and the bounded
+ * cold-start 503 retry ({@link withColdStartRetry}).
+ *
+ * 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.
+ */
+import { AGENT_ERROR_CODES } from "./error-codes.js";
+import { AgentResponseError } from "./errors.js";
+import type { InvokeRequest, InvokeTransport } from "./types.js";
+
+/**
+ * Fallback wait before the saturation retry when the pod sent no usable
+ * `Retry-After` — the same 15s the pod's governor hints today
+ * (`GOVERNOR_RETRY_AFTER_SECONDS`), so a stripped header behaves like the
+ * normal case rather than hammering.
+ */
+const SATURATION_FALLBACK_DELAY_SECONDS = 15;
+
+/**
+ * Ceiling on the honoured hint. A pod that (mis)configures a multi-minute
+ * `Retry-After` must not park a chat UI in `connecting` for that long — past
+ * this the user is better served by the visible failure they can act on.
+ */
+const SATURATION_MAX_DELAY_SECONDS = 30;
+
+/**
+ * Read `Retry-After` as WHOLE SECONDS, or `undefined`.
+ *
+ * HTTP also allows an absolute HTTP-date, which is deliberately NOT parsed:
+ * the pod only ever emits a delta-seconds integer, and silently mis-reading a
+ * date as `NaN` seconds is worse than falling back to the fixed delay.
+ *
+ * Exported because every transport that builds an {@link AgentResponseError}
+ * has to fill `retryAfterSeconds` the same way for {@link withSaturationRetry}
+ * to honour the same hint — a second hand-rolled regex in a host adapter is
+ * exactly the drift this module exists to prevent.
+ */
+export function parseRetryAfterSeconds(header: string | null): number | undefined {
+  if (header === null) return undefined;
+  const trimmed = header.trim();
+  if (!/^\d+$/.test(trimmed)) return undefined;
+  const seconds = Number(trimmed);
+  return Number.isSafeInteger(seconds) ? seconds : undefined;
+}
+
+/** How long to wait before the single saturation retry, in milliseconds. */
+function saturationDelayMs(retryAfterSeconds: number | undefined): number {
+  const hinted = retryAfterSeconds ?? SATURATION_FALLBACK_DELAY_SECONDS;
+  return Math.min(hinted, SATURATION_MAX_DELAY_SECONDS) * 1000;
+}
+
+/**
+ * Wait `ms`, or resolve early if the turn is aborted — a user who hits stop
+ * must not sit through the remainder of a 15s backoff before the UI settles.
+ */
+function delay(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    if (signal.aborted) {
+      resolve();
+      return;
+    }
+    const finish = (): void => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", finish);
+      resolve();
+    };
+    const timer = setTimeout(finish, ms);
+    signal.addEventListener("abort", finish, { once: true });
+  });
+}
+
+/** Options for {@link withSaturationRetry}. */
+export interface SaturationRetryOptions {
+  /**
+   * The saturation-retry wait. Injectable so tests drive the retry without a
+   * real 15s timer; production uses an abort-aware `setTimeout`.
+   */
+  sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+}
+
+/**
+ * Wrap an invoke transport with ONE automatic retry on a saturated pod.
+ *
+ * ## What retries, and what deliberately does not
+ *
+ * `POD_SATURATED` (503) means the pod is at its concurrent-turn cap right now
+ * — a transient queue state that clears as in-flight turns finish, so a single
+ * delayed re-send usually just works. The wait is the pod's own `Retry-After`
+ * hint (via {@link AgentResponseError.retryAfterSeconds}), defaulting to 15s
+ * when it sent none and capped at 30s.
+ *
+ * `DRAINING` (also 503 + `Retry-After`) is NOT retried in v1. The refusing pod
+ * is shutting down: its readiness probe is already failing and the endpoint
+ * pull is in flight, so the useful retry is the one that reaches a DIFFERENT
+ * pod — and a wrapped transport re-sends to the same URL. Retrying here would
+ * spend the user's 15s to arrive back at the same draining pod (or at a fresh
+ * one by luck), which is not a guarantee worth building on. When the retry can
+ * be made routing-aware, this is the code to revisit.
+ *
+ * Exactly ONE retry: a second saturation propagates as
+ * {@link AgentResponseError}, so a genuinely overloaded agent surfaces instead
+ * of looping. Nothing is retried once a chunk has been yielded — replaying
+ * mid-stream would duplicate a partial assistant turn (the same `yielded`
+ * guard the widget's `withIdentifiedToken` 401-retry uses). An abort during
+ * the wait skips the retry and surfaces the original refusal.
+ *
+ * The retry is INVISIBLE to `useAgentInvoke`: no frames were yielded, so the
+ * turn simply stays in `connecting` for the duration of the wait. There is no
+ * `retrying` status by design — the hook's state machine describes the pod's
+ * turn lifecycle, not the transport's plumbing.
+ *
+ * The wrapped transport is re-invoked from scratch for the retry, so a host
+ * that resolves identity inside its own generator (Portal's RN transport reads
+ * the bearer bridge per attempt) re-reads it on the second try rather than
+ * replaying a token that may have expired during the wait.
+ */
+export function withSaturationRetry(
+  transport: InvokeTransport,
+  options: SaturationRetryOptions = {},
+): InvokeTransport {
+  return async function* retrying(req: InvokeRequest): AsyncGenerator<string> {
+    let yielded = false;
+    try {
+      for await (const chunk of transport(req)) {
+        yielded = true;
+        yield chunk;
+      }
+      return;
+    } catch (err) {
+      const saturated =
+        err instanceof AgentResponseError && err.code === AGENT_ERROR_CODES.POD_SATURATED;
+      if (!saturated || yielded) throw err;
+      await (options.sleep ?? delay)(saturationDelayMs(err.retryAfterSeconds), req.signal);
+      // Aborted mid-wait: the user is done with this turn. Surface the refusal
+      // that caused the wait rather than spending a request that `fetch` would
+      // reject on the signal anyway.
+      if (req.signal.aborted) throw err;
+    }
+    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;
+      }
+    }
+  };
+}

package/src/sse.ts

@@ -4,7 +4,7 @@
  * verbatim across web (Studio) and React-Native (Portal).
  */
 
-import type { ProfileConsentRequest, ProfileLinkRequest } from "./types";
+import type { ProfileConsentRequest, ProfileLinkRequest } from "./types.js";
 
 export interface ParsedSseEvent {
   event: string;