@toren-run/core 0.1.0

package/dist/loop.js

@@ -0,0 +1,413 @@
+import { canonicalDigest } from "./digest.js";
+import { effectiveEvents } from "./fold.js";
+import { ev } from "./events.js";
+import { needsApproval, toolSpecs } from "./tools.js";
+import { withSpan } from "./tracing.js";
+export class TaskLeaseLostError extends Error {
+}
+/**
+ * Thrown instead of appending yet another StreamInvalidated when a stream has
+ * been invalidated repeatedly in a short window — the signature of two worker
+ * versions fighting over one stream during a rolling deploy, each re-paying
+ * the other's voided model calls. The worker defers the message instead; the
+ * war starves until one version drains, and a legitimate re-edit waits out
+ * the window at worst.
+ */
+export class InvalidationStormError extends Error {
+}
+export const INVALIDATION_STORM_LIMIT = 3;
+export const INVALIDATION_STORM_WINDOW_MS = 5 * 60 * 1000;
+/** Provider defaults; agent.yaml `contextWindow:` overrides. mock/ gets none, so tests never compact by surprise. */
+export function defaultContextWindow(model) {
+    if (model.startsWith("anthropic/"))
+        return 200_000;
+    if (model.startsWith("openai/"))
+        return 128_000;
+    return undefined;
+}
+// ---- context compaction constants. Changing these mid-run invalidates in-flight
+// suffixes (same contract as changing a prompt); recorded compactions replay by value.
+export const COMPACT_ELIDE_AT = 0.5; // of contextWindow: replace old tool results with stubs
+export const COMPACT_SUMMARY_AT = 0.78; // of contextWindow: fold history into a recorded summary
+export const COMPACT_KEEP_RESULTS = 3; // most recent tool results always kept verbatim
+export const COMPACT_KEEP_TAIL = 6; // minimum recent messages kept verbatim through a summary fold
+export const COMPACT_MIN_ELIDE_CHARS = 500; // tool results smaller than this are never elided
+export const COMPACT_SUMMARY_MAX_TOKENS = 2048;
+const ELIDE_MARK = "[elided:";
+export const SUMMARIZE_SYSTEM = "You compress an agent conversation so the agent can continue it in less space. " +
+    "Write a summary that preserves, in this order: (1) the original task or request, quoted; " +
+    "(2) every user message so far, enumerated verbatim; (3) decisions made and constraints discovered; " +
+    "(4) facts, numbers, names, and URLs learned from tools that are still needed; " +
+    "(5) current state of the work; (6) the immediate next step. " +
+    "Be dense and specific. Output only the summary text.";
+// Events the loop itself emits in execution order; replay walks these.
+const WALK_TYPES = new Set([
+    "LlmCallStarted", "LlmCallCompleted",
+    "ToolCallStarted", "ToolCallCompleted",
+    "ApprovalRequested", "TaskCompleted",
+    "InputRequested", "UserMessage",
+    "ContextCompacted",
+]);
+/** Layered onto the system prompt in session mode; constant, so replay digests stay stable. */
+export const SESSION_PREAMBLE = "\n\nYou are in an interactive session with a user. Answer their current message directly; " +
+    "ask a clarifying question when the request is ambiguous. Keep responses conversational and " +
+    "sized to the question — the user can always ask for more.";
+export async function runTaskLoop(args) {
+    return withSpan("toren.task", { "toren.run_id": args.runId, "toren.task_id": args.taskId }, () => runTaskLoopImpl(args));
+}
+async function runTaskLoopImpl(args) {
+    const { store, provider, runId, taskId, agent } = args;
+    const streamId = `task:${taskId}`;
+    const raw = await store.read(runId, streamId);
+    let head = raw.at(-1)?.seq ?? 0;
+    const eff = effectiveEvents(raw);
+    const terminalFailure = eff.find((e) => e.type === "TaskFailed" && !e.payload.willRetry);
+    if (terminalFailure)
+        return { status: "failed", error: String(terminalFailure.payload.error ?? "") };
+    const resolutions = new Map();
+    for (const e of eff) {
+        if (e.type === "ApprovalResolved") {
+            resolutions.set(String(e.payload.stepId), {
+                granted: Boolean(e.payload.granted),
+                by: e.payload.by,
+                comment: e.payload.comment,
+            });
+        }
+    }
+    const walk = eff.filter((e) => WALK_TYPES.has(e.type));
+    let ptr = 0;
+    let invalidated = false;
+    const peek = () => (invalidated || ptr >= walk.length ? undefined : walk[ptr]);
+    async function append(events) {
+        const r = await store.append(runId, streamId, head, events);
+        if (!r.ok)
+            throw new TaskLeaseLostError(`stream advanced concurrently (expected ${head}, actual ${r.actualSeq})`);
+        head = r.lastSeq;
+    }
+    const recentInvalidations = raw.filter((e) => e.type === "StreamInvalidated" && Date.now() - e.recordedAt.getTime() < INVALIDATION_STORM_WINDOW_MS).length;
+    async function invalidateFrom(fromSeq, reason) {
+        if (recentInvalidations >= INVALIDATION_STORM_LIMIT) {
+            throw new InvalidationStormError(`invalidation storm: ${recentInvalidations} invalidations on ${streamId} in the last 5m — deferring instead of re-paying (likely mixed worker versions mid-deploy); latest cause: ${reason}`);
+        }
+        await append([ev("StreamInvalidated", { fromSeq, reason })]);
+        invalidated = true;
+    }
+    const attempt = raw.filter((e) => e.type === "TaskStarted").length + 1;
+    await append([ev("TaskStarted", { attempt })]);
+    const messages = [{ role: "user", content: [{ type: "text", text: args.input }] }];
+    const specs = toolSpecs(agent.tools);
+    const system = args.sessionMode ? agent.system + SESSION_PREAMBLE : agent.system;
+    let steps = 0;
+    // ---- context pressure: exact usage from the previous model call plus a
+    // chars/3 bound on what we appended since. Deterministic on replay because
+    // usage rides in LlmCallCompleted and appends are reconstructed identically.
+    const contextWindow = agent.contextWindow ?? defaultContextWindow(agent.model);
+    let lastUsage;
+    let pendingChars = 0;
+    let elidedSavingsTokens = 0;
+    const pressure = () => lastUsage ? lastUsage.inputTokens + lastUsage.outputTokens + Math.ceil(pendingChars / 3) - elidedSavingsTokens : 0;
+    /** The record/replay dance for one model call; identical semantics for the main loop and summarization. */
+    async function recordedLlmCall(request) {
+        const digest = canonicalDigest(request);
+        let next = peek();
+        if (next?.type === "ContextCompacted") {
+            // A recorded compaction the live code no longer performs here: stale suffix.
+            await invalidateFrom(next.seq, "compaction decision changed (code or thresholds)");
+            next = peek();
+        }
+        if (next?.type === "LlmCallStarted" && next.payload.requestDigest !== digest) {
+            await invalidateFrom(next.seq, "request digest mismatch (prompt or code changed)");
+            next = peek();
+        }
+        let response;
+        if (next?.type === "LlmCallStarted") {
+            const completed = walk[ptr + 1];
+            if (completed?.type === "LlmCallCompleted" && completed.payload.stepId === next.payload.stepId) {
+                response = completed.payload.response; // replayed — zero tokens spent
+                ptr += 2;
+            }
+            else {
+                // Crash window: call was issued but the response never landed. Re-issue (at-least-once).
+                ptr += 1;
+                response = await withSpan("toren.llm", { "gen_ai.request.model": request.model }, () => provider.complete(request));
+                await append([ev("LlmCallCompleted", { stepId: next.payload.stepId, response, usage: response.usage })]);
+            }
+        }
+        else {
+            const stepId = `s${head + 1}`;
+            await append([ev("LlmCallStarted", { stepId, requestDigest: digest, model: request.model })]);
+            response = await withSpan("toren.llm", { "gen_ai.request.model": request.model }, () => provider.complete(request));
+            await append([ev("LlmCallCompleted", { stepId, response, usage: response.usage })]);
+        }
+        if (response.usage) {
+            lastUsage = response.usage;
+            pendingChars = 0;
+            elidedSavingsTokens = 0;
+        }
+        return response;
+    }
+    /** Old, large tool results not among the last COMPACT_KEEP_RESULTS and not already stubbed. */
+    function elidableTargets() {
+        const hits = [];
+        for (const m of messages) {
+            if (m.role !== "user")
+                continue;
+            for (const b of m.content) {
+                if (b.type === "toolResult" && typeof b.content === "string"
+                    && b.content.length >= COMPACT_MIN_ELIDE_CHARS && !b.content.startsWith(ELIDE_MARK)) {
+                    hits.push({ id: b.toolUseId, chars: b.content.length });
+                }
+            }
+        }
+        return hits.slice(0, Math.max(0, hits.length - COMPACT_KEEP_RESULTS)).map((h) => h.id);
+    }
+    function toolNameFor(toolUseId) {
+        for (const m of messages) {
+            if (m.role !== "assistant")
+                continue;
+            for (const b of m.content)
+                if (b.type === "toolUse" && b.id === toolUseId)
+                    return b.name;
+        }
+        return "the tool";
+    }
+    function applyElide(toolUseIds) {
+        const ids = new Set(Array.isArray(toolUseIds) ? toolUseIds.map(String) : []);
+        for (const m of messages) {
+            if (m.role !== "user")
+                continue;
+            m.content = m.content.map((b) => {
+                if (b.type !== "toolResult" || !ids.has(b.toolUseId) || typeof b.content !== "string")
+                    return b;
+                const name = toolNameFor(b.toolUseId);
+                elidedSavingsTokens += Math.floor(b.content.length / 3);
+                return {
+                    ...b,
+                    content: `${ELIDE_MARK} earlier ${name} result removed to save context. The full output is preserved in the run's event log; call ${name} again if you need it.]`,
+                };
+            });
+        }
+    }
+    /** Largest boundary landing on an assistant message, keeping at least COMPACT_KEEP_TAIL recent messages. */
+    function summaryBoundary() {
+        for (let b = messages.length - COMPACT_KEEP_TAIL; b >= 1; b--) {
+            if (messages[b].role === "assistant")
+                return b;
+        }
+        return 0;
+    }
+    function applySummary(payload) {
+        const keepFrom = Number(payload.keepFrom);
+        const summary = String(payload.summary ?? "");
+        messages.splice(0, keepFrom, {
+            role: "user",
+            content: [{
+                    type: "text",
+                    text: `[The earlier conversation was compacted to save context. Summary of everything before this point:]\n\n${summary}\n\n[Continue the task from here. The recent messages below are verbatim.]`,
+                }],
+        });
+    }
+    /**
+     * Compaction pass, run before each model call. Both tiers are recorded events:
+     * replay applies the recorded payload by value, so the fold is a pure function
+     * of the log and survives prompt, threshold, and code changes.
+     */
+    async function maybeCompact() {
+        if (!contextWindow || !lastUsage || invalidated)
+            return;
+        if (pressure() >= COMPACT_ELIDE_AT * contextWindow) {
+            const targets = elidableTargets();
+            if (targets.length > 0) {
+                const next = peek();
+                if (next?.type === "ContextCompacted" && next.payload.kind === "elide") {
+                    ptr += 1;
+                    applyElide(next.payload.toolUseIds);
+                }
+                else {
+                    // A differing recorded suffix (older code compacted differently) is
+                    // voided first; the append then lands after the StreamInvalidated cut.
+                    if (next)
+                        await invalidateFrom(next.seq, "compaction decision changed (code or thresholds)");
+                    await append([ev("ContextCompacted", { kind: "elide", toolUseIds: targets })]);
+                    applyElide(targets);
+                }
+            }
+        }
+        if (pressure() >= COMPACT_SUMMARY_AT * contextWindow) {
+            const keepFrom = summaryBoundary();
+            if (keepFrom <= 1)
+                return; // nothing worth folding
+            const sumRequest = {
+                model: agent.model,
+                system: SUMMARIZE_SYSTEM,
+                messages: messages.slice(0, keepFrom),
+                tools: specs,
+                maxTokens: COMPACT_SUMMARY_MAX_TOKENS,
+            };
+            const sumResponse = await recordedLlmCall(sumRequest);
+            const summary = sumResponse.content
+                .filter((b) => b.type === "text")
+                .map((b) => b.text).join("\n");
+            const next = peek();
+            if (next?.type === "ContextCompacted" && next.payload.kind === "summary") {
+                ptr += 1;
+                applySummary(next.payload);
+            }
+            else {
+                if (next)
+                    await invalidateFrom(next.seq, "compaction decision changed (code or thresholds)");
+                await append([ev("ContextCompacted", { kind: "summary", keepFrom, summary })]);
+                applySummary({ keepFrom, summary });
+            }
+            // The summary replaces the history the trigger measured; usage resets on the next call.
+            lastUsage = undefined;
+        }
+    }
+    async function runHandlerAndComplete(def, tu, stepId) {
+        let result;
+        let isError = false;
+        try {
+            const parsed = def.input.parse(tu.input);
+            result = await withSpan("toren.tool", { "toren.tool.name": def.name, "toren.tool.effects": def.effects }, () => def.handler(parsed, { runId, taskId, toolUseId: tu.id, env: agent.env ?? {}, files: args.files, sandbox: args.sandbox, processes: args.processes }));
+        }
+        catch (e) {
+            result = `tool error: ${e instanceof Error ? e.message : String(e)}`;
+            isError = true;
+        }
+        await append([ev("ToolCallCompleted", { stepId, toolUseId: tu.id, result, isError })]);
+        return { type: "toolResult", toolUseId: tu.id, content: result, ...(isError ? { isError } : {}) };
+    }
+    // Replays a recorded execution of this toolUse if the walk holds one; null = nothing recorded.
+    async function replayRecordedTool(def, tu) {
+        const next = peek();
+        if (next?.type !== "ToolCallStarted" || next.payload.toolUseId !== tu.id)
+            return null;
+        const completed = walk[ptr + 1];
+        if (completed?.type === "ToolCallCompleted" && completed.payload.toolUseId === tu.id) {
+            ptr += 2;
+            const isError = Boolean(completed.payload.isError);
+            return { type: "toolResult", toolUseId: tu.id, content: String(completed.payload.result ?? ""), ...(isError ? { isError } : {}) };
+        }
+        // Crash window: started, never completed. Keyed tools re-run under the same
+        // idempotency key (effectively-once downstream); unkeyed tools are documented at-least-once.
+        ptr += 1;
+        return runHandlerAndComplete(def, tu, String(next.payload.stepId));
+    }
+    async function executeToolLive(def, tu) {
+        const recorded = await replayRecordedTool(def, tu);
+        if (recorded)
+            return recorded;
+        const stepId = `s${head + 1}`;
+        const idempotencyKey = canonicalDigest({ runId, taskId, stepId, tool: def.name, args: tu.input });
+        await append([ev("ToolCallStarted", { stepId, toolUseId: tu.id, tool: def.name, args: tu.input, idempotencyKey, effects: def.effects })]);
+        return runHandlerAndComplete(def, tu, stepId);
+    }
+    async function execTool(tu) {
+        const def = agent.tools.find((t) => t.name === tu.name);
+        if (!def)
+            return { type: "toolResult", toolUseId: tu.id, content: `unknown tool: ${tu.name}`, isError: true };
+        const next = peek();
+        if (next?.type === "ApprovalRequested" && next.payload.toolUseId === tu.id) {
+            ptr += 1;
+            const res = resolutions.get(String(next.payload.stepId));
+            if (!res)
+                return "PARKED"; // still parked; the recorded request stands
+            if (!res.granted) {
+                return {
+                    type: "toolResult", toolUseId: tu.id, isError: true,
+                    content: `denied by ${res.by ?? "operator"}${res.comment ? `: ${res.comment}` : ""}`,
+                };
+            }
+            return executeToolLive(def, tu);
+        }
+        const recorded = await replayRecordedTool(def, tu);
+        if (recorded)
+            return recorded;
+        if (needsApproval(def, tu.input)) {
+            const stepId = `s${head + 1}`;
+            await append([ev("ApprovalRequested", { stepId, toolUseId: tu.id, tool: tu.name, args: tu.input })]);
+            return "PARKED";
+        }
+        return executeToolLive(def, tu);
+    }
+    while (true) {
+        if (++steps > agent.maxSteps) {
+            const error = "maxSteps exceeded";
+            await append([ev("TaskFailed", { error, willRetry: false })]);
+            return { status: "failed", error };
+        }
+        await maybeCompact();
+        const request = { model: agent.model, system, messages: [...messages], tools: specs, maxTokens: agent.maxTokens };
+        const response = await recordedLlmCall(request);
+        messages.push({ role: "assistant", content: response.content });
+        if (response.stopReason === "toolUse") {
+            const toolUses = response.content.filter((b) => b.type === "toolUse");
+            const results = [];
+            for (const tu of toolUses) {
+                const r = await execTool(tu);
+                if (r === "PARKED")
+                    return { status: "waitingApproval" };
+                results.push(r);
+            }
+            messages.push({ role: "user", content: results });
+            pendingChars += JSON.stringify(results).length;
+            continue;
+        }
+        if (response.stopReason === "refusal") {
+            const error = "model refused the request";
+            await append([ev("TaskFailed", { error, willRetry: false })]);
+            return { status: "failed", error };
+        }
+        // endTurn / maxTokens → final output
+        const text = response.content
+            .filter((b) => b.type === "text")
+            .map((b) => b.text).join("\n");
+        if (args.sessionMode) {
+            // Turn boundary: park awaiting the user (or consume their recorded reply and go again).
+            const recInput = peek();
+            if (recInput?.type === "InputRequested") {
+                ptr += 1;
+            }
+            else {
+                await append([ev("InputRequested", { text })]);
+                return { status: "awaitingInput" };
+            }
+            const userMsg = peek();
+            if (userMsg?.type !== "UserMessage")
+                return { status: "awaitingInput" };
+            ptr += 1;
+            if (userMsg.payload.close) {
+                const recordedClose = peek();
+                if (recordedClose?.type === "TaskCompleted") {
+                    ptr += 1;
+                    return { status: "completed", output: String(recordedClose.payload.result ?? "") };
+                }
+                await append([ev("TaskCompleted", { result: text })]);
+                return { status: "completed", output: text };
+            }
+            messages.push({ role: "user", content: [{ type: "text", text: String(userMsg.payload.text ?? "") }] });
+            pendingChars += String(userMsg.payload.text ?? "").length;
+            steps = 0; // each user turn gets a fresh step budget
+            continue;
+        }
+        if (agent.outputSchema) {
+            try {
+                agent.outputSchema.parse(JSON.parse(text));
+            }
+            catch (e) {
+                messages.push({
+                    role: "user",
+                    content: [{ type: "text", text: `Your final answer failed output validation: ${e instanceof Error ? e.message : String(e)}. Reply with a corrected final answer only.` }],
+                });
+                continue;
+            }
+        }
+        const recordedDone = peek();
+        if (recordedDone?.type === "TaskCompleted") {
+            ptr += 1;
+            return { status: "completed", output: String(recordedDone.payload.result ?? "") };
+        }
+        await append([ev("TaskCompleted", { result: text })]);
+        return { status: "completed", output: text };
+    }
+}

