@orchagent/cli 0.3.64 → 0.3.66

package/dist/commands/index.js

@@ -34,6 +34,7 @@ const service_1 = require("./service");
 const transfer_1 = require("./transfer");
 const pull_1 = require("./pull");
 const logs_1 = require("./logs");
+const secrets_1 = require("./secrets");
 function registerCommands(program) {
     (0, login_1.registerLoginCommand)(program);
     (0, whoami_1.registerWhoamiCommand)(program);
@@ -68,4 +69,5 @@ function registerCommands(program) {
     (0, transfer_1.registerTransferCommand)(program);
     (0, pull_1.registerPullCommand)(program);
     (0, logs_1.registerLogsCommand)(program);
+    (0, secrets_1.registerSecretsCommand)(program);
 }

package/dist/commands/init.js

@@ -7,6 +7,7 @@ exports.registerInitCommand = registerInitCommand;
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
 const errors_1 = require("../lib/errors");
+const github_weekly_summary_1 = require("./templates/github-weekly-summary");
 const MANIFEST_TEMPLATE = `{
   "name": "my-agent",
   "description": "A simple AI agent",
@@ -86,6 +87,64 @@ if __name__ == "__main__":
     main()
 `;
 function readmeTemplate(agentName, flavor) {
+    if (flavor === 'discord') {
+        return `# ${agentName}
+
+An always-on Discord bot powered by Claude.
+
+## Setup
+
+### 1. Create a Discord bot
+
+1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
+2. Create a new application, then go to **Bot** and copy the bot token
+3. Under **Privileged Gateway Intents**, enable **Message Content Intent**
+4. Go to **OAuth2 > URL Generator**, select \`bot\` scope, then invite to your server
+
+### 2. Get channel IDs
+
+Enable Developer Mode in Discord (Settings > Advanced), then right-click a channel and copy its ID.
+
+### 3. Local development
+
+\`\`\`sh
+cp .env.example .env
+# Fill in DISCORD_BOT_TOKEN, ANTHROPIC_API_KEY, DISCORD_CHANNEL_IDS
+
+pip install -r requirements.txt
+python main.py
+\`\`\`
+
+### 4. Deploy
+
+\`\`\`sh
+orch publish
+
+# Add secrets in your workspace (web dashboard > Settings > Secrets):
+#   DISCORD_BOT_TOKEN — your bot token
+#   DISCORD_CHANNEL_IDS — comma-separated channel IDs
+
+orch service deploy
+\`\`\`
+
+## Customization
+
+Edit \`main.py\` to customize:
+
+- **SYSTEM_PROMPT** — controls how the bot responds
+- **MODEL** / **MAX_TOKENS** — override via env vars
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| \`DISCORD_BOT_TOKEN\` | Yes | Discord bot token (workspace secret) |
+| \`ANTHROPIC_API_KEY\` | Auto | Injected by orchagent via \`supported_providers\` |
+| \`DISCORD_CHANNEL_IDS\` | Yes | Comma-separated channel IDs (workspace secret) |
+| \`MODEL\` | No | Claude model (default: claude-sonnet-4-5-20250929) |
+| \`MAX_TOKENS\` | No | Max response tokens (default: 1024) |
+`;
+    }
     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'
@@ -230,6 +289,162 @@ if __name__ == "__main__":
 `;
 const ORCHESTRATOR_REQUIREMENTS = `orchagent-sdk>=0.1.0
 `;
+const DISCORD_MAIN_PY = `"""
+Discord bot agent — powered by Claude.
+
+Listens for messages in configured channels and responds using the Anthropic API.
+
+Local development:
+  1. Copy .env.example to .env and fill in your tokens
+  2. pip install -r requirements.txt
+  3. python main.py
+"""
+
+import asyncio
+import logging
+import os
+import sys
+
+import anthropic
+import discord
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+DISCORD_BOT_TOKEN = os.environ.get("DISCORD_BOT_TOKEN", "")
+ANTHROPIC_API_KEY = os.environ.get("ANTHROPIC_API_KEY", "")
+DISCORD_CHANNEL_IDS = os.environ.get("DISCORD_CHANNEL_IDS", "")
+
+MODEL = os.environ.get("MODEL", "claude-sonnet-4-5-20250929")
+MAX_TOKENS = int(os.environ.get("MAX_TOKENS", "1024"))
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    stream=sys.stdout,
+)
+logger = logging.getLogger("discord-bot")
+
+SYSTEM_PROMPT = """\\
+You are a helpful assistant in a Discord server.
+
+Be concise and friendly. Use code blocks for code examples.
+Keep responses under 1800 characters (Discord limit is 2000)."""
+
+
+# ---------------------------------------------------------------------------
+# Anthropic API
+# ---------------------------------------------------------------------------
+
+
+def ask_claude(client: anthropic.Anthropic, user_message: str) -> str:
+    """Send a message to Claude and return the response."""
+    response = client.messages.create(
+        model=MODEL,
+        max_tokens=MAX_TOKENS,
+        system=SYSTEM_PROMPT,
+        messages=[{"role": "user", "content": user_message}],
+    )
+    return response.content[0].text
+
+
+# ---------------------------------------------------------------------------
+# Discord bot
+# ---------------------------------------------------------------------------
+
+
+def parse_channel_ids(raw: str) -> set[int]:
+    """Parse comma-separated channel IDs from env var."""
+    return {int(x.strip()) for x in raw.split(",") if x.strip().isdigit()}
+
+
+class Bot(discord.Client):
+    def __init__(self, anthropic_client: anthropic.Anthropic, allowed_channels: set[int]):
+        intents = discord.Intents.default()
+        intents.message_content = True
+        super().__init__(intents=intents)
+        self.anthropic_client = anthropic_client
+        self.allowed_channels = allowed_channels
+
+    async def on_ready(self):
+        logger.info("Bot connected as %s", self.user)
+
+    async def on_message(self, message: discord.Message):
+        if message.author.bot or not message.content.strip():
+            return
+
+        # Only respond in allowed channels (or threads within them)
+        channel_id = message.channel.id
+        parent_id = getattr(message.channel, "parent_id", None)
+        if channel_id not in self.allowed_channels and parent_id not in self.allowed_channels:
+            return
+
+        logger.info("Message from %s: %.100s", message.author, message.content)
+
+        async with message.channel.typing():
+            try:
+                answer = await asyncio.to_thread(
+                    ask_claude, self.anthropic_client, message.content
+                )
+            except anthropic.APIError as exc:
+                logger.error("Anthropic API error: %s", exc)
+                await message.reply("Sorry, I ran into an issue. Please try again.")
+                return
+
+        if len(answer) > 1900:
+            answer = answer[:1897] + "..."
+
+        await message.reply(answer)
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main():
+    if not DISCORD_BOT_TOKEN:
+        logger.error("DISCORD_BOT_TOKEN not set")
+        sys.exit(1)
+    if not ANTHROPIC_API_KEY:
+        logger.error("ANTHROPIC_API_KEY not set")
+        sys.exit(1)
+    if not DISCORD_CHANNEL_IDS:
+        logger.error("DISCORD_CHANNEL_IDS not set — add comma-separated channel IDs")
+        sys.exit(1)
+
+    allowed = parse_channel_ids(DISCORD_CHANNEL_IDS)
+    if not allowed:
+        logger.error("No valid channel IDs in DISCORD_CHANNEL_IDS=%r", DISCORD_CHANNEL_IDS)
+        sys.exit(1)
+
+    logger.info("Starting bot — model: %s, channels: %s", MODEL, allowed)
+
+    client = anthropic.Anthropic(api_key=ANTHROPIC_API_KEY)
+    bot = Bot(client, allowed)
+    bot.run(DISCORD_BOT_TOKEN, log_handler=None)
+
+
+if __name__ == "__main__":
+    main()
+`;
+const DISCORD_REQUIREMENTS = `discord.py>=2.3.0,<3.0.0
+anthropic>=0.40.0,<1.0.0
+`;
+const DISCORD_ENV_EXAMPLE = `# Required — get your bot token from https://discord.com/developers/applications
+DISCORD_BOT_TOKEN=
+
+# Required for local dev — auto-injected in production via supported_providers
+ANTHROPIC_API_KEY=
+
+# Required — comma-separated Discord channel IDs where the bot should respond
+DISCORD_CHANNEL_IDS=
+
+# Optional — customize the model and response length
+# MODEL=claude-sonnet-4-5-20250929
+# MAX_TOKENS=1024
+`;
 const SKILL_TEMPLATE = `---
 name: my-skill
 description: When to use this skill
@@ -264,9 +479,10 @@ function registerInitCommand(program) {
         .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')
+        .option('--template <name>', 'Start from a template (available: github-weekly-summary, discord)')
         .action(async (name, options) => {
         const cwd = process.cwd();
-        const runMode = (options.runMode || 'on_demand').trim().toLowerCase();
+        let runMode = (options.runMode || 'on_demand').trim().toLowerCase();
         if (!['on_demand', 'always_on'].includes(runMode)) {
             throw new errors_1.CliError("Invalid --run-mode. Use 'on_demand' or 'always_on'.");
         }
@@ -277,6 +493,26 @@ function registerInitCommand(program) {
             }
             initMode = { type: 'agent', flavor: 'orchestrator' };
         }
+        if (options.template) {
+            const template = options.template.trim().toLowerCase();
+            const validTemplates = ['discord', 'github-weekly-summary'];
+            if (!validTemplates.includes(template)) {
+                throw new errors_1.CliError(`Unknown --template '${template}'. Available templates: ${validTemplates.join(', ')}`);
+            }
+            if (options.orchestrator) {
+                throw new errors_1.CliError('Cannot use --template with --orchestrator.');
+            }
+            if (initMode.type === 'skill') {
+                throw new errors_1.CliError('Cannot use --template with --type skill.');
+            }
+            if (template === 'discord') {
+                initMode = { type: 'agent', flavor: 'discord' };
+                runMode = 'always_on';
+            }
+            else if (template === 'github-weekly-summary') {
+                initMode = { type: 'agent', flavor: 'github_weekly_summary' };
+            }
+        }
         // 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);
@@ -314,6 +550,61 @@ function registerInitCommand(program) {
             }
             return;
         }
+        // Handle github-weekly-summary template separately (own file set + output)
+        if (initMode.flavor === 'github_weekly_summary') {
+            const manifestPath = path_1.default.join(targetDir, 'orchagent.json');
+            // Check if already initialized
+            try {
+                await promises_1.default.access(manifestPath);
+                throw new errors_1.CliError(`Already initialized (orchagent.json exists in ${name ? name + '/' : 'current directory'})`);
+            }
+            catch (err) {
+                if (err.code !== 'ENOENT') {
+                    throw err;
+                }
+            }
+            const sub = (s) => s.replace(/\{\{name\}\}/g, agentName);
+            // Create prompts/ subdirectory
+            await promises_1.default.mkdir(path_1.default.join(targetDir, 'prompts'), { recursive: true });
+            // Write all files
+            await promises_1.default.writeFile(manifestPath, sub(github_weekly_summary_1.TEMPLATE_MANIFEST));
+            await promises_1.default.writeFile(path_1.default.join(targetDir, 'main.py'), github_weekly_summary_1.TEMPLATE_MAIN_PY);
+            await promises_1.default.writeFile(path_1.default.join(targetDir, 'config.py'), github_weekly_summary_1.TEMPLATE_CONFIG_PY);
+            await promises_1.default.writeFile(path_1.default.join(targetDir, 'github_fetcher.py'), github_weekly_summary_1.TEMPLATE_GITHUB_FETCHER_PY);
+            await promises_1.default.writeFile(path_1.default.join(targetDir, 'activity_store.py'), github_weekly_summary_1.TEMPLATE_ACTIVITY_STORE_PY);
+            await promises_1.default.writeFile(path_1.default.join(targetDir, 'analyst.py'), github_weekly_summary_1.TEMPLATE_ANALYST_PY);
+            await promises_1.default.writeFile(path_1.default.join(targetDir, 'models.py'), github_weekly_summary_1.TEMPLATE_MODELS_PY);
+            await promises_1.default.writeFile(path_1.default.join(targetDir, 'requirements.txt'), github_weekly_summary_1.TEMPLATE_REQUIREMENTS_TXT);
+            await promises_1.default.writeFile(path_1.default.join(targetDir, 'prompts', 'weekly_summary.md'), github_weekly_summary_1.TEMPLATE_WEEKLY_SUMMARY_PROMPT);
+            await promises_1.default.writeFile(path_1.default.join(targetDir, '.env.example'), sub(github_weekly_summary_1.TEMPLATE_ENV_EXAMPLE));
+            await promises_1.default.writeFile(path_1.default.join(targetDir, 'README.md'), sub(github_weekly_summary_1.TEMPLATE_README));
+            const prefix = name ? name + '/' : '';
+            process.stdout.write(`\nInitialized github-weekly-summary agent "${agentName}" in ${targetDir}\n`);
+            process.stdout.write(`\nFiles created:\n`);
+            process.stdout.write(`  ${prefix}orchagent.json            Agent manifest\n`);
+            process.stdout.write(`  ${prefix}main.py                   Entrypoint\n`);
+            process.stdout.write(`  ${prefix}config.py                 Config loader\n`);
+            process.stdout.write(`  ${prefix}github_fetcher.py         GitHub API client\n`);
+            process.stdout.write(`  ${prefix}activity_store.py         Stats computation\n`);
+            process.stdout.write(`  ${prefix}analyst.py                LLM summary generator\n`);
+            process.stdout.write(`  ${prefix}models.py                 Data models\n`);
+            process.stdout.write(`  ${prefix}requirements.txt          Python dependencies\n`);
+            process.stdout.write(`  ${prefix}prompts/weekly_summary.md LLM prompt template\n`);
+            process.stdout.write(`  ${prefix}.env.example              Secret reference\n`);
+            process.stdout.write(`  ${prefix}README.md                 Setup guide\n`);
+            process.stdout.write(`\nNext steps:\n`);
+            const s = name ? 2 : 1;
+            if (name) {
+                process.stdout.write(`  1. cd ${name}\n`);
+            }
+            process.stdout.write(`  ${s}. orch github connect                  Connect your GitHub account\n`);
+            process.stdout.write(`  ${s + 1}. orch publish                          Publish the agent\n`);
+            process.stdout.write(`  ${s + 2}. Add secrets in web dashboard          ORCHAGENT_API_KEY, DISCORD_WEBHOOK_URL, ANTHROPIC_API_KEY, GITHUB_REPOS\n`);
+            process.stdout.write(`  ${s + 3}. orch run <org>/${agentName}            Test it\n`);
+            process.stdout.write(`  ${s + 4}. orch schedule create <org>/${agentName} --cron "0 9 * * 1"   Schedule weekly\n`);
+            process.stdout.write(`\n  See README.md for full setup guide.\n`);
+            return;
+        }
         const manifestPath = path_1.default.join(targetDir, 'orchagent.json');
         const promptPath = path_1.default.join(targetDir, 'prompt.md');
         const schemaPath = path_1.default.join(targetDir, 'schema.json');
@@ -327,7 +618,7 @@ function registerInitCommand(program) {
                 throw err;
             }
         }
-        if (initMode.flavor !== 'code_runtime' && initMode.flavor !== 'orchestrator' && runMode === 'always_on') {
+        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.");
         }
         // Create manifest and type-specific files
@@ -353,6 +644,13 @@ function registerInitCommand(program) {
             manifest.loop = { max_turns: 25 };
             manifest.required_secrets = [];
         }
+        else if (initMode.flavor === 'discord') {
+            manifest.description = 'An always-on Discord bot powered by Claude';
+            manifest.runtime = { command: 'python main.py' };
+            manifest.supported_providers = ['anthropic'];
+            manifest.required_secrets = ['DISCORD_BOT_TOKEN', 'DISCORD_CHANNEL_IDS'];
+            manifest.tags = ['discord', 'always-on'];
+        }
         else if (initMode.flavor === 'code_runtime') {
             manifest.description = 'A code-runtime agent';
             manifest.runtime = { command: 'python main.py' };
@@ -366,6 +664,14 @@ function registerInitCommand(program) {
             await promises_1.default.writeFile(requirementsPath, ORCHESTRATOR_REQUIREMENTS);
             await promises_1.default.writeFile(schemaPath, AGENT_SCHEMA_TEMPLATE);
         }
+        else if (initMode.flavor === 'discord') {
+            const entrypointPath = path_1.default.join(targetDir, 'main.py');
+            const requirementsPath = path_1.default.join(targetDir, 'requirements.txt');
+            const envExamplePath = path_1.default.join(targetDir, '.env.example');
+            await promises_1.default.writeFile(entrypointPath, DISCORD_MAIN_PY);
+            await promises_1.default.writeFile(requirementsPath, DISCORD_REQUIREMENTS);
+            await promises_1.default.writeFile(envExamplePath, DISCORD_ENV_EXAMPLE);
+        }
         else if (initMode.flavor === 'code_runtime') {
             const entrypointPath = path_1.default.join(targetDir, 'main.py');
             await promises_1.default.writeFile(entrypointPath, CODE_TEMPLATE_PY);
@@ -390,16 +696,23 @@ function registerInitCommand(program) {
             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 === 'discord') {
+            process.stdout.write(`  ${prefix}main.py           - Discord bot (discord.py + Anthropic)\n`);
+            process.stdout.write(`  ${prefix}requirements.txt  - Python dependencies\n`);
+            process.stdout.write(`  ${prefix}.env.example      - Environment variables template\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}schema.json       - Input/output schemas\n`);
+        if (initMode.flavor !== 'discord') {
+            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 === 'orchestrator' ? 'code_runtime (orchestrator)' : initMode.flavor}\n`);
+        process.stdout.write(`  Execution: ${initMode.flavor === 'orchestrator' ? 'code_runtime (orchestrator)' : initMode.flavor === 'discord' ? 'code_runtime (discord)' : initMode.flavor}\n`);
         process.stdout.write(`\nNext steps:\n`);
         if (initMode.flavor === 'orchestrator') {
             const stepNum = name ? 2 : 1;
@@ -410,6 +723,17 @@ function registerInitCommand(program) {
             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 === 'discord') {
+            const stepNum = name ? 2 : 1;
+            if (name) {
+                process.stdout.write(`  1. cd ${name}\n`);
+            }
+            process.stdout.write(`  ${stepNum}. Create a Discord bot at https://discord.com/developers/applications\n`);
+            process.stdout.write(`  ${stepNum + 1}. Enable Message Content Intent in bot settings\n`);
+            process.stdout.write(`  ${stepNum + 2}. Copy .env.example to .env and fill in your tokens\n`);
+            process.stdout.write(`  ${stepNum + 3}. Test locally: pip install -r requirements.txt && python main.py\n`);
+            process.stdout.write(`  ${stepNum + 4}. Deploy: orch publish\n`);
+        }
         else if (initMode.flavor === 'code_runtime') {
             const stepNum = name ? 2 : 1;
             if (name) {

package/dist/commands/publish.js

@@ -753,6 +753,9 @@ function registerPublishCommand(program) {
             else if (effectiveSkills?.length) {
                 process.stderr.write(`  Skills:      ${effectiveSkills.join(', ')}\n`);
             }
+            if (manifest.required_secrets?.length) {
+                process.stderr.write(`  Secrets:     ${manifest.required_secrets.join(', ')}\n`);
+            }
             process.stderr.write(`\nWould publish: ${preview.org_slug}/${manifest.name}@${preview.next_version}\n`);
             if (shouldUploadBundle) {
                 const bundlePreview = await (0, bundle_1.previewBundle)(cwd, {
@@ -936,6 +939,18 @@ function registerPublishCommand(program) {
         process.stdout.write(`Callable: ${callable ? 'enabled' : 'disabled'}\n`);
         process.stdout.write(`Providers: ${supportedProviders.join(', ')}\n`);
         process.stdout.write(`Visibility: private\n`);
+        // Show required secrets with setup instructions (F-18)
+        if (manifest.required_secrets?.length) {
+            process.stdout.write(`\nRequired secrets:\n`);
+            for (const secret of manifest.required_secrets) {
+                process.stdout.write(`  ${secret}\n`);
+            }
+            process.stdout.write(`\nSet secrets before running:\n`);
+            for (const secret of manifest.required_secrets) {
+                process.stdout.write(`  orch secrets set ${secret} <value>\n`);
+            }
+            process.stdout.write(`\nView existing secrets: ${chalk_1.default.cyan('orch secrets list')}\n`);
+        }
         // Show security review result if available
         const secReview = result.security_review;
         if (secReview?.verdict) {

package/dist/commands/run.js

@@ -1624,6 +1624,38 @@ async function executeCloud(agentRef, file, options) {
         runtime: agentMeta.runtime ?? null,
         loop: agentMeta.loop ?? null,
     });
+    // Pre-flight: check required secrets before running (F-18)
+    // Only for sandbox-backed engines where secrets are injected as env vars
+    if (cloudEngine !== 'direct_llm') {
+        const agentRequiredSecrets = agentMeta.required_secrets;
+        if (agentRequiredSecrets?.length) {
+            try {
+                const wsSlug = configFile.workspace;
+                if (wsSlug) {
+                    const { workspaces } = await (0, api_1.request)(resolved, 'GET', '/workspaces');
+                    const ws = workspaces.find((w) => w.slug === wsSlug);
+                    if (ws) {
+                        const secretsResult = await (0, api_1.request)(resolved, 'GET', `/workspaces/${ws.id}/secrets`);
+                        const existingNames = new Set(secretsResult.secrets.map((s) => s.name));
+                        const missing = agentRequiredSecrets.filter((s) => !existingNames.has(s));
+                        if (missing.length > 0) {
+                            throw new errors_1.CliError(`Agent requires secrets not found in workspace '${wsSlug}':\n` +
+                                missing.map((s) => `  - ${s}`).join('\n') + '\n\n' +
+                                `Set them before running:\n` +
+                                missing.map((s) => `  orch secrets set ${s} <value>`).join('\n') + '\n\n' +
+                                `Secrets are injected as environment variables into the agent sandbox.\n` +
+                                `View existing secrets: orch secrets list`);
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                if (err instanceof errors_1.CliError)
+                    throw err;
+                // Non-fatal: gateway will catch missing secrets at execution time
+            }
+        }
+    }
     // Pre-call balance check for paid agents
     let pricingInfo;
     if ((0, pricing_1.isPaidAgent)(agentMeta)) {
@@ -1680,6 +1712,7 @@ async function executeCloud(agentRef, file, options) {
     const headers = {
         Authorization: `Bearer ${resolved.apiKey}`,
         'X-CLI-Version': package_json_1.default.version,
+        'X-OrchAgent-Client': 'cli',
     };
     if (options.tenant) {
         headers['X-OrchAgent-Tenant'] = options.tenant;
@@ -2022,6 +2055,37 @@ async function executeCloud(agentRef, file, options) {
                 `  - Contacting the agent author to increase the timeout` +
                 refSuffix);
         }
+        if (errorCode === 'MISSING_SECRETS') {
+            spinner?.fail('Missing workspace secrets');
+            // Extract secret names from gateway message:
+            // "Agent requires secret(s) not found in workspace: NAME1, NAME2. Add them in Settings > Secrets."
+            const secretNames = [];
+            if (message) {
+                const match = message.match(/not found in workspace:\s*(.+?)\./);
+                if (match) {
+                    secretNames.push(...match[1].split(',').map((s) => s.trim()).filter(Boolean));
+                }
+            }
+            let hint = '';
+            if (secretNames.length > 0) {
+                hint += `Missing secrets:\n`;
+                for (const name of secretNames) {
+                    hint += `  - ${name}\n`;
+                }
+                hint += `\nSet them with:\n`;
+                for (const name of secretNames) {
+                    hint += `  orch secrets set ${name} <value>\n`;
+                }
+            }
+            else {
+                hint += `${message}\n\n`;
+                hint += `Set missing secrets:\n`;
+                hint += `  orch secrets set <NAME> <value>\n`;
+            }
+            hint += `\nView existing secrets:\n`;
+            hint += `  orch secrets list`;
+            throw new errors_1.CliError(hint + refSuffix);
+        }
         if (response.status >= 500) {
             spinner?.fail(`Server error (${response.status})`);
             throw new errors_1.CliError(`${message}\n\n` +
@@ -2103,6 +2167,10 @@ async function executeCloud(agentRef, file, options) {
                     if (parts.length > 0) {
                         process.stderr.write(chalk_1.default.gray(`${parts.join(' · ')}\n`));
                     }
+                    const runId = response.headers?.get?.('x-run-id');
+                    if (runId) {
+                        process.stderr.write(chalk_1.default.gray(`View logs: orch logs ${runId}\n`));
+                    }
                 }
             }
         }
@@ -2191,6 +2259,10 @@ async function executeCloud(agentRef, file, options) {
             if (parts.length > 0) {
                 process.stderr.write(chalk_1.default.gray(`\n${parts.join(' · ')}\n`));
             }
+            const runId = response.headers?.get?.('x-run-id');
+            if (runId) {
+                process.stderr.write(chalk_1.default.gray(`View logs: orch logs ${runId}\n`));
+            }
         }
     }
 }