@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

package/dist/agent/deleteHandlers.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 统一对象删除(2026-10-19,Task 14):objects.delete 的领域层。
+ * 带类型 ID 决定清理行为(spec 9.2),四类对象的删除处理器按
+ * `{[K in SceneObjectKind]: DeleteHandler<K>}` 全量覆盖:
+ *
+ * - model:deletePlacement —— 清单行移除 + forgetObject 清持久数据
+ *   (变换/姿势/动画覆盖与轨道),单个事务;
+ * - camera:removeCamera —— forgetObject + 注册表移除合并为单个事务;
+ * - anchor:removeAnchor —— 同事务折进子级锚点的 parent 解绑 + 世界定格
+ *   (collectAnchorChildResets),避免子组件「父级消失看护」事后补一笔
+ *   提交造成的撤销陷阱;
+ * - path:deletePathDomain(Task 11)—— forgetObject + 注册表移除 +
+ *   绑定相机 pathKey 重置与机位世界定格合并为单个事务,detachObject
+ *   等非 historic 清理在事务后;最后一点删除复用同一 handler。
+ *
+ * 事务合并后,各注册表删除函数的 forgetObject 走内部 Studio 的
+ * stateEditors(按地址清持久数据):注册表有条目但没有挂载 ref 的对象
+ * 同样真删,不需要 SheetObject 句柄,也不创建新对象——查询/删除都
+ * 不落实 SheetObject(resolver 的无副作用契约对删除同样成立)。
+ *
+ * 执行顺序:解析 ID(类型/存在性,只探测不创建)→ Studio 可用性 →
+ * beforeWrite(命令层挂 expectedRevision 检查,先于任何副作用)→
+ * 领域事务。任一校验失败抛出,不调用会话清理、不返回 deleted。
+ */
+import type { ISheet } from '@dreamerbird/core';
+import type { AgentRuntime } from './runtime';
+import type { SceneObjectId, SceneObjectKind } from './types';
+declare module './runtime' {
+    interface AgentSceneRuntimeHandlers {
+        /**
+         * 对象删除后的会话清理(CameraScene 绑定,Task 15 接线;UI 删除
+         * 流程共用同一实现):路径编辑态/控制点选择/大纲伪集合残留/右键
+         * 菜单随被删对象清理;活动相机回退、镜头视角退出与导出中止由
+         * CameraScene 的推导与看护 effect 自动完成。只在领域删除的项目
+         * 事务成功提交后调用;未绑定时静默跳过(CameraScene 未挂载,
+         * 会话态不存在)。
+         */
+        afterSceneObjectDeleted(args: {
+            id: SceneObjectId;
+            kind: SceneObjectKind;
+            key: string;
+        }): void;
+    }
+}
+/** 按类型的领域删除处理器:同步完成项目事务,抛错即整体失败 */
+export type DeleteHandler<K extends SceneObjectKind> = (sheet: ISheet, key: string) => void;
+export declare const deleteHandlers: {
+    [K in SceneObjectKind]: DeleteHandler<K>;
+};
+/**
+ * 统一删除入口(objects.delete 的命令实现):解析带类型 ID → 注册表
+ * 存在性校验(只探测不创建)→ Studio 可用性 → beforeWrite(乐观并发
+ * 检查,先于任何副作用)→ 按类型执行完整删除的项目事务。
+ * 返回解析后的 ID 信息,供命令层做会话清理与结果返回。
+ */
+export declare function deleteSceneObject(runtime: AgentRuntime, objectId: string, beforeWrite?: () => void): {
+    id: SceneObjectId;
+    kind: SceneObjectKind;
+    key: string;
+};
+//# sourceMappingURL=deleteHandlers.d.ts.map

