pi-crew 0.9.53 → 0.9.55

package/src/extension/registration/registration-types.ts

@@ -0,0 +1,158 @@
+/**
+ * Shared types for the registration modules under `src/extension/registration/`.
+ *
+ * The orchestrator (`src/extension/register.ts`) builds a single mutable
+ * `RegistrationContext` object once and threads it through each install
+ * function. This avoids passing 20+ parameters to every module and keeps
+ * the orchestrator's mutable state in one place where each module can read
+ * it without ceremony.
+ *
+ * Every field is described inline so refactors can keep the contract
+ * observable. If you add a new dependency here, document it; future
+ * contributors will look at this file to discover the seam between the
+ * orchestrator and its extracted modules.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { BatchBarrier } from "../../runtime/batch-barrier.ts";
+import type { createManifestCache } from "../../runtime/manifest-cache.ts";
+import type { CrewScheduler } from "../../runtime/scheduler.ts";
+import type { SubagentManager } from "../../subagents/manager.ts";
+import type { RenderScheduler } from "../../ui/render-scheduler.ts";
+import type { createRunSnapshotCache } from "../../ui/run-snapshot-cache.ts";
+import type { TerminalStatusController } from "../../ui/terminal-status.ts";
+import type { CrewWidgetState } from "../../ui/widget/index.ts";
+import type { RunWatcherRegistry } from "../../utils/run-watcher-registry.ts";
+import type { AsyncNotifierState } from "../async-notifier.ts";
+import type { PiCrewRpcHandle } from "../cross-extension-rpc.ts";
+import type { NotificationDescriptor } from "../notification-router.ts";
+import type { CrashRecoveryCache } from "./crash-recovery-cache.ts";
+import type { LifecycleState } from "./lifecycle.ts";
+import type { ObservabilityState } from "./observability.ts";
+import type { UiState } from "./ui.ts";
+
+/** Foreground team-run & subagent abort controllers. */
+export type AbortKey = string | symbol;
+export type AbortControllerMap = Map<AbortKey, AbortController>;
+
+/**
+ * Single auto-recovery cooldown gate entry. Tracked by the render-tick
+ * health notifier so the same warning doesn't fire repeatedly within a
+ * 5-minute cooldown. Uses LRU-like semantics — see register.ts.
+ */
+export interface AutoRecoveryEntry {
+	insertedAt: number;
+	lastAccessAt: number;
+}
+
+/**
+ * Mutable context bag passed from the orchestrator to every
+ * registration module. Treat as a shared object: modules read
+ * `ctx.X` to consume orchestrator state and may write back to
+ * fields like `ctx.currentCtx` to keep it fresh.
+ *
+ * Splitting this into many interfaces would buy little — the
+ * modules genuinely share this state, and TypeScript's structural
+ * typing means each module only sees the fields it imports.
+ */
+export interface RegistrationContext {
+	pi: ExtensionAPI;
+
+	// ── Mutable session/runtime state ──────────────────────────────────
+	/** Current ExtensionContext (set on session_start, cleared on cleanup). */
+	currentCtx: ExtensionContext | undefined;
+	/** Bumped on session_start + cleanup. Owner tokens compare against this. */
+	sessionGeneration: number;
+	/** Idempotency flag for cleanup. */
+	cleanedUp: boolean;
+	/** Active RPC handle (set once at registration, cleared on cleanup). */
+	rpcHandle: PiCrewRpcHandle | undefined;
+
+	// ── Caches (per-cwd, lazily swapped) ────────────────────────────────
+	manifestCache: ReturnType<typeof createManifestCache>;
+	runSnapshotCache: ReturnType<typeof createRunSnapshotCache>;
+	cacheCwd: string;
+	getManifestCache: (cwd: string) => ReturnType<typeof createManifestCache>;
+	getRunSnapshotCache: (cwd: string) => ReturnType<typeof createRunSnapshotCache>;
+
+	// ── UI / widget state ──────────────────────────────────────────────
+	widgetState: CrewWidgetState;
+	uiState: UiState;
+
+	// ── Observability + lifecycle state ────────────────────────────────
+	observabilityState: ObservabilityState;
+	lifecycleState: LifecycleState;
+
+	// ── Async notifier ─────────────────────────────────────────────────
+	notifierState: AsyncNotifierState;
+
+	// ── Abort controllers ──────────────────────────────────────────────
+	foregroundControllers: AbortControllerMap;
+	foregroundTeamRunControllers: AbortControllerMap;
+
+	// ── Render & terminal state ────────────────────────────────────────
+	renderScheduler: RenderScheduler | undefined;
+	renderSchedulerUnsubscribers: Array<() => void>;
+	terminalStatus: TerminalStatusController | undefined;
+	terminalStatusActive: boolean;
+
+	// ── Scheduler + watch timers ───────────────────────────────────────
+	crewScheduler: CrewScheduler | undefined;
+	preloadTimer: ReturnType<typeof setTimeout> | undefined;
+	crewRunWatchers: RunWatcherRegistry | undefined;
+	userCrewWatchers: RunWatcherRegistry | undefined;
+
+	// ── Subagents + batching ───────────────────────────────────────────
+	subagentManager: SubagentManager;
+	batchBarrier: BatchBarrier;
+
+	// ── Autocomplete guard (register-once) ─────────────────────────────
+	crewAutocompleteRegistered: boolean;
+
+	// ── Cooldown map for health notifications ──────────────────────────
+	autoRecoveryLast: Map<string, AutoRecoveryEntry>;
+	/** Defensive cap on autoRecoveryLast size (LRU eviction). */
+	AUTO_RECOVERY_LAST_MAX_ENTRIES: number;
+
+	// ── i18n teardown ──────────────────────────────────────────────────
+	disposeI18n: () => void;
+
+	// ── Global store for cross-instance cleanup handoff ────────────────
+	globalStore: Record<string | symbol, unknown>;
+	runtimeCleanupStoreKey: symbol;
+
+	// ── Bound predicates ───────────────────────────────────────────────
+	captureSessionGeneration: () => number;
+	isOwnerSessionCurrent: (ownerGeneration: number | undefined) => boolean;
+	isContextCurrent: (ctx: ExtensionContext, ownerGeneration: number) => boolean;
+	telemetryEnabled: () => boolean;
+
+	// ── Bound notification sink ────────────────────────────────────────
+	notifyOperator: (notification: NotificationDescriptor) => void;
+
+	// ── Bound cleanup + lifecycle methods ──────────────────────────────
+	cleanupSessionResourcesOnly: () => void;
+	cleanupRuntime: () => void;
+	disposeRenderSchedulerSubscriptions: () => void;
+	stopSessionBoundSubagents: () => void;
+
+	// ── Bound helpers (configure* lazily install lifecycle/observability) ──
+	configureNotifications: (ctx: ExtensionContext) => void;
+	configureObservability: (ctx: ExtensionContext) => void;
+	configureDeliveryCoordinator: () => void;
+	importCrashRecovery: () => Promise<CrashRecoveryCache>;
+	purgeStaleActiveRunIndexSyncIfLoaded: () => void;
+
+	// ── Foreground helpers (consumed by tools + commands) ─────────────
+	startForegroundRun: (ctx: ExtensionContext, runner: (signal?: AbortSignal) => Promise<void>, runId?: string) => void;
+	abortForegroundRun: (runId: string) => boolean;
+	openLiveSidebar: (ctx: ExtensionContext, runId: string) => void;
+	/**
+	 * Phase 0 inter-pi broker lifecycle controller. Set by `register.ts`
+	 * after `installSessionLifecycleHandlers`. The controller is a no-op
+	 * when the broker is disabled or the current process is a subagent;
+	 * callers (e.g. child-pi-spawn consumers) MUST handle the case where
+	 * `issueForChild` returns undefined. The controller is stopped
+	 * during session_shutdown via `stop()`.
+	 */
+	brokerController: import("./lifecycle-handlers.ts").CrewBrokerLifecycleController | undefined;
+}

