@dynamicagents/core 0.9.0

package/dist/subagent/run.js

@@ -0,0 +1,540 @@
+import { generateText, isStepCount } from "ai";
+import { CHUNK_SOFT_MS } from "../platform.js";
+import { stepAllowance } from "../agent/budget.js";
+import { isTransientAiError, nonRecoverableKind } from "../agent/inference.js";
+import { validateRecipe } from "../contract/validation.js";
+import { renderSubagentPrompt } from "./prompt.js";
+/**
+ * Trim the conversation to the most recent `window` turns (plus the seed message),
+ * cutting at an assistant boundary so no tool-result message is left orphaned.
+ * Older turns fall out of context — the recipe's soul directs the model to persist
+ * anything durable to its workspace, which the window never touches.
+ */
+export function windowMessages(messages, window) {
+    if (messages.length <= 1)
+        return messages;
+    const assistantIdx = [];
+    for (let i = 1; i < messages.length; i++) {
+        if (messages[i].role === "assistant")
+            assistantIdx.push(i);
+    }
+    if (assistantIdx.length <= window)
+        return messages;
+    const start = assistantIdx[assistantIdx.length - window];
+    return [messages[0], ...messages.slice(start)];
+}
+/** What replaces a tool result that has aged out of the detail window. */
+export const ELIDED_TOOL_OUTPUT = "[output from an earlier turn, trimmed to save context]";
+/**
+ * Below this many serialized characters a result is not worth stubbing — the
+ * stub would be most of what it replaced.
+ */
+const MIN_ELIDABLE_OUTPUT = 200;
+/** Serialized size of a tool result's output, for the "worth stubbing" test. */
+function outputSize(output) {
+    if (output.type === "text" || output.type === "error-text")
+        return output.value.length;
+    if (output.type === "execution-denied")
+        return (output.reason ?? "").length;
+    try {
+        return JSON.stringify(output.value).length;
+    }
+    catch {
+        return Number.POSITIVE_INFINITY;
+    }
+}
+/**
+ * Shrink the window without shortening it: stub out the *payloads* of tool
+ * results the model has moved past, leaving every message, every tool call — and
+ * therefore every note the model wrote itself — exactly where it was.
+ *
+ * This is the other half of {@link windowMessages}, and it exists because the two
+ * things a rolling window holds have opposite value curves. A recipe's own
+ * reasoning and its tool-call *inputs* stay useful for as long as the run does; a
+ * tool *result* is a snapshot of a world that has since moved, and it is also
+ * where nearly all the tokens are. Dropping whole turns to bound context throws
+ * both away together, which is why a short window makes a model re-derive what it
+ * already knew.
+ *
+ * A result's output survives if any of:
+ *
+ * 1. it is within the last `keepRecent` assistant messages — the same unit
+ *    `windowMessages` counts in, so the two knobs are commensurable;
+ * 2. **it is the newest result for its tool**, at any age. Tools may hold state
+ *    about what they have already shown this chunk and answer a repeat with
+ *    "unchanged since you last looked" — a real optimization that becomes a lie
+ *    the moment the render it points at is gone. Keeping the newest per tool is
+ *    what makes "your latest view" a thing the model can still see, and it is why
+ *    `keepRecent` can be small;
+ * 3. it reports a failure or a denial — short, diagnostic, and losing *why* a
+ *    call failed costs a retry to rediscover for no saving;
+ * 4. it is already small enough that stubbing it saves nothing.
+ *
+ * Idempotent: a stubbed part is small, so a later pass leaves it alone.
+ *
+ * `keepRecent` is normalized rather than trusted — see the note on `keep` below.
+ * Zero is a legal, meaningful value: no turn is recent, so rule 1 protects
+ * nothing and rules 2-4 carry the whole of what survives.
+ */
+export function elideToolOutputs(messages, keepRecent) {
+    /**
+     * Rule 1's width, normalized to a non-negative integer.
+     *
+     * Not defensive habit: `keepRecent` is a config value reaching a function whose
+     * arithmetic indexes an array with it, and every out-of-contract value used to
+     * land on the *same* wrong branch. `assistantIdx[len - 0]` is `undefined`, as is
+     * any negative or `NaN` index, and `i >= undefined` is false for every `i` — so
+     * `cutoff` silently meant "no turn is recent" instead of throwing or clamping.
+     * That happens to be right for 0 and wrong for everything else, which is the
+     * worst way for a guard to fail: correct until the day someone passes -1.
+     *
+     * So 0 now says it explicitly (see `cutoff`), and nothing else can reach it by
+     * accident. `NaN` is the one value with no reading at all, and it takes the
+     * conservative floor — still bounded by rules 2-4, which keep the newest result
+     * per tool, every failure, and everything already small. Both infinities keep
+     * the reading they plainly have: an unboundedly wide window keeps everything, a
+     * negative one keeps nothing.
+     */
+    const keep = Number.isNaN(keepRecent)
+        ? 0
+        : Math.max(0, Math.trunc(keepRecent));
+    // Where the detail window starts, counted in assistant messages so it lines up
+    // with `historyWindow`. Everything before it is a candidate for elision, so
+    // `messages.length` is the honest spelling of an empty window and 0 the honest
+    // spelling of a window covering everything (fewer assistant messages than the
+    // window ⇒ keep all).
+    const assistantIdx = [];
+    for (const [i, m] of messages.entries()) {
+        if (m.role === "assistant")
+            assistantIdx.push(i);
+    }
+    const cutoff = keep === 0
+        ? messages.length
+        : assistantIdx.length <= keep
+            ? 0
+            : assistantIdx[assistantIdx.length - keep];
+    if (cutoff === 0)
+        return messages;
+    // The newest result per tool, so rule 2 can be a lookup rather than a scan.
+    const newestPerTool = new Map();
+    for (const [i, message] of messages.entries()) {
+        if (message.role !== "tool")
+            continue;
+        for (const part of message.content) {
+            if (part.type === "tool-result")
+                newestPerTool.set(part.toolName, i);
+        }
+    }
+    let changed = false;
+    const out = messages.map((message, i) => {
+        if (message.role !== "tool" || i >= cutoff)
+            return message;
+        let messageChanged = false;
+        const content = message.content.map((part) => {
+            if (part.type !== "tool-result")
+                return part;
+            if (newestPerTool.get(part.toolName) === i)
+                return part;
+            if (part.output.type === "error-text" ||
+                part.output.type === "error-json" ||
+                part.output.type === "execution-denied")
+                return part;
+            if (outputSize(part.output) < MIN_ELIDABLE_OUTPUT)
+                return part;
+            messageChanged = true;
+            return {
+                ...part,
+                output: { type: "text", value: ELIDED_TOOL_OUTPUT }
+            };
+        });
+        if (!messageChanged)
+            return message;
+        changed = true;
+        return { ...message, content };
+    });
+    return changed ? out : messages;
+}
+/** Human-readable elapsed time for the metrics footer. */
+function formatDuration(ms) {
+    const total = Math.round(ms / 1000);
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = total % 60;
+    if (h > 0)
+        return `${h}h ${m}m ${s}s`;
+    if (m > 0)
+        return `${m}m ${s}s`;
+    return `${s}s`;
+}
+function metricsFooter(state, now) {
+    return (`\n\n---\nRan ${state.turns} model turn(s) across ${state.llmCalls} model ` +
+        `call(s) in ${formatDuration(now - state.startedAtMs)}.`);
+}
+/**
+ * Has this execution spent its whole-run budget? Turns and wall-clock are one
+ * predicate because they mean the same thing to the runner — the run is over and
+ * owes a report — and because checking only turns is what let a slow-turning
+ * recipe run for hours while its turn counter looked healthy.
+ *
+ * `startedAtMs` rides in the checkpoint, so the deadline survives chunk
+ * boundaries, step retries and isolate restarts without any storage of its own.
+ */
+function budgetSpent(state, deps) {
+    return (state.turns >= deps.limits.maxTurns ||
+        deps.now() - state.startedAtMs >= deps.limits.maxWallMs);
+}
+function completed(state, deps, text, modelId) {
+    const finalText = deps.reportMetrics
+        ? text + metricsFooter(state, deps.now())
+        : text;
+    return {
+        outcome: {
+            done: true,
+            result: {
+                status: "completed",
+                resultParts: [{ kind: "text", text: finalText }],
+                modelId
+            },
+            progress: deps.progress
+        },
+        state
+    };
+}
+/**
+ * Fail a chunk on an error no second attempt can clear.
+ *
+ * Terminal for this subtask, and deliberately *not* a throw: a throw is retried
+ * by the Workflow step, which is exactly the spend this classification exists to
+ * avoid. The parent round then hits the same condition on its own inference and
+ * fails carrying the kind, which is where an operator-facing message gets
+ * attached — a subagent has no channel of its own to say "a human must fix
+ * this", only this row's `error` string.
+ */
+function nonRecoverableOutcome(state, deps, modelId, kind, diagnostic) {
+    console.error("[recipe-runner] non-recoverable model failure", {
+        model: modelId,
+        kind,
+        diagnostic
+    });
+    return {
+        outcome: {
+            done: true,
+            result: {
+                status: "failed",
+                error: `${kind}: ${diagnostic}`,
+                modelId
+            },
+            progress: deps.progress
+        },
+        state
+    };
+}
+/**
+ * Run one durable chunk. Returns a terminal result (natural completion, budget
+ * exhaustion, or exhausted models) or a `done: false` yield with the progress
+ * emitted this chunk. Throws only on a transient platform fault, so the Workflow
+ * step retries and resumes from the last checkpoint.
+ */
+export async function runResumableChunk(prev, deps) {
+    const state = prev ?? {
+        messages: [{ role: "user", content: deps.seedPrompt }],
+        turns: 0,
+        llmCalls: 0,
+        startedAtMs: deps.now()
+    };
+    /**
+     * Hand the chunk back with no terminal result. An abort takes this exit too —
+     * that is the whole point: nothing terminal is produced, so the facet caches
+     * nothing and no bogus failure can replay on a later retry.
+     */
+    const yielded = () => ({
+        outcome: { done: false, progress: deps.progress },
+        state
+    });
+    // Already canceled before this chunk started: don't call a model at all.
+    if (deps.abortSignal?.aborted)
+        return yielded();
+    // The durable enforcement point for the whole-run budget: it reads persisted
+    // state before any model call, so every chunk re-checks it however the previous
+    // one ended. It also covers the retry that resumes from a checkpoint taken on
+    // the final allowed turn before the chunk returned — e.g. summarizeBudget's own
+    // call threw a transient fault and the Workflow step retried. The budget is
+    // already spent, so summarize now instead of running another unbudgeted,
+    // side-effecting turn (which `stopWhen`'s `Math.max(1, …)` would otherwise force).
+    if (budgetSpent(state, deps)) {
+        return summarizeBudget(state, deps);
+    }
+    const chunkStartMs = deps.now();
+    const onStepEnd = async (step) => {
+        state.turns += 1;
+        // Window first (drops whole turns at an assistant boundary), then elide what
+        // survived. Both before the checkpoint, so the durable `run_state` row
+        // shrinks with the context rather than tracking the untrimmed run.
+        state.messages = elideToolOutputs(windowMessages([...state.messages, ...step.response.messages], deps.historyWindow), deps.toolOutputWindow);
+        await deps.checkpoint(state);
+    };
+    /**
+     * Four boundaries, and only the first two are budgets. A chunk ends on
+     * whichever comes first; the run ends only on a budget.
+     *
+     * Rebuilt per attempt rather than once per chunk, and that is the whole point:
+     * `isStepCount` counts within one `generateText` call, so a `stopWhen` shared
+     * with the fallback would hand it the turn allowance the primary already spent.
+     * `onStepEnd` has moved `state.turns` by then, so recomputing here charges the
+     * fallback for what the run has actually used.
+     */
+    const boundaries = () => [
+        // The turn budget — all of what is left of it. There is deliberately no
+        // per-chunk turn allowance: a turn count cannot bound a step's *duration*,
+        // which is the only thing the step timeout cares about, so the wall-clock
+        // predicate below owns that job alone.
+        isStepCount(stepAllowance(deps.limits.maxTurns, state.turns)),
+        // The run-wide deadline. Without it the entry guard would only observe the
+        // deadline at the next chunk boundary, up to `chunkSoftMs` past it.
+        () => deps.now() - state.startedAtMs >= deps.limits.maxWallMs,
+        // Not a budget: the configured step timeout, which needs this chunk to
+        // checkpoint and hand back a fresh step before it trips. Soft, and only
+        // checked here between turns — the turn already in flight when it trips still
+        // runs to completion, which is why `STEP_TIMEOUT_MS - CHUNK_SOFT_MS` is sized
+        // to cover a whole turn rather than a nominal moment. See `platform.ts`.
+        () => deps.now() - chunkStartMs >= deps.chunkSoftMs,
+        // Not a budget either: publish progress to the user promptly.
+        () => deps.progress.length > 0
+    ];
+    const attempt = async (model, modelId) => {
+        state.llmCalls += 1;
+        let result;
+        try {
+            result = await generateText({
+                model: model(),
+                instructions: deps.system,
+                messages: state.messages,
+                tools: deps.tools,
+                stopWhen: boundaries(),
+                maxOutputTokens: deps.maxOutputTokens,
+                // Not a duplicate of the fallback: the fallback answers "this model
+                // cannot do it", and a 429 says "not yet". See `ModelConfig.maxRetries`.
+                maxRetries: deps.maxRetries,
+                abortSignal: deps.abortSignal,
+                onStepEnd
+            });
+        }
+        catch (error) {
+            // Check the signal before the error: an abort surfaces as a rejection, and
+            // reading it as bad model output would spend the fallback and cache a
+            // failure for work that was cancelled on purpose.
+            if (deps.abortSignal?.aborted)
+                return { kind: "aborted" };
+            return { kind: "failed", diagnostic: String(error), error, modelId };
+        }
+        if (deps.abortSignal?.aborted)
+            return { kind: "aborted" };
+        if (result.finishReason === "length") {
+            // Its own warning, not just a diagnostic string: hitting the output ceiling
+            // is a tuning signal about `config.model.maxOutputTokens`, distinct from the
+            // model producing bad output, and the two are indistinguishable once folded
+            // into the "recipe exhausted" message.
+            console.warn("[recipe-runner] model output truncated", {
+                model: modelId,
+                maxOutputTokens: deps.maxOutputTokens
+            });
+            return {
+                kind: "failed",
+                diagnostic: "truncated (finish_reason=length)",
+                modelId
+            };
+        }
+        if (result.finishReason === "stop") {
+            const text = result.text.trim();
+            return text === ""
+                ? { kind: "failed", diagnostic: "empty final reply", modelId }
+                : { kind: "completed", text, modelId };
+        }
+        // Not a final answer (e.g. finish_reason=tool-calls): a stop condition fired
+        // mid-loop — the chunk yielded a durable boundary with more work to do.
+        return { kind: "yield" };
+    };
+    let a = await attempt(deps.models.primary, deps.models.primaryId());
+    if (a.kind === "aborted")
+        return yielded();
+    if (a.kind === "failed") {
+        // Checked before the fallback, not after: the second slot would present the
+        // same rejected credential. Returned rather than thrown — a throw here is
+        // retried by the Workflow step, which is the other cost this avoids. The
+        // chunk fails, and the parent's next round classifies it properly.
+        const blocked = nonRecoverableKind(a.error);
+        if (blocked) {
+            return nonRecoverableOutcome(state, deps, a.modelId, blocked, a.diagnostic);
+        }
+        console.warn("[recipe-runner] primary attempt failed, trying fallback", {
+            model: a.modelId,
+            diagnostic: a.diagnostic
+        });
+        const primaryFailure = a;
+        a = await attempt(deps.models.fallback, deps.models.fallbackId());
+        if (a.kind === "aborted")
+            return yielded();
+        if (a.kind === "failed") {
+            // Both attempts failed. A transient fault anywhere means a retry could
+            // succeed — throw it for the Workflow step (most recent first).
+            for (const failed of [a, primaryFailure]) {
+                if (failed.error !== undefined && isTransientAiError(failed.error)) {
+                    throw failed.error;
+                }
+            }
+            return {
+                outcome: {
+                    done: true,
+                    result: {
+                        status: "failed",
+                        error: `recipe exhausted: primary (${primaryFailure.modelId}): ` +
+                            `${primaryFailure.diagnostic}; fallback (${a.modelId}): ${a.diagnostic}`,
+                        modelId: a.modelId
+                    },
+                    progress: deps.progress
+                },
+                state
+            };
+        }
+    }
+    if (a.kind === "completed")
+        return completed(state, deps, a.text, a.modelId);
+    // The chunk yielded. If the run budget is spent, force a final summary so the
+    // run still returns useful output; otherwise ask the Workflow for another chunk.
+    if (budgetSpent(state, deps)) {
+        return summarizeBudget(state, deps);
+    }
+    return yielded();
+}
+/**
+ * The run budget — turns or wall-clock — is exhausted mid-loop: run one final
+ * no-tools call asking the model to produce its answer/report from the work so
+ * far. Primary → fallback, same transient/deterministic split. This is what makes
+ * "uncapped but bounded" safe — the ceiling yields a report instead of a dropped
+ * run.
+ *
+ * The message deliberately does not name *which* budget ran out. The model can
+ * do nothing differently either way, and the one instruction that matters —
+ * report now, take no more actions — is the same.
+ */
+async function summarizeBudget(state, deps) {
+    const messages = [
+        ...state.messages,
+        {
+            role: "user",
+            content: "You have reached your execution budget and can take no more actions. " +
+                "Write your final answer or report now, based on the work so far."
+        }
+    ];
+    const summarize = async (model, modelId) => {
+        state.llmCalls += 1;
+        let result;
+        try {
+            result = await generateText({
+                model: model(),
+                instructions: deps.system,
+                messages,
+                stopWhen: isStepCount(1),
+                maxOutputTokens: deps.maxOutputTokens,
+                // Retries on this model, honouring `retry-after`, before the fallback.
+                // See `ModelConfig.maxRetries`.
+                maxRetries: deps.maxRetries,
+                abortSignal: deps.abortSignal
+            });
+        }
+        catch (error) {
+            if (deps.abortSignal?.aborted)
+                return { kind: "aborted" };
+            return { kind: "failed", diagnostic: String(error), error, modelId };
+        }
+        if (deps.abortSignal?.aborted)
+            return { kind: "aborted" };
+        const text = result.text.trim();
+        return text === ""
+            ? { kind: "failed", diagnostic: "empty summary", modelId }
+            : { kind: "completed", text, modelId };
+    };
+    // An abort yields with no terminal result, exactly as in the main loop: the
+    // budget summary is output, and cancelled work publishes none.
+    const yielded = () => ({
+        outcome: { done: false, progress: deps.progress },
+        state
+    });
+    let a = await summarize(deps.models.primary, deps.models.primaryId());
+    if (a.kind === "aborted")
+        return yielded();
+    if (a.kind === "failed") {
+        // Same rule as the work loop: no fallback on a credential the API already
+        // rejected. A summary is the cheapest call in the run, but it is not free.
+        const blocked = nonRecoverableKind(a.error);
+        if (blocked) {
+            return nonRecoverableOutcome(state, deps, a.modelId, blocked, a.diagnostic);
+        }
+        const primaryFailure = a;
+        a = await summarize(deps.models.fallback, deps.models.fallbackId());
+        if (a.kind === "aborted")
+            return yielded();
+        if (a.kind === "failed") {
+            for (const failed of [a, primaryFailure]) {
+                if (failed.error !== undefined && isTransientAiError(failed.error)) {
+                    throw failed.error;
+                }
+            }
+            // Even the summary failed: return a plain budget-exhausted notice.
+            const text = "Reached the execution budget without producing a final report.";
+            return completed(state, deps, text, a.modelId);
+        }
+    }
+    return a.kind === "completed"
+        ? completed(state, deps, a.text, a.modelId)
+        : completed(state, deps, "Reached the execution budget.", deps.models.fallbackId());
+}
+/**
+ * Run one recipe execution to a terminal result, driving {@link runResumableChunk}
+ * chunk by chunk in memory. A run that fits its budget finishes in one chunk;
+ * otherwise it loops until the budget yields a summary. Used by tests and any
+ * caller wanting the whole outcome; the facet drives chunks durably instead, for
+ * crash-safety across the Workflow.
+ *
+ * Throws only on a transient platform fault (as {@link runResumableChunk} does).
+ */
+export async function runRecipeExecution(request, deps) {
+    if (request.prompt.trim() === "") {
+        return { status: "failed", error: "empty subtask prompt", modelId: null };
+    }
+    const recipe = validateRecipe(request.recipe, deps.policy);
+    const { system, prompt } = renderSubagentPrompt({ ...request, recipe });
+    const now = deps.now ?? Date.now;
+    let state = null;
+    // A chunk always advances ≥1 turn unless it completes, so `maxTurns` chunks is
+    // the ceiling and this can never spin. Turn-derived on purpose: `maxWallMs` and
+    // `chunkSoftMs` only ever end a run *sooner*, so neither can loosen the bound.
+    const maxChunks = recipe.limits.maxTurns + 2;
+    for (let chunk = 0; chunk < maxChunks; chunk++) {
+        const chunkDeps = {
+            system,
+            seedPrompt: prompt,
+            models: deps.models,
+            tools: deps.tools,
+            limits: recipe.limits,
+            chunkSoftMs: CHUNK_SOFT_MS,
+            historyWindow: recipe.historyWindow,
+            toolOutputWindow: deps.toolOutputWindow,
+            reportMetrics: recipe.reportMetrics,
+            maxOutputTokens: deps.maxOutputTokens,
+            maxRetries: deps.maxRetries,
+            now,
+            progress: [],
+            checkpoint: () => { }
+        };
+        const { outcome, state: next } = await runResumableChunk(state, chunkDeps);
+        if (outcome.done)
+            return outcome.result;
+        state = next;
+    }
+    return {
+        status: "failed",
+        error: `recipe did not terminate within ${maxChunks} chunks`,
+        modelId: null
+    };
+}

