@clinebot/core 0.0.21 → 0.0.23

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

@@ -0,0 +1,229 @@
+import type { AgentResult, TeamEvent } from "@clinebot/agents";
+import { formatUserInputBlock } from "@clinebot/shared";
+import {
+	buildTeamProgressSummary,
+	toTeamProgressLifecycleEvent,
+} from "../team";
+import type { CoreSessionEvent } from "../types/events";
+import type { ActiveSession, TeamRunUpdate } from "./utils/types";
+
+export function trackTeamRunState(
+	session: ActiveSession,
+	event: TeamEvent,
+): void {
+	switch (event.type) {
+		case "run_queued":
+		case "run_started":
+			session.activeTeamRunIds.add(event.run.id);
+			break;
+		case "run_completed":
+		case "run_failed":
+		case "run_cancelled":
+		case "run_interrupted": {
+			let runError: string | undefined;
+			if (event.type === "run_failed") {
+				runError = event.run.error;
+			} else if (
+				event.type === "run_cancelled" ||
+				event.type === "run_interrupted"
+			) {
+				runError = event.run.error ?? event.reason;
+			}
+			session.activeTeamRunIds.delete(event.run.id);
+			session.pendingTeamRunUpdates.push({
+				runId: event.run.id,
+				agentId: event.run.agentId,
+				taskId: event.run.taskId,
+				status: event.type.replace("run_", "") as TeamRunUpdate["status"],
+				error: runError,
+				iterations: event.run.result?.iterations,
+			});
+			notifyTeamRunWaiters(session);
+			break;
+		}
+		default:
+			break;
+	}
+}
+
+export async function dispatchTeamEventToBackend(
+	rootSessionId: string,
+	event: TeamEvent,
+	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",
+				rootSessionId,
+				event.agentId,
+				event.message,
+			);
+			break;
+		case "task_end": {
+			if (event.error) {
+				await invokeOptional(
+					"onTeamTaskEnd",
+					rootSessionId,
+					event.agentId,
+					"failed",
+					`[error] ${event.error.message}`,
+					event.messages,
+				);
+			} else if (event.result?.finishReason === "aborted") {
+				await invokeOptional(
+					"onTeamTaskEnd",
+					rootSessionId,
+					event.agentId,
+					"cancelled",
+					"[done] aborted",
+					event.result.messages,
+				);
+			} else {
+				await invokeOptional(
+					"onTeamTaskEnd",
+					rootSessionId,
+					event.agentId,
+					"completed",
+					`[done] ${event.result?.finishReason ?? "completed"}`,
+					event.result?.messages,
+				);
+			}
+			break;
+		}
+		default:
+			break;
+	}
+}
+
+export function emitTeamProgress(
+	session: ActiveSession,
+	rootSessionId: string,
+	event: TeamEvent,
+	emit: (event: CoreSessionEvent) => void,
+): void {
+	if (!session.runtime.teamRuntime) return;
+	const teamName = session.config.teamName?.trim() || "team";
+	emit({
+		type: "team_progress",
+		payload: {
+			sessionId: rootSessionId,
+			teamName,
+			lifecycle: toTeamProgressLifecycleEvent({
+				teamName,
+				sessionId: rootSessionId,
+				event,
+			}),
+			summary: buildTeamProgressSummary(
+				teamName,
+				session.runtime.teamRuntime.exportState(),
+			),
+		},
+	});
+}
+
+export function hasPendingTeamRunWork(session: ActiveSession): boolean {
+	return (
+		session.activeTeamRunIds.size > 0 ||
+		session.pendingTeamRunUpdates.length > 0
+	);
+}
+
+export function shouldAutoContinueTeamRuns(
+	session: ActiveSession,
+	finishReason: AgentResult["finishReason"],
+): boolean {
+	if (session.aborting) {
+		return false;
+	}
+	const canAutoContinue =
+		finishReason === "completed" || finishReason === "max_iterations";
+	if (!canAutoContinue) {
+		return false;
+	}
+	return (
+		session.config.enableAgentTeams === true && hasPendingTeamRunWork(session)
+	);
+}
+
+export function notifyTeamRunWaiters(session: ActiveSession): void {
+	const waiters = session.teamRunWaiters.splice(0);
+	for (const resolve of waiters) resolve();
+}
+
+export async function waitForTeamRunUpdates(
+	session: ActiveSession,
+): Promise<TeamRunUpdate[]> {
+	while (true) {
+		if (session.aborting) return [];
+		if (session.pendingTeamRunUpdates.length > 0) {
+			const updates = [...session.pendingTeamRunUpdates];
+			session.pendingTeamRunUpdates.length = 0;
+			return updates;
+		}
+		if (session.activeTeamRunIds.size === 0) return [];
+		await new Promise<void>((resolve) => {
+			session.teamRunWaiters.push(resolve);
+		});
+	}
+}
+
+export function buildTeamRunContinuationPrompt(
+	session: ActiveSession,
+	updates: TeamRunUpdate[],
+): string {
+	const lines = updates.map((u) => {
+		const parts = [`- ${u.runId} (${u.agentId}) -> ${u.status}`];
+		if (u.taskId) parts.push(` task=${u.taskId}`);
+		if (typeof u.iterations === "number")
+			parts.push(` iterations=${u.iterations}`);
+		if (u.error) parts.push(` error=${u.error}`);
+		return parts.join("");
+	});
+	const remaining = session.activeTeamRunIds.size;
+	const instruction =
+		remaining > 0
+			? `There are still ${remaining} teammate run(s) in progress. Continue coordination and decide whether to wait for more updates.`
+			: "No teammate runs are currently in progress. Continue coordination using these updates.";
+	return formatModePrompt(
+		`System-delivered teammate async run updates:\n${lines.join("\n")}\n\n${instruction}`,
+		session.config.mode,
+	);
+}
+
+export function formatModePrompt(
+	prompt: string,
+	mode: "act" | "plan" | undefined,
+): string {
+	return formatUserInputBlock(prompt, mode === "plan" ? "plan" : "act");
+}

