@clinebot/core 0.0.14 → 0.0.16

package/src/session/file-session-service.ts

@@ -0,0 +1,280 @@
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { resolveSessionDataDir } from "@clinebot/shared/storage";
+import type { SessionRow } from "./session-service";
+import type {
+	PersistedSessionUpdateInput,
+	SessionPersistenceAdapter,
+} from "./unified-session-persistence-service";
+import { UnifiedSessionPersistenceService } from "./unified-session-persistence-service";
+
+interface FileSessionIndex {
+	version: 1;
+	sessions: Record<string, SessionRow>;
+}
+
+interface FileSpawnRequest {
+	id: number;
+	rootSessionId: string;
+	parentAgentId: string;
+	task?: string;
+	systemPrompt?: string;
+	createdAt: string;
+	consumedAt?: string;
+}
+
+interface FileSpawnQueue {
+	version: 1;
+	nextId: number;
+	requests: FileSpawnRequest[];
+}
+
+function nowIso(): string {
+	return new Date().toISOString();
+}
+
+function atomicWriteJson(path: string, value: unknown): void {
+	const tempPath = `${path}.tmp`;
+	writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+	renameSync(tempPath, path);
+}
+
+function defaultSessionsDir(): string {
+	return resolveSessionDataDir();
+}
+
+class FileSessionPersistenceAdapter implements SessionPersistenceAdapter {
+	constructor(
+		private readonly sessionsDirPath: string = defaultSessionsDir(),
+	) {}
+
+	ensureSessionsDir(): string {
+		if (!existsSync(this.sessionsDirPath)) {
+			mkdirSync(this.sessionsDirPath, { recursive: true });
+		}
+		return this.sessionsDirPath;
+	}
+
+	private indexPath(): string {
+		return join(this.ensureSessionsDir(), "sessions.index.json");
+	}
+
+	private spawnQueuePath(): string {
+		return join(this.ensureSessionsDir(), "subagent-spawn-queue.json");
+	}
+
+	private readIndex(): FileSessionIndex {
+		const path = this.indexPath();
+		if (!existsSync(path)) {
+			return { version: 1, sessions: {} };
+		}
+		try {
+			const parsed = JSON.parse(readFileSync(path, "utf8")) as FileSessionIndex;
+			if (parsed?.version === 1 && parsed.sessions) {
+				return parsed;
+			}
+		} catch {
+			// Ignore invalid persistence and fall back to an empty index.
+		}
+		return { version: 1, sessions: {} };
+	}
+
+	private writeIndex(index: FileSessionIndex): void {
+		atomicWriteJson(this.indexPath(), index);
+	}
+
+	private readQueue(): FileSpawnQueue {
+		const path = this.spawnQueuePath();
+		if (!existsSync(path)) {
+			return { version: 1, nextId: 1, requests: [] };
+		}
+		try {
+			const parsed = JSON.parse(readFileSync(path, "utf8")) as FileSpawnQueue;
+			if (
+				parsed?.version === 1 &&
+				typeof parsed.nextId === "number" &&
+				Array.isArray(parsed.requests)
+			) {
+				return parsed;
+			}
+		} catch {
+			// Ignore invalid persistence and fall back to an empty queue.
+		}
+		return { version: 1, nextId: 1, requests: [] };
+	}
+
+	private writeQueue(queue: FileSpawnQueue): void {
+		atomicWriteJson(this.spawnQueuePath(), queue);
+	}
+
+	async upsertSession(row: SessionRow): Promise<void> {
+		const index = this.readIndex();
+		index.sessions[row.sessionId] = row;
+		this.writeIndex(index);
+	}
+
+	async getSession(sessionId: string): Promise<SessionRow | undefined> {
+		return this.readIndex().sessions[sessionId];
+	}
+
+	async listSessions(options: {
+		limit: number;
+		parentSessionId?: string;
+		status?: string;
+	}): Promise<SessionRow[]> {
+		return Object.values(this.readIndex().sessions)
+			.filter((row) =>
+				options.parentSessionId !== undefined
+					? row.parentSessionId === options.parentSessionId
+					: true,
+			)
+			.filter((row) =>
+				options.status !== undefined ? row.status === options.status : true,
+			)
+			.sort((a, b) => b.startedAt.localeCompare(a.startedAt))
+			.slice(0, options.limit);
+	}
+
+	async updateSession(
+		input: PersistedSessionUpdateInput,
+	): Promise<{ updated: boolean; statusLock: number }> {
+		const index = this.readIndex();
+		const existing = index.sessions[input.sessionId];
+		if (!existing) {
+			return { updated: false, statusLock: 0 };
+		}
+		if (
+			input.expectedStatusLock !== undefined &&
+			existing.statusLock !== input.expectedStatusLock
+		) {
+			return { updated: false, statusLock: existing.statusLock };
+		}
+
+		const nextStatusLock =
+			input.expectedStatusLock !== undefined
+				? input.expectedStatusLock + 1
+				: existing.statusLock;
+		const next: SessionRow = {
+			...existing,
+			status: input.status ?? existing.status,
+			endedAt:
+				input.endedAt !== undefined
+					? input.endedAt
+					: (existing.endedAt ?? null),
+			exitCode:
+				input.exitCode !== undefined
+					? input.exitCode
+					: (existing.exitCode ?? null),
+			prompt:
+				input.prompt !== undefined ? input.prompt : (existing.prompt ?? null),
+			metadata:
+				input.metadata !== undefined
+					? (input.metadata ?? null)
+					: (existing.metadata ?? null),
+			parentSessionId:
+				input.parentSessionId !== undefined
+					? (input.parentSessionId ?? null)
+					: (existing.parentSessionId ?? null),
+			parentAgentId:
+				input.parentAgentId !== undefined
+					? (input.parentAgentId ?? null)
+					: (existing.parentAgentId ?? null),
+			agentId:
+				input.agentId !== undefined
+					? (input.agentId ?? null)
+					: (existing.agentId ?? null),
+			conversationId:
+				input.conversationId !== undefined
+					? (input.conversationId ?? null)
+					: (existing.conversationId ?? null),
+			statusLock: nextStatusLock,
+			isSubagent:
+				input.setRunning || input.parentSessionId !== undefined
+					? true
+					: existing.isSubagent,
+			updatedAt: nowIso(),
+		};
+
+		if (input.setRunning) {
+			next.status = "running";
+			next.endedAt = null;
+			next.exitCode = null;
+		}
+
+		index.sessions[input.sessionId] = next;
+		this.writeIndex(index);
+		return { updated: true, statusLock: next.statusLock };
+	}
+
+	async deleteSession(sessionId: string, cascade: boolean): Promise<boolean> {
+		const index = this.readIndex();
+		const existing = index.sessions[sessionId];
+		if (!existing) {
+			return false;
+		}
+		delete index.sessions[sessionId];
+		if (cascade) {
+			for (const row of Object.values(index.sessions)) {
+				if (row.parentSessionId === sessionId) {
+					delete index.sessions[row.sessionId];
+				}
+			}
+		}
+		this.writeIndex(index);
+		return true;
+	}
+
+	async enqueueSpawnRequest(input: {
+		rootSessionId: string;
+		parentAgentId: string;
+		task?: string;
+		systemPrompt?: string;
+	}): Promise<void> {
+		const queue = this.readQueue();
+		queue.requests.push({
+			id: queue.nextId,
+			rootSessionId: input.rootSessionId,
+			parentAgentId: input.parentAgentId,
+			task: input.task,
+			systemPrompt: input.systemPrompt,
+			createdAt: nowIso(),
+		});
+		queue.nextId += 1;
+		this.writeQueue(queue);
+	}
+
+	async claimSpawnRequest(
+		rootSessionId: string,
+		parentAgentId: string,
+	): Promise<string | undefined> {
+		const queue = this.readQueue();
+		const request = queue.requests.find(
+			(item) =>
+				item.rootSessionId === rootSessionId &&
+				item.parentAgentId === parentAgentId &&
+				!item.consumedAt,
+		);
+		if (!request) {
+			return undefined;
+		}
+		request.consumedAt = nowIso();
+		this.writeQueue(queue);
+		return request.task;
+	}
+}
+
+export class FileSessionService extends UnifiedSessionPersistenceService {
+	constructor(sessionsDir?: string) {
+		super(new FileSessionPersistenceAdapter(sessionsDir));
+	}
+
+	override ensureSessionsDir(): string {
+		return super.ensureSessionsDir();
+	}
+}

