@orchagent/cli 0.3.63 → 0.3.64

package/dist/commands/init.js

@@ -86,15 +86,15 @@ if __name__ == "__main__":
     main()
 `;
 function readmeTemplate(agentName, flavor) {
-    const inputField = flavor === 'managed_loop' ? 'task' : 'input';
-    const inputDescription = flavor === 'managed_loop' ? 'The task to perform' : 'The input to process';
+    const inputField = flavor === 'managed_loop' || flavor === 'orchestrator' ? 'task' : 'input';
+    const inputDescription = flavor === 'managed_loop' || flavor === 'orchestrator' ? 'The task to perform' : 'The input to process';
     const cloudExample = flavor === 'code_runtime'
         ? `orchagent run ${agentName} --data '{"input": "Hello world"}'`
         : `orchagent run ${agentName} --data '{"${inputField}": "Hello world"}'`;
     const localExample = flavor === 'code_runtime'
         ? `orchagent run ${agentName} --local --data '{"input": "Hello world"}'`
         : `orchagent run ${agentName} --local --data '{"${inputField}": "Hello world"}'`;
-    return `# ${agentName}
+    let readme = `# ${agentName}
 
 A brief description of what this agent does.
 
@@ -124,6 +124,20 @@ ${localExample}
 |-------|------|-------------|
 | \`result\` | string | The agent's response |
 `;
+    if (flavor === 'orchestrator') {
+        readme += `
+## Dependencies
+
+This orchestrator calls other agents. Update \`manifest.dependencies\` in \`orchagent.json\` with your actual dependencies.
+
+**Publish order:** Publish dependency agents first, then this orchestrator.
+
+| Dependency | Version | Description |
+|------------|---------|-------------|
+| \`org/agent-name\` | v1 | TODO: describe what this agent does |
+`;
+    }
+    return readme;
 }
 const AGENT_PROMPT_TEMPLATE = `You are a helpful AI agent.
 
@@ -157,6 +171,65 @@ const AGENT_SCHEMA_TEMPLATE = `{
   }
 }
 `;
+const ORCHESTRATOR_MAIN_PY = `"""
+orchagent orchestrator entrypoint.
+
+Reads JSON input from stdin, calls dependency agents via the orchagent SDK,
+and writes JSON output to stdout.
+
+Usage:
+  echo '{"task": "do something"}' | python main.py
+"""
+
+import asyncio
+import json
+import sys
+
+from orchagent import AgentClient
+
+
+def main():
+    # Read JSON input from stdin
+    raw = sys.stdin.read()
+    try:
+        data = json.loads(raw) if raw.strip() else {}
+    except json.JSONDecodeError:
+        print(json.dumps({"error": "Invalid JSON input"}))
+        sys.exit(1)
+
+    task = data.get("task", "")
+
+    # --- Your orchestration logic here ---
+    # The AgentClient reads ORCHAGENT_SERVICE_KEY from the environment automatically.
+    # Do NOT add ORCHAGENT_SERVICE_KEY to required_secrets — the gateway injects it.
+    client = AgentClient()
+
+    # Call a dependency agent (must be listed in manifest.dependencies)
+    result = asyncio.run(
+        client.call("org/agent-name@v1", {"input": task})
+    )
+
+    # You can chain multiple calls, run them in parallel, or add conditional logic:
+    #
+    # Sequential:
+    #   result2 = asyncio.run(client.call("org/another-agent@v1", {"input": result}))
+    #
+    # Parallel:
+    #   r1, r2 = asyncio.run(asyncio.gather(
+    #       client.call("org/agent-a@v1", {"input": task}),
+    #       client.call("org/agent-b@v1", {"input": task}),
+    #   ))
+    # --- End orchestration logic ---
+
+    # Write JSON output to stdout
+    print(json.dumps({"result": result, "success": True}))
+
+
+if __name__ == "__main__":
+    main()
+`;
+const ORCHESTRATOR_REQUIREMENTS = `orchagent-sdk>=0.1.0
+`;
 const SKILL_TEMPLATE = `---
 name: my-skill
 description: When to use this skill
