@clinebot/core 0.0.36 → 0.0.37

package/src/runtime/loop-detection.ts

@@ -0,0 +1,162 @@
+/**
+ * Repeated tool-call loop detection.
+ *
+ * @see PLAN.md §3.1 — helpers moved from `packages/agents/src/context/loop-detection.ts`.
+ * @see PLAN.md §3.2.3 — public surface of `LoopDetectionTracker`.
+ *
+ * The pure helpers (`createLoopDetectionState`, `resetLoopDetectionState`,
+ * `toolCallSignature`, `checkRepeatedToolCall`) are ported verbatim. The
+ * `LoopDetectionTracker` class is a thin wrapper that owns a
+ * `LoopDetectionState` and exposes the `inspect()` / `reset()` surface that
+ * `SessionRuntime` installs as a `beforeTool` hook per §3.2.3.
+ */
+
+import type { LoopDetectionConfig } from "@clinebot/shared";
+
+// =============================================================================
+// Pure helpers (verbatim port)
+// =============================================================================
+
+export interface LoopDetectionState {
+	lastToolName: string;
+	lastToolSignature: string;
+	consecutiveIdenticalCount: number;
+}
+
+export function createLoopDetectionState(): LoopDetectionState {
+	return {
+		lastToolName: "",
+		lastToolSignature: "",
+		consecutiveIdenticalCount: 0,
+	};
+}
+
+export function resetLoopDetectionState(state: LoopDetectionState): void {
+	state.lastToolName = "";
+	state.lastToolSignature = "";
+	state.consecutiveIdenticalCount = 0;
+}
+
+function sortKeys(value: unknown): unknown {
+	if (value == null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map(sortKeys);
+	const sorted: Record<string, unknown> = {};
+	for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+		sorted[key] = sortKeys((value as Record<string, unknown>)[key]);
+	}
+	return sorted;
+}
+
+export function toolCallSignature(input: unknown): string {
+	if (input == null) return "null";
+	if (typeof input === "string") return input;
+	if (typeof input !== "object") return String(input);
+	try {
+		return JSON.stringify(sortKeys(input));
+	} catch {
+		return String(input);
+	}
+}
+
+export interface LoopCheckResult {
+	softWarning: boolean;
+	hardEscalation: boolean;
+}
+
+export function checkRepeatedToolCall(
+	state: LoopDetectionState,
+	toolName: string,
+	signature: string,
+	config: LoopDetectionConfig,
+): LoopCheckResult {
+	if (
+		toolName === state.lastToolName &&
+		signature === state.lastToolSignature
+	) {
+		state.consecutiveIdenticalCount++;
+	} else {
+		state.consecutiveIdenticalCount = 1;
+	}
+	state.lastToolName = toolName;
+	state.lastToolSignature = signature;
+
+	return {
+		softWarning: state.consecutiveIdenticalCount === config.softThreshold,
+		hardEscalation: state.consecutiveIdenticalCount >= config.hardThreshold,
+	};
+}
+
+// =============================================================================
+// Class wrapper (new — per PLAN.md §3.2.3)
+// =============================================================================
+
+/**
+ * Verdict returned by {@link LoopDetectionTracker.inspect}.
+ *
+ * - `"ok"`   — no repeated call detected.
+ * - `"soft"` — soft-warning threshold reached; SessionRuntime may surface a
+ *              recovery notice but should not block the call.
+ * - `"hard"` — hard-escalation threshold reached; SessionRuntime should
+ *              stop the run with the provided `message`.
+ */
+export interface LoopDetectionVerdict {
+	kind: "ok" | "soft" | "hard";
+	message?: string;
+}
+
+/** Minimal call shape the tracker needs; matches `AgentToolCallPart` subset. */
+export interface LoopDetectionCall {
+	name: string;
+	input: unknown;
+}
+
+const DEFAULT_CONFIG: LoopDetectionConfig = {
+	softThreshold: 3,
+	hardThreshold: 5,
+};
+
+/**
+ * Per-session repeated-tool-call detector.
+ *
+ * `SessionRuntime` owns the instance and installs a `beforeTool` hook
+ * (see `AgentRuntimeHooks.beforeTool`) that calls `inspect()` to decide
+ * whether to return `{ skip, stop, reason }`.
+ */
+export class LoopDetectionTracker {
+	private readonly config: LoopDetectionConfig;
+	private readonly state: LoopDetectionState = createLoopDetectionState();
+
+	constructor(config?: Partial<LoopDetectionConfig>) {
+		this.config = {
+			softThreshold: config?.softThreshold ?? DEFAULT_CONFIG.softThreshold,
+			hardThreshold: config?.hardThreshold ?? DEFAULT_CONFIG.hardThreshold,
+		};
+	}
+
+	inspect(call: LoopDetectionCall): LoopDetectionVerdict {
+		const signature = toolCallSignature(call.input);
+		const result = checkRepeatedToolCall(
+			this.state,
+			call.name,
+			signature,
+			this.config,
+		);
+		if (result.hardEscalation) {
+			return {
+				kind: "hard",
+				message: `Detected ${this.state.consecutiveIdenticalCount} consecutive identical calls to \`${call.name}\`; stopping to avoid a loop.`,
+			};
+		}
+		if (result.softWarning) {
+			return {
+				kind: "soft",
+				message: `Detected ${this.state.consecutiveIdenticalCount} consecutive identical calls to \`${call.name}\`; consider trying a different approach.`,
+			};
+		}
+		return { kind: "ok" };
+	}
+
+	reset(): void {
+		resetLoopDetectionState(this.state);
+	}
+}

