@pantheon.ai/agents 0.3.0 → 0.3.1

package/README.md

@@ -49,6 +49,28 @@ To avoid running it twice, apply the rest of the file to `pantheon_agents`:
 sed '1d' src/db/schema/tidb.sql | mysql --host 127.0.0.1 --port 4000 -u root pantheon_agents
 ```
 
+## Versioned Migrations
+
+When schema changes across versions, add versioned migration SQL files under:
+
+- `src/db/migrations/tidb`
+- `src/db/migrations/db9`
+
+Example migration added in this version:
+
+- `src/db/migrations/tidb/20260304_0001_add_task_retry_columns.sql`
+- `src/db/migrations/db9/20260304_0001_add_task_retry_columns.sql`
+
+Apply manually:
+
+```bash
+# TiDB/MySQL
+mysql --host 127.0.0.1 --port 4000 -u root pantheon_agents < src/db/migrations/tidb/20260304_0001_add_task_retry_columns.sql
+
+# db9/PostgreSQL
+psql "$DATABASE_URL" -f src/db/migrations/db9/20260304_0001_add_task_retry_columns.sql
+```
+
 ## Developer Local Setup
 
 This section is only for developing this package locally.
@@ -136,6 +158,9 @@ pantheon-agents show-config <agent-name>
 pantheon-agents show-tasks --all
 pantheon-agents get-task <agent-name> <task-id>
 pantheon-agents cancel-task <agent-name> <task-id> [reason] --yes
+pantheon-agents retry-task <agent-name> <task-id> [reason] --yes
+pantheon-agents skill.sh
+pantheon-agents gen-migration-sql --provider tidb --from 0.3.0
 pantheon-agents delete-task <agent-name> <task-id>
 ```
 

package/dist/db/migrations/db9/20260304_0001_add_task_retry_columns.sql

@@ -0,0 +1,11 @@
+-- introduced_in: 0.3.1
+-- Add retry metadata and policy columns for db9/PostgreSQL.
+
+ALTER TABLE task
+  ADD COLUMN IF NOT EXISTS attempt_count INT NOT NULL DEFAULT 1;
+
+ALTER TABLE agent_project_config
+  ADD COLUMN IF NOT EXISTS max_retry_attempts INT NOT NULL DEFAULT 3;
+
+ALTER TABLE agent_project_config
+  ADD COLUMN IF NOT EXISTS retry_backoff_seconds INT NOT NULL DEFAULT 30;

package/dist/db/migrations/tidb/20260304_0001_add_task_retry_columns.sql

@@ -0,0 +1,9 @@
+-- introduced_in: 0.3.1
+-- Add retry metadata and policy columns for TiDB/MySQL.
+
+ALTER TABLE task
+  ADD COLUMN IF NOT EXISTS attempt_count INT NOT NULL DEFAULT 1;
+
+ALTER TABLE agent_project_config
+  ADD COLUMN IF NOT EXISTS max_retry_attempts INT NOT NULL DEFAULT 3,
+  ADD COLUMN IF NOT EXISTS retry_backoff_seconds INT NOT NULL DEFAULT 30;

package/dist/index.js

@@ -2,7 +2,8 @@
 import { createRequire } from "node:module";
 import { Command, InvalidArgumentError, createCommand } from "commander";
 import process$1 from "node:process";
-import * as fs from "node:fs";
+import * as fs$1 from "node:fs";
+import fs from "node:fs";
 import path from "node:path";
 import { multistream, pino, transport } from "pino";
 import { Kysely, MysqlDialect, PostgresDialect } from "kysely";
@@ -11,6 +12,7 @@ import z$1, { z } from "zod";
 import { createPool } from "mysql2";
 import readline from "node:readline/promises";
 import expandTilde from "expand-tilde";
+import { fileURLToPath } from "node:url";
 import blessed from "reblessed";
 import { inspect } from "node:util";
 import { parse } from "shell-quote";
