@clinebot/core 0.0.0

package/src/session/session-artifacts.ts

@@ -0,0 +1,106 @@
+import {
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	rmdirSync,
+	unlinkSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+export function nowIso(): string {
+	return new Date().toISOString();
+}
+
+export function unlinkIfExists(path: string | null | undefined): void {
+	if (!path || !existsSync(path)) {
+		return;
+	}
+	try {
+		unlinkSync(path);
+	} catch {
+		// Best effort cleanup.
+	}
+}
+
+export interface SessionArtifactPaths {
+	transcriptPath: string;
+	hookPath: string;
+	messagesPath: string;
+}
+
+export class SessionArtifacts {
+	constructor(private readonly ensureSessionsDir: () => string) {}
+
+	public sessionArtifactsDir(sessionId: string): string {
+		return join(this.ensureSessionsDir(), sessionId);
+	}
+
+	public ensureSessionArtifactsDir(sessionId: string): string {
+		const dir = this.sessionArtifactsDir(sessionId);
+		if (!existsSync(dir)) {
+			mkdirSync(dir, { recursive: true });
+		}
+		return dir;
+	}
+
+	public sessionTranscriptPath(sessionId: string): string {
+		return join(this.ensureSessionArtifactsDir(sessionId), `${sessionId}.log`);
+	}
+
+	public sessionHookPath(sessionId: string): string {
+		return join(
+			this.ensureSessionArtifactsDir(sessionId),
+			`${sessionId}.hooks.jsonl`,
+		);
+	}
+
+	public sessionMessagesPath(sessionId: string): string {
+		return join(
+			this.ensureSessionArtifactsDir(sessionId),
+			`${sessionId}.messages.json`,
+		);
+	}
+
+	public sessionManifestPath(sessionId: string, ensureDir = true): string {
+		const base = ensureDir
+			? this.ensureSessionArtifactsDir(sessionId)
+			: this.sessionArtifactsDir(sessionId);
+		return join(base, `${sessionId}.json`);
+	}
+
+	public removeSessionDirIfEmpty(sessionId: string): void {
+		let dir = this.sessionArtifactsDir(sessionId);
+		const sessionsDir = this.ensureSessionsDir();
+		while (dir.startsWith(sessionsDir) && dir !== sessionsDir) {
+			if (!existsSync(dir)) {
+				dir = dirname(dir);
+				continue;
+			}
+			try {
+				if (readdirSync(dir).length > 0) {
+					break;
+				}
+				rmdirSync(dir);
+			} catch {
+				// Best-effort cleanup.
+				break;
+			}
+			dir = dirname(dir);
+		}
+	}
+
+	public subagentArtifactPaths(
+		sessionId: string,
+		subAgentId: string,
+		activeTeamTaskSessionId?: string,
+	): SessionArtifactPaths {
+		void subAgentId;
+		void activeTeamTaskSessionId;
+		const dir = this.ensureSessionArtifactsDir(sessionId);
+		return {
+			transcriptPath: join(dir, `${sessionId}.log`),
+			hookPath: join(dir, `${sessionId}.hooks.jsonl`),
+			messagesPath: join(dir, `${sessionId}.messages.json`),
+		};
+	}
+}

package/src/session/session-graph.ts

@@ -0,0 +1,90 @@
+import type { HookEventPayload } from "@clinebot/agents";
+import { nanoid } from "nanoid";
+import type { SessionStatus } from "../types/common";
+
+export function sanitizeSessionToken(value: string): string {
+	return value.replace(/[^a-zA-Z0-9._-]+/g, "_");
+}
+
+export function makeSubSessionId(
+	rootSessionId: string,
+	agentId: string,
+): string {
+	const root = sanitizeSessionToken(rootSessionId);
+	const agent = sanitizeSessionToken(agentId);
+	const joined = `${root}__${agent}`;
+	return joined.length > 180 ? joined.slice(0, 180) : joined;
+}
+
+export function makeTeamTaskSubSessionId(
+	rootSessionId: string,
+	agentId: string,
+): string {
+	const root = sanitizeSessionToken(rootSessionId);
+	const agent = sanitizeSessionToken(agentId);
+	return `${root}__teamtask__${agent}__${nanoid(6)}`;
+}
+
+export function parseTeamTaskSubSessionId(
+	sessionId: string,
+): { rootSessionId: string; agentId: string; teamTaskId: string } | null {
+	const marker = "__teamtask__";
+	const markerIndex = sessionId.indexOf(marker);
+	if (markerIndex <= 0) {
+		return null;
+	}
+	const rootSessionId = sessionId.slice(0, markerIndex);
+	const remainder = sessionId.slice(markerIndex + marker.length);
+	const lastSeparator = remainder.lastIndexOf("__");
+	if (lastSeparator <= 0) {
+		return null;
+	}
+	const agentId = remainder.slice(0, lastSeparator);
+	const teamTaskId = remainder.slice(lastSeparator + 2);
+	if (!rootSessionId || !agentId || !teamTaskId) {
+		return null;
+	}
+	return { rootSessionId, agentId, teamTaskId };
+}
+
+export function parseSubSessionId(
+	sessionId: string,
+): { rootSessionId: string; agentId: string } | null {
+	if (parseTeamTaskSubSessionId(sessionId)) {
+		return null;
+	}
+	const separator = "__";
+	const separatorIndex = sessionId.indexOf(separator);
+	if (separatorIndex <= 0) {
+		return null;
+	}
+	const rootSessionId = sessionId.slice(0, separatorIndex);
+	const agentId = sessionId.slice(separatorIndex + separator.length);
+	if (!rootSessionId || !agentId) {
+		return null;
+	}
+	return { rootSessionId, agentId };
+}
+
+export function deriveSubsessionStatus(event: HookEventPayload): SessionStatus {
+	switch (event.hookName) {
+		case "agent_end":
+			return "completed";
+		case "session_shutdown": {
+			const reason = String(event.reason ?? "").toLowerCase();
+			if (
+				reason.includes("cancel") ||
+				reason.includes("abort") ||
+				reason.includes("interrupt")
+			) {
+				return "cancelled";
+			}
+			if (reason.includes("fail") || reason.includes("error")) {
+				return "failed";
+			}
+			return "completed";
+		}
+		default:
+			return "running";
+	}
+}

package/src/session/session-host.ts

@@ -0,0 +1,190 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type {
+	AgentConfig,
+	ToolApprovalRequest,
+	ToolApprovalResult,
+} from "@clinebot/agents";
+import { getRpcServerHealth } from "@clinebot/rpc";
+import { resolveSessionDataDir } from "@clinebot/shared/storage";
+import { nanoid } from "nanoid";
+import type { ToolExecutors } from "../default-tools";
+import { SqliteSessionStore } from "../storage/sqlite-session-store";
+import { DefaultSessionManager } from "./default-session-manager";
+import { RpcCoreSessionService } from "./rpc-session-service";
+import type { SessionManager } from "./session-manager";
+import { CoreSessionService } from "./session-service";
+
+const DEFAULT_RPC_ADDRESS =
+	process.env.CLINE_RPC_ADDRESS?.trim() || "127.0.0.1:4317";
+
+type SessionBackend = RpcCoreSessionService | CoreSessionService;
+
+let cachedBackend: SessionBackend | undefined;
+let backendInitPromise: Promise<SessionBackend> | undefined;
+
+export interface CreateSessionHostOptions {
+	distinctId?: string;
+	sessionService?: SessionBackend;
+	backendMode?: "auto" | "rpc" | "local";
+	rpcAddress?: string;
+	autoStartRpcServer?: boolean;
+	rpcConnectAttempts?: number;
+	rpcConnectDelayMs?: number;
+	defaultToolExecutors?: Partial<ToolExecutors>;
+	toolPolicies?: AgentConfig["toolPolicies"];
+	requestToolApproval?: (
+		request: ToolApprovalRequest,
+	) => Promise<ToolApprovalResult>;
+}
+
+export type SessionHost = SessionManager;
+
+function isLikelyScriptEntryPath(pathValue: string | undefined): boolean {
+	if (!pathValue) {
+		return false;
+	}
+	return /\.(?:[cm]?[jt]s|tsx?)$/i.test(pathValue);
+}
+
+function startRpcServerInBackground(address: string): void {
+	const launcher = process.argv[0];
+	const entry = process.argv[1];
+	const startArgs = ["rpc", "start", "--address", address];
+	const args =
+		entry && isLikelyScriptEntryPath(entry) ? [entry, ...startArgs] : startArgs;
+
+	const child = spawn(launcher, args, {
+		detached: true,
+		stdio: "ignore",
+		env: process.env,
+		cwd: process.cwd(),
+	});
+	child.unref();
+}
+
+async function tryConnectRpcBackend(
+	address: string,
+): Promise<RpcCoreSessionService | undefined> {
+	try {
+		const health = await getRpcServerHealth(address);
+		if (!health) {
+			return undefined;
+		}
+		return new RpcCoreSessionService({
+			address,
+			sessionsDir: resolveSessionDataDir(),
+		});
+	} catch {
+		return undefined;
+	}
+}
+
+function createLocalBackend(): CoreSessionService {
+	return new CoreSessionService(new SqliteSessionStore());
+}
+
+function resolveHostDistinctId(explicitDistinctId: string | undefined): string {
+	if (
+		typeof explicitDistinctId === "string" &&
+		explicitDistinctId.trim().length > 0
+	) {
+		return explicitDistinctId.trim();
+	}
+
+	const sessionDataDir = resolveSessionDataDir();
+	const distinctIdPath = resolve(sessionDataDir, "machine-id");
+	try {
+		if (existsSync(distinctIdPath)) {
+			const savedDistinctId = readFileSync(distinctIdPath, "utf8").trim();
+			if (savedDistinctId.length > 0) {
+				return savedDistinctId;
+			}
+		}
+	} catch {
+		// Ignore read errors and generate a fresh fallback ID.
+	}
+
+	const generatedDistinctId = nanoid();
+	try {
+		mkdirSync(sessionDataDir, { recursive: true });
+		writeFileSync(distinctIdPath, generatedDistinctId, "utf8");
+	} catch {
+		// Ignore write errors and continue with in-memory fallback.
+	}
+	return generatedDistinctId;
+}
+
+async function resolveBackend(
+	options: CreateSessionHostOptions,
+): Promise<SessionBackend> {
+	if (cachedBackend) {
+		return cachedBackend;
+	}
+	if (backendInitPromise) {
+		return await backendInitPromise;
+	}
+
+	const mode = options.backendMode ?? "auto";
+	const address = options.rpcAddress?.trim() || DEFAULT_RPC_ADDRESS;
+	const attempts = Math.max(1, options.rpcConnectAttempts ?? 5);
+	const delayMs = Math.max(0, options.rpcConnectDelayMs ?? 100);
+	const autoStartRpc = options.autoStartRpcServer !== false;
+
+	backendInitPromise = (async () => {
+		if (mode === "local") {
+			cachedBackend = createLocalBackend();
+			return cachedBackend;
+		}
+
+		const existingRpcBackend = await tryConnectRpcBackend(address);
+		if (existingRpcBackend) {
+			cachedBackend = existingRpcBackend;
+			return cachedBackend;
+		}
+
+		if (mode === "rpc") {
+			throw new Error(`RPC backend unavailable at ${address}`);
+		}
+
+		if (autoStartRpc) {
+			try {
+				startRpcServerInBackground(address);
+			} catch {
+				// Ignore launch failures and fall back to local backend.
+			}
+
+			for (let attempt = 0; attempt < attempts; attempt += 1) {
+				const rpcBackend = await tryConnectRpcBackend(address);
+				if (rpcBackend) {
+					cachedBackend = rpcBackend;
+					return cachedBackend;
+				}
+				if (delayMs > 0) {
+					await new Promise((resolve) => setTimeout(resolve, delayMs));
+				}
+			}
+		}
+
+		cachedBackend = createLocalBackend();
+		return cachedBackend;
+	})().finally(() => {
+		backendInitPromise = undefined;
+	});
+
+	return await backendInitPromise;
+}
+
+export async function createSessionHost(
+	options: CreateSessionHostOptions,
+): Promise<SessionHost> {
+	const backend = options.sessionService ?? (await resolveBackend(options));
+	return new DefaultSessionManager({
+		sessionService: backend,
+		defaultToolExecutors: options.defaultToolExecutors,
+		toolPolicies: options.toolPolicies,
+		requestToolApproval: options.requestToolApproval,
+		distinctId: resolveHostDistinctId(options.distinctId),
+	});
+}

package/src/session/session-manager.ts

@@ -0,0 +1,56 @@
+import type { AgentResult } from "@clinebot/agents";
+import type { providers as LlmsProviders } from "@clinebot/llms";
+import type { SessionSource } from "../types/common";
+import type { CoreSessionConfig } from "../types/config";
+import type { CoreSessionEvent } from "../types/events";
+import type { SessionRecord } from "../types/sessions";
+import type { SessionManifest } from "./session-manifest";
+
+export interface StartSessionInput {
+	config: CoreSessionConfig;
+	source?: SessionSource;
+	prompt?: string;
+	interactive?: boolean;
+	initialMessages?: LlmsProviders.Message[];
+	userImages?: string[];
+	userFiles?: string[];
+	userInstructionWatcher?: import("../agents").UserInstructionConfigWatcher;
+	onTeamRestored?: () => void;
+	defaultToolExecutors?: Partial<import("../default-tools").ToolExecutors>;
+	toolPolicies?: import("@clinebot/agents").AgentConfig["toolPolicies"];
+	requestToolApproval?: (
+		request: import("@clinebot/agents").ToolApprovalRequest,
+	) => Promise<import("@clinebot/agents").ToolApprovalResult>;
+}
+
+export interface StartSessionResult {
+	sessionId: string;
+	manifest: SessionManifest;
+	manifestPath: string;
+	transcriptPath: string;
+	hookPath: string;
+	messagesPath: string;
+	result?: AgentResult;
+}
+
+export interface SendSessionInput {
+	sessionId: string;
+	prompt: string;
+	userImages?: string[];
+	userFiles?: string[];
+}
+
+export interface SessionManager {
+	start(input: StartSessionInput): Promise<StartSessionResult>;
+	send(input: SendSessionInput): Promise<AgentResult | undefined>;
+	abort(sessionId: string): Promise<void>;
+	stop(sessionId: string): Promise<void>;
+	dispose(reason?: string): Promise<void>;
+	get(sessionId: string): Promise<SessionRecord | undefined>;
+	list(limit?: number): Promise<SessionRecord[]>;
+	delete(sessionId: string): Promise<boolean>;
+	readMessages(sessionId: string): Promise<LlmsProviders.Message[]>;
+	readTranscript(sessionId: string, maxChars?: number): Promise<string>;
+	readHooks(sessionId: string, limit?: number): Promise<unknown[]>;
+	subscribe(listener: (event: CoreSessionEvent) => void): () => void;
+}

package/src/session/session-manifest.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { SESSION_STATUSES, SessionSource } from "../types/common";
+
+const SessionStatusSchema = z.enum(SESSION_STATUSES);
+
+export const SessionManifestSchema = z.object({
+	version: z.literal(1),
+	session_id: z.string().min(1),
+	source: z.enum(SessionSource),
+	pid: z.number().int(),
+	started_at: z.string().min(1),
+	ended_at: z.string().min(1).optional(),
+	exit_code: z.number().int().nullable().optional(),
+	status: SessionStatusSchema,
+	interactive: z.boolean(),
+	provider: z.string().min(1),
+	model: z.string().min(1),
+	cwd: z.string().min(1),
+	workspace_root: z.string().min(1),
+	team_name: z.string().min(1).optional(),
+	enable_tools: z.boolean(),
+	enable_spawn: z.boolean(),
+	enable_teams: z.boolean(),
+	prompt: z.string().optional(),
+	metadata: z.record(z.string(), z.unknown()).optional(),
+	messages_path: z.string().min(1).optional(),
+});
+
+export type SessionManifest = z.infer<typeof SessionManifestSchema>;

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

@@ -0,0 +1,48 @@
+import { existsSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AgentTeamsRuntime } from "@clinebot/agents";
+import { describe, expect, it } from "vitest";
+import { FileTeamPersistenceStore } from "./session-service";
+
+describe("FileTeamPersistenceStore", () => {
+	it("does not create state.json for an empty runtime", () => {
+		const baseDir = mkdtempSync(join(tmpdir(), "team-store-"));
+		const store = new FileTeamPersistenceStore({
+			teamName: "agent-team-nmnn9",
+			baseDir,
+		});
+		const runtime = new AgentTeamsRuntime({ teamName: "agent-team-nmnn9" });
+
+		store.persist(runtime);
+
+		expect(
+			existsSync(join(baseDir, "agent-team-nmnn9", "state.json")),
+		).toBeFalsy();
+	});
+
+	it("removes persisted state when runtime becomes empty again", () => {
+		const baseDir = mkdtempSync(join(tmpdir(), "team-store-"));
+		const store = new FileTeamPersistenceStore({
+			teamName: "agent-team-cleanup",
+			baseDir,
+		});
+		const runtime = new AgentTeamsRuntime({ teamName: "agent-team-cleanup" });
+
+		store.upsertTeammateSpec({
+			agentId: "worker",
+			rolePrompt: "Implement tasks",
+		});
+		store.persist(runtime);
+		expect(
+			existsSync(join(baseDir, "agent-team-cleanup", "state.json")),
+		).toBeTruthy();
+
+		store.removeTeammateSpec("worker");
+		runtime.cleanup();
+		store.persist(runtime);
+		expect(
+			existsSync(join(baseDir, "agent-team-cleanup", "state.json")),
+		).toBeFalsy();
+	});
+});