@dynamicagents/core 0.9.0

package/dist/runtime/index.js

@@ -0,0 +1,186 @@
+import { resolveConfig } from "../config.js";
+import { PLUGIN_CONTRACT_VERSION } from "../contract/plugin.js";
+import { memoryWorkspaceBacking } from "../subagent/workspace.js";
+import { makeSubtaskTypes } from "../subtasks/subtask-types.js";
+import { collectToolFamilies } from "./tool-families.js";
+export { buildRecipeTools, collectToolFamilies } from "./tool-families.js";
+/**
+ * Thrown when the installed plugins and the host disagree — a contract-version
+ * skew, a duplicate key, or a missing binding. Always at DO start, never mid-request.
+ */
+export class RuntimeSetupError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RuntimeSetupError";
+    }
+}
+export function createAgentRuntime(options) {
+    const config = resolveConfig(options.config);
+    const plugins = options.plugins;
+    // --- contract + identity checks, all up front -----------------------------
+    const byKey = new Map();
+    for (const plugin of plugins) {
+        if (byKey.has(plugin.key)) {
+            throw new RuntimeSetupError(`duplicate plugin key "${plugin.key}" — two installed plugins claim it`);
+        }
+        byKey.set(plugin.key, plugin);
+        if (plugin.contractVersion !== PLUGIN_CONTRACT_VERSION) {
+            throw new RuntimeSetupError(`plugin "${plugin.key}" was built against plugin contract v${plugin.contractVersion}, ` +
+                `but this @dynamicagents/core speaks v${PLUGIN_CONTRACT_VERSION}. ` +
+                "Upgrade whichever of the two is behind — they publish from separate repos, " +
+                "so a version train can leave one lagging.");
+        }
+    }
+    // --- what the plugins contribute ------------------------------------------
+    const specs = plugins.flatMap((p) => (p.subtaskType ? [p.subtaskType] : []));
+    const types = makeSubtaskTypes(specs);
+    const toolFamilies = collectToolFamilies(plugins);
+    const typeOwner = new Map();
+    for (const plugin of plugins) {
+        if (plugin.subtaskType)
+            typeOwner.set(plugin.subtaskType.key, plugin);
+    }
+    const stores = plugins.flatMap((p) => (p.store ? [p.store] : []));
+    const displacementListeners = plugins.flatMap((p) => p.onMessagesDisplaced
+        ? [{ key: p.key, notify: p.onMessagesDisplaced.bind(p) }]
+        : []);
+    const turnGates = plugins.flatMap((p) => p.shouldHandleTurn ? [{ key: p.key, gate: p.shouldHandleTurn.bind(p) }] : []);
+    // At most one backend: two would mean two answers to "where did that file go".
+    const backings = plugins.flatMap((p) => p.workspaceBacking ? [{ key: p.key, make: p.workspaceBacking.bind(p) }] : []);
+    if (backings.length > 1) {
+        throw new RuntimeSetupError(`plugins ${backings.map((b) => `"${b.key}"`).join(" and ")} both declare a ` +
+            "workspaceBacking — an execution has one workspace, so only one plugin may back it");
+    }
+    const workspaceBacking = backings[0]?.make ?? memoryWorkspaceBacking;
+    const secrets = [
+        ...new Set(plugins.flatMap((p) => [...(p.requires?.secrets ?? [])]))
+    ];
+    const bindings = [
+        ...new Set(plugins.flatMap((p) => [...(p.requires?.bindings ?? [])]))
+    ];
+    if (options.env) {
+        const env = options.env;
+        const missing = [];
+        for (const plugin of plugins) {
+            for (const name of [
+                ...(plugin.requires?.secrets ?? []),
+                ...(plugin.requires?.bindings ?? [])
+            ]) {
+                const value = env[name];
+                if (value === undefined || value === null || value === "") {
+                    missing.push(`${name} (required by "${plugin.key}")`);
+                }
+            }
+        }
+        if (missing.length > 0) {
+            throw new RuntimeSetupError(`missing bindings or secrets: ${missing.join(", ")}. ` +
+                "A plugin cannot add its own wrangler binding — declare these in wrangler.jsonc " +
+                "(and `wrangler secret put` the secrets).");
+        }
+    }
+    const policy = {
+        primaryModelId: config.model.chatModelId,
+        fallbackModelId: config.model.fallbackChatModelId,
+        knownToolFamilies: new Set(toolFamilies.keys()),
+        baselineLimits: config.subagentLimits
+    };
+    const pluginForType = (type) => typeOwner.get(type) ?? null;
+    return {
+        config,
+        plugins,
+        types,
+        toolFamilies,
+        policy,
+        stores,
+        requirements: { secrets, bindings },
+        workspaceBacking,
+        pluginForType,
+        async mainAgentTools(ctx) {
+            const tools = {};
+            // Sequential rather than fanned out: this is a handful of plugins reading
+            // one session, and merging in declaration order is what makes a name
+            // collision resolve the same way on every call.
+            for (const plugin of plugins) {
+                if (plugin.mainAgentTools)
+                    Object.assign(tools, await plugin.mainAgentTools(ctx));
+            }
+            return tools;
+        },
+        renderCapabilities() {
+            const blocks = [];
+            for (const plugin of plugins) {
+                // Both blocks a plugin may declare, emitted adjacently: a plugin that
+                // declares a subtask type puts its capability on the *type*, and one
+                // that only offers main-agent tools puts it on the plugin. Declaring
+                // both is legal and means the model reads both.
+                if (plugin.capability)
+                    blocks.push(plugin.capability);
+                if (plugin.subtaskType?.capability)
+                    blocks.push(plugin.subtaskType.capability);
+            }
+            return blocks.join("\n\n");
+        },
+        async shouldHandleTurn(ctx) {
+            if (turnGates.length === 0)
+                return true;
+            // Same `allSettled` + `async`-wrapped-callback discipline as
+            // `onMessagesDisplaced` below, and for the same two reasons: every gate is
+            // consulted even when one throws, and a gate that throws *synchronously*
+            // (reading a binding before its first await) is caught rather than
+            // escaping past the aggregation.
+            //
+            // A rejection resolves to `true`. That is not leniency — it is the only
+            // safe default here. A wrong reply is noise the user sees and ignores; a
+            // wrong silence is invisible to the person who needed an answer, so a
+            // broken gate must degrade to "run the turn" and never to a mute agent.
+            const results = await Promise.allSettled(turnGates.map(async (g) => g.gate(ctx)));
+            return results.every((result, i) => {
+                if (result.status === "rejected") {
+                    console.warn(`[runtime] plugin "${turnGates[i].key}" turn gate failed, handling the turn`, result.reason);
+                    return true;
+                }
+                return result.value;
+            });
+        },
+        async onMessagesDisplaced(messages) {
+            // allSettled, not all: `all` rejects at the first listener to throw and
+            // stops awaiting the rest, so every other plugin's write is still in
+            // flight when this returns — and on a Durable Object the isolate can be
+            // evicted before it lands. One plugin's outage would silently cost the
+            // others their writes. Each rejection is logged against the key that
+            // caused it; an anonymous aggregate is not debuggable across plugins.
+            //
+            // The `async` on the map callback is load-bearing, not style. A listener
+            // is typed `(messages) => Promise<void>`, which does not oblige it to be
+            // `async` — one that reads a binding before starting its async work can
+            // throw *synchronously*, during this very `.map()`. Without the `async`
+            // that throw escapes before `Promise.allSettled` exists to catch it: this
+            // method rejects despite documenting that it never does, and `.map()`
+            // aborts mid-iteration so every listener after the thrower is never even
+            // invoked — strictly worse than the `Promise.all` failure mode above.
+            const results = await Promise.allSettled(displacementListeners.map(async (l) => l.notify(messages)));
+            results.forEach((result, i) => {
+                if (result.status === "rejected") {
+                    console.error(`[runtime] plugin "${displacementListeners[i].key}" failed on displaced messages`, result.reason);
+                }
+            });
+        },
+        async resolveRuntime(ctx) {
+            const plugin = pluginForType(ctx.type);
+            if (!plugin?.resolveRuntime)
+                return {};
+            return (await plugin.resolveRuntime(ctx));
+        },
+        async enrichResult(ctx, result) {
+            const plugin = pluginForType(ctx.request.type);
+            if (!plugin?.enrichResult)
+                return result;
+            return plugin.enrichResult(ctx, result);
+        },
+        async onAbort(ctx) {
+            const plugin = pluginForType(ctx.type);
+            if (plugin?.onAbort)
+                await plugin.onAbort(ctx);
+        }
+    };
+}

