@clinebot/core 0.0.36 → 0.0.37

package/src/extensions/tools/definitions.ts

@@ -15,6 +15,7 @@ import {
 	formatReadFileQuery,
 	formatRunCommandQuery,
 	getEditorSizeError,
+	getReadFileRangeError,
 	normalizeReadFileRequests,
 	normalizeRunCommandsInput,
 	withTimeout,
@@ -92,6 +93,16 @@ export function createReadFilesTool(
 
 			return Promise.all(
 				requests.map(async (request): Promise<ToolOperationResult> => {
+					const rangeError = getReadFileRangeError(request);
+					if (rangeError) {
+						return {
+							query: formatReadFileQuery(request),
+							result: "",
+							error: `Invalid file range: ${rangeError}`,
+							success: false,
+						};
+					}
+
 					try {
 						const content = await withTimeout(
 							executor(request, context),
@@ -206,16 +217,23 @@ export function createBashTool(
 		maxRetries: 0,
 		execute: async (input, context) => {
 			const validate = validateWithZod(RunCommandsInputUnionSchema, input);
-			const commands = Array.isArray(validate)
-				? validate
-				: typeof validate === "object"
-					? Array.isArray(validate.commands)
-						? validate.commands
-						: [validate.commands]
-					: [validate];
+			let commands: string[];
+			if (typeof validate === "string") {
+				commands = [validate];
+			} else if (Array.isArray(validate)) {
+				commands = validate;
+			} else if ("commands" in validate) {
+				commands = Array.isArray(validate.commands)
+					? validate.commands
+					: [validate.commands];
+			} else if ("command" in validate) {
+				commands = [validate.command];
+			} else {
+				commands = [validate.cmd];
+			}
 
 			return Promise.all(
-				commands.map(async (command): Promise<ToolOperationResult> => {
+				commands.map(async (command: string): Promise<ToolOperationResult> => {
 					try {
 						const output = await withTimeout(
 							executor(command, cwd, context),
@@ -564,11 +582,8 @@ export function createSkillsTool(
  */
 export function createAskQuestionTool(
 	executor: AskQuestionExecutor,
-	config: Pick<DefaultToolsConfig, "askQuestionTimeoutMs"> = {},
 ): Tool<AskQuestionInput, string> {
-	const timeoutMs = config.askQuestionTimeoutMs ?? 15000;
-
-	return createTool<AskQuestionInput, string>({
+	return {
 		name: "ask_question",
 		description:
 			"Ask user a question for clarifying or gathering information needed to complete the task. " +
@@ -577,18 +592,13 @@ export function createAskQuestionTool(
 			"Provide an array of 2-5 options for the user to choose from. " +
 			"Never include an option to toggle to Act mode.",
 		inputSchema: zodToJsonSchema(AskQuestionInputSchema),
-		timeoutMs,
 		retryable: false,
 		maxRetries: 0,
 		execute: async (input, context) => {
 			const validatedInput = validateWithZod(AskQuestionInputSchema, input);
-			return withTimeout(
-				executor(validatedInput.question, validatedInput.options, context),
-				timeoutMs,
-				`ask_question timed out after ${timeoutMs}ms`,
-			);
+			return executor(validatedInput.question, validatedInput.options, context);
 		},
-	});
+	};
 }
 
 export function createSubmitAndExitTool(
@@ -632,8 +642,7 @@ export function createSubmitAndExitTool(
  *
  * @example
  * ```typescript
- * import { Agent } from "@clinebot/agents"
- * import { createDefaultTools } from "@clinebot/core"
+ * import { Agent, createDefaultTools } from "@clinebot/core"
  * import * as fs from "fs/promises"
  * import { exec } from "child_process"
  *
@@ -719,7 +728,7 @@ export function createDefaultTools(options: CreateDefaultToolsOptions): Tool[] {
 
 	// Add ask_question tool if enabled and executor provided
 	if (enableAskQuestion && executors.askQuestion) {
-		tools.push(createAskQuestionTool(executors.askQuestion, config));
+		tools.push(createAskQuestionTool(executors.askQuestion));
 	} else if (enableSubmitAndExit && executors.submit) {
 		// Add submit_and_exit tool if enabled and executor provided
 		tools.push(createSubmitAndExitTool(executors.submit, config));

package/src/extensions/tools/executors/editor.ts

@@ -157,14 +157,15 @@ async function insertInFile(
 ): Promise<string> {
 	const content = await fs.readFile(filePath, encoding);
 	const lines = content.split("\n");
-	const insertLine = insertLineOneBased - 1; // Convert to zero-based index
+	const maxBoundaryLine = lines.length + 1;
 
-	if (insertLine < 0 || insertLine > lines.length) {
+	if (insertLineOneBased < 1 || insertLineOneBased > maxBoundaryLine) {
 		throw new Error(
-			`Invalid line number: ${insertLineOneBased}. Valid range: 1-${lines.length}`,
+			`Invalid insert_line: ${insertLineOneBased}. insert_line must be a positive one-based boundary line in the range 1-${maxBoundaryLine}. Use ${maxBoundaryLine} to append at EOF.`,
 		);
 	}
 
+	const insertLine = insertLineOneBased - 1;
 	lines.splice(insertLine, 0, ...newStr.split("\n"));
 	await fs.writeFile(filePath, lines.join("\n"), { encoding });
 

package/src/extensions/tools/helpers.ts

@@ -76,6 +76,13 @@ export function normalizeReadFileRequests(input: unknown): ReadFileRequest[] {
 		return filePaths.map((filePath) => ({ path: filePath }));
 	}
 
+	if ("paths" in validate) {
+		const paths = Array.isArray(validate.paths)
+			? validate.paths
+			: [validate.paths];
+		return paths.map((path) => (typeof path === "string" ? { path } : path));
+	}
+
 	return [validate];
 }
 
@@ -89,6 +96,15 @@ export function formatReadFileQuery(request: ReadFileRequest): string {
 	return `${path}:${start}-${end}`;
 }
 
+export function getReadFileRangeError(request: ReadFileRequest): string | null {
+	const { start_line, end_line } = request;
+	if (start_line == null || end_line == null || start_line <= end_line) {
+		return null;
+	}
+
+	return `start_line must be less than or equal to end_line (received start_line: ${start_line}, end_line: ${end_line})`;
+}
+
 export function normalizeRunCommandsInput(
 	input: unknown,
 ): Array<string | StructuredCommandInput> {
@@ -108,6 +124,14 @@ export function normalizeRunCommandsInput(
 			: [validate.commands];
 	}
 
+	if ("command" in validate) {
+		return "args" in validate ? [validate] : [validate.command];
+	}
+
+	if ("cmd" in validate) {
+		return [validate.cmd];
+	}
+
 	return [validate];
 }
 

package/src/extensions/tools/index.ts

@@ -143,8 +143,7 @@ export interface CreateBuiltinToolsOptions
  *
  * @example
  * ```typescript
- * import { Agent } from "@clinebot/agents"
- * import { createBuiltinTools } from "@clinebot/core"
+ * import { Agent, createBuiltinTools } from "@clinebot/core"
  *
  * const tools = createBuiltinTools({
  *   cwd: "/path/to/project",

package/src/extensions/tools/presets.ts

@@ -26,7 +26,7 @@ export const ToolPresets = {
 		enableReadFiles: true,
 		enableSearch: true,
 		enableBash: true,
-		enableWebFetch: false,
+		enableWebFetch: true,
 		enableApplyPatch: false,
 		enableEditor: true,
 		enableSkills: true,

package/src/extensions/tools/schemas.ts

@@ -37,14 +37,7 @@ export const ReadFileLineRangeSchema = z
 				"Optional one-based ending line number to read through; use null or omit for the end of the file",
 			),
 	})
-	.refine(
-		({ start_line, end_line }) =>
-			start_line == null || end_line == null || start_line <= end_line,
-		{
-			message: "start_line must be less than or equal to end_line",
-			path: ["end_line"],
-		},
-	);
+	.describe("Optional inclusive one-based file line range");
 
 export const ReadFileRequestSchema = z
 	.object({
@@ -52,13 +45,8 @@ export const ReadFileRequestSchema = z
 		start_line: ReadFileLineRangeSchema.shape.start_line,
 		end_line: ReadFileLineRangeSchema.shape.end_line,
 	})
-	.refine(
-		({ start_line, end_line }) =>
-			start_line == null || end_line == null || start_line <= end_line,
-		{
-			message: "start_line must be less than or equal to end_line",
-			path: ["end_line"],
-		},
+	.describe(
+		"A file read request with optional inclusive one-based line bounds",
 	);
 
 /**
@@ -84,6 +72,9 @@ export const ReadFilesInputUnionSchema = z.union([
 	z.object({ files: ReadFileRequestSchema }),
 	z.object({ file_paths: z.array(AbsolutePath) }),
 	z.object({ file_paths: z.string() }),
+	z.object({ paths: z.array(z.union([AbsolutePath, ReadFileRequestSchema])) }),
+	z.object({ paths: ReadFileRequestSchema }),
+	z.object({ paths: z.string() }),
 ]);
 
 /**
@@ -126,6 +117,8 @@ export const RunCommandsInputSchema = z.object({
 export const RunCommandsInputUnionSchema = z.union([
 	RunCommandsInputSchema,
 	z.object({ commands: CommandInputSchema }),
+	z.object({ command: CommandInputSchema }),
+	z.object({ cmd: CommandInputSchema }),
 	z.array(z.string()),
 	z.string(),
 ]);
@@ -163,10 +156,12 @@ export const StructuredCommandsInputUnionSchema = z.union([
 	RunCommandsInputSchema,
 	StructuredCommandsInputSchema,
 	z.object({ commands: StructuredCommandEntrySchema }),
-	z.array(z.string()),
 	z.array(StructuredCommandInputSchema),
-	z.string(),
 	StructuredCommandInputSchema,
+	z.object({ command: CommandInputSchema }),
+	z.object({ cmd: CommandInputSchema }),
+	z.array(z.string()),
+	z.string(),
 ]);
 
 /**
@@ -213,7 +208,7 @@ export const EditFileInputSchema = z
 			.nullable()
 			.optional()
 			.describe(
-				"Optional one-based line index. When provided, the tool inserts new_text at that line instead of performing a replacement edit.",
+				"Optional positive one-based boundary line. When provided, the tool inserts new_text before that line instead of performing a replacement edit; use line_count + 1 to append at EOF.",
 			),
 	})
 	.describe(

package/src/extensions/tools/team/delegated-agent.ts

@@ -1,4 +1,3 @@
-import { Agent } from "@clinebot/agents";
 import type {
 	AgentConfig,
 	AgentEvent,
@@ -10,6 +9,7 @@ import type {
 	ToolApprovalRequest,
 	ToolApprovalResult,
 } from "@clinebot/shared";
+import { SessionRuntime } from "../../../runtime/session-runtime-orchestrator";
 import {
 	buildSubAgentSystemPrompt,
 	buildTeammateSystemPrompt,
@@ -126,6 +126,11 @@ export function buildDelegatedAgentConfig(
 
 export function createDelegatedAgent(
 	options: BuildDelegatedAgentConfigOptions,
-): Agent {
-	return new Agent(buildDelegatedAgentConfig(options));
+): SessionRuntime {
+	const config = buildDelegatedAgentConfig(options);
+	const session = new SessionRuntime(config);
+	if (config.onEvent) {
+		session.subscribeEvents(config.onEvent);
+	}
+	return session;
 }

package/src/extensions/tools/team/multi-agent.ts

@@ -4,7 +4,6 @@
  * Utilities for orchestrating multiple agents working together.
  */
 
-import { type Agent, createAgent } from "@clinebot/agents";
 import {
 	type AgentConfig,
 	type AgentEvent,
@@ -33,6 +32,7 @@ import {
 	type TeamTaskStatus,
 } from "@clinebot/shared";
 import { nanoid } from "nanoid";
+import { SessionRuntime } from "../../../runtime/session-runtime-orchestrator";
 
 // Re-export shared types for backward compatibility
 export {
@@ -155,14 +155,26 @@ function isAbortLikeError(error: unknown): boolean {
 	);
 }
 
+function isIntentionalShutdownAbort(
+	member: TeamMemberState | undefined,
+	error: unknown,
+): boolean {
+	return member?.status === "stopped" && isAbortLikeError(error);
+}
+
 // =============================================================================
 // AgentTeam
 // =============================================================================
 
 const TEAMMATE_API_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
+const RECOVERED_QUEUED_ACTIVITY = "recovered_queued";
+
+function buildRecoveredRunMessage(run: TeamRunRecord): string {
+	return `This is an automatic recovery of interrupted team run ${run.id}. The previous process stopped before completion. Continue the task safely, inspect the current workspace state before making changes, and avoid duplicating completed work.\n\n${run.message}`;
+}
 
 export class AgentTeam {
-	private agents: Map<string, Agent> = new Map();
+	private agents: Map<string, SessionRuntime> = new Map();
 	private configs: Map<string, TeamMemberConfig> = new Map();
 	private onTeamEvent?: (event: TeamEvent) => void;
 
@@ -196,7 +208,10 @@ export class AgentTeam {
 			},
 		};
 
-		const agent = createAgent(wrappedConfig);
+		const agent = new SessionRuntime(wrappedConfig);
+		if (wrappedConfig.onEvent) {
+			agent.subscribeEvents(wrappedConfig.onEvent);
+		}
 		this.agents.set(id, agent);
 		this.configs.set(id, config);
 	}
@@ -206,7 +221,7 @@ export class AgentTeam {
 		return this.agents.delete(id);
 	}
 
-	getAgent(id: string): Agent | undefined {
+	getAgent(id: string): SessionRuntime | undefined {
 		return this.agents.get(id);
 	}
 
@@ -497,7 +512,7 @@ export function createWorkerReviewerTeam(configs: {
 // =============================================================================
 
 interface TeamMemberState extends TeamMemberSnapshot {
-	agent?: Agent;
+	agent?: SessionRuntime;
 	runningCount: number;
 	lastMissionStep: number;
 	lastMissionAt: number;
@@ -522,6 +537,7 @@ export class AgentTeamsRuntime {
 	private readonly runs: Map<string, TeamRunRecord & { result?: AgentResult }> =
 		new Map();
 	private readonly runQueue: string[] = [];
+	private queuedRunDispatchTimer: ReturnType<typeof setTimeout> | undefined;
 	private readonly outcomes: Map<string, TeamOutcome> = new Map();
 	private readonly outcomeFragments: Map<string, TeamOutcomeFragment> =
 		new Map();
@@ -707,6 +723,7 @@ export class AgentTeamsRuntime {
 	}
 
 	hydrateState(state: TeamRuntimeState): void {
+		this.clearQueuedRunDispatchTimer();
 		this.tasks.clear();
 		for (const task of state.tasks) {
 			this.tasks.set(task.id, { ...task });
@@ -851,7 +868,10 @@ export class AgentTeamsRuntime {
 			},
 		};
 
-		const agent = createAgent(wrappedConfig);
+		const agent = new SessionRuntime(wrappedConfig);
+		if (wrappedConfig.onEvent) {
+			agent.subscribeEvents(wrappedConfig.onEvent);
+		}
 		const teammate: TeamMemberState = {
 			agentId,
 			role: "teammate",
@@ -1038,12 +1058,14 @@ export class AgentTeamsRuntime {
 				error: err,
 				messages: member.agent.getMessages(),
 			});
-			this.appendMissionLog({
-				agentId,
-				taskId: options?.taskId,
-				kind: "error",
-				summary: err.message,
-			});
+			if (!isIntentionalShutdownAbort(member, err)) {
+				this.appendMissionLog({
+					agentId,
+					taskId: options?.taskId,
+					kind: "error",
+					summary: err.message,
+				});
+			}
 			throw err;
 		} finally {
 			member.runningCount--;
@@ -1091,11 +1113,19 @@ export class AgentTeamsRuntime {
 	}
 
 	private dispatchQueuedRuns(): void {
+		this.clearQueuedRunDispatchTimer();
+		let nextDelayedAttemptAt: Date | undefined;
 		while (
 			this.countActiveRuns() < this.maxConcurrentRuns &&
 			this.runQueue.length > 0
 		) {
-			const nextRunIndex = this.selectNextQueuedRunIndex();
+			const nextRun = this.selectNextDispatchableQueuedRun();
+			nextDelayedAttemptAt = nextRun.nextDelayedAttemptAt;
+			const nextRunIndex = nextRun.index;
+			if (nextRunIndex < 0) {
+				this.scheduleQueuedRunDispatch(nextDelayedAttemptAt);
+				return;
+			}
 			const [runId] = this.runQueue.splice(nextRunIndex, 1);
 			const run = runId ? this.runs.get(runId) : undefined;
 			if (!run || run.status !== "queued") {
@@ -1103,22 +1133,53 @@ export class AgentTeamsRuntime {
 			}
 			void this.executeQueuedRun(run);
 		}
+		this.scheduleQueuedRunDispatch(nextDelayedAttemptAt);
 	}
 
-	private selectNextQueuedRunIndex(): number {
-		let selectedIndex = 0;
+	private selectNextDispatchableQueuedRun(): {
+		index: number;
+		nextDelayedAttemptAt?: Date;
+	} {
+		let selectedIndex = -1;
 		let bestPriority = Number.NEGATIVE_INFINITY;
+		let nextDelayedAttemptAt: Date | undefined;
+		const now = Date.now();
 		for (let index = 0; index < this.runQueue.length; index++) {
 			const run = this.runs.get(this.runQueue[index]);
 			if (!run || run.status !== "queued") {
 				continue;
 			}
+			if (run.nextAttemptAt && run.nextAttemptAt.getTime() > now) {
+				if (!nextDelayedAttemptAt || run.nextAttemptAt < nextDelayedAttemptAt) {
+					nextDelayedAttemptAt = run.nextAttemptAt;
+				}
+				continue;
+			}
 			if (run.priority > bestPriority) {
 				bestPriority = run.priority;
 				selectedIndex = index;
 			}
 		}
-		return selectedIndex;
+		return { index: selectedIndex, nextDelayedAttemptAt };
+	}
+
+	private scheduleQueuedRunDispatch(nextAttemptAt: Date | undefined): void {
+		if (!nextAttemptAt) {
+			return;
+		}
+		const delayMs = Math.max(0, nextAttemptAt.getTime() - Date.now());
+		this.queuedRunDispatchTimer = setTimeout(() => {
+			this.queuedRunDispatchTimer = undefined;
+			this.dispatchQueuedRuns();
+		}, delayMs);
+	}
+
+	private clearQueuedRunDispatchTimer(): void {
+		if (!this.queuedRunDispatchTimer) {
+			return;
+		}
+		clearTimeout(this.queuedRunDispatchTimer);
+		this.queuedRunDispatchTimer = undefined;
 	}
 
 	private countActiveRuns(): number {
@@ -1134,6 +1195,8 @@ export class AgentTeamsRuntime {
 	private async executeQueuedRun(
 		run: TeamRunRecord & { result?: AgentResult },
 	): Promise<void> {
+		const recoveredRun = run.currentActivity === RECOVERED_QUEUED_ACTIVITY;
+		run.nextAttemptAt = undefined;
 		run.status = "running";
 		run.startedAt = new Date();
 		run.heartbeatAt = new Date();
@@ -1148,7 +1211,10 @@ export class AgentTeamsRuntime {
 		}, 2000);
 
 		try {
-			const result = await this.routeToTeammate(run.agentId, run.message, {
+			const runMessage = recoveredRun
+				? buildRecoveredRunMessage(run)
+				: run.message;
+			const result = await this.routeToTeammate(run.agentId, runMessage, {
 				taskId: run.taskId,
 				continueConversation: run.continueConversation,
 			});
@@ -1164,7 +1230,16 @@ export class AgentTeamsRuntime {
 					: String(error ?? "Unknown error");
 			run.error = message;
 			run.endedAt = new Date();
-			if (run.retryCount < run.maxRetries) {
+			const member = this.members.get(run.agentId);
+			if (isIntentionalShutdownAbort(member, error)) {
+				run.status = "cancelled";
+				run.currentActivity = "cancelled";
+				this.emitEvent({
+					type: TeamMessageType.RunCancelled,
+					run: { ...run },
+					reason: message,
+				});
+			} else if (run.retryCount < run.maxRetries) {
 				run.retryCount++;
 				run.status = "queued";
 				run.nextAttemptAt = new Date(
@@ -1215,7 +1290,7 @@ export class AgentTeamsRuntime {
 		if (!run) {
 			throw new Error(`Run "${runId}" was not found`);
 		}
-		while (run.status === "running") {
+		while (run.status === "queued" || run.status === "running") {
 			await sleep(pollIntervalMs);
 		}
 		return { ...run };
@@ -1256,6 +1331,45 @@ export class AgentTeamsRuntime {
 		return { ...run };
 	}
 
+	recoverActiveRuns(reason = "runtime_recovered"): TeamRunRecord[] {
+		const recovered: TeamRunRecord[] = [];
+		for (const run of this.runs.values()) {
+			if (!["queued", "running"].includes(run.status)) {
+				continue;
+			}
+
+			const member = this.members.get(run.agentId);
+			if (!member || member.role !== "teammate" || !member.agent) {
+				run.status = "interrupted";
+				run.error = "teammate_unavailable_after_recovery";
+				run.endedAt = new Date();
+				run.currentActivity = "interrupted";
+				this.emitEvent({
+					type: TeamMessageType.RunInterrupted,
+					run: { ...run },
+					reason: run.error,
+				});
+				continue;
+			}
+
+			const now = new Date();
+			run.status = "queued";
+			run.error = undefined;
+			run.endedAt = undefined;
+			run.heartbeatAt = now;
+			run.lastProgressAt = now;
+			run.lastProgressMessage = reason;
+			run.currentActivity = RECOVERED_QUEUED_ACTIVITY;
+			if (!this.runQueue.includes(run.id)) {
+				this.runQueue.push(run.id);
+			}
+			recovered.push({ ...run });
+			this.emitEvent({ type: TeamMessageType.RunQueued, run: { ...run } });
+		}
+		this.dispatchQueuedRuns();
+		return recovered;
+	}
+
 	markStaleRunsInterrupted(reason = "runtime_recovered"): TeamRunRecord[] {
 		const interrupted: TeamRunRecord[] = [];
 		for (const run of this.runs.values()) {
@@ -1274,6 +1388,7 @@ export class AgentTeamsRuntime {
 			});
 		}
 		this.runQueue.length = 0;
+		this.clearQueuedRunDispatchTimer();
 		return interrupted;
 	}
 
@@ -1513,6 +1628,7 @@ export class AgentTeamsRuntime {
 		this.missionLog.length = 0;
 		this.runs.clear();
 		this.runQueue.length = 0;
+		this.clearQueuedRunDispatchTimer();
 		this.outcomes.clear();
 		this.outcomeFragments.clear();