@clinebot/core 0.0.34 → 0.0.35

package/src/{session → runtime}/rpc-runtime-ensure.ts

@@ -24,6 +24,10 @@ type RpcStartupLockRecord = {
 	pid: number;
 	address: string;
 	acquiredAt: string;
+	updatedAt: string;
+	status: "starting" | "running";
+	resolvedAddress?: string;
+	serverId?: string;
 };
 
 export type RpcDiscoveryRecord = {
@@ -233,22 +237,54 @@ function isProbeBlocked(error: unknown): boolean {
 	return isUnimplementedError(error) || isAuthenticationError(error);
 }
 
-async function hasRuntimeMethods(address: string): Promise<boolean> {
+function formatProbeError(error: unknown): string {
+	if (error instanceof Error && error.message.trim()) {
+		return error.message.trim();
+	}
+	return String(error);
+}
+
+type RuntimeMethodsProbeResult = {
+	available: boolean;
+	reason?: string;
+};
+
+async function probeRuntimeMethods(
+	address: string,
+): Promise<RuntimeMethodsProbeResult> {
 	const client = new RpcSessionClient({ address });
 	try {
 		try {
 			await client.stopRuntimeSession("__rpc_probe__");
 		} catch (error) {
-			if (isProbeBlocked(error)) return false;
+			if (isProbeBlocked(error)) {
+				return {
+					available: false,
+					reason: `runtime probe blocked (${formatProbeError(error)})`,
+				};
+			}
 		}
-		return true;
+		return { available: true };
 	} catch (error) {
-		return !isProbeBlocked(error);
+		if (isProbeBlocked(error)) {
+			return {
+				available: false,
+				reason: `runtime probe blocked (${formatProbeError(error)})`,
+			};
+		}
+		return {
+			available: false,
+			reason: `runtime probe failed (${formatProbeError(error)})`,
+		};
 	} finally {
 		client.close();
 	}
 }
 
+async function hasRuntimeMethods(address: string): Promise<boolean> {
+	return (await probeRuntimeMethods(address)).available;
+}
+
 export async function isCompatibleRuntime(address: string): Promise<boolean> {
 	const health = await getRpcServerHealth(address);
 	return (
@@ -258,6 +294,32 @@ export async function isCompatibleRuntime(address: string): Promise<boolean> {
 	);
 }
 
+async function describeRpcRuntimeReadinessFailure(
+	address: string,
+): Promise<string> {
+	let health: Awaited<ReturnType<typeof getRpcServerHealth>> | undefined;
+	try {
+		health = await getRpcServerHealth(address);
+	} catch (error) {
+		return `health probe failed (${formatProbeError(error)})`;
+	}
+	if (!health?.running) {
+		return "health probe reported no running server";
+	}
+	if (!isHealthCompatible(health)) {
+		const actualVersion =
+			typeof health.rpcVersion === "string" && health.rpcVersion.trim()
+				? health.rpcVersion.trim()
+				: "unknown";
+		return `protocol mismatch (expected=${RPC_PROTOCOL_VERSION}, actual=${actualVersion})`;
+	}
+	const runtimeProbe = await probeRuntimeMethods(address);
+	if (!runtimeProbe.available) {
+		return runtimeProbe.reason ?? "runtime methods unavailable";
+	}
+	return "runtime did not become compatible before readiness deadline";
+}
+
 async function isPortFree(host: string, port: number): Promise<boolean> {
 	return new Promise<boolean>((resolve) => {
 		const server = createServer();
@@ -294,13 +356,8 @@ function isPidAlive(pid: number | undefined): boolean {
 
 async function writeRpcStartupLockRecord(
 	lockDir: string,
-	address: string,
+	record: RpcStartupLockRecord,
 ): Promise<void> {
-	const record: RpcStartupLockRecord = {
-		pid: process.pid,
-		address,
-		acquiredAt: new Date().toISOString(),
-	};
 	await writeFile(
 		join(lockDir, "owner.json"),
 		JSON.stringify(record, null, 2),
@@ -318,7 +375,9 @@ async function readRpcStartupLockRecord(
 		if (
 			typeof parsed.pid !== "number" ||
 			typeof parsed.address !== "string" ||
-			typeof parsed.acquiredAt !== "string"
+			typeof parsed.acquiredAt !== "string" ||
+			typeof parsed.updatedAt !== "string" ||
+			(parsed.status !== "starting" && parsed.status !== "running")
 		) {
 			return undefined;
 		}
@@ -326,6 +385,14 @@ async function readRpcStartupLockRecord(
 			pid: parsed.pid,
 			address: parsed.address,
 			acquiredAt: parsed.acquiredAt,
+			updatedAt: parsed.updatedAt,
+			status: parsed.status,
+			resolvedAddress:
+				typeof parsed.resolvedAddress === "string"
+					? parsed.resolvedAddress
+					: undefined,
+			serverId:
+				typeof parsed.serverId === "string" ? parsed.serverId : undefined,
 		};
 	} catch {
 		return undefined;
@@ -336,12 +403,59 @@ async function removeRpcStartupLockDir(lockDir: string): Promise<void> {
 	await rm(lockDir, { recursive: true, force: true }).catch(() => {});
 }
 
+async function updateRpcStartupLockRecord(
+	lockDir: string,
+	patch: Partial<Omit<RpcStartupLockRecord, "pid" | "address" | "acquiredAt">>,
+): Promise<void> {
+	const current = await readRpcStartupLockRecord(lockDir);
+	if (!current) {
+		return;
+	}
+	await writeRpcStartupLockRecord(lockDir, {
+		...current,
+		...patch,
+		updatedAt: new Date().toISOString(),
+	});
+}
+
+async function isRpcStartupLockStale(
+	existing: RpcStartupLockRecord | undefined,
+): Promise<boolean> {
+	const acquiredAtMs = existing ? new Date(existing.acquiredAt).getTime() : NaN;
+	if (
+		!existing ||
+		!Number.isFinite(acquiredAtMs) ||
+		Date.now() - acquiredAtMs > RPC_STARTUP_LOCK_MAX_AGE_MS ||
+		!isPidAlive(existing.pid)
+	) {
+		return true;
+	}
+	if (existing.status !== "running") {
+		return false;
+	}
+	const targetAddress = existing.resolvedAddress?.trim() || existing.address;
+	try {
+		return !(await getRpcServerHealth(targetAddress))?.running;
+	} catch {
+		return true;
+	}
+}
+
+export type RpcStartupLockHandle = {
+	markRunning: (details?: {
+		resolvedAddress?: string;
+		serverId?: string;
+	}) => Promise<void>;
+};
+
 export async function withRpcStartupLock<T>(
 	address: string,
-	action: () => Promise<T>,
+	action: (lock: RpcStartupLockHandle) => Promise<T>,
 ): Promise<T> {
 	if (process.env[RPC_STARTUP_LOCK_BYPASS_ENV] === "1") {
-		return await action();
+		return await action({
+			markRunning: async () => undefined,
+		});
 	}
 
 	const lockDir = getRpcStartupLockDir(address);
@@ -351,9 +465,23 @@ export async function withRpcStartupLock<T>(
 	while (true) {
 		try {
 			await mkdir(lockDir, { recursive: false });
-			await writeRpcStartupLockRecord(lockDir, address);
+			await writeRpcStartupLockRecord(lockDir, {
+				pid: process.pid,
+				address,
+				acquiredAt: new Date().toISOString(),
+				updatedAt: new Date().toISOString(),
+				status: "starting",
+			});
 			try {
-				return await action();
+				return await action({
+					markRunning: async (details) => {
+						await updateRpcStartupLockRecord(lockDir, {
+							status: "running",
+							resolvedAddress: details?.resolvedAddress?.trim() || undefined,
+							serverId: details?.serverId?.trim() || undefined,
+						});
+					},
+				});
 			} finally {
 				await removeRpcStartupLockDir(lockDir);
 			}
@@ -361,22 +489,17 @@ export async function withRpcStartupLock<T>(
 			if (errorCode(error) !== "EEXIST") throw error;
 
 			const existing = await readRpcStartupLockRecord(lockDir);
-			const acquiredAtMs = existing
-				? new Date(existing.acquiredAt).getTime()
-				: Number.NaN;
-			const isStale =
-				!existing ||
-				!Number.isFinite(acquiredAtMs) ||
-				Date.now() - acquiredAtMs > RPC_STARTUP_LOCK_MAX_AGE_MS ||
-				!isPidAlive(existing.pid);
+			const isStale = await isRpcStartupLockStale(existing);
 			if (isStale) {
 				await removeRpcStartupLockDir(lockDir);
 				continue;
 			}
 
 			if (Date.now() - startedAt >= RPC_STARTUP_LOCK_WAIT_MS) {
+				const ownerPid =
+					typeof existing?.pid === "number" ? existing.pid : "unknown";
 				throw new Error(
-					`timed out waiting for rpc startup lock at ${address} (owner pid=${existing.pid})`,
+					`timed out waiting for rpc startup lock at ${address} (owner pid=${ownerPid})`,
 				);
 			}
 			await sleep(RPC_STARTUP_LOCK_POLL_MS);
@@ -415,11 +538,18 @@ export async function resolveEnsuredRpcRuntime(
 	options: {
 		owner?: RpcOwnerContext;
 		resolveOwner?: () => RpcOwnerContext;
+		/**
+		 * When true, skip startup lock acquisition. Use this when the caller
+		 * already holds the lock via {@link withRpcStartupLock} to avoid a
+		 * deadlock from nested lock acquisition on the same address.
+		 */
+		lockAlreadyHeld?: boolean;
 	} = {},
 ): Promise<ResolveRpcRuntimeResult> {
 	const owner =
 		options.owner ?? options.resolveOwner?.() ?? resolveRpcOwnerContext();
-	return await withRpcStartupLock(requestedAddress, async () => {
+
+	const core = async (): Promise<ResolveRpcRuntimeResult> => {
 		const discovery = await readRpcDiscovery(owner);
 		if (discovery?.address) {
 			const discoveredHealth = await getRpcServerHealth(discovery.address);
@@ -475,7 +605,12 @@ export async function resolveEnsuredRpcRuntime(
 			action: "new-port",
 			owner,
 		} satisfies ResolveRpcRuntimeResult;
-	});
+	};
+
+	if (options.lockAlreadyHeld) {
+		return await core();
+	}
+	return await withRpcStartupLock(requestedAddress, core);
 }
 
 export async function waitForCompatibleRpcRuntime(
@@ -506,7 +641,10 @@ export async function ensureRpcRuntimeAddress(
 			options.readinessCheck,
 		))
 	) {
-		throw new Error(`failed to ensure rpc runtime at ${resolved.address}`);
+		const reason = await describeRpcRuntimeReadinessFailure(resolved.address);
+		throw new Error(
+			`failed to ensure rpc runtime at ${resolved.address}: ${reason}`,
+		);
 	}
 	const health = await getRpcServerHealth(resolved.address);
 	await recordRpcDiscovery(resolved.owner, {

package/src/{session → runtime}/rpc-spawn-lease.test.ts

@@ -1,4 +1,5 @@
-import { mkdtempSync, rmSync } from "node:fs";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
@@ -46,4 +47,35 @@ describe("tryAcquireRpcSpawnLease", () => {
 		first?.release();
 		second?.release();
 	});
+
+	it("reclaims a leftover lease owned by the current process", () => {
+		const dataDir = mkdtempSync(path.join(os.tmpdir(), "rpc-spawn-lease-"));
+		tempDirs.push(dataDir);
+		process.env.CLINE_DATA_DIR = dataDir;
+
+		const first = tryAcquireRpcSpawnLease("127.0.0.1:4317");
+		expect(first).toBeDefined();
+		const leasePath = first?.path;
+		expect(leasePath).toBeTruthy();
+		first?.release();
+
+		writeFileSync(
+			leasePath!,
+			JSON.stringify({
+				address: "127.0.0.1:4317",
+				pid: process.pid,
+				createdAt: Date.now(),
+			}),
+			"utf8",
+		);
+
+		const second = tryAcquireRpcSpawnLease("127.0.0.1:4317");
+		assert(second);
+		expect(
+			JSON.parse(readFileSync(second.path, "utf8")) as { pid: number },
+		).toMatchObject({
+			pid: process.pid,
+		});
+		second.release();
+	});
 });

package/src/{session → runtime}/rpc-spawn-lease.ts

@@ -10,7 +10,7 @@ import {
 import { dirname, resolve } from "node:path";
 import { resolveSessionDataDir } from "@clinebot/shared/storage";
 
-const DEFAULT_LEASE_TTL_MS = 15_000;
+const DEFAULT_LEASE_TTL_MS = 5_000;
 
 interface RpcSpawnLeaseRecord {
 	address: string;
@@ -23,6 +23,10 @@ export interface RpcSpawnLease {
 	release: () => void;
 }
 
+const ACTIVE_LEASE_RELEASES = new Set<() => void>();
+const ACTIVE_LEASE_PATHS = new Set<string>();
+let EXIT_CLEANUP_REGISTERED = false;
+
 function encodeAddress(address: string): string {
 	return Buffer.from(address).toString("base64url");
 }
@@ -52,19 +56,43 @@ function shouldClearLease(path: string, ttlMs: number): boolean {
 	try {
 		const raw = readFileSync(path, "utf8");
 		const parsed = JSON.parse(raw) as Partial<RpcSpawnLeaseRecord>;
+		const pid = Number(parsed.pid ?? 0);
 		const createdAt = Number(parsed.createdAt ?? 0);
+		if (pid === process.pid && !ACTIVE_LEASE_PATHS.has(path)) {
+			return true;
+		}
 		if (!Number.isFinite(createdAt) || createdAt <= 0) {
 			return true;
 		}
 		if (Date.now() - createdAt > ttlMs) {
 			return true;
 		}
-		return !isProcessAlive(Number(parsed.pid ?? 0));
+		return !isProcessAlive(pid);
 	} catch {
 		return true;
 	}
 }
 
+function cleanupActiveLeases(): void {
+	for (const release of [...ACTIVE_LEASE_RELEASES]) {
+		try {
+			release();
+		} catch {
+			// Best effort.
+		}
+	}
+}
+
+function registerExitCleanupOnce(): void {
+	if (EXIT_CLEANUP_REGISTERED) {
+		return;
+	}
+	EXIT_CLEANUP_REGISTERED = true;
+	process.once("exit", cleanupActiveLeases);
+	process.once("SIGINT", cleanupActiveLeases);
+	process.once("SIGTERM", cleanupActiveLeases);
+}
+
 export function tryAcquireRpcSpawnLease(
 	address: string,
 	options?: { ttlMs?: number },
@@ -98,25 +126,31 @@ export function tryAcquireRpcSpawnLease(
 	}
 
 	let released = false;
+	const release = () => {
+		if (released) {
+			return;
+		}
+		released = true;
+		ACTIVE_LEASE_RELEASES.delete(release);
+		ACTIVE_LEASE_PATHS.delete(path);
+		try {
+			if (typeof fd === "number") {
+				closeSync(fd);
+			}
+		} catch {
+			// Best effort.
+		}
+		try {
+			rmSync(path, { force: true });
+		} catch {
+			// Best effort.
+		}
+	};
+	registerExitCleanupOnce();
+	ACTIVE_LEASE_RELEASES.add(release);
+	ACTIVE_LEASE_PATHS.add(path);
 	return {
 		path,
-		release: () => {
-			if (released) {
-				return;
-			}
-			released = true;
-			try {
-				if (typeof fd === "number") {
-					closeSync(fd);
-				}
-			} catch {
-				// Best effort.
-			}
-			try {
-				rmSync(path, { force: true });
-			} catch {
-				// Best effort.
-			}
-		},
+		release,
 	};
 }

package/src/runtime/runtime-builder.team-persistence.test.ts

@@ -35,7 +35,7 @@ class MockAgentTeamsRuntime {
 	shutdownTeammate = vi.fn();
 }
 
-vi.mock("../team", () => ({
+vi.mock("../extensions/tools/team", () => ({
 	AgentTeamsRuntime: MockAgentTeamsRuntime,
 	bootstrapAgentTeams: bootstrapAgentTeamsMock,
 	createDelegatedAgentConfigProvider: (config: Record<string, unknown>) => {
@@ -59,13 +59,16 @@ vi.mock("../team", () => ({
 	},
 }));
 
-vi.mock("../default-tools", () => ({
+vi.mock("../extensions/tools", () => ({
 	ALL_DEFAULT_TOOL_NAMES: [],
 	createBuiltinTools: createBuiltinToolsMock,
 	ToolPresets: {
 		development: {},
 		readonly: {},
 	},
+	resolveToolPresetName: () => "development",
+	resolveToolRoutingConfig: () => [],
+	DEFAULT_MODEL_TOOL_ROUTING_RULES: [],
 }));
 
 let teamStoreInstance: MockTeamStore | undefined;
@@ -100,7 +103,7 @@ class MockTeamStore {
 	persistRuntime = vi.fn();
 }
 
-vi.mock("../storage/team-store", () => ({
+vi.mock("../services/storage/team-store", () => ({
 	createLocalTeamStore: () => new MockTeamStore(),
 }));
 

package/src/runtime/runtime-builder.test.ts

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Tool } from "@clinebot/shared";
 import { describe, expect, it } from "vitest";
-import { TelemetryService } from "../telemetry/TelemetryService";
+import { TelemetryService } from "../services/telemetry/TelemetryService";
 import type { CoreSessionConfig } from "../types/config";
 import { DefaultRuntimeBuilder } from "./runtime-builder";
 
@@ -83,8 +83,7 @@ describe("DefaultRuntimeBuilder", () => {
 	it("uses yolo preset only when yolo mode is explicit", async () => {
 		const runtime = await new DefaultRuntimeBuilder().build({
 			config: makeBaseConfig({
-				mode: "act",
-				yolo: true,
+				mode: "yolo",
 			}),
 			defaultToolExecutors: {
 				submit: async () => "submitted",
@@ -120,7 +119,7 @@ describe("DefaultRuntimeBuilder", () => {
 			config: {
 				...makeBaseConfig({
 					enableTools: false,
-					yolo: true,
+					mode: "yolo",
 				}),
 			} as CoreSessionConfig,
 			createSpawnTool: makeSpawnTool,

package/src/runtime/runtime-builder.ts

@@ -16,13 +16,6 @@ import {
 	registerMcpServersFromSettingsFile,
 	resolveDefaultMcpSettingsPath,
 } from "../extensions/mcp";
-import { createLocalTeamStore } from "../storage/team-store";
-import {
-	AgentTeamsRuntime,
-	bootstrapAgentTeams,
-	createDelegatedAgentConfigProvider,
-	type TeamEvent,
-} from "../team";
 import {
 	createBuiltinTools,
 	DEFAULT_MODEL_TOOL_ROUTING_RULES,
@@ -32,7 +25,14 @@ import {
 	type ToolExecutors,
 	ToolPresets,
 	type ToolRoutingRule,
-} from "../tools";
+} from "../extensions/tools";
+import {
+	AgentTeamsRuntime,
+	bootstrapAgentTeams,
+	createDelegatedAgentConfigProvider,
+	type TeamEvent,
+} from "../extensions/tools/team";
+import { createLocalTeamStore } from "../services/storage/team-store";
 import type { CoreAgentMode, CoreSessionConfig } from "../types/config";
 import type {
 	RuntimeBuilder,
@@ -82,14 +82,13 @@ function createBuiltinToolsList(
 	cwd: string,
 	providerId: string,
 	mode: CoreAgentMode,
-	yolo: boolean | undefined,
 	modelId: string,
 	toolRoutingRules: ToolRoutingRule[] | undefined,
 	toolPolicies: CoreSessionConfig["toolPolicies"],
 	skillsExecutor?: SkillsExecutorWithMetadata,
 	executorOverrides?: Partial<ToolExecutors>,
 ): Tool[] {
-	const preset = ToolPresets[resolveToolPresetName({ mode, yolo })];
+	const preset = ToolPresets[resolveToolPresetName({ mode })];
 	const toolRoutingConfig = resolveToolRoutingConfig(
 		providerId,
 		modelId,
@@ -429,16 +428,11 @@ function normalizeConfig(
 		| "sessionId"
 	>
 > {
-	const preset =
-		ToolPresets[
-			resolveToolPresetName({
-				mode: config.mode,
-				yolo: config.yolo,
-			})
-		];
+	const preset = ToolPresets[resolveToolPresetName({ mode: config.mode })];
 	return {
 		sessionId: config.sessionId || "",
-		mode: config.mode === "plan" ? "plan" : "act",
+		mode:
+			config.mode === "plan" ? "plan" : config.mode === "yolo" ? "yolo" : "act",
 		enableTools: config.enableTools !== false,
 		enableSpawnAgent:
 			config.enableSpawnAgent ?? preset.enableSpawnAgent ?? true,
@@ -523,7 +517,6 @@ export class DefaultRuntimeBuilder implements RuntimeBuilder {
 					config.cwd,
 					config.providerId,
 					normalized.mode,
-					normalized.yolo,
 					config.modelId,
 					config.toolRoutingRules,
 					config.toolPolicies,
@@ -653,7 +646,6 @@ export class DefaultRuntimeBuilder implements RuntimeBuilder {
 									config.cwd,
 									config.providerId,
 									normalized.mode,
-									normalized.yolo,
 									config.modelId,
 									config.toolRoutingRules,
 									config.toolPolicies,
@@ -715,7 +707,7 @@ export class DefaultRuntimeBuilder implements RuntimeBuilder {
 						if (pending) parts.push(`Unfinished tasks: ${pending}`);
 						if (activeRunSummary)
 							parts.push(`Active runs: ${activeRunSummary}`);
-						return `[SYSTEM] You still have team obligations. ${parts.join(". ")}. Use team_run_task to delegate work, or team_task with action=complete to mark tasks done, or team_await_run / team_await_all_runs to wait for active runs. Do NOT stop until all tasks are completed.`;
+						return `[SYSTEM] You still have team obligations. ${parts.join(". ")}. Use team_run_task to delegate work, or team_task with action=complete to mark tasks done, or team_await_runs to wait for active runs. Do NOT stop until all tasks are completed.`;
 					}
 					return undefined;
 				}