package/dist/agent/deleteHandlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deleteHandlers.d.ts","sourceRoot":"","sources":["../../src/agent/deleteHandlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAA;AAW7C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,WAAW,CAAA;AAC3C,OAAO,KAAK,EAAC,aAAa,EAAE,eAAe,EAAC,MAAM,SAAS,CAAA;AAE3D,OAAO,QAAQ,WAAW,CAAC;IACzB,UAAU,yBAAyB;QACjC;;;;;;;WAOG;QACH,uBAAuB,CAAC,IAAI,EAAE;YAC5B,EAAE,EAAE,aAAa,CAAA;YACjB,IAAI,EAAE,eAAe,CAAA;YACrB,GAAG,EAAE,MAAM,CAAA;SACZ,GAAG,IAAI,CAAA;KACT;CACF;AAED,mCAAmC;AACnC,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,eAAe,IAAI,CACrD,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,KACR,IAAI,CAAA;AAET,eAAO,MAAM,cAAc,EAAE;KAAE,CAAC,IAAI,eAAe,GAAG,aAAa,CAAC,CAAC,CAAC;CAMrE,CAAA;AASD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,IAAI,GACvB;IAAC,EAAE,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,CAYzD"}

package/dist/agent/deleteHandlers.js

@@ -0,0 +1,41 @@
+// 内部 Studio 通道(注册表删除函数实际使用的实例;与 keyframeTracks 同先例)
+import getStudio from '@dreamerbird/studio/getStudio';
+import { deletePlacement } from '../PlacementManager';
+import { collectAnchorChildResets } from '../aimTargets';
+import { removeAnchor } from '../anchorsRegistry';
+import { removeCamera } from '../cameraRegistry';
+import { deletePathDomain } from './pathCommands';
+import { AgentApiError } from './errors';
+import { formatSceneObjectId, parseSceneObjectId } from './objectIds';
+import { listSceneObjectKeys } from './objectResolver';
+export const deleteHandlers = {
+    model: (sheet, key) => deletePlacement(sheet, key),
+    camera: (sheet, key) => removeCamera(sheet, { cameraKey: key }),
+    anchor: (sheet, key) => removeAnchor(sheet, key, collectAnchorChildResets(sheet, key)),
+    path: (sheet, key) => deletePathDomain(sheet, key),
+};
+/** Studio 不可用 = SCENE_UNAVAILABLE(spec 8.3:静默 return 不得翻译成成功) */
+function requireStudio() {
+    if (!getStudio()) {
+        throw new AgentApiError('SCENE_UNAVAILABLE', 'Studio 不可用,无法删除对象');
+    }
+}
+/**
+ * 统一删除入口(objects.delete 的命令实现):解析带类型 ID → 注册表
+ * 存在性校验(只探测不创建)→ Studio 可用性 → beforeWrite(乐观并发
+ * 检查,先于任何副作用)→ 按类型执行完整删除的项目事务。
+ * 返回解析后的 ID 信息,供命令层做会话清理与结果返回。
+ */
+export function deleteSceneObject(runtime, objectId, beforeWrite) {
+    const { kind, key } = parseSceneObjectId(objectId);
+    if (!listSceneObjectKeys(runtime.sheet, kind).includes(key)) {
+        throw new AgentApiError('OBJECT_NOT_FOUND', `场景对象不存在: ${objectId}`, {
+            details: { objectId, kind },
+        });
+    }
+    requireStudio();
+    // 全部校验完成;expectedRevision 等并发检查先于任何副作用
+    beforeWrite?.();
+    deleteHandlers[kind](runtime.sheet, key);
+    return { id: formatSceneObjectId(kind, key), kind, key };
+}

