@chances-ai/engine 24.0.0

package/dist/lsp/rpc.js

@@ -0,0 +1,134 @@
+/**
+ * (4.2) RPC layer with per-request ownership.
+ *
+ *  Wraps a `vscode-jsonrpc` MessageConnection with a per-instance
+ *  `pending` map. Every `sendRequest`:
+ *    1. Registers a pending entry BEFORE the wire write so a concurrent
+ *       crash can `rejectAll` deterministically.
+ *    2. Drives cancellation via a vscode-jsonrpc `CancellationToken`
+ *       (codex Round-2 MUST-FIX #2 — using a synthetic id sent in
+ *       `$/cancelRequest` would target the WRONG request because
+ *       vscode-jsonrpc owns the wire-level id internally). `signal`
+ *       aborts and timeouts both `cancel()` the token; vscode-jsonrpc
+ *       emits the correct `$/cancelRequest` itself.
+ *    3. On response / error / timeout / cancel: removes the entry.
+ *
+ *  Tests provide a `FakeConnection` that satisfies the small
+ *  `Connection` shape; the `token` parameter is optional so fakes
+ *  don't need to ship a CancellationToken implementation.
+ */
+import { AppError, ErrorCode } from "@chances-ai/runtime";
+import { LspError } from "./errors.js";
+/** Tracks in-flight requests for an LSP instance. One per
+ *  LspServerInstance. */
+export class PendingRegistry {
+    entries = new Map();
+    nextId = 1;
+    /** Optional factory for cancellation token sources. Set by
+     *  `LspServerInstance` when it knows vscode-jsonrpc is loaded; null
+     *  in tests so the FakeConnection path stays simple. */
+    ctsFactory;
+    setCancellationFactory(factory) {
+        this.ctsFactory = factory;
+    }
+    get activeRequests() {
+        return this.entries.size;
+    }
+    /** Issues a request through the underlying connection, registering
+     *  ownership BEFORE the wire write so cancellation is always safe.
+     *  Cancellation propagates through the optional CancellationToken so
+     *  vscode-jsonrpc emits `$/cancelRequest` with the correct id. */
+    async send(opts) {
+        const { connection, method, params, signal, requestTimeoutMs } = opts;
+        if (signal.aborted)
+            throw new AppError(ErrorCode.Cancelled, "lsp request cancelled before send");
+        const id = this.nextId++;
+        let abortListener;
+        let timer;
+        let entryReject;
+        let settled = false;
+        const cts = this.ctsFactory?.();
+        const cleanup = () => {
+            if (settled)
+                return;
+            settled = true;
+            this.entries.delete(id);
+            if (abortListener)
+                signal.removeEventListener("abort", abortListener);
+            if (timer !== undefined)
+                clearTimeout(timer);
+            try {
+                cts?.dispose();
+            }
+            catch { /* ignore */ }
+        };
+        const entry = {
+            id,
+            method,
+            startedAt: Date.now(),
+            reject: (err) => {
+                if (entryReject)
+                    entryReject(err);
+            },
+            cleanup,
+            cts,
+        };
+        this.entries.set(id, entry);
+        return new Promise((resolve, reject) => {
+            entryReject = (err) => {
+                cleanup();
+                reject(err);
+            };
+            abortListener = () => {
+                // Use the token path so vscode-jsonrpc emits $/cancelRequest with
+                // the correct wire-level id. No `connection.sendNotification`
+                // anywhere — the previous implementation invented an id that
+                // didn't correspond to any real in-flight request.
+                try {
+                    cts?.cancel();
+                }
+                catch { /* ignore */ }
+                entryReject?.(new AppError(ErrorCode.Cancelled, `lsp ${method} cancelled`));
+            };
+            signal.addEventListener("abort", abortListener, { once: true });
+            timer = setTimeout(() => {
+                try {
+                    cts?.cancel();
+                }
+                catch { /* ignore */ }
+                entryReject?.(new LspError("REQUEST_TIMEOUT", `lsp ${method} timed out after ${requestTimeoutMs}ms`));
+            }, requestTimeoutMs);
+            void connection.sendRequest(method, params, cts?.token).then((value) => {
+                if (settled)
+                    return;
+                cleanup();
+                resolve(value);
+            }, (err) => {
+                if (settled)
+                    return;
+                cleanup();
+                reject(err);
+            });
+        });
+    }
+    /** Rejects every pending request with `cause`. Used on connection
+     *  close so a subsequent restart can never resurrect a stale id.
+     *  (codex Round-1 MUST-FIX #5.) */
+    rejectAll(cause) {
+        const entries = Array.from(this.entries.values());
+        this.entries.clear();
+        for (const entry of entries) {
+            try {
+                entry.cts?.cancel();
+            }
+            catch { /* ignore */ }
+            try {
+                entry.reject(cause);
+            }
+            catch {
+                /* listener already detached; swallow */
+            }
+        }
+    }
+}
+//# sourceMappingURL=rpc.js.map

