@runtypelabs/cli 2.44.1 → 2.45.0

package/README.md

@@ -644,6 +644,7 @@ Manage agents.
 | `agents execute <id> -m <message>` | Execute an agent with a message                 |
 | `agents task <agent> -g <goal>`    | Run a multi-session task (see Marathon section) |
 | `agents ensure <file>`             | Converge a definition from a file               |
+| `agents pull <name>`               | Print the definition file `ensure` reads        |
 | `agents delete <id>`               | Delete an agent                                 |
 
 `agents execute` and `dispatch --agent` take `--alias <name>` or `--version-id <id>`
@@ -677,7 +678,48 @@ runtype agents aliases activate agent_abc live --version-id agentver_9 --revisio
 
 `agents ensure <file> --deploy <alias>` saves and activates in one step;
 `--release publish|none` is the older spelling of the same thing, and supplying both
-is refused. A non-live deploy leaves live unchanged.
+is refused. A non-live deploy leaves live unchanged. `--bindings-file <file>` (a JSON
+object of `{ SECRET_NAME: value }`) replaces the secret bindings of the `--deploy`
+alias; `{}` clears them. Keep that file out of version control.
+
+### Config as code: `ensure` and `pull`
+
+Each entity the TypeScript SDK converges has an `ensure` and a `pull` subcommand.
+`pull` prints the definition file that `ensure` reads (stdout, or `-o <file>`), so
+`runtype flows pull "Triage" > flows/triage.json` absorbs a dashboard edit into the repo.
+
+| Command                                       | Definition file                |
+| --------------------------------------------- | ------------------------------ |
+| `agents ensure` / `agents pull`               | `defineAgent` input + `skills` |
+| `agents skills ensure` / `agents skills pull` | `defineSkill` input            |
+| `flows ensure` / `flows pull`                 | `defineFlow` input             |
+| `tools ensure` / `tools pull`                 | `defineTool` input             |
+| `products ensure` / `products pull`           | `defineProduct` input          |
+| `surfaces ensure` / `surfaces pull --product` | `defineSurface` input          |
+| `products ensure-fpo` / `products pull-fpo`   | Full Product Object            |
+
+`agents skills` manages Runtype Agent Skills, the context bundles deployed agents
+load. `runtype skills` installs skills into local coding agents; it is unrelated.
+
+Every `ensure` takes `--dry-run`, `--expect-no-changes` (exit 1 on drift, for CI),
+`--overwrite-managed` (converge over a dashboard edit) and
+`--expected-remote-hash <hash>`. A dry run prints the remote hash; pass it to the
+apply so the write is refused if someone changed the entity in between:
+
+```bash
+runtype flows ensure flows/triage.json --dry-run
+runtype flows ensure flows/triage.json --expected-remote-hash <remoteHash>
+```
+
+Agents, skills and flows also take `--release none|publish` (agents: `--deploy`) and
+`--label` / `--notes`, which stamp provenance such as a git SHA on the appended
+version. `products ensure-fpo` also takes `--prune`, which removes product-scoped
+capabilities and surfaces the FPO no longer declares, and `--hash-probe`, which
+skips the upload when the live product already matches (useful for a pulled FPO).
+
+`client-tokens ensure <file>` converges a client token by name (`--dry-run`,
+`--expect-no-changes`, `--json`). It has no `pull`, and it never deletes or
+regenerates a token.
 
 ##### Cleaning up a pull request's preview
 

package/dist/index.js

@@ -11,7 +11,7 @@ import { Box, Text, render, useApp, useInput, useStdout } from "ink";
 import open from "open";
 import crypto$1 from "crypto";
 import express from "express";
-import { AgentAliasPreviewLimitError, DEFAULT_STALL_STOP_AFTER, ENSURE_RELEASE_DEPLOY_CONFLICT_MESSAGE, LEDGER_ARTIFACT_LINE_PREFIX, RuntypeApiError, RuntypeClient, activateAgentPromotion, buildLedgerOffloadReference, compileWorkflowConfig, createClient, defaultWorkflow, deployWorkflow, ensureDefaultWorkflowHooks, evaluateGeneratedRuntimeToolProposal, gameWorkflow, getDefaultPlanPath, isBuiltinToolExecuteResponse, isWorkflowHookRef, parseFinalBuffer, parseLedgerArtifactRelativePath, parseOffloadedOutputId, parseSSEChunk, prepareAgentPromotion, processStream, registerWorkflowHook, validateAgentPromotion } from "@runtypelabs/sdk";
+import { AgentAliasPreviewLimitError, ClientTokensNamespace, DEFAULT_STALL_STOP_AFTER, ENSURE_RELEASE_DEPLOY_CONFLICT_MESSAGE, FlowsNamespace, LEDGER_ARTIFACT_LINE_PREFIX, ProductsNamespace, RuntypeApiError, RuntypeClient, SkillsNamespace, SurfacesNamespace, ToolsNamespace, activateAgentPromotion, buildLedgerOffloadReference, compileWorkflowConfig, createClient, defaultWorkflow, defineFlow, defineFpo, defineProduct, defineSkill, defineSurface, defineTool, deployWorkflow, ensureDefaultWorkflowHooks, evaluateGeneratedRuntimeToolProposal, gameWorkflow, getDefaultPlanPath, isBuiltinToolExecuteResponse, isWorkflowHookRef, parseFinalBuffer, parseLedgerArtifactRelativePath, parseOffloadedOutputId, parseSSEChunk, prepareAgentPromotion, processStream, registerWorkflowHook, validateAgentPromotion } from "@runtypelabs/sdk";
 import Conf from "conf";
 import os, { tmpdir } from "os";
 import path$1, { delimiter, dirname as dirname$1, join as join$1, relative as relative$1, resolve as resolve$1, sep as sep$1 } from "path";
@@ -3318,6 +3318,114 @@ function handleIntersectionResults(result, left, right) {
 	result.value = merged.data;
 	return result;
 }
