openworkgraph 0.2.12

package/dist/run-api.d.ts

@@ -0,0 +1,10 @@
+import type { IncomingMessage } from 'node:http';
+import type { ApiResult } from './api.js';
+import { Auth } from './auth.js';
+import { WorkflowRuntime } from './runtime.js';
+export declare class RunApi {
+    readonly runtime: WorkflowRuntime;
+    readonly auth: Auth;
+    constructor(runtime: WorkflowRuntime, auth: Auth);
+    handle(request: IncomingMessage, path: string, token: string, origin: string): Promise<ApiResult>;
+}

package/dist/run-api.js

@@ -0,0 +1,308 @@
+import { Auth } from './auth.js';
+import { WorkflowRuntime } from './runtime.js';
+import { readJson } from './http.js';
+import { ServiceError } from './errors.js';
+import { Repositories, canonicalJson } from './persistence/repositories.js';
+import { BackendError } from './backend/types.js';
+function text(value) { if (typeof value !== 'string' || !value)
+    throw new ServiceError('INVALID_REQUEST', '需要非空字符串。'); return value; }
+function fields(body, allowed) { if (Object.keys(body).some(key => !allowed.includes(key)))
+    throw new ServiceError('INVALID_REQUEST', '请求包含未知字段。'); }
+function requireSecureCredentialConnection(request, origin) {
+    const web = new URL(origin), host = request.headers.host ?? '';
+    const remote = request.socket.remoteAddress ?? '';
+    const local = (value) => ['localhost', '127.0.0.1', '::1', '::ffff:127.0.0.1', '[::1]'].includes(value);
+    const hostName = host.startsWith('[') ? host.slice(0, host.indexOf(']') + 1) : host.split(':')[0];
+    const forwarded = request.headers['x-forwarded-proto'];
+    const forwardedProto = (Array.isArray(forwarded) ? forwarded[0] : forwarded)?.split(',')[0]?.trim().toLowerCase();
+    const secure = (request.socket.encrypted === true || forwardedProto === 'https') && web.protocol === 'https:';
+    if (!secure && !(web.protocol === 'http:' && local(web.hostname) && local(remote) && local(hostName)))
+        throw new ServiceError('HOST_DENIED', '密钥只能通过回环连接或 HTTPS 录入。');
+}
+function imageRoute(body) {
+    if (body.kind !== 'image_generation') {
+        if ('imageRoute' in body)
+            throw new ServiceError('INVALID_REQUEST', '只有图片任务可以指定生成方式。');
+        return undefined;
+    }
+    if (body.imageRoute === undefined)
+        return { type: 'codex' }; // Old clients always mean Codex.
+    const route = body.imageRoute;
+    if (!route || typeof route !== 'object' || Array.isArray(route))
+        throw new ServiceError('INVALID_REQUEST', '图片生成方式无效。');
+    const value = route;
+    const parseOptions = () => {
+        if (value.options === undefined)
+            return undefined;
+        if (!value.options || typeof value.options !== 'object' || Array.isArray(value.options))
+            throw new ServiceError('INVALID_REQUEST', '图片参数无效。');
+        const raw = value.options;
+        fields(raw, ['size', 'quality', 'aspectRatio', 'outputFormat']);
+        for (const key of ['size', 'aspectRatio'])
+            if (raw[key] !== undefined && (typeof raw[key] !== 'string' || !raw[key].trim() || raw[key].length > 60))
+                throw new ServiceError('INVALID_REQUEST', '图片参数无效。');
+        if (raw.quality !== undefined && !['auto', 'high', 'medium', 'low'].includes(String(raw.quality)))
+            throw new ServiceError('INVALID_REQUEST', '图片质量无效。');
+        if (raw.outputFormat !== undefined && !['png', 'jpeg', 'webp'].includes(String(raw.outputFormat)))
+            throw new ServiceError('INVALID_REQUEST', '图片格式无效。');
+        return raw;
+    };
+    if (value.type === 'codex') {
+        fields(value, ['type', 'options']);
+        const options = parseOptions();
+        return { type: 'codex', ...(options ? { options } : {}) };
+    }
+    if (value.type !== 'api')
+        throw new ServiceError('INVALID_REQUEST', '图片生成方式无效。');
+    fields(value, ['type', 'providerId', 'modelId', 'options']);
+    if (typeof value.providerId !== 'string' || !value.providerId.trim() || typeof value.modelId !== 'string' || !value.modelId.trim())
+        throw new ServiceError('INVALID_REQUEST', '需要有效的服务商和模型 ID。');
+    if ('modelOverride' in body || 'reasoningEffort' in body)
+        throw new ServiceError('INVALID_REQUEST', 'API 图片任务不能使用 Codex 模型或推理强度。');
+    const options = parseOptions();
+    return { type: 'api', providerId: value.providerId, modelId: value.modelId, ...(options ? { options } : {}) };
+}
+export class RunApi {
+    runtime;
+    auth;
+    constructor(runtime, auth) {
+        this.runtime = runtime;
+        this.auth = auth;
+    }
+    async handle(request, path, token, origin) {
+        const graph = /^[/]v1[/]projects[/]([a-zA-Z0-9_-]+)[/]graphs[/]([a-zA-Z0-9_-]+)[/](runs|input-preview)$/.exec(path);
+        const run = /^[/]v1[/]runs(?:[/]([a-zA-Z0-9_-]+))?(?:[/](cancel|cancel-chain|reply|history|snapshot|public-metadata|interactions|active-interaction|candidate|continue|input-changes|execution-plan|start))?$/.exec(path);
+        const notifications = path === '/v1/notifications';
+        const notificationRead = /^[/]v1[/]notifications[/]([a-zA-Z0-9_-]+)[/]read$/.exec(path);
+        const notificationReadAll = path === '/v1/notifications/read-all';
+        const history = /^[/]v1[/]history[/](preview|clear)$/.exec(path);
+        const providers = /^[/]v1[/]image-providers(?:[/]([a-zA-Z0-9_-]+)(?:[/](.+))?)?$/.exec(path);
+        if (!graph && !run && !history && !providers && !notifications && !notificationRead && !notificationReadAll && !['/v1/models', '/v1/capacity', '/v1/execution-settings'].includes(path))
+            return { handled: false };
+        const principal = this.auth.withSession(token, origin, s => s.id);
+        const body = request.method === 'POST' ? await readJson(request, 2 * 1024 * 1024) : {};
+        const read = (work) => this.auth.withSession(token, origin, work);
+        const ok = (value) => ({ handled: true, body: value });
+        const rt = this.runtime, repo = new Repositories(rt.db);
+        if (notifications && request.method === 'GET')
+            return ok(read(() => rt.runs.notifications()));
+        if (notificationRead && request.method === 'POST') {
+            fields(body, ['expectedRevision']);
+            return ok(read(() => rt.runs.readNotification(notificationRead[1], body.expectedRevision)));
+        }
+        if (notificationReadAll && request.method === 'POST') {
+            fields(body, []);
+            return ok(read(() => rt.runs.readAllNotifications()));
+        }
+        if (providers) {
+            if (request.method === 'GET' && !providers[1]) {
+                await rt.imageProviders.refreshCredentials();
+                return ok(read(() => rt.imageProviders.list()));
+            }
+            if (request.method === 'POST') {
+                if (providers[1]) {
+                    if (providers[2] === 'delete') {
+                        fields(body, ['expectedRevision']);
+                        return ok(read(() => { rt.imageProviders.deleteProvider(providers[1], body.expectedRevision); return { deleted: true }; }));
+                    }
+                    if (providers[2] === 'models/discover') {
+                        fields(body, ['expectedRevision']);
+                        if (!Number.isSafeInteger(body.expectedRevision))
+                            throw new ServiceError('INVALID_REQUEST', '需要有效的修订号。');
+                        this.auth.assertActive(token, origin);
+                        const result = await rt.discoverImageModels(providers[1], body.expectedRevision);
+                        return ok(read(() => result));
+                    }
+                    if (providers[2] === 'models/select') {
+                        fields(body, ['models', 'expectedRevision']);
+                        if (!Array.isArray(body.models) || !Number.isSafeInteger(body.expectedRevision))
+                            throw new ServiceError('INVALID_REQUEST', '模型选择无效。');
+                        return ok(read(() => rt.imageProviders.syncDiscoveredModels(providers[1], body.models, body.expectedRevision)));
+                    }
+                    if (providers[2] === 'models/delete') {
+                        fields(body, ['modelId', 'expectedRevision']);
+                        if (typeof body.modelId !== 'string')
+                            throw new ServiceError('INVALID_REQUEST', '图片模型 ID 无效。');
+                        return ok(read(() => rt.imageProviders.deleteModel(providers[1], body.modelId, body.expectedRevision)));
+                    }
+                    const modelAction = /^models[/]([^/]+)[/]delete$/.exec(providers[2] ?? '');
+                    let actionModel;
+                    if (modelAction) {
+                        try {
+                            actionModel = decodeURIComponent(modelAction[1]);
+                        }
+                        catch {
+                            throw new ServiceError('INVALID_REQUEST', '图片模型 ID 无效。');
+                        }
+                    }
+                    if (modelAction) {
+                        fields(body, ['expectedRevision']);
+                        return ok(read(() => rt.imageProviders.deleteModel(providers[1], actionModel, body.expectedRevision)));
+                    }
+                    if (providers[2] === 'credential' || providers[2] === 'credential-revoke') {
+                        fields(body, providers[2] === 'credential' ? ['secret', 'expectedRevision'] : ['expectedRevision']);
+                        requireSecureCredentialConnection(request, origin);
+                        if (!Number.isSafeInteger(body.expectedRevision))
+                            throw new ServiceError('INVALID_REQUEST', '需要有效的修订号。');
+                        this.auth.assertActive(token, origin);
+                        const result = providers[2] === 'credential'
+                            ? await rt.imageProviders.setCredential(providers[1], body.secret, body.expectedRevision)
+                            : await rt.imageProviders.revokeCredential(providers[1], body.expectedRevision);
+                        return ok(read(() => result));
+                    }
+                    fields(body, ['id', 'name', 'modes', 'formats', 'sizes', 'qualities', 'isDefault', 'expectedRevision']);
+                    return ok(read(() => rt.imageProviders.setModel(providers[1], body, body.expectedRevision)));
+                }
+                fields(body, ['id', 'name', 'driver', 'endpoint', 'enabled', 'expectedRevision']);
+                return ok(read(() => rt.imageProviders.setProvider(body, body.expectedRevision)));
+            }
+        }
+        if (path === '/v1/execution-settings') {
+            if (request.method === 'GET')
+                return ok(read(() => rt.executionSettings.get()));
+            if (request.method === 'POST') {
+                fields(body, ['sandboxMode', 'expectedRevision']);
+                return ok(read(() => rt.executionSettings.set(body.sandboxMode, body.expectedRevision)));
+            }
+        }
+        if (path === '/v1/models') {
+            if (request.method === 'GET') {
+                await rt.refreshModels();
+                return ok(read(() => rt.models.get(rt.catalog)));
+            }
+            if (request.method === 'POST') {
+                fields(body, ['selection', 'expectedRevision']);
+                const selection = body.selection;
+                if (!selection || typeof selection !== 'object' || Array.isArray(selection) || typeof selection.model !== 'string' || !selection.model || !(selection.reasoningEffort === null || typeof selection.reasoningEffort === 'string') || Object.keys(selection).some(k => !['model', 'reasoningEffort'].includes(k)) || !Number.isSafeInteger(body.expectedRevision))
+                    throw new ServiceError('INVALID_REQUEST', '模型配置无效。');
+                try {
+                    return ok(read(() => rt.models.set(selection, body.expectedRevision, rt.catalog)));
+                }
+                catch (error) {
+                    if (error instanceof BackendError)
+                        throw new ServiceError(error.code === 'CONFLICT' ? 'REVISION_CONFLICT' : 'MODEL_UNAVAILABLE', error.message);
+                    throw error;
+                }
+            }
+        }
+        if (path === '/v1/capacity' && request.method === 'GET')
+            return ok(read(() => rt.runs.capacity()));
+        if (graph) {
+            const scope = { serviceId: rt.serviceId, projectId: graph[1], graphId: graph[2] };
+            read(() => rt.graphs.scope(scope));
+            if (graph[3] === 'input-preview' && request.method === 'POST') {
+                fields(body, ['nodeId', 'excludeFiles']);
+                if (body.excludeFiles !== undefined && typeof body.excludeFiles !== 'boolean')
+                    throw new ServiceError('INVALID_REQUEST', '无效输入预检选项');
+                return ok(read(() => rt.inputs.inputPreview(scope.graphId, text(body.nodeId), body.excludeFiles === true)));
+            }
+            if (graph[3] === 'runs' && request.method === 'GET')
+                return ok(read(() => rt.runs.list(scope.projectId).filter(value => value.graphId === scope.graphId)));
+            if (graph[3] === 'runs' && request.method === 'POST') {
+                fields(body, ['nodeId', 'kind', 'idempotencyKey', 'expectedExecutionRevision', 'modelOverride', 'imageRoute']);
+                const route = imageRoute(body);
+                const input = { ...body, ...scope, ...(route ? { imageRoute: route } : {}) };
+                text(input.nodeId);
+                text(input.idempotencyKey);
+                let prior;
+                try {
+                    prior = read(() => repo.replay(principal + ':run.submit', input.idempotencyKey, input));
+                }
+                catch (error) {
+                    // Old persisted request hashes predate imageRoute. Only retry the exact old
+                    // body for a legacy image request; all other key collisions still fail.
+                    if (!(error instanceof ServiceError && error.code === 'IDEMPOTENCY_CONFLICT' && body.kind === 'image_generation' && !('imageRoute' in body)))
+                        throw error;
+                    prior = read(() => repo.replay(principal + ':run.submit', input.idempotencyKey, { ...body, ...scope }));
+                }
+                if (prior !== undefined)
+                    return ok(prior && typeof prior === 'object' && !Array.isArray(prior) && 'executionStart' in prior ? read(() => rt.runs.get(String(prior.id))) : prior);
+                const commit = await rt.prepareSubmission(input);
+                return ok(read(() => commit(principal)));
+            }
+        }
+        if (history && request.method === 'POST') {
+            fields(body, history[1] === 'clear' ? ['runIds', 'idempotencyKey'] : ['runIds']);
+            return ok(read(() => history[1] === 'preview' ? rt.history.preview(body.runIds) : rt.history.clear(body.runIds, principal + ':' + text(body.idempotencyKey))));
+        }
+        if (run) {
+            const id = run[1], action = run[2];
+            if (request.method === 'GET' && !id)
+                return ok(read(() => rt.runs.list()));
+            if (id) {
+                const current = read(() => rt.runs.get(id));
+                if (request.method === 'GET' && action === 'execution-plan')
+                    return ok(read(() => rt.executionChains.forRun(id)));
+                if (request.method === 'POST' && action === 'start') {
+                    fields(body, ['nodeIds', 'expectedExecutionRevision', 'idempotencyKey']);
+                    const key = text(body.idempotencyKey);
+                    if (!Array.isArray(body.nodeIds) || body.nodeIds.some(v => typeof v !== 'string') || !Number.isSafeInteger(body.expectedExecutionRevision))
+                        throw new ServiceError('INVALID_REQUEST', '无效执行范围。');
+                    const data = { nodeIds: body.nodeIds, expectedExecutionRevision: body.expectedExecutionRevision };
+                    const prior = read(() => repo.replay(principal + ':run.start:' + id, key, data));
+                    if (prior !== undefined)
+                        return ok(read(() => rt.runs.get(id)));
+                    const commit = await rt.prepareExecutionStart(id, body.nodeIds, body.expectedExecutionRevision);
+                    return ok(read(() => commit(principal, key)));
+                }
+                if (request.method === 'GET' && !action)
+                    return ok(current);
+                if (request.method === 'GET' && action === 'history')
+                    return ok(read(() => rt.history.records(id)));
+                if (request.method === 'GET' && action === 'active-interaction')
+                    return ok(read(() => rt.runs.activeInteraction(id)));
+                if (request.method === 'GET' && action === 'snapshot')
+                    return ok(read(() => rt.runs.snapshot(id)));
+                if (request.method === 'GET' && action === 'public-metadata')
+                    return ok(read(() => {
+                        const snapshot = rt.runs.snapshot(id), details = rt.runs.runtime(id).details;
+                        const result = details.result;
+                        const publicId = result && typeof result === 'object' && !Array.isArray(result) ? result.requestId : null;
+                        return { imageRoute: snapshot.imageRoute ?? { type: 'codex' }, inputMode: snapshot.inputMode ?? null, requestId: typeof publicId === 'string' && /^[a-zA-Z0-9_-]{1,100}$/.test(publicId) ? publicId : null };
+                    }));
+                if (request.method === 'GET' && action === 'input-changes')
+                    return ok(read(() => {
+                        // Compare editable reference inputs with the submission snapshot; execution
+                        // outputs are bound later and must not look like user edits on every poll.
+                        const snapshot = JSON.parse(String(rt.db.prepare('SELECT payload FROM snapshots WHERE run_id=?').get(id).payload)), preview = rt.inputs.inputPreview(current.graphId, current.nodeId);
+                        if (preview.issues.length)
+                            return { state: 'unknown', issues: preview.issues };
+                        const before = canonicalJson({ prompt: snapshot.prompt, resources: snapshot.resources, projectFiles: snapshot.projectFiles ?? [] });
+                        const after = canonicalJson({ prompt: preview.prompt, resources: preview.resources, projectFiles: preview.projectFiles });
+                        const dependencies = rt.runs.runtime(id).details.chainDependencies;
+                        const bound = Array.isArray(dependencies) ? dependencies.map(runId => rt.runs.get(String(runId)).nodeId).sort() : null;
+                        const live = bound ? rt.graphs.snapshot(current).edges.filter(e => e.kind === 'execution' && e.targetId === current.nodeId).map(e => e.sourceId).sort() : null;
+                        return { state: before === after && JSON.stringify(bound) === JSON.stringify(live) ? 'unchanged' : 'changed', issues: [] };
+                    }));
+                if (request.method === 'GET' && action === 'interactions')
+                    return ok(read(() => rt.db.prepare('SELECT id FROM interactions WHERE run_id=? ORDER BY rowid').all(id).map(row => rt.runs.interaction(String(row.id)))));
+                if (request.method === 'GET' && action === 'candidate')
+                    return ok(read(() => { const row = rt.db.prepare('SELECT base_version,content,state FROM generation_candidates WHERE run_id=?').get(id); return row ? { baseVersion: row.base_version, content: JSON.parse(String(row.content)), state: row.state } : null; }));
+                if (request.method === 'POST' && action === 'cancel') {
+                    fields(body, ['idempotencyKey']);
+                    return ok(read(() => rt.runs.cancel(id, text(body.idempotencyKey), principal)));
+                }
+                if (request.method === 'POST' && action === 'cancel-chain') {
+                    fields(body, ['idempotencyKey']);
+                    return ok(read(() => rt.executionChains.cancel(id, text(body.idempotencyKey), principal)));
+                }
+                if (request.method === 'POST' && action === 'continue') {
+                    fields(body, ['idempotencyKey']);
+                    const key = text(body.idempotencyKey);
+                    const commit = await rt.prepareContinuation(id);
+                    return ok(read(() => commit(principal, key)));
+                }
+                if (request.method === 'POST' && action === 'reply') {
+                    fields(body, ['interactionId', 'epoch', 'expectedVersion', 'idempotencyKey', 'answer']);
+                    return ok(read(() => rt.runs.reply({ ...body, runId: id }, principal)));
+                }
+                if (request.method === 'POST' && action === 'candidate') {
+                    fields(body, ['idempotencyKey', 'decision', 'expectedContentVersion']);
+                    return ok(read(() => repo.idempotent(principal + ':candidate:' + id, text(body.idempotencyKey), body, () => rt.publication.decide({ ...current, runId: id, decision: body.decision, expectedContentVersion: body.expectedContentVersion }))));
+                }
+            }
+        }
+        throw new ServiceError('NOT_FOUND', '运行接口不存在。');
+    }
+}
+//# sourceMappingURL=run-api.js.map

