@clinebot/core 0.0.11 → 0.0.12

package/src/session/default-session-manager.ts

@@ -223,6 +223,7 @@ export class DefaultSessionManager implements SessionManager {
 				hookPath,
 				sessionId,
 				this.defaultTelemetry,
+				(e) => void this.handlePluginEvent(sessionId, e),
 			);
 		const providerConfig = buildResolvedProviderConfig(
 			effectiveConfig,
@@ -307,6 +308,8 @@ export class DefaultSessionManager implements SessionManager {
 			activeTeamRunIds: new Set<string>(),
 			pendingTeamRunUpdates: [],
 			teamRunWaiters: [],
+			pendingPrompts: [],
+			drainingPendingPrompts: false,
 			pluginSandboxShutdown,
 		};
 		this.sessions.set(sessionId, active);
@@ -349,8 +352,18 @@ export class DefaultSessionManager implements SessionManager {
 				promptLength: input.prompt.length,
 				userImageCount: input.userImages?.length ?? 0,
 				userFileCount: input.userFiles?.length ?? 0,
+				delivery: input.delivery ?? "immediate",
 			},
 		});
+		if (input.delivery === "queue" || input.delivery === "steer") {
+			this.enqueuePendingPrompt(input.sessionId, {
+				prompt: input.prompt,
+				delivery: input.delivery,
+				userImages: input.userImages,
+				userFiles: input.userFiles,
+			});
+			return undefined;
+		}
 		try {
 			const result = await this.runTurn(session, {
 				prompt: input.prompt,
@@ -360,6 +373,9 @@ export class DefaultSessionManager implements SessionManager {
 			if (!session.interactive) {
 				await this.finalizeSingleRun(session, result.finishReason);
 			}
+			queueMicrotask(() => {
+				void this.drainPendingPrompts(input.sessionId);
+			});
 			return result;
 		} catch (error) {
 			await this.failSession(session);
@@ -766,6 +782,151 @@ export class DefaultSessionManager implements SessionManager {
 		this.emitStatus(session.sessionId, status);
 	}
 
+	private async handlePluginEvent(
+		rootSessionId: string,
+		event: { name: string; payload?: unknown },
+	): Promise<void> {
+		if (
+			event.name !== "steer_message" &&
+			event.name !== "queue_message" &&
+			event.name !== "pending_prompt"
+		) {
+			return;
+		}
+		const payload =
+			event.payload && typeof event.payload === "object"
+				? (event.payload as Record<string, unknown>)
+				: undefined;
+		const targetSessionId =
+			typeof payload?.sessionId === "string" &&
+			payload.sessionId.trim().length > 0
+				? payload.sessionId.trim()
+				: rootSessionId;
+		const prompt =
+			typeof payload?.prompt === "string" ? payload.prompt.trim() : "";
+		if (!prompt) {
+			return;
+		}
+		const delivery =
+			event.name === "steer_message"
+				? "steer"
+				: event.name === "queue_message"
+					? "queue"
+					: payload?.delivery === "steer"
+						? "steer"
+						: "queue";
+		this.enqueuePendingPrompt(targetSessionId, {
+			prompt,
+			delivery,
+		});
+	}
+
+	private enqueuePendingPrompt(
+		sessionId: string,
+		entry: {
+			prompt: string;
+			delivery: "queue" | "steer";
+			userImages?: string[];
+			userFiles?: string[];
+		},
+	): void {
+		const session = this.sessions.get(sessionId);
+		if (!session) {
+			return;
+		}
+		const { prompt, delivery, userImages, userFiles } = entry;
+		const existingIndex = session.pendingPrompts.findIndex(
+			(queued) => queued.prompt === prompt,
+		);
+		if (existingIndex >= 0) {
+			const [existing] = session.pendingPrompts.splice(existingIndex, 1);
+			if (delivery === "steer" || existing.delivery === "steer") {
+				session.pendingPrompts.unshift({
+					id: existing.id,
+					prompt,
+					delivery: "steer",
+					userImages: userImages ?? existing.userImages,
+					userFiles: userFiles ?? existing.userFiles,
+				});
+			} else {
+				session.pendingPrompts.push({
+					...existing,
+					userImages: userImages ?? existing.userImages,
+					userFiles: userFiles ?? existing.userFiles,
+				});
+			}
+		} else if (delivery === "steer") {
+			session.pendingPrompts.unshift({
+				id: `pending_${Date.now()}_${nanoid(5)}`,
+				prompt,
+				delivery,
+				userImages,
+				userFiles,
+			});
+		} else {
+			session.pendingPrompts.push({
+				id: `pending_${Date.now()}_${nanoid(5)}`,
+				prompt,
+				delivery,
+				userImages,
+				userFiles,
+			});
+		}
+		this.emitPendingPrompts(session);
+		queueMicrotask(() => {
+			void this.drainPendingPrompts(sessionId);
+		});
+	}
+
+	private async drainPendingPrompts(sessionId: string): Promise<void> {
+		const session = this.sessions.get(sessionId);
+		if (!session || session.drainingPendingPrompts) {
+			return;
+		}
+		const canStartRun =
+			typeof (session.agent as Agent & { canStartRun?: () => boolean })
+				.canStartRun === "function"
+				? (
+						session.agent as Agent & {
+							canStartRun: () => boolean;
+						}
+					).canStartRun()
+				: true;
+		if (!canStartRun) {
+			return;
+		}
+		const next = session.pendingPrompts.shift();
+		if (!next) {
+			return;
+		}
+		this.emitPendingPrompts(session);
+		this.emitPendingPromptSubmitted(session, next);
+		session.drainingPendingPrompts = true;
+		try {
+			await this.send({
+				sessionId,
+				prompt: next.prompt,
+				userImages: next.userImages,
+				userFiles: next.userFiles,
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			if (message.includes("already in progress")) {
+				session.pendingPrompts.unshift(next);
+				this.emitPendingPrompts(session);
+			} else {
+				throw error;
+			}
+		} finally {
+			session.drainingPendingPrompts = false;
+			if (session.pendingPrompts.length > 0) {
+				queueMicrotask(() => {
+					void this.drainPendingPrompts(sessionId);
+				});
+			}
+		}
+	}
+
 	// ── Agent event handling ────────────────────────────────────────────
 
 	private onAgentEvent(
@@ -791,6 +952,45 @@ export class DefaultSessionManager implements SessionManager {
 		handleAgentEvent(ctx, event);
 	}
 
+	private emitPendingPrompts(session: ActiveSession): void {
+		this.emit({
+			type: "pending_prompts",
+			payload: {
+				sessionId: session.sessionId,
+				prompts: session.pendingPrompts.map((entry) => ({
+					id: entry.id,
+					prompt: entry.prompt,
+					delivery: entry.delivery,
+					attachmentCount:
+						(entry.userImages?.length ?? 0) + (entry.userFiles?.length ?? 0),
+				})),
+			},
+		});
+	}
+
+	private emitPendingPromptSubmitted(
+		session: ActiveSession,
+		entry: {
+			id: string;
+			prompt: string;
+			delivery: "queue" | "steer";
+			userImages?: string[];
+			userFiles?: string[];
+		},
+	): void {
+		this.emit({
+			type: "pending_prompt_submitted",
+			payload: {
+				sessionId: session.sessionId,
+				id: entry.id,
+				prompt: entry.prompt,
+				delivery: entry.delivery,
+				attachmentCount:
+					(entry.userImages?.length ?? 0) + (entry.userFiles?.length ?? 0),
+			},
+		});
+	}
+
 	// ── Spawn / sub-agents ──────────────────────────────────────────────
 
 	private createSpawnTool(

package/src/session/session-config-builder.ts

@@ -24,6 +24,7 @@ export async function buildEffectiveConfig(
 	hookPath: string,
 	sessionId: string,
 	defaultTelemetry: ITelemetryService | undefined,
+	onPluginEvent?: (event: { name: string; payload?: unknown }) => void,
 ): Promise<{
 	config: CoreSessionConfig;
 	pluginSandboxShutdown?: () => Promise<void>;
@@ -54,6 +55,7 @@ export async function buildEffectiveConfig(
 		pluginPaths: input.config.pluginPaths,
 		workspacePath,
 		cwd: input.config.cwd,
+		onEvent: onPluginEvent,
 	});
 	const effectiveExtensions = mergeAgentExtensions(
 		input.config.extensions,

package/src/session/session-manager.ts

@@ -38,6 +38,7 @@ export interface SendSessionInput {
 	prompt: string;
 	userImages?: string[];
 	userFiles?: string[];
+	delivery?: "queue" | "steer";
 }
 
 export interface SessionAccumulatedUsage {

package/src/session/session-team-coordination.ts

@@ -52,6 +52,36 @@ export async function dispatchTeamEventToBackend(
 	invokeOptional: (method: string, ...args: unknown[]) => Promise<void>,
 ): Promise<void> {
 	switch (event.type) {
+		case "run_progress":
+			await invokeOptional(
+				"onTeamTaskProgress",
+				rootSessionId,
+				event.run.agentId,
+				event.message,
+				{ kind: event.message === "heartbeat" ? "heartbeat" : "progress" },
+			);
+			break;
+		case "agent_event":
+			if (
+				event.event.type === "content_start" &&
+				event.event.contentType === "text" &&
+				typeof event.event.text === "string"
+			) {
+				const snippet = event.event.text
+					.replace(/\s+/g, " ")
+					.trim()
+					.slice(0, 120);
+				if (snippet) {
+					await invokeOptional(
+						"onTeamTaskProgress",
+						rootSessionId,
+						event.agentId,
+						snippet,
+						{ kind: "text" },
+					);
+				}
+			}
+			break;
 		case "task_start":
 			await invokeOptional(
 				"onTeamTaskStart",

package/src/session/unified-session-persistence-service.ts

@@ -167,9 +167,15 @@ export interface SessionPersistenceAdapter {
 
 export class UnifiedSessionPersistenceService {
 	private readonly teamTaskSessionsByAgent = new Map<string, string[]>();
+	private readonly teamTaskLastHeartbeatBySession = new Map<string, number>();
+	private readonly teamTaskLastProgressLineBySession = new Map<
+		string,
+		string
+	>();
 	protected readonly artifacts: SessionArtifacts;
 	private static readonly STALE_REASON = "failed_external_process_exit";
 	private static readonly STALE_SOURCE = "stale_session_reconciler";
+	private static readonly TEAM_HEARTBEAT_LOG_INTERVAL_MS = 30_000;
 
 	constructor(private readonly adapter: SessionPersistenceAdapter) {
 		this.artifacts = new SessionArtifacts(() => this.ensureSessionsDir());
@@ -763,6 +769,45 @@ export class UnifiedSessionPersistenceService {
 			summary ?? `[done] ${status}`,
 		);
 		await this.applySubagentStatusBySessionId(sessionId, status);
+		this.teamTaskLastHeartbeatBySession.delete(sessionId);
+		this.teamTaskLastProgressLineBySession.delete(sessionId);
+	}
+
+	async onTeamTaskProgress(
+		rootSessionId: string,
+		agentId: string,
+		progress: string,
+		options?: { kind?: "heartbeat" | "progress" | "text" },
+	): Promise<void> {
+		const key = this.teamTaskQueueKey(rootSessionId, agentId);
+		const sessionId = this.teamTaskSessionsByAgent.get(key)?.[0];
+		if (!sessionId) return;
+
+		const trimmed = progress.trim();
+		if (!trimmed) return;
+
+		const kind = options?.kind ?? "progress";
+		if (kind === "heartbeat") {
+			const now = Date.now();
+			const last = this.teamTaskLastHeartbeatBySession.get(sessionId) ?? 0;
+			if (
+				now - last <
+				UnifiedSessionPersistenceService.TEAM_HEARTBEAT_LOG_INTERVAL_MS
+			) {
+				return;
+			}
+			this.teamTaskLastHeartbeatBySession.set(sessionId, now);
+		}
+
+		const line =
+			kind === "heartbeat"
+				? "[progress] heartbeat"
+				: kind === "text"
+					? `[progress] text: ${trimmed}`
+					: `[progress] ${trimmed}`;
+		if (this.teamTaskLastProgressLineBySession.get(sessionId) === line) return;
+		this.teamTaskLastProgressLineBySession.set(sessionId, line);
+		await this.appendSubagentTranscriptLine(sessionId, line);
 	}
 
 	// ── SubAgent lifecycle ────────────────────────────────────────────

package/src/session/utils/types.ts

@@ -22,10 +22,20 @@ export type ActiveSession = {
 	activeTeamRunIds: Set<string>;
 	pendingTeamRunUpdates: TeamRunUpdate[];
 	teamRunWaiters: Array<() => void>;
+	pendingPrompts: PendingPrompt[];
+	drainingPendingPrompts: boolean;
 	pluginSandboxShutdown?: () => Promise<void>;
 	turnUsageBaseline?: SessionAccumulatedUsage;
 };
 
+export type PendingPrompt = {
+	id: string;
+	prompt: string;
+	delivery: "queue" | "steer";
+	userImages?: string[];
+	userFiles?: string[];
+};
+
 export type TeamRunUpdate = {
 	runId: string;
 	agentId: string;

package/src/storage/sqlite-team-store.ts

@@ -120,6 +120,8 @@ export class SqliteTeamStore implements TeamStore {
 	}
 
 	private ensureSchema(db: SqliteDb): void {
+		db.exec("PRAGMA journal_mode = WAL;");
+		db.exec("PRAGMA busy_timeout = 5000;");
 		db.exec(`
 			CREATE TABLE IF NOT EXISTS team_events (
 				id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -130,16 +132,20 @@ export class SqliteTeamStore implements TeamStore {
 				causation_id TEXT,
 				correlation_id TEXT
 			);
+		`);
+		db.exec(`
 			CREATE INDEX IF NOT EXISTS idx_team_events_name_ts
 				ON team_events(team_name, ts DESC);
-
+		`);
+		db.exec(`
 			CREATE TABLE IF NOT EXISTS team_runtime_snapshot (
 				team_name TEXT PRIMARY KEY,
 				state_json TEXT NOT NULL,
 				teammates_json TEXT NOT NULL,
 				updated_at TEXT NOT NULL
 			);
-
+		`);
+		db.exec(`
 			CREATE TABLE IF NOT EXISTS team_tasks (
 				team_name TEXT NOT NULL,
 				task_id TEXT NOT NULL,
@@ -153,7 +159,8 @@ export class SqliteTeamStore implements TeamStore {
 				updated_at TEXT NOT NULL,
 				PRIMARY KEY(team_name, task_id)
 			);
-
+		`);
+		db.exec(`
 			CREATE TABLE IF NOT EXISTS team_runs (
 				team_name TEXT NOT NULL,
 				run_id TEXT NOT NULL,
@@ -169,9 +176,12 @@ export class SqliteTeamStore implements TeamStore {
 				version INTEGER NOT NULL DEFAULT 1,
 				PRIMARY KEY(team_name, run_id)
 			);
+		`);
+		db.exec(`
 			CREATE INDEX IF NOT EXISTS idx_team_runs_status
 				ON team_runs(team_name, status);
-
+		`);
+		db.exec(`
 			CREATE TABLE IF NOT EXISTS team_outcomes (
 				team_name TEXT NOT NULL,
 				outcome_id TEXT NOT NULL,
@@ -182,7 +192,8 @@ export class SqliteTeamStore implements TeamStore {
 				version INTEGER NOT NULL DEFAULT 1,
 				PRIMARY KEY(team_name, outcome_id)
 			);
-
+		`);
+		db.exec(`
 			CREATE TABLE IF NOT EXISTS team_outcome_fragments (
 				team_name TEXT NOT NULL,
 				outcome_id TEXT NOT NULL,

package/src/tools/definitions.test.ts

@@ -3,7 +3,18 @@ import {
 	createBashTool,
 	createDefaultTools,
 	createReadFilesTool,
+	createSkillsTool,
 } from "./definitions.js";
+import type { SkillsExecutorWithMetadata } from "./types.js";
+
+function createMockSkillsExecutor(
+	fn: (...args: unknown[]) => Promise<string> = async () => "ok",
+	configuredSkills?: SkillsExecutorWithMetadata["configuredSkills"],
+): SkillsExecutorWithMetadata {
+	const executor = fn as SkillsExecutorWithMetadata;
+	executor.configuredSkills = configuredSkills;
+	return executor;
+}
 
 describe("default skills tool", () => {
 	it("is included only when enabled with a skills executor", () => {
@@ -17,18 +28,43 @@ describe("default skills tool", () => {
 
 		const toolsWithExecutor = createDefaultTools({
 			executors: {
-				skills: async () => "ok",
+				skills: createMockSkillsExecutor(),
 			},
 			enableSkills: true,
 		});
 		expect(toolsWithExecutor.map((tool) => tool.name)).toContain("skills");
 	});
 
+	it("includes configured skill names in description", () => {
+		const executor = createMockSkillsExecutor(
+			async () => "ok",
+			[
+				{ id: "commit", name: "commit", disabled: false },
+				{
+					id: "review-pr",
+					name: "review-pr",
+					description: "Review a PR",
+					disabled: false,
+				},
+				{ id: "disabled-skill", name: "disabled-skill", disabled: true },
+			],
+		);
+		const tool = createSkillsTool(executor);
+		expect(tool.description).toContain("Available skills: commit, review-pr.");
+		expect(tool.description).not.toContain("disabled-skill");
+	});
+
+	it("omits skill list from description when no skills are configured", () => {
+		const executor = createMockSkillsExecutor(async () => "ok");
+		const tool = createSkillsTool(executor);
+		expect(tool.description).not.toContain("Available skills");
+	});
+
 	it("validates and executes skill invocation input", async () => {
 		const execute = vi.fn(async () => "loaded");
 		const tools = createDefaultTools({
 			executors: {
-				skills: execute,
+				skills: createMockSkillsExecutor(execute),
 			},
 			enableReadFiles: false,
 			enableSearch: false,
@@ -310,6 +346,48 @@ describe("default read_files tool", () => {
 			}),
 		);
 	});
+
+	it("treats null line bounds as full-file boundaries", async () => {
+		const execute = vi.fn(async () => "full file");
+		const tool = createReadFilesTool(execute);
+
+		const result = await tool.execute(
+			{
+				files: [
+					{
+						path: "/tmp/example.ts",
+						start_line: null,
+						end_line: null,
+					},
+				],
+			},
+			{
+				agentId: "agent-1",
+				conversationId: "conv-1",
+				iteration: 1,
+			},
+		);
+
+		expect(result).toEqual([
+			{
+				query: "/tmp/example.ts",
+				result: "full file",
+				success: true,
+			},
+		]);
+		expect(execute).toHaveBeenCalledWith(
+			{
+				path: "/tmp/example.ts",
+				start_line: null,
+				end_line: null,
+			},
+			expect.objectContaining({
+				agentId: "agent-1",
+				conversationId: "conv-1",
+				iteration: 1,
+			}),
+		);
+	});
 });
 
 describe("zod schema conversion", () => {
@@ -329,19 +407,20 @@ describe("zod schema conversion", () => {
 							"The absolute file path of a text file to read content from",
 					},
 					start_line: {
-						type: "integer",
-						description: "Optional one-based starting line number to read from",
+						anyOf: [{ type: "integer" }, { type: "null" }],
+						description:
+							"Optional one-based starting line number to read from; use null or omit for the start of the file",
 					},
 					end_line: {
-						type: "integer",
+						anyOf: [{ type: "integer" }, { type: "null" }],
 						description:
-							"Optional one-based ending line number to read through",
+							"Optional one-based ending line number to read through; use null or omit for the end of the file",
 					},
 				},
 				required: ["path"],
 			},
 			description:
-				"Array of file read requests. Omit start_line and end_line to return the full file content; provide them to return only that inclusive one-based line range. Prefer this tool over running terminal command to get file content for better performance and reliability.",
+				"Array of file read requests. Omit start_line/end_line or set them to null to return the full file content boundaries; provide integers to return only that inclusive one-based line range. Prefer this tool over running terminal command to get file content for better performance and reliability.",
 		});
 		expect(inputSchema.required).toEqual(["files"]);
 	});
@@ -349,7 +428,7 @@ describe("zod schema conversion", () => {
 	it("exposes skills args as optional nullable in tool schemas", () => {
 		const tools = createDefaultTools({
 			executors: {
-				skills: async () => "ok",
+				skills: createMockSkillsExecutor(),
 			},
 			enableReadFiles: false,
 			enableSearch: false,