openworkgraph 0.2.12

package/README.md

@@ -0,0 +1,64 @@
+# OpenWorkgraph
+
+OpenWorkgraph 是基于无限画布思想的软件开发工作流产品，同时面向其他领域的工作组织与协作。
+
+## 快速开始
+
+打开 [OpenWorkgraph 官方编辑器](https://workgraph.giarld.com/)，按照页面提供的引导完成配置即可开始使用。
+
+## 本地构建与运行
+
+### Agent Service
+
+在仓库根目录构建协议包和 Agent Service：
+
+```sh
+npm run build
+```
+
+构建完成后，以前台方式运行 Agent Service：
+
+```sh
+node agent-service/dist/cli.js start
+```
+
+### Web Client
+
+在仓库根目录构建 Web Client，并通过 Vite Preview 在 `http://127.0.0.1:4173` 运行生产构建：
+
+```sh
+npm --prefix web-client run build
+npm --prefix web-client run preview -- --host 127.0.0.1 --port 4173
+```
+
+打开 Web Client 后，填写运行时地址并点击“生成客户端码”。在运行时所在机器执行以下命令，输入浏览器显示的 8 位客户端码，核对来源和公钥指纹后确认；浏览器会轮询批准状态，完成私钥证明和通讯凭据交换后自动连接：
+
+```sh
+node agent-service/dist/cli.js pair --client-code '<客户端码>'
+```
+
+客户端码显示为连续 8 位数字，例如 `12345678`，中间没有空格，5 分钟有效。终端默认输出英文可读的批准结果；仅脚本需要解析时加 `--output-json`（非交互批准还需 `--yes`）。
+
+一机只运行一个服务。`--data-dir` 仅用于 `start` 和 `serve`；启动成功后自动记住目录，配对、查看状态、停止、日志和备份命令都无需再填写。停服后运行 `start` 会沿用原目录，首次启动未指定时使用用户主目录下的 `.openworkgraph`。重复启动会明确拒绝，不提供服务选择或切换步骤。
+
+无需手填 `--origin`，不强制 HTTPS，支持可信局域网普通 HTTP。HTTP 不加密，请勿暴露公网。
+
+### 检查与测试
+
+```sh
+npm test
+npm --prefix web-client run typecheck
+npm --prefix web-client test
+npm --prefix web-client run build
+npm --prefix web-client run test:e2e
+```
+
+以上命令在仓库根目录执行；Web 构建输出为 `web-client/dist/`，浏览器测试使用已安装的 Chrome。
+
+## 参考依据与致谢
+
+Web UI 参考了 [basketikun/infinite-canvas](https://github.com/basketikun/infinite-canvas) 的视觉风格和画布交互，感谢原作者 basketikun。该项目采用 [MIT License](https://github.com/basketikun/infinite-canvas/blob/d213a74614e0e4bd8a26383d1e1e907249e9c61b/LICENSE)；复用其代码或其他适用内容时，应保留原版权与许可声明。第三方素材若有独立授权，以其各自许可为准。
+
+## 许可证
+
+本项目采用 [MIT License](LICENSE)。第三方来源的版权与许可声明按原始归属保留。

package/dist/api-image-agent.d.ts

@@ -0,0 +1,32 @@
+import type { InputSnapshot, Interaction, Json, Run } from "./vendor/protocol/index.js";
+import type { SchedulerBackend, BackendContext, ReconcileResult } from './scheduler.js';
+import { Runs } from './runs.js';
+import { Resources } from './resources.js';
+import { ImageProviders } from './image-providers.js';
+import { ImageCredentials } from './image-credentials.js';
+import { type DataDirectories } from './directories.js';
+/** No project file/tool access: only the accepted Run's immutable canvas blobs,
+ * its empty output directory and the registered frozen provider API base URL. */
+export declare class ApiImageAgent implements SchedulerBackend {
+    readonly runs: Runs;
+    readonly resources: Resources;
+    readonly providers: ImageProviders;
+    readonly credentials: ImageCredentials;
+    readonly dirs: DataDirectories;
+    private readonly pending;
+    constructor(runs: Runs, resources: Resources, providers: ImageProviders, credentials: ImageCredentials, dirs: DataDirectories);
+    start(run: Run, snapshot: InputSnapshot, context: BackendContext): Promise<void>;
+    cancel(run: Run, context: BackendContext): Promise<'confirmed' | 'unknown'>;
+    reconcile(run: Run, _context: BackendContext): Promise<ReconcileResult>;
+}
+export declare class RoutedImageBackend implements SchedulerBackend {
+    readonly codex: SchedulerBackend;
+    readonly api: ApiImageAgent;
+    readonly runs: Runs;
+    constructor(codex: SchedulerBackend, api: ApiImageAgent, runs: Runs);
+    private delegate;
+    start(run: Run, snapshot: InputSnapshot, context: BackendContext): Promise<void>;
+    cancel(run: Run, context: BackendContext): Promise<'confirmed' | 'unknown'>;
+    reconcile(run: Run, context: BackendContext): Promise<ReconcileResult>;
+    reply(run: Run, interaction: Interaction, answer: Json, context: BackendContext): Promise<void>;
+}

package/dist/api-image-agent.js

@@ -0,0 +1,132 @@
+import { Runs } from './runs.js';
+import { Resources } from './resources.js';
+import { ImageProviders } from './image-providers.js';
+import { ImageCredentials } from './image-credentials.js';
+import { ServiceError } from './errors.js';
+import { planOpenAiImage, executeOpenAiImage } from './openai-image-driver.js';
+import { stageApiImageOutput } from './api-image-output.js';
+import { runDirectories } from './directories.js';
+/** No project file/tool access: only the accepted Run's immutable canvas blobs,
+ * its empty output directory and the registered frozen provider API base URL. */
+export class ApiImageAgent {
+    runs;
+    resources;
+    providers;
+    credentials;
+    dirs;
+    pending = new Map();
+    constructor(runs, resources, providers, credentials, dirs) {
+        this.runs = runs;
+        this.resources = resources;
+        this.providers = providers;
+        this.credentials = credentials;
+        this.dirs = dirs;
+    }
+    async start(run, snapshot, context) {
+        const route = snapshot.imageRoute;
+        if (!route || route.type !== 'api')
+            throw new ServiceError('INVALID_REQUEST', 'API 执行器只能运行冻结的 API 图片任务。');
+        const controller = new AbortController();
+        this.pending.set(run.id, controller);
+        let phase = 'preparing';
+        try {
+            if (this.runs.db.prepare('SELECT 1 FROM image_provider_revoked_credentials WHERE provider_id=? AND revision=?').get(route.providerId, route.credentialRevision))
+                throw new ServiceError('MODEL_UNAVAILABLE', '冻结凭据已撤销。');
+            const secret = await this.credentials.read(route.providerId, route.credentialRevision);
+            if (!secret)
+                throw new ServiceError('MODEL_UNAVAILABLE', '冻结凭据版本不在本机。');
+            const frozen = this.providers.frozen(route.providerId, route.configRevision, route.modelId);
+            const references = [];
+            for (const envelope of snapshot.resources) {
+                if (envelope.kind !== 'image' || !envelope.resource)
+                    continue;
+                const metadata = this.resources.readCanvasVersion(run, envelope.resource.resourceId, envelope.resource.version);
+                if (metadata.sha256 !== envelope.resource.sha256 || metadata.bytes !== envelope.resource.bytes)
+                    throw new ServiceError('INPUT_BLOCKED', '冻结参考图版本已变化。');
+                const content = await this.resources.readContent(run, 'canvas', envelope.resource.resourceId, envelope.resource.version);
+                if (!['image/png', 'image/jpeg', 'image/webp'].includes(content.mime))
+                    throw new ServiceError('INPUT_BLOCKED', '参考图格式不支持。');
+                references.push({ bytes: content.bytes, mime: content.mime });
+            }
+            const plan = planOpenAiImage({ prompt: snapshot.prompt, references: snapshot.resources, images: references, route, model: frozen.model });
+            runDirectories(this.dirs, run.id);
+            if (controller.signal.aborted || this.runs.get(run.id).status === 'cancelling') {
+                context.emit({ type: 'stopped' });
+                return;
+            }
+            // After this point an uncertain transport outcome can represent a paid request.
+            context.emit({ type: 'started' });
+            if (this.runs.db.prepare('SELECT 1 FROM image_provider_revoked_credentials WHERE provider_id=? AND revision=?').get(route.providerId, route.credentialRevision))
+                throw new ServiceError('MODEL_UNAVAILABLE', '冻结凭据已撤销。');
+            phase = 'provider_request';
+            const result = await executeOpenAiImage(plan, frozen.endpoint, secret, AbortSignal.any([controller.signal, AbortSignal.timeout(180000)]));
+            if (controller.signal.aborted || this.runs.get(run.id).status === 'cancelling') {
+                context.emit({ type: 'stopped' });
+                return;
+            }
+            phase = 'output_staging';
+            await stageApiImageOutput(run, this.dirs, result.bytes, { providerId: route.providerId, modelId: route.modelId, inputDigest: snapshot.inputDigest });
+            if (result.requestId)
+                context.emit({ type: 'progress', payload: { requestId: result.requestId, source: 'image_provider' } });
+            context.emit({ type: 'completed', result: { providerId: route.providerId, modelId: route.modelId, ...(result.requestId ? { requestId: result.requestId } : {}) } });
+        }
+        catch (error) {
+            if (controller.signal.aborted) {
+                context.emit({ type: 'stopped' });
+                return;
+            }
+            if (error instanceof ServiceError && error.code === 'CONFLICT')
+                throw error; // unknown acceptance: reconcile, never re-send
+            if (!(error instanceof ServiceError)) {
+                const code = error && typeof error === 'object' && 'code' in error ? String(error.code).slice(0, 40) : undefined;
+                const name = error instanceof Error ? error.name : 'UnknownError';
+                const message = (error instanceof Error ? error.message : String(error)).replace(/Bearer\s+\S+/gi, 'Bearer <redacted>').replace(/https?:\/\/\S+/gi, '<redacted-url>').replace(/[A-Za-z0-9_-]{32,}/g, '<redacted>').slice(0, 500);
+                this.runs.record(run.id, 'api-image.error', { phase, name, ...(code ? { code } : {}), message });
+            }
+            const fallback = phase === 'output_staging' ? '服务商请求已成功返回，但保存图片输出失败。' : phase === 'provider_request' ? '服务商响应处理失败。' : '图片任务准备失败。';
+            context.emit({ type: 'failed', error: error instanceof ServiceError ? error.message : fallback });
+        }
+        finally {
+            this.pending.delete(run.id);
+        }
+    }
+    async cancel(run, context) {
+        const pending = this.pending.get(run.id);
+        if (pending) {
+            pending.abort();
+            return 'confirmed';
+        }
+        // Aborting local wait is not proof of provider cancellation; no new attempt follows.
+        if (this.runs.runtime(run.id).details.cancelRequested === true) {
+            context.emit({ type: 'stopped' });
+            return 'confirmed';
+        }
+        return 'unknown';
+    }
+    async reconcile(run, _context) {
+        if (this.runs.runtime(run.id).details.cancelRequested === true)
+            return 'interrupted';
+        return 'unknown'; // No provider query/idempotency contract: preserve uncertainty after restart.
+    }
+}
+export class RoutedImageBackend {
+    codex;
+    api;
+    runs;
+    constructor(codex, api, runs) {
+        this.codex = codex;
+        this.api = api;
+        this.runs = runs;
+    }
+    delegate(run) { return this.runs.snapshot(run.id).imageRoute?.type === 'api' ? this.api : this.codex; }
+    start(run, snapshot, context) { return (snapshot.imageRoute?.type === 'api' ? this.api : this.codex).start(run, snapshot, context); }
+    cancel(run, context) { return this.delegate(run).cancel(run, context); }
+    reconcile(run, context) { return this.delegate(run).reconcile?.(run, context) ?? Promise.resolve('unknown'); }
+    reply(run, interaction, answer, context) {
+        const delegate = this.delegate(run);
+        if (!delegate.reply)
+            throw new ServiceError('INVALID_REQUEST', 'API 图片任务不支持交互。');
+        return delegate.reply(run, interaction, answer, context);
+    }
+}
+//# sourceMappingURL=api-image-agent.js.map

package/dist/api-image-output.d.ts

@@ -0,0 +1,8 @@
+import type { Run } from "./vendor/protocol/index.js";
+import { type DataDirectories } from './directories.js';
+/** Publishes nothing itself: the existing Publication re-reads and validates these files. */
+export declare function stageApiImageOutput(run: Run, dirs: DataDirectories, image: Buffer, publicMetadata: {
+    providerId: string;
+    modelId: string;
+    inputDigest: string;
+}): Promise<void>;

package/dist/api-image-output.js

@@ -0,0 +1,41 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { open, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { runDirectories } from './directories.js';
+import { ServiceError } from './errors.js';
+import { validateImageOutput } from './publication.js';
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+async function writeExclusive(path, bytes) {
+    const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Publishes nothing itself: the existing Publication re-reads and validates these files. */
+export async function stageApiImageOutput(run, dirs, image, publicMetadata) {
+    if (!/^[a-zA-Z0-9_-]{1,100}$/.test(publicMetadata.providerId) || !/^[a-zA-Z0-9_.-]{1,100}$/.test(publicMetadata.modelId) || ['.', '..'].includes(publicMetadata.modelId) || !/^[a-f0-9]{64}$/.test(publicMetadata.inputDigest) || publicMetadata.inputDigest !== run.inputDigest)
+        throw new ServiceError('INPUT_BLOCKED', '输出配置与冻结 Run 不一致。');
+    const mime = validateImageOutput(image);
+    const suffix = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp' }[mime];
+    const root = runDirectories(dirs, run.id).output;
+    if ((await readdir(root)).length)
+        throw new ServiceError('CONFLICT', 'API Run 输出目录非空，不能覆盖或重发。');
+    const note = Buffer.from('# 图片生成结果\n\n服务商：' + publicMetadata.providerId + '\n\n模型：' + publicMetadata.modelId + '\n\n输入摘要：' + run.inputDigest + '\n', 'utf8');
+    const outputs = [
+        { outputKey: 'image', path: 'image.' + suffix, mime, bytes: image.length, sha256: sha256(image) },
+        { outputKey: 'description', path: 'description.md', mime: 'text/markdown', bytes: note.length, sha256: sha256(note) },
+    ];
+    const manifest = Buffer.from(JSON.stringify({ outputs }), 'utf8');
+    if (manifest.length > 64 * 1024)
+        throw new ServiceError('PAYLOAD_TOO_LARGE', '输出清单超出限制。');
+    await writeExclusive(join(root, outputs[0].path), image);
+    await writeExclusive(join(root, outputs[1].path), note);
+    // A complete manifest is the last durable commit marker for Publication.
+    await writeExclusive(join(root, 'manifest.json'), manifest);
+}
+//# sourceMappingURL=api-image-output.js.map

package/dist/api.d.ts

@@ -0,0 +1,35 @@
+import type { IncomingMessage } from 'node:http';
+import type { DatabaseSync } from 'node:sqlite';
+import { Auth } from './auth.js';
+import { Graphs } from './graphs.js';
+import { ResourceApi } from './resource-api.js';
+import { WorkflowRuntime } from './runtime.js';
+import { RunApi } from './run-api.js';
+import { Backups } from './operations/backups.js';
+import { BackupApi } from './backup-api.js';
+export interface ApiResult {
+    handled: boolean;
+    body?: unknown;
+    status?: number;
+    binary?: Buffer;
+    binaryParts?: Uint8Array[];
+    headers?: Record<string, string>;
+}
+export declare class BusinessApi {
+    readonly db: DatabaseSync;
+    readonly serviceId: string;
+    readonly auth: Auth;
+    readonly runtime: WorkflowRuntime;
+    readonly graphs: Graphs;
+    readonly resources: ResourceApi;
+    readonly runApi: RunApi;
+    readonly backups: Backups;
+    readonly backupApi: BackupApi;
+    private transferApi?;
+    private pluginApi?;
+    private projectFilesApi?;
+    private skillsApi?;
+    private storageApi?;
+    constructor(db: DatabaseSync, serviceId: string, auth: Auth, runtime: WorkflowRuntime);
+    handle(request: IncomingMessage, path: string, token: string, origin: string): Promise<ApiResult>;
+}

package/dist/api.js

@@ -0,0 +1,153 @@
+import { Auth } from './auth.js';
+import { Graphs } from './graphs.js';
+import { Events } from './events.js';
+import { readJson } from './http.js';
+import { ServiceError } from './errors.js';
+import { ResourceApi } from './resource-api.js';
+import { WorkflowRuntime } from './runtime.js';
+import { RunApi } from './run-api.js';
+import { Backups } from './operations/backups.js';
+import { BackupApi } from './backup-api.js';
+import { TransferApi } from './transfer-api.js';
+import { GraphTransfer } from './graph-transfer.js';
+import { PluginApi } from './plugin-api.js';
+import { PluginManagement } from './plugin-management.js';
+import { Repositories } from './persistence/repositories.js';
+import { ProjectFilesApi } from './project-files-api.js';
+import { SkillsApi } from './skills-api.js';
+import { StorageApi } from './storage-api.js';
+export class BusinessApi {
+    db;
+    serviceId;
+    auth;
+    runtime;
+    graphs;
+    resources;
+    runApi;
+    backups;
+    backupApi;
+    transferApi;
+    pluginApi;
+    projectFilesApi;
+    skillsApi;
+    storageApi;
+    constructor(db, serviceId, auth, runtime) {
+        this.db = db;
+        this.serviceId = serviceId;
+        this.auth = auth;
+        this.runtime = runtime;
+        this.graphs = runtime.graphs;
+        this.resources = new ResourceApi(runtime.resources, this.graphs, auth);
+        this.runApi = new RunApi(runtime, auth);
+        this.backups = new Backups(db, runtime.directories, { withBlobLease: work => runtime.resources.withBlobLease(work) });
+        this.backupApi = new BackupApi(this.backups, auth);
+    }
+    async handle(request, path, token, origin) {
+        this.storageApi ??= new StorageApi(this.db, this.runtime.directories, this.runtime.resources, this.auth);
+        const storage = await this.storageApi.handle(request, path, token, origin);
+        if (storage.handled)
+            return storage;
+        this.skillsApi ??= new SkillsApi(this.db, this.auth, this.runtime);
+        const skills = await this.skillsApi.handle(request, path, token, origin);
+        if (skills.handled)
+            return skills;
+        this.projectFilesApi ??= new ProjectFilesApi(this.db, this.auth, this.graphs, this.runtime.resources, this.runtime.directories.runs);
+        const files = await this.projectFilesApi.handle(request, path, token, origin);
+        if (files.handled)
+            return files;
+        const page = /^[/]v1[/]projects[/]([a-zA-Z0-9_-]+)[/]graphs[/]page$/.exec(path);
+        if (page && request.method === 'POST') {
+            this.auth.withSession(token, origin, () => undefined);
+            const body = await readJson(request, 16 * 1024);
+            return this.auth.withSession(token, origin, current => {
+                const result = this.graphs.page(page[1], body, current.id);
+                // service.ts decorates the outer eventCursor; nested snapshots must also
+                // carry session-bound cursors, never raw database sequence numbers.
+                const events = new Events(this.db, this.serviceId, this.auth);
+                return { handled: true, body: { ...result, items: events.decorate(result.items, current.id) } };
+            });
+        }
+        this.pluginApi ??= new PluginApi(new PluginManagement(this.graphs, this.runtime.plugins), this.auth);
+        const plugin = await this.pluginApi.handle(request, path, token, origin);
+        if (plugin.handled)
+            return plugin;
+        this.transferApi ??= new TransferApi(new GraphTransfer(this.graphs, this.runtime.resources), this.auth);
+        const transfer = await this.transferApi.handle(request, path, token, origin);
+        if (transfer.handled)
+            return transfer;
+        const backup = await this.backupApi.handle(request, path, token, origin);
+        if (backup.handled)
+            return backup;
+        const resource = await this.resources.handle(request, path, token, origin);
+        if (resource.handled)
+            return resource;
+        const run = await this.runApi.handle(request, path, token, origin);
+        if (run.handled)
+            return run;
+        const match = /^[/]v1[/]projects[/]([a-zA-Z0-9_-]+)[/]graphs(?:[/]([a-zA-Z0-9_-]+))?(?:[/](commands|history|all|archive|trash|restore|purge|permanent-delete))?$/.exec(path);
+        if (!match)
+            return { handled: false };
+        this.auth.withSession(token, origin, () => undefined);
+        const body = request.method === 'POST' ? await readJson(request, 16 * 1024 * 1024) : undefined;
+        const result = this.auth.withSession(token, origin, current => {
+            const projectId = match[1], graphId = match[2], action = match[3];
+            if (request.method === 'GET' && !graphId)
+                return { handled: true, body: this.graphs.list(projectId) };
+            if (request.method === 'GET' && graphId === 'all')
+                return { handled: true, body: this.graphs.list(projectId, true, true) };
+            if (request.method === 'GET' && graphId === 'trash' && !action)
+                return { handled: true, body: this.graphs.list(projectId, true, true, true) };
+            if (request.method === 'GET' && graphId && !action)
+                return { handled: true, body: this.graphs.snapshot({ serviceId: this.serviceId, projectId, graphId }) };
+            if (request.method === 'POST' && !graphId && body) {
+                if (Object.keys(body).some(key => !['title', 'idempotencyKey'].includes(key)) || typeof body['title'] !== 'string' || typeof body['idempotencyKey'] !== 'string')
+                    throw new ServiceError('INVALID_REQUEST', '建图请求须包含 title 和 idempotencyKey。');
+                return { handled: true, body: this.graphs.create(projectId, body['title'], body['idempotencyKey'], current.id) };
+            }
+            if (request.method === 'POST' && graphId && action === 'permanent-delete' && body) {
+                if (Object.keys(body).some(key => !['idempotencyKey', 'expectedExecutionRevision', 'expectedLayoutRevision', 'confirmTitle'].includes(key)) || typeof body['idempotencyKey'] !== 'string')
+                    throw new ServiceError('INVALID_REQUEST', '无效的彻底删除请求。');
+                return { handled: true, body: this.graphs.permanentDelete({ ...body, serviceId: this.serviceId, projectId, graphId }, this.runtime.resources, current.id) };
+            }
+            if (request.method === 'POST' && graphId && action && ['archive', 'trash', 'restore', 'purge'].includes(action) && body) {
+                const allowed = action === 'purge' ? ['idempotencyKey', 'expectedExecutionRevision', 'confirmationTitle'] : ['idempotencyKey', 'expectedExecutionRevision'];
+                if (Object.keys(body).some(key => !allowed.includes(key)) || typeof body['idempotencyKey'] !== 'string' || !Number.isSafeInteger(body['expectedExecutionRevision']) || Number(body['expectedExecutionRevision']) < 0 || (action === 'purge' && typeof body['confirmationTitle'] !== 'string'))
+                    throw new ServiceError('INVALID_REQUEST', '生命周期请求需要幂等键、执行版本；彻底删除还需 confirmationTitle。');
+                const scope = { serviceId: this.serviceId, projectId, graphId };
+                const value = new Repositories(this.db).idempotent(current.id + ':graph.lifecycle:' + graphId, body['idempotencyKey'], { ...body, ...scope, action }, () => {
+                    const snapshot = this.graphs.snapshot(scope);
+                    const base = { ...scope, idempotencyKey: body['idempotencyKey'], expectedExecutionRevision: body['expectedExecutionRevision'], expectedLayoutRevision: snapshot.layoutRevision };
+                    if (action === 'purge')
+                        return this.graphs.permanentDelete({ ...base, confirmTitle: body['confirmationTitle'] }, this.runtime.resources, current.id);
+                    const operation = action === 'archive' ? { type: 'graph.archive', archived: true } : action === 'trash' ? { type: 'graph.trash', trashed: true } : snapshot.trashed ? { type: 'graph.trash', trashed: false } : { type: 'graph.archive', archived: false };
+                    return this.graphs.command({ ...base, operations: [operation] }, current.id);
+                });
+                return { handled: true, body: value };
+            }
+            if (request.method === 'POST' && graphId && action === 'history' && body) {
+                if (Object.keys(body).some(key => !['idempotencyKey', 'expectedExecutionRevision', 'expectedLayoutRevision', 'expectedCursor', 'direction'].includes(key)) || typeof body['idempotencyKey'] !== 'string')
+                    throw new ServiceError('INVALID_REQUEST', '无效的历史恢复请求。');
+                const snapshot = this.graphs.history.travel({ ...body, serviceId: this.serviceId, projectId, graphId }, current.id);
+                this.runtime.resources.collectGarbage();
+                return { handled: true, body: snapshot };
+            }
+            if (request.method === 'POST' && graphId && action === 'commands' && body) {
+                if (Object.keys(body).some(key => !['idempotencyKey', 'expectedExecutionRevision', 'expectedLayoutRevision', 'operations'].includes(key)))
+                    throw new ServiceError('INVALID_REQUEST', '图命令包含未知字段。');
+                const command = { ...body, serviceId: this.serviceId, projectId, graphId };
+                if (typeof command.idempotencyKey !== 'string' || !Number.isSafeInteger(command.expectedExecutionRevision) || !Number.isSafeInteger(command.expectedLayoutRevision))
+                    throw new ServiceError('INVALID_REQUEST', '图命令需要幂等键和整数版本。');
+                const snapshot = this.graphs.command(command, current.id);
+                this.runtime.resources.collectGarbage();
+                return { handled: true, body: snapshot };
+            }
+            throw new ServiceError('NOT_FOUND', '图接口不存在。');
+        });
+        if (request.method === 'POST') {
+            await this.runtime.resources.drainFileDeletions();
+            await this.runtime.graphFiles.drain();
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/auth.d.ts

@@ -0,0 +1,58 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ClientPairingStatus, PairRequest, PairResponse, Session } from "./vendor/protocol/index.js";
+export declare const SESSION_IDLE_MS: number;
+export declare const PAIRING_TTL_MS: number;
+export declare function normalizeOrigin(value: string): string;
+export declare class Auth {
+    readonly db: DatabaseSync;
+    readonly serviceId: string;
+    readonly now: () => number;
+    private pendingClients;
+    private shortAttempts;
+    private prunePairingRequests;
+    /** Public registration grants no trust. Only the local control channel can resolve/approve it. */
+    requestClientPairing(clientCode: string, origin: string): {
+        code: string;
+        expiresAt: string;
+        serviceId: string;
+    };
+    resolveClientPairing(code: string): string;
+    approveClientPairing(code: string, clientCode: string): {
+        status: string;
+        origin: string;
+        fingerprint: string;
+        expiresAt: string;
+        serviceId: string;
+    };
+    claimClientPairing(input: PairRequest, origin: string): ClientPairingStatus;
+    completeClientPairing(codeInput: string, expectedServiceId: string, token: string, origin: string): ClientPairingStatus;
+    constructor(db: DatabaseSync, serviceId: string, now?: () => number);
+    private hash;
+    /** Local-only authority. Never route issuance through the network API. */
+    issueCode(originInput: string): {
+        code: string;
+        origin: string;
+        expiresAt: string;
+        serviceId: string;
+    };
+    /** Local authorization only. A bound grant can never use the legacy exchange. */
+    issueClientCode(clientCode: string, short?: boolean): {
+        code: string;
+        origin: string;
+        fingerprint: string;
+        expiresAt: string;
+        serviceId: string;
+    };
+    requireOrigin(origin: string | undefined): string;
+    pair(input: PairRequest, origin: string): PairResponse;
+    private active;
+    /** Recheck immediately before a stream emits data; keepalives must not renew idle expiry. */
+    assertActive(token: string, origin: string): void;
+    /** Authorization, renewal and each short operation share a transaction, including CLI revocation races. */
+    withSession<T>(token: string, origin: string, operation: (session: Session) => T): T;
+    list(currentId?: string): Session[];
+    /** Call in the authenticated operation transaction, or through revokeLocal. */
+    revoke(id: string): void;
+    revokeLocal(id: string): void;
+    private toSession;
+}