@dynamicagents/core 0.9.0

package/dist/agent/session.js

@@ -0,0 +1,82 @@
+import { generateText } from "ai";
+import { Session } from "agents/experimental/memory/session";
+import { createCompactFunction } from "agents/experimental/memory/utils";
+import { sessionText } from "./history.js";
+/**
+ * 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 async function appendOnce(session, message) {
+    await session.appendMessage(message);
+    const stored = await session.getMessage(message.id);
+    return stored ? sessionText(stored) : sessionText(message);
+}
+/**
+ * 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 function notifyingCompaction(base, onMessagesDisplaced) {
+    if (!onMessagesDisplaced)
+        return base;
+    return async (history, options) => {
+        const result = await base(history, options);
+        if (result) {
+            const from = history.findIndex((m) => m.id === result.fromMessageId);
+            const to = history.findIndex((m) => m.id === result.toMessageId);
+            if (from !== -1 && to !== -1) {
+                try {
+                    await onMessagesDisplaced(history.slice(from, to + 1));
+                }
+                catch (err) {
+                    console.error("[session] displacement listener failed", err);
+                }
+            }
+        }
+        return result;
+    };
+}
+/**
+ * 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 function buildAgentSession(agent, model, opts) {
+    const compact = notifyingCompaction(createCompactFunction({
+        // The one boundary worth owning. `protectHead` (3) and `minTailMessages`
+        // (2) keep the SDK defaults: the head is the conversation's opening and is
+        // cheap, and the tail floor is a safety net rather than a budget.
+        tailTokenBudget: opts.compactTailTokens,
+        // Bounded like every other 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.
+        summarize: (prompt) => generateText({
+            model,
+            prompt,
+            maxOutputTokens: opts.maxOutputTokens
+        }).then((r) => r.text)
+    }), opts.onMessagesDisplaced);
+    return Session.create(agent)
+        .withContext("soul", { provider: { get: async () => opts.soul() } })
+        .withContext("memory", {
+        description: opts.memoryDescription,
+        maxTokens: opts.memoryMaxTokens
+    })
+        .onCompaction(compact)
+        .compactAfter(opts.compactAfterTokens);
+}

package/dist/agent/workers-ai/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Workers AI — core's default model provider.
+ *
+ * A provider rather than a capability: it ships no tools, no prompt copy and no
+ * policy; it satisfies {@link file://../model.ts ModelRuntime} and stops.
+ *
+ * Two things about its shape are worth stating, because both look like
+ * omissions:
+ *
+ * **No `LanguageModel` adapter.** `workers-ai-provider` ships one, so this
+ * directory is a factory and nothing else — one file rather than the five a
+ * hand-written adapter costs (a prompt mapping, a cache-control policy, an
+ * error taxonomy). That is what makes it the cheap default.
+ *
+ * **No package subpath.** `workers-ai-provider` is a *required* peer and this is
+ * the default every un-overridden seam reaches through `DynamicAgent` itself, so
+ * it is in every consumer's module graph already and a subpath would buy
+ * nothing. It is exported from `@dynamicagents/core/agent` — one symbol, one import
+ * path. A provider behind an *optional* peer would want its own subpath instead,
+ * so that an agent never calling it does not pay for it; `./anthropic` was one
+ * until 0.8.0.
+ */
+export { createWorkersAIModelRuntime, workersAIModels, type WorkersAIRuntimeDeps } from "./runtime.js";

package/dist/agent/workers-ai/index.js

