dsh-lsp-actions 0.2.0

package/lib/runner.js

@@ -0,0 +1,149 @@
+/**
+ * The action runner the three tools call: official-seam-first, own-client-fallback. When the
+ * extended `ctx.lsp` seam is mounted, actions go through it; when the seam is absent, too old, or
+ * has no provider for the file, the plugin's own client serves the call from the `servers` table.
+ * A seam provider that exists but lacks the capability fails loud — the user configured the
+ * server in one place and gets a real error instead of a silently spawned duplicate.
+ * @module dsh-lsp-actions/runner
+ */
+import { finalExtension } from "./extension.js";
+import { firstLanguageId, routeFile } from "./servers.js";
+import { trySeamAction } from "./seam.js";
+import { LspActionError } from "./vocabulary.js";
+/**
+ * Create the seam-first action runner. The seam is resolved through `getSeam` on every call, not
+ * captured at apply time, so the plugin serves through a seam that loads after it or is re-added
+ * later; a seam that is absent at call time falls back to the own client.
+ * @param options - the per-call seam resolver, the own client, and the resolved server table.
+ * @returns the runner facade.
+ */
+export function createActionRunner(options) {
+    return {
+        diagnostics: (request, signal) => runOp({ ...options, seam: options.getSeam() }, 'diagnostics', request, signal),
+        formatDocument: (request, signal) => runOp({ ...options, seam: options.getSeam() }, 'formatDocument', request, signal),
+        completion: (request, signal) => runOp({ ...options, seam: options.getSeam() }, 'completion', request, signal),
+        codeActions: (request, signal) => runOp({ ...options, seam: options.getSeam() }, 'codeAction', request, signal),
+        workspaceSymbols: (request, signal) => runOp({ ...options, seam: options.getSeam() }, 'workspaceSymbol', request, signal),
+        documentSymbols: (request, signal) => runOp({ ...options, seam: options.getSeam() }, 'documentSymbol', request, signal),
+        signatureHelp: (request, signal) => runOp({ ...options, seam: options.getSeam() }, 'signatureHelp', request, signal),
+        inlayHints: (request, signal) => runOp({ ...options, seam: options.getSeam() }, 'inlayHint', request, signal),
+        rename: (request, newName, signal) => renameOp({ ...options, seam: options.getSeam() }, request, newName, signal),
+    };
+}
+async function runOp(options, operation, request, signal) {
+    if (options.seam !== undefined) {
+        const attempt = await trySeamAction(options.seam, operation, request.filePath, request.workspaceRoot, request.position, request.range, signal, extrasFor(operation, request));
+        if (attempt.ok)
+            return attempt.result;
+        if (attempt.reason === 'unsupported') {
+            throw new LspActionError(`the mounted ctx.lsp provider does not support ${operation}; configure a server that advertises it`, 'LSP_ACTION_UNSUPPORTED');
+        }
+        if (attempt.reason === 'error')
+            throw attempt.error;
+        // absent / legacy / unavailable: the seam cannot serve this action — fall through to the
+        // plugin's own client, which fails loud itself when no server entry handles the file.
+    }
+    // Workspace symbol search has no document to route by: when no entry matches (or no file path
+    // was supplied), fall back to the first configured server.
+    const route = routeFile(options.servers, request.filePath) ?? firstServerRoute(options.servers, operation);
+    if (route === undefined) {
+        throw new LspActionError(noRouteMessage(request.filePath), 'LSP_ACTION_UNAVAILABLE');
+    }
+    if (operation === 'workspaceSymbol') {
+        // With a routing file, keep it open for the request: project-based servers (tsls) refuse
+        // document-free workspace/symbol.
+        if (request.source !== undefined) {
+            const actionRequest = {
+                filePath: request.filePath,
+                workspaceRoot: request.workspaceRoot,
+                source: request.source,
+                languageId: route.languageId,
+            };
+            return await options.client.workspaceSymbolsInDocument(route.server, actionRequest, request.query ?? '', signal);
+        }
+        return await options.client.workspaceSymbols(route.server, request.workspaceRoot, request.query ?? '', signal);
+    }
+    if (request.source === undefined) {
+        throw new LspActionError(`the ${operation} action requires a source document`, 'LSP_ACTION_WORKSPACE_REQUIRED');
+    }
+    const actionRequest = {
+        filePath: request.filePath,
+        workspaceRoot: request.workspaceRoot,
+        source: request.source,
+        languageId: route.languageId,
+        ...request.position === undefined ? {} : { position: request.position },
+        ...request.range === undefined ? {} : { range: request.range },
+        ...request.onlyKinds === undefined ? {} : { onlyKinds: request.onlyKinds },
+    };
+    switch (operation) {
+        case 'diagnostics': return await options.client.diagnostics(route.server, actionRequest, signal);
+        case 'formatDocument': return await options.client.formatDocument(route.server, actionRequest, signal);
+        case 'completion': return await options.client.completion(route.server, actionRequest, signal);
+        case 'codeAction': return await options.client.codeActions(route.server, actionRequest, signal);
+        case 'documentSymbol': return await options.client.documentSymbols(route.server, actionRequest, signal);
+        case 'signatureHelp': return await options.client.signatureHelp(route.server, actionRequest, signal);
+        case 'inlayHint': return await options.client.inlayHints(route.server, actionRequest, signal);
+    }
+}
+/** The first configured server's route, for workspace-scoped actions without a file to route by. */
+function firstServerRoute(servers, operation) {
+    if (operation !== 'workspaceSymbol')
+        return undefined;
+    const first = servers[0];
+    if (first === undefined)
+        return undefined;
+    return { server: first, languageId: firstLanguageId(first) };
+}
+/** The operation-specific extras one seam query carries (`query` for symbol search, `only` filters). */
+function extrasFor(operation, request) {
+    switch (operation) {
+        case 'workspaceSymbol': return request.query === undefined ? {} : { query: request.query };
+        case 'codeAction': return request.onlyKinds === undefined ? {} : { onlyKinds: request.onlyKinds };
+        default: return {};
+    }
+}
+/**
+ * Serve the rename action: seam first (only a seam that answers with the `rename` result kind
+ * serves it — any current seam vintage falls back), then the plugin's own client.
+ */
+async function renameOp(options, request, newName, signal) {
+    if (options.seam !== undefined) {
+        const attempt = await trySeamAction(options.seam, 'rename', request.filePath, request.workspaceRoot, request.position, request.range, signal, { newName });
+        if (attempt.ok) {
+            if (attempt.result.kind === 'rename')
+                return attempt.result;
+            // A seam answered with a different result kind: it cannot serve rename — fall through.
+        }
+        else {
+            if (attempt.reason === 'unsupported') {
+                throw new LspActionError('the mounted ctx.lsp provider does not support rename; configure a server that advertises it', 'LSP_ACTION_UNSUPPORTED');
+            }
+            if (attempt.reason === 'error')
+                throw attempt.error;
+            // absent / legacy / unavailable: the seam cannot serve rename — fall through to the
+            // plugin's own client, which fails loud itself when no entry handles the file.
+        }
+    }
+    const route = routeFile(options.servers, request.filePath);
+    if (route === undefined) {
+        throw new LspActionError(noRouteMessage(request.filePath), 'LSP_ACTION_UNAVAILABLE');
+    }
+    if (request.source === undefined) {
+        throw new LspActionError('the rename action requires a source document', 'LSP_ACTION_WORKSPACE_REQUIRED');
+    }
+    const actionRequest = {
+        filePath: request.filePath,
+        workspaceRoot: request.workspaceRoot,
+        source: request.source,
+        languageId: route.languageId,
+        ...request.position === undefined ? {} : { position: request.position },
+    };
+    return await options.client.rename(route.server, actionRequest, newName, signal);
+}
+/** The fail-loud message when neither the seam nor the servers table handles the file. */
+function noRouteMessage(filePath) {
+    const extension = finalExtension(filePath);
+    const subject = extension === '' ? 'this file type' : `files with the "${extension}" extension`;
+    return `no LSP server is configured for ${subject} — add an entry to the lsp-actions servers table, or register an LSP provider on ctx.lsp`;
+}
+//# sourceMappingURL=runner.js.map

