@inflexa-ai/harness 0.45.1 → 0.46.2

package/dist/loop/tool-adapter.js

@@ -0,0 +1,364 @@
+/**
+ * The adapter from a harness `Tool` to an AI SDK tool.
+ *
+ * Each call runs as one durable step inside a workflow (`durableTools`), and
+ * directly outside one. The step output is one plain JSON value, the
+ * `ToolCallOutput`: the outcome of the call, its value or its excerpt, the
+ * call record, and the pictures. Thus a replay gets back each fact that the
+ * loop reads later, and the tool body does not run again.
+ *
+ * The adapter never throws for a failed call: the failure becomes an error
+ * output that the model reads. Only a fatal error leaves the call, for example
+ * the cancel of the workflow, and the loop then ends the run with it.
+ *
+ * The model reads the view that `toModelOutput` builds from the output. It never
+ * reads the call record.
+ */
+import { durableTools } from "@dbos-inc/vercel-ai";
+import { jsonSchema, tool as aiTool } from "ai";
+import { z } from "zod";
+import { stripNulCharacters } from "../input-sanitization.js";
+import { ResultError } from "../lib/result.js";
+import { errorMessageOf, errorNameOf, errorOf } from "../lib/thrown.js";
+import { textOf } from "../lib/unknown-text.js";
+import { describeZodIssueShapes } from "../lib/zod-issue-shape.js";
+import { hintForZodIssue, repairToolInput } from "../lib/zod-issues.js";
+import { classifyProviderError } from "../providers/errors.js";
+import { isWorkflowCancellation } from "../runtime/dbos.js";
+import { isToolError, readToolCallRecord, readToolResultImages, } from "../tools/define-tool.js";
+import { recordKeyFor } from "./accounting.js";
+import { computeDetail, computeResultDetail } from "./tool-detail.js";
+import { excerptOf, keptTextOf, TOOL_RESULT_CAP, toolOutputRef } from "./tool-output.js";
+const ToolResultImageSchema = z.object({ base64: z.string(), mediaType: z.string() });
+const JsonSchema = z.json();
+/**
+ * The output of one tool call, as its step records it.
+ *
+ * - `ok`: the value that the tool gave, or the excerpt of a value longer than
+ *   the cap. A cut value keeps only its excerpt. `record` is the call record,
+ *   and `images` are the pictures that the wire of the run carries.
+ * - `error`: the text that the model reads, already cut when it is long.
+ * - `denied`: the user rejected the approval that the tool asked for.
+ */
+export const ToolCallOutputSchema = z.discriminatedUnion("outcome", [
+    z.object({
+        outcome: z.literal("ok"),
+        value: JsonSchema.optional(),
+        excerpt: z.string().optional(),
+        record: JsonSchema.optional(),
+        images: z.array(ToolResultImageSchema).optional(),
+    }),
+    z.object({ outcome: z.literal("error"), text: z.string() }),
+    z.object({ outcome: z.literal("denied"), reason: z.string() }),
+]);
+/**
+ * The input of a recorded call as the call itself read it. A stringified
+ * argument gets the repair of the call, thus a selector of the outcome reads
+ * the value that the tool checked.
+ */
+export function recordedInputOf(schema, raw) {
+    const parsed = schema.safeParse(raw);
+    if (parsed.success)
+        return parsed.data;
+    const repaired = schema.safeParse(repairToolInput(raw, parsed.error));
+    return repaired.success ? repaired.data : undefined;
+}
+/** A cancel of the run or of its workflow is control flow, never a result that the model reads. */
+export function isFatalToolError(err) {
+    return errorNameOf(err) === "AbortError" || isWorkflowCancellation(err);
+}
+/**
+ * The AI SDK tools of a run. Inside a workflow each call is a durable step
+ * named `<tool>.<toolCallId>`. A throw from a call is fatal by construction,
+ * because the adapter turns each other failure into an output.
+ */
+export function adaptTools(tools, run) {
+    const set = {};
+    for (const harnessTool of tools) {
+        set[harnessTool.id] = aiTool({
+            description: harnessTool.description,
+            // No validation here: the call validates its input, thus a failure keeps
+            // the repair of a stringified argument and the hints of the harness.
+            inputSchema: jsonSchema(harnessTool.jsonSchema),
+            execute: (input, options) => runToolCall(harnessTool, input, options, run),
+            toModelOutput: ({ output }) => modelViewOf(output),
+        });
+    }
+    // A call that starts a child workflow runs in the body, because a step cannot start a workflow.
+    const inBody = Object.fromEntries(tools.filter((tool) => tool.startsWorkflow === true).map((tool) => [tool.id, false]));
+    const durable = durableTools(set, { tools: inBody, writer: run.writer });
+    const guarded = {};
+    for (const [name, definition] of Object.entries(durable)) {
+        const execute = definition.execute;
+        if (execute === undefined) {
+            guarded[name] = definition;
+            continue;
+        }
+        guarded[name] = {
+            ...definition,
+            execute: async (input, options) => {
+                try {
+                    return await execute(input, options);
+                }
+                catch (err) {
+                    run.fail(err);
+                    throw err;
+                }
+            },
+        };
+    }
+    return guarded;
+}
+/** What the model reads of one output. */
+export function modelViewOf(output) {
+    switch (output.outcome) {
+        case "ok": {
+            const images = output.images ?? [];
+            if (images.length > 0) {
+                return {
+                    type: "content",
+                    value: [
+                        { type: "text", text: output.excerpt ?? JSON.stringify(output.value ?? null) },
+                        ...images.map((image) => ({ type: "file", mediaType: image.mediaType, data: { type: "data", data: image.base64 } })),
+                    ],
+                };
+            }
+            return output.excerpt === undefined ? { type: "json", value: output.value ?? null } : { type: "text", value: output.excerpt };
+        }
+        case "error":
+            return { type: "error-text", value: output.text };
+        case "denied":
+            return { type: "execution-denied", reason: output.reason };
+    }
+}
+/** The outcome that an event and a counter report for one output. */
+export function outcomeOf(output) {
+    return output.outcome;
+}
+/** Hand the call record of each output to its tool, in the order of the calls. A throw is logged, because the call has settled already. */
+export function foldCallRecords(tools, calls, log) {
+    const byId = new Map(tools.map((t) => [t.id, t]));
+    for (const call of calls) {
+        const output = call.output;
+        if (output?.outcome !== "ok" || output.record === undefined)
+            continue;
+        const tool = byId.get(call.toolName);
+        if (tool?.foldCallRecord === undefined)
+            continue;
+        try {
+            tool.foldCallRecord(output.record);
+        }
+        catch (err) {
+            log.error("a tool call record did not fold", { tool: tool.id, toolCallId: call.toolCallId, ...log.errorFields(err) });
+        }
+    }
+}
+async function runToolCall(tool, input, options, run) {
+    const startedAt = performance.now();
+    const { toolCallId } = options;
+    const detail = computeDetail(tool, input, run.log);
+    // The emit and the call start before the first await: a call that runs in the body of a workflow takes its
+    // function ids in the order of the calls, thus a replay gives each call its own child.
+    const started = run.emit({ type: "tool-started", source: run.source, toolUseId: toolCallId, name: tool.id, input, ...detailField(detail) });
+    const ctx = {
+        invocationId: toolCallId,
+        session: run.session,
+        signal: options.abortSignal ?? new AbortController().signal,
+        emit: run.emit,
+        turnUsage: run.turnUsage,
+    };
+    // One wait reads the two, thus a failed emit leaves no rejection of the call unread.
+    const [, settled] = await Promise.all([started, settleCall(tool, input, ctx, run)]);
+    const output = await cutLongOutput(settled.output, tool.id, toolCallId, run);
+    await run.emit({
+        type: "tool-finished",
+        source: run.source,
+        toolUseId: toolCallId,
+        name: tool.id,
+        outcome: output.outcome,
+        ...detailField(settled.detail ?? detail),
+        durationMs: Math.round(performance.now() - startedAt),
+    });
+    return output;
+}
+async function settleCall(tool, input, ctx, run) {
+    const parsed = tool.inputSchema.safeParse(input);
+    let data;
+    if (parsed.success) {
+        data = parsed.data;
+    }
+    else {
+        // A complete JSON argument can arrive as a string behind function-call
+        // markup or a code fence. Repair only makes the schema reachable — the
+        // repaired value is validated in full, and the tool's own semantic checks
+        // still run, so nothing here weakens validation.
+        const repairedInput = repairToolInput(input, parsed.error);
+        const repaired = repairedInput === undefined ? undefined : tool.inputSchema.safeParse(repairedInput);
+        if (repaired?.success !== true) {
+            // The Zod text can quote the input, thus the log gets only the shape of the failure.
+            run.log.warn("tool call rejected", { tool: tool.id, toolCallId: ctx.invocationId, issues: describeZodIssueShapes(parsed.error, tool.inputSchema) });
+            return { output: errorOutput(`input validation failed: ${formatZodIssues(parsed.error, input)}`) };
+        }
+        data = repaired.data;
+    }
+    try {
+        const result = await tool.execute(data, ctx);
+        if (result.isErr()) {
+            logToolFailure(tool, ctx.invocationId, result.error, run.log);
+            return { output: errorOutput(toolErrorContent(result.error)) };
+        }
+        // The one place a result description runs: the ok value in hand, the
+        // input already validated, and the guard inside the compute.
+        return { output: okOutput(tool.id, result.value, run), detail: computeResultDetail(tool, data, result.value, run.log) };
+    }
+    catch (err) {
+        if (isFatalToolError(err))
+            throw err;
+        logToolFailure(tool, ctx.invocationId, err, run.log);
+        return { output: errorOutput(toolErrorContent(err)) };
+    }
+}
+/**
+ * The ok output of a value. The JSON data loses each NUL, and the pictures leave
+ * it. A wire that carries no picture in a tool result gets the text alone, and
+ * one warn with the count rides the log: base64 text floods the context, and the
+ * model cannot see it.
+ */
+function okOutput(toolId, value, run) {
+    const output = {
+        outcome: "ok",
+        value: jsonValue(value),
+    };
+    const record = readToolCallRecord(value);
+    // The record crosses the step cache, thus the contract of a call record is plain JSON.
+    if (record !== undefined)
+        output.record = jsonValue(record);
+    const images = readToolResultImages(value);
+    if (images.length > 0) {
+        if (run.capabilities.imageToolResults === true) {
+            output.images = images.map((image) => ({ base64: image.base64, mediaType: image.mediaType }));
+        }
+        else {
+            run.log.warn("the wired provider carries no picture in a tool result, thus the pictures are dropped", {
+                toolName: toolId,
+                imageCount: images.length,
+            });
+        }
+    }
+    return output;
+}
+function errorOutput(text) {
+    // A thrown tool error routinely quotes stderr verbatim — as exposed to NUL as a success payload.
+    return { outcome: "error", text: stripNulCharacters(text) };
+}
+/**
+ * The output with an excerpt in place of a text longer than the cap. The text
+ * is kept first under a reference that a rerun of the call gives again, and the
+ * excerpt does not depend on the outcome of the put. Thus a rerun gives the
+ * same bytes.
+ */
+async function cutLongOutput(output, toolName, toolCallId, run) {
+    if (output.outcome === "denied")
+        return output;
+    const text = output.outcome === "ok" ? JSON.stringify(output.value ?? null) : output.text;
+    if (text.length <= TOOL_RESULT_CAP)
+        return output;
+    let kept;
+    if (run.store !== undefined) {
+        const { session } = run;
+        const ref = toolOutputRef(recordKeyFor(session, run.invocationId, toolCallId));
+        const content = keptTextOf(text);
+        // A run session carries the thread of the chat that started the run, but a run belongs to its analysis.
+        const threadId = session.runFrame === undefined ? session.scope.threadId : undefined;
+        const put = await run.store.put({
+            analysisId: session.scope.analysisId,
+            ref,
+            toolName,
+            toolCallId,
+            content,
+            totalLength: text.length,
+            threadId,
+        });
+        if (put.isErr())
+            run.log.warn("tool output not kept", { toolName, toolCallId, ref, errorType: put.error.type });
+        kept = { ref, keptLength: content.length };
+    }
+    const excerpt = excerptOf(text, kept);
+    if (output.outcome === "error")
+        return { outcome: "error", text: excerpt };
+    const cut = {
+        outcome: "ok",
+        excerpt,
+    };
+    if (output.record !== undefined)
+        cut.record = output.record;
+    if (output.images !== undefined)
+        cut.images = output.images;
+    return cut;
+}
+/**
+ * Log a tool failure. A `ToolError` is a failure that the tool modeled, thus its
+ * own text is the account. Any other `Error` is a fault that the tool did not
+ * model, and the log gets one warn.
+ */
+function logToolFailure(tool, toolCallId, failure, log) {
+    if (modeledToolError(failure) !== undefined)
+        return;
+    const failureError = errorOf(failure);
+    if (failureError !== undefined)
+        log.warn("tool call threw", { tool: tool.id, toolCallId, ...log.errorFields(failureError) });
+}
+/** The `ToolError` of a failure: the value itself, or the value that `unwrapOrThrow` wrapped in a `ResultError`. */
+function modeledToolError(failure) {
+    if (isToolError(failure))
+        return failure;
+    return failure instanceof ResultError && isToolError(failure.value) ? failure.value : undefined;
+}
+/**
+ * Normalize a tool's return value to plain JSON, stripping NUL from every string
+ * it holds. The reviver sees values, not keys — a NUL in an object KEY would
+ * still reach the row, but keys come from tool result types rather than scanned
+ * bytes, so nothing produces one.
+ */
+function jsonValue(value) {
+    // The stringify/parse round trip holds only JSON values, so the parse never
+    // refuses; it moves the parser's `any` out of the tool-result field.
+    // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the NUL-stripping reviver walks a value this code serialized one line above, not text of unknown shape; a schema proves nothing here.
+    const serialized = JSON.parse(JSON.stringify(value ?? null), (_key, v) => (typeof v === "string" ? stripNulCharacters(v) : v));
+    return JsonSchema.parse(serialized);
+}
+// NUL is stripped from the prose BEFORE it is serialized: past the stringify it
+// is the six-character escape \u0000 — legitimate JSON text, and no longer
+// distinguishable from an error that happens to quote that escape.
+function toolErrorContent(value) {
+    const toolError = modeledToolError(value);
+    if (toolError !== undefined) {
+        return JSON.stringify({ error: stripNulCharacters(toolError.error), retryable: toolError.retryable });
+    }
+    const { retryable } = classifyProviderError(value);
+    const error = stripNulCharacters(errorMessageOf(value) ?? textOf(value));
+    return JSON.stringify({ error, retryable });
+}
+/** The prose of a rejected approval is the only account that the model gets of the denial. */
+export function deniedReason(feedback) {
+    return feedback === undefined || feedback.length === 0
+        ? "The user rejected this action."
+        : `The user rejected this action with the following feedback: ${feedback}`;
+}
+/**
+ * The optional `detail` field, present only when there is one. Spread rather
+ * than assigned so an undescribed call emits an event with no `detail` key at
+ * all, which is what the contract promises: absent, never empty.
+ */
+function detailField(detail) {
+    return detail === undefined ? {} : { detail };
+}
+function formatZodIssues(error, input) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+        const hint = hintForZodIssue(issue, input);
+        return hint === undefined ? `${path}: ${issue.message}` : `${path}: ${issue.message} — ${hint}`;
+    })
+        .join("; ");
+}