package/dist/run-context.d.ts

@@ -0,0 +1,54 @@
+import type { Run } from "./vendor/protocol/index.js";
+import { Runs } from './runs.js';
+import { type DataDirectories } from './directories.js';
+export interface RunContextRequest {
+    runId: string;
+    section: 'summary' | 'snapshot' | 'history' | 'outputs' | 'output';
+    outputKey?: string;
+    offset?: number;
+}
+export interface RunLineage {
+    version: 1;
+    projectId: string;
+    rootRunId: string;
+    nodes: RunDescription[];
+    edges: {
+        sourceRunId: string;
+        targetRunId: string;
+    }[];
+}
+interface RunDescription {
+    runId: string;
+    nodeId: string;
+    graphId: string;
+    status: Run['status'];
+    inputDigest: string;
+    historyState: Run['historyState'];
+    predecessorRunIds: string[];
+    lineageRecorded: boolean;
+    outputs: ReturnType<RunContexts['outputs']>;
+    nodeSnapshot: {
+        contentVersion: number | null;
+        title: string | null;
+        promptPreview: string;
+        promptTruncated: boolean;
+        executionRevision: number;
+    };
+}
+/** Run identities, not live graph edges, define historical ancestry. */
+export declare class RunContexts {
+    readonly runs: Runs;
+    readonly dirs: DataDirectories;
+    private readonly copies;
+    constructor(runs: Runs, dirs: DataDirectories);
+    private scoped;
+    describe(run: Run): RunDescription;
+    lineage(runId: string): RunLineage;
+    outputs(run: Run): {
+        canvas: Record<string, import("node:sqlite").SQLOutputValue>[];
+        projectFiles: Record<string, import("node:sqlite").SQLOutputValue>[];
+        projectFileNotice: string;
+    };
+    read(callerRunId: string, request: RunContextRequest): Promise<string>;
+}
+export {};