package/dist/runtime/tool-families.d.ts

@@ -0,0 +1,32 @@
+import type { RecipeToolSet, ToolFamilyBuilder, ToolFamilyContext } from "../contract/plugin.js";
+import type { SubtaskRuntime } from "../subtasks/types.js";
+/**
+ * Assemble a recipe's toolset from the installed families.
+ *
+ * This replaces the predecessor's dispatcher, which was an `if / else if` chain
+ * naming three families inline — including a domain one — inside otherwise
+ * generic code, with static imports of that domain's modules at the top of the
+ * file. That is the single edit that made every agent's bundle carry every
+ * domain, and it is why this takes a map instead.
+ *
+ * A family a recipe names but no plugin registered is skipped rather than
+ * throwing: `validateRecipe` already dropped unknown families, so reaching one
+ * here means the policy and the registry disagreed, and a subagent that silently
+ * runs with fewer tools degrades better than one that fails a whole branch. The
+ * skipped names are returned so a caller can log them.
+ */
+export declare function buildRecipeTools<TRuntime = SubtaskRuntime>(families: readonly string[], registry: ReadonlyMap<string, ToolFamilyBuilder<TRuntime>>, ctx: ToolFamilyContext<TRuntime>): RecipeToolSet<TRuntime> & {
+    skipped: string[];
+};
+/**
+ * Collect every family builder the installed plugins registered, refusing
+ * duplicates.
+ *
+ * Two plugins claiming one family name is a misconfiguration whose symptom would
+ * otherwise be a subagent silently getting the wrong domain's tools — so it fails
+ * at DO start, named, instead.
+ */
+export declare function collectToolFamilies<TRuntime = SubtaskRuntime>(plugins: readonly {
+    key: string;
+    toolFamilies?: Record<string, ToolFamilyBuilder<TRuntime>>;
+}[]): Map<string, ToolFamilyBuilder<TRuntime>>;

