@mindscraft/branch-video-agent-cli 0.4.4 → 0.4.5

package/README.md

@@ -1,6 +1,20 @@
 # Branch Video Agent CLI
 
-`@mindscraft/branch-video-agent-cli` 是一个可脱离当前代码仓库使用的发布版 CLI，用于通过 Bearer agent token 调用 branch-video、AIHub workflow 与 AI Gateway agent API。
+`@mindscraft/branch-video-agent-cli` 是一个可脱离当前代码仓库使用的发布版 CLI，用于通过 Bearer agent token 调用 branch-video、AIHub workflow 与 AI Gateway agent API。
+
+## 图片持久任务（待发布）
+
+`ai-gateway image-generate` / `image-edit` 支持 `--async` 提交、`--wait` 等待，stdin JSON 必须含稳定 `idempotencyKey`。无这两个标记时保持同步兼容。
+
+```powershell
+'{"idempotencyKey":"asset-shot09-v1","model":"gpt-image-2","prompt":"原提示词"}' | branch-video-agent ai-gateway image-generate --async --raw 2>receipt.jsonl
+'{"idempotencyKey":"asset-shot09-v1"}' | branch-video-agent ai-gateway image-get --wait --raw
+'{"taskId":"img_..."}' | branch-video-agent ai-gateway image-get --raw
+```
+
+stderr 输出提交前幂等身份、提交后 taskId 回执；stdout 为单个 JSON。提交响应丢失后按同 key 查询或原样重提，不换 key。等待超时返回任务最后状态及 `waitStopped`，Ctrl+C 不取消服务器任务；unknown 需要人工核对，不能自动重新生成。成功结果保留 `data[].url`，URL 需同项目 Bearer 下载再进入现有资产上传流程，不是公开 CDN URL。
+
+完整 API、幂等与发布边界见仓库 `docs/ai-gateway-image-tasks.md`。本地构建验收需设 `BRANCH_VIDEO_AGENT_DISABLE_AUTO_UPDATE=1`，确保运行候选 dist 而非自动切换到 registry 版本；本任务不执行 npm 发布。
 
 ## 安装与执行
 
@@ -94,11 +108,11 @@ sidecar 使用 `branch-video-playtest/1`，Web 结果必须提供 iframe 内的
 
 支持 `click`、`fill`、`selectOption`、`check`、`press`、`dragTo`、`setInputFiles` 和 `waitFor`。只要输入中有合法 `reportDir`，静态门禁、契约、版本漂移和浏览器启动等前置失败也会输出 `branch-video-playtest-report.json`、`junit.xml`；失败场景另存截图、trace、视频和浏览器日志。若 Chromium 缺失，执行 `npx playwright install chromium`。
 
-CI 顺序为：V3 静态 self-test → 草稿 `playtest run` → 外部发布步骤 → `version get` 精确内容读回。发布内容与已测草稿一致时无需再跑发布版全量测试；内容变化后应重新测试。`playtest run` 自身始终只读，不承担发布。
-
-从 `0.4.3` 起，规划器删除被更长场景完整包含的有序前缀场景，保留条件、状态效果与全部目标边；场景数由实际图决定，不固定为 96。重复搜索状态也会合并以减少规划开销。覆盖或路径预算失败仍返回失败，不通过删边取得通过。复测时记录实际可执行文件路径；升级全局 npm 包不会更新任务内复制的旧 CLI。
-
-从 `0.4.4` 起，runner 在现有超时内等待“进入游戏”或“开始体验”入口；已开始播放时直接继续，后续节点和路由断言保持不变。
+CI 顺序为：V3 静态 self-test → 草稿 `playtest run` → 外部发布步骤 → `version get` 精确内容读回。发布内容与已测草稿一致时无需再跑发布版全量测试；内容变化后应重新测试。`playtest run` 自身始终只读，不承担发布。
+
+从 `0.4.3` 起，规划器删除被更长场景完整包含的有序前缀场景，保留条件、状态效果与全部目标边；场景数由实际图决定，不固定为 96。重复搜索状态也会合并以减少规划开销。覆盖或路径预算失败仍返回失败，不通过删边取得通过。复测时记录实际可执行文件路径；升级全局 npm 包不会更新任务内复制的旧 CLI。
+
+从 `0.4.4` 起，runner 在现有超时内等待“进入游戏”或“开始体验”入口；已开始播放时直接继续，后续节点和路由断言保持不变。
 
 AIHub 导入公共库示例：
 

