patchwork-os 0.2.0-beta.0 → 0.2.0-beta.10

package/dist/drivers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/drivers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAkBpD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAgB,EAChB,IAAuB,EACvB,GAA0B;IAE1B,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,IAAI,KAAK,YAAY;QACvB,OAAO,IAAI,gBAAgB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAChE,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC;IAC9C,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC;IACvD,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC;IACnD,IAAI,IAAI,KAAK,QAAQ;QACnB,OAAO,IAAI,sBAAsB,CAC/B,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EACjD,GAAG,EACH,IAAI,CAAC,SAAS,CACf,CAAC;IACJ,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,EAAE,CAAC,CAAC;AAClD,CAAC;AAED,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAOpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/drivers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAoBpD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAgB,EAChB,IAAuB,EACvB,GAA0B;IAE1B,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,IAAI,KAAK,YAAY;QACvB,OAAO,IAAI,gBAAgB,CACzB,IAAI,CAAC,MAAM,EACX,IAAI,CAAC,SAAS,EACd,GAAG,EACH,IAAI,CAAC,SAAS,CACf,CAAC;IACJ,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC;IAC9C,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC;IACvD,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC;IACnD,IAAI,IAAI,KAAK,QAAQ;QACnB,OAAO,IAAI,sBAAsB,CAC/B,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EACjD,GAAG,EACH,IAAI,CAAC,SAAS,CACf,CAAC;IACJ,IAAI,IAAI,KAAK,YAAY;QAAE,OAAO,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC;IAC3D,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,cAAc,CAAC,GAAG,CAAC,CAAC;IACrD,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,EAAE,CAAC,CAAC;AAClD,CAAC;AAED,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAOpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}

package/dist/drivers/local/index.d.ts

@@ -0,0 +1,43 @@
+import { OpenAIApiDriver } from "../openai/index.js";
+/**
+ * Reject any LOCAL_ENDPOINT that doesn't resolve to loopback or RFC1918
+ * private space. The local driver streams the user prompt + context-file
+ * paths to whatever URL is set; if a malicious recipe (or a user pasting
+ * a phishy "free local LLM" link) sets `LOCAL_ENDPOINT=https://attacker/v1`,
+ * everything the local driver receives gets exfiltrated.
+ *
+ * Rule: hostname must be one of
+ *   - localhost / 127.0.0.1 / ::1
+ *   - RFC1918 private space (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
+ *   - link-local (169.254.0.0/16, fe80::/10)
+ *   - .local mDNS / .lan / .home / .internal suffixes
+ *
+ * To opt out (e.g. authorized remote inference cluster), the operator can
+ * set LOCAL_ENDPOINT_ALLOW_REMOTE=1 — explicit override, audited via env.
+ */
+export declare function isLoopbackOrPrivateEndpoint(rawUrl: string): boolean;
+/**
+ * Local LLM driver — Ollama, LM Studio, vLLM, llama.cpp server, and most
+ * other self-hosted runtimes expose an OpenAI-compatible chat-completions
+ * endpoint at /v1/chat/completions. Same trick as Grok / Gemini API:
+ * subclass OpenAIApiDriver with a different baseURL + default model.
+ *
+ * Auth: most local runtimes don't validate the API key, but the OpenAI SDK
+ * requires *something* in the apiKey field — we send a constant placeholder.
+ *
+ * Configuration: LOCAL_ENDPOINT and LOCAL_MODEL environment variables.
+ * The bridge auto-injects `patchwork.localEndpoint` / `patchwork.localModel`
+ * into these env vars at startup (see config.ts), so saving via the
+ * dashboard's Local LLM card flows straight through to the driver.
+ *
+ * Examples:
+ *   Ollama     → http://localhost:11434/v1
+ *   LM Studio  → http://localhost:1234/v1
+ *   vLLM       → http://localhost:8000/v1
+ *   llama.cpp  → http://localhost:8080/v1
+ */
+export declare class LocalApiDriver extends OpenAIApiDriver {
+    readonly name = "local";
+    constructor(log: (msg: string) => void);
+    protected apiKey(): string | undefined;
+}