package/dist/lsp/rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../../src/lsp/rpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAoCvC;yBACyB;AACzB,MAAM,OAAO,eAAe;IACT,OAAO,GAAG,IAAI,GAAG,EAAwB,CAAC;IACnD,MAAM,GAAG,CAAC,CAAC;IACnB;;4DAEwD;IAChD,UAAU,CAAiC;IAEnD,sBAAsB,CAAC,OAAoD;QACzE,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC;IAC5B,CAAC;IAED,IAAI,cAAc;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED;;;sEAGkE;IAClE,KAAK,CAAC,IAAI,CAAI,IAMb;QACC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC;QACtE,IAAI,MAAM,CAAC,OAAO;YAAE,MAAM,IAAI,QAAQ,CAAC,SAAS,CAAC,SAAS,EAAE,mCAAmC,CAAC,CAAC;QAEjG,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACzB,IAAI,aAAuC,CAAC;QAC5C,IAAI,KAAgD,CAAC;QACrD,IAAI,WAA+C,CAAC;QACpD,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;QAEhC,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACxB,IAAI,aAAa;gBAAE,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;YACtE,IAAI,KAAK,KAAK,SAAS;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YAC7C,IAAI,CAAC;gBAAC,GAAG,EAAE,OAAO,EAAE,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;QAChD,CAAC,CAAC;QAEF,MAAM,KAAK,GAAiB;YAC1B,EAAE;YACF,MAAM;YACN,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,MAAM,EAAE,CAAC,GAAU,EAAE,EAAE;gBACrB,IAAI,WAAW;oBAAE,WAAW,CAAC,GAAG,CAAC,CAAC;YACpC,CAAC;YACD,OAAO;YACP,GAAG;SACJ,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QAE5B,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACxC,WAAW,GAAG,CAAC,GAAG,EAAE,EAAE;gBACpB,OAAO,EAAE,CAAC;gBACV,MAAM,CAAC,GAAG,CAAC,CAAC;YACd,CAAC,CAAC;YAEF,aAAa,GAAG,GAAG,EAAE;gBACnB,kEAAkE;gBAClE,8DAA8D;gBAC9D,6DAA6D;gBAC7D,mDAAmD;gBACnD,IAAI,CAAC;oBAAC,GAAG,EAAE,MAAM,EAAE,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;gBAC7C,WAAW,EAAE,CAAC,IAAI,QAAQ,CAAC,SAAS,CAAC,SAAS,EAAE,OAAO,MAAM,YAAY,CAAC,CAAC,CAAC;YAC9E,CAAC,CAAC;YACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAEhE,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBACtB,IAAI,CAAC;oBAAC,GAAG,EAAE,MAAM,EAAE,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;gBAC7C,WAAW,EAAE,CAAC,IAAI,QAAQ,CAAC,iBAAiB,EAAE,OAAO,MAAM,oBAAoB,gBAAgB,IAAI,CAAC,CAAC,CAAC;YACxG,CAAC,EAAE,gBAAgB,CAAC,CAAC;YAErB,KAAK,UAAU,CAAC,WAAW,CAAI,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,IAAI,CAC7D,CAAC,KAAK,EAAE,EAAE;gBACR,IAAI,OAAO;oBAAE,OAAO;gBACpB,OAAO,EAAE,CAAC;gBACV,OAAO,CAAC,KAAK,CAAC,CAAC;YACjB,CAAC,EACD,CAAC,GAAG,EAAE,EAAE;gBACN,IAAI,OAAO;oBAAE,OAAO;gBACpB,OAAO,EAAE,CAAC;gBACV,MAAM,CAAC,GAAG,CAAC,CAAC;YACd,CAAC,CACF,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;uCAEmC;IACnC,SAAS,CAAC,KAAY;QACpB,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC;YACtB,CAAC;YAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;YACxB,IAAI,CAAC;gBACH,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;YAAC,MAAM,CAAC;gBACP,wCAAwC;YAC1C,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/lsp/safe-uri.d.ts