package/dist/loop/tool-detail.d.ts

@@ -19,7 +19,7 @@
 import type { ToolCallDetail } from "../contracts/chat-events.js";
 import type { Logger } from "../lib/logger.js";
 import type { Tool } from "../tools/define-tool.js";
-export type { ToolCallDetail };
+export type { ToolCallDetail } from "../contracts/chat-events.js";
 /**
  * The length cap, in characters. A full workspace path with a line range fits
  * comfortably; a `write_file` content field does not, which is the point — a

package/dist/loop/tool-detail.js

@@ -17,6 +17,7 @@
  *    the length cap slightly wrong. Here it is one auditable path.
  */
 import { normalizeUnicode, redactSecrets } from "../input-sanitization.js";
+import { collapseWhitespace } from "../lib/text.js";
 /**
  * The length cap, in characters. A full workspace path with a line range fits
  * comfortably; a `write_file` content field does not, which is the point — a
@@ -88,7 +89,7 @@ export function normalizeDetail(raw) {
     // `normalizeUnicode` leaves tab, newline and carriage return in place (they
     // are legitimate whitespace in prose); the collapse below is what turns them
     // into the single line this contract promises.
-    const oneLine = normalizeUnicode(raw).replace(/\s+/g, " ").trim();
+    const oneLine = collapseWhitespace(normalizeUnicode(raw));
     if (oneLine.length === 0)
         return undefined;
     const capped = capCodePoints(redactSecrets(oneLine), DETAIL_MAX_LENGTH);
@@ -112,9 +113,9 @@ export function computeDetail(tool, rawInput, log) {
     // an open list — an embedder contributes its own through the host-tools seam —
     // so a `describeCall` that is not callable is reachable. Such a tool counts as
     // undescribed, because the alternative is a TypeError on every one of its calls.
-    const describeCall = tool.describeCall;
-    if (typeof describeCall !== "function")
+    if (typeof tool.describeCall !== "function")
         return undefined;
+    const describeCall = tool.describeCall.bind(tool);
     try {
         // The parse is INSIDE the guard, not before it. `safeParse` returns an
         // error for a rejected value but THROWS for a schema it cannot run
@@ -155,9 +156,9 @@ export function computeResultDetail(tool, parsedInput, result, log) {
     // The guard tests for a function, not for presence, for the same reason as in
     // `computeDetail`: a packaged tool comes from an open list, thus a
     // `describeResult` that is not callable is reachable.
-    const describeResult = tool.describeResult;
-    if (typeof describeResult !== "function")
+    if (typeof tool.describeResult !== "function")
         return undefined;
+    const describeResult = tool.describeResult.bind(tool);
     try {
         return normalizeDetail(describeResult(parsedInput, result));
     }

package/dist/loop/tool-outcome.d.ts

@@ -9,7 +9,7 @@
  * reporting success for every call because it never looked at the result at all.
  */
 import type { ToolOutcome } from "../contracts/chat-events.js";