@@ -189,6 +262,7 @@ function registerInitCommand(program) {
         .description('Initialize a new agent project')
         .argument('[name]', 'Agent name (default: current directory name)')
         .option('--type <type>', 'Type: prompt, tool, agent, or skill (legacy aliases: agentic, code)', 'prompt')
+        .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')
         .action(async (name, options) => {
         const cwd = process.cwd();
@@ -196,7 +270,13 @@ function registerInitCommand(program) {
         if (!['on_demand', 'always_on'].includes(runMode)) {
             throw new errors_1.CliError("Invalid --run-mode. Use 'on_demand' or 'always_on'.");
         }
-        const initMode = resolveInitFlavor(options.type);
+        let initMode = resolveInitFlavor(options.type);
+        if (options.orchestrator) {
+            if (initMode.type === 'skill') {
+                throw new errors_1.CliError('Cannot use --orchestrator with --type skill. Orchestrators are agent-type agents that call other agents.');
+            }
+            initMode = { type: 'agent', flavor: 'orchestrator' };
+        }
         // When a name is provided, create a subdirectory for the project
         const targetDir = name ? path_1.default.join(cwd, name) : cwd;
         const agentName = name || path_1.default.basename(cwd);
@@ -247,7 +327,7 @@ function registerInitCommand(program) {
                 throw err;
             }
         }
-        if (initMode.flavor !== 'code_runtime' && runMode === 'always_on') {
+        if (initMode.flavor !== 'code_runtime' && initMode.flavor !== 'orchestrator' && 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.");
         }
         // Create manifest and type-specific files
@@ -255,7 +335,19 @@ function registerInitCommand(program) {
         manifest.name = agentName;
         manifest.type = initMode.type;
         manifest.run_mode = runMode;
-        if (initMode.flavor === 'managed_loop') {
+        if (initMode.flavor === 'orchestrator') {
+            manifest.description = 'An orchestrator agent that coordinates other agents';
+            manifest.runtime = { command: 'python main.py' };
+            manifest.manifest = {
+                manifest_version: 1,
+                dependencies: [{ id: 'org/agent-name', version: 'v1' }],
+                max_hops: 3,
+                timeout_ms: 120000,
+                per_call_downstream_cap: 50,
+            };
+            manifest.required_secrets = [];
+        }
+        else if (initMode.flavor === 'managed_loop') {
             manifest.description = 'An AI agent with tool use';
             manifest.supported_providers = ['anthropic'];
             manifest.loop = { max_turns: 25 };
@@ -267,7 +359,14 @@ function registerInitCommand(program) {
             manifest.required_secrets = [];
         }
         await promises_1.default.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
-        if (initMode.flavor === 'code_runtime') {
+        if (initMode.flavor === 'orchestrator') {
+            const entrypointPath = path_1.default.join(targetDir, 'main.py');
+            const requirementsPath = path_1.default.join(targetDir, 'requirements.txt');
+            await promises_1.default.writeFile(entrypointPath, ORCHESTRATOR_MAIN_PY);
+            await promises_1.default.writeFile(requirementsPath, ORCHESTRATOR_REQUIREMENTS);
+            await promises_1.default.writeFile(schemaPath, AGENT_SCHEMA_TEMPLATE);
+        }
+        else if (initMode.flavor === 'code_runtime') {
             const entrypointPath = path_1.default.join(targetDir, 'main.py');
             await promises_1.default.writeFile(entrypointPath, CODE_TEMPLATE_PY);
             await promises_1.default.writeFile(schemaPath, SCHEMA_TEMPLATE);
@@ -286,19 +385,32 @@ function registerInitCommand(program) {
         process.stdout.write(`Initialized agent "${agentName}" in ${targetDir}\n`);
         process.stdout.write(`\nFiles created:\n`);
         const prefix = name ? name + '/' : '';
-        process.stdout.write(`  ${prefix}orchagent.json - Agent configuration\n`);
-        if (initMode.flavor === 'code_runtime') {
-            process.stdout.write(`  ${prefix}main.py        - Agent entrypoint (stdin/stdout JSON)\n`);
+        process.stdout.write(`  ${prefix}orchagent.json    - Agent configuration\n`);
+        if (initMode.flavor === 'orchestrator') {
+            process.stdout.write(`  ${prefix}main.py           - Orchestrator entrypoint (SDK calls)\n`);
+            process.stdout.write(`  ${prefix}requirements.txt  - Python dependencies (orchagent-sdk)\n`);
+        }
+        else if (initMode.flavor === 'code_runtime') {
+            process.stdout.write(`  ${prefix}main.py           - Agent entrypoint (stdin/stdout JSON)\n`);
         }
         else {
-            process.stdout.write(`  ${prefix}prompt.md      - Prompt template\n`);
+            process.stdout.write(`  ${prefix}prompt.md         - Prompt template\n`);
         }
-        process.stdout.write(`  ${prefix}schema.json    - Input/output schemas\n`);
-        process.stdout.write(`  ${prefix}README.md      - Agent documentation\n`);
+        process.stdout.write(`  ${prefix}schema.json       - Input/output schemas\n`);
+        process.stdout.write(`  ${prefix}README.md         - Agent documentation\n`);
         process.stdout.write(`  Run mode: ${runMode}\n`);
-        process.stdout.write(`  Execution: ${initMode.flavor}\n`);
+        process.stdout.write(`  Execution: ${initMode.flavor === 'orchestrator' ? 'code_runtime (orchestrator)' : initMode.flavor}\n`);
         process.stdout.write(`\nNext steps:\n`);
-        if (initMode.flavor === 'code_runtime') {
+        if (initMode.flavor === 'orchestrator') {
+            const stepNum = name ? 2 : 1;
+            if (name) {
+                process.stdout.write(`  1. cd ${name}\n`);
+            }
+            process.stdout.write(`  ${stepNum}. Update manifest.dependencies in orchagent.json with your actual agents\n`);
+            process.stdout.write(`  ${stepNum + 1}. Edit main.py with your orchestration logic\n`);
+            process.stdout.write(`  ${stepNum + 2}. Publish dependency agents first, then: orchagent publish\n`);
+        }
+        else if (initMode.flavor === 'code_runtime') {
             const stepNum = name ? 2 : 1;
             if (name) {
                 process.stdout.write(`  1. cd ${name}\n`);

package/dist/commands/publish.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractTemplateVariables = extractTemplateVariables;
 exports.deriveInputSchema = deriveInputSchema;
 exports.scanUndeclaredEnvVars = scanUndeclaredEnvVars;
+exports.checkDependencies = checkDependencies;
 exports.registerPublishCommand = registerPublishCommand;
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
@@ -15,7 +16,6 @@ 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 api_2 = require("../lib/api");
 const analytics_1 = require("../lib/analytics");
 const bundle_1 = require("../lib/bundle");
 /**
@@ -270,6 +270,56 @@ function commandForEntrypoint(entrypoint) {
     }
     return `python ${entrypoint}`;
 }
+/**
+ * Check if manifest dependencies are published and callable.
+ * Best-effort: network errors cause the check to be silently skipped
+ * (returns empty array) to avoid false alarms.
+ */
+async function checkDependencies(config, dependencies, publishingOrgSlug, workspaceId) {
+    // Pre-fetch user's agents if any deps are in the same org (one API call)
+    let myAgents = null;
+    const hasSameOrgDeps = dependencies.some(d => {
+        const [org] = d.id.split('/');
+        return org === publishingOrgSlug;
+    });
+    if (hasSameOrgDeps) {
+        try {
+            const headers = {};
+            if (workspaceId)
+                headers['X-Workspace-Id'] = workspaceId;
+            myAgents = await (0, api_1.request)(config, 'GET', '/agents', { headers });
+        }
+        catch {
+            return []; // Can't reach API — skip check entirely
+        }
+    }
+    return Promise.all(dependencies.map(async (dep) => {
+        const parts = dep.id.split('/');
+        const ref = `${dep.id}@${dep.version}`;
+        if (parts.length !== 2)
+            return { ref, status: 'not_found' };
+        const [depOrg, depName] = parts;
+        // Same org: check against pre-fetched agent list
+        if (depOrg === publishingOrgSlug && myAgents) {
+            const match = myAgents.find(a => a.name === depName && a.version === dep.version);
+            if (!match)
+                return { ref, status: 'not_found' };
+            return { ref, status: match.callable ? 'found_callable' : 'found_not_callable' };
+        }
+        // Different org: try public endpoint
+        try {
+            const agent = await (0, api_1.getPublicAgent)(config, depOrg, depName, dep.version);
+            return { ref, status: agent.callable ? 'found_callable' : 'found_not_callable' };
+        }
+        catch (err) {
+            if (err?.status === 404) {
+                return { ref, status: 'not_found' };
+            }
+            // Network/unexpected error — don't false alarm
+            return { ref, status: 'found_callable' };
+        }
+    }));
+}
 function registerPublishCommand(program) {
     program
         .command('publish')
@@ -287,18 +337,33 @@ function registerPublishCommand(program) {
             : undefined;
         const config = await (0, config_1.getResolvedConfig)({}, options.profile);
         const cwd = process.cwd();
+        // Resolve workspace context — if `orch workspace use` was called, publish
+        // to that workspace instead of the personal org (F-5)
+        const configFile = await (0, config_1.loadConfig)();
+        let workspaceId;
+        if (configFile.workspace) {
+            const { workspaces } = await (0, api_1.request)(config, 'GET', '/workspaces');
+            const ws = workspaces.find(w => w.slug === configFile.workspace);
+            if (!ws) {
+                throw new errors_1.CliError(`Workspace '${configFile.workspace}' not found. Run \`orch workspace list\` to see available workspaces.`);
+            }
+            workspaceId = ws.id;
+        }
         // Check for SKILL.md first (skills take precedence)
         const skillMdPath = path_1.default.join(cwd, 'SKILL.md');
         const skillData = await parseSkillMd(skillMdPath);
         if (skillData) {
             // Publish as a skill (server auto-assigns version)
-            const org = await (0, api_1.getOrg)(config);
+            const org = await (0, api_1.getOrg)(config, workspaceId);
+            if (workspaceId && !options.dryRun) {
+                process.stdout.write(`Workspace: ${org.slug}\n`);
+            }
             // SC-05: Collect all files in the skill directory for multi-file support
             const skillFiles = await collectSkillFiles(cwd);
             const hasMultipleFiles = skillFiles.length > 1;
             // Handle dry-run for skills
             if (options.dryRun) {
-                const preview = await (0, api_1.previewAgentVersion)(config, skillData.frontmatter.name);
+                const preview = await (0, api_1.previewAgentVersion)(config, skillData.frontmatter.name, workspaceId);
                 const skillBodyBytes = Buffer.byteLength(skillData.body, 'utf-8');
                 const totalFilesSize = skillFiles.reduce((sum, f) => sum + f.size, 0);
                 const versionInfo = preview.existing_versions.length > 0
@@ -315,6 +380,9 @@ function registerPublishCommand(program) {
                 process.stderr.write('\nSkill Preview:\n');
                 process.stderr.write(`  Name:        ${skillData.frontmatter.name}\n`);
                 process.stderr.write(`  Type:        skill\n`);
+                if (workspaceId) {
+                    process.stderr.write(`  Workspace:   ${org.slug}\n`);
+                }
                 process.stderr.write(`  Version:     ${versionInfo}\n`);
                 process.stderr.write(`  Visibility:  private\n`);
                 process.stderr.write(`  Providers:   any\n`);
@@ -345,7 +413,7 @@ function registerPublishCommand(program) {
                     // SC-05: Include all skill files for UI preview
                     skill_files: hasMultipleFiles ? skillFiles : undefined,
                     allow_local_download: options.localDownload || false,
-                });
+                }, workspaceId);
                 const skillVersion = skillResult.agent?.version || 'v1';
                 const skillAgentId = skillResult.agent?.id;
                 await (0, analytics_1.track)('cli_publish', { agent_type: 'skill', multi_file: hasMultipleFiles });
@@ -574,8 +642,11 @@ function registerPublishCommand(program) {
         if (options.docker && executionEngine !== 'code_runtime') {
             throw new errors_1.CliError('--docker is only supported for code runtime agents');
         }
-        // Get org info
-        const org = await (0, api_1.getOrg)(config);
+        // Get org info (workspace-aware — returns workspace org if workspace is active)
+        const org = await (0, api_1.getOrg)(config, workspaceId);
+        if (workspaceId && !options.dryRun) {
+            process.stdout.write(`Workspace: ${org.slug}\n`);
+        }
         // Default to 'any' provider if not specified
         const supportedProviders = manifest.supported_providers || ['any'];
         // Detect SDK compatibility for code runtime agents
@@ -586,9 +657,33 @@ function registerPublishCommand(program) {
                 process.stdout.write(`SDK detected - agent will be marked as Local Ready\n`);
             }
         }
+        // Check if manifest dependencies are published and callable (F-9b).
+        // Runs for both dry-run and normal publish so users catch issues early.
+        const manifestDeps = manifest.manifest?.dependencies;
+        if (manifestDeps?.length) {
+            const depResults = await checkDependencies(config, manifestDeps, org.slug, workspaceId);
+            const notFound = depResults.filter(r => r.status === 'not_found');
+            const notCallable = depResults.filter(r => r.status === 'found_not_callable');
+            if (notFound.length > 0) {
+                process.stderr.write(chalk_1.default.yellow(`\n⚠ Unpublished dependencies:\n`));
+                for (const dep of notFound) {
+                    process.stderr.write(chalk_1.default.yellow(`  - ${dep.ref}\n`));
+                }
+                process.stderr.write(`\n  These agents must be published before this orchestrator can call them.\n` +
+                    `  Publish each dependency first, then re-run this publish.\n\n`);
+            }
+            if (notCallable.length > 0) {
+                process.stderr.write(chalk_1.default.yellow(`\n⚠ Dependencies not marked as callable:\n`));
+                for (const dep of notCallable) {
+                    process.stderr.write(chalk_1.default.yellow(`  - ${dep.ref}\n`));
+                }
+                process.stderr.write(`\n  Agents must have callable: true in orchagent.json to be invoked\n` +
+                    `  by orchestrators. Update and republish each dependency.\n\n`);
+            }
+        }
         // Handle dry-run for agents
         if (options.dryRun) {
-            const preview = await (0, api_1.previewAgentVersion)(config, manifest.name);
+            const preview = await (0, api_1.previewAgentVersion)(config, manifest.name, workspaceId);
             const versionInfo = preview.existing_versions.length > 0
                 ? `${preview.next_version} (new version, ${preview.existing_versions[preview.existing_versions.length - 1]} exists)`
                 : `${preview.next_version} (first version)`;
@@ -641,6 +736,9 @@ function registerPublishCommand(program) {
             process.stderr.write('\nAgent Preview:\n');
             process.stderr.write(`  Name:        ${manifest.name}\n`);
             process.stderr.write(`  Type:        ${canonicalType}\n`);
+            if (workspaceId) {
+                process.stderr.write(`  Workspace:   ${org.slug}\n`);
+            }
             process.stderr.write(`  Run mode:    ${runMode}\n`);
             process.stderr.write(`  Engine:      ${executionEngine}${shouldUploadBundle ? ' (hosted)' : ''}\n`);
             process.stderr.write(`  Callable:    ${callable ? 'enabled' : 'disabled'}\n`);
@@ -719,11 +817,11 @@ function registerPublishCommand(program) {
                 default_skills: skillsFromFlag || manifest.default_skills,
                 skills_locked: manifest.skills_locked || options.skillsLocked || undefined,
                 allow_local_download: options.localDownload || false,
-            });
+            }, workspaceId);
         }
         catch (err) {
             // Improve SECURITY_BLOCKED error display
-            if (err instanceof api_2.ApiError && err.status === 422) {
+            if (err instanceof api_1.ApiError && err.status === 422) {
                 const payload = err.payload;
                 const errorCode = payload?.error?.code;
                 if (errorCode === 'SECURITY_BLOCKED') {
@@ -855,6 +953,22 @@ function registerPublishCommand(program) {
             process.stdout.write(`\nService key (save this - shown only once):\n`);
             process.stdout.write(`  ${result.service_key}\n`);
         }
+        // Show next-step CLI command based on run mode
+        const runRef = `${org.slug}/${manifest.name}`;
+        if (runMode === 'always_on') {
+            process.stdout.write(`\nDeploy as service:\n`);
+            process.stdout.write(`  orch service deploy ${runRef}\n`);
+        }
+        else {
+            const schemaProps = inputSchema && typeof inputSchema === 'object' && 'properties' in inputSchema
+                ? Object.keys(inputSchema.properties).slice(0, 3)
+                : null;
+            const exampleFields = schemaProps?.length
+                ? schemaProps.map(k => `"${k}": "..."`).join(', ')
+                : '"input": "..."';
+            process.stdout.write(`\nRun with CLI:\n`);
+            process.stdout.write(`  orch run ${runRef} --data '{${exampleFields}}'\n`);
+        }
         process.stdout.write(`\nAPI endpoint:\n`);
         process.stdout.write(`  POST ${config.apiUrl}/${org.slug}/${manifest.name}/${assignedVersion}/run\n`);
         if (shouldUploadBundle) {

package/dist/lib/api.js

@@ -275,8 +275,11 @@ async function publicRequest(config, path) {
     }
     return (await response.json());
 }
-async function getOrg(config) {
-    return request(config, 'GET', '/org');
+async function getOrg(config, workspaceId) {
+    const headers = {};
+    if (workspaceId)
+        headers['X-Workspace-Id'] = workspaceId;
+    return request(config, 'GET', '/org', { headers });
 }
 async function updateOrg(config, payload) {
     return request(config, 'PATCH', '/org', {
@@ -290,10 +293,13 @@ async function getPublicAgent(config, org, agent, version) {
 async function listMyAgents(config) {
     return request(config, 'GET', '/agents');
 }
-async function createAgent(config, data) {
+async function createAgent(config, data, workspaceId) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (workspaceId)
+        headers['X-Workspace-Id'] = workspaceId;
     return request(config, 'POST', '/agents', {
         body: JSON.stringify(data),
-        headers: { 'Content-Type': 'application/json' },
+        headers,
     });
 }
 async function fetchLlmKeys(config) {
@@ -446,8 +452,11 @@ async function transferAgent(config, agentId, data) {
 /**
  * Preview the next version number for an agent.
  */
-async function previewAgentVersion(config, agentName) {
-    return request(config, 'GET', `/agents/preview?name=${encodeURIComponent(agentName)}`);
+async function previewAgentVersion(config, agentName, workspaceId) {
+    const headers = {};
+    if (workspaceId)
+        headers['X-Workspace-Id'] = workspaceId;
+    return request(config, 'GET', `/agents/preview?name=${encodeURIComponent(agentName)}`, { headers });
 }
 /**
  * Report a skill installation to the backend.

package/package.json

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