@avocadostudio-ai/orchestrator-core 0.29.0 → 0.30.0

package/dist/agents/assistant/skills.d.ts

@@ -0,0 +1,31 @@
+import type { RuntimeTool } from "../runtime/definition.ts";
+export type Skill = {
+    /** Lowercase, digits and dashes; the name `use_skill` takes. */
+    name: string;
+    /** A label for people, e.g. "Search analysis". */
+    title: string;
+    /** One line: what it is for and when to use it. Always in the prompt. */
+    description: string;
+    /** The method. Loaded on demand. */
+    body: string;
+    /** Connector ids it cannot work without. */
+    needs: string[];
+    origin: "builtin" | "site";
+};
+export declare const SKILL_MAX_CHARS = 12000;
+/** Parse a `SKILL.md`. Only `name`, `title`, `description` and `needs` are read from the frontmatter. */
+export declare function parseSkillMarkdown(text: string, origin: Skill["origin"]): Skill | {
+    error: string;
+};
+export declare const BUILTIN_SKILLS: Skill[];
+/** Built-ins first; a site skill with a built-in's name is ignored rather than allowed to replace it. */
+export declare function mergeSkills(site: Skill[]): Skill[];
+/** The lines that tell a run which skills exist. */
+export declare function skillCatalog(skills: Skill[]): string;
+/** A skill's body as preloaded into a routine's instructions. */
+export declare function skillSection(skill: Skill): string;
+/**
+ * `use_skill`: load a skill's method. Reading is its only effect. What it
+ * returns is instructions from the site's own skills, so it is not fenced.
+ */
+export declare function useSkillTool(skills: Skill[]): RuntimeTool;

package/dist/agents/assistant/skills.js