package/lib/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAezC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAiChD;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAIlC;IACC,OAAO;QACL,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC;QAChH,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,CAAC;QACtH,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,CAAC;QAC9G,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,CAAC;QAC/G,gBAAgB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,CAAC;QACzH,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,CAAC;QACvH,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,CAAC;QACpH,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC;QAC7G,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC;KAClH,CAAA;AACH,CAAC;AAyED,KAAK,UAAU,KAAK,CAClB,OAIC,EACD,SAAgJ,EAChJ,OAAsB,EACtB,MAAoB;IAEpB,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,MAAM,aAAa,CACjC,OAAO,CAAC,IAAI,EACZ,SAAS,EACT,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,aAAa,EACrB,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,KAAK,EACb,MAAM,EACN,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC,CAC9B,CAAA;QACD,IAAI,OAAO,CAAC,EAAE;YAAE,OAAO,OAAO,CAAC,MAAM,CAAA;QACrC,IAAI,OAAO,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;YACrC,MAAM,IAAI,cAAc,CACtB,iDAAiD,SAAS,yCAAyC,EACnG,wBAAwB,CACzB,CAAA;QACH,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,OAAO;YAAE,MAAM,OAAO,CAAC,KAAK,CAAA;QACnD,yFAAyF;QACzF,sFAAsF;IACxF,CAAC;IACD,8FAA8F;IAC9F,2DAA2D;IAC3D,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAA;IAC1G,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,cAAc,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,wBAAwB,CAAC,CAAA;IACtF,CAAC;IACD,IAAI,SAAS,KAAK,iBAAiB,EAAE,CAAC;QACpC,yFAAyF;QACzF,kCAAkC;QAClC,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACjC,MAAM,aAAa,GAAkB;gBACnC,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,aAAa,EAAE,OAAO,CAAC,aAAa;gBACpC,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,UAAU,EAAE,KAAK,CAAC,UAAU;aAC7B,CAAA;YACD,OAAO,MAAM,OAAO,CAAC,MAAM,CAAC,0BAA0B,CAAC,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE,EAAE,MAAM,CAAC,CAAA;QAClH,CAAC;QACD,OAAO,MAAM,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE,EAAE,MAAM,CAAC,CAAA;IAChH,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,IAAI,cAAc,CAAC,OAAO,SAAS,oCAAoC,EAAE,+BAA+B,CAAC,CAAA;IACjH,CAAC;IACD,MAAM,aAAa,GAAkB;QACnC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,GAAG,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE;QACvE,GAAG,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE;QAC9D,GAAG,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE;KAC3E,CAAA;IACD,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,aAAa,CAAC,CAAC,OAAO,MAAM,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,CAAC,CAAA;QAChG,KAAK,gBAAgB,CAAC,CAAC,OAAO,MAAM,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,CAAC,CAAA;QACtG,KAAK,YAAY,CAAC,CAAC,OAAO,MAAM,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,CAAC,CAAA;QAC9F,KAAK,YAAY,CAAC,CAAC,OAAO,MAAM,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,CAAC,CAAA;QAC/F,KAAK,gBAAgB,CAAC,CAAC,OAAO,MAAM,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,CAAC,CAAA;QACvG,KAAK,eAAe,CAAC,CAAC,OAAO,MAAM,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,CAAC,CAAA;QACpG,KAAK,WAAW,CAAC,CAAC,OAAO,MAAM,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,CAAC,CAAA;IAC/F,CAAC;AACH,CAAC;AAED,oGAAoG;AACpG,SAAS,gBAAgB,CAAC,OAAkC,EAAE,SAAiB;IAC7E,IAAI,SAAS,KAAK,iBAAiB;QAAE,OAAO,SAAS,CAAA;IACrD,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IACxB,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACzC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,eAAe,CAAC,KAAK,CAAC,EAAE,CAAA;AAC9D,CAAC;AAED,wGAAwG;AACxG,SAAS,SAAS,CAAC,SAAiB,EAAE,OAAsB;IAC1D,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,iBAAiB,CAAC,CAAC,OAAO,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAA;QAC1F,KAAK,YAAY,CAAC,CAAC,OAAO,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAA;QACjG,OAAO,CAAC,CAAC,OAAO,EAAE,CAAA;IACpB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,QAAQ,CACrB,OAIC,EACD,OAAsB,EACtB,OAAe,EACf,MAAoB;IAEpB,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,MAAM,aAAa,CACjC,OAAO,CAAC,IAAI,EACZ,QAAQ,EACR,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,aAAa,EACrB,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,KAAK,EACb,MAAM,EACN,EAAE,OAAO,EAAE,CACZ,CAAA;QACD,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC;YACf,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,OAAO,CAAC,MAAM,CAAA;YAC3D,uFAAuF;QACzF,CAAC;aAAM,CAAC;YACN,IAAI,OAAO,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;gBACrC,MAAM,IAAI,cAAc,CACtB,6FAA6F,EAC7F,wBAAwB,CACzB,CAAA;YACH,CAAC;YACD,IAAI,OAAO,CAAC,MAAM,KAAK,OAAO;gBAAE,MAAM,OAAO,CAAC,KAAK,CAAA;YACnD,oFAAoF;YACpF,+EAA+E;QACjF,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC1D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,cAAc,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,wBAAwB,CAAC,CAAA;IACtF,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,IAAI,cAAc,CAAC,8CAA8C,EAAE,+BAA+B,CAAC,CAAA;IAC3G,CAAC;IACD,MAAM,aAAa,GAAkB;QACnC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,GAAG,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE;KACxE,CAAA;IACD,OAAO,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,CAAA;AAClF,CAAC;AAED,0FAA0F;AAC1F,SAAS,cAAc,CAAC,QAAgB;IACtC,MAAM,SAAS,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAA;IAC1C,MAAM,OAAO,GAAG,SAAS,KAAK,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,mBAAmB,SAAS,aAAa,CAAA;IAC/F,OAAO,mCAAmC,OAAO,0FAA0F,CAAA;AAC7I,CAAC"}

