@clinebot/core 0.0.21 → 0.0.23

package/src/session/session-agent-events.ts

@@ -0,0 +1,248 @@
+import type { AgentEvent } from "@clinebot/agents";
+import {
+	captureConversationTurnEvent,
+	captureDiffEditFailure,
+	captureProviderApiError,
+	captureSkillUsed,
+	captureTokenUsage,
+	captureToolUsage,
+	type TelemetryAgentIdentityProperties,
+} from "../telemetry/core-events";
+import type { CoreSessionConfig } from "../types/config";
+import type { CoreSessionEvent } from "../types/events";
+import type { SessionAccumulatedUsage } from "./session-manager";
+import { serializeAgentEvent } from "./utils/helpers";
+import type { ActiveSession } from "./utils/types";
+import { accumulateUsageTotals } from "./utils/usage";
+
+export function extractSkillNameFromToolInput(
+	input: unknown,
+): string | undefined {
+	if (!input || typeof input !== "object") return undefined;
+	const record = input as Record<string, unknown>;
+	const skillName = record.skill ?? record.skill_name ?? record.skillName;
+	if (typeof skillName !== "string") return undefined;
+	const trimmed = skillName.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+export interface AgentEventContext {
+	sessionId: string;
+	config: CoreSessionConfig;
+	liveSession: ActiveSession | undefined;
+	usageBySession: Map<string, SessionAccumulatedUsage>;
+	persistMessages: (
+		sessionId: string,
+		messages: unknown[],
+		systemPrompt?: string,
+	) => void;
+	emit: (event: CoreSessionEvent) => void;
+}
+
+export interface AgentTelemetryContextOverrides {
+	agentId?: string;
+	conversationId?: string;
+	parentAgentId?: string | null;
+	createdByAgentId?: string;
+	teamId?: string;
+	teamName?: string;
+	teamRole?: "lead" | "teammate";
+	teamAgentId?: string;
+	isPrimaryAgentEvent?: boolean;
+}
+
+export function extractAgentEventMetadata(event: AgentEvent): {
+	agentId?: string;
+	conversationId?: string;
+	parentAgentId?: string;
+} {
+	if (!event || typeof event !== "object") {
+		return {};
+	}
+	const record = event as unknown as Record<string, unknown>;
+	return {
+		agentId: typeof record.agentId === "string" ? record.agentId : undefined,
+		conversationId:
+			typeof record.conversationId === "string"
+				? record.conversationId
+				: undefined,
+		parentAgentId:
+			typeof record.parentAgentId === "string"
+				? record.parentAgentId
+				: undefined,
+	};
+}
+
+export function buildTelemetryAgentIdentity(
+	context: AgentTelemetryContextOverrides,
+): TelemetryAgentIdentityProperties | undefined {
+	const agentId = context.agentId?.trim();
+	if (!agentId) {
+		return undefined;
+	}
+	const parentAgentId = context.parentAgentId?.trim() || undefined;
+	const teamRole = context.teamRole;
+	let agentKind: TelemetryAgentIdentityProperties["agentKind"] = "root";
+	if (teamRole === "teammate") {
+		agentKind = "team_teammate";
+	} else if (teamRole === "lead") {
+		agentKind = "team_lead";
+	} else if (parentAgentId) {
+		agentKind = "subagent";
+	}
+	return {
+		agentId,
+		agentKind,
+		conversationId: context.conversationId?.trim() || undefined,
+		parentAgentId,
+		createdByAgentId:
+			context.createdByAgentId?.trim() || parentAgentId || undefined,
+		isSubagent: Boolean(parentAgentId),
+		teamId: context.teamId?.trim() || undefined,
+		teamName: context.teamName?.trim() || undefined,
+		teamRole,
+		teamAgentId: context.teamAgentId?.trim() || undefined,
+	};
+}
+
+export function handleAgentEvent(
+	ctx: AgentEventContext,
+	event: AgentEvent,
+	overrides?: AgentTelemetryContextOverrides,
+): void {
+	const { sessionId, config, liveSession, emit } = ctx;
+	const telemetry = config.telemetry;
+	const teamRuntime = liveSession?.runtime.teamRuntime;
+	const isPrimaryAgentEvent = overrides?.isPrimaryAgentEvent ?? true;
+	const eventMetadata = extractAgentEventMetadata(event);
+	const agentIdentity = buildTelemetryAgentIdentity({
+		agentId: overrides?.agentId ?? eventMetadata.agentId,
+		conversationId: overrides?.conversationId ?? eventMetadata.conversationId,
+		parentAgentId: overrides?.parentAgentId ?? eventMetadata.parentAgentId,
+		createdByAgentId: overrides?.createdByAgentId,
+		teamId: overrides?.teamId ?? teamRuntime?.getTeamId(),
+		teamName: overrides?.teamName ?? teamRuntime?.getTeamName(),
+		teamRole: overrides?.teamRole,
+		teamAgentId: overrides?.teamAgentId,
+	});
+
+	if (
+		event.type === "content_start" &&
+		event.contentType === "tool" &&
+		event.toolName === "skills"
+	) {
+		const skillName = extractSkillNameFromToolInput(event.input);
+		if (skillName) {
+			captureSkillUsed(telemetry, {
+				ulid: sessionId,
+				skillName,
+				skillSource: "project",
+				skillsAvailableGlobal: 0,
+				skillsAvailableProject: 0,
+				provider: config.providerId,
+				modelId: config.modelId,
+				...agentIdentity,
+			});
+		}
+	}
+
+	if (event.type === "content_end" && event.contentType === "tool") {
+		const toolName = event.toolName ?? "unknown";
+		const success = !event.error;
+		captureToolUsage(telemetry, {
+			ulid: sessionId,
+			tool: toolName,
+			autoApproved: undefined,
+			success,
+			modelId: config.modelId,
+			provider: config.providerId,
+			...agentIdentity,
+		});
+		if (!success && (toolName === "editor" || toolName === "apply_patch")) {
+			captureDiffEditFailure(telemetry, {
+				ulid: sessionId,
+				modelId: config.modelId,
+				provider: config.providerId,
+				errorType: event.error,
+				...agentIdentity,
+			});
+		}
+	}
+
+	if (event.type === "notice" && event.reason === "api_error") {
+		captureProviderApiError(telemetry, {
+			ulid: sessionId,
+			model: config.modelId,
+			provider: config.providerId,
+			errorMessage: event.message,
+			...agentIdentity,
+		});
+	}
+
+	if (event.type === "error") {
+		captureProviderApiError(telemetry, {
+			ulid: sessionId,
+			model: config.modelId,
+			provider: config.providerId,
+			errorMessage: event.error?.message ?? "unknown error",
+			...agentIdentity,
+		});
+	}
+
+	if (
+		event.type === "usage" &&
+		isPrimaryAgentEvent &&
+		liveSession?.turnUsageBaseline
+	) {
+		ctx.usageBySession.set(
+			sessionId,
+			accumulateUsageTotals(liveSession.turnUsageBaseline, {
+				inputTokens: event.inputTokens,
+				outputTokens: event.outputTokens,
+				cacheWriteTokens: event.cacheWriteTokens,
+				cacheReadTokens: event.cacheReadTokens,
+				totalCost: event.cost,
+			}),
+		);
+		captureConversationTurnEvent(telemetry, {
+			ulid: sessionId,
+			provider: config.providerId,
+			model: config.modelId,
+			source: "assistant",
+			mode: config.mode,
+			...agentIdentity,
+		});
+		captureTokenUsage(telemetry, {
+			ulid: sessionId,
+			tokensIn: event.inputTokens,
+			tokensOut: event.outputTokens,
+			cacheWriteTokens: event.cacheWriteTokens,
+			cacheReadTokens: event.cacheReadTokens,
+			totalCost: event.cost,
+			model: config.modelId,
+			...agentIdentity,
+		});
+	}
+
+	if (event.type === "iteration_end" && isPrimaryAgentEvent) {
+		ctx.persistMessages(
+			sessionId,
+			liveSession?.agent.getMessages() ?? [],
+			liveSession?.config.systemPrompt,
+		);
+	}
+
+	emit({
+		type: "agent_event",
+		payload: { sessionId, event },
+	});
+	emit({
+		type: "chunk",
+		payload: {
+			sessionId,
+			stream: "agent",
+			chunk: serializeAgentEvent(event),
+			ts: Date.now(),
+		},
+	});
+}

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-config-builder.ts

@@ -0,0 +1,113 @@
+import type { ITelemetryService } from "@clinebot/shared";
+import { resolveAndLoadAgentPlugins } from "../agents/plugin-config-loader";
+import {
+	createHookAuditHooks,
+	createHookConfigFileHooks,
+	mergeAgentHooks,
+} from "../runtime/hook-file-hooks";
+import type { ProviderSettingsManager } from "../storage/provider-settings-manager";
+import type { CoreSessionConfig } from "../types/config";
+import {
+	type ProviderConfig,
+	type ProviderSettings,
+	toProviderConfig,
+} from "../types/provider-settings";
+import type { StartSessionInput } from "./session-manager";
+import { hasRuntimeHooks, mergeAgentExtensions } from "./utils/helpers";
+
+export function resolveWorkspacePath(config: CoreSessionConfig): string {
+	return config.workspaceRoot ?? config.cwd;
+}
+
+export async function buildEffectiveConfig(
+	input: StartSessionInput,
+	hookPath: string,
+	sessionId: string,
+	defaultTelemetry: ITelemetryService | undefined,
+	onPluginEvent?: (event: { name: string; payload?: unknown }) => void,
+): Promise<{
+	config: CoreSessionConfig;
+	pluginSandboxShutdown?: () => Promise<void>;
+}> {
+	const workspacePath = resolveWorkspacePath(input.config);
+
+	const fileHooks = createHookConfigFileHooks({
+		cwd: input.config.cwd,
+		workspacePath,
+		rootSessionId: sessionId,
+		hookLogPath: hookPath,
+		logger: input.config.logger,
+	});
+	const auditHooks = hasRuntimeHooks(input.config.hooks)
+		? undefined
+		: createHookAuditHooks({
+				hookLogPath: hookPath,
+				rootSessionId: sessionId,
+				workspacePath,
+			});
+	const effectiveHooks = mergeAgentHooks([
+		input.config.hooks,
+		fileHooks,
+		auditHooks,
+	]);
+
+	const loadedPlugins = await resolveAndLoadAgentPlugins({
+		pluginPaths: input.config.pluginPaths,
+		workspacePath,
+		cwd: input.config.cwd,
+		onEvent: onPluginEvent,
+	});
+	const effectiveExtensions = mergeAgentExtensions(
+		input.config.extensions,
+		loadedPlugins.extensions,
+	);
+
+	return {
+		config: {
+			...input.config,
+			hooks: effectiveHooks,
+			extensions: effectiveExtensions,
+			telemetry: input.config.telemetry ?? defaultTelemetry,
+		},
+		pluginSandboxShutdown: loadedPlugins.shutdown,
+	};
+}
+
+export function buildResolvedProviderConfig(
+	config: CoreSessionConfig,
+	providerSettingsManager: ProviderSettingsManager,
+	resolveReasoningFn: (
+		config: CoreSessionConfig,
+		storedReasoning: ProviderSettings["reasoning"],
+	) => ProviderSettings["reasoning"],
+): ProviderConfig {
+	const stored = providerSettingsManager.getProviderSettings(config.providerId);
+	const settings: ProviderSettings = {
+		...(stored ?? {}),
+		provider: config.providerId,
+		model: config.modelId,
+		apiKey: config.apiKey ?? stored?.apiKey,
+		baseUrl: config.baseUrl ?? stored?.baseUrl,
+		headers: config.headers ?? stored?.headers,
+		reasoning: resolveReasoningFn(config, stored?.reasoning),
+	};
+	const providerConfig = toProviderConfig(settings);
+	if (config.knownModels) {
+		providerConfig.knownModels = config.knownModels;
+	}
+	return providerConfig;
+}
+
+export function resolveReasoningSettings(
+	config: CoreSessionConfig,
+	storedReasoning: ProviderSettings["reasoning"],
+): ProviderSettings["reasoning"] {
+	const hasThinking = typeof config.thinking === "boolean";
+	const hasEffort = typeof config.reasoningEffort === "string";
+	if (!hasThinking && !hasEffort) return storedReasoning;
+	return {
+		...(storedReasoning ?? {}),
+		...(hasThinking ? { enabled: config.thinking } : {}),
+		...(hasEffort ? { effort: config.reasoningEffort } : {}),
+	};
+}

package/src/session/session-graph.ts

@@ -0,0 +1,92 @@
+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 "agent_error":
+			return "failed";
+		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.test.ts

@@ -0,0 +1,89 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { FileSessionService } from "./file-session-service";
+
+const sqliteInitMock = vi.hoisted(() => vi.fn());
+const ensureRpcRuntimeAddressMock = vi.hoisted(() => vi.fn());
+const resolveRpcOwnerContextMock = vi.hoisted(() =>
+	vi.fn(() => ({
+		ownerId: "core-owner",
+		buildId: "core-build",
+		discoveryPath: "/tmp/rpc-owner.json",
+	})),
+);
+const rpcHealthByAddress = vi.hoisted(() => new Map<string, unknown>());
+
+vi.mock("@clinebot/rpc", () => ({
+	RPC_BUILD_VERSION: "rpc-build-test",
+	getRpcServerDefaultAddress: () => "ws://127.0.0.1:0",
+	getRpcServerHealth: vi.fn(async (address: string) => {
+		return rpcHealthByAddress.get(address);
+	}),
+}));
+
+vi.mock("./rpc-runtime-ensure", () => ({
+	ensureRpcRuntimeAddress: ensureRpcRuntimeAddressMock,
+	resolveRpcOwnerContext: resolveRpcOwnerContextMock,
+}));
+
+vi.mock("../storage/sqlite-session-store", () => ({
+	SqliteSessionStore: class {
+		init(): void {
+			sqliteInitMock();
+		}
+	},
+}));
+
+describe("resolveSessionBackend", () => {
+	afterEach(() => {
+		sqliteInitMock.mockReset();
+		ensureRpcRuntimeAddressMock.mockReset();
+		resolveRpcOwnerContextMock.mockClear();
+		rpcHealthByAddress.clear();
+		vi.resetModules();
+	});
+
+	it("falls back to file session storage when sqlite initialization fails", async () => {
+		const { resolveSessionBackend } = await import("./session-host");
+		sqliteInitMock.mockImplementation(() => {
+			throw new Error("sqlite unavailable");
+		});
+
+		const backend = await resolveSessionBackend({ backendMode: "local" });
+		expect(backend).toBeInstanceOf(FileSessionService);
+	});
+
+	it("connects to the ensured rpc address when the sidecar relocates ports", async () => {
+		const { resolveSessionBackend } = await import("./session-host");
+		ensureRpcRuntimeAddressMock.mockResolvedValue({
+			address: "ws://127.0.0.1:12345",
+			action: "new-port",
+			owner: {
+				ownerId: "core-owner",
+				buildId: "core-build",
+				discoveryPath: "/tmp/rpc-owner.json",
+			},
+		});
+		rpcHealthByAddress.set("ws://127.0.0.1:12345", {
+			running: true,
+			serverId: "rpc-server",
+		});
+
+		const backend = await resolveSessionBackend({
+			backendMode: "auto",
+			rpc: {
+				address: "ws://127.0.0.1:4317",
+				connectAttempts: 1,
+				connectDelayMs: 0,
+			},
+		});
+
+		expect(ensureRpcRuntimeAddressMock).toHaveBeenCalledWith(
+			"ws://127.0.0.1:4317",
+			expect.objectContaining({
+				spawnIfNeeded: expect.any(Function),
+				resolveOwner: expect.any(Function),
+			}),
+		);
+		expect(backend).not.toBeInstanceOf(FileSessionService);
+	});
+});