@dynamicagents/core 0.9.0

package/dist/agent/history.js

@@ -0,0 +1,133 @@
+const TURN_TAG_RE = /^<turn\b([^>]*)>([\s\S]*)<\/turn>$/;
+const ATTR_RE = /(\w+)="([^"]*)"/g;
+function parseAttrs(raw) {
+    const out = {};
+    let m;
+    ATTR_RE.lastIndex = 0;
+    while ((m = ATTR_RE.exec(raw)) !== null)
+        out[m[1]] = m[2];
+    return out;
+}
+const ATTR_UNESCAPES = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"'
+};
+/** Reverse the gatekeeper's attribute escaping — single pass so `&amp;` round-trips. */
+function unescAttr(value) {
+    return value.replace(/&(amp|lt|gt|quot);/g, (_, e) => ATTR_UNESCAPES[e]);
+}
+/**
+ * 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 function parseTurn(text) {
+    const m = TURN_TAG_RE.exec(text);
+    if (!m)
+        return null;
+    const attrs = parseAttrs(m[1]);
+    if (!attrs.from || !attrs.id || !attrs.channel || !attrs.at)
+        return null;
+    return {
+        from: unescAttr(attrs.from),
+        id: unescAttr(attrs.id),
+        channel: unescAttr(attrs.channel),
+        at: unescAttr(attrs.at),
+        body: m[2]
+    };
+}
+/**
+ * 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 function taskUserMessageId(taskId) {
+    return `task:${taskId}:user`;
+}
+/**
+ * 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 function roundAckMessageId(taskId, round) {
+    return `task:${taskId}:round:${round}:ack`;
+}
+/** Matches {@link roundAckMessageId}; the trailing suffix is fixed, so the greedy
+ * task-id group cannot swallow it. */
+const ROUND_ACK_ID = /^task:(.+):round:(\d+):ack$/;
+/**
+ * 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 function parseRoundAckMessageId(id) {
+    const match = ROUND_ACK_ID.exec(id);
+    return match ? { taskId: match[1], round: Number(match[2]) } : null;
+}
+/** Id of the terminal reply — the round in which the agent answered the user. */
+export function finalReplyMessageId(taskId) {
+    return `task:${taskId}:reply:final`;
+}
+/** A Sessions-store message with a caller-chosen (deterministic) id. */
+export function deterministicSessionMessage(id, role, text) {
+    return {
+        id,
+        role,
+        createdAt: new Date(),
+        parts: [{ type: "text", text }]
+    };
+}
+/**
+ * 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 function sessionMessage(role, text) {
+    return deterministicSessionMessage(crypto.randomUUID(), role, text);
+}
+/** Concatenate the text parts of a stored session message. */
+export function sessionText(m) {
+    return m.parts
+        .filter((p) => p.type === "text" && typeof p.text === "string")
+        .map((p) => p.text)
+        .join("");
+}
+/** Convert stored history to AI-SDK model messages (user/assistant text only). */
+export function toModelMessages(history) {
+    return history
+        .filter((m) => m.role === "user" || m.role === "assistant")
+        .map((m) => ({
+        role: m.role,
+        content: sessionText(m)
+    }));
+}