package/src/session/session-host.test.ts

@@ -0,0 +1,29 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@clinebot/rpc", () => ({
+	getRpcServerDefaultAddress: () => "ws://127.0.0.1:0",
+	getRpcServerHealth: vi.fn(async () => undefined),
+}));
+
+describe("resolveSessionBackend", () => {
+	afterEach(() => {
+		vi.resetModules();
+		vi.restoreAllMocks();
+	});
+
+	it("falls back to file session storage when sqlite initialization fails", async () => {
+		vi.doMock("../storage/sqlite-session-store", () => ({
+			SqliteSessionStore: class {
+				init(): void {
+					throw new Error("sqlite unavailable");
+				}
+			},
+		}));
+
+		const { resolveSessionBackend } = await import("./session-host");
+		const { FileSessionService } = await import("./file-session-service");
+
+		const backend = await resolveSessionBackend({ backendMode: "local" });
+		expect(backend).toBeInstanceOf(FileSessionService);
+	});
+});

package/src/session/session-host.ts

@@ -13,6 +13,7 @@ import { nanoid } from "nanoid";
 import { SqliteSessionStore } from "../storage/sqlite-session-store";
 import type { ToolExecutors } from "../tools";
 import { DefaultSessionManager } from "./default-session-manager";
+import { FileSessionService } from "./file-session-service";
 import { RpcCoreSessionService } from "./rpc-session-service";
 import { tryAcquireRpcSpawnLease } from "./rpc-spawn-lease";
 import type { SessionManager } from "./session-manager";
