@mindscraft/branch-video-agent-cli 0.4.7 → 0.5.0

package/README.md

@@ -252,7 +252,61 @@ AI Gateway Seed Audio 音频生成并等待示例：
 '@ | npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- ai-gateway seed-audio-create -- --wait --raw
 ```
 
-`tts-create` / `tts-get` 是 Seed Audio 的历史兼容别名；新脚本优先使用 `seed-audio-create` / `seed-audio-get`。
+`tts-create` / `tts-get` 是 Seed Audio 的历史兼容别名；新脚本优先使用 `seed-audio-create` / `seed-audio-get`。
+
+## RPG2 生产工作台
+
+工作台 CLI 只提交调用方显式登记的项目、产物和归档清单；它不会扫描 RPG 阶段目录，也不会根据文件名推断版本关系。认证仍使用 `AIHUB_AGENT_TOKEN` 与 `BRANCH_VIDEO_AGENT_BASE_URL`，不要在 JSON、命令行或日志中保存 token。
+
+项目、生产记录和外部 CDN 产物可使用 JSON 文件提交：
+
+```powershell
+branch-video-agent workbench project create --file .\project.json --raw
+branch-video-agent workbench record put --project wb_project_id --file .\record.json --raw
+branch-video-agent workbench submit --file .\artifact-external.json --raw
+branch-video-agent workbench annotation put --project wb_project_id --file .\annotation.json --raw
+```
+
+同一产物用稳定的 `artifactKey` 和由流程侧持久维护的递增 `sourceRevision`。`idempotencyKey` 由流程侧保存并在重试时复用。已有持久媒体使用 `content.type: "external"`；本地文档、脱敏 session 或其他需要长期保存的文件使用 `content.type: "local"` 与 `sourcePath`。CLI 会先计算 SHA-256、声明 blob，再以原始二进制流上传；服务端只收到 blob 描述，绝不会收到本地路径。单文件上限为 64 MiB。
+
+```json
+{
+  "schemaVersion": "workbench.artifact/1",
+  "projectId": "wb_project_id",
+  "artifactKey": "document:director-program",
+  "sourceRevision": 2,
+  "idempotencyKey": "persisted-event-uuid",
+  "kind": "markdown",
+  "stageKey": "04",
+  "title": "导演稿",
+  "content": {
+    "type": "local",
+    "sourcePath": "C:/production/canonical/director.md",
+    "mime": "text/markdown"
+  },
+  "source": {
+    "productionRecordId": "record_id",
+    "archiveGeneration": 0,
+    "sourceSchema": "director-program/4"
+  }
+}
+```
+
+上传响应在网络中丢失时，CLI 会先查询同一个已声明 blob；ready 状态不会重传，也不会重新登记业务版本。失败交给流程侧持久待传队列用相同事件重试。
+
+`sync` 只读取 `--manifest` 中显式的 `items`。每个 item 为 `type: "artifact"`（默认）或 `type: "annotation"`，可直接携带提交字段或放进 `submission`；不会递归任何工作目录。
+
+```powershell
+branch-video-agent workbench sync --manifest .\.workbench\pending-items.json --raw
+branch-video-agent workbench archive prepare --manifest .\.workbench\archive-wrapper.json --raw
+branch-video-agent workbench archive finalize --project wb_project_id --record record_id --revision 1 --manifest-hash <sha256> --raw
+branch-video-agent workbench archive status --project wb_project_id --record record_id --raw
+branch-video-agent workbench archive download --project wb_project_id --record record_id --revision 1 --file .\entry.json --output .\session.jsonl.zst --raw
+```
+
+`archive prepare` 的文件是调用方维护的 wrapper：`{ manifest, manifestHash, expectedPreviousRevision }`；CLI 原样提交规范化清单和 hash。`archive finalize` 只校验已经提交的清单，不补扫文件。下载的 `entry.json` 至少包含 `{ "entryId": "..." }`；受权限保护的字节写入 `--output`，stdout 仍只输出 JSON 回执。
+
+`record put` 的路径参数是稳定的流程 `recordKey`，返回对象的 `id` 才是后续 `end-intent`、`reopen` 和所有 `archive` 命令使用的 `productionRecordId`（也可传给 `--record`）。不要把 `recordKey` 当成归档路由 ID。
 
 ## 在仓库内构建发布包
 
@@ -260,8 +314,16 @@ AI Gateway Seed Audio 音频生成并等待示例：
 
 ```powershell
 npm run agent:cli:package:build
