@opencomputer/cli 0.6.5 → 0.6.7

package/dist/commands.js

@@ -7,6 +7,12 @@ import { ensureProjectBinding, findOpenComputerProjectRoot, } from "./binding.js
 import { assertStarterTarget, buildAgentArtifact, findAgentRoot, initializeAgentProject, } from "./project.js";
 import { developmentAgentReference, parseSessionCommand, resolveProjectAgent, } from "./session-command.js";
 import { formatSessionEvent } from "./session-prompt.js";
+import { buildTemplateProject, normalizeTemplateRepositoryUrl, readTemplateManifest, templateDeployUrl, } from "./template.js";
+import { defaultTemplateDirectory, materializeTemplateCheckout, } from "./template-local.js";
+import { materializeProjectArchive } from "./project-local.js";
+import { createInterface } from "node:readline/promises";
+import { doctorProject } from "./doctor.js";
+import { CLIError } from "./errors.js";
 export function deploymentAlias(requestedAlias) {
     return requestedAlias ?? "development";
 }
@@ -16,6 +22,9 @@ export function shouldBindModelAccessProject(projectReference, currentAgentRoot)
 function printJSON(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
+function printJSONLine(value) {
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+}
 function flag(args, name) {
     const index = args.indexOf(name);
     if (index < 0)
@@ -56,15 +65,13 @@ function consumeModelAccessProvider(args) {
     }
     return "codex";
 }
-async function readSecretValue() {
+async function readTemplateSecretValue() {
     if (!process.stdin.isTTY) {
         const chunks = [];
         for await (const chunk of process.stdin) {
             chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
         }
-        const value = Buffer.concat(chunks)
-            .toString("utf8")
-            .replace(/\r?\n$/, "");
+        const value = Buffer.concat(chunks).toString("utf8").replace(/\r?\n$/, "");
         if (!value)
             throw new Error("Secret value was empty");
         return value;
@@ -101,7 +108,33 @@ async function readSecretValue() {
         process.stdin.on("data", onData);
     });
 }
-async function selectedProject(client, config, reference, interactive = true) {
+async function readStdinValue(enabled) {
+    if (!enabled) {
+        throw new CLIError("value_stdin_required", "A value must be supplied through standard input.", "Pipe the value into this command and add `--value-stdin`.");
+    }
+    if (process.stdin.isTTY) {
+        throw new CLIError("value_stdin_required", "--value-stdin requires piped standard input.", "Use `printf %s \"$VALUE\" | opencomputer ... --value-stdin`.");
+    }
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const value = Buffer.concat(chunks).toString("utf8").replace(/\r?\n$/, "");
+    if (!value)
+        throw new Error("Standard-input value was empty");
+    return value;
+}
+function printDoctor(result, json) {
+    if (json)
+        return printJSON(result);
+    for (const item of result.diagnostics) {
+        process.stdout.write(`${item.severity.toUpperCase()} ${item.code} ${item.file}${item.line ? `:${item.line}` : ""}\n` +
+            `  ${item.message}\n  fix: ${item.hint}\n`);
+    }
+    process.stdout.write(`${result.ok ? "Doctor passed" : "Doctor failed"}: ${result.summary.errors} errors, ` +
+        `${result.summary.warnings} warnings in ${result.durationMs}ms.\n`);
+}
+async function selectedProject(client, config, reference) {
     if (reference) {
         const project = (await client.projects()).find((candidate) => candidate.id === reference || candidate.slug === reference);
         if (!project)
@@ -112,9 +145,7 @@ async function selectedProject(client, config, reference, interactive = true) {
         return { projectId: project.id, agentId: agent.id };
     }
     const root = await findOpenComputerProjectRoot(process.cwd());
-    const binding = await ensureProjectBinding(client, config, root, {
-        interactive,
-    });
+    const binding = await ensureProjectBinding(client, config, root);
     return { projectId: binding.projectId, agentId: binding.agentId };
 }
 async function selectedSessionAgent(client, project, selector) {
@@ -200,7 +231,7 @@ function printAgentEvent(event, json) {
         printToolProgress(event);
     }
 }
-async function sendAgentTurn(client, sessionId, prompt, keep, json) {
+async function sendAgentTurn(client, sessionId, prompt, keep, json, idempotencyKey) {
     const existing = await client.events(sessionId, 0);
     let cursor = existing.at(-1)?.seq ?? 0;
     const session = await client.session(sessionId);
@@ -210,7 +241,7 @@ async function sendAgentTurn(client, sessionId, prompt, keep, json) {
         const connected = await waitForEvent(client, sessionId, cursor, (event) => event.type === "runtime.connected", () => undefined, 90_000);
         cursor = connected.cursor;
     }
-    const turn = await client.createTurn(sessionId, prompt);
+    const turn = await client.createTurn(sessionId, prompt, idempotencyKey);
     let streamedText = "";
     let completedText = "";
     const completed = await waitForEvent(client, sessionId, cursor, (event) => event.type === "turn.completed" || event.type === "turn.failed", (event) => {
@@ -274,6 +305,33 @@ async function attachSession(client, sessionId, json) {
         process.off("SIGINT", stop);
     }
 }
+async function tailSession(client, sessionId, after, follow, json) {
+    let cursor = after;
+    let stopped = false;
+    const stop = () => {
+        stopped = true;
+    };
+    process.once("SIGINT", stop);
+    try {
+        do {
+            const events = await client.events(sessionId, cursor);
+            for (const event of events) {
+                cursor = Math.max(cursor, event.seq);
+                if (json)
+                    printJSONLine({ sessionId, cursor: event.seq, ...event });
+                else {
+                    process.stdout.write(`${event.seq} ${event.type} ${JSON.stringify(event.data)}\n`);
+                }
+            }
+            if (follow && !stopped) {
+                await new Promise((resolve) => setTimeout(resolve, 500));
+            }
+        } while (follow && !stopped);
+    }
+    finally {
+        process.off("SIGINT", stop);
+    }
+}
 export function nextAgentEventDeadline(deadline, timeoutMs, receivedEvents, now = Date.now()) {
     return receivedEvents > 0 ? now + timeoutMs : deadline;
 }
@@ -301,11 +359,11 @@ async function waitForEvent(client, sessionId, after, terminal, onEvent, timeout
     }
     throw new Error("Timed out waiting for the agent.");
 }
-async function runAgent(client, agent, prompt, keep, json, verbose) {
+async function runAgent(client, agent, prompt, keep, json, verbose, idempotencyKey) {
     const created = await client.createSession(agent);
     process.stderr.write(`Starting ${agent}…\n`);
     const connected = await waitForEvent(client, created.session.id, 0, (event) => event.type === "runtime.connected", (event) => printSessionProgress(event, json, verbose), 90_000);
-    const turn = await client.createTurn(created.session.id, prompt);
+    const turn = await client.createTurn(created.session.id, prompt, idempotencyKey);
     let streamed = false;
     let streamedText = "";
     let completedText = "";
@@ -347,8 +405,224 @@ async function runAgent(client, agent, prompt, keep, json, verbose) {
 }
 export async function runCommand(command, rawArgs, globals) {
     const args = [...rawArgs];
+    if (command === "template" && args[0] === "validate") {
+        args.shift();
+        const repositoryUrl = option(args, "--repository-url");
+        const appUrl = option(args, "--app-url");
+        const directory = args.shift() ?? process.cwd();
+        if (args.length)
+            throw new Error(`Unexpected argument: ${args[0]}`);
+        const manifest = await readTemplateManifest(directory);
+        const deployUrl = repositoryUrl
+            ? templateDeployUrl(repositoryUrl, appUrl)
+            : undefined;
+        if (globals.json) {
+            printJSON({ file: "oc-template.toml", manifest, deployUrl });
+        }
+        else {
+            process.stdout.write(`Valid template: ${manifest.template.name}\n` +
+                (deployUrl ? `Deploy URL: ${deployUrl}\n` : ""));
+        }
+        return;
+    }
+    if (command === "template" && args[0] === "build") {
+        args.shift();
+        const output = option(args, "--output");
+        const directory = args.shift() ?? process.cwd();
+        if (args.length)
+            throw new Error(`Unexpected argument: ${args[0]}`);
+        const bundle = await buildTemplateProject(directory);
+        const serialized = `${JSON.stringify(bundle)}\n`;
+        if (output) {
+            const { writeFile } = await import("node:fs/promises");
+            await writeFile(output, serialized, { mode: 0o600 });
+            if (!globals.json)
+                process.stdout.write(`Built template bundle: ${output}\n`);
+        }
+        else {
+            process.stdout.write(serialized);
+        }
+        return;
+    }
     const config = await resolveConfig(globals);
-    const client = new OpenComputerClient(config);
+    const client = new OpenComputerClient(config, globals.idempotencyKey);
+    if (command === "project" && args[0] === "clone") {
+        args.shift();
+        const directory = option(args, "--directory");
+        const projectId = args.shift();
+        if (!projectId || args.length) {
+            throw new Error("Usage: opencomputer project clone <project-id> [--directory <path>]");
+        }
+        const project = (await client.projects()).find((candidate) => candidate.id === projectId);
+        if (!project)
+            throw new Error(`Project not found: ${projectId}`);
+        const checkout = await materializeProjectArchive({
+            response: await client.projectSourceArchive(project.id),
+            directory: directory ?? project.slug,
+        });
+        const binding = await ensureProjectBinding(client, config, checkout.directory, {
+            project: project.id,
+        });
+        if (globals.json)
+            printJSON({ checkout, binding });
+        else {
+            process.stdout.write(`Cloned ${binding.projectName} (${binding.projectId}).\n\n` +
+                `Next:\n  cd ${checkout.directory}\n  npm install\n` +
+                `  npm run deploy -- --watch --api-url ${config.apiUrl}\n`);
+        }
+        return;
+    }
+    if (command === "template") {
+        const action = args.shift();
+        if (action === "clone") {
+            const commitSha = option(args, "--commit");
+            const project = option(args, "--project");
+            const directory = option(args, "--directory");
+            const repositoryUrl = args.shift();
+            if (!repositoryUrl || !commitSha || !project || args.length) {
+                throw new Error("Usage: opencomputer template clone <repository-url> --commit <sha> --project <id> [--directory <path>]");
+            }
+            const normalized = normalizeTemplateRepositoryUrl(repositoryUrl);
+            const checkout = await materializeTemplateCheckout(normalized, commitSha, directory);
+            const binding = await ensureProjectBinding(client, config, checkout.directory, { project });
+            if (globals.json)
+                printJSON({ checkout, binding });
+            else {
+                process.stdout.write(`Cloned ${normalized}@${commitSha.slice(0, 12)}\n` +
+                    `Linked to ${binding.projectName} (${binding.projectId}).\n\n` +
+                    `Next:\n  cd ${checkout.directory}\n  npm install\n  npm run deploy -- --watch\n`);
+            }
+            return;
+        }
+        if (action !== "deploy") {
+            throw new Error("Usage: opencomputer template <deploy|clone> ...");
+        }
+        const projectNameOption = option(args, "--project-name");
+        const directoryOption = option(args, "--directory");
+        const confirmed = flag(args, "--yes");
+        const repositoryUrl = args.shift();
+        if (!repositoryUrl) {
+            throw new Error("A GitHub repository URL is required");
+        }
+        if (args.length)
+            throw new Error(`Unexpected argument: ${args[0]}`);
+        const inspection = await client.inspectTemplate(normalizeTemplateRepositoryUrl(repositoryUrl));
+        if (!globals.json) {
+            process.stdout.write(`\n${inspection.template.name}\n${inspection.template.description}\n` +
+                `Source: ${inspection.repository.fullName}@${inspection.repository.commitSha.slice(0, 12)}\n` +
+                `Agents: ${inspection.agents.map((agent) => agent.name).join(", ")}\n` +
+                `Target: Development\n\n`);
+        }
+        if (inspection.requirements.connections.length) {
+            throw new Error("This template needs an interactive provider connection. Open its deploy URL in the dashboard to continue.");
+        }
+        const requiredSecrets = inspection.requirements.secrets.filter((requirement) => requirement.required !== false);
+        if (!process.stdin.isTTY && requiredSecrets.length) {
+            throw new Error(`Secret ${requiredSecrets[0].name} requires an interactive terminal; secret values are never accepted as command-line arguments`);
+        }
+        if ((!process.stdin.isTTY || !process.stdout.isTTY) && !projectNameOption) {
+            throw new Error("--project-name is required in non-interactive mode");
+        }
+        const terminal = process.stdin.isTTY && process.stdout.isTTY
+            ? createInterface({ input: process.stdin, output: process.stdout })
+            : undefined;
+        let projectName = projectNameOption ??
+            inspection.template.defaultProjectName ??
+            inspection.template.name;
+        if (terminal && !projectNameOption) {
+            projectName =
+                (await terminal.question(`Project name [${projectName}]: `)).trim() ||
+                    projectName;
+        }
+        if (terminal && !confirmed) {
+            const answer = (await terminal.question("Create this Development project? [y/N] "))
+                .trim()
+                .toLowerCase();
+            if (answer !== "y" && answer !== "yes") {
+                terminal.close();
+                throw new Error("Template deployment cancelled");
+            }
+        }
+        const checkout = await materializeTemplateCheckout(inspection.repository.url, inspection.repository.commitSha, directoryOption ?? defaultTemplateDirectory(inspection.repository.url));
+        const runtimeValues = new Map();
+        for (const requirement of inspection.requirements.runtimeVariables) {
+            if (!terminal) {
+                if (requirement.required) {
+                    throw new Error(`Runtime variable ${requirement.name} requires an interactive terminal`);
+                }
+                continue;
+            }
+            const hint = requirement.example ? ` [${requirement.example}]` : "";
+            const value = (await terminal.question(`${requirement.name}${hint}: `)).trim() ||
+                requirement.example ||
+                "";
+            if (requirement.required && !value) {
+                terminal.close();
+                throw new Error(`${requirement.name} is required`);
+            }
+            if (value)
+                runtimeValues.set(requirement.name, value);
+        }
+        terminal?.close();
+        const installation = await client.createTemplateInstallation({
+            inspectionId: inspection.id,
+            projectName,
+            idempotencyKey: crypto.randomUUID(),
+        });
+        const installationAgentId = (localAgentId) => !localAgentId || localAgentId === inspection.agents[0]?.id
+            ? installation.projectAgentId
+            : `${installation.projectAgentId}--${localAgentId}`;
+        for (const requirement of requiredSecrets) {
+            process.stderr.write(`${requirement.name}\n`);
+            const value = await readTemplateSecretValue();
+            await client.putSecret({
+                projectId: installation.projectId,
+                name: requirement.name,
+                value,
+                environment: "development",
+                agentId: installationAgentId(requirement.agentId),
+                allowedOrigins: requirement.allowedOrigins,
+            });
+        }
+        for (const requirement of inspection.requirements.runtimeVariables) {
+            const value = runtimeValues.get(requirement.name);
+            if (!value)
+                continue;
+            await client.putRuntimeVariable({
+                projectId: installation.projectId,
+                name: requirement.name,
+                value,
+                environment: "development",
+                agentId: installationAgentId(requirement.agentId),
+            });
+        }
+        let current = await client.finalizeTemplateInstallation(installation.id);
+        const deadline = Date.now() + 10 * 60_000;
+        while (!["ready", "failed"].includes(current.state) &&
+            Date.now() < deadline) {
+            await new Promise((resolvePromise) => setTimeout(resolvePromise, 1_000));
+            current = await client.templateInstallation(current.id);
+            if (!globals.json)
+                process.stderr.write(`Template installation: ${current.state}\r`);
+        }
+        if (current.state === "failed") {
+            throw new Error(current.error?.message ?? "Template installation failed");
+        }
+        if (current.state !== "ready") {
+            throw new Error(`Template installation is still ${current.state}; ${current.projectUrl}`);
+        }
+        const binding = await ensureProjectBinding(client, config, checkout.directory, {
+            project: current.projectId,
+        });
+        if (globals.json)
+            printJSON({ installation: current, checkout, binding });
+        else {
+            process.stdout.write(`\nReady: ${current.projectUrl}\n` +
+                `Local: ${checkout.directory}\n\n` +
+                `Next:\n  cd ${checkout.directory}\n  npm install\n  npm run deploy -- --watch\n`);
+        }
+        return;
+    }
     if (command === "login") {
         const identity = await login(config, {
             noBrowser: flag(args, "--no-browser"),
@@ -409,7 +683,7 @@ export async function runCommand(command, rawArgs, globals) {
             const enterDirectory = directory === "." ? "" : `  cd ${directory}\n`;
             process.stdout.write(`Created the ${initialized.manifest.name} OpenComputer app\n` +
                 `Directory: ${initialized.root}\n` +
-                `Project:   choose or create one on the first watched deployment\n` +
+                `Project:   link explicitly with --project or --create-project\n` +
                 `Agents:    opencomputer/\n` +
                 (spa
                     ? `Web app:   src/ (separate lifecycle)\n\n`
@@ -442,13 +716,28 @@ export async function runCommand(command, rawArgs, globals) {
         }
         return;
     }
+    if (command === "doctor") {
+        if (args.length)
+            throw new Error(`Unexpected argument: ${args[0]}`);
+        const root = await findOpenComputerProjectRoot(process.cwd());
+        const result = await doctorProject(root);
+        if (!result.ok) {
+            if (!globals.json)
+                printDoctor(result, false);
+            throw new CLIError("doctor_failed", "Local project diagnostics failed.", "Fix the reported errors and rerun `opencomputer doctor --json`.", result);
+        }
+        printDoctor(result, globals.json);
+        return;
+    }
     if (command === "link") {
+        const project = option(args, "--project");
+        const createProjectName = option(args, "--create-project");
         if (args.length)
             throw new Error(`Unexpected argument: ${args[0]}`);
         const root = await findOpenComputerProjectRoot(process.cwd());
         const binding = await ensureProjectBinding(client, config, root, {
-            interactive: !globals.json,
-            select: true,
+            project,
+            createProjectName,
         });
         if (globals.json)
             printJSON(binding);
@@ -468,6 +757,10 @@ export async function runCommand(command, rawArgs, globals) {
         if (!root) {
             throw new Error("No OpenComputer project found. Run `opencomputer init <directory>` first.");
         }
+        const diagnosis = await doctorProject(root);
+        if (!diagnosis.ok) {
+            throw new CLIError("doctor_failed", "Deploy stopped because local project diagnostics failed.", "Run `opencomputer doctor --json`, fix the errors, and deploy again.", diagnosis);
+        }
         if (watch) {
             if (requestedAlias && requestedAlias !== "development") {
                 throw new Error("--watch deploys only to development; omit --alias or use --alias development");
@@ -475,7 +768,6 @@ export async function runCommand(command, rawArgs, globals) {
             await runDeploymentWatch(client, config, root, {
                 project,
                 createProjectName,
-                interactive: !globals.json,
             });
             return;
         }
@@ -483,10 +775,7 @@ export async function runCommand(command, rawArgs, globals) {
             throw new Error("--project and --create-project require --watch");
         }
         const alias = deploymentAlias(requestedAlias);
-        const binding = await ensureProjectBinding(client, config, root, {
-            interactive: !globals.json,
-            select: true,
-        });
+        const binding = await ensureProjectBinding(client, config, root);
         const results = await publishProjectDeployment(client, root, binding, alias);
         for (const { built } of results) {
             process.stderr.write(`Built ${built.agentId} in ${String(built.elapsedMs)}ms\n`);
@@ -509,7 +798,7 @@ export async function runCommand(command, rawArgs, globals) {
         if (!agent || !prompt) {
             throw new Error("Usage: opencomputer run <agent> <prompt>");
         }
-        const result = await runAgent(client, agent, prompt, keep, globals.json, globals.verbose === true);
+        const result = await runAgent(client, agent, prompt, keep, globals.json, globals.verbose === true, globals.idempotencyKey);
         if (globals.json)
             printJSON(result);
         return;
@@ -520,10 +809,14 @@ export async function runCommand(command, rawArgs, globals) {
         if (args.length)
             throw new Error(`Unexpected argument: ${args[0]}`);
         process.stderr.write("`opencomputer dev` is deprecated. Use `opencomputer deploy --watch`; start any web app separately.\n");
-        await runCloudDevelopment(client, config, await findOpenComputerProjectRoot(process.cwd()), {
+        const root = await findOpenComputerProjectRoot(process.cwd());
+        const diagnosis = await doctorProject(root);
+        if (!diagnosis.ok) {
+            throw new CLIError("doctor_failed", "Deploy stopped because local project diagnostics failed.", "Run `opencomputer doctor --json`, fix the errors, and deploy again.", diagnosis);
+        }
+        await runCloudDevelopment(client, config, root, {
             project,
             createProjectName,
-            interactive: !globals.json,
         });
         return;
     }
@@ -532,7 +825,7 @@ export async function runCommand(command, rawArgs, globals) {
         const projectReference = option(args, "--project");
         const agentOption = option(args, "--agent");
         const environment = environmentOption(option(args, "--environment"));
-        const project = await selectedProject(client, config, projectReference, !globals.json);
+        const project = await selectedProject(client, config, projectReference);
         const agentId = agentOption
             ? agentOption === "current"
                 ? project.agentId
@@ -565,6 +858,7 @@ export async function runCommand(command, rawArgs, globals) {
         }
         if (action === "set") {
             const explicitOrigins = options(args, "--allow-origin");
+            const valueStdin = flag(args, "--value-stdin");
             if (args.length)
                 throw new Error(`Unexpected argument: ${args[0]}`);
             let allowedOrigins = explicitOrigins;
@@ -584,7 +878,7 @@ export async function runCommand(command, rawArgs, globals) {
             const secret = await client.putSecret({
                 projectId: project.projectId,
                 name,
-                value: await readSecretValue(),
+                value: await readStdinValue(valueStdin),
                 environment,
                 ...(agentId ? { agentId } : {}),
                 allowedOrigins,
@@ -636,7 +930,7 @@ export async function runCommand(command, rawArgs, globals) {
                 throw new Error(`Unexpected argument: ${args[0]}`);
             const currentAgentRoot = projectReference ? null : await findAgentRoot();
             const project = shouldBindModelAccessProject(projectReference, currentAgentRoot)
-                ? await selectedProject(client, config, projectReference, false)
+                ? await selectedProject(client, config, projectReference)
                 : undefined;
             const environments = project
                 ? ["development", "production"]
@@ -709,7 +1003,7 @@ export async function runCommand(command, rawArgs, globals) {
         const projectReference = option(args, "--project");
         const agentOption = option(args, "--agent");
         const environment = environmentOption(option(args, "--environment"));
-        const project = await selectedProject(client, config, projectReference, !globals.json);
+        const project = await selectedProject(client, config, projectReference);
         const agentId = agentOption
             ? agentOption === "current"
                 ? project.agentId
@@ -740,12 +1034,13 @@ export async function runCommand(command, rawArgs, globals) {
             throw new Error("Use `opencomputer env set|list|remove <name>`.");
         }
         if (action === "set") {
+            const valueStdin = flag(args, "--value-stdin");
             if (args.length)
                 throw new Error(`Unexpected argument: ${args[0]}`);
             const variable = await client.putRuntimeVariable({
                 projectId: project.projectId,
                 name,
-                value: await readSecretValue(),
+                value: await readStdinValue(valueStdin),
                 environment,
                 ...(agentId ? { agentId } : {}),
             });
@@ -779,7 +1074,7 @@ export async function runCommand(command, rawArgs, globals) {
         const projectReference = option(args, "--project");
         const agentOption = option(args, "--agent");
         const environment = environmentOption(option(args, "--environment"));
-        const project = await selectedProject(client, config, projectReference, !globals.json);
+        const project = await selectedProject(client, config, projectReference);
         const agentId = await selectedSessionAgent(client, project, !agentOption || agentOption === "current" ? undefined : agentOption);
         if (action === "list") {
             if (args.length)
@@ -806,19 +1101,26 @@ export async function runCommand(command, rawArgs, globals) {
             if (!name || args.length) {
                 throw new Error("Use `opencomputer webhooks create <name>`.");
             }
-            const webhook = await client.createWebhook({
+            const existing = (await client.webhooks({
                 projectId: project.projectId,
-                name,
                 environment,
                 agentId,
-            });
+            })).find((candidate) => candidate.name === name);
+            const webhook = existing ??
+                (await client.createWebhook({
+                    projectId: project.projectId,
+                    name,
+                    environment,
+                    agentId,
+                }));
             if (globals.json)
-                printJSON(webhook);
+                printJSON({ ...webhook, reused: Boolean(existing) });
             else {
-                process.stdout.write(`Created ${webhook.name} (${webhook.id}) for ${agentId}@${environment}.\n` +
+                process.stdout.write(`${existing ? "Reused" : "Created"} ${webhook.name} (${webhook.id}) for ${agentId}@${environment}.\n` +
                     `URL: ${webhook.invocationUrl}\n` +
-                    `Token: ${webhook.token ?? "unavailable"}\n` +
-                    "Save this token now. It will not be shown again.\n");
+                    (existing
+                        ? "The existing token remains unchanged.\n"
+                        : `Token: ${webhook.token ?? "unavailable"}\nSave this token now. It will not be shown again.\n`));
             }
             return;
         }
@@ -886,7 +1188,7 @@ export async function runCommand(command, rawArgs, globals) {
                 insideProject = false;
             }
             if (insideProject) {
-                agentId = (await selectedProject(client, config, undefined, !globals.json)).agentId;
+                agentId = (await selectedProject(client, config)).agentId;
             }
         }
         let cursor = "";
@@ -916,7 +1218,50 @@ export async function runCommand(command, rawArgs, globals) {
         }
         return;
     }
-    if (command === "session") {
+    if (command === "channels") {
+        const action = args.shift();
+        if (action !== "status") {
+            throw new Error("Use `opencomputer channels status`.");
+        }
+        const projectReference = option(args, "--project");
+        const agentOption = option(args, "--agent");
+        const environment = environmentOption(option(args, "--environment"));
+        if (args.length)
+            throw new Error(`Unexpected argument: ${args[0]}`);
+        const project = await selectedProject(client, config, projectReference);
+        const agentId = await selectedSessionAgent(client, project, !agentOption || agentOption === "current" ? undefined : agentOption);
+        const channels = (await client.channels()).filter((channel) => channel.agentId === agentId && channel.alias === environment);
+        if (globals.json)
+            printJSON({ projectId: project.projectId, environment, channels });
+        else if (!channels.length)
+            process.stdout.write("No matching channels.\n");
+        else {
+            for (const channel of channels) {
+                process.stdout.write(`${channel.id} ${channel.status} ${channel.channel} ${channel.agentId}@${channel.alias}\n` +
+                    `  last event: ${channel.lastEventAt ?? "—"}\n` +
+                    `  last delivery: ${channel.lastDelivery ? `${channel.lastDelivery.status} at ${channel.lastDelivery.at}` : "—"}\n` +
+                    `  last error: ${channel.lastError ? `${channel.lastError.category} at ${channel.lastError.at}` : "—"}\n`);
+            }
+        }
+        return;
+    }
+    if (command === "session" || command === "sessions") {
+        if (args[0] === "tail") {
+            args.shift();
+            const sessionId = args.shift();
+            const afterValue = option(args, "--after");
+            const follow = !flag(args, "--no-follow");
+            if (!sessionId)
+                throw new Error("A session ID is required.");
+            if (args.length)
+                throw new Error(`Unexpected argument: ${args[0]}`);
+            const after = afterValue ? Number.parseInt(afterValue, 10) : 0;
+            if (!Number.isFinite(after) || after < 0) {
+                throw new Error("--after must be a non-negative event cursor");
+            }
+            await tailSession(client, sessionId, after, follow, globals.json);
+            return;
+        }
         const session = parseSessionCommand(args);
         const sessionArgs = session.args;
         if (session.action === "list") {
@@ -933,11 +1278,11 @@ export async function runCommand(command, rawArgs, globals) {
         }
         if (session.action === "create") {
             const prompt = sessionArgs.join(" ").trim();
-            const project = await selectedProject(client, config, undefined, !globals.json);
+            const project = await selectedProject(client, config, undefined);
             const agentId = await selectedSessionAgent(client, project, session.agent);
             const agent = developmentAgentReference(agentId);
             if (prompt) {
-                const result = await runAgent(client, agent, prompt, session.keep, globals.json, globals.verbose === true);
+                const result = await runAgent(client, agent, prompt, session.keep, globals.json, globals.verbose === true, globals.idempotencyKey);
                 if (globals.json)
                     printJSON(result);
                 return;
@@ -983,7 +1328,7 @@ export async function runCommand(command, rawArgs, globals) {
             const prompt = sessionArgs.join(" ").trim();
             if (!prompt)
                 throw new Error("A prompt is required.");
-            const result = await sendAgentTurn(client, sessionId, prompt, session.keep, globals.json);
+            const result = await sendAgentTurn(client, sessionId, prompt, session.keep, globals.json, globals.idempotencyKey);
             if (globals.json) {
                 printJSON({ sessionId, ...result, status: "completed" });
             }