@@ -0,0 +1,23 @@
+/**
+ * Workers AI — core's default model provider.
+ *
+ * A provider rather than a capability: it ships no tools, no prompt copy and no
+ * policy; it satisfies {@link file://../model.ts ModelRuntime} and stops.
+ *
+ * Two things about its shape are worth stating, because both look like
+ * omissions:
+ *
+ * **No `LanguageModel` adapter.** `workers-ai-provider` ships one, so this
+ * directory is a factory and nothing else — one file rather than the five a
+ * hand-written adapter costs (a prompt mapping, a cache-control policy, an
+ * error taxonomy). That is what makes it the cheap default.
+ *
+ * **No package subpath.** `workers-ai-provider` is a *required* peer and this is
+ * the default every un-overridden seam reaches through `DynamicAgent` itself, so
+ * it is in every consumer's module graph already and a subpath would buy
+ * nothing. It is exported from `@dynamicagents/core/agent` — one symbol, one import
+ * path. A provider behind an *optional* peer would want its own subpath instead,
+ * so that an agent never calling it does not pay for it; `./anthropic` was one
+ * until 0.8.0.
+ */
+export { createWorkersAIModelRuntime, workersAIModels } from "./runtime.js";

package/dist/agent/workers-ai/runtime.d.ts

@@ -0,0 +1,42 @@
+import type { ModelConfig } from "../../config.js";
+import type { AiEnv } from "../../env.js";
+import type { ModelRuntime, ModelRuntimeFactory } from "../model.js";
+/**
+ * The Workers-AI model pair every loop runs on by default, built per agent
+ * instance.
+ *
+ * The predecessor read `env.AI` and five config constants as module-level
+ * imports. Neither survives packaging: `env` does not exist at module scope on
+ * Workers, and a module constant cannot be overridden by a consumer. So this is
+ * a factory over an injected binding and an injected {@link ModelConfig}.
+ */
+export interface WorkersAIRuntimeDeps {
+    /** The `AI` binding. Read lazily — see {@link createWorkersAIModelRuntime}. */
+    ai: Ai;
+    config: ModelConfig;
+}
+/**
+ * Build the Workers AI model runtime for one agent instance.
+ *
+ * The provider is constructed on first *use*, not here. During `wrangler deploy`
+ * Cloudflare evaluates module scope to validate the new version, and bindings
+ * are not populated at that point — constructing eagerly makes `createWorkersAI`
+ * throw "you must provide either a binding or credentials". The same laziness
+ * protects a consumer who builds their runtime early.
+ */
+export declare function createWorkersAIModelRuntime(deps: WorkersAIRuntimeDeps): ModelRuntime;
+/**
+ * Core's default provider — what every {@link ModelRuntimeFactory} seam lands on
+ * when an agent does not override it.
+ *
+ * One definition rather than one per base class. The body used to be written
+ * twice, once in {@link file://../../host/agent.ts DynamicAgent.modelRuntime}
+ * and once in
+ * {@link file://../../round/subagent.ts RecipeSubagentHost.modelRuntime}, which
+ * is the same duplication the seam exists to let a *consumer* avoid.
+ *
+ * Typed on {@link AiEnv} rather than a caller's full `Env`: a factory that
+ * accepts the narrow shape is callable with any env that satisfies it, so both
+ * base classes pass `this.env` straight through.
+ */
+export declare const workersAIModels: ModelRuntimeFactory<AiEnv>;

package/dist/agent/workers-ai/runtime.js