package/src/session/session-telemetry.ts

@@ -0,0 +1,100 @@
+import type { ITelemetryService } from "@clinebot/shared";
+import {
+	listHookConfigFiles,
+	resolveDocumentsHooksDirectoryPath,
+} from "../agents/hooks-config-loader";
+import type { enrichPromptWithMentions } from "../input";
+import {
+	captureHookDiscovery,
+	captureMentionFailed,
+	captureMentionSearchResults,
+	captureMentionUsed,
+	captureTaskCreated,
+	captureTaskRestarted,
+	type TelemetryAgentIdentityProperties,
+} from "../telemetry/core-events";
+import type { SessionSource } from "../types/common";
+import type { CoreSessionConfig } from "../types/config";
+
+export function emitSessionCreationTelemetry(
+	config: CoreSessionConfig,
+	sessionId: string,
+	source: SessionSource,
+	isRestart: boolean,
+	workspacePath: string,
+	agentIdentity?: Partial<TelemetryAgentIdentityProperties>,
+): void {
+	if (isRestart) {
+		captureTaskRestarted(config.telemetry, {
+			ulid: sessionId,
+			apiProvider: config.providerId,
+			...agentIdentity,
+		});
+	} else {
+		captureTaskCreated(config.telemetry, {
+			ulid: sessionId,
+			apiProvider: config.providerId,
+			...agentIdentity,
+		});
+	}
+	captureHookDiscoveryTelemetry(config.telemetry, { workspacePath });
+	config.telemetry?.capture({
+		event: "session.started",
+		properties: {
+			sessionId,
+			source,
+			providerId: config.providerId,
+			modelId: config.modelId,
+			enableTools: config.enableTools,
+			enableSpawnAgent: config.enableSpawnAgent,
+			enableAgentTeams: config.enableAgentTeams,
+			...agentIdentity,
+		},
+	});
+}
+
+export function captureHookDiscoveryTelemetry(
+	telemetry: ITelemetryService | undefined,
+	options: { workspacePath: string },
+): void {
+	const globalHooksDir = resolveDocumentsHooksDirectoryPath();
+	const entries = listHookConfigFiles(options.workspacePath);
+	const counts = new Map<string, { global: number; workspace: number }>();
+	for (const entry of entries) {
+		const hookName = entry.hookEventName ?? "unknown";
+		const current = counts.get(hookName) ?? { global: 0, workspace: 0 };
+		if (
+			entry.path === globalHooksDir ||
+			entry.path.startsWith(`${globalHooksDir}/`)
+		) {
+			current.global += 1;
+		} else {
+			current.workspace += 1;
+		}
+		counts.set(hookName, current);
+	}
+	for (const [hookName, count] of counts.entries()) {
+		captureHookDiscovery(telemetry, hookName, count.global, count.workspace);
+	}
+}
+
+export function emitMentionTelemetry(
+	telemetry: ITelemetryService | undefined,
+	enriched: Awaited<ReturnType<typeof enrichPromptWithMentions>>,
+): void {
+	for (const mention of enriched.mentions) {
+		captureMentionSearchResults(
+			telemetry,
+			mention,
+			enriched.matchedFiles.includes(mention) ? 1 : 0,
+			"file",
+			!enriched.matchedFiles.includes(mention),
+		);
+	}
+	for (const matched of enriched.matchedFiles) {
+		captureMentionUsed(telemetry, "file", matched.length);
+	}
+	for (const ignored of enriched.ignoredMentions) {
+		captureMentionFailed(telemetry, "file", "not_found", ignored);
+	}
+}

