@visual-z/xeno 0.5.0 → 0.7.0

package/src/runtime/loop.ts

@@ -43,7 +43,10 @@ import { randomUUID } from "node:crypto";
 import { pendingToolCalls } from "../core/execution.ts";
 import { declaredToolNames, recordedDeclarations } from "../core/tool-discovery.ts";
 import { DISCOVERY_TOOL, DISCOVERY_TOOL_NAME, currentDeferredTools, discoveryFingerprint, discoveryPermitted, searchDeferredTools } from "./tool-discovery.ts";
-import { executionOutcome, modelOutcome, type ExecutionOutcome } from "../core/outcome.ts";
+import { executionOutcome, modelOutcome, type ExecutionOutcome, type ExecutionReason } from "../core/outcome.ts";
+import { finalizationNotice, requestPhase } from "../core/request-budget.ts";
+import { stopReport } from "../core/stop-report.ts";
+import { supportsToolDisabling, type ProviderSendOptions } from "./provider-tool-policy.ts";
 import { commandCompletion } from "../core/command-contract.ts";
 import { ExecutionControl } from "./execution-control.ts";
 import { BranchJobs } from "./branch-jobs.ts";
@@ -153,7 +156,8 @@ export interface LoopEvent {
   outcome?: ExecutionOutcome;
   /** Q23: task evidence is separate from the execution outcome; rebuilt from original receipts. */
   request?: RequestState;
-  progress?: Extract<StreamDelta, { kind: "tool" | "retry" }> | { kind: "output"; text: string; name: string };
+  progress?: Extract<StreamDelta, { kind: "tool" | "retry" }> | { kind: "output"; text: string; name: string }
+    | { kind: "waiting"; session: number; active: boolean };
 }
 
 /**
@@ -187,6 +191,12 @@ export const DEFAULT_BRANCH_LIMITS: BranchLimits = {
 };
 
 export interface SessionConfig {
+  /** Runtime-only output contract, explicitly selected by the current caller. */
+  validateOutput?: (text: string) => { ok: boolean; error?: string };
+  /** Persist a selector, never persisted profile code or authorization (D6/D13). */
+  agentProfile?: { name: string; workflowExplicit: boolean };
+  /** An explicit mode command's capability default, independent of role authority. */
+  workflowToolProfile?: "foundation";
   /** P.3: legacy full snapshots are an explicit compatibility mode, never the CLI default. */
   workspaceTracking?: "journal" | "legacy";
   shellCheckpoints?: boolean;
@@ -330,7 +340,7 @@ export type RewindResult =
   | { ok: false; error: string };
 
 /** O.5: child execution returns facts; only the parent coordinator accepts them. */
-type DeferredToolResult = ToolResult & { accept?: () => Promise<LoopEvent[]>; annotation?: LogEvent };
+type DeferredToolResult = ToolResult & { accept?: () => Promise<LoopEvent[]>; annotation?: LogEvent; finalText?: string };
 type ToolCall = Extract<AssistantBlock, { type: "tool_use" }>;
 type SessionBrokerReceipt = BrokerReceipt<DeferredToolResult> & { events: LoopEvent[] };
 type PreparedBrokerCall = { run(emit?: (event: LoopEvent) => void): Promise<SessionBrokerReceipt> };