package/dist/agent/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Agent API 稳定错误类别(2026-10-17,spec 第 12 节):
+ * `code` 是 Agent 分支判断的稳定依据,HTTP 状态码只表达传输/结果类别。
+ * `KEYFRAME_NOT_FOUND` 为命令额外声明的子类错误码。
+ */
+/** spec 第 12 节全部错误码 + `KEYFRAME_NOT_FOUND` */
+export declare const AGENT_API_ERROR_CODES: readonly ["API_NOT_READY", "API_DISPOSED", "SCENE_UNAVAILABLE", "COMMAND_NOT_FOUND", "CAPABILITY_UNAVAILABLE", "INVALID_ARGUMENT", "INVALID_ID_KIND", "OBJECT_NOT_FOUND", "ASSET_NOT_FOUND", "PATH_POINT_NOT_FOUND", "KEYFRAME_NOT_FOUND", "INVALID_STATE", "REVISION_CONFLICT", "JOB_NOT_FOUND", "JOB_NOT_CANCELABLE", "JOB_CANCELLED", "FILE_NOT_FOUND", "PAYLOAD_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "STORAGE_ERROR", "NETWORK_ERROR", "RESOURCE_LOAD_FAILED", "PARTIAL_FAILURE", "INTERNAL_ERROR"];
+export type AgentApiErrorCode = (typeof AGENT_API_ERROR_CODES)[number];
+/** 结构化 API 错误:JS 侧直接 throw,HTTP 侧由桥接转成失败结果 */
+export declare class AgentApiError extends Error {
+    readonly code: AgentApiErrorCode;
+    readonly retryable: boolean;
+    readonly details?: unknown;
+    constructor(code: AgentApiErrorCode, message: string, { retryable, details }?: {
+        retryable?: boolean;
+        details?: unknown;
+    });
+}
+/**
+ * 未知异常归一化:已有结构化错误原样保留,
+ * 其余一律包装为 `INTERNAL_ERROR`(非重试,带上原始信息)。
+ */
+export declare function asAgentApiError(error: unknown): AgentApiError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/agent/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/agent/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,8CAA8C;AAC9C,eAAO,MAAM,qBAAqB,6eA0BxB,CAAA;AAEV,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEtE,8CAA8C;AAC9C,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;gBAGxB,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,MAAM,EACf,EAAC,SAAiB,EAAE,OAAO,EAAC,GAAE;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAM;CAQ9E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAU7D"}

package/dist/agent/errors.js

@@ -0,0 +1,59 @@
+/**
+ * Agent API 稳定错误类别(2026-10-17,spec 第 12 节):
+ * `code` 是 Agent 分支判断的稳定依据,HTTP 状态码只表达传输/结果类别。
+ * `KEYFRAME_NOT_FOUND` 为命令额外声明的子类错误码。
+ */
+/** spec 第 12 节全部错误码 + `KEYFRAME_NOT_FOUND` */
+export const AGENT_API_ERROR_CODES = [
+    'API_NOT_READY',
+    'API_DISPOSED',
+    'SCENE_UNAVAILABLE',
+    'COMMAND_NOT_FOUND',
+    'CAPABILITY_UNAVAILABLE',
+    'INVALID_ARGUMENT',
+    'INVALID_ID_KIND',
+    'OBJECT_NOT_FOUND',
+    'ASSET_NOT_FOUND',
+    'PATH_POINT_NOT_FOUND',
+    'KEYFRAME_NOT_FOUND',
+    'INVALID_STATE',
+    'REVISION_CONFLICT',
+    'JOB_NOT_FOUND',
+    'JOB_NOT_CANCELABLE',
+    'JOB_CANCELLED',
+    'FILE_NOT_FOUND',
+    'PAYLOAD_TOO_LARGE',
+    'UNAUTHORIZED',
+    'FORBIDDEN',
+    'STORAGE_ERROR',
+    'NETWORK_ERROR',
+    'RESOURCE_LOAD_FAILED',
+    'PARTIAL_FAILURE',
+    'INTERNAL_ERROR',
+];
+/** 结构化 API 错误:JS 侧直接 throw,HTTP 侧由桥接转成失败结果 */
+export class AgentApiError extends Error {
+    constructor(code, message, { retryable = false, details } = {}) {
+        super(message);
+        this.name = 'AgentApiError';
+        this.code = code;
+        this.retryable = retryable;
+        this.details = details;
+    }
+}
+/**
+ * 未知异常归一化:已有结构化错误原样保留,
+ * 其余一律包装为 `INTERNAL_ERROR`(非重试,带上原始信息)。
+ */
+export function asAgentApiError(error) {
+    if (error instanceof AgentApiError)
+        return error;
+    if (error instanceof Error) {
+        return new AgentApiError('INTERNAL_ERROR', error.message, {
+            details: { cause: error.message },
+        });
+    }
+    return new AgentApiError('INTERNAL_ERROR', '未知错误', {
+        details: { cause: String(error) },
+    });
+}

package/dist/agent/errors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=errors.test.d.ts.map

package/dist/agent/errors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.d.ts","sourceRoot":"","sources":["../../src/agent/errors.test.ts"],"names":[],"mappings":""}

package/dist/agent/errors.test.js

@@ -0,0 +1,25 @@
+import { AgentApiError, asAgentApiError } from './errors';
+test('errors expose stable machine fields', () => {
+    const error = new AgentApiError('REVISION_CONFLICT', 'stale', {
+        retryable: false,
+        details: { actualRevision: 2 },
+    });
+    expect(error).toMatchObject({
+        code: 'REVISION_CONFLICT',
+        retryable: false,
+        details: { actualRevision: 2 },
+    });
+});
+test('asAgentApiError preserves structured errors and wraps unknown exceptions', () => {
+    const structured = new AgentApiError('OBJECT_NOT_FOUND', 'gone');
+    expect(asAgentApiError(structured)).toBe(structured);
+    const wrapped = asAgentApiError(new Error('boom'));
+    expect(wrapped).toBeInstanceOf(AgentApiError);
+    expect(wrapped).toMatchObject({
+        code: 'INTERNAL_ERROR',
+        retryable: false,
+        details: { cause: 'boom' },
+    });
+    const wrappedString = asAgentApiError('weird');
+    expect(wrappedString).toMatchObject({ code: 'INTERNAL_ERROR' });
+});

package/dist/agent/expectedCommands.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Agent 命令面预期清单(2026-10-19,Task 16,spec §9 逐字):
+ * 浏览器 JS API、后续 HTTP 桥接与 SKILL 计划的覆盖校验共用同一份常量。
+ * 任何变更必须先改 spec 第 9 节,再同步本清单——契约覆盖测试
+ * (contractCoverage.test.ts)对缺少与多出都失败。
+ */
+export declare const EXPECTED_AGENT_COMMANDS: readonly ["scene.getSnapshot", "selection.get", "selection.selectObject", "selection.clear", "objects.list", "objects.get", "objects.update", "objects.delete", "models.create", "assets.list", "assets.get", "assets.importModel", "assets.rename", "assets.delete", "poses.apply", "poses.applyCustom", "poses.clear", "poses.saveCurrent", "poses.setGesture", "poses.session.start", "poses.session.commit", "poses.session.cancel", "animations.apply", "animations.clear", "animations.getStatus", "cameras.create", "cameras.setActive", "cameras.setAimTarget", "cameras.bindPath", "cameras.unbindPath", "anchors.create", "anchors.setParent", "anchors.clearParent", "paths.listPresets", "paths.createPreset", "paths.addPoint", "paths.updatePoint", "paths.deletePoint", "paths.setPointTiming", "paths.sample", "paths.session.startEditing", "paths.session.exitEditing", "paths.session.selectPoint", "sequence.getState", "sequence.play", "sequence.pause", "sequence.seek", "sequence.setLength", "keyframes.list", "keyframes.set", "keyframes.move", "keyframes.delete", "history.undo", "history.redo", "view.getState", "view.setShotView", "view.setPipVisible", "view.orbit", "view.pan", "view.dolly", "view.reset", "ui.hide", "ui.restore", "ui.setLeftStripHidden", "ui.openPanel", "ui.closePanel", "ui.setGizmoMode", "project.exportState", "exports.startVideo", "jobs.get", "jobs.cancel"];
+export type ExpectedAgentCommand = (typeof EXPECTED_AGENT_COMMANDS)[number];
+//# sourceMappingURL=expectedCommands.d.ts.map

package/dist/agent/expectedCommands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expectedCommands.d.ts","sourceRoot":"","sources":["../../src/agent/expectedCommands.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,+1CAwE1B,CAAA;AAEV,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAA"}

package/dist/agent/expectedCommands.js

@@ -0,0 +1,79 @@
+/**
+ * Agent 命令面预期清单(2026-10-19,Task 16,spec §9 逐字):
+ * 浏览器 JS API、后续 HTTP 桥接与 SKILL 计划的覆盖校验共用同一份常量。
+ * 任何变更必须先改 spec 第 9 节,再同步本清单——契约覆盖测试
+ * (contractCoverage.test.ts)对缺少与多出都失败。
+ */
+export const EXPECTED_AGENT_COMMANDS = [
+    'scene.getSnapshot',
+    'selection.get',
+    'selection.selectObject',
+    'selection.clear',
+    'objects.list',
+    'objects.get',
+    'objects.update',
+    'objects.delete',
+    'models.create',
+    'assets.list',
+    'assets.get',
+    'assets.importModel',
+    'assets.rename',
+    'assets.delete',
+    'poses.apply',
+    'poses.applyCustom',
+    'poses.clear',
+    'poses.saveCurrent',
+    'poses.setGesture',
+    'poses.session.start',
+    'poses.session.commit',
+    'poses.session.cancel',
+    'animations.apply',
+    'animations.clear',
+    'animations.getStatus',
+    'cameras.create',
+    'cameras.setActive',
+    'cameras.setAimTarget',
+    'cameras.bindPath',
+    'cameras.unbindPath',
+    'anchors.create',
+    'anchors.setParent',
+    'anchors.clearParent',
+    'paths.listPresets',
+    'paths.createPreset',
+    'paths.addPoint',
+    'paths.updatePoint',
+    'paths.deletePoint',
+    'paths.setPointTiming',
+    'paths.sample',
+    'paths.session.startEditing',
+    'paths.session.exitEditing',
+    'paths.session.selectPoint',
+    'sequence.getState',
+    'sequence.play',
+    'sequence.pause',
+    'sequence.seek',
+    'sequence.setLength',
+    'keyframes.list',
+    'keyframes.set',
+    'keyframes.move',
+    'keyframes.delete',
+    'history.undo',
+    'history.redo',
+    'view.getState',
+    'view.setShotView',
+    'view.setPipVisible',
+    'view.orbit',
+    'view.pan',
+    'view.dolly',
+    'view.reset',
+    'ui.hide',
+    'ui.restore',
+    'ui.setLeftStripHidden',
+    'ui.openPanel',
+    'ui.closePanel',
+    'ui.setGizmoMode',
+    'project.exportState',
+    'exports.startVideo',
+    'jobs.get',
+    'jobs.cancel',
+];

package/dist/agent/jobs.d.ts

@@ -0,0 +1,52 @@
+import type { JobSnapshot } from './types';
+/** 订阅者收到的快照:与 `get` 返回同一冻结对象 */
+export type JobListener = (snapshot: JobSnapshot<unknown>) => void;
+/** `execute` 收到的控制句柄:AbortSignal + 进度/阶段上报 */
+export type JobControls = {
+    signal: AbortSignal;
+    update: (patch: {
+        progress?: number;
+        phase?: JobSnapshot['phase'];
+    }) => void;
+};
+export declare class AgentJobManager {
+    private readonly snapshots;
+    private readonly controllers;
+    private readonly listeners;
+    /**
+     * 发布最新快照:冻结后存表并广播。当前快照已是终态时
+     * (如取消后 execute 晚到 settle)不再覆盖,返回当前快照。
+     */
+    private emit;
+    /**
+     * 启动任务并立即返回句柄;同步发布 `running` 快照后开始执行。
+     * `done` 在 execute settle 后以终态快照 resolve。
+     */
+    start<T>(args: {
+        kind: string;
+        cancelable: boolean;
+        execute: (controls: JobControls) => Promise<T>;
+    }): {
+        jobId: string;
+        done: Promise<JobSnapshot<T>>;
+    };
+    /** 返回该任务的最新冻结快照;未知 ID 抛 `JOB_NOT_FOUND` */
+    get<T = unknown>(jobId: string): JobSnapshot<T>;
+    /**
+     * 取消任务:触发 `AbortController.abort()` 并立即映射为
+     * `cancelled`。不可取消任务抛 `JOB_NOT_CANCELABLE`,
+     * 未知 ID 抛 `JOB_NOT_FOUND`,已结束任务抛 `INVALID_STATE`。
+     */
+    cancel(jobId: string): void;
+    /** 订阅全部任务快照;返回解绑函数 */
+    subscribe(listener: JobListener): () => void;
+    /**
+     * 会话拆解(Task 15 决策,Task 3 遗留):硬取消全部未结束任务——
+     * abort 其 AbortController 并立即映射为 cancelled(错误码
+     * API_DISPOSED),不把任务留进已拆解的会话继续跑。execute 守约监听
+     * signal(如视频导出)就此收尾,`done` 以 cancelled 快照 resolve;
+     * 晚到的 settle 被 emit 的终态保护吞掉,不会复活任务。
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=jobs.d.ts.map

package/dist/agent/jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../../src/agent/jobs.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAA;AAExC,gCAAgC;AAChC,MAAM,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,KAAK,IAAI,CAAA;AAElE,8CAA8C;AAC9C,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,WAAW,CAAA;IACnB,MAAM,EAAE,CAAC,KAAK,EAAE;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;KAAC,KAAK,IAAI,CAAA;CAC3E,CAAA;AA8BD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0C;IACpE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqC;IACjE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IAEnD;;;OAGG;IACH,OAAO,CAAC,IAAI;IAoBZ;;;OAGG;IACH,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE;QACb,IAAI,EAAE,MAAM,CAAA;QACZ,UAAU,EAAE,OAAO,CAAA;QACnB,OAAO,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;KAC/C,GAAG;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;KAAC;IAwDlD,2CAA2C;IAC3C,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC;IAQ/C;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAe3B,sBAAsB;IACtB,SAAS,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,IAAI;IAO5C;;;;;;OAMG;IACH,OAAO,IAAI,IAAI;CAehB"}

package/dist/agent/jobs.js

@@ -0,0 +1,175 @@
+/**
+ * Agent 任务管理器(2026-10-17,spec 8.7):长任务的登记、进度、终态和取消。
+ * 管理器保存每个任务的最后一个快照,并向订阅者发送不可变副本;
+ * `done` promise 是任务终态的唯一权威。
+ */
+import { AgentApiError, asAgentApiError } from './errors';
+/** 终态之后不再接受 update/cancel */
+const TERMINAL_STATES = new Set(['succeeded', 'failed', 'cancelled']);
+let jobIdFallbackCounter = 0;
+/**
+ * 任务 ID:优先 `crypto.randomUUID()`;运行环境缺失(如旧 jsdom)
+ * 时回退为带进程内计数器的 `job-${Date.now()}-${counter}`。
+ */
+function newJobId() {
+    const cryptoApi = globalThis.crypto;
+    if (cryptoApi && typeof cryptoApi.randomUUID === 'function') {
+        return cryptoApi.randomUUID();
+    }
+    jobIdFallbackCounter += 1;
+    return `job-${Date.now()}-${jobIdFallbackCounter}`;
+}
+function errorDetails(error) {
+    const details = {
+        code: error.code,
+        message: error.message,
+        retryable: error.retryable,
+    };
+    if (error.details !== undefined)
+        details.details = error.details;
+    return details;
+}
+export class AgentJobManager {
+    constructor() {
+        this.snapshots = new Map();
+        this.controllers = new Map();
+        this.listeners = new Set();
+    }
+    /**
+     * 发布最新快照:冻结后存表并广播。当前快照已是终态时
+     * (如取消后 execute 晚到 settle)不再覆盖,返回当前快照。
+     */
+    emit(jobId, snapshot) {
+        const current = this.snapshots.get(jobId);
+        if (current && TERMINAL_STATES.has(current.state))
+            return current;
+        const frozen = Object.freeze(snapshot);
+        this.snapshots.set(jobId, frozen);
+        // 单个订阅者抛错不得中断广播,也不得反向污染任务状态
+        // (异常若传回 execute 调用点,会被 start 的 catch 误判为任务失败)
+        for (const listener of [...this.listeners]) {
+            try {
+                listener(frozen);
+            }
+            catch {
+                // 忽略:后续订阅者仍应收到本快照
+            }
+        }
+        return frozen;
+    }
+    /**
+     * 启动任务并立即返回句柄;同步发布 `running` 快照后开始执行。
+     * `done` 在 execute settle 后以终态快照 resolve。
+     */
+    start(args) {
+        const jobId = newJobId();
+        const controller = new AbortController();
+        this.controllers.set(jobId, controller);
+        this.emit(jobId, {
+            jobId,
+            kind: args.kind,
+            state: 'running',
+            progress: 0,
+            phase: 'accepted',
+            cancelable: args.cancelable,
+        });
+        const done = (async () => {
+            try {
+                const result = await args.execute({
+                    signal: controller.signal,
+                    update: (patch) => {
+                        const current = this.snapshots.get(jobId);
+                        this.emit(jobId, {
+                            ...current,
+                            progress: patch.progress ?? current.progress,
+                            phase: patch.phase ?? current.phase,
+                        });
+                    },
+                });
+                const current = this.snapshots.get(jobId);
+                this.emit(jobId, { ...current, state: 'succeeded', progress: 1, result });
+            }
+            catch (error) {
+                const current = this.snapshots.get(jobId);
+                const normalized = asAgentApiError(error);
+                // execute 以 JOB_CANCELLED 拒绝 = 任务因取消而结束(如视频导出的
+                // 用户侧中止:Esc/开录相机被删,非 jobs.cancel 路径)——终态应为
+                // cancelled 并带上错误码,轮询方据此区分"被中止"与真失败;
+                // 若已是 cancelled(jobs.cancel 先到),emit 的终态保护保持原样
+                if (normalized.code === 'JOB_CANCELLED') {
+                    this.emit(jobId, {
+                        ...current,
+                        state: 'cancelled',
+                        error: errorDetails(normalized),
+                    });
+                }
+                else {
+                    this.emit(jobId, {
+                        ...current,
+                        state: 'failed',
+                        error: errorDetails(normalized),
+                    });
+                }
+            }
+            return this.snapshots.get(jobId);
+        })();
+        return { jobId, done };
+    }
+    /** 返回该任务的最新冻结快照;未知 ID 抛 `JOB_NOT_FOUND` */
+    get(jobId) {
+        const snapshot = this.snapshots.get(jobId);
+        if (!snapshot) {
+            throw new AgentApiError('JOB_NOT_FOUND', `未知任务: ${jobId}`);
+        }
+        return snapshot;
+    }
+    /**
+     * 取消任务:触发 `AbortController.abort()` 并立即映射为
+     * `cancelled`。不可取消任务抛 `JOB_NOT_CANCELABLE`,
+     * 未知 ID 抛 `JOB_NOT_FOUND`,已结束任务抛 `INVALID_STATE`。
+     */
+    cancel(jobId) {
+        const snapshot = this.snapshots.get(jobId);
+        if (!snapshot) {
+            throw new AgentApiError('JOB_NOT_FOUND', `未知任务: ${jobId}`);
+        }
+        if (!snapshot.cancelable) {
+            throw new AgentApiError('JOB_NOT_CANCELABLE', `任务不可取消: ${jobId}`);
+        }
+        if (TERMINAL_STATES.has(snapshot.state)) {
+            throw new AgentApiError('INVALID_STATE', `任务已结束,无法取消: ${jobId}`);
+        }
+        this.controllers.get(jobId)?.abort();
+        this.emit(jobId, { ...snapshot, state: 'cancelled' });
+    }
+    /** 订阅全部任务快照;返回解绑函数 */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * 会话拆解(Task 15 决策,Task 3 遗留):硬取消全部未结束任务——
+     * abort 其 AbortController 并立即映射为 cancelled(错误码
+     * API_DISPOSED),不把任务留进已拆解的会话继续跑。execute 守约监听
+     * signal(如视频导出)就此收尾,`done` 以 cancelled 快照 resolve;
+     * 晚到的 settle 被 emit 的终态保护吞掉,不会复活任务。
+     */
+    dispose() {
+        for (const [jobId, snapshot] of [...this.snapshots]) {
+            if (TERMINAL_STATES.has(snapshot.state))
+                continue;
+            this.controllers.get(jobId)?.abort();
+            this.emit(jobId, {
+                ...snapshot,
+                state: 'cancelled',
+                error: {
+                    code: 'API_DISPOSED',
+                    message: 'Camera Studio API 已销毁,任务随会话取消',
+                    retryable: false,
+                },
+            });
+        }
+    }
+}

package/dist/agent/jobs.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=jobs.test.d.ts.map

package/dist/agent/jobs.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.test.d.ts","sourceRoot":"","sources":["../../src/agent/jobs.test.ts"],"names":[],"mappings":""}