@autonome-research/thread-phase 3.0.0

package/dist/session/sqlite-job-store.js

@@ -0,0 +1,200 @@
+/**
+ * sqlite-backed JobStore implementation — the bundled default.
+ *
+ * Two tables (job, event) on a single sqlite file. WAL journal for write
+ * concurrency, foreign keys enforced.
+ *
+ * The interface (`JobStore`) is async-by-default in v3.0.0; this
+ * implementation wraps its sync better-sqlite3 calls in `async` methods.
+ * better-sqlite3 stays sync internally — the only overhead is one
+ * microtask per call, which is negligible against sqlite's already
+ * sub-millisecond write cost. We pay this cost to keep one unified
+ * interface across all backends (Postgres, Redis, network stores)
+ * instead of two parallel sync + async hierarchies.
+ */
+import Database from 'better-sqlite3';
+import { randomUUID } from 'crypto';
+const MIGRATIONS = [
+    {
+        version: 1,
+        up: `
+      CREATE TABLE IF NOT EXISTS job (
+        id           TEXT PRIMARY KEY,
+        name         TEXT NOT NULL,
+        input        TEXT NOT NULL,
+        status       TEXT NOT NULL DEFAULT 'PENDING',
+        result       TEXT,
+        error        TEXT,
+        created_at   TEXT NOT NULL DEFAULT (datetime('now')),
+        started_at   TEXT,
+        completed_at TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_job_name_created
+        ON job (name, created_at DESC);
+
+      CREATE TABLE IF NOT EXISTS event (
+        id          INTEGER PRIMARY KEY AUTOINCREMENT,
+        job_id      TEXT NOT NULL,
+        event_type  TEXT NOT NULL,
+        data        TEXT NOT NULL,
+        created_at  TEXT NOT NULL DEFAULT (datetime('now')),
+        FOREIGN KEY (job_id) REFERENCES job(id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_event_job_id ON event (job_id, id);
+    `,
+    },
+];
+function defaultDbPath() {
+    return process.env.THREAD_PHASE_DB ?? './thread-phase.db';
+}
+function parseDate(s) {
+    return s ? new Date(s + 'Z') : null;
+}
+export class SqliteJobStore {
+    db;
+    constructor(dbPath = defaultDbPath()) {
+        this.db = new Database(dbPath);
+        this.db.pragma('journal_mode = WAL');
+        this.db.pragma('foreign_keys = ON');
+        this.runMigrations();
+    }
+    /**
+     * Apply any unapplied migrations. Reads `PRAGMA user_version`, applies
+     * each entry from `MIGRATIONS` whose version is greater, inside a
+     * transaction per step, then bumps user_version.
+     *
+     * Idempotent: running twice is a no-op once the schema is current.
+     */
+    runMigrations() {
+        const current = this.db.pragma('user_version', { simple: true }) ?? 0;
+        for (const m of MIGRATIONS) {
+            if (m.version <= current)
+                continue;
+            this.db.transaction(() => {
+                this.db.exec(m.up);
+                // user_version is an integer pragma; better-sqlite3 doesn't support
+                // parameter binding for pragmas, so interpolate the integer directly.
+                this.db.pragma(`user_version = ${m.version}`);
+            })();
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Job lifecycle
+    // -------------------------------------------------------------------------
+    async createJob(name, input) {
+        const id = randomUUID();
+        this.db
+            .prepare(`INSERT INTO job (id, name, input) VALUES (?, ?, ?)`)
+            .run(id, name, JSON.stringify(input));
+        return id;
+    }
+    async acquireExclusive(name, input) {
+        // better-sqlite3's `db.transaction(fn)` wraps the callback in BEGIN…COMMIT
+        // (defaults to deferred, but the runtime upgrades to a write lock the
+        // moment we INSERT, which serializes concurrent acquireExclusive calls
+        // on the same DB file). The check + insert therefore happens atomically:
+        // a second caller racing on the same name will see the row we just
+        // inserted (status='RUNNING') and return null.
+        const tx = this.db.transaction((n, i) => {
+            const existing = this.db
+                .prepare(`SELECT id FROM job WHERE name = ? AND status = 'RUNNING' LIMIT 1`)
+                .get(n);
+            if (existing)
+                return null;
+            const id = randomUUID();
+            this.db
+                .prepare(`INSERT INTO job (id, name, input, status, started_at)
+           VALUES (?, ?, ?, 'RUNNING', datetime('now'))`)
+                .run(id, n, JSON.stringify(i));
+            return id;
+        });
+        return tx(name, input);
+    }
+    async setRunning(jobId) {
+        // COALESCE on started_at: idempotent w.r.t. acquireExclusive, which
+        // already sets status='RUNNING' and started_at at claim time.
+        this.db
+            .prepare(`UPDATE job SET status = 'RUNNING',
+                        started_at = COALESCE(started_at, datetime('now'))
+         WHERE id = ?`)
+            .run(jobId);
+    }
+    async setCompleted(jobId, result) {
+        this.db
+            .prepare(`UPDATE job SET status = 'COMPLETED', result = ?, completed_at = datetime('now') WHERE id = ?`)
+            .run(JSON.stringify(result ?? null), jobId);
+    }
+    async setFailed(jobId, error) {
+        this.db
+            .prepare(`UPDATE job SET status = 'FAILED', error = ?, completed_at = datetime('now') WHERE id = ?`)
+            .run(error, jobId);
+    }
+    // -------------------------------------------------------------------------
+    // Job reads
+    // -------------------------------------------------------------------------
+    async getJob(jobId) {
+        const row = this.db
+            .prepare(`SELECT j.*, (SELECT COUNT(*) FROM event WHERE job_id = j.id) AS event_count
+         FROM job j WHERE j.id = ?`)
+            .get(jobId);
+        return row ? this.toJobRecord(row) : null;
+    }
+    async listJobs(options = {}) {
+        const limit = options.limit ?? 50;
+        // Build one parameterized query — `name IS NULL OR j.name = name` lets a
+        // null parameter act as a no-filter wildcard, removing the duplicated
+        // SELECT/ORDER/LIMIT clauses that were previously copied per branch.
+        const sql = `
+      SELECT j.*, (SELECT COUNT(*) FROM event WHERE job_id = j.id) AS event_count
+      FROM job j
+      WHERE (? IS NULL OR j.name = ?)
+      ORDER BY j.created_at DESC
+      LIMIT ?
+    `;
+        const name = options.name ?? null;
+        const rows = this.db.prepare(sql).all(name, name, limit);
+        return rows.map((r) => this.toJobRecord(r));
+    }
+    toJobRecord(row) {
+        return {
+            id: row.id,
+            name: row.name,
+            input: JSON.parse(row.input),
+            status: row.status,
+            result: row.result ? JSON.parse(row.result) : null,
+            error: row.error,
+            eventCount: row.event_count,
+            createdAt: parseDate(row.created_at),
+            startedAt: parseDate(row.started_at),
+            completedAt: parseDate(row.completed_at),
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Events — append-only log, resumable via afterId
+    // -------------------------------------------------------------------------
+    async appendEvent(jobId, event) {
+        const result = this.db
+            .prepare(`INSERT INTO event (job_id, event_type, data) VALUES (?, ?, ?)`)
+            .run(jobId, event.type, JSON.stringify(event));
+        return Number(result.lastInsertRowid);
+    }
+    async getEvents(jobId, afterId = 0) {
+        const rows = this.db
+            .prepare(`SELECT id, job_id, event_type, data, created_at
+         FROM event WHERE job_id = ? AND id > ? ORDER BY id ASC`)
+            .all(jobId, afterId);
+        return rows.map((r) => ({
+            id: r.id,
+            jobId: r.job_id,
+            eventType: r.event_type,
+            data: JSON.parse(r.data),
+            createdAt: parseDate(r.created_at),
+        }));
+    }
+    close() {
+        this.db.close();
+    }
+}
+//# sourceMappingURL=sqlite-job-store.js.map

package/dist/session/sqlite-job-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-job-store.js","sourceRoot":"","sources":["../../src/session/sqlite-job-store.ts"],"names":[],"mappings":"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"}

package/dist/session/sse.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Server-Sent Events helper — adapt a JobRunner live stream + replay log
+ * into an SSE wire format for HTTP consumers.
+ *
+ * Wire shape:
+ *   - Each event is `id: <eventId>\nevent: <type>\ndata: <json>\n\n`.
+ *   - The eventId is the JobStore's monotonic id, so disconnected clients
+ *     can resume by reading `Last-Event-ID` and replaying via JobStore.
+ *   - The connection closes after a `done` or `error` event.
+ *
+ * The helper is framework-agnostic: it writes to a minimal `SSEResponse`
+ * interface so it works with Node's `http.ServerResponse`, Express's
+ * `Response`, Fastify's reply (after .raw), etc.
+ *
+ * Typical usage:
+ *
+ *   app.get('/jobs/:id/events', (req, res) => {
+ *     const lastId = Number(req.headers['last-event-id'] ?? 0);
+ *     res.writeHead(200, {
+ *       'Content-Type': 'text/event-stream',
+ *       'Cache-Control': 'no-cache',
+ *       'Connection': 'keep-alive',
+ *     });
+ *     streamToSSE({ runner, store, jobId: req.params.id, res, afterId: lastId });
+ *   });
+ */
+import type { JobStore } from './job-store.js';
+import type { JobRunner } from './job-runner.js';
+/**
+ * Minimal response interface — `http.ServerResponse` and Express's `Response`
+ * both satisfy this without modification.
+ */
+export interface SSEResponse {
+    write(chunk: string): boolean;
+    end(): void;
+    on(event: 'close', listener: () => void): void;
+}
+export interface StreamToSSEOptions {
+    runner: JobRunner;
+    store: JobStore;
+    jobId: string;
+    res: SSEResponse;
+    /**
+     * Replay events with id > afterId before subscribing live. Use the value
+     * of the client's `Last-Event-ID` header to resume after disconnect.
+     */
+    afterId?: number;
+    /**
+     * Heartbeat interval in ms. Default 25s. Sends an SSE comment line to
+     * keep proxies and intermediaries from closing the connection. Set 0 to
+     * disable.
+     */
+    heartbeatMs?: number;
+}
+/**
+ * Pump a job's events to an SSE response. Resolves when the connection
+ * closes (either because the job ended or the client disconnected).
+ */
+export declare function streamToSSE(options: StreamToSSEOptions): Promise<void>;
+//# sourceMappingURL=sse.d.ts.map

package/dist/session/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/session/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,iBAAiB,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,GAAG,IAAI,IAAI,CAAC;IACZ,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,WAAW,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqE5E"}

package/dist/session/sse.js

@@ -0,0 +1,97 @@
+/**
+ * Server-Sent Events helper — adapt a JobRunner live stream + replay log
+ * into an SSE wire format for HTTP consumers.
+ *
+ * Wire shape:
+ *   - Each event is `id: <eventId>\nevent: <type>\ndata: <json>\n\n`.
+ *   - The eventId is the JobStore's monotonic id, so disconnected clients
+ *     can resume by reading `Last-Event-ID` and replaying via JobStore.
+ *   - The connection closes after a `done` or `error` event.
+ *
+ * The helper is framework-agnostic: it writes to a minimal `SSEResponse`
+ * interface so it works with Node's `http.ServerResponse`, Express's
+ * `Response`, Fastify's reply (after .raw), etc.
+ *
+ * Typical usage:
+ *
+ *   app.get('/jobs/:id/events', (req, res) => {
+ *     const lastId = Number(req.headers['last-event-id'] ?? 0);
+ *     res.writeHead(200, {
+ *       'Content-Type': 'text/event-stream',
+ *       'Cache-Control': 'no-cache',
+ *       'Connection': 'keep-alive',
+ *     });
+ *     streamToSSE({ runner, store, jobId: req.params.id, res, afterId: lastId });
+ *   });
+ */
+/**
+ * Pump a job's events to an SSE response. Resolves when the connection
+ * closes (either because the job ended or the client disconnected).
+ */
+export async function streamToSSE(options) {
+    const { runner, store, jobId, res, afterId = 0 } = options;
+    const heartbeatMs = options.heartbeatMs ?? 25_000;
+    let closed = false;
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        res.end();
+    };
+    res.on('close', () => {
+        closed = true;
+    });
+    const writeFrame = (id, type, data) => {
+        if (closed)
+            return false;
+        const payload = `id: ${id}\n` +
+            `event: ${type}\n` +
+            `data: ${JSON.stringify(data)}\n\n`;
+        return res.write(payload);
+    };
+    // Step 1: replay anything the client has missed.
+    let lastId = afterId;
+    const replay = await store.getEvents(jobId, afterId);
+    for (const evt of replay) {
+        writeFrame(evt.id, evt.eventType, evt.data);
+        lastId = Math.max(lastId, evt.id);
+    }
+    // If the job is already finished and replay covered everything, close.
+    const job = await store.getJob(jobId);
+    if (job && (job.status === 'COMPLETED' || job.status === 'FAILED')) {
+        close();
+        return;
+    }
+    // Step 2: subscribe to live events. Buffer events that arrived during
+    // replay if their id is past lastId (otherwise they're already sent).
+    const channel = `job:${jobId}`;
+    const onLive = (evt) => {
+        if (closed)
+            return;
+        if (evt.id <= lastId)
+            return;
+        lastId = evt.id;
+        writeFrame(evt.id, evt.eventType, evt.data);
+        if (evt.eventType === 'done' || evt.eventType === 'error') {
+            close();
+        }
+    };
+    runner.on(channel, onLive);
+    // Heartbeat: comment line every N seconds to keep proxies from idling out.
+    let heartbeat = null;
+    if (heartbeatMs > 0) {
+        heartbeat = setInterval(() => {
+            if (closed)
+                return;
+            res.write(`: keepalive ${Date.now()}\n\n`);
+        }, heartbeatMs);
+    }
+    // Wait until the connection closes.
+    await new Promise((resolve) => {
+        res.on('close', resolve);
+    });
+    if (heartbeat)
+        clearInterval(heartbeat);
+    runner.off(channel, onLive);
+}
+//# sourceMappingURL=sse.js.map

package/dist/session/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/session/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAiCH;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAA2B;IAC3D,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC;IAC3D,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,MAAM,CAAC;IAElD,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,MAAM,KAAK,GAAG,GAAG,EAAE;QACjB,IAAI,MAAM;YAAE,OAAO;QACnB,MAAM,GAAG,IAAI,CAAC;QACd,GAAG,CAAC,GAAG,EAAE,CAAC;IACZ,CAAC,CAAC;IAEF,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QACnB,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC,CAAC,CAAC;IAEH,MAAM,UAAU,GAAG,CAAC,EAAU,EAAE,IAAY,EAAE,IAAa,EAAW,EAAE;QACtE,IAAI,MAAM;YAAE,OAAO,KAAK,CAAC;QACzB,MAAM,OAAO,GACX,OAAO,EAAE,IAAI;YACb,UAAU,IAAI,IAAI;YAClB,SAAS,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC;QACtC,OAAO,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC,CAAC;IAEF,iDAAiD;IACjD,IAAI,MAAM,GAAG,OAAO,CAAC;IACrB,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACrD,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAC5C,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,uEAAuE;IACvE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,WAAW,IAAI,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC,EAAE,CAAC;QACnE,KAAK,EAAE,CAAC;QACR,OAAO;IACT,CAAC;IAED,sEAAsE;IACtE,sEAAsE;IACtE,MAAM,OAAO,GAAG,OAAO,KAAK,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,CAAC,GAAc,EAAE,EAAE;QAChC,IAAI,MAAM;YAAE,OAAO;QACnB,IAAI,GAAG,CAAC,EAAE,IAAI,MAAM;YAAE,OAAO;QAC7B,MAAM,GAAG,GAAG,CAAC,EAAE,CAAC;QAChB,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,GAAG,CAAC,SAAS,KAAK,MAAM,IAAI,GAAG,CAAC,SAAS,KAAK,OAAO,EAAE,CAAC;YAC1D,KAAK,EAAE,CAAC;QACV,CAAC;IACH,CAAC,CAAC;IACF,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAE3B,2EAA2E;IAC3E,IAAI,SAAS,GAA0C,IAAI,CAAC;IAC5D,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QACpB,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;YAC3B,IAAI,MAAM;gBAAE,OAAO;YACnB,GAAG,CAAC,KAAK,CAAC,eAAe,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC,EAAE,WAAW,CAAC,CAAC;IAClB,CAAC;IAED,oCAAoC;IACpC,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAClC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC3B,CAAC,CAAC,CAAC;IAEH,IAAI,SAAS;QAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACxC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAC9B,CAAC"}

package/dist/tools/index.d.ts

@@ -0,0 +1,2 @@
+export { ToolRegistry, type ToolHandler, type ToolRegistryOptions, } from './registry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,mBAAmB,GACzB,MAAM,eAAe,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,2 @@
+export { ToolRegistry, } from './registry.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,GAGb,MAAM,eAAe,CAAC"}

package/dist/tools/registry.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Tool registry — name → {definition, handler} dispatch with optional
+ * JSON-Schema validation of arguments.
+ *
+ * Implements `ToolExecutor` so it can be passed directly to
+ * `runAgentWithTools({ ..., toolExecutor: registry })`.
+ *
+ * Validation behaviour: when enabled (the default), arguments coming back
+ * from the model are checked against the tool's `inputSchema` before the
+ * handler runs. Failures return an error string to the agent rather than
+ * throwing — the model gets to read what went wrong and try again.
+ *
+ * Same policy for unknown tools and handler exceptions: errors become
+ * agent-readable strings, not thrown exceptions, so a single bad tool call
+ * doesn't kill the whole pipeline.
+ */
+import type { ToolDefinition, ToolExecutor, ToolResult } from '../messages.js';
+/**
+ * Handler signature — receives parsed args plus optional context, returns the
+ * tool's result content as a string. Anything string-shaped works (JSON,
+ * markdown, plain text); the agent sees it raw.
+ */
+export type ToolHandler = (args: Record<string, unknown>, context: {
+    toolCallId: string;
+}) => Promise<string>;
+export interface ToolRegistryOptions {
+    /** When false, skip schema validation. Default: true. */
+    validate?: boolean;
+}
+export declare class ToolRegistry implements ToolExecutor {
+    private tools;
+    private ajv;
+    constructor(options?: ToolRegistryOptions);
+    /**
+     * Register a tool. Throws on duplicate names — pipelines should be aware of
+     * what they expose, not silently overwrite.
+     */
+    register(definition: ToolDefinition, handler: ToolHandler): this;
+    /** All registered tool definitions, in registration order. Hand to AgentConfig.tools. */
+    definitions(): ToolDefinition[];
+    has(name: string): boolean;
+    execute(name: string, toolCallId: string, args: Record<string, unknown>): Promise<ToolResult>;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/tools/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE/E;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,KAC5B,OAAO,CAAC,MAAM,CAAC,CAAC;AAErB,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AASD,qBAAa,YAAa,YAAW,YAAY;IAC/C,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,GAAG,CAAa;gBAEZ,OAAO,GAAE,mBAAwB;IAI7C;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAShE,yFAAyF;IACzF,WAAW,IAAI,cAAc,EAAE;IAI/B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIpB,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,UAAU,CAAC;CA+BvB"}

package/dist/tools/registry.js

@@ -0,0 +1,74 @@
+/**
+ * Tool registry — name → {definition, handler} dispatch with optional
+ * JSON-Schema validation of arguments.
+ *
+ * Implements `ToolExecutor` so it can be passed directly to
+ * `runAgentWithTools({ ..., toolExecutor: registry })`.
+ *
+ * Validation behaviour: when enabled (the default), arguments coming back
+ * from the model are checked against the tool's `inputSchema` before the
+ * handler runs. Failures return an error string to the agent rather than
+ * throwing — the model gets to read what went wrong and try again.
+ *
+ * Same policy for unknown tools and handler exceptions: errors become
+ * agent-readable strings, not thrown exceptions, so a single bad tool call
+ * doesn't kill the whole pipeline.
+ */
+import { Ajv } from 'ajv';
+export class ToolRegistry {
+    tools = new Map();
+    ajv;
+    constructor(options = {}) {
+        this.ajv = options.validate === false ? null : new Ajv({ allErrors: true, strict: false });
+    }
+    /**
+     * Register a tool. Throws on duplicate names — pipelines should be aware of
+     * what they expose, not silently overwrite.
+     */
+    register(definition, handler) {
+        if (this.tools.has(definition.name)) {
+            throw new Error(`ToolRegistry: tool already registered: ${definition.name}`);
+        }
+        const validator = this.ajv ? this.ajv.compile(definition.inputSchema) : null;
+        this.tools.set(definition.name, { definition, handler, validator });
+        return this;
+    }
+    /** All registered tool definitions, in registration order. Hand to AgentConfig.tools. */
+    definitions() {
+        return [...this.tools.values()].map((e) => e.definition);
+    }
+    has(name) {
+        return this.tools.has(name);
+    }
+    async execute(name, toolCallId, args) {
+        const entry = this.tools.get(name);
+        if (!entry) {
+            return {
+                toolCallId,
+                content: `Error: unknown tool "${name}". Registered tools: ${[...this.tools.keys()].join(', ') || '(none)'}.`,
+            };
+        }
+        if (entry.validator) {
+            const ok = entry.validator(args);
+            if (!ok) {
+                const errs = entry.validator.errors ?? [];
+                const detail = errs
+                    .map((e) => `${e.instancePath || '/'} ${e.message ?? 'invalid'}`)
+                    .join('; ');
+                return {
+                    toolCallId,
+                    content: `Error: invalid arguments for "${name}": ${detail}`,
+                };
+            }
+        }
+        try {
+            const content = await entry.handler(args, { toolCallId });
+            return { toolCallId, content };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { toolCallId, content: `Error: tool "${name}" threw: ${message}` };
+        }
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"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"}

package/dist/triggers/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Triggers — entry-point abstraction for thread-phase pipelines.
+ *
+ * The `Trigger` interface is the protocol every signal source implements:
+ * timers, webhooks, queue consumers, file watchers, message brokers.
+ * Core ships only `TimerTrigger`; HTTP/queue/file-watch adapters live in
+ * `examples/triggers/` as recipes.
+ *
+ * `runTrigger` is the canonical consumer — reads events, dispatches
+ * pipelines, optionally persists through a `JobRunner`.
+ */
+export type { Trigger, TriggerEvent } from './types.js';
+export { TimerTrigger, type TimerTriggerOptions } from './timer-trigger.js';
+export { runTrigger, type RunTriggerOptions, type RunTriggerHandle, } from './run-trigger.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/triggers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/triggers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EACL,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC"}

package/dist/triggers/index.js

@@ -0,0 +1,14 @@
+/**
+ * Triggers — entry-point abstraction for thread-phase pipelines.
+ *
+ * The `Trigger` interface is the protocol every signal source implements:
+ * timers, webhooks, queue consumers, file watchers, message brokers.
+ * Core ships only `TimerTrigger`; HTTP/queue/file-watch adapters live in
+ * `examples/triggers/` as recipes.
+ *
+ * `runTrigger` is the canonical consumer — reads events, dispatches
+ * pipelines, optionally persists through a `JobRunner`.
+ */
+export { TimerTrigger } from './timer-trigger.js';
+export { runTrigger, } from './run-trigger.js';
+//# sourceMappingURL=index.js.map

package/dist/triggers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/triggers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,YAAY,EAA4B,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EACL,UAAU,GAGX,MAAM,kBAAkB,CAAC"}

package/dist/triggers/run-trigger.d.ts

@@ -0,0 +1,86 @@
+/**
+ * runTrigger — the canonical Trigger consumer.
+ *
+ * Reads events from a `Trigger`, calls a user-supplied factory to produce
+ * `{ phases, ctx }` per event, and dispatches each pipeline. If a
+ * `JobRunner` is supplied, dispatch is persisted (job rows, event log,
+ * cancellation); otherwise the pipeline runs inline via
+ * `runPipelineToSummary` and events are discarded after dispatch.
+ *
+ * Resolves when the trigger generator exhausts, the abort signal fires,
+ * or `stop()` is called via the returned handle.
+ *
+ * Concurrency cap is a blocking semaphore. When `maxConcurrency` pipelines
+ * are in flight, the loop awaits a slot before pulling the next event
+ * from the trigger. The trigger's generator naturally pauses production
+ * — no events are dropped, no unbounded queue grows.
+ *
+ * Pipeline failures are isolated — one failing pipeline does not stop
+ * the trigger loop. Errors go through `onError` (or default stderr log)
+ * and the next event is still dispatched.
+ *
+ * Cancellation: each in-flight dispatch owns an `AbortController`. Call
+ * `handle.cancel(triggerEventId)` to abort that specific pipeline; the
+ * signal flows into `runPipelineToSummary` (inline) or `jobRunner.cancel`
+ * (persisted). Returns `true` if the pipeline was found and aborted,
+ * `false` if the event id is unknown or already completed.
+ *
+ * Observability: `onCapacityFull(event)` fires when an event arrives
+ * while the concurrency cap is full (the loop blocks on `Promise.race`
+ * before pulling the event, so this is the moment backpressure starts).
+ * `onDispatchStart(event)` fires immediately when a dispatch begins,
+ * before the user-supplied factory runs.
+ */
+import type { JobRunner } from '../session/index.js';
+import type { BasePipelineContext, Phase } from '../phase.js';
+import type { Trigger, TriggerEvent } from './types.js';
+export interface RunTriggerOptions<TInput, TCtx extends BasePipelineContext> {
+    /**
+     * Optional JobRunner. If provided, each event creates a persisted job
+     * row and pipelines run through `runner.run()` (events go to the
+     * event log, cancellation works via `runner.cancel(jobId)`). If
+     * omitted, pipelines run inline.
+     */
+    jobRunner?: JobRunner;
+    /** Name used for job rows when `jobRunner` is set. Default: `trigger.name`. */
+    pipelineName?: string;
+    /**
+     * Maximum concurrent in-flight pipelines from this trigger. When the
+     * cap is reached, the loop blocks before pulling the next event
+     * (backpressure flows back to the trigger). Default: 1.
+     */
+    maxConcurrency?: number;
+    /** Abort the run loop and call `trigger.stop()`. Outstanding pipelines complete. */
+    signal?: AbortSignal;
+    /** Called when a pipeline is about to start, after dispatch picks it up. */
+    onStart?: (event: TriggerEvent<TInput>, jobId?: string) => void;
+    /** Called when a pipeline completes successfully. */
+    onComplete?: (event: TriggerEvent<TInput>, jobId?: string) => void;
+    /** Called when a pipeline throws. Default: log to stderr. */
+    onError?: (event: TriggerEvent<TInput>, error: Error, jobId?: string) => void;
+    /**
+     * Called when an event arrives while the concurrency cap is full —
+     * the moment backpressure begins. The dispatch still happens once a
+     * slot frees; this hook only signals the wait.
+     */
+    onCapacityFull?: (event: TriggerEvent<TInput>) => void;
+    /** Called the moment dispatch starts, before the pipeline factory runs. */
+    onDispatchStart?: (event: TriggerEvent<TInput>) => void;
+}
+export interface RunTriggerHandle {
+    /** Resolves when the run loop has exited (trigger exhausted, signal fired, or `stop()` called). */
+    done: Promise<void>;
+    /** Stop the trigger and resolve `done` once outstanding pipelines complete. */
+    stop(): Promise<void>;
+    /**
+     * Abort a specific in-flight pipeline by its trigger event id. Returns
+     * `true` if the pipeline was found and cancellation was initiated;
+     * `false` if the event id is unknown or already completed.
+     */
+    cancel(triggerEventId: number): boolean;
+}
+export declare function runTrigger<TInput, TCtx extends BasePipelineContext>(trigger: Trigger<TInput>, pipelineFactory: (input: TInput, event: TriggerEvent<TInput>) => {
+    phases: ReadonlyArray<Phase<TCtx>>;
+    ctx: TCtx;
+}, options?: RunTriggerOptions<TInput, TCtx>): RunTriggerHandle;
+//# sourceMappingURL=run-trigger.d.ts.map

package/dist/triggers/run-trigger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-trigger.d.ts","sourceRoot":"","sources":["../../src/triggers/run-trigger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EACV,mBAAmB,EACnB,KAAK,EACN,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAExD,MAAM,WAAW,iBAAiB,CAAC,MAAM,EAAE,IAAI,SAAS,mBAAmB;IACzE;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oFAAoF;IACpF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAChE,qDAAqD;IACrD,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnE,6DAA6D;IAC7D,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9E;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IACvD,2EAA2E;IAC3E,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;CACzD;AAED,MAAM,WAAW,gBAAgB;IAC/B,mGAAmG;IACnG,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB,+EAA+E;IAC/E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC;CACzC;AAQD,wBAAgB,UAAU,CAAC,MAAM,EAAE,IAAI,SAAS,mBAAmB,EACjE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,EACxB,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK;IAC/D,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACnC,GAAG,EAAE,IAAI,CAAC;CACX,EACD,OAAO,GAAE,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAM,GAC5C,gBAAgB,CA+HlB"}