@orchagent/cli 0.3.100 → 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 ?? '', workspaceId };
+    return { agent: latest, agentId: latest.id, orgSlug: latest.org_slug ?? org, workspaceId };
 }
 function registerAgentKeysCommand(program) {
     const agentKeys = program

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/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

@@ -1494,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') {
@@ -1511,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) => {
@@ -1617,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
@@ -2037,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))
@@ -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.");
@@ -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;

package/dist/commands/run.js

@@ -54,6 +54,7 @@ const child_process_1 = require("child_process");
 const chalk_1 = __importDefault(require("chalk"));
 const dotenv_1 = require("../lib/dotenv");
 const config_1 = require("../lib/config");
+const resolve_agent_1 = require("../lib/resolve-agent");
 const api_1 = require("../lib/api");
 const errors_1 = require("../lib/errors");
 const output_1 = require("../lib/output");
@@ -84,18 +85,6 @@ function localCommandForEntrypoint(entrypoint) {
     }
     return 'python3';
 }
-function parseAgentRef(value) {
-    const [ref, versionPart] = value.split('@');
-    const version = versionPart?.trim() || DEFAULT_VERSION;
-    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 or agent format.');
-}
 function canonicalAgentType(typeValue) {
     const normalized = (typeValue || 'agent').toLowerCase();
     // Handle legacy type names: agentic → agent, code → tool
@@ -1869,15 +1858,8 @@ async function executeCloud(agentRef, file, options) {
     if (!resolved.apiKey) {
         throw new errors_1.CliError('Missing API key. Run `orchagent login` first.');
     }
-    const parsed = parseAgentRef(agentRef);
-    const configFile = await (0, config_1.loadConfig)();
-    const org = parsed.org ?? configFile.workspace ?? resolved.defaultOrg;
-    if (!org) {
-        throw new errors_1.CliError('Missing org. Use org/agent or set default org.');
-    }
-    // Resolve workspace context for the target org
-    const workspaceId = await (0, api_1.resolveWorkspaceIdForOrg)(resolved, org);
-    const agentMeta = await (0, api_1.getAgentWithFallback)(resolved, org, parsed.agent, parsed.version, workspaceId);
+    const { org, agent: agentName, version, workspaceId } = await (0, resolve_agent_1.resolveAgentContext)(agentRef, resolved);
+    const agentMeta = await (0, api_1.getAgentWithFallback)(resolved, org, agentName, version, workspaceId);
     const cloudType = canonicalAgentType(agentMeta.type);
     const cloudEngine = resolveExecutionEngine({
         type: agentMeta.type,
@@ -1891,10 +1873,8 @@ async function executeCloud(agentRef, file, options) {
         const agentRequiredSecrets = agentMeta.required_secrets;
         if (agentRequiredSecrets?.length) {
             try {
-                // Use already-resolved workspaceId (or fall back to config workspace slug)
-                const wsId = workspaceId ?? (configFile.workspace ? (await (0, api_1.resolveWorkspaceIdForOrg)(resolved, configFile.workspace)) : undefined);
-                if (wsId) {
-                    const secretsResult = await (0, api_1.request)(resolved, 'GET', `/workspaces/${wsId}/secrets`);
+                if (workspaceId) {
+                    const secretsResult = await (0, api_1.request)(resolved, 'GET', `/workspaces/${workspaceId}/secrets`);
                     const existingNames = new Set(secretsResult.secrets.map((s) => s.name));
                     const missing = agentRequiredSecrets.filter((s) => !existingNames.has(s));
                     if (missing.length > 0) {
@@ -1918,7 +1898,7 @@ async function executeCloud(agentRef, file, options) {
     // --estimate-only: show cost estimate and exit without running
     if (options.estimate || options.estimateOnly) {
         try {
-            const est = await (0, api_1.getAgentCostEstimate)(resolved, org, parsed.agent, parsed.version);
+            const est = await (0, api_1.getAgentCostEstimate)(resolved, org, agentName, version);
             const e = est.estimate;
             if (e.sample_size === 0) {
                 process.stderr.write(chalk_1.default.yellow('\nNo run history available for cost estimation.\n'));
@@ -2245,7 +2225,7 @@ async function executeCloud(agentRef, file, options) {
         }
     } // end of non-injection path
     const verboseQs = options.verbose ? '?verbose=true' : '';
-    const url = `${resolved.apiUrl.replace(/\/$/, '')}/${org}/${parsed.agent}/${parsed.version}/${endpoint}${verboseQs}`;
+    const url = `${resolved.apiUrl.replace(/\/$/, '')}/${org}/${agentName}/${version}/${endpoint}${verboseQs}`;
     // Enable SSE streaming for sandbox-backed engines (unless --json or --no-stream or --output)
     const isManagedLoopAgent = cloudType === 'agent' && cloudEngine === 'managed_loop';
     const isCodeRuntimeAgent = cloudEngine === 'code_runtime';
@@ -2257,13 +2237,13 @@ async function executeCloud(agentRef, file, options) {
     }
     // Print verbose debug info before request
     if (options.verbose && !options.json) {
-        process.stderr.write(chalk_1.default.gray(`\n[verbose] ${org}/${parsed.agent}@${parsed.version}\n` +
+        process.stderr.write(chalk_1.default.gray(`\n[verbose] ${org}/${agentName}@${version}\n` +
             `[verbose] type=${cloudType}  engine=${cloudEngine}  endpoint=${endpoint}\n` +
             `[verbose] stream=${wantStream ? 'yes' : 'no'}  url=${url}\n`));
     }
     const { spinner, dispose: disposeSpinner } = options.json
         ? { spinner: null, dispose: () => { } }
-        : (0, spinner_1.createElapsedSpinner)(`Running ${org}/${parsed.agent}@${parsed.version}...`);
+        : (0, spinner_1.createElapsedSpinner)(`Running ${org}/${agentName}@${version}...`);
     spinner?.start();
     // Streamed sandbox runs can take longer; use 10 min timeout (or --wait-timeout).
     const waitTimeoutSec = options.waitTimeout ? parseInt(options.waitTimeout, 10) : undefined;
@@ -2432,11 +2412,11 @@ async function executeCloud(agentRef, file, options) {
         let finalPayload = null;
         let hadError = false;
         if (options.verbose) {
-            process.stderr.write(chalk_1.default.gray(`\nStreaming ${org}/${parsed.agent}@${parsed.version} (verbose):\n`));
+            process.stderr.write(chalk_1.default.gray(`\nStreaming ${org}/${agentName}@${version} (verbose):\n`));
             process.stderr.write(chalk_1.default.gray(`  type=${cloudType}  engine=${cloudEngine}  endpoint=${endpoint}\n`));
         }
         else {
-            process.stderr.write(chalk_1.default.gray(`\nStreaming ${org}/${parsed.agent}@${parsed.version}:\n`));
+            process.stderr.write(chalk_1.default.gray(`\nStreaming ${org}/${agentName}@${version}:\n`));
         }
         let progressErrorShown = false;
         let streamTimedOut = false;
@@ -2497,7 +2477,7 @@ async function executeCloud(agentRef, file, options) {
                     ? ''
                     : chalk_1.default.gray('Tip: Use --wait-timeout <seconds> to wait longer.\n')));
             await (0, analytics_1.track)('cli_run', {
-                agent: `${org}/${parsed.agent}@${parsed.version}`,
+                agent: `${org}/${agentName}@${version}`,
                 input_type: hasInjection ? 'file_injection' : unkeyedFileArgs.length > 0 ? 'file' : options.data ? 'json' : 'empty',
                 mode: 'cloud',
                 streamed: true,
@@ -2508,7 +2488,7 @@ async function executeCloud(agentRef, file, options) {
             throw err;
         }
         await (0, analytics_1.track)('cli_run', {
-            agent: `${org}/${parsed.agent}@${parsed.version}`,
+            agent: `${org}/${agentName}@${version}`,
             input_type: hasInjection ? 'file_injection' : unkeyedFileArgs.length > 0 ? 'file' : options.data ? 'json' : 'empty',
             mode: 'cloud',
             streamed: true,
@@ -2549,14 +2529,14 @@ async function executeCloud(agentRef, file, options) {
                     }
                     const runId = response.headers?.get?.('x-run-id');
                     if (runId) {
-                        process.stderr.write(chalk_1.default.gray(`View logs: orch logs ${runId}\n`));
+                        process.stderr.write(chalk_1.default.gray(`Snapshot saved · Logs: orch logs ${runId}  · Replay: orch replay ${runId}\n`));
                     }
                 }
             }
         }
         return;
     }
-    spinner?.succeed(`Ran ${org}/${parsed.agent}@${parsed.version}`);
+    spinner?.succeed(`Ran ${org}/${agentName}@${version}`);
     const inputType = hasInjection
         ? 'file_injection'
         : unkeyedFileArgs.length > 0
@@ -2569,7 +2549,7 @@ async function executeCloud(agentRef, file, options) {
                         ? 'metadata'
                         : 'empty';
     await (0, analytics_1.track)('cli_run', {
-        agent: `${org}/${parsed.agent}@${parsed.version}`,
+        agent: `${org}/${agentName}@${version}`,
         input_type: inputType,
         mode: 'cloud',
     });
@@ -2638,7 +2618,7 @@ async function executeCloud(agentRef, file, options) {
             }
             const runId = response.headers?.get?.('x-run-id');
             if (runId) {
-                process.stderr.write(chalk_1.default.gray(`View logs: orch logs ${runId}\n`));
+                process.stderr.write(chalk_1.default.gray(`Snapshot saved · Logs: orch logs ${runId}  · Replay: orch replay ${runId}\n`));
             }
         }
     }
@@ -2670,21 +2650,14 @@ async function executeLocal(agentRef, args, options) {
         }
     }
     const resolved = await (0, config_1.getResolvedConfig)();
-    const parsed = parseAgentRef(agentRef);
-    const configFile = await (0, config_1.loadConfig)();
-    const org = parsed.org ?? configFile.workspace ?? resolved.defaultOrg;
-    if (!org) {
-        throw new errors_1.CliError('Missing org. Use org/agent format.');
-    }
-    // Resolve workspace context for the target org
-    const workspaceId = await (0, api_1.resolveWorkspaceIdForOrg)(resolved, org);
+    const { org, agent: localAgentName, version: localVersion, workspaceId } = await (0, resolve_agent_1.resolveAgentContext)(agentRef, resolved);
     // Download agent definition with spinner
-    const agentData = await (0, spinner_1.withSpinner)(`Downloading ${org}/${parsed.agent}@${parsed.version}...`, async () => {
+    const agentData = await (0, spinner_1.withSpinner)(`Downloading ${org}/${localAgentName}@${localVersion}...`, async () => {
         try {
-            return await downloadAgent(resolved, org, parsed.agent, parsed.version, workspaceId);
+            return await downloadAgent(resolved, org, localAgentName, localVersion, workspaceId);
         }
         catch (err) {
-            const agentMeta = await (0, api_1.getPublicAgent)(resolved, org, parsed.agent, parsed.version);
+            const agentMeta = await (0, api_1.getPublicAgent)(resolved, org, localAgentName, localVersion);
             return {
                 type: agentMeta.type || 'agent',
                 run_mode: agentMeta.run_mode ?? null,
@@ -2696,7 +2669,7 @@ async function executeLocal(agentRef, args, options) {
                 supported_providers: agentMeta.supported_providers || ['any'],
             };
         }
-    }, { successText: `Downloaded ${org}/${parsed.agent}@${parsed.version}` });
+    }, { successText: `Downloaded ${org}/${localAgentName}@${localVersion}` });
     const localType = canonicalAgentType(agentData.type);
     const localEngine = resolveExecutionEngine(agentData);
     // Skills cannot be run directly
@@ -2704,8 +2677,8 @@ async function executeLocal(agentRef, args, options) {
         throw new errors_1.CliError('Skills cannot be run directly.\n\n' +
             'Skills are instructions meant to be injected into AI agent contexts.\n\n' +
             'Options:\n' +
-            `  Install for AI tools:  orchagent skill install ${org}/${parsed.agent}\n` +
-            `  Use with an agent:     orchagent run <agent> --skills ${org}/${parsed.agent}`);
+            `  Install for AI tools:  orchagent skill install ${org}/${localAgentName}\n` +
+            `  Use with an agent:     orchagent run <agent> --skills ${org}/${localAgentName}`);
     }
     // Managed-loop agents execute locally with the agent runner.
     if (localEngine === 'managed_loop') {
@@ -2713,11 +2686,11 @@ async function executeLocal(agentRef, args, options) {
             throw new errors_1.CliError('Agent prompt not available for local execution.\n\n' +
                 'This agent may have local download disabled.\n' +
                 'Remove the --local flag to run in the cloud:\n' +
-                `  orch run ${org}/${parsed.agent}@${parsed.version} --data '{"task": "..."}'`);
+                `  orch run ${org}/${localAgentName}@${localVersion} --data '{"task": "..."}'`);
         }
         if (!options.input) {
             process.stderr.write(`\nAgent downloaded. Run with:\n`);
-            process.stderr.write(`  orch run ${org}/${parsed.agent}@${parsed.version} --local --data '{\"task\": \"...\"}'\n`);
+            process.stderr.write(`  orch run ${org}/${localAgentName}@${localVersion} --local --data '{\"task\": \"...\"}'\n`);
             return;
         }
         // Resolve @file.json / @- stdin syntax before parsing
@@ -2731,7 +2704,7 @@ async function executeLocal(agentRef, args, options) {
         }
         warnInputSchemaErrors(agentInputData, agentData.input_schema);
         // Write prompt to temp dir and run
-        const tempAgentDir = path_1.default.join(os_1.default.tmpdir(), `orchagent-agent-${parsed.agent}-${Date.now()}`);
+        const tempAgentDir = path_1.default.join(os_1.default.tmpdir(), `orchagent-agent-${localAgentName}-${Date.now()}`);
         await promises_1.default.mkdir(tempAgentDir, { recursive: true });
         try {
             await promises_1.default.writeFile(path_1.default.join(tempAgentDir, 'prompt.md'), agentData.prompt);
@@ -2761,7 +2734,7 @@ async function executeLocal(agentRef, args, options) {
         }
         if (choice === 'server') {
             process.stderr.write(`\nRun without --local for server execution:\n`);
-            process.stderr.write(`  orch run ${org}/${parsed.agent}@${parsed.version} --data '{...}'\n\n`);
+            process.stderr.write(`  orch run ${org}/${localAgentName}@${localVersion} --data '{...}'\n\n`);
             process.exit(0);
         }
         await downloadDependenciesRecursively(resolved, depStatuses, new Set(), workspaceId);
@@ -2784,13 +2757,13 @@ async function executeLocal(agentRef, args, options) {
         }
     }
     // Save locally
-    const agentDir = await saveAgentLocally(org, parsed.agent, agentData);
+    const agentDir = await saveAgentLocally(org, localAgentName, agentData);
     process.stderr.write(`\nAgent saved to: ${agentDir}\n`);
     if (localEngine === 'code_runtime') {
         if (agentData.has_bundle) {
             if (options.downloadOnly) {
                 process.stdout.write(`\nCode runtime bundle is available for local execution.\n`);
-                process.stdout.write(`Run with: orch run ${org}/${parsed.agent} --local [args...]\n`);
+                process.stdout.write(`Run with: orch run ${org}/${localAgentName} --local [args...]\n`);
                 return;
             }
             // Pre-build injected payload for bundle agent if keyed files/mounts present
@@ -2806,13 +2779,13 @@ async function executeLocal(agentRef, args, options) {
                 });
                 bundleInput = injected.body;
             }
-            await executeBundleAgent(resolved, org, parsed.agent, parsed.version, agentData, args, bundleInput, workspaceId);
+            await executeBundleAgent(resolved, org, localAgentName, localVersion, agentData, args, bundleInput, workspaceId);
             return;
         }
         if (agentData.run_command && (agentData.source_url || agentData.pip_package)) {
             if (options.downloadOnly) {
                 process.stdout.write(`\nTool ready for local execution.\n`);
-                process.stdout.write(`Run with: orch run ${org}/${parsed.agent} --local [args...]\n`);
+                process.stdout.write(`Run with: orch run ${org}/${localAgentName} --local [args...]\n`);
                 return;
             }
             await executeTool(agentData, args);
@@ -2820,12 +2793,12 @@ async function executeLocal(agentRef, args, options) {
         }
         // Fallback: code runtime agent doesn't support local execution.
         process.stdout.write(`\nThis code runtime agent is configured for server execution.\n`);
-        process.stdout.write(`\nRun without --local: orch run ${org}/${parsed.agent}@${parsed.version} --data '{...}'\n`);
+        process.stdout.write(`\nRun without --local: orch run ${org}/${localAgentName}@${localVersion} --data '{...}'\n`);
         return;
     }
     if (options.downloadOnly) {
         process.stdout.write(`\nAgent downloaded. Run with:\n`);
-        process.stdout.write(`  orch run ${org}/${parsed.agent}@${parsed.version} --local --input '{...}'\n`);
+        process.stdout.write(`  orch run ${org}/${localAgentName}@${localVersion} --local --input '{...}'\n`);
         return;
     }
     // Check for keyed file/mount injection
@@ -2835,7 +2808,7 @@ async function executeLocal(agentRef, args, options) {
     // Direct LLM agents execute locally via prompt composition.
     if (!options.input && !execLocalHasInjection) {
         process.stdout.write(`\nAgent ready.\n`);
-        process.stdout.write(`Run with: orch run ${org}/${parsed.agent}@${parsed.version} --local --input '{...}'\n`);
+        process.stdout.write(`Run with: orch run ${org}/${localAgentName}@${localVersion} --local --input '{...}'\n`);
         return;
     }
     let inputData;

package/dist/commands/schedule.js

@@ -162,6 +162,7 @@ function registerScheduleCommand(program) {
         .option('--alert-webhook <url>', 'Webhook URL to POST on failure (HTTPS required)')
         .option('--alert-on-failure-count <n>', 'Number of consecutive failures before alerting (default: 3)', parseInt)
         .option('--workspace <slug>', 'Workspace slug (default: current workspace)')
+        .option('--json', 'Output as JSON')
         .action(async (agentArg, options) => {
         const config = await (0, config_1.getResolvedConfig)();
         if (!config.apiKey) {
@@ -217,6 +218,10 @@ function registerScheduleCommand(program) {
             body: JSON.stringify(body),
             headers: { 'Content-Type': 'application/json' },
         });
+        if (options.json) {
+            (0, output_1.printJson)(result);
+            return;
+        }
         const s = result.schedule;
         process.stdout.write(chalk_1.default.green('\u2713') + ` Schedule created\n\n`);
         process.stdout.write(`  ID:          ${s.id}\n`);
@@ -264,6 +269,7 @@ function registerScheduleCommand(program) {
         .option('--alert-on-failure-count <n>', 'Number of consecutive failures before alerting', parseInt)
         .option('--clear-alert-webhook', 'Remove the alert webhook URL')
         .option('--workspace <slug>', 'Workspace slug (default: current workspace)')
+        .option('--json', 'Output as JSON')
         .action(async (partialScheduleId, options) => {
         const config = await (0, config_1.getResolvedConfig)();
         if (!config.apiKey) {
@@ -322,6 +328,10 @@ function registerScheduleCommand(program) {
             body: JSON.stringify(updates),
             headers: { 'Content-Type': 'application/json' },
         });
+        if (options.json) {
+            (0, output_1.printJson)(result);
+            return;
+        }
         const s = result.schedule;
         process.stdout.write(chalk_1.default.green('\u2713') + ` Schedule updated\n\n`);
         process.stdout.write(`  ID:      ${s.id}\n`);
@@ -349,6 +359,7 @@ function registerScheduleCommand(program) {
         .description('Delete a schedule')
         .option('-y, --yes', 'Skip confirmation prompt')
         .option('--workspace <slug>', 'Workspace slug (default: current workspace)')
+        .option('--json', 'Output as JSON (implies --yes)')
         .action(async (partialScheduleId, options) => {
         const config = await (0, config_1.getResolvedConfig)();
         if (!config.apiKey) {
@@ -356,7 +367,7 @@ function registerScheduleCommand(program) {
         }
         const workspaceId = await resolveWorkspaceId(config, options.workspace);
         const scheduleId = await resolveScheduleId(config, partialScheduleId, workspaceId);
-        if (!options.yes) {
+        if (!options.yes && !options.json) {
             const rl = promises_1.default.createInterface({
                 input: process.stdin,
                 output: process.stdout,
@@ -368,7 +379,11 @@ function registerScheduleCommand(program) {
                 return;
             }
         }
-        await (0, api_1.request)(config, 'DELETE', `/workspaces/${workspaceId}/schedules/${scheduleId}`);
+        const result = await (0, api_1.request)(config, 'DELETE', `/workspaces/${workspaceId}/schedules/${scheduleId}`);
+        if (options.json) {
+            (0, output_1.printJson)({ ...result, id: scheduleId });
+            return;
+        }
         process.stdout.write(chalk_1.default.green('\u2713') + ` Schedule ${scheduleId} deleted\n`);
     });
     // orch schedule trigger <schedule-id>
@@ -378,6 +393,7 @@ function registerScheduleCommand(program) {
         .option('--data <json>', 'Override input data as JSON')
         .addOption(new commander_1.Option('--input <json>').hideHelp())
         .option('--workspace <slug>', 'Workspace slug (default: current workspace)')
+        .option('--json', 'Output as JSON')
         .action(async (partialScheduleId, options) => {
         const config = await (0, config_1.getResolvedConfig)();
         if (!config.apiKey) {
@@ -396,11 +412,17 @@ function registerScheduleCommand(program) {
                 throw new errors_1.CliError('Invalid JSON in --data');
             }
         }
-        process.stdout.write('Triggering schedule...\n');
+        if (!options.json) {
+            process.stdout.write('Triggering schedule...\n');
+        }
         const result = await (0, api_1.request)(config, 'POST', `/workspaces/${workspaceId}/schedules/${scheduleId}/trigger`, body ? {
             body,
             headers: { 'Content-Type': 'application/json' },
         } : {});
+        if (options.json) {
+            (0, output_1.printJson)(result);
+            return;
+        }
         // Status-aware header message
         const isAsync = result.status === 'queued' || result.status === 'deduplicated';
         if (isAsync) {
@@ -565,6 +587,7 @@ function registerScheduleCommand(program) {
         .command('test-alert <schedule-id>')
         .description('Send a test alert to the schedule\'s configured webhook URL')
         .option('--workspace <slug>', 'Workspace slug (default: current workspace)')
+        .option('--json', 'Output as JSON')
         .action(async (partialScheduleId, options) => {
         const config = await (0, config_1.getResolvedConfig)();
         if (!config.apiKey) {
@@ -572,8 +595,14 @@ function registerScheduleCommand(program) {
         }
         const workspaceId = await resolveWorkspaceId(config, options.workspace);
         const scheduleId = await resolveScheduleId(config, partialScheduleId, workspaceId);
-        process.stdout.write('Sending test alert...\n');
+        if (!options.json) {
+            process.stdout.write('Sending test alert...\n');
+        }
         const result = await (0, api_1.request)(config, 'POST', `/workspaces/${workspaceId}/schedules/${scheduleId}/test-alert`);
+        if (options.json) {
+            (0, output_1.printJson)({ ...result, schedule_id: scheduleId });
+            return;
+        }
         if (result.success) {
             process.stdout.write(chalk_1.default.green('\u2713') + ' Test alert delivered successfully\n');
         }
@@ -587,6 +616,7 @@ function registerScheduleCommand(program) {
         .description('Regenerate the webhook secret (invalidates old URL)')
         .option('--workspace <slug>', 'Workspace slug (default: current workspace)')
         .option('-y, --yes', 'Skip confirmation prompt')
+        .option('--json', 'Output as JSON (implies --yes)')
         .action(async (partialScheduleId, options) => {
         const config = await (0, config_1.getResolvedConfig)();
         if (!config.apiKey) {
@@ -594,7 +624,7 @@ function registerScheduleCommand(program) {
         }
         const workspaceId = await resolveWorkspaceId(config, options.workspace);
         const scheduleId = await resolveScheduleId(config, partialScheduleId, workspaceId);
-        if (!options.yes) {
+        if (!options.yes && !options.json) {
             const rl = promises_1.default.createInterface({
                 input: process.stdin,
                 output: process.stdout,
@@ -609,6 +639,10 @@ function registerScheduleCommand(program) {
             }
         }
         const result = await (0, api_1.request)(config, 'POST', `/workspaces/${workspaceId}/schedules/${scheduleId}/regenerate-webhook`);
+        if (options.json) {
+            (0, output_1.printJson)({ ...result, schedule_id: scheduleId });
+            return;
+        }
         process.stdout.write(chalk_1.default.green('\u2713') + ' Webhook secret regenerated\n\n');
         process.stdout.write(`  ${chalk_1.default.bold('New Webhook URL')} (save this — retrieve later with ${chalk_1.default.cyan('orch schedule info --reveal')}):\n`);
         process.stdout.write(`  ${result.webhook_url}\n\n`);

package/dist/commands/security.js

@@ -11,26 +11,11 @@ const chalk_1 = __importDefault(require("chalk"));
 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 output_1 = require("../lib/output");
 const spinner_1 = require("../lib/spinner");
 const llm_1 = require("../lib/llm");
 const analytics_1 = require("../lib/analytics");
-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 { agent: segments[0], version };
-    }
-    if (segments.length === 2) {
-        return { org: segments[0], agent: segments[1], version };
-    }
-    if (segments.length === 3) {
-        return { org: segments[0], agent: segments[1], version: segments[2] };
-    }
-    throw new errors_1.CliError('Invalid agent reference. Use org/agent/version or org/agent@version format.');
-}
 // Severity color mapping
 function severityColor(severity) {
     switch (severity.toLowerCase()) {
@@ -189,15 +174,8 @@ Examples:
         if (!resolved.apiKey) {
             throw new errors_1.CliError('Missing API key. Run `orchagent login` first.');
         }
-        const parsed = parseAgentRef(agentRef);
-        const configFile = await (0, config_1.loadConfig)();
-        const org = parsed.org ?? configFile.workspace ?? resolved.defaultOrg;
-        if (!org) {
-            throw new errors_1.CliError('Missing org. Use org/agent or set default org.');
-        }
-        const agentId = `${org}/${parsed.agent}/${parsed.version}`;
-        // Resolve workspace context for the target org
-        const workspaceId = await (0, api_1.resolveWorkspaceIdForOrg)(resolved, org);
+        const { org, agent: agentName, version, workspaceId } = await (0, resolve_agent_1.resolveAgentContext)(agentRef, resolved);
+        const agentId = `${org}/${agentName}/${version}`;
         // Detect LLM key for the scan
         let llmKey;
         let llmProvider;
@@ -235,6 +213,12 @@ Examples:
         if (options.maxAttacks) {
             requestBody.max_attacks = options.maxAttacks;
         }
+        // Send provider preference so gateway can narrow vault key search
+        // (even when no local key is found, the gateway resolves from vault)
+        const effectiveProvider = llmProvider || options.provider;
+        if (effectiveProvider) {
+            requestBody.llm_provider = effectiveProvider;
+        }
         const url = `${resolved.apiUrl.replace(/\/$/, '')}/security/test`;
         // Make the API call with a spinner
         const spinner = (0, spinner_1.createSpinner)(`Scanning ${agentId} for vulnerabilities...`);

package/dist/commands/transfer.js

@@ -8,6 +8,7 @@ const promises_1 = __importDefault(require("readline/promises"));
 const chalk_1 = __importDefault(require("chalk"));
 const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
+const agent_ref_1 = require("../lib/agent-ref");
 const errors_1 = require("../lib/errors");
 const analytics_1 = require("../lib/analytics");
 const output_1 = require("../lib/output");
@@ -34,7 +35,7 @@ async function promptText(message) {
 }
 function registerTransferCommand(program) {
     program
-        .command('transfer <agent-name>')
+        .command('transfer <agent>')
         .description('Transfer an agent to another workspace')
         .requiredOption('--to <workspace-slug>', 'Target workspace slug')
         .option('-w, --workspace <workspace-slug>', 'Source workspace slug (defaults to active workspace)')
@@ -43,12 +44,13 @@ function registerTransferCommand(program) {
         .option('--json', 'Output result as JSON')
         .addHelpText('after', `
 Examples:
-  orch transfer my-agent --to team-workspace           # Transfer agent to another workspace
+  orch transfer my-agent --to team-workspace           # Transfer by name
+  orch transfer my-org/my-agent --to team-workspace    # Transfer using org/agent format
   orch transfer my-agent --to team-workspace --workspace my-team
   orch transfer my-agent --to team-workspace --dry-run  # Preview transfer
   orch transfer my-agent --to team-workspace --yes      # Skip confirmation
 `)
-        .action(async (agentName, options) => {
+        .action(async (agentArg, options) => {
         const write = (message) => {
             if (!options.json)
                 process.stdout.write(message);
@@ -58,6 +60,14 @@ Examples:
         if (!config.apiKey) {
             throw new errors_1.CliError('Not logged in. Run `orchagent login` first.');
         }
+        // Parse org/agent[@version] or bare agent name
+        const parsed = (0, agent_ref_1.parseAgentRef)(agentArg);
+        const agentName = parsed.agent;
+        // If org was provided via org/agent format, use it as source workspace
+        // --workspace flag takes precedence if both are given
+        if (parsed.org && options.workspace && parsed.org !== options.workspace) {
+            throw new errors_1.CliError(`Conflicting source workspace: '${parsed.org}' (from agent ref) vs '${options.workspace}' (from --workspace flag).`);
+        }
         write('Finding agent and workspaces...\n');
         // Fetch workspace list first (needed to resolve source/target IDs).
         const workspacesResponse = await (0, api_1.request)(config, 'GET', '/workspaces');
@@ -66,8 +76,8 @@ Examples:
         if (!targetWorkspace) {
             throw new errors_1.CliError(`Workspace '${options.to}' not found. Run \`orchagent workspace list\` to see available workspaces.`);
         }
-        // Resolve source workspace (optional). If set, list agents from that workspace.
-        const sourceWorkspaceSlug = options.workspace ?? configFile.workspace;
+        // Resolve source workspace: --workspace flag > org from ref > config workspace
+        const sourceWorkspaceSlug = options.workspace ?? parsed.org ?? configFile.workspace;
         const sourceWorkspace = sourceWorkspaceSlug
             ? workspacesResponse.workspaces.find((w) => w.slug === sourceWorkspaceSlug)
             : null;

package/dist/commands/tree.js

@@ -27,9 +27,21 @@ function registerTreeCommand(program) {
             throw new errors_1.CliError('Missing org. Use org/agent format or set default org.');
         }
         const { agent, version } = parsed;
-        // Resolve workspace context for team workspaces
-        const workspaceId = await (0, api_1.resolveWorkspaceIdForOrg)(config, org);
-        const tree = await (0, api_1.request)(config, 'GET', `/agents/${org}/${agent}/${version}/tree`, ...(workspaceId ? [{ headers: { 'X-Workspace-Id': workspaceId } }] : []));
+        // Public-first fallback: try public tree endpoint (works for any public
+        // agent regardless of caller context), then fall back to authenticated
+        // endpoint with workspace header for private agents. Matches the pattern
+        // used by info/fork/estimate commands. (T12-04)
+        let tree;
+        try {
+            tree = await (0, api_1.publicRequest)(config, `/public/agents/${org}/${agent}/${version}/tree`);
+        }
+        catch (err) {
+            if (!(err instanceof api_1.ApiError) || err.status !== 404)
+                throw err;
+            // Public endpoint returned 404 — try authenticated endpoint for private agents
+            const workspaceId = await (0, api_1.resolveWorkspaceIdForOrg)(config, org);
+            tree = await (0, api_1.request)(config, 'GET', `/agents/${org}/${agent}/${version}/tree`, workspaceId ? { headers: { 'X-Workspace-Id': workspaceId } } : undefined);
+        }
         if (options.json) {
             console.log(JSON.stringify(tree, null, 2));
             return;

package/dist/lib/bundle.js

@@ -137,18 +137,23 @@ async function createCodeBundle(sourceDir, outputPath, options = {}) {
         const output = (0, fs_1.createWriteStream)(outputPath);
         const archive = (0, archiver_1.default)('zip', { zlib: { level: 9 } });
         let fileCount = 0;
+        const files = [];
         output.on('close', () => {
             resolve({
                 path: outputPath,
                 sizeBytes: archive.pointer(),
                 fileCount,
+                files,
             });
         });
         archive.on('error', (err) => {
             reject(err);
         });
-        archive.on('entry', () => {
+        archive.on('entry', (entry) => {
             fileCount++;
+            if (entry.name) {
+                files.push(entry.name);
+            }
         });
         archive.pipe(output);
         // Add directory contents with exclusions
@@ -235,6 +240,7 @@ async function previewBundle(sourceDir, options = {}) {
         totalSizeBytes,
         entrypoint,
         excludePatterns,
+        files,
     };
 }
 /**

package/dist/lib/resolve-agent.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveOrg = resolveOrg;
+exports.resolveAgentContext = resolveAgentContext;
+const agent_ref_1 = require("./agent-ref");
+const config_1 = require("./config");
+const api_1 = require("./api");
+const errors_1 = require("./errors");
+/**
+ * Resolve the org from a parsed AgentRef using the standard fallback chain:
+ *   1. Explicit org from ref (org/agent@version)
+ *   2. Workspace from config file
+ *   3. defaultOrg from resolved config
+ *
+ * Throws CliError if no org can be determined.
+ */
+async function resolveOrg(parsed, config, options) {
+    if (parsed.org)
+        return parsed.org;
+    const configFile = await (0, config_1.loadConfig)();
+    const org = configFile.workspace ?? config.defaultOrg;
+    if (!org) {
+        throw new errors_1.CliError(options?.missingOrgMessage ??
+            'Missing org. Use org/agent format or set default org.');
+    }
+    return org;
+}
+/**
+ * Central agent-reference resolution pipeline used by all commands.
+ *
+ * Takes a raw agent reference string (e.g., "org/agent@v2", "agent", "agent@latest")
+ * and resolves it to a full context with org, agent name, version, and workspace ID.
+ *
+ * Resolution steps:
+ *   1. Parse the ref string into { org?, agent, version }
+ *   2. Resolve org via fallback chain: ref → config workspace → defaultOrg
+ *   3. Resolve workspace ID for team workspace context (optional)
+ *
+ * @example
+ *   const ctx = await resolveAgentContext('acme/my-agent@v2', config)
+ *   // ctx = { org: 'acme', agent: 'my-agent', version: 'v2', workspaceId: 'ws-123' }
+ *
+ * @example
+ *   const ctx = await resolveAgentContext('my-agent', config)
+ *   // ctx = { org: 'default-org', agent: 'my-agent', version: 'latest', workspaceId: undefined }
+ */
+async function resolveAgentContext(agentRefString, config, options) {
+    const parsed = (0, agent_ref_1.parseAgentRef)(agentRefString);
+    const org = await resolveOrg(parsed, config, {
+        missingOrgMessage: options?.missingOrgMessage,
+    });
+    let workspaceId;
+    if (!options?.skipWorkspaceResolution) {
+        workspaceId = await (0, api_1.resolveWorkspaceIdForOrg)(config, org);
+    }
+    return {
+        org,
+        agent: parsed.agent,
+        version: parsed.version,
+        workspaceId,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchagent/cli",
-  "version": "0.3.100",
+  "version": "0.3.101",
   "description": "Command-line interface for orchagent — deploy and run AI agents for your team",
   "license": "MIT",
   "author": "orchagent <hello@orchagent.io>",