@@ -0,0 +1,63 @@
+import { createWorkersAI } from "workers-ai-provider";
+/**
+ * Build the Workers AI model runtime for one agent instance.
+ *
+ * The provider is constructed on first *use*, not here. During `wrangler deploy`
+ * Cloudflare evaluates module scope to validate the new version, and bindings
+ * are not populated at that point — constructing eagerly makes `createWorkersAI`
+ * throw "you must provide either a binding or credentials". The same laziness
+ * protects a consumer who builds their runtime early.
+ */
+export function createWorkersAIModelRuntime(deps) {
+    const { config } = deps;
+    let provider;
+    const workersai = () => (provider ??= createWorkersAI({
+        binding: deps.ai,
+        gateway: { id: config.aiGatewayId }
+    }));
+    /**
+     * Per-model Workers-AI settings: pin the AI Gateway id (so per-call metadata does
+     * not drop the AI Gateway route), attach correlation metadata when supplied, and
+     * set the reasoning budget.
+     *
+     * Always returns a settings object, even with no metadata: `reasoning_effort`
+     * has to reach the binding on every call, and an `undefined` return drops it.
+     */
+    const chatSettings = (metadata) => ({
+        gateway: { id: config.aiGatewayId, ...(metadata ? { metadata } : {}) },
+        reasoning_effort: config.reasoningEffort
+    });
+    return {
+        createModelPair(overrides = {}) {
+            const primaryId = overrides.primaryModelId ?? config.chatModelId;
+            const fallbackId = overrides.fallbackModelId ?? config.fallbackChatModelId;
+            let primary;
+            let fallback;
+            const settings = chatSettings(overrides.metadata);
+            return {
+                primary: () => (primary ??= overrides.model ?? workersai()(primaryId, settings)),
+                fallback: () => (fallback ??=
+                    overrides.fallbackModel ??
+                        overrides.model ??
+                        workersai()(fallbackId, settings)),
+                primaryId: () => primaryId,
+                fallbackId: () => fallbackId
+            };
+        }
+    };
+}
+/**
+ * Core's default provider — what every {@link ModelRuntimeFactory} seam lands on
+ * when an agent does not override it.
+ *
+ * One definition rather than one per base class. The body used to be written
+ * twice, once in {@link file://../../host/agent.ts DynamicAgent.modelRuntime}
+ * and once in
+ * {@link file://../../round/subagent.ts RecipeSubagentHost.modelRuntime}, which
+ * is the same duplication the seam exists to let a *consumer* avoid.
+ *
+ * Typed on {@link AiEnv} rather than a caller's full `Env`: a factory that
+ * accepts the narrow shape is callable with any env that satisfies it, so both
+ * base classes pass `this.env` straight through.
+ */
+export const workersAIModels = (env, config) => createWorkersAIModelRuntime({ ai: env.AI, config });

package/dist/alarm/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `@dynamicagents/core/alarm` — many deadlines over a Durable Object's one alarm.
+ *
+ * A Durable Object has exactly **one** alarm, and an object that needs to wake
+ * for more than one reason cannot simply call `setAlarm` from each of them: the
+ * last writer silently wins, and whatever the loser was waiting on never
+ * happens. {@link WakeMap} is the fix — one storage row holding every pending
+ * intent, and the only thing in a DO that calls `setAlarm`.
+ *
+ * **Its own subpath, deliberately.** This is useful to a plain `DurableObject`,
+ * not only to a {@link DynamicAgent}, so it must be importable without pulling
+ * the agent machinery into a bundle.
+ *
+ * **Why not `Agent.schedule()`.** The `agents` SDK has the same mechanism, but
+ * sells it only as a method on `Agent`: adopting it means the object becomes an
+ * `Agent`, whose constructor creates `cf_agents_state`, `cf_agents_mcp_servers`
+ * and `cf_agents_queues` in that object's SQLite, builds an `MCPClientManager`,
+ * and prototype-patches every public method for tracing. For an object whose
+ * SQLite is something else already — a container's filesystem, say — that is a
+ * large import for a small one. `agents/schedule` is not an alternative: it is a
+ * prompt and a zod schema for parsing natural-language dates, not alarm
+ * machinery.
+ *
+ * This owns *when* an object wakes. What it owes on waking is the object's own:
+ * `alarm()` reads {@link WakeMap.due} and dispatches.
+ */
+/** One scheduled wake-up. */
+export interface WakeIntent {
+    /** Why we are waking. Namespace it, e.g. `sync-retry:container-shell`. */
+    key: string;
+    /** Epoch ms at which this intent becomes due. */
+    notBefore: number;
+    /** Retry counter, for the intents that carry one. */
+    attempt?: number;
+}
+/** The single storage row holding every intent. Small, and written atomically. */
+export declare const WAKE_KEY = "wake";
+/** How far out {@link WakeMap.repair} re-arms when the handler itself failed. */
+export declare const WAKE_REPAIR_MS = 60000;
+export declare class WakeMap {
+    #private;
+    constructor(storage: DurableObjectStorage);
+    /**
+     * Every pending intent, as a **null-prototype** dictionary rebuilt from own
+     * entries only.
+     *
+     * {@link WakeIntent.key} is a caller-supplied string, so an ordinary object
+     * literal would let three of them misbehave: `get("toString")` would return an
+     * inherited function rather than `undefined`, `clear("constructor")` would
+     * treat a key it never held as present, and `set` on `"__proto__"` would hit
+     * `Object.prototype`'s setter and change the prototype instead of storing the
+     * intent. With no prototype there is nothing to inherit and nothing to poison,
+     * and every string round-trips as an ordinary key.
+     */
+    all(): Promise<Record<string, WakeIntent>>;
+    get(key: string): Promise<WakeIntent | undefined>;
+    set(intent: WakeIntent): Promise<void>;
+    clear(key: string): Promise<void>;
+    /** Every intent whose time has come, earliest first. */
+    due(now: number): Promise<WakeIntent[]>;
+    /**
+     * Point the alarm at the earliest deadline.
+     *
+     * Only ever moved **earlier**, never later: an alarm that fires too soon finds
+     * nothing due, re-arms, and costs one wake-up, whereas an alarm pushed later
+     * by a coincidental write silently delays whatever was already waiting. When
+     * no intents remain the alarm is deleted outright, so an idle object does not
+     * wake on a schedule it has no use for.
+     */
+    rearm(): Promise<void>;
+    /**
+     * Re-arm shortly, for when the handler failed before it could work out what
+     * it owed. Distinct from {@link rearm} because that one trusts the map, and
+     * the map is what we just failed to read.
+     */
+    repair(now: number): Promise<void>;
+}

