@narumitw/pi-subagents 1.0.0 → 1.0.2

package/src/inspect-registration.ts

@@ -0,0 +1,64 @@
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { cachedModuleLoader, throwIfAborted } from "./cached-module-loader.js";
+import type { SubagentInspectRuntime } from "./inspect.js";
+import { renderInspectCall, renderInspectResult } from "./inspect-render.js";
+import { SubagentInspectParams } from "./inspect-tool.js";
+
+interface InspectExecutionModule {
+	executeSubagentInspect: typeof import("./inspect.js").executeSubagentInspect;
+}
+
+export interface InspectRegistrationDependencies {
+	loadExecution?: () => Promise<InspectExecutionModule>;
+}
+
+export function registerSubagentInspect(
+	pi: ExtensionAPI,
+	runtime: SubagentInspectRuntime,
+	dependencies: InspectRegistrationDependencies = {},
+): void {
+	const loadExecution = cachedModuleLoader(
+		dependencies.loadExecution ?? (() => import("./inspect.js")),
+	);
+	let lifecycleGeneration = 0;
+	pi.on("session_start", () => {
+		lifecycleGeneration += 1;
+	});
+	pi.on("session_shutdown", () => {
+		lifecycleGeneration += 1;
+	});
+	const definition: ToolDefinition<typeof SubagentInspectParams, Record<string, unknown>> = {
+		name: "subagent_inspect",
+		label: "Inspect Subagents",
+		description:
+			"Inspect available subagent definitions, models, retained runs, persisted blocking workflows, runtime status, and diagnostics without changing subagent or workspace state. This tool never starts a child, sends or acknowledges messages, interrupts or closes runs, changes settings, or modifies files.",
+		promptSnippet: "Inspect subagent metadata and runtime state without changing it",
+		parameters: SubagentInspectParams,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const ownerGeneration = lifecycleGeneration;
+			throwIfAborted(signal, "Subagent inspection loading was cancelled");
+			let executionModule: InspectExecutionModule;
+			try {
+				executionModule = await loadExecution();
+			} catch (error) {
+				throwIfAborted(signal, "Subagent inspection loading was cancelled");
+				if (ownerGeneration !== lifecycleGeneration) {
+					throw new DOMException("Subagent inspection session was replaced", "AbortError");
+				}
+				throw error;
+			}
+			throwIfAborted(signal, "Subagent inspection loading was cancelled");
+			if (ownerGeneration !== lifecycleGeneration) {
+				throw new DOMException("Subagent inspection session was replaced", "AbortError");
+			}
+			return executionModule.executeSubagentInspect(params, ctx, runtime);
+		},
+		renderCall(args, theme) {
+			return renderInspectCall(args, theme);
+		},
+		renderResult(result, options, theme, context) {
+			return renderInspectResult(result, options, theme, context);
+		},
+	};
+	pi.registerTool(definition);
+}

package/src/inspect-tool.ts

@@ -0,0 +1,43 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type Static, Type } from "typebox";
+
+const INSPECT_ACTIONS = [
+	"list_agents",
+	"get_agent",
+	"list_runs",
+	"get_run",
+	"list_workflows",
+	"get_workflow",
+	"list_models",
+	"preview_context",
+	"status",
+	"diagnose",
+] as const;
+
+const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
+	default: "user",
+	description: "Agent definition scope. Project scopes require a trusted project.",
+});
+const LimitSchema = Type.Number({ minimum: 1, maximum: 100, multipleOf: 1 });
+const ContextModeSchema = Type.Union([
+	StringEnum(["none", "all", "summary"] as const),
+	Type.Number({ minimum: 1, multipleOf: 1 }),
+]);
+
+export const SubagentInspectParams = Type.Object(
+	{
+		action: StringEnum(INSPECT_ACTIONS),
+		agent: Type.Optional(Type.String({ minLength: 1 })),
+		agentId: Type.Optional(Type.String({ minLength: 1 })),
+		workflowId: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+		agentScope: Type.Optional(AgentScopeSchema),
+		limit: Type.Optional(LimitSchema),
+		includeClosed: Type.Optional(Type.Boolean({ default: false })),
+		context: Type.Optional(ContextModeSchema),
+		contextEntryIds: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+	},
+	{ additionalProperties: false },
+);
+
+export type SubagentInspectParams = Static<typeof SubagentInspectParams>;
+export { INSPECT_ACTIONS };

