@clinebot/core 0.0.35 → 0.0.36

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

@@ -0,0 +1,397 @@
+import { appendFileSync } from "node:fs";
+import { join } from "node:path";
+import type * as LlmsProviders from "@clinebot/llms";
+import type { AgentResult } from "@clinebot/shared";
+import { resolveRootSessionId } from "@clinebot/shared";
+import { ensureHookLogDir } from "@clinebot/shared/storage";
+import { z } from "zod";
+import type {
+	SubAgentEndContext,
+	SubAgentStartContext,
+} from "../extensions/tools/team";
+import type { HookEventPayload } from "../hooks";
+import { nowIso } from "../services/session-artifacts";
+import { resolveMetadataWithTitle } from "../services/session-data";
+import type { SessionStatus } from "../types/common";
+import type {
+	SessionPersistenceAdapter,
+	StoredMessageWithMetadata,
+} from "../types/session";
+import {
+	deriveSubsessionStatus,
+	makeSubSessionId,
+	makeTeamTaskSubSessionId,
+} from "./session-graph";
+import type { SessionManifestStore } from "./session-manifest-store";
+import type { SessionRow, UpsertSubagentInput } from "./session-row";
+
+const SUBSESSION_SOURCE = "subagent";
+const SpawnAgentInputSchema = z.looseObject({
+	task: z.string().optional(),
+	systemPrompt: z.string().optional(),
+});
+
+export class SubagentSessionManager {
+	private readonly teamTaskSessionsByAgent = new Map<string, string[]>();
+	private readonly teamTaskLastHeartbeatBySession = new Map<string, number>();
+	private readonly teamTaskLastProgressLineBySession = new Map<
+		string,
+		string
+	>();
+
+	constructor(
+		private readonly adapter: SessionPersistenceAdapter,
+		private readonly manifestStore: SessionManifestStore,
+		private readonly toPersistedMessages: (
+			messages: LlmsProviders.Message[] | undefined,
+			result?: AgentResult,
+			previousMessages?: LlmsProviders.Message[],
+		) => StoredMessageWithMetadata[] | undefined,
+		private readonly heartbeatLogIntervalMs: number,
+	) {}
+
+	private teamTaskQueueKey(rootSessionId: string, agentId: string): string {
+		return `${rootSessionId}::${agentId}`;
+	}
+
+	private activeTeamTaskSessionId(
+		rootSessionId: string,
+		parentAgentId: string,
+	): string | undefined {
+		const queue = this.teamTaskSessionsByAgent.get(
+			this.teamTaskQueueKey(rootSessionId, parentAgentId),
+		);
+		return queue?.at(-1);
+	}
+
+	private buildSubsessionRow(
+		root: SessionRow,
+		opts: {
+			sessionId: string;
+			parentSessionId: string;
+			parentAgentId: string;
+			agentId: string;
+			conversationId?: string | null;
+			prompt: string;
+			startedAt: string;
+			messagesPath: string;
+		},
+	): SessionRow {
+		return {
+			sessionId: opts.sessionId,
+			source: SUBSESSION_SOURCE,
+			pid: process.ppid,
+			startedAt: opts.startedAt,
+			endedAt: null,
+			exitCode: null,
+			status: "running",
+			statusLock: 0,
+			interactive: false,
+			provider: root.provider,
+			model: root.model,
+			cwd: root.cwd,
+			workspaceRoot: root.workspaceRoot,
+			teamName: root.teamName ?? null,
+			enableTools: root.enableTools,
+			enableSpawn: root.enableSpawn,
+			enableTeams: root.enableTeams,
+			parentSessionId: opts.parentSessionId,
+			parentAgentId: opts.parentAgentId,
+			agentId: opts.agentId,
+			conversationId: opts.conversationId ?? null,
+			isSubagent: true,
+			prompt: opts.prompt,
+			metadata: resolveMetadataWithTitle({ prompt: opts.prompt }),
+			hookPath: "",
+			messagesPath: opts.messagesPath,
+			updatedAt: opts.startedAt,
+		};
+	}
+
+	async queueSpawnRequest(event: HookEventPayload): Promise<void> {
+		if (event.hookName !== "tool_call" || event.parent_agent_id !== null)
+			return;
+		if (event.tool_call?.name !== "spawn_agent") return;
+
+		const rootSessionId = resolveRootSessionId(event.sessionContext);
+		if (!rootSessionId) return;
+
+		const parsed = SpawnAgentInputSchema.safeParse(event.tool_call.input);
+		await this.adapter.enqueueSpawnRequest({
+			rootSessionId,
+			parentAgentId: event.agent_id,
+			task: parsed.success ? parsed.data.task : undefined,
+			systemPrompt: parsed.success ? parsed.data.systemPrompt : undefined,
+		});
+	}
+
+	async upsertSubagentSession(
+		input: UpsertSubagentInput,
+	): Promise<string | undefined> {
+		const rootSessionId = input.rootSessionId;
+		if (!rootSessionId) return undefined;
+
+		const root = await this.adapter.getSession(rootSessionId);
+		if (!root) return undefined;
+
+		const sessionId = makeSubSessionId(rootSessionId, input.agentId);
+		const existing = await this.adapter.getSession(sessionId);
+		const startedAt = nowIso();
+		const artifactPaths = this.manifestStore.artifacts.subagentArtifactPaths(
+			sessionId,
+			input.agentId,
+			this.activeTeamTaskSessionId(rootSessionId, input.parentAgentId),
+		);
+
+		let prompt = input.prompt ?? existing?.prompt ?? undefined;
+		if (!prompt) {
+			prompt =
+				(await this.adapter.claimSpawnRequest(
+					rootSessionId,
+					input.parentAgentId,
+				)) ?? `Subagent run by ${input.parentAgentId}`;
+		}
+
+		if (!existing) {
+			await this.adapter.upsertSession(
+				this.buildSubsessionRow(root, {
+					sessionId,
+					parentSessionId: rootSessionId,
+					parentAgentId: input.parentAgentId,
+					agentId: input.agentId,
+					conversationId: input.conversationId,
+					prompt,
+					startedAt,
+					...artifactPaths,
+				}),
+			);
+			this.manifestStore.initializeMessagesFile(
+				sessionId,
+				artifactPaths.messagesPath,
+				startedAt,
+			);
+			return sessionId;
+		}
+
+		await this.adapter.updateSession({
+			sessionId,
+			setRunning: true,
+			parentSessionId: rootSessionId,
+			parentAgentId: input.parentAgentId,
+			agentId: input.agentId,
+			conversationId: input.conversationId,
+			prompt: existing.prompt ?? prompt ?? null,
+			metadata: resolveMetadataWithTitle({
+				metadata: existing.metadata ?? undefined,
+				prompt: existing.prompt ?? prompt ?? null,
+			}),
+			expectedStatusLock: existing.statusLock,
+		});
+		return sessionId;
+	}
+
+	async upsertSubagentSessionFromHook(
+		event: HookEventPayload,
+	): Promise<string | undefined> {
+		if (!event.parent_agent_id) return undefined;
+		const rootSessionId = resolveRootSessionId(event.sessionContext);
+		if (!rootSessionId) return undefined;
+		if (event.hookName === "session_shutdown") {
+			const sessionId = makeSubSessionId(rootSessionId, event.agent_id);
+			const existing = await this.adapter.getSession(sessionId);
+			return existing ? sessionId : undefined;
+		}
+		return await this.upsertSubagentSession({
+			agentId: event.agent_id,
+			parentAgentId: event.parent_agent_id,
+			conversationId: event.taskId,
+			rootSessionId,
+		});
+	}
+
+	async applySubagentStatus(
+		subSessionId: string,
+		event: HookEventPayload,
+	): Promise<void> {
+		await this.applySubagentStatusBySessionId(
+			subSessionId,
+			deriveSubsessionStatus(event),
+		);
+	}
+
+	async applySubagentStatusBySessionId(
+		subSessionId: string,
+		status: SessionStatus,
+	): Promise<void> {
+		const row = await this.adapter.getSession(subSessionId);
+		if (!row) return;
+		const endedAt = status === "running" ? null : nowIso();
+		const exitCode = status === "running" ? null : status === "failed" ? 1 : 0;
+		await this.adapter.updateSession({
+			sessionId: subSessionId,
+			status,
+			endedAt,
+			exitCode,
+			expectedStatusLock: row.statusLock,
+		});
+	}
+
+	async applyStatusToRunningChildSessions(
+		parentSessionId: string,
+		status: Exclude<SessionStatus, "running">,
+	): Promise<void> {
+		if (!parentSessionId) return;
+		const rows = await this.adapter.listSessions({
+			limit: 2000,
+			parentSessionId,
+			status: "running",
+		});
+		for (const row of rows) {
+			await this.applySubagentStatusBySessionId(row.sessionId, status);
+		}
+	}
+
+	async onTeamTaskStart(
+		rootSessionId: string,
+		agentId: string,
+		message: string,
+	): Promise<void> {
+		const root = await this.adapter.getSession(rootSessionId);
+		if (!root) return;
+		const sessionId = makeTeamTaskSubSessionId(rootSessionId, agentId);
+		const startedAt = nowIso();
+		const { messagesPath } = this.manifestStore.artifacts.subagentArtifactPaths(
+			sessionId,
+			agentId,
+		);
+		await this.adapter.upsertSession(
+			this.buildSubsessionRow(root, {
+				sessionId,
+				parentSessionId: rootSessionId,
+				parentAgentId: "lead",
+				agentId,
+				prompt: message || `Team task for ${agentId}`,
+				startedAt,
+				messagesPath,
+			}),
+		);
+		this.manifestStore.initializeMessagesFile(
+			sessionId,
+			messagesPath,
+			startedAt,
+		);
+		const key = this.teamTaskQueueKey(rootSessionId, agentId);
+		const queue = this.teamTaskSessionsByAgent.get(key) ?? [];
+		queue.push(sessionId);
+		this.teamTaskSessionsByAgent.set(key, queue);
+	}
+
+	async onTeamTaskEnd(
+		rootSessionId: string,
+		agentId: string,
+		status: SessionStatus,
+		_summary?: string,
+		result?: AgentResult,
+		messages?: LlmsProviders.Message[],
+	): Promise<void> {
+		const key = this.teamTaskQueueKey(rootSessionId, agentId);
+		const queue = this.teamTaskSessionsByAgent.get(key);
+		if (!queue || queue.length === 0) return;
+		const sessionId = queue.shift();
+		if (queue.length === 0) this.teamTaskSessionsByAgent.delete(key);
+		if (!sessionId) return;
+		const teammateMessages = result?.messages ?? messages;
+		const persistedMessages = this.toPersistedMessages(
+			teammateMessages,
+			result,
+			messages,
+		);
+		if (persistedMessages) {
+			await this.manifestStore.persistSessionMessages(
+				sessionId,
+				persistedMessages,
+			);
+		}
+		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 < this.heartbeatLogIntervalMs) {
+				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);
+	}
+
+	async handleSubAgentStart(
+		rootSessionId: string,
+		context: SubAgentStartContext,
+	): Promise<void> {
+		const subSessionId = await this.upsertSubagentSession({
+			agentId: context.subAgentId,
+			parentAgentId: context.parentAgentId,
+			conversationId: context.conversationId,
+			prompt: context.input.task,
+			rootSessionId,
+		});
+		if (!subSessionId) return;
+		await this.applySubagentStatusBySessionId(subSessionId, "running");
+	}
+
+	async handleSubAgentEnd(
+		rootSessionId: string,
+		context: SubAgentEndContext,
+	): Promise<void> {
+		const subSessionId = await this.upsertSubagentSession({
+			agentId: context.subAgentId,
+			parentAgentId: context.parentAgentId,
+			conversationId: context.conversationId,
+			prompt: context.input.task,
+			rootSessionId,
+		});
+		if (!subSessionId) return;
+		if (context.error) {
+			await this.applySubagentStatusBySessionId(subSessionId, "failed");
+			return;
+		}
+		const reason = context.result?.finishReason ?? "completed";
+		await this.applySubagentStatusBySessionId(
+			subSessionId,
+			reason === "aborted" ? "cancelled" : "completed",
+		);
+	}
+
+	appendSubagentHookAudit(event: HookEventPayload): void {
+		const envPath = process.env.CLINE_HOOKS_LOG_PATH?.trim() || undefined;
+		const logPath = envPath ?? join(ensureHookLogDir(), "hooks.jsonl");
+		appendFileSync(
+			logPath,
+			`${JSON.stringify({ ts: nowIso(), ...event })}\n`,
+			"utf8",
+		);
+	}
+}