package/src/session/sqlite-rpc-session-backend.ts

@@ -0,0 +1,303 @@
+import type {
+	RpcSessionBackend,
+	RpcSessionRow,
+	RpcSessionStatus,
+	RpcSessionUpdateInput,
+	RpcSpawnQueueItem,
+} from "@clinebot/rpc";
+import {
+	asBool,
+	asOptionalString,
+	asString,
+	nowIso,
+	toBoolInt,
+} from "@clinebot/shared/db";
+import { SqliteSessionStore } from "../storage/sqlite-session-store";
+
+export interface SqliteRpcSessionBackendOptions {
+	sessionsDir?: string;
+}
+
+export class SqliteRpcSessionBackend implements RpcSessionBackend {
+	private readonly store: SqliteSessionStore;
+
+	constructor(options: SqliteRpcSessionBackendOptions = {}) {
+		this.store = new SqliteSessionStore({ sessionsDir: options.sessionsDir });
+	}
+
+	public init(): void {
+		this.store.init();
+	}
+
+	public upsertSession(row: RpcSessionRow): void {
+		this.store.run(
+			`INSERT OR REPLACE INTO sessions (
+				session_id, source, pid, started_at, ended_at, exit_code, status, status_lock, interactive,
+				provider, model, cwd, workspace_root, team_name, enable_tools, enable_spawn, enable_teams,
+				parent_session_id, parent_agent_id, agent_id, conversation_id, is_subagent, prompt,
+				metadata_json, transcript_path, hook_path, messages_path, updated_at
+			) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+			[
+				row.sessionId,
+				row.source,
+				row.pid,
+				row.startedAt,
+				row.endedAt ?? null,
+				row.exitCode ?? null,
+				row.status,
+				row.statusLock,
+				toBoolInt(row.interactive),
+				row.provider,
+				row.model,
+				row.cwd,
+				row.workspaceRoot,
+				row.teamName ?? null,
+				toBoolInt(row.enableTools),
+				toBoolInt(row.enableSpawn),
+				toBoolInt(row.enableTeams),
+				row.parentSessionId ?? null,
+				row.parentAgentId ?? null,
+				row.agentId ?? null,
+				row.conversationId ?? null,
+				toBoolInt(row.isSubagent),
+				row.prompt ?? null,
+				row.metadata ? JSON.stringify(row.metadata) : null,
+				row.transcriptPath,
+				row.hookPath,
+				row.messagesPath ?? null,
+				row.updatedAt || nowIso(),
+			],
+		);
+	}
+
+	public getSession(sessionId: string): RpcSessionRow | undefined {
+		const row = this.store.queryOne<Record<string, unknown>>(
+			`SELECT session_id, source, pid, started_at, ended_at, exit_code, status, status_lock, interactive,
+				provider, model, cwd, workspace_root, team_name, enable_tools, enable_spawn, enable_teams,
+				parent_session_id, parent_agent_id, agent_id, conversation_id, is_subagent, prompt,
+				metadata_json, transcript_path, hook_path, messages_path, updated_at
+			 FROM sessions WHERE session_id = ?`,
+			[sessionId],
+		);
+		if (!row) {
+			return undefined;
+		}
+		return {
+			sessionId: asString(row.session_id),
+			source: asString(row.source),
+			pid: Number(row.pid ?? 0),
+			startedAt: asString(row.started_at),
+			endedAt: (row.ended_at as string | null | undefined) ?? null,
+			exitCode: (row.exit_code as number | null | undefined) ?? null,
+			status: asString(row.status) as RpcSessionStatus,
+			statusLock: Number(row.status_lock ?? 0),
+			interactive: asBool(row.interactive),
+			provider: asString(row.provider),
+			model: asString(row.model),
+			cwd: asString(row.cwd),
+			workspaceRoot: asString(row.workspace_root),
+			teamName: asOptionalString(row.team_name),
+			enableTools: asBool(row.enable_tools),
+			enableSpawn: asBool(row.enable_spawn),
+			enableTeams: asBool(row.enable_teams),
+			parentSessionId: asOptionalString(row.parent_session_id),
+			parentAgentId: asOptionalString(row.parent_agent_id),
+			agentId: asOptionalString(row.agent_id),
+			conversationId: asOptionalString(row.conversation_id),
+			isSubagent: asBool(row.is_subagent),
+			prompt: asOptionalString(row.prompt),
+			metadata: (() => {
+				const raw = asOptionalString(row.metadata_json);
+				if (!raw) {
+					return undefined;
+				}
+				try {
+					const parsed = JSON.parse(raw) as unknown;
+					if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+						return parsed as Record<string, unknown>;
+					}
+				} catch {
+					// Ignore malformed metadata payloads.
+				}
+				return undefined;
+			})(),
+			transcriptPath: asString(row.transcript_path),
+			hookPath: asString(row.hook_path),
+			messagesPath: asOptionalString(row.messages_path),
+			updatedAt: asString(row.updated_at) || nowIso(),
+		};
+	}
+
+	public listSessions(options: {
+		limit: number;
+		parentSessionId?: string;
+		status?: string;
+	}): RpcSessionRow[] {
+		const where: string[] = [];
+		const params: unknown[] = [];
+		if (options.parentSessionId) {
+			where.push("parent_session_id = ?");
+			params.push(options.parentSessionId);
+		}
+		if (options.status) {
+			where.push("status = ?");
+			params.push(options.status);
+		}
+		const whereClause = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+		const limit = Math.max(1, Math.floor(options.limit));
+		const rows = this.store.queryAll<{ session_id?: string }>(
+			`SELECT session_id FROM sessions ${whereClause} ORDER BY started_at DESC LIMIT ?`,
+			[...params, limit],
+		);
+		const out: RpcSessionRow[] = [];
+		for (const row of rows) {
+			if (!row.session_id) {
+				continue;
+			}
+			const item = this.getSession(row.session_id);
+			if (item) {
+				out.push(item);
+			}
+		}
+		return out;
+	}
+
+	public updateSession(input: RpcSessionUpdateInput): {
+		updated: boolean;
+		statusLock: number;
+	} {
+		const existing = this.getSession(input.sessionId);
+		if (!existing) {
+			return { updated: false, statusLock: 0 };
+		}
+		if (
+			typeof input.expectedStatusLock === "number" &&
+			existing.statusLock !== input.expectedStatusLock
+		) {
+			return { updated: false, statusLock: existing.statusLock };
+		}
+		const nextLock = existing.statusLock + 1;
+		const nextStatus = input.setRunning
+			? "running"
+			: (input.status ?? existing.status);
+		const nextEndedAt =
+			input.setRunning === true
+				? null
+				: input.endedAt !== undefined
+					? input.endedAt
+					: (existing.endedAt ?? null);
+		const nextExitCode =
+			input.setRunning === true
+				? null
+				: input.exitCode !== undefined
+					? input.exitCode
+					: (existing.exitCode ?? null);
+		const nextPrompt =
+			input.prompt !== undefined
+				? (input.prompt ?? undefined)
+				: existing.prompt;
+		const nextMetadata =
+			input.metadata !== undefined
+				? (input.metadata ?? undefined)
+				: existing.metadata;
+
+		this.store.run(
+			`UPDATE sessions
+			 SET status = ?, ended_at = ?, exit_code = ?, prompt = ?, metadata_json = ?,
+				 parent_session_id = ?, parent_agent_id = ?, agent_id = ?, conversation_id = ?,
+				 status_lock = ?, updated_at = ?
+			 WHERE session_id = ?`,
+			[
+				nextStatus,
+				nextEndedAt,
+				nextExitCode,
+				nextPrompt ?? null,
+				nextMetadata ? JSON.stringify(nextMetadata) : null,
+				input.parentSessionId !== undefined
+					? (input.parentSessionId ?? null)
+					: (existing.parentSessionId ?? null),
+				input.parentAgentId !== undefined
+					? (input.parentAgentId ?? null)
+					: (existing.parentAgentId ?? null),
+				input.agentId !== undefined
+					? (input.agentId ?? null)
+					: (existing.agentId ?? null),
+				input.conversationId !== undefined
+					? (input.conversationId ?? null)
+					: (existing.conversationId ?? null),
+				nextLock,
+				nowIso(),
+				input.sessionId,
+			],
+		);
+		return { updated: true, statusLock: nextLock };
+	}
+
+	public deleteSession(sessionId: string): boolean {
+		const changes =
+			this.store.run("DELETE FROM sessions WHERE session_id = ?", [sessionId])
+				.changes ?? 0;
+		return changes > 0;
+	}
+
+	public deleteSessionsByParent(parentSessionId: string): void {
+		this.store.run("DELETE FROM sessions WHERE parent_session_id = ?", [
+			parentSessionId,
+		]);
+	}
+
+	public enqueueSpawnRequest(input: {
+		rootSessionId: string;
+		parentAgentId: string;
+		task?: string;
+		systemPrompt?: string;
+	}): void {
+		this.store.run(
+			`INSERT INTO subagent_spawn_queue (root_session_id, parent_agent_id, task, system_prompt, created_at, consumed_at)
+			 VALUES (?, ?, ?, ?, ?, NULL)`,
+			[
+				input.rootSessionId,
+				input.parentAgentId,
+				input.task ?? null,
+				input.systemPrompt ?? null,
+				nowIso(),
+			],
+		);
+	}
+
+	public claimSpawnRequest(
+		rootSessionId: string,
+		parentAgentId: string,
+	): RpcSpawnQueueItem | undefined {
+		const row = this.store.queryOne<Record<string, unknown>>(
+			`SELECT id, root_session_id, parent_agent_id, task, system_prompt, created_at, consumed_at
+			 FROM subagent_spawn_queue
+			 WHERE root_session_id = ? AND parent_agent_id = ? AND consumed_at IS NULL
+			 ORDER BY id ASC LIMIT 1`,
+			[rootSessionId, parentAgentId],
+		);
+		if (!row || typeof row.id !== "number") {
+			return undefined;
+		}
+		const consumedAt = nowIso();
+		this.store.run(
+			"UPDATE subagent_spawn_queue SET consumed_at = ? WHERE id = ?",
+			[consumedAt, row.id],
+		);
+		return {
+			id: row.id,
+			rootSessionId: asString(row.root_session_id),
+			parentAgentId: asString(row.parent_agent_id),
+			task: asOptionalString(row.task),
+			systemPrompt: asOptionalString(row.system_prompt),
+			createdAt: asString(row.created_at),
+			consumedAt,
+		};
+	}
+}
+
+export function createSqliteRpcSessionBackend(
+	options: SqliteRpcSessionBackendOptions = {},
+): RpcSessionBackend {
+	return new SqliteRpcSessionBackend(options);
+}

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

@@ -0,0 +1,85 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { SqliteSessionStore } from "../storage/sqlite-session-store";
+import { SessionSource } from "../types/common";
+import { CoreSessionService } from "./session-service";
+
+describe("UnifiedSessionPersistenceService", () => {
+	const tempDirs: string[] = [];
+	const stores: Array<SqliteSessionStore> = [];
+
+	afterEach(() => {
+		for (const store of stores.splice(0)) {
+			store.close();
+		}
+		for (const dir of tempDirs.splice(0)) {
+			rmSync(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("reconciles dead running sessions into failed manifests with terminal markers", async () => {
+		const sessionsDir = mkdtempSync(join(tmpdir(), "stale-session-reconcile-"));
+		tempDirs.push(sessionsDir);
+
+		const store = new SqliteSessionStore({ sessionsDir });
+		stores.push(store);
+		const service = new CoreSessionService(store);
+		const sessionId = "stale-root-session";
+		const artifacts = await service.createRootSessionWithArtifacts({
+			sessionId,
+			source: SessionSource.CLI,
+			pid: 999_999_999,
+			interactive: false,
+			provider: "mock-provider",
+			model: "mock-model",
+			cwd: "/tmp/project",
+			workspaceRoot: "/tmp/project",
+			enableTools: true,
+			enableSpawn: true,
+			enableTeams: false,
+			prompt: "hello",
+			startedAt: "2026-01-01T00:00:00.000Z",
+		});
+
+		const reconciled = await service.reconcileDeadSessions();
+		expect(reconciled).toBe(1);
+
+		const rows = await service.listSessions(10);
+		expect(rows).toHaveLength(1);
+		expect(rows[0]).toMatchObject({
+			sessionId,
+			status: "failed",
+			exitCode: 1,
+		});
+		expect(rows[0]?.endedAt).toBeTruthy();
+
+		const manifest = JSON.parse(
+			readFileSync(artifacts.manifestPath, "utf8"),
+		) as Record<string, unknown>;
+		expect(manifest.status).toBe("failed");
+		expect(manifest.exit_code).toBe(1);
+		expect(manifest.ended_at).toBeTruthy();
+		expect(manifest.metadata).toMatchObject({
+			terminal_marker: "failed_external_process_exit",
+			terminal_marker_pid: 999_999_999,
+			terminal_marker_source: "stale_session_reconciler",
+		});
+		expect(
+			(manifest.metadata as Record<string, unknown>).terminal_marker_at,
+		).toBeTruthy();
+
+		expect(existsSync(artifacts.hookPath)).toBe(true);
+		expect(existsSync(artifacts.transcriptPath)).toBe(true);
+		expect(readFileSync(artifacts.hookPath, "utf8")).toContain(
+			'"hookName":"session_shutdown"',
+		);
+		expect(readFileSync(artifacts.hookPath, "utf8")).toContain(
+			'"reason":"failed_external_process_exit"',
+		);
+		expect(readFileSync(artifacts.transcriptPath, "utf8")).toContain(
+			"[shutdown] failed_external_process_exit",
+		);
+	});
+});