package/lib/sandbox.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The sandbox-escalation API for the mutation tools (`lsp_format` / `lsp_rename`): per-call policy
+ * resolution, the advertised escalation fields, and denial-marker mapping — delegating the
+ * vocabulary and the fail-closed approval sequence to `@deepseek-ai/dsh-sandbox`, exactly as
+ * `dsh-tool-fs` does for `write`/`edit`, so formatting and rename escalate identically to the
+ * official mutation tools.
+ * @module dsh-lsp-actions/sandbox
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+/** The two escalation arguments a mutation tool may carry (advertised only under a confining backend). */
+export interface FormatEscalationArgs {
+    sandbox_permissions?: string;
+    justification?: string;
+}
+/** The schema fields for the escalation arguments, spread into the tool's `parameters`. */
+export interface EscalationSchemaFields {
+    sandbox_permissions: {
+        type: 'string';
+        enum: string[];
+        description: string;
+    };
+    justification: {
+        type: 'string';
+        description: string;
+    };
+}
+/**
+ * The mutation-escalation API: advertisement gating, per-call policy resolution, the one-approved
+ * wider retry, and denial-marker mapping. A pure product of `ctx` at plugin apply time.
+ */
+export declare class FormatSandboxController {
+    private readonly ctx;
+    /** The escalation targets this composition advertises (`[]` when no confining backend is mounted). */
+    readonly escalationModes: readonly SandboxMode[];
+    /** Shared per-session policy resolver, required by a confining backend. */
+    private readonly policy;
+    constructor(ctx: Context);
+    /**
+     * The escalation schema fields for a mutation tool's `parameters`. Call it only under a confining
+     * backend (guard on {@link escalationModes}); the enum pins the closed target vocabulary, the
+     * strict-wider check happens per call at execution.
+     * @param actionLabel - the action named in the advertised descriptions (`formatting`, `rename`).
+     * @returns the two escalation parameter specs.
+     */
+    schemaFields(actionLabel: string): EscalationSchemaFields;
+    /**
+     * The policy to stamp onto this formatting: an approved escalation grant (a strictly wider retry
+     * resolved through `ctx.approval` before anything executes), else the session's standing mode.
+     * The calling session's cwd is always carried as the workspace root. Validates the escalation
+     * argument pairing first.
+     * @param toolName - the tool's name, for the approval audit trail.
+     * @param args - the call's escalation arguments.
+     * @param exec - the tool-execution context (agent, callId, signal).
+     * @returns the policy to pass to the write, or undefined for an unsandboxed backend.
+     */
+    resolvePolicy(toolName: string, args: FormatEscalationArgs, exec: ToolExecution): Promise<SandboxExecutionPolicy | undefined>;
+    /**
+     * Map a thrown provider error for the model: a `FS_SANDBOX_DENIED` becomes an `FsError` whose
+     * text is the shared `[sandbox: …]` denial marker plus the same-turn escalation hint, so a policy
+     * denial reads identically to bash's WHILE keeping the structured `FS_SANDBOX_DENIED` code.
+     * @param error - the error thrown by the write.
+     * @param policy - the policy stamped onto the call (names the mode in the marker).
+     * @returns the error to throw — the marker `FsError` for a sandbox denial, else the original.
+     */
+    mapError(error: unknown, policy: SandboxExecutionPolicy | undefined): unknown;
+}
+//# sourceMappingURL=sandbox.d.ts.map

