openworkgraph 0.2.12

package/dist/cli.js

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { formatHelp } from './cli-help.js';
+import { SERVICE_VERSION, normalizeShortPairingCode } from "./vendor/protocol/index.js";
+import { ServiceError } from './errors.js';
+import { localControl } from './local-control.js';
+import { fileURLToPath } from 'node:url';
+import { acquireOperationsLock, manage, readInstance, requestInstance, rootPath, startBackground, waitUntilStopped } from './operations/lifecycle.js';
+import { serveManaged } from './operations/daemon.js';
+import { OperationsLog } from './operations/logs.js';
+import { withOfflineBackups, withReadBackups } from './operations/local-admin.js';
+import { writeNew, readSafe } from './operations/files.js';
+import { localCapacity } from './operations/capacity.js';
+import { registerLocalPlugin } from './operations/plugins.js';
+import { Repositories } from './persistence/repositories.js';
+import { inspectClientCode } from './client-pairing.js';
+import { createInterface } from 'node:readline/promises';
+import { acquireServiceSingleton, rememberServiceDirectory, selectedServiceDirectory } from './operations/cli-context.js';
+import { formatCliError, formatPairingResult, printOutput } from './cli-output.js';
+import { updateAgentService } from './operations/update.js';
+const rawOutputJson = process.argv.slice(2).some(argument => argument === '--output-json' || argument === '--json');
+function printPairingResult(value, outputJson = false) { console.log(formatPairingResult(value, outputJson)); }
+async function main() {
+    const { values, positionals } = parseArgs({ allowPositionals: true, options: { 'data-dir': { type: 'string' }, origin: { type: 'string' }, 'client-code': { type: 'string' }, yes: { type: 'boolean' }, json: { type: 'boolean' }, 'output-json': { type: 'boolean' }, host: { type: 'string', default: '0.0.0.0' }, port: { type: 'string', default: '14317' }, sha256: { type: 'string' }, output: { type: 'string' }, 'idempotency-key': { type: 'string' }, 'interrupt-and-stop': { type: 'boolean' }, version: { type: 'boolean' }, help: { type: 'boolean' } } });
+    const outputJson = values['output-json'] || values.json || false;
+    if (values.version) {
+        console.log(SERVICE_VERSION);
+        return;
+    }
+    if (values.help || positionals.length === 0) {
+        console.log(formatHelp());
+        return;
+    }
+    const command = positionals[0];
+    if (command === 'version') {
+        if (positionals.length !== 1)
+            throw new ServiceError('INVALID_REQUEST', 'The version command does not accept arguments.');
+        console.log(SERVICE_VERSION);
+        return;
+    }
+    if (values['data-dir'] !== undefined && command !== 'start' && command !== 'serve')
+        throw new ServiceError('INVALID_REQUEST', '--data-dir is only available for start and serve; this command uses the saved local service directory.');
+    if (!['start', 'serve', 'restart', 'update', 'stop', 'status', 'logs', 'pair', 'pair-code', 'sessions', 'revoke-session', 'capacity', 'plugin', 'backup', 'restore'].includes(command))
+        throw new ServiceError('INVALID_REQUEST', 'Unknown command. Use --help to see available commands.');
+    const starting = command === 'start' || command === 'serve';
+    const dataDir = (starting || command === 'restart' || command === 'update')
+        ? values['data-dir'] ?? await selectedServiceDirectory().catch(error => {
+            if (error instanceof ServiceError && error.code === 'SERVICE_NOT_RUNNING')
+                return undefined;
+            if (command === 'update' && error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        })
+        : await selectedServiceDirectory();
+    if (command === 'pair' || (command === 'pair-code' && values['client-code'])) {
+        if (positionals.length !== 1 || !values['client-code'] || values.origin !== undefined)
+            throw new ServiceError('INVALID_REQUEST', 'Use pair --client-code <CLIENT_CODE>; --origin is not required.');
+        const enteredCode = values['client-code'].trim();
+        const shortCode = normalizeShortPairingCode(enteredCode);
+        const clientCode = shortCode ? await manage(dataDir, 'resolve-client', shortCode) : enteredCode;
+        const { client, fingerprint } = inspectClientCode(clientCode);
+        console.error(`Client origin: ${client.origin}\nPublic key fingerprint SHA-256: ${fingerprint}\nThis client will receive runtime management access. Verify the origin and fingerprint shown in the browser.`);
+        if (!values.yes) {
+            if (!process.stdin.isTTY)
+                throw new ServiceError('INVALID_REQUEST', 'Non-interactive terminals must pass --yes to approve this client. No authorization was issued.');
+            const prompt = createInterface({ input: process.stdin, output: process.stderr });
+            let accepted;
+            try {
+                accepted = await prompt.question('Allow this client to pair? [y/N] ');
+            }
+            finally {
+                prompt.close();
+            }
+            if (!/^(y|yes)$/i.test(accepted.trim())) {
+                console.error('Cancelled. No authorization was issued.');
+                return;
+            }
+        }
+        // Only the live owner may issue a new client grant. Never bypass IPC failure
+        // by opening a running database from a second process.
+        const result = await manage(dataDir, shortCode ? 'pair-short' : 'pair-client', shortCode ? JSON.stringify({ code: shortCode, clientCode }) : clientCode);
+        printPairingResult(result, outputJson);
+        return;
+    }
+    if (command === 'plugin') {
+        if (positionals[1] !== 'register' || positionals.length !== 3)
+            throw new Error('Use plugin register TRUSTED_MANIFEST.json');
+        const manifest = (await readSafe(positionals[2], 1024 * 1024)).toString();
+        let result;
+        try {
+            result = await manage(dataDir, 'plugin-register', manifest);
+        }
+        catch {
+            result = await withOfflineBackups(dataDir, async (backups) => registerLocalPlugin(backups.db, new Repositories(backups.db).identity(), manifest));
+        }
+        printOutput('plugin register', result, outputJson);
+        return;
+    }
+    if (command === 'capacity') {
+        if (positionals.length > 2)
+            throw new Error('Unexpected capacity arguments');
+        let result;
+        try {
+            result = await manage(dataDir, 'capacity', positionals[1]);
+        }
+        catch {
+            result = await withOfflineBackups(dataDir, async (backups) => localCapacity(backups.db, positionals[1]));
+        }
+        printOutput('capacity', result, outputJson);
+        return;
+    }
+    if (['start', 'restart', 'update', 'stop', 'status', 'logs'].includes(command)) {
+        if (positionals.length !== 1)
+            throw new Error('Unexpected arguments');
+        if (command === 'update') {
+            printOutput('update', await updateAgentService(dataDir, fileURLToPath(import.meta.url), Boolean(values['interrupt-and-stop']), outputJson), outputJson);
+        }
+        else if (command === 'restart') {
+            if (!/^\d+$/.test(values.port) || Number(values.port) > 65535)
+                throw new ServiceError('INVALID_REQUEST', 'Port must be an integer from 0 to 65535');
+            let record;
+            try {
+                record = await readInstance(dataDir);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            let status;
+            if (record)
+                try {
+                    status = await requestInstance(record, 'status');
+                }
+                catch (error) {
+                    if (error.code !== 'ECONNREFUSED')
+                        throw error;
+                }
+            if (!record || !status) {
+                const args = ['--host', values.host, '--port', values.port];
+                if (dataDir)
+                    args.push('--data-dir', dataDir);
+                printOutput('restart', await startBackground(fileURLToPath(import.meta.url), args), outputJson);
+                return;
+            }
+            // Older daemons expose reachable endpoints, which cannot distinguish a
+            // wildcard listener from a loopback-only listener. Never guess its scope.
+            const hostSpecified = process.argv.slice(2).some(arg => arg === '--host' || arg.startsWith('--host='));
+            const portSpecified = process.argv.slice(2).some(arg => arg === '--port' || arg.startsWith('--port='));
+            const host = hostSpecified ? values.host : status.listenHost;
+            const port = portSpecified ? values.port : new URL(status.localEndpoint).port || '80';
+            if (!host)
+                throw new ServiceError('INVALID_REQUEST', 'The older runtime did not report its listen address. Use restart --host <ORIGINAL_ADDRESS>; the runtime has not been stopped.');
+            if (!/^\d+$/.test(port) || Number(port) > 65535)
+                throw new ServiceError('INVALID_REQUEST', 'Port must be an integer from 0 to 65535');
+            await requestInstance(record, values['interrupt-and-stop'] ? 'interrupt-and-stop' : 'stop');
+            await waitUntilStopped(record);
+            printOutput('restart', await startBackground(fileURLToPath(import.meta.url), ['--data-dir', dataDir, '--host', host, '--port', port]), outputJson);
+        }
+        else if (command === 'start') {
+            const args = ['--host', values.host, '--port', values.port];
+            if (dataDir)
+                args.push('--data-dir', dataDir);
+            printOutput('start', await startBackground(fileURLToPath(import.meta.url), args), outputJson);
+        }
+        else if (command === 'logs')
+            printOutput('logs', await new OperationsLog(rootPath(dataDir)).read(), outputJson);
+        else
+            printOutput(command, await manage(dataDir, command === 'status' ? 'status' : values['interrupt-and-stop'] ? 'interrupt-and-stop' : 'stop'), outputJson);
+        return;
+    }
+    if (command === 'backup' || command === 'restore') {
+        const action = positionals[1], path = positionals[2];
+        if (command === 'backup' && action === 'create') {
+            if (positionals.length !== 2)
+                throw new Error('Unexpected backup arguments');
+            // Online IPC is authenticated; on refusal, offline acquisition fails closed
+            // if any instance (including a maintenance operation) owns the directory.
+            let result;
+            try {
+                result = await manage(dataDir, 'backup-create', values['idempotency-key']);
+            }
+            catch {
+                result = await withOfflineBackups(dataDir, backups => backups.create(values['idempotency-key']));
+            }
+            printOutput('backup create', result, outputJson);
+            return;
+        }
+        const useBackups = command === 'restore' && action === 'apply' ? withOfflineBackups : withReadBackups;
+        const result = await useBackups(dataDir, async (backups) => {
+            if (command === 'backup' && action === 'list' && positionals.length === 2)
+                return backups.list();
+            if (command === 'backup' && action === 'download' && path && values.output && positionals.length === 3) {
+                const download = await backups.readDownload(path);
+                await writeNew(values.output, download.body);
+                return { output: values.output, bytes: download.body.length };
+            }
+            if (command === 'restore' && action === 'preview' && path && positionals.length === 3)
+                return backups.previewRestore(path);
+            if (command === 'restore' && action === 'apply' && path && values.sha256 && positionals.length === 3) {
+                await backups.restore(path, values.sha256);
+                return { restored: true, invalidatesAllSessions: true, pausesQueuedRuns: true };
+            }
+            throw new Error('Invalid backup/restore arguments; use --help');
+        });
+        printOutput(command + ' ' + action, result, outputJson);
+        return;
+    }
+    if (['pair-code', 'sessions', 'revoke-session'].includes(positionals[0])) {
+        const command = positionals[0];
+        if (command === 'pair-code' && !values.origin)
+            throw new ServiceError('INVALID_REQUEST', 'pair-code requires the web origin in --origin.');
+        if (command === 'pair-code')
+            console.error('Legacy pairing compatibility: new clients should use pair --client-code <CLIENT_CODE>; --origin is not required.');
+        if (positionals.length !== (command === 'revoke-session' ? 2 : 1))
+            throw new ServiceError('INVALID_REQUEST', 'Invalid command arguments. Use --help.');
+        // Live admin commands run inside the owning instance. Offline session
+        // inspection/revocation acquires maintenance ownership before SQLite opens.
+        try {
+            const result = await manage(dataDir, command, command === 'pair-code' ? values.origin : positionals[1]);
+            if (command === 'pair-code')
+                printPairingResult(result, outputJson);
+            else
+                printOutput(command, result, outputJson);
+            return;
+        }
+        catch { /* The kernel lock below distinguishes offline from an IPC refusal. */ }
+        const lock = await acquireOperationsLock(dataDir);
+        let control;
+        try {
+            control = localControl(lock.root);
+        }
+        catch (error) {
+            await lock.release();
+            throw error;
+        }
+        try {
+            if (command === 'pair-code')
+                printPairingResult(await control.pairingCode(values.origin), outputJson);
+            else if (command === 'sessions')
+                printOutput('sessions', control.auth.list(), outputJson);
+            else {
+                control.auth.revokeLocal(positionals[1]);
+                printOutput('revoke-session', { revoked: positionals[1], acceptedTasksUnaffected: true }, outputJson);
+            }
+        }
+        finally {
+            control.close();
+            await lock.release();
+        }
+        return;
+    }
+    if (positionals.length !== 1 || positionals[0] !== 'serve')
+        throw new ServiceError('INVALID_REQUEST', 'Unknown command. Use --help to see available commands.');
+    if (!/^\d+$/.test(values.port) || Number(values.port) > 65535)
+        throw new ServiceError('INVALID_REQUEST', 'Port must be an integer from 0 to 65535');
+    const singleton = await acquireServiceSingleton();
+    let daemon;
+    try {
+        daemon = await serveManaged(dataDir, values.host, Number(values.port), () => singleton.release());
+    }
+    catch (error) {
+        await singleton.release();
+        throw error;
+    }
+    try {
+        await rememberServiceDirectory(daemon.lock.root);
+    }
+    catch (error) {
+        await daemon.stop(true);
+        throw error;
+    }
+    const status = { ...daemon.status(), mode: 'pairing', pairingCommand: 'openworkgraph pair --client-code <CLIENT_CODE>' };
+    printOutput('status', status, outputJson);
+    if (process.send)
+        process.send({ ok: true, status });
+}
+main().catch(error => {
+    const message = error instanceof Error ? error.message : 'Startup failed';
+    if (process.send)
+        process.send({ ok: false, error: message });
+    console.error(formatCliError(error, rawOutputJson));
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/client-pairing.d.ts

@@ -0,0 +1,8 @@
+export declare function clientCodeHash(code: string): string;
+export declare function inspectClientCode(code: string): {
+    client: import("./vendor/protocol/index.js").PairingClient;
+    key: import("crypto").KeyObject;
+    fingerprint: string;
+    clientHash: string;
+};
+export declare function requirePairingProof(clientCode: string, proof: unknown, serviceId: string, origin: string, authorization: string, browserName: string): void;

package/dist/client-pairing.js

@@ -0,0 +1,30 @@
+import { createHash, createPublicKey, verify } from 'node:crypto';
+import { decodeBase64Url, parseClientCode, pairingProofMessage } from "./vendor/protocol/index.js";
+import { ServiceError } from './errors.js';
+export function clientCodeHash(code) { return createHash('sha256').update(code).digest('hex'); }
+export function inspectClientCode(code) {
+    try {
+        const client = parseClientCode(code);
+        const raw = Buffer.from(decodeBase64Url(client.publicKey, 65));
+        // OpenSSL validates that the exact uncompressed point is on P-256.
+        const key = createPublicKey({ format: 'jwk', key: { kty: 'EC', crv: 'P-256', x: raw.subarray(1, 33).toString('base64url'), y: raw.subarray(33).toString('base64url') } });
+        return { client, key, fingerprint: createHash('sha256').update(raw).digest('hex'), clientHash: clientCodeHash(code) };
+    }
+    catch {
+        throw new ServiceError('PAIRING_CODE_INVALID', 'The client code is invalid or unsupported. Copy it from the browser again.');
+    }
+}
+export function requirePairingProof(clientCode, proof, serviceId, origin, authorization, browserName) {
+    const { client, key } = inspectClientCode(clientCode);
+    if (client.origin !== origin)
+        throw new ServiceError('ORIGIN_DENIED', 'The client code does not belong to the current web origin.');
+    try {
+        const signature = decodeBase64Url(proof, 64);
+        if (signature.length !== 64 || !verify('sha256', pairingProofMessage(serviceId, origin, authorization, clientCode, browserName), { key, dsaEncoding: 'ieee-p1363' }, signature))
+            throw new Error();
+    }
+    catch {
+        throw new ServiceError('PAIRING_CODE_INVALID', 'The client private-key proof is invalid. Pair from the original page that generated the client code.');
+    }
+}
+//# sourceMappingURL=client-pairing.js.map

package/dist/directories.d.ts

@@ -0,0 +1,14 @@
+export interface DataDirectories {
+    root: string;
+    database: string;
+    config: string;
+    blobs: string;
+    staging: string;
+    runs: string;
+    backups: string;
+}
+export declare function initializeDirectories(path?: string): DataDirectories;
+export declare function runDirectories(directories: DataDirectories, runId: string): {
+    input: string;
+    output: string;
+};

package/dist/directories.js

@@ -0,0 +1,34 @@
+import { lstatSync, mkdirSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { ServiceError } from './errors.js';
+function privateDirectory(path) {
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new ServiceError('INVALID_REQUEST', 'Service directories must be real directories, not symlinks');
+    return realpathSync(path);
+}
+export function initializeDirectories(path = join(homedir(), '.openworkgraph')) {
+    const root = privateDirectory(resolve(path));
+    const result = { root, database: join(root, 'service.sqlite'), config: privateDirectory(join(root, 'config')), blobs: privateDirectory(join(root, 'blobs')), staging: privateDirectory(join(root, 'staging')), runs: privateDirectory(join(root, 'runs')), backups: privateDirectory(join(root, 'backups')) };
+    for (const file of [result.database, result.database + '-wal', result.database + '-shm']) {
+        try {
+            if (lstatSync(file).isSymbolicLink())
+                throw new ServiceError('INVALID_REQUEST', 'Database files cannot be symlinks');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return result;
+}
+export function runDirectories(directories, runId) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(runId))
+        throw new ServiceError('INVALID_REQUEST', 'Invalid Run identifier');
+    const runs = privateDirectory(directories.runs);
+    const root = privateDirectory(join(runs, runId));
+    return { input: privateDirectory(join(root, 'input')), output: privateDirectory(join(root, 'output')) };
+}
+//# sourceMappingURL=directories.js.map

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+import type { ErrorCode, Json } from "./vendor/protocol/index.js";
+interface ServiceErrorOptions extends ErrorOptions {
+    details?: Json;
+    retryable?: boolean;
+}
+export declare class ServiceError extends Error {
+    readonly code: ErrorCode;
+    readonly details: Json | undefined;
+    readonly retryable: boolean;
+    constructor(code: ErrorCode, message: string, options?: ServiceErrorOptions);
+}
+export {};

package/dist/errors.js

@@ -0,0 +1,7 @@
+export class ServiceError extends Error {
+    code;
+    details;
+    retryable;
+    constructor(code, message, options) { super(message, options); this.name = 'ServiceError'; this.code = code; this.details = options?.details; this.retryable = options?.retryable ?? false; }
+}
+//# sourceMappingURL=errors.js.map

package/dist/events.d.ts

@@ -0,0 +1,22 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { DatabaseSync } from "node:sqlite";
+import type { ServiceEvent } from "./vendor/protocol/index.js";
+import { Auth } from "./auth.js";
+export declare class Events {
+    readonly db: DatabaseSync;
+    readonly serviceId: string;
+    readonly auth: Auth;
+    private readonly closers;
+    constructor(db: DatabaseSync, serviceId: string, auth: Auth);
+    watermark(): number;
+    cursor(sessionId: string, sequence: number | string): string;
+    /** Capture before reading lists: authenticate and read the watermark in one transaction. */
+    currentCursor(token: string, origin: string): {
+        cursor: string;
+    };
+    decode(sessionId: string, cursor?: string): number;
+    replay(sessionId: string, sequence: number, limit?: number): ServiceEvent[];
+    decorate(value: unknown, sessionId: string): unknown;
+    stream(request: IncomingMessage, response: ServerResponse, token: string, origin: string): void;
+    close(): void;
+}

package/dist/events.js

@@ -0,0 +1,155 @@
+import { Auth } from "./auth.js";
+import { ServiceError } from "./errors.js";
+import { atomic } from "./persistence/database.js";
+export class Events {
+    db;
+    serviceId;
+    auth;
+    closers = new Set();
+    constructor(db, serviceId, auth) {
+        this.db = db;
+        this.serviceId = serviceId;
+        this.auth = auth;
+    }
+    watermark() {
+        return Number(this.db
+            .prepare("SELECT COALESCE((SELECT seq FROM sqlite_sequence WHERE name='events'),0) n")
+            .get()["n"]);
+    }
+    cursor(sessionId, sequence) {
+        return Buffer.from(JSON.stringify([this.serviceId, sessionId, String(sequence)])).toString("base64url");
+    }
+    /** Capture before reading lists: authenticate and read the watermark in one transaction. */
+    currentCursor(token, origin) {
+        return this.auth.withSession(token, origin, (session) => ({
+            cursor: this.cursor(session.id, this.watermark()),
+        }));
+    }
+    decode(sessionId, cursor) {
+        if (!cursor)
+            return 0;
+        try {
+            const value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+            if (!Array.isArray(value) ||
+                value.length !== 3 ||
+                value[0] !== this.serviceId ||
+                value[1] !== sessionId ||
+                typeof value[2] !== "string" ||
+                !/^\d+$/.test(value[2]))
+                throw new Error();
+            const n = Number(value[2]);
+            if (!Number.isSafeInteger(n))
+                throw new Error();
+            return n;
+        }
+        catch {
+            throw new ServiceError("INVALID_REQUEST", "事件游标不属于当前服务/会话或格式无效，请重读快照。");
+        }
+    }
+    replay(sessionId, sequence, limit = 256) {
+        return atomic(this.db, () => {
+            const floor = Number(JSON.parse(String(this.db
+                .prepare("SELECT value FROM settings WHERE key='eventFloor'")
+                .get()?.["value"] ?? "0")));
+            if (sequence < floor)
+                throw new ServiceError("CURSOR_EXPIRED", "事件游标已过期，请读取权威快照后重新订阅。");
+            if (sequence > this.watermark())
+                throw new ServiceError("INVALID_REQUEST", "事件游标超过当前水位。");
+            return this.db
+                .prepare("SELECT * FROM events WHERE sequence>? ORDER BY sequence LIMIT ?")
+                .all(sequence, limit)
+                .map((row) => ({
+                serviceId: this.serviceId,
+                cursor: this.cursor(sessionId, String(row["sequence"])),
+                eventId: String(row["id"]),
+                type: row["type"],
+                projectId: row["project_id"],
+                graphId: row["graph_id"],
+                entityId: String(row["entity_id"]),
+                revision: Number(row["revision"]),
+                occurredAt: String(row["occurred_at"]),
+                payload: JSON.parse(String(row["payload"])),
+            }));
+        });
+    }
+    decorate(value, sessionId) {
+        if (Array.isArray(value))
+            return value.map((v) => this.decorate(v, sessionId));
+        if (value && typeof value === "object" && "eventCursor" in value) {
+            const row = value;
+            return {
+                ...row,
+                eventCursor: this.cursor(sessionId, String(row["eventCursor"])),
+            };
+        }
+        return value;
+    }
+    stream(request, response, token, origin) {
+        const session = this.auth.withSession(token, origin, (current) => current);
+        let sequence = this.decode(session.id, request.headers["last-event-id"]);
+        this.replay(session.id, sequence);
+        response.writeHead(200, {
+            "Content-Type": "text/event-stream; charset=utf-8",
+            "Cache-Control": "no-store",
+            "X-Accel-Buffering": "no",
+        });
+        let stopped = false;
+        let lastHeartbeat = 0;
+        const close = () => {
+            if (stopped)
+                return;
+            stopped = true;
+            clearInterval(timer);
+            this.closers.delete(close);
+            response.end();
+        };
+        const flush = () => {
+            if (stopped || response.destroyed) {
+                close();
+                return;
+            }
+            try {
+                this.auth.assertActive(token, origin);
+                if (response.writableLength > 1024 * 1024) {
+                    close();
+                    return;
+                }
+                for (const event of this.replay(session.id, sequence)) {
+                    this.auth.assertActive(token, origin);
+                    response.write("id: " +
+                        event.cursor +
+                        "\nevent: workgraph\ndata: " +
+                        JSON.stringify(event) +
+                        "\n\n");
+                    sequence = this.decode(session.id, event.cursor);
+                }
+                if (Date.now() - lastHeartbeat > 5000) {
+                    this.auth.assertActive(token, origin);
+                    response.write(": heartbeat\n\n");
+                    lastHeartbeat = Date.now();
+                }
+            }
+            catch (error) {
+                if (!response.destroyed) {
+                    response.write("event: stream-error\ndata: " +
+                        JSON.stringify({
+                            code: error instanceof ServiceError ? error.code : "INTERNAL_ERROR",
+                            reloadSnapshot: true,
+                        }) +
+                        "\n\n");
+                }
+                close();
+            }
+        };
+        const timer = setInterval(flush, 100);
+        timer.unref();
+        this.closers.add(close);
+        response.on("close", close);
+        flush();
+    }
+    close() {
+        for (const close of [...this.closers])
+            close();
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/execution-chains.d.ts

@@ -0,0 +1,24 @@
+import { type ExecutionPlan, type GraphSnapshot, type Json, type Run, type SubmitRun } from "./vendor/protocol/index.js";
+import { Runs } from './runs.js';
+import { Graphs } from './graphs.js';
+import { Resources } from './resources.js';
+/** Accepted runs are durable submissions. Only confirmed, dependency-ready runs enter the queue. */
+export declare class ExecutionChains {
+    readonly runs: Runs;
+    readonly graphs: Graphs;
+    readonly resources: Resources;
+    private pumping;
+    private stopped;
+    stop(): void;
+    constructor(runs: Runs, graphs: Graphs, resources: Resources);
+    private get db();
+    private histories;
+    plan(graph: GraphSnapshot, targetId: string, exclude?: string): ExecutionPlan;
+    forRun(id: string): ExecutionPlan;
+    cancel(id: string, key: string, principal: string): Run;
+    selection(plan: ExecutionPlan, seeds: string[]): string[];
+    setMode(id: string, executionStart: Run['executionStart'], extra?: Record<string, Json>): void;
+    /** Prepare every missing run before entering the auth transaction. No partial batch on failure. */
+    prepareMembers(graph: GraphSnapshot, plan: ExecutionPlan, selected: string[], targetRunId: string | undefined, prepare: (request: SubmitRun) => Promise<(principal: string) => Run>): Promise<(principal: string, target?: Run) => Run>;
+    pump(): Promise<void>;
+}