-export type { ToolOutcome };
+export type { ToolOutcome } from "../contracts/chat-events.js";
 /**
  * Classify a tool result's output type.
  *

package/dist/loop/tool-output.d.ts

@@ -14,7 +14,7 @@ export declare const EXCERPT_TAIL_CHARS: number;
 /** The bound of a file that `grep` reads, thus a pattern search over a kept text costs no more than a `grep`. */
 export declare const TOOL_OUTPUT_KEEP_MAX: number;
 export declare const READ_TOOL_OUTPUT_TOOL_ID = "read_tool_output";
-export interface KeptToolOutput {
+export type KeptToolOutput = {
     readonly analysisId: string;
     readonly ref: string;
     readonly toolName: string;
@@ -25,13 +25,13 @@ export interface KeptToolOutput {
     readonly content: string;
     /** The length of the whole text of the result. */
     readonly totalLength: number;
-}
+};
 /** Keeps the text of each cut tool result for `read_tool_output`. */
-export interface ToolOutputStore {
+export type ToolOutputStore = {
     /** A second put of the same analysis id and reference replaces the text. */
     put(output: KeptToolOutput): ResultAsync<void, DomainError>;
     get(analysisId: string, ref: string): ResultAsync<KeptToolOutput | null, DomainError>;
-}
+};
 /** The reference of one kept text. It is short, because the model copies it. */
 export declare function toolOutputRef(key: string): string;
 /** The text that the model reads for a result, or `undefined` for a denial, which is never cut. */

package/dist/loop/tool-output.js

@@ -26,7 +26,7 @@ export function resultTextOf(output) {
         case "error-text":
             return output.value;
         case "content":
-            return output.value.map((part) => (part.type === "text" ? part.text : "")).join("");
+            return output.value.map((part) => ("text" in part ? part.text : "")).join("");
         case "execution-denied":
             return undefined;
     }
@@ -72,7 +72,7 @@ export function withExcerpt(part, excerpt) {
         case "error-text":
             return { ...part, output: { type: "error-text", value: excerpt } };
         case "content":
-            return { ...part, output: { type: "content", value: [{ type: "text", text: excerpt }, ...output.value.filter((p) => p.type !== "text")] } };
+            return { ...part, output: { type: "content", value: [{ type: "text", text: excerpt }, ...output.value.filter((p) => !("text" in p))] } };
         case "execution-denied":
             return part;
     }

package/dist/loop/turn-credentials.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The live credential of each chat turn of this process.
+ *
+ * A chat turn stores no credential in its workflow. The open of a turn puts the
+ * credential of the request here, and the end of the turn takes it away. A turn
+ * that a recovery runs in a new process finds no entry, thus the function of
+ * the host gives its credential, or nothing. A sub-agent of a turn asks for the
+ * credential of its root turn, which it knows from the context of its body.
+ */
+import type { LanguageModelMiddleware } from "ai";
+import type { AuthContext } from "../auth/types.js";
+export declare const turnCredentials: {
+    put(turnId: string, auth: AuthContext): void;
+    drop(turnId: string): void;
+    /** The credential of a turn: the live one of this process, else the one that the function of the host gives. */
+    of(turnId: string): AuthContext | undefined;
+    /** The function of the host for a turn that this process did not open. */
+    setHostCredential(credentialFor: ((turnId: string) => AuthContext | undefined) | undefined): void;
+};
+/**
+ * The `auth` of a session whose credential can come later: each read goes to `current`, and no credential reads as an
+ * empty object. A copy of the session keeps this object, thus each copy sees the credential that a resume puts.
+ */
+export declare function liveAuth(current: () => AuthContext | undefined): AuthContext;
+/** Run the body of a turn, or of one of its sub-agents, with the id of its root turn in its context. */
+export declare function withRootTurn<T>(turnId: string, body: () => Promise<T>): Promise<T>;
+/** The id of the root chat turn of the body that runs, or `undefined` outside a chat turn. */
+export declare function currentRootTurn(): string | undefined;
+/** The error of a model call of a turn whose host gives no credential. The turn pauses on it with the cause `credential`. */
+export declare class TurnCredentialMissingError extends Error {
+    constructor();
+}
+/**
+ * A middleware that fails each model call while `credentialOf` gives no credential. It runs inside the step of the
+ * call, thus a replay of a recorded call does not read the credential again.
+ */
+export declare function credentialGuard(credentialOf: () => AuthContext | undefined): LanguageModelMiddleware;
+/** Whether an error, or an error on its cause chain, is a missing credential of a turn. A replay of a step gives the name again. */
+export declare function isTurnCredentialMissing(err: unknown): boolean;

package/dist/loop/turn-credentials.js

@@ -0,0 +1,90 @@
+/**
+ * The live credential of each chat turn of this process.
+ *
+ * A chat turn stores no credential in its workflow. The open of a turn puts the
+ * credential of the request here, and the end of the turn takes it away. A turn
+ * that a recovery runs in a new process finds no entry, thus the function of
+ * the host gives its credential, or nothing. A sub-agent of a turn asks for the
+ * credential of its root turn, which it knows from the context of its body.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { z } from "zod";
+import { errorNameOf } from "../lib/thrown.js";
+const credentials = new Map();
+let hostCredential;
+const rootTurn = new AsyncLocalStorage();
+export const turnCredentials = {
+    put(turnId, auth) {
+        credentials.set(turnId, auth);
+    },
+    drop(turnId) {
+        credentials.delete(turnId);
+    },
+    /** The credential of a turn: the live one of this process, else the one that the function of the host gives. */
+    of(turnId) {
+        return credentials.get(turnId) ?? hostCredential?.(turnId);
+    },
+    /** The function of the host for a turn that this process did not open. */
+    setHostCredential(credentialFor) {
+        hostCredential = credentialFor;
+    },
+};
+/**
+ * The `auth` of a session whose credential can come later: each read goes to `current`, and no credential reads as an
+ * empty object. A copy of the session keeps this object, thus each copy sees the credential that a resume puts.
+ */
+export function liveAuth(current) {
+    const credential = () => current() ?? {};
+    return new Proxy({}, {
+        get: (_shell, key) => Reflect.get(credential(), key),
+        has: (_shell, key) => Reflect.has(credential(), key),
+        ownKeys: () => Reflect.ownKeys(credential()),
+        getOwnPropertyDescriptor: (_shell, key) => {
+            const descriptor = Reflect.getOwnPropertyDescriptor(credential(), key);
+            // A proxy can report a key that its shell does not hold only as configurable.
+            return descriptor === undefined ? undefined : { ...descriptor, configurable: true };
+        },
+    });
+}
+/** Run the body of a turn, or of one of its sub-agents, with the id of its root turn in its context. */
+export function withRootTurn(turnId, body) {
+    return rootTurn.run(turnId, body);
+}
+/** The id of the root chat turn of the body that runs, or `undefined` outside a chat turn. */
+export function currentRootTurn() {
+    return rootTurn.getStore();
+}
+/** The error of a model call of a turn whose host gives no credential. The turn pauses on it with the cause `credential`. */
+export class TurnCredentialMissingError extends Error {
+    constructor() {
+        super("The turn has no credential of its user.");
+        this.name = "TurnCredentialMissingError";
+    }
+}
+/**
+ * A middleware that fails each model call while `credentialOf` gives no credential. It runs inside the step of the
+ * call, thus a replay of a recorded call does not read the credential again.
+ */
+export function credentialGuard(credentialOf) {
+    const missing = () => credentialOf() === undefined;
+    return {
+        specificationVersion: "v4",
+        wrapStream: ({ doStream }) => (missing() ? Promise.reject(new TurnCredentialMissingError()) : doStream()),
+        wrapGenerate: ({ doGenerate }) => (missing() ? Promise.reject(new TurnCredentialMissingError()) : doGenerate()),
+    };
+}
+/** A link of the chain whose cause is an error. The error of a missing credential is an `Error`, thus the walk follows errors only. */
+const CauseLinkSchema = z.looseObject({ cause: z.instanceof(Error) });
+/** The depth of a cause chain that the walk reads, as a bound for a chain with a cycle. */
+const CAUSE_CHAIN_DEPTH = 8;
+/** Whether an error, or an error on its cause chain, is a missing credential of a turn. A replay of a step gives the name again. */
+export function isTurnCredentialMissing(err) {
+    let link = err;
+    for (let depth = 0; depth < CAUSE_CHAIN_DEPTH && link !== undefined; depth++) {
+        if (errorNameOf(link) === "TurnCredentialMissingError")
+            return true;
+        const next = CauseLinkSchema.safeParse(link);
+        link = next.success ? next.data.cause : undefined;
+    }
+    return false;
+}