package/src/extension/registration/runtime-cleanup.ts

@@ -0,0 +1,230 @@
+/**
+ * Runtime cleanup installer for pi-crew.
+ *
+ * Owns the two cleanup functions used at session boundaries:
+ *   • `cleanupRuntime` — full shutdown. Aborts foreground team runs,
+ *     stops scheduler, disposes all caches, disposes notifier, etc.
+ *   • `cleanupSessionResourcesOnly` — session switch (resume/new/fork).
+ *     Same as above but does NOT abort foreground team runs — they share
+ *     the process with the session and clean up naturally when the
+ *     ExtensionContext tears down.
+ *
+ * Both also handle the global-runtime-handoff symbol: if a previous
+ * pi-crew instance left a cleanup handler in `globalStore[runtimeCleanupStoreKey]`,
+ * it is fired-and-forgotten before we install our own.
+ *
+ * Other bounded helpers used by these functions (stopSessionBoundSubagents,
+ * disposeRenderSchedulerSubscriptions) are co-located here because they
+ * belong to the same lifecycle phase.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../../config/config.ts";
+import { clearHooksScoped } from "../../hooks/registry.ts";
+import { terminateActiveChildPiProcesses } from "../../subagents/spawn.ts";
+import { clearPiCrewPowerbar, disposePowerbarCoalescer } from "../../ui/powerbar-publisher.ts";
+import { stopCrewWidget } from "../../ui/widget/index.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { clearProjectRootCache } from "../../utils/paths.ts";
+import { stopAsyncRunNotifier } from "../async-notifier.ts";
+import { uninstallCrewGlobalRegistry } from "../team-tool.ts";
+import { disposeNotifications } from "./lifecycle.ts";
+import { disposeObservability } from "./observability.ts";
+import type { RegistrationContext } from "./registration-types.ts";
+
+/**
+ * Install both cleanup functions into the registration context AND wire
+ * the global handoff symbol so a previous instance's cleanup runs first.
+ */
+export function installRuntimeCleanup(_pi: ExtensionAPI, ctx: RegistrationContext): void {
+	// Best-effort cleanup of the previous runtime instance. Errors are logged but
+	// do not halt new registration — a failing cleanup from a prior instance is
+	// preferable to leaving pi-crew unregistered, and any stale state from the
+	// previous instance will be reconciled when the new instance initializes.
+	const previousRuntimeCleanup = ctx.globalStore[ctx.runtimeCleanupStoreKey];
+	if (typeof previousRuntimeCleanup === "function") {
+		try {
+			previousRuntimeCleanup();
+		} catch (error) {
+			logInternalError("register.prev-cleanup", error);
+		}
+	}
+
+	ctx.cleanupSessionResourcesOnly = buildCleanupSessionResourcesOnly(ctx);
+	ctx.cleanupRuntime = buildCleanupRuntime(ctx);
+	ctx.disposeRenderSchedulerSubscriptions = buildDisposeRenderSchedulerSubscriptions(ctx);
+	ctx.stopSessionBoundSubagents = buildStopSessionBoundSubagents(ctx);
+
+	ctx.globalStore[ctx.runtimeCleanupStoreKey] = ctx.cleanupRuntime;
+}
+
+/**
+ * Build a cleanup function for session-switch events. Same teardown as
+ * cleanupRuntime except foreground team-run controllers are NOT aborted.
+ */
+function buildCleanupSessionResourcesOnly(ctx: RegistrationContext): () => void {
+	return (): void => {
+		if (ctx.cleanedUp) return;
+		ctx.cleanedUp = true;
+		if (ctx.preloadTimer) {
+			clearTimeout(ctx.preloadTimer);
+			ctx.preloadTimer = undefined;
+		}
+		ctx.crewRunWatchers?.closeAll();
+		ctx.crewRunWatchers = undefined;
+		ctx.userCrewWatchers?.closeAll();
+		ctx.userCrewWatchers = undefined;
+		ctx.stopSessionBoundSubagents();
+		// P0 fix: Do NOT abort foreground team runs on session switch.
+		// Foreground team runs run in the same process as the session; they naturally clean up
+		// when the session context is torn down. Only subagents need explicit abort on switch.
+		// Foreground runs will be aborted by cleanupRuntime() during actual session shutdown.
+		ctx.crewScheduler?.stop();
+		stopAsyncRunNotifier(ctx.notifierState);
+
+		// P0: Purge all stale active-run-index entries on session cleanup.
+		ctx.purgeStaleActiveRunIndexSyncIfLoaded();
+
+		stopCrewWidget(ctx.currentCtx, ctx.widgetState, ctx.currentCtx ? loadConfig(ctx.currentCtx.cwd).config.ui : undefined);
+		clearPiCrewPowerbar(ctx.pi.events);
+		disposePowerbarCoalescer();
+		void disposeObservability(ctx.observabilityState, ctx.cleanedUp);
+		ctx.lifecycleState.deliveryCoordinator?.dispose();
+		clearHooksScoped();
+		uninstallCrewGlobalRegistry();
+		ctx.lifecycleState.overflowTracker?.dispose();
+		ctx.lifecycleState.deliveryCoordinator = undefined;
+		ctx.lifecycleState.overflowTracker = undefined;
+		ctx.manifestCache.dispose();
+		ctx.runSnapshotCache.dispose?.();
+		clearProjectRootCache();
+		ctx.renderScheduler?.dispose();
+		ctx.renderScheduler = undefined;
+		ctx.autoRecoveryLast.clear();
+		disposeNotifications(ctx.lifecycleState);
+		ctx.rpcHandle?.unsubscribe();
+		ctx.rpcHandle = undefined;
+		ctx.disposeI18n();
+		ctx.sessionGeneration += 1;
+		ctx.currentCtx = undefined;
+		if (ctx.globalStore[ctx.runtimeCleanupStoreKey] === ctx.cleanupSessionResourcesOnly) {
+			delete ctx.globalStore[ctx.runtimeCleanupStoreKey];
+		}
+	};
+}
+
+/**
+ * Build the full shutdown cleanup. Aborts both subagent controllers AND
+ * foreground team-run controllers.
+ */
+function buildCleanupRuntime(ctx: RegistrationContext): () => void {
+	return (): void => {
+		if (ctx.cleanedUp) return;
+		ctx.cleanedUp = true;
+		if (ctx.preloadTimer) {
+			clearTimeout(ctx.preloadTimer);
+			ctx.preloadTimer = undefined;
+		}
+		ctx.crewRunWatchers?.closeAll();
+		ctx.crewRunWatchers = undefined;
+		ctx.userCrewWatchers?.closeAll();
+		ctx.userCrewWatchers = undefined;
+		ctx.stopSessionBoundSubagents();
+		// P0 fix: also abort foreground team runs on session shutdown (not on session switch).
+		// This is the only place where foreground team run controllers should be aborted.
+		for (const controller of ctx.foregroundTeamRunControllers.values()) controller.abort();
+		ctx.foregroundTeamRunControllers.clear();
+		ctx.crewScheduler?.stop();
+		stopAsyncRunNotifier(ctx.notifierState);
+
+		// Best-effort: kill any async background runners that are still alive.
+		// NOTE: Background runners are designed to outlive the Pi session.
+		// Do NOT kill them on session_shutdown — they manage their own lifecycle.
+		// Only kill foreground child processes (handled above via abort controllers).
+		// See Bug #17: killing async runners on session_shutdown was the root cause
+		// of the "background runner dies at ~35s" bug.
+		// (kill-async block intentionally omitted — see history.)
+
+		// P0: Purge all stale active-run-index entries on session cleanup.
+		// This handles: normal exit, SIGTERM, Ctrl+C — any case where cleanupRuntime fires.
+		// For SIGKILL / crash / SIGHUP (where cleanupRuntime does NOT fire),
+		// purgeStaleActiveRunIndex() runs at next session_start instead.
+		// 2.7: only purge if crash-recovery has been loaded already; otherwise
+		// the next session_start will fire the lazy import + purge.
+		ctx.purgeStaleActiveRunIndexSyncIfLoaded();
+
+		stopCrewWidget(ctx.currentCtx, ctx.widgetState, ctx.currentCtx ? loadConfig(ctx.currentCtx.cwd).config.ui : undefined);
+		clearPiCrewPowerbar(ctx.pi.events);
+		disposePowerbarCoalescer();
+		// H3-L2 split: observability disposal delegated to registration/observability.ts.
+		void disposeObservability(ctx.observabilityState, ctx.cleanedUp);
+		ctx.lifecycleState.deliveryCoordinator?.dispose();
+		clearHooksScoped();
+		uninstallCrewGlobalRegistry();
+		ctx.lifecycleState.overflowTracker?.dispose();
+		ctx.lifecycleState.deliveryCoordinator = undefined;
+		ctx.lifecycleState.overflowTracker = undefined;
+		ctx.manifestCache.dispose();
+		ctx.runSnapshotCache.dispose?.();
+		// 2.10: drop cached findRepoRoot results when the extension reloads.
+		clearProjectRootCache();
+		ctx.renderScheduler?.dispose();
+		ctx.renderScheduler = undefined;
+		ctx.autoRecoveryLast.clear();
+		// H3-L2 split: notification disposal delegated to registration/lifecycle.ts.
+		disposeNotifications(ctx.lifecycleState);
+		ctx.rpcHandle?.unsubscribe();
+		ctx.rpcHandle = undefined;
+		ctx.disposeI18n();
+		ctx.sessionGeneration += 1;
+		ctx.currentCtx = undefined;
+		if (ctx.globalStore[ctx.runtimeCleanupStoreKey] === ctx.cleanupRuntime) {
+			delete ctx.globalStore[ctx.runtimeCleanupStoreKey];
+		}
+	};
+}
+
+/**
+ * Build the dispose-render-scheduler-subscriptions helper. Unsubscribes
+ * every entry in `ctx.renderSchedulerUnsubscribers`, then clears the list.
+ * Errors per-entry are logged but don't abort the loop.
+ */
+function buildDisposeRenderSchedulerSubscriptions(ctx: RegistrationContext): () => void {
+	return (): void => {
+		for (const unsub of ctx.renderSchedulerUnsubscribers.splice(0)) {
+			try {
+				unsub();
+			} catch (error) {
+				logInternalError("register.renderScheduler.unsubscribe", error);
+			}
+		}
+	};
+}
+
+/**
+ * Build the stop-session-bound-subagents helper. Aborts every foreground
+ * subagent controller (NOT foreground team runs — those are owned by the
+ * team-tool, not the subagent manager). Disposes render scheduler,
+ * terminal status, live sidebar, and clears the powerbar.
+ */
+function buildStopSessionBoundSubagents(ctx: RegistrationContext): () => void {
+	return (): void => {
+		// Only abort subagent controllers — NOT foreground team runs.
+		// Foreground team runs are bound to the session lifecycle; they will be aborted
+		// by cleanupRuntime during session_shutdown.
+		for (const controller of ctx.foregroundControllers.values()) controller.abort();
+		ctx.foregroundControllers.clear();
+		ctx.subagentManager.abortAll("Session switching — foreground subagents cancelled.");
+		terminateActiveChildPiProcesses();
+		ctx.disposeRenderSchedulerSubscriptions();
+		ctx.renderScheduler?.dispose();
+		ctx.renderScheduler = undefined;
+		ctx.terminalStatus?.dispose();
+		ctx.terminalStatus = undefined;
+		ctx.terminalStatusActive = false;
+		ctx.uiState.liveSidebarRunId = undefined;
+		if (ctx.currentCtx) {
+			stopCrewWidget(ctx.currentCtx, ctx.widgetState, loadConfig(ctx.currentCtx.cwd).config.ui);
+		}
+		clearPiCrewPowerbar(ctx.pi.events);
+	};
+}