package/dist/run-context.js

@@ -0,0 +1,137 @@
+import { Runs } from './runs.js';
+import { ServiceError } from './errors.js';
+import { materializeInputs } from './input-materialization.js';
+import { runDirectories } from './directories.js';
+/** Run identities, not live graph edges, define historical ancestry. */
+export class RunContexts {
+    runs;
+    dirs;
+    copies = new Map();
+    constructor(runs, dirs) {
+        this.runs = runs;
+        this.dirs = dirs;
+    }
+    scoped(caller, id) {
+        if (typeof id !== 'string' || !id || id.length > 200)
+            throw new ServiceError('INVALID_REQUEST', 'A valid Run ID is required');
+        if (!this.runs.db.prepare('SELECT 1 FROM runs WHERE id=? AND project_id=?').get(id, caller.projectId))
+            throw new ServiceError('NOT_FOUND', 'Run is unavailable in the current project');
+        return this.runs.get(id);
+    }
+    describe(run) {
+        const details = this.runs.runtime(run.id).details;
+        const dependencies = details.chainDependencies;
+        if (dependencies !== undefined && (!Array.isArray(dependencies) || dependencies.some(id => typeof id !== 'string')))
+            throw new ServiceError('INPUT_BLOCKED', 'Invalid persisted Run lineage');
+        const predecessorRunIds = [...new Set((dependencies ?? []))];
+        const snapshot = this.runs.snapshot(run.id);
+        const version = typeof details.baseVersion === 'number' ? details.baseVersion : null;
+        const row = version === null ? undefined : this.runs.db.prepare('SELECT content FROM node_versions WHERE node_id=? AND version=?').get(run.nodeId, version);
+        const content = row ? JSON.parse(String(row.content)) : null;
+        return {
+            runId: run.id, nodeId: run.nodeId, graphId: run.graphId, status: run.status,
+            inputDigest: snapshot.inputDigest, historyState: run.historyState, predecessorRunIds, lineageRecorded: dependencies !== undefined, outputs: this.outputs(run),
+            nodeSnapshot: { contentVersion: version, title: typeof content?.title === 'string' ? content.title : null,
+                promptPreview: snapshot.prompt.slice(0, 2000), promptTruncated: snapshot.prompt.length > 2000, executionRevision: snapshot.executionRevision },
+        };
+    }
+    lineage(runId) {
+        const root = this.runs.get(runId);
+        const nodes = [], edges = [];
+        const visited = new Set(), active = new Set();
+        const stack = [{ id: runId, exit: false }];
+        while (stack.length) {
+            const entry = stack.pop();
+            if (entry.exit) {
+                active.delete(entry.id);
+                visited.add(entry.id);
+                continue;
+            }
+            if (active.has(entry.id))
+                throw new ServiceError('INPUT_BLOCKED', 'Persisted Run lineage contains a cycle');
+            if (visited.has(entry.id))
+                continue;
+            if (nodes.length >= 10000)
+                throw new ServiceError('INPUT_BUDGET_EXCEEDED', 'Run lineage exceeds 10000 runs');
+            const node = this.describe(this.scoped(root, entry.id));
+            nodes.push(node);
+            active.add(entry.id);
+            stack.push({ id: entry.id, exit: true });
+            for (const id of node.predecessorRunIds) {
+                edges.push({ sourceRunId: id, targetRunId: entry.id });
+                stack.push({ id, exit: false });
+            }
+        }
+        return { version: 1, projectId: root.projectId, rootRunId: runId, nodes, edges };
+    }
+    outputs(run) {
+        const canvas = this.runs.db.prepare(`SELECT o.output_key AS outputKey, o.resource_id AS resourceId,
+      o.resource_version AS version, v.mime, v.sha256, b.bytes
+      FROM canvas_outputs o JOIN canvas_resource_versions v ON v.resource_id=o.resource_id AND v.version=o.resource_version
+      JOIN blobs b ON b.sha256=v.sha256 WHERE o.run_id=? AND o.graph_id=? ORDER BY o.output_key`).all(run.id, run.graphId);
+        const projectFiles = this.runs.db.prepare(`SELECT output_key AS outputKey, relative_path AS relativePath, bytes, sha256
+      FROM project_file_outputs WHERE run_id=? AND project_id=? ORDER BY output_key`).all(run.id, run.projectId);
+        return { canvas, projectFiles, projectFileNotice: 'Project file paths refer to the live working tree, not frozen historical file contents. Verify their hashes before assuming they match this Run.' };
+    }
+    async read(callerRunId, request) {
+        if (!request || typeof request !== 'object' || Array.isArray(request) ||
+            Object.keys(request).some(key => !['runId', 'section', 'outputKey', 'offset'].includes(key)) ||
+            !['summary', 'snapshot', 'history', 'outputs', 'output'].includes(request.section) ||
+            !Number.isSafeInteger(request.offset ?? 0) || (request.offset ?? 0) < 0 ||
+            (request.section === 'output' ? typeof request.outputKey !== 'string' || !request.outputKey || request.outputKey.length > 1024 : request.outputKey !== undefined))
+            throw new ServiceError('INVALID_REQUEST', 'Invalid Run context request');
+        const caller = this.runs.get(callerRunId), target = this.scoped(caller, request.runId);
+        let value;
+        switch (request.section) {
+            case 'summary':
+                value = this.describe(target);
+                break;
+            case 'snapshot':
+                value = this.runs.snapshot(target.id);
+                break;
+            case 'outputs':
+                value = this.outputs(target);
+                break;
+            case 'history':
+                value = { historyState: target.historyState, records: target.historyState === 'cleared' ? [] :
+                        this.runs.db.prepare('SELECT id,occurred_at AS occurredAt,kind,payload FROM run_process_records WHERE run_id=? ORDER BY id').all(target.id)
+                            .map(row => ({ ...row, payload: JSON.parse(String(row.payload)) })) };
+                break;
+            case 'output': {
+                const output = this.outputs(target).canvas.find(item => item.outputKey === request.outputKey);
+                if (!output)
+                    throw new ServiceError('NOT_FOUND', 'Published canvas output unavailable; no newer Run or live project file is substituted');
+                const resource = { resourceId: String(output.resourceId), version: Number(output.version), mime: String(output.mime),
+                    sha256: String(output.sha256), bytes: Number(output.bytes), representationVersion: null };
+                const key = JSON.stringify([callerRunId, target.id, request.outputKey, resource.sha256]);
+                let copy = this.copies.get(key);
+                if (!copy) {
+                    const snapshot = { inputDigest: '', executionRevision: 0, prompt: '', model: { model: '', reasoningEffort: null },
+                        resources: [{ kind: 'file', text: null, sourceNodeIds: [target.nodeId], resource }] };
+                    copy = materializeInputs(snapshot, { inputDirectory: runDirectories(this.dirs, callerRunId).input, blobDirectory: this.dirs.blobs,
+                        resolveBlobPath: sha => {
+                            const row = this.runs.db.prepare('SELECT path FROM resource_blob_files WHERE sha256=?').get(sha);
+                            if (!row)
+                                throw new ServiceError('NOT_FOUND', 'Published output bytes are unavailable');
+                            return String(row.path);
+                        } });
+                    this.copies.set(key, copy);
+                    copy.catch(() => this.copies.delete(key));
+                }
+                const file = (await copy).files[0];
+                value = { ...output, path: file.path, notice: 'Verified immutable output copied to the current Run input directory. Read this file using the available file tools.' };
+                break;
+            }
+        }
+        // Page serialized data inside a valid JSON envelope; never truncate the wire JSON.
+        const serialized = JSON.stringify(value), offset = request.offset ?? 0;
+        if (offset > serialized.length)
+            throw new ServiceError('INVALID_REQUEST', 'Offset exceeds section length');
+        let end = Math.min(offset + 4000, serialized.length);
+        if (end < serialized.length && /[\uD800-\uDBFF]/.test(serialized[end - 1]))
+            end--;
+        return JSON.stringify({ runId: target.id, section: request.section, encoding: 'json-text', offset,
+            nextOffset: end < serialized.length ? end : null, totalCharacters: serialized.length, text: serialized.slice(offset, end) });
+    }
+}
+//# sourceMappingURL=run-context.js.map