@@ -21,7 +22,10 @@ import { CoreSessionService } from "./session-service";
 const DEFAULT_RPC_ADDRESS =
 	process.env.CLINE_RPC_ADDRESS?.trim() || getRpcServerDefaultAddress();
 
-export type SessionBackend = RpcCoreSessionService | CoreSessionService;
+export type SessionBackend =
+	| RpcCoreSessionService
+	| CoreSessionService
+	| FileSessionService;
 
 let cachedBackend: SessionBackend | undefined;
 let backendInitPromise: Promise<SessionBackend> | undefined;
@@ -111,8 +115,18 @@ async function tryConnectRpcBackend(
 	}
 }
 
-function createLocalBackend(): CoreSessionService {
-	return new CoreSessionService(new SqliteSessionStore());
+function createLocalBackend(): SessionBackend {
+	try {
+		const store = new SqliteSessionStore();
+		store.init();
+		return new CoreSessionService(store);
+	} catch (error) {
+		console.warn(
+			"SQLite session persistence unavailable, falling back to file-based session storage.",
+			error,
+		);
+		return new FileSessionService();
+	}
 }
 
 function resolveHostDistinctId(explicitDistinctId: string | undefined): string {

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

@@ -163,11 +163,12 @@ export function shouldAutoContinueTeamRuns(
 	session: ActiveSession,
 	finishReason: AgentResult["finishReason"],
 ): boolean {
-	if (
-		session.aborting ||
-		finishReason === "aborted" ||
-		finishReason === "error"
-	) {
+	if (session.aborting) {
+		return false;
+	}
+	const canAutoContinue =
+		finishReason === "completed" || finishReason === "max_iterations";
+	if (!canAutoContinue) {
 		return false;
 	}
 	return (

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

@@ -8,8 +8,12 @@ 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 });
 		}
@@ -19,9 +23,9 @@ describe("UnifiedSessionPersistenceService", () => {
 		const sessionsDir = mkdtempSync(join(tmpdir(), "stale-session-reconcile-"));
 		tempDirs.push(sessionsDir);
 
-		const service = new CoreSessionService(
-			new SqliteSessionStore({ 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,

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

@@ -0,0 +1,257 @@
+import {
+	appendFileSync,
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import type {
+	TeamEvent,
+	TeamRuntimeState,
+	TeamTeammateSpec,
+} from "@clinebot/agents";
+import { resolveTeamDataDir } from "@clinebot/shared/storage";
+import type { TeamStore } from "../types/storage";
+
+function nowIso(): string {
+	return new Date().toISOString();
+}
+
+function sanitizeTeamName(name: string): string {
+	return name
+		.toLowerCase()
+		.replace(/[^a-z0-9._-]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+}
+
+function reviveTeamRuntimeStateDates(
+	state: TeamRuntimeState,
+): TeamRuntimeState {
+	return {
+		...state,
+		tasks: state.tasks.map((task) => ({
+			...task,
+			createdAt: new Date(task.createdAt),
+			updatedAt: new Date(task.updatedAt),
+		})),
+		mailbox: state.mailbox.map((message) => ({
+			...message,
+			sentAt: new Date(message.sentAt),
+			readAt: message.readAt ? new Date(message.readAt) : undefined,
+		})),
+		missionLog: state.missionLog.map((entry) => ({
+			...entry,
+			ts: new Date(entry.ts),
+		})),
+		runs: (state.runs ?? []).map((run) => ({
+			...run,
+			startedAt: new Date(run.startedAt),
+			endedAt: run.endedAt ? new Date(run.endedAt) : undefined,
+			nextAttemptAt: run.nextAttemptAt
+				? new Date(run.nextAttemptAt)
+				: undefined,
+			heartbeatAt: run.heartbeatAt ? new Date(run.heartbeatAt) : undefined,
+		})),
+		outcomes: (state.outcomes ?? []).map((outcome) => ({
+			...outcome,
+			createdAt: new Date(outcome.createdAt),
+			finalizedAt: outcome.finalizedAt
+				? new Date(outcome.finalizedAt)
+				: undefined,
+		})),
+		outcomeFragments: (state.outcomeFragments ?? []).map((fragment) => ({
+			...fragment,
+			createdAt: new Date(fragment.createdAt),
+			reviewedAt: fragment.reviewedAt
+				? new Date(fragment.reviewedAt)
+				: undefined,
+		})),
+	};
+}
+
+interface PersistedTeamEnvelope {
+	version: 1;
+	updatedAt: string;
+	teamState: TeamRuntimeState;
+	teammates: TeamTeammateSpec[];
+}
+
+export interface FileTeamStoreOptions {
+	teamDir?: string;
+}
+
+export interface TeamRuntimeLoadResult {
+	state?: TeamRuntimeState;
+	teammates: TeamTeammateSpec[];
+	interruptedRunIds: string[];
+}
+
+export class FileTeamStore implements TeamStore {
+	private readonly teamDirPath: string;
+
+	constructor(options: FileTeamStoreOptions = {}) {
+		this.teamDirPath = options.teamDir ?? resolveTeamDataDir();
+	}
+
+	init(): void {
+		this.ensureTeamDir();
+	}
+
+	listTeamNames(): string[] {
+		if (!existsSync(this.teamDirPath)) {
+			return [];
+		}
+		return readdirSync(this.teamDirPath, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory())
+			.filter((entry) => existsSync(this.statePath(entry.name)))
+			.map((entry) => entry.name)
+			.sort();
+	}
+
+	readState(teamName: string): TeamRuntimeState | undefined {
+		const envelope = this.readEnvelope(teamName);
+		return envelope?.teamState
+			? reviveTeamRuntimeStateDates(envelope.teamState)
+			: undefined;
+	}
+
+	readHistory(teamName: string, limit = 200): unknown[] {
+		const historyPath = this.historyPath(teamName);
+		if (!existsSync(historyPath)) {
+			return [];
+		}
+		return readFileSync(historyPath, "utf8")
+			.split("\n")
+			.map((line) => line.trim())
+			.filter(Boolean)
+			.map((line) => {
+				try {
+					return JSON.parse(line) as unknown;
+				} catch {
+					return undefined;
+				}
+			})
+			.filter((item): item is unknown => item !== undefined)
+			.reverse()
+			.slice(0, limit);
+	}
+
+	loadRuntime(teamName: string): TeamRuntimeLoadResult {
+		const envelope = this.readEnvelope(teamName);
+		const interruptedRunIds = this.markInProgressRunsInterrupted(
+			teamName,
+			"runtime_recovered",
+		);
+		return {
+			state: envelope?.teamState
+				? reviveTeamRuntimeStateDates(envelope.teamState)
+				: undefined,
+			teammates: envelope?.teammates ?? [],
+			interruptedRunIds,
+		};
+	}
+
+	handleTeamEvent(teamName: string, event: TeamEvent): void {
+		this.ensureTeamSubdir(teamName);
+		appendFileSync(
+			this.historyPath(teamName),
+			`${JSON.stringify({ ts: nowIso(), eventType: event.type, payload: event })}\n`,
+			"utf8",
+		);
+	}
+
+	persistRuntime(
+		teamName: string,
+		state: TeamRuntimeState,
+		teammates: TeamTeammateSpec[],
+	): void {
+		this.ensureTeamSubdir(teamName);
+		const envelope: PersistedTeamEnvelope = {
+			version: 1,
+			updatedAt: nowIso(),
+			teamState: state,
+			teammates,
+		};
+		const path = this.statePath(teamName);
+		const tempPath = `${path}.tmp`;
+		writeFileSync(tempPath, `${JSON.stringify(envelope, null, 2)}\n`, "utf8");
+		renameSync(tempPath, path);
+	}
+
+	markInProgressRunsInterrupted(teamName: string, reason: string): string[] {
+		const envelope = this.readEnvelope(teamName);
+		if (!envelope?.teamState?.runs?.length) {
+			return [];
+		}
+		const interrupted = envelope.teamState.runs
+			.filter((run) => run.status === "queued" || run.status === "running")
+			.map((run) => run.id);
+		if (interrupted.length === 0) {
+			return [];
+		}
+		const endedAt = new Date();
+		envelope.teamState = {
+			...envelope.teamState,
+			runs: envelope.teamState.runs.map((run) =>
+				run.status === "queued" || run.status === "running"
+					? {
+							...run,
+							status: "interrupted",
+							error: reason,
+							endedAt,
+						}
+					: run,
+			),
+		};
+		this.persistRuntime(teamName, envelope.teamState, envelope.teammates);
+		return interrupted;
+	}
+
+	private ensureTeamDir(): string {
+		if (!existsSync(this.teamDirPath)) {
+			mkdirSync(this.teamDirPath, { recursive: true });
+		}
+		return this.teamDirPath;
+	}
+
+	private ensureTeamSubdir(teamName: string): string {
+		const path = join(this.ensureTeamDir(), sanitizeTeamName(teamName));
+		if (!existsSync(path)) {
+			mkdirSync(path, { recursive: true });
+		}
+		return path;
+	}
+
+	private statePath(teamName: string): string {
+		return join(this.ensureTeamDir(), sanitizeTeamName(teamName), "state.json");
+	}
+
+	private historyPath(teamName: string): string {
+		return join(
+			this.ensureTeamDir(),
+			sanitizeTeamName(teamName),
+			"task-history.jsonl",
+		);
+	}
+
+	private readEnvelope(teamName: string): PersistedTeamEnvelope | undefined {
+		const path = this.statePath(teamName);
+		if (!existsSync(path)) {
+			return undefined;
+		}
+		try {
+			const parsed = JSON.parse(
+				readFileSync(path, "utf8"),
+			) as PersistedTeamEnvelope;
+			if (parsed?.version === 1 && parsed.teamState) {
+				return parsed;
+			}
+		} catch {
+			// Ignore invalid persistence and fall back to undefined.
+		}
+		return undefined;
+	}
+}

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

@@ -57,6 +57,11 @@ export class SqliteSessionStore implements SessionStore {
 		return db;
 	}
 
+	close(): void {
+		this.db?.close?.();
+		this.db = undefined;
+	}
+
 	run(sql: string, params: unknown[] = []): { changes?: number } {
 		return this.getRawDb()
 			.prepare(sql)

package/src/storage/team-store.ts

@@ -1,5 +1,40 @@
 export type { TeamStore } from "../types/storage";
 export {
+	FileTeamStore,
+	type FileTeamStoreOptions,
+} from "./file-team-store";
+export {
+	SqliteTeamStore,
+	type SqliteTeamStoreOptions,
+} from "./sqlite-team-store";
+
+import { FileTeamStore } from "./file-team-store";
+import {
 	SqliteTeamStore,
 	type SqliteTeamStoreOptions,
 } from "./sqlite-team-store";
+
+export function createLocalTeamStore(options: SqliteTeamStoreOptions = {}): {
+	init(): void;
+	listTeamNames(): string[];
+	readState(teamName: string): ReturnType<FileTeamStore["readState"]>;
+	readHistory(teamName: string, limit?: number): unknown[];
+	loadRuntime(teamName: string): ReturnType<FileTeamStore["loadRuntime"]>;
+	handleTeamEvent: FileTeamStore["handleTeamEvent"];
+	persistRuntime: FileTeamStore["persistRuntime"];
+	markInProgressRunsInterrupted: FileTeamStore["markInProgressRunsInterrupted"];
+} {
+	try {
+		const store = new SqliteTeamStore(options);
+		store.init();
+		return store;
+	} catch (error) {
+		console.warn(
+			"SQLite team persistence unavailable, falling back to file-based team storage.",
+			error,
+		);
+		const store = new FileTeamStore({ teamDir: options.teamDir });
+		store.init();
+		return store;
+	}
+}