@@ -85,7 +87,7 @@ var require_package = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 //#endregion
 //#region ../../node_modules/dotenv/lib/main.js
 var require_main = /* @__PURE__ */ __commonJSMin(((exports, module) => {
-	const fs$1 = __require("fs");
+	const fs$2 = __require("fs");
 	const path$1 = __require("path");
 	const os = __require("os");
 	const crypto = __require("crypto");
@@ -222,10 +224,10 @@ var require_main = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	function _vaultPath(options) {
 		let possibleVaultPath = null;
 		if (options && options.path && options.path.length > 0) if (Array.isArray(options.path)) {
-			for (const filepath of options.path) if (fs$1.existsSync(filepath)) possibleVaultPath = filepath.endsWith(".vault") ? filepath : `${filepath}.vault`;
+			for (const filepath of options.path) if (fs$2.existsSync(filepath)) possibleVaultPath = filepath.endsWith(".vault") ? filepath : `${filepath}.vault`;
 		} else possibleVaultPath = options.path.endsWith(".vault") ? options.path : `${options.path}.vault`;
 		else possibleVaultPath = path$1.resolve(process.cwd(), ".env.vault");
-		if (fs$1.existsSync(possibleVaultPath)) return possibleVaultPath;
+		if (fs$2.existsSync(possibleVaultPath)) return possibleVaultPath;
 		return null;
 	}
 	function _resolveHome(envPath) {
@@ -259,7 +261,7 @@ var require_main = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		let lastError;
 		const parsedAll = {};
 		for (const path of optionPaths) try {
-			const parsed = DotenvModule.parse(fs$1.readFileSync(path, { encoding }));
+			const parsed = DotenvModule.parse(fs$2.readFileSync(path, { encoding }));
 			DotenvModule.populate(parsedAll, parsed, options);
 		} catch (e) {
 			if (debug) _debug(`Failed to load ${path} ${e.message}`);
@@ -397,7 +399,7 @@ var require_cli_options = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 
 //#endregion
 //#region package.json
-var version = "0.2.2";
+var version = "0.3.0";
 
 //#endregion
 //#region src/db/db9.ts
@@ -427,8 +429,10 @@ const taskCommonSchema = z.object({
 	base_branch_id: z.uuid(),
 	parent_task_id: z.string().nullable().optional(),
 	config_version: z.number().int().positive().nullable().default(null),
+	attempt_count: z.coerce.number().int().positive().optional(),
 	cancel_reason: z.string().nullable().default(null),
-	queued_at: z.coerce.date()
+	queued_at: z.coerce.date(),
+	error: z.string().nullable().optional()
 });
 const taskItemSchema = z.discriminatedUnion("status", [
 	taskCommonSchema.extend({ status: z.literal("pending") }),
@@ -510,6 +514,7 @@ var TaskListProvider = class {
 			base_branch_id: params.base_branch_id,
 			parent_task_id: parentTaskId,
 			config_version: params.type === "reconfig" || params.type === "bootstrap" ? params.configVersion : null,
+			attempt_count: 1,
 			cancel_reason: null,
 			queued_at: /* @__PURE__ */ new Date()
 		});
@@ -630,6 +635,8 @@ var TaskListDb9Provider = class extends TaskListProvider {
 			"agent_project_config.config_version",
 			"agent_project_config.config_task_id",
 			"agent_project_config.concurrency",
+			"agent_project_config.max_retry_attempts",
+			"agent_project_config.retry_backoff_seconds",
 			"agent_project_config.role",
 			"agent_project_config.skills",
 			"agent_project_config.prototype_url",
@@ -646,6 +653,8 @@ var TaskListDb9Provider = class extends TaskListProvider {
 			"agent_project_config.config_version",
 			"agent_project_config.config_task_id",
 			"agent_project_config.concurrency",
+			"agent_project_config.max_retry_attempts",
+			"agent_project_config.retry_backoff_seconds",
 			"agent_project_config.role",
 			"agent_project_config.skills",
 			"agent_project_config.prototype_url",
@@ -653,16 +662,24 @@ var TaskListDb9Provider = class extends TaskListProvider {
 		]).select((eb) => eb.ref("task.status").$castTo().as("config_task_status")).where("agent_project_config.agent", "=", this.agentName).execute();
 	}
 	async setAgentConfig({ skills, ...config }) {
+		const maxRetryAttempts = config.max_retry_attempts ?? 3;
+		const retryBackoffSeconds = config.retry_backoff_seconds ?? 30;
 		await this.db.insertInto("agent_project_config").values({
 			agent: this.agentName,
 			skills: JSON.stringify(skills),
-			...config
+			...config,
+			max_retry_attempts: maxRetryAttempts,
+			retry_backoff_seconds: retryBackoffSeconds
 		}).execute();
 	}
 	async updateAgentConfig({ skills, ...config }) {
+		const maxRetryAttempts = config.max_retry_attempts;
+		const retryBackoffSeconds = config.retry_backoff_seconds;
 		const result = await this.db.updateTable("agent_project_config").set({
 			skills: JSON.stringify(skills),
-			...config
+			...config,
+			...maxRetryAttempts == null ? {} : { max_retry_attempts: maxRetryAttempts },
+			...retryBackoffSeconds == null ? {} : { retry_backoff_seconds: retryBackoffSeconds }
 		}).where("agent", "=", this.agentName).where("project_id", "=", config.project_id).executeTakeFirst();
 		if (Number(result.numUpdatedRows ?? 0) === 0) throw new Error(`No config found to update for agent ${this.agentName} and project ${config.project_id}.`);
 	}
@@ -704,13 +721,15 @@ var TaskListDb9Provider = class extends TaskListProvider {
 	}
 	async insertTask(taskItem) {
 		const { started_at, ended_at, queued_at, cancelled_at, ...rest } = taskItem;
+		const attemptCount = taskItem.attempt_count ?? 1;
 		const inserted = await this.db.insertInto("task").values({
 			agent: this.agentName,
 			started_at,
 			ended_at,
 			queued_at,
 			cancelled_at,
-			...rest
+			...rest,
+			attempt_count: attemptCount
 		}).returningAll().executeTakeFirstOrThrow();
 		return taskItemSchema.parse(inserted);
 	}
@@ -765,16 +784,24 @@ var TaskListTidbProvider = class extends TaskListProvider {
 		return await this.db.selectFrom("agent_project_config").innerJoin("task", "task.id", "agent_project_config.config_task_id").selectAll("agent_project_config").select((eb) => eb.ref("task.status").$castTo().as("config_task_status")).where("agent_project_config.agent", "=", this.agentName).execute();
 	}
 	async setAgentConfig({ skills, ...config }) {
+		const maxRetryAttempts = config.max_retry_attempts ?? 3;
+		const retryBackoffSeconds = config.retry_backoff_seconds ?? 30;
 		await this.db.insertInto("agent_project_config").values({
 			agent: this.agentName,
 			skills: JSON.stringify(skills),
-			...config
+			...config,
+			max_retry_attempts: maxRetryAttempts,
+			retry_backoff_seconds: retryBackoffSeconds
 		}).execute();
 	}
 	async updateAgentConfig({ skills, ...config }) {
+		const maxRetryAttempts = config.max_retry_attempts;
+		const retryBackoffSeconds = config.retry_backoff_seconds;
 		const result = await this.db.updateTable("agent_project_config").set({
 			skills: JSON.stringify(skills),
-			...config
+			...config,
+			...maxRetryAttempts == null ? {} : { max_retry_attempts: maxRetryAttempts },
+			...retryBackoffSeconds == null ? {} : { retry_backoff_seconds: retryBackoffSeconds }
 		}).where("agent", "=", this.agentName).where("project_id", "=", config.project_id).executeTakeFirst();
 		if (Number(result.numUpdatedRows ?? 0) === 0) throw new Error(`No config found to update for agent ${this.agentName} and project ${config.project_id}.`);
 	}
@@ -816,13 +843,15 @@ var TaskListTidbProvider = class extends TaskListProvider {
 	}
 	async insertTask(taskItem) {
 		const { started_at, ended_at, queued_at, cancelled_at, ...rest } = taskItem;
+		const attemptCount = taskItem.attempt_count ?? 1;
 		const { insertId } = await this.db.insertInto("task").values({
 			agent: this.agentName,
 			started_at,
 			ended_at,
 			queued_at,
 			cancelled_at,
-			...rest
+			...rest,
+			attempt_count: attemptCount
 		}).executeTakeFirstOrThrow();
 		return {
 			...taskItem,
@@ -1171,7 +1200,7 @@ const branchExecutionResultSchema = z.object({
 	status: z.string(),
 	status_text: z.string(),
 	branch_id: z.string(),
-	snap_id: z.string(),
+	snap_id: z.string().nullable(),
 	background_task_id: z.string().nullable(),
 	started_at: zodJsonDate,
 	last_polled_at: zodJsonDate,
@@ -1248,7 +1277,7 @@ const explorationResultSchema = z.object({
 			status: z.string(),
 			status_text: z.string().nullable(),
 			branch_id: z.string(),
-			snap_id: z.string(),
+			snap_id: z.string().nullable(),
 			background_task_id: z.string().nullable(),
 			started_at: zodJsonDate,
 			last_polled_at: zodJsonDate,
@@ -2057,7 +2086,65 @@ async function executeOnPantheon({ projectId, branchId, prompt, agent }) {
 //#endregion
 //#region src/core/task-list.ts
 const DEFAULT_CONCURRENCY = 1;
+const DEFAULT_MAX_RETRY_ATTEMPTS$1 = 3;
+const DEFAULT_RETRY_BACKOFF_SECONDS$1 = 30;
 const AUTO_RECONFIG_PROMPT = "Config outdated. Reconfigure this branch against the latest agent config.";
+function getTaskAttemptCount(task) {
+	if (Number.isInteger(task.attempt_count) && task.attempt_count > 0) return task.attempt_count;
+	return 1;
+}
+function getMaxRetryAttempts(config, logger) {
+	const configured = config.max_retry_attempts;
+	if (configured == null) return DEFAULT_MAX_RETRY_ATTEMPTS$1;
+	if (Number.isInteger(configured) && configured >= 0) return configured;
+	logger.warn("Invalid max_retry_attempts=%o for project %s; fallback to %d.", configured, config.project_id, DEFAULT_MAX_RETRY_ATTEMPTS$1);
+	return DEFAULT_MAX_RETRY_ATTEMPTS$1;
+}
+function getRetryBackoffSeconds(config, logger) {
+	const configured = config.retry_backoff_seconds;
+	if (configured == null) return DEFAULT_RETRY_BACKOFF_SECONDS$1;
+	if (Number.isInteger(configured) && configured > 0) return configured;
+	logger.warn("Invalid retry_backoff_seconds=%o for project %s; fallback to %d.", configured, config.project_id, DEFAULT_RETRY_BACKOFF_SECONDS$1);
+	return DEFAULT_RETRY_BACKOFF_SECONDS$1;
+}
+function getBackoffDelaySeconds(backoffBaseSeconds, nextAttemptCount) {
+	return backoffBaseSeconds * 2 ** (Math.max(1, nextAttemptCount - 1) - 1);
+}
+async function retryFailedTaskInPlace(provider, task, logger, options = {}) {
+	const config = await provider.getAgentConfig(task.project_id);
+	if (!config) {
+		logger.warn("Skip retry for task %s because project config %s is missing.", task.id, task.project_id);
+		return null;
+	}
+	const currentAttemptCount = getTaskAttemptCount(task);
+	const retriesUsed = Math.max(0, currentAttemptCount - 1);
+	const maxRetryAttempts = getMaxRetryAttempts(config, logger);
+	if (!options.ignoreRetryLimit && retriesUsed >= maxRetryAttempts) {
+		logger.info("Task %s reached max retries (%d). Keep failed status.", task.id, maxRetryAttempts);
+		return null;
+	}
+	const nextAttemptCount = currentAttemptCount + 1;
+	const now = Date.now();
+	const delaySeconds = options.immediate ? 0 : getBackoffDelaySeconds(getRetryBackoffSeconds(config, logger), nextAttemptCount);
+	const queuedAt = new Date(now + delaySeconds * 1e3);
+	const retriedTask = {
+		status: "pending",
+		id: task.id,
+		task: task.task,
+		type: task.type,
+		project_id: task.project_id,
+		base_branch_id: task.base_branch_id,
+		parent_task_id: task.parent_task_id ?? null,
+		config_version: task.config_version ?? null,
+		attempt_count: nextAttemptCount,
+		cancel_reason: task.cancel_reason ?? null,
+		queued_at: queuedAt,
+		error: task.error
+	};
+	await provider.updateTask(retriedTask);
+	logger.info("Requeued failed task %s for attempt %d at %s%s.", task.id, nextAttemptCount, queuedAt.toISOString(), options.reason ? ` (reason: ${options.reason})` : "");
+	return retriedTask;
+}
 function buildTaskPromptSequence(config, taskPrompt, taskType = "default") {
 	if (taskType === "bootstrap" && taskPrompt === "$setup") return [buildConfigSetupStep({
 		prototypeRepoUrl: config.prototype_url,
@@ -2144,6 +2231,8 @@ async function pollRunningTaskState(provider, state, logger) {
 	} else if (newStatus.state === "failed") {
 		logger.info(`Task failed on Branch[id = ${newStatus.branch.id},snap_id=${newStatus.branch.latest_snap_id}] with error: %s`, newStatus.error);
 		await provider.failTask(state, newStatus.error);
+		const failedTask = await provider.getTask(state.id);
+		if (failedTask?.status === "failed") await retryFailedTaskInPlace(provider, failedTask, logger.child({ name: `task:${state.id}:auto-retry` }));
 	}
 }
 function isTaskOutdated(task, config) {
@@ -2268,6 +2357,7 @@ async function startPendingTasksUpToConcurrency(provider, pendingTasks, runningT
 		return config;
 	};
 	for (const task of pendingTasks) {
+		if (task.queued_at.getTime() > Date.now()) continue;
 		const config = await getProjectConfig(task.project_id);
 		if (!config) {
 			if (!missingConfigProjects.has(task.project_id)) {
@@ -2284,6 +2374,8 @@ async function startPendingTasksUpToConcurrency(provider, pendingTasks, runningT
 			runningCountByProject.set(task.project_id, runningCount + 1);
 		} catch (e) {
 			logger.error(`Failed to start task ${task.id}: ${getErrorMessage(e)}`);
+			const failedTask = await provider.getTask(task.id);
+			if (failedTask?.status === "failed") await retryFailedTaskInPlace(provider, failedTask, logger.child({ name: `task:${task.id}:auto-retry` }));
 		}
 	}
 }
@@ -2713,10 +2805,12 @@ var WatchStepAggregator = class {
 
 //#endregion
 //#region src/core/index.ts
+const DEFAULT_MAX_RETRY_ATTEMPTS = 3;
+const DEFAULT_RETRY_BACKOFF_SECONDS = 30;
 async function runAgent(name, options, logger) {
 	const agentDir = path.join(options.dataDir, "agents", name);
 	const pidFile = path.join(agentDir, "pid");
-	await fs.promises.mkdir(agentDir, { recursive: true });
+	await fs$1.promises.mkdir(agentDir, { recursive: true });
 	await assertsSingleton(logger, pidFile);
 	await startTaskListLoop(name, { loopInterval: options.loopInterval }, logger);
 }
@@ -2749,6 +2843,18 @@ async function configAgent(name, options) {
 			process.exitCode = 1;
 			return;
 		}
+		const maxRetryAttempts = options.maxRetryAttempts ?? previousConfig?.max_retry_attempts ?? DEFAULT_MAX_RETRY_ATTEMPTS;
+		if (!Number.isInteger(maxRetryAttempts) || maxRetryAttempts < 0) {
+			console.error("--max-retry-attempts must be a non-negative integer.");
+			process.exitCode = 1;
+			return;
+		}
+		const retryBackoffSeconds = options.retryBackoffSeconds ?? previousConfig?.retry_backoff_seconds ?? DEFAULT_RETRY_BACKOFF_SECONDS;
+		if (!Number.isInteger(retryBackoffSeconds) || retryBackoffSeconds <= 0) {
+			console.error("--retry-backoff-seconds must be a positive integer.");
+			process.exitCode = 1;
+			return;
+		}
 		const resolvedSkills = options.skills ?? normalizeSkills(previousConfig?.skills);
 		const resolvedExecuteAgent = options.executeAgent.trim() || previousConfig?.execute_agent || "codex";
 		const resolvedPrototypeUrl = options.prototypeUrl.trim() || previousConfig?.prototype_url || "https://github.com/pingcap-inc/pantheon-agents";
@@ -2779,6 +2885,8 @@ async function configAgent(name, options) {
 				config_task_id: configTaskId,
 				config_version: previousConfig.config_version + (options.prompt ? 2 : 1),
 				concurrency,
+				max_retry_attempts: maxRetryAttempts,
+				retry_backoff_seconds: retryBackoffSeconds,
 				execute_agent: resolvedExecuteAgent,
 				role: resolvedRole ?? previousConfig.role,
 				skills: resolvedSkills,
@@ -2846,6 +2954,8 @@ async function configAgent(name, options) {
 				config_task_id: configTaskId,
 				config_version: configVersion,
 				concurrency,
+				max_retry_attempts: maxRetryAttempts,
+				retry_backoff_seconds: retryBackoffSeconds,
 				execute_agent: resolvedExecuteAgent,
 				role: resolvedRole,
 				skills: resolvedSkills,
@@ -2857,6 +2967,8 @@ async function configAgent(name, options) {
 				config_task_id: configTaskId,
 				config_version: configVersion,
 				concurrency,
+				max_retry_attempts: maxRetryAttempts,
+				retry_backoff_seconds: retryBackoffSeconds,
 				execute_agent: resolvedExecuteAgent,
 				role: resolvedRole ?? previousConfig.role,
 				skills: resolvedSkills,
@@ -2936,6 +3048,22 @@ async function cancelTask(agentName, taskId, reason) {
 		await provider.close();
 	}
 }
+async function retryTask(agentName, taskId, reason) {
+	const provider = createTaskListProvider(agentName, pino());
+	try {
+		const task = await provider.getTask(taskId);
+		if (!task) return null;
+		if (task.status !== "failed") throw new Error(`Task ${taskId} is ${task.status}; only failed tasks can be retried.`);
+		if (!await retryFailedTaskInPlace(provider, task, pino(), {
+			immediate: true,
+			reason,
+			ignoreRetryLimit: true
+		})) throw new Error(`Task ${taskId} retry was not scheduled.`);
+		return await provider.getTask(taskId);
+	} finally {
+		await provider.close();
+	}
+}
 async function showAgentConfig(agentName, projectId) {
 	const provider = createTaskListProvider(agentName, pino());
 	try {
@@ -3038,24 +3166,26 @@ function formatConciseTaskLine(options) {
 	const statusText = formatStatus(task.status, useColor);
 	const timeText = formatRelativeTime(timestamp);
 	const taskText = truncateText(task.task, maxTaskLength);
+	const attempt = Number.isInteger(task.attempt_count) && task.attempt_count > 0 ? task.attempt_count : 1;
 	return [
 		agent,
 		statusText,
 		task.id,
+		`attempt:${attempt}`,
 		timeText,
 		taskText
 	].filter((part) => part !== "").join("  ");
 }
 async function assertsSingleton(logger, pidFile) {
 	try {
-		const pid = await fs.promises.readFile(pidFile, "utf-8");
+		const pid = await fs$1.promises.readFile(pidFile, "utf-8");
 		process.kill(parseInt(pid), 0);
 		console.error("Failed to assert singleton agent process:");
 		process.exit(1);
 	} catch (e) {
-		await fs.promises.writeFile(pidFile, process.pid.toString());
+		await fs$1.promises.writeFile(pidFile, process.pid.toString());
 		process.on("exit", () => {
-			fs.promises.rm(pidFile);
+			fs$1.promises.rm(pidFile);
 		});
 	}
 }
@@ -3224,8 +3354,18 @@ function parseConcurrency(value) {
 	if (!Number.isInteger(parsed) || parsed < 1) throw new InvalidArgumentError("concurrency must be a positive integer.");
 	return parsed;
 }
+function parseNonNegativeInteger(value, fieldName) {
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed < 0) throw new InvalidArgumentError(`${fieldName} must be a non-negative integer.`);
+	return parsed;
+}
+function parsePositiveInteger(value, fieldName) {
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed <= 0) throw new InvalidArgumentError(`${fieldName} must be a positive integer.`);
+	return parsed;
+}
 function createConfigAgentCommand(version, deps = {}) {
-	return createCommand("config").version(version).description("Queue a configuration task for an agent/project").argument("<name>", "The name of the agent.").argument("[prompt]", "The configuration task prompt.").option("--project-id <project-id>", "The project id of the agent. Defaults to DEFAULT_PANTHEON_PROJECT_ID.").option("--task-id <task-id>", "Optional parent task id.").option("--role <role>", "Role metadata. Required for first-time project config; optional override later.").option("--skills <skills>", "The skills of the agent. Multiple values are separated by comma.", parseUniqueCommaList).option("--execute-agent <agent>", "The execute agent of the agent.", "codex").option("--concurrency <number>", "Max number of parallel running tasks for this project.", parseConcurrency).option("--root-branch-id <branchId>", "The root branch id of the agent. Defaults to DEFAULT_PANTHEON_ROOT_BRANCH_ID, then project root branch id.").option("--prototype-url <url>", "Role and skill definitions repo.", "https://github.com/pingcap-inc/pantheon-agents").action(async function() {
+	return createCommand("config").version(version).description("Queue a configuration task for an agent/project").argument("<name>", "The name of the agent.").argument("[prompt]", "The configuration task prompt.").option("--project-id <project-id>", "The project id of the agent. Defaults to DEFAULT_PANTHEON_PROJECT_ID.").option("--task-id <task-id>", "Optional parent task id.").option("--role <role>", "Role metadata. Required for first-time project config; optional override later.").option("--skills <skills>", "The skills of the agent. Multiple values are separated by comma.", parseUniqueCommaList).option("--execute-agent <agent>", "The execute agent of the agent.", "codex").option("--concurrency <number>", "Max number of parallel running tasks for this project.", parseConcurrency).option("--max-retry-attempts <number>", "Max automatic retry attempts per task after failures.", (value) => parseNonNegativeInteger(value, "max-retry-attempts")).option("--retry-backoff-seconds <seconds>", "Base delay (seconds) for exponential retry backoff.", (value) => parsePositiveInteger(value, "retry-backoff-seconds")).option("--root-branch-id <branchId>", "The root branch id of the agent. Defaults to DEFAULT_PANTHEON_ROOT_BRANCH_ID, then project root branch id.").option("--prototype-url <url>", "Role and skill definitions repo.", "https://github.com/pingcap-inc/pantheon-agents").action(async function() {
 		const [name, prompt] = this.args;
 		const options = this.opts();
 		const resolvedProjectId = resolvePantheonProjectId(options.projectId);
@@ -3243,6 +3383,8 @@ function createConfigAgentCommand(version, deps = {}) {
 			role: options.role,
 			executeAgent: options.executeAgent,
 			concurrency: options.concurrency,
+			maxRetryAttempts: options.maxRetryAttempts,
+			retryBackoffSeconds: options.retryBackoffSeconds,
 			skills: options.skills,
 			prototypeUrl: options.prototypeUrl,
 			rootBranchId: resolvedRootBranchId
@@ -3297,9 +3439,11 @@ function formatTaskAsSkillTask(agent, task) {
 	const endedAt = "ended_at" in task ? task.ended_at ?? null : null;
 	const canceledAt = task.status === "cancelled" ? task.cancelled_at : null;
 	const finishedAt = endedAt ?? canceledAt ?? null;
+	const attempt = Number.isInteger(task.attempt_count) && task.attempt_count > 0 ? task.attempt_count : 1;
 	return {
 		agent,
 		task: task.task,
+		attempt,
 		parent_task_id: task.parent_task_id ?? null,
 		status: toSkillTaskStatus(task.status),
 		queued_at: task.queued_at.toISOString(),
@@ -3309,7 +3453,7 @@ function formatTaskAsSkillTask(agent, task) {
 		canceled_at: toIsoOrNull(canceledAt),
 		cancel_reason: task.cancel_reason ?? null,
 		output: task.status === "completed" ? task.output : null,
-		error: task.status === "failed" ? task.error : null
+		error: task.error ?? null
 	};
 }
 function createGetTaskCommand(version, deps = {}) {
@@ -3390,6 +3534,8 @@ function createShowConfigCommand(version) {
 				config_version: config.config_version,
 				config_task_id: config.config_task_id,
 				concurrency: config.concurrency,
+				max_retry_attempts: config.max_retry_attempts ?? 3,
+				retry_backoff_seconds: config.retry_backoff_seconds ?? 30,
 				role: config.role,
 				execute_agent: config.execute_agent,
 				prototype_url: config.prototype_url,
@@ -3414,6 +3560,8 @@ function createShowConfigCommand(version) {
 			config_version: config.config_version,
 			config_task_id: config.config_task_id,
 			concurrency: config.concurrency,
+			max_retry_attempts: config.max_retry_attempts ?? 3,
+			retry_backoff_seconds: config.retry_backoff_seconds ?? 30,
 			role: config.role,
 			execute_agent: config.execute_agent,
 			prototype_url: config.prototype_url,
@@ -3537,6 +3685,135 @@ function createShowTasksCommand(version, deps = {}) {
 	});
 }
 
+//#endregion
+//#region src/cli/commands/retry-task.ts
+function resolveTaskAttempt(value) {
+	if (typeof value === "number" && Number.isInteger(value) && value > 0) return value;
+	return 1;
+}
+function createRetryTaskCommand(version, deps = {}) {
+	return createCommand("retry-task").version(version).description("Retry a failed task for an agent").argument("<name>", "The name of the agent.").argument("<task-id>", "The id of the failed task.").argument("[reason]", "Optional retry reason.").option("-y, --yes", "Skip confirmation prompt.").option("-f, --force", "Alias for --yes.").action(async function() {
+		const [name, taskId, reason] = this.args;
+		const options = this.opts();
+		if (!ensureEnv(["DATABASE_URL"])) return;
+		const rl = options.yes || options.force ? null : readline.createInterface({
+			input: process$1.stdin,
+			output: process$1.stdout
+		});
+		try {
+			if (rl) {
+				if ((await rl.question(`Type the task id (${taskId}) to confirm retry: `)).trim() !== taskId) {
+					console.error("Confirmation failed. Task id did not match.");
+					process$1.exitCode = 1;
+					return;
+				}
+				if ((await rl.question("Type RETRY to requeue this failed task: ")).trim() !== "RETRY") {
+					console.error("Confirmation failed. Aborting retry.");
+					process$1.exitCode = 1;
+					return;
+				}
+			}
+			const updatedTask = await (deps.retryTask ?? retryTask)(name, taskId, reason);
+			if (!updatedTask) {
+				console.error(`Task ${taskId} not found for agent ${name}.`);
+				process$1.exitCode = 1;
+				return;
+			}
+			if (updatedTask.status !== "pending") {
+				console.error(`Unexpected result: task ${taskId} status is ${updatedTask.status} after retry.`);
+				process$1.exitCode = 1;
+				return;
+			}
+			const attempt = resolveTaskAttempt(updatedTask.attempt_count);
+			console.log(`Requeued task ${taskId} for agent ${name} as attempt ${attempt}, next run at ${updatedTask.queued_at.toISOString()}.${reason ? ` Reason: ${reason}` : ""}`);
+		} catch (error) {
+			console.error(error instanceof Error ? error.message : String(error));
+			process$1.exitCode = 1;
+		} finally {
+			rl?.close();
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/skill-sh.ts
+const EMBEDDED_SKILL_MARKDOWN = "---\nname: pantheon-agents\ndescription: \"Pantheon Agents CLI Usage\"\n---\n\n> Pantheon is the project name of an internal VM environment management project. Do not guess any usage from the name.\n\n\n## Pantheon Agents CLI Usage\n\n### Concepts\n\n- agent: Each agent has a role (like `developer`) and several skills to use.\n- environment: The context of tools, codes or anything else for agents to run tasks. You don't need to know the details.\n- tasks: tasks for each agent to run, each task will create a new environment.\n\n#### Task structure\n\n- agent: The agent to executing the task\n- task (text): The task content\n- attempt: Attempt number (starts from 1 and increases on retries)\n- parent_task_id: The parent task id\n- status: `pending`, `running`, `completed`, `failed`, `canceled`\n- queued_at\n- started_at\n- ended_at\n- finished_at\n- canceled_at\n- cancel_reason\n- output: The output of the completed task.\n- error: The last known error message (failed task error is kept across retries).\n\n#### Other internal implementation details you don't need to know or use\n\n- project\n- branches\n\n### CLI Commands\n\n**You can only use the CLI commands listed below.**\n\n#### Setup a base environment for an agent:\n\n```shell\n# Use default setup script at first time configuration\npantheon-agents config 'Kris' \\\n    --role 'developer' \\\n    --skills pantheon-issue-resolve,pantheon-solution-design \\\n    --max-retry-attempts 3 \\\n    --retry-backoff-seconds 30\n\n# Add some custom prompts\npantheon-agents config 'Kris' \\\n    --role 'developer' \\\n    --skills pantheon-issue-resolve,pantheon-solution-design \\\n    'Update tools to the latest version.'\n```\n\n#### Update agent's environment\n\n##### Configure agent environment by prompt\n\n```shell\npantheon-agents config 'Kris' 'Install some tools'\n```\n\n##### Configure agent to a task result environment\n\npantheon-agents config 'Kris' --task-id 42\n\n#### Enqueue tasks\n\n```shell\npantheon-agents add-task 'Kris' 'Some awesome task'\n ```\n\nWhen adding tasks, cli will output the task id. You can add tasks with `--parent-task-id` to create a task hierarchy.\n\n```shell\npantheon-agents add-task 'Kris' 'Some awesome task' --parent-task-id 42\n```\n\n\n#### List tasks\n\n```shell\npantheon-agents show-tasks --json 'Kris'\n```\n\n\n#### Show single task info\n\n```shell\npantheon-agents get-task 'Kris' 42\n```\n\nReturns task info using this task structure (without internal project/branch fields):\n\n```json\n{\n  \"agent\": \"Kris\",\n  \"task\": \"Some awesome task\",\n  \"attempt\": 1,\n  \"parent_task_id\": \"41\",\n  \"status\": \"completed\",\n  \"queued_at\": \"2026-02-12T00:00:00.000Z\",\n  \"started_at\": \"2026-02-12T00:00:05.000Z\",\n  \"ended_at\": \"2026-02-12T00:05:00.000Z\",\n  \"finished_at\": \"2026-02-12T00:05:00.000Z\",\n  \"canceled_at\": null,\n  \"cancel_reason\": null,\n  \"output\": \"Task output\",\n  \"error\": null\n}\n```\n\n#### Cancel task\n\n```shell\npantheon-agents cancel-task 'Kris' 42 'Reason'\n```\n\n#### Retry failed task\n\n```shell\n# Manual retry (immediate requeue and increases attempt)\npantheon-agents retry-task 'Kris' 42 'Reason'\n```\n\n#### Print embedded skill markdown\n\n```shell\npantheon-agents skill.sh\n```\n";
+function createSkillShCommand(version) {
+	return createCommand("skill.sh").version(version).description("Print embedded pantheon-agents skill markdown").action(() => {
+		process$1.stdout.write(EMBEDDED_SKILL_MARKDOWN);
+	});
+}
+
+//#endregion
+//#region src/cli/commands/gen-migration-sql.ts
+const introducedInPattern = /^--\s*introduced_in:\s*([0-9]+\.[0-9]+\.[0-9]+)\s*$/m;
+function parseProvider(value) {
+	if (value === "tidb" || value === "db9") return value;
+	throw new InvalidArgumentError("provider must be one of: tidb, db9");
+}
+function parseSemver(value) {
+	const matched = value.trim().match(/^(\d+)\.(\d+)\.(\d+)$/);
+	if (!matched) return null;
+	return [
+		Number(matched[1]),
+		Number(matched[2]),
+		Number(matched[3])
+	];
+}
+function parseSemverOption(value) {
+	if (parseSemver(value) == null) throw new InvalidArgumentError("from must be a semver like 0.3.0");
+	return value;
+}
+function compareSemver(a, b) {
+	const pa = parseSemver(a);
+	const pb = parseSemver(b);
+	if (!pa || !pb) throw new Error(`Invalid semver comparison: '${a}' vs '${b}'`);
+	for (let i = 0; i < 3; i++) {
+		if (pa[i] > pb[i]) return 1;
+		if (pa[i] < pb[i]) return -1;
+	}
+	return 0;
+}
+function resolveMigrationDir(provider, cwd) {
+	const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+	const candidates = [
+		path.resolve(cwd, "src/db/migrations", provider),
+		path.resolve(cwd, "packages/agents/src/db/migrations", provider),
+		path.resolve(moduleDir, "db/migrations", provider),
+		path.resolve(moduleDir, "../db/migrations", provider),
+		path.resolve(moduleDir, "../../db/migrations", provider)
+	];
+	for (const candidate of candidates) if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) return candidate;
+	throw new Error(`Migration directory not found for provider '${provider}'. Checked: ${candidates.join(", ")}`);
+}
+function loadProviderMigrations(provider, options = {}) {
+	const migrationDir = resolveMigrationDir(provider, options.cwd ?? process$1.cwd());
+	return fs.readdirSync(migrationDir).filter((name) => name.endsWith(".sql")).sort((a, b) => a.localeCompare(b)).map((fileName) => {
+		const filePath = path.join(migrationDir, fileName);
+		const sql = fs.readFileSync(filePath, "utf8");
+		const introduced = sql.match(introducedInPattern)?.[1];
+		if (!introduced) throw new Error(`Migration file '${fileName}' missing required header '-- introduced_in: x.y.z'.`);
+		return {
+			fileName,
+			introducedIn: introduced,
+			sql
+		};
+	});
+}
+function getMigrationSql(provider, fromVersion, options = {}) {
+	if (!parseSemver(fromVersion)) throw new Error(`Invalid from version '${fromVersion}'. Expected x.y.z`);
+	const migrations = loadProviderMigrations(provider, options).filter((migration) => compareSemver(migration.introducedIn, fromVersion) > 0);
+	if (migrations.length === 0) return `-- No migrations for provider '${provider}' since ${fromVersion}.\n`;
+	return migrations.map((migration) => `-- migration: ${migration.fileName}\n${migration.sql.trimEnd()}\n`).join("\n");
+}
+function createGenMigrationSqlCommand(version, deps = {}) {
+	return createCommand("gen-migration-sql").version(version).description("Print SQL migrations since a given package version").requiredOption("--provider <provider>", "Database provider: tidb or db9.", parseProvider).requiredOption("--from <version>", "Print migrations introduced after this version.", parseSemverOption).action(async function() {
+		const options = this.opts();
+		const output = (deps.getMigrationSql ?? getMigrationSql)(options.provider, options.from);
+		process$1.stdout.write(output);
+	});
+}
+
 //#endregion
 //#region ../agent-stream-parser/src/utils.ts
 function isRecord(value) {
@@ -5962,7 +6239,7 @@ function createWatchStreamCommand(version) {
 
 //#endregion
 //#region src/cli/index.ts
-const program = new Command().name("pantheon-agents").description("Pantheon agents CLI").version(version).showHelpAfterError().showSuggestionAfterError().addHelpCommand().addCommand(createAddTaskCommand(version)).addCommand(createConfigAgentCommand(version)).addCommand(createDeleteTaskCommand(version)).addCommand(createCancelTaskCommand(version)).addCommand(createGetTaskCommand(version)).addCommand(createRunAgentCommand(version)).addCommand(createShowConfigCommand(version)).addCommand(createShowTasksCommand(version)).addCommand(createWatchCommand(version)).addCommand(createWatchStreamCommand(version));
+const program = new Command().name("pantheon-agents").description("Pantheon agents CLI").version(version).showHelpAfterError().showSuggestionAfterError().addHelpCommand().addCommand(createAddTaskCommand(version)).addCommand(createConfigAgentCommand(version)).addCommand(createDeleteTaskCommand(version)).addCommand(createCancelTaskCommand(version)).addCommand(createGetTaskCommand(version)).addCommand(createRunAgentCommand(version)).addCommand(createRetryTaskCommand(version)).addCommand(createSkillShCommand(version)).addCommand(createGenMigrationSqlCommand(version)).addCommand(createShowConfigCommand(version)).addCommand(createShowTasksCommand(version)).addCommand(createWatchCommand(version)).addCommand(createWatchStreamCommand(version));
 async function main() {
 	if (process$1.argv.length <= 2) {
 		program.outputHelp();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pantheon.ai/agents",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "bin": {
     "pantheon-agents": "dist/index.js"
   },
@@ -12,7 +12,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rolldown -c rolldown.config.ts && chmod +x dist/index.js",
+    "build": "rolldown -c rolldown.config.ts && mkdir -p dist/db && cp -R src/db/migrations dist/db/ && chmod +x dist/index.js",
     "typecheck": "tsc --noEmit --skipLibCheck --allowImportingTsExtensions --lib ESNext,DOM,DOM.Iterable",
     "test": "bun test",
     "test:coverage": "bun test --coverage",