package/src/session/team-persistence-store.ts

@@ -0,0 +1,176 @@
+import {
+	appendFileSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import type { TeamTeammateSpec } from "@clinebot/shared";
+import { resolveTeamDataDir } from "@clinebot/shared/storage";
+import type { AgentTeamsRuntime, TeamEvent } from "../extensions/tools/team";
+import {
+	type PersistedTeamEnvelope,
+	reviveTeamStateDates,
+	type TeamRuntimeState,
+} from "./session-row";
+
+function sanitizeTeamName(name: string): string {
+	return name
+		.toLowerCase()
+		.replace(/[^a-z0-9._-]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+}
+
+export interface FileTeamPersistenceStoreOptions {
+	teamName: string;
+	baseDir?: string;
+}
+
+export class FileTeamPersistenceStore {
+	private readonly dirPath: string;
+	private readonly statePath: string;
+	private readonly taskHistoryPath: string;
+	private readonly teammateSpecs: Map<string, TeamTeammateSpec> = new Map();
+
+	constructor(options: FileTeamPersistenceStoreOptions) {
+		const safeTeamName = sanitizeTeamName(options.teamName);
+		const baseDir = options.baseDir?.trim() || resolveTeamDataDir();
+		this.dirPath = join(baseDir, safeTeamName);
+		this.statePath = join(this.dirPath, "state.json");
+		this.taskHistoryPath = join(this.dirPath, "task-history.jsonl");
+	}
+
+	loadState(): TeamRuntimeState | undefined {
+		if (!existsSync(this.statePath)) {
+			return undefined;
+		}
+		try {
+			const raw = readFileSync(this.statePath, "utf8");
+			const parsed = JSON.parse(raw) as PersistedTeamEnvelope;
+			if (parsed.version !== 1 || !parsed.teamState) {
+				return undefined;
+			}
+			for (const spec of parsed.teammates ?? []) {
+				this.teammateSpecs.set(spec.agentId, spec);
+			}
+			return reviveTeamStateDates(parsed.teamState);
+		} catch {
+			return undefined;
+		}
+	}
+
+	getTeammateSpecs(): TeamTeammateSpec[] {
+		return Array.from(this.teammateSpecs.values());
+	}
+
+	upsertTeammateSpec(spec: TeamTeammateSpec): void {
+		this.teammateSpecs.set(spec.agentId, spec);
+	}
+
+	removeTeammateSpec(agentId: string): void {
+		this.teammateSpecs.delete(agentId);
+	}
+
+	persist(runtime: AgentTeamsRuntime): void {
+		if (!this.hasPersistableState(runtime)) {
+			this.clearPersistedState();
+			return;
+		}
+		this.ensureDir();
+		const envelope: PersistedTeamEnvelope = {
+			version: 1,
+			updatedAt: new Date().toISOString(),
+			teamState: runtime.exportState(),
+			teammates: Array.from(this.teammateSpecs.values()),
+		};
+		const tmpPath = `${this.statePath}.tmp`;
+		writeFileSync(tmpPath, `${JSON.stringify(envelope, null, 2)}\n`, "utf8");
+		renameSync(tmpPath, this.statePath);
+	}
+
+	appendTaskHistory(event: TeamEvent): void {
+		let task: Record<string, unknown> = {};
+		switch (event.type) {
+			case "team_task_updated":
+				task = event.task as unknown as Record<string, unknown>;
+				break;
+			case "team_message":
+				task = {
+					agentId: event.message.fromAgentId,
+					toAgentId: event.message.toAgentId,
+					subject: event.message.subject,
+					taskId: event.message.taskId,
+				};
+				break;
+			case "team_mission_log":
+				task = {
+					agentId: event.entry.agentId,
+					kind: event.entry.kind,
+					summary: event.entry.summary,
+					taskId: event.entry.taskId,
+				};
+				break;
+			case "teammate_spawned":
+			case "teammate_shutdown":
+			case "task_start":
+				task = {
+					agentId: event.agentId,
+					message: "message" in event ? event.message : undefined,
+				};
+				break;
+			case "task_end":
+				task = {
+					agentId: event.agentId,
+					finishReason: event.result?.finishReason,
+					error: event.error?.message,
+				};
+				break;
+			case "agent_event":
+				task = {
+					agentId: event.agentId,
+					eventType: event.event.type,
+				};
+				break;
+		}
+		this.ensureDir();
+		appendFileSync(
+			this.taskHistoryPath,
+			`${JSON.stringify({
+				ts: new Date().toISOString(),
+				type: event.type,
+				task,
+			})}\n`,
+			"utf8",
+		);
+	}
+
+	private ensureDir(): void {
+		if (!existsSync(this.dirPath)) {
+			mkdirSync(this.dirPath, { recursive: true });
+		}
+	}
+
+	private hasPersistableState(runtime: AgentTeamsRuntime): boolean {
+		const state = runtime.exportState();
+		if (this.teammateSpecs.size > 0) {
+			return true;
+		}
+		if (state.members.some((member) => member.role === "teammate")) {
+			return true;
+		}
+		return (
+			state.tasks.length > 0 ||
+			state.mailbox.length > 0 ||
+			state.missionLog.length > 0
+		);
+	}
+
+	private clearPersistedState(): void {
+		if (existsSync(this.statePath)) {
+			unlinkSync(this.statePath);
+		}
+	}
+}