@dynamicagents/core 0.9.0

package/dist/agent/control.d.ts

@@ -0,0 +1,109 @@
+import type { Tool, ToolSet } from "ai";
+import type { ReferenceCatalogEntry } from "../subtasks/catalog.js";
+import type { SubtaskTypeRegistry } from "../subtasks/subtask-types.js";
+import type { SubtaskDraft } from "../subtasks/types.js";
+/**
+ * The **control tools** — the calls that end a round — and the one thing they all
+ * need that the SDK cannot do for them: checking their own input.
+ *
+ * A work tool carries an `execute`, so the SDK validates its input against the
+ * tool's schema, runs it, and feeds any failure — bad input, unknown tool, a throw
+ * from inside — back into the loop as a failed tool result. The model sees what
+ * went wrong and gets to try again, for free, for every work tool that exists or
+ * ever will.
+ *
+ * A control tool has no `execute`. The call *is* the round's output, so the loop
+ * halts on it and none of that machinery runs: **its input is never validated at
+ * all**. That is not a subtlety, it is a hole. A `final_reply` whose `text` was
+ * blank passed `nonBlank` untouched and was delivered to the user as an empty
+ * message; a `delegate` whose payload was not a decomposition at all reached
+ * {@link resolveDecomposition} and failed there on a raw `TypeError`.
+ *
+ * So each control tool declares a {@link ControlTool.parse}, and the round runs it
+ * where the SDK would have: between the call and any use of it. `parse` either
+ * produces the {@link TurnDecision} or throws, and a throw is handed straight back
+ * to the model as a failed result for that call — the same repair loop, from the
+ * same shape of feedback, that a work tool gets from the SDK. Adding a control tool
+ * means writing its `parse`; it inherits validation and repair by existing.
+ */
+/** What one round decided. A future `escalate` is another variant here. */
+export type TurnDecision = {
+    kind: "reply";
+    text: string;
+} | {
+    kind: "delegate";
+    reply: string;
+    drafts: SubtaskDraft[];
+};
+/**
+ * Thrown by a {@link ControlTool.parse} for a call the round cannot use.
+ *
+ * Its `message` is written for the **model**, not for a log: it is what comes back
+ * in the failed tool result, and it is the only thing the next attempt knows about
+ * why this one was rejected. Say what was wrong with the call.
+ */
+export declare class ControlCallError extends Error {
+    constructor(message: string);
+}
+/** One control tool: what the model sees, and how the round reads what comes back. */
+export interface ControlTool {
+    /** The tool's name, as declared to the model. */
+    readonly name: string;
+    /** The tool as the model sees it — no `execute`, by definition. */
+    readonly tool: Tool;
+    /**
+     * How this ending competes with another emitted in the same step. The highest
+     * precedence among the tools actually called wins, and the rest are dropped.
+     *
+     * It ranks by **commitment**: `delegate` starts durable work that a reply cannot
+     * undo, so a `delegate` alongside a `final_reply` means the reply is the
+     * acknowledgment *for* that work, not an answer instead of it. A future
+     * `escalate` slots in by saying how committal it is, and nothing else changes.
+     */
+    readonly precedence: number;
+    /**
+     * Pick the one call that counts out of **every** call the attempt made to this
+     * tool, or throw a {@link ControlCallError} if a repeat is itself the error.
+     *
+     * Separate from {@link ControlTool.parse} because what a repeat means is the
+     * tool's own business — a second `delegate` would start a second batch of durable
+     * work and is refused, while a repeated `final_reply` is just the model restating
+     * its answer and the last one stands — and the round needs that answer *before* it
+     * has a decision: the call it shows back to the model in a repair has to be the
+     * same one validation rejected, not whichever happened to come first.
+     *
+     * Never called with an empty array: a tool with no calls did not end the round.
+     */
+    select(inputs: readonly unknown[]): unknown;
+    /**
+     * Turn the selected call into the round's decision, or throw a
+     * {@link ControlCallError} describing what is wrong with it.
+     *
+     * The input is `unknown` on purpose. Nothing has checked it yet — that is this
+     * method's job, and typing it as anything else would be the assumption that
+     * caused the hole this interface exists to close.
+     */
+    parse(input: unknown): TurnDecision;
+}
+/**
+ * The control tools for one round, in the order the model is shown them.
+ *
+ * Built per round rather than defined once, because validating a `delegate` needs
+ * this round's reference catalog — the same values the model was shown as
+ * `[ref N]` markers, which is what makes "reference 4" checkable at all.
+ *
+ * `delegate` is withheld from a `final` round, which has no budget left to spend on
+ * work. `final_reply` is declared on every round including that one: withhold both
+ * and the round has no legal way to end.
+ */
+export declare function controlTools(opts: {
+    catalog: ReferenceCatalogEntry[];
+    /** Whether this round may still hand out work (`false` on a `final` round). */
+    delegable: boolean;
+    /** The installed subtask types — what `delegate` may name. */
+    types: SubtaskTypeRegistry;
+    /** `CoreConfig.maxSubtasks`, the per-round fan-out bound. */
+    maxSubtasks: number;
+}): ControlTool[];
+/** The tools as the SDK takes them, in declaration order. */
+export declare function controlToolSet(tools: ControlTool[]): ToolSet;

