@orchagent/cli 0.3.99 → 0.3.101

package/dist/commands/agent-keys.js

@@ -9,18 +9,14 @@ const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
 const errors_1 = require("../lib/errors");
 const key_store_1 = require("../lib/key-store");
+const resolve_agent_1 = require("../lib/resolve-agent");
 /**
  * Resolve an agent reference ("org/agent" or just "agent") to an agent ID.
- * Uses the authenticated list-agents endpoint and finds the latest version.
+ * Uses the shared resolveAgentContext() for parsing and org/workspace resolution,
+ * then finds the latest version via the authenticated list-agents endpoint.
  */
 async function resolveAgentId(config, ref) {
-    const parts = ref.split('/');
-    const agentName = parts.length >= 2 ? parts[1] : parts[0];
-    const orgSlug = parts.length >= 2 ? parts[0] : undefined;
-    // Resolve workspace context from org slug or config
-    const configFile = await (0, config_1.loadConfig)();
-    const resolvedOrg = orgSlug ?? configFile.workspace ?? config.defaultOrg;
-    const workspaceId = resolvedOrg ? await (0, api_1.resolveWorkspaceIdForOrg)(config, resolvedOrg) : undefined;
+    const { org, agent: agentName, workspaceId } = await (0, resolve_agent_1.resolveAgentContext)(ref, config);
     const agents = await (0, api_1.listMyAgents)(config, workspaceId);
     const matching = agents.filter(a => a.name === agentName);
     if (matching.length === 0) {
@@ -28,7 +24,7 @@ async function resolveAgentId(config, ref) {
     }
     // Use the latest version
     const latest = matching.sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime())[0];
-    return { agent: latest, agentId: latest.id, orgSlug: latest.org_slug ?? resolvedOrg ?? '' };
+    return { agent: latest, agentId: latest.id, orgSlug: latest.org_slug ?? org, workspaceId };
 }
 function registerAgentKeysCommand(program) {
     const agentKeys = program
@@ -42,8 +38,8 @@ function registerAgentKeysCommand(program) {
         if (!config.apiKey) {
             throw new errors_1.CliError('Missing API key. Run `orchagent login` first.');
         }
-        const { agent, agentId, orgSlug } = await resolveAgentId(config, ref);
-        const result = await (0, api_1.listAgentKeys)(config, agentId);
+        const { agent, agentId, orgSlug, workspaceId } = await resolveAgentId(config, ref);
+        const result = await (0, api_1.listAgentKeys)(config, agentId, workspaceId);
         // Load locally-saved keys for this agent
         const localKeys = await (0, key_store_1.loadServiceKeys)(orgSlug, agent.name);
         const localPrefixes = new Set(localKeys.map(k => k.prefix));
@@ -76,8 +72,8 @@ function registerAgentKeysCommand(program) {
         if (!config.apiKey) {
             throw new errors_1.CliError('Missing API key. Run `orchagent login` first.');
         }
-        const { agent, orgSlug } = await resolveAgentId(config, ref);
-        const result = await (0, api_1.createAgentKey)(config, agent.id);
+        const { agent, orgSlug, workspaceId } = await resolveAgentId(config, ref);
+        const result = await (0, api_1.createAgentKey)(config, agent.id, workspaceId);
         process.stdout.write(`\nNew service key for ${agent.name}:\n\n`);
         process.stdout.write(`  ${result.key}\n\n`);
         try {
@@ -96,8 +92,8 @@ function registerAgentKeysCommand(program) {
         if (!config.apiKey) {
             throw new errors_1.CliError('Missing API key. Run `orchagent login` first.');
         }
-        const { agent, agentId } = await resolveAgentId(config, ref);
-        await (0, api_1.deleteAgentKey)(config, agentId, keyId);
+        const { agent, agentId, workspaceId } = await resolveAgentId(config, ref);
+        await (0, api_1.deleteAgentKey)(config, agentId, keyId, workspaceId);
         process.stdout.write(`Deleted key ${keyId} from ${agent.name}.\n`);
     });
 }

package/dist/commands/diff.js

@@ -246,8 +246,10 @@ function parseSecondRef(value, firstOrg, firstName) {
         const parsed = (0, agent_ref_1.parseAgentRef)(value);
         return { org: parsed.org ?? firstOrg, agent: parsed.agent, version: parsed.version };
     }
-    // Otherwise treat as a version shorthand for the same agent
-    return { org: firstOrg, agent: firstName, version: value };
+    // Otherwise treat as a version shorthand for the same agent.
+    // Strip leading '@' — users naturally type `@v2` since the full form is `org/agent@v2`.
+    const version = value.startsWith('@') ? value.slice(1) : value;
+    return { org: firstOrg, agent: firstName, version };
 }
 // ── Command ────────────────────────────────────────────────────
 function registerDiffCommand(program) {

package/dist/commands/docs.js

@@ -10,16 +10,21 @@ const DOCS_ROUTES = {
     '': '/',
     'cli': '/using-agents/cli-commands',
     'agents': '/building-agents/agent-types',
+    'orchestration': '/building-agents/orchestration',
     'skills': '/building-agents/orchestration',
     'sdk': '/building-agents/sdk',
     'api': '/api-reference/overview',
     'quickstart': '/quickstart',
+    'scheduling': '/using-agents/scheduling',
+    'services': '/using-agents/services',
+    'security': '/concepts/security',
+    'billing': '/concepts/billing',
 };
 function registerDocsCommand(program) {
     program
         .command('docs')
         .description('Open documentation in browser')
-        .argument('[topic]', 'Topic: cli, agents, skills, sdk, api, quickstart')
+        .argument('[topic]', 'Topic: cli, agents, orchestration, skills, sdk, api, quickstart, scheduling, services, security, billing')
         .action(async (topic) => {
         if (topic && !(topic in DOCS_ROUTES)) {
             const validTopics = Object.keys(DOCS_ROUTES).filter(k => k).join(', ');

package/dist/commands/estimate.js

@@ -43,9 +43,10 @@ function registerEstimateCommand(program) {
             process.exit(1);
         }
         const { agent, version } = parsed;
+        const workspaceId = await (0, api_1.resolveWorkspaceIdForOrg)(config, org);
         let data;
         try {
-            data = await (0, api_1.getAgentCostEstimate)(config, org, agent, version);
+            data = await (0, api_1.getAgentCostEstimate)(config, org, agent, version, workspaceId);
         }
         catch (err) {
             if (err instanceof api_1.ApiError && err.status === 404) {

package/dist/commands/fork.js

@@ -81,8 +81,9 @@ Examples:
             throw new errors_1.CliError('Missing org. Use org/agent format or set default org.');
         }
         const { agent, version } = parsed;
+        const workspaceId = await (0, api_1.resolveWorkspaceIdForOrg)(config, org);
         write('Resolving source agent...\n');
-        const source = await (0, api_1.getAgentWithFallback)(config, org, agent, version);
+        const source = await (0, api_1.getAgentWithFallback)(config, org, agent, version, workspaceId);
         if (!source.id) {
             throw new errors_1.CliError(`Could not resolve source agent ID for '${org}/${agent}@${version}'.`);
         }

package/dist/commands/init.js

@@ -412,7 +412,8 @@ import asyncio
 import json
 import sys
 
-from orchagent import AgentClient
+# pip install orchagent-sdk  (package name)
+from orchagent import AgentClient  # module name
 
 
 async def run():
@@ -503,7 +504,8 @@ import asyncio
 import json
 import sys
 
-from orchagent import AgentClient
+# pip install orchagent-sdk  (package name)
+from orchagent import AgentClient  # module name
 
 
 async def run():
@@ -589,7 +591,8 @@ import asyncio
 import json
 import sys
 
-from orchagent import AgentClient
+# pip install orchagent-sdk  (package name)
+from orchagent import AgentClient  # module name
 
 
 async def run():
@@ -1207,7 +1210,8 @@ import asyncio
 import json
 import sys
 
-from orchagent import AgentClient
+# pip install orchagent-sdk  (package name)
+from orchagent import AgentClient  # module name
 
 
 def main():
@@ -1490,7 +1494,10 @@ function resolveInitFlavor(typeOption) {
     if (normalized === 'prompt') {
         return { type: 'prompt', flavor: 'direct_llm' };
     }
-    if (normalized === 'agent' || normalized === 'agentic') {
+    if (normalized === 'agent') {
+        return { type: 'agent', flavor: 'managed_loop' };
+    }
+    if (normalized === 'agentic') {
         return { type: 'agent', flavor: 'code_runtime' };
     }
     if (normalized === 'tool' || normalized === 'code') {
@@ -1507,7 +1514,7 @@ function registerInitCommand(program) {
         .option('--orchestrator', 'Create an orchestrator agent with dependency scaffolding and SDK boilerplate')
         .option('--run-mode <mode>', 'Run mode for agents: on_demand or always_on', 'on_demand')
         .option('--language <lang>', 'Language: python or javascript (default: python)', 'python')
-        .option('--loop', 'Use platform-managed LLM loop instead of code runtime (requires --type agent)')
+        .option('--loop', 'Use platform-managed LLM loop execution (explicit for --type agentic; default for --type agent)')
         .option('--template <name>', 'Start from a template (use --list-templates to see options)')
         .option('--list-templates', 'Show available templates with descriptions')
         .action(async (name, options) => {
@@ -1613,7 +1620,7 @@ function registerInitCommand(program) {
         const isJavaScript = ['javascript', 'js', 'typescript', 'ts'].includes(language);
         // Block unsupported JS flavors
         if (isJavaScript && initMode.flavor === 'managed_loop') {
-            throw new errors_1.CliError('JavaScript is not supported for --loop (managed loop). Use --type agent without --loop for a code-runtime agent.');
+            throw new errors_1.CliError('JavaScript is not supported for managed-loop agents. Use --type agentic for a code-runtime agent scaffold.');
         }
         // JS orchestrators are now supported via the orchagent-sdk npm package
         // Block --language for types that don't create runtime files
@@ -2033,7 +2040,7 @@ function registerInitCommand(program) {
             }
         }
         if (initMode.flavor !== 'code_runtime' && initMode.flavor !== 'orchestrator' && initMode.flavor !== 'discord' && runMode === 'always_on') {
-            throw new errors_1.CliError("run_mode=always_on requires runtime.command in orchagent.json (e.g. \"runtime\": { \"command\": \"python main.py\" }). Use --type tool for code-runtime agents.");
+            throw new errors_1.CliError("run_mode=always_on requires runtime.command in orchagent.json (e.g. \"runtime\": { \"command\": \"python main.py\" }). Use --type tool or --type agentic for code-runtime agents.");
         }
         // Create manifest and type-specific files
         const manifest = JSON.parse(MANIFEST_TEMPLATE);

package/dist/commands/install.js

@@ -10,24 +10,12 @@ const os_1 = __importDefault(require("os"));
 const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
 const errors_1 = require("../lib/errors");
+const resolve_agent_1 = require("../lib/resolve-agent");
 const analytics_1 = require("../lib/analytics");
 const adapters_1 = require("../adapters");
 const skill_resolve_1 = require("../lib/skill-resolve");
 const installed_1 = require("../lib/installed");
 const agents_md_utils_1 = require("../lib/agents-md-utils");
-const DEFAULT_VERSION = 'latest';
-function parseAgentRef(value) {
-    const [ref, versionPart] = value.split('@');
-    const version = versionPart?.trim() || DEFAULT_VERSION;
-    const segments = ref.split('/');
-    if (segments.length === 1) {
-        return { name: segments[0], version };
-    }
-    if (segments.length === 2) {
-        return { org: segments[0], name: segments[1], version };
-    }
-    throw new errors_1.CliError('Invalid agent reference. Use org/agent or agent format.');
-}
 async function downloadAgentWithFallback(config, org, name, version, workspaceId) {
     // Fetch public metadata first to check if paid
     let publicMeta;
@@ -135,19 +123,21 @@ function registerInstallCommand(program) {
             errors: [],
         };
         const resolved = await (0, config_1.getResolvedConfig)();
-        const parsed = parseAgentRef(agentArg);
-        const configFile = await (0, config_1.loadConfig)();
-        const org = parsed.org ?? configFile.workspace ?? resolved.defaultOrg;
-        if (!org) {
-            if (jsonMode) {
-                result.errors.push('Missing org. Use org/agent format or set default org.');
+        let agentCtx;
+        try {
+            agentCtx = await (0, resolve_agent_1.resolveAgentContext)(agentArg, resolved);
+        }
+        catch (err) {
+            if (jsonMode && err instanceof errors_1.CliError) {
+                result.errors.push(err.message);
                 process.stdout.write(JSON.stringify(result, null, 2) + '\n');
                 process.exit(errors_1.ExitCodes.INVALID_INPUT);
             }
-            throw new errors_1.CliError('Missing org. Use org/agent format or set default org.');
+            throw err;
         }
-        result.agent = `${org}/${parsed.name}`;
-        result.version = parsed.version;
+        const { org, agent: agentName, version, workspaceId } = agentCtx;
+        result.agent = `${org}/${agentName}`;
+        result.version = version;
         // Determine target formats
         let targetFormats = [];
         if (options.format) {
@@ -186,13 +176,11 @@ function registerInstallCommand(program) {
             throw new errors_1.CliError(errMsg);
         }
         result.scope = scope;
-        // Resolve workspace context for the target org
-        const workspaceId = await (0, api_1.resolveWorkspaceIdForOrg)(resolved, org);
         // Download agent
-        log(`Fetching ${org}/${parsed.name}@${parsed.version}...\n`);
+        log(`Fetching ${org}/${agentName}@${version}...\n`);
         let agent;
         try {
-            agent = await downloadAgentWithFallback(resolved, org, parsed.name, parsed.version, workspaceId);
+            agent = await downloadAgentWithFallback(resolved, org, agentName, version, workspaceId);
         }
         catch (err) {
             if (jsonMode) {
@@ -273,15 +261,15 @@ function registerInstallCommand(program) {
                     catch {
                         // File doesn't exist, will create new
                     }
-                    const agentRef = `${org}/${parsed.name}`;
+                    const agentRef = `${org}/${agentName}`;
                     file.content = (0, agents_md_utils_1.mergeAgentsMdContent)(existingContent, file.content, agentRef);
                 }
                 await promises_1.default.writeFile(fullPath, file.content);
                 filesWritten++;
                 // Track installation
                 const installedAgent = {
-                    agent: `${org}/${parsed.name}`,
-                    version: parsed.version,
+                    agent: `${org}/${agentName}`,
+                    version: version,
                     format: formatId,
                     scope: effectiveScope,
                     path: fullPath,
@@ -297,7 +285,7 @@ function registerInstallCommand(program) {
         if (!options.dryRun) {
             if (filesWritten > 0) {
                 await (0, analytics_1.track)('cli_agent_install', {
-                    agent: `${org}/${parsed.name}`,
+                    agent: `${org}/${agentName}`,
                     formats: targetFormats,
                     scope,
                 });

package/dist/commands/logs.js

@@ -182,7 +182,7 @@ async function listRuns(config, workspaceId, agentName, options) {
     if (result.total > result.runs.length) {
         process.stdout.write(chalk_1.default.gray(`\nShowing ${result.runs.length} of ${result.total} runs. Use --limit to see more.\n`));
     }
-    process.stdout.write(chalk_1.default.gray('\nView detailed logs for a run: orch logs <run-id>\n'));
+    process.stdout.write(chalk_1.default.gray('\nView detailed logs for a run: orch logs <run-id>  · Replay a run: orch replay <run-id>\n'));
 }
 // ============================================
 // SHOW RUN LOGS
@@ -229,5 +229,7 @@ async function showRunLogs(config, workspaceId, runId, json) {
         process.stdout.write(chalk_1.default.gray('\nNo sandbox output available for this run. ' +
             'Execution logs are captured for agents with a code runtime (tool/agent types with runtime.command).\n'));
     }
+    // Footer hints
+    process.stdout.write(chalk_1.default.gray(`\nReplay: orch replay ${runId.slice(0, 8)}  · Trace: orch trace ${runId.slice(0, 8)}\n`));
     process.stdout.write('\n');
 }

package/dist/commands/publish.js

@@ -510,6 +510,8 @@ async function batchPublish(rootDir, options) {
         forwardArgs.push('--no-local-download');
     if (options.requiredSecrets === false)
         forwardArgs.push('--no-required-secrets');
+    if (options.verbose)
+        forwardArgs.push('--verbose');
     const results = [];
     for (let i = 0; i < sorted.length; i++) {
         const agent = sorted[i];
@@ -586,6 +588,7 @@ function registerPublishCommand(program) {
         .option('--no-local-download', 'Prevent users from downloading and running locally (default: allowed)')
         .option('--no-required-secrets', '(deprecated) No longer needed — required_secrets defaults to []')
         .option('--all', 'Publish all agents in subdirectories (dependency order)')
+        .option('--verbose', 'Show detailed bundle contents (file list)')
         .action(async (options) => {
         const cwd = process.cwd();
         // --all: batch publish all agents in subdirectories
@@ -696,6 +699,11 @@ function registerPublishCommand(program) {
                 process.stdout.write(`\n${chalk_1.default.green('✔')} Published ${org.slug}/${skillData.frontmatter.name}@${skillVersion} successfully!\n\n`);
                 if (hasMultipleFiles) {
                     process.stdout.write(`Files: ${skillFiles.length} files included\n`);
+                    if (options.verbose) {
+                        for (const f of skillFiles) {
+                            process.stdout.write(`  ${f.path}\n`);
+                        }
+                    }
                 }
                 process.stdout.write(`Visibility: private\n`);
                 process.stdout.write(`\nView analytics and usage: https://orchagent.io/dashboard\n`);
@@ -1061,6 +1069,12 @@ function registerPublishCommand(program) {
                 process.stderr.write(`  Files:       ${bundlePreview.fileCount} files\n`);
                 process.stderr.write(`  Size:        ${(bundlePreview.totalSizeBytes / 1024).toFixed(1)} KB\n`);
                 process.stderr.write(`  Entrypoint:  ${bundlePreview.entrypoint}\n`);
+                if (options.verbose && bundlePreview.files?.length) {
+                    process.stderr.write(`  Bundled files:\n`);
+                    for (const f of bundlePreview.files) {
+                        process.stderr.write(`    ${f}\n`);
+                    }
+                }
             }
             process.stderr.write('\nAgent Preview:\n');
             process.stderr.write(`  Name:        ${manifest.name}\n`);
@@ -1324,6 +1338,12 @@ function registerPublishCommand(program) {
                     skipEntrypointCheck: false,
                 });
                 process.stdout.write(`  Created bundle: ${bundleResult.fileCount} files, ${(bundleResult.sizeBytes / 1024).toFixed(1)}KB\n`);
+                if (options.verbose && bundleResult.files?.length) {
+                    process.stdout.write(`  Bundled files:\n`);
+                    for (const f of bundleResult.files) {
+                        process.stdout.write(`    ${f}\n`);
+                    }
+                }
                 // Validate bundle size
                 const validation = await (0, bundle_1.validateBundle)(bundlePath);
                 if (!validation.valid) {
@@ -1404,14 +1424,20 @@ function registerPublishCommand(program) {
         // Show security review result if available
         const secReview = result.security_review;
         if (secReview?.verdict) {
-            if (secReview.verdict === 'passed') {
+            if (secReview.verdict === 'approved') {
                 process.stdout.write(`Security: ${chalk_1.default.green('passed')}\n`);
             }
             else if (secReview.verdict === 'flagged') {
                 process.stdout.write(`Security: ${chalk_1.default.yellow('flagged')} — ${secReview.summary || 'review recommended'}\n`);
             }
+            else if (secReview.verdict === 'error') {
+                process.stdout.write(`Security: ${chalk_1.default.gray('review unavailable')} — publish succeeded, review will be retried\n`);
+            }
+            else if (secReview.verdict === 'skipped') {
+                process.stdout.write(`Security: ${chalk_1.default.gray('review skipped')} — ${secReview.summary || 'content not eligible for review'}\n`);
+            }
             else {
-                process.stdout.write(`Security: ${secReview.verdict}\n`);
+                process.stdout.write(`Security: ${chalk_1.default.gray(secReview.verdict)} — ${secReview.summary || ''}\n`);
             }
         }
         if (result.service_key) {

package/dist/commands/pull.js

@@ -12,21 +12,10 @@ const child_process_1 = require("child_process");
 const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
 const errors_1 = require("../lib/errors");
+const resolve_agent_1 = require("../lib/resolve-agent");
 const analytics_1 = require("../lib/analytics");
 const output_1 = require("../lib/output");
 // ─── Helpers ────────────────────────────────────────────────────────────────
-function parsePullRef(value) {
-    const [ref, versionPart] = value.split('@');
-    const version = versionPart?.trim() || 'latest';
-    const segments = ref.split('/');
-    if (segments.length === 1) {
-        return { agent: segments[0], version };
-    }
-    if (segments.length === 2) {
-        return { org: segments[0], agent: segments[1], version };
-    }
-    throw new errors_1.CliError('Invalid agent reference. Use org/agent[@version] or agent[@version] format.');
-}
 function canonicalType(typeValue) {
     const normalized = (typeValue || 'agent').toLowerCase();
     if (['prompt', 'tool', 'agent', 'skill'].includes(normalized))
@@ -292,7 +281,7 @@ function buildManifest(data) {
     return manifest;
 }
 // ─── Bundle Download + Extraction ───────────────────────────────────────────
-async function downloadBundle(config, org, agent, version, agentId) {
+async function downloadBundle(config, org, agent, version, agentId, workspaceId) {
     try {
         return await (0, api_1.downloadCodeBundle)(config, org, agent, version);
     }
@@ -305,7 +294,7 @@ async function downloadBundle(config, org, agent, version, agentId) {
     }
     if (config.apiKey && agentId) {
         try {
-            return await (0, api_1.downloadCodeBundleAuthenticated)(config, agentId);
+            return await (0, api_1.downloadCodeBundleAuthenticated)(config, agentId, workspaceId);
         }
         catch (err) {
             if (!(err instanceof api_1.ApiError) || err.status !== 404)
@@ -359,19 +348,12 @@ Examples:
                 process.stdout.write(message);
         };
         const config = await (0, config_1.getResolvedConfig)();
-        const parsed = parsePullRef(agentRef);
-        // Resolve org from workspace / defaultOrg fallback
-        const configFile = await (0, config_1.loadConfig)();
-        const org = parsed.org ?? configFile.workspace ?? config.defaultOrg;
-        if (!org) {
-            throw new errors_1.CliError('Missing org. Use org/agent[@version] format, or set a default org with:\n' +
-                '  orch config set default-org <org>');
-        }
-        // Resolve workspace context for the target org
-        const workspaceId = await (0, api_1.resolveWorkspaceIdForOrg)(config, org);
-        write(`Resolving ${org}/${parsed.agent}@${parsed.version}...\n`);
+        const { org, agent: agentName, version, workspaceId } = await (0, resolve_agent_1.resolveAgentContext)(agentRef, config, {
+            missingOrgMessage: 'Missing org. Use org/agent[@version] format, or set a default org with:\n  orch config set default-org <org>',
+        });
+        write(`Resolving ${org}/${agentName}@${version}...\n`);
         // Resolve agent data
-        const data = await resolveAgent(config, org, parsed.agent, parsed.version, workspaceId);
+        const data = await resolveAgent(config, org, agentName, version, workspaceId);
         // Reject skills
         if (canonicalType(data.type) === 'skill') {
             throw new errors_1.CliError("This is a skill. Use 'orch skill install <ref>' instead.");
@@ -411,7 +393,7 @@ Examples:
         // and exit-code 1.
         if (engine === 'code_runtime' && data.has_bundle) {
             write('Downloading code bundle...\n');
-            const bundle = await downloadBundle(config, org, data.name, data.version, data.agentId);
+            const bundle = await downloadBundle(config, org, data.name, data.version, data.agentId, workspaceId);
             if (bundle) {
                 const tempDir = path_1.default.join(os_1.default.tmpdir(), `orchagent-pull-${Date.now()}`);
                 const zipPath = path_1.default.join(tempDir, 'bundle.zip');
@@ -455,7 +437,7 @@ Examples:
         // Track analytics
         await (0, analytics_1.track)('cli_pull', {
             org,
-            agent: parsed.agent,
+            agent: agentName,
             version: data.version,
             engine,
             source: data.source,
@@ -465,7 +447,7 @@ Examples:
         if (options.json) {
             const result = {
                 success: true,
-                requested_ref: `${org}/${parsed.agent}@${parsed.version}`,
+                requested_ref: `${org}/${agentName}@${version}`,
                 resolved_ref: resolvedRef,
                 output_dir: outputDir,
                 engine,

package/dist/commands/replay.js

@@ -91,6 +91,21 @@ function registerReplayCommand(program) {
         .option('--override-policy <id>', 'Override provider policy ID for this replay')
         .option('--no-wait', 'Queue the replay and return immediately without waiting for results')
         .option('--json', 'Output as JSON')
+        .addHelpText('after', `
+How snapshots work:
+  Every cloud run automatically captures a snapshot of its input, config,
+  secrets, and agent version before execution. This snapshot enables
+  deterministic replay — even if the agent has been updated since.
+
+  Local runs (--local) do not create snapshots and cannot be replayed.
+  Runs created before snapshot support was added also cannot be replayed.
+
+Examples:
+  orch replay a1b2c3d4                  Replay and wait for results
+  orch replay a1b2c3d4 --no-wait        Queue and return immediately
+  orch replay a1b2c3d4 --reason "debug" Replay with audit reason
+  orch replay a1b2c3d4 --json           Output as JSON
+`)
         .action(async (runId, options) => {
         const config = await (0, config_1.getResolvedConfig)();
         if (!config.apiKey) {
@@ -109,15 +124,33 @@ function registerReplayCommand(program) {
             throw new errors_1.CliError(`Invalid run ID '${runId}'. Provide a full UUID or a short hex prefix (7+ characters).`);
         }
         // Submit replay request
-        const body = {};
+        const reqBody = {};
         if (options.reason)
-            body.reason = options.reason;
+            reqBody.reason = options.reason;
         if (options.overridePolicy)
-            body.override_provider_policy_id = options.overridePolicy;
-        const replay = await (0, api_1.request)(config, 'POST', `/workspaces/${workspaceId}/runs/${resolvedRunId}/replay`, {
-            body: JSON.stringify(body),
-            headers: { 'Content-Type': 'application/json' },
-        });
+            reqBody.override_provider_policy_id = options.overridePolicy;
+        let replay;
+        try {
+            replay = await (0, api_1.request)(config, 'POST', `/workspaces/${workspaceId}/runs/${resolvedRunId}/replay`, {
+                body: JSON.stringify(reqBody),
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        catch (err) {
+            if (err instanceof api_1.ApiError && err.status === 404) {
+                const isSnapshotMissing = err.message.toLowerCase().includes('snapshot');
+                if (isSnapshotMissing) {
+                    throw new errors_1.CliError(`No snapshot available for run ${resolvedRunId.slice(0, 8)}.\n\n` +
+                        `Snapshots are captured automatically for cloud runs. This run may have been:\n` +
+                        `  - A local run (--local), which does not create snapshots\n` +
+                        `  - Created before snapshot support was added\n\n` +
+                        `Run \`orch logs ${resolvedRunId.slice(0, 8)}\` to inspect the original run.`);
+                }
+                throw new errors_1.CliError(`Run ${resolvedRunId.slice(0, 8)} not found. ` +
+                    `Check the run ID and workspace, or run \`orch logs\` to list recent runs.`);
+            }
+            throw err;
+        }
         if (options.json && options.wait === false) {
             (0, output_1.printJson)(replay);
             return;