package/dist/commands/aiGateway.js

@@ -127,6 +127,58 @@ function normalizeImageEditPayload(payload) {
         files,
     };
 }
+const imageTasksPath = '/api/agent/ai-gateway/images/tasks';
+function validateImageWait(context) {
+    if (context.flags.wait && [context.flags.timeoutMs, context.flags.pollIntervalMs].some((value) => !Number.isSafeInteger(value) || value <= 0)) {
+        throw new CliCommandError('Image wait timeout and poll interval must be positive integer milliseconds', 'VALIDATION_ERROR');
+    }
+}
+async function finishImageTask(context, initial) {
+    let task = initial;
+    context.runtime.writeStderr(`${JSON.stringify({ event: 'image-task', taskId: task.taskId, idempotencyKey: task.idempotencyKey, status: task.status })}\n`);
+    if (!context.flags.wait)
+        return { data: task };
+    const deadline = context.runtime.now() + context.flags.timeoutMs;
+    while (true) {
+        if (task.status === 'succeeded') {
+            const result = task.result || {};
+            return { data: { ...result, data: (result.data || []).map((item) => ({ ...item, url: context.client.resolveUrl(item.url) })),
+                    taskId: task.taskId, idempotencyKey: task.idempotencyKey, status: task.status } };
+        }
+        if (task.status === 'failed' || task.status === 'unknown') {
+            throw new CliCommandError(task.error?.message || `Image task ${task.status}`, task.status === 'unknown' ? 'RECONCILIATION_REQUIRED' : 'RUN_FAILED', task);
+        }
+        const remaining = deadline - context.runtime.now();
+        if (remaining <= 0)
+            return { data: { ...task, waitStopped: 'timeout', message: 'Local wait stopped; query this task to continue. No new submission was made.' } };
+        await context.runtime.sleep(Math.min(context.flags.pollIntervalMs, remaining));
+        if (context.runtime.now() >= deadline)
+            return { data: { ...task, waitStopped: 'timeout', message: 'Local wait stopped; query this task to continue. No new submission was made.' } };
+        try {
+            task = (await context.client.request(`${imageTasksPath}/${encodeURIComponent(task.taskId)}`, { method: 'GET', timeoutMs: Math.max(1, Math.min(15000, deadline - context.runtime.now())) })).data;
+        }
+        catch {
+            return { data: { ...task, waitStopped: context.runtime.now() >= deadline ? 'timeout' : 'query_error', message: 'Local wait stopped; task status is last observed. Recover using taskId.' } };
+        }
+    }
+}
+async function submitImage(context, operation) {
+    validateImageWait(context);
+    const idempotencyKey = getRequiredString(context.payload, 'idempotencyKey');
+    if (!/^[A-Za-z0-9._:-]{1,128}$/.test(idempotencyKey))
+        throw new CliCommandError('Invalid idempotencyKey', 'VALIDATION_ERROR');
+    const payload = omitKeys(context.payload, ['idempotencyKey']);
+    context.runtime.writeStderr(`${JSON.stringify({ event: 'image-submit', idempotencyKey, recovery: 'ai-gateway image-get' })}\n`);
+    let result;
+    try {
+        result = await context.client.request(imageTasksPath, { method: 'POST', timeoutMs: 15000,
+            body: { idempotencyKey, operation, body: operation === 'edits' ? normalizeImageEditPayload(payload) : payload } });
+    }
+    catch (error) {
+        throw new CliCommandError('Submission response unavailable or rejected; recover by idempotencyKey before any new generation.', 'IMAGE_SUBMIT_ERROR', { idempotencyKey, status: 'submission_unconfirmed', error: error instanceof Error ? error.message : String(error) });
+    }
+    return finishImageTask(context, result.data);
+}
 function inferMusicQueryOperation(operation) {
     switch (operation) {
         case 'vocal-removal':
@@ -197,20 +249,33 @@ export const aiGatewayCommands = {
         });
         return { data: result.data, requestId: result.requestId };
     },
