@clinebot/core 0.0.27 → 0.0.29

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

@@ -1,5 +1,5 @@
-import type { AgentResult, TeamEvent } from "@clinebot/agents";
-import { formatUserInputBlock } from "@clinebot/shared";
+import { type AgentResult, formatUserInputBlock } from "@clinebot/shared";
+import type { TeamEvent } from "../team";
 import {
 	buildTeamProgressSummary,
 	toTeamProgressLifecycleEvent,
@@ -36,7 +36,8 @@ export function trackTeamRunState(
 				taskId: event.run.taskId,
 				status: event.type.replace("run_", "") as TeamRunUpdate["status"],
 				error: runError,
-				iterations: event.run.result?.iterations,
+				iterations: (event.run.result as { iterations?: number } | undefined)
+					?.iterations,
 			});
 			notifyTeamRunWaiters(session);
 			break;
@@ -98,6 +99,7 @@ export async function dispatchTeamEventToBackend(
 					event.agentId,
 					"failed",
 					`[error] ${event.error.message}`,
+					undefined,
 					event.messages,
 				);
 			} else if (event.result?.finishReason === "aborted") {
@@ -107,6 +109,7 @@ export async function dispatchTeamEventToBackend(
 					event.agentId,
 					"cancelled",
 					"[done] aborted",
+					event.result,
 					event.result.messages,
 				);
 			} else {
@@ -116,6 +119,7 @@ export async function dispatchTeamEventToBackend(
 					event.agentId,
 					"completed",
 					`[done] ${event.result?.finishReason ?? "completed"}`,
+					event.result,
 					event.result?.messages,
 				);
 			}

package/src/session/session-telemetry.ts

