diff --git a/README.md b/README.md index 5a7b133..e20c734 100644 --- a/README.md +++ b/README.md @@ -259,6 +259,13 @@ Agent mode redacts URL-like fields and adds next-step guidance for `sume jobs watch --agent --json` and `sume jobs result --agent --json`. +Timeout is not terminal for paid async work. After submitting Avatar or Avatar +Video jobs, keep the job ids in local state, poll with `sume jobs watch`, and +fetch terminal job/resource readback before reporting the workflow complete. If +`jobs watch` times out while jobs are still queued or processing, recheck with +`--timeout-seconds 0`, continue polling or ask whether to keep watching, and do +not submit duplicate paid jobs. + For natural creative prompt routing, see [docs/agent-workflows.md](docs/agent-workflows.md). For local bundled skill setup, see [docs/agent-skills.md](docs/agent-skills.md). The current public API diff --git a/agent/sume-avatar-video/SKILL.md b/agent/sume-avatar-video/SKILL.md index 96fc8bd..b963519 100644 --- a/agent/sume-avatar-video/SKILL.md +++ b/agent/sume-avatar-video/SKILL.md @@ -38,6 +38,13 @@ sume jobs result --agent --json sume avatar-videos get --agent --json ``` +Timeout is not terminal. After a paid submit, keep ownership until the job is +completed, failed, canceled, or the user explicitly tells you to stop. If +`jobs watch` times out while the job is non-terminal, rerun +`sume jobs watch --timeout-seconds 0 --agent --json` as a one-shot +status check, then continue polling or ask whether to keep watching. Do not +submit a duplicate paid job while recovering from timeout or transport failure. + Scripts are estimated locally and by the API; accepted target duration is 4-60 seconds inclusive. Use handles for avatar handoffs. Add `--product-image` when the user provides a public product/reference image; @@ -58,6 +65,10 @@ sume avatar-videos batch result ./avatar-videos.json --state-file ./avatar-video Read `references/avatar-video-batch-manifest.md` for manifest shape. Rerunning batch create with the same state file must not duplicate already submitted paid jobs. +For multiple submitted video jobs, poll all job ids together with +`sume jobs watch --ids , --agent --json` or an agent-managed +loop using `--timeout-seconds 0`, then fetch terminal job/resource readback +before reporting the workflow complete. ## Not For diff --git a/agent/sume-avatar/SKILL.md b/agent/sume-avatar/SKILL.md index 43f96ab..524036b 100644 --- a/agent/sume-avatar/SKILL.md +++ b/agent/sume-avatar/SKILL.md @@ -53,6 +53,14 @@ sume avatars batch watch ./avatars.json --state-file ./avatars.state.json --json sume avatars batch result ./avatars.json --state-file ./avatars.state.json --json ``` +Timeout is not terminal. After submitting paid avatar jobs, keep ownership of +the job set until every job is completed, failed, canceled, or the user +explicitly tells you to stop. If `batch watch` or `jobs watch` times out while +jobs are still non-terminal, run a one-shot aggregate status check such as +`sume jobs watch --ids , --timeout-seconds 0 --agent --json`, +then continue polling or ask whether to keep watching. Do not submit duplicate +paid jobs while recovering from a timeout. + Use ready avatar handles with `sume-avatar-video`. Rerunning batch create with the same state file must not duplicate already diff --git a/agent/sume-min-latency/SKILL.md b/agent/sume-min-latency/SKILL.md index b6d496f..10cd0f1 100644 --- a/agent/sume-min-latency/SKILL.md +++ b/agent/sume-min-latency/SKILL.md @@ -27,8 +27,12 @@ respecting paid gates and avoiding duplicate jobs. 4. For multiple independent candidates, draft a manifest and use batch plan/create/watch/result with a persistent state file. 5. Use stable idempotency keys. Reruns must skip already-created jobs. -6. Do not download media unless local comparison is required or the user asks. -7. If the user prioritizes speed/cost, explicitly choose `quality=standard`; +6. Timeout is not terminal. If `jobs watch` returns non-terminal jobs, run a + one-shot aggregate check with `--timeout-seconds 0`, then continue polling or + ask whether to keep watching. Do not final-answer as complete until terminal + result/resource readback exists or the user explicitly stops the workflow. +7. Do not download media unless local comparison is required or the user asks. +8. If the user prioritizes speed/cost, explicitly choose `quality=standard`; otherwise preserve the platform default quality. ## Fast Avatar Video Loop @@ -46,11 +50,21 @@ sume jobs watch --agent --json sume jobs result --agent --json ``` +For multiple jobs, use one aggregate watcher: + +```bash +sume jobs watch --ids , --agent --json +``` + +If it times out, do not submit replacement paid jobs. Recheck with +`--timeout-seconds 0`, keep polling, or ask whether to continue. + ## Report Report job id, resource id, requested quality, wall-clock time if measured, queue/run state, captured/refunded cost when available, and sanitized result -availability. Do not paste full media URLs. +availability. Report non-terminal jobs as still in progress, not complete. Do +not paste full media URLs. ## Not For diff --git a/agent/sume-spend-capped-dogfood/SKILL.md b/agent/sume-spend-capped-dogfood/SKILL.md index bdc2d1a..1fbe3a9 100644 --- a/agent/sume-spend-capped-dogfood/SKILL.md +++ b/agent/sume-spend-capped-dogfood/SKILL.md @@ -15,7 +15,9 @@ Use this skill when the user authorizes paid Sume QA with a hard budget. schema. - Use stable idempotency keys. - Use batch state files for more than one job. -- Stop once the evidence is sufficient. +- Stop once terminal evidence is sufficient. +- Timeout is not terminal. A paid job remains owned by the agent until it is + completed, failed, canceled, or the user explicitly tells you to stop. If a future release enables MCP paid tools, `idempotency_key` and `max_spend_usd` are mandatory. For current CLI commands, record the approved cap @@ -50,12 +52,19 @@ sume jobs result --agent --json sume balance --json ``` +If `jobs watch` times out while the job is still non-terminal, run +`sume jobs watch --timeout-seconds 0 --agent --json`, then continue +polling or ask whether to keep watching. Do not submit duplicate paid jobs while +recovering from timeout or transport failure. + ## Report Report requested quality, job id, resource id, expected/reserved/captured/ refunded cost when available, status/result, and whether the cap was respected. -If exact cost telemetry is missing, state that as a product gap instead of -inferring a billing guarantee. +If jobs are still non-terminal, say the workflow is still in progress and give +the resume/watch command instead of reporting completion. If exact cost +telemetry is missing, state that as a product gap instead of inferring a billing +guarantee. ## Not For diff --git a/agent/sume/SKILL.md b/agent/sume/SKILL.md index 72a3679..7b13210 100644 --- a/agent/sume/SKILL.md +++ b/agent/sume/SKILL.md @@ -25,10 +25,13 @@ Sume databases, internal app routes, Railway services, provider APIs, or old 5. Ask for explicit approval before `--confirm-submit` or `--confirm-paid`. 6. Paid work must use idempotency and a spend cap where the command/tool supports it. -7. Do not print API keys, auth approval URLs/codes in final reports, signed +7. Timeout is not terminal. After a paid submit, keep ownership until all jobs + are completed, failed, canceled, or the user explicitly tells you to stop. + Do not submit duplicate paid jobs while recovering from timeout. +8. Do not print API keys, auth approval URLs/codes in final reports, signed URLs, private media URLs, storage object keys, raw provider identifiers, workspace/user ids, or full result URLs. -8. Use current public launch API surfaces only: account, catalog, balance, +9. Use current public launch API surfaces only: account, catalog, balance, usage, jobs, Avatar 1.0, and Avatar Video 1.0. ## First Checks diff --git a/agent/sume/references/eval-scenarios.md b/agent/sume/references/eval-scenarios.md index 296c289..e1b7fc5 100644 --- a/agent/sume/references/eval-scenarios.md +++ b/agent/sume/references/eval-scenarios.md @@ -5,14 +5,19 @@ Use these scenarios to QA skill routing and safety behavior. 1. Missing auth: agent runs `sume doctor --agent --json`, sees missing auth, and asks for login/API-key setup without printing secrets in the final report. 2. Create several avatars: agent drafts a local avatar batch plan, asks for paid - approval, submits with idempotency keys, then watches jobs. + approval, submits with idempotency keys, watches all jobs together, treats + timeout as a re-evaluation point, and does not submit duplicate paid jobs. 3. Choose an avatar: agent lists ready avatars with `--agent --json`, compares names/status/artifacts, and asks the user to choose by taste. 4. Selected avatar to video: agent uses the chosen ready avatar handle with `sume avatar-videos create --confirm-paid --agent --json`, then watches - and reads result. + until terminal status and reads result/resource metadata. 5. Metadata/readback: agent calls `sume avatar-videos get` and `sume jobs result --agent --json`, summarizes status, scenes/tags/summary if present, and does not paste full URLs. 6. Paid gate: agent refuses to submit Avatar or Avatar Video jobs until the user explicitly authorizes paid generation work. +7. Timeout handling: if `jobs watch` returns non-terminal jobs, agent runs a + one-shot status aggregate, continues polling or asks whether to keep + watching, and does not final-answer as complete while paid jobs are still + processing. diff --git a/docs/agent-workflows.md b/docs/agent-workflows.md index 315cbde..4075f03 100644 --- a/docs/agent-workflows.md +++ b/docs/agent-workflows.md @@ -84,7 +84,7 @@ sume avatars batch result ./avatars.batch.json --state-file ./avatars.state.json ``` `batch plan` is local and does not call the API. `batch create` queues paid -paid generation jobs and uses stable per-item idempotency keys. Use +generation jobs and uses stable per-item idempotency keys. Use `sume avatars list --ready --agent --json` and ask the user to choose by taste. ## Avatar Video 1.0 @@ -126,8 +126,17 @@ After any submit command: 1. Capture `data.job.id` or `data.request_id` from the redacted response. 2. Poll with `sume jobs watch --agent --json` when using the CLI. -3. Read completed output with `sume jobs result --agent --json`. -4. Save media only on request with +3. For multiple independent jobs, poll all ids together with + `sume jobs watch --ids , --agent --json`. +4. Treat timeout as a re-evaluation point, not completion. If jobs are still + non-terminal, run a one-shot aggregate check with + `--timeout-seconds 0`, then continue polling or ask whether to keep + watching. +5. Do not submit duplicate paid jobs while recovering from timeout or transport + failure; reuse idempotency keys and local state. +6. Read completed output with `sume jobs result --agent --json` and the + relevant resource get command before reporting the workflow complete. +7. Save media only on request with `sume jobs download --output-dir ./outputs --json`. Sume MCP is coming soon and is not part of this public CLI launch release yet. @@ -139,3 +148,5 @@ Use direct CLI commands for current automation. - Use `--agent --json` for submit, watch, and result outputs read by agents. - Do not echo raw signed, private, or provider media URLs in final reports. - Reuse `--idempotency-key` for retries after timeouts or transport failures. +- Do not final-answer as complete while paid jobs are still queued or + processing unless the user explicitly tells you to stop watching. diff --git a/src/commands/avatar-videos.ts b/src/commands/avatar-videos.ts index 352b737..065f0a6 100644 --- a/src/commands/avatar-videos.ts +++ b/src/commands/avatar-videos.ts @@ -135,6 +135,8 @@ export function registerAvatarVideosCommand(program: Command) { .option("--webhook-url ", "Public HTTPS callback URL for webhook mode.") .option("--wait-timeout-seconds ", "Sync wait budget, 0-30 seconds.") .option("--idempotency-key ", "Idempotency-Key request header.") + .option("--agent", "Return an agent-safe redacted submission response.") + .option("--redact-urls", "Redact URL and sensitive fields from JSON output.") .option( "--confirm-submit", "Confirm the user approved creating or queueing this job.", diff --git a/src/commands/avatars.ts b/src/commands/avatars.ts index 664b71e..d9a0674 100644 --- a/src/commands/avatars.ts +++ b/src/commands/avatars.ts @@ -180,6 +180,8 @@ export function registerAvatarsCommand(program: Command) { .option("--webhook-url ", "Public HTTPS callback URL for webhook mode.") .option("--wait-timeout-seconds ", "Sync wait budget, 0-30 seconds.") .option("--idempotency-key ", "Idempotency-Key request header.") + .option("--agent", "Return an agent-safe redacted submission response.") + .option("--redact-urls", "Redact URL and sensitive fields from JSON output.") .option( "--confirm-submit", "Confirm the user approved creating or queueing this job.", diff --git a/src/commands/submit-helpers.ts b/src/commands/submit-helpers.ts index 60dc3bb..ee4dcc6 100644 --- a/src/commands/submit-helpers.ts +++ b/src/commands/submit-helpers.ts @@ -105,8 +105,9 @@ export function submissionTransform(value: unknown, options: SubmissionOptions) nextSteps: [ "Capture data.job.id or data.request_id from the submit response.", "Use sume jobs watch --agent --json to monitor the job.", - "Use sume jobs result --agent --json after the job completes.", - "Do not echo raw result URLs in agent reports.", + "If watch times out while the job is non-terminal, keep polling or ask the user before stopping; do not submit a duplicate paid job.", + "Use sume jobs result --agent --json after the job completes.", + "Do not echo raw result URLs in agent reports.", ], }); } diff --git a/src/lib/bundled-skills-data.ts b/src/lib/bundled-skills-data.ts index d861c1a..1b75725 100644 --- a/src/lib/bundled-skills-data.ts +++ b/src/lib/bundled-skills-data.ts @@ -1,38 +1,38 @@ export const bundledSkillFiles = { "sume": { - "SKILL.md": "---\nname: sume\ndescription: Router for current Sume.com public API workflows. Use for auth, schema discovery, Avatar 1.0, Avatar Video 1.0, jobs, spend-capped dogfooding, minimum-latency generation loops, media QA, and selecting focused Sume skills.\n---\n\n# Sume Skill Router\n\nStart here for Sume agent work. The executable source of truth is the `sume`\nCLI over current `api.sume.com`; this skill chooses the safest workflow and\npoints agents to focused skills.\n\nSume CLI must remain a thin wrapper over public API boundaries. Do not call\nSume databases, internal app routes, Railway services, provider APIs, or old\n`sume.so`-only surfaces.\n\n## Core Rules\n\n1. Run readiness checks when the local state is unknown.\n2. Use `sume tools list --json` and `sume tools schema --json` before\n constructing any write or paid request.\n3. Use `sume skills list --json` and `sume skills export --json` to\n discover bundled skill content instead of guessing.\n4. Use `--agent --json` whenever automation reads jobs, avatars, or avatar\n videos.\n5. Ask for explicit approval before `--confirm-submit` or `--confirm-paid`.\n6. Paid work must use idempotency and a spend cap where the command/tool\n supports it.\n7. Do not print API keys, auth approval URLs/codes in final reports, signed\n URLs, private media URLs, storage object keys, raw provider identifiers,\n workspace/user ids, or full result URLs.\n8. Use current public launch API surfaces only: account, catalog, balance,\n usage, jobs, Avatar 1.0, and Avatar Video 1.0.\n\n## First Checks\n\n```bash\nsume --version\nsume doctor --agent --json\nsume tools list --json\nsume skills list --json\n```\n\nUse `sume tools schema --json` before constructing writes. Do not copy\nrequest schemas from memory or from stale docs.\n\n## Auth\n\nUse browser login when the browser is local:\n\n```bash\nsume login\n```\n\nFor remote/headless terminals, use a short-lived background login process and\nshow the URL/code only to the requesting user. See `references/safety.md` for\nthe exact pattern.\n\n## Routing\n\n| User intent | Use skill | First command |\n| --- | --- | --- |\n| Schema, tool list, MCP status, skill setup | `sume-tools` | `sume tools list --json` |\n| Login, API key, local readiness | `sume-auth` | `sume auth status --json` |\n| Create or choose avatars | `sume-avatar` | `sume tools schema avatars.create --json` |\n| Generate videos from ready avatars | `sume-avatar-video` | `sume tools schema avatar-videos.create --json` |\n| Fastest safe iteration loop | `sume-min-latency` | local manifest/state file, then async create/watch/result |\n| Controlled quality comparisons | `sume-quality-experiment` | variant manifest, then schema check before paid calls |\n| Paid QA under an explicit cap | `sume-spend-capped-dogfood` | estimate/admission check if available, then idempotent capped submit |\n| Local result inspection/comparison | `sume-media-qa` | `sume jobs download --output-dir --json` |\n| Advanced compatibility assets | `sume-assets` | `sume tools schema assets.upload_url --json` |\n\nRead `references/safety.md` for auth, paid/write gates, and redaction rules.\nRead `references/eval-scenarios.md` when validating agent behavior.\n\n## MCP State\n\nSume MCP is coming soon and is not part of this public CLI launch release yet.\nUse direct CLI commands today.\n\n## Not For\n\nDo not use old `sume.so` Brand, Ads, Face Swap, generic image/video generation,\nraw provider model, billing-write, file, or asset-search workflows unless they\nappear in the current public `api.sume.com` catalog and tool schemas.\n", - "references/eval-scenarios.md": "# Sume Agent Eval Scenarios\n\nUse these scenarios to QA skill routing and safety behavior.\n\n1. Missing auth: agent runs `sume doctor --agent --json`, sees missing auth, and\n asks for login/API-key setup without printing secrets in the final report.\n2. Create several avatars: agent drafts a local avatar batch plan, asks for paid\n approval, submits with idempotency keys, then watches jobs.\n3. Choose an avatar: agent lists ready avatars with `--agent --json`, compares\n names/status/artifacts, and asks the user to choose by taste.\n4. Selected avatar to video: agent uses the chosen ready avatar handle\n with `sume avatar-videos create --confirm-paid --agent --json`, then watches\n and reads result.\n5. Metadata/readback: agent calls `sume avatar-videos get` and\n `sume jobs result --agent --json`, summarizes status, scenes/tags/summary if\n present, and does not paste full URLs.\n6. Paid gate: agent refuses to submit Avatar or Avatar Video jobs until the user\n explicitly authorizes paid generation work.\n", - "references/safety.md": "# Sume Safety Reference\n\n## Auth\n\n- Prefer `sume login` only when the browser is on the same machine.\n- In remote/headless terminals, avoid a long foreground login waiter because\n intermediate auth URLs/codes can be hidden until timeout or persisted in logs.\n- Use a short-lived process log:\n\n```bash\nlogin_log=\"$(mktemp -t sume-login.XXXXXX.log)\"\n(sume login --no-browser --timeout 600 >\"$login_log\" 2>&1; echo $? >\"$login_log.status\") &\nlogin_pid=$!\nsleep 4\nsed -n '1,80p' \"$login_log\"\n```\n\nAfter user approval:\n\n```bash\nwait \"$login_pid\"\nsume auth status --json\nrm -f \"$login_log\" \"$login_log.status\"\n```\n\n## Gates\n\n- `--confirm-submit`: non-paid writes such as asset registration, upload\n completion, and job cancellation.\n- `--confirm-paid`: paid generation submits such as Avatar 1.0 and Avatar Video\n 1.0 creation.\n\n## Sensitive Outputs\n\nNever echo API keys, approval codes, signed upload/download URLs, private media\nURLs, storage object keys, raw auth headers, provider ids, workspace/user ids,\nor full result URLs in reports. Use `--agent --json` and summarize redacted\nmetadata.\n\n## Current Public Boundary\n\nAllowed current launch surfaces: `GET /me`, `GET /catalog`, `GET /balance`,\n`GET /usage`, jobs, Avatar 1.0 model runs, Avatar Video 1.0 model runs, avatar\nresources, and avatar-video resources. `/v1/assets/*` is advanced\ncompatibility tooling only and is hidden from the launch OpenAPI/catalog.\n\nExcluded until public contracts exist: old Brand, Ads, Face Swap, generic\nimage/video generation, arbitrary file APIs, provider ids, and billing-write\noperations.\n\nSume MCP is coming soon and is not part of this public CLI launch release yet.\nUse direct CLI commands today.\n" + "references/eval-scenarios.md": "# Sume Agent Eval Scenarios\n\nUse these scenarios to QA skill routing and safety behavior.\n\n1. Missing auth: agent runs `sume doctor --agent --json`, sees missing auth, and\n asks for login/API-key setup without printing secrets in the final report.\n2. Create several avatars: agent drafts a local avatar batch plan, asks for paid\n approval, submits with idempotency keys, watches all jobs together, treats\n timeout as a re-evaluation point, and does not submit duplicate paid jobs.\n3. Choose an avatar: agent lists ready avatars with `--agent --json`, compares\n names/status/artifacts, and asks the user to choose by taste.\n4. Selected avatar to video: agent uses the chosen ready avatar handle\n with `sume avatar-videos create --confirm-paid --agent --json`, then watches\n until terminal status and reads result/resource metadata.\n5. Metadata/readback: agent calls `sume avatar-videos get` and\n `sume jobs result --agent --json`, summarizes status, scenes/tags/summary if\n present, and does not paste full URLs.\n6. Paid gate: agent refuses to submit Avatar or Avatar Video jobs until the user\n explicitly authorizes paid generation work.\n7. Timeout handling: if `jobs watch` returns non-terminal jobs, agent runs a\n one-shot status aggregate, continues polling or asks whether to keep\n watching, and does not final-answer as complete while paid jobs are still\n processing.\n", + "references/safety.md": "# Sume Safety Reference\n\n## Auth\n\n- Prefer `sume login` only when the browser is on the same machine.\n- In remote/headless terminals, avoid a long foreground login waiter because\n intermediate auth URLs/codes can be hidden until timeout or persisted in logs.\n- Use a short-lived process log:\n\n```bash\nlogin_log=\"$(mktemp -t sume-login.XXXXXX.log)\"\n(sume login --no-browser --timeout 600 >\"$login_log\" 2>&1; echo $? >\"$login_log.status\") &\nlogin_pid=$!\nsleep 4\nsed -n '1,80p' \"$login_log\"\n```\n\nAfter user approval:\n\n```bash\nwait \"$login_pid\"\nsume auth status --json\nrm -f \"$login_log\" \"$login_log.status\"\n```\n\n## Gates\n\n- `--confirm-submit`: non-paid writes such as asset registration, upload\n completion, and job cancellation.\n- `--confirm-paid`: paid generation submits such as Avatar 1.0 and Avatar Video\n 1.0 creation.\n\n## Sensitive Outputs\n\nNever echo API keys, approval codes, signed upload/download URLs, private media\nURLs, storage object keys, raw auth headers, provider ids, workspace/user ids,\nor full result URLs in reports. Use `--agent --json` and summarize redacted\nmetadata.\n\n## Current Public Boundary\n\nAllowed current launch surfaces: `GET /me`, `GET /catalog`, `GET /balance`,\n`GET /usage`, jobs, Avatar 1.0 model runs, Avatar Video 1.0 model runs, avatar\nresources, and avatar-video resources. `/v1/assets/*` is advanced\ncompatibility tooling only and is hidden from the launch OpenAPI/catalog.\n\nExcluded until public contracts exist: old Brand, Ads, Face Swap, generic\nimage/video generation, arbitrary file APIs, provider ids, and billing-write\noperations.\n\nSume MCP is coming soon and is not part of this public CLI launch release yet.\nUse direct CLI commands today.\n", + "SKILL.md": "---\nname: sume\ndescription: Router for current Sume.com public API workflows. Use for auth, schema discovery, Avatar 1.0, Avatar Video 1.0, jobs, spend-capped dogfooding, minimum-latency generation loops, media QA, and selecting focused Sume skills.\n---\n\n# Sume Skill Router\n\nStart here for Sume agent work. The executable source of truth is the `sume`\nCLI over current `api.sume.com`; this skill chooses the safest workflow and\npoints agents to focused skills.\n\nSume CLI must remain a thin wrapper over public API boundaries. Do not call\nSume databases, internal app routes, Railway services, provider APIs, or old\n`sume.so`-only surfaces.\n\n## Core Rules\n\n1. Run readiness checks when the local state is unknown.\n2. Use `sume tools list --json` and `sume tools schema --json` before\n constructing any write or paid request.\n3. Use `sume skills list --json` and `sume skills export --json` to\n discover bundled skill content instead of guessing.\n4. Use `--agent --json` whenever automation reads jobs, avatars, or avatar\n videos.\n5. Ask for explicit approval before `--confirm-submit` or `--confirm-paid`.\n6. Paid work must use idempotency and a spend cap where the command/tool\n supports it.\n7. Timeout is not terminal. After a paid submit, keep ownership until all jobs\n are completed, failed, canceled, or the user explicitly tells you to stop.\n Do not submit duplicate paid jobs while recovering from timeout.\n8. Do not print API keys, auth approval URLs/codes in final reports, signed\n URLs, private media URLs, storage object keys, raw provider identifiers,\n workspace/user ids, or full result URLs.\n9. Use current public launch API surfaces only: account, catalog, balance,\n usage, jobs, Avatar 1.0, and Avatar Video 1.0.\n\n## First Checks\n\n```bash\nsume --version\nsume doctor --agent --json\nsume tools list --json\nsume skills list --json\n```\n\nUse `sume tools schema --json` before constructing writes. Do not copy\nrequest schemas from memory or from stale docs.\n\n## Auth\n\nUse browser login when the browser is local:\n\n```bash\nsume login\n```\n\nFor remote/headless terminals, use a short-lived background login process and\nshow the URL/code only to the requesting user. See `references/safety.md` for\nthe exact pattern.\n\n## Routing\n\n| User intent | Use skill | First command |\n| --- | --- | --- |\n| Schema, tool list, MCP status, skill setup | `sume-tools` | `sume tools list --json` |\n| Login, API key, local readiness | `sume-auth` | `sume auth status --json` |\n| Create or choose avatars | `sume-avatar` | `sume tools schema avatars.create --json` |\n| Generate videos from ready avatars | `sume-avatar-video` | `sume tools schema avatar-videos.create --json` |\n| Fastest safe iteration loop | `sume-min-latency` | local manifest/state file, then async create/watch/result |\n| Controlled quality comparisons | `sume-quality-experiment` | variant manifest, then schema check before paid calls |\n| Paid QA under an explicit cap | `sume-spend-capped-dogfood` | estimate/admission check if available, then idempotent capped submit |\n| Local result inspection/comparison | `sume-media-qa` | `sume jobs download --output-dir --json` |\n| Advanced compatibility assets | `sume-assets` | `sume tools schema assets.upload_url --json` |\n\nRead `references/safety.md` for auth, paid/write gates, and redaction rules.\nRead `references/eval-scenarios.md` when validating agent behavior.\n\n## MCP State\n\nSume MCP is coming soon and is not part of this public CLI launch release yet.\nUse direct CLI commands today.\n\n## Not For\n\nDo not use old `sume.so` Brand, Ads, Face Swap, generic image/video generation,\nraw provider model, billing-write, file, or asset-search workflows unless they\nappear in the current public `api.sume.com` catalog and tool schemas.\n" }, "sume-assets": { - "SKILL.md": "---\nname: sume-assets\ndescription: Use advanced compatibility Sume asset upload/download helpers only when explicitly requested; launch Avatar and Avatar Video inputs should use stable public HTTPS URLs directly.\n---\n\n# Sume Assets\n\nUse this skill only when the user explicitly asks for advanced compatibility\n`api.sume.com` asset tooling. `/v1/assets/*` is hidden from the launch\nOpenAPI/catalog; normal Avatar and Avatar Video generation should use stable\npublic HTTPS URLs directly.\n\n## Discover Contracts\n\n```bash\nsume tools schema assets.create --json\nsume tools schema assets.upload_url --json\nsume tools schema assets.complete --json\nsume tools schema assets.download_url --json\n```\n\n## Register Public URL\n\n```bash\nsume assets create \\\n --source-url https://example.com/reference.png \\\n --media-type image \\\n --confirm-submit \\\n --agent \\\n --json\n```\n\nOnly register public HTTPS URLs that the user approved. The public API does not\necho the original source URL in readback.\n\n## Direct Upload\n\nUse `assets upload-url`, PUT bytes outside the CLI, then `assets complete`.\nNever paste signed URLs into reports.\n\n## Download\n\nUse CLI download helpers only when the user asks for local files:\n\n```bash\nsume assets download --output-dir ./outputs --json\nsume jobs download --output-dir ./outputs --json\n```\n\nRead `references/media-workflows.md` for details.\n\n## Not For\n\nDo not use assets as the default launch upload path, and do not pass asset ids\ninto generation requests unless the current OpenAPI schema explicitly accepts\nthem. Do not use old Asset Library scene search or `uploads/presign`; those are\n`sume.so`-only unless the current public catalog exposes them. Do not use this\nskill for paid generation; route Avatar work to `sume-avatar`, Avatar Video work\nto `sume-avatar-video`, and local comparison work to `sume-media-qa`.\n", - "references/media-workflows.md": "# Media Workflows\n\n## Upload Safety\n\n- Signed upload URLs and headers are temporary credentials.\n- Do not send Sume API auth headers to signed storage URLs.\n- Direct upload helpers should keep signed URLs internal and return only\n redacted asset metadata.\n\n## Download Safety\n\n- Download only into an explicit user-approved output directory.\n- Download helpers should accept only URL fields returned by public Sume job or\n asset responses.\n- Final reports should summarize local filenames, sizes, and counts, not remote\n URLs.\n\n## Asset Usage\n\nLaunch model-run inputs accept URL references where the OpenAPI schema defines\nmedia fields. `/v1/assets/*` remains an advanced compatibility workflow, not the\ndefault public upload path. Do not assume an asset id is valid in a submit\nrequest unless the schema says so.\n" + "references/media-workflows.md": "# Media Workflows\n\n## Upload Safety\n\n- Signed upload URLs and headers are temporary credentials.\n- Do not send Sume API auth headers to signed storage URLs.\n- Direct upload helpers should keep signed URLs internal and return only\n redacted asset metadata.\n\n## Download Safety\n\n- Download only into an explicit user-approved output directory.\n- Download helpers should accept only URL fields returned by public Sume job or\n asset responses.\n- Final reports should summarize local filenames, sizes, and counts, not remote\n URLs.\n\n## Asset Usage\n\nLaunch model-run inputs accept URL references where the OpenAPI schema defines\nmedia fields. `/v1/assets/*` remains an advanced compatibility workflow, not the\ndefault public upload path. Do not assume an asset id is valid in a submit\nrequest unless the schema says so.\n", + "SKILL.md": "---\nname: sume-assets\ndescription: Use advanced compatibility Sume asset upload/download helpers only when explicitly requested; launch Avatar and Avatar Video inputs should use stable public HTTPS URLs directly.\n---\n\n# Sume Assets\n\nUse this skill only when the user explicitly asks for advanced compatibility\n`api.sume.com` asset tooling. `/v1/assets/*` is hidden from the launch\nOpenAPI/catalog; normal Avatar and Avatar Video generation should use stable\npublic HTTPS URLs directly.\n\n## Discover Contracts\n\n```bash\nsume tools schema assets.create --json\nsume tools schema assets.upload_url --json\nsume tools schema assets.complete --json\nsume tools schema assets.download_url --json\n```\n\n## Register Public URL\n\n```bash\nsume assets create \\\n --source-url https://example.com/reference.png \\\n --media-type image \\\n --confirm-submit \\\n --agent \\\n --json\n```\n\nOnly register public HTTPS URLs that the user approved. The public API does not\necho the original source URL in readback.\n\n## Direct Upload\n\nUse `assets upload-url`, PUT bytes outside the CLI, then `assets complete`.\nNever paste signed URLs into reports.\n\n## Download\n\nUse CLI download helpers only when the user asks for local files:\n\n```bash\nsume assets download --output-dir ./outputs --json\nsume jobs download --output-dir ./outputs --json\n```\n\nRead `references/media-workflows.md` for details.\n\n## Not For\n\nDo not use assets as the default launch upload path, and do not pass asset ids\ninto generation requests unless the current OpenAPI schema explicitly accepts\nthem. Do not use old Asset Library scene search or `uploads/presign`; those are\n`sume.so`-only unless the current public catalog exposes them. Do not use this\nskill for paid generation; route Avatar work to `sume-avatar`, Avatar Video work\nto `sume-avatar-video`, and local comparison work to `sume-media-qa`.\n" }, "sume-auth": { "SKILL.md": "---\nname: sume-auth\ndescription: Set up and verify Sume CLI authentication safely, including browser login, API-key readiness, doctor checks, and headless-terminal caveats without exposing secrets.\n---\n\n# Sume Auth\n\nUse this skill for local CLI readiness, login, and API-key configuration.\n\n## Discover\n\n```bash\nsume --version\nsume auth status --json\nsume doctor --agent --json\n```\n\n## Local Browser Login\n\nUse browser login only when the browser is on the same machine as the CLI\nprocess:\n\n```bash\nsume login\nsume auth status --json\n```\n\n## Headless Or Remote Terminals\n\nIn remote/headless terminals, avoid long foreground login waiters because\napproval URLs/codes can be hidden until timeout or retained in logs. Use the\nshort-lived process-log pattern in `sume/references/safety.md`, surface the\napproval URL/code only to the requesting user, and delete logs after approval.\n\n## API Keys\n\nPrefer approved local config or environment variables. Do not ask the user to\npaste API keys into chat unless they explicitly choose manual key setup.\n\n## Not For\n\nDo not run paid generation, uploads, downloads, MCP setup, or production\ninfrastructure work from this skill. Do not print auth URLs/codes, API keys, or\nlocal config contents in final reports, issues, PRs, or persistent logs.\n" }, "sume-avatar": { - "SKILL.md": "---\nname: sume-avatar\ndescription: Create, batch-plan, watch, inspect, and select current Sume Avatar 1.0 resources by avatar_handle with safe paid gates and agent-redacted readback.\n---\n\n# Sume Avatar\n\nUse this skill for Avatar 1.0 creation and selection.\nUse `sume tools schema avatars.create --json` before constructing writes; do\nnot copy request schemas from memory.\n\n## Discover\n\n```bash\nsume tools schema avatars.create --json\nsume tools schema avatars.list --json\nsume tools schema avatars.batch.plan --json\nsume tools schema jobs.watch --json\n```\n\n## Single Avatar\n\n```bash\nsume avatars create \\\n --type prompt \\\n --avatar-handle presenter \\\n --prompt \"Friendly skincare presenter\" \\\n --confirm-paid \\\n --agent \\\n --json\n```\n\nPhoto and profile-style creation are current public inputs:\n\n```bash\nsume avatars create --type photo --avatar-handle photo_ref --image-url https://example.com/person.png --confirm-paid --agent --json\nsume avatars create --type props --avatar-handle profile --ethnicity Asian --sex female --age 28 --confirm-paid --agent --json\n```\n\n## Several Avatars\n\nPlan locally first:\n\n```bash\nsume avatars batch plan ./avatars.json --output-file ./avatars.plan.json --json\n```\n\nAfter explicit paid approval:\n\n```bash\nsume avatars batch create ./avatars.json --state-file ./avatars.state.json --confirm-paid --json\nsume avatars batch watch ./avatars.json --state-file ./avatars.state.json --json\nsume avatars batch result ./avatars.json --state-file ./avatars.state.json --json\n```\n\nUse ready avatar handles with `sume-avatar-video`.\n\nRerunning batch create with the same state file must not duplicate already\nsubmitted paid jobs.\n\n## Selection\n\n```bash\nsume avatars list --ready --agent --json\nsume avatars list --handle presenter --agent --json\nsume avatars get --agent --json\n```\n\nSummarize name, status, creation style, artifacts count, and any taste-relevant\nmetadata. Do not paste raw media URLs.\n\n## Not For\n\nDo not use this skill for Avatar Video generation, generic image/video\ngeneration, old `sume.so` Brand/Ads/Face Swap workflows, raw provider models,\nor paid QA experiments. Use `sume-avatar-video`, `sume-quality-experiment`, or\n`sume-spend-capped-dogfood` as appropriate.\n", - "references/avatar-batch-manifest.md": "# Avatar Batch Manifest\n\n```json\n{\n \"defaults\": {\n \"mode\": \"async\"\n },\n \"avatars\": [\n {\n \"id\": \"friendly\",\n \"type\": \"prompt\",\n \"avatar_handle\": \"friendly_presenter\",\n \"prompt\": \"Warm, direct-to-camera skincare presenter\"\n },\n {\n \"id\": \"photo\",\n \"type\": \"photo\",\n \"avatar_handle\": \"photo_reference\",\n \"image_url\": \"https://example.com/person.png\"\n },\n {\n \"id\": \"profile\",\n \"type\": \"props\",\n \"avatar_handle\": \"profile_presenter\",\n \"ethnicity\": \"Asian\",\n \"sex\": \"female\",\n \"age\": 28\n }\n ]\n}\n```\n\n`batch plan` is local and no-provider. `batch create` is paid generation\nand must use `--confirm-paid`. Reruns with the same state file should not create\nduplicate jobs for items that already have a job id.\n" + "references/avatar-batch-manifest.md": "# Avatar Batch Manifest\n\n```json\n{\n \"defaults\": {\n \"mode\": \"async\"\n },\n \"avatars\": [\n {\n \"id\": \"friendly\",\n \"type\": \"prompt\",\n \"avatar_handle\": \"friendly_presenter\",\n \"prompt\": \"Warm, direct-to-camera skincare presenter\"\n },\n {\n \"id\": \"photo\",\n \"type\": \"photo\",\n \"avatar_handle\": \"photo_reference\",\n \"image_url\": \"https://example.com/person.png\"\n },\n {\n \"id\": \"profile\",\n \"type\": \"props\",\n \"avatar_handle\": \"profile_presenter\",\n \"ethnicity\": \"Asian\",\n \"sex\": \"female\",\n \"age\": 28\n }\n ]\n}\n```\n\n`batch plan` is local and no-provider. `batch create` is paid generation\nand must use `--confirm-paid`. Reruns with the same state file should not create\nduplicate jobs for items that already have a job id.\n", + "SKILL.md": "---\nname: sume-avatar\ndescription: Create, batch-plan, watch, inspect, and select current Sume Avatar 1.0 resources by avatar_handle with safe paid gates and agent-redacted readback.\n---\n\n# Sume Avatar\n\nUse this skill for Avatar 1.0 creation and selection.\nUse `sume tools schema avatars.create --json` before constructing writes; do\nnot copy request schemas from memory.\n\n## Discover\n\n```bash\nsume tools schema avatars.create --json\nsume tools schema avatars.list --json\nsume tools schema avatars.batch.plan --json\nsume tools schema jobs.watch --json\n```\n\n## Single Avatar\n\n```bash\nsume avatars create \\\n --type prompt \\\n --avatar-handle presenter \\\n --prompt \"Friendly skincare presenter\" \\\n --confirm-paid \\\n --agent \\\n --json\n```\n\nPhoto and profile-style creation are current public inputs:\n\n```bash\nsume avatars create --type photo --avatar-handle photo_ref --image-url https://example.com/person.png --confirm-paid --agent --json\nsume avatars create --type props --avatar-handle profile --ethnicity Asian --sex female --age 28 --confirm-paid --agent --json\n```\n\n## Several Avatars\n\nPlan locally first:\n\n```bash\nsume avatars batch plan ./avatars.json --output-file ./avatars.plan.json --json\n```\n\nAfter explicit paid approval:\n\n```bash\nsume avatars batch create ./avatars.json --state-file ./avatars.state.json --confirm-paid --json\nsume avatars batch watch ./avatars.json --state-file ./avatars.state.json --json\nsume avatars batch result ./avatars.json --state-file ./avatars.state.json --json\n```\n\nTimeout is not terminal. After submitting paid avatar jobs, keep ownership of\nthe job set until every job is completed, failed, canceled, or the user\nexplicitly tells you to stop. If `batch watch` or `jobs watch` times out while\njobs are still non-terminal, run a one-shot aggregate status check such as\n`sume jobs watch --ids , --timeout-seconds 0 --agent --json`,\nthen continue polling or ask whether to keep watching. Do not submit duplicate\npaid jobs while recovering from a timeout.\n\nUse ready avatar handles with `sume-avatar-video`.\n\nRerunning batch create with the same state file must not duplicate already\nsubmitted paid jobs.\n\n## Selection\n\n```bash\nsume avatars list --ready --agent --json\nsume avatars list --handle presenter --agent --json\nsume avatars get --agent --json\n```\n\nSummarize name, status, creation style, artifacts count, and any taste-relevant\nmetadata. Do not paste raw media URLs.\n\n## Not For\n\nDo not use this skill for Avatar Video generation, generic image/video\ngeneration, old `sume.so` Brand/Ads/Face Swap workflows, raw provider models,\nor paid QA experiments. Use `sume-avatar-video`, `sume-quality-experiment`, or\n`sume-spend-capped-dogfood` as appropriate.\n" }, "sume-avatar-video": { - "SKILL.md": "---\nname: sume-avatar-video\ndescription: Create, batch-plan, watch, and inspect Sume Avatar Video 1.0 jobs from selected avatar handles, including productless/product-image flows, metadata readback, and paid gates.\n---\n\n# Sume Avatar Video\n\nUse this skill after a ready avatar is selected.\nUse `sume tools schema avatar-videos.create --json` before constructing writes;\ndo not copy request schemas from memory.\n\n## Discover\n\n```bash\nsume tools schema avatar-videos.create --json\nsume tools schema avatar-videos.get --json\nsume tools schema avatar-videos.batch.plan --json\nsume tools schema jobs.result --json\n```\n\n## Single Video\n\n```bash\nsume avatar-videos create \\\n --avatar-handle \\\n --script \"This serum absorbs quickly.\" \\\n --scene-prompt \"Bright clean studio\" \\\n --confirm-paid \\\n --agent \\\n --json\n```\n\nThen:\n\n```bash\nsume jobs watch --agent --json\nsume jobs result --agent --json\nsume avatar-videos get --agent --json\n```\n\nScripts are estimated locally and by the API; accepted target duration is 4-60\nseconds inclusive. Use handles for avatar handoffs.\nAdd `--product-image` when the user provides a public product/reference image;\nomit it for productless avatar videos.\n\nSummarize status, artifacts, duration, tags, scenes, transcript, and summary\nwhen present. Do not paste full media URLs.\n\n## Batch Videos\n\n```bash\nsume avatar-videos batch plan ./avatar-videos.json --output-file ./avatar-videos.plan.json --json\nsume avatar-videos batch create ./avatar-videos.json --state-file ./avatar-videos.state.json --confirm-paid --json\nsume avatar-videos batch watch ./avatar-videos.json --state-file ./avatar-videos.state.json --json\nsume avatar-videos batch result ./avatar-videos.json --state-file ./avatar-videos.state.json --json\n```\n\nRead `references/avatar-video-batch-manifest.md` for manifest shape.\nRerunning batch create with the same state file must not duplicate already\nsubmitted paid jobs.\n\n## Not For\n\nDo not route generic video generation, Ads, UGC Ads, Face Swap, or raw provider\nmodel ids through this skill unless they are added to the current public\n`api.sume.com` catalog. Do not use this skill for local media inspection only;\nuse `sume-media-qa` when no paid generation is needed.\n", - "references/avatar-video-batch-manifest.md": "# Avatar Video Batch Manifest\n\n```json\n{\n \"defaults\": {\n \"avatar_handle\": \"ready_avatar\",\n \"scene_prompt\": \"Bright studio\",\n \"mode\": \"async\"\n },\n \"videos\": [\n {\n \"id\": \"hook\",\n \"script\": \"This is the quick morning skincare step.\"\n },\n {\n \"id\": \"demo\",\n \"script\": \"Apply a small amount and watch it absorb.\",\n \"title\": \"Application demo\"\n }\n ]\n}\n```\n\n`batch plan` is local and no-provider. `batch create` is paid generation\nand requires `--confirm-paid`. Use a persistent state file so reruns skip items\nthat already have a job id.\n\nScripts are estimated locally and by the API; accepted target duration is 4-60\nseconds inclusive.\nAdd `product_image` in defaults or per-video entries only when the user provides\na public product/reference image.\n" + "references/avatar-video-batch-manifest.md": "# Avatar Video Batch Manifest\n\n```json\n{\n \"defaults\": {\n \"avatar_handle\": \"ready_avatar\",\n \"scene_prompt\": \"Bright studio\",\n \"mode\": \"async\"\n },\n \"videos\": [\n {\n \"id\": \"hook\",\n \"script\": \"This is the quick morning skincare step.\"\n },\n {\n \"id\": \"demo\",\n \"script\": \"Apply a small amount and watch it absorb.\",\n \"title\": \"Application demo\"\n }\n ]\n}\n```\n\n`batch plan` is local and no-provider. `batch create` is paid generation\nand requires `--confirm-paid`. Use a persistent state file so reruns skip items\nthat already have a job id.\n\nScripts are estimated locally and by the API; accepted target duration is 4-60\nseconds inclusive.\nAdd `product_image` in defaults or per-video entries only when the user provides\na public product/reference image.\n", + "SKILL.md": "---\nname: sume-avatar-video\ndescription: Create, batch-plan, watch, and inspect Sume Avatar Video 1.0 jobs from selected avatar handles, including productless/product-image flows, metadata readback, and paid gates.\n---\n\n# Sume Avatar Video\n\nUse this skill after a ready avatar is selected.\nUse `sume tools schema avatar-videos.create --json` before constructing writes;\ndo not copy request schemas from memory.\n\n## Discover\n\n```bash\nsume tools schema avatar-videos.create --json\nsume tools schema avatar-videos.get --json\nsume tools schema avatar-videos.batch.plan --json\nsume tools schema jobs.result --json\n```\n\n## Single Video\n\n```bash\nsume avatar-videos create \\\n --avatar-handle \\\n --script \"This serum absorbs quickly.\" \\\n --scene-prompt \"Bright clean studio\" \\\n --confirm-paid \\\n --agent \\\n --json\n```\n\nThen:\n\n```bash\nsume jobs watch --agent --json\nsume jobs result --agent --json\nsume avatar-videos get --agent --json\n```\n\nTimeout is not terminal. After a paid submit, keep ownership until the job is\ncompleted, failed, canceled, or the user explicitly tells you to stop. If\n`jobs watch` times out while the job is non-terminal, rerun\n`sume jobs watch --timeout-seconds 0 --agent --json` as a one-shot\nstatus check, then continue polling or ask whether to keep watching. Do not\nsubmit a duplicate paid job while recovering from timeout or transport failure.\n\nScripts are estimated locally and by the API; accepted target duration is 4-60\nseconds inclusive. Use handles for avatar handoffs.\nAdd `--product-image` when the user provides a public product/reference image;\nomit it for productless avatar videos.\n\nSummarize status, artifacts, duration, tags, scenes, transcript, and summary\nwhen present. Do not paste full media URLs.\n\n## Batch Videos\n\n```bash\nsume avatar-videos batch plan ./avatar-videos.json --output-file ./avatar-videos.plan.json --json\nsume avatar-videos batch create ./avatar-videos.json --state-file ./avatar-videos.state.json --confirm-paid --json\nsume avatar-videos batch watch ./avatar-videos.json --state-file ./avatar-videos.state.json --json\nsume avatar-videos batch result ./avatar-videos.json --state-file ./avatar-videos.state.json --json\n```\n\nRead `references/avatar-video-batch-manifest.md` for manifest shape.\nRerunning batch create with the same state file must not duplicate already\nsubmitted paid jobs.\nFor multiple submitted video jobs, poll all job ids together with\n`sume jobs watch --ids , --agent --json` or an agent-managed\nloop using `--timeout-seconds 0`, then fetch terminal job/resource readback\nbefore reporting the workflow complete.\n\n## Not For\n\nDo not route generic video generation, Ads, UGC Ads, Face Swap, or raw provider\nmodel ids through this skill unless they are added to the current public\n`api.sume.com` catalog. Do not use this skill for local media inspection only;\nuse `sume-media-qa` when no paid generation is needed.\n" }, "sume-media-qa": { "SKILL.md": "---\nname: sume-media-qa\ndescription: Inspect and compare Sume media outputs locally with no provider calls, using duration/codec checks, still sheets, side-by-side comparisons, and artifact notes.\n---\n\n# Sume Media QA\n\nUse this skill to inspect existing Sume outputs without submitting new paid\ngeneration jobs.\n\n## Get Files Only When Needed\n\n```bash\nsume jobs result --agent --json\nsume jobs download --output-dir ./sume-outputs --json\n```\n\nUse explicit output directories. Final reports should mention local filenames,\ncounts, dimensions, duration, and issues, not full media URLs.\n\n## Local Checks\n\nUse local tools when available:\n\n```bash\nffprobe -v error -show_format -show_streams ./sume-outputs/video.mp4\n```\n\nCheck:\n\n- duration and aspect ratio;\n- codec/container compatibility;\n- audio presence and sync;\n- obvious visual artifacts;\n- product/identity continuity;\n- whether a side-by-side comparison or still sheet is needed.\n\n## Report\n\nReturn a compact QA note with files inspected, pass/fail observations, and\nrecommended next action. Keep provider internals and full URLs out of the\nreport.\n\n## Not For\n\nDo not create Avatar or Avatar Video jobs from this skill. Use\n`sume-avatar-video`, `sume-min-latency`, `sume-quality-experiment`, or\n`sume-spend-capped-dogfood` when paid generation is needed.\n" }, "sume-min-latency": { - "SKILL.md": "---\nname: sume-min-latency\ndescription: Run the fastest safe Sume Avatar/Avatar Video iteration loop using async submits, batch state files, parallel polling, deferred downloads, and explicit quality/cost tradeoffs.\n---\n\n# Sume Minimum Latency\n\nUse this skill when the user wants the fastest useful Sume result while still\nrespecting paid gates and avoiding duplicate jobs.\n\n## Rules\n\n1. Run readiness only if local state is unknown:\n\n ```bash\n sume doctor --agent --json\n ```\n\n2. Use schema discovery only for the write you are about to make:\n\n ```bash\n sume tools schema avatars.create --json\n sume tools schema avatar-videos.create --json\n ```\n\n3. Prefer async submit plus watch/result over blocking waits.\n4. For multiple independent candidates, draft a manifest and use batch\n plan/create/watch/result with a persistent state file.\n5. Use stable idempotency keys. Reruns must skip already-created jobs.\n6. Do not download media unless local comparison is required or the user asks.\n7. If the user prioritizes speed/cost, explicitly choose `quality=standard`;\n otherwise preserve the platform default quality.\n\n## Fast Avatar Video Loop\n\n```bash\nsume avatar-videos create \\\n --avatar-handle \\\n --script \"Short reviewed script.\" \\\n --quality standard \\\n --confirm-paid \\\n --agent \\\n --json\n\nsume jobs watch --agent --json\nsume jobs result --agent --json\n```\n\n## Report\n\nReport job id, resource id, requested quality, wall-clock time if measured,\nqueue/run state, captured/refunded cost when available, and sanitized result\navailability. Do not paste full media URLs.\n\n## Not For\n\nDo not use this skill for broad quality exploration or side-by-side evaluation;\nuse `sume-quality-experiment`. Do not use it to bypass spend caps, paid\napproval, idempotency, or state files.\n" + "SKILL.md": "---\nname: sume-min-latency\ndescription: Run the fastest safe Sume Avatar/Avatar Video iteration loop using async submits, batch state files, parallel polling, deferred downloads, and explicit quality/cost tradeoffs.\n---\n\n# Sume Minimum Latency\n\nUse this skill when the user wants the fastest useful Sume result while still\nrespecting paid gates and avoiding duplicate jobs.\n\n## Rules\n\n1. Run readiness only if local state is unknown:\n\n ```bash\n sume doctor --agent --json\n ```\n\n2. Use schema discovery only for the write you are about to make:\n\n ```bash\n sume tools schema avatars.create --json\n sume tools schema avatar-videos.create --json\n ```\n\n3. Prefer async submit plus watch/result over blocking waits.\n4. For multiple independent candidates, draft a manifest and use batch\n plan/create/watch/result with a persistent state file.\n5. Use stable idempotency keys. Reruns must skip already-created jobs.\n6. Timeout is not terminal. If `jobs watch` returns non-terminal jobs, run a\n one-shot aggregate check with `--timeout-seconds 0`, then continue polling or\n ask whether to keep watching. Do not final-answer as complete until terminal\n result/resource readback exists or the user explicitly stops the workflow.\n7. Do not download media unless local comparison is required or the user asks.\n8. If the user prioritizes speed/cost, explicitly choose `quality=standard`;\n otherwise preserve the platform default quality.\n\n## Fast Avatar Video Loop\n\n```bash\nsume avatar-videos create \\\n --avatar-handle \\\n --script \"Short reviewed script.\" \\\n --quality standard \\\n --confirm-paid \\\n --agent \\\n --json\n\nsume jobs watch --agent --json\nsume jobs result --agent --json\n```\n\nFor multiple jobs, use one aggregate watcher:\n\n```bash\nsume jobs watch --ids , --agent --json\n```\n\nIf it times out, do not submit replacement paid jobs. Recheck with\n`--timeout-seconds 0`, keep polling, or ask whether to continue.\n\n## Report\n\nReport job id, resource id, requested quality, wall-clock time if measured,\nqueue/run state, captured/refunded cost when available, and sanitized result\navailability. Report non-terminal jobs as still in progress, not complete. Do\nnot paste full media URLs.\n\n## Not For\n\nDo not use this skill for broad quality exploration or side-by-side evaluation;\nuse `sume-quality-experiment`. Do not use it to bypass spend caps, paid\napproval, idempotency, or state files.\n" }, "sume-quality-experiment": { "SKILL.md": "---\nname: sume-quality-experiment\ndescription: Design and run controlled Sume quality experiments with one-variable variants, reusable manifests, side-by-side artifact comparison, and rubric-based sanitized reports.\n---\n\n# Sume Quality Experiment\n\nUse this skill for controlled Avatar or Avatar Video comparisons.\n\n## Experiment Rules\n\n1. Write a short local manifest before paid calls.\n2. Change one variable per variant: quality tier, scene prompt, product image,\n avatar handle, script, duration, or aspect ratio.\n3. Keep shared anchors identical across variants.\n4. Run no-cost checks first: schema discovery, manifest validation, and local\n media inspection when outputs already exist.\n5. Ask for explicit paid approval and a spend cap before paid generation.\n6. Use idempotency keys and state files so reruns do not duplicate jobs.\n\n## Commands\n\n```bash\nsume tools schema avatar-videos.create --json\nsume avatar-videos batch plan ./experiment.videos.json --output-file ./experiment.plan.json --json\nsume avatar-videos batch create ./experiment.videos.json --state-file ./experiment.state.json --confirm-paid --json\nsume avatar-videos batch watch ./experiment.videos.json --state-file ./experiment.state.json --json\nsume avatar-videos batch result ./experiment.videos.json --state-file ./experiment.state.json --json\n```\n\nUse `sume-media-qa` after results exist if the user needs local files, still\nsheets, codec checks, or side-by-side comparison.\n\n## Rubric\n\nScore or summarize:\n\n- identity preservation;\n- product fidelity;\n- script/audio fit;\n- scene continuity;\n- artifact severity;\n- metadata/readback usefulness;\n- cost and elapsed time.\n\n## Not For\n\nDo not use this skill for unrestricted exploration, raw provider endpoint\ntests, or one-off fastest iteration. Use `sume-min-latency` for speed and\n`sume-spend-capped-dogfood` for paid QA with a strict budget.\n" }, "sume-spend-capped-dogfood": { - "SKILL.md": "---\nname: sume-spend-capped-dogfood\ndescription: Run paid Sume dogfood QA under an explicit USD cap using idempotency, max_spend_usd where available, cost readback, and no duplicate paid submissions.\n---\n\n# Sume Spend-Capped Dogfood\n\nUse this skill when the user authorizes paid Sume QA with a hard budget.\n\n## Required Before Paid Calls\n\n- Confirm the exact USD cap.\n- Identify the minimum number of jobs needed for evidence.\n- Prefer dry-run/admission preview or estimate if exposed by the current tool\n schema.\n- Use stable idempotency keys.\n- Use batch state files for more than one job.\n- Stop once the evidence is sufficient.\n\nIf a future release enables MCP paid tools, `idempotency_key` and\n`max_spend_usd` are mandatory. For current CLI commands, record the approved cap\nin the manifest/report and pass idempotency keys where supported.\n\n## Commands\n\n```bash\nsume doctor --agent --json\nsume balance --json\nsume tools schema avatar-videos.create --json\n```\n\nSingle-job example after explicit approval:\n\n```bash\nsume avatar-videos create \\\n --avatar-handle \\\n --script \"Short QA script.\" \\\n --quality standard \\\n --idempotency-key \\\n --confirm-paid \\\n --agent \\\n --json\n```\n\nThen:\n\n```bash\nsume jobs watch --agent --json\nsume jobs result --agent --json\nsume balance --json\n```\n\n## Report\n\nReport requested quality, job id, resource id, expected/reserved/captured/\nrefunded cost when available, status/result, and whether the cap was respected.\nIf exact cost telemetry is missing, state that as a product gap instead of\ninferring a billing guarantee.\n\n## Not For\n\nDo not use this skill without an explicit cap. Do not keep spending for broad\nexploration. Do not print secrets, full URLs, signed URLs, provider payloads, or\nprivate identifiers.\n" + "SKILL.md": "---\nname: sume-spend-capped-dogfood\ndescription: Run paid Sume dogfood QA under an explicit USD cap using idempotency, max_spend_usd where available, cost readback, and no duplicate paid submissions.\n---\n\n# Sume Spend-Capped Dogfood\n\nUse this skill when the user authorizes paid Sume QA with a hard budget.\n\n## Required Before Paid Calls\n\n- Confirm the exact USD cap.\n- Identify the minimum number of jobs needed for evidence.\n- Prefer dry-run/admission preview or estimate if exposed by the current tool\n schema.\n- Use stable idempotency keys.\n- Use batch state files for more than one job.\n- Stop once terminal evidence is sufficient.\n- Timeout is not terminal. A paid job remains owned by the agent until it is\n completed, failed, canceled, or the user explicitly tells you to stop.\n\nIf a future release enables MCP paid tools, `idempotency_key` and\n`max_spend_usd` are mandatory. For current CLI commands, record the approved cap\nin the manifest/report and pass idempotency keys where supported.\n\n## Commands\n\n```bash\nsume doctor --agent --json\nsume balance --json\nsume tools schema avatar-videos.create --json\n```\n\nSingle-job example after explicit approval:\n\n```bash\nsume avatar-videos create \\\n --avatar-handle \\\n --script \"Short QA script.\" \\\n --quality standard \\\n --idempotency-key \\\n --confirm-paid \\\n --agent \\\n --json\n```\n\nThen:\n\n```bash\nsume jobs watch --agent --json\nsume jobs result --agent --json\nsume balance --json\n```\n\nIf `jobs watch` times out while the job is still non-terminal, run\n`sume jobs watch --timeout-seconds 0 --agent --json`, then continue\npolling or ask whether to keep watching. Do not submit duplicate paid jobs while\nrecovering from timeout or transport failure.\n\n## Report\n\nReport requested quality, job id, resource id, expected/reserved/captured/\nrefunded cost when available, status/result, and whether the cap was respected.\nIf jobs are still non-terminal, say the workflow is still in progress and give\nthe resume/watch command instead of reporting completion. If exact cost\ntelemetry is missing, state that as a product gap instead of inferring a billing\nguarantee.\n\n## Not For\n\nDo not use this skill without an explicit cap. Do not keep spending for broad\nexploration. Do not print secrets, full URLs, signed URLs, provider payloads, or\nprivate identifiers.\n" }, "sume-tools": { - "SKILL.md": "---\nname: sume-tools\ndescription: Discover current Sume CLI tool schemas, inspect bundled skills, check readiness, and choose safe CLI/MCP workflows without executing paid generation.\n---\n\n# Sume Tools\n\nUse this skill for schema discovery and local skill maintenance.\n\nDo not construct write or paid payloads from memory. Use the local tool registry\nas the executable contract.\n\n## Discovery\n\n```bash\nsume doctor --agent --json\nsume tools list --json\nsume tools schema avatars.create --json\nsume tools schema avatar-videos.create --json\nsume tools schema jobs.watch --json\nsume balance --json\nsume usage get --json\n```\n\n## Skill Maintenance\n\n```bash\nsume skills list --json\nsume skills export sume --json\nsume skills install sume --json\nsume skills install sume-avatar --json\nsume skills update --json\n```\n\nSkills install into `.agents/skills/` when `.agents/` exists, otherwise\n`.claude/skills/` when `.claude/` exists.\n\n## MCP\n\nSume MCP is coming soon and is not part of this public CLI launch release yet.\nUse direct CLI commands today.\n\nIf a future release enables MCP, treat MCP tool descriptions and\n`sume tools schema` safety metadata as the source of truth for toolsets, write\ngates, paid gates, and redaction behavior.\n\n## Not For\n\nDo not execute paid creation directly from this skill. Route avatar work to\n`sume-avatar`, video work to `sume-avatar-video`, spend-capped QA to\n`sume-spend-capped-dogfood`, local artifact checks to `sume-media-qa`, and fast\niteration to `sume-min-latency`. Route media inputs through public HTTPS URLs\nunless the user explicitly asks for advanced compatibility asset tooling.\n", - "references/mcp-toolsets.md": "# MCP Coming Soon\n\nSume MCP is coming soon and is not part of this public CLI launch release yet.\nUse direct CLI commands today for auth, schema discovery, Avatar, Avatar Video,\njobs, balance, and usage workflows.\n\n```bash\nsume login\nsume doctor --agent --json\nsume tools list --json\nsume tools schema avatars.create --json\nsume tools schema avatar-videos.create --json\n```\n" + "references/mcp-toolsets.md": "# MCP Coming Soon\n\nSume MCP is coming soon and is not part of this public CLI launch release yet.\nUse direct CLI commands today for auth, schema discovery, Avatar, Avatar Video,\njobs, balance, and usage workflows.\n\n```bash\nsume login\nsume doctor --agent --json\nsume tools list --json\nsume tools schema avatars.create --json\nsume tools schema avatar-videos.create --json\n```\n", + "SKILL.md": "---\nname: sume-tools\ndescription: Discover current Sume CLI tool schemas, inspect bundled skills, check readiness, and choose safe CLI/MCP workflows without executing paid generation.\n---\n\n# Sume Tools\n\nUse this skill for schema discovery and local skill maintenance.\n\nDo not construct write or paid payloads from memory. Use the local tool registry\nas the executable contract.\n\n## Discovery\n\n```bash\nsume doctor --agent --json\nsume tools list --json\nsume tools schema avatars.create --json\nsume tools schema avatar-videos.create --json\nsume tools schema jobs.watch --json\nsume balance --json\nsume usage get --json\n```\n\n## Skill Maintenance\n\n```bash\nsume skills list --json\nsume skills export sume --json\nsume skills install sume --json\nsume skills install sume-avatar --json\nsume skills update --json\n```\n\nSkills install into `.agents/skills/` when `.agents/` exists, otherwise\n`.claude/skills/` when `.claude/` exists.\n\n## MCP\n\nSume MCP is coming soon and is not part of this public CLI launch release yet.\nUse direct CLI commands today.\n\nIf a future release enables MCP, treat MCP tool descriptions and\n`sume tools schema` safety metadata as the source of truth for toolsets, write\ngates, paid gates, and redaction behavior.\n\n## Not For\n\nDo not execute paid creation directly from this skill. Route avatar work to\n`sume-avatar`, video work to `sume-avatar-video`, spend-capped QA to\n`sume-spend-capped-dogfood`, local artifact checks to `sume-media-qa`, and fast\niteration to `sume-min-latency`. Route media inputs through public HTTPS URLs\nunless the user explicitly asks for advanced compatibility asset tooling.\n" } } as const; diff --git a/src/lib/tool-registry.ts b/src/lib/tool-registry.ts index 30e6c75..9e42504 100644 --- a/src/lib/tool-registry.ts +++ b/src/lib/tool-registry.ts @@ -1000,7 +1000,7 @@ const staticToolDefinitions: Record = { ], }, "avatars.create": { - command: "sume avatars create --confirm-submit --json ...", + command: "sume avatars create --confirm-submit --agent --json ...", description: "Submit an Avatar 1.0 model run through the public Sume Avatar model-run API.", confirmation: submitConfirmation, @@ -1065,6 +1065,7 @@ const staticToolDefinitions: Record = { }, ...communicationProperties, ...submitConfirmationProperties, + ...agentOutputProperties, }, ), mcp_input_schema: objectSchema( @@ -1085,9 +1086,9 @@ const staticToolDefinitions: Record = { ["idempotency_key", "max_spend_usd", "payload"], ), examples: [ - "sume avatars create --confirm-submit --avatar-handle presenter --prompt 'A friendly presenter' --json", - "sume avatars create --confirm-submit --type photo --avatar-handle photo_presenter --image-url --json", - "sume avatars create --confirm-submit --payload-json '{\"avatar_handle\":\"presenter\",\"input\":{\"type\":\"prompt\",\"prompt\":\"A friendly presenter\"}}' --json", + "sume avatars create --confirm-submit --avatar-handle presenter --prompt 'A friendly presenter' --agent --json", + "sume avatars create --confirm-submit --type photo --avatar-handle photo_presenter --image-url --agent --json", + "sume avatars create --confirm-submit --payload-json '{\"avatar_handle\":\"presenter\",\"input\":{\"type\":\"prompt\",\"prompt\":\"A friendly presenter\"}}' --agent --json", ], next_steps: [ "Ask for explicit user approval before passing --confirm-submit or --confirm-paid.", @@ -1329,7 +1330,7 @@ const staticToolDefinitions: Record = { ], }, "avatar-videos.create": { - command: "sume avatar-videos create --confirm-submit --json ...", + command: "sume avatar-videos create --confirm-submit --agent --json ...", description: "Submit an Avatar Video 1.0 talking-video run through /v1/avatar-1.0/talking-video.", confirmation: submitConfirmation, @@ -1378,6 +1379,7 @@ const staticToolDefinitions: Record = { title: { ...stringProperty, description: "Optional title." }, ...communicationProperties, ...submitConfirmationProperties, + ...agentOutputProperties, }, ["script", "avatar_handle"], ), @@ -1435,8 +1437,8 @@ const staticToolDefinitions: Record = { ], }, examples: [ - "sume avatar-videos create --confirm-submit --script 'Say hello.' --avatar-handle studio_presenter --scene-prompt 'Clean studio' --json", - "sume avatar-videos create --confirm-submit --script 'Say hello.' --avatar-handle studio_presenter --quality standard --aspect-ratio 9:16 --json", + "sume avatar-videos create --confirm-submit --script 'Say hello.' --avatar-handle studio_presenter --scene-prompt 'Clean studio' --agent --json", + "sume avatar-videos create --confirm-submit --script 'Say hello.' --avatar-handle studio_presenter --quality standard --aspect-ratio 9:16 --agent --json", ], next_steps: [ "Ask for explicit user approval before passing --confirm-submit or --confirm-paid.", diff --git a/test/cli.test.ts b/test/cli.test.ts index cc0ecfb..09d5d83 100644 --- a/test/cli.test.ts +++ b/test/cli.test.ts @@ -906,6 +906,8 @@ describe("CLI", () => { minimum: 20, type: "integer", }), + agent: expect.objectContaining({ type: "boolean" }), + redact_urls: expect.objectContaining({ type: "boolean" }), confirm_submit: expect.objectContaining({ type: "boolean" }), }, }, @@ -953,6 +955,8 @@ describe("CLI", () => { mode: expect.objectContaining({ enum: ["async", "sync", "subscribe", "webhook"], }), + agent: expect.objectContaining({ type: "boolean" }), + redact_urls: expect.objectContaining({ type: "boolean" }), }, }, mcp_input_schema: null, @@ -1619,6 +1623,67 @@ describe("CLI", () => { ); }); + it("accepts --agent on avatar submits and redacts submit readback", async () => { + const help = await execFileAsync(tsx, [ + "src/index.ts", + "avatars", + "create", + "--help", + ]); + expect(help.stdout).toContain("--agent"); + expect(help.stdout).toContain("--redact-urls"); + + await withMockApi( + () => ({ + data: { + request_id: "job_avatar_agent", + status_url: "https://api.sume.com/v1/jobs/job_avatar_agent/status", + result_url: "https://api.sume.com/v1/jobs/job_avatar_agent/result", + job: { + id: "job_avatar_agent", + status: "queued", + }, + }, + }), + async (baseUrl, requests) => { + const { stdout } = await runCli( + [ + "--json", + "avatars", + "create", + "--confirm-paid", + "--agent", + "--avatar-handle", + "presenter", + "--prompt", + "A friendly presenter", + ], + baseUrl, + ); + const parsed = JSON.parse(stdout); + expect(JSON.stringify(parsed)).not.toContain("https://"); + expect(parsed).toMatchObject({ + data: { + request_id: "job_avatar_agent", + status_url: "[redacted]", + result_url: "[redacted]", + job: { id: "job_avatar_agent", status: "queued" }, + }, + agent: { + safe: true, + next_steps: expect.arrayContaining([ + expect.stringContaining("Do not echo raw result URLs"), + ]), + }, + }); + expect(requests[0]).toMatchObject({ + method: "POST", + url: "/v1/avatar-1.0/generate", + }); + }, + ); + }); + it("rejects deprecated Avatar quality flags before making API calls", async () => { await withMockApi( () => { @@ -2578,6 +2643,69 @@ describe("CLI", () => { ); }); + it("accepts --agent on avatar-video submits and redacts submit readback", async () => { + const help = await execFileAsync(tsx, [ + "src/index.ts", + "avatar-videos", + "create", + "--help", + ]); + expect(help.stdout).toContain("--agent"); + expect(help.stdout).toContain("--redact-urls"); + + await withMockApi( + () => ({ + data: { + request_id: "job_video_agent", + status_url: "https://api.sume.com/v1/jobs/job_video_agent/status", + result_url: "https://api.sume.com/v1/jobs/job_video_agent/result", + job: { + id: "job_video_agent", + type: "avatar_video", + status: "queued", + }, + }, + }), + async (baseUrl, requests) => { + const { stdout } = await runCli( + [ + "--json", + "avatar-videos", + "create", + "--confirm-paid", + "--agent", + "--script", + "Say hello.", + "--avatar-handle", + "@studio_presenter", + ], + baseUrl, + ); + const parsed = JSON.parse(stdout); + expect(JSON.stringify(parsed)).not.toContain("https://"); + expect(parsed).toMatchObject({ + data: { + request_id: "job_video_agent", + status_url: "[redacted]", + result_url: "[redacted]", + job: { id: "job_video_agent", status: "queued" }, + }, + agent: { + safe: true, + next_steps: expect.arrayContaining([ + expect.stringContaining("If watch times out"), + expect.stringContaining("Do not echo raw result URLs"), + ]), + }, + }); + expect(requests[0]).toMatchObject({ + method: "POST", + url: "/v1/avatar-1.0/talking-video", + }); + }, + ); + }); + it("rejects avatar-video scripts outside the local duration limit", async () => { await withMockApi( () => ({ data: { ok: true } }), diff --git a/test/skills-registry.test.ts b/test/skills-registry.test.ts index d6a04a4..42989e3 100644 --- a/test/skills-registry.test.ts +++ b/test/skills-registry.test.ts @@ -56,6 +56,25 @@ describe("skills registry", () => { expect(paidSkill).toContain("idempotency"); expect(paidSkill).toContain("max_spend_usd"); expect(paidSkill).toContain("no duplicate paid submissions"); + expect(paidSkill).toContain("Timeout is not terminal"); + expect(paidSkill).toContain("--timeout-seconds 0"); + expect(paidSkill).toContain("workflow is still in progress"); + + const avatarSkill = exportBundledSkill("sume-avatar").files["SKILL.md"]; + expect(avatarSkill).toContain("Timeout is not terminal"); + expect(avatarSkill).toContain("one-shot aggregate status check"); + expect(avatarSkill).toMatch(/Do not submit duplicate\s+paid jobs/u); + + const avatarVideoSkill = + exportBundledSkill("sume-avatar-video").files["SKILL.md"]; + expect(avatarVideoSkill).toContain("Timeout is not terminal"); + expect(avatarVideoSkill).toContain("poll all job ids together"); + expect(avatarVideoSkill).toContain("fetch terminal job/resource readback"); + + const latencySkill = exportBundledSkill("sume-min-latency").files["SKILL.md"]; + expect(latencySkill).toContain("Timeout is not terminal"); + expect(latencySkill).toContain("--ids ,"); + expect(latencySkill).toContain("Do not final-answer as complete"); const mediaQa = JSON.stringify(exportBundledSkill("sume-media-qa")); expect(mediaQa).toContain("no provider calls");