-    'image-generate': async ({ client, payload }) => {
+    'image-generate': async (context) => {
+        if (context.flags.async || context.flags.wait)
+            return submitImage(context, 'generations');
+        const { client, payload } = context;
         const result = await client.request('/api/agent/ai-gateway/images/generations', {
             method: 'POST',
             body: payload,
         });
         return { data: result.data, requestId: result.requestId };
     },
-    'image-edit': async ({ client, payload }) => {
+    'image-edit': async (context) => {
+        if (context.flags.async || context.flags.wait)
+            return submitImage(context, 'edits');
+        const { client, payload } = context;
         const result = await client.request('/api/agent/ai-gateway/images/edits', {
             method: 'POST',
             body: normalizeImageEditPayload(payload),
         });
         return { data: result.data, requestId: result.requestId };
     },
+    'image-get': async (context) => {
+        validateImageWait(context);
+        const taskId = getOptionalString(context.payload, 'taskId');
+        const idempotencyKey = taskId ? '' : getRequiredString(context.payload, 'idempotencyKey');
+        const result = await context.client.request(taskId ? `${imageTasksPath}/${encodeURIComponent(taskId)}` : imageTasksPath, { method: 'GET', query: idempotencyKey ? { idempotencyKey } : undefined, timeoutMs: 15000 });
+        return finishImageTask(context, result.data);
+    },
     'video-create': async (context) => {
         const result = await context.client.request('/api/agent/ai-gateway/predictions', {
             method: 'POST',

package/dist/lib/flags.d.ts

@@ -3,6 +3,7 @@ import type { CliRuntime } from './runtime.js';
 export type CliFlags = {
     raw: boolean;
     wait: boolean;
+    async?: boolean;
     help: boolean;
     timeoutMs: number;
     pollIntervalMs: number;

package/dist/lib/flags.js

@@ -58,6 +58,9 @@ export function parseCliArgs(argv) {
             case '--wait':
                 flags.wait = true;
                 break;
+            case '--async':
+                flags.async = true;
+                break;
             case '--timeout':
                 flags.timeoutMs = Number(readValue(argv, index, arg));
                 index += 1;
@@ -100,7 +103,8 @@ export function getCliHelpText() {
         '  agent-production create | status | cancel | finalize | autopilot-binding | events | metrics | multica-comment-payload | node claim|inputs|complete|submit|block|fail|retry|expire | blocker resolve | artifact submit|list | asset-job poll|retry|revise|attach-artifact|fail | gate evaluate|results',
         '  aihub-production schema | start | status | retry',
         '  character  search | create | get',
-        '  ai-gateway capabilities | request | media-understand | image-generate | image-edit | video-create | video-get | seed-audio-create | seed-audio-get | music-submit | music-get | tts-create | tts-get',
+        '  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',
         '',
         'Config precedence:',

package/dist/lib/http.d.ts

@@ -2,6 +2,7 @@ type RequestOptions = {
     method: string;
     body?: unknown;
     query?: Record<string, unknown>;
+    timeoutMs?: number;
 };
 type RequestResult<T> = {
     data: T;

package/dist/lib/http.js

@@ -42,6 +42,7 @@ export class CliHttpClient {
                 method: options.method,
                 headers,
                 body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                signal: options.timeoutMs ? AbortSignal.timeout(options.timeoutMs) : undefined,
             });
         }
         catch (error) {

package/package.json

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