@kikimoradev/kcloud 0.14.0 → 0.15.0

package/dist/main.js

@@ -988,6 +988,15 @@ const errorCodes = Object.keys({
 	"runtime.monitor_draining": "conflict",
 	"runtime.monitor_limited": "conflict",
 	"runtime.monitor_check_unsupported": "rule_violation",
+	"node.not_found": "not_found",
+	"node.name_taken": "conflict",
+	"node.offline": "rule_violation",
+	"node.not_registered": "rule_violation",
+	"node.registration_invalid": "unauthenticated",
+	"node.registration_used": "conflict",
+	"node.in_use": "conflict",
+	"project.last_admin": "conflict",
+	"agent.node_unassigned": "rule_violation",
 	"stream.too_many": "rate_limited",
 	"infrastructure.not_configured": "rule_violation",
 	"infrastructure.provider_error": "internal",
@@ -1329,7 +1338,8 @@ z.object({
 	unavailableReason: z.enum([
 		"not_found",
 		"tampered",
-		"too_large"
+		"too_large",
+		"node_offline"
 	]).nullable(),
 	truncated: z.boolean()
 }).meta({ id: "TranscriptPage" });
@@ -1392,6 +1402,109 @@ pageSchema(z.object({
 	finishedAt: z.iso.datetime().nullable()
 }).meta({ id: "TaskCost" })).meta({ id: "TaskCostPage" });
 costQuerySchema.extend({ cursor: cursorSchema.optional() });
+const nodeStateSchema = z.enum([
+	"pending",
+	"online",
+	"offline"
+]);
+const nodeProviderSchema = z.enum(["self_hosted"]);
+const nodeNameSchema = z.string().trim().regex(slugPattern);
+const nodeHostSchema = z.object({
+	cpus: z.number().nonnegative(),
+	memoryBytes: z.number().nonnegative(),
+	dataRoot: z.string(),
+	serverVersion: z.string()
+}).meta({ id: "NodeHost" });
+const nodeCapabilitiesSchema = z.object({
+	sandbox: z.boolean(),
+	uidIsolation: z.boolean()
+}).meta({ id: "NodeCapabilities" });
+const nodeSchema = z.object({
+	id: idSchema,
+	name: nodeNameSchema,
+	provider: nodeProviderSchema,
+	state: nodeStateSchema,
+	engine: z.enum(runtimeEngineKinds).nullable(),
+	version: z.string().nullable(),
+	host: nodeHostSchema.nullable(),
+	capabilities: nodeCapabilitiesSchema.nullable(),
+	agentCount: z.int().nonnegative(),
+	connectedAt: z.iso.datetime().nullable(),
+	lastSeenAt: z.iso.datetime().nullable(),
+	registrationExpiresAt: z.iso.datetime().nullable(),
+	createdAt: z.iso.datetime()
+}).meta({ id: "Node" });
+const nodeAgentSchema = z.object({
+	id: idSchema,
+	name: z.string(),
+	slug: z.string(),
+	projectId: idSchema,
+	projectName: z.string(),
+	state: agentStateSchema
+}).meta({ id: "NodeAgent" });
+const nodeRuntimeSchema = z.object({
+	reportedAt: z.iso.datetime(),
+	docker: z.object({
+		state: z.enum([
+			"ok",
+			"unavailable",
+			"disabled",
+			"adopting"
+		]),
+		lastError: z.string().nullable()
+	}),
+	storage: z.object({
+		data: storageStateSchema,
+		engine: storageStateSchema
+	}),
+	reconcile: z.object({
+		lastTickAt: z.iso.datetime().nullable(),
+		lastTickError: z.string().nullable(),
+		agentsQueued: z.int().nonnegative(),
+		agentsActive: z.int().nonnegative()
+	}),
+	ingest: z.object({ readers: z.int().nonnegative() }),
+	sessions: z.object({
+		monitor: z.object({
+			effective: z.int().nonnegative(),
+			inUse: z.int().nonnegative()
+		}),
+		executor: z.object({
+			effective: z.int().nonnegative(),
+			inUse: z.int().nonnegative()
+		})
+	})
+}).meta({ id: "NodeRuntime" });
+nodeSchema.extend({
+	agents: z.array(nodeAgentSchema),
+	runtime: nodeRuntimeSchema.nullable()
+}).meta({ id: "NodeDetail" });
+z.object({ items: z.array(nodeSchema) }).meta({ id: "NodeList" });
+z.object({ nodeId: idSchema });
+z.object({
+	organizationId: idSchema,
+	nodeId: idSchema
+});
+const createNodeBodySchema = z.object({ name: nodeNameSchema }).meta({ id: "CreateNodeBody" });
+const nodeRegistrationSchema = z.object({
+	token: z.string(),
+	expiresAt: z.iso.datetime()
+}).meta({ id: "NodeRegistration" });
+z.object({
+	node: nodeSchema,
+	registration: nodeRegistrationSchema
+}).meta({ id: "CreatedNode" }).meta({ id: "RenewedNodeRegistration" });
+z.object({
+	token: z.string().min(1).max(256),
+	version: z.string().min(1).max(128),
+	engine: z.enum(runtimeEngineKinds),
+	host: nodeHostSchema.nullable(),
+	capabilities: nodeCapabilitiesSchema
+}).meta({ id: "RegisterNodeBody" });
+z.object({
+	nodeId: idSchema,
+	credential: z.string()
+}).meta({ id: "RegisteredNode" });
 //#endregion
 //#region ../../packages/contracts/src/identity.ts
 const emailSchema = z.email().max(254);
@@ -1575,6 +1688,10 @@ const auditActionSchema = z.enum([
 	"node.volume_resized",
 	"node.quiesced",
 	"node.resumed",
+	"node.created",
+	"node.registered",
+	"node.registration_renewed",
+	"node.deleted",
 	"master_key.reencrypted",
 	"dead_letter.retried",
 	"dead_letter.discarded"
@@ -1594,7 +1711,8 @@ const auditTargetTypeSchema = z.enum([
 	"backup",
 	"host_operation",
 	"volume",
-	"queue"
+	"queue",
+	"node"
 ]);
 const auditEntrySchema = z.object({
 	id: idSchema,
@@ -2116,6 +2234,11 @@ const agentListItemSchema = z.object({
 	availableActions: z.array(agentActionSchema),
 	updatedAt: z.iso.datetime()
 }).meta({ id: "AgentListItem" });
+const agentNodeSchema = z.object({
+	id: idSchema,
+	name: nodeNameSchema,
+	state: nodeStateSchema
+}).meta({ id: "AgentNode" });
 agentListItemSchema.extend({
 	version: z.int().nonnegative(),
 	description: z.string(),
@@ -2130,6 +2253,7 @@ agentListItemSchema.extend({
 	toolAssignments: z.array(agentToolSchema),
 	release: releaseSummarySchema.nullable(),
 	runtime: agentRuntimeSchema,
+	node: agentNodeSchema.nullable(),
 	runtimeUid: z.int().positive().nullable(),
 	sandbox: agentSandboxSchema.nullable(),
 	createdAt: z.iso.datetime()
@@ -2152,6 +2276,7 @@ const createAgentBodySchema = z.object({
 	slug: slugSchema.optional(),
 	description: agentDescriptionSchema,
 	kikimoraVersion: kikimoraVersionSchema,
+	nodeId: idSchema,
 	claudeCredentialId: idSchema,
 	githubCredentialId: idSchema,
 	repositories: agentRepositoryLinksSchema,
@@ -2423,7 +2548,7 @@ z.object({
 		pending: z.array(idSchema)
 	}),
 	capacity: capacityForecastSchema
-}).meta({ id: "Node" });
+}).meta({ id: "PlatformNode" });
 z.object({ role: volumeRoleSchema });
 z.object({ sizeGb: z.int().positive() }).meta({ id: "ResizeVolumeBody" });
 z.object({ agents: z.int().nonnegative() }).meta({ id: "QuiesceResult" });
@@ -2529,6 +2654,7 @@ z.object({
 	version: z.string(),
 	apiImage: installedImageSchema,
 	webImage: installedImageSchema,
+	nodeImage: installedImageSchema,
 	latest: z.string().nullable(),
 	latestError: registryUnavailableSchema.nullable(),
 	versions: z.array(z.string()),
@@ -2619,11 +2745,16 @@ const agentUsageSchema = z.object({
 	blockReadBytes: byteCountSchema,
 	blockWriteBytes: byteCountSchema
 }).meta({ id: "AgentUsage" });
+const nodeHostSeriesSchema = z.object({
+	nodeId: idSchema,
+	nodeName: z.string(),
+	points: z.array(hostPointSchema)
+}).meta({ id: "NodeHostSeries" });
 z.object({
 	resolution: metricsResolutionSchema,
 	from: instantSchema,
 	to: instantSchema,
-	host: z.array(hostPointSchema),
+	nodes: z.array(nodeHostSeriesSchema),
 	agents: z.array(agentUsageSchema)
 }).meta({ id: "HostMetrics" });
 z.object({
@@ -2712,7 +2843,11 @@ z.strictObject({ label: textParam }), z.strictObject({
 }), z.strictObject({
 	agentName: textParam,
 	failureCount: countParam
-}), z.strictObject({ agentName: textParam }), z.strictObject({ ratio: ratioParam }), z.strictObject({
+}), z.strictObject({ agentName: textParam }), z.strictObject({
+	node: textParam,
+	ratio: ratioParam
+}), z.strictObject({
+	node: textParam,
 	filesystem: filesystemNameSchema,
 	ratio: ratioParam
 }), z.strictObject({ backupKind: backupKindSchema }), z.strictObject({ hours: z.int().positive() }), z.strictObject({
@@ -3418,7 +3553,8 @@ const agentHints = {
 	"project.not_found": "kcloud projects list shows the projects you are a member of.",
 	"agent.invalid_transition": "kcloud agents show <agent> lists the actions it takes now.",
 	"agent.busy": "The agent is working on another action; try again in a moment.",
-	"concurrency.conflict": "Someone changed the agent meanwhile; read it again and retry."
+	"concurrency.conflict": "Someone changed the agent meanwhile; read it again and retry.",
+	"node.offline": "The node of the agent is not connected; kcloud nodes show <node> tells when it was last seen."
 };
 const agentFrom = async (run, reference, project) => {
 	if (reference === void 0 || reference === "") throw new UsageError("This command needs an agent.", "Name it as <project>/<agent>, or pass --project.");
@@ -3497,6 +3633,7 @@ const agentPlanOf = (agent) => ({
 	slug: agent.slug,
 	description: agent.description,
 	kikimoraVersion: agent.kikimoraVersion,
+	...agent.node === null ? {} : { nodeId: agent.node.id },
 	claudeCredentialId: agent.claudeCredential.id,
 	githubCredentialId: agent.githubCredential.id,
 	repositories: agent.repositories.map(({ repositoryId, directory }) => ({
@@ -3675,6 +3812,7 @@ const detailsOf = (agent) => [
 		["wanted", agent.desiredState],
 		["observed", agent.observedState],
 		["release", agent.kikimoraVersion],
+		["node", agent.node === null ? "none" : `${agent.node.name} (${agent.node.state})`],
 		["timezone", agent.timezone],
 		["machine", `${agent.machine.cpus} vCPU, ${agent.machine.memoryMb} MB`],
 		["docker", agent.machine.docker ? "yes" : "no"],
@@ -3699,6 +3837,272 @@ const detailsOf = (agent) => [
 	]))
 ].join("\n");
 //#endregion
+//#region src/commands/nodes.ts
+const nodeHints = {
+	...organizationHints,
+	"node.not_found": "kcloud nodes list shows the nodes of the organization.",
+	"node.name_taken": "Another node of the organization has that name.",
+	"node.in_use": "Delete the agents placed on it first; kcloud nodes show <node> lists them.",
+	"node.registration_used": "The node has joined and holds its own credential; it needs no token."
+};
+const nodesOf = async (api, organizationId) => dataOf("list the nodes", await api.GET("/organizations/{organizationId}/nodes", { params: { path: { organizationId } } }), nodeHints).items;
+const namesOf = (nodes) => nodes.map(({ name }) => name).join(", ");
+const nodeIn = (nodes, reference, organization) => {
+	const found = nodes.find((node) => node.id === reference.toLowerCase() || node.name === reference);
+	if (found === void 0) throw new CliError(`There is no node ${reference} in ${organization}.`, nodes.length === 0 ? "kcloud nodes create <name> creates one." : `kcloud nodes list shows ${namesOf(nodes)}.`);
+	return found;
+};
+const resolveNode = async (scope, reference) => {
+	const organization = await scope.organization();
+	if (isId(reference)) return {
+		organizationId: organization.id,
+		nodeId: reference
+	};
+	const node = nodeIn(await nodesOf(scope.api, organization.id), reference, organization.slug);
+	return {
+		organizationId: organization.id,
+		nodeId: node.id
+	};
+};
+const nodeDetailOf = async (api, { organizationId, nodeId }) => dataOf("describe the node", await api.GET("/organizations/{organizationId}/nodes/{nodeId}", { params: { path: {
+	organizationId,
+	nodeId
+} } }), nodeHints);
+const createdNode = async (api, organizationId, name) => {
+	const body = { name };
+	validated(createNodeBodySchema, body, "a node");
+	return dataOf("create the node", await api.POST("/organizations/{organizationId}/nodes", {
+		params: { path: { organizationId } },
+		body
+	}), nodeHints);
+};
+const renewedRegistration = async (api, { organizationId, nodeId }) => dataOf("issue a registration token for the node", await api.POST("/organizations/{organizationId}/nodes/{nodeId}/registration", { params: { path: {
+	organizationId,
+	nodeId
+} } }), nodeHints);
+const deleteNode = async (api, { organizationId, nodeId }) => {
+	doneWith("delete the node", await api.DELETE("/organizations/{organizationId}/nodes/{nodeId}", { params: { path: {
+		organizationId,
+		nodeId
+	} } }), nodeHints);
+};
+const gibibytes = (bytes) => `${(bytes / 1024 ** 3).toFixed(1)} GiB`;
+const hostOf = (node) => node.host === null ? "-" : `${node.host.cpus} CPU, ${gibibytes(node.host.memoryBytes)} of memory`;
+const capabilitiesOf = (node) => {
+	if (node.capabilities === null) return "-";
+	const { sandbox, uidIsolation } = node.capabilities;
+	return `sandbox ${sandbox ? "yes" : "no"}, uid isolation ${uidIsolation ? "yes" : "no"}`;
+};
+const registrationOf = (node) => node.registrationExpiresAt === null ? "-" : `a token waits until ${node.registrationExpiresAt}`;
+const storageOf = ({ state, freeBytes, totalBytes, path }) => `${state}, ${gibibytes(freeBytes)} free of ${gibibytes(totalBytes)} at ${path}`;
+const runtimeRowsOf = (runtime) => [
+	["reported", runtime.reportedAt],
+	["docker", runtime.docker.lastError === null ? runtime.docker.state : `${runtime.docker.state}: ${runtime.docker.lastError}`],
+	["data storage", storageOf(runtime.storage.data)],
+	["engine storage", storageOf(runtime.storage.engine)],
+	["last reconcile", runtime.reconcile.lastTickError === null ? runtime.reconcile.lastTickAt ?? "never" : `${runtime.reconcile.lastTickAt ?? "never"}: ${runtime.reconcile.lastTickError}`],
+	["agents", `${runtime.reconcile.agentsActive} active, ${runtime.reconcile.agentsQueued} queued`],
+	["monitor slots", `${runtime.sessions.monitor.inUse} of ${runtime.sessions.monitor.effective} in use`],
+	["executor slots", `${runtime.sessions.executor.inUse} of ${runtime.sessions.executor.effective} in use`],
+	["log readers", String(runtime.ingest.readers)]
+];
+const nodeDetailsText = (node) => [
+	renderTable([{ header: "FIELD" }, { header: "VALUE" }], [
+		["name", node.name],
+		["state", node.state],
+		["provider", node.provider],
+		["engine", node.engine ?? "-"],
+		["version", node.version ?? "-"],
+		["host", hostOf(node)],
+		["server", node.host?.serverVersion ?? "-"],
+		["data root", node.host?.dataRoot ?? "-"],
+		["capabilities", capabilitiesOf(node)],
+		["registration", registrationOf(node)],
+		["connected", node.connectedAt ?? "never"],
+		["last seen", node.lastSeenAt ?? "never"],
+		["created", node.createdAt],
+		["id", node.id]
+	]),
+	"",
+	node.agents.length === 0 ? "No agent is placed on the node." : renderTable([
+		{ header: "PROJECT" },
+		{ header: "AGENT" },
+		{ header: "STATE" },
+		{ header: "ID" }
+	], node.agents.map((agent) => [
+		agent.projectName,
+		agent.slug,
+		agent.state,
+		agent.id
+	])),
+	"",
+	node.runtime === null ? "The node has reported no runtime yet." : renderTable([{ header: "RUNTIME" }, { header: "VALUE" }], runtimeRowsOf(node.runtime))
+].join("\n");
+const startHintOf = (origin) => [
+	"Start the node with it as docs/install.md of kikimora-cloud describes. On a Linux host, after read -rs token:",
+	`  printf '%s\\n' "$token" | /opt/kikimora-cloud/infra/node/install.sh --platform-url ${origin} --image ghcr.io/kikimoradev/kikimora-cloud/node:<version> --registration-token -`,
+	"On a Windows PC:",
+	`  C:\\kikimora-cloud\\src\\infra\\windows\\install.ps1 -PlatformUrl ${origin} -RegistrationToken <token>`
+].join("\n");
+const printedRegistration = (run, created) => {
+	if (run.settings.json) {
+		run.context.terminal.json(created);
+		return exitCodes.ok;
+	}
+	run.context.terminal.line(created.registration.token);
+	run.context.terminal.error([`The registration token of ${created.node.name} is shown only here and works once, until ${created.registration.expiresAt}.`, startHintOf(run.origin)].join("\n"));
+	return exitCodes.ok;
+};
+const nodeUsage = [["", "a node is named by its name or its id"]];
+const createNodesCommand = (adaptersOf) => defineGroup({
+	name: "nodes",
+	summary: "The nodes of the organization, the hosts its agents run on.",
+	usage: "nodes <command>",
+	subcommands: [
+		defineCommand({
+			name: "list",
+			summary: "List the nodes of the organization.",
+			usage: "nodes list",
+			options: {},
+			positionals: {
+				min: 0,
+				max: 0
+			},
+			run: async (invocation) => {
+				const run = await runOf(adaptersOf, invocation);
+				const organization = await run.organization();
+				const items = await nodesOf(run.api, organization.id);
+				return printed(run, items, (nodes) => nodes.length === 0 ? `${organization.slug} has no node yet; kcloud nodes create <name> creates one.` : renderTable([
+					{ header: "NAME" },
+					{ header: "STATE" },
+					{ header: "ENGINE" },
+					{ header: "VERSION" },
+					{
+						header: "AGENTS",
+						align: "right"
+					},
+					{ header: "LAST SEEN" },
+					{ header: "ID" }
+				], nodes.map((node) => [
+					node.name,
+					node.state,
+					node.engine ?? "-",
+					node.version ?? "-",
+					String(node.agentCount),
+					node.lastSeenAt ?? "never",
+					node.id
+				])));
+			}
+		}),
+		defineCommand({
+			name: "show",
+			summary: "Show a node with its host, the agents placed on it and its runtime.",
+			usage: "nodes show <node>",
+			optionsUsage: nodeUsage,
+			options: {},
+			positionals: {
+				min: 1,
+				max: 1
+			},
+			run: async (invocation) => {
+				const run = await runOf(adaptersOf, invocation);
+				const reference = await resolveNode(run, invocation.positionals[0] ?? "");
+				return printed(run, await nodeDetailOf(run.api, reference), nodeDetailsText);
+			}
+		}),
+		defineCommand({
+			name: "create",
+			summary: "Create a node and print its one-time registration token.",
+			usage: "nodes create <name>",
+			optionsUsage: [["", "the name holds lowercase letters, digits and hyphens"], ["", "the token goes to stdout alone, how to start the node to stderr"]],
+			options: {},
+			positionals: {
+				min: 1,
+				max: 1
+			},
+			run: async (invocation) => {
+				const run = await runOf(adaptersOf, invocation);
+				const organization = await run.organization();
+				return printedRegistration(run, await createdNode(run.api, organization.id, invocation.positionals[0] ?? ""));
+			}
+		}),
+		defineCommand({
+			name: "token",
+			summary: "Issue a new registration token for a node that has not joined yet.",
+			usage: "nodes token <node>",
+			optionsUsage: [...nodeUsage, ["", "the token replaces the one issued before, which stops working"]],
+			options: {},
+			positionals: {
+				min: 1,
+				max: 1
+			},
+			run: async (invocation) => {
+				const run = await runOf(adaptersOf, invocation);
+				const reference = await resolveNode(run, invocation.positionals[0] ?? "");
+				return printedRegistration(run, await renewedRegistration(run.api, reference));
+			}
+		}),
+		defineCommand({
+			name: "delete",
+			summary: "Delete a node that runs no agent.",
+			usage: "nodes delete <node>",
+			optionsUsage: nodeUsage,
+			options: {},
+			positionals: {
+				min: 1,
+				max: 1
+			},
+			run: async (invocation) => {
+				const run = await runOf(adaptersOf, invocation);
+				const given = invocation.positionals[0] ?? "";
+				const reference = await resolveNode(run, given);
+				await confirmed({
+					prompt: run.prompt,
+					settings: run.settings,
+					question: `Delete the node ${given}? Its host can no longer reach the platform.`
+				});
+				await deleteNode(run.api, reference);
+				return said(run, `Deleted the node ${given}.`);
+			}
+		})
+	]
+});
+//#endregion
+//#region src/commands/projects/shared.ts
+const defaultProjectColor = "#7c86ff";
+const projectHint = {
+	"project.not_found": "kcloud projects list shows the projects you are a member of.",
+	"project.slug_taken": "Another project of the organization has that slug.",
+	"project.invalid_slug": "A slug holds lowercase letters, digits and hyphens.",
+	"project.not_empty": "Delete its agents, credentials, repositories and tools first.",
+	"project.member_not_found": "kcloud projects members list <project> shows them.",
+	"project.member_must_be_active": "kcloud orgs members enable <member> enables the account first."
+};
+const projectOf = async (api, id) => dataOf("describe the project", await api.GET("/projects/{id}", { params: { path: { id } } }), projectHint);
+//#endregion
+//#region src/commands/agents/placement.ts
+const placedNodeId = async (run, { projectId, given, ask }) => {
+	const project = await projectOf(run.api, projectId);
+	const organization = `the organization of ${project.slug}`;
+	const nodes = await nodesOf(run.api, project.organizationId);
+	if (given !== void 0) return nodeIn(nodes, given, organization).id;
+	const [only, ...others] = nodes;
+	if (only === void 0) throw new CliError(`The organization of ${project.slug} has no node to run the agent on.`, "kcloud nodes create <name> creates one, and its host joins with the token it prints.");
+	if (others.length === 0) {
+		run.context.terminal.error(`The agent runs on ${only.name}, the only node of ${organization}.`);
+		return only.id;
+	}
+	if (ask) return run.prompt.select({
+		message: "The node it runs on",
+		choices: nodes.map((node) => ({
+			value: node.id,
+			label: node.name,
+			hint: node.state
+		}))
+	});
+	throw new UsageError(`agents create needs --node <name>, because ${organization} has ${nodes.length} nodes.`, `The nodes are ${nodes.map(({ name }) => name).join(", ")}.`);
+};
+//#endregion
 //#region src/commands/agents/create.ts
 const claudeKinds = /* @__PURE__ */ new Set(["anthropic_api_key", "claude_oauth_token"]);
 const catalogueOf = async (api, projectId) => {
@@ -3802,6 +4206,11 @@ const promptText = async (run, file, question) => {
 };
 const localTimezone = () => Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
 const askedPlan = async (run, projectId, values) => {
+	const nodeId = await placedNodeId(run, {
+		projectId,
+		given: values.node,
+		ask: !run.settings.yes
+	});
 	const catalogue = await catalogueOf(run.api, projectId);
 	const name = values.name ?? await run.prompt.text({
 		message: "The name of the agent",
@@ -3819,6 +4228,7 @@ const askedPlan = async (run, projectId, values) => {
 		name,
 		description: "",
 		kikimoraVersion: release,
+		nodeId,
 		claudeCredentialId: await chosenCredential(run.prompt, catalogue, (kind) => claudeKinds.has(kind), "The Claude credential it works with"),
 		githubCredentialId: await chosenCredential(run.prompt, catalogue, (kind) => kind === "github_pat", "The GitHub credential it clones with"),
 		repositories: [...await chosenRepositories(run.prompt, catalogue)],
@@ -3837,17 +4247,27 @@ const askedPlan = async (run, projectId, values) => {
 		}
 	};
 };
-const fileOf = async (run, file) => {
+const isObject = (document) => typeof document === "object" && document !== null && !Array.isArray(document);
+const fileOf = async (run, projectId, { file, node }) => {
 	const document = await documentOf(run, file);
-	validated(createAgentBodySchema, document, "an agent");
-	return document;
+	const placed = !isObject(document) || node === void 0 && "nodeId" in document ? document : {
+		...document,
+		nodeId: await placedNodeId(run, {
+			projectId,
+			given: node,
+			ask: false
+		})
+	};
+	validated(createAgentBodySchema, placed, "an agent");
+	return placed;
 };
 const createCommand = (adaptersOf) => defineCommand({
 	name: "create",
 	summary: "Create an agent from a file, from flags, or by asking step by step.",
-	usage: "agents create --project <name> [--file <path>] [--name <name>]",
+	usage: "agents create --project <name> [--node <node>] [--file <path>] [--name <name>]",
 	optionsUsage: [
 		["--project <name>", "the project that owns the agent"],
+		["--node <node>", "the node it runs on, by name or id; needed when the organization has several"],
 		["--file <path>", "the whole agent as JSON, or - to read stdin"],
 		["--name <name>", "the name of the agent, instead of asking"],
 		["--release <x.y.z>", "the Kikimora release it runs, instead of asking"],
@@ -3856,11 +4276,13 @@ const createCommand = (adaptersOf) => defineCommand({
 		["--timezone <zone>", "the timezone of the agent (default: this machine's)"],
 		["--docker", "give the agent a Docker sidecar, when the project allows it"],
 		["--browser", "give the agent a browser"],
-		["", "kcloud agents show <agent> --as-file prints what --file takes"]
+		["", "kcloud agents show <agent> --as-file prints what --file takes"],
+		["", "--node replaces the nodeId of the file"]
 	],
 	options: {
 		...fileOptions,
 		project: { type: "string" },
+		node: { type: "string" },
 		name: { type: "string" },
 		release: { type: "string" },
 		"monitor-prompt-file": { type: "string" },
@@ -3884,7 +4306,10 @@ const createCommand = (adaptersOf) => defineCommand({
 		const run = await runOf(adaptersOf, invocation);
 		if (values.project === void 0) throw new UsageError("agents create needs --project <name>.", "kcloud projects list shows the projects you are a member of.");
 		const projectId = await resolveProjectId(run, values.project);
-		const body = values.file === void 0 ? await askedPlan(run, projectId, values) : await fileOf(run, values.file);
+		const body = values.file === void 0 ? await askedPlan(run, projectId, values) : await fileOf(run, projectId, {
+			file: values.file,
+			node: values.node
+		});
 		const agent = dataOf("create the agent", await run.api.POST("/projects/{id}/agents", {
 			params: { path: { id: projectId } },
 			body
@@ -5204,7 +5629,7 @@ const agentTools = [
 	defineTool({
 		name: "agent_create",
 		title: "Create an agent",
-		description: "Create an agent in a project. The credentials, repositories and tools are named by the ids that credentials_list, repositories_list and tools_list return; agent_show with asPlan shows a complete example. The agent stays stopped until agent_action starts it.",
+		description: "Create an agent in a project. The node it runs on, the credentials, repositories and tools are named by the ids that nodes_list, credentials_list, repositories_list and tools_list return; agent_show with asPlan shows a complete example. The agent stays stopped until agent_action starts it.",
 		operations: ["createAgent"],
 		safety: "write",
 		input: z.object({
@@ -5369,6 +5794,42 @@ const credentialTools = [
 	})
 ];
 //#endregion
+//#region src/mcp/tools/nodes.ts
+const nodeField = z.string().trim().min(1).describe("The node, by its name or its id, from nodes_list.");
+const nodeTools = [
+	defineTool({
+		name: "nodes_list",
+		title: "List nodes",
+		description: "List the nodes of the organization this server acts in, the hosts its agents run on, with their state, engine, version and agent count.",
+		operations: ["listNodes"],
+		safety: "read",
+		input: z.object({}),
+		run: async (_, run) => nodesOf(run.api, (await run.organization()).id)
+	}),
+	defineTool({
+		name: "node_show",
+		title: "Show a node",
+		description: "Show one node with its host, its capabilities, the agents placed on it and the runtime it reported last.",
+		operations: ["getNode"],
+		safety: "read",
+		input: z.object({ node: nodeField }),
+		run: async ({ node }, run) => nodeDetailOf(run.api, await resolveNode(run, node))
+	}),
+	defineTool({
+		name: "node_delete",
+		title: "Delete a node",
+		description: "Delete a node, after which its host can no longer reach the platform. The instance refuses while agents are placed on it.",
+		operations: ["deleteNode"],
+		safety: "destructive",
+		input: z.object({ node: nodeField }),
+		run: async ({ node }, run) => {
+			const reference = await resolveNode(run, node);
+			await deleteNode(run.api, reference);
+			return { deleted: reference.nodeId };
+		}
+	})
+];
+//#endregion
 //#region src/commands/notifications.ts
 const notificationHints = { "notification.not_found": "kcloud notifications list shows them." };
 const createNotificationsCommand = (adaptersOf) => defineGroup({
@@ -6583,18 +7044,6 @@ const projectToolTools = [
 	})
 ];
 //#endregion
-//#region src/commands/projects/shared.ts
-const defaultProjectColor = "#7c86ff";
-const projectHint = {
-	"project.not_found": "kcloud projects list shows the projects you are a member of.",
-	"project.slug_taken": "Another project of the organization has that slug.",
-	"project.invalid_slug": "A slug holds lowercase letters, digits and hyphens.",
-	"project.not_empty": "Delete its agents, credentials, repositories and tools first.",
-	"project.member_not_found": "kcloud projects members list <project> shows them.",
-	"project.member_must_be_active": "kcloud orgs members enable <member> enables the account first."
-};
-const projectOf = async (api, id) => dataOf("describe the project", await api.GET("/projects/{id}", { params: { path: { id } } }), projectHint);
-//#endregion
 //#region src/commands/projects/members.ts
 const projectMembersOf = async (api, projectId) => dataOf("list the members of the project", await api.GET("/projects/{id}/members", { params: { path: { id: projectId } } }), projectHint).items;
 const resolveProjectMember = async (api, projectId, reference) => {
@@ -7400,6 +7849,7 @@ const kcloudTools = [
 	...credentialTools,
 	...repositoryTools,
 	...projectToolTools,
+	...nodeTools,
 	...agentTools,
 	...taskTools,
 	...observabilityTools,
@@ -7407,6 +7857,7 @@ const kcloudTools = [
 	...releaseTools
 ];
 const passwordPrinted = (what) => `a secret never passes through the context of a model, and kcloud prints ${what}`;
+passwordPrinted("the one-time registration token of the node");
 passwordPrinted("the temporary password of the new member"), passwordPrinted("the new temporary password");
 //#endregion
 //#region src/mcp/server.ts
@@ -7523,6 +7974,7 @@ const kcloudCommands = () => [
 	createCredentialsCommand(createAdapters),
 	createRepositoriesCommand(createAdapters),
 	createToolsCommand(createAdapters),
+	createNodesCommand(createAdapters),
 	createAgentsCommand(createAdapters),
 	createNotificationsCommand(createAdapters),
 	createReleasesCommand(createAdapters),

package/package.json

@@ -15,7 +15,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.14.0",
+  "version": "0.15.0",
   "dependencies": {
     "@clack/prompts": "1.8.1",
     "@modelcontextprotocol/server": "2.1.0",