@foir/sdk 0.30.0 → 0.31.0

package/CHANGELOG.md

@@ -180,6 +180,20 @@ Changes on `dev` that have not been published to npm.
   stream nobody read, which threw. A page loaded again still picks the answer
   up from the stored run with `resume`.
 
+### Changed
+
+- **Breaking: a prose entry's identity is `_id`.** `Passage._key` is now
+  `Passage._id`, a markDef is named by its `_id`, and the renderers key
+  entries by `_id` alone. Ask for `_id` where a query asked for `_key`. The id
+  is minted once and never changes, and is unique within its record; it is not
+  a record id.
+- **Breaking: a reference is followed by `_targetId` alone.**
+  `Reference._targetNaturalKey` is gone: a reference names its target by id.
+  `Reference._id` is the entry's own id, never the target's.
+- **`Image`, `Video`, `FileValue` and `GeoPoint` carry `_id`**: the value's own
+  id when it is an item of a list or an entry of a prose field, and null on a
+  plain field's value.
+
 ## [0.29.0] — 2026-10-21
 
 ### Added

package/README.md

@@ -27,7 +27,7 @@ pnpm add yjs y-websocket    # for @foir/sdk/realtime
 | `@foir/sdk/data` | Typed data client over `/graphql` — `createFoirClient`, per-key-shaped ops, `include`/`omit`, `fetchFoirManifest`; prints the document for you, so still no `graphql` | **none** |
 | `@foir/sdk/auth` | Framework-agnostic sign-in for your app's users: login/register/OTP/provider flows, token lifecycle (`SessionAdapter`), `createFoirSessionClient` (Foir-hosted cookie sessions), `authedRequest`, guards | `graphql` |
 | `@foir/sdk/react` | Drop-in React auth — `<FoirProvider>` (token or `hostedSession` mode), `useFoirSession`/`useFoirUser`/`useFoirAuth`, `<SignIn>`, `<OAuthButtons>`, `<UserButton>` | `react`, `graphql` |
-| `@foir/sdk/next` | Next.js App Router BFF auth — `createFoirCookieAdapter`, `getFoirSession`, `foirSignIn*`, `completeFoirProviderLogin`, `createFoirMiddleware` | `graphql` |
+| `@foir/sdk/next` | Next.js App Router BFF auth: `createFoirCookieAdapter`, `getFoirSession`, `foirSignIn*`, `startFoirProviderSignIn`, `finishFoirProviderSignIn`, `createFoirMiddleware` | `graphql` |
 | `@foir/sdk/server` | Server-side helpers for extension/config API backends — `createServerClient`, `verifyWebhookSignature`, `verifyScopedToken`, callback client | — |
 | `@foir/sdk/live` | Live reads — the client half of Foir's invalidation graph: tag index, raw-payload store, `seq` ordering, record-change → tag mapping | **none** |
 | `@foir/sdk/live/react` | `<FoirLive>` — one socket, refcounted per model, wired to a query client you already have | `react` |

package/dist/ai/index.d.ts

@@ -55,9 +55,10 @@
  * `foirChatMessages` reads a thread back as `useChat`'s messages.
  */
 import type { ChatTransport, FlexibleSchema, UIMessage, UIMessageChunk } from 'ai';
-import type { FoirAgentAttachmentUpload, FoirAgentRun, FoirAgentRunNode, FoirAgentThread, FoirCreateAgentAttachmentArgs, FoirStartAgentRunArgs } from '../data/builtins';
+import type { FoirAgentAttachmentUpload, FoirAgentRun, FoirAgentHeldAct, FoirAgentRunNode, FoirAgentThread, FoirCreateAgentAttachmentArgs, FoirStartAgentRunArgs } from '../data/builtins';
 import type { FoirAgentRunEvent, FoirAgentRunSubscribeOptions } from '../data/subscriptions';
 import type { FoirSubscription } from '../data/ws-transport';