package/dist/runtime/tool-families.js

@@ -0,0 +1,61 @@
+/**
+ * Assemble a recipe's toolset from the installed families.
+ *
+ * This replaces the predecessor's dispatcher, which was an `if / else if` chain
+ * naming three families inline — including a domain one — inside otherwise
+ * generic code, with static imports of that domain's modules at the top of the
+ * file. That is the single edit that made every agent's bundle carry every
+ * domain, and it is why this takes a map instead.
+ *
+ * A family a recipe names but no plugin registered is skipped rather than
+ * throwing: `validateRecipe` already dropped unknown families, so reaching one
+ * here means the policy and the registry disagreed, and a subagent that silently
+ * runs with fewer tools degrades better than one that fails a whole branch. The
+ * skipped names are returned so a caller can log them.
+ */
+export function buildRecipeTools(families, registry, ctx) {
+    const tools = {};
+    const aborts = [];
+    const skipped = [];
+    for (const family of families) {
+        const build = registry.get(family);
+        if (!build) {
+            skipped.push(family);
+            continue;
+        }
+        const built = build(ctx);
+        Object.assign(tools, built.tools);
+        if (built.abort)
+            aborts.push(built.abort);
+    }
+    const abort = aborts.length === 0
+        ? undefined
+        : async (c) => {
+            for (const run of aborts)
+                await run(c);
+        };
+    return { tools, abort, skipped };
+}
+/**
+ * Collect every family builder the installed plugins registered, refusing
+ * duplicates.
+ *
+ * Two plugins claiming one family name is a misconfiguration whose symptom would
+ * otherwise be a subagent silently getting the wrong domain's tools — so it fails
+ * at DO start, named, instead.
+ */
+export function collectToolFamilies(plugins) {
+    const registry = new Map();
+    const owner = new Map();
+    for (const plugin of plugins) {
+        for (const [family, build] of Object.entries(plugin.toolFamilies ?? {})) {
+            const existing = owner.get(family);
+            if (existing) {
+                throw new Error(`tool family "${family}" is registered by both "${existing}" and "${plugin.key}"`);
+            }
+            owner.set(family, plugin.key);
+            registry.set(family, build);
+        }
+    }
+    return registry;
+}

