@toren-run/core 0.1.0

package/dist/conversations.d.ts

@@ -0,0 +1,38 @@
+import { type TickDeps } from "./orchestrator.js";
+import type { PgStateStore } from "./store.js";
+export type SessionState = "working" | "awaiting_input" | "completed" | "failed" | "cancelled";
+export interface SessionTurn {
+    role: "user" | "assistant";
+    text: string;
+    channel?: string;
+    seq: number;
+}
+export declare class SessionBusyError extends Error {
+    constructor();
+}
+export declare function startSession(deps: TickDeps, req: {
+    agent: string;
+    message: string;
+    channel?: string;
+}): Promise<string>;
+export declare function getSession(store: PgStateStore, runId: string): Promise<{
+    runId: string;
+    agent: string;
+    state: SessionState;
+    transcript: SessionTurn[];
+} | null>;
+/**
+ * Appends the user's turn and wakes the worker. Rejects while the agent is
+ * mid-turn (strict turn-taking; the caller shows "agent is working").
+ */
+export declare function sendSessionMessage(deps: TickDeps, runId: string, req: {
+    text: string;
+    channel?: string;
+    close?: boolean;
+}): Promise<void>;
+export declare function listSessions(store: PgStateStore, limit?: number): Promise<{
+    runId: string;
+    agent: string;
+    status: string;
+    createdAt: Date;
+}[]>;

package/dist/conversations.js

@@ -0,0 +1,87 @@
+import { effectiveEvents } from "./fold.js";
+import { ev } from "./events.js";
+import { startRun } from "./orchestrator.js";
+/**
+ * Sessions: turn-based conversations as durable runs. A session is a run in
+ * mode "session" whose root task alternates agent turns and user turns on one
+ * event stream — the transcript IS the log, so a resumed session replays every
+ * prior turn for free and survives anything mid-sentence.
+ *
+ * Turn-taking is strict: a message is accepted only while the session awaits
+ * input. That keeps the stream single-writer (the worker owns it mid-turn)
+ * and matches the product model — you talk, the agent works, it answers.
+ */
+/** The default workflow plans exactly one task; sessions ride it. */
+const SESSION_TASK = "w0t0";
+export class SessionBusyError extends Error {
+    constructor() { super("the agent is mid-turn — wait for it to finish before sending"); }
+}
+export async function startSession(deps, req) {
+    return startRun(deps, { agent: req.agent, input: req.message, mode: "session" });
+}
+async function foldSession(store, runId) {
+    const run = await store.getRun(runId);
+    if (!run || run.mode !== "session")
+        return null;
+    const eff = effectiveEvents(await store.read(runId, `task:${SESSION_TASK}`));
+    let lastInputSeq = 0, lastUserSeq = 0;
+    for (const e of eff) {
+        if (e.type === "InputRequested")
+            lastInputSeq = e.seq;
+        else if (e.type === "UserMessage")
+            lastUserSeq = e.seq;
+    }
+    const awaiting = lastInputSeq > 0 && lastUserSeq < lastInputSeq;
+    const head = eff.at(-1)?.seq ?? 0;
+    return { run, eff, awaiting, head };
+}
+export async function getSession(store, runId) {
+    const s = await foldSession(store, runId);
+    if (!s)
+        return null;
+    const transcript = [];
+    const input = typeof s.run.input === "string" ? s.run.input : JSON.stringify(s.run.input);
+    transcript.push({ role: "user", text: input, seq: 0 });
+    for (const e of s.eff) {
+        if (e.type === "InputRequested") {
+            transcript.push({ role: "assistant", text: String(e.payload.text ?? ""), seq: e.seq });
+        }
+        else if (e.type === "UserMessage" && !e.payload.close) {
+            transcript.push({ role: "user", text: String(e.payload.text ?? ""), channel: e.payload.channel, seq: e.seq });
+        }
+        else if (e.type === "TaskCompleted") {
+            // The closing assistant text is already in the last InputRequested.
+        }
+    }
+    const state = s.run.status === "completed" || s.run.status === "failed" || s.run.status === "cancelled"
+        ? s.run.status
+        : s.awaiting ? "awaiting_input" : "working";
+    return { runId, agent: s.run.agent, state, transcript };
+}
+/**
+ * Appends the user's turn and wakes the worker. Rejects while the agent is
+ * mid-turn (strict turn-taking; the caller shows "agent is working").
+ */
+export async function sendSessionMessage(deps, runId, req) {
+    const s = await foldSession(deps.store, runId);
+    if (!s)
+        throw new Error(`no session ${runId}`);
+    if (s.run.status === "completed" || s.run.status === "failed" || s.run.status === "cancelled") {
+        throw new Error(`session is ${s.run.status}`);
+    }
+    if (!s.awaiting)
+        throw new SessionBusyError();
+    const r = await deps.store.append(runId, `task:${SESSION_TASK}`, s.head, [
+        ev("UserMessage", { text: req.text, channel: req.channel, ...(req.close ? { close: true } : {}) }),
+    ]);
+    if (!r.ok)
+        throw new SessionBusyError(); // a worker touched the stream since we looked
+    await deps.queue.send("tasks-short", {
+        kind: "task", runId, taskId: SESSION_TASK, agent: s.run.agent,
+        dedupeKey: `msg-${runId}-${r.lastSeq}`,
+    });
+}
+export async function listSessions(store, limit = 50) {
+    const runs = await store.listRuns(limit * 2);
+    return runs.filter((r) => r.mode === "session").slice(0, limit);
+}

