@runtypelabs/cli 2.59.0 → 2.59.2

package/dist/chunk-DSRYhUus.js

@@ -0,0 +1,993 @@
+#!/usr/bin/env node
+import { t as isTTY } from "./index.js";
+import { ConfirmPrompt, DataList, EntityCard, MutationResult, React, render, useEffect, useState } from "./chunk-CoAWdSiE.js";
+import "./chunk-6uTxgdiY.js";
+import { r as createCliClient } from "./chunk-BW2fg46T.js";
+import { n as ensureAuth } from "./chunk-CJraEBVd.js";
+import { a as printJson, i as printDetail, n as buildListParams, r as getTotalCount, s as printNextCursorHint } from "./chunk-CcFCyqbB.js";
+import { taskCommand } from "./chunk-ZCTfmOs7.js";
+import { t as readJsonFile } from "./chunk-DGv7X9S_.js";
+import { n as addExecutionInputOptions, r as resolveExecutionInput, t as runExecution } from "./chunk-Cs4pwCQ-.js";
+import { f as writePulledDefinition, o as agentSkillsCommand } from "./chunk-BirUxTtH.js";
+import { r as describeAgentExportFailure, t as agentReleaseSelectorParams } from "./chunk-87nRnNRG.js";
+import { t as buildAgentVersionSelector } from "./chunk-BxNJgYbE.js";
+import { Command } from "commander";
+import chalk from "chalk";
+import * as fs$1 from "node:fs";
+import { writeFileSync } from "node:fs";
+import * as path$1 from "node:path";
+import { ENSURE_RELEASE_DEPLOY_CONFLICT_MESSAGE, RuntypeApiError, activateAgentPromotion, prepareAgentPromotion, validateAgentPromotion } from "@runtypelabs/sdk";
+// src/commands/agent-aliases.ts
+/** Print a failure the way every other CLI command does, then exit non-zero. */
+function fail$1(headline, error) {
+	const message = error instanceof Error ? error.message : String(error);
+	console.error(chalk.red(headline));
+	console.error(chalk.red(message));
+	process.exit(1);
+}
+function describeAlias(row) {
+	const version = row.versionNumber !== null ? `v${row.versionNumber}` : row.versionId;
+	const label = row.label ? ` ${row.label}` : "";
+	const archived = row.archivedAt ? chalk.gray(" [archived]") : "";
+	const expires = row.expiresAt ? chalk.gray(` expires ${row.expiresAt}`) : "";
+	return `  ${chalk.green(row.alias)} ${version}${label} ${chalk.gray(`rev ${row.revision}`)}${archived}${expires}`;
+}
+const agentAliasesCommand = new Command("aliases").description("Manage the release aliases that select which agent version runs");
+agentAliasesCommand.command("list <agentId>").description("List release aliases for an agent").option("--include-archived", "Include archived aliases, which never resolve for execution").option("--limit <n>", "Maximum aliases to return").option("--cursor <cursor>", "Pagination cursor from a previous page").option("--json", "Output as JSON").action(async (agentId, options) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	try {
+		const result = await client.agents.aliases.list(agentId, {
+			...options.includeArchived ? { includeArchived: true } : {},
+			...options.limit ? { limit: Number(options.limit) } : {},
+			...options.cursor ? { cursor: options.cursor } : {}
+		});
+		if (options.json) {
+			printJson(result);
+			return;
+		}
+		const rows = result.data ?? [];
+		if (rows.length === 0) {
+			console.log(chalk.gray("No release aliases found"));
+			return;
+		}
+		console.log(chalk.cyan(`Release aliases for agent ${agentId}:`));
+		for (const row of rows) console.log(describeAlias(row));
+		if (result.nextCursor) console.log(chalk.gray(`Next page: --cursor ${result.nextCursor}`));
+	} catch (error) {
+		fail$1("Failed to list release aliases", error);
+	}
+});
+agentAliasesCommand.command("get <agentId> <alias>").description("Get one release alias").option("--include-archived", "Resolve the alias even when it is archived").option("--json", "Output as JSON").action(async (agentId, alias, options) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	try {
+		const row = await client.agents.aliases.get(agentId, alias, { ...options.includeArchived ? { includeArchived: true } : {} });
+		if (options.json) {
+			printJson(row);
+			return;
+		}
+		printDetail("Release alias", [
+			{
+				label: "Alias",
+				value: row.alias
+			},
+			{
+				label: "Version",
+				value: row.versionId
+			},
+			{
+				label: "Version number",
+				value: row.versionNumber
+			},
+			{
+				label: "Label",
+				value: row.label
+			},
+			{
+				label: "Revision",
+				value: row.revision
+			},
+			{
+				label: "Content hash",
+				value: row.contentHash
+			},
+			{
+				label: "Expires",
+				value: row.expiresAt
+			},
+			{
+				label: "Archived",
+				value: row.archivedAt
+			}
+		]);
+	} catch (error) {
+		fail$1("Failed to fetch the release alias", error);
+	}
+});
+agentAliasesCommand.command("activate <agentId> <alias>").description("Activate a version at a release alias").requiredOption("--version-id <id>", "The exact version to aim the alias at").option("--revision <n>", "The alias revision you read, sent as If-Match. Required for live").option("--idempotency-key <key>", "Replay key so a retry does not deploy twice").option("--reason <text>", "Why this deployment happened, recorded on the receipt").option("--json", "Output as JSON").action(async (agentId, alias, options) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	try {
+		const result = await client.agents.aliases.activate(agentId, alias, {
+			versionId: options.versionId,
+			...options.revision ? { revision: Number(options.revision) } : {},
+			...options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {},
+			...options.reason ? { reason: options.reason } : {}
+		});
+		if (options.json) {
+			printJson(result);
+			return;
+		}
+		console.log(chalk.green(`${result.changed ? "Deployed" : "Already deployed"} ${result.versionId} at "${result.alias}" (revision ${result.revision})`));
+		console.log(chalk.gray(`Receipt ${result.receiptId}`));
+	} catch (error) {
+		fail$1("Failed to activate the release alias", error);
+	}
+});
+/**
+* `archive <agentId> <alias>` archives one pointer; `archive <alias> --all`
+* archives that name on every agent in the organization. The first positional
+* changes meaning with `--all`, which is what keeps the PR-close call a one-liner.
+*/
+async function archiveAliasEverywhere(alias, options) {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	try {
+		if (options.dryRun) {
+			const rows = (await client.agents.aliases.listByName(alias)).data ?? [];
+			if (options.json) {
+				printJson({
+					alias,
+					dryRun: true,
+					wouldArchive: rows
+				});
+				return;
+			}
+			if (rows.length === 0) {
+				console.log(chalk.gray(`No active "${alias}" aliases to archive`));
+				return;
+			}
+			console.log(chalk.cyan(`Would archive "${alias}" on ${rows.length} agent(s):`));
+			for (const row of rows) console.log(`  ${chalk.green(row.agentId)} ${row.agentName} ${chalk.gray(`rev ${row.revision}`)}`);
+			return;
+		}
+		const result = await client.agents.aliases.archiveEverywhere(alias);
+		if (options.json) printJson(result);
+		else {
+			for (const row of result.archived) console.log(chalk.green(`Archived "${alias}" on ${row.agentId} (${row.agentName})`));
+			for (const row of result.failed) console.error(chalk.red(`Failed on ${row.agentId} (${row.agentName}): ${row.error}`));
+			if (result.archived.length === 0 && result.failed.length === 0) console.log(chalk.gray(`No active "${alias}" aliases to archive`));
+		}
+		if (result.failed.length > 0) process.exit(1);
+	} catch (error) {
+		fail$1("Failed to archive the release alias", error);
+	}
+}
+agentAliasesCommand.command("archive <agentIdOrAlias> [alias]").description("Archive a preview alias so it stops resolving for new executions. With --all, the first argument is the alias name and it is archived on every agent in the organization.").option("--all", "Archive this alias name on every agent in the organization").option("--dry-run", "Report what would be archived and archive nothing").option("--revision <n>", "The alias revision you read, sent as If-Match").option("--json", "Output as JSON").action(async (agentIdOrAlias, alias, options) => {
+	if (options.all) {
+		if (alias !== void 0) {
+			console.error(chalk.red("With --all, pass only the alias name: runtype agents aliases archive <alias> --all"));
+			process.exit(1);
+		}
+		await archiveAliasEverywhere(agentIdOrAlias, options);
+		return;
+	}
+	if (alias === void 0) {
+		console.error(chalk.red("Pass an agent id and an alias, or an alias name with --all."));
+		process.exit(1);
+	}
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	try {
+		if (options.dryRun) {
+			const pointer = await client.agents.aliases.get(agentIdOrAlias, alias);
+			if (options.json) {
+				printJson({
+					agentId: agentIdOrAlias,
+					alias,
+					dryRun: true,
+					wouldArchive: pointer
+				});
+				return;
+			}
+			console.log(chalk.cyan(`Would archive "${pointer.alias}" on ${agentIdOrAlias} (revision ${pointer.revision})`));
+			return;
+		}
+		const result = await client.agents.aliases.archive(agentIdOrAlias, alias, { ...options.revision ? { revision: Number(options.revision) } : {} });
+		if (options.json) {
+			printJson(result);
+			return;
+		}
+		console.log(chalk.green(`Archived "${result.alias}" (revision ${result.revision})`));
+	} catch (error) {
+		fail$1("Failed to archive the release alias", error);
+	}
+});
+agentAliasesCommand.command("rollback <agentId> <alias>").description("Roll a release alias back to its previous version").option("--steps <n>", "How many pointer-moving receipts to walk back", "1").option("--revision <n>", "The alias revision you read, sent as If-Match. Required for live").option("--reason <text>", "Why this rollback happened, recorded on the receipt").option("--json", "Output as JSON").action(async (agentId, alias, options) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	try {
+		const result = await client.agents.aliases.rollback(agentId, alias, {
+			...options.steps ? { steps: Number(options.steps) } : {},
+			...options.revision ? { revision: Number(options.revision) } : {},
+			...options.reason ? { reason: options.reason } : {}
+		});
+		if (options.json) {
+			printJson(result);
+			return;
+		}
+		console.log(chalk.green(`Rolled "${result.alias}" back to ${result.versionId} (revision ${result.revision})`));
+		console.log(chalk.gray(`Receipt ${result.receiptId}`));
+	} catch (error) {
+		fail$1("Failed to roll the release alias back", error);
+	}
+});
+const agentDeploymentsCommand = new Command("deployments").description("Read the append-only deployment history of an agent");
+agentDeploymentsCommand.command("list <agentId>").description("List deployment receipts for an agent, newest first").option("--alias <name>", "Only receipts for this release alias").option("--limit <n>", "Maximum receipts to return").option("--cursor <cursor>", "Pagination cursor from a previous page").option("--json", "Output as JSON").action(async (agentId, options) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	try {
+		const result = await client.agents.deployments.list(agentId, {
+			...options.alias ? { alias: options.alias } : {},
+			...options.limit ? { limit: Number(options.limit) } : {},
+			...options.cursor ? { cursor: options.cursor } : {}
+		});
+		if (options.json) {
+			printJson(result);
+			return;
+		}
+		const rows = result.data ?? [];
+		if (rows.length === 0) {
+			console.log(chalk.gray("No deployment receipts found"));
+			return;
+		}
+		console.log(chalk.cyan(`Deployment history for agent ${agentId}:`));
+		for (const row of rows) {
+			const from = row.previousVersionId ? `${row.previousVersionId} -> ` : "";
+			console.log(`  ${chalk.green(row.alias)} ${row.action} ${from}${row.versionId} ${chalk.gray(`rev ${row.aliasRevision} ${row.createdAt}`)}`);
+		}
+	} catch (error) {
+		fail$1("Failed to list deployment receipts", error);
+	}
+});
+// src/commands/agent-ensure.ts
+/**
+* The activation the flags ask for. `release` and `deploy` are two spellings of
+* one thing, so supplying both is refused before any request is sent.
+*/
+function buildEnsureActivation(flags, bindings) {
+	if (flags.release !== void 0 && flags.deploy !== void 0) throw new Error(ENSURE_RELEASE_DEPLOY_CONFLICT_MESSAGE);
+	if (bindings !== void 0 && flags.deploy === void 0) throw new Error("--bindings-file sets per-alias secret bindings, so it needs --deploy <alias>.");
+	if (flags.deploy !== void 0) return { deploy: {
+		alias: flags.deploy,
+		...bindings !== void 0 ? { bindings } : {}
+	} };
+	if (flags.release !== void 0) return { release: flags.release };
+	return {};
+}
+/** The API refuses expectedRemoteHash on a preview deploy, since it guards live-row writes only. */
+function acceptsExpectedRemoteHash(deploy) {
+	return deploy === void 0 || deploy === "live";
+}
+/**
+* Parse a `--bindings-file` object of `{ SECRET_NAME: value }`. The whole object
+* replaces the alias's bindings, so `{}` clears them.
+*/
+function parseAliasBindings(file) {
+	const bindings = {};
+	for (const [name, value] of Object.entries(file)) {
+		if (typeof value !== "string") throw new Error(`Binding "${name}" must be a string secret value.`);
+		bindings[name] = value;
+	}
+	return bindings;
+}
+/** The file `agents ensure` reads back: the definition with its skills and capabilities at the top level. */
+function agentPullToDefinitionFile(pulled) {
+	return {
+		...pulled.definition,
+		...pulled.skills !== void 0 ? { skills: pulled.skills } : {},
+		...pulled.capabilities !== void 0 ? { capabilities: pulled.capabilities } : {}
+	};
+}
+/**
+* Lift a definition file's top-level `skills` (the agent's complete binding set)
+* out of the definition, which ensure hashes, and into the request.
+*/
+function splitDefinitionSkills(file) {
+	if (!("skills" in file)) return { definition: file };
+	const { skills, ...definition } = file;
+	if (!Array.isArray(skills)) throw new Error("\"skills\" must be an array of { name, version?, enabled? } bindings.");
+	return {
+		definition,
+		skills
+	};
+}
+/**
+* Lift a definition file's top-level `skills` and `capabilities` (each the agent's
+* complete set) out of the definition and into the request.
+*/
+function splitDefinitionAgentState(file) {
+	const { definition: withCapabilities, skills } = splitDefinitionSkills(file);
+	if (!("capabilities" in withCapabilities)) return {
+		definition: withCapabilities,
+		...skills !== void 0 ? { skills } : {}
+	};
+	const { capabilities, ...definition } = withCapabilities;
+	if (!Array.isArray(capabilities)) throw new Error("\"capabilities\" must be an array of { toolName, flow | agent | tool, description?, parametersSchema?, enabled? } entries.");
+	return {
+		definition,
+		...skills !== void 0 ? { skills } : {},
+		capabilities
+	};
+}
+function formatCapabilityChange(change) {
+	const target = change.kind && change.source ? ` (${change.kind}:${change.source})` : "";
+	return `  capability:${change.toolName} ${change.action}${target}`;
+}
+/**
+* Whether a dry-run plan drifts from the definition: content, skill bindings, capabilities, or,
+* when the flags ask for a deploy, the release pointer or its binding names (#9371).
+*/
+function ensurePlanHasDrift(result, activation) {
+	if (result.result !== "plan") return false;
+	if (result.changes !== "none") return true;
+	if ((result.skillBindings ?? []).some((b) => b.action !== "unchanged")) return true;
+	if ((result.capabilityChanges ?? []).some((c) => c.action !== "unchanged")) return true;
+	return (activation.deploy !== void 0 || activation.release === "publish") && (result.deployment?.changed === true || result.deployment?.bindingsChanged === true);
+}
+function formatSkillBinding(binding) {
+	const pin = binding.version === null ? "published" : `v${binding.version}`;
+	return `  skill:${binding.name} ${binding.action} (${pin})`;
+}
+const agentEnsureCommand = new Command("ensure").description("Converge an agent definition from a JSON file, optionally deploying it").argument("<file>", "Agent definition JSON file, or - to read from stdin").option("--deploy <alias>", "Activate the converged version at this release alias").option("--release <mode>", "Compatibility spelling of deploy: none or publish").option("--dry-run", "Plan without writing").option("--expect-no-changes", "Plan and exit 1 on any drift (the CI gate)").option("--overwrite-managed", "Converge even when the last write came from the dashboard").option("--label <text>", "Version label recorded on the version this converge appends").option("--notes <text>", "Version notes recorded on the version this converge appends").option("--expected-remote-hash <hash>", "Apply only if the remote still hashes to this value (the remoteHash a dry run printed)").option("--bindings-file <file>", "JSON object of { SECRET_NAME: value } bound to the --deploy alias (replaces the whole set)").option("--json", "Output as JSON").action(async (file, options) => {
+	if (options.release !== void 0 && !["none", "publish"].includes(options.release)) {
+		console.error(chalk.red("--release must be none or publish"));
+		process.exit(1);
+	}
+	let activation;
+	try {
+		activation = buildEnsureActivation(options, options.bindingsFile !== void 0 ? parseAliasBindings(readJsonFile(options.bindingsFile, { label: "alias bindings" })) : void 0);
+	} catch (error) {
+		console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+		process.exit(1);
+	}
+	let parsed;
+	try {
+		parsed = splitDefinitionAgentState(readJsonFile(file, {
+			label: "agent definition",
+			unwrapKey: "agent"
+		}));
+	} catch (error) {
+		console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+		process.exit(1);
+	}
+	const { definition, skills, capabilities } = parsed;
+	const name = definition.name;
+	if (typeof name !== "string" || name.length === 0) {
+		console.error(chalk.red("The agent definition needs a non-empty \"name\"."));
+		process.exit(1);
+	}
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	const dryRun = options.dryRun || options.expectNoChanges;
+	const version = options.label || options.notes ? {
+		...options.label ? { label: options.label } : {},
+		...options.notes ? { notes: options.notes } : {}
+	} : void 0;
+	try {
+		const result = await client.post("/agents/ensure", {
+			name,
+			definition,
+			...dryRun ? { dryRun: true } : {},
+			...options.overwriteManaged ? { onConflict: "overwrite" } : {},
+			...version ? { version } : {},
+			...options.expectedRemoteHash ? { expectedRemoteHash: options.expectedRemoteHash } : {},
+			...skills !== void 0 ? { skills } : {},
+			...capabilities !== void 0 ? { capabilities } : {},
+			...activation
+		});
+		if (options.json) printJson(result);
+		else if (result.result === "plan") {
+			console.log(chalk.cyan(`Plan for "${name}": ${result.changes}`));
+			for (const key of result.changedKeys ?? []) console.log(`  ${key}`);
+			if (result.remoteHash && acceptsExpectedRemoteHash(options.deploy)) console.log(chalk.gray(`Apply this plan with --expected-remote-hash ${result.remoteHash}`));
+		} else {
+			console.log(chalk.green(`Agent "${name}" ${result.result} (${result.agentId})`));
+			if (result.versionId) console.log(chalk.gray(`Version ${result.versionId}`));
+		}
+		const skillChanges = (result.skillBindings ?? []).filter((b) => b.action !== "unchanged");
+		const capabilityChanges = (result.capabilityChanges ?? []).filter((change) => change.action !== "unchanged");
+		if (!options.json) {
+			for (const binding of skillChanges) console.log(formatSkillBinding(binding));
+			for (const change of capabilityChanges) console.log(formatCapabilityChange(change));
+		}
+		if (result.deployment && !options.json) {
+			const { alias, versionId, revision, changed, bindingsChanged } = result.deployment;
+			const planned = result.result === "plan";
+			const verb = changed ? planned ? "Would deploy over" : "Deployed" : "Already deployed";
+			console.log(chalk.green(`${verb} ${versionId} at "${alias}" (revision ${revision})`));
+			if (planned && bindingsChanged) console.log(`  deploy:${alias} (bindings)`);
+			if (alias !== "live") console.log(chalk.gray("Live unchanged."));
+		}
+		if (!options.json) for (const warning of result._warnings ?? []) console.warn(chalk.yellow(`Warning: ${warning}`));
+		if (options.expectNoChanges && ensurePlanHasDrift(result, activation)) process.exit(1);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.error(chalk.red("Failed to converge the agent"));
+		console.error(chalk.red(message));
+		process.exit(1);
+	}
+});
+const agentPullCommand = new Command("pull").description("Print an agent as the definition file `agents ensure` reads (dashboard wins)").argument("<name>", "Agent name").option("-o, --out <file>", "Write the definition file here instead of stdout").option("--json", "Print the full pull response (definition, contentHash, provenance)").action(async (name, options) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	try {
+		const pulled = await client.get("/agents/pull", { name });
+		writePulledDefinition(options.json ? pulled : agentPullToDefinitionFile(pulled), {
+			out: options.out,
+			contentHash: pulled.contentHash,
+			warnings: pulled.warnings
+		});
+	} catch (error) {
+		console.error(chalk.red(`Failed to pull agent "${name}"`));
+		console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+		process.exit(1);
+	}
+});
+// src/commands/agent-promote.ts
+const DEFAULT_SOURCE_KEY_ENV = "RUNTYPE_SOURCE_API_KEY";
+const DEFAULT_TARGET_KEY_ENV = "RUNTYPE_TARGET_API_KEY";
+const DEFAULT_MANIFEST_PATH = "promotion.json";
+/** Print a failure the way every other CLI command does, then exit non-zero. */
+function fail(headline, error) {
+	const message = error instanceof Error ? error.message : String(error);
+	console.error(chalk.red(headline));
+	console.error(chalk.red(message));
+	process.exit(1);
+}
+/**
+* Read one organization's key out of the named environment variable. The key
+* itself is never a command-line argument, so it cannot leak into shell history
+* or a CI log of the invoked command.
+*/
+function readKeyFromEnv(variable, role, env = process.env) {
+	const value = env[variable];
+	if (!value) throw new Error(`No ${role} API key: set ${variable} in the environment, or point --${role}-key-env at the variable that holds it. Never pass a key on the command line.`);
+	return value;
+}
+function transports(options, env = process.env) {
+	const sourceKey = readKeyFromEnv(options.sourceKeyEnv ?? DEFAULT_SOURCE_KEY_ENV, "source", env);
+	const targetKey = readKeyFromEnv(options.targetKeyEnv ?? DEFAULT_TARGET_KEY_ENV, "target", env);
+	return {
+		source: createCliClient(sourceKey, options.sourceUrl),
+		target: createCliClient(targetKey, options.targetUrl)
+	};
+}
+/** The commit this promotion ran from, taken from CI rather than by shelling out. */
+function resolveCommit(explicit, env = process.env) {
+	return explicit || env.RUNTYPE_COMMIT || env.GITHUB_SHA || void 0;
+}
+function readManifest(path) {
+	return readJsonFile(path, { label: "promotion manifest" });
+}
+function addCredentialOptions(command) {
+	return command.option("--source-key-env <var>", "Environment variable holding the source organization API key", DEFAULT_SOURCE_KEY_ENV).option("--target-key-env <var>", "Environment variable holding the target organization API key", DEFAULT_TARGET_KEY_ENV).option("--source-url <url>", "API base URL for the source organization").option("--target-url <url>", "API base URL for the target organization");
+}
+const agentPromoteCommand = new Command("promote").description("Promote an agent between organizations: prepare, validate, evaluate, activate");
+addCredentialOptions(agentPromoteCommand.command("prepare <name>").description("Pull an agent definition from the source organization and stage it at a preview alias in the target. Live is never touched and credentials never move.").requiredOption("--alias <name>", "Preview alias to stage the candidate at. Never live").option("--commit <sha>", "Source-control commit, defaulting to RUNTYPE_COMMIT or GITHUB_SHA").option("--manifest <path>", "Where to write the promotion manifest", DEFAULT_MANIFEST_PATH).option("--json", "Output the manifest as JSON")).action(async (name, options) => {
+	try {
+		const { source, target } = transports(options);
+		const commit = resolveCommit(options.commit);
+		const manifest = await prepareAgentPromotion({
+			source,
+			target,
+			name,
+			alias: options.alias,
+			...commit ? { commit } : {}
+		});
+		writeFileSync(options.manifest, `${JSON.stringify(manifest, null, 2)}\n`);
+		if (options.json) {
+			printJson(manifest);
+			return;
+		}
+		console.log(chalk.green(`Staged ${manifest.target.versionId} at "${manifest.target.alias}" on agent ${manifest.target.agentId}`));
+		console.log(chalk.gray(`Live is unchanged. Manifest written to ${options.manifest}`));
+	} catch (error) {
+		fail("Failed to prepare the promotion", error);
+	}
+});
+addCredentialOptions(agentPromoteCommand.command("validate <manifest>").description("Re-plan the staged candidate in the target organization and report every named reference it could not resolve. Exits 1 when any reference is unresolved.").option("--json", "Output the validation result as JSON")).action(async (manifestPath, options) => {
+	try {
+		const manifest = readManifest(manifestPath);
+		const { source, target } = transports(options);
+		const validation = await validateAgentPromotion({
+			source,
+			target,
+			manifest
+		});
+		if (options.json) printJson(validation);
+		else {
+			console.log(chalk.cyan(`Plan for "${manifest.name}" in the target organization: ${validation.plan.changes}`));
+			for (const ref of validation.refs) {
+				const mark = ref.resolvedId ? chalk.green("resolved") : chalk.red("unresolved");
+				console.log(`  ${mark} ${ref.ref}${ref.resolvedId ? ` -> ${ref.resolvedId}` : ""}`);
+			}
+			if (validation.ok) console.log(chalk.green("Every named reference resolves in the target organization."));
+			else console.error(chalk.red(`Unresolved in the target organization: ${validation.unresolvedRefs.join(", ")}`));
+		}
+		if (!validation.ok) process.exit(1);
+	} catch (error) {
+		fail("Failed to validate the promotion", error);
+	}
+});
+addCredentialOptions(agentPromoteCommand.command("evaluate <manifest>").description("Run an eval suite in the target organization pinned to the staged version. Reports the result; nothing gates activation on it.").requiredOption("--suite <id>", "Eval suite in the target organization to run").option("--json", "Output the run summary as JSON")).action(async (manifestPath, options) => {
+	let passed = true;
+	try {
+		const manifest = readManifest(manifestPath);
+		const targetKey = readKeyFromEnv(options.targetKeyEnv ?? DEFAULT_TARGET_KEY_ENV, "target");
+		const result = await createCliClient(targetKey, options.targetUrl).post(`/eval/suites/${options.suite}/run`, { agent: { versionId: manifest.target.versionId } });
+		passed = result.passed !== false;
+		if (options.json) printJson(result);
+		else {
+			console.log(chalk.cyan(`Suite ${options.suite} ran against ${manifest.target.versionId}: ${passed ? "passed" : "failed"}`));
+			if (result.runId) console.log(chalk.gray(`Run ${result.runId}`));
+			console.log(chalk.gray("Reporting only: activation is never gated on this result (ADR 0025)."));
+		}
+	} catch (error) {
+		fail("Failed to evaluate the promotion", error);
+	}
+	if (!passed) process.exit(1);
+});
+addCredentialOptions(agentPromoteCommand.command("activate <manifest>").description("Deploy the exact staged version at the target organization pointer, quoting its revision and linking the source ids on the receipt.").option("--alias <name>", "Pointer to deploy to in the target organization", "live").option("--reason <text>", "Why this deployment happened, recorded on the receipt").option("--idempotency-key <key>", "Replay key, defaulting to one derived from the manifest").option("--json", "Output the activation result as JSON")).action(async (manifestPath, options) => {
+	try {
+		const manifest = readManifest(manifestPath);
+		const targetKey = readKeyFromEnv(options.targetKeyEnv ?? DEFAULT_TARGET_KEY_ENV, "target");
+		const target = createCliClient(targetKey, options.targetUrl);
+		const result = await activateAgentPromotion({
+			target,
+			manifest,
+			alias: options.alias,
+			...options.reason ? { reason: options.reason } : {},
+			...options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}
+		});
+		if (options.json) {
+			printJson(result);
+			return;
+		}
+		console.log(chalk.green(`${result.changed ? "Deployed" : "Already deployed"} ${result.versionId} at "${result.alias}" (revision ${result.revision})`));
+		console.log(chalk.gray(`Receipt ${result.receiptId}`));
+	} catch (error) {
+		fail("Failed to activate the promotion", error);
+	}
+});
+// src/commands/agent-export-runtime.ts
+const agentExportRuntimeCommand = new Command("export-runtime").description("Export an agent for @runtypelabs/runtime, as JSON or as a vendorable bundle zip").argument("<id>", "Agent ID").option("--alias <name>", "Export the version the agent's release alias points at").option("--version-id <id>", "Export this published agent version").option("--format <format>", "json (the definition) or bundle (definition + prebuilt runtime zip)", "json").option("--output <path>", "Write to this file (bundle default: the server-provided file name)").action(async (id, options) => {
+	if (options.format !== "json" && options.format !== "bundle") {
+		console.error(chalk.red(`Error: unknown --format "${options.format}". Must be json or bundle.`));
+		process.exit(1);
+	}
+	const selector = agentReleaseSelectorParams(options, 1);
+	if ("error" in selector) {
+		console.error(chalk.red(`Error: ${selector.error}`));
+		process.exit(1);
+	}
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	try {
+		if (options.format === "json") {
+			const exported = await client.agents.exportRuntime(id, selector.params);
+			const body = `${JSON.stringify(exported, null, 2)}\n`;
+			if (options.output) fs$1.writeFileSync(path$1.resolve(options.output), body);
+			else process.stdout.write(body);
+			return;
+		}
+		const bundle = await client.agents.exportRuntimeBundle(id, selector.params);
+		const outPath = path$1.resolve(options.output ?? bundle.fileName);
+		fs$1.writeFileSync(outPath, bundle.bytes);
+		console.log(JSON.stringify({
+			path: outPath,
+			bytes: bundle.bytes.byteLength,
+			contentHash: bundle.contentHash,
+			runtimeVersion: bundle.runtimeVersion,
+			runtimeCommit: bundle.runtimeCommit
+		}, null, 2));
+	} catch (err) {
+		const message = err instanceof RuntypeApiError ? err.message : String(err);
+		console.error(chalk.red(`Failed to export agent ${id}: ${message}`));
+		for (const hint of describeAgentExportFailure(err)) console.error(chalk.yellow(`  ${hint}`));
+		process.exit(1);
+	}
+});
+// src/commands/agents.ts
+const agentsCommand = new Command("agents").description("Manage agents");
+agentsCommand.addCommand(taskCommand);
+agentsCommand.addCommand(agentAliasesCommand);
+agentsCommand.addCommand(agentDeploymentsCommand);
+agentsCommand.addCommand(agentEnsureCommand);
+agentsCommand.addCommand(agentPullCommand);
+agentsCommand.addCommand(agentSkillsCommand);
+agentsCommand.addCommand(agentPromoteCommand);
+agentsCommand.addCommand(agentExportRuntimeCommand);
+agentsCommand.command("list").description("List all agents").option("--json", "Output as JSON").option("--limit <n>", "Limit results", "20").option("--cursor <cursor>", "Pagination cursor for the next page").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(async (options) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	const params = buildListParams(options);
+	if (!isTTY(options) || options.json) {
+		try {
+			const data = await client.get("/agents", params);
+			if (options.json) {
+				printJson(data);
+				return;
+			}
+			const agents = data.data ?? [];
+			if (agents.length === 0) {
+				console.log("No agents found");
+				return;
+			}
+			console.log("Your Agents:");
+			for (const agent of agents) {
+				const desc = agent.description ? ` - ${agent.description}` : "";
+				console.log(`  ${agent.id} ${agent.name}${desc}`);
+			}
+			const total = getTotalCount(data.pagination);
+			if (total !== void 0) console.log(`\n  Total: ${total} agents`);
+			printNextCursorHint("runtype agents list", data.pagination);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "Unknown error";
+			console.error(chalk.red(`Failed to fetch agents: ${message}`));
+			process.exit(1);
+		}
+		return;
+	}
+	const App = () => {
+		const [items, setItems] = useState(null);
+		const [error, setError] = useState(null);
+		const [total, setTotal] = useState();
+		useEffect(() => {
+			client.get("/agents", params).then((res) => {
+				setItems(res.data ?? []);
+				setTotal(getTotalCount(res.pagination));
+			}).catch((err) => setError(err instanceof Error ? err : new Error(String(err))));
+		}, []);
+		return React.createElement(DataList, {
+			title: "Your Agents",
+			items,
+			error,
+			loading: items === null && error === null,
+			total,
+			renderCard: (item) => {
+				const agent = item;
+				return React.createElement(EntityCard, { fields: [
+					{
+						label: "ID",
+						value: agent.id,
+						color: "green"
+					},
+					{
+						label: "Name",
+						value: agent.name
+					},
+					{
+						label: "Description",
+						value: agent.description,
+						color: "gray"
+					},
+					{
+						label: "Model",
+						value: agent.model,
+						color: "blue"
+					}
+				] });
+			},
+			emptyMessage: "No agents found"
+		});
+	};
+	const { waitUntilExit } = render(React.createElement(App));
+	await waitUntilExit();
+});
+agentsCommand.command("get <id>").description("Get agent details").option("--json", "Output as JSON").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(async (id, options) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	if (!isTTY(options) || options.json) {
+		try {
+			const data = await client.get(`/agents/${id}`);
+			if (options.json) {
+				printJson(data);
+				return;
+			}
+			printDetail("Agent", [
+				{
+					label: "ID",
+					value: data.id
+				},
+				{
+					label: "Name",
+					value: data.name
+				},
+				{
+					label: "Description",
+					value: data.description
+				},
+				{
+					label: "Status",
+					value: data.status
+				},
+				{
+					label: "Model",
+					value: data.model
+				}
+			]);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "Unknown error";
+			console.error(chalk.red(`Failed to fetch agent: ${message}`));
+			process.exit(1);
+		}
+		return;
+	}
+	const App = () => {
+		const [items, setItems] = useState(null);
+		const [error, setError] = useState(null);
+		useEffect(() => {
+			client.get(`/agents/${id}`).then((res) => setItems([res])).catch((err) => setError(err instanceof Error ? err : new Error(String(err))));
+		}, []);
+		return React.createElement(DataList, {
+			title: "Agent",
+			items,
+			error,
+			loading: items === null && error === null,
+			renderCard: (item) => {
+				const agent = item;
+				return React.createElement(EntityCard, { fields: [
+					{
+						label: "ID",
+						value: agent.id,
+						color: "green"
+					},
+					{
+						label: "Name",
+						value: agent.name
+					},
+					{
+						label: "Description",
+						value: agent.description
+					},
+					{
+						label: "Model",
+						value: agent.model,
+						color: "blue"
+					},
+					{
+						label: "Capabilities",
+						value: agent.capabilities?.length
+					}
+				] });
+			}
+		});
+	};
+	const { waitUntilExit } = render(React.createElement(App));
+	await waitUntilExit();
+});
+agentsCommand.command("create").description("Create a new agent").requiredOption("-n, --name <name>", "Agent name").option("-d, --description <desc>", "Agent description").option("--json", "Output as JSON").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(async (options) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	if (!isTTY(options) || options.json) {
+		try {
+			const data = await client.post("/agents", {
+				name: options.name,
+				description: options.description
+			});
+			if (options.json) {
+				printJson(data);
+				return;
+			}
+			console.log(`  ID: ${data.id}`);
+			console.log(`  Name: ${data.name}`);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "Unknown error";
+			console.error(chalk.red(`Failed to create agent: ${message}`));
+			process.exit(1);
+		}
+		return;
+	}
+	const App = () => {
+		const [loading, setLoading] = useState(true);
+		const [success, setSuccess] = useState(null);
+		const [error, setError] = useState(null);
+		const [result, setResult] = useState(null);
+		useEffect(() => {
+			client.post("/agents", {
+				name: options.name,
+				description: options.description
+			}).then((data) => {
+				setResult(data);
+				setSuccess(true);
+				setLoading(false);
+			}).catch((err) => {
+				setError(err instanceof Error ? err : new Error(String(err)));
+				setSuccess(false);
+				setLoading(false);
+			});
+		}, []);
+		return React.createElement(MutationResult, {
+			loading,
+			loadingLabel: "Creating agent...",
+			success,
+			successMessage: "Agent created",
+			error,
+			result: result ? React.createElement(EntityCard, { fields: [{
+				label: "ID",
+				value: result.id,
+				color: "green"
+			}, {
+				label: "Name",
+				value: result.name
+			}] }) : void 0
+		});
+	};
+	const { waitUntilExit } = render(React.createElement(App));
+	await waitUntilExit();
+});
+agentsCommand.command("update <id>").description("Update an agent").option("-n, --name <name>", "New agent name").option("-d, --description <desc>", "New agent description").option("--from-file <file>", "Update agent from JSON file (full body)").option("--json", "Output as JSON").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(async (id, options) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	let body = {};
+	if (options.fromFile) body = readJsonFile(options.fromFile, {
+		label: "agent file",
+		unwrapKey: "agent"
+	});
+	if (options.name !== void 0) body.name = options.name;
+	if (options.description !== void 0) body.description = options.description;
+	if (Object.keys(body).length === 0) {
+		console.error(chalk.red("Error: provide at least one of --name, --description, or --from-file"));
+		process.exit(1);
+	}
+	if (!isTTY(options) || options.json) {
+		try {
+			const data = await client.put(`/agents/${id}`, body);
+			if (options.json) {
+				printJson(data);
+				return;
+			}
+			console.log(chalk.green("Agent updated"));
+			console.log(`  ID: ${chalk.green(data.id)}`);
+			console.log(`  Name: ${data.name}`);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "Unknown error";
+			console.error(chalk.red(`Failed to update agent: ${message}`));
+			process.exit(1);
+		}
+		return;
+	}
+	const App = () => {
+		const [loading, setLoading] = useState(true);
+		const [success, setSuccess] = useState(null);
+		const [error, setError] = useState(null);
+		const [result, setResult] = useState(null);
+		useEffect(() => {
+			client.put(`/agents/${id}`, body).then((data) => {
+				setResult(data);
+				setSuccess(true);
+				setLoading(false);
+			}).catch((err) => {
+				setError(err instanceof Error ? err : new Error(String(err)));
+				setSuccess(false);
+				setLoading(false);
+			});
+		}, []);
+		return React.createElement(MutationResult, {
+			loading,
+			loadingLabel: "Updating agent...",
+			success,
+			successMessage: "Agent updated",
+			error,
+			result: result ? React.createElement(EntityCard, { fields: [{
+				label: "ID",
+				value: result.id,
+				color: "green"
+			}, {
+				label: "Name",
+				value: result.name
+			}] }) : void 0
+		});
+	};
+	const { waitUntilExit } = render(React.createElement(App));
+	await waitUntilExit();
+});
+agentsCommand.command("delete <id>").description("Delete an agent").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(async (id, options) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	if (!isTTY(options)) {
+		try {
+			await client.agents.delete(id);
+			console.log(JSON.stringify({
+				status: "deleted",
+				id
+			}, null, 2));
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "Unknown error";
+			console.error(chalk.red(`Failed to delete agent: ${message}`));
+			process.exit(1);
+		}
+		return;
+	}
+	const App = () => {
+		const [confirmed, setConfirmed] = useState(null);
+		const [loading, setLoading] = useState(false);
+		const [success, setSuccess] = useState(null);
+		const [error, setError] = useState(null);
+		useEffect(() => {
+			if (confirmed !== true) return void 0;
+			setLoading(true);
+			client.delete(`/agents/${id}`).then(() => {
+				setSuccess(true);
+				setLoading(false);
+			}).catch((err) => {
+				setError(err instanceof Error ? err : new Error(String(err)));
+				setSuccess(false);
+				setLoading(false);
+			});
+		}, [confirmed]);
+		if (confirmed === null) return React.createElement(ConfirmPrompt, {
+			message: `Delete agent ${id}?`,
+			onConfirm: (val) => setConfirmed(val)
+		});
+		if (confirmed === false) return React.createElement(MutationResult, {
+			loading: false,
+			success: true,
+			successMessage: "Cancelled",
+			error: null
+		});
+		return React.createElement(MutationResult, {
+			loading,
+			loadingLabel: "Deleting agent...",
+			success,
+			successMessage: "Agent deleted",
+			error
+		});
+	};
+	const { waitUntilExit } = render(React.createElement(App));
+	await waitUntilExit();
+});
+addExecutionInputOptions(agentsCommand.command("execute <id>").description("Execute an agent").option("-m, --message <text>", "Message to send").option("--stream", "Stream the response (default)", true).option("--no-stream", "Wait for complete response").option("--alias <name>", "Run whichever version this release alias points at").option("--version-id <id>", "Run this exact version snapshot").option("--json", "Output one final JSON result").option("--jsonl", "Output stream events and a terminal execution_summary as JSON lines")).action(async (id, options) => {
+	const hasInputs = options.inputs !== void 0 || options.inputsFile !== void 0 || !!options.variable?.length;
+	await runExecution(options, () => {
+		if (hasInputs) {
+			const input = resolveExecutionInput(options);
+			if (!input.messages?.length) throw new Error("Either --message or --messages-file is required");
+			const selector = buildAgentVersionSelector(options);
+			return {
+				...input,
+				agent: {
+					agentId: id,
+					...selector ?? {}
+				}
+			};
+		}
+		const { messages } = resolveExecutionInput(options, true);
+		return {
+			messages,
+			...buildAgentVersionSelector(options) ?? {}
+		};
+	}, (client, payload) => {
+		if (hasInputs) return options.stream ? client.dispatch.executeStream(payload) : client.dispatch.execute(payload);
+		return options.stream ? client.agents.executeStream(id, payload) : client.agents.execute(id, payload);
+	}, "agent");
+});
+export { agentsCommand };
+