package/src/extension/registration/subagent-helpers.ts

@@ -0,0 +1,125 @@
+import * as fs from "node:fs";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadRunManifestById } from "../../state/state-store.ts";
+import { type SubagentRecord, type SubagentSpawnOptions, savePersistedSubagentRecord } from "../../subagents/manager.ts";
+import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
+
+interface FollowUpCapablePi {
+	sendMessage?: (message: unknown, options?: unknown) => void;
+	sendUserMessage?: (content: string, options?: unknown) => void;
+}
+
+export function sendFollowUp(pi: ExtensionAPI, content: string): void {
+	const api = pi as unknown as FollowUpCapablePi;
+	if (typeof api.sendMessage !== "function") return;
+	api.sendMessage.call(
+		pi,
+		{ customType: "pi-crew-subagent-notification", content, display: true },
+		{ deliverAs: "followUp", triggerTurn: true },
+	);
+}
+
+export function sendAgentWakeUp(pi: ExtensionAPI, content: string): boolean {
+	const api = pi as unknown as FollowUpCapablePi;
+	try {
+		if (typeof api.sendUserMessage === "function") {
+			api.sendUserMessage.call(pi, content, {
+				deliverAs: "followUp",
+				triggerTurn: true,
+			});
+			return true;
+		}
+		if (typeof api.sendMessage === "function") {
+			api.sendMessage.call(
+				pi,
+				{
+					customType: "pi-crew-subagent-wakeup",
+					content,
+					display: true,
+				},
+				{ deliverAs: "followUp", triggerTurn: true },
+			);
+			return true;
+		}
+	} catch {
+		return false;
+	}
+	return false;
+}
+
+export function refreshPersistedSubagentRecord(ctx: ExtensionContext | ExtensionCommandContext, record: SubagentRecord): SubagentRecord {
+	if (!record.runId) return record;
+	const loaded = loadRunManifestById(ctx.cwd, record.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
+	if (!loaded) return record;
+	if (
+		loaded.manifest.status === "completed" ||
+		loaded.manifest.status === "failed" ||
+		loaded.manifest.status === "cancelled" ||
+		loaded.manifest.status === "blocked"
+	) {
+		const refreshed = {
+			...record,
+			status: loaded.manifest.status,
+			error: loaded.manifest.status === "completed" || loaded.manifest.status === "blocked" ? undefined : loaded.manifest.summary,
+			completedAt: loaded.manifest.status === "blocked" ? undefined : (record.completedAt ?? Date.now()),
+		};
+		savePersistedSubagentRecord(ctx.cwd, refreshed);
+		return refreshed;
+	}
+	return record;
+}
+
+export function formatSubagentRecord(record: SubagentRecord): string {
+	const duration = record.completedAt ? `${Math.round((record.completedAt - record.startedAt) / 1000)}s` : "running";
+	return [
+		`Agent: ${record.id}`,
+		`Type: ${record.type}`,
+		`Status: ${record.status}`,
+		record.runId ? `Run: ${record.runId}` : undefined,
+		`Description: ${record.description}`,
+		record.model ? `Model: ${record.model}` : undefined,
+		`Duration: ${duration}`,
+		record.error ? `Error: ${record.error}` : undefined,
+	]
+		.filter((line): line is string => Boolean(line))
+		.join("\n");
+}
+
+export function readSubagentRunResult(ctx: ExtensionContext | ExtensionCommandContext, record: SubagentRecord): string | undefined {
+	if (!record.runId) return record.result;
+	const loaded = loadRunManifestById(ctx.cwd, record.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
+	const task = loaded?.tasks.find((item) => item.resultArtifact) ?? loaded?.tasks[0];
+	const artifactPath = task?.resultArtifact?.path;
+	if (!artifactPath || !loaded) return undefined;
+	try {
+		const safePath = resolveRealContainedPath(loaded.manifest.artifactsRoot, artifactPath);
+		return fs.readFileSync(safePath, "utf-8").trim();
+	} catch {
+		return undefined;
+	}
+}
+
+export function subagentToolResult(text: string, details: Record<string, unknown> = {}, isError = false) {
+	return { content: [{ type: "text" as const, text }], details, isError };
+}
+
+function parseSkillParam(value: unknown): string | string[] | false | undefined {
+	if (value === false) return false;
+	if (typeof value === "string") return value;
+	if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) return value;
+	return undefined;
+}
+
+export function __test__subagentSpawnParams(params: Record<string, unknown>, ctx: Pick<ExtensionContext, "cwd">): SubagentSpawnOptions {
+	return {
+		cwd: ctx.cwd,
+		type: typeof params.subagent_type === "string" && params.subagent_type.trim() ? params.subagent_type.trim() : "executor",
+		description: typeof params.description === "string" && params.description.trim() ? params.description.trim() : "pi-crew subagent",
+		prompt: typeof params.prompt === "string" ? params.prompt : "",
+		background: params.run_in_background === true,
+		model: typeof params.model === "string" && params.model.trim() ? params.model.trim() : undefined,
+		skill: parseSkillParam(params.skill),
+		maxTurns: typeof params.max_turns === "number" && Number.isFinite(params.max_turns) ? params.max_turns : undefined,
+		batchId: typeof params.batch_id === "string" && params.batch_id.trim() ? params.batch_id.trim() : undefined,
+	};
+}