package/dist/db.d.ts

@@ -0,0 +1,3 @@
+import pg from "pg";
+export declare function createPool(url?: string): pg.Pool;
+export declare function tx<T>(pool: pg.Pool, fn: (c: pg.PoolClient) => Promise<T>): Promise<T>;

package/dist/db.js

@@ -0,0 +1,20 @@
+import pg from "pg";
+export function createPool(url = process.env.DATABASE_URL ?? "postgres://toren:toren@localhost:5433/toren") {
+    return new pg.Pool({ connectionString: url, max: 10 });
+}
+export async function tx(pool, fn) {
+    const c = await pool.connect();
+    try {
+        await c.query("BEGIN");
+        const r = await fn(c);
+        await c.query("COMMIT");
+        return r;
+    }
+    catch (e) {
+        await c.query("ROLLBACK");
+        throw e;
+    }
+    finally {
+        c.release();
+    }
+}

package/dist/digest.d.ts

@@ -0,0 +1 @@
+export declare function canonicalDigest(value: unknown): string;

package/dist/digest.js

@@ -0,0 +1,13 @@
+import { createHash } from "node:crypto";
+function canonical(v) {
+    if (Array.isArray(v))
+        return v.map(canonical);
+    if (v && typeof v === "object") {
+        return Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, val]) => [k, canonical(val)]));
+    }
+    return v;
+}
+export function canonicalDigest(value) {
+    return createHash("sha256").update(JSON.stringify(canonical(value))).digest("hex");
+}

package/dist/events.d.ts

@@ -0,0 +1,20 @@
+export type StreamId = "run" | `task:${string}`;
+export type EventType = "RunCreated" | "RunStarted" | "SideEffectRecorded" | "TimerSet" | "TimerFired" | "WavePlanned" | "WaveDispatched" | "WaveTaskSettled" | "WaveSettled" | "RunCompleted" | "RunFailed" | "RunCancelled" | "TaskStarted" | "LlmCallStarted" | "LlmCallCompleted" | "ToolCallStarted" | "ToolCallCompleted" | "ApprovalRequested" | "ApprovalResolved" | "StreamInvalidated" | "TaskCompleted" | "TaskFailed" | "InputRequested" | "UserMessage" | "ContextCompacted";
+export interface NewEvent {
+    type: EventType;
+    payload: Record<string, unknown> & {
+        v: 1;
+    };
+}
+export interface RecordedEvent extends NewEvent {
+    seq: number;
+    recordedAt: Date;
+}
+export declare const ev: (type: EventType, payload: Record<string, unknown>) => NewEvent;
+export declare function isInvalidation(e: RecordedEvent): e is RecordedEvent & {
+    payload: {
+        v: 1;
+        fromSeq: number;
+        reason: string;
+    };
+};