package/dist/agent/control.js

@@ -0,0 +1,115 @@
+import { FINAL_REPLY_TOOL_NAME, finalReplyInputSchema, finalReplyTool } from "./final-reply.js";
+import { makeDecompositionProposalSchema, resolveDecomposition } from "../subtasks/decomposition.js";
+import { DELEGATE_TOOL_NAME, makeDelegateTool } from "../subtasks/delegate.js";
+/**
+ * Thrown by a {@link ControlTool.parse} for a call the round cannot use.
+ *
+ * Its `message` is written for the **model**, not for a log: it is what comes back
+ * in the failed tool result, and it is the only thing the next attempt knows about
+ * why this one was rejected. Say what was wrong with the call.
+ */
+export class ControlCallError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ControlCallError";
+    }
+}
+/**
+ * The control tools for one round, in the order the model is shown them.
+ *
+ * Built per round rather than defined once, because validating a `delegate` needs
+ * this round's reference catalog — the same values the model was shown as
+ * `[ref N]` markers, which is what makes "reference 4" checkable at all.
+ *
+ * `delegate` is withheld from a `final` round, which has no budget left to spend on
+ * work. `final_reply` is declared on every round including that one: withhold both
+ * and the round has no legal way to end.
+ */
+export function controlTools(opts) {
+    const tools = [
+        {
+            name: FINAL_REPLY_TOOL_NAME,
+            tool: finalReplyTool,
+            precedence: 0,
+            // The last call of a repeated set: a model that restated its answer meant
+            // the restatement.
+            select: (inputs) => inputs.at(-1),
+            parse(input) {
+                const parsed = finalReplyInputSchema.safeParse(input);
+                if (!parsed.success) {
+                    throw new ControlCallError(`${FINAL_REPLY_TOOL_NAME} input is invalid — ${issues(parsed.error)}`);
+                }
+                return { kind: "reply", text: parsed.data.text.trim() };
+            }
+        }
+    ];
+    // A round with no registered types has nothing to delegate to, so `delegate`
+    // is withheld for the same reason a `final` round withholds it: the tool would
+    // advertise an empty enum the model has no legal way to satisfy.
+    if (opts.delegable && opts.types.keys.length > 0) {
+        const proposalSchema = makeDecompositionProposalSchema(opts.types, opts.maxSubtasks);
+        tools.push({
+            name: DELEGATE_TOOL_NAME,
+            tool: makeDelegateTool(opts.types, opts.maxSubtasks),
+            precedence: 1,
+            select(inputs) {
+                if (inputs.length > 1) {
+                    throw new ControlCallError(`${DELEGATE_TOOL_NAME} was called ${inputs.length} times in one turn. ` +
+                        `Delegate once, with every subtask this round needs in that single call.`);
+                }
+                return inputs[0];
+            },
+            parse(input) {
+                const parsed = proposalSchema.safeParse(input);
+                if (!parsed.success) {
+                    throw new ControlCallError(`${DELEGATE_TOOL_NAME} input is invalid — ${issues(parsed.error)}`);
+                }
+                // Everything past the schema — unknown reference indexes, a type's
+                // required params — throws its own error, already worded for the model.
+                const { reply, drafts } = resolveDecomposition({
+                    ...parsed.data,
+                    subtasks: parsed.data.subtasks.map((s) => ({
+                        ...s,
+                        params: definedParams(s.params)
+                    }))
+                }, opts.catalog, opts.types);
+                return { kind: "delegate", reply, drafts };
+            }
+        });
+    }
+    return tools;
+}
+/**
+ * Drop params the model sent as an explicit `undefined`.
+ *
+ * The delegate schema declares the union of every type's param keys, all optional,
+ * so one tool schema can serve every type (see
+ * `SubtaskTypeRegistry.paramProperties`). A model that names a key and leaves it
+ * empty has sent no param, and forwarding the key with an `undefined` value would
+ * only make a missing required param report itself as a *present* one. Whether
+ * what survives satisfies the type is still
+ * `SubtaskTypeRegistry.validateParams`'s call, downstream.
+ */
+function definedParams(params) {
+    if (!params)
+        return undefined;
+    const entries = Object.entries(params).filter(([, v]) => v !== undefined);
+    return entries.length > 0
+        ? Object.fromEntries(entries)
+        : undefined;
+}
+/**
+ * A zod failure as one line the model can act on: which field, and what was wrong.
+ * The same rendering
+ * {@link file://../subtasks/subtask-types.ts SubtaskTypeRegistry.validateParams}
+ * uses, so every rejection a control call can produce reads the same way.
+ */
+function issues(error) {
+    return error.issues
+        .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+        .join("; ");
+}
+/** The tools as the SDK takes them, in declaration order. */
+export function controlToolSet(tools) {
+    return Object.fromEntries(tools.map((c) => [c.name, c.tool]));
+}