@@ -0,0 +1,18 @@
+export interface ContainResult {
+    /** Resolved absolute path (realpath when extant). */
+    abs: string;
+    /** Path relative to `workspaceRoot`, or undefined when outside. */
+    rel?: string;
+    /** True when `abs` resolves OUTSIDE `workspaceRoot`. */
+    external: boolean;
+}
+/** Converts a `file://` URI (or absolute path) to a safe-containment
+ *  triple. Symlinks inside the workspace are resolved through
+ *  `realpath` so a symlink-to-outside is caught. Non-extant leaves
+ *  walk up to the nearest existing ancestor (matches the `safePath`
+ *  pattern in `_shared.ts`) so a path like `<ws>/does-not-exist.ts`
+ *  on a symlinked tmpdir resolves correctly. */
+export declare function containUri(uri: string, workspaceRoot: string): ContainResult;
+/** For navigable results — returns the relative path or `null`. */
+export declare function containLocationUri(uri: string, workspaceRoot: string): string | null;
+//# sourceMappingURL=safe-uri.d.ts.map

package/dist/lsp/safe-uri.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-uri.d.ts","sourceRoot":"","sources":["../../src/lsp/safe-uri.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;gDAKgD;AAChD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,aAAa,CAe5E;AAwCD,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGpF"}

package/dist/lsp/safe-uri.js

@@ -0,0 +1,96 @@
+/**
+ * (4.2) URI containment for server-returned locations
+ *  (codex Round-1 MUST-FIX #3).
+ *
+ *  LSP servers can return arbitrary `file://` URIs in `Location`,
+ *  `LocationLink`, `SymbolInformation`, and `CallHierarchyItem`.
+ *  We must NOT format those directly as relative paths: in a
+ *  worktree-isolated session a server rooted at the worktree can
+ *  still return a path outside the worktree via symlinks, generated
+ *  metadata, shared git storage, or external library indexes.
+ *
+ *  Two helpers:
+ *    - `containLocationUri` — for navigable results
+ *      (`goToDefinition`/`findReferences`/`goToImplementation`/
+ *      `workspaceSymbol` location-class). Returns `null` when
+ *      outside; caller drops or counts as `[omitted]`.
+ *    - `markExternalUri` — for `documentSymbol` /
+ *      `prepareCallHierarchy` / `incomingCalls` / `outgoingCalls`
+ *      where dropping silently would hide answers. Returns the
+ *      absolute path and a boolean `external: true` so the
+ *      formatter can prepend `[external]`.
+ */
+import { lstatSync, readlinkSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const SYMLINK_RESOLVE_MAX_DEPTH = 8;
+/** Converts a `file://` URI (or absolute path) to a safe-containment
+ *  triple. Symlinks inside the workspace are resolved through
+ *  `realpath` so a symlink-to-outside is caught. Non-extant leaves
+ *  walk up to the nearest existing ancestor (matches the `safePath`
+ *  pattern in `_shared.ts`) so a path like `<ws>/does-not-exist.ts`
+ *  on a symlinked tmpdir resolves correctly. */
+export function containUri(uri, workspaceRoot) {
+    const raw = uri.startsWith("file://") ? fileURLToPath(uri) : uri;
+    const absInput = isAbsolute(raw) ? raw : resolve(workspaceRoot, raw);
+    const absReal = realpathExtant(absInput);
+    let rootReal;
+    try {
+        rootReal = realpathSync(workspaceRoot);
+    }
+    catch {
+        rootReal = workspaceRoot;
+    }
+    const rel = relative(rootReal, absReal);
+    const external = rel.startsWith("..") || isAbsolute(rel);
+    return external
+        ? { abs: absReal, external: true }
+        : { abs: absReal, rel, external: false };
+}
+/** Realpath a path that may not exist. Handles dangling symlinks at
+ *  the leaf the same way `packages/tools/src/builtins/_shared.ts`
+ *  does (4.1 Round-2 MUST-FIX #3): `lstat` first so a leaf-symlink
+ *  whose target doesn't exist still gets resolved through
+ *  `readlink` and re-checked, otherwise `realpathSync` would throw
+ *  ENOENT and we'd treat a path that POSIX will later follow as if
+ *  it were lexically contained. */
+function realpathExtant(p, depth = 0) {
+    try {
+        const lst = lstatSync(p);
+        if (lst.isSymbolicLink()) {
+            if (depth >= SYMLINK_RESOLVE_MAX_DEPTH)
+                return p;
+            const target = readlinkSync(p);
+            const resolved = isAbsolute(target) ? target : resolve(dirname(p), target);
+            return realpathExtant(resolved, depth + 1);
+        }
+    }
+    catch {
+        /* lstat ENOENT — fall through to the walk-up below. */
+    }
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        /* fall through */
+    }
+    let current = dirname(p);
+    let tail = p.slice(current.length);
+    while (current !== dirname(current)) {
+        try {
+            const real = realpathSync(current);
+            return join(real, tail);
+        }
+        catch {
+            tail = current.slice(dirname(current).length) + tail;
+            current = dirname(current);
+        }
+    }
+    return p;
+}
+/** For navigable results — returns the relative path or `null`. */
+export function containLocationUri(uri, workspaceRoot) {
+    const r = containUri(uri, workspaceRoot);
+    return r.external ? null : r.rel ?? null;
+}
+//# sourceMappingURL=safe-uri.js.map