package/dist/events.js

@@ -0,0 +1,4 @@
+export const ev = (type, payload) => ({ type, payload: { v: 1, ...payload } });
+export function isInvalidation(e) {
+    return e.type === "StreamInvalidated" && typeof e.payload.fromSeq === "number";
+}

package/dist/files.d.ts

@@ -0,0 +1,28 @@
+import type pg from "pg";
+/**
+ * Deployment-wide file store: raw bytes plus parsed text, keyed by content
+ * hash. Parsing happens once at upload; agents read the parsed pages through
+ * the read_file builtin, and every read is recorded with keyed idempotency,
+ * so replay never re-reads and a 200-page document never floods a context
+ * window — the agent pages through it.
+ */
+export interface StoredFile {
+    id: string;
+    name: string;
+    mediaType: string;
+    bytes: number;
+    pages: string[];
+}
+export declare class PgFiles {
+    private pool;
+    constructor(pool: pg.Pool);
+    put(file: {
+        name: string;
+        mediaType: string;
+        data: Buffer;
+        pages: string[];
+    }): Promise<StoredFile>;
+    get(id: string): Promise<StoredFile | null>;
+}
+/** The manifest line appended to a run input or session message for each attachment. */
+export declare function fileManifest(files: StoredFile[]): string;

package/dist/files.js

@@ -0,0 +1,27 @@
+import { createHash } from "node:crypto";
+export class PgFiles {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async put(file) {
+        const id = createHash("sha256").update(file.data).digest("hex").slice(0, 16);
+        await this.pool.query(`INSERT INTO toren_control.files (id, name, media_type, bytes, pages, data)
+       VALUES ($1, $2, $3, $4, $5, $6) ON CONFLICT (id) DO NOTHING`, [id, file.name, file.mediaType, file.data.length, JSON.stringify(file.pages), file.data]);
+        return { id, name: file.name, mediaType: file.mediaType, bytes: file.data.length, pages: file.pages };
+    }
+    async get(id) {
+        const r = await this.pool.query(`SELECT id, name, media_type, bytes, pages FROM toren_control.files WHERE id = $1`, [id]);
+        const row = r.rows[0];
+        if (!row)
+            return null;
+        return { id: row.id, name: row.name, mediaType: row.media_type, bytes: row.bytes, pages: row.pages };
+    }
+}
+/** The manifest line appended to a run input or session message for each attachment. */
+export function fileManifest(files) {
+    if (files.length === 0)
+        return "";
+    const lines = files.map((f) => `- ${f.name} (file_id: ${f.id}, ${f.pages.length} page${f.pages.length === 1 ? "" : "s"})`);
+    return `\n\n[Attached files:\n${lines.join("\n")}\nRead them with the read_file tool.]`;
+}

package/dist/fold.d.ts

@@ -0,0 +1,3 @@
+import { type RecordedEvent } from "./events.js";
+/** Events whose effects survive all StreamInvalidated markers, in order. */
+export declare function effectiveEvents(events: RecordedEvent[]): RecordedEvent[];

package/dist/fold.js

@@ -0,0 +1,6 @@
+import { isInvalidation } from "./events.js";
+/** Events whose effects survive all StreamInvalidated markers, in order. */
+export function effectiveEvents(events) {
+    const cuts = events.filter(isInvalidation).map((m) => ({ from: m.payload.fromSeq, at: m.seq }));
+    return events.filter((e) => !isInvalidation(e) && !cuts.some((c) => e.seq >= c.from && e.seq < c.at));
+}

package/dist/guardians.d.ts

@@ -0,0 +1,9 @@
+import type { TickDeps } from "./orchestrator.js";
+/**
+ * The guardians: one scheduled pass that re-nudges every
+ * non-terminal run. Covers lost queue messages (reconciler role) and runs
+ * whose workers died mid-flight (watchdog role — expired leases simply stop
+ * blocking the next tick). Ticks are cheap no-ops when nothing changed, so
+ * the sweep needs no per-run state.
+ */
+export declare function sweep(deps: Pick<TickDeps, "store" | "queue">, agent?: string): Promise<number>;