package/dist/agent/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `@dynamicagents/core/agent` — the primitives a loop is built from.
+ *
+ * The session, the model pair with its fallback, the budget, and the
+ * control-tool abstraction that turns "the model called something that ends the
+ * round" into a checked value. Everything both predecessor loops needed
+ * identically, and nothing about how a round is shaped.
+ *
+ * This subpath ships **no loop** — that is what makes it importable by one. A
+ * loop module needs these primitives without also pulling in a Durable Object
+ * base class and drizzle, which is why `DynamicAgent` lives in
+ * `@dynamicagents/core/host` and the delegating round loop in
+ * `@dynamicagents/core/round`.
+ *
+ * Core as a whole *does* now ship a loop, opt-in, in `/round`. The rule it
+ * still keeps is narrower and better: **core ships no prompt copy and no
+ * policy** — see `AGENTS.md`, "The line core does not cross". An agent that
+ * wants a different round shape imports none of `/round` and builds it from
+ * exactly what is here.
+ */
+export { newTurnBudget, stepAllowance, type TurnBudget } from "./budget.js";
+export { type AiGatewayMetadata, type ModelOverrides, type ModelPair, type ModelRuntime, type ModelRuntimeFactory } from "./model.js";
+export { CredentialRejectedError, type CredentialRejectedBy } from "./errors.js";
+export { createWorkersAIModelRuntime, workersAIModels, type WorkersAIRuntimeDeps } from "./workers-ai/index.js";
+export { appendOnce, buildAgentSession, notifyingCompaction, type AgentSessionOptions, type SessionHost, type SessionLike } from "./session.js";
+export { deterministicSessionMessage, finalReplyMessageId, parseRoundAckMessageId, parseTurn, roundAckMessageId, sessionMessage, sessionText, taskUserMessageId, toModelMessages, type ParsedTurn } from "./history.js";
+export { buildIntermediateContentHandler, isTransientAiError, nonRecoverableKind, type NonRecoverableKind, type OnContent, type RoundFailureKind } from "./inference.js";
+export { ControlCallError, controlTools, controlToolSet, type ControlTool, type TurnDecision } from "./control.js";
+export { FINAL_REPLY_TOOL_NAME, finalReplyInputSchema, finalReplyTool } from "./final-reply.js";

package/dist/agent/index.js

@@ -0,0 +1,29 @@
+/**
+ * `@dynamicagents/core/agent` — the primitives a loop is built from.
+ *
+ * The session, the model pair with its fallback, the budget, and the
+ * control-tool abstraction that turns "the model called something that ends the
+ * round" into a checked value. Everything both predecessor loops needed
+ * identically, and nothing about how a round is shaped.
+ *
+ * This subpath ships **no loop** — that is what makes it importable by one. A
+ * loop module needs these primitives without also pulling in a Durable Object
+ * base class and drizzle, which is why `DynamicAgent` lives in
+ * `@dynamicagents/core/host` and the delegating round loop in
+ * `@dynamicagents/core/round`.
+ *
+ * Core as a whole *does* now ship a loop, opt-in, in `/round`. The rule it
+ * still keeps is narrower and better: **core ships no prompt copy and no
+ * policy** — see `AGENTS.md`, "The line core does not cross". An agent that
+ * wants a different round shape imports none of `/round` and builds it from
+ * exactly what is here.
+ */
+export { newTurnBudget, stepAllowance } from "./budget.js";
+export {} from "./model.js";
+export { CredentialRejectedError } from "./errors.js";
+export { createWorkersAIModelRuntime, workersAIModels } from "./workers-ai/index.js";
+export { appendOnce, buildAgentSession, notifyingCompaction } from "./session.js";
+export { deterministicSessionMessage, finalReplyMessageId, parseRoundAckMessageId, parseTurn, roundAckMessageId, sessionMessage, sessionText, taskUserMessageId, toModelMessages } from "./history.js";
+export { buildIntermediateContentHandler, isTransientAiError, nonRecoverableKind } from "./inference.js";
+export { ControlCallError, controlTools, controlToolSet } from "./control.js";
+export { FINAL_REPLY_TOOL_NAME, finalReplyInputSchema, finalReplyTool } from "./final-reply.js";

package/dist/agent/inference.d.ts

