@kikimoradev/kcloud 1.0.4 → 1.1.0

package/dist/main.js

@@ -781,9 +781,13 @@ const errorCodes = Object.keys({
 	"runtime.monitor_draining": "conflict",
 	"runtime.monitor_limited": "conflict",
 	"runtime.monitor_check_unsupported": "rule_violation",
+	"runtime.task_deletion_unsupported": "rule_violation",
+	"task.not_found": "not_found",
+	"task.not_finished": "conflict",
 	"node.not_found": "not_found",
 	"node.name_taken": "conflict",
 	"node.offline": "rule_violation",
+	"node.outdated": "rule_violation",
 	"node.not_registered": "rule_violation",
 	"node.registration_invalid": "unauthenticated",
 	"node.registration_used": "conflict",
@@ -1235,10 +1239,16 @@ const agentEventSummarySchema = z.object({
 	durationMs: z.int().nullable(),
 	payload: z.record(z.string(), z.unknown())
 }).meta({ id: "AgentEventSummary" });
+const agentEventLimitSchema = z.coerce.number().int().min(1).max(500).default(200);
 z.object({
 	since: z.string().max(64).optional(),
-	limit: z.coerce.number().int().min(1).max(500).default(200)
+	limit: agentEventLimitSchema
 });
+z.object({
+	before: z.string().max(64).optional(),
+	limit: agentEventLimitSchema
+});
+pageSchema(agentEventSummarySchema).meta({ id: "LiveHistoryPage" });
 const taskStatuses = [
 	"pending",
 	"in_progress",
@@ -1247,6 +1257,13 @@ const taskStatuses = [
 	"cancelled"
 ];
 const taskStatusSchema = z.enum(taskStatuses);
+const finalTaskStatuses = [
+	"done",
+	"failed",
+	"cancelled"
+];
+const finalTaskStatusSchema = z.enum(finalTaskStatuses);
+const taskDeletionKikimoraVersion = "0.14.0";
 const maxTaskDescriptionLength = 4e3;
 const agentTaskSchema = z.object({
 	id: z.string(),
@@ -1262,15 +1279,31 @@ const agentTaskSchema = z.object({
 	startedAt: z.iso.datetime().nullable(),
 	finishedAt: z.iso.datetime().nullable()
 }).meta({ id: "AgentTask" });
+const agentTaskSourceSchema = z.enum(["worker", "projection"]);
+const agentTaskStaleReasonSchema = z.enum([
+	"unreachable",
+	"timeout",
+	"stopped"
+]).nullable();
+const taskCountsSchema = z.object({
+	pending: z.int().nonnegative(),
+	in_progress: z.int().nonnegative(),
+	done: z.int().nonnegative(),
+	failed: z.int().nonnegative(),
+	cancelled: z.int().nonnegative()
+}).meta({ id: "TaskCounts" });
 z.object({
 	items: z.array(agentTaskSchema),
-	source: z.enum(["worker", "projection"]),
-	staleReason: z.enum([
-		"unreachable",
-		"timeout",
-		"stopped"
-	]).nullable()
+	nextCursor: z.string().nullable(),
+	counts: taskCountsSchema.nullable(),
+	source: agentTaskSourceSchema,
+	staleReason: agentTaskStaleReasonSchema
 }).meta({ id: "AgentTaskList" });
+z.object({
+	task: agentTaskSchema,
+	source: agentTaskSourceSchema,
+	staleReason: agentTaskStaleReasonSchema
+}).meta({ id: "AgentTaskView" });
 z.object({
 	title: z.string().trim().min(1).max(200).optional(),
 	description: z.string().trim().min(1).max(maxTaskDescriptionLength)
@@ -1279,7 +1312,9 @@ z.object({
 	state: z.enum(["requested", "running"]),
 	cycle: z.int().nonnegative().nullable()
 }).meta({ id: "MonitorCheck" });
-z.object({ status: taskStatusSchema.optional() });
+cursorQuerySchema.extend({ status: taskStatusSchema.optional() });
+z.object({ status: finalTaskStatusSchema });
+z.object({ deleted: z.array(z.string()) }).meta({ id: "AgentTasksDeleted" });
 z.object({
 	id: idSchema,
 	taskId: z.string().min(1).max(128)
@@ -2030,6 +2065,7 @@ const auditActionSchema = z.enum([
 	"agent.action",
 	"agent.backup_requested",
 	"agent.restored",
+	"agent.tasks_deleted",
 	"platform.settings_updated",
 	"runtime.sessions_updated",
 	"platform.upgrade_requested",
@@ -5048,6 +5084,7 @@ const collect = async (page, { limit, all }) => {
 		cursor = next.nextCursor;
 	}
 	return {
+		...first,
 		items,
 		nextCursor: null
 	};
@@ -5511,42 +5548,67 @@ const streamOptions = {
 		default: false
 	},
 	since: { type: "string" },
+	before: { type: "string" },
 	limit: { type: "string" }
 };
 const streamUsage = [
 	...agentUsage,
 	["-f, --follow", "keep the stream open instead of leaving when the output stops"],
 	["--since <id>", "start after this event instead of at the start of the buffer"],
-	["--limit <n>", "how many events to replay before the live ones"]
+	["--limit <n>", "how many events to replay before the live ones, or the page size with --before"]
 ];
-const lineOf = (frame) => {
-	const parsed = agentEventSummarySchema.safeParse(frame.data);
-	if (!parsed.success) return JSON.stringify(frame.data);
+const beforeUsage = ["--before <id>", "print the stored output before this event and leave, oldest first"];
+const linePrinter = (json) => (data) => {
+	if (json) return JSON.stringify(data);
+	const parsed = agentEventSummarySchema.safeParse(data);
+	if (!parsed.success) return JSON.stringify(data);
 	const event = parsed.data;
 	const text = "text" in event.payload && typeof event.payload.text === "string" ? event.payload.text : JSON.stringify(event.payload);
 	return `${event.ts} ${event.level.padEnd(5)} ${event.agentRole ?? "-"} ${event.event} ${text}`;
 };
+const earlierOutput = async (session, agentId, before, limit) => dataOf("read the earlier output of the agent", await session.api.GET("/agents/{id}/live/history", { params: {
+	path: { id: agentId },
+	query: {
+		before,
+		...limit === void 0 ? {} : { limit: Number(limit) }
+	}
+} }), agentHints);
+const olderPageCommand = (reference, project, cursor, limit) => [
+	"kcloud agents logs",
+	reference,
+	...project === void 0 ? [] : ["--project", project],
+	"--before",
+	cursor,
+	...limit === void 0 ? [] : ["--limit", limit]
+].join(" ");
 const streamCommands = (adaptersOf) => [{
 	name: "logs",
 	path: "/agents/{id}/live",
 	summary: "Print what the agent is writing, and keep printing with --follow.",
-	resumable: false
+	resumable: false,
+	pagesBack: true
 }, {
 	name: "events",
 	path: "/agents/{id}/events",
 	summary: "Print the stored events of the agent, and keep printing with --follow.",
-	resumable: true
-}].map(({ name, path, summary, resumable }) => defineCommand({
+	resumable: true,
+	pagesBack: false
+}].map(({ name, path, summary, resumable, pagesBack }) => defineCommand({
 	name,
 	summary,
-	usage: `agents ${name} <agent> [--project <name>] [--follow] [--since <id>] [--limit <n>]`,
-	optionsUsage: streamUsage,
+	usage: pagesBack ? `agents ${name} <agent> [--project <name>] [--follow] [--since <id>] [--before <id>] [--limit <n>]` : `agents ${name} <agent> [--project <name>] [--follow] [--since <id>] [--limit <n>]`,
+	optionsUsage: pagesBack ? [...streamUsage, beforeUsage] : streamUsage,
 	options: streamOptions,
 	positionals: {
 		min: 1,
 		max: 1
 	},
 	run: async ({ values, positionals, settings, context }) => {
+		const before = values.before;
+		if (before !== void 0 && !pagesBack) throw new UsageError("--before reads the output of kcloud agents logs alone.");
+		if (before !== void 0 && (values.follow || values.since !== void 0)) throw new UsageError("--before reads earlier output; leave out --follow and --since.");
+		const limit = values.limit;
+		if (limit !== void 0 && !/^[0-9]+$/u.test(limit)) throw new UsageError(`--limit ${limit} is not a whole number.`);
 		const adapters = adaptersOf(context);
 		const session = await openSession({
 			settings,
@@ -5555,8 +5617,17 @@ const streamCommands = (adaptersOf) => [{
 		});
 		const reference = positionals[0] ?? "";
 		const agentId = await resolveAgentId(session, reference, values.project);
-		const limit = values.limit;
-		if (limit !== void 0 && !/^[0-9]+$/u.test(limit)) throw new UsageError(`--limit ${limit} is not a whole number.`);
+		const lineOf = linePrinter(settings.json);
+		if (before !== void 0) {
+			const page = await earlierOutput(session, agentId, before, limit);
+			if (settings.json) {
+				context.terminal.line(JSON.stringify(page));
+				return exitCodes.ok;
+			}
+			for (const event of page.items) context.terminal.line(lineOf(event));
+			context.terminal.error(context.terminal.errorStyles.dim(page.nextCursor === null ? "The stored output begins here." : `older: ${olderPageCommand(reference, values.project, page.nextCursor, limit)}`));
+			return exitCodes.ok;
+		}
 		await streamFrames({
 			origin: session.origin,
 			token: session.token,
@@ -5575,7 +5646,7 @@ const streamCommands = (adaptersOf) => [{
 			},
 			onFrame: (frame) => {
 				if (frame.event === "agent.state") return;
-				context.terminal.line(settings.json ? JSON.stringify(frame.data) : lineOf(frame));
+				context.terminal.line(lineOf(frame.data));
 			}
 		});
 		return exitCodes.ok;
@@ -5585,7 +5656,10 @@ const streamCommands = (adaptersOf) => [{
 //#region src/commands/agents/tasks.ts
 const taskHints = {
 	...agentHints,
-	"runtime.control_unreachable": "The worker is not answering; kcloud agents show <agent> tells whether it runs."
+	"runtime.control_unreachable": "The worker is not answering; kcloud agents show <agent> tells whether it runs.",
+	"task.not_found": "kcloud agents tasks list <agent> shows the tasks of the agent.",
+	"task.not_finished": "Only done, failed and cancelled tasks can be deleted; kcloud agents tasks cancel <agent> <task> cancels a pending one.",
+	"runtime.task_deletion_unsupported": `Move the agent to Kikimora ${taskDeletionKikimoraVersion} or newer with kcloud agents set, then kcloud agents update.`
 };
 const tasksCommand = (adaptersOf) => defineGroup({
 	name: "tasks",
@@ -5595,11 +5669,21 @@ const tasksCommand = (adaptersOf) => defineGroup({
 		defineCommand({
 			name: "list",
 			summary: "List the tasks of an agent.",
-			usage: "agents tasks list <agent> [--project <name>] [--status <status>]",
-			optionsUsage: [...agentUsage, ["--status <status>", `one of ${taskStatuses.join(", ")}`]],
+			usage: "agents tasks list <agent> [--project <name>] [--status <status>] [--limit <n>] [--all]",
+			optionsUsage: [
+				...agentUsage,
+				["--status <status>", `one of ${taskStatuses.join(", ")}`],
+				["--limit <n>", `how many tasks, newest first (default: 50)`],
+				["--all", "follow the cursor to the end instead of one page"]
+			],
 			options: {
 				...agentOption,
-				status: { type: "string" }
+				status: { type: "string" },
+				limit: { type: "string" },
+				all: {
+					type: "boolean",
+					default: false
+				}
 			},
 			positionals: {
 				min: 1,
@@ -5611,10 +5695,14 @@ const tasksCommand = (adaptersOf) => defineGroup({
 				const given = invocation.values.status;
 				const status = taskStatuses.find((candidate) => candidate === given);
 				if (given !== void 0 && status === void 0) throw new UsageError(`--status ${given} is not a status of a task.`, `The statuses are ${taskStatuses.join(", ")}.`);
-				const listed = dataOf("list the tasks of the agent", await run.api.GET("/agents/{id}/tasks", { params: {
+				const listed = await collect(async (cursor, limit) => dataOf("list the tasks of the agent", await run.api.GET("/agents/{id}/tasks", { params: {
 					path: { id: agentId },
-					...status === void 0 ? {} : { query: { status } }
-				} }), taskHints);
+					query: {
+						limit,
+						...cursor === null ? {} : { cursor },
+						...status === void 0 ? {} : { status }
+					}
+				} }), taskHints), windowOf(invocation.values.limit, invocation.values.all));
 				return printed(run, listed, (page) => page.items.length === 0 ? "The agent has no task in its queue." : renderTable([
 					{ header: "STATUS" },
 					{ header: "TITLE" },
@@ -5627,12 +5715,42 @@ const tasksCommand = (adaptersOf) => defineGroup({
 				], page.items.map((task) => [
 					task.status,
 					task.title,
-					`${String(task.attempt)}/${String(task.maxAttempts)}`,
+					task.attempt === null ? "-" : task.maxAttempts === null ? String(task.attempt) : `${String(task.attempt)}/${String(task.maxAttempts)}`,
 					task.costUsd === null ? "-" : task.costUsd.toFixed(2),
 					task.id
 				])));
 			}
 		}),
+		defineCommand({
+			name: "show",
+			summary: "Show one task of an agent with its description and error.",
+			usage: "agents tasks show <agent> <task> [--project <name>]",
+			optionsUsage: agentUsage,
+			options: agentOption,
+			positionals: {
+				min: 2,
+				max: 2
+			},
+			run: async (invocation) => {
+				const run = await runOf(adaptersOf, invocation);
+				const agentId = await agentFrom(run, invocation.positionals[0], invocation.values.project);
+				const taskId = invocation.positionals[1] ?? "";
+				const view = dataOf("read the task", await run.api.GET("/agents/{id}/tasks/{taskId}", { params: { path: {
+					id: agentId,
+					taskId
+				} } }), taskHints);
+				return printed(run, view, ({ task }) => [
+					`${task.title} (${task.id})`,
+					`status   ${task.status}`,
+					`attempt  ${task.attempt === null ? "-" : String(task.attempt)}${task.maxAttempts === null ? "" : `/${String(task.maxAttempts)}`}`,
+					`created  ${task.createdAt ?? "-"}`,
+					`started  ${task.startedAt ?? "-"}`,
+					`finished ${task.finishedAt ?? "-"}`,
+					...task.error === null ? [] : [`error    ${task.error}`],
+					...task.description === null ? [] : ["", task.description]
+				].join("\n"));
+			}
+		}),
 		defineCommand({
 			name: "add",
 			summary: "Put a task in the queue of an agent.",
@@ -5712,9 +5830,50 @@ const tasksCommand = (adaptersOf) => defineGroup({
 				} } }), taskHints);
 				return said(run, `Cancelled the task ${taskId}.`);
 			}
+		}),
+		defineCommand({
+			name: "delete",
+			summary: "Delete a finished task, or every task of one final status.",
+			usage: "agents tasks delete <agent> <task> [--project <name>] | agents tasks delete <agent> --status <status> [--project <name>]",
+			optionsUsage: [...agentUsage, ["--status <status>", `one of ${finalTaskStatuses.join(", ")}`]],
+			options: {
+				...agentOption,
+				status: { type: "string" }
+			},
+			positionals: {
+				min: 1,
+				max: 2
+			},
+			run: async (invocation) => {
+				const taskId = invocation.positionals[1];
+				const given = invocation.values.status;
+				if (taskId === void 0 === (given === void 0)) throw new UsageError("agents tasks delete needs either a task or --status, not both.", "kcloud agents tasks delete <agent> <task> deletes one task.");
+				const status = finalTaskStatuses.find((candidate) => candidate === given);
+				if (given !== void 0 && status === void 0) throw new UsageError(`--status ${given} is not a final status of a task.`, `Only ${finalTaskStatuses.join(", ")} tasks can be deleted.`);
+				const run = await runOf(adaptersOf, invocation);
+				const agentId = await agentFrom(run, invocation.positionals[0], invocation.values.project);
+				await confirmed({
+					prompt: run.prompt,
+					settings: run.settings,
+					question: status === void 0 ? `Delete the task ${taskId ?? ""}?` : `Delete every ${status} task of the agent?${status === "done" ? " The monitor may report them again." : ""}`
+				});
+				const answer = dataOf("delete the tasks", status === void 0 ? await run.api.DELETE("/agents/{id}/tasks/{taskId}", { params: { path: {
+					id: agentId,
+					taskId: taskId ?? ""
+				} } }) : await run.api.DELETE("/agents/{id}/tasks", { params: {
+					path: { id: agentId },
+					query: { status }
+				} }), taskHints);
+				return printed(run, answer, ({ deleted }) => deletedSummary(deleted.length, status ?? null, taskId ?? null));
+			}
 		})
 	]
 });
+const deletedSummary = (count, status, taskId) => {
+	if (status === null) return `Deleted the task ${taskId ?? ""}.`;
+	if (count === 0) return `The agent has no ${status} task.`;
+	return `Deleted ${String(count)} ${status} ${count === 1 ? "task" : "tasks"}.`;
+};
 const descriptionOf = async (run, given) => {
 	if (given === "-") {
 		const chunks = [];
@@ -7220,6 +7379,25 @@ const observabilityTools = [
 			}
 		} }), agentHints)
 	}),
+	defineTool({
+		name: "agent_earlier_output",
+		title: "Read the earlier output of an agent",
+		description: "Read what an agent wrote before an event, oldest first: the newest page without before. Pass nextCursor as before to read the page before that; null means the stored output begins here.",
+		operations: ["listAgentLiveHistory"],
+		safety: "read",
+		input: z.object({
+			...agentFields,
+			before: z.string().trim().min(1).max(64).optional().describe("End the page before this event id."),
+			limit: z.int().min(1).max(500).optional().describe("How many events to read.")
+		}),
+		run: async ({ before, limit, ...reference }, run) => dataOf("read the earlier output of the agent", await run.api.GET("/agents/{id}/live/history", { params: {
+			path: { id: await agentIdOf(run, reference) },
+			query: {
+				...before === void 0 ? {} : { before },
+				...limit === void 0 ? {} : { limit }
+			}
+		} }), agentHints)
+	}),
 	defineTool({
 		name: "agent_events",
 		title: "Read the events of an agent",
@@ -8919,17 +9097,40 @@ const taskTools = [
 	defineTool({
 		name: "agent_tasks_list",
 		title: "List the tasks of an agent",
-		description: "List the task queue of an agent, with the status, attempts and cost of each task.",
+		description: "List the task queue of an agent, newest first, with the status, attempts and cost of each task.",
 		operations: ["listAgentTasks"],
 		safety: "read",
 		input: z.object({
 			...agentFields,
+			...pageFields,
 			status: z.enum(taskStatuses).optional()
 		}),
-		run: async ({ status, ...reference }, run) => dataOf("list the tasks of the agent", await run.api.GET("/agents/{id}/tasks", { params: {
-			path: { id: await agentIdOf(run, reference) },
-			...status === void 0 ? {} : { query: { status } }
-		} }), taskHints)
+		run: async ({ status, limit, all, ...reference }, run) => {
+			const agentId = await agentIdOf(run, reference);
+			return collect(async (cursor, size) => dataOf("list the tasks of the agent", await run.api.GET("/agents/{id}/tasks", { params: {
+				path: { id: agentId },
+				query: {
+					limit: size,
+					...cursor === null ? {} : { cursor },
+					...status === void 0 ? {} : { status }
+				}
+			} }), taskHints), windowOfPage({
+				limit,
+				all
+			}));
+		}
+	}),
+	defineTool({
+		name: "agent_task_show",
+		title: "Show a task",
+		description: "Read one task of an agent with its description, status, attempts, cost and error.",
+		operations: ["getAgentTask"],
+		safety: "read",
+		input: z.object(taskFields),
+		run: async ({ task, ...reference }, run) => dataOf("read the task", await run.api.GET("/agents/{id}/tasks/{taskId}", { params: { path: {
+			id: await agentIdOf(run, reference),
+			taskId: task
+		} } }), taskHints)
 	}),
 	defineTool({
 		name: "agent_task_add",
@@ -8979,6 +9180,33 @@ const taskTools = [
 			} } }), taskHints);
 			return { cancelled: task };
 		}
+	}),
+	defineTool({
+		name: "agent_task_delete",
+		title: "Delete a task",
+		description: "Delete a done, failed or cancelled task of an agent. A monitor may report a deleted done task again.",
+		operations: ["deleteAgentTask"],
+		safety: "destructive",
+		input: z.object(taskFields),
+		run: async ({ task, ...reference }, run) => dataOf("delete the task", await run.api.DELETE("/agents/{id}/tasks/{taskId}", { params: { path: {
+			id: await agentIdOf(run, reference),
+			taskId: task
+		} } }), taskHints)
+	}),
+	defineTool({
+		name: "agent_tasks_delete",
+		title: "Delete the tasks of a status",
+		description: "Delete every task of an agent with one final status: done, failed or cancelled. A monitor may report a deleted done task again.",
+		operations: ["deleteAgentTasks"],
+		safety: "destructive",
+		input: z.object({
+			...agentFields,
+			status: z.enum(finalTaskStatuses)
+		}),
+		run: async ({ status, ...reference }, run) => dataOf("delete the tasks", await run.api.DELETE("/agents/{id}/tasks", { params: {
+			path: { id: await agentIdOf(run, reference) },
+			query: { status }
+		} }), taskHints)
 	})
 ];
 //#endregion

package/package.json

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