package/dist/subagent/fingerprint.d.ts

@@ -0,0 +1,37 @@
+import type { RecipeExecutionRequest } from "../subtasks/types.js";
+/**
+ * Version of the canonicalization format below.
+ *
+ * Bump it **only** when a change to `canonicalRequest` would make two equal
+ * executions hash differently. Bumping invalidates every cached result and every
+ * in-flight run's checkpoint, so it is a deliberate act, not a side effect.
+ */
+export declare const FINGERPRINT_VERSION = 1;
+/**
+ * Canonical JSON of the fields that define an execution's identity, rebuilt as
+ * literals in fixed key order so `JSON.stringify` is deterministic (object
+ * insertion order). Array order is semantic and preserved: the parent builds
+ * references from ordinal-ordered rows, so a retry of the same execution is
+ * byte-identical.
+ *
+ * **Limits are canonicalized as *declared*, not as merged.** The predecessor
+ * merged them against the house baseline first, on the reasoning that `{}` and
+ * an explicit restatement of the baseline are the same execution and should hash
+ * alike. That reasoning is sound but its cost is not payable once the baseline
+ * lives in a versioned package: a patch release that nudges a default would
+ * change every fingerprint at once, and every in-flight subagent run would miss
+ * its checkpoint and restart from turn zero having already spent its budget.
+ *
+ * Hashing the sparse declaration inverts that trade. A recipe that spells out
+ * the baseline explicitly gets a different key from one that omits it — worth
+ * exactly one redundant execution, once, for a recipe nobody writes — and the
+ * host's baseline becomes free to move. {@link FINGERPRINT_VERSION} is the
+ * deliberate lever for the invalidation the merge used to cause accidentally.
+ */
+export declare function canonicalRequest(request: RecipeExecutionRequest): string;
+/**
+ * SHA-256 hex digest of the canonical request — the deterministic key for the
+ * subagent's single cached terminal result. The raw (pre-validation) request is
+ * fingerprinted, so the key matches exactly what the parent re-sends on retry.
+ */
+export declare function fingerprintRequest(request: RecipeExecutionRequest): Promise<string>;

package/dist/subagent/fingerprint.js