package/dist/migrate.d.ts

@@ -0,0 +1,4 @@
+import type pg from "pg";
+export declare function migrateControl(c: pg.PoolClient): Promise<void>;
+export declare function agentSchemaName(agent: string): string;
+export declare function provisionAgent(c: pg.PoolClient, agent: string): Promise<string>;

package/dist/migrate.js

@@ -0,0 +1,167 @@
+const CONTROL_SQL = `
+CREATE SCHEMA IF NOT EXISTS toren_control;
+CREATE TABLE IF NOT EXISTS toren_control.agents (
+  name text PRIMARY KEY,
+  schema_name text NOT NULL UNIQUE,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS toren_control.queue_messages (
+  id bigserial PRIMARY KEY,
+  queue text NOT NULL,
+  payload jsonb NOT NULL,
+  dedupe_key text,
+  visible_at timestamptz NOT NULL DEFAULT now(),
+  locked_until timestamptz,
+  attempts int NOT NULL DEFAULT 0,
+  max_attempts int NOT NULL DEFAULT 5,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS queue_visible_idx ON toren_control.queue_messages (queue, visible_at) WHERE locked_until IS NULL;
+CREATE TABLE IF NOT EXISTS toren_control.dead_letters (
+  id bigint PRIMARY KEY,
+  queue text NOT NULL,
+  payload jsonb NOT NULL,
+  attempts int NOT NULL,
+  failed_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS toren_control.schedules (
+  id uuid PRIMARY KEY,
+  agent text NOT NULL,
+  name text NOT NULL,
+  cron text NOT NULL,
+  tz text NOT NULL DEFAULT 'UTC',
+  input text NOT NULL,
+  process text NOT NULL DEFAULT 'main',
+  enabled boolean NOT NULL DEFAULT true,
+  next_fire_at timestamptz NOT NULL,
+  last_fired_at timestamptz,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+ALTER TABLE toren_control.schedules ADD COLUMN IF NOT EXISTS process text NOT NULL DEFAULT 'main';
+CREATE INDEX IF NOT EXISTS schedules_due_idx ON toren_control.schedules (next_fire_at) WHERE enabled;
+CREATE TABLE IF NOT EXISTS toren_control.schedule_fires (
+  schedule_id uuid NOT NULL,
+  scheduled_for timestamptz NOT NULL,
+  run_id uuid NOT NULL,
+  agent text NOT NULL,
+  input text NOT NULL,
+  process text NOT NULL DEFAULT 'main',
+  fired_at timestamptz NOT NULL DEFAULT now(),
+  settled boolean NOT NULL DEFAULT false,
+  PRIMARY KEY (schedule_id, scheduled_for)
+);
+ALTER TABLE toren_control.schedule_fires ADD COLUMN IF NOT EXISTS process text NOT NULL DEFAULT 'main';
+CREATE INDEX IF NOT EXISTS schedule_fires_open_idx ON toren_control.schedule_fires (agent) WHERE NOT settled;
+CREATE TABLE IF NOT EXISTS toren_control.api_keys (
+  id uuid PRIMARY KEY,
+  name text NOT NULL,
+  key_hash text NOT NULL UNIQUE,
+  prefix text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  revoked_at timestamptz,
+  last_used_at timestamptz
+);
+CREATE TABLE IF NOT EXISTS toren_control.telegram_users (
+  user_id bigint PRIMARY KEY,
+  paired_at timestamptz NOT NULL DEFAULT now(),
+  via_code text
+);
+CREATE TABLE IF NOT EXISTS toren_control.telegram_invites (
+  code text PRIMARY KEY,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  used_by bigint
+);
+CREATE TABLE IF NOT EXISTS toren_control.telegram_bindings (
+  chat_id bigint PRIMARY KEY,
+  agent text NOT NULL,
+  run_id uuid,
+  last_delivered_seq int NOT NULL DEFAULT 0,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS toren_control.telegram_state (
+  id int PRIMARY KEY DEFAULT 1,
+  last_update_id bigint NOT NULL DEFAULT 0
+);
+CREATE TABLE IF NOT EXISTS toren_control.files (
+  id text PRIMARY KEY,
+  name text NOT NULL,
+  media_type text NOT NULL,
+  bytes int NOT NULL,
+  pages jsonb NOT NULL,
+  data bytea,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS toren_control.run_watchers (
+  child_run_id uuid PRIMARY KEY,
+  parent_run_id uuid NOT NULL,
+  agent text NOT NULL,
+  process text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  settled boolean NOT NULL DEFAULT false
+);
+CREATE INDEX IF NOT EXISTS run_watchers_open_idx ON toren_control.run_watchers (agent) WHERE NOT settled;
+CREATE TABLE IF NOT EXISTS toren_control.sandboxes (
+  run_id uuid PRIMARY KEY,
+  provider text NOT NULL,
+  sandbox_id text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  last_used_at timestamptz NOT NULL DEFAULT now()
+);
+`;
+const AGENT_TABLES_SQL = (s) => `
+CREATE SCHEMA IF NOT EXISTS ${s};
+CREATE TABLE IF NOT EXISTS ${s}.runs (
+  run_id uuid PRIMARY KEY,
+  agent text NOT NULL,
+  status text NOT NULL DEFAULT 'created',
+  input jsonb, output jsonb, error jsonb,
+  code_hash text, trace_context jsonb,
+  mode text NOT NULL DEFAULT 'task',
+  process text NOT NULL DEFAULT 'main',
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+ALTER TABLE ${s}.runs ADD COLUMN IF NOT EXISTS mode text NOT NULL DEFAULT 'task';
+ALTER TABLE ${s}.runs ADD COLUMN IF NOT EXISTS process text NOT NULL DEFAULT 'main';
+CREATE TABLE IF NOT EXISTS ${s}.streams (
+  run_id uuid NOT NULL, stream_id text NOT NULL,
+  head_seq bigint NOT NULL DEFAULT 0,
+  PRIMARY KEY (run_id, stream_id)
+);
+CREATE TABLE IF NOT EXISTS ${s}.events (
+  run_id uuid NOT NULL, stream_id text NOT NULL, seq bigint NOT NULL,
+  type text NOT NULL, payload jsonb NOT NULL,
+  recorded_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (run_id, stream_id, seq)
+);
+CREATE TABLE IF NOT EXISTS ${s}.leases (
+  run_id uuid NOT NULL, stream_id text NOT NULL,
+  owner text NOT NULL, epoch bigint NOT NULL DEFAULT 1,
+  expires_at timestamptz NOT NULL,
+  PRIMARY KEY (run_id, stream_id)
+);
+CREATE TABLE IF NOT EXISTS ${s}.blobs (
+  run_id uuid NOT NULL, key text NOT NULL, data bytea NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (run_id, key)
+);
+`;
+const AGENT_NAME_RE = /^[a-z][a-z0-9_]{0,40}$/;
+// Concurrent booters (parallel workers, parallel test files) race CREATE IF NOT EXISTS;
+// a transaction-scoped advisory lock serializes DDL. 727001/727002 are arbitrary app-unique keys.
+export async function migrateControl(c) {
+    await c.query(`SELECT pg_advisory_xact_lock(727001)`);
+    await c.query(CONTROL_SQL);
+}
+export function agentSchemaName(agent) {
+    if (!AGENT_NAME_RE.test(agent))
+        throw new Error(`invalid agent name: ${agent}`);
+    return `agent_${agent}`;
+}
+export async function provisionAgent(c, agent) {
+    const schema = agentSchemaName(agent);
+    await c.query(`SELECT pg_advisory_xact_lock(727002)`);
+    await c.query(AGENT_TABLES_SQL(schema));
+    await c.query(`INSERT INTO toren_control.agents (name, schema_name) VALUES ($1, $2) ON CONFLICT (name) DO NOTHING`, [agent, schema]);
+    return schema;
+}

