@guuey/agent-client 0.3.1 → 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
@@ -34,7 +35,11 @@ import { createWebAdapters } from "@guuey/agent-client";
 
 export function Chat({ endpointUrl, appId }: { endpointUrl: string; appId: string }) {
   const adapters = createWebAdapters({ getAccessToken: async () => myToken });
-  const { messages, send, isStreaming } = useAgentInvoke({ endpointUrl, appId, adapters });
+  const { messages, send, status, activeTool, error } = useAgentInvoke({
+    endpointUrl,
+    appId,
+    adapters,
+  });
 
   return (
     <>
@@ -43,7 +48,10 @@ export function Chat({ endpointUrl, appId }: { endpointUrl: string; appId: strin
           {m.text}
         </p>
       ))}
-      <button disabled={isStreaming} onClick={() => send("hello")}>
+      {status === "connecting" && <p>Waking your agent…</p>}
+      {status === "using-tool" && <p>Using {activeTool}…</p>}
+      {error && <p role="alert">{error}</p>}
+      <button disabled={status !== "ready"} onClick={() => send("hello")}>
         Send
       </button>
     </>
@@ -51,9 +59,48 @@ export function Chat({ endpointUrl, appId }: { endpointUrl: string; appId: strin
 }
 ```
 
+`status` walks the turn lifecycle — `ready` → `connecting` → `thinking` /
+`using-tool` (with `activeTool` naming the tool) / `responding` → back to
+`ready`. Failures never occupy `status`; they land in `error` and the
+composer re-enables. The full vocabulary is documented at
+[docs.guuey.com/sdk](https://docs.guuey.com/sdk).
+
 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

@@ -0,0 +1,87 @@
+/**
+ * The pod's error-envelope wire codes, TRANSCRIBED.
+ *
+ * The source of truth is the runtime's own private module
+ * (`backend/services/nocode-runtime/src/error-codes.ts`). This package is
+ * published to npm and cannot take a `@guuey-private` dependency, so it keeps
+ * its own copy — the same arrangement as {@link GUEST_HEADER} in
+ * `./web-adapters.ts` and `@guuey/host`'s mirrored fs-contract constants. The
+ * copies are not trusted to prose alone: `agent-client-codes.sync.test.ts` in
+ * the runtime package (which can import BOTH) asserts they stay identical, so
+ * renaming a code on either side fails that test rather than silently breaking
+ * a client branch.
+ *
+ * WIRE CONTRACT (what these codes appear in):
+ *
+ *  - a pre-stream refusal — `{ "code": …, "message": … }` with an HTTP status,
+ *    parsed into {@link AgentResponseError};
+ *  - an in-band failure — `event: error` / `data: { code, message }`, surfaced
+ *    as `useAgentInvoke`'s `errorCode`.
+ *
+ * Both channels carry the SAME vocabulary, which is why one mirror serves them.
+ */
+export declare const AGENT_ERROR_CODES: {
+    /** No usable identity on a surface that requires one. */
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    /** The invoke body did not parse / validate. */
+    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. */
+    readonly MANAGED_SPEND_CAP: "MANAGED_SPEND_CAP";
+    /**
+     * The pod is at its concurrent-turn cap (scaling S1-F3). A 503 carrying a
+     * `Retry-After` hint, and the ONE code {@link fetchStreamTransport} retries
+     * by itself — see its docblock for the single-attempt rule.
+     */
+    readonly POD_SATURATED: "POD_SATURATED";
+    /**
+     * The pod took SIGTERM and refuses NEW turns while in-flight ones finish.
+     * Also a 503 + `Retry-After`, but deliberately NOT auto-retried (the
+     * endpoint pull re-routes the next request; retrying into the same pod is
+     * the one thing guaranteed not to help).
+     */
+    readonly DRAINING: "DRAINING";
+    /** Refused for this caller — e.g. the link-prompt dismiss route's byo-only rule. */
+    readonly FORBIDDEN: "FORBIDDEN";
+    /** The turn ran past the pod's wall-clock budget. */
+    readonly TIMEOUT: "TIMEOUT";
+    /** A guuey-side dependency failed (not the agent's own code). */
+    readonly PLATFORM_ERROR: "PLATFORM_ERROR";
+    /** Unclassified pod failure. */
+    readonly INTERNAL: "INTERNAL";
+};
+/** 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

@@ -0,0 +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;;;;;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

@@ -0,0 +1,82 @@
+/**
+ * The pod's error-envelope wire codes, TRANSCRIBED.
+ *
+ * The source of truth is the runtime's own private module
+ * (`backend/services/nocode-runtime/src/error-codes.ts`). This package is
+ * published to npm and cannot take a `@guuey-private` dependency, so it keeps
+ * its own copy — the same arrangement as {@link GUEST_HEADER} in
+ * `./web-adapters.ts` and `@guuey/host`'s mirrored fs-contract constants. The
+ * copies are not trusted to prose alone: `agent-client-codes.sync.test.ts` in
+ * the runtime package (which can import BOTH) asserts they stay identical, so
+ * renaming a code on either side fails that test rather than silently breaking
+ * a client branch.
+ *
+ * WIRE CONTRACT (what these codes appear in):
+ *
+ *  - a pre-stream refusal — `{ "code": …, "message": … }` with an HTTP status,
+ *    parsed into {@link AgentResponseError};
+ *  - an in-band failure — `event: error` / `data: { code, message }`, surfaced
+ *    as `useAgentInvoke`'s `errorCode`.
+ *
+ * Both channels carry the SAME vocabulary, which is why one mirror serves them.
+ */
+export const AGENT_ERROR_CODES = {
+    /** No usable identity on a surface that requires one. */
+    UNAUTHORIZED: "UNAUTHORIZED",
+    /** The invoke body did not parse / validate. */
+    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. */
+    MANAGED_SPEND_CAP: "MANAGED_SPEND_CAP",
+    /**
+     * The pod is at its concurrent-turn cap (scaling S1-F3). A 503 carrying a
+     * `Retry-After` hint, and the ONE code {@link fetchStreamTransport} retries
+     * by itself — see its docblock for the single-attempt rule.
+     */
+    POD_SATURATED: "POD_SATURATED",
+    /**
+     * The pod took SIGTERM and refuses NEW turns while in-flight ones finish.
+     * Also a 503 + `Retry-After`, but deliberately NOT auto-retried (the
+     * endpoint pull re-routes the next request; retrying into the same pod is
+     * the one thing guaranteed not to help).
+     */
+    DRAINING: "DRAINING",
+    /** Refused for this caller — e.g. the link-prompt dismiss route's byo-only rule. */
+    FORBIDDEN: "FORBIDDEN",
+    /** The turn ran past the pod's wall-clock budget. */
+    TIMEOUT: "TIMEOUT",
+    /** A guuey-side dependency failed (not the agent's own code). */
+    PLATFORM_ERROR: "PLATFORM_ERROR",
+    /** 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/errors.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Error types the transports throw and the hook branches on.
+ *
+ * Its own module (rather than living in `./web-adapters.ts`) so `useAgentInvoke`
+ * — which must stay platform-agnostic — can `instanceof`-narrow a caught error
+ * without pulling the web adapter bundle (`fetch`, the history reader,
+ * `@guuey/mcp-apps-host`) into a React-Native build.
+ */
+/**
+ * Thrown when the pod returns a non-2xx status on `/agent/invoke` (before any
+ * SSE stream opens). Carries the pod's structured `{ code, message }` when
+ * present — e.g. a `QUOTA_EXCEEDED` 429 whose message ("…reached its plan
+ * generation limit…") the chat UI should surface — falling back to the bare
+ * status for non-JSON failures. See `AGENT_ERROR_CODES` for the vocabulary.
+ */
+export declare class AgentResponseError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    /**
+     * The response's `Retry-After` hint in whole seconds, when it sent a
+     * parseable one. The pod attaches it to its two 503 refusals
+     * (`POD_SATURATED`, `DRAINING`) and exposes the header across origins via
+     * `Access-Control-Expose-Headers`, so a browser client can actually read
+     * it. `undefined` when the header was absent, malformed, or in the
+     * HTTP-date form the pod never emits.
+     */
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(message: string, status: number, code?: string | undefined, 
+    /**
+     * The response's `Retry-After` hint in whole seconds, when it sent a
+     * parseable one. The pod attaches it to its two 503 refusals
+     * (`POD_SATURATED`, `DRAINING`) and exposes the header across origins via
+     * `Access-Control-Expose-Headers`, so a browser client can actually read
+     * it. `undefined` when the header was absent, malformed, or in the
+     * HTTP-date form the pod never emits.
+     */
+    retryAfterSeconds?: number | undefined);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM;gBAXnC,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,YAAA;IACtB;;;;;;;OAOG;IACM,iBAAiB,CAAC,EAAE,MAAM,YAAA;CAKtC"}

package/dist/errors.js

@@ -0,0 +1,36 @@
+/**
+ * Error types the transports throw and the hook branches on.
+ *
+ * Its own module (rather than living in `./web-adapters.ts`) so `useAgentInvoke`
+ * — which must stay platform-agnostic — can `instanceof`-narrow a caught error
+ * without pulling the web adapter bundle (`fetch`, the history reader,
+ * `@guuey/mcp-apps-host`) into a React-Native build.
+ */
+/**
+ * Thrown when the pod returns a non-2xx status on `/agent/invoke` (before any
+ * SSE stream opens). Carries the pod's structured `{ code, message }` when
+ * present — e.g. a `QUOTA_EXCEEDED` 429 whose message ("…reached its plan
+ * generation limit…") the chat UI should surface — falling back to the bare
+ * status for non-JSON failures. See `AGENT_ERROR_CODES` for the vocabulary.
+ */
+export class AgentResponseError extends Error {
+    status;
+    code;
+    retryAfterSeconds;
+    constructor(message, status, code, 
+    /**
+     * The response's `Retry-After` hint in whole seconds, when it sent a
+     * parseable one. The pod attaches it to its two 503 refusals
+     * (`POD_SATURATED`, `DRAINING`) and exposes the header across origins via
+     * `Access-Control-Expose-Headers`, so a browser client can actually read
+     * it. `undefined` when the header was absent, malformed, or in the
+     * HTTP-date form the pod never emits.
+     */
+    retryAfterSeconds) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = "AgentResponseError";
+    }
+}

package/dist/history.d.ts

@@ -11,7 +11,7 @@
  * has its own copy today and can migrate onto this later.
  */
 import type { AgMessage, JsonValue } from "@silverprotocol/core";
-import type { AgentMessage, HistoryCard, HistoryLoadResult } from "./types";
+import type { AgentMessage, HistoryCard, HistoryLoadResult } from "./types.js";
 /** One row of `GET /v1/threads/:id/messages`. */
 export interface ThreadHistoryRow {
     seq: number;

package/dist/history.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE5E,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CACjC;AAOD;;;;;;;;GAQG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,SAA6B;CAIjD;AAeD,qEAAqE;AACrE,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,YAAY,EAAE,CAOpF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,WAAW,EAAE,CAOhF;AAED,MAAM,WAAW,yBAAyB;IACxC,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,OAAO,EACP,QAAQ,EACR,WAAW,EACX,YAAoB,EACpB,SAAiB,GAClB,EAAE,yBAAyB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAuBxD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,WAAW,EAAE,CAE7E"}
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/E,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CACjC;AAOD;;;;;;;;GAQG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,SAA6B;CAIjD;AAeD,qEAAqE;AACrE,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,YAAY,EAAE,CAOpF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,WAAW,EAAE,CAOhF;AAED,MAAM,WAAW,yBAAyB;IACxC,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,OAAO,EACP,QAAQ,EACR,WAAW,EACX,YAAoB,EACpB,SAAiB,GAClB,EAAE,yBAAyB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAuBxD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,WAAW,EAAE,CAE7E"}

package/dist/index.d.ts

@@ -1,9 +1,15 @@
-export { parseSseEvents, extractAssistantText, reduceAssistantText, stringField, parseConsentRequest, parseLinkRequest, type ParsedSseEvent, } from "./sse";
-export { dismissLinkPrompt } from "./link-prompt";
-export { createUiResourceReader, type CreateUiResourceReaderOptions, createWebAdapters, localStorageThreadStore, webGenerateId, fetchStreamTransport, AgentResponseError, type CreateWebAdaptersOptions, } from "./web-adapters";
-export { fetchThreadHistory, threadHistoryRowsToMessages, threadHistoryRowsToCards, HistoryUnauthorizedError, type ThreadHistoryRow, type ThreadHistoryFetchOptions, } from "./history";
-export { ingestMessageFrame } from "./blocks";
-export { sortHistoryCards, toolNameFor } from "./history";
+export { parseSseEvents, extractAssistantText, reduceAssistantText, stringField, parseConsentRequest, parseLinkRequest, type ParsedSseEvent, } from "./sse.js";
+export { dismissLinkPrompt } from "./link-prompt.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, 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";
+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,OAAO,CAAC;AACf,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,sBAAsB,EACtB,KAAK,6BAA6B,EAClC,iBAAiB,EACjB,uBAAuB,EACvB,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,wBAAwB,GAC9B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,GAC/B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAK9C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAI1D,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,SAAS,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,10 +1,35 @@
-export { parseSseEvents, extractAssistantText, reduceAssistantText, stringField, parseConsentRequest, parseLinkRequest, } from "./sse";
-export { dismissLinkPrompt } from "./link-prompt";
-export { createUiResourceReader, createWebAdapters, localStorageThreadStore, webGenerateId, fetchStreamTransport, AgentResponseError, } from "./web-adapters";
-export { fetchThreadHistory, threadHistoryRowsToMessages, threadHistoryRowsToCards, HistoryUnauthorizedError, } from "./history";
-export { ingestMessageFrame } from "./blocks";
+export { parseSseEvents, extractAssistantText, reduceAssistantText, stringField, parseConsentRequest, parseLinkRequest, } 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 } 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, 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
 // (shared by Studio's `AgentBlocks` and Portal-web's agent chat). React-free.
 // 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";
+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"}