-npm run agent:cli:package:smoke
-```
+npm run agent:cli:package:smoke
+```
+
+需要运行会启动 standalone Mongo、真实 CLI HTTP 流、Python adapter 或 Chromium 的 Production Workbench 集成验收时，使用专用命令；常规 `npm test` 会排除这些外部运行时依赖。adapter E2E 需要相邻的 rpg2 adapter checkout，或显式设置 `RPG2_WORKBENCH_ADAPTER_ROOT`；缺失 checkout、`zstd` 或 Chromium 时命令应失败。
+
+```powershell
+npm run test:workbench-cli-integration
+npm run test:workbench-adapter-e2e
+npm run test:workbench-integration
+```
 
 产物输出到：
 

package/dist/commands/workbench.d.ts

@@ -0,0 +1,2 @@
+import type { CommandHandler } from '../lib/types.js';
+export declare const workbenchCommands: Record<string, CommandHandler>;

package/dist/commands/workbench.js

@@ -0,0 +1,305 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { stat, writeFile } from 'node:fs/promises';
+import { Readable } from 'node:stream';
+import { CliCommandError } from '../lib/errors.js';
+import { ensureObject, getRequiredInt, getRequiredString, omitKeys, pickDefined } from '../lib/payload.js';
+const workbenchPath = '/api/production-workbench';
+const MAX_LOCAL_FILE_BYTES = 64 * 1024 * 1024;
+const blobPurposes = new Set(['artifact', 'manifest', 'session', 'evidence']);
+function payloadValue(payload, flagValue, key) {
+    return getRequiredString({ [key]: payload[key] || flagValue }, key);
+}
+function projectId(payload, flagValue) {
+    return payloadValue(payload, flagValue, 'projectId');
+}
+function productionRecordId(payload, flagValue) {
+    return getRequiredString({ productionRecordId: payload.productionRecordId || payload.recordId || flagValue }, 'productionRecordId');
+}
+function getRevision(payload, flagValue) {
+    return payload.revision === undefined && flagValue
+        ? getRequiredInt({ revision: flagValue }, 'revision')
+        : getRequiredInt(payload, 'revision');
+}
+function localContent(payload) {
+    const content = ensureObject(payload.content, 'content');
+    const sourcePath = typeof content.sourcePath === 'string' && content.sourcePath.trim()
+        ? content.sourcePath.trim()
+        : typeof payload.sourcePath === 'string' && payload.sourcePath.trim()
+            ? payload.sourcePath.trim()
+            : '';
+    return sourcePath ? { content, sourcePath } : null;
+}
+async function sha256File(sourcePath) {
+    const digest = createHash('sha256');
+    for await (const chunk of createReadStream(sourcePath))
+        digest.update(chunk);
+    return digest.digest('hex');
+}
+async function uploadLocalContent(context, sourcePath, content) {
+    let fileStat;
+    try {
+        fileStat = await stat(sourcePath);
+    }
+    catch (error) {
+        throw new CliCommandError(`Cannot read sourcePath: ${error?.message || error}`, 'VALIDATION_ERROR');
+    }
+    if (!fileStat.isFile())
+        throw new CliCommandError('sourcePath must be a regular file', 'VALIDATION_ERROR');
+    if (fileStat.size > MAX_LOCAL_FILE_BYTES)
+        throw new CliCommandError(`sourcePath exceeds ${MAX_LOCAL_FILE_BYTES} byte upload limit`, 'FILE_TOO_LARGE');
+    const sha256 = await sha256File(sourcePath);
+    if (typeof content.sha256 === 'string' && content.sha256 && content.sha256 !== sha256) {
+        throw new CliCommandError('sourcePath sha256 does not match content.sha256', 'VALIDATION_ERROR');
+    }
+    const mime = typeof content.mime === 'string' && content.mime ? content.mime : 'application/octet-stream';
+    const purpose = typeof content.purpose === 'string' && content.purpose ? content.purpose : 'artifact';
+    if (!blobPurposes.has(purpose))
+        throw new CliCommandError(`Invalid local content purpose: ${purpose}`, 'VALIDATION_ERROR');
+    const declared = await context.client.request(`${workbenchPath}/projects/${encodeURIComponent(projectId(context.payload, context.flags.project))}/blobs`, {
+        method: 'POST',
+        body: {
+            sha256,
+            size: fileStat.size,
+            mime,
+            purpose,
+            ...(content.redaction === undefined ? {} : { redaction: content.redaction }),
+        },
+        timeoutMs: context.flags.timeoutMs,
+    });
+    const blobId = getRequiredString(declared.data, 'id');
+    if (declared.data.state !== 'ready') {
+        let uploadError;
+        try {
+            await context.client.requestStream(`${workbenchPath}/projects/${encodeURIComponent(projectId(context.payload, context.flags.project))}/blobs/${encodeURIComponent(blobId)}/content`, {
+                method: 'PUT',
+                body: Readable.toWeb(createReadStream(sourcePath)),
+                contentType: mime,
+                timeoutMs: context.flags.timeoutMs,
+            });
+        }
+        catch (error) {
+            uploadError = error;
+        }
+        if (uploadError) {
+            const status = await context.client.request(`${workbenchPath}/projects/${encodeURIComponent(projectId(context.payload, context.flags.project))}/blobs/${encodeURIComponent(blobId)}`, {
+                method: 'GET',
+                timeoutMs: context.flags.timeoutMs,
+            });
+            if (status.data.state !== 'ready')
+                throw uploadError;
+        }
+    }
+    return { type: 'blob', blobId, sha256, size: fileStat.size, mime };
+}
+function validateSubmission(payload) {
+    if (payload.schemaVersion !== 'workbench.artifact/1') {
+        throw new CliCommandError('schemaVersion must be workbench.artifact/1', 'VALIDATION_ERROR');
+    }
+    getRequiredString(payload, 'artifactKey');
+    const sourceRevision = getRequiredInt(payload, 'sourceRevision');
+    if (sourceRevision < 1)
+        throw new CliCommandError('Invalid sourceRevision', 'VALIDATION_ERROR');
+    getRequiredString(payload, 'idempotencyKey');
+    getRequiredString(payload, 'title');
+    getRequiredString(payload, 'kind');
+    getRequiredString(payload, 'stageKey');
+    const source = ensureObject(payload.source, 'source');
+    getRequiredString(source, 'productionRecordId');
+    const archiveGeneration = getRequiredInt(source, 'archiveGeneration');
+    if (archiveGeneration < 0)
+        throw new CliCommandError('Invalid source.archiveGeneration', 'VALIDATION_ERROR');
+}
+async function submitArtifact(context, payload) {
+    const id = projectId(payload, context.flags.project);
+    validateSubmission(payload);
+    const local = localContent(payload);
+    let body = omitKeys(payload, ['projectId', 'sourcePath']);
+    if (local) {
+        const blob = await uploadLocalContent({ ...context, payload }, local.sourcePath, local.content);
+        body = { ...body, content: blob };
+    }
+    const result = await context.client.request(`${workbenchPath}/projects/${encodeURIComponent(id)}/artifact-versions`, {
+        method: 'POST',
+        body,
+        timeoutMs: context.flags.timeoutMs,
+    });
+    return { data: result.data, requestId: result.requestId };
+}
+async function readManifest(context) {
+    if (!context.flags.manifest)
+        throw new CliCommandError('Missing --manifest', 'VALIDATION_ERROR');
+    try {
+        return ensureObject(JSON.parse(await context.runtime.readTextFile(context.flags.manifest)), '--manifest');
+    }
+    catch (error) {
+        if (error instanceof CliCommandError)
+            throw error;
+        throw new CliCommandError(`Invalid JSON in --manifest: ${error?.message || error}`, 'VALIDATION_ERROR');
+    }
+}
+export const workbenchCommands = {
+    'project.create': async ({ client, payload }) => {
+        const result = await client.request(`${workbenchPath}/projects`, {
+            method: 'POST',
+            body: payload,
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    'project.get': async ({ client, payload, flags }) => {
+        const id = payloadValue(payload, flags.id, 'id');
+        const result = await client.request(`${workbenchPath}/projects/${encodeURIComponent(id)}`, { method: 'GET' });
+        return { data: result.data, requestId: result.requestId };
+    },
+    'project.list': async ({ client, payload }) => {
+        const result = await client.request(`${workbenchPath}/projects`, {
+            method: 'GET',
+            query: pickDefined(payload, ['cursor', 'limit', 'query']),
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    'project.update': async ({ client, payload, flags }) => {
+        const id = projectId(payload, flags.id);
+        const result = await client.request(`${workbenchPath}/projects/${encodeURIComponent(id)}`, {
+            method: 'PATCH',
+            body: omitKeys(payload, ['projectId']),
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    'record.put': async ({ client, payload, flags }) => {
+        const id = projectId(payload, flags.project);
+        const recordKey = payloadValue(payload, flags.record, 'recordKey');
+        const result = await client.request(`${workbenchPath}/projects/${encodeURIComponent(id)}/records/${encodeURIComponent(recordKey)}`, {
+            method: 'PUT',
+            body: omitKeys(payload, ['projectId', 'recordKey']),
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    'record.end-intent': async ({ client, payload, flags }) => {
+        const id = projectId(payload, flags.project);
+        const recordId = productionRecordId(payload, flags.record);
+        const result = await client.request(`${workbenchPath}/projects/${encodeURIComponent(id)}/records/${encodeURIComponent(recordId)}/end-intent`, {
+            method: 'POST',
+            body: omitKeys(payload, ['projectId', 'productionRecordId', 'recordId']),
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    'record.reopen': async ({ client, payload, flags }) => {
+        const id = projectId(payload, flags.project);
+        const recordId = productionRecordId(payload, flags.record);
+        const result = await client.request(`${workbenchPath}/projects/${encodeURIComponent(id)}/records/${encodeURIComponent(recordId)}/reopen`, {
+            method: 'POST',
+            body: omitKeys(payload, ['projectId', 'productionRecordId', 'recordId']),
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    'annotation.put': async ({ client, payload, flags }) => {
+        const id = projectId(payload, flags.project);
+        const result = await client.request(`${workbenchPath}/projects/${encodeURIComponent(id)}/annotations`, {
+            method: 'POST',
+            body: omitKeys(payload, ['projectId']),
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    'artifact.list': async ({ client, payload, flags }) => {
+        const id = projectId(payload, flags.project);
+        const result = await client.request(`${workbenchPath}/projects/${encodeURIComponent(id)}/artifacts`, {
+            method: 'GET', query: pickDefined(payload, ['kind', 'stageKey', 'query', 'cursor', 'limit']),
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    'artifact.versions': async ({ client, payload, flags }) => {
+        const id = projectId(payload, flags.project);
+        const result = await client.request(`${workbenchPath}/projects/${encodeURIComponent(id)}/artifact-versions`, {
+            method: 'GET', query: pickDefined(payload, ['artifactKey', 'idempotencyKey', 'cursor', 'limit']),
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    'blob.put': async (context) => {
+        projectId(context.payload, context.flags.project);
+        const local = localContent(context.payload);
+        if (!local)
+            throw new CliCommandError('blob put requires local content.sourcePath', 'VALIDATION_ERROR');
+        return { data: await uploadLocalContent(context, local.sourcePath, local.content) };
+    },
+    submit: async (context) => submitArtifact(context, context.payload),
+    sync: async (context) => {
+        const manifest = await readManifest(context);
+        const items = manifest.items;
+        if (!Array.isArray(items))
+            throw new CliCommandError('--manifest items must be an array', 'VALIDATION_ERROR');
+        const results = [];
+        for (const item of items) {
+            const entry = ensureObject(item, 'manifest item');
+            const type = typeof entry.type === 'string' ? entry.type : 'artifact';
+            const itemPayload = entry.submission === undefined
+                ? omitKeys(entry, ['type'])
+                : ensureObject(entry.submission, 'manifest item submission');
+            const merged = { ...itemPayload, projectId: itemPayload.projectId || manifest.projectId || context.flags.project };
+            if (type === 'artifact')
+                results.push((await submitArtifact(context, merged)).data);
+            else if (type === 'annotation') {
+                const id = projectId(merged, context.flags.project);
+                results.push((await context.client.request(`${workbenchPath}/projects/${encodeURIComponent(id)}/annotations`, {
+                    method: 'POST', body: omitKeys(merged, ['projectId']), timeoutMs: context.flags.timeoutMs,
+                })).data);
+            }
+            else
+                throw new CliCommandError(`Unsupported sync item type: ${type}`, 'VALIDATION_ERROR');
+        }
+        return { data: { items: results, nextCursor: null } };
+    },
+    'archive.prepare': async (context) => {
+        const wrapper = await readManifest(context);
+        const manifest = ensureObject(wrapper.manifest || wrapper, 'manifest');
+        const id = projectId(manifest, context.flags.project);
+        const recordKey = payloadValue(manifest, context.flags.record, 'productionRecordId');
+        const revision = getRequiredInt(manifest, 'revision');
+        const manifestHash = payloadValue(wrapper, context.flags.manifestHash, 'manifestHash');
+        const result = await context.client.request(`${workbenchPath}/projects/${encodeURIComponent(id)}/records/${encodeURIComponent(recordKey)}/manifests/${revision}`, {
+            method: 'PUT',
+            body: {
+                manifest,
+                manifestHash,
+                expectedPreviousRevision: wrapper.expectedPreviousRevision,
+            },
+            timeoutMs: context.flags.timeoutMs,
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    'archive.finalize': async ({ client, payload, flags }) => {
+        const id = projectId(payload, flags.project);
+        const recordId = productionRecordId(payload, flags.record);
+        const revision = getRevision(payload, flags.revision);
+        const manifestHash = payloadValue(payload, flags.manifestHash, 'manifestHash');
+        const result = await client.request(`${workbenchPath}/projects/${encodeURIComponent(id)}/records/${encodeURIComponent(recordId)}/manifests/${revision}/finalize`, {
+            method: 'POST',
+            body: { manifestHash, ...pickDefined(payload, ['archiveGeneration']) },
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    'archive.status': async ({ client, payload, flags }) => {
+        const id = projectId(payload, flags.project);
+        const recordId = productionRecordId(payload, flags.record);
+        const result = await client.request(`${workbenchPath}/projects/${encodeURIComponent(id)}/records/${encodeURIComponent(recordId)}/archive`, { method: 'GET' });
+        return { data: result.data, requestId: result.requestId };
+    },
+    'archive.download': async ({ client, payload, flags }) => {
+        const id = projectId(payload, flags.project);
+        const recordId = productionRecordId(payload, flags.record);
+        const revision = getRevision(payload, flags.revision);
+        const entryId = getRequiredString(payload, 'entryId');
+        if (!flags.output)
+            throw new CliCommandError('Missing --output', 'VALIDATION_ERROR');
+        const result = await client.requestBinary(`${workbenchPath}/projects/${encodeURIComponent(id)}/records/${encodeURIComponent(recordId)}/manifests/${revision}/files/${encodeURIComponent(entryId)}/content`, {
+            method: 'GET', timeoutMs: flags.timeoutMs,
+        });
+        try {
+            await writeFile(flags.output, result.data);
+        }
+        catch (error) {
+            throw new CliCommandError(`Cannot write --output: ${error?.message || error}`, 'VALIDATION_ERROR');
+        }
+        return { data: { output: flags.output, size: result.data.byteLength, contentType: result.contentType }, requestId: result.requestId };
+    },
+};

package/dist/index.js

@@ -7,6 +7,7 @@ import { workflowCommands } from './commands/workflow.js';
 import { characterCommands } from './commands/character.js';
 import { aiGatewayCommands } from './commands/aiGateway.js';
 import { playtestCommands } from './commands/playtest.js';
+import { workbenchCommands } from './commands/workbench.js';
 import { CliCommandError } from './lib/errors.js';
 import { getCliHelpText, parseCliArgs, resolveCliConfig } from './lib/flags.js';
 import { CliHttpClient } from './lib/http.js';
@@ -22,6 +23,7 @@ const commandRegistry = {
     character: characterCommands,
     'ai-gateway': aiGatewayCommands,
     playtest: playtestCommands,
+    workbench: workbenchCommands,
 };
 function normalizeError(error) {
     if (error instanceof CliCommandError) {
@@ -53,6 +55,16 @@ function writeError(runtime, command, raw, error) {
         meta: { command },
     });
 }
+async function readJsonFile(runtime, filePath, flag) {
+    try {
+        return ensureObject(JSON.parse(await runtime.readTextFile(filePath)));
+    }
+    catch (error) {
+        if (error instanceof CliCommandError)
+            throw error;
+        throw new CliCommandError(`Invalid JSON in ${flag}: ${error?.message || error}`, 'VALIDATION_ERROR');
+    }
+}
 export async function main(argv, runtime = createProcessRuntime()) {
     let commandName = '';
     let rawOutput = false;
@@ -79,7 +91,9 @@ export async function main(argv, runtime = createProcessRuntime()) {
                 throw new CliCommandError(`Invalid stdin JSON: ${error?.message || error}`, 'VALIDATION_ERROR');
             }
         }
-        const { baseUrl, token, commandPayload } = await resolveCliConfig(stdinPayload, parsed.flags, runtime);
+        const filePayload = parsed.flags.file ? await readJsonFile(runtime, parsed.flags.file, '--file') : {};
+        const mergedPayload = { ...filePayload, ...stdinPayload };
+        const { baseUrl, token, commandPayload } = await resolveCliConfig(mergedPayload, parsed.flags, runtime);
         const client = new CliHttpClient(baseUrl, token, runtime.fetchImpl);
         const result = await command({
             payload: commandPayload,

package/dist/lib/flags.d.ts

@@ -10,6 +10,14 @@ export type CliFlags = {
     baseUrlArg: string;
     tokenArg: string;
     tokenFile: string;
+    file: string;
+    manifest: string;
+    id: string;
+    project: string;
+    record: string;
+    revision: string;
+    manifestHash: string;
+    output: string;
 };
 export type ParsedCliArgs = {
     group: string;

package/dist/lib/flags.js

@@ -38,6 +38,14 @@ export function parseCliArgs(argv) {
         baseUrlArg: '',
         tokenArg: '',
         tokenFile: '',
+        file: '',
+        manifest: '',
+        id: '',
+        project: '',
+        record: '',
+        revision: '',
+        manifestHash: '',
+        output: '',
     };
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
@@ -81,6 +89,38 @@ export function parseCliArgs(argv) {
                 flags.tokenFile = readValue(argv, index, arg).trim();
                 index += 1;
                 break;
+            case '--file':
+                flags.file = readValue(argv, index, arg).trim();
+                index += 1;
+                break;
+            case '--manifest':
+                flags.manifest = readValue(argv, index, arg).trim();
+                index += 1;
+                break;
+            case '--id':
+                flags.id = readValue(argv, index, arg).trim();
+                index += 1;
+                break;
+            case '--project':
+                flags.project = readValue(argv, index, arg).trim();
+                index += 1;
+                break;
+            case '--record':
+                flags.record = readValue(argv, index, arg).trim();
+                index += 1;
+                break;
+            case '--revision':
+                flags.revision = readValue(argv, index, arg).trim();
+                index += 1;
+                break;
+            case '--manifest-hash':
+                flags.manifestHash = readValue(argv, index, arg).trim();
+                index += 1;
+                break;
+            case '--output':
+                flags.output = readValue(argv, index, arg).trim();
+                index += 1;
+                break;
             default:
                 throw new CliCommandError(`Unknown flag: ${arg}`, 'VALIDATION_ERROR');
         }
@@ -93,7 +133,7 @@ export function parseCliArgs(argv) {
 }
 export function getCliHelpText() {
     return [
-        'Usage: branch-video-agent <group> <action> [--wait] [--raw] [--timeout <ms>] [--poll-interval <ms>] [--base-url <url>] [--token <token>] [--token-file <path>]',
+        'Usage: branch-video-agent <group> <action> [--file <json>] [--manifest <json>] [--raw] [--timeout <ms>] [--base-url <url>] [--token-file <path>]',
         '',
         'Groups:',
         '  preset     list | upsert',
@@ -106,6 +146,7 @@ export function getCliHelpText() {
         '  ai-gateway capabilities | request | media-understand | image-generate | image-edit | image-get | video-create | video-get | seed-audio-create | seed-audio-get | music-submit | music-get | tts-create | tts-get',
         '  Images: --async (or --wait) requires stdin idempotencyKey; image-get accepts taskId or idempotencyKey. Recovery receipts go to stderr; stdout remains one JSON document.',
         '  playtest   run',
+        '  workbench  project create|get|list|update | record put|end-intent|reopen | submit | sync | annotation put | archive prepare|finalize|status|download',
         '',
         'Config precedence:',
         '  AIHUB_AGENT_TOKEN / BRANCH_VIDEO_AGENT_BASE_URL > stdin JSON or --token-file > command flags',

package/dist/lib/http.d.ts

@@ -9,6 +9,18 @@ type RequestResult<T> = {
     status: number;
     requestId: string | null;
 };
+type StreamRequestOptions = {
+    method: string;
+    body: ReadableStream<Uint8Array>;
+    contentType: string;
+    timeoutMs?: number;
+};
+type BinaryRequestResult = {
+    data: Uint8Array;
+    status: number;
+    requestId: string | null;
+    contentType: string | null;
+};
 export declare class CliHttpClient {
     private readonly baseUrl;
     private readonly token;
@@ -16,5 +28,10 @@ export declare class CliHttpClient {
     constructor(baseUrl: string, token: string, fetchImpl: typeof fetch);
     resolveUrl(path: string): string;
     request<T>(path: string, options: RequestOptions): Promise<RequestResult<T>>;
+    requestStream<T>(path: string, options: StreamRequestOptions): Promise<RequestResult<T>>;
+    requestBinary(path: string, options: {
+        method: string;
+        timeoutMs?: number;
+    }): Promise<BinaryRequestResult>;
 }
 export {};

package/dist/lib/http.js

@@ -17,6 +17,21 @@ function extractRequestId(response, parsed) {
         || response.headers.get('x-ai-gateway-request-id')
         || (typeof parsed?.requestId === 'string' ? parsed.requestId : null);
 }
+function parseResponseError(parsed, response) {
+    const error = typeof parsed === 'object' && parsed ? parsed?.error : undefined;
+    const nested = typeof error === 'object' && error ? error : undefined;
+    const message = typeof nested?.message === 'string'
+        ? nested.message
+        : typeof error === 'string'
+            ? error
+            : response.statusText || 'Request failed';
+    const code = typeof nested?.code === 'string'
+        ? nested.code
+        : typeof parsed?.code === 'string'
+            ? String(parsed.code)
+            : `HTTP_${response.status}`;
+    return { message, code };
+}
 export class CliHttpClient {
     baseUrl;
     token;
@@ -61,13 +76,8 @@ export class CliHttpClient {
             : null;
         const requestId = extractRequestId(response, parsed);
         if (!response.ok) {
-            const errorMessage = typeof parsed === 'object' && parsed && typeof parsed.error === 'string'
-                ? String(parsed.error)
-                : response.statusText || 'Request failed';
-            const errorCode = typeof parsed === 'object' && parsed && typeof parsed.code === 'string'
-                ? String(parsed.code)
-                : `HTTP_${response.status}`;
-            throw new CliCommandError(errorMessage, errorCode, parsed, requestId, response.status);
+            const error = parseResponseError(parsed, response);
+            throw new CliCommandError(error.message, error.code, parsed, requestId, response.status);
         }
         return {
             data: parsed,
@@ -75,4 +85,68 @@ export class CliHttpClient {
             requestId,
         };
     }
+    async requestStream(path, options) {
+        let response;
+        try {
+            response = await this.fetchImpl(buildUrl(this.baseUrl, path), {
+                method: options.method,
+                headers: {
+                    Authorization: `Bearer ${this.token}`,
+                    'content-type': options.contentType,
+                },
+                body: options.body,
+                duplex: 'half',
+                // A redirect to another origin must never receive the bearer token.
+                redirect: 'error',
+                signal: options.timeoutMs ? AbortSignal.timeout(options.timeoutMs) : undefined,
+            });
+        }
+        catch (error) {
+            throw new CliCommandError(error?.message || 'Network request failed', 'NETWORK_ERROR');
+        }
+        const text = await response.text();
+        const parsed = text
+            ? (() => {
+                try {
+                    return JSON.parse(text);
+                }
+                catch {
+                    return text;
+                }
+            })()
+            : null;
+        const requestId = extractRequestId(response, parsed);
+        if (!response.ok) {
+            const error = parseResponseError(parsed, response);
+            throw new CliCommandError(error.message, error.code, parsed, requestId, response.status);
+        }
+        return { data: parsed, status: response.status, requestId };
+    }
+    async requestBinary(path, options) {
+        let response;
+        try {
+            response = await this.fetchImpl(buildUrl(this.baseUrl, path), {
+                method: options.method,
+                headers: { Authorization: `Bearer ${this.token}` },
+                redirect: 'error',
+                signal: options.timeoutMs ? AbortSignal.timeout(options.timeoutMs) : undefined,
+            });
+        }
+        catch (error) {
+            throw new CliCommandError(error?.message || 'Network request failed', 'NETWORK_ERROR');
+        }
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        const requestId = response.headers.get('x-request-id') || response.headers.get('x-correlation-id');
+        if (!response.ok) {
+            const text = new TextDecoder().decode(bytes);
+            let parsed = text;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch { /* preserve plain error body */ }
+            const error = parseResponseError(parsed, response);
+            throw new CliCommandError(error.message, error.code, parsed, requestId, response.status);
+        }
+        return { data: bytes, status: response.status, requestId, contentType: response.headers.get('content-type') };
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindscraft/branch-video-agent-cli",
-  "version": "0.4.7",
+  "version": "0.5.0",
   "description": "Published CLI for branch-video and AIHub agent APIs.",
   "type": "module",
   "bin": {