package/dist/agent/errors.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Failures the loops must treat specially, whichever provider raised them.
+ *
+ * A sibling of {@link file://./model.ts model.ts} and neutral for the same
+ * reason: a provider directory may throw these, and nothing here may know that
+ * any particular one exists. `nonRecoverableKind` in
+ * {@link file://./inference.ts inference.ts} keys on this file, so a provider
+ * written outside core — the thing `ModelRuntimeFactory` exists to make cheap —
+ * gets the same handling as core's own, with no change to core.
+ *
+ * ## Why a third classification was needed at all
+ *
+ * Core's attempt ladder splits every failure two ways — transient conditions
+ * throw out so the Workflow step retries the whole round, everything else burns
+ * the model slot and hands over to the fallback (see
+ * {@link file://./inference.ts isTransientAiError}). An expired credential fits
+ * neither: retrying spends the Workflow's budget on a request that can never
+ * succeed, and falling back spends the second slot on the *same* rejected token.
+ * It has to stop the round and say what a human must do.
+ *
+ * Note that being non-transient is not enough on its own — "not transient" is
+ * precisely the signal that means "try the fallback".
+ */
+/**
+ * Who refused the request, when a `401` came back.
+ *
+ * Two authorities sit on the path, each with its own credential: the AI Gateway
+ * (`cf-aig-authorization`) and the model provider itself (`Authorization`). They
+ * fail with the same status code and have completely different remedies, so a
+ * rejection that does not say which one it was sends an operator to rotate the
+ * wrong secret — which is exactly what happened before this existed.
+ *
+ * `"unknown"` is a real answer and the default. Guessing `"provider"` for an
+ * unrecognised body is how the misdiagnosis happens; saying "one of these, here
+ * is how to check each" is worse copy and better information.
+ *
+ * A third arm, `"proxy"`, named an optional intermediary between the two — the
+ * shape where a deployment terminates the AI Gateway request at its own Worker to
+ * attach a credential. It was removed in 0.8.0 with the deployment that had one.
+ * If you build that topology again, the honest classification for its refusals
+ * is `"unknown"` until you widen this union, because the remedy genuinely
+ * differs: an intermediary minting its caller credential per request fails for
+ * reasons upstream of any stored secret, so the fix is to look rather than to
+ * rotate.
+ */
+export type CredentialRejectedBy = "provider" | "gateway" | "unknown";
+/**
+ * A credential on the path to the model was rejected (HTTP 401 / 403).
+ *
+ * Deliberately not an `APICallError`: the AI SDK's classifier treats those as
+ * potentially retryable, and this never is.
+ * {@link file://./inference.ts nonRecoverableKind} maps it to one of the
+ * credential kinds — which one depends on {@link source} — and that is what
+ * stops the round before the fallback slot; `isTransientAiError` additionally
+ * returns `false` so the message text can never be mistaken for a rate limit.
+ *
+ * The round then fails carrying that kind, and the host supplies the
+ * operator-facing copy through `HandleTaskDeps.failureCopy` — core owns the
+ * signal and the delivery, never the wording.
+ */
+export declare class CredentialRejectedError extends Error {
+    readonly name = "CredentialRejectedError";
+    /** The upstream status, when one was available. */
+    readonly status: number | undefined;
+    /** Which authority rejected it. See {@link CredentialRejectedBy}. */
+    readonly source: CredentialRejectedBy;
+    constructor(message: string, options?: {
+        status?: number;
+        source?: CredentialRejectedBy;
+        cause?: unknown;
+    });
+    /**
+     * Structural check rather than `instanceof`.
+     *
+     * A Worker bundle can end up with two copies of this module (core linked as a
+     * tarball while a plugin resolves its own), and `instanceof` fails across
+     * them — the same realm hazard `AGENTS.md` calls out for `agents`. The name is
+     * a readonly literal, so this is as strong in practice and survives bundling.
+     *
+     * It is also what lets a provider outside core raise one: anything named
+     * `CredentialRejectedError` with a `source` is honoured, no shared class
+     * identity required.
+     */
+    static isInstance(err: unknown): err is CredentialRejectedError;
+}

package/dist/agent/errors.js

@@ -0,0 +1,64 @@
+/**
+ * Failures the loops must treat specially, whichever provider raised them.
+ *
+ * A sibling of {@link file://./model.ts model.ts} and neutral for the same
+ * reason: a provider directory may throw these, and nothing here may know that
+ * any particular one exists. `nonRecoverableKind` in
+ * {@link file://./inference.ts inference.ts} keys on this file, so a provider
+ * written outside core — the thing `ModelRuntimeFactory` exists to make cheap —
+ * gets the same handling as core's own, with no change to core.
+ *
+ * ## Why a third classification was needed at all
+ *
+ * Core's attempt ladder splits every failure two ways — transient conditions
+ * throw out so the Workflow step retries the whole round, everything else burns
+ * the model slot and hands over to the fallback (see
+ * {@link file://./inference.ts isTransientAiError}). An expired credential fits
+ * neither: retrying spends the Workflow's budget on a request that can never
+ * succeed, and falling back spends the second slot on the *same* rejected token.
+ * It has to stop the round and say what a human must do.
+ *
+ * Note that being non-transient is not enough on its own — "not transient" is
+ * precisely the signal that means "try the fallback".
+ */
+/**
+ * A credential on the path to the model was rejected (HTTP 401 / 403).
+ *
+ * Deliberately not an `APICallError`: the AI SDK's classifier treats those as
+ * potentially retryable, and this never is.
+ * {@link file://./inference.ts nonRecoverableKind} maps it to one of the
+ * credential kinds — which one depends on {@link source} — and that is what
+ * stops the round before the fallback slot; `isTransientAiError` additionally
+ * returns `false` so the message text can never be mistaken for a rate limit.
+ *
+ * The round then fails carrying that kind, and the host supplies the
+ * operator-facing copy through `HandleTaskDeps.failureCopy` — core owns the
+ * signal and the delivery, never the wording.
+ */
+export class CredentialRejectedError extends Error {
+    name = "CredentialRejectedError";
+    /** The upstream status, when one was available. */
+    status;
+    /** Which authority rejected it. See {@link CredentialRejectedBy}. */
+    source;
+    constructor(message, options) {
+        super(message, { cause: options?.cause });
+        this.status = options?.status;
+        this.source = options?.source ?? "unknown";
+    }
+    /**
+     * Structural check rather than `instanceof`.
+     *
+     * A Worker bundle can end up with two copies of this module (core linked as a
+     * tarball while a plugin resolves its own), and `instanceof` fails across
+     * them — the same realm hazard `AGENTS.md` calls out for `agents`. The name is
+     * a readonly literal, so this is as strong in practice and survives bundling.
+     *
+     * It is also what lets a provider outside core raise one: anything named
+     * `CredentialRejectedError` with a `source` is honoured, no shared class
+     * identity required.
+     */
+    static isInstance(err) {
+        return err instanceof Error && err.name === "CredentialRejectedError";
+    }
+}

package/dist/agent/final-reply.d.ts

@@ -0,0 +1,49 @@
+import { type Tool } from "ai";
+import { z } from "zod";
+/**
+ * The `final_reply` tool — the main agent answering the user itself, and the other
+ * way a round can end.
+ *
+ * A round used to end either by calling `delegate` or by stopping with plain text,
+ * and that asymmetry was the bug: to the code, "the model answered the user" and
+ * "the model narrated an action it never took" were the same outcome — a non-empty
+ * string. A model that wrote "I'll start the game" and emitted no call completed the
+ * Task successfully, having done nothing.
+ *
+ * So prose is no longer an outcome. Both endings are now named tools, the round runs
+ * with `toolChoice: "required"`, and a round that ends any other way has failed its
+ * attempt. The *choice* is still entirely the model's — the point of the design (see
+ * {@link file://../round/turn.ts turn.ts}) was never that the model be steered toward
+ * delegating, only that it not be forced. Picking between two named tools is also a
+ * far easier discrimination for a small model than picking between prose and a tool,
+ * which is what the weaker fallback models kept getting wrong.
+ *
+ * This lives outside `subtasks/` deliberately: replying is not a subtask concept.
+ */
+export declare const FINAL_REPLY_TOOL_NAME = "final_reply";
+/**
+ * The call's input, exported as the zod schema rather than only as the tool's
+ * `inputSchema`, because the round has to run it itself.
+ *
+ * A tool with no `execute` never has its input validated by the SDK — the loop
+ * halts on the call and nothing checks it. That is what let a blank `text` through
+ * to the user despite {@link nonBlank}. The round now parses every control call
+ * with the tool's own schema before using it (see
+ * {@link file://./control.ts control.ts}), and needs the schema in hand to do it.
+ */
+export declare const finalReplyInputSchema: z.ZodObject<{
+    text: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The tool as the model sees it. **Without `execute`**, exactly like
+ * {@link file://../subtasks/delegate.ts delegateTool}: the call *is* the round's
+ * output, so there is nothing for the SDK to run and the loop halts on it.
+ *
+ * Unlike `delegate`, this call is never reconstructed in a later round's history —
+ * a past reply is stored as, and replayed as, ordinary assistant text (history is
+ * text-only by design). The tool exists to constrain *generation*, not to become a
+ * new shape in the transcript.
+ */
+export declare const finalReplyTool: Tool<{
+    text: string;
+}>;

package/dist/agent/final-reply.js

@@ -0,0 +1,68 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { nonBlank } from "../subtasks/decomposition.js";
+/**
+ * The `final_reply` tool — the main agent answering the user itself, and the other
+ * way a round can end.
+ *
+ * A round used to end either by calling `delegate` or by stopping with plain text,
+ * and that asymmetry was the bug: to the code, "the model answered the user" and
+ * "the model narrated an action it never took" were the same outcome — a non-empty
+ * string. A model that wrote "I'll start the game" and emitted no call completed the
+ * Task successfully, having done nothing.
+ *
+ * So prose is no longer an outcome. Both endings are now named tools, the round runs
+ * with `toolChoice: "required"`, and a round that ends any other way has failed its
+ * attempt. The *choice* is still entirely the model's — the point of the design (see
+ * {@link file://../round/turn.ts turn.ts}) was never that the model be steered toward
+ * delegating, only that it not be forced. Picking between two named tools is also a
+ * far easier discrimination for a small model than picking between prose and a tool,
+ * which is what the weaker fallback models kept getting wrong.
+ *
+ * This lives outside `subtasks/` deliberately: replying is not a subtask concept.
+ */
+export const FINAL_REPLY_TOOL_NAME = "final_reply";
+/**
+ * The call's input, exported as the zod schema rather than only as the tool's
+ * `inputSchema`, because the round has to run it itself.
+ *
+ * A tool with no `execute` never has its input validated by the SDK — the loop
+ * halts on the call and nothing checks it. That is what let a blank `text` through
+ * to the user despite {@link nonBlank}. The round now parses every control call
+ * with the tool's own schema before using it (see
+ * {@link file://./control.ts control.ts}), and needs the schema in hand to do it.
+ */
+export const finalReplyInputSchema = z.object({
+    text: nonBlank("text").describe("Your reply, in your own voice. This is shown to the user verbatim, so it must be the complete answer and must not be blank.")
+});
+/**
+ * The tool as the model sees it. **Without `execute`**, exactly like
+ * {@link file://../subtasks/delegate.ts delegateTool}: the call *is* the round's
+ * output, so there is nothing for the SDK to run and the loop halts on it.
+ *
+ * Unlike `delegate`, this call is never reconstructed in a later round's history —
+ * a past reply is stored as, and replayed as, ordinary assistant text (history is
+ * text-only by design). The tool exists to constrain *generation*, not to become a
+ * new shape in the transcript.
+ */
+/*
+ * Annotated, not inferred, and the annotation is a **packaging** constraint
+ * rather than a style choice.
+ *
+ * `tool()` returns `Tool<Input, Output, Context>`, and `Context` lives in
+ * `@ai-sdk/provider-utils` — an internal of `ai`, which resolves it as a nested
+ * copy. Left inferred, `tsc` emits `import("@ai-sdk/provider-utils").Context`
+ * into this module's `.d.ts`, so every consumer typechecking
+ * `@dynamicagents/core/agent` needs a package this one does not declare and cannot
+ * usefully declare: pinning it here installs a *second*, different major
+ * alongside `ai`'s own, and TypeScript then refuses the reference outright as
+ * unportable.
+ *
+ * Naming the type through `ai`'s own re-export keeps the emitted declaration
+ * pointing at a package that is already a required peer. `verify:exports` walks
+ * the declaration graph for exactly this.
+ */
+export const finalReplyTool = tool({
+    description: "Answer the user and end this round. Use this whenever the request is yours to answer — anything about this conversation, your own history, memory, or tools, and anything you can settle with the tools available to you here, including work that has already come back to you.",
+    inputSchema: finalReplyInputSchema
+});

package/dist/agent/history.d.ts

@@ -0,0 +1,97 @@
+import type { ModelMessage } from "ai";
+import type { SessionMessage } from "agents/experimental/memory/session";
+/**
+ * Session-history glue for the agent runtime: parse the gatekeeper-authored `<turn>`
+ * provenance wrapper, and bridge between plain text and the Agents-SDK Sessions
+ * store. No A2A types cross this boundary — the {@link file://../a2a/parts.ts
+ * A2A adapter} has already reduced the inbound message to a plain string.
+ *
+ * The gatekeeper inlines a `<turn from="…" id="…" channel="…" at="…">…</turn>` tag
+ * into the message text in multi-actor channels so the model — and anything
+ * downstream that needs per-message provenance — can attribute "who said what".
+ * This agent only *parses* that wrapper; it never authors one.
+ *
+ * We persist only the user turn and the assistant's final text: intra-turn tool
+ * steps stay inside the single `generateText` call, so stored history is plain
+ * text messages and the conversion to AI-SDK `ModelMessage`s is trivial.
+ */
+/** The fields recovered from a gatekeeper-rendered `<turn>` wrapper. */
+export interface ParsedTurn {
+    from: string;
+    /** Slack user id, as rendered. */
+    id: string;
+    channel: string;
+    /** ISO-8601 instant. */
+    at: string;
+    /** The raw inner body. */
+    body: string;
+}
+/**
+ * Recover the structured provenance from a gatekeeper-authored turn. Returns null
+ * for any text that isn't a `<turn>` wrapper (plain messages, assistant replies),
+ * so callers can treat the provenance as optional.
+ */
+export declare function parseTurn(text: string): ParsedTurn | null;
+/**
+ * Deterministic Session-message ids for the task round loop.
+ *
+ * A round runs inside a durable Workflow step that can re-run after a crash, so
+ * its Session appends must be exactly-once. `Session.appendMessage` already
+ * dedupes on message id (an id that exists is not re-written), so deriving the id
+ * from the task id + round makes the append idempotent for free — no
+ * read-then-write race, no duplicate turns in history on replay. Pair with
+ * {@link file://./session.ts appendOnce}, which reads the durable text back so a
+ * retry that re-inferred still returns the *stored* reply.
+ *
+ * These ids share the Session id-space with random UUIDs (plain turns) and the
+ * SDK's `compaction_`-prefixed summaries; the `task:` prefix cannot collide with
+ * either.
+ */
+/** Id of the inbound user turn for a task (appended once, by round 0). */
+export declare function taskUserMessageId(taskId: string): string;
+/**
+ * Id of the acknowledgment a **delegating** round publishes — the message the
+ * user sees while that round's Subtasks run. Also the anchor a later round finds
+ * to reattach the round's `delegate` call to (see
+ * {@link file://../round/turn.ts renderTurnMessages}), which is why it is
+ * derived from the round rather than stored.
+ */
+export declare function roundAckMessageId(taskId: string, round: number): string;
+/**
+ * Recognize an acknowledgment id — **any** Task's, not just the one being
+ * rendered. A Session outlives the Task that wrote it and is shared by every Task
+ * from the same caller, so its history accumulates acks the current render has no
+ * branches for: earlier Tasks' acks, and (in the window between a round's ack
+ * append and its Subtask rows) this Task's own. Both are the agent's scaffolding
+ * rather than conversation, so both must stay out of the reference catalog; the
+ * `branches`-derived anchor map alone cannot see either.
+ *
+ * Returns the parsed Task id and round so the caller can tell whose ack it is.
+ */
+export declare function parseRoundAckMessageId(id: string): {
+    taskId: string;
+    round: number;
+} | null;
+/** Id of the terminal reply — the round in which the agent answered the user. */
+export declare function finalReplyMessageId(taskId: string): string;
+/** A Sessions-store message with a caller-chosen (deterministic) id. */
+export declare function deterministicSessionMessage(id: string, role: "user" | "assistant", text: string): SessionMessage;
+/**
+ * A Sessions-store message with a fresh random id.
+ *
+ * The counterpart to {@link deterministicSessionMessage}, and choosing between
+ * them is a real decision rather than a style one. A deterministic id makes an
+ * append **idempotent**, which is what a durable-Workflow agent needs: its round
+ * can re-run after a crash, and the id is what stops the retry from duplicating a
+ * turn or rewriting a reply the user already received.
+ *
+ * A conversational agent that answers inline has no such replay to defend
+ * against — every turn is a new message and there is no step to re-enter — so a
+ * random id is correct and a synthesized deterministic one would be a lie about
+ * what is being deduplicated.
+ */
+export declare function sessionMessage(role: "user" | "assistant", text: string): SessionMessage;
+/** Concatenate the text parts of a stored session message. */
+export declare function sessionText(m: SessionMessage): string;
+/** Convert stored history to AI-SDK model messages (user/assistant text only). */
+export declare function toModelMessages(history: SessionMessage[]): ModelMessage[];