package/lib/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAInF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAE3D,0GAA0G;AAC1G,MAAM,WAAW,oBAAoB;IACnC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,2FAA2F;AAC3F,MAAM,WAAW,sBAAsB;IACrC,mBAAmB,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5E,aAAa,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;CACvD;AAED;;;GAGG;AACH,qBAAa,uBAAuB;IAMtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IALhC,sGAAsG;IACtG,QAAQ,CAAC,eAAe,EAAE,SAAS,WAAW,EAAE,CAAA;IAChD,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;gBAE5B,GAAG,EAAE,OAAO;IASzC;;;;;;OAMG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,sBAAsB;IAgBzD;;;;;;;;;OASG;IACG,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC;IAuBnI;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,sBAAsB,GAAG,SAAS,GAAG,OAAO;CAO9E"}

package/lib/sandbox.js

@@ -0,0 +1,98 @@
+/**
+ * The sandbox-escalation API for the mutation tools (`lsp_format` / `lsp_rename`): per-call policy
+ * resolution, the advertised escalation fields, and denial-marker mapping — delegating the
+ * vocabulary and the fail-closed approval sequence to `@deepseek-ai/dsh-sandbox`, exactly as
+ * `dsh-tool-fs` does for `write`/`edit`, so formatting and rename escalate identically to the
+ * official mutation tools.
+ * @module dsh-lsp-actions/sandbox
+ */
+import { ESCALATION_TARGETS, approveEscalation, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox';
+import { FsError } from '@deepseek-ai/dsh-fs';
+/**
+ * The mutation-escalation API: advertisement gating, per-call policy resolution, the one-approved
+ * wider retry, and denial-marker mapping. A pure product of `ctx` at plugin apply time.
+ */
+export class FormatSandboxController {
+    ctx;
+    /** The escalation targets this composition advertises (`[]` when no confining backend is mounted). */
+    escalationModes;
+    /** Shared per-session policy resolver, required by a confining backend. */
+    policy;
+    constructor(ctx) {
+        this.ctx = ctx;
+        const defaultMode = ctx.fs.sandboxMode;
+        this.escalationModes = defaultMode === undefined ? [] : ESCALATION_TARGETS;
+        this.policy = defaultMode === undefined ? undefined : ctx.get('sandboxPolicy');
+        if (defaultMode !== undefined && this.policy === undefined) {
+            throw new Error('lsp-actions: the mounted filesystem confines but ctx.sandboxPolicy is missing');
+        }
+    }
+    /**
+     * The escalation schema fields for a mutation tool's `parameters`. Call it only under a confining
+     * backend (guard on {@link escalationModes}); the enum pins the closed target vocabulary, the
+     * strict-wider check happens per call at execution.
+     * @param actionLabel - the action named in the advertised descriptions (`formatting`, `rename`).
+     * @returns the two escalation parameter specs.
+     */
+    schemaFields(actionLabel) {
+        return {
+            sandbox_permissions: {
+                type: 'string',
+                enum: [...this.escalationModes],
+                description: 'The wider sandbox mode this operation needs. Only valid as a one-shot retry '
+                    + 'of an operation the sandbox just denied; requires justification and user approval.',
+            },
+            justification: {
+                type: 'string',
+                description: 'Required with sandbox_permissions: one sentence for the user explaining '
+                    + `why this exact ${actionLabel} needs the wider access.`,
+            },
+        };
+    }
+    /**
+     * The policy to stamp onto this formatting: an approved escalation grant (a strictly wider retry
+     * resolved through `ctx.approval` before anything executes), else the session's standing mode.
+     * The calling session's cwd is always carried as the workspace root. Validates the escalation
+     * argument pairing first.
+     * @param toolName - the tool's name, for the approval audit trail.
+     * @param args - the call's escalation arguments.
+     * @param exec - the tool-execution context (agent, callId, signal).
+     * @returns the policy to pass to the write, or undefined for an unsandboxed backend.
+     */
+    async resolvePolicy(toolName, args, exec) {
+        validateEscalationArgs(args.sandbox_permissions, args.justification);
+        const standingPolicy = this.policy?.resolve({ ...exec.agent ? { session: exec.agent.session } : {} });
+        if (args.sandbox_permissions === undefined || args.justification === undefined) {
+            return standingPolicy;
+        }
+        if (this.escalationModes.length === 0) {
+            throw new Error('sandbox_permissions is not available in this composition (no sandboxing filesystem to escalate)');
+        }
+        const policy = standingPolicy;
+        const approvedMode = await approveEscalation({ requestedMode: args.sandbox_permissions, justification: args.justification, effectiveMode: policy.mode, subject: 'operation' }, {
+            approver: this.ctx.get('approval'),
+            agent: exec.agent,
+            callId: exec.callId,
+            toolName,
+            signal: exec.signal,
+        });
+        return { ...policy, mode: approvedMode };
+    }
+    /**
+     * Map a thrown provider error for the model: a `FS_SANDBOX_DENIED` becomes an `FsError` whose
+     * text is the shared `[sandbox: …]` denial marker plus the same-turn escalation hint, so a policy
+     * denial reads identically to bash's WHILE keeping the structured `FS_SANDBOX_DENIED` code.
+     * @param error - the error thrown by the write.
+     * @param policy - the policy stamped onto the call (names the mode in the marker).
+     * @returns the error to throw — the marker `FsError` for a sandbox denial, else the original.
+     */
+    mapError(error, policy) {
+        if (!(error instanceof FsError) || error.code !== 'FS_SANDBOX_DENIED')
+            return error;
+        // A FS_SANDBOX_DENIED only arises under a confining backend, whose tool path always resolves a
+        // policy before the write.
+        const mode = policy.mode;
+        return new FsError(`${sandboxDenialMarker(mode)}\n${escalationHintMarker('operation')}`, 'FS_SANDBOX_DENIED', { cause: error });
+    }
+}
+//# sourceMappingURL=sandbox.js.map

package/lib/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAA;AAEnJ,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAe7C;;;GAGG;AACH,MAAM,OAAO,uBAAuB;IAML;IAL7B,sGAAsG;IAC7F,eAAe,CAAwB;IAChD,2EAA2E;IAC1D,MAAM,CAAkC;IAEzD,YAA6B,GAAY;QAAZ,QAAG,GAAH,GAAG,CAAS;QACvC,MAAM,WAAW,GAAG,GAAG,CAAC,EAAE,CAAC,WAAW,CAAA;QACtC,IAAI,CAAC,eAAe,GAAG,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,kBAAkB,CAAA;QAC1E,IAAI,CAAC,MAAM,GAAG,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,eAAe,CAAC,CAAA;QAC9E,IAAI,WAAW,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC3D,MAAM,IAAI,KAAK,CAAC,+EAA+E,CAAC,CAAA;QAClG,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,YAAY,CAAC,WAAmB;QAC9B,OAAO;YACL,mBAAmB,EAAE;gBACnB,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,eAAe,CAAC;gBAC/B,WAAW,EAAE,8EAA8E;sBACvF,oFAAoF;aACzF;YACD,aAAa,EAAE;gBACb,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,0EAA0E;sBACnF,kBAAkB,WAAW,0BAA0B;aAC5D;SACF,CAAA;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,aAAa,CAAC,QAAgB,EAAE,IAA0B,EAAE,IAAmB;QACnF,sBAAsB,CAAC,IAAI,CAAC,mBAAmB,EAAE,IAAI,CAAC,aAAa,CAAC,CAAA;QACpE,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;QACrG,IAAI,IAAI,CAAC,mBAAmB,KAAK,SAAS,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;YAC/E,OAAO,cAAc,CAAA;QACvB,CAAC;QACD,IAAI,IAAI,CAAC,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,iGAAiG,CAAC,CAAA;QACpH,CAAC;QACD,MAAM,MAAM,GAAG,cAAwC,CAAA;QACvD,MAAM,YAAY,GAAG,MAAM,iBAAiB,CAC1C,EAAE,aAAa,EAAE,IAAI,CAAC,mBAAmB,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,aAAa,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,EAChI;YACE,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC;YAClC,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,QAAQ;YACR,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CACF,CAAA;QACD,OAAO,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,CAAA;IAC1C,CAAC;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAc,EAAE,MAA0C;QACjE,IAAI,CAAC,CAAC,KAAK,YAAY,OAAO,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,mBAAmB;YAAE,OAAO,KAAK,CAAA;QACnF,+FAA+F;QAC/F,2BAA2B;QAC3B,MAAM,IAAI,GAAI,MAAiC,CAAC,IAAI,CAAA;QACpD,OAAO,IAAI,OAAO,CAAC,GAAG,mBAAmB,CAAC,IAAI,CAAC,KAAK,oBAAoB,CAAC,WAAW,CAAC,EAAE,EAAE,mBAAmB,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;IACjI,CAAC;CACF"}

package/lib/seam.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The official-seam consumer (path one): run each action through the extended `ctx.lsp` seam when
+ * it is mounted and serves the operation, and classify failures so the runner can fall back to
+ * the plugin's own client only where that is the right call. The seam vocabulary is consumed
+ * structurally, never by import, so the plugin keeps working against every seam vintage.
+ * @module dsh-lsp-actions/seam
+ */
+import type { LspActionOperation, LspActionResult, LspPosition, LspRange } from './vocabulary.ts';
+/** The structural surface the extended `ctx.lsp` seam exposes (see the upstream PR proposal). */
+export interface SeamService {
+    query(request: {
+        readonly operation: LspActionOperation;
+        readonly filePath: string;
+        readonly position?: LspPosition;
+        readonly range?: LspRange;
+        readonly workspaceRoot: string;
+        /** The symbol-name query, for workspace symbol search. */
+        readonly query?: string;
+        /** CodeActionKind filters, for code actions. */
+        readonly onlyKinds?: readonly string[];
+        /** The new symbol name, for rename. */
+        readonly newName?: string;
+    }, signal?: AbortSignal): Promise<LspActionResult>;
+}
+/** Operation-specific extras a seam query may carry (`query`, `onlyKinds`, `newName`). */
+export interface SeamExtras {
+    readonly query?: string;
+    readonly onlyKinds?: readonly string[];
+    readonly newName?: string;
+}
+/** The classification of one seam attempt, deciding whether the runner falls back or fails. */
+export type SeamAttempt = {
+    readonly ok: true;
+    readonly result: LspActionResult;
+} | {
+    readonly ok: false;
+    readonly reason: 'absent';
+} | {
+    readonly ok: false;
+    readonly reason: 'legacy';
+} | {
+    readonly ok: false;
+    readonly reason: 'unavailable';
+} | {
+    readonly ok: false;
+    readonly reason: 'unsupported';
+} | {
+    readonly ok: false;
+    readonly reason: 'error';
+    readonly error: unknown;
+};
+/**
+ * Run one action through the seam and classify the outcome. Success returns the result; the
+ * fallback reasons (`absent`, `legacy`, `unavailable`) let the runner serve the call through the
+ * plugin's own client, while `unsupported` and `error` fail loud.
+ * @param seam - the mounted `ctx.lsp` service, when present.
+ * @param operation - the action to run.
+ * @param filePath - the source file.
+ * @param workspaceRoot - the workspace root.
+ * @param position - the cursor position, for completion, signature help, and rename.
+ * @param range - the formatting/code-action/inlay-hint range.
+ * @param signal - optional cancellation.
+ * @param extras - operation-specific extras (`query`, `onlyKinds`, `newName`) the operation carries.
+ * @returns the classified attempt.
+ */
+export declare function trySeamAction(seam: SeamService | undefined, operation: LspActionOperation, filePath: string, workspaceRoot: string, position: LspPosition | undefined, range: LspRange | undefined, signal: AbortSignal | undefined, extras?: SeamExtras): Promise<SeamAttempt>;
+//# sourceMappingURL=seam.d.ts.map

package/lib/seam.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seam.d.ts","sourceRoot":"","sources":["../src/seam.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAEjG,iGAAiG;AACjG,MAAM,WAAW,WAAW;IAC1B,KAAK,CACH,OAAO,EAAE;QACP,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAA;QACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;QACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAA;QAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAA;QACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;QAC9B,0DAA0D;QAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;QACvB,gDAAgD;QAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;QACtC,uCAAuC;QACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAC1B,EACD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC,CAAA;CAC5B;AAED,0FAA0F;AAC1F,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,+FAA+F;AAC/F,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAE7E;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,SAAS,EAAE,kBAAkB,EAC7B,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,WAAW,GAAG,SAAS,EACjC,KAAK,EAAE,QAAQ,GAAG,SAAS,EAC3B,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,MAAM,GAAE,UAAe,GACtB,OAAO,CAAC,WAAW,CAAC,CA0BtB"}

package/lib/seam.js

@@ -0,0 +1,62 @@
+/**
+ * The official-seam consumer (path one): run each action through the extended `ctx.lsp` seam when
+ * it is mounted and serves the operation, and classify failures so the runner can fall back to
+ * the plugin's own client only where that is the right call. The seam vocabulary is consumed
+ * structurally, never by import, so the plugin keeps working against every seam vintage.
+ * @module dsh-lsp-actions/seam
+ */
+/**
+ * Run one action through the seam and classify the outcome. Success returns the result; the
+ * fallback reasons (`absent`, `legacy`, `unavailable`) let the runner serve the call through the
+ * plugin's own client, while `unsupported` and `error` fail loud.
+ * @param seam - the mounted `ctx.lsp` service, when present.
+ * @param operation - the action to run.
+ * @param filePath - the source file.
+ * @param workspaceRoot - the workspace root.
+ * @param position - the cursor position, for completion, signature help, and rename.
+ * @param range - the formatting/code-action/inlay-hint range.
+ * @param signal - optional cancellation.
+ * @param extras - operation-specific extras (`query`, `onlyKinds`, `newName`) the operation carries.
+ * @returns the classified attempt.
+ */
+export async function trySeamAction(seam, operation, filePath, workspaceRoot, position, range, signal, extras = {}) {
+    if (seam === undefined)
+        return { ok: false, reason: 'absent' };
+    try {
+        const result = await seam.query({
+            operation,
+            filePath,
+            workspaceRoot,
+            ...position === undefined ? {} : { position },
+            ...range === undefined ? {} : { range },
+            ...extras.query === undefined ? {} : { query: extras.query },
+            ...extras.onlyKinds === undefined ? {} : { onlyKinds: extras.onlyKinds },
+            ...extras.newName === undefined ? {} : { newName: extras.newName },
+        }, signal);
+        return { ok: true, result };
+    }
+    catch (error) {
+        // An abort is the caller's own cancellation (timeout policy), not a seam capability fact:
+        // surface the signal's reason, never the seam's unrelated error or a fallback classification.
+        if (signal?.aborted)
+            throw signal.reason;
+        const code = errorCodeOf(error);
+        if (code === 'LSP_UNAVAILABLE')
+            return { ok: false, reason: 'unavailable' };
+        if (code === 'LSP_UNSUPPORTED_OPERATION')
+            return { ok: false, reason: 'unsupported' };
+        // A code-less failure is the pre-action seam (or its provider) rejecting an unknown operation:
+        // it can never serve actions, so the runner falls back to the plugin's own client.
+        if (code === undefined)
+            return { ok: false, reason: 'legacy' };
+        return { ok: false, reason: 'error', error };
+    }
+}
+/** Extract a stable error code from an unknown thrown value, without instanceof across copies. */
+function errorCodeOf(error) {
+    if (error === null || typeof error !== 'object')
+        return undefined;
+    const code = error.code;
+    return typeof code === 'string' ? code : undefined;
+}
+//# sourceMappingURL=seam.js.map

package/lib/seam.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seam.js","sourceRoot":"","sources":["../src/seam.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAwCH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAA6B,EAC7B,SAA6B,EAC7B,QAAgB,EAChB,aAAqB,EACrB,QAAiC,EACjC,KAA2B,EAC3B,MAA+B,EAC/B,SAAqB,EAAE;IAEvB,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAA;IAC9D,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC;YAC9B,SAAS;YACT,QAAQ;YACR,aAAa;YACb,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE;YAC7C,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE;YACvC,GAAG,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE;YAC5D,GAAG,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE;YACxE,GAAG,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE;SACnE,EAAE,MAAM,CAAC,CAAA;QACV,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,0FAA0F;QAC1F,8FAA8F;QAC9F,IAAI,MAAM,EAAE,OAAO;YAAE,MAAM,MAAM,CAAC,MAAM,CAAA;QACxC,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,CAAA;QAC/B,IAAI,IAAI,KAAK,iBAAiB;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAA;QAC3E,IAAI,IAAI,KAAK,2BAA2B;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAA;QACrF,+FAA+F;QAC/F,mFAAmF;QACnF,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAA;QAC9D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;IAC9C,CAAC;AACH,CAAC;AAED,kGAAkG;AAClG,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAA;IACjE,MAAM,IAAI,GAAI,KAA4B,CAAC,IAAI,CAAA;IAC/C,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AACpD,CAAC"}

package/lib/servers.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Server configuration and routing: the `servers` table schema, load-time validation and
+ * executable resolution, and the per-file routing that picks one server entry (glob patterns
+ * first, then the extension map) plus its language id.
+ * @module dsh-lsp-actions/servers
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** The default byte cap for any single source document a tool opens for a language server. */
+export declare const DEFAULT_MAX_DOCUMENT_BYTES = 4000000;
+/** One configured local language server and its host bounds. */
+export interface LspServerEntry {
+    /** Executable to spawn (absolute, or resolved on PATH at load). */
+    command: string;
+    /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */
+    extensionToLanguage: Record<string, string>;
+    /** Optional path globs (e.g. `src/**\/*.ts`); when a file matches, this entry wins over the extension map. */
+    fileGlobs?: string[];
+    /** Arguments passed to the executable (no shell). Default `[]`. */
+    args?: string[];
+    /** Extra env vars merged on top of the scrubbed ambient env. Default `{}`. */
+    env?: Record<string, string>;
+    /** Static `initialize` options forwarded to the server. Default `null`. */
+    initializationOptions?: unknown;
+    /** Static answer to every `workspace/configuration` item. Default `null`. */
+    configuration?: unknown;
+    /** Static `textDocument/formatting` options (`{ tabSize, insertSpaces }`); omitted when null. Default `null`. */
+    formattingOptions?: unknown;
+    /** Largest single framed message accepted from the server (bytes). Default 16000000. */
+    maxMessageBytes?: number;
+    /** Largest stderr tail retained for diagnostics (bytes). Default 1000000. */
+    maxStderrBytes?: number;
+    /** Request-cancel and SIGTERM→SIGKILL grace (ms). Default 2000. */
+    killGraceMs?: number;
+    /** Graceful `shutdown`/`exit` budget before escalation (ms). Default 5000. */
+    shutdownTimeoutMs?: number;
+    /** Settle window for push-only diagnostics after `didOpen` (ms). Default 2000. */
+    diagnosticsSettleMs?: number;
+    /** Quiet period after the last pushed batch before the client returns it (ms). Default 250. */
+    diagnosticsDebounceMs?: number;
+    /** Idle time before an unused server instance is disposed (ms); 0 keeps it alive. Default 0. */
+    idleTimeoutMs?: number;
+}
+/** Plugin configuration: a named table of local language servers plus tool result caps. */
+export interface Config {
+    /** Named server entries; empty disables the plugin's own client (the official seam may still serve). */
+    servers: Record<string, LspServerEntry>;
+    /** Largest number of rendered diagnostics before an omission marker. Default 200. */
+    maxDiagnostics?: number;
+    /** Largest number of rendered completion items before an omission marker. Default 20. */
+    maxCompletionItems?: number;
+    /** Largest number of rendered code actions before an omission marker. Default 50. */
+    maxCodeActions?: number;
+    /** Largest number of rendered symbols before an omission marker. Default 100. */
+    maxSymbols?: number;
+    /** Largest number of rendered signatures in one signature-help result. Default 10. */
+    maxSignatures?: number;
+    /** Largest number of rendered inlay hints before an omission marker. Default 200. */
+    maxInlayHints?: number;
+    /** Largest complete rendered result in characters, including truncation metadata. Default 16000. */
+    maxResultChars?: number;
+    /** Largest source file a tool will open for a language server (bytes). Default 4000000. */
+    maxDocumentBytes?: number;
+    /** Tool-call timeout budget in ms, enforced by the official timeout policy. Default 60000. */
+    timeoutMs?: number;
+}
+export declare const LspServerEntry: z<LspServerEntry>;
+export declare const Config: z<Config>;
+/** One server entry after schemastery filled every default. */
+export type ResolvedServerEntry = Required<LspServerEntry>;
+/** The plugin config after schemastery filled every default. */
+export type ResolvedConfig = Required<Config>;
+/** One resolved, executable server plus its routing. */
+export interface ResolvedServer {
+    /** The entry's stable key in the `servers` table. */
+    readonly serverId: string;
+    /** The entry with every default filled and validated. */
+    readonly entry: ResolvedServerEntry;
+    /** The absolute executable resolved at load. */
+    readonly executable: string;
+}
+/** The route one file selects: which server and what language id to open it with. */
+export interface ServerRoute {
+    readonly server: ResolvedServer;
+    readonly languageId: string;
+}
+/**
+ * Resolve every server entry's executable at load (fail loud on a missing command or an invalid
+ * bound) before any provider publishes. Mirrors the official `lsp-stdio` load contract.
+ * @param ctx - the plugin context (uses `ctx.subprocess.resolveExecutable`).
+ * @param servers - the schemastery-resolved servers table.
+ * @param signal - load cancellation.
+ * @returns the resolved servers in config order.
+ */
+export declare function resolveServers(ctx: Context, servers: Record<string, ResolvedServerEntry>, signal?: AbortSignal): Promise<ResolvedServer[]>;
+/**
+ * Route one file to a server entry: entries with matching `fileGlobs` first, then entries whose
+ * `extensionToLanguage` maps the file's extension, both in config order. A glob route uses the
+ * file's own extension mapping when the entry maps it; the entry's first mapping is the fallback
+ * only for files whose extension the glob — not the map — selected.
+ * @param servers - the resolved servers.
+ * @param filePath - the source file path (absolute or workspace-relative).
+ * @returns the route, or undefined when no entry handles the file.
+ */
+export declare function routeFile(servers: readonly ResolvedServer[], filePath: string): ServerRoute | undefined;
+/** The first extension mapping's language id, used when a glob route wins without an extension hit. */
+export declare function firstLanguageId(server: ResolvedServer): string;
+/**
+ * Compile a path glob (`*`/`**`/`?`) to an anchored regular expression. `*` and `?` do not cross
+ * separators; `**` does. Matching runs against `/`-normalized paths.
+ * @param pattern - the glob pattern.
+ * @returns the compiled, anchored expression.
+ * @throws Error when the pattern is empty or contains unbalanced brackets.
+ */
+export declare function globToRegExp(pattern: string): RegExp;
+/** Reject a timer value Node would clamp instead of scheduling as configured. */
+export declare function assertTimer(name: string, value: number): void;
+/** Reject a nonpositive or non-integer config value at load. */
+export declare function assertPositiveInteger(name: string, value: number): void;
+//# sourceMappingURL=servers.d.ts.map

package/lib/servers.d.ts.map

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