package/src/runtime/mistake-tracker.ts

@@ -0,0 +1,221 @@
+/**
+ * Per-session consecutive-mistake tracker.
+ *
+ * @see PLAN.md §3.1 — wrapped around `recordMistake` moved from
+ *                    `packages/agents/src/api/error-handling.ts` lines 147–311.
+ * @see PLAN.md §3.2.3 — public surface of `MistakeTracker`.
+ *
+ * The pure procedural `recordMistake(input, deps)` becomes `record(input)`
+ * on the class; `consecutiveMistakes` is internal state. Other deps flow
+ * through the constructor instead.
+ *
+ * NOTE: the §3.2.3 constructor shape omits some fields (agentId,
+ * conversationId/runId getters, appendRecoveryNotice). They are retained
+ * here for log + notice parity per PLAN.md §3.4.3/§3.4.5. Step 8
+ * (`impl-runtime-porter`) may refactor once SessionRuntime is wired up.
+ */
+
+import type {
+	AgentEvent,
+	BasicLogMetadata,
+	ConsecutiveMistakeLimitContext,
+	ConsecutiveMistakeLimitDecision,
+} from "@clinebot/shared";
+
+/**
+ * Legacy-agents-style leveled log function. The sdk-re `BasicLogger`
+ * does not carry a level argument (§shared/logging/logger.ts); callers
+ * are expected to bridge via `metadata.severity` or dispatch to
+ * `debug`/`log`/`error`. `MistakeTracker` accepts a leveled callable
+ * here so Step 8 can plug in whichever bridging shape `SessionRuntime`
+ * ends up using.
+ */
+export type LeveledLog = (
+	level: "debug" | "info" | "warn" | "error",
+	message: string,
+	metadata?: BasicLogMetadata,
+) => void;
+
+export type MistakeReason =
+	| "api_error"
+	| "invalid_tool_call"
+	| "tool_execution_failed";
+
+export interface RecordMistakeInput {
+	iteration: number;
+	reason: MistakeReason;
+	details?: string;
+	/** When true, jump straight to maxConsecutiveMistakes instead of incrementing by 1. */
+	forceAtLimit?: boolean;
+}
+
+export type MistakeOutcome =
+	| { action: "continue"; guidance?: string }
+	| { action: "stop"; message: string; reason?: string };
+
+export interface MistakeTrackerOptions {
+	readonly maxConsecutiveMistakes: number;
+	readonly onLimitReached?: (
+		ctx: ConsecutiveMistakeLimitContext,
+	) =>
+		| Promise<ConsecutiveMistakeLimitDecision>
+		| ConsecutiveMistakeLimitDecision;
+	readonly emit: (event: AgentEvent) => void;
+	readonly log: LeveledLog;
+	readonly agentId: string;
+	readonly getConversationId: () => string;
+	readonly getActiveRunId: () => string;
+	readonly appendRecoveryNotice: (
+		message: string,
+		reason: MistakeReason,
+	) => void;
+}
+
+export class MistakeTracker {
+	private consecutiveMistakes = 0;
+	private readonly options: MistakeTrackerOptions;
+
+	constructor(options: MistakeTrackerOptions) {
+		this.options = options;
+	}
+
+	async record(input: RecordMistakeInput): Promise<MistakeOutcome> {
+		const max = this.options.maxConsecutiveMistakes;
+		const next = input.forceAtLimit && max ? max : this.consecutiveMistakes + 1;
+		this.consecutiveMistakes = next;
+
+		const errorMessage =
+			input.details?.trim() || `consecutive mistake (${input.reason})`;
+		this.options.emit({
+			type: "error",
+			error: new Error(errorMessage),
+			recoverable: true,
+			iteration: input.iteration,
+		});
+		this.options.log("warn", "Recorded consecutive mistake", {
+			agentId: this.options.agentId,
+			conversationId: this.options.getConversationId(),
+			runId: this.options.getActiveRunId(),
+			iteration: input.iteration,
+			reason: input.reason,
+			details: input.details,
+			consecutiveMistakes: next,
+			maxConsecutiveMistakes: this.options.maxConsecutiveMistakes,
+		});
+
+		if (!max || next < max) {
+			return { action: "continue" };
+		}
+
+		const decision = await resolveConsecutiveMistakeDecision(
+			{
+				iteration: input.iteration,
+				consecutiveMistakes: next,
+				maxConsecutiveMistakes: max,
+				reason: input.reason,
+				details: input.details,
+			},
+			this.options.onLimitReached,
+		);
+
+		if (decision.action === "continue") {
+			const guidance = decision.guidance?.trim();
+			if (guidance) {
+				this.options.appendRecoveryNotice(guidance, input.reason);
+			}
+			this.consecutiveMistakes = 0;
+			return { action: "continue", guidance };
+		}
+
+		return {
+			action: "stop",
+			reason: decision.reason?.trim() || undefined,
+			message: buildMistakeLimitStopMessage({
+				iteration: input.iteration,
+				consecutiveMistakes: next,
+				maxConsecutiveMistakes: max,
+				reason: input.reason,
+				details: input.details,
+				stopReason: decision.reason,
+			}),
+		};
+	}
+
+	reset(): void {
+		this.consecutiveMistakes = 0;
+	}
+
+	get value(): number {
+		return this.consecutiveMistakes;
+	}
+}
+
+// =============================================================================
+// Mistake Limit Stop Message (pure helper — ported verbatim)
+// =============================================================================
+
+export function buildMistakeLimitStopMessage(input: {
+	iteration: number;
+	consecutiveMistakes: number;
+	maxConsecutiveMistakes: number;
+	reason:
+		| "api_error"
+		| "invalid_tool_call"
+		| "completion_without_submit"
+		| "tool_execution_failed";
+	details?: string;
+	stopReason?: string;
+}): string {
+	const parts = [
+		`Stopped after ${input.consecutiveMistakes}/${input.maxConsecutiveMistakes} consecutive mistakes (${input.reason}) at iteration ${input.iteration}.`,
+	];
+	const details = input.details?.trim();
+	if (details) {
+		parts.push(`Error: ${details}`);
+	}
+	const stopReason = input.stopReason?.trim();
+	if (stopReason) {
+		parts.push(`Decision: ${stopReason}`);
+	}
+	parts.push(
+		"Session state was preserved. Send a new prompt to resume from the latest state.",
+	);
+	return parts.join(" ");
+}
+
+// =============================================================================
+// Consecutive Mistake Decision Resolution (pure helper — ported verbatim)
+// =============================================================================
+
+async function resolveConsecutiveMistakeDecision(
+	input: ConsecutiveMistakeLimitContext,
+	callback?: (
+		context: ConsecutiveMistakeLimitContext,
+	) =>
+		| Promise<ConsecutiveMistakeLimitDecision>
+		| ConsecutiveMistakeLimitDecision,
+): Promise<ConsecutiveMistakeLimitDecision> {
+	if (!callback) {
+		return {
+			action: "stop",
+			reason: `maximum consecutive mistakes reached (${input.maxConsecutiveMistakes})`,
+		};
+	}
+	try {
+		return await callback(input);
+	} catch (error) {
+		return {
+			action: "stop",
+			reason:
+				error instanceof Error
+					? error.message
+					: `maximum consecutive mistakes reached (${input.maxConsecutiveMistakes})`,
+		};
+	}
+}
+
+// TODO(PLAN.md Step 8): The `emit` channel currently accepts legacy `AgentEvent`
+// so the "recoverable error" event shape is preserved verbatim. When
+// `SessionRuntime` wires this up in Step 8, consider whether this should
+// emit an `AgentRuntimeEvent` (per the §3.2.3 signature proposal) and let
+// the bridge translate, or keep the direct legacy channel for notice parity.