@@ -0,0 +1,110 @@
+import type { StepResult, ToolSet } from "ai";
+/**
+ * Shared Workers-AI plumbing for the agent's inference operations — the pieces
+ * every model call needs regardless of *which* operation it belongs to.
+ *
+ * The two loops themselves are deliberately separate, not layered on a common
+ * one: the main agent's Session-coupled round lives in
+ * {@link file://../round/turn.ts turn.ts}, and the Session-less subagent loop in
+ * {@link file://../subagent/run.ts run.ts}. They share error classification and
+ * progress streaming; their control flow has nothing in common worth abstracting.
+ */
+/**
+ * Called with each **intermediate** assistant content message — text the model
+ * emits in a step that also makes tool calls (`finishReason:"tool-calls"`), i.e.
+ * before the final reply. Used to stream those messages out live; the final reply
+ * is the operation's return value, not an `onContent` call. `stepIndex` is the
+ * 0-based step ordinal (stable enough across a primary→fallback re-run for the
+ * gatekeeper to dedupe on). Best-effort — the caller must swallow its own failures.
+ */
+export type OnContent = (text: string, stepIndex: number) => void | Promise<void>;
+/**
+ * Whether an error is a transient availability condition rather than a
+ * deterministic bad-output one.
+ *
+ * The distinction decides who handles it: transient throws out of the attempt loop
+ * so the Workflow step retries the whole round, while everything else burns the
+ * model slot and hands over to the fallback. Classifying a capacity blip as
+ * deterministic is the expensive mistake — it spends both slots on an outage and
+ * fails a Task that would have succeeded a second later.
+ *
+ * Structured signals first: the SDK's own `APICallError.isRetryable`, then the
+ * status code, then `RetryError` (raised once the SDK's internal backoff is
+ * exhausted). The message fragments stay as the last resort for the Workers-AI
+ * error codes, which arrive as prose on a plain `Error`.
+ */
+export declare function isTransientAiError(err: unknown): boolean;
+/**
+ * Why a round stopped without a second attempt being worth making.
+ *
+ * A stable string rather than the error itself, because this value crosses two
+ * serialization boundaries — the DO's RPC return and a Workflow step result —
+ * and an `Error` survives neither reliably. The host maps it to operator-facing
+ * copy; core never owns that wording.
+ *
+ * The credential kinds are separate strings rather than one, because they have
+ * different remedies and the host cannot tell them apart afterwards:
+ *
+ * - `credential` — the model provider rejected the token. Rotate that one.
+ * - `gateway-credential` — the AI Gateway *in front of* the provider rejected the
+ *   request, which the provider therefore never saw. Rotate the AI Gateway token
+ *   (`cf-aig-authorization`) instead; the model credential is very likely fine.
+ * - `unknown-credential` — a `401`/`403` matching none of the shapes. Says so,
+ *   rather than picking one and sending an operator to rotate a working secret.
+ *
+ * A fourth, `proxy-credential`, was removed in 0.8.0 along with
+ * {@link file://./errors.ts CredentialRejectedBy}'s `"proxy"` arm. Adding a kind
+ * back is a breaking change for every consumer, because the `Record` they map it
+ * with is total — which is the property that makes a new kind impossible to
+ * ignore, and the reason to remove one rather than leave it unreachable.
+ */
+export type NonRecoverableKind = "credential" | "gateway-credential" | "unknown-credential";
+/**
+ * Why a round ended with no answer — one terminal status, two situations.
+ *
+ * `exhausted` is the ladder run to the end: both slots tried, every repair
+ * spent, nothing usable produced. Every other member is the ladder stopping
+ * early, because nothing further could have cleared the fault — see
+ * {@link nonRecoverableKind}.
+ *
+ * The distinction is a *reason*, not an outcome: both deliver a failed Task with
+ * the same shape. What it decides is the words, and only the host has those (see
+ * `HandleTaskDeps.failureCopy`) — which is why this is a total union rather than
+ * an optional field. A consumer that maps kinds to copy is then a `Record` the
+ * compiler checks, and a new kind cannot be silently ignored by any of them.
+ */
+export type RoundFailureKind = "exhausted" | NonRecoverableKind;
+/**
+ * Whether an error is one that **no** further attempt can clear, and the reason.
+ *
+ * This is the third classification, and the one the other two cannot express.
+ * {@link isTransientAiError} splits failures into "retry the step" (`true`) and
+ * "burn this slot, try the fallback" (`false`) — and for a rejected credential
+ * *both* are wrong. Retrying spends the Workflow's budget on a request that can
+ * never succeed; falling back spends the second slot presenting the *same* dead
+ * token. Returning `false` from the transient check only avoids the first.
+ *
+ * So the attempt ladders check this **before** entering the fallback slot and
+ * stop there, and `runHandleTask` ends the Task with copy the host supplies.
+ * Nothing is retried and nothing is spent proving the obvious twice.
+ *
+ * Keyed on {@link file://./errors.ts CredentialRejectedError}, which is neutral
+ * and structurally matched — so a provider outside core raises one and gets this
+ * handling with nothing here to change.
+ */
+export declare function nonRecoverableKind(err: unknown): NonRecoverableKind | undefined;
+/**
+ * Returns a fresh `onStepEnd` callback for one `generateText` attempt.
+ * Fires `onContent` for each intermediate step (text that accompanies tool
+ * calls); the final step is skipped because its text is the operation's return
+ * value. A fresh handler per attempt resets the 0-based `stepIndex` counter so a
+ * primary→fallback re-run reuses the same indices and the gatekeeper dedupes.
+ *
+ * `terminalToolNames` are the loop's **halting** control tools (e.g. the main
+ * agent's `delegate`): a step that calls one still has `finishReason:"tool-calls"`,
+ * but it is the round's *final* step, and its accompanying text is the round's
+ * acknowledgment — which the caller publishes separately as a milestone. Streaming
+ * it here too would double-post the same text under a second messageId, so those
+ * steps are skipped. Default `[]` (the subagent loop has no control tools).
+ */
+export declare function buildIntermediateContentHandler(onContent: OnContent, terminalToolNames?: string[]): (step: StepResult<ToolSet>) => Promise<void>;