package/dist/guardians.js

@@ -0,0 +1,14 @@
+/**
+ * The guardians: one scheduled pass that re-nudges every
+ * non-terminal run. Covers lost queue messages (reconciler role) and runs
+ * whose workers died mid-flight (watchdog role — expired leases simply stop
+ * blocking the next tick). Ticks are cheap no-ops when nothing changed, so
+ * the sweep needs no per-run state.
+ */
+export async function sweep(deps, agent) {
+    const runs = await deps.store.listNonTerminalRuns();
+    for (const runId of runs) {
+        await deps.queue.send("orchestrator", { kind: "tick", runId, agent, dedupeKey: `sweep-${runId}` });
+    }
+    return runs.length;
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+export declare const TOREN_VERSION = "0.0.1";
+export * from "./events.js";
+export * from "./fold.js";
+export * from "./db.js";
+export * from "./migrate.js";
+export * from "./store.js";
+export * from "./leases.js";
+export * from "./queue.js";
+export * from "./blobs.js";
+export * from "./files.js";
+export * from "./model.js";
+export * from "./digest.js";
+export * from "./tools.js";
+export * from "./builtins.js";
+export * from "./providers/mock.js";
+export * from "./providers/echo.js";
+export * from "./approvals.js";
+export * from "./apiKeys.js";
+export * from "./schedules.js";
+export * from "./tracing.js";
+export * from "./loop.js";
+export * from "./workflow.js";
+export * from "./orchestrator.js";
+export * from "./worker.js";
+export * from "./guardians.js";
+export * from "./conversations.js";
+export * from "./spawn.js";

package/dist/index.js

@@ -0,0 +1,27 @@
+export const TOREN_VERSION = "0.0.1";
+export * from "./events.js";
+export * from "./fold.js";
+export * from "./db.js";
+export * from "./migrate.js";
+export * from "./store.js";
+export * from "./leases.js";
+export * from "./queue.js";
+export * from "./blobs.js";
+export * from "./files.js";
+export * from "./model.js";
+export * from "./digest.js";
+export * from "./tools.js";
+export * from "./builtins.js";
+export * from "./providers/mock.js";
+export * from "./providers/echo.js";
+export * from "./approvals.js";
+export * from "./apiKeys.js";
+export * from "./schedules.js";
+export * from "./tracing.js";
+export * from "./loop.js";
+export * from "./workflow.js";
+export * from "./orchestrator.js";
+export * from "./worker.js";
+export * from "./guardians.js";
+export * from "./conversations.js";
+export * from "./spawn.js";

package/dist/leases.d.ts

@@ -0,0 +1,16 @@
+import type pg from "pg";
+import type { StreamId } from "./events.js";
+export interface Lease {
+    runId: string;
+    streamId: StreamId;
+    owner: string;
+    epoch: number;
+}
+export declare class PgLeases {
+    private pool;
+    private schema;
+    constructor(pool: pg.Pool, schema: string);
+    acquire(runId: string, streamId: StreamId, owner: string, ttlSeconds: number): Promise<Lease | null>;
+    renew(lease: Lease, ttlSeconds?: number): Promise<boolean>;
+    release(lease: Lease): Promise<void>;
+}

package/dist/leases.js

@@ -0,0 +1,30 @@
+export class PgLeases {
+    pool;
+    schema;
+    constructor(pool, schema) {
+        this.pool = pool;
+        this.schema = schema;
+    }
+    async acquire(runId, streamId, owner, ttlSeconds) {
+        const r = await this.pool.query(`INSERT INTO ${this.schema}.leases (run_id, stream_id, owner, epoch, expires_at)
+       VALUES ($1, $2, $3, 1, now() + make_interval(secs => $4))
+       ON CONFLICT (run_id, stream_id) DO UPDATE
+         SET owner = EXCLUDED.owner,
+             epoch = ${this.schema}.leases.epoch + 1,
+             expires_at = EXCLUDED.expires_at
+         WHERE ${this.schema}.leases.expires_at < now()
+       RETURNING epoch`, [runId, streamId, owner, ttlSeconds]);
+        const row = r.rows[0];
+        return row ? { runId, streamId, owner, epoch: Number(row.epoch) } : null;
+    }
+    async renew(lease, ttlSeconds = 60) {
+        const r = await this.pool.query(`UPDATE ${this.schema}.leases SET expires_at = now() + make_interval(secs => $5)
+       WHERE run_id = $1 AND stream_id = $2 AND owner = $3 AND epoch = $4 AND expires_at >= now()`, [lease.runId, lease.streamId, lease.owner, lease.epoch, ttlSeconds]);
+        return (r.rowCount ?? 0) > 0;
+    }
+    async release(lease) {
+        // Expire rather than delete: the row keeps the epoch so the next acquire fences correctly.
+        await this.pool.query(`UPDATE ${this.schema}.leases SET expires_at = now() - interval '1 second'
+       WHERE run_id = $1 AND stream_id = $2 AND owner = $3 AND epoch = $4`, [lease.runId, lease.streamId, lease.owner, lease.epoch]);
+    }
+}

package/dist/loop.d.ts

@@ -0,0 +1,69 @@
+import type { z } from "zod";
+import { type ToolDefAny } from "./tools.js";
+import type { ModelProvider } from "./model.js";
+import type { PgStateStore } from "./store.js";
+export declare 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 declare class InvalidationStormError extends Error {
+}
+export declare const INVALIDATION_STORM_LIMIT = 3;
+export declare const INVALIDATION_STORM_WINDOW_MS: number;
+export interface AgentSpec {
+    model: string;
+    system: string;
+    tools: ToolDefAny[];
+    maxTokens: number;
+    maxSteps: number;
+    outputSchema?: z.ZodTypeAny;
+    /** Declared env values (from agent.yaml `env:`) passed to tool handlers as ctx.env. */
+    env?: Record<string, string>;
+    /** Model context window in tokens; drives compaction. Defaults per provider; unset for mock disables compaction. */
+    contextWindow?: number;
+}
+/** Provider defaults; agent.yaml `contextWindow:` overrides. mock/ gets none, so tests never compact by surprise. */
+export declare function defaultContextWindow(model: string): number | undefined;
+export declare const COMPACT_ELIDE_AT = 0.5;
+export declare const COMPACT_SUMMARY_AT = 0.78;
+export declare const COMPACT_KEEP_RESULTS = 3;
+export declare const COMPACT_KEEP_TAIL = 6;
+export declare const COMPACT_MIN_ELIDE_CHARS = 500;
+export declare const COMPACT_SUMMARY_MAX_TOKENS = 2048;
+export declare const SUMMARIZE_SYSTEM: string;
+export interface TaskLoopArgs {
+    store: PgStateStore;
+    provider: ModelProvider;
+    runId: string;
+    taskId: string;
+    agent: AgentSpec;
+    input: string;
+    /** Attached-file access, passed through to tool handlers (read_file builtin). */
+    files?: import("./tools.js").ToolCtx["files"];
+    /** Per-run sandbox execution for the bash builtin; wired by the runtime. */
+    sandbox?: import("./tools.js").SandboxExec;
+    /** Background named-process runs for the run_process/check_run builtins; wired by the runtime. */
+    processes?: import("./tools.js").ProcessesCtx;
+    /** Conversational session: end-of-turn parks awaiting the next UserMessage instead of completing. */
+    sessionMode?: boolean;
+}
+export type TaskLoopResult = {
+    status: "completed";
+    output: string;
+} | {
+    status: "waitingApproval";
+} | {
+    status: "awaitingInput";
+} | {
+    status: "failed";
+    error: string;
+};
+/** Layered onto the system prompt in session mode; constant, so replay digests stay stable. */
+export declare const SESSION_PREAMBLE: string;
+export declare function runTaskLoop(args: TaskLoopArgs): Promise<TaskLoopResult>;