package/src/runtime/runtime-builder.ts

@@ -1,6 +1,11 @@
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import type { BasicLogger, TeamTeammateSpec, Tool } from "@clinebot/shared";
+import type {
+	BasicLogger,
+	RuntimeConfigExtensionKind,
+	TeamTeammateSpec,
+	Tool,
+} from "@clinebot/shared";
 import { resolveSkillsConfigSearchPaths } from "@clinebot/shared/storage";
 import { nanoid } from "nanoid";
 import {
@@ -55,6 +60,19 @@ type SkillsExecutorWithMetadata = SkillsExecutor & {
 	configuredSkills?: SkillsExecutorMetadataItem[];
 };
 
+const ALL_CONFIG_EXTENSIONS: readonly RuntimeConfigExtensionKind[] = [
+	"rules",
+	"skills",
+	"plugins",
+];
+
+function hasConfigExtension(
+	extensions: ReadonlyArray<RuntimeConfigExtensionKind> | undefined,
+	kind: RuntimeConfigExtensionKind,
+): boolean {
+	return new Set(extensions ?? ALL_CONFIG_EXTENSIONS).has(kind);
+}
+
 function isToolEnabledByPolicies(
 	toolName: string,
 	toolPolicies: CoreSessionConfig["toolPolicies"],
@@ -423,6 +441,28 @@ function shutdownTeamRuntime(
 	}
 }
 
+function isRuntimeLifecycleShutdownReason(reason: string | undefined): boolean {
+	if (reason === undefined) {
+		return true;
+	}
+	switch (reason) {
+		case "session_stop":
+		case "session_complete":
+		case "session_error":
+		case "session_manager_dispose":
+		case "cli_run_shutdown":
+		case "cli_interactive_shutdown":
+		case "cli_interactive_startup_cancelled":
+		case "provider_change":
+		case "acp_shutdown":
+		case "hub_server_stop":
+		case "vscode_webview_dispose":
+			return true;
+		default:
+			return false;
+	}
+}
+
 function normalizeConfig(
 	config: CoreSessionConfig,
 ): Required<
@@ -485,6 +525,7 @@ export class DefaultRuntimeBuilder implements RuntimeBuilder {
 			createSpawnTool,
 			onTeamRestored,
 			userInstructionWatcher: sharedUserInstructionWatcher,
+			configExtensions,
 			defaultToolExecutors,
 		} = input;
 		const onTeamEvent = input.onTeamEvent ?? (() => {});
@@ -493,7 +534,8 @@ export class DefaultRuntimeBuilder implements RuntimeBuilder {
 		const tools: Tool[] = [];
 		const effectiveTeamName = config.teamName?.trim() || createTeamName();
 		const teamStoreKey = config.sessionId?.trim() || effectiveTeamName;
-		const hasLocalSkills = hasSkillsFiles(config.cwd);
+		const skillsEnabled = hasConfigExtension(configExtensions, "skills");
+		const hasLocalSkills = skillsEnabled && hasSkillsFiles(config.cwd);
 		let teamToolsRegistered = false;
 		const watcherProvided = Boolean(sharedUserInstructionWatcher);
 		let userInstructionWatcher = sharedUserInstructionWatcher;
@@ -501,7 +543,12 @@ export class DefaultRuntimeBuilder implements RuntimeBuilder {
 		let skillsExecutor: SkillsExecutorWithMetadata | undefined;
 		let mcpShutdown: (() => Promise<void>) | undefined;
 
-		if (!userInstructionWatcher && normalized.enableTools && hasLocalSkills) {
+		if (
+			!userInstructionWatcher &&
+			normalized.enableTools &&
+			skillsEnabled &&
+			hasLocalSkills
+		) {
 			userInstructionWatcher = createUserInstructionConfigWatcher({
 				skills: { workspacePath: config.cwd },
 				rules: { workspacePath: config.cwd },
@@ -512,6 +559,7 @@ export class DefaultRuntimeBuilder implements RuntimeBuilder {
 
 		if (
 			normalized.enableTools &&
+			skillsEnabled &&
 			userInstructionWatcher &&
 			(watcherProvided ||
 				hasLocalSkills ||
@@ -561,6 +609,7 @@ export class DefaultRuntimeBuilder implements RuntimeBuilder {
 			  }
 			| undefined;
 		let pendingLeadTeamTools: Tool[] = [];
+		let restoredStateHydratedIntoRuntime = false;
 		const delegatedAgentConfigProvider = createDelegatedAgentConfigProvider({
 			providerId: config.providerId,
 			modelId: config.modelId,
@@ -616,7 +665,10 @@ export class DefaultRuntimeBuilder implements RuntimeBuilder {
 								};
 								teammateSpecs.set(spec.agentId, spec);
 							}
-							if (event.type === "teammate_shutdown") {
+							if (
+								event.type === "teammate_shutdown" &&
+								!isRuntimeLifecycleShutdownReason(event.reason)
+							) {
 								teammateSpecs.delete(event.agentId);
 							}
 							teamStore.handleTeamEvent(teamStoreKey, event);
@@ -630,7 +682,7 @@ export class DefaultRuntimeBuilder implements RuntimeBuilder {
 				});
 				if (restoredTeamState) {
 					teamRuntime.hydrateState(restoredTeamState);
-					teamRuntime.markStaleRunsInterrupted("runtime_recovered");
+					restoredStateHydratedIntoRuntime = true;
 				}
 				registryEntry.runtime = teamRuntime;
 			}
@@ -668,6 +720,10 @@ export class DefaultRuntimeBuilder implements RuntimeBuilder {
 					teammateConfigProvider: delegatedAgentConfigProvider,
 				});
 
+				if (restoredStateHydratedIntoRuntime) {
+					teamRuntime.recoverActiveRuns("runtime_recovered");
+				}
+
 				if (teamBootstrap.restoredFromPersistence) {
 					onTeamRestored?.();
 				}