@runtypelabs/cli 2.44.1 → 2.46.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
 
@@ -701,9 +743,8 @@ jobs:
           RUNTYPE_API_KEY: ${{ secrets.RUNTYPE_API_KEY }}
 ```
 
-An organization holds at most 50 active preview aliases and one agent at most 10.
-Creating one past either limit is refused with `PREVIEW_ALIAS_LIMIT`; archiving one
-frees the quota immediately.
+There is no limit on how many preview aliases an agent or organization holds.
+Archiving on pull-request close, as above, and the 14-day expiry retire them.
 
 #### Promoting between organizations
 

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 { 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);
@@ -8041,6 +8234,19 @@ const RUN_COMPLETENESS_VALUES = [
 /** Which lane produced the header: a Runtype-hosted run, or one exported into ingest. */
 const RUN_SOURCES = ["hosted", "ingested"];
 const RUN_KINDS = ["agent", "flow"];
+const runViaSchema = object({
+	kind: _enum([
+		"schedule",
+		"surface",
+		"api",
+		"mcp",
+		"cli",
+		"test",
+		"eval"
+	]).describe("One word for the way the run started."),
+	id: string().nullable().describe("The thing that started it: the schedule id (schedule), product surface id (surface), API key id (api), the acting user id (cli) or eval suite id (eval). Null for mcp and test, and for an api run whose header predates key stamping."),
+	label: string().nullable().describe("Its display name when the API could resolve one: schedule name, surface name, API key name as it was at dispatch, MCP client name, the acting user's first name, or eval suite name. Null when unresolved, for example a deleted schedule.")
+});
 /** The sentence every overlay field repeats, so absence is never read as `false`. */
 const ABSENT = "Absent means the overlay did not answer, which is not false and not null.";
 const str = (d) => string().nullable().describe(d);
@@ -8085,6 +8291,7 @@ object({
 	inlineDefinition: boolean().nullable().describe("True when the dispatch carried a complete inline agent definition (name and model) beside or instead of an agentId, so the run executed that inline config and no stored version; such a row stamps no agentVersionId. False when the run executed the saved definition by reference. NULL when the header states nothing: a flow run, a lane that resolves no agent definition, or a row that predates the field."),
 	requestedFlowId: string().max(128).nullish().describe(`The flow.id an inline /v1/dispatch named when the caller's organization does not own a flow with that id. Such a run executes as the "virtual" flow, so flowId reads "virtual" and this field carries the caller's id (control characters stripped, cut to 128 characters) so the caller can still recognise its runs. It is a label only: it grants nothing, is never used as a sender or resume identity, and is not a list filter; filter with flowId=virtual and match on this field. Absent when the run executed under the id it named.`),
 	test: boolean().nullable().meta({ deprecated: true }).describe("DEPRECATED: a derived alias of origin, kept for one release — read origin instead. True when the run came from the dashboard, i.e. origin === \"dashboard\"; NULL exactly when origin is NULL. It is never derived from storeResults, which defaults to false across the whole flow lane and which an API caller sets for its own privacy reasons: reading it as \"test\" labelled production runs as tests. A run whose header predates origin therefore reads NULL rather than claiming either answer."),
+	via: runViaSchema.nullish().describe("How the run started, for a Via column. Forward-only for schedule, api key, cli, mcp and eval detail: a header written before those stamps reads null, or falls back to the coarse origin/surface facts when they alone answer it. A label is a snapshot or a lookup and never authority; mcp, cli and sdk are self-declared by the client."),
 	stopReason: string().nullish().describe("Stop reason from the terminal frame."),
 	iterations: number$1().nullish().describe("Loop iterations from the terminal frame."),
 	inputPreview: string().nullish().describe(`The run's first user message, secret-scrubbed and cut to 160 characters, so a list can say what a run was asked to do without reading content. Absent means no input text is recorded for this run, which is not an empty message: the span store holds no run-level input at all, so a run with no control-plane row (a flow leg, a storeResults:false run) has none.`),
@@ -8135,6 +8342,8 @@ function runListCompactOmitSentence() {
 const RUN_LIST_VIEWS = ["compact", "full"];
 /** Whether the control-plane overlay runs for this page. */
 const RUN_LIST_OVERLAY_MODES = ["live", "none"];
+/** The most runs `includeCount` counts: a bounded probe, never a window-wide COUNT(*). */
+const RUN_LIST_COUNT_CAP = 1e3;
 /**
 * The three statuses a header COLUMN can answer. `queued`, `awaiting` and
 * `cancelled` are overlay-only, and filtering after the overlay would drop rows
@@ -8167,7 +8376,8 @@ object({
 	view: _enum(RUN_LIST_VIEWS).optional().describe(runListCompactOmitSentence()),
 	overlay: _enum(RUN_LIST_OVERLAY_MODES).optional().describe("live adds control-plane fields; defaults to live for a session, none for an API key."),
 	limit: string().optional().describe(`Page size, at most 100.`),
-	cursor: string().optional().describe("Keyset cursor from a previous page.")
+	cursor: string().optional().describe("Keyset cursor from a previous page."),
+	includeCount: string().optional().describe(`"true" adds pagination.totalCount and pagination.totalCountCapped: the number of runs matching this request's filters within its window, ignoring the cursor and limit, counted up to ${RUN_LIST_COUNT_CAP}. Past that the count stops at ${RUN_LIST_COUNT_CAP} and totalCountCapped is true, so read it as "more than ${RUN_LIST_COUNT_CAP}". Omitted, or any other value, the response carries neither field.`)
 });
 object({
 	kind: _enum([
@@ -12478,7 +12688,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 +12749,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 +14707,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 +14785,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 +14812,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 +14849,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 +18863,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 +22419,8 @@ _enum([
 	"saved_from_run",
 	"generated",
 	"imported",
-	"fpo"
+	"fpo",
+	"ensure"
 ]);
 /**
 * Where a saved_from_run case was forked from.
@@ -22919,7 +23190,9 @@ const capabilitySchema = object({
 	flow: flowDefinitionSchema.optional(),
 	agent: union([agentDefinitionSchema, agentDefinitionSchemaV2]).optional(),
 	existingFlowId: string().optional(),
-	existingAgentId: string().optional()
+	existingAgentId: string().optional(),
+	/** Whether the product link is enabled; omitted preserves the live value (new links start enabled). */
+	enabled: boolean().optional()
 }).refine((cap) => {
 	return [
 		cap.flow,
@@ -23098,6 +23371,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 +23388,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 +24377,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 +27457,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 +27501,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 +27553,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 +27573,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 +27601,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 +28210,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 +28812,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 +32027,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 +32823,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 +33498,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) {
@@ -46416,7 +46990,6 @@ function fail$2(headline, error) {
 	const message = error instanceof Error ? error.message : String(error);
 	console.error(chalk.red(headline));
 	console.error(chalk.red(message));
-	if (error instanceof AgentAliasPreviewLimitError) console.error(chalk.gray(`${error.active} of ${error.limit} preview aliases active for this ${error.scope}. Archive one with: runtype agents aliases archive <alias> --all`));
 	process.exit(1);
 }
 function describeAlias(row) {
@@ -46658,28 +47231,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 +47358,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 +47394,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 +48913,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 +50583,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 +50628,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 +52200,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.46.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.11.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.71.0",
     "@types/express": "^5.0.6",
     "@types/micromatch": "^4.0.9",
     "@types/node": "^25.3.3",