+import { type StepReply } from '../runs/step-reply';
 /** What the transport needs of a client: the agents namespace a key that runs an agent is given. */
 export interface FoirChatClient {
     ns: {
@@ -68,12 +69,7 @@ export interface FoirChatClient {
                 id: string;
                 approve: boolean;
                 reason?: string;
-            }): Promise<FoirAgentRunNode | null>;
-            answerPageTool(args: {
-                id: string;
-                output: unknown;
-                visitorToken?: string;
-            }): Promise<FoirAgentRunNode | null>;
+            }): Promise<FoirAgentHeldAct | null>;
             agentThread(args: {
                 id: string;
                 visitorToken?: string;
@@ -133,12 +129,6 @@ export interface FoirChatTransportOptions {
      */
     pageTools?: Record<string, FoirPageTool>;
 }
-/**
- * One run's events as `useChat`'s chunks. A run outlives a stream: it stops
- * for a decision and carries on once it is made, so what the person has
- * already been shown (the steps, the last event) is kept per run, and each
- * stream only opens and closes its own text.
- */
 export declare class FoirRunChunks {
     private readonly runId;
     private readonly runs;
@@ -150,14 +140,19 @@ export declare class FoirRunChunks {
     private opened;
     /** The run stopped for this stream's followers: it ended, or holds an act. */
     stopped: boolean;
-    /** Calls to the page's tools waiting for the app's `addToolOutput`. */
-    readonly pageCalls: Set<string>;
+    /**
+     * Calls to the page's tools waiting for the app's `addToolOutput`, each with
+     * the reply the page answers it by.
+     */
+    readonly pageCalls: Map<string, StepReply | null>;
     /** Calls to the page's tools the transport runs and answers itself, until the run hears them. */
     readonly answering: Set<string>;
     /** Calls the transport is to run: taken with `takeCalls`. */
     private toRun;
     /** Acts held for a decision, by anyone. */
     private readonly held;
+    /** The messages whose text this run has shown, streamed or whole. */
+    private readonly shown;
     /** `runs` names the page's tools the transport runs itself. */
     constructor(runId: string, runs?: (tool: string) => boolean);
     /** The calls to the page's tools that arrived for the transport to run. */

package/dist/ai.js

@@ -57,9 +57,162 @@ function randomSecret() {
   return out;
 }
 
+// src/transport/foir-http.ts
+var FoirRequestError = class extends Error {
+  /** HTTP status code, when the request failed at the HTTP layer. */
+  status;
+  /** GraphQL errors, when the request failed with a no-data error envelope. */
+  graphQLErrors;
+  /**
+   * The `data` the server did return, when a STRICT read refused a partial
+   * response. Present only on that path: without it, opting into strictness
+   * would trade a silent wrong answer for a thrown one that discards the answer,
+   * and a caller that wants to log what it nearly rendered could not.
+   */
+  partialData;
+  /**
+   * The selections the server stripped, when the refusal was a pruned document
+   * rather than a partial error. Same purpose as `partialData`: a caller that
+   * wants to log what it nearly rendered, or name the offending path in a
+   * developer-facing message, has it without re-parsing anything.
+   */
+  prunedSelections;
+  cause;
+  constructor(message, options) {
+    super(message);
+    this.name = "FoirRequestError";
+    this.cause = options?.cause;
+    this.status = options?.status;
+    this.graphQLErrors = options?.graphQLErrors;
+    this.partialData = options?.partialData;
+    this.prunedSelections = options?.prunedSelections;
+  }
+  /**
+   * The code of the first error, if the response carried one.
+   *
+   * A getter rather than a stored field so it stays correct for an error
+   * constructed anywhere, including by a caller in a test.
+   */
+  get code() {
+    return this.graphQLErrors?.[0]?.extensions?.code;
+  }
+  /** The correlation id, if the response carried one. */
+  get requestId() {
+    return this.graphQLErrors?.[0]?.extensions?.requestId;
+  }
+  /**
+   * Whether retrying this request could succeed.
+   *
+   * The 429 is the one that has to be in here and is easy to leave out: it sits
+   * among the 4xx statuses that are otherwise permanent, so a policy written as
+   * "retry 5xx, never retry 4xx" excludes exactly the failure that clears on its
+   * own. A storefront wrote that policy, its key saturated, and every read
+   * failed on the first attempt for an hour.
+   */
+  get retryable() {
+    if (this.status === void 0) {
+      if (this.graphQLErrors?.length || this.prunedSelections?.length) {
+        return this.code === "RATE_LIMITED" || this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
+      }
+      return true;
+    }
+    if (this.status === 429 || this.code === "RATE_LIMITED") return true;
+    if (this.status >= 500) return true;
+    return this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
+  }
+  /**
+   * How long to wait before retrying, in milliseconds, when the server said.
+   * Undefined when it did not, which means the caller picks its own backoff.
+   */
+  get retryAfterMs() {
+    const seconds = this.graphQLErrors?.[0]?.extensions?.retryAfter;
+    return typeof seconds === "number" && seconds > 0 ? seconds * 1e3 : void 0;
+  }
+};
+
+// src/transport/retry.ts
+var DEFAULT_ATTEMPTS = 3;
+var DEFAULT_BASE_DELAY_MS = 200;
+var DEFAULT_MAX_DELAY_MS = 2e4;
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function foirRetryDelayMs(error, attempt, policy = {}) {
+  if (!(error instanceof FoirRequestError) || !error.retryable) return null;
+  const max = policy.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+  const stated = error.retryAfterMs;
+  if (stated !== void 0) return Math.min(stated, max);
+  const base = policy.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+  return Math.min(base * 2 ** (attempt - 1), max);
+}
+async function withFoirRetry(fn, policy = {}) {
+  const attempts = Math.max(1, policy.attempts ?? DEFAULT_ATTEMPTS);
+  const sleep = policy.sleep ?? defaultSleep;
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await fn();
+    } catch (error) {
+      const delayMs = attempt >= attempts ? null : foirRetryDelayMs(error, attempt, policy);
+      if (delayMs === null) throw error;
+      policy.onRetry?.({ attempt, delayMs, error });
+      await sleep(delayMs);
+    }
+  }
+}
+
+// src/runs/step-reply.ts
+async function replyToStep(reply, body, opts = {}) {
+  if (!reply?.token || !reply.signingKey || !reply.endpoint) {
+    throw new Error("replyToStep: the step was handed no reply, so it cannot answer");
+  }
+  return sendReply(reply.endpoint, reply.token, reply.signingKey, body, opts);
+}
+async function sendReply(endpoint, token, signingKey, body, opts = {}) {
+  const fetchImpl = opts.fetch ?? globalThis.fetch;
+  if (!fetchImpl) throw new Error("replyToStep: no fetch available; pass opts.fetch on runtimes without a global fetch");
+  const payload = JSON.stringify(body);
+  const signature = await hmacSha256Hex(signingKey, payload);
+  return withFoirRetry(async () => {
+    let resp;
+    try {
+      resp = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`,
+          "X-Foir-Signature": `sha256=${signature}`
+        },
+        body: payload,
+        ...opts.signal ? { signal: opts.signal } : {}
+      });
+    } catch (err) {
+      if (opts.signal?.aborted) throw err;
+      throw new FoirRequestError("the reply got no answer", { cause: err });
+    }
+    if (!resp.ok) {
+      throw new FoirRequestError(`the reply was refused with HTTP ${resp.status}: ${await resp.text()}`, { status: resp.status });
+    }
+    const out = await resp.json();
+    if (!out || typeof out.status !== "string") {
+      throw new FoirRequestError("the reply was answered with nothing", { status: resp.status });
+    }
+    return { status: out.status, cancelled: out.cancelled === true, applied: out.applied === true };
+  }, opts.retry);
+}
+async function hmacSha256Hex(secret, body) {
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(body));
+  return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
 // src/ai/index.ts
 var TOOL_KINDS = /* @__PURE__ */ new Set(["VERB", "OPERATION", "MCP_TOOL", "AGENT", "PAGE_TOOL"]);
 var STOPS = /* @__PURE__ */ new Set(["COMPLETED", "FAILED", "SKIPPED", "CANCELLED", "HELD"]);
+function keptText(parts) {
+  return parts.map((p) => {
+    const part = p;
+    return part && part.type === "text" && typeof part.text === "string" ? part.text : "";
+  }).join("");
+}
 var FoirRunChunks = class {
   /** `runs` names the page's tools the transport runs itself. */
   constructor(runId, runs = () => false) {
@@ -76,14 +229,19 @@ var FoirRunChunks = class {
   opened = false;
   /** The run stopped for this stream's followers: it ended, or holds an act. */
   stopped = false;
-  /** Calls to the page's tools waiting for the app's `addToolOutput`. */
-  pageCalls = /* @__PURE__ */ new Set();
+  /**
+   * Calls to the page's tools waiting for the app's `addToolOutput`, each with
+   * the reply the page answers it by.
+   */
+  pageCalls = /* @__PURE__ */ new Map();
   /** Calls to the page's tools the transport runs and answers itself, until the run hears them. */
   answering = /* @__PURE__ */ new Set();
   /** Calls the transport is to run: taken with `takeCalls`. */
   toRun = [];
   /** Acts held for a decision, by anyone. */
   held = /* @__PURE__ */ new Set();
+  /** The messages whose text this run has shown, streamed or whole. */
+  shown = /* @__PURE__ */ new Set();
   /** The calls to the page's tools that arrived for the transport to run. */
   takeCalls() {
     const out = this.toRun;
@@ -118,6 +276,7 @@ var FoirRunChunks = class {
     switch (event.kind) {
       case "TEXT": {
         if (!event.text) break;
+        if (event.messageId) this.shown.add(event.messageId);
         this.open(out, fresh);
         this.closeReasoning(out);
         if (!this.textId) {
@@ -146,6 +305,19 @@ var FoirRunChunks = class {
         out.push(...this.toolChunks(node));
         break;
       }
+      case "MESSAGE": {
+        const message = event.message;
+        if (!message || message.role !== "ASSISTANT" || this.shown.has(message.id)) break;
+        const text = keptText(message.parts);
+        if (!text) break;
+        this.shown.add(message.id);
+        this.open(out, fresh);
+        this.closeText(out);
+        this.closeReasoning(out);
+        const id = `${this.runId}:m:${message.id}`;
+        out.push({ type: "text-start", id }, { type: "text-delta", id, delta: text }, { type: "text-end", id });
+        break;
+      }
       case "DATA": {
         if (!event.dataName) break;
         this.open(out, fresh);
@@ -161,7 +333,7 @@ var FoirRunChunks = class {
         if (event.status === "FAILED") {
           out.push({ type: "error", errorText: event.error || "The answer could not be finished." });
         }
-        if (event.status === "SKIPPED" && event.answer && this.tools.size === 0) {
+        if (event.status === "SKIPPED" && event.answer && this.tools.size === 0 && this.shown.size === 0) {
           const id = `${this.runId}:refusal`;
           out.push({ type: "text-start", id }, { type: "text-delta", id, delta: event.answer }, { type: "text-end", id });
         }
@@ -228,7 +400,7 @@ var FoirRunChunks = class {
         this.answering.add(node.id);
         this.toRun.push(node);
       } else {
-        this.pageCalls.add(node.id);
+        this.pageCalls.set(node.id, node.reply ?? null);
       }
       return out;
     }
@@ -348,7 +520,6 @@ function agentsOf(client, caller) {
       startAgentRun: refuse,
       onRun: refuse,
       decideAgentApproval: refuse,
-      answerPageTool: refuse,
       agentThread: refuse,
       createAgentAttachment: refuse
     };
@@ -394,6 +565,10 @@ function foirChatTransport(options) {
     }
     return c;
   };
+  const answerPage = async (id, reply, output) => {
+    if (!reply) throw new Error(`The call ${id} came without its reply, so the page cannot answer it.`);
+    await replyToStep(reply, { result: output ?? null });
+  };
   const answerCall = async (node, signal) => {
     const tool = pageTools[node.key];
     let output;
@@ -404,7 +579,7 @@ function foirChatTransport(options) {
     } catch (err) {
       output = { error: err instanceof Error ? err.message : String(err) };
     }
-    await agents.answerPageTool({ id: node.id, output, visitorToken: visitor });
+    await answerPage(node.id, node.reply, output);
   };
   const follow = (runId, fresh, signal) => {
     const chunks = chunksOf(runId);
@@ -456,7 +631,7 @@ function foirChatTransport(options) {
     async sendMessages({ chatId, messages, abortSignal }) {
       const decisions = decisionsIn(messages, decided);
       const waiting = /* @__PURE__ */ new Set();
-      for (const c of runs.values()) for (const id2 of c.pageCalls) waiting.add(id2);
+      for (const c of runs.values()) for (const id2 of c.pageCalls.keys()) waiting.add(id2);
       const answers = pageAnswersIn(messages, waiting);
       if (decisions.length > 0 || answers.length > 0) {
         for (const d of decisions) {
@@ -464,7 +639,9 @@ function foirChatTransport(options) {
           decided.add(d.id);
         }
         for (const a of answers) {
-          await agents.answerPageTool({ id: a.id, output: a.output, visitorToken: visitor });
+          let reply;
+          for (const c of runs.values()) reply ??= c.pageCalls.get(a.id);
+          await answerPage(a.id, reply, a.output);
           for (const c of runs.values()) c.pageCalls.delete(a.id);
         }
         let runId = lastRun.get(chatId);

package/dist/app/client.d.ts

@@ -462,11 +462,15 @@ export interface AppClient {
             deleted: boolean;
         }>;
         /**
-         * Drop what the data API has cached for one record, by natural key or id,
-         * so its next read resolves it again. False when Foir holds no such
-         * record. For a source read live from its host.
+         * Drop what the data API has cached for one record, named by its id or
+         * by its natural key, so its next read resolves it again. False when Foir
+         * holds no such record. For a source read live from its host.
          */
-        refresh(model: string, idOrKey: string): Promise<{
+        refresh(model: string, record: {
+            id: string;
+        } | {
+            naturalKey: string;
+        }): Promise<{
             refreshed: boolean;
         }>;
         /**
@@ -766,7 +770,7 @@ export interface AppStartedOperation {
     /** True when `concurrencyKey` matched a run in flight, so nothing was started. */
     joined: boolean;
     /** True when `idempotencyKey` matched a run in flight or completed, so nothing was started. */
-    deduplicated: boolean;
+    replayed: boolean;
 }
 /** Build the client an installed app calls Foir with. See the module doc. */
 export declare function createAppClient(config: AppClientConfig): AppClient;

package/dist/app.js

@@ -632,10 +632,16 @@ function createAppClient(config) {
         const deleted = await field(name, `mutation AppDeleteRecord($id: String!) { ${name}(id: $id) }`, { id });
         return { deleted: deleted === true };
       },
-      async refresh(model, idOrKey) {
-        if (idOrKey === "") refuse(`a record refresh on ${model} was given an empty name`);
+      async refresh(model, record) {
+        const byId = "id" in record;
+        const value = byId ? record.id : record.naturalKey;
+        if (value === "") refuse(`a record refresh on ${model} was given an empty name`);
         const name = `refresh${appModelTypeName(model)}`;
-        const refreshed = await field(name, `mutation AppRefreshRecord($idOrKey: String!) { ${name}(idOrKey: $idOrKey) }`, { idOrKey });
+        const refreshed = await field(
+          name,
+          byId ? `mutation AppRefreshRecord($id: ID!) { ${name}(id: $id) }` : `mutation AppRefreshRecord($naturalKey: String!) { ${name}(naturalKey: $naturalKey) }`,
+          byId ? { id: value } : { naturalKey: value }
+        );
         if (typeof refreshed !== "boolean") return refuse(`${name} reported no error and did not say whether it refreshed the record`);
         return { refreshed };
       },
@@ -972,12 +978,12 @@ function createAppClient(config) {
           args.push("concurrencyKey: $concurrencyKey");
           variables.concurrencyKey = options.concurrencyKey;
         }
-        const document = `mutation AppStartOperation(${params.join(", ")}) { startOperation(${args.join(", ")}) { executionId joined deduplicated } }`;
+        const document = `mutation AppStartOperation(${params.join(", ")}) { startOperation(${args.join(", ")}) { executionId joined replayed } }`;
         const keyed = Boolean(options.idempotencyKey || options.concurrencyKey);
         const data = keyed ? await run(document, variables) : await send(document, variables);
         const answer = data["startOperation"];
         if (!answer?.executionId) return refuse("startOperation reported no error and named no run");
-        return { executionId: answer.executionId, joined: answer.joined === true, deduplicated: answer.deduplicated === true };
+        return { executionId: answer.executionId, joined: answer.joined === true, replayed: answer.replayed === true };
       }
     }
   };
@@ -1067,18 +1073,11 @@ function readCallback(value) {
   if (!isObject(value)) return void 0;
   const token = text(value.token);
   if (!token) return void 0;
-  const mutations = isObject(value.mutations) ? value.mutations : {};
   const signingKey = text(value.signingKey);
   return {
-    gqlEndpoint: text(value.gqlEndpoint) ?? "",
+    endpoint: text(value.endpoint) ?? "",
     token,
     expiresAt: text(value.expiresAt) ?? "",
-    mutations: {
-      complete: text(mutations.complete) ?? "",
-      fail: text(mutations.fail) ?? "",
-      progress: text(mutations.progress) ?? "",
-      cancel: text(mutations.cancel) ?? ""
-    },
     ...Array.isArray(value.causationChain) ? { causationChain: value.causationChain.map(String) } : {},
     ...signingKey ? { signingKey } : {}
   };