@@ -0,0 +1,92 @@
+/**
+ * Version of the canonicalization format below.
+ *
+ * Bump it **only** when a change to `canonicalRequest` would make two equal
+ * executions hash differently. Bumping invalidates every cached result and every
+ * in-flight run's checkpoint, so it is a deliberate act, not a side effect.
+ */
+export const FINGERPRINT_VERSION = 1;
+/**
+ * Canonical JSON of the fields that define an execution's identity, rebuilt as
+ * literals in fixed key order so `JSON.stringify` is deterministic (object
+ * insertion order). Array order is semantic and preserved: the parent builds
+ * references from ordinal-ordered rows, so a retry of the same execution is
+ * byte-identical.
+ *
+ * **Limits are canonicalized as *declared*, not as merged.** The predecessor
+ * merged them against the house baseline first, on the reasoning that `{}` and
+ * an explicit restatement of the baseline are the same execution and should hash
+ * alike. That reasoning is sound but its cost is not payable once the baseline
+ * lives in a versioned package: a patch release that nudges a default would
+ * change every fingerprint at once, and every in-flight subagent run would miss
+ * its checkpoint and restart from turn zero having already spent its budget.
+ *
+ * Hashing the sparse declaration inverts that trade. A recipe that spells out
+ * the baseline explicitly gets a different key from one that omits it — worth
+ * exactly one redundant execution, once, for a recipe nobody writes — and the
+ * host's baseline becomes free to move. {@link FINGERPRINT_VERSION} is the
+ * deliberate lever for the invalidation the merge used to cause accidentally.
+ */
+export function canonicalRequest(request) {
+    const canonical = {
+        v: FINGERPRINT_VERSION,
+        taskId: request.taskId,
+        subtaskId: request.subtaskId,
+        type: request.type,
+        recipe: {
+            key: request.recipe.key,
+            version: request.recipe.version,
+            // No model ids. Their absence is the same trade this file already makes
+            // for `limits`: the host's own configuration stays out of the fingerprint,
+            // so changing it does not invalidate every checkpoint at once and restart
+            // every in-flight run from turn zero with its budget already spent. A run
+            // that resumes on a newly configured model resumes from conversation
+            // state, which is model-independent.
+            soul: request.recipe.soul,
+            toolFamilies: request.recipe.toolFamilies,
+            enabled: request.recipe.enabled,
+            limits: canonicalLimits(request.recipe.limits),
+            historyWindow: request.recipe.historyWindow,
+            reportMetrics: request.recipe.reportMetrics
+        },
+        prompt: request.prompt,
+        references: request.references.map((ref) => ({
+            role: ref.role,
+            text: ref.text
+        })),
+        // Params ARE identity: the same prompt against a different external resource
+        // is different work, and must not replay a cached result. Key order is fixed
+        // by sorting, so an equivalent params object always canonicalizes identically.
+        params: Object.fromEntries(Object.entries(request.params).sort(([a], [b]) => (a < b ? -1 : 1)))
+    };
+    return JSON.stringify(canonical);
+}
+/**
+ * A recipe's declared budget, normalized: only positive integers count (matching
+ * what `resolveLimits` would honor), and fields appear in fixed order with
+ * absent ones omitted. So `{}`, `{ maxTurns: 0 }`, and `{ maxTurns: 1.5 }` all
+ * canonicalize alike — they all mean "inherit the baseline".
+ */
+function canonicalLimits(limits) {
+    const keep = (n) => typeof n === "number" && Number.isInteger(n) && n > 0 ? n : undefined;
+    const out = {};
+    const maxTurns = keep(limits?.maxTurns);
+    if (maxTurns !== undefined)
+        out.maxTurns = maxTurns;
+    const maxWallMs = keep(limits?.maxWallMs);
+    if (maxWallMs !== undefined)
+        out.maxWallMs = maxWallMs;
+    return out;
+}
+/**
+ * SHA-256 hex digest of the canonical request — the deterministic key for the
+ * subagent's single cached terminal result. The raw (pre-validation) request is
+ * fingerprinted, so the key matches exactly what the parent re-sends on retry.
+ */
+export async function fingerprintRequest(request) {
+    const bytes = new TextEncoder().encode(canonicalRequest(request));
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return [...new Uint8Array(digest)]
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}

package/dist/subagent/index.d.ts

