@clinebot/core 0.0.35 → 0.0.37

package/src/runtime/agent-runtime-config-builder.ts

@@ -0,0 +1,205 @@
+/**
+ * Build an `AgentRuntimeConfig` from an `AgentConfig` plus session-owned
+ * supporting objects (model handler, tools, hooks, plugins, telemetry).
+ *
+ * @see PLAN.md §3.1 — new file introduced alongside the core runtime port.
+ * @see PLAN.md §3.2.1 — field-by-field mapping.
+ *
+ * Implemented in Step 8c. The function is intentionally **pure** — it
+ * does not create handlers or tools itself; it receives them already
+ * adapted (via `agent-config-adapter.ts`) from the caller
+ * (`SessionRuntime`) and wires them into an `AgentRuntimeConfig`.
+ *
+ * Fields that do **not** round-trip into `AgentRuntimeConfig`
+ * (e.g. `execution.maxConsecutiveMistakes`,
+ * `execution.loopDetection`, `hookPolicies`) are
+ * consumed by `SessionRuntime` / `MistakeTracker` /
+ * `LoopDetectionTracker` — not passed through here. See §3.2.1's
+ * "Fields with no corresponding AgentRuntimeConfig slot" note.
+ */
+
+import type {
+	AgentConfig,
+	AgentMessage,
+	AgentModel,
+	AgentRuntimeConfig,
+	AgentRuntimePlugin,
+	AgentTelemetry,
+	AgentTool,
+	BasicLogger,
+} from "@clinebot/shared";
+import type { HookBridge } from "../hooks/hook-bridge";
+
+/**
+ * Inputs required to assemble an `AgentRuntimeConfig`. Distinct from
+ * `AgentConfig` because some of these (the model adapter, the hook
+ * bridge's runtime-hooks bag, a resolved plugin list) can only be
+ * produced inside `SessionRuntime`.
+ */
+export interface CreateAgentRuntimeConfigInput {
+	readonly agentConfig: AgentConfig;
+	/**
+	 * Core/hub runtime session identifier used for host lifecycle operations,
+	 * event routing, persistence, and approval delivery.
+	 */
+	readonly sessionId?: string;
+	readonly agentId: string;
+	/**
+	 * Agent conversation/transcript identifier used by tools, hooks, telemetry,
+	 * and model history correlation.
+	 */
+	readonly conversationId?: string;
+	readonly parentAgentId?: string;
+	/** The role label for teammates (`AgentConfig.role` in sub-agent configs). */
+	readonly agentRole?: string;
+	/** Pre-built model adapter (produced by `apiHandlerToAgentModel`). */
+	readonly model: AgentModel;
+	readonly logger?: BasicLogger;
+	readonly telemetry?: AgentTelemetry;
+	/** Pre-built tool array (builtins + plugin-contributed + session extras). */
+	readonly tools?: readonly AgentTool<unknown, unknown>[];
+	/** Pre-resolved plugin list from the plugin loader. */
+	readonly plugins?: readonly AgentRuntimePlugin[];
+	/**
+	 * Optional hook bridge. When provided, `AgentRuntimeConfig.hooks`
+	 * is populated from `hookBridge.toRuntimeHooks()`. Omit for
+	 * runtimes that do not need hook dispatch (e.g. unit tests).
+	 */
+	readonly hookBridge?: HookBridge;
+	/** Seed messages (usually `session.conversation.getMessages()`). */
+	readonly initialMessages?: readonly AgentMessage[];
+	/**
+	 * Override for `AgentRuntimeConfig.systemPrompt` — useful when
+	 * the caller has composed additional guidance (e.g. via
+	 * `LocalRuntimeHost.composeSystemPrompt`). Defaults to
+	 * `agentConfig.systemPrompt`.
+	 */
+	readonly systemPrompt?: string;
+}
+
+/**
+ * Produce an `AgentRuntimeConfig` per PLAN.md §3.2.1 mapping.
+ */
+export function createAgentRuntimeConfig(
+	input: CreateAgentRuntimeConfigInput,
+): AgentRuntimeConfig {
+	const { agentConfig } = input;
+
+	const modelOptions = buildModelOptions(agentConfig);
+	const messageModelInfo = buildMessageModelInfo(agentConfig);
+	const hooks = input.hookBridge?.toRuntimeHooks();
+	const toolExecution = resolveToolExecution(agentConfig.maxParallelToolCalls);
+
+	const config: AgentRuntimeConfig = {
+		sessionId: input.sessionId ?? agentConfig.sessionId,
+		agentId: input.agentId,
+		conversationId: input.conversationId,
+		agentRole: input.agentRole,
+		systemPrompt: input.systemPrompt ?? agentConfig.systemPrompt,
+		messageModelInfo,
+		model: input.model,
+		modelOptions,
+		tools: input.tools,
+		hooks,
+		plugins: input.plugins,
+		logger: input.logger ?? agentConfig.logger,
+		telemetry: input.telemetry ?? mapTelemetry(agentConfig.telemetry),
+		initialMessages: input.initialMessages,
+		maxIterations: agentConfig.maxIterations,
+		toolExecution,
+		toolPolicies: agentConfig.toolPolicies,
+		requestToolApproval: agentConfig.requestToolApproval,
+	};
+
+	return config;
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/**
+ * Collect the provider-/reasoning-related fields from `AgentConfig`
+ * into `AgentRuntimeConfig.modelOptions`. Kept undefined when every
+ * field is undefined so the runtime does not receive an empty object.
+ */
+export function buildModelOptions(
+	config: AgentConfig,
+): Record<string, unknown> | undefined {
+	const options: Record<string, unknown> = {};
+	if (config.thinking !== undefined) {
+		options.thinking = config.thinking;
+	}
+	if (config.reasoningEffort !== undefined) {
+		options.reasoningEffort = config.reasoningEffort;
+	}
+	if (config.thinkingBudgetTokens !== undefined) {
+		options.thinkingBudgetTokens = config.thinkingBudgetTokens;
+	}
+	if (config.maxTokensPerTurn !== undefined) {
+		options.maxTokensPerTurn = config.maxTokensPerTurn;
+	}
+	if (config.apiTimeoutMs !== undefined) {
+		options.apiTimeoutMs = config.apiTimeoutMs;
+	}
+	return Object.keys(options).length > 0 ? options : undefined;
+}
+
+/**
+ * Compose `messageModelInfo` from the provider-related fields per
+ * §3.2.1: `{ id: modelId, provider: providerId, family:
+ * providerConfig?.family }`.
+ */
+export function buildMessageModelInfo(
+	config: AgentConfig,
+): AgentMessage["modelInfo"] {
+	const family = (config.providerConfig as { family?: string } | undefined)
+		?.family;
+	return {
+		id: config.modelId,
+		provider: config.providerId,
+		family,
+	};
+}
+
+/**
+ * `"parallel"` when `maxParallelToolCalls ≥ 2`, `"sequential"` when
+ * `1`, `undefined` when the caller did not specify.
+ */
+export function resolveToolExecution(
+	maxParallelToolCalls: number | undefined,
+): "sequential" | "parallel" | undefined {
+	if (maxParallelToolCalls === undefined) {
+		return undefined;
+	}
+	return maxParallelToolCalls >= 2 ? "parallel" : "sequential";
+}
+
+/**
+ * Adapt the full `ITelemetryService` to the minimal `AgentTelemetry`
+ * shape. The runtime only calls `capture(event, properties)`; the
+ * remaining methods are host concerns and stay on the
+ * `ITelemetryService` instance owned by `SessionRuntime`.
+ */
+export function mapTelemetry(
+	telemetry: AgentConfig["telemetry"],
+): AgentTelemetry | undefined {
+	if (!telemetry) {
+		return undefined;
+	}
+	return {
+		capture: (event, properties) => {
+			// The runtime's `AgentTelemetry.capture` signature uses
+			// `Record<string, unknown>`, which is wider than
+			// `TelemetryProperties`. We cast at the boundary — any
+			// non-telemetry-compatible values are ignored by the
+			// underlying service.
+			telemetry.capture({
+				event,
+				properties: properties as
+					| Parameters<typeof telemetry.capture>[0]["properties"]
+					| undefined,
+			});
+		},
+	};
+}

package/src/runtime/error-feedback.ts

@@ -0,0 +1,142 @@
+/**
+ * Pure error-classification and tool-call-feedback helpers.
+ *
+ * @see PLAN.md §3.1 — moved from `packages/agents/src/api/error-handling.ts` lines 20–145.
+ *
+ * Consumed by `SessionRuntime` (and `MistakeTracker`) when composing
+ * follow-up turns after API failures or invalid tool calls.
+ */
+
+import type * as LlmsProviders from "@clinebot/llms";
+import type { ToolCallRecord } from "@clinebot/shared";
+
+// =============================================================================
+// API Error Classification
+// =============================================================================
+
+const NON_RECOVERABLE_STATUS_CODES = [
+	400, 401, 402, 403, 404, 405, 406, 409, 410, 429,
+];
+
+const NON_RECOVERABLE_PHRASES = [
+	"not found",
+	"unsupported for",
+	"missing api key",
+	"invalid api key",
+	"authentication",
+	"unauthorized",
+	"forbidden",
+	"overloaded",
+	"insufficient balance",
+];
+
+export function isNonRecoverableApiError(error: Error): boolean {
+	const message = error.message.toLowerCase();
+
+	if (
+		NON_RECOVERABLE_STATUS_CODES.some((code) =>
+			new RegExp(`(?:\\b|\\"code\\"\\s*:\\s*)${code}(?:\\b|\\s)`).test(message),
+		)
+	) {
+		return true;
+	}
+
+	if (NON_RECOVERABLE_PHRASES.some((s) => message.includes(s))) {
+		return true;
+	}
+
+	return false;
+}
+
+// =============================================================================
+// Invalid Tool Call Feedback
+// =============================================================================
+
+export interface InvalidToolCall {
+	id: string;
+	name?: string;
+	input?: unknown;
+	reason: "missing_name" | "missing_arguments" | "invalid_arguments";
+}
+
+function extractParseError(input: unknown): string | undefined {
+	if (
+		input &&
+		typeof input === "object" &&
+		!Array.isArray(input) &&
+		typeof (input as { parse_error?: unknown }).parse_error === "string"
+	) {
+		return (input as { parse_error: string }).parse_error;
+	}
+	return undefined;
+}
+
+export function buildInvalidToolCallFeedback(
+	invalidToolCalls: readonly InvalidToolCall[],
+): string {
+	const details = invalidToolCalls
+		.map((call) => {
+			const name = call.name?.trim() || "(unknown tool)";
+			const parseError = extractParseError(call.input);
+			const reason =
+				call.reason === "missing_name"
+					? "missing tool name"
+					: call.reason === "missing_arguments"
+						? "missing arguments"
+						: (parseError ?? "arguments could not be parsed as JSON");
+			return `${name} [${call.id}]: ${reason}`;
+		})
+		.join("; ");
+	return `One or more tool calls were invalid or missing required parameters (${details}). Retry with valid tool names and arguments.`;
+}
+
+export function buildInvalidToolResultMessage(
+	invalidToolCalls: readonly InvalidToolCall[],
+): LlmsProviders.Message {
+	return {
+		role: "user",
+		content: invalidToolCalls.map((call) => ({
+			type: "tool_result" as const,
+			tool_use_id: call.id,
+			content: JSON.stringify({
+				toolName: call.name?.trim() || "(unknown tool)",
+				query: call.input ?? {},
+				result: "",
+				error:
+					call.reason === "missing_name"
+						? "Tool call was missing a tool name"
+						: call.reason === "missing_arguments"
+							? "Tool call was missing required arguments"
+							: (extractParseError(call.input) ??
+								"Tool call arguments could not be parsed as JSON"),
+				success: false,
+			}),
+			is_error: true,
+		})),
+	};
+}
+
+// =============================================================================
+// Failed Tool Call Feedback
+// =============================================================================
+
+export function buildFailedToolCallFeedback(
+	toolResults: readonly ToolCallRecord[],
+): string {
+	const failed = toolResults.filter((record) => !!record.error);
+	if (failed.length === 0) {
+		return "";
+	}
+	const details = failed
+		.slice(0, 3)
+		.map((record) => {
+			const message = String(record.error ?? "unknown tool error")
+				.replace(/\s+/g, " ")
+				.trim();
+			return `${record.name}: ${message}`;
+		})
+		.join("; ");
+	return failed.length > 3
+		? `${details}; +${failed.length - 3} more failed tool call(s)`
+		: details;
+}

package/src/runtime/history.ts

@@ -1,5 +1,10 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
 import type * as LlmsProviders from "@clinebot/llms";
 import { formatDisplayUserInput, normalizeUserInput } from "@clinebot/shared";
+import { resolveSessionDataDir } from "@clinebot/shared/storage";
+import type { SessionManifest } from "../session/session-manifest";
+import { SessionManifestSchema } from "../session/session-manifest";
 import type {
 	SessionHistoryMetadata,
 	SessionHistoryRecord,
@@ -7,6 +12,12 @@ import type {
 } from "../types/sessions";
 import type { RuntimeHost } from "./runtime-host";
 
+export interface SessionHistoryListOptions {
+	limit?: number;
+	includeManifestFallback?: boolean;
+	hydrate?: boolean;
+}
+
 type StoredSessionMessage = LlmsProviders.Message & {
 	metrics?: {
 		cost?: number;
@@ -51,6 +62,103 @@ function asHistoryMetadata(value: unknown): SessionHistoryMetadata | undefined {
 	return { ...(value as Record<string, unknown>) };
 }
 
+function normalizeHistoryLimit(limit: number | undefined): number {
+	const value = limit ?? 200;
+	return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 200;
+}
+
+function extractSessionRecencyToken(sessionId: string): number {
+	const matches = sessionId.match(/\d{13,}/g);
+	if (!matches || matches.length === 0) {
+		return 0;
+	}
+	let best = 0;
+	for (const match of matches) {
+		const value = Number.parseInt(match, 10);
+		if (Number.isFinite(value) && value > best) {
+			best = value;
+		}
+	}
+	return best;
+}
+
+function manifestToSessionRecord(manifest: SessionManifest): SessionRecord {
+	return {
+		sessionId: manifest.session_id,
+		source: manifest.source,
+		pid: manifest.pid,
+		startedAt: manifest.started_at,
+		endedAt: manifest.ended_at ?? null,
+		exitCode: manifest.exit_code ?? null,
+		status: manifest.status,
+		interactive: manifest.interactive,
+		provider: manifest.provider,
+		model: manifest.model,
+		cwd: manifest.cwd,
+		workspaceRoot: manifest.workspace_root,
+		teamName: manifest.team_name,
+		enableTools: manifest.enable_tools,
+		enableSpawn: manifest.enable_spawn,
+		enableTeams: manifest.enable_teams,
+		isSubagent: false,
+		prompt: manifest.prompt,
+		metadata: manifest.metadata,
+		messagesPath: manifest.messages_path,
+		updatedAt: manifest.ended_at ?? manifest.started_at,
+	};
+}
+
+async function listManifestHistoryRows(
+	limit: number,
+): Promise<SessionRecord[]> {
+	const requestedLimit = normalizeHistoryLimit(limit);
+	const sessionsDir = resolveSessionDataDir();
+	const entries = await readdir(sessionsDir, { withFileTypes: true }).catch(
+		() => [],
+	);
+	const candidateEntries = entries
+		.filter((entry) => entry.isDirectory())
+		.map((entry) => ({
+			entry,
+			recency: extractSessionRecencyToken(entry.name.trim()),
+		}))
+		.sort(
+			(left, right) =>
+				right.recency - left.recency ||
+				right.entry.name.localeCompare(left.entry.name),
+		)
+		.slice(0, requestedLimit);
+	const rows = await Promise.all(
+		candidateEntries.map(async ({ entry }) => {
+			const sessionId = entry.name.trim();
+			if (!sessionId) {
+				return undefined;
+			}
+			const manifestPath = join(sessionsDir, sessionId, `${sessionId}.json`);
+			const raw = await readFile(manifestPath, "utf8").catch(() => undefined);
+			if (!raw) {
+				return undefined;
+			}
+			let parsedJson: unknown;
+			try {
+				parsedJson = JSON.parse(raw) as unknown;
+			} catch {
+				return undefined;
+			}
+			const parsedManifest = SessionManifestSchema.safeParse(parsedJson);
+			if (!parsedManifest.success) {
+				return undefined;
+			}
+			return manifestToSessionRecord(parsedManifest.data);
+		}),
+	);
+
+	return rows
+		.filter((row): row is SessionRecord => Boolean(row))
+		.sort((left, right) => right.startedAt.localeCompare(left.startedAt))
+		.slice(0, requestedLimit);
+}
+
 function extractTextFromContent(
 	content: LlmsProviders.Message["content"],
 ): string {
@@ -235,3 +343,32 @@ export async function hydrateSessionHistory(
 		}),
 	);
 }
+
+export async function listSessionHistory(
+	host: Pick<RuntimeHost, "list" | "readMessages">,
+	options: SessionHistoryListOptions = {},
+): Promise<SessionHistoryRecord[]> {
+	const limit = normalizeHistoryLimit(options.limit);
+	const backendRows = (await host.list(limit)).slice(0, limit);
+	const manifestRows =
+		options.includeManifestFallback === true && backendRows.length < limit
+			? await listManifestHistoryRows(Math.min(Math.max(limit * 2, 100), 500))
+			: [];
+	const merged = new Map<string, SessionRecord>();
+	for (const row of [...backendRows, ...manifestRows]) {
+		if (merged.has(row.sessionId)) {
+			continue;
+		}
+		merged.set(row.sessionId, row);
+	}
+	const rows =
+		manifestRows.length === 0
+			? backendRows
+			: Array.from(merged.values())
+					.sort((left, right) => right.startedAt.localeCompare(left.startedAt))
+					.slice(0, limit);
+	if (options.hydrate === false) {
+		return rows.map((row) => normalizeHistoryRow(row));
+	}
+	return await hydrateSessionHistory(host, rows);
+}