package/dist/lsp/safe-uri.js.map

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

package/dist/lsp/types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * (4.2) LSP package types — kept narrow and JSON-serialisable so config and
+ * runtime can round-trip them without coupling to vscode-languageserver-protocol.
+ */
+/** One language-server entry. Identical shape to `LspServerConfig` in
+ * `@chances-ai/config` — re-declared here to keep the lsp package
+ * boundary-clean (importing the type from `@chances-ai/config` is
+ * allowed at the value layer too). */
+export interface LspServerConfig {
+    command: string;
+    args?: readonly string[];
+    extensions: readonly string[];
+    env?: Record<string, string>;
+    initializationOptions?: unknown;
+    startupTimeoutMs?: number;
+    maxRestarts?: number;
+    enabled?: boolean;
+    /** Per-instance LRU cap on opened documents. Default 64. */
+    maxOpenDocs?: number;
+}
+/** Resolved server entry with its key. Identity inside the manager. */
+export interface ResolvedServer {
+    /** Short user-facing name, e.g. "typescript". Stable for cache keys
+     *  and permission summaries. */
+    name: string;
+    config: LspServerConfig;
+    /** Absolute resolved binary path (set when detection succeeds);
+     *  undefined when binary not found on PATH or in project-local bin
+     *  dirs (`BINARY_MISSING` at execute time). */
+    resolvedCommand?: string;
+}
+export type LspOp = "goToDefinition" | "findReferences" | "hover" | "documentSymbol" | "workspaceSymbol" | "goToImplementation" | "prepareCallHierarchy" | "incomingCalls" | "outgoingCalls";
+export declare const ALL_OPS: readonly LspOp[];
+/** Input shape passed from the tool wrapper to `LspHost.execute`. The
+ *  union is intentionally loose at the type level — the host narrows
+ *  on `op` and validates per-op. */
+export interface LspOpRequest {
+    op: LspOp;
+    filePath?: string;
+    line?: number;
+    character?: number;
+    query?: string;
+    cwd: string;
+    signal: AbortSignal;
+}
+/** What the wrapper returns — same shape as `ToolResult` so the
+ *  wrapper can forward it without re-wrapping. */
+export interface LspOpResult {
+    ok: boolean;
+    output: string;
+}
+/** Logger shape — subset of `@chances-ai/runtime`'s Logger. */
+export interface Logger {
+    debug(msg: string): void;
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+/** Permission resolver shape — the host calls this once per
+ *  `(serverName, command, cwd)` and caches the answer for the
+ *  session. */
+export interface LspPermissionResolver {
+    (req: {
+        serverName: string;
+        command: string;
+        args: readonly string[];
+        cwd: string;
+    }): Promise<boolean>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/lsp/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lsp/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;sCAGsC;AACtC,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B;oCACgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,eAAe,CAAC;IACxB;;mDAE+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,KAAK,GACb,gBAAgB,GAChB,gBAAgB,GAChB,OAAO,GACP,gBAAgB,GAChB,iBAAiB,GACjB,oBAAoB,GACpB,sBAAsB,GACtB,eAAe,GACf,eAAe,CAAC;AAEpB,eAAO,MAAM,OAAO,EAAE,SAAS,KAAK,EAUnC,CAAC;AAEF;;oCAEoC;AACpC,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,KAAK,CAAC;IACV,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;kDACkD;AAClD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,+DAA+D;AAC/D,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;eAEe;AACf,MAAM,WAAW,qBAAqB;IACpC,CAAC,GAAG,EAAE;QACJ,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;QACxB,GAAG,EAAE,MAAM,CAAC;KACb,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB"}

package/dist/lsp/types.js

@@ -0,0 +1,16 @@
+/**
+ * (4.2) LSP package types — kept narrow and JSON-serialisable so config and
+ * runtime can round-trip them without coupling to vscode-languageserver-protocol.
+ */
+export const ALL_OPS = [
+    "goToDefinition",
+    "findReferences",
+    "hover",
+    "documentSymbol",
+    "workspaceSymbol",
+    "goToImplementation",
+    "prepareCallHierarchy",
+    "incomingCalls",
+    "outgoingCalls",
+];
+//# sourceMappingURL=types.js.map

package/dist/lsp/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/lsp/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA0CH,MAAM,CAAC,MAAM,OAAO,GAAqB;IACvC,gBAAgB;IAChB,gBAAgB;IAChB,OAAO;IACP,gBAAgB;IAChB,iBAAiB;IACjB,oBAAoB;IACpB,sBAAsB;IACtB,eAAe;IACf,eAAe;CAChB,CAAC"}

package/dist/mcp/bridge.d.ts

@@ -0,0 +1,57 @@
+import type { JSONValue } from "@chances-ai/runtime";
+import type { Tool } from "../tools/index.js";
+import { type ToolAnnotations } from "./category.js";
+import { type McpContentPart } from "./content.js";
+export type { McpContentPart };
+/**
+ * Subset of the MCP `Tool` descriptor we actually consume. Defining it locally
+ * keeps `bridge.ts` decoupled from `@modelcontextprotocol/sdk` — tests
+ * construct one with a plain object, no SDK import needed.
+ */
+export interface McpToolDescriptor {
+    name: string;
+    description?: string;
+    /** JSON Schema for the args object. */
+    inputSchema?: JSONValue;
+    annotations?: ToolAnnotations | null;
+}
+/** What the bridge calls when the model invokes a wrapped tool. The host
+ * supplies an adapter around the live MCP `Client`; tests supply a fake. */
+export interface McpCallToolClient {
+    callTool(name: string, args: Record<string, unknown>, opts: {
+        signal: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<McpCallToolResult>;
+}
+/** Subset of the MCP `CallToolResult` we surface to the engine. */
+export interface McpCallToolResult {
+    content?: ReadonlyArray<McpContentPart>;
+    isError?: boolean;
+}
+export interface BridgeOptions {
+    /** Per-server config-supplied default; falls through to 30 000 ms. */
+    defaultTimeoutMs?: number;
+    /**
+     * Optional scrubber for error messages. Server hosts supply one bound to
+     * the per-server secret bag (env values, header values, URL userinfo) so
+     * any SDK error that quotes back the bearer token or env var does not
+     * reach the bus / tool result.
+     */
+    redact?: (message: string) => string;
+}
+/**
+ * Wraps a single MCP tool as a chances `Tool` the engine can dispatch.
+ *
+ * Naming: `mcp__<serverId>__<toolName>` (double underscore, claude-code
+ * convention). Both segments are normalized via `sanitizeMcpName` so the
+ * resulting name is safe to thread through provider APIs that restrict tool
+ * names to `[A-Za-z0-9_-]`.
+ */
+export declare function bridgeMcpTool(serverId: string, descriptor: McpToolDescriptor, client: McpCallToolClient, options?: BridgeOptions): Tool;
+/**
+ * MCP spec allows alphanumerics + underscore in tool names; provider APIs
+ * sometimes also reject dashes mid-name. Conservative: keep `[A-Za-z0-9_]`,
+ * everything else collapses to `_`. Consecutive `_` collapse to one.
+ */
+export declare function sanitizeMcpName(raw: string): string;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/mcp/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../src/mcp/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,KAAK,eAAe,EAA2B,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,cAAc,CAAC;AAI1E,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,WAAW,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CACtC;AAED;4EAC4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,EAAE;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAChD,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC/B;AAED,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,iBAAiB,EAC7B,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,aAAkB,GAC1B,IAAI,CAiDN;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/mcp/bridge.js

@@ -0,0 +1,98 @@
+import { AppError, ErrorCode } from "@chances-ai/runtime";
+import { categoryFromAnnotations } from "./category.js";
+import { renderMcpContentParts } from "./content.js";
+/**
+ * Wraps a single MCP tool as a chances `Tool` the engine can dispatch.
+ *
+ * Naming: `mcp__<serverId>__<toolName>` (double underscore, claude-code
+ * convention). Both segments are normalized via `sanitizeMcpName` so the
+ * resulting name is safe to thread through provider APIs that restrict tool
+ * names to `[A-Za-z0-9_-]`.
+ */
+export function bridgeMcpTool(serverId, descriptor, client, options = {}) {
+    const sanitizedServer = sanitizeMcpName(serverId);
+    const sanitizedTool = sanitizeMcpName(descriptor.name);
+    const name = `mcp__${sanitizedServer}__${sanitizedTool}`;
+    const category = categoryFromAnnotations(descriptor.annotations);
+    const description = descriptor.description
+        ? `[mcp:${serverId}] ${descriptor.description}`
+        : `[mcp:${serverId}] tool ${descriptor.name}`;
+    const parameters = sanitizeInputSchema(descriptor.inputSchema);
+    return {
+        name,
+        description,
+        category,
+        parameters,
+        summarize: (args) => summarize(name, args),
+        async execute(args, ctx) {
+            const redact = options.redact ?? ((m) => m);
+            try {
+                const argObj = toRecord(args);
+                const result = await client.callTool(descriptor.name, argObj, {
+                    signal: ctx.signal,
+                    timeoutMs: options.defaultTimeoutMs,
+                });
+                // Apply the per-server redactor to *all* MCP output, not just the
+                // catch path. A malicious or careless server can echo Authorization
+                // headers or env values in its own response body — `isError` is the
+                // most likely vector but a successful response is not safe either.
+                // (5.4) `renderMcpContentParts` strips terminal controls then redacts.
+                const text = renderMcpContentParts(result.content, { redact });
+                if (result.isError)
+                    return { ok: false, output: text || "MCP tool reported an error" };
+                return { ok: true, output: text };
+            }
+            catch (e) {
+                // Cancellation must terminate the whole turn — never swallow it as a
+                // tool error. The SDK rejects with its own McpError on abort (not an
+                // AppError), so check the signal first and re-raise as
+                // AppError(Cancelled) before the generic AppError branch.
+                if (ctx.signal.aborted) {
+                    throw new AppError(ErrorCode.Cancelled, "Operation cancelled");
+                }
+                if (e instanceof AppError && e.code === ErrorCode.Cancelled)
+                    throw e;
+                // Everything else (validation, transport, server-side error) surfaces
+                // as `ok: false` so the engine can show the failure inline. Run the
+                // message through the host-supplied redactor first — SDK HTTP errors
+                // can echo back bearer tokens in their error bodies.
+                return { ok: false, output: redact(e.message) };
+            }
+        },
+    };
+}
+/**
+ * MCP spec allows alphanumerics + underscore in tool names; provider APIs
+ * sometimes also reject dashes mid-name. Conservative: keep `[A-Za-z0-9_]`,
+ * everything else collapses to `_`. Consecutive `_` collapse to one.
+ */
+export function sanitizeMcpName(raw) {
+    return raw.replace(/[^A-Za-z0-9_]/g, "_").replace(/_+/g, "_");
+}
+function summarize(toolName, args) {
+    const preview = args && typeof args === "object" ? Object.keys(args).slice(0, 3).join(",") : "";
+    return preview ? `${toolName}(${preview})` : toolName;
+}
+function toRecord(args) {
+    if (!args || typeof args !== "object" || Array.isArray(args)) {
+        throw new AppError(ErrorCode.Tool, "MCP tool args must be a JSON object");
+    }
+    return args;
+}
+/**
+ * MCP `inputSchema` is a JSON Schema. Provider APIs (Anthropic / OpenAI)
+ * expect `{ type: "object", properties: {...} }`; some MCP servers omit
+ * `type` and only ship `properties`. Coerce defensively so the engine never
+ * forwards a malformed schema to the provider.
+ */
+function sanitizeInputSchema(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return { type: "object", properties: {} };
+    }
+    const obj = raw;
+    if (obj["type"] !== "object") {
+        return { type: "object", properties: {}, ...obj };
+    }
+    return obj;
+}
+//# sourceMappingURL=bridge.js.map

package/dist/mcp/bridge.js.map

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

package/dist/mcp/category.d.ts

@@ -0,0 +1,22 @@
+import type { ToolCategory } from "@chances-ai/runtime/config";
+/**
+ * MCP tools advertise behavior via three optional annotations
+ * (`readOnlyHint` / `destructiveHint` / `openWorldHint`) — see the MCP spec's
+ * `ToolAnnotations`. We translate them into the chances `ToolCategory` so MCP
+ * tools naturally inherit the user's existing per-category permission policy
+ * instead of needing a parallel gate.
+ *
+ * Mapping rationale (matches claude-code's behavior flags):
+ *   - `readOnlyHint: true` → file-read (default policy: allow)
+ *   - `destructiveHint: true` + `openWorldHint: true` → shell (prompt)
+ *   - `destructiveHint: true` → file-write (prompt)
+ *   - no annotation → integration (prompt; the user added the server, so we
+ *     prompt per-tool first time rather than silently allowing)
+ */
+export interface ToolAnnotations {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    openWorldHint?: boolean;
+}
+export declare function categoryFromAnnotations(annotations?: ToolAnnotations | null): ToolCategory;
+//# sourceMappingURL=category.d.ts.map

package/dist/mcp/category.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"category.d.ts","sourceRoot":"","sources":["../../src/mcp/category.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,uBAAuB,CAAC,WAAW,CAAC,EAAE,eAAe,GAAG,IAAI,GAAG,YAAY,CAO1F"}

package/dist/mcp/category.js

@@ -0,0 +1,11 @@
+export function categoryFromAnnotations(annotations) {
+    if (!annotations)
+        return "integration";
+    if (annotations.readOnlyHint === true)
+        return "file-read";
+    if (annotations.destructiveHint === true) {
+        return annotations.openWorldHint === true ? "shell" : "file-write";
+    }
+    return "integration";
+}
+//# sourceMappingURL=category.js.map

package/dist/mcp/category.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"category.js","sourceRoot":"","sources":["../../src/mcp/category.ts"],"names":[],"mappings":"AAsBA,MAAM,UAAU,uBAAuB,CAAC,WAAoC;IAC1E,IAAI,CAAC,WAAW;QAAE,OAAO,aAAa,CAAC;IACvC,IAAI,WAAW,CAAC,YAAY,KAAK,IAAI;QAAE,OAAO,WAAW,CAAC;IAC1D,IAAI,WAAW,CAAC,eAAe,KAAK,IAAI,EAAE,CAAC;QACzC,OAAO,WAAW,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC;IACrE,CAAC;IACD,OAAO,aAAa,CAAC;AACvB,CAAC"}