package/dist/runs.d.ts

@@ -0,0 +1,82 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { InputSnapshot, Interaction, InteractionReply, Json, Run, RunNotification, RunStatus, SubmitRun, SandboxMode } from "./vendor/protocol/index.js";
+import { Repositories } from './persistence/repositories.js';
+export interface RunContext {
+    runId: string;
+    projectId: string;
+    graphId: string;
+    nodeId: string;
+    kind: SubmitRun['kind'];
+    baseVersion: number;
+    canonicalPath: string;
+    publicationVersion: 1 | 2;
+    sandboxMode?: SandboxMode;
+}
+export interface RunsDependencies {
+    /** Synchronous: extraction/preflight caches must already be prepared. */
+    freeze: (request: SubmitRun, context: RunContext) => InputSnapshot;
+    validate?: (request: SubmitRun, context: RunContext) => void;
+    validateReply?: (interaction: Interaction, answer: Json) => void;
+    now?: () => number;
+}
+export interface RunToken {
+    epoch: string;
+    revision: number;
+}
+export interface RunRuntime extends RunToken {
+    details: {
+        [key: string]: Json;
+    };
+}
+/** All authoritative changes are short synchronous transactions (safe inside Auth). */
+export declare class Runs {
+    readonly db: DatabaseSync;
+    readonly serviceId: string;
+    readonly dependencies: RunsDependencies;
+    readonly repo: Repositories;
+    readonly now: () => number;
+    constructor(db: DatabaseSync, serviceId: string, dependencies: RunsDependencies);
+    get(id: string): Run;
+    list(projectId?: string): Run[];
+    notifications(): RunNotification[];
+    readNotification(id: string, expectedRevision: number): {
+        read: boolean;
+    };
+    readAllNotifications(): {
+        read: number;
+    };
+    runtime(id: string): RunRuntime;
+    snapshot(id: string): InputSnapshot;
+    private event;
+    private refreshNotification;
+    record(id: string, kind: string, payload: Json): void;
+    submit(request: SubmitRun, principal?: string, holdExecution?: boolean): Run;
+    capacity(): {
+        capacity: number;
+        occupied: number;
+        available: number;
+    };
+    /** ExecutionChains enqueues only dependency-ready runs. Claim those in persisted
+     * order up to capacity, without serializing unrelated nodes by project or batch. */
+    claimNext(epoch: string, excludedProjectIds?: readonly string[], eligible?: (run: Run, snapshot: InputSnapshot) => boolean): Run | null;
+    /** Persist the uncertain spawn boundary BEFORE calling an external backend. */
+    markBackendLaunching(id: string, token: RunToken): RunToken;
+    /** Only a known lock-contention result BEFORE the spawn boundary can requeue.
+     * No generic preparing -> queued transition is allowed after uncertain launch. */
+    requeueUnstarted(id: string, token: RunToken): Run;
+    transition(id: string, token: RunToken, next: RunStatus, details?: {
+        [key: string]: Json;
+    }): Run;
+    cancel(id: string, key: string, principal?: string): Run;
+    interaction(id: string): Interaction;
+    /** Oldest independent action whose reply has not been acknowledged by its responder. */
+    activeInteraction(id: string): Interaction | null;
+    acknowledgeReply(id: string, epoch: string, interactionId: string): Run;
+    openInteraction(id: string, token: RunToken, kind: Interaction['kind'], payload: Json, interactionId?: string): Interaction;
+    private expireInteractions;
+    reply(request: InteractionReply, sessionId: string, principal?: string): Interaction;
+    /** Caller must first establish previous service ownership is stale (not just a PID check). */
+    recover(epoch: string): Run[];
+    /** A new service instance must not replay or retain ownership of old work. */
+    abandonOnRestart(epoch: string): Run[];
+}