package/dist/subagent/workspace.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The narrow file-store surface the resumable runner and its tool families use.
+ *
+ * Core declares the *interface* and the caps; it does not declare a backend.
+ * The predecessor backed this with `@cloudflare/shell`, which is experimental
+ * ("expect breaking changes") — so an agent that never delegates file work should
+ * not carry it. `@dynamicagents/plugins/workspace` supplies the shell-backed
+ * implementation and the model-facing `ws_read`/`ws_write`/`ws_list` tools; core
+ * only needs to be able to *name* a workspace, because {@link ToolFamilyContext}
+ * hands one to every tool family.
+ */
+export interface WorkspaceHandle {
+    /** File content, or null if the file does not exist. */
+    read(path: string): Promise<string | null>;
+    /** Write (create or overwrite) a text file. Parent directories are created. */
+    write(path: string, content: string): Promise<void>;
+    /** Whether a file or directory exists at the path. */
+    exists(path: string): Promise<boolean>;
+    /** Delete a file. Returns whether a file was removed. */
+    remove(path: string): Promise<boolean>;
+    /** Immediate entries under `dir` (default root): their path and byte size. */
+    list(dir?: string): Promise<WorkspaceEntry[]>;
+    /** Parse a JSON file, or null if it does not exist. Throws on malformed JSON. */
+    readJson<T>(path: string): Promise<T | null>;
+    /** Serialize a value to a JSON file (pretty-printed). */
+    writeJson(path: string, value: unknown): Promise<void>;
+}
+export interface WorkspaceEntry {
+    path: string;
+    type: "file" | "directory" | "symlink";
+    size: number;
+}
+/**
+ * The backend surface {@link makeWorkspaceHandle} needs, declared **structurally**
+ * rather than as `Pick<Workspace, …>`.
+ *
+ * That is the whole reason core can stay free of `@cloudflare/shell`: a shell
+ * `Workspace` satisfies this by construction, and so does a plain in-memory fake
+ * in a test, without either being named here.
+ */
+export interface WorkspaceBacking {
+    readFile(path: string): Promise<string | null>;
+    writeFile(path: string, content: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    deleteFile(path: string): Promise<boolean>;
+    readDir(dir?: string): Promise<readonly WorkspaceEntry[]>;
+    getWorkspaceInfo(): Promise<{
+        fileCount: number;
+    }>;
+}
+/**
+ * An in-memory {@link WorkspaceBacking} — the fallback when no installed plugin
+ * declares one.
+ *
+ * Deliberately **not durable**, and that is the honest behaviour rather than a
+ * shortcut: a durable stand-in would have to invent a storage layout that a real
+ * backend would then have to migrate away from. An agent that delegates file
+ * work installs a backend; one that does not never writes a file, and pays
+ * nothing for the option. What this buys is that `createAgentRuntime` composes
+ * without a workspace plugin at all, so `SubagentRuntime.workspaceBacking` can
+ * stay required and a host never writes a null check.
+ *
+ * Scoped per call, so each execution gets its own map, exactly as a facet's own
+ * SQLite would give it its own tables. Contents are lost on isolate eviction —
+ * the resumable runner treats a lost workspace as a resumable state everywhere
+ * it matters.
+ *
+ * Signature matches {@link AgentPlugin.workspaceBacking}; both arguments are
+ * ignored.
+ */
+export declare function memoryWorkspaceBacking(_sql?: SqlStorage, _name?: () => string | undefined): WorkspaceBacking;
+/** Per-file byte ceiling — safely under the 2 MB Durable Object SQLite row limit. */
+export declare const WORKSPACE_MAX_FILE_BYTES: number;
+/** Max number of files in one workspace — a cheap guard against runaway writes. */
+export declare const WORKSPACE_MAX_FILES = 200;
+export declare class WorkspaceLimitError extends Error {
+    constructor(message: string);
+}
+/**
+ * Build a {@link WorkspaceHandle} over a shell workspace (or a test fake),
+ * enforcing the per-file and file-count caps. The caps degrade a misbehaving
+ * recipe to an explicit error rather than letting it exceed the DO row limit or
+ * fill storage.
+ */
+export declare function makeWorkspaceHandle(ws: WorkspaceBacking): WorkspaceHandle;