package/src/inspect.ts

@@ -1,11 +1,5 @@
 import * as path from "node:path";
-import { StringEnum } from "@earendil-works/pi-ai";
-import {
-	CONFIG_DIR_NAME,
-	type ExtensionAPI,
-	type ExtensionContext,
-} from "@earendil-works/pi-coding-agent";
-import { type Static, Type } from "typebox";
+import { CONFIG_DIR_NAME, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { discoverAgents } from "./agents/discovery.js";
 import type {
 	AgentConfig,
@@ -16,7 +10,7 @@ import type {
 import { projectCapabilityManifest } from "./capabilities.js";
 import { resolveConsultTools } from "./consult-policy.js";
 import { buildContextSnapshot, type ContextMode } from "./context.js";
-import { renderInspectCall, renderInspectResult } from "./inspect-render.js";
+import { INSPECT_ACTIONS } from "./inspect-tool.js";
 import { DEFAULT_MAX_CONTEXT_BYTES } from "./limits.js";
 import { resolvePiInvocation } from "./pi-invocation.js";
 import type { AgentRunInspectionDetail, AgentRunInspectionSummary } from "./registry.js";
@@ -36,47 +30,10 @@ import type { StatefulSubagentRuntimeStatus } from "./stateful.js";
 import type { WorkItemLedgerSnapshot } from "./work-item-ledger.js";
 import { inspectSessionWorkflows } from "./work-item-persistence.js";
 
-const INSPECT_ACTIONS = [
-	"list_agents",
-	"get_agent",
-	"list_runs",
-	"get_run",
-	"list_workflows",
-	"get_workflow",
-	"list_models",
-	"preview_context",
-	"status",
-	"diagnose",
-] as const;
-
-const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
-	default: "user",
-	description: "Agent definition scope. Project scopes require a trusted project.",
-});
-
-const LimitSchema = Type.Number({ minimum: 1, maximum: 100, multipleOf: 1 });
-const ContextModeSchema = Type.Union([
-	StringEnum(["none", "all", "summary"] as const),
-	Type.Number({ minimum: 1, multipleOf: 1 }),
-]);
 const MAX_DETAILS_LIST_BYTES = 40 * 1024;
 
-export const SubagentInspectParams = Type.Object(
-	{
-		action: StringEnum(INSPECT_ACTIONS),
-		agent: Type.Optional(Type.String({ minLength: 1 })),
-		agentId: Type.Optional(Type.String({ minLength: 1 })),
-		workflowId: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
-		agentScope: Type.Optional(AgentScopeSchema),
-		limit: Type.Optional(LimitSchema),
-		includeClosed: Type.Optional(Type.Boolean({ default: false })),
-		context: Type.Optional(ContextModeSchema),
-		contextEntryIds: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
-	},
-	{ additionalProperties: false },
-);
-
-export type SubagentInspectParams = Static<typeof SubagentInspectParams>;
+export { registerSubagentInspect } from "./inspect-registration.js";
+export { SubagentInspectParams } from "./inspect-tool.js";
 
 export interface SubagentInspectRuntime {
 	getBlockingEnabled(): boolean;
@@ -106,26 +63,6 @@ type ValidatedInspectOperation =
 	| { action: "status" }
 	| { action: "diagnose" };
 
-export function registerSubagentInspect(pi: ExtensionAPI, runtime: SubagentInspectRuntime): void {
-	pi.registerTool({
-		name: "subagent_inspect",
-		label: "Inspect Subagents",
-		description:
-			"Inspect available subagent definitions, models, retained runs, persisted blocking workflows, runtime status, and diagnostics without changing subagent or workspace state. This tool never starts a child, sends or acknowledges messages, interrupts or closes runs, changes settings, or modifies files.",
-		promptSnippet: "Inspect subagent metadata and runtime state without changing it",
-		parameters: SubagentInspectParams,
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx): Promise<InspectToolResult> {
-			return executeSubagentInspect(validateInspectParams(params), ctx, runtime);
-		},
-		renderCall(args, theme) {
-			return renderInspectCall(args, theme);
-		},
-		renderResult(result, options, theme, context) {
-			return renderInspectResult(result, options, theme, context);
-		},
-	});
-}
-
 export function validateInspectParams(params: unknown): ValidatedInspectOperation {
 	const values = parameterRecord(params);
 	const rawAction = values.action;
@@ -195,11 +132,12 @@ export function validateInspectParams(params: unknown): ValidatedInspectOperatio
 	return { action };
 }
 
-async function executeSubagentInspect(
-	operation: ValidatedInspectOperation,
+export async function executeSubagentInspect(
+	params: unknown,
 	ctx: ExtensionContext,
 	runtime: SubagentInspectRuntime,
 ): Promise<InspectToolResult> {
+	const operation = validateInspectParams(params);
 	if (operation.action === "list_agents" || operation.action === "get_agent") {
 		assertTrustedScope(operation.agentScope, ctx);
 		const settings = inspectSubagentSettings().settings;

package/src/panel-planning.ts

@@ -1,9 +1,9 @@
 import type { AgentConfig } from "./agents/types.js";
 import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
+import type { PanelPreset } from "./panel-presets.js";
 import { type WorkItemDefinition, WorkItemLedger } from "./work-item-ledger.js";
 
-export const PANEL_PRESETS = ["code-review", "research", "security-review", "custom"] as const;
-export type PanelPreset = (typeof PANEL_PRESETS)[number];
+export type { PanelPreset } from "./panel-presets.js";
 
 export interface PanelReviewerRequest {
 	id: string;

package/src/panel-presets.ts

@@ -0,0 +1,3 @@
+export const PANEL_PRESETS = ["code-review", "research", "security-review", "custom"] as const;
+
+export type PanelPreset = (typeof PANEL_PRESETS)[number];

package/src/params.ts

@@ -3,10 +3,10 @@ import { type Static, Type } from "typebox";
 import { THINKING_LEVELS } from "./agents/types.js";
 import { DelegationContractSchema } from "./delegation-contract.js";
 import { MAX_CONFIGURABLE_PARALLEL_TASKS, MAX_SUBAGENT_TIMEOUT_MS } from "./limits.js";
-import { PANEL_PRESETS } from "./panel-planning.js";
+import { PANEL_PRESETS } from "./panel-presets.js";
 import { SUBAGENT_RESULT_FORMATS } from "./result-contract.js";
 import { MAX_SUBAGENT_TOOL_CALLS, MAX_SUBAGENT_TURNS } from "./turn-budget.js";
-import { VerifiedExecutionContractSchema } from "./verified-execution-contract.js";
+import { VerifiedExecutionContractSchema } from "./verified-execution-schema.js";
 
 const TimeoutMs = Type.Number({
 	description:

package/src/pi-args.ts

@@ -0,0 +1,41 @@
+import type { SubagentThinkingLevel } from "./agents/types.js";
+
+export interface PiArgsOptions {
+	model?: string;
+	thinkingLevel?: SubagentThinkingLevel;
+	tools?: string[];
+	disableExtensions?: boolean;
+	disableSkills?: boolean;
+	disablePromptTemplates?: boolean;
+	disableContextFiles?: boolean;
+	projectTrust?: boolean;
+	baseSystemPromptPath?: string;
+	appendSystemPromptPaths?: string[];
+	/** Existing single append prompt path retained for compatibility. */
+	systemPromptPath?: string;
+	task: string;
+}
+
+export function buildPiArgs(options: PiArgsOptions): string[] {
+	const args: string[] = ["--mode", "json", "-p", "--no-session"];
+	if (options.model) args.push("--model", options.model);
+	if (options.thinkingLevel) args.push("--thinking", options.thinkingLevel);
+	if (options.disableExtensions) args.push("--no-extensions");
+	if (options.disableSkills) args.push("--no-skills");
+	if (options.disablePromptTemplates) args.push("--no-prompt-templates");
+	if (options.disableContextFiles) args.push("--no-context-files");
+	if (options.projectTrust !== undefined) {
+		args.push(options.projectTrust ? "--approve" : "--no-approve");
+	}
+	if (Array.isArray(options.tools)) {
+		if (options.tools.length > 0) args.push("--tools", options.tools.join(","));
+		else args.push("--no-tools");
+	}
+	if (options.baseSystemPromptPath) args.push("--system-prompt", options.baseSystemPromptPath);
+	for (const promptPath of options.appendSystemPromptPaths ?? []) {
+		args.push("--append-system-prompt", promptPath);
+	}
+	if (options.systemPromptPath) args.push("--append-system-prompt", options.systemPromptPath);
+	args.push(`Task: ${options.task}`);
+	return args;
+}

package/src/render.ts

@@ -7,16 +7,13 @@ import {
 	type ToolRenderResultOptions,
 } from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
-import type { AgentScope, SubagentThinkingLevel } from "./agents/types.js";
+import type { AgentScope } from "./agents/types.js";
 import { renderPanelCall, renderPanelResult } from "./panel-render.js";
 import { hasUsableAggregator, type SubagentParams } from "./params.js";
 import { expansionHint, formatToolActivity, safeBlock, safeLine } from "./render-common.js";
-import {
-	getResultFinalOutput,
-	isResultError,
-	type SingleResult,
-	type SubagentDetails,
-} from "./runner.js";
+import type { SingleResult, SubagentDetails } from "./runner.js";
+import { getResultFinalOutput, isResultError } from "./runner-outcome.js";
+import { formatUsageStats } from "./usage-format.js";
 
 const COLLAPSED_ITEM_COUNT = 5;
 
@@ -29,46 +26,6 @@ function previewAgent(agent: unknown): string {
 	return safeLine(agent, "...", 256);
 }
 
-export function formatTokens(count: number): string {
-	if (count < 1000) return count.toString();
-	if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
-	if (count < 1000000) return `${Math.round(count / 1000)}k`;
-	return `${(count / 1000000).toFixed(1)}M`;
-}
-
-export function formatUsageStats(
-	usage: {
-		input: number;
-		output: number;
-		cacheRead: number;
-		cacheWrite: number;
-		cost: number;
-		contextTokens?: number;
-		turns?: number;
-	},
-	model?: string,
-	thinkingLevel?: SubagentThinkingLevel,
-	actualProvider?: string,
-	actualModel?: string,
-): string {
-	const parts: string[] = [];
-	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
-	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
-	if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
-	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
-	if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
-	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
-	if (usage.contextTokens && usage.contextTokens > 0)
-		parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
-	const safeProvider = actualProvider ? safeLine(actualProvider, "", 256) : undefined;
-	const safeModel = actualModel ? safeLine(actualModel, "", 256) : undefined;
-	const actual =
-		safeProvider && safeModel ? `${safeProvider}/${safeModel}` : (safeModel ?? safeProvider);
-	if (actual ?? model) parts.push(actual ?? safeLine(model, "", 256));
-	if (thinkingLevel) parts.push(`requested-thinking:${safeLine(thinkingLevel, "", 128)}`);
-	return parts.join(" ");
-}
-
 function formatResultUsageStats(result: SingleResult): string {
 	return formatUsageStats(
 		result.usage,

package/src/runner-outcome.ts

@@ -0,0 +1,31 @@
+import type { SingleResult } from "./runner.js";
+import {
+	formatResultFailure as formatBaseResultFailure,
+	getResultFinalOutput as getBaseResultFinalOutput,
+	isResultError as isBaseResultError,
+} from "./runner-result.js";
+
+export function getResultFinalOutput(result: SingleResult): string {
+	return getBaseResultFinalOutput(result);
+}
+
+export function isResultError(result: SingleResult): boolean {
+	return (
+		isBaseResultError(result) ||
+		result.resultContractInvalid === true ||
+		(result.outcome !== undefined &&
+			result.outcome.status !== "completed" &&
+			result.outcome.status !== "partial")
+	);
+}
+
+export function formatResultFailure(result: SingleResult): string {
+	const contractError = result.resultContractInvalid
+		? `Subagent returned an invalid ${result.resultFormat ?? "structured"} result contract`
+		: result.outcome && !["completed", "partial"].includes(result.outcome.status)
+			? `Subagent outcome ${result.outcome.status}${result.outcome.reasonCode ? ` (${result.outcome.reasonCode})` : ""}; recovery: ${result.outcome.recoveryActions.join(", ") || "none"}`
+			: undefined;
+	return contractError
+		? formatBaseResultFailure({ ...result, errorMessage: contractError })
+		: formatBaseResultFailure(result);
+}

package/src/runner.ts

@@ -31,6 +31,7 @@ import type { PanelSynthesis } from "./panel-contract.js";
 import type { PanelEvidenceArtifact } from "./panel-evidence.js";
 import type { PanelFailure } from "./panel-failure.js";
 import type { PanelPhaseBudgets, PanelPreset } from "./panel-planning.js";
+import { buildPiArgs } from "./pi-args.js";
 import { resolvePiInvocation } from "./pi-invocation.js";
 import { JsonLineDecoder } from "./protocol.js";
 import {
@@ -38,12 +39,8 @@ import {
 	parseAnyStructuredSubagentResult,
 	type SubagentResultFormat,
 } from "./result-contract.js";
-import {
-	formatResultFailure as formatBaseResultFailure,
-	getResultFinalOutput as getBaseResultFinalOutput,
-	getFinalOutput,
-	isResultError as isBaseResultError,
-} from "./runner-result.js";
+import { formatResultFailure, getResultFinalOutput, isResultError } from "./runner-outcome.js";
+import { getFinalOutput } from "./runner-result.js";
 import {
 	addUsageValue,
 	mergeUsageStats,
@@ -68,6 +65,13 @@ import type { WorkItemLedgerSnapshot } from "./work-item-ledger.js";
 
 export const KILL_GRACE_MS = 5000;
 
+export type { PiArgsOptions } from "./pi-args.js";
+export { buildPiArgs } from "./pi-args.js";
+export {
+	formatResultFailure,
+	getResultFinalOutput,
+	isResultError,
+} from "./runner-outcome.js";
 export type { UsageStats } from "./runner-usage.js";
 export type RecentActivityItem =
 	| { type: "text"; text: string }
@@ -154,31 +158,6 @@ export interface SubagentDetails {
 	isError?: boolean;
 }
 
-export function getResultFinalOutput(result: SingleResult): string {
-	return getBaseResultFinalOutput(result);
-}
-
-export function isResultError(result: SingleResult): boolean {
-	return (
-		isBaseResultError(result) ||
-		result.resultContractInvalid === true ||
-		(result.outcome !== undefined &&
-			result.outcome.status !== "completed" &&
-			result.outcome.status !== "partial")
-	);
-}
-
-export function formatResultFailure(result: SingleResult): string {
-	const contractError = result.resultContractInvalid
-		? `Subagent returned an invalid ${result.resultFormat ?? "structured"} result contract`
-		: result.outcome && !["completed", "partial"].includes(result.outcome.status)
-			? `Subagent outcome ${result.outcome.status}${result.outcome.reasonCode ? ` (${result.outcome.reasonCode})` : ""}; recovery: ${result.outcome.recoveryActions.join(", ") || "none"}`
-			: undefined;
-	return contractError
-		? formatBaseResultFailure({ ...result, errorMessage: contractError })
-		: formatBaseResultFailure(result);
-}
-
 function boundMessageText(
 	message: Message,
 	maxBytes: number,
@@ -359,46 +338,6 @@ async function writePromptToTempFile(
 	return { dir: tmpDir, filePath };
 }
 
-export interface PiArgsOptions {
-	model?: string;
-	thinkingLevel?: SubagentThinkingLevel;
-	tools?: string[];
-	disableExtensions?: boolean;
-	disableSkills?: boolean;
-	disablePromptTemplates?: boolean;
-	disableContextFiles?: boolean;
-	projectTrust?: boolean;
-	baseSystemPromptPath?: string;
-	appendSystemPromptPaths?: string[];
-	/** Existing single append prompt path retained for compatibility. */
-	systemPromptPath?: string;
-	task: string;
-}
-
-export function buildPiArgs(options: PiArgsOptions): string[] {
-	const args: string[] = ["--mode", "json", "-p", "--no-session"];
-	if (options.model) args.push("--model", options.model);
-	if (options.thinkingLevel) args.push("--thinking", options.thinkingLevel);
-	if (options.disableExtensions) args.push("--no-extensions");
-	if (options.disableSkills) args.push("--no-skills");
-	if (options.disablePromptTemplates) args.push("--no-prompt-templates");
-	if (options.disableContextFiles) args.push("--no-context-files");
-	if (options.projectTrust !== undefined) {
-		args.push(options.projectTrust ? "--approve" : "--no-approve");
-	}
-	if (Array.isArray(options.tools)) {
-		if (options.tools.length > 0) args.push("--tools", options.tools.join(","));
-		else args.push("--no-tools");
-	}
-	if (options.baseSystemPromptPath) args.push("--system-prompt", options.baseSystemPromptPath);
-	for (const promptPath of options.appendSystemPromptPaths ?? []) {
-		args.push("--append-system-prompt", promptPath);
-	}
-	if (options.systemPromptPath) args.push("--append-system-prompt", options.systemPromptPath);
-	args.push(`Task: ${options.task}`);
-	return args;
-}
-
 function signalProcess(proc: ReturnType<typeof spawn>, signal: NodeJS.Signals): void {
 	if (process.platform !== "win32" && proc.pid) {
 		try {
@@ -857,16 +796,16 @@ export async function runSingleAgent(
 				onExceeded: stopForBudget,
 			});
 
-			timeout = setTimeout(() => {
-				stopForBudget({
-					reason: launchPolicy?.workTimeoutReason ?? "work_timeout",
-					limit: launchPolicy?.workTimeoutReportLimit ?? timeoutMs,
-				});
-			}, timeoutMs);
-			timeout.unref();
-
 			proc.once("spawn", () => {
 				currentResult.processStarted = true;
+				if (settled || budgetStop || wasAborted) return;
+				timeout = setTimeout(() => {
+					stopForBudget({
+						reason: launchPolicy?.workTimeoutReason ?? "work_timeout",
+						limit: launchPolicy?.workTimeoutReportLimit ?? timeoutMs,
+					});
+				}, timeoutMs);
+				timeout.unref();
 			});
 			proc.stdout?.on("data", (data) => decoder.push(data));
 			proc.stderr?.on("data", (data) => {

package/src/settings.ts

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
+import { createRequire } from "node:module";
 import * as path from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import lockfile from "proper-lockfile";
 import type {
 	AgentConfig,
 	CompletionDelivery,
@@ -76,6 +76,8 @@ export {
 
 const SETTINGS_FILE = "pi-subagents.json";
 const LEGACY_SETTINGS_FILE = "pi-subagents-config.json";
+const require = createRequire(import.meta.url);
+
 const SETTINGS_LOCK_FS_ADAPTER = {
 	mkdir: fs.mkdir,
 	mkdirSync: fs.mkdirSync,
@@ -511,6 +513,7 @@ function writeSettingsObjectUnlocked(settings: object, replaceCanonical?: boolea
 }
 
 function withSettingsMutationLock<T>(mutate: () => T): T {
+	const lockfile = require("proper-lockfile") as typeof import("proper-lockfile");
 	const agentDir = getAgentDir();
 	fs.mkdirSync(agentDir, { recursive: true });
 	const configPath = path.join(agentDir, SETTINGS_FILE);