+const $ZodTuple = /*@__PURE__*/ $constructor("$ZodTuple", (inst, def) => {
+	$ZodType.init(inst, def);
+	const items = def.items;
+	const memo = globalConfig.memoizer;
+	memo?.attach(inst);
+	inst._zod.parse = (payload, ctx) => {
+		const input = payload.value;
+		if (!Array.isArray(input)) {
+			payload.issues.push({
+				input,
+				inst,
+				expected: "tuple",
+				code: "invalid_type"
+			});
+			return payload;
+		}
+		payload.value = memo ? memo.alloc(inst, payload, [], ctx) : [];
+		const proms = [];
+		const optinStart = getTupleOptStart(items, "optin");
+		const optoutStart = getTupleOptStart(items, "optout");
+		if (!def.rest) {
+			if (input.length < optinStart) {
+				payload.issues.push({
+					code: "too_small",
+					minimum: optinStart,
+					inclusive: true,
+					input,
+					inst,
+					origin: "array"
+				});
+				return payload;
+			}
+			if (input.length > items.length) payload.issues.push({
+				code: "too_big",
+				maximum: items.length,
+				inclusive: true,
+				input,
+				inst,
+				origin: "array"
+			});
+		}
+		const itemResults = new Array(items.length);
+		const abortEarly = def.rest ? ctx?.abortEarly : void 0;
+		let itemAborted = false;
+		for (let i = 0; i < items.length; i++) {
+			const r = items[i]._zod.run({
+				value: input[i],
+				issues: []
+			}, ctx);
+			if (r instanceof Promise) proms.push(r.then((rr) => {
+				itemResults[i] = rr;
+			}));
+			else {
+				itemResults[i] = r;
+				if (abortEarly && !itemAborted && r.issues.length) itemAborted = aborted(r);
+			}
+		}
+		if (def.rest && !itemAborted) {
+			let i = items.length - 1;
+			const rest = input.slice(items.length);
+			let seen = payload.issues.length;
+			for (const el of rest) {
+				if (abortEarly && payload.issues.length !== seen) {
+					if (aborted(payload, seen)) break;
+					seen = payload.issues.length;
+				}
+				i++;
+				const result = def.rest._zod.run({
+					value: el,
+					issues: []
+				}, ctx);
+				if (result instanceof Promise) proms.push(result.then((r) => handleTupleResult(r, payload, i)));
+				else handleTupleResult(result, payload, i);
+			}
+		}
+		if (proms.length) return Promise.all(proms).then(() => handleTupleResults(itemResults, payload, items, input, optoutStart));
+		return handleTupleResults(itemResults, payload, items, input, optoutStart);
+	};
+});
+function getTupleOptStart(items, key) {
+	for (let i = items.length - 1; i >= 0; i--) if (!(key === "optin" ? items[i]._zod.optin !== void 0 : items[i]._zod.optout === "optional")) return i + 1;
+	return 0;
+}
+function handleTupleResult(result, final, index) {
+	if (result.issues.length) final.issues.push(...prefixIssues(index, result.issues));
+	final.value[index] = result.value;
+}
+function handleTupleResults(itemResults, final, items, input, optoutStart) {
+	for (let i = 0; i < items.length; i++) {
+		const r = itemResults[i];
+		const isPresent = i < input.length;
+		if (!isPresent && i >= optoutStart && items[i]._zod.optin === "optional") {
+			final.value.length = i;
+			break;
+		}
+		if (r.issues.length) {
+			if (!isPresent && i >= optoutStart) {
+				final.value.length = i;
+				break;
+			}
+			final.issues.push(...prefixIssues(i, r.issues));
+		}
+		final.value[i] = r.value;
+	}
+	for (let i = final.value.length - 1; i >= input.length; i--) if (items[i]._zod.optout === "optional" && final.value[i] === void 0) final.value.length = i;
+	else break;
+	return final;
+}
 const $ZodRecord = /*@__PURE__*/ $constructor("$ZodRecord", (inst, def) => {
 	$ZodType.init(inst, def);
 	const memo = globalConfig.memoizer;
@@ -5394,6 +5502,58 @@ const intersectionProcessor = (schema, ctx, json, params) => {
 	json.allOf = allOf;
 	ctx.intersections.push(allOf);
 };
+const tupleProcessor = (schema, ctx, _json, params) => {
+	const json = _json;
+	const def = schema._zod.def;
+	json.type = "array";
+	const prefixPath = ctx.target === "draft-2020-12" ? "prefixItems" : "items";
+	const restPath = ctx.target === "draft-2020-12" ? "items" : ctx.target === "openapi-3.0" ? "items" : "additionalItems";
+	const prefixItems = def.items.map((x, i) => processSchema(x, ctx, {
+		...params,
+		path: [
+			...params.path,
+			prefixPath,
+			i
+		]
+	}));
+	const rest = def.rest ? processSchema(def.rest, ctx, {
+		...params,
+		path: [
+			...params.path,
+			restPath,
+			...ctx.target === "openapi-3.0" ? [def.items.length] : []
+		]
+	}) : null;
+	let minItems = def.items.length;
+	while (minItems > 0) {
+		const item = def.items[minItems - 1];
+		if (!(ctx.io === "input" ? inputOptin(item) !== void 0 : item._zod.optout === "optional")) break;
+		minItems--;
+	}
+	const maxItems = def.items.length;
+	const isClosed = !def.rest;
+	if (ctx.target === "draft-2020-12") {
+		json.prefixItems = prefixItems;
+		if (isClosed) json.items = false;
+		else if (rest) json.items = rest;
+		if (minItems > 0) json.minItems = minItems;
+		if (isClosed) json.maxItems = maxItems;
+	} else if (ctx.target === "openapi-3.0") {
+		json.items = { anyOf: prefixItems };
+		if (rest) json.items.anyOf.push(rest);
+		if (minItems > 0) json.minItems = minItems;
+		if (isClosed) json.maxItems = maxItems;
+	} else {
+		json.items = prefixItems;
+		if (isClosed) json.additionalItems = false;
+		else if (rest) json.additionalItems = rest;
+		if (minItems > 0) json.minItems = minItems;
+		if (isClosed) json.maxItems = maxItems;
+	}
+	const { minimum, maximum } = aggregateChecks(schema);
+	if (typeof minimum === "number") json.minItems = minimum;
+	if (typeof maximum === "number") json.maxItems = maximum;
+};
 /** JSON object keys are always strings, so a numeric record key schema is re-expressed over the
 * numeric-string form the record parser matches. Deferred to `finalize`, after the flatten: a key
 * behind a wrapper only carries its own `type` before then, and a union key only has its branches.
@@ -6315,6 +6475,39 @@ function intersection(left, right) {
 		right
 	});
 }
+const ZodTuple = /*@__PURE__*/ $constructor("ZodTuple", (inst, def) => {
+	_ensureDefaultMemoizer();
+	$ZodTuple.init(inst, def);
+	ZodType.init(inst, def);
+	inst._zod.processJSONSchema = (ctx, json, params) => tupleProcessor(inst, ctx, json, params);
+}, {
+	rest(rest) {
+		return this.clone({
+			...this._zod.def,
+			rest
+		});
+	},
+	partial() {
+		const def = this._zod.def;
+		if (def.checks?.length) throw new Error(".partial() cannot be used on tuple schemas containing refinements");
+		return this.clone({
+			...def,
+			items: def.items.map((item) => new ZodOptional({
+				type: "optional",
+				innerType: item
+			}))
+		});
+	}
+});
+function tuple(items, _paramsOrRest, _params) {
+	const hasRest = _paramsOrRest instanceof $ZodType;
+	return new ZodTuple({
+		type: "tuple",
+		items,
+		rest: hasRest ? _paramsOrRest : null,
+		...normalizeParams(hasRest ? _params : _paramsOrRest)
+	});
+}
 const ZodRecord = /*@__PURE__*/ $constructor("ZodRecord", (inst, def) => {
 	_ensureDefaultMemoizer();
 	$ZodRecord.init(inst, def);
@@ -12478,7 +12671,48 @@ const GEN_AI_ATTRIBUTES = {
 	toolCallId: "gen_ai.tool.call.id"
 };
 //#endregion
-//#region ../shared/dist/chunk-B1SxgkWd.mjs
+//#region ../shared/dist/context-manifest-wire.mjs
+const entryTupleSchema = union([tuple([
+	string(),
+	number$1().int(),
+	number$1().int(),
+	number$1().int(),
+	number$1().int(),
+	number$1().int(),
+	number$1().int()
+]), tuple([
+	string(),
+	number$1().int(),
+	number$1().int(),
+	number$1().int(),
+	number$1().int(),
+	number$1().int(),
+	number$1().int(),
+	string(),
+	string()
+])]);
+object({
+	v: literal(1),
+	s: number$1().int().nonnegative(),
+	e: array(entryTupleSchema),
+	b: array(number$1().int().nonnegative()),
+	x: array(tuple([entryTupleSchema, number$1().int()]))
+});
+object({
+	v: literal(1),
+	b: array(tuple([
+		string(),
+		string(),
+		union([literal(0), literal(1)])
+	]))
+});
+object({
+	hash: string(),
+	content: string(),
+	truncated: boolean()
+});
+//#endregion
+//#region ../shared/dist/chunk-_ZhmfUpr.mjs
 /**
 * GenAI semconv content attributes, set by a customer's own instrumentation when it opts into content export.
 * Two first-party producers write them: @runtypelabs/runtime's OTLP tracer for exported agents (content on by default), and @runtypelabs/flue-otel (opt-in).
@@ -12498,7 +12732,9 @@ const GEN_AI_CONTENT_ATTRIBUTES = {
 	/** `execute_tool` span: the arguments the tool was called with. */
 	toolCallArguments: GEN_AI_TOOL_CALL_ARGUMENTS,
 	/** `execute_tool` span: the result the tool returned. */
-	toolCallResult: GEN_AI_TOOL_CALL_RESULT
+	toolCallResult: GEN_AI_TOOL_CALL_RESULT,
+	/** `chat` span: the tool schemas the call offered the model. */
+	toolDefinitions: "gen_ai.tool.definitions"
 };
 /**
 * Read-side aliases for content attributes: canonical semconv name to vendor-namespaced spellings a stock instrumentation uses.
@@ -14454,6 +14690,39 @@ function unknownCatalogToolMessage(toolId) {
 	return `Tool "${toolId}" is not a built-in or platform catalog tool. Check the id against the tool catalog (list_tools), or point toolId at a saved tool's "tool_..." id or its "tool:<name>" reference.`;
 }
 /**
+* Name-based references to saved agents and flows (agent:<name>, flow:<name>) for portable ensure/config-as-code definitions.
+* The name is canonical: hashed and persisted verbatim so definitions converge to the same content hash across environments.
+* Grammar mirrors parseNamedToolRef: split on the first colon only, exact case-sensitive match, no trimming.
+* The flow: prefix also names a template-variable namespace, but the two grammars never collide.
+*/
+/** Reserved prefix for a name-based saved-agent reference (`agent:<name>`). */
+const NAMED_AGENT_REF_PREFIX = "agent:";
+/** Reserved prefix for a name-based saved-flow reference (`flow:<name>`). */
+const NAMED_FLOW_REF_PREFIX = "flow:";
+function isNamedRef(value, prefix) {
+	return value.startsWith(prefix) && value.length > prefix.length;
+}
+function parseNamedRef(value, prefix) {
+	if (!isNamedRef(value, prefix)) return null;
+	return { name: value.slice(prefix.length) };
+}
+/**
+* Parse an `agent:<name>` reference into its name. Split on the FIRST colon
+* only; the remainder is the agent name verbatim. Returns null when `value` is
+* not a valid named agent ref.
+*/
+function parseNamedAgentRef(value) {
+	return parseNamedRef(value, NAMED_AGENT_REF_PREFIX);
+}
+/**
+* Parse a `flow:<name>` reference into its name. Split on the FIRST colon only;
+* the remainder is the flow name verbatim. Returns null when `value` is not a
+* valid named flow ref.
+*/
+function parseNamedFlowRef(value) {
+	return parseNamedRef(value, NAMED_FLOW_REF_PREFIX);
+}
+/**
 * Return whether an `execute-agent` step's `config.agentId` is a template
 * expression rather than a fixed agent reference. No static gate can scan the
 * agent a `{{...}}` ref substitutes to, so the runtime lane folds it as
@@ -14499,10 +14768,12 @@ function walkSteps$1(steps, basePath, context, state) {
 }
 function walkStep(node, path, context, state) {
 	if (!isRecord$1(node)) return;
-	if (node.enabled === false) return;
+	if (node.enabled === false && !state.includeDisabled) return;
 	const config = isRecord$1(node.config) ? node.config : void 0;
 	if (!config) return;
+	state.visitor.visitStep?.(node, config, path, context);
 	if (node.type === "execute-agent") state.visitor.visitExecuteAgent(node, config, path, context);
+	visitFlowFallbacks(config, path, context, state);
 	walkToolPayloads(config.tools, `${path}.config.tools`, context, state);
 	const deeper = {
 		...state,
@@ -14524,6 +14795,21 @@ function walkStep(node, path, context, state) {
 	});
 	for (const key of CONDITIONAL_BRANCH_STEP_KEYS$2) walkSteps$1(config[key], `${path}.config.${key}`, context, nested);
 }
+function visitFlowFallbacks(config, path, context, state) {
+	const { visitFlowFallback, visitStepFallback } = state.visitor;
+	if (!visitFlowFallback && !visitStepFallback || !isRecord$1(config.errorHandling)) return;
+	const fallbacks = config.errorHandling.fallbacks;
+	if (!Array.isArray(fallbacks)) return;
+	fallbacks.forEach((fallback, index) => {
+		if (!isRecord$1(fallback)) return;
+		const fallbackPath = `${path}.config.errorHandling.fallbacks[${index}]`;
+		if (fallback.type === "flow") visitFlowFallback?.(fallback, fallbackPath, context);
+		else if (fallback.type === "step" && visitStepFallback && isRecord$1(fallback.stepConfig)) {
+			visitStepFallback(fallback, fallback.stepConfig, fallbackPath, context);
+			walkToolPayloads(fallback.stepConfig.tools, `${fallbackPath}.stepConfig.tools`, context, state);
+		}
+	});
+}
 const TOOL_BAG_KEYS = ["runtimeTools", "inlineTools"];
 /** Descend the inline flow-as-tool and skill payloads a step's tool bag can carry. */
 function walkToolPayloads(tools, path, context, state) {
@@ -14546,7 +14832,7 @@ function walkRuntimeTools(runtimeTools, basePath, context, state) {
 		if (!config) return;
 		const toolPath = `${basePath}[${index}].config`;
 		if (isRecord$1(config.skill) && Array.isArray(config.skill.resolvedTools)) walkRuntimeTools(config.skill.resolvedTools, `${toolPath}.skill.resolvedTools`, context, deeper);
-		if (isRecord$1(config.flow) && Array.isArray(config.flow.steps)) {
+		if (!state.skipInlineFlows && isRecord$1(config.flow) && Array.isArray(config.flow.steps)) {
 			const nestedContext = state.visitor.enterNestedFlow?.(config.flow, context) ?? context;
 			walkSteps$1(config.flow.steps, `${toolPath}.flow.steps`, nestedContext, {
 				...deeper,
@@ -18560,39 +18846,6 @@ function normalizeMemorySummaryConfig(config) {
 		defaultValue: config.defaultValue ?? config.default_value
 	};
 }
-/**
-* Name-based references to saved agents and flows (agent:<name>, flow:<name>) for portable ensure/config-as-code definitions.
-* The name is canonical: hashed and persisted verbatim so definitions converge to the same content hash across environments.
-* Grammar mirrors parseNamedToolRef: split on the first colon only, exact case-sensitive match, no trimming.
-* The flow: prefix also names a template-variable namespace, but the two grammars never collide.
-*/
-/** Reserved prefix for a name-based saved-agent reference (`agent:<name>`). */
-const NAMED_AGENT_REF_PREFIX = "agent:";
-/** Reserved prefix for a name-based saved-flow reference (`flow:<name>`). */
-const NAMED_FLOW_REF_PREFIX = "flow:";
-function isNamedRef(value, prefix) {
-	return value.startsWith(prefix) && value.length > prefix.length;
-}
-function parseNamedRef(value, prefix) {
-	if (!isNamedRef(value, prefix)) return null;
-	return { name: value.slice(prefix.length) };
-}
-/**
-* Parse an `agent:<name>` reference into its name. Split on the FIRST colon
-* only; the remainder is the agent name verbatim. Returns null when `value` is
-* not a valid named agent ref.
-*/
-function parseNamedAgentRef(value) {
-	return parseNamedRef(value, NAMED_AGENT_REF_PREFIX);
-}
-/**
-* Parse a `flow:<name>` reference into its name. Split on the FIRST colon only;
-* the remainder is the flow name verbatim. Returns null when `value` is not a
-* valid named flow ref.
-*/
-function parseNamedFlowRef(value) {
-	return parseNamedRef(value, NAMED_FLOW_REF_PREFIX);
-}
 function sanitizeCodeToolIdentifier(name) {
 	let safe = name.replace(/[^a-zA-Z0-9_$]/g, "_");
 	if (/^[0-9]/.test(safe)) safe = "_" + safe;
@@ -22149,7 +22402,8 @@ _enum([
 	"saved_from_run",
 	"generated",
 	"imported",
-	"fpo"
+	"fpo",
+	"ensure"
 ]);
 /**
 * Where a saved_from_run case was forked from.
@@ -23098,6 +23352,11 @@ const fpoSkillCapabilitiesSchema = object({
 	inlineTools: array(fpoSkillInlineToolSchema).optional(),
 	mcpServers: never({ error: "Skill capabilities cannot declare `mcpServers` — MCP server bindings are rejected at write for v1 skills. Bind MCP tools via a saved tool id or an inlineTool instead." }).optional()
 });
+/** A `bindTo` entry that pins the binding to one skill versionNumber instead of following published. */
+const fpoSkillBindTargetSchema = object({
+	capability: string().min(1),
+	version: number$1().int().positive().optional()
+}).strict();
 const fpoSkillSchema = object({
 	id: string().min(1),
 	slug: string().regex(SKILL_NAME_PATTERN, "Skill slug must start with a letter and contain only lowercase letters, digits, underscores, and hyphens (max 64 chars).").optional(),
@@ -23110,7 +23369,7 @@ const fpoSkillSchema = object({
 		"community"
 	]).optional(),
 	capabilities: fpoSkillCapabilitiesSchema.optional(),
-	bindTo: array(string()).optional(),
+	bindTo: array(union([string(), fpoSkillBindTargetSchema])).optional(),
 	createPolicy: createPolicySchema
 });
 const metaSchema = object({
@@ -24099,8 +24358,17 @@ function validateFPO(fpo) {
 			if (!skill || typeof skill !== "object") continue;
 			const s = skill;
 			if (Array.isArray(s.bindTo)) {
-				for (const [bi, ref] of s.bindTo.entries()) if (!capIds.has(ref)) result.errors.push(createIssue("error", "SKILL_BIND_CAPABILITY_NOT_FOUND", `Skill "${id ?? ""}" binds to capability "${ref}" which does not exist`, `skills[${i}].bindTo[${bi}]`));
-				else if (!agentBackedCapIds.has(ref)) result.errors.push(createIssue("error", "SKILL_BIND_TARGET_NOT_AGENT", `Skill "${id ?? ""}" binds to capability "${ref}" which is not agent-backed; skills can only be bound to agent capabilities`, `skills[${i}].bindTo[${bi}]`));
+				const boundRefs = /* @__PURE__ */ new Set();
+				for (const [bi, entry] of s.bindTo.entries()) {
+					const ref = entry && typeof entry === "object" ? entry.capability : entry;
+					if (boundRefs.has(ref)) {
+						result.errors.push(createIssue("error", "SKILL_BIND_DUPLICATE_CAPABILITY", `Skill "${id ?? ""}" binds to capability "${ref}" more than once; list each capability once with the version it should load`, `skills[${i}].bindTo[${bi}]`));
+						continue;
+					}
+					boundRefs.add(ref);
+					if (!capIds.has(ref)) result.errors.push(createIssue("error", "SKILL_BIND_CAPABILITY_NOT_FOUND", `Skill "${id ?? ""}" binds to capability "${ref}" which does not exist`, `skills[${i}].bindTo[${bi}]`));
+					else if (!agentBackedCapIds.has(ref)) result.errors.push(createIssue("error", "SKILL_BIND_TARGET_NOT_AGENT", `Skill "${id ?? ""}" binds to capability "${ref}" which is not agent-backed; skills can only be bound to agent capabilities`, `skills[${i}].bindTo[${bi}]`));
+				}
 			}
 			const capabilityRefs = s.capabilities && typeof s.capabilities === "object" ? s.capabilities.capabilityRefs : void 0;
 			if (Array.isArray(capabilityRefs)) {
@@ -27170,18 +27438,18 @@ const VERIFY_NEXT = "Ask the user for the 6-digit code from their email, then ru
 function claimNext(email) {
 	return email ? `Send the verification email with: runtype auth claim ${email}` : "Ask the user for their email address, then run: runtype auth claim <email>";
 }
-function fail$3(payload) {
+function fail$4(payload) {
 	console.error(JSON.stringify(payload, null, 2));
 	process.exit(1);
 }
 function failFromError(error, fallbackNext) {
-	if (error instanceof AgentAuthError) fail$3({
+	if (error instanceof AgentAuthError) fail$4({
 		status: "error",
 		code: error.code,
 		error: error.message,
 		...error.hint || fallbackNext ? { next: error.hint || fallbackNext } : {}
 	});
-	fail$3({
+	fail$4({
 		status: "error",
 		error: error instanceof Error ? error.message : String(error),
 		...fallbackNext ? { next: fallbackNext } : {}
@@ -27214,7 +27482,7 @@ async function registerAction(options) {
 			return;
 		}
 	}
-	if (hasCredentials && !existingClaim && !options.force) fail$3({
+	if (hasCredentials && !existingClaim && !options.force) fail$4({
 		status: "error",
 		code: "already_authenticated",
 		error: "Credentials are already stored for a claimed account.",
@@ -27266,7 +27534,7 @@ async function registerAction(options) {
 		});
 		return;
 	} catch (error) {
-		if (error instanceof AgentAuthError) fail$3({
+		if (error instanceof AgentAuthError) fail$4({
 			...base,
 			status: "registered_claim_failed",
 			code: error.code,
@@ -27286,7 +27554,7 @@ async function claimAction(email, options) {
 	const apiUrl = options.apiUrl || claimState?.apiUrl || (await store.getCredentials())?.apiUrl || getApiUrl();
 	if (!claimState) {
 		const hasCredentials = await store.hasCredentials();
-		fail$3({
+		fail$4({
 			status: "error",
 			code: "no_pending_registration",
 			error: hasCredentials ? "Stored credentials are already claimed; there is nothing to claim." : "No registration found.",
@@ -27314,13 +27582,13 @@ async function verifyAction(code, options) {
 	const store = new CredentialStore();
 	const claimState = await store.getClaimState();
 	const apiUrl = options.apiUrl || claimState?.apiUrl || (await store.getCredentials())?.apiUrl || getApiUrl();
-	if (!claimState) fail$3({
+	if (!claimState) fail$4({
 		status: "error",
 		code: "no_pending_registration",
 		error: "No claim in progress.",
 		next: "Run: runtype auth register --email <email> first."
 	});
-	if (!claimState.claimEmail) fail$3({
+	if (!claimState.claimEmail) fail$4({
 		status: "error",
 		code: "claim_not_initiated",
 		error: "No verification email has been sent yet, so there is no code to verify.",
@@ -27923,6 +28191,283 @@ function resolveJsonPayload(inline, fromFile, label) {
 	return parseJsonObject$1(inline, label);
 }
 //#endregion
+//#region src/lib/ensure-output.ts
+/**
+* Emit a pulled definition as JSON: to `out` when given, otherwise to stdout so
+* `runtype <entity> pull <name> > file.json` works. Hash and warnings go to stderr.
+*/
+function writePulledDefinition(data, meta) {
+	const json = `${JSON.stringify(data, null, 2)}\n`;
+	if (meta.out) {
+		writeFileSync$1(meta.out, json);
+		console.error(chalk.green(`Wrote ${meta.out}`));
+	} else process.stdout.write(json);
+	if (meta.contentHash) console.error(chalk.gray(`contentHash ${meta.contentHash}`));
+	for (const warning of meta.warnings ?? []) console.error(chalk.yellow(`warning: ${warning}`));
+}
+//#endregion
+//#region src/commands/entity-ensure.ts
+function namespaceTransport(client) {
+	const transport = {
+		get: (path, params) => client.get(path, params),
+		post: (path, body) => client.post(path, body)
+	};
+	return () => transport;
+}
+/** The SDK ensure options these flags ask for, shared by every entity. */
+function buildEntityEnsureOptions(flags, support) {
+	if (flags.release !== void 0 && !["none", "publish"].includes(flags.release)) throw new Error("--release must be none or publish");
+	const version = support.version && (flags.label || flags.notes) ? {
+		...flags.label ? { label: flags.label } : {},
+		...flags.notes ? { notes: flags.notes } : {}
+	} : void 0;
+	return {
+		...flags.dryRun ? { dryRun: true } : {},
+		...flags.expectNoChanges ? { expectNoChanges: true } : {},
+		...flags.overwriteManaged ? { onConflict: "overwrite" } : {},
+		...flags.expectedRemoteHash ? { expectedRemoteHash: flags.expectedRemoteHash } : {},
+		...support.release && flags.release ? { release: flags.release } : {},
+		...version ? { version } : {}
+	};
+}
+const define = (fn, definition) => fn(definition);
+const SKILL_ENSURE_SPEC = {
+	noun: "skill",
+	idKey: "skillId",
+	release: true,
+	version: true,
+	productScoped: false,
+	ensure: async (t, def, options) => new SkillsNamespace(t).ensure(define(defineSkill, def), options),
+	pull: (t, name) => new SkillsNamespace(t).pull(name)
+};
+const FLOW_ENSURE_SPEC = {
+	noun: "flow",
+	idKey: "flowId",
+	release: true,
+	version: true,
+	productScoped: false,
+	ensure: async (t, def, options) => new FlowsNamespace(t).ensure(define(defineFlow, def), options),
+	pull: (t, name) => new FlowsNamespace(t).pull(name)
+};
+const TOOL_ENSURE_SPEC = {
+	noun: "tool",
+	idKey: "toolId",
+	release: false,
+	version: false,
+	productScoped: false,
+	ensure: async (t, def, options) => new ToolsNamespace(t).ensure(define(defineTool, def), options),
+	pull: (t, name) => new ToolsNamespace(t).pull(name)
+};
+const PRODUCT_ENSURE_SPEC = {
+	noun: "product",
+	idKey: "productId",
+	release: false,
+	version: false,
+	productScoped: false,
+	ensure: async (t, def, options) => new ProductsNamespace(t).ensure(define(defineProduct, def), options),
+	pull: (t, name) => new ProductsNamespace(t).pull(name)
+};
+const SURFACE_ENSURE_SPEC = {
+	noun: "surface",
+	idKey: "surfaceId",
+	release: false,
+	version: false,
+	productScoped: true,
+	ensure: async (t, def, options, productId) => new SurfacesNamespace(t).ensure(productId, define(defineSurface, def), options),
+	pull: (t, name, productId) => new SurfacesNamespace(t).pull(productId, name)
+};
+function isDriftError(error) {
+	return error instanceof Error && error.name.endsWith("DriftError") && "plan" in error;
+}
+function printEnsureOutcome(spec, name, result) {
+	if (result.result === "plan") {
+		console.log(chalk.cyan(`Plan for ${spec.noun} "${name}": ${result.changes ?? "n/a"}`));
+		for (const key of result.changedKeys ?? []) console.log(`  ${key}`);
+		if (result.remoteHash) console.log(chalk.gray(`Apply this plan with --expected-remote-hash ${result.remoteHash}`));
+		return;
+	}
+	const id = typeof result[spec.idKey] === "string" ? ` (${result[spec.idKey]})` : "";
+	console.log(chalk.green(`${spec.noun[0].toUpperCase()}${spec.noun.slice(1)} "${name}" ${result.result}${id}`));
+	if (result.versionId) console.log(chalk.gray(`Version ${result.versionId}`));
+}
+function fail$3(message, detail) {
+	console.error(chalk.red(message));
+	if (detail !== void 0) console.error(chalk.red(detail instanceof Error ? detail.message : String(detail)));
+	process.exit(1);
+}
+/** `ensure <file>`: converge a definition file (a pull's output, or its `definition`). */
+function buildEntityEnsureCommand(spec) {
+	const command = new Command("ensure").description(`Converge a ${spec.noun} definition from a JSON file (config-as-code)`).argument("<file>", `${spec.noun} definition JSON file, or - to read from stdin`);
+	if (spec.productScoped) command.requiredOption("--product <productId>", "Product the surface belongs to");
+	command.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("--expected-remote-hash <hash>", "Apply only if the remote still hashes to this value (the remoteHash a dry run printed)");
+	if (spec.release) command.option("--release <mode>", "none or publish");
+	if (spec.version) command.option("--label <text>", "Version label recorded on the version this converge appends").option("--notes <text>", "Version notes recorded on the version this converge appends");
+	command.option("--json", "Output as JSON").action(async (file, flags) => {
+		let options;
+		let definition;
+		try {
+			options = buildEntityEnsureOptions(flags, spec);
+			definition = readJsonFile(file, {
+				label: `${spec.noun} definition`,
+				unwrapKey: "definition"
+			});
+		} catch (error) {
+			fail$3(error instanceof Error ? error.message : String(error));
+		}
+		const name = typeof definition.name === "string" ? definition.name : "";
+		const apiKey = await ensureAuth();
+		if (!apiKey) return;
+		const transport = namespaceTransport(createCliClient(apiKey));
+		try {
+			const result = await spec.ensure(transport, definition, options, flags.product);
+			if (flags.json) printJson(result);
+			else printEnsureOutcome(spec, name, result);
+		} catch (error) {
+			if (isDriftError(error)) {
+				if (flags.json) printJson({
+					drift: true,
+					plan: error.plan
+				});
+				else console.error(chalk.yellow(error.message));
+				process.exit(1);
+			}
+			fail$3(`Failed to converge the ${spec.noun}`, error);
+		}
+	});
+	return command;
+}
+/** `pull <name>`: print the definition file `ensure` reads back (dashboard wins). */
+function buildEntityPullCommand(spec) {
+	const command = new Command("pull").description(`Print a ${spec.noun} as the definition file \`ensure\` reads (dashboard wins)`).argument("<name>", `${spec.noun} name`);
+	if (spec.productScoped) command.requiredOption("--product <productId>", "Product the surface belongs to");
+	command.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, flags) => {
+		const apiKey = await ensureAuth();
+		if (!apiKey) return;
+		const transport = namespaceTransport(createCliClient(apiKey));
+		try {
+			const pulled = await spec.pull(transport, name, flags.product);
+			writePulledDefinition(flags.json ? pulled : pulled.definition, {
+				out: flags.out,
+				contentHash: pulled.contentHash,
+				warnings: pulled.warnings
+			});
+		} catch (error) {
+			fail$3(`Failed to pull ${spec.noun} "${name}"`, error);
+		}
+	});
+	return command;
+}
+function buildFpoEnsureOptions(flags) {
+	if (flags.release !== void 0 && !["none", "publish"].includes(flags.release)) throw new Error("--release must be none or publish");
+	return {
+		...flags.dryRun ? { dryRun: true } : {},
+		...flags.expectNoChanges ? { expectNoChanges: true } : {},
+		...flags.overwriteManaged ? { onConflict: "overwrite" } : {},
+		...flags.expectedRemoteHash ? { expectedRemoteHash: flags.expectedRemoteHash } : {},
+		...flags.prune ? { prune: true } : {},
+		...flags.hashProbe ? { hashProbe: true } : {},
+		...flags.release ? { release: flags.release } : {}
+	};
+}
+/** `ensure-fpo <file>`: converge a whole Full Product Object. */
+const productEnsureFpoCommand = new Command("ensure-fpo").description("Converge a whole Full Product Object (product, capabilities, surfaces, ...) from a JSON file").argument("<file>", "FPO JSON file (a pull-fpo output, or its fpo), or - to read from stdin").option("--dry-run", "Plan without writing").option("--expect-no-changes", "Plan and exit 1 when any entity would change (the CI gate)").option("--overwrite-managed", "Converge over dashboard/API edits").option("--expected-remote-hash <hash>", "Apply only if the live product still hashes to this value (the remoteHash a dry run printed)").option("--prune", "Remove product-scoped capabilities and surfaces absent from the FPO").option("--release <mode>", "publish (default: converged agents and flows go live) or none (save drafts)").option("--hash-probe", "With --release none, skip the upload when the live product already matches (best for pulled FPOs)").option("--json", "Output as JSON").action(async (file, flags) => {
+	let fpo;
+	try {
+		fpo = defineFpo(readJsonFile(file, {
+			label: "FPO",
+			unwrapKey: "fpo"
+		}));
+	} catch (error) {
+		fail$3(error instanceof Error ? error.message : String(error));
+	}
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const products = new ProductsNamespace(namespaceTransport(createCliClient(apiKey)));
+	try {
+		const result = await products.ensureFpo(fpo, buildFpoEnsureOptions(flags));
+		if (flags.json) printJson(result);
+		else {
+			console.log(chalk.cyan(`Product FPO ${result.result}${result.productId ? ` (${result.productId})` : ""}`));
+			for (const entity of result.entities) {
+				const line = `  ${entity.kind}:${entity.name} ${entity.result}`;
+				console.log(entity.result === "failed" ? chalk.red(`${line} — ${entity.error ?? ""}`) : line);
+			}
+			if (result.remoteHash) console.log(chalk.gray(`Apply this plan with --expected-remote-hash ${result.remoteHash}`));
+		}
+		if (result.hasFailures) process.exit(1);
+	} catch (error) {
+		if (isDriftError(error)) {
+			if (flags.json) printJson({
+				drift: true,
+				plan: error.plan
+			});
+			else console.error(chalk.yellow(error.message));
+			process.exit(1);
+		}
+		fail$3("Failed to converge the product FPO", error);
+	}
+});
+/** Runtype Agent Skills live under `agents` because `runtype skills` installs coding-agent skills. */
+const agentSkillsCommand = new Command("skills").description("Runtype Agent Skills: context bundles deployed agents load (for coding-agent skills see `runtype skills`)");
+agentSkillsCommand.addCommand(buildEntityEnsureCommand(SKILL_ENSURE_SPEC));
+agentSkillsCommand.addCommand(buildEntityPullCommand(SKILL_ENSURE_SPEC));
+/** `pull-fpo <name>`: print the whole product as the FPO `ensure-fpo` reads. */
+const productPullFpoCommand = new Command("pull-fpo").description("Print a product graph as the FPO `ensure-fpo` reads (dashboard wins)").argument("<name>", "Product name").option("-o, --out <file>", "Write the FPO here instead of stdout").option("--json", "Print the full pull response (fpo, contentHash, warnings)").action(async (name, flags) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const products = new ProductsNamespace(namespaceTransport(createCliClient(apiKey)));
+	try {
+		const pulled = await products.pullFpo(name);
+		writePulledDefinition(flags.json ? pulled : pulled.fpo, {
+			out: flags.out,
+			contentHash: pulled.contentHash,
+			warnings: pulled.warnings
+		});
+	} catch (error) {
+		fail$3(`Failed to pull product "${name}"`, error);
+	}
+});
+/** Converge a client token file through the SDK; it keys on `name` and never deletes or regenerates. */
+async function ensureClientTokenFromFile(client, definition, flags) {
+	const getClient = (() => client);
+	return new ClientTokensNamespace(getClient).ensure(definition, {
+		...flags.dryRun ? { dryRun: true } : {},
+		...flags.expectNoChanges ? { expectNoChanges: true } : {}
+	});
+}
+/** `client-tokens ensure <file>`: the widget token step of the agent-plus-token workflow. */
+const clientTokenEnsureCommand = new Command("ensure").description("Converge a client token definition from a JSON file, keyed by its name").argument("<file>", "Client token definition JSON file, or - to read from stdin").option("--dry-run", "Plan without writing").option("--expect-no-changes", "Plan and exit 1 on any drift (the CI gate)").option("--json", "Output as JSON").action(async (file, flags) => {
+	let definition;
+	try {
+		definition = readJsonFile(file, { label: "client token definition" });
+	} catch (error) {
+		fail$3(error instanceof Error ? error.message : String(error));
+	}
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	try {
+		const result = await ensureClientTokenFromFile(createCliClient(apiKey), definition, flags);
+		if (flags.json) printJson(result);
+		else if (result.result === "plan") {
+			console.log(chalk.cyan(`Plan for client token "${String(definition.name)}": ${result.changes}`));
+			for (const key of result.changedKeys) console.log(`  ${key}`);
+		} else {
+			console.log(chalk.green(`Client token "${result.clientToken.name}" ${result.result} (${result.clientToken.id})`));
+			if (result.token) console.log(`Token ${result.token}`);
+		}
+	} catch (error) {
+		if (isDriftError(error)) {
+			if (flags.json) printJson({
+				drift: true,
+				plan: error.plan
+			});
+			else console.error(chalk.yellow(error.message));
+			process.exit(1);
+		}
+		fail$3("Failed to converge the client token", error);
+	}
+});
+//#endregion
 //#region src/lib/execution-input.ts
 function addExecutionInputOptions(command) {
 	return command.option("--inputs <json>", "Typed input variables as a JSON object").option("--inputs-file <file|->", "Read input variables from a JSON object file or stdin").option("-v, --variable <key=value>", "Set a string variable (repeatable)", collectVariables, []).option("--messages-file <file|->", "Read structured messages from a JSON array file or stdin");
@@ -28248,6 +28793,8 @@ function flowsListParams(options) {
 	};
 }
 const flowsCommand = new Command("flows").description("Manage flows");
+flowsCommand.addCommand(buildEntityEnsureCommand(FLOW_ENSURE_SPEC));
+flowsCommand.addCommand(buildEntityPullCommand(FLOW_ENSURE_SPEC));
 flowsCommand.command("list").description("List all flows").option("--limit <n>", "Limit results (defaults to the API page size)").option("--cursor <cursor>", "Pagination cursor for the next page").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;
@@ -31461,6 +32008,8 @@ function formatToolMetadata(metadata) {
 	return parts.join("; ");
 }
 const toolsCommand = new Command("tools").description("Manage runtime tools (saved tools)");
+toolsCommand.addCommand(buildEntityEnsureCommand(TOOL_ENSURE_SPEC));
+toolsCommand.addCommand(buildEntityPullCommand(TOOL_ENSURE_SPEC));
 toolsCommand.command("list").description("List your tools").option("--limit <n>", "Limit results (defaults to the API page size)").option("--cursor <cursor>", "Pagination cursor for the next page").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;
@@ -32255,6 +32804,8 @@ function parsePositiveInteger$1(value, option) {
 	return parsed;
 }
 const surfacesCommand = new Command("surfaces").description("View product surfaces");
+surfacesCommand.addCommand(buildEntityEnsureCommand(SURFACE_ENSURE_SPEC));
+surfacesCommand.addCommand(buildEntityPullCommand(SURFACE_ENSURE_SPEC));
 surfacesCommand.command("list").description("List surfaces across your products").option("--json", "Output as JSON").option("--limit <n>", "Maximum number of surfaces to return").option("--cursor <cursor>", "Pagination cursor for the next page").option("--type <type>", "Filter by surface type").option("--status <status>", "Filter by surface status").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(async (options) => {
 	const apiKey = await ensureAuth();
 	if (!apiKey) return;
@@ -32928,6 +33479,10 @@ async function validateUrl(url, apiUrl) {
 	return validateQuickStartUrl(url, apiUrl);
 }
 const productsCommand = new Command("products").description("Manage products");
+productsCommand.addCommand(buildEntityEnsureCommand(PRODUCT_ENSURE_SPEC));
+productsCommand.addCommand(buildEntityPullCommand(PRODUCT_ENSURE_SPEC));
+productsCommand.addCommand(productEnsureFpoCommand);
+productsCommand.addCommand(productPullFpoCommand);
 productsCommand.command("init").description("Initialize a product from an external resource").option("--from <url>", "URL to validate and import").option("--name <name>", "Custom product name (defaults to agent name)").option("--open", "Open browser to dashboard instead of creating via API").option("--json", "Output as JSON").option("--api-url <url>", "Override API URL").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(async (options) => {
 	const isJsonMode = !!options.json;
 	if (!isTTY(options) || isJsonMode) {
@@ -46658,28 +47213,113 @@ agentDeploymentsCommand.command("list <agentId>").description("List deployment r
 * 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) {
+function buildEnsureActivation(flags, bindings) {
 	if (flags.release !== void 0 && flags.deploy !== void 0) throw new Error(ENSURE_RELEASE_DEPLOY_CONFLICT_MESSAGE);
-	if (flags.deploy !== void 0) return { deploy: { alias: flags.deploy } };
+	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 {};
 }
-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("--json", "Output as JSON").action(async (file, options) => {
+/** 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);
+		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);
 	}
-	const definition = readJsonFile(file, {
-		label: "agent definition",
-		unwrapKey: "agent"
-	});
+	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\"."));
@@ -46700,22 +47340,35 @@ const agentEnsureCommand = new Command("ensure").description("Converge an agent
 			...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 } = result.deployment;
-			console.log(chalk.green(`${changed ? "Deployed" : "Already deployed"} ${versionId} at "${alias}" (revision ${revision})`));
+			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.expectNoChanges && result.result === "plan" && result.changes !== "none") process.exit(1);
+		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"));
@@ -46723,6 +47376,23 @@ const agentEnsureCommand = new Command("ensure").description("Converge an agent
 		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);
+	}
+});
 //#endregion
 //#region src/commands/agent-promote.ts
 const DEFAULT_SOURCE_KEY_ENV = "RUNTYPE_SOURCE_API_KEY";
@@ -48225,6 +48895,8 @@ 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) => {
@@ -49893,7 +50565,7 @@ function toJUnitSuite(outcome) {
 		}))
 	};
 }
-evalCommand.command("run [idOrDirPrefix]").description("Run code-colocated eval suites (**/*.eval.ts) as a CI gate (exit 0 pass / 1 fail / 2 config)").option("--strict", "Fail the exit code on soft grader misses too (default: soft misses are reported but do not fail)").option("--virtual", "Run inline without persisting a suite/batch to the dashboard").option("--junit <path>", "Write JUnit XML results to <path>").option("--url <api>", "Override the API base URL (e.g. staging)").option("--cwd <dir>", "Directory to discover *.eval.ts under (default: current directory)").option("--alias <name>", "Run an Agent-target suite against whichever version this release alias points at").option("--version-id <id>", "Run an Agent-target suite against this exact version snapshot").action(async (idOrDirPrefix, options) => {
+evalCommand.command("run [idOrDirPrefix]").description("Run code-colocated eval suites (**/*.eval.ts) as a CI gate (exit 0 pass / 1 fail / 2 config)").option("--strict", "Fail the exit code on soft grader misses too (default: soft misses are reported but do not fail)").option("--virtual", "Run inline without persisting a suite/batch to the dashboard").option("--junit <path>", "Write JUnit XML results to <path>").option("--url <api>", "Override the API base URL (e.g. staging)").option("--cwd <dir>", "Directory to discover *.eval.ts under (default: current directory)").option("--alias <name>", "Run an Agent-target suite against whichever version this release alias points at").option("--version-id <id>", "Run an Agent-target suite against this exact version snapshot").option("--overwrite-managed", "Converge each suite even when its last write came from the dashboard or API (replaces edited ensure-owned cases)").action(async (idOrDirPrefix, options) => {
 	const apiKey = await ensureAuth();
 	if (!apiKey) failConfig("Not authenticated. Set RUNTYPE_API_KEY or run `runtype login`.");
 	let agentSelector = {};
@@ -49938,7 +50610,8 @@ evalCommand.command("run [idOrDirPrefix]").description("Run code-colocated eval
 			else {
 				const ensured = await client.post("/eval/ensure", {
 					name: def.name,
-					definition: def
+					definition: def,
+					...options.overwriteManaged ? { onConflict: "overwrite" } : {}
 				});
 				if (!ensured.suiteId) throw new Error(`ensure did not return a suiteId (result: ${ensured.result})`);
 				result = await client.post("/eval/run", {
@@ -51509,6 +52182,7 @@ clientTokensCommand.command("regenerate <id>").description("Regenerate a client
 	const { waitUntilExit } = render(React.createElement(App));
 	await waitUntilExit();
 });
+clientTokensCommand.addCommand(clientTokenEnsureCommand);
 //#endregion
 //#region ../../node_modules/.pnpm/@runtypelabs+persona@4.24.0/node_modules/@runtypelabs/persona/dist/codegen.js
 var j = "4.24.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/cli",
-  "version": "2.44.1",
+  "version": "2.45.0",
   "description": "Command-line interface for Runtype AI platform",
   "type": "module",
   "main": "dist/index.js",
@@ -11,7 +11,7 @@
     "@modelcontextprotocol/client": "2.0.0",
     "@modelcontextprotocol/core": "2.0.0",
     "@runtypelabs/ink-components": "0.3.9",
-    "@runtypelabs/sdk": "10.8.1",
+    "@runtypelabs/sdk": "10.9.0",
     "@runtypelabs/terminal-animations": "0.2.4",
     "add-mcp": "2.0.0",
     "chalk": "^5.3.0",
@@ -33,7 +33,7 @@
   "devDependencies": {
     "@modelcontextprotocol/server": "2.0.0",
     "@runtypelabs/persona": "4.24.0",
-    "@runtypelabs/shared": "3.68.2",
+    "@runtypelabs/shared": "3.69.0",
     "@types/express": "^5.0.6",
     "@types/micromatch": "^4.0.9",
     "@types/node": "^25.3.3",