package/dist/agent/inference.js

@@ -0,0 +1,120 @@
+import { APICallError, RetryError } from "ai";
+// Type-only would not work: this is a runtime guard. `errors.ts` is the neutral
+// sibling of `model.ts` and imports nothing, so this reaches no provider.
+import { CredentialRejectedError } from "./errors.js";
+/** Workers-AI error codes and message fragments that mean "try again later". */
+const TRANSIENT_MESSAGE_FRAGMENTS = [
+    "3040",
+    "3046",
+    "capacity temporarily exceeded",
+    "request timeout",
+    "rate limit",
+    "too many requests",
+    "overloaded",
+    "service unavailable"
+];
+/** HTTP statuses worth another attempt: timeout, conflict, throttle, any 5xx. */
+function isRetryableStatus(status) {
+    if (status === undefined)
+        return false;
+    return status === 408 || status === 409 || status === 429 || status >= 500;
+}
+/**
+ * Whether an error is a transient availability condition rather than a
+ * deterministic bad-output one.
+ *
+ * The distinction decides who handles it: transient throws out of the attempt loop
+ * so the Workflow step retries the whole round, while everything else burns the
+ * model slot and hands over to the fallback. Classifying a capacity blip as
+ * deterministic is the expensive mistake — it spends both slots on an outage and
+ * fails a Task that would have succeeded a second later.
+ *
+ * Structured signals first: the SDK's own `APICallError.isRetryable`, then the
+ * status code, then `RetryError` (raised once the SDK's internal backoff is
+ * exhausted). The message fragments stay as the last resort for the Workers-AI
+ * error codes, which arrive as prose on a plain `Error`.
+ */
+export function isTransientAiError(err) {
+    // Checked first because a rejected credential's message can carry "rate
+    // limit"-adjacent prose the fragment scan below would misread as transient.
+    // Note that `false` alone does not protect the fallback slot — see
+    // {@link nonRecoverableKind}, which is what actually stops the ladder.
+    if (nonRecoverableKind(err) !== undefined)
+        return false;
+    if (APICallError.isInstance(err)) {
+        if (err.isRetryable)
+            return true;
+        if (isRetryableStatus(err.statusCode))
+            return true;
+    }
+    if (RetryError.isInstance(err))
+        return true;
+    if (!(err instanceof Error))
+        return false;
+    const message = err.message.toLowerCase();
+    return TRANSIENT_MESSAGE_FRAGMENTS.some((fragment) => message.includes(fragment));
+}
+/**
+ * Whether an error is one that **no** further attempt can clear, and the reason.
+ *
+ * This is the third classification, and the one the other two cannot express.
+ * {@link isTransientAiError} splits failures into "retry the step" (`true`) and
+ * "burn this slot, try the fallback" (`false`) — and for a rejected credential
+ * *both* are wrong. Retrying spends the Workflow's budget on a request that can
+ * never succeed; falling back spends the second slot presenting the *same* dead
+ * token. Returning `false` from the transient check only avoids the first.
+ *
+ * So the attempt ladders check this **before** entering the fallback slot and
+ * stop there, and `runHandleTask` ends the Task with copy the host supplies.
+ * Nothing is retried and nothing is spent proving the obvious twice.
+ *
+ * Keyed on {@link file://./errors.ts CredentialRejectedError}, which is neutral
+ * and structurally matched — so a provider outside core raises one and gets this
+ * handling with nothing here to change.
+ */
+export function nonRecoverableKind(err) {
+    if (!CredentialRejectedError.isInstance(err))
+        return undefined;
+    switch (err.source) {
+        case "provider":
+            return "credential";
+        case "gateway":
+            return "gateway-credential";
+        // Includes an error that crossed a realm boundary carrying no `source` at
+        // all: `isInstance` is structural, so that is reachable, and "unknown" is
+        // the honest reading of it.
+        default:
+            return "unknown-credential";
+    }
+}
+/** A step is "intermediate" when it makes tool calls — more content follows. */
+function isIntermediateStep(step) {
+    return step.finishReason === "tool-calls";
+}
+/**
+ * Returns a fresh `onStepEnd` callback for one `generateText` attempt.
+ * Fires `onContent` for each intermediate step (text that accompanies tool
+ * calls); the final step is skipped because its text is the operation's return
+ * value. A fresh handler per attempt resets the 0-based `stepIndex` counter so a
+ * primary→fallback re-run reuses the same indices and the gatekeeper dedupes.
+ *
+ * `terminalToolNames` are the loop's **halting** control tools (e.g. the main
+ * agent's `delegate`): a step that calls one still has `finishReason:"tool-calls"`,
+ * but it is the round's *final* step, and its accompanying text is the round's
+ * acknowledgment — which the caller publishes separately as a milestone. Streaming
+ * it here too would double-post the same text under a second messageId, so those
+ * steps are skipped. Default `[]` (the subagent loop has no control tools).
+ */
+export function buildIntermediateContentHandler(onContent, terminalToolNames = []) {
+    let stepIndex = 0;
+    return async (step) => {
+        const i = stepIndex++;
+        if (!isIntermediateStep(step))
+            return;
+        if (step.toolCalls.some((c) => terminalToolNames.includes(c.toolName)))
+            return;
+        const content = step.text.trim();
+        if (content)
+            await onContent(content, i);
+    };
+}