@@ -0,0 +1,169 @@
+import { Agent } from "agents";
+import type { ModelPair, ModelRuntime } from "../agent/model.js";
+import type { ToolFamilyBuilder } from "../contract/plugin.js";
+import { type RecipePolicy } from "../contract/validation.js";
+import type { RecipeChunkResult, RecipeExecutionRequest, SubtaskId, SubtaskRuntime } from "../subtasks/types.js";
+import { type SubtaskTypeRegistry } from "../subtasks/subtask-types.js";
+import { type WorkspaceBacking } from "./workspace.js";
+/**
+ * Everything the facet needs that comes from the *host*: resolved config, the
+ * capability policy, the installed subtask types and tool families, the model
+ * runtime, and a workspace backend.
+ *
+ * A Durable Object class is constructed by the runtime, so it cannot take
+ * constructor arguments — which is exactly the problem a library version of this
+ * facet has to solve. {@link RecipeSubagentBase} takes it from an abstract
+ * method instead: the consumer subclasses once, and everything host-specific
+ * arrives through that one seam.
+ */
+export interface SubagentRuntime {
+    policy: RecipePolicy;
+    types: SubtaskTypeRegistry;
+    models: ModelRuntime;
+    toolFamilies: ReadonlyMap<string, ToolFamilyBuilder>;
+    /** `CoreConfig.toolOutputWindow`. */
+    toolOutputWindow: number;
+    /** `CoreConfig.model.maxOutputTokens`. */
+    maxOutputTokens: number;
+    /** `CoreConfig.model.maxRetries`. */
+    maxRetries: number;
+    /**
+     * Build the durable file store over this facet's own SQLite.
+     *
+     * Supplied by the host because the backend is a plugin's: core declares the
+     * {@link WorkspaceBacking} shape and the caps, `@dynamicagents/plugins/workspace`
+     * supplies the `@cloudflare/shell` implementation, and an agent that never
+     * delegates file work installs neither.
+     */
+    workspaceBacking(sql: SqlStorage, name: () => string | undefined): WorkspaceBacking;
+}
+/**
+ * Message prefix of the error thrown when a child that already holds a cached
+ * terminal result receives a *different* request. Custom error classes don't
+ * survive DO RPC, so this prefix is the cross-boundary contract: it signals a
+ * parent lifecycle bug — stale children must be deleted before a genuinely new
+ * execution — and a Workflow retry after the parent's cleanup will succeed.
+ */
+export declare const FINGERPRINT_MISMATCH = "recipe-subagent: request fingerprint mismatch";
+/** Deterministic managed-child name for one Subtask execution. */
+export declare function subagentName(taskId: string, subtaskId: SubtaskId): string;
+/**
+ * `RecipeSubagent` — the isolated, stateless managed child that executes one
+ * Subtask under a resolved Recipe. Created as an Agents SDK sub-agent (facet)
+ * beneath the calling agent, so it needs no wrangler Durable Object binding and
+ * no `new_sqlite_classes` entry; it must only be exported from the consuming
+ * Worker's entry so `ctx.exports` can resolve it by class name.
+ *
+ * It never constructs a Session, never reads parent history beyond the
+ * references supplied on its request, never reaches durable memory, and never
+ * resolves a Recipe itself — it defensively re-validates the resolved Recipe the
+ * parent sends and accepts no configuration beyond it.
+ *
+ * Retry safety: the child persists at most one terminal result in its own
+ * SQLite, keyed by the deterministic request fingerprint, plus the rolling
+ * `run_state` of an in-progress multi-chunk run. A retry with the same
+ * fingerprint replays the terminal result or resumes the run without repeating
+ * completed work; a different request for the same child name is rejected
+ * ({@link FINGERPRINT_MISMATCH}). Transient platform faults throw and cache
+ * nothing, so the enclosing Workflow step can retry. The parent deletes the child
+ * (`deleteSubAgent`) only after its durable copy of the result succeeds, which
+ * wipes this storage — the workspace and run state included.
+ *
+ * Not "stateless" like the single-shot original: it owns per-execution durable
+ * state (the workspace and the run checkpoint), scoped to one execution and swept
+ * with the child.
+ */
+export declare abstract class RecipeSubagentBase<TEnv extends Cloudflare.Env = Cloudflare.Env> extends Agent<TEnv> {
+    /**
+     * Supply the host runtime. Called per RPC, not memoized here — an
+     * implementation that builds something expensive should memoize its own.
+     *
+     * ```ts
+     * export class RecipeSubagent extends RecipeSubagentBase<Env> {
+     *   protected subagentRuntime() {
+     *     return (this._rt ??= buildSubagentRuntime(this.env));
+     *   }
+     * }
+     * ```
+     */
+    protected abstract subagentRuntime(): SubagentRuntime;
+    /**
+     * Test-only `ModelPair` injection (a field, so never on the RPC stub).
+     * A whole pair — rather than model instances — so error-path tests can throw
+     * synchronously from the pair's factories, the repo convention (a rejecting
+     * `doGenerate` inside `generateText` leaks an unhandled rejection through
+     * the AI SDK telemetry span that workerd flags as a failure).
+     */
+    modelsOverride?: ModelPair;
+    private _workspace?;
+    /**
+     * The chunk currently executing here, if any. In memory only — it exists to be
+     * interrupted mid-call, and an isolate that lost it has no in-flight call left
+     * to interrupt. See {@link abortRun}.
+     */
+    private inflight?;
+    /**
+     * This deployment's own public origin, as the parent DO passes it on every
+     * chunk, pinned from the first. In memory for the same reason {@link inflight}
+     * is: a facet is reached only through {@link executeChunk}, so an instance that
+     * lost it is an instance that will be told again before it can run anything.
+     * See {@link SelfOrigin}.
+     */
+    private readonly selfOriginMemo;
+    onStart(): Promise<void>;
+    /**
+     * Idempotent schema bootstrap. Also called lazily from the RPCs so
+     * `runInDurableObject`-style tests reach ready tables without RPC dispatch
+     * (mirroring how `AgentDB` migrates on construction).
+     */
+    private ensureTables;
+    /** The recipe's durable workspace, backed by this facet's own SQLite storage. */
+    private workspace;
+    /**
+     * This deployment's own public origin, if the parent has passed it to this
+     * instance yet. See {@link SelfOrigin}.
+     */
+    protected selfOrigin(): string | undefined;
+    /**
+     * The same, for a caller that cannot proceed without it — a facet that signs
+     * its own caller tokens, above all. Mirrors `DynamicAgent.requireSelfOrigin`,
+     * because a facet must run on the same provider, and so the same credential
+     * path, as the parent that delegated to it.
+     */
+    protected requireSelfOrigin(): string;
+    /**
+     * Execute one durable chunk of a Subtask under the parent's resolved Recipe.
+     *
+     * A terminal outcome (completed / failed) is cached and replayed on retry. A
+     * mid-run chunk persists its rolling state to `run_state` and returns a
+     * `done: false` yield for the Workflow to run another chunk. `chunk` and
+     * `selfOrigin` are separate arguments — never part of `request` — so every
+     * chunk fingerprints identically and the cache/resume keys line up. Only
+     * transient platform faults throw (nothing cached), so a Workflow retry
+     * resumes from the last checkpoint.
+     */
+    executeChunk(request: RecipeExecutionRequest, _chunk: number, runtime?: SubtaskRuntime, selfOrigin?: string): Promise<RecipeChunkResult>;
+    /**
+     * Interrupt the chunk running here right now, so a cancellation lands on the
+     * current model call instead of at the next chunk boundary (up to `chunkSoftMs`
+     * later — minutes, for a long recipe). Returns whether there was one to stop.
+     *
+     * Distinct from {@link abortExecution}, which releases *external* state after
+     * the fact; this only stops local work. An aborted run yields rather than
+     * producing a terminal result, so nothing is cached and the parent resolves the
+     * row itself. Reaching a facet mid-`executeChunk` works because it is awaiting
+     * a model `fetch` at the time, which does not hold the input gate closed.
+     */
+    abortRun(): Promise<boolean>;
+    /**
+     * Best-effort cleanup on cancellation: rebuild the recipe's tool families and
+     * run their `abort` hooks (e.g. release an external resource recorded in the
+     * workspace session file). Reconstructible from the workspace, so it is safe on a fresh
+     * isolate. The parent supplies the validated tool families it resolved.
+     */
+    abortExecution(toolFamilies: string[]): Promise<void>;
+    /** Persist a terminal result to the cache and return it as a done chunk. */
+    private cacheTerminal;
+    /** Persist the rolling run state (called after every model turn). */
+    private saveRunState;
+}