package/dist/alarm/index.js

@@ -0,0 +1,116 @@
+/**
+ * `@dynamicagents/core/alarm` — many deadlines over a Durable Object's one alarm.
+ *
+ * A Durable Object has exactly **one** alarm, and an object that needs to wake
+ * for more than one reason cannot simply call `setAlarm` from each of them: the
+ * last writer silently wins, and whatever the loser was waiting on never
+ * happens. {@link WakeMap} is the fix — one storage row holding every pending
+ * intent, and the only thing in a DO that calls `setAlarm`.
+ *
+ * **Its own subpath, deliberately.** This is useful to a plain `DurableObject`,
+ * not only to a {@link DynamicAgent}, so it must be importable without pulling
+ * the agent machinery into a bundle.
+ *
+ * **Why not `Agent.schedule()`.** The `agents` SDK has the same mechanism, but
+ * sells it only as a method on `Agent`: adopting it means the object becomes an
+ * `Agent`, whose constructor creates `cf_agents_state`, `cf_agents_mcp_servers`
+ * and `cf_agents_queues` in that object's SQLite, builds an `MCPClientManager`,
+ * and prototype-patches every public method for tracing. For an object whose
+ * SQLite is something else already — a container's filesystem, say — that is a
+ * large import for a small one. `agents/schedule` is not an alternative: it is a
+ * prompt and a zod schema for parsing natural-language dates, not alarm
+ * machinery.
+ *
+ * This owns *when* an object wakes. What it owes on waking is the object's own:
+ * `alarm()` reads {@link WakeMap.due} and dispatches.
+ */
+/** The single storage row holding every intent. Small, and written atomically. */
+export const WAKE_KEY = "wake";
+/** How far out {@link WakeMap.repair} re-arms when the handler itself failed. */
+export const WAKE_REPAIR_MS = 60_000;
+export class WakeMap {
+    #storage;
+    constructor(storage) {
+        this.#storage = storage;
+    }
+    /**
+     * Every pending intent, as a **null-prototype** dictionary rebuilt from own
+     * entries only.
+     *
+     * {@link WakeIntent.key} is a caller-supplied string, so an ordinary object
+     * literal would let three of them misbehave: `get("toString")` would return an
+     * inherited function rather than `undefined`, `clear("constructor")` would
+     * treat a key it never held as present, and `set` on `"__proto__"` would hit
+     * `Object.prototype`'s setter and change the prototype instead of storing the
+     * intent. With no prototype there is nothing to inherit and nothing to poison,
+     * and every string round-trips as an ordinary key.
+     */
+    async all() {
+        const stored = await this.#storage.get(WAKE_KEY);
+        const intents = Object.create(null);
+        // `Object.entries` is own-enumerable-only, so nothing from a prototype can
+        // enter here even if the stored value arrived with one.
+        if (stored) {
+            for (const [key, intent] of Object.entries(stored))
+                intents[key] = intent;
+        }
+        return intents;
+    }
+    async get(key) {
+        return (await this.all())[key];
+    }
+    async set(intent) {
+        const all = await this.all();
+        all[intent.key] = intent;
+        await this.#storage.put(WAKE_KEY, all);
+        await this.rearm();
+    }
+    async clear(key) {
+        const all = await this.all();
+        // `hasOwn`, not `in`: the dictionary has no prototype today, and this stays
+        // correct if that ever changes.
+        if (!Object.hasOwn(all, key))
+            return;
+        delete all[key];
+        await this.#storage.put(WAKE_KEY, all);
+        await this.rearm();
+    }
+    /** Every intent whose time has come, earliest first. */
+    async due(now) {
+        return Object.values(await this.all())
+            .filter((intent) => intent.notBefore <= now)
+            .sort((a, b) => a.notBefore - b.notBefore);
+    }
+    /**
+     * Point the alarm at the earliest deadline.
+     *
+     * Only ever moved **earlier**, never later: an alarm that fires too soon finds
+     * nothing due, re-arms, and costs one wake-up, whereas an alarm pushed later
+     * by a coincidental write silently delays whatever was already waiting. When
+     * no intents remain the alarm is deleted outright, so an idle object does not
+     * wake on a schedule it has no use for.
+     */
+    async rearm() {
+        const deadlines = Object.values(await this.all()).map((i) => i.notBefore);
+        const existing = await this.#storage.getAlarm();
+        if (deadlines.length === 0) {
+            if (existing !== null)
+                await this.#storage.deleteAlarm();
+            return;
+        }
+        const earliest = Math.min(...deadlines);
+        if (existing === null || existing > earliest) {
+            await this.#storage.setAlarm(earliest);
+        }
+    }
+    /**
+     * Re-arm shortly, for when the handler failed before it could work out what
+     * it owed. Distinct from {@link rearm} because that one trusts the map, and
+     * the map is what we just failed to read.
+     */
+    async repair(now) {
+        const existing = await this.#storage.getAlarm();
+        if (existing === null)
+            await this.#storage.setAlarm(now + WAKE_REPAIR_MS);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,202 @@
+/** Model ids and per-call generation settings. */
+export interface ModelConfig {
+    /**
+     * Workers AI model for the tool loop. Must support function calling.
+     *
+     * **Required — core ships no default.** Which model an agent runs on is the
+     * single most consequential thing about it: it sets the cost of every turn,
+     * the tool-calling reliability the whole control-tool design rests on, and the
+     * failure modes the fallback exists to escape. A default here would be core
+     * making that choice on a consumer's behalf, silently, and being wrong for
+     * most of them — the same reason core ships no prompt copy.
+     *
+     * It is also the value most likely to age badly. A model id baked into a
+     * published package survives every deprecation until someone bumps the
+     * package; one written in the agent that uses it is read by whoever owns the
+     * bill.
+     */
+    chatModelId: string;
+    /**
+     * Tried when the primary throws. **Required — core ships no default.**
+     *
+     * Should be a *different vendor and family* — a same-family fallback shares
+     * the failure mode you are falling back from, which makes it a retry wearing
+     * a costume. Core cannot pick this for you precisely because it depends on
+     * what you chose as primary.
+     */
+    fallbackChatModelId: string;
+    /** AI Gateway slug; `"default"` auto-provisions on first request. */
+    aiGatewayId: string;
+    /**
+     * Output-token ceiling for every chat call. Left unset, the binding applies a
+     * per-model default which a reasoning model spends on `reasoning_content`
+     * before emitting the tool call — a truncated round that reads as a clean
+     * answer. Generous on purpose: it bounds a runaway, it does not ration.
+     */
+    maxOutputTokens: number;
+    /** Reasoning budget forwarded on the binding's `inputs` by workers-ai-provider. */
+    reasoningEffort: "low" | "medium" | "high";
+    /**
+     * How many times a single model call is retried **on the same model** before
+     * the round gives up on that slot and moves to the fallback.
+     *
+     * This was hardcoded to `0` for a long time, with a reason that was right for
+     * one case and wrong for the other. The reason: primary→fallback recovery is
+     * ours, so provider-level backoff only adds latency and duplicates it. True
+     * when the two slots are different vendors, which is what
+     * {@link fallbackChatModelId} advises — a 429 on one says nothing about the
+     * other, so falling straight through is the fastest correct move.
+     *
+     * It is false for a rate limit on an agent whose slots share a credential. A
+     * coder running Opus with Sonnet as its step-down burns the fallback proving
+     * the same 429 twice, then throws, then the Workflow retries the whole round
+     * and does it again. Waiting the `retry-after` the provider actually sent is
+     * both cheaper and far more likely to work.
+     *
+     * The AI SDK does the waiting, and it does it properly:
+     * `retryWithExponentialBackoffRespectingRetryHeaders` honours `retry-after-ms`
+     * and `retry-after` and falls back to exponential backoff. It only fires for
+     * an `APICallError` carrying `isRetryable`, so a provider written outside core
+     * has to map its errors into that shape rather than rethrowing them raw, or
+     * none of this fires for it.
+     *
+     * Bounded at 4 by `resolveConfig`. The retries happen *inside*
+     * `step.do("turn:<round>")`, and the SDK caps a single honoured `retry-after`
+     * at 60s, so the worst case is roughly `maxRetries` minutes of waiting before
+     * the round has spent a token of its own — against
+     * {@link file://./platform.ts STEP_TIMEOUT_MS}, which is where that ceiling is
+     * stated and the only place it should be read from.
+     */
+    maxRetries: number;
+}
+/**
+ * An execution budget, in the only two currencies that mean anything: **turns**
+ * (what it costs) and **wall clock** (how long it can run away for).
+ *
+ * Rounds, chunks and steps are *mechanics*, not budgets — a round is the
+ * delegate/answer loop, a chunk is a durable slice sized by the Workers step
+ * timeout. None of them is tunable and none belongs here. Conflating the two is
+ * what once made an overnight runaway look healthy to every cap in the system.
+ *
+ * Reaching either ceiling does the same thing at either level: one final call
+ * with **no tools** — "you have spent your budget, answer now from what you
+ * have". A ceiling yields an answer; it never drops the work.
+ */
+export interface AgentLimits {
+    /**
+     * Tool-loop steps, summed across every round *and* across the
+     * primary→fallback attempt within a round — a fallback attempt is real spend.
+     */
+    maxTurns: number;
+    /**
+     * Measured from the first durable step. Note for whoever implements
+     * escalation: this must be **rebased** after a `step.waitForEvent(...)`
+     * returns, or a human's thinking time is charged to the agent and a task that
+     * asks a question at minute 5 is dead before the answer arrives. Turns need no
+     * such care — waiting costs none.
+     */
+    maxWallMs: number;
+}
+/** Session memory + compaction tuning. */
+export interface SessionConfig {
+    /** Soft cap (tokens) for the self-edited `"memory"` scratchpad block. */
+    memoryMaxTokens: number;
+    /** Live-history token threshold that triggers automatic compaction. */
+    compactAfterTokens: number;
+    /**
+     * Tokens of the most recent history compaction keeps **verbatim**.
+     *
+     * Read this together with {@link compactAfterTokens}; neither means anything
+     * alone. After a compaction the floor is `system + protectHead + summary +
+     * tail`, so the conversation that must accumulate before compaction fires
+     * again is `Δ = compactAfterTokens − floor`, and the SDK sizes each summary at
+     * 20% of the middle it folded, so at equilibrium `S ≈ 0.2Δ`.
+     *
+     * INVARIANT: `compactAfterTokens − compactTailTokens >= 10_000`, asserted in
+     * `session.spec.ts`. Below it the fixed floor eats the gap and compaction
+     * fires on nearly every append, each firing spending a summarizer call on a
+     * near-empty middle. Never lower the threshold without lowering the tail too.
+     */
+    compactTailTokens: number;
+    /** One-line description shown to the model for the writable `"memory"` block. */
+    memoryDescription: string;
+}
+export interface CoreConfig {
+    model: ModelConfig;
+    /** What bounds the MAIN agent across every round of one task. */
+    mainAgentLimits: AgentLimits;
+    /**
+     * The baseline every subagent branch runs under. A recipe may override either
+     * field — to any positive integer, larger included — and inherits the baseline
+     * for whatever it does not validly declare. A default, not a ceiling.
+     */
+    subagentLimits: AgentLimits;
+    /**
+     * How many of the most recent assistant turns keep their tool **results** in a
+     * subagent's rolling window. Older results are stubbed; the tool *calls* and
+     * the model's own text always survive the full `historyWindow`, because that
+     * is where a recipe's model keeps whatever it wrote down for itself.
+     *
+     * A mechanic of the window, not a property of a domain — which is why it is
+     * deliberately not a recipe field: recipe fields are fingerprinted, and
+     * changing a fingerprint strands every in-flight run behind a mismatch that
+     * costs it its whole history.
+     */
+    toolOutputWindow: number;
+    /**
+     * Upper bound on subtasks per **round** — a core invariant: a delegating round
+     * emits `1..maxSubtasks` subtasks, which is also what bounds its fan-out (they
+     * all run concurrently, with no other concurrency cap).
+     *
+     * Not a budget but a shape: it is what the delegation schema offers the model,
+     * and the data layer re-checks it as the durable guard.
+     */
+    maxSubtasks: number;
+    session: SessionConfig;
+}
+/** The two ids an agent must choose for itself. Core has no opinion. */
+export type RequiredModelIds = Pick<ModelConfig, "chatModelId" | "fallbackChatModelId">;
+/**
+ * The baseline, which is everything core *does* still have an opinion about.
+ *
+ * Note what is missing: the model pair. This type is `CoreConfig` minus those
+ * two ids precisely so that no value of it can supply them — a default nobody
+ * declared is how an agent ends up billing a model its author never chose.
+ */
+export type CoreConfigBaseline = Omit<CoreConfig, "model"> & {
+    model: Omit<ModelConfig, keyof RequiredModelIds>;
+};
+/**
+ * A working baseline. Every value is overridable; none is a ceiling. These are
+ * the values both predecessor agents converged on in production, so they are a
+ * reasonable place to start rather than an opinion about your domain.
+ *
+ * **It carries no model ids.** See {@link ModelConfig.chatModelId}.
+ */
+export declare const DEFAULT_CORE_CONFIG: CoreConfigBaseline;
+/**
+ * One level of optionality per nested group — enough for a config this shallow.
+ *
+ * `model` is the exception, and deliberately not optional: an agent must name
+ * its own primary and fallback. That is a compile error rather than a runtime
+ * one, so the omission is found while writing the agent rather than on the first
+ * request it serves.
+ */
+export type CoreConfigOverrides = {
+    [K in Exclude<keyof CoreConfig, "model">]?: CoreConfig[K] extends object ? Partial<CoreConfig[K]> : CoreConfig[K];
+} & {
+    /** Required: the two model ids, plus any generation setting you want changed. */
+    model: RequiredModelIds & Partial<Omit<ModelConfig, keyof RequiredModelIds>>;
+};
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Merge overrides onto {@link DEFAULT_CORE_CONFIG} and check the invariants that
+ * are cheap to get wrong and expensive to notice.
+ *
+ * Called once, at DO start, and the result threaded explicitly from there. Do
+ * not call it per-request: the point of resolving is that every module downstream
+ * reads the same object.
+ */
+export declare function resolveConfig(overrides: CoreConfigOverrides): CoreConfig;