@@ -350,6 +360,7 @@ export class Session {
   private readonly hostPending = new Set<Promise<NativeCommandResult>>();
   private stall: StallState | null = null;
   private recovery: RecoveryState | null = null;
+  private processWake = new AbortController();
   private pendingAdoption: number | null = null;
   private readonly allocatedEventIds = new Set<string>();
   private recordTail: Promise<void> = Promise.resolve();
@@ -371,8 +382,10 @@ export class Session {
     stallDecision(emptyStallState(), config.stallLimit ?? DEFAULT_STALL_LIMIT);
     validateOutputRecoveryLimit(config.outputRecoveryLimit ?? DEFAULT_OUTPUT_RECOVERY_LIMIT);
     schedulingWindow([], 0, config.maxParallelTools ?? 3);
+    requestPhase(0, config.maxTurns);
     this.allocation = allocation;
-    this.config = { ...config, ...(config.acceptanceContract ? { acceptanceContract: parseAcceptanceContract(config.acceptanceContract) } : {}), tools: { ...config.tools, execOwner: this.execOwner, historyCache: new HistoryCache() } };
+    this.config = { ...config, ...(config.acceptanceContract ? { acceptanceContract: parseAcceptanceContract(config.acceptanceContract) } : {}), tools: { ...config.tools, execOwner: this.execOwner, historyCache: new HistoryCache(),
+      processWait: { wake: () => this.processWake.signal } } };
     // A child or restored Session must never inherit another live invocation scope.
     delete this.config.tools.invoke;
     delete this.config.tools.invokeHost;
@@ -384,6 +397,13 @@ export class Session {
     // Branch capability sets are owned by branchTools; a parent's optional catalog is not a grant.
     if ((config.branchDepth ?? 0) > 0) delete this.config.tools.deferredTools;
     this.config.tools.outputStore ??= join(config.logDir, "artifacts");
+    this.config.tools.historyEvents = async () => {
+      const history = await readNodeHistory(this.config.logDir, this.state.node, undefined, "context");
+      if (!history.ok) throw Error(history.error);
+      return history.nodes.flatMap(node => node.node === this.state.node ? structuredClone(this.state.events) : node.events);
+    };
+    if (config.blobDir) this.config.tools.checkpointBlobs = config.blobDir;
+    this.config.tools.frozenSystem = () => this.config.frozen.system;
     // R4 / D8: full ancestry, not the bounded model view or a second mutable ledger.
     // Each child Session installs its own callback even when contexts are copied.
     this.config.tools.observedFileVersion = async absolute => {
@@ -492,7 +512,16 @@ export class Session {
         if (plan.cursor.context_ref) {
           const saved = await getBlob(join(dir, "artifacts"), plan.cursor.context_ref);
           if (saved === null) throw new Error("missing frozen session context");
-          const context = JSON.parse(saved) as { skills?: Skill[]; acceptanceContract?: AcceptanceContract; strictVerification?: boolean; workingSet?: boolean; workingSetVersion?: 1 | 2; guidanceVersion?: 1; projectionVersion?: number; frozen: FrozenPrefix; boundary?: Partial<BoundaryConfig>; contextPolicy?: unknown; stallLimit?: number; outputRecoveryLimit?: number; guidance?: boolean; gates: Record<string, string>; snapshotIgnore?: readonly string[]; workspaceTracking?: "journal" | "legacy"; shellCheckpoints?: boolean; workNamespace?: string; maxParallelTools?: number };
+          const context = JSON.parse(saved) as { agentProfile?: { name: string; workflowExplicit: boolean }; workflowMode?: "build" | "plan"; skills?: Skill[]; acceptanceContract?: AcceptanceContract; strictVerification?: boolean; workingSet?: boolean; workingSetVersion?: 1 | 2; guidanceVersion?: 1; projectionVersion?: number; frozen: FrozenPrefix; boundary?: Partial<BoundaryConfig>; contextPolicy?: unknown; stallLimit?: number; outputRecoveryLimit?: number; guidance?: boolean; gates: Record<string, string>; snapshotIgnore?: readonly string[]; workspaceTracking?: "journal" | "legacy"; shellCheckpoints?: boolean; workNamespace?: string; maxParallelTools?: number };
+          if (context.agentProfile !== undefined) {
+            if (!context.agentProfile || typeof context.agentProfile.name !== "string" || !/^[a-z][a-z0-9_-]{0,63}$/.test(context.agentProfile.name) || typeof context.agentProfile.workflowExplicit !== "boolean") throw Error("unsupported saved agent profile selector");
+            this.config.agentProfile = { ...context.agentProfile };
+          }
+          if (context.workflowMode !== undefined) { if (!["build", "plan"].includes(context.workflowMode)) throw Error("unsupported saved workflow mode"); this.config.tools.workflowMode = context.workflowMode; }
+          if ("workflowToolProfile" in context && context.workflowToolProfile !== undefined) {
+            if (context.workflowToolProfile !== "foundation") throw Error("unsupported saved workflow tool profile");
+            this.config.workflowToolProfile = "foundation";
+          }
           if (context.projectionVersion !== undefined && context.projectionVersion !== PROJECTION_VERSION) throw new Error("unsupported saved projection version");
           this.config.workingSet = context.workingSet === true;
           if (context.workingSetVersion !== undefined && ![1, 2].includes(context.workingSetVersion)) throw new Error("unsupported saved working-set version");
@@ -760,12 +789,18 @@ export class Session {
   }
 
   /** D6: changing the frozen prefix is an explicit checkpoint, never in-place prompt surgery. */
-  async reloadResources(frozen: FrozenPrefix, skills = this.config.skills): Promise<boolean> {
-    if (JSON.stringify(frozen) === JSON.stringify(this.config.frozen) && JSON.stringify(skills) === JSON.stringify(this.config.skills)) return false;
+  assertResourceIdle(): void {
     if (this.running || this.isHalfRound()) throw new Error("cannot reload resources while a turn is active or a tool call is unpaired");
+  }
+
+  async reloadResources(frozen: FrozenPrefix, skills = this.config.skills, nextProvider?: Provider, forceCheckpoint = false): Promise<boolean> {
+    if (!nextProvider && !forceCheckpoint && JSON.stringify(frozen) === JSON.stringify(this.config.frozen) && JSON.stringify(skills) === JSON.stringify(this.config.skills)) return false;
+    this.assertResourceIdle();
     const contextRef = await this.persistContext(frozen, skills);
-    await this.performCut("model_checkpoint", this.provider.config.spec.id, undefined,
-      this.provider.config.spec.provider, this.provider.config.effort, contextRef);
+    const provider = nextProvider ?? this.provider;
+    await this.performCut("model_checkpoint", provider.config.spec.id, undefined,
+      provider.config.spec.provider, provider.config.effort, contextRef);
+    this.provider = provider;
     this.config.frozen = frozen;
     if (skills !== undefined) this.config.skills = skills;
     this.installSkillResources();
@@ -825,6 +860,9 @@ export class Session {
     pull?: (phase: Phase) => Promise<UserInput | null>,
   ): Promise<UserInput | null> {
     if (pull === undefined || this.isHalfRound()) return null;
+    // Rotate before pulling: an input queued during the async pull still wakes
+    // the next wait. A wake never cancels the process's lifetime signal.
+    this.processWake = new AbortController();
     const text = await pull("after_tools");
     if (text === null || typeof text === "string" && text.length === 0) return null;
     if (this.turnTools) this.config.tools = { ...this.turnTools };
@@ -850,6 +888,9 @@ export class Session {
       ...(this.config.workingSet && this.config.workingSetVersion === 2 ? { workingSetVersion: 2 } : {}),
       ...(this.config.guidanceVersion === 1 ? { guidanceVersion: 1 } : {}),
       frozen, gates: this.config.tools.gates,
+      ...(this.config.tools.workflowMode ? { workflowMode: this.config.tools.workflowMode } : {}),
+      ...(this.config.agentProfile ? { agentProfile: this.config.agentProfile } : {}),
+      ...(this.config.workflowToolProfile ? { workflowToolProfile: this.config.workflowToolProfile } : {}),
       workNamespace: this.config.workNamespace ?? "main",
       maxParallelTools: this.config.maxParallelTools ?? 3,
       ...(this.config.boundary ? { boundary: this.config.boundary } : {}),
@@ -953,13 +994,31 @@ export class Session {
         await result.accept?.();
         await this.record({ t: "extension", id: this.clock.nextId(), at: this.clock.now(), customType: "skill_result", content: result.content,
           display: true, inContext: true });
+        // Evidence stays in the receipt; structured output validates the child's
+        // actual final message, never the human-readable receipt wrapper (D11).
+        const finalText = this.config.validateOutput ? result.finalText ?? "" : result.content;
+        let outcome = result.outcome ?? executionOutcome("execution_error"), reason = "isolated skill finished";
+        if (outcome.status === "completed") {
+          const error = await this.validateFinalOutput(finalText);
+          if (error !== undefined) { outcome = executionOutcome("execution_error"); reason = error; }
+        }
+        await this.record({ t: "outcome", id: this.clock.nextId(), at: this.clock.now(), reason, outcome });
         await this.saveCursor();
-        yield { kind: "assistant_text", text: result.content };
-        yield { kind: "done", outcome: result.outcome ?? executionOutcome("execution_error"), reason: "isolated skill finished" };
+        yield { kind: "assistant_text", text: finalText };
+        yield { kind: "done", outcome, reason };
       } finally { owned.finish(); }
     } finally { this.config.tools = savedTools; this.restoreDeclaredTools(); }
   }
 
+  /** Every final publication path records the same validator receipt (D11). */
+  private async validateFinalOutput(text: string): Promise<string | undefined> {
+    if (!this.config.validateOutput) return undefined;
+    const validation = this.config.validateOutput(text);
+    await this.appendExtension({ customType: "output_validation", content: validation.ok ? "Final JSON output passed the selected schema." : `Final JSON output failed: ${validation.error ?? "schema mismatch"}`,
+      display: false, inContext: false, data: { valid: validation.ok } });
+    return validation.ok ? undefined : `output schema validation failed: ${validation.error ?? "schema mismatch"}`;
+  }
+
   /** O.8: dispatch and diagnostics share exact source hints, including forks. */
   contextInput(): ProjectInput {
     return { frozen: this.config.frozen, handoff: this.state.handoff, events: this.state.events,
@@ -1136,6 +1195,7 @@ export class Session {
   ): AsyncGenerator<LoopEvent> {
     if (this.cleanup || this.closing) throw new Error("session is draining or disposed");
     const owned = this.execution.begin(signal);
+    this.processWake = new AbortController();
     const savedTools = this.config.tools;
     this.turnTools = savedTools;
     this.config.tools = { ...savedTools };
@@ -1222,6 +1282,7 @@ export class Session {
       let overflowRetried = false;
       const requestStarted = this.clock.now();
       for (let turn = 0; turn < this.config.maxTurns; turn++) {
+        const phase = requestPhase(turn, this.config.maxTurns);
         completedThisTurn.length = 0;
         if (signal?.aborted) {
           yield* this.closeInterrupted(completedThisTurn);
@@ -1229,12 +1290,18 @@ export class Session {
         }
 
         if (yield* this.checkStall()) {
-          yield { kind: "done", reason: "stopped: consecutive tool exchanges without new evidence", outcome: executionOutcome("stalled") };
+          yield { kind: "done", reason: await this.terminationReport("no-progress allowance exhausted", turn), outcome: executionOutcome("stalled") };
+          return;
+        }
+        if (phase === "finalize" && !supportsToolDisabling(this.provider.config.spec.api)) {
+          yield { kind: "done", reason: await this.terminationReport("work budget exhausted; protocol cannot disable tools while preserving frozen definitions", turn), outcome: executionOutcome("max_turns") };
           return;
         }
         yield { kind: "turn_start", node: this.state.node };
 
-        if (this.config.guidance !== false) {
+        if (phase === "finalize") {
+          await this.record({ t: "guidance", id: this.clock.nextId(), at: this.clock.now(), reason: "budget", sources: [], text: finalizationNotice() });
+        } else if (this.config.guidance !== false) {
           const names = this.adviceNames();
           const guidance = (this.config.harnessReviews === false ? null : await this.recoveryGuidance(names)) ??
             continuationGuidance({ events: this.state.events, handoff: this.state.handoff,
@@ -1276,7 +1343,7 @@ export class Session {
 
         let result: Turn;
         try {
-          result = yield* this.awaitProvider(projected.messages, signal);
+          result = yield* this.awaitProvider(projected.messages, signal, phase === "finalize" ? { toolUse: "disabled" } : undefined);
         } catch (error) {
           // D11: retain a typed response receipt once, without anchoring rejected content or trusting arbitrary error fields.
           if (error instanceof FailedResponseError && error.usage !== undefined) this.state.usage.push({ ...error.usage });
@@ -1284,6 +1351,11 @@ export class Session {
             yield* this.closeInterrupted(completedThisTurn);
             return;
           }
+          if (phase === "finalize") {
+            yield { kind: "discard" };
+            yield { kind: "done", reason: await this.terminationReport("final response failed; no additional request was made", turn + 1), outcome: executionOutcome("provider_error") };
+            return;
+          }
           if (!(error instanceof Error) || !isContextOverflow(error.message, statusOf(error))) throw error;
           // The estimate said this fit and the provider says it does not: the
           // estimate is wrong for this content. The only projection that can
@@ -1374,6 +1446,16 @@ export class Session {
           (b): b is Extract<AssistantBlock, { type: "tool_use" }> => b.type === "tool_use",
         );
 
+        // Provider policy is a wire instruction, not authority. Pair every
+        // refused call, but never admit execution in the reserved final request.
+        if (phase === "finalize" && (calls.length > 0 || !isCompleteResponse(result.stopReason) ||
+            !result.blocks.some(block => block.type === "text" && block.text.trim()))) {
+          for (const item of await this.answerUnpairedTools("not executed: tools are disabled in the final request", "not_started"))
+            yield { kind: "tool_result", text: item.content, ok: false };
+          yield { kind: "done", reason: await this.terminationReport("request budget exhausted; final response did not provide a complete text answer", turn + 1), outcome: executionOutcome("max_turns") };
+          return;
+        }
+
         // N.12: syntactically valid arguments in an unfinished response are not
         // authorization to execute a partial batch. Pair without side effects.
         if (!isCompleteResponse(result.stopReason)) {
@@ -1427,6 +1509,12 @@ export class Session {
             continue;
           }
           const stopped = yield* this.maybeCut(counter, false);
+          if (!stopped) {
+            const error = await this.validateFinalOutput(result.blocks.filter(block => block.type === "text").map(block => block.text).join("\n"));
+            if (error !== undefined) {
+              yield { kind: "done", reason: error, outcome: executionOutcome("execution_error") }; return;
+            }
+          }
           yield {
             kind: "done",
             reason: stopped ? "stopped: no verifiable progress" : result.stopReason ?? "end_turn",
@@ -1508,7 +1596,7 @@ export class Session {
         }
       }
 
-      yield { kind: "done", reason: `hit maxTurns (${this.config.maxTurns})`, outcome: executionOutcome("max_turns") };
+      yield { kind: "done", reason: await this.terminationReport("request budget exhausted", this.config.maxTurns), outcome: executionOutcome("max_turns") };
     } finally {
       // If the consumer aborts and stops pulling, the generator is closed
       // without running the yield* closeInterrupted path. Pairing still
@@ -1526,6 +1614,7 @@ export class Session {
    */
   private async answerUnpairedTools(
     content = "interrupted: the user cancelled before this tool completed",
+    reason: ExecutionReason = "unknown",
   ): Promise<{ callId: string; content: string }[]> {
     const added: { callId: string; content: string }[] = [];
     for (const block of pendingToolCalls(this.state.events)) {
@@ -1540,7 +1629,7 @@ export class Session {
           ...(block.origin ? { origin: block.origin } : {}),
           ok: false,
           content: resultText,
-          outcome: executionOutcome("unknown"),
+          outcome: executionOutcome(reason),
         });
         added.push({ callId: block.call_id, content: resultText });
     }
@@ -1589,6 +1678,7 @@ export class Session {
   private async *awaitProvider(
     messages: readonly Message[],
     signal?: AbortSignal,
+    options?: ProviderSendOptions,
   ): AsyncGenerator<LoopEvent, Turn> {
     const hydrated = await hydrateImages(messages, this.config.blobDir ?? join(this.config.logDir, "blobs"),
       this.provider.config.spec.input?.includes("image") ?? false);
@@ -1610,7 +1700,7 @@ export class Session {
         default:
           return assertNever(delta, "onDelta");
       }
-    }));
+    }, options));
   }
 
   /**
@@ -1759,6 +1849,7 @@ export class Session {
       if (native) context = nativeCommandContext(context);
       const decoder = new TextDecoder();
       context.onOutput = chunk => emit({ kind: "progress", progress: { kind: "output", name: call.name, text: decoder.decode(chunk, { stream: true }) } });
+      context.onProcessWait = (session, active) => emit({ kind: "progress", progress: { kind: "waiting", session, active } });
       const broker = new ToolBroker<DeferredToolResult>({
         parallelLimit: this.config.maxParallelTools ?? 3,
         callId: () => `nested-${randomUUID()}`,
@@ -2021,14 +2112,15 @@ export class Session {
     this.children.set(node, branch);
     yield { kind: "branch_start", node, reason: purpose, at: Date.now() };
 
-    let text = "";
+    let finalParts: string[] = [];
     let outcome = executionOutcome("unknown");
     try {
       for await (const event of branch.snapshotTurn([], true)) {
         if (event.kind === "snapshot_failed") throw new Error(`cannot establish branch baseline: ${event.reason}`);
       }
       for await (const e of branch.send(prompt, signal)) {
-        if (e.kind === "assistant_text" && e.text) text = e.text;
+        if (e.kind === "turn_start" || e.kind === "discard") finalParts = [];
+        if (e.kind === "assistant_text") finalParts.push(e.text ?? "");
         if (e.kind === "done") outcome = e.outcome ?? executionOutcome("unknown");
       }
     } catch {
@@ -2055,6 +2147,7 @@ export class Session {
       ? `\n\nIts changes are in ${worktree.path} on branch ${worktree.branch}, ` +
         "not in your files. Adopting continues in that checkout without merging it into this one."
       : "";
+    const text = finalParts.join("\n");
     const summary = text.trim() || "(the branch produced no closing message)";
     const receiptHistory = await readNodeHistory(this.config.logDir, tip, undefined, "context");
     if (!receiptHistory.ok) throw new Error(receiptHistory.error);
@@ -2081,6 +2174,7 @@ export class Session {
         (this.adviceNames().includes("resolve") ? `Resolve it with resolve(node: ${node}, ...).` : "Branch-resolution capability unavailable."),
       ok: outcome.status === "completed",
       outcome,
+      finalText: text,
       accept: async () => {
         if ((await this.branchStatuses()).some(item => item.node === node && item.handoff_ref)) return [];
         this.state.usage.push(...branch.state.usage);
@@ -2662,14 +2756,23 @@ export class Session {
     }
     const decision = stallDecision(this.stall, limit);
     if (decision.stop) {
-      yield { kind: "stop_and_ask", reason: `${decision.consecutive} consecutive tool exchanges without new evidence or fresh verification; change the approach or provide new input` };
+      yield { kind: "stop_and_ask", reason: `${decision.unproductive} total tool exchanges without new evidence (${decision.consecutive} consecutive; ${decision.failures} failed receipts; ${decision.emptyWaits} empty waits); change the approach or provide new input` };
       return true;
     }
     if (decision.warn) await this.record({ t: "guidance", id: this.clock.nextId(), at: this.clock.now(), reason: "stall", sources: [],
-      text: `Harness: ${decision.consecutive} consecutive tool exchanges without new evidence or fresh verification. Change the method, run a meaningful check, or give the final result with unresolved limits. The harness will stop at ${limit} such exchanges. Notes and repeated observations do not count as progress.` });
+      text: `Harness: ${decision.unproductive} total tool exchanges without new evidence or fresh verification (${decision.consecutive} consecutive; ${decision.failures} failed receipts; ${decision.emptyWaits} empty waits). Change the method, run a meaningful check, or give the final result with unresolved limits. The harness will stop at ${limit} total unproductive exchanges. Novel observations reset the streak, not the spent allowance. Notes and repeated observations do not count as progress.` });
     return false;
   }
 
+  /** A steering signal releases only the wait; cancellation owns process termination. */
+  wakeProcessWaits(): void { this.processWake.abort(); }
+
+  private async terminationReport(cause: string, requests: number): Promise<string> {
+    const history = await readNodeHistory(this.config.logDir, this.state.node, undefined, "context");
+    if (!history.ok) throw new Error(history.error);
+    return stopReport(history.nodes.flatMap(part => part.events), requests, this.config.maxTurns, cause);
+  }
+
   /** N.8: build and check the replacement before committing a durable boundary. */
   /**
    * `overflowed` is the provider's own verdict that the current projection

package/src/runtime/lsp-client.ts

@@ -0,0 +1,201 @@
+/** Explicit trusted servers, one lifecycle each; server edits never bypass checkpoint ownership. */
+import { extname } from "node:path";
+import { pathToFileURL } from "node:url";
+import { nextLspFrame, encodeLspFrame, diagnosticFreshness, MAX_LSP_FRAME, MAX_LSP_HEADER } from "../core/lsp-framing.ts";
+import { readLspDocument } from "../store/lsp-document.ts";
+import { presentObservation, type ToolDefinition, type ToolResult } from "./tools.ts";
+
+export interface LspConfig { name: string; command: string[]; extensions: string[]; languageId: string }
+export function parseLspConfig(value: unknown): LspConfig[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > 16) throw Error("lsp must be an array of at most 16 servers");
+  const names = new Set<string>();
+  return value.map(item => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) throw Error("invalid LSP config");
+    const v = item as Record<string, unknown>;
+    if (Object.keys(v).some(key => !["name", "command", "extensions", "languageId"].includes(key)) || typeof v["name"] !== "string" || !/^[a-zA-Z0-9_-]{1,64}$/.test(v["name"]) || names.has(v["name"]) || typeof v["languageId"] !== "string" || !v["languageId"] || !Array.isArray(v["command"]) || !v["command"].length || v["command"].some(part => typeof part !== "string" || !part || part.includes("\0")) || !Array.isArray(v["extensions"]) || !v["extensions"].length || v["extensions"].some(part => typeof part !== "string" || !/^\.[a-zA-Z0-9]+$/.test(part))) throw Error("invalid or duplicate LSP config");
+    names.add(v["name"]); return { name: v["name"], languageId: v["languageId"], command: v["command"].map(String), extensions: v["extensions"].map(String) };
+  });
+}
+type Pending = { resolve(value: unknown): void; reject(error: Error): void; cancel(): void };
+// Operational limits, not segment thresholds: bound unsolicited traffic and retained server state.
+const MAX_LSP_STREAM_BYTES = 32 * 1024 * 1024;
+const MAX_LSP_DIAGNOSTIC_BYTES = 512 * 1024;
+const MAX_LSP_OPEN_DOCUMENTS = 32;
+class LspConnection {
+  private readonly root: string;
+  private readonly config: LspConfig;
+  private process: ReturnType<typeof Bun.spawn> | undefined;
+  private buffer = new Uint8Array(0);
+  private next = 1;
+  private readonly pending = new Map<number, Pending>();
+  private readonly documents = new Map<string, { sha256: string; version: number }>();
+  private readonly diagnostics = new Map<string, { version?: number; items: unknown[] }>();
+  private ready: Promise<void> | undefined;
+  private closed = false;
+  private failure: string | undefined;
+  private streamBytes = 0;
+  private documentVersion = 0;
+  get usable(): boolean { return !this.closed && this.failure === undefined; }
+  constructor(root: string, config: LspConfig) { this.root = root; this.config = config; }
+  private send(message: unknown): void {
+    if (this.failure) throw Error(this.failure);
+    const stdin = this.process?.stdin;
+    if (!stdin || typeof stdin === "number") throw Error("LSP server is unavailable");
+    stdin.write(encodeLspFrame(message)); stdin.flush();
+  }
+  private notify(method: string, params: unknown): void { this.send({ jsonrpc: "2.0", method, params }); }
+  private request(method: string, params: unknown, signal?: AbortSignal, timeoutMs = 10_000): Promise<unknown> {
+    if (signal?.aborted) return Promise.reject(Error("LSP request cancelled"));
+    const id = this.next++;
+    return new Promise((resolve, reject) => {
+      const stop = (reason: string) => { const pending = this.pending.get(id); if (!pending) return; this.pending.delete(id); pending.cancel(); try { this.notify("$/cancelRequest", { id }); } catch { /* process may be dead */ } reject(Error(reason)); };
+      const aborted = () => stop("LSP request cancelled");
+      const timer = setTimeout(() => stop("LSP request timed out"), timeoutMs);
+      this.pending.set(id, { resolve, reject, cancel: () => { clearTimeout(timer); signal?.removeEventListener("abort", aborted); } });
+      signal?.addEventListener("abort", aborted, { once: true });
+      try { this.streamBytes = 0; this.send({ jsonrpc: "2.0", id, method, params }); } catch (error) { this.pending.delete(id); clearTimeout(timer); signal?.removeEventListener("abort", aborted); reject(error); }
+    });
+  }
+  private fail(reason: string): void {
+    this.failure ??= reason;
+    for (const item of this.pending.values()) { item.cancel(); item.reject(Error(reason)); } this.pending.clear();
+  }
+  private receive(value: unknown): void {
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw Error("invalid LSP envelope");
+    const v = value as Record<string, unknown>;
+    if (v["jsonrpc"] !== "2.0") throw Error("invalid LSP version");
+    if (typeof v["method"] === "string") {
+      const params = v["params"] !== null && typeof v["params"] === "object" && !Array.isArray(v["params"]) ? v["params"] as Record<string, unknown> : undefined;
+      if (v["method"] === "textDocument/publishDiagnostics" && typeof params?.["uri"] === "string" && Array.isArray(params["diagnostics"])) {
+        const version = params["version"];
+        // A server may report a whole workspace; cache only documents opened by this client.
+        if (this.documents.has(params["uri"])) {
+          if (version !== undefined && (typeof version !== "number" || !Number.isInteger(version) || version < 0 || version > 2 ** 31 - 1)) throw Error("invalid LSP diagnostic version");
+          if (new TextEncoder().encode(JSON.stringify(params["diagnostics"])).length > MAX_LSP_DIAGNOSTIC_BYTES) throw Error("LSP diagnostics exceeded");
+          this.diagnostics.set(params["uri"], { ...(typeof version === "number" ? { version } : {}), items: params["diagnostics"] });
+        }
+      }
+      if (v["id"] !== undefined) {
+        if (typeof v["id"] !== "string" && (typeof v["id"] !== "number" || !Number.isSafeInteger(v["id"]))) throw Error("invalid LSP request id");
+        const method = v["method"];
+        if (method === "workspace/configuration") this.send({ jsonrpc: "2.0", id: v["id"], result: Array.isArray(params?.["items"]) ? params["items"].map(() => null) : [] });
+        else if (method === "workspace/workspaceFolders") this.send({ jsonrpc: "2.0", id: v["id"], result: [{ uri: pathToFileURL(this.root).href, name: this.config.name }] });
+        else if (method === "workspace/applyEdit") this.send({ jsonrpc: "2.0", id: v["id"], result: { applied: false, failureReason: "use the owned Patch tool; LSP cannot write files" } });
+        else this.send({ jsonrpc: "2.0", id: v["id"], error: { code: -32601, message: "client capability not supported" } });
+      }
+      return;
+    }
+    if (typeof v["id"] !== "number" || !Number.isSafeInteger(v["id"])) throw Error("invalid LSP response id");
+    const pending = this.pending.get(v["id"]); if (!pending) return;
+    if (Object.hasOwn(v, "result") === Object.hasOwn(v, "error")) throw Error("invalid LSP response result");
+    this.pending.delete(v["id"]); pending.cancel(); this.streamBytes = 0;
+    if (v["error"] !== undefined) pending.reject(Error(JSON.stringify(v["error"]).slice(0, 512))); else pending.resolve(v["result"]);
+  }
+  async start(signal?: AbortSignal): Promise<void> {
+    signal?.throwIfAborted();
+    if (this.closed) throw Error("LSP connection disposed");
+    if (this.failure) throw Error(this.failure);
+    if (this.ready) return this.ready;
+    this.ready = (async () => {
+      this.process = Bun.spawn(this.config.command, { cwd: this.root, stdin: "pipe", stdout: "pipe", stderr: "ignore" });
+      const process = this.process;
+      void (async () => {
+        try {
+          if (!process.stdout || typeof process.stdout === "number") throw Error("missing LSP stdout");
+          for await (const chunk of process.stdout) {
+            this.streamBytes += chunk.length;
+            if (this.streamBytes > MAX_LSP_STREAM_BYTES) throw Error("LSP stream budget exceeded");
+            // Drain complete frames before admitting more bytes; OS chunk boundaries are arbitrary.
+            for (let offset = 0; offset < chunk.length;) {
+              const capacity = MAX_LSP_FRAME + MAX_LSP_HEADER + 4 - this.buffer.length;
+              if (capacity <= 0) throw Error("LSP receive buffer exceeded");
+              const part = chunk.subarray(offset, offset + capacity); offset += part.length;
+              const merged = new Uint8Array(this.buffer.length + part.length); merged.set(this.buffer); merged.set(part, this.buffer.length); this.buffer = merged;
+              for (;;) { const frame = nextLspFrame(this.buffer); if (!frame) break; this.buffer = this.buffer.slice(frame.consumed); this.receive(JSON.parse(new TextDecoder("utf8", { fatal: true }).decode(frame.body))); }
+            }
+          }
+          this.fail("LSP server exited");
+        } catch { this.fail("LSP protocol failed"); process.kill("SIGKILL"); }
+      })();
+      const result = await this.request("initialize", { processId: globalThis.process.pid, rootUri: pathToFileURL(this.root).href,
+        capabilities: { general: { positionEncodings: ["utf-16"] }, workspace: { applyEdit: false }, textDocument: { synchronization: { dynamicRegistration: false }, diagnostic: {} } },
+        workspaceFolders: [{ uri: pathToFileURL(this.root).href, name: this.config.name }] }, signal);
+      if (!result || typeof result !== "object" || Array.isArray(result) || !("capabilities" in result) || !result.capabilities || typeof result.capabilities !== "object") throw Error("invalid LSP initialize result");
+      const encoding = (result.capabilities as Record<string, unknown>)["positionEncoding"];
+      if (encoding !== undefined && encoding !== "utf-16") throw Error("LSP server does not support UTF-16 positions");
+      signal?.throwIfAborted();
+      this.notify("initialized", {});
+    })();
+    try { await this.ready; } catch (error) { this.fail(error instanceof Error ? error.message : "LSP initialization failed"); this.process?.kill("SIGKILL"); throw error; }
+  }
+  async call(action: string, path: string, line: number, character: number, signal?: AbortSignal): Promise<unknown> {
+    const document = await readLspDocument(this.root, path, signal);
+    await this.start(signal); signal?.throwIfAborted();
+    const old = this.documents.get(document.uri);
+    const changed = old !== undefined && old.sha256 !== document.sha256;
+    // Monotonic versions also prevent late diagnostics from an evicted/reopened file matching it.
+    const version = !old || changed ? ++this.documentVersion : old.version;
+    if (!old && this.documents.size >= MAX_LSP_OPEN_DOCUMENTS) {
+      const oldest = this.documents.keys().next().value;
+      if (oldest !== undefined) { this.notify("textDocument/didClose", { textDocument: { uri: oldest } }); this.documents.delete(oldest); this.diagnostics.delete(oldest); }
+    }
+    if (!old) this.notify("textDocument/didOpen", { textDocument: { uri: document.uri, languageId: this.config.languageId, version, text: document.text } });
+    else if (changed) { this.diagnostics.delete(document.uri); this.notify("textDocument/didChange", { textDocument: { uri: document.uri, version }, contentChanges: [{ text: document.text }] }); }
+    const current = version;
+    this.documents.set(document.uri, { sha256: document.sha256, version: current });
+    if (action === "diagnostics") {
+      try {
+        const result = await this.request("textDocument/diagnostic", { textDocument: { uri: document.uri } }, signal);
+        const onDisk = await readLspDocument(this.root, path, signal);
+        return { sha256: document.sha256, version: current, kind: "pull", freshness: onDisk.sha256 === document.sha256 ? "current" : "stale", result };
+      }
+      catch (error) {
+        signal?.throwIfAborted(); if (this.failure) throw Error(this.failure);
+        const observed = this.diagnostics.get(document.uri), onDisk = await readLspDocument(this.root, path, signal);
+        const freshness = onDisk.sha256 !== document.sha256 ? "stale" : observed ? diagnosticFreshness(observed.version, current) : "unavailable";
+        return { sha256: document.sha256, version: current, kind: "push", freshness, observedVersion: observed?.version ?? null,
+          available: freshness === "current", versionConfirmed: freshness === "current", diagnostics: freshness === "current" ? observed?.items ?? [] : [],
+          unconfirmedCount: freshness === "current" ? 0 : observed?.items.length ?? 0, reason: error instanceof Error ? error.message : "pull diagnostics unavailable" };
+      }
+    }
+    const methods: Record<string, string> = { hover: "textDocument/hover", definition: "textDocument/definition", references: "textDocument/references" };
+    const method = methods[action]; if (!method) throw Error("unsupported LSP action");
+    const result = await this.request(method, { textDocument: { uri: document.uri }, position: { line, character }, ...(action === "references" ? { context: { includeDeclaration: true } } : {}) }, signal);
+    const onDisk = await readLspDocument(this.root, path, signal);
+    return { sha256: document.sha256, version: current, freshness: onDisk.sha256 === document.sha256 ? "current" : "stale", result };
+  }
+  async dispose(): Promise<void> {
+    if (this.closed) return; this.closed = true;
+    if (this.process) {
+      try { await this.request("shutdown", null, undefined, 500); this.notify("exit", null); } catch { /* bounded shutdown falls back to kill */ }
+      // This process is client-owned. A server ignoring shutdown cannot leave a resident leak.
+      this.process.kill("SIGKILL"); await this.process.exited;
+    }
+    this.fail("LSP disposed"); this.documents.clear(); this.diagnostics.clear();
+  }
+}
+export class LspManager {
+  private readonly root: string;
+  private readonly configs: LspConfig[];
+  private readonly connections = new Map<string, LspConnection>();
+  private closed = false;
+  constructor(root: string, configs: LspConfig[]) { this.root = root; this.configs = configs.map(config => ({ ...config, command: [...config.command], extensions: [...config.extensions] })); }
+  tool(): ToolDefinition {
+    return { name: "lsp", description: "Read language-server diagnostics, hover, definitions or references for a current workspace file. Positions use zero-based UTF-16 units. Servers come from trusted explicit configuration.",
+      access: "read", branch: "none", execution: "exclusive", input_schema: { type: "object", required: ["action", "path"],
+        properties: { action: { type: "string", enum: ["diagnostics", "hover", "definition", "references"] }, path: { type: "string" }, line: { type: "integer", minimum: 0 }, character: { type: "integer", minimum: 0 }, server: { type: "string" } } },
+      run: async (ctx, input): Promise<ToolResult> => {
+        if (this.closed) throw Error("LSP manager disposed");
+        const selected = this.configs.filter(config => config.extensions.includes(extname(String(input["path"]))) && (input["server"] === undefined || config.name === input["server"]));
+        if (selected.length !== 1) return { ok: false, content: "Select exactly one configured language server for this file." };
+        const config = selected[0]!; let connection = this.connections.get(config.name);
+        if (!connection) { connection = new LspConnection(this.root, config); this.connections.set(config.name, connection); }
+        try {
+          const result = await connection.call(String(input["action"]), String(input["path"]), Number(input["line"] ?? 0), Number(input["character"] ?? 0), ctx.signal);
+          return { ok: true, ...await presentObservation(ctx, JSON.stringify(result)) };
+        } catch (error) { if (!connection.usable) this.connections.delete(config.name); throw error; }
+      } };
+  }
+  async dispose(): Promise<void> { this.closed = true; await Promise.all([...this.connections.values()].map(connection => connection.dispose())); this.connections.clear(); }
+}