@@ -2,7 +2,7 @@ import type { ITelemetryService } from "@clinebot/shared";
 import {
 	listHookConfigFiles,
 	resolveDocumentsHooksDirectoryPath,
-} from "../agents/hooks-config-loader";
+} from "../extensions/config/hooks-config-loader";
 import type { enrichPromptWithMentions } from "../input";
 import {
 	captureHookDiscovery,

package/src/session/utils/helpers.test.ts

@@ -0,0 +1,160 @@
+import type { MessageWithMetadata } from "@clinebot/llms";
+import type { AgentResult } from "@clinebot/shared";
+import { describe, expect, it } from "vitest";
+import { withLatestAssistantTurnMetadata } from "./helpers";
+
+type LegacyStoredMessage = MessageWithMetadata & {
+	providerId?: string;
+	modelId?: string;
+};
+
+function createResult(overrides: Partial<AgentResult> = {}): AgentResult {
+	return {
+		text: "ok",
+		iterations: 1,
+		finishReason: "completed",
+		usage: {
+			inputTokens: 3,
+			outputTokens: 2,
+			totalCost: 0.01,
+		},
+		messages: [],
+		toolCalls: [],
+		durationMs: 1,
+		model: {
+			id: "claude-sonnet-4-6",
+			provider: "anthropic",
+			info: {
+				id: "claude-sonnet-4-6",
+				family: "claude-sonnet-4",
+			},
+		},
+		startedAt: new Date("2026-01-01T00:00:00.000Z"),
+		endedAt: new Date("2026-01-01T00:00:01.000Z"),
+		...overrides,
+	};
+}
+
+describe("withLatestAssistantTurnMetadata", () => {
+	it("normalizes legacy stored provider/model fields into modelInfo", () => {
+		const messages = [
+			{ role: "user", content: "hello" },
+			{ role: "assistant", content: "first answer" },
+			{ role: "user", content: "again" },
+			{ role: "assistant", content: "second answer" },
+		] as const;
+
+		const previousMessages: LegacyStoredMessage[] = [
+			{ role: "user", content: "hello" },
+			{
+				role: "assistant",
+				content: "first answer",
+				providerId: "anthropic",
+				modelId: "claude-sonnet-4-5",
+			},
+			{ role: "user", content: "again" },
+		];
+
+		const persisted = withLatestAssistantTurnMetadata(
+			[...messages],
+			createResult(),
+			previousMessages,
+		);
+
+		expect(persisted[1]).toEqual({
+			id: expect.any(String),
+			role: "assistant",
+			content: "first answer",
+			modelInfo: {
+				id: "claude-sonnet-4-5",
+				provider: "anthropic",
+			},
+		});
+		expect(persisted[3]).toMatchObject({
+			id: expect.any(String),
+			role: "assistant",
+			content: "second answer",
+			modelInfo: {
+				id: "claude-sonnet-4-6",
+				provider: "anthropic",
+				family: "claude-sonnet-4",
+			},
+			metrics: {
+				inputTokens: 3,
+				outputTokens: 2,
+				cost: 0.01,
+			},
+		});
+		expect("providerId" in (persisted[1] ?? {})).toBe(false);
+		expect("modelId" in (persisted[1] ?? {})).toBe(false);
+		expect("providerId" in (persisted[3] ?? {})).toBe(false);
+		expect("modelId" in (persisted[3] ?? {})).toBe(false);
+	});
+
+	it("applies turn model metadata and usage to every assistant message created in the turn", () => {
+		const persisted = withLatestAssistantTurnMetadata(
+			[
+				{ role: "user", content: "spawn a team" },
+				{
+					role: "assistant",
+					content: [{ type: "tool_use", id: "1", name: "spawn", input: {} }],
+				},
+				{
+					role: "user",
+					content: [{ type: "tool_result", tool_use_id: "1", content: "ok" }],
+				},
+				{
+					role: "assistant",
+					content: [
+						{
+							type: "text",
+							text: "Both agents are spawned! Now let me send them tasks.",
+						},
+						{ type: "tool_use", id: "2", name: "run_task", input: {} },
+					],
+				},
+			],
+			createResult({
+				usage: {
+					inputTokens: 10,
+					outputTokens: 5,
+					cacheReadTokens: 2,
+					cacheWriteTokens: 1,
+					totalCost: 0.12,
+				},
+			}),
+			[],
+		);
+
+		expect(persisted[1]).toMatchObject({
+			role: "assistant",
+			modelInfo: {
+				id: "claude-sonnet-4-6",
+				provider: "anthropic",
+				family: "claude-sonnet-4",
+			},
+			metrics: {
+				inputTokens: 10,
+				outputTokens: 5,
+				cacheReadTokens: 2,
+				cacheWriteTokens: 1,
+				cost: 0.12,
+			},
+		});
+		expect(persisted[3]).toMatchObject({
+			role: "assistant",
+			modelInfo: {
+				id: "claude-sonnet-4-6",
+				provider: "anthropic",
+				family: "claude-sonnet-4",
+			},
+			metrics: {
+				inputTokens: 10,
+				outputTokens: 5,
+				cacheReadTokens: 2,
+				cacheWriteTokens: 1,
+				cost: 0.12,
+			},
+		});
+	});
+});

package/src/session/utils/helpers.ts

@@ -1,23 +1,18 @@
-import type { AgentConfig, AgentEvent, AgentResult } from "@clinebot/agents";
-import type * as LlmsProviders from "@clinebot/llms/providers";
-import type { SessionSource } from "../../types/common";
+import { writeFileSync } from "node:fs";
+import type * as LlmsProviders from "@clinebot/llms";
+import type { AgentConfig, AgentEvent, AgentResult } from "@clinebot/shared";
+import { normalizeUserInput } from "@clinebot/shared";
+import { nanoid } from "nanoid";
+import type { SessionSource, SessionStatus } from "../../types/common";
 import type { SessionRecord } from "../../types/sessions";
+import { parseSubSessionId, parseTeamTaskSubSessionId } from "../session-graph";
+import {
+	type SessionManifest,
+	SessionManifestSchema,
+} from "../session-manifest";
 import type { SessionRow } from "../session-service";
 import type { StoredMessageWithMetadata } from "./types";
 
-const WORKSPACE_CONFIGURATION_MARKER = "# Workspace Configuration";
-
-export function extractWorkspaceMetadataFromSystemPrompt(
-	systemPrompt: string,
-): string | undefined {
-	const markerIndex = systemPrompt.lastIndexOf(WORKSPACE_CONFIGURATION_MARKER);
-	if (markerIndex < 0) {
-		return undefined;
-	}
-	const metadata = systemPrompt.slice(markerIndex).trim();
-	return metadata.length > 0 ? metadata : undefined;
-}
-
 export function hasRuntimeHooks(hooks: AgentConfig["hooks"]): boolean {
 	if (!hooks) {
 		return false;
@@ -58,6 +53,67 @@ export function serializeAgentEvent(event: AgentEvent): string {
 	});
 }
 
+function trimNonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function normalizeStoredMessageModelMetadata(
+	message: StoredMessageWithMetadata,
+	fallback?: {
+		id?: string;
+		provider?: string;
+		family?: string;
+	},
+): StoredMessageWithMetadata {
+	const next = {
+		...(message as StoredMessageWithMetadata & {
+			providerId?: string;
+			modelId?: string;
+		}),
+	};
+	next.id = trimNonEmptyString(next.id) ?? nanoid();
+	const modelInfo =
+		next.modelInfo && typeof next.modelInfo === "object"
+			? { ...next.modelInfo }
+			: undefined;
+	const resolvedModelInfo = {
+		id:
+			trimNonEmptyString(modelInfo?.id) ??
+			trimNonEmptyString(next.modelId) ??
+			trimNonEmptyString(fallback?.id),
+		provider:
+			trimNonEmptyString(modelInfo?.provider) ??
+			trimNonEmptyString(next.providerId) ??
+			trimNonEmptyString(fallback?.provider),
+		family:
+			trimNonEmptyString(modelInfo?.family) ??
+			trimNonEmptyString(fallback?.family),
+	};
+
+	delete next.providerId;
+	delete next.modelId;
+
+	if (resolvedModelInfo.id && resolvedModelInfo.provider) {
+		next.modelInfo = {
+			id: resolvedModelInfo.id,
+			provider: resolvedModelInfo.provider,
+			...(resolvedModelInfo.family ? { family: resolvedModelInfo.family } : {}),
+		};
+	} else {
+		delete next.modelInfo;
+	}
+
+	return next;
+}
+
+export function normalizeStoredMessagesForPersistence(
+	messages: LlmsProviders.MessageWithMetadata[],
+): StoredMessageWithMetadata[] {
+	return messages.map((message) =>
+		normalizeStoredMessageModelMetadata(message as StoredMessageWithMetadata),
+	);
+}
+
 export function withLatestAssistantTurnMetadata(
 	messages: LlmsProviders.Message[],
 	result: AgentResult,
@@ -68,41 +124,51 @@ export function withLatestAssistantTurnMetadata(
 		const sameMessage =
 			previous?.role === message.role &&
 			JSON.stringify(previous.content) === JSON.stringify(message.content);
-		return sameMessage
+		const merged = sameMessage
 			? ({
 					...previous,
 					...message,
 				} as StoredMessageWithMetadata)
 			: ({ ...message } as StoredMessageWithMetadata);
+		return normalizeStoredMessageModelMetadata(merged);
 	});
-	const assistantIndex = [...next]
-		.reverse()
-		.findIndex((message) => message.role === "assistant");
-	if (assistantIndex === -1) {
-		return next;
+	const firstNewMessageIndex = previousMessages.length;
+	const assistantIndexes: number[] = [];
+	for (let index = firstNewMessageIndex; index < next.length; index += 1) {
+		if (next[index]?.role === "assistant") {
+			assistantIndexes.push(index);
+		}
+	}
+	if (assistantIndexes.length === 0) {
+		const lastAssistantIndex = [...next]
+			.reverse()
+			.findIndex((message) => message.role === "assistant");
+		if (lastAssistantIndex === -1) {
+			return next;
+		}
+		assistantIndexes.push(next.length - 1 - lastAssistantIndex);
 	}
 
-	const targetIndex = next.length - 1 - assistantIndex;
-	const target = next[targetIndex];
 	const usage = result.usage;
-	next[targetIndex] = {
-		...target,
-		providerId: target.providerId ?? result.model.provider,
-		modelId: target.modelId ?? result.model.id,
-		modelInfo: target.modelInfo ?? {
-			id: result.model.id,
-			provider: result.model.provider,
-		},
-		metrics: {
-			...(target.metrics ?? {}),
-			inputTokens: usage.inputTokens,
-			outputTokens: usage.outputTokens,
-			cacheReadTokens: usage.cacheReadTokens,
-			cacheWriteTokens: usage.cacheWriteTokens,
-			cost: usage.totalCost,
-		},
-		ts: target.ts ?? result.endedAt.getTime(),
-	};
+	for (const targetIndex of assistantIndexes) {
+		const target = next[targetIndex];
+		next[targetIndex] = {
+			...normalizeStoredMessageModelMetadata(target, {
+				id: result.model.id,
+				provider: result.model.provider,
+				family: result.model.info?.family,
+			}),
+			metrics: {
+				...(target.metrics ?? {}),
+				inputTokens: usage.inputTokens,
+				outputTokens: usage.outputTokens,
+				cacheReadTokens: usage.cacheReadTokens ?? 0,
+				cacheWriteTokens: usage.cacheWriteTokens ?? 0,
+				cost: usage.totalCost,
+			},
+			ts: target.ts ?? result.endedAt.getTime(),
+		};
+	}
 	return next;
 }
 
@@ -137,3 +203,184 @@ export function toSessionRecord(row: SessionRow): SessionRecord {
 		updatedAt: row.updatedAt,
 	};
 }