@@ -0,0 +1,79 @@
+import { BUILTIN_SKILL_TEXTS } from "./builtin-skills.js";
+const NAME = /^[a-z0-9][a-z0-9-]{1,47}$/;
+export const SKILL_MAX_CHARS = 12_000;
+function listValue(raw) {
+    return raw
+        .replace(/^\[|\]$/g, "")
+        .split(",")
+        .map((part) => part.trim().replace(/^["']|["']$/g, ""))
+        .filter(Boolean);
+}
+/** Parse a `SKILL.md`. Only `name`, `title`, `description` and `needs` are read from the frontmatter. */
+export function parseSkillMarkdown(text, origin) {
+    if (text.length > SKILL_MAX_CHARS)
+        return { error: `a skill is at most ${SKILL_MAX_CHARS} characters` };
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text.trim());
+    if (!match)
+        return { error: "a skill starts with frontmatter between --- lines" };
+    const fields = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const pair = /^([a-z_]+):\s*(.*)$/.exec(line.trim());
+        if (pair)
+            fields[pair[1]] = pair[2].trim().replace(/^["']|["']$/g, "");
+    }
+    const name = fields.name ?? "";
+    if (!NAME.test(name))
+        return { error: "name must be lowercase letters, digits and dashes" };
+    const description = fields.description ?? "";
+    if (!description)
+        return { error: "description is required" };
+    const body = match[2].trim();
+    if (!body)
+        return { error: "the skill has no body" };
+    const title = fields.title || name.replace(/-/g, " ").replace(/^./, (c) => c.toUpperCase());
+    return { name, title, description, body, needs: fields.needs ? listValue(fields.needs) : [], origin };
+}
+function parseBuiltin(text) {
+    const parsed = parseSkillMarkdown(text, "builtin");
+    if ("error" in parsed)
+        throw new Error(`built-in skill does not parse: ${parsed.error}`);
+    return parsed;
+}
+export const BUILTIN_SKILLS = BUILTIN_SKILL_TEXTS.map(parseBuiltin);
+/** Built-ins first; a site skill with a built-in's name is ignored rather than allowed to replace it. */
+export function mergeSkills(site) {
+    const builtin = new Set(BUILTIN_SKILLS.map((skill) => skill.name));
+    return [...BUILTIN_SKILLS, ...site.filter((skill) => !builtin.has(skill.name))];
+}
+/** The lines that tell a run which skills exist. */
+export function skillCatalog(skills) {
+    if (skills.length === 0)
+        return "";
+    return [
+        "Skills you can load with use_skill, by name, when a task matches one. Load it before you act on that task:",
+        ...skills.map((skill) => `- ${skill.name}: ${skill.description}`)
+    ].join("\n");
+}
+/** A skill's body as preloaded into a routine's instructions. */
+export function skillSection(skill) {
+    return `## Skill: ${skill.title}\n\n${skill.body}`;
+}
+/**
+ * `use_skill`: load a skill's method. Reading is its only effect. What it
+ * returns is instructions from the site's own skills, so it is not fenced.
+ */
+export function useSkillTool(skills) {
+    return {
+        name: "use_skill",
+        effect: "read",
+        description: "Load a skill's method by name before doing the task it covers. The list of skills is in your instructions.",
+        inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
+        run: async (input) => {
+            const name = typeof input.name === "string" ? input.name.trim() : "";
+            const skill = skills.find((candidate) => candidate.name === name);
+            if (!skill)
+                return { result: `No skill ${name}. Use one of: ${skills.map((s) => s.name).join(", ")}.`, isError: true };
+            return { result: skillSection(skill), trace: `loaded skill ${skill.name}` };
+        }
+    };
+}

package/dist/agents/learning.js

@@ -38,6 +38,13 @@ export const SITE_FACT_KINDS = ["fact", "preference", "glossary"];
 export function isSiteFactKind(value) {
     return typeof value === "string" && SITE_FACT_KINDS.includes(value);
 }
+/** The About-this-site sections (agents/assistant/context.ts keys), as the planner reads them. */
+const ABOUT_LABELS = {
+    "about.business": "About the business",
+    "about.voice": "Voice and tone",
+    "about.goals": "What counts as a win",
+    "about.avoid": "Do not touch"
+};
 /** How many facts reach the planner. The rest stay visible in the editor. */
 export const SITE_FACTS_IN_PROMPT = 40;
 /** Longer than this and a "fact" is a document; it belongs in the site's content. */
@@ -59,13 +66,20 @@ export async function siteFactsForPlanner(scopeKey, log) {
     if (!siteOpsAgentsEnabled())
         return [];
     try {
-        const facts = await listSiteFacts(scopeKey, SITE_FACTS_IN_PROMPT);
-        if (facts.length === 0)
-            return [];
-        void getDurableStore()
-            .touchMemory(facts.map((fact) => fact.id))
-            .catch(() => { });
-        return facts.map((fact) => fact.value);
+        const [facts, about] = await Promise.all([
+            listSiteFacts(scopeKey, SITE_FACTS_IN_PROMPT),
+            getDurableStore().listMemory({ scopeKey, scope: "site", kind: "decision", status: "active", limit: 20 })
+        ]);
+        if (facts.length > 0) {
+            void getDurableStore()
+                .touchMemory(facts.map((fact) => fact.id))
+                .catch(() => { });
+        }
+        // About this site (agents/assistant/context.ts): what the assistant reads first, the planner reads too.
+        const aboutLines = about
+            .filter((row) => ABOUT_LABELS[row.key])
+            .map((row) => `${ABOUT_LABELS[row.key]}: ${row.value}`);
+        return [...aboutLines, ...facts.map((fact) => fact.value)];
     }
     catch (error) {
         log?.warn({ err: error }, "[learning] site facts unavailable; planning without them");

package/dist/agents/runtime/apply.d.ts

@@ -0,0 +1,29 @@
+import type { Logger } from "../../logger.ts";
+import type { VersionActor } from "../../state/sqlite-store.ts";
+import { type ProposedChange } from "./toolkit.ts";
+export type ChangeSetOutcome = {
+    applied: Array<{
+        slug: string;
+        changes: number;
+    }>;
+    /** A field somebody changed after it was read: left as the person wrote it. */
+    stale: Array<{
+        slug: string;
+        path: string;
+    }>;
+    failed: Array<{
+        slug: string;
+        error: string;
+    }>;
+    /** Pages that no longer exist. */
+    missing: string[];
+    previewVersion?: number;
+};
+export declare function applyChangeSet(args: {
+    scopeKey: string;
+    changes: ProposedChange[];
+    actor: VersionActor;
+    /** The version log's line for it. */
+    summary: string;
+    log?: Logger;
+}): Promise<ChangeSetOutcome>;

package/dist/agents/runtime/apply.js

@@ -0,0 +1,72 @@
+/*
+ * Applying a set of field changes to the draft, page by page, with undo.
+ *
+ * Two callers: approving an agent's proposal in the Inbox (approve.ts), and
+ * the site assistant changing the site in chat, where the person who asked is
+ * the approval (`apply_changes`, toolkit.ts). Both write the same way: each
+ * change only onto the value it was written against, each page atomically and
+ * with its own undo entry, and one version-log entry naming who made it.
+ */
+import { buildBlockManifest } from "@avocadostudio-ai/shared";
+import { consoleLogger } from "../../logger.js";
+import { applyOpsAtomically } from "../../ops/ops-engine.js";
+import { bumpVersion, getPage, pushUndo, pushVersionEntry, schedulePersistState } from "../../state/session-state.js";
+import { readField, writeOpFor } from "./toolkit.js";
+const sameValue = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+export async function applyChangeSet(args) {
+    const byPage = new Map();
+    for (const change of args.changes)
+        byPage.set(change.pageSlug, [...(byPage.get(change.pageSlug) ?? []), change]);
+    const outcome = { applied: [], stale: [], failed: [], missing: [] };
+    const appliedOps = [];
+    let lastSlug;
+    const manifest = buildBlockManifest();
+    for (const [slug, changes] of byPage) {
+        const page = getPage(args.scopeKey, slug);
+        if (!page) {
+            outcome.missing.push(slug);
+            continue;
+        }
+        const ops = [];
+        for (const change of changes) {
+            const current = readField(page, change.blockId, change.path);
+            if (!current.found || !sameValue(current.value, change.base)) {
+                outcome.stale.push({ slug, path: `${change.blockId}.${change.path}` });
+                continue;
+            }
+            const op = writeOpFor({ pageSlug: slug, blockId: change.blockId, path: change.path, value: change.value, ...(change.itemId ? { itemId: change.itemId } : {}) });
+            if (op)
+                ops.push(op);
+        }
+        if (ops.length === 0)
+            continue;
+        const before = structuredClone(page);
+        try {
+            await applyOpsAtomically(args.scopeKey, ops, { componentsManifest: manifest });
+            pushUndo(args.scopeKey, slug, before);
+            appliedOps.push(...ops);
+            lastSlug = slug;
+            outcome.applied.push({ slug, changes: ops.length });
+        }
+        catch (error) {
+            outcome.failed.push({ slug, error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    if (appliedOps.length > 0 && lastSlug) {
+        const previewVersion = bumpVersion(args.scopeKey);
+        const snapshot = getPage(args.scopeKey, lastSlug);
+        pushVersionEntry(args.scopeKey, {
+            version: previewVersion,
+            slug: lastSlug,
+            summary: args.summary,
+            opTypes: appliedOps.map((op) => op.op),
+            opCount: appliedOps.length,
+            source: "direct",
+            actor: args.actor,
+            snapshot: snapshot ? structuredClone(snapshot) : null
+        });
+        schedulePersistState(args.log ?? consoleLogger());
+        outcome.previewVersion = previewVersion;
+    }
+    return outcome;
+}

package/dist/agents/runtime/approve.d.ts

@@ -0,0 +1,71 @@
+import type { DurableStore } from "../../durable/types.ts";
+import type { Logger } from "../../logger.ts";
+export type ProposalOutcome = {
+    applied: Array<{
+        slug: string;
+        changes: number;
+    }>;
+    stale: Array<{
+        slug: string;
+        path: string;
+    }>;
+    failed: Array<{
+        slug: string;
+        error: string;
+    }>;
+    rejected: string[];
+    /** True once every page of the proposal is decided and the Inbox item closed. */
+    closed: boolean;
+    previewVersion?: number;
+};
+/**
+ * Apply a proposal's changes, for every page or for `slugs` only.
+ *
+ * Each page applies atomically on its own: one page's refusal does not undo
+ * another's success, and the outcome says which is which.
+ */
+export declare function approveAgentProposal(args: {
+    store: DurableStore;
+    scopeKey: string;
+    inboxItemId: string;
+    slugs?: string[];
+    by?: string;
+    now?: () => number;
+    log?: Logger;
+}): Promise<ProposalOutcome>;
+export declare function rejectAgentProposal(args: {
+    store: DurableStore;
+    scopeKey: string;
+    inboxItemId: string;
+    slugs?: string[];
+    by?: string;
+    note?: string;
+    now?: () => number;
+}): Promise<ProposalOutcome>;
+/**
+ * The owner answered an agent's question: close it, resume the run, and keep the
+ * answer as a site fact when they asked for that.
+ */
+export declare function answerAgentQuestion(args: {
+    store: DurableStore;
+    scopeKey: string;
+    inboxItemId: string;
+    answer: string;
+    by?: string;
+    remember?: {
+        key: string;
+    };
+    now?: () => number;
+}): Promise<{
+    resumed: boolean;
+    runId: string;
+}>;
+/**
+ * Questions older than their expiry close, and their runs stop: a run that has
+ * waited a week on an answer is acting on a week-old picture of the site.
+ */
+export declare function expireAgentQuestions(args: {
+    store: DurableStore;
+    scopeKey: string;
+    now?: () => number;
+}): Promise<number>;

package/dist/agents/runtime/approve.js

@@ -0,0 +1,145 @@
+import { answerRun, stopRun } from "./engine.js";
+import { applyChangeSet } from "./apply.js";
+async function openProposal(store, inboxItemId) {
+    const item = await store.getInboxItem(inboxItemId);
+    if (!item || item.kind !== "proposal")
+        throw new Error(`no proposal ${inboxItemId}`);
+    if (item.status !== "open")
+        throw new Error("this proposal is already decided");
+    return item;
+}
+function changesOf(item) {
+    return (item.payload?.changes ?? []).slice();
+}
+/** Record which pages are decided; close the item and the proposal once all are. */
+async function recordDecisions(store, item, decisions, by, now, appliedSlugs = []) {
+    const decided = { ...(item.payload?.decided ?? {}), ...decisions };
+    // When each page's change reached the draft: what a follow-up measures from.
+    const appliedAt = {
+        ...(item.payload?.appliedAt ?? {}),
+        ...Object.fromEntries(appliedSlugs.map((slug) => [slug, now]))
+    };
+    const allSlugs = [...new Set(changesOf(item).map((c) => c.pageSlug))];
+    const done = allSlugs.every((slug) => decided[slug]);
+    const { status: _status, revision: _revision, updatedAt: _updatedAt, ...input } = item;
+    await store.putInboxItem({ ...input, payload: { ...item.payload, decided, appliedAt } });
+    if (!done)
+        return false;
+    const values = Object.values(decided);
+    const resolution = values.every((d) => d === "approved") ? "approved" : values.every((d) => d === "rejected") ? "rejected" : "partly_approved";
+    await store.resolveInboxItem(item.id, { resolution, ...(by ? { resolvedBy: by } : {}), at: now });
+    const proposalId = item.payload?.proposalId;
+    if (typeof proposalId === "string")
+        await store.setProposalStatus(proposalId, resolution === "rejected" ? "discarded" : "approved", now);
+    return true;
+}
+/**
+ * Apply a proposal's changes, for every page or for `slugs` only.
+ *
+ * Each page applies atomically on its own: one page's refusal does not undo
+ * another's success, and the outcome says which is which.
+ */
+export async function approveAgentProposal(args) {
+    const now = args.now ?? Date.now;
+    const item = await openProposal(args.store, args.inboxItemId);
+    if (item.scopeKey !== args.scopeKey)
+        throw new Error(`no proposal ${args.inboxItemId}`);
+    const decided = item.payload?.decided ?? {};
+    const byPage = new Map();
+    for (const change of changesOf(item)) {
+        if (decided[change.pageSlug])
+            continue;
+        if (args.slugs && !args.slugs.includes(change.pageSlug))
+            continue;
+        byPage.set(change.pageSlug, [...(byPage.get(change.pageSlug) ?? []), change]);
+    }
+    const applied = await applyChangeSet({
+        scopeKey: args.scopeKey,
+        changes: [...byPage.values()].flat(),
+        actor: { kind: "agent", id: item.agent },
+        summary: `Approved ${item.agent}'s proposal: ${item.title}${args.by ? ` (by ${args.by})` : ""}`,
+        ...(args.log ? { log: args.log } : {})
+    });
+    const outcome = {
+        applied: applied.applied,
+        stale: applied.stale,
+        failed: [...applied.failed, ...applied.missing.map((slug) => ({ slug, error: "the page no longer exists" }))],
+        rejected: [],
+        closed: false,
+        ...(applied.previewVersion !== undefined ? { previewVersion: applied.previewVersion } : {})
+    };
+    // A page that is gone is decided as rejected; every other page asked about is approved, stale fields and all.
+    const decisions = Object.fromEntries([...byPage.keys()].map((slug) => [slug, applied.missing.includes(slug) ? "rejected" : "approved"]));
+    outcome.closed = await recordDecisions(args.store, item, decisions, args.by, now(), outcome.applied.map((a) => a.slug));
+    return outcome;
+}
+export async function rejectAgentProposal(args) {
+    const now = args.now ?? Date.now;
+    const item = await openProposal(args.store, args.inboxItemId);
+    if (item.scopeKey !== args.scopeKey)
+        throw new Error(`no proposal ${args.inboxItemId}`);
+    const decided = item.payload?.decided ?? {};
+    const slugs = [...new Set(changesOf(item).map((c) => c.pageSlug))].filter((slug) => !decided[slug] && (!args.slugs || args.slugs.includes(slug)));
+    const decisions = Object.fromEntries(slugs.map((slug) => [slug, "rejected"]));
+    const closed = await recordDecisions(args.store, item, decisions, args.by, now());
+    if (closed && args.note) {
+        await args.store.resolveInboxItem(item.id, { resolution: "rejected", note: args.note, ...(args.by ? { resolvedBy: args.by } : {}) });
+    }
+    return { applied: [], stale: [], failed: [], rejected: slugs, closed };
+}
+/**
+ * The owner answered an agent's question: close it, resume the run, and keep the
+ * answer as a site fact when they asked for that.
+ */
+export async function answerAgentQuestion(args) {
+    const now = args.now ?? Date.now;
+    const answer = args.answer.trim();
+    if (!answer)
+        throw new Error("an answer is required");
+    const item = await args.store.getInboxItem(args.inboxItemId);
+    if (!item || item.kind !== "question" || item.scopeKey !== args.scopeKey)
+        throw new Error(`no question ${args.inboxItemId}`);
+    if (item.status !== "open")
+        throw new Error("this question is already closed");
+    const runId = String(item.payload?.runId ?? "");
+    const resumed = await answerRun({ store: args.store, now }, runId, answer);
+    await args.store.resolveInboxItem(item.id, {
+        resolution: "answered",
+        note: answer,
+        ...(args.by ? { resolvedBy: args.by } : {}),
+        at: now()
+    });
+    if (args.remember?.key) {
+        await args.store.putMemory({
+            scope: "site",
+            scopeKey: args.scopeKey,
+            kind: "fact",
+            key: args.remember.key,
+            value: answer,
+            source: "user",
+            sourceRef: item.id,
+            confidence: 1
+        }, now());
+    }
+    return { resumed, runId };
+}
+/**
+ * Questions older than their expiry close, and their runs stop: a run that has
+ * waited a week on an answer is acting on a week-old picture of the site.
+ */
+export async function expireAgentQuestions(args) {
+    const now = (args.now ?? Date.now)();
+    const open = await args.store.listInboxItems({ scopeKey: args.scopeKey, kind: "question", status: "open" });
+    let expired = 0;
+    for (const item of open) {
+        const expiresAt = Number(item.payload?.expiresAt ?? Number.POSITIVE_INFINITY);
+        if (expiresAt > now)
+            continue;
+        await args.store.resolveInboxItem(item.id, { resolution: "expired", at: now });
+        const runId = item.payload?.runId;
+        if (typeof runId === "string")
+            await stopRun({ store: args.store, now: () => now }, runId, "question_expired");
+        expired += 1;
+    }
+    return expired;
+}

package/dist/agents/runtime/definition.d.ts

@@ -0,0 +1,88 @@
+import type { DurableStore } from "../../durable/types.ts";
+export type AgentTier = "fast" | "balanced" | "reasoning";
+export type AgentBudget = {
+    /** Stop a run once it has spent this much. */
+    usdPerRun: number;
+    /** Stop starting steps once the agent has spent this much in a site this calendar month (UTC). */
+    usdPerMonth: number;
+};
+/** Decided 2026-10-03: per agent, per site; overridable per agent. */
+export declare const DEFAULT_AGENT_BUDGET: AgentBudget;
+/** A run that keeps calling tools without converging is stopped, not paid for. */
+export declare const DEFAULT_MAX_STEPS = 25;
+/**
+ * Output tokens a step may use; only what is used is paid for. 4096 was too
+ * few: on real content Sonnet 5.5 spent all of it thinking about a large
+ * proposal and never wrote one. A step that still hits its cap is retried with
+ * double, up to `MAX_TOKENS_CEILING` (see engine.ts).
+ */
+export declare const DEFAULT_MAX_TOKENS_PER_STEP = 8192;
+export declare const MAX_TOKENS_CEILING = 32768;
+export type ToolContext = {
+    runId: string;
+    scopeKey: string;
+    agentId: string;
+    store: DurableStore;
+    now: () => number;
+};
+export type ToolOutcome = 
+/**
+ * `trace` is the one line the run page shows; `result` is what the model
+ * reads, and `images` what it sees beside it (base64, a type Claude reads).
+ */
+{
+    result: string;
+    isError?: boolean;
+    trace?: string;
+    images?: Array<{
+        mediaType: "image/jpeg" | "image/png" | "image/webp" | "image/gif";
+        data: string;
+    }>;
+}
+/** The run pauses until the owner answers this Inbox item (the `ask` tool). */
+ | {
+    waitFor: {
+        inboxItemId: string;
+    };
+    trace?: string;
+};
+/**
+ * What calling a tool does, which is what a permission is about (assistant
+ * concept §3). `apply` changes the draft at once, and is given only to the
+ * chat assistant, where the person who asked is the approval. `outbound` sends something off the site — an email, a message,
+ * a write to someone else's system — and is the one the lethal-trifecta rule
+ * guards: once a run has read untrusted content, it is refused.
+ */
+export type ToolEffect = "read" | "propose" | "apply" | "ask" | "remember" | "report" | "outbound";
+export type RuntimeTool = {
+    name: string;
+    /** Defaults to "read". */
+    effect?: ToolEffect;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    run: (input: Record<string, unknown>, ctx: ToolContext) => Promise<ToolOutcome>;
+};
+export type AgentDefinition = {
+    id: string;
+    /** One line, in the owner's language: what it is for. */
+    job: string;
+    /** The system prompt, after the preamble. */
+    instructions: string;
+    /** Replaces the runtime's default preamble: the chat assistant talks to a person, not to an Inbox. */
+    preamble?: string;
+    tools: RuntimeTool[];
+    tier: AgentTier;
+    budget: AgentBudget;
+    maxSteps?: number;
+    maxTokensPerStep?: number;
+    /**
+     * Tools that close a run: a step that calls only these, beside its text,
+     * runs them and finishes with that text, without another model call. The
+     * chat assistant's next_steps is one: it goes with the answer.
+     */
+    finishOn?: string[];
+};

package/dist/agents/runtime/definition.js

@@ -0,0 +1,12 @@
+/** Decided 2026-10-03: per agent, per site; overridable per agent. */
+export const DEFAULT_AGENT_BUDGET = { usdPerRun: 0.5, usdPerMonth: 20 };
+/** A run that keeps calling tools without converging is stopped, not paid for. */
+export const DEFAULT_MAX_STEPS = 25;
+/**
+ * Output tokens a step may use; only what is used is paid for. 4096 was too
+ * few: on real content Sonnet 5.5 spent all of it thinking about a large
+ * proposal and never wrote one. A step that still hits its cap is retried with
+ * double, up to `MAX_TOKENS_CEILING` (see engine.ts).
+ */
+export const DEFAULT_MAX_TOKENS_PER_STEP = 8192;
+export const MAX_TOKENS_CEILING = 32_768;

package/dist/agents/runtime/engine.d.ts

@@ -0,0 +1,88 @@
+import type Anthropic from "@anthropic-ai/sdk";
+import type { AgentRunRecord, DurableStore, RunStepRecord, RunStepToolCall } from "../../durable/types.ts";
+import type { Logger } from "../../logger.ts";
+import { type AgentDefinition } from "./definition.ts";
+import { type AgentModel } from "./model.ts";
+export type RuntimeDeps = {
+    store: DurableStore;
+    model: AgentModel;
+    /** Defaults to the planner's tier defaults. Tests pin it. */
+    modelForTier?: (tier: AgentDefinition["tier"]) => string;
+    now?: () => number;
+    log?: Logger;
+};
+export type StepOutcome = {
+    status: "continue";
+} | {
+    status: "waiting";
+    inboxItemId: string;
+} | {
+    status: "done";
+    summary: string;
+} | {
+    status: "stopped";
+    reason: string;
+}
+/** The model call failed. The run is left as it was; the next slice tries again. */
+ | {
+    status: "error";
+    message: string;
+};
+/** Midnight UTC on the first of `now`'s month: the start of the monthly budget. */
+export declare function startOfMonthUtc(now: number): number;
+/** The conversation a run has had so far, rebuilt from its steps. */
+export declare function transcriptOf(run: Pick<AgentRunRecord, "input">, steps: RunStepRecord[]): Anthropic.Messages.MessageParam[];
+export declare function startAgentRun(deps: RuntimeDeps, definition: AgentDefinition, args: {
+    scopeKey: string;
+    trigger: string;
+    input: string;
+    idempotencyKey?: string;
+}): Promise<AgentRunRecord>;
+export declare const OUTBOUND_REFUSED = "Refused: this run has read site or connector content, so it may not send anything off the site on its own. Describe what you would send in your summary; the owner decides.";
+/**
+ * The lethal-trifecta rule (assistant concept §3). A run that holds private
+ * data, has read content a stranger could have written, and can send data out
+ * can be steered into leaking it. Every read tool returns such content (pages,
+ * search queries, connector rows), so once any read has happened in a run, an
+ * outbound tool is refused, whatever the site's permissions say. Enforced here,
+ * not in a prompt, because the prompt is exactly what an injection rewrites.
+ */
+export declare function readsUntrusted(definition: AgentDefinition, steps: RunStepRecord[], current: RunStepToolCall[]): boolean;
+/** Advance a run by one step. Callers hold its lease (see `driveRun`). */
+export declare function stepRun(deps: RuntimeDeps, definition: AgentDefinition, runId: string): Promise<StepOutcome>;
+/**
+ * The owner answered: give the waiting step its missing tool result and let the
+ * run continue. Answering twice, or a run that is not waiting, changes nothing.
+ */
+/** What answering and stopping need: no model is called. */
+export type StoreDeps = Pick<RuntimeDeps, "store" | "now">;
+export declare function answerRun(deps: StoreDeps, runId: string, answer: string): Promise<boolean>;
+/** Stop a run from outside it: an expired question, a person pressing Stop. */
+export declare function stopRun(deps: StoreDeps, runId: string, reason: string): Promise<void>;
+export type DriveOptions = {
+    /** Who is driving, for the lease: a process id, a request id. */
+    owner: string;
+    /** Stop starting new steps after this long; a later slice continues. */
+    sliceMs?: number;
+    /** How long the lease holds without renewal. Renewed before every step. */
+    leaseMs?: number;
+};
+export type DriveResult = {
+    status: "busy";
+} | {
+    status: "continue";
+    steps: number;
+} | Exclude<StepOutcome, {
+    status: "continue";
+}> & {
+    steps: number;
+};
+/**
+ * Advance a run for one time slice under its lease.
+ *
+ * A long-lived process calls this until the run settles; a serverless host
+ * calls it once per invocation (`waitUntil`, a tick) and the next call picks up
+ * from `run_steps`. The lease is what stops two processes, or a tick and a
+ * request, from stepping the same run at once.
+ */
+export declare function driveRun(deps: RuntimeDeps, definition: AgentDefinition, runId: string, options: DriveOptions): Promise<DriveResult>;