package/dist/model.d.ts

@@ -0,0 +1,42 @@
+export interface ToolSpec {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export type ContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "toolUse";
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: "toolResult";
+    toolUseId: string;
+    content: string;
+    isError?: boolean;
+};
+export interface ChatMessage {
+    role: "user" | "assistant";
+    content: ContentBlock[];
+}
+export interface ModelRequest {
+    model: string;
+    system: string;
+    messages: ChatMessage[];
+    tools: ToolSpec[];
+    maxTokens: number;
+}
+export type StopReason = "endTurn" | "toolUse" | "maxTokens" | "refusal";
+export interface ModelResponse {
+    content: ContentBlock[];
+    stopReason: StopReason;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+export interface ModelProvider {
+    complete(req: ModelRequest): Promise<ModelResponse>;
+}

package/dist/model.js

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

package/dist/orchestrator.d.ts

@@ -0,0 +1,35 @@
+import type { PgStateStore } from "./store.js";
+import type { QueueAdapter } from "./queue.js";
+import type { PgLeases } from "./leases.js";
+import type { ModelProvider } from "./model.js";
+import type { AgentSpec } from "./loop.js";
+import { type WorkflowFn } from "./workflow.js";
+export interface TickDeps {
+    store: PgStateStore;
+    queue: QueueAdapter;
+    leases: PgLeases;
+    provider: ModelProvider;
+    agents: Record<string, AgentSpec>;
+    /** Keyed by process name — an agent's named workflows ("main" is the single/default one). */
+    workflows: Record<string, WorkflowFn>;
+    /** Per-run sandbox provider; enables the bash builtin. */
+    sandbox?: import("./tools.js").SandboxProvider;
+    /** Deployment file store; enables the read_file builtin. */
+    files?: import("./files.js").PgFiles;
+    /** Background named-process runs; enables the run_process/check_run builtins. */
+    processes?: import("./tools.js").ProcessesCtx;
+}
+export type TickResult = "leased" | "terminal" | "blocked" | "completed" | "failed";
+export declare function startRun(deps: TickDeps, req: {
+    agent: string;
+    input: string;
+    process?: string;
+    runId?: string;
+    mode?: "task" | "session";
+}): Promise<string>;
+export declare function tick(deps: TickDeps, runId: string): Promise<TickResult>;
+/** Locates a planned task's spec by scanning the run stream (workers use this). */
+export declare function findTaskSpec(store: PgStateStore, runId: string, taskId: string): Promise<{
+    agentRef: string;
+    input: string;
+} | null>;