+
+// ── Metadata helpers ──────────────────────────────────────────────────
+
+const MAX_TITLE_LENGTH = 120;
+
+export function normalizeTitle(title?: string | null): string | undefined {
+	const trimmed = title?.trim();
+	return trimmed ? trimmed.slice(0, MAX_TITLE_LENGTH) : undefined;
+}
+
+export function deriveTitleFromPrompt(
+	prompt?: string | null,
+): string | undefined {
+	const normalized = normalizeUserInput(prompt ?? "").trim();
+	if (!normalized) return undefined;
+	return normalizeTitle(normalized.split("\n")[0]?.trim());
+}
+
+export function sanitizeMetadata(
+	metadata: Record<string, unknown> | null | undefined,
+): Record<string, unknown> | undefined {
+	if (!metadata) return undefined;
+	const next = { ...metadata };
+	const title = normalizeTitle(
+		typeof next.title === "string" ? next.title : undefined,
+	);
+	if (title) {
+		next.title = title;
+	} else {
+		delete next.title;
+	}
+	return Object.keys(next).length > 0 ? next : undefined;
+}
+
+export function resolveMetadataWithTitle(input: {
+	metadata?: Record<string, unknown> | null;
+	title?: string | null;
+	prompt?: string | null;
+}): Record<string, unknown> | undefined {
+	const base = sanitizeMetadata(input.metadata) ?? {};
+	const title =
+		input.title !== undefined
+			? normalizeTitle(input.title)
+			: deriveTitleFromPrompt(input.prompt);
+	if (title) base.title = title;
+	return Object.keys(base).length > 0 ? base : undefined;
+}
+
+// ── Messages file helpers ─────────────────────────────────────────────
+
+export type MessagesFileContext = {
+	agent: "lead" | "subagent" | "teammate";
+	sessionId: string;
+	taskType?: string;
+};
+
+export type MessagesFilePayload = {
+	version: number;
+	updated_at: string;
+	agent: "lead" | "subagent" | "teammate";
+	sessionId: string;
+	taskType?: string;
+	systemPrompt?: string;
+	messages: LlmsProviders.Message[];
+};
+
+export function buildMessagesFilePayload(input: {
+	updatedAt: string;
+	context: MessagesFileContext;
+	messages: LlmsProviders.Message[];
+	systemPrompt?: string;
+}): MessagesFilePayload {
+	return {
+		version: 1,
+		updated_at: input.updatedAt,
+		agent: input.context.agent,
+		sessionId: input.context.sessionId,
+		...(input.context.taskType ? { taskType: input.context.taskType } : {}),
+		...(input.systemPrompt ? { systemPrompt: input.systemPrompt } : {}),
+		messages: input.messages,
+	};
+}
+
+export function writeEmptyMessagesFile(
+	path: string,
+	startedAt: string,
+	context: MessagesFileContext,
+): void {
+	writeFileSync(
+		path,
+		`${JSON.stringify(
+			buildMessagesFilePayload({
+				updatedAt: startedAt,
+				context,
+				messages: [],
+			}),
+			null,
+			2,
+		)}\n`,
+		"utf8",
+	);
+}
+
+export function resolveMessagesFileContext(
+	sessionId: string,
+): MessagesFileContext {
+	const teamTask = parseTeamTaskSubSessionId(sessionId);
+	if (teamTask) {
+		return {
+			agent: "teammate",
+			sessionId: teamTask.rootSessionId,
+			taskType: "team",
+		};
+	}
+
+	const subagent = parseSubSessionId(sessionId);
+	if (subagent) {
+		return {
+			agent: "subagent",
+			sessionId: subagent.rootSessionId,
+		};
+	}
+
+	return {
+		agent: "lead",
+		sessionId,
+	};
+}
+
+// ── Manifest helper ───────────────────────────────────────────────────
+
+export function buildManifestFromRow(
+	row: SessionRow,
+	overrides?: {
+		status?: SessionStatus;
+		endedAt?: string | null;
+		exitCode?: number | null;
+		metadata?: Record<string, unknown>;
+	},
+): SessionManifest {
+	return SessionManifestSchema.parse({
+		version: 1,
+		session_id: row.sessionId,
+		source: row.source,
+		pid: row.pid,
+		started_at: row.startedAt,
+		ended_at: overrides?.endedAt ?? row.endedAt ?? undefined,
+		exit_code: overrides?.exitCode ?? row.exitCode ?? undefined,
+		status: overrides?.status ?? row.status,
+		interactive: row.interactive,
+		provider: row.provider,
+		model: row.model,
+		cwd: row.cwd,
+		workspace_root: row.workspaceRoot,
+		team_name: row.teamName ?? undefined,
+		enable_tools: row.enableTools,
+		enable_spawn: row.enableSpawn,
+		enable_teams: row.enableTeams,
+		prompt: row.prompt ?? undefined,
+		metadata: overrides?.metadata ?? row.metadata ?? undefined,
+		messages_path: row.messagesPath ?? undefined,
+	});
+}
+
+// ── OCC retry helper ──────────────────────────────────────────────────
+
+export const OCC_MAX_RETRIES = 4;
+
+export async function withOccRetry<T>(
+	getRow: () => Promise<{ statusLock: number } | undefined>,
+	action: (statusLock: number) => Promise<{ updated: boolean } & T>,
+	maxRetries = OCC_MAX_RETRIES,
+): Promise<({ updated: true } & T) | { updated: false }> {
+	for (let attempt = 0; attempt < maxRetries; attempt++) {
+		const row = getRow ? await getRow() : undefined;
+		if (!row) return { updated: false } as { updated: false };
+		const result = await action(row.statusLock);
+		if (result.updated) return result as { updated: true } & T;
+	}
+	return { updated: false } as { updated: false };
+}