package/dist/drivers/local/index.js

@@ -0,0 +1,140 @@
+import { OpenAIApiDriver } from "../openai/index.js";
+/**
+ * Reject any LOCAL_ENDPOINT that doesn't resolve to loopback or RFC1918
+ * private space. The local driver streams the user prompt + context-file
+ * paths to whatever URL is set; if a malicious recipe (or a user pasting
+ * a phishy "free local LLM" link) sets `LOCAL_ENDPOINT=https://attacker/v1`,
+ * everything the local driver receives gets exfiltrated.
+ *
+ * Rule: hostname must be one of
+ *   - localhost / 127.0.0.1 / ::1
+ *   - RFC1918 private space (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
+ *   - link-local (169.254.0.0/16, fe80::/10)
+ *   - .local mDNS / .lan / .home / .internal suffixes
+ *
+ * To opt out (e.g. authorized remote inference cluster), the operator can
+ * set LOCAL_ENDPOINT_ALLOW_REMOTE=1 — explicit override, audited via env.
+ */
+export function isLoopbackOrPrivateEndpoint(rawUrl) {
+    let host;
+    let wasBracketed = false;
+    try {
+        host = new URL(rawUrl).hostname.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+    if (!host)
+        return false;
+    // Strip IPv6 brackets if any
+    if (host.startsWith("[") && host.endsWith("]")) {
+        host = host.slice(1, -1);
+        wasBracketed = true;
+    }
+    if (host === "localhost" || host === "127.0.0.1" || host === "::1") {
+        return true;
+    }
+    // IPv4 RFC1918 + link-local + 127/8 (check first — strict literal match)
+    const v4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (v4) {
+        const a = Number(v4[1]);
+        const b = Number(v4[2]);
+        if (a === 10)
+            return true;
+        if (a === 127)
+            return true;
+        if (a === 169 && b === 254)
+            return true;
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+        return false;
+    }
+    // IPv6 ranges — only when the input looked like an IPv6 literal (was
+    // bracketed in the URL, or matches an IPv6 syntactic shape). Without this
+    // gate, a hostname like `fc-services.example.com` or `fe8a-test` would
+    // match the legacy `startsWith("fc")` / `startsWith("fe8")` checks and
+    // bypass the validator. RFC3986 allows IPv6 literals only inside `[…]`,
+    // so requiring the brackets is the conservative path.
+    if (wasBracketed || /^[0-9a-f:]+$/.test(host)) {
+        if (host.startsWith("fe8") ||
+            host.startsWith("fe9") ||
+            host.startsWith("fea") ||
+            host.startsWith("feb")) {
+            return true; // link-local fe80::/10
+        }
+        if (host.startsWith("fc") || host.startsWith("fd")) {
+            return true; // unique-local fc00::/7
+        }
+    }
+    // mDNS / common LAN suffixes — checked LAST and require a leading dot
+    // boundary so attacker-registered public domains like `evil.com.local`
+    // don't slip through (`.local` and `.lan` are not reserved TLDs at the
+    // DNS resolver level — only RFC6762 reserves them for mDNS, but public
+    // resolvers will happily look them up).
+    //
+    // The trade-off: a host literally named `printer.local` (single label
+    // before `.local`) is the legitimate mDNS form and matches; a host like
+    // `evil.com.local` (two-or-more labels before `.local`) is only the
+    // mDNS form by accident and is the bypass we're rejecting.
+    for (const suffix of [".local", ".lan", ".home", ".internal"]) {
+        if (host.endsWith(suffix)) {
+            const labels = host.split(".");
+            // 2 labels exactly: `<name>.local` — legitimate mDNS shape.
+            if (labels.length === 2)
+                return true;
+            // More labels: ambiguous — refuse by default. Operator can opt out
+            // via LOCAL_ENDPOINT_ALLOW_REMOTE for legitimate multi-label
+            // internal DNS zones (e.g. `service.team.internal`).
+        }
+    }
+    return false;
+}
+/**
+ * Local LLM driver — Ollama, LM Studio, vLLM, llama.cpp server, and most
+ * other self-hosted runtimes expose an OpenAI-compatible chat-completions
+ * endpoint at /v1/chat/completions. Same trick as Grok / Gemini API:
+ * subclass OpenAIApiDriver with a different baseURL + default model.
+ *
+ * Auth: most local runtimes don't validate the API key, but the OpenAI SDK
+ * requires *something* in the apiKey field — we send a constant placeholder.
+ *
+ * Configuration: LOCAL_ENDPOINT and LOCAL_MODEL environment variables.
+ * The bridge auto-injects `patchwork.localEndpoint` / `patchwork.localModel`
+ * into these env vars at startup (see config.ts), so saving via the
+ * dashboard's Local LLM card flows straight through to the driver.
+ *
+ * Examples:
+ *   Ollama     → http://localhost:11434/v1
+ *   LM Studio  → http://localhost:1234/v1
+ *   vLLM       → http://localhost:8000/v1
+ *   llama.cpp  → http://localhost:8080/v1
+ */
+export class LocalApiDriver extends OpenAIApiDriver {
+    name = "local";
+    constructor(log) {
+        const baseURL = process.env.LOCAL_ENDPOINT;
+        if (!baseURL) {
+            throw new Error("LocalApiDriver requires LOCAL_ENDPOINT environment variable (e.g. http://localhost:11434/v1)");
+        }
+        if (process.env.LOCAL_ENDPOINT_ALLOW_REMOTE !== "1" &&
+            !isLoopbackOrPrivateEndpoint(baseURL)) {
+            throw new Error(`LocalApiDriver: LOCAL_ENDPOINT="${baseURL}" is not loopback or private. ` +
+                `The local driver streams prompts + context to this URL — a public host ` +
+                `would exfiltrate them. Set LOCAL_ENDPOINT_ALLOW_REMOTE=1 to override ` +
+                `(only for audited internal inference clusters).`);
+        }
+        super(log, {
+            baseURL,
+            // Per-install default — caller can still override via input.model.
+            defaultModel: process.env.LOCAL_MODEL ?? "llama3.2",
+        });
+    }
+    apiKey() {
+        // Most local runtimes ignore the key but the OpenAI SDK requires a
+        // non-empty value. "ollama" is the conventional placeholder.
+        return process.env.LOCAL_API_KEY ?? "ollama";
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/drivers/local/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/drivers/local/index.ts"],"names":[],"mappings":"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"}

package/dist/drivers/openai/index.js

@@ -17,6 +17,16 @@ export class OpenAIApiDriver {
         if (!process.env.OPENAI_API_KEY && !opts.baseURL) {
             throw new Error("OpenAIApiDriver requires OPENAI_API_KEY environment variable");
         }
+        // Subclasses (Grok, Gemini, Local) MUST set their own defaultModel —
+        // a bare OpenAI driver defaults to gpt-4o here, but a subclass that
+        // overrides baseURL without defaultModel would otherwise silently dial
+        // the foreign endpoint asking for gpt-4o (which doesn't exist on Grok,
+        // Gemini, or local LLMs) and surface as a confusing 404 / phantom-model
+        // error far from the actual misconfiguration.
+        if (opts.baseURL && !opts.defaultModel) {
+            throw new Error("OpenAIApiDriver: subclass must set defaultModel when baseURL is " +
+                "overridden — bare 'gpt-4o' fallback only applies to OpenAI's API.");
+        }
     }
     async run(input) {
         // biome-ignore lint/suspicious/noExplicitAny: dynamic import of optional peer dep
@@ -71,10 +81,28 @@ export class OpenAIApiDriver {
                 if (delta) {
                     if (firstChunkAt === undefined)
                         firstChunkAt = Date.now();
-                    text += delta;
-                    if (text.length <= OUTPUT_CAP) {
+                    if (text.length < OUTPUT_CAP) {
+                        // Cap accumulation in-loop to bound memory under runaway streams
+                        // (e.g. local LLMs that loop). Once we hit the cap, stop appending
+                        // and abort the upstream stream so sockets and decoder buffers
+                        // are released. onChunk is gated by the same cap so partial
+                        // listeners stop receiving deltas.
+                        text += delta;
                         input.onChunk?.(delta);
                     }
+                    else {
+                        // biome-ignore lint/suspicious/noExplicitAny: stream shape
+                        const ctrl = stream.controller;
+                        if (ctrl && typeof ctrl.abort === "function") {
+                            try {
+                                ctrl.abort();
+                            }
+                            catch {
+                                /* best effort */
+                            }
+                        }
+                        break;
+                    }
                 }
             }
         }

package/dist/drivers/openai/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/drivers/openai/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/drivers/openai/index.ts"],"names":[],"mappings":"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"}

package/dist/extensionClient.d.ts

@@ -154,6 +154,15 @@ export declare class ExtensionClient {
      * for that, do a runtime shape check in the client method.
      */
     private tryRequest;
+    /**
+     * Like tryRequest, but preserves the extension error message instead of
+     * collapsing it to null. Use when the caller wants to surface the upstream
+     * error (e.g. report "format provider errored: X" instead of silently
+     * falling back to a CLI tool). Returns an envelope so the success-path
+     * value is still typed and the historical `value === null` check works
+     * unchanged.
+     */
+    private tryRequestWithError;
     /**
      * Shape-validated request — handles shape-wrap bugs where the extension
      * handler returns a different structural shape than the client expects
@@ -191,7 +200,11 @@ export declare class ExtensionClient {
     getHover(file: string, line: number, column: number, signal?: AbortSignal): Promise<unknown>;
     getCodeActions(file: string, startLine: number, startColumn: number, endLine: number, endColumn: number, signal?: AbortSignal): Promise<unknown>;
     applyCodeAction(file: string, startLine: number, startColumn: number, endLine: number, endColumn: number, actionTitle: string, signal?: AbortSignal): Promise<unknown>;
-    previewCodeAction(file: string, startLine: number, startColumn: number, endLine: number, endColumn: number, actionTitle: string, signal?: AbortSignal): Promise<unknown>;
+    previewCodeAction(file: string, startLine: number, startColumn: number, endLine: number, endColumn: number, actionTitle: string, signal?: AbortSignal): Promise<{
+        value: unknown;
+        error: string | null;
+        errorData: Record<string, unknown> | null;
+    }>;
     renameSymbol(file: string, line: number, column: number, newName: string, signal?: AbortSignal): Promise<unknown>;
     searchSymbols(query: string, maxResults?: number, signal?: AbortSignal): Promise<unknown>;
     prepareRename(file: string, line: number, column: number, signal?: AbortSignal): Promise<unknown>;
@@ -215,9 +228,21 @@ export declare class ExtensionClient {
     replaceBlock(filePath: string, oldContent: string, newContent: string, save?: boolean): Promise<unknown>;
     getDocumentSymbols(file: string, signal?: AbortSignal): Promise<unknown>;
     getCallHierarchy(file: string, line: number, column: number, direction?: string, maxResults?: number, signal?: AbortSignal): Promise<unknown>;
-    formatDocument(file: string): Promise<unknown>;
-    fixAllLintErrors(file: string): Promise<unknown>;
-    organizeImports(file: string): Promise<unknown>;
+    formatDocument(file: string): Promise<{
+        value: unknown;
+        error: string | null;
+        errorData: Record<string, unknown> | null;
+    }>;
+    fixAllLintErrors(file: string): Promise<{
+        value: unknown;
+        error: string | null;
+        errorData: Record<string, unknown> | null;
+    }>;
+    organizeImports(file: string): Promise<{
+        value: unknown;
+        error: string | null;
+        errorData: Record<string, unknown> | null;
+    }>;
     createTerminal(name?: string, cwd?: string, env?: Record<string, string>, show?: boolean): Promise<unknown>;
     sendTerminalCommand(text: string, name?: string, index?: number, addNewline?: boolean): Promise<unknown>;
     waitForTerminalOutput(pattern: string, name?: string, index?: number, timeoutMs?: number): Promise<unknown>;
@@ -269,6 +294,14 @@ export declare class ExtensionClient {
         openCount: number;
         lastOpenedAt: string | null;
     };
+    /**
+     * Tracks whether the connected extension has a protocol-major-version
+     * mismatch with the bridge. When set, `isConnected()` returns false so
+     * `extensionRequired` tools fail fast with a clear "extension protocol
+     * mismatch" error instead of attempting requests that would silently
+     * misbehave (e.g. handler accepting a v1 shape but bridge sending v2).
+     */
+    private extensionProtocolMismatch;
     isConnected(): boolean;
     /**
      * Push a server-initiated notification to the connected extension.

package/dist/extensionClient.js

@@ -144,6 +144,9 @@ export class ExtensionClient {
             this.diagnosticsListeners.clear();
             // Clear LSP readiness — language servers may need to re-index after reconnect
             this.lspReadyLanguages.clear();
+            // Reset protocol-mismatch flag so a fresh hello on reconnect can
+            // re-evaluate compatibility (operator may have updated the extension).
+            this.extensionProtocolMismatch = false;
             this.logger.info(`Extension disconnected: ${reason}`);
             this.safeCallback(this.onExtensionDisconnected);
         };
@@ -326,9 +329,20 @@ export class ExtensionClient {
                 const bridgeMajor = Number.parseInt(BRIDGE_PROTOCOL_VERSION.split(".")[0] ?? "", 10);
                 if (Number.isNaN(extMajor)) {
                     this.logger.debug(`Extension protocol version "${extVer}" is not a recognized semver format, skipping version check`);
+                    this.extensionProtocolMismatch = false;
                 }
                 else if (extMajor !== bridgeMajor) {
-                    this.logger.warn(`Extension protocol major version mismatch: bridge=${BRIDGE_PROTOCOL_VERSION}, extension=${extVer}. Consider updating.`);
+                    // Mark the extension as unavailable. Without this, the bridge
+                    // would proceed sending requests of one protocol-major to a
+                    // handler of another, surfacing as opaque field-shape errors
+                    // far from the actual cause. `extensionRequired` tools fail
+                    // fast with a clear isError content block.
+                    this.logger.error(`Extension protocol major version mismatch: bridge=${BRIDGE_PROTOCOL_VERSION}, extension=${extVer}. ` +
+                        `Marking extension as unavailable. Update the VS Code extension to a build whose protocolVersion major matches the bridge.`);
+                    this.extensionProtocolMismatch = true;
+                }
+                else {
+                    this.extensionProtocolMismatch = false;
                 }
                 break;
             }
@@ -658,6 +672,23 @@ export class ExtensionClient {
             return null;
         return raw;
     }
+    /**
+     * Like tryRequest, but preserves the extension error message instead of
+     * collapsing it to null. Use when the caller wants to surface the upstream
+     * error (e.g. report "format provider errored: X" instead of silently
+     * falling back to a CLI tool). Returns an envelope so the success-path
+     * value is still typed and the historical `value === null` check works
+     * unchanged.
+     */
+    async tryRequestWithError(method, params, timeout, signal) {
+        const raw = await this.requestOrNull(method, params, timeout, signal);
+        if (this.isErrorResponse(raw)) {
+            const obj = raw;
+            const msg = typeof obj.error === "string" ? obj.error : "extension error";
+            return { value: null, error: msg, errorData: obj };
+        }
+        return { value: raw, error: null, errorData: null };
+    }
     /**
      * Shape-validated request — handles shape-wrap bugs where the extension
      * handler returns a different structural shape than the client expects
@@ -781,7 +812,7 @@ export class ExtensionClient {
         return this.validatedRequest("extension/getHover", { file, line, column }, (r) => {
             const o = r;
             return Array.isArray(o.contents) ? r : null;
-        }, undefined, signal);
+        }, 12_000, signal);
     }
     // handler returns { actions: [{title, kind?, isPreferred}] } — validated
     async getCodeActions(file, startLine, startColumn, endLine, endColumn, signal) {
@@ -797,9 +828,10 @@ export class ExtensionClient {
             return typeof o.applied === "boolean" ? r : null;
         }, undefined, signal);
     }
-    // handler returns { title, changes, ... } | { error } — tryRequest (error-obj on failure)
+    // handler returns { title, changes, ... } | { error, available? } — preserve error so
+    // callers can include the upstream message (and `available` list) in their failure reply
     async previewCodeAction(file, startLine, startColumn, endLine, endColumn, actionTitle, signal) {
-        return this.tryRequest("extension/previewCodeAction", { file, startLine, startColumn, endLine, endColumn, actionTitle }, 15_000, signal);
+        return this.tryRequestWithError("extension/previewCodeAction", { file, startLine, startColumn, endLine, endColumn, actionTitle }, 15_000, signal);
     }
     // handler returns { success, newName?, affectedFiles?, totalEdits?, error? } — rich contract, caller needs success field
     async renameSymbol(file, line, column, newName, signal) {
@@ -924,7 +956,7 @@ export class ExtensionClient {
         return this.validatedRequest("extension/getDocumentSymbols", { file }, (r) => {
             const o = r;
             return Array.isArray(o.symbols) ? r : null;
-        }, undefined, signal);
+        }, 15_000, signal);
     }
     // handler returns { symbol, incoming?, outgoing? } | null — validated
     async getCallHierarchy(file, line, column, direction, maxResults, signal) {
@@ -934,20 +966,17 @@ export class ExtensionClient {
         }, 15_000, signal);
     }
     // --- Code Actions (format, fix, organize) ---
+    // Extension returns { error: "..." } on failure. Envelope preserves the
+    // error string so callers can surface it before falling back to a CLI tool
+    // (previously the message was silently dropped — see [extension-shape] audit).
     async formatDocument(file) {
-        // Extension returns { error: "..." } when the format command fails.
-        // tryRequest unwraps to null so consumers' `!== null` check falls through
-        // to their CLI formatter fallback instead of reporting false success.
-        return this.tryRequest("extension/formatDocument", { file }, 15_000);
+        return this.tryRequestWithError("extension/formatDocument", { file }, 15_000);
     }
     async fixAllLintErrors(file) {
-        // Extension returns { error: "..." } on command failure. tryRequest
-        // unwraps to null so consumers fall through to their CLI fallback.
-        return this.tryRequest("extension/fixAllLintErrors", { file }, 15_000);
+        return this.tryRequestWithError("extension/fixAllLintErrors", { file }, 15_000);
     }
-    // handler returns { success: true, actionsApplied } | { error } — tryRequest (error-obj on failure)
     async organizeImports(file) {
-        return this.tryRequest("extension/organizeImports", { file }, 15_000);
+        return this.tryRequestWithError("extension/organizeImports", { file }, 15_000);
     }
     // --- Terminal Control ---
     // handler returns { success: true, name, index } — validatedRequest
@@ -1177,7 +1206,12 @@ export class ExtensionClient {
                 this.latestDiagnosticsUpdatedAt.delete(f);
             }
         }
-        return Array.from(this.latestDiagnostics.values()).flat();
+        const result = [];
+        for (const diags of this.latestDiagnostics.values()) {
+            for (const d of diags)
+                result.push(d);
+        }
+        return result;
     }
     addDiagnosticsListener(listener) {
         this.diagnosticsListeners.add(listener);
@@ -1226,8 +1260,16 @@ export class ExtensionClient {
             lastOpenedAt: this._lastCircuitOpenedAt?.toISOString() ?? null,
         };
     }
+    /**
+     * Tracks whether the connected extension has a protocol-major-version
+     * mismatch with the bridge. When set, `isConnected()` returns false so
+     * `extensionRequired` tools fail fast with a clear "extension protocol
+     * mismatch" error instead of attempting requests that would silently
+     * misbehave (e.g. handler accepting a v1 shape but bridge sending v2).
+     */
+    extensionProtocolMismatch = false;
     isConnected() {
-        return this.connected;
+        return this.connected && !this.extensionProtocolMismatch;
     }
     /**
      * Push a server-initiated notification to the connected extension.