package/dist/agent/model.d.ts

@@ -0,0 +1,90 @@
+import type { LanguageModel } from "ai";
+import type { ModelConfig } from "../config.js";
+/**
+ * The provider contract every loop runs against — and nothing that implements
+ * it.
+ *
+ * {@link ModelRuntime} is the whole seam: an agent that returns one runs every
+ * loop in core unchanged, because nothing downstream — the round loop, the
+ * control-tool repair ladder, the Session's compaction, the Workflow — ever sees
+ * more than a `LanguageModel` from `ai`. It never learns which provider produced
+ * it.
+ *
+ * Core ships exactly one implementation —
+ * {@link file://./workers-ai/index.ts `./workers-ai`} — as a sibling directory
+ * under `agent/`. A second provider is a second directory exporting one
+ * {@link ModelRuntimeFactory}, and nothing here has to change to admit it;
+ * a consumer can equally supply one from outside the package, which is the
+ * point of the seam.
+ *
+ * There was a `./anthropic` sibling until 0.8.0 — a hand-written Messages API
+ * adapter behind an optional peer dependency. It was removed with the only
+ * deployment that used it. Nothing about this contract changed when it went,
+ * which is the strongest thing that can be said for the contract.
+ *
+ * Which is why this file has no runtime imports at all. The Workers AI factory
+ * used to live in it, and a contract that ships one implementation inline reads
+ * as *the* runtime with an escape hatch, rather than as one of N.
+ */
+/**
+ * Custom metadata attached to the AI Gateway log for every call a pair makes.
+ * AI Gateway's own `metadata` is otherwise `null`, so a model call can only be
+ * tied back to its task by timestamp; stamping `{ taskId, round }` (a turn) or
+ * `{ taskId, subtaskId }` (a chunk) makes correlation exact. Values are limited
+ * to AI Gateway's accepted scalar set.
+ */
+export type AiGatewayMetadata = Record<string, number | string | boolean>;
+export interface ModelOverrides {
+    /** Test override for the primary slot. */
+    model?: LanguageModel;
+    /** Test override for the fallback slot. */
+    fallbackModel?: LanguageModel;
+    /**
+     * The provider's model id for the primary slot. Defaults to the configured
+     * `chatModelId`.
+     *
+     * The subagent path passes `ValidatedRecipe.primaryModelId`, which is the
+     * host's own configured id — `validateRecipe` copies the pair on, and a recipe
+     * has no field to name a model with. So this parameterizes the pair without
+     * ever widening which models are reachable.
+     */
+    primaryModelId?: string;
+    /** The provider's model id for the fallback slot. See {@link primaryModelId}. */
+    fallbackModelId?: string;
+    /** AI Gateway log metadata for correlation — see {@link AiGatewayMetadata}. */
+    metadata?: AiGatewayMetadata;
+}
+/** The primary/fallback models (lazily memoized) plus their ids for logging. */
+export interface ModelPair {
+    primary: () => LanguageModel;
+    fallback: () => LanguageModel;
+    primaryId: () => string;
+    fallbackId: () => string;
+}
+export interface ModelRuntime {
+    /**
+     * Lazily build + memoize a primary/fallback model pair (overridable in tests,
+     * id-parameterized so a subagent can run the pair its validated recipe
+     * carries). Nothing is checked here — the ids reaching this can only be the
+     * host's own, which `resolveConfig` has already proven non-empty and distinct.
+     */
+    createModelPair(overrides?: ModelOverrides): ModelPair;
+}
+/**
+ * How a provider is supplied to an agent: given the Worker env and the agent's
+ * *resolved* model config, return a runtime.
+ *
+ * Both base-class seams — `DynamicAgent.modelRuntime` and
+ * `RecipeSubagentHost.modelRuntime` — take this shape, which is the point of it.
+ * A provider written as one of these is defined once and referenced from the
+ * agent and its subagent facet, instead of being spelled out twice in two class
+ * bodies that nothing keeps in step. See
+ * {@link file://./workers-ai/runtime.ts workersAIModels} for core's own.
+ *
+ * Config arrives as an argument rather than being read off `this`: the facet
+ * resolves its config inside `buildRuntime` and calls the seam from there, so
+ * there is no `this.config` to read at that point — and a factory that cannot
+ * reach for one cannot disagree with its caller about which AI Gateway the agent
+ * is on.
+ */
+export type ModelRuntimeFactory<TEnv> = (env: TEnv, config: ModelConfig) => ModelRuntime;