package/src/session/utils/types.ts

@@ -1,10 +1,10 @@
 import type { Agent } from "@clinebot/agents";
-import type * as LlmsProviders from "@clinebot/llms/providers";
+import type * as LlmsProviders from "@clinebot/llms";
 import type { BuiltRuntime } from "../../runtime/session-runtime";
-import type { SessionSource } from "../../types/common";
+import type { SessionSource, SessionStatus } from "../../types/common";
 import type { CoreSessionConfig } from "../../types/config";
 import type { SessionAccumulatedUsage } from "../session-manager";
-import type { RootSessionArtifacts } from "../session-service";
+import type { RootSessionArtifacts, SessionRow } from "../session-service";
 
 export type ActiveSession = {
 	sessionId: string;
@@ -45,13 +45,53 @@ export type TeamRunUpdate = {
 	iterations?: number;
 };
 
-export type StoredMessageWithMetadata = LlmsProviders.MessageWithMetadata & {
-	providerId?: string;
-	modelId?: string;
-};
+export type StoredMessageWithMetadata = LlmsProviders.MessageWithMetadata;
 
 export type PreparedTurnInput = {
 	prompt: string;
 	userImages?: string[];
 	userFiles?: string[];
 };
+
+// ── Persistence interfaces ────────────────────────────────────────────
+
+export interface PersistedSessionUpdateInput {
+	sessionId: string;
+	expectedStatusLock?: number;
+	status?: SessionStatus;
+	endedAt?: string | null;
+	exitCode?: number | null;
+	prompt?: string | null;
+	metadata?: Record<string, unknown> | null;
+	title?: string | null;
+	parentSessionId?: string | null;
+	parentAgentId?: string | null;
+	agentId?: string | null;
+	conversationId?: string | null;
+	setRunning?: boolean;
+}
+
+export interface SessionPersistenceAdapter {
+	ensureSessionsDir(): string;
+	upsertSession(row: SessionRow): Promise<void>;
+	getSession(sessionId: string): Promise<SessionRow | undefined>;
+	listSessions(options: {
+		limit: number;
+		parentSessionId?: string;
+		status?: string;
+	}): Promise<SessionRow[]>;
+	updateSession(
+		input: PersistedSessionUpdateInput,
+	): Promise<{ updated: boolean; statusLock: number }>;
+	deleteSession(sessionId: string, cascade: boolean): Promise<boolean>;
+	enqueueSpawnRequest(input: {
+		rootSessionId: string;
+		parentAgentId: string;
+		task?: string;
+		systemPrompt?: string;
+	}): Promise<void>;
+	claimSpawnRequest(
+		rootSessionId: string,
+		parentAgentId: string,
+	): Promise<string | undefined>;
+}

package/src/session/workspace-manager.ts

@@ -1,10 +1,12 @@
-import type { WorkspaceInfo } from "../types/workspace";
 import {
-	generateWorkspaceInfo,
-	normalizeWorkspacePath,
 	upsertWorkspaceInfo,
+	type WorkspaceInfo,
 	type WorkspaceManifest,
 	WorkspaceManifestSchema,
+} from "@clinebot/shared";
+import {
+	generateWorkspaceInfo,
+	normalizeWorkspacePath,
 } from "./workspace-manifest";
 
 export interface WorkspaceManagerEvent {