package/dist/agent/model.js

@@ -0,0 +1 @@
+export {};

package/dist/agent/session.d.ts

@@ -0,0 +1,100 @@
+import type { LanguageModel, ToolSet } from "ai";
+import { Session } from "agents/experimental/memory/session";
+import type { SessionMessage } from "agents/experimental/memory/session";
+import { createCompactFunction } from "agents/experimental/memory/utils";
+/**
+ * The one continuous {@link Session} an agent Durable Object owns: soul + memory
+ * + compaction, one Session per DO.
+ *
+ * Compaction is the one **lossy** thing this module does, so it is also the one
+ * thing it announces: `onMessagesDisplaced` hands over the raw messages a
+ * summary is about to replace. Core neither stores them nor knows who wants
+ * them — a host wires the seam to whatever does.
+ */
+/**
+ * The SQLite-backed host the Sessions API needs — satisfied by the Agents SDK
+ * `Agent` (`this.sql`).
+ */
+export interface SessionHost {
+    sql<T = Record<string, string | number | boolean | null>>(strings: TemplateStringsArray, ...values: (string | number | boolean | null)[]): T[];
+}
+/** The subset of `Session` the agent loop drives — lets tests inject a fake. */
+export interface SessionLike {
+    appendMessage(message: SessionMessage, parentId?: string | null): Promise<unknown> | unknown;
+    getHistory(): Promise<SessionMessage[]>;
+    /**
+     * Read one message by id, or null. Reads the **raw stored row**, so it is
+     * unaffected by compaction overlays — a message folded into a summary is still
+     * readable here. That is what makes {@link appendOnce}'s read-back a reliable
+     * recovery path for a round whose Workflow step re-ran.
+     */
+    getMessage(id: string): Promise<SessionMessage | null>;
+    refreshSystemPrompt(): Promise<string>;
+    tools(): Promise<ToolSet>;
+    /** Compaction overlays so far — non-empty ⇒ history has been displaced. */
+    getCompactions(): Promise<unknown[]>;
+}
+/**
+ * Append a message with a deterministic id exactly once, and return the text that
+ * is **durably stored** under that id.
+ *
+ * `Session.appendMessage` is already idempotent by id: appending an id that
+ * exists is a no-op. The read-back is what matters for a re-run step — if it
+ * crashed after appending and the retry re-inferred a *different* reply, the
+ * append no-ops and this returns the original, durable text. The Session and the
+ * value the caller goes on to deliver therefore never disagree.
+ *
+ * Falls back to the message's own text if the read-back returns null (it cannot,
+ * having just been appended) rather than failing a round over a missing echo.
+ */
+export declare function appendOnce(session: SessionLike, message: SessionMessage): Promise<string>;
+export interface AgentSessionOptions {
+    /** Read-only identity block injected into the system prompt every turn. */
+    soul: () => string | Promise<string>;
+    /** Description of the writable SQLite `"memory"` scratchpad the model self-edits. */
+    memoryDescription: string;
+    /** Soft cap (tokens) for the `"memory"` block. */
+    memoryMaxTokens: number;
+    /** History token threshold that triggers compaction. */
+    compactAfterTokens: number;
+    /**
+     * Tokens of recent history compaction keeps verbatim. Coupled to
+     * {@link compactAfterTokens} — see `SessionConfig.compactTailTokens` for the
+     * invariant that binds them, which `resolveConfig` enforces.
+     */
+    compactTailTokens: number;
+    /**
+     * Output-token ceiling for the summarizer call. An unbounded summary is not
+     * the risk; a silently truncated one is — it becomes this caller's memory of
+     * everything that scrolled out, with no way to tell it was cut short.
+     */
+    maxOutputTokens: number;
+    /**
+     * Hand over the raw messages each compaction displaces, before a summary
+     * replaces them. Best-effort: a throw here must never abort compaction.
+     *
+     * The seam, not a policy — pass `runtime.onMessagesDisplaced` to reach every
+     * installed plugin declaring the hook, or any function of your own.
+     */
+    onMessagesDisplaced?: (messages: SessionMessage[]) => Promise<void>;
+}
+type CompactFn = ReturnType<typeof createCompactFunction>;
+/**
+ * Wrap a compaction function so the raw messages it folds into a summary are
+ * also handed to `onMessagesDisplaced` before they stop being readable as
+ * history. The displaced range is `fromMessageId..toMessageId` of the result,
+ * sliced from the `history` the compaction saw.
+ *
+ * A listener's failure is swallowed — compaction must still shorten history
+ * when whatever is listening is briefly unavailable. The alternative is
+ * unbounded context because a side concern is down.
+ */
+export declare function notifyingCompaction(base: CompactFn, onMessagesDisplaced?: (messages: SessionMessage[]) => Promise<void>): CompactFn;
+/**
+ * Build the one continuous `Session` an agent Durable Object owns: a read-only
+ * `"soul"` identity block + a writable `"memory"` scratchpad, with history
+ * compaction summarized by the same model. All of a caller's turns (any channel
+ * or thread) accumulate into this single conversation.
+ */
+export declare function buildAgentSession(agent: SessionHost, model: LanguageModel, opts: AgentSessionOptions): Session;
+export {};