@try-works/dsh-tool-mode 0.0.0-stage → 0.5.44

package/lib/tool-mode-run.js

@@ -0,0 +1,411 @@
+/**
+ * The ONE authorized program-execution pipeline (CODE-02, CODE-03, CODE-08, ARCH-05).
+ *
+ * THE DEFECT THIS FIXES, found by adversarial review rather than by a test:
+ * `ptc-authority.ts` and `ptc-runtime.ts` had **zero callers outside tests**. Everything in
+ * them was correct and thoroughly covered — `buildToolBindings`, the guarded mount,
+ * `mayExposeToClients()` — and none of it ran in production. `tool_mode_run` did not exist,
+ * the mount guard never executed, and the exposure gate guarded nothing because there was
+ * no caller to refuse.
+ *
+ * A security control with no callers is not a control; it is a symbol. This module is the
+ * caller.
+ *
+ * The wiring enforces three things the directive requires and nothing else did:
+ *
+ * 1. **ONE pipeline.** Native PTC and any external `tool_mode_run` reach tools through the
+ *    SAME `buildToolBindings` call, so authorization cannot differ between the two doors.
+ * 2. **The grant is the grant.** The requested names are intersected with the host's own
+ *    `allowedTools` and the live registry, and the whole request is refused if anything is
+ *    unattainable.
+ * 3. **The exposure gate has a caller.** `mayExposeToClients()` returning false now
+ *    actually refuses something, with the reason attached.
+ *
+ * @module @try-works/dsh-tool-mode/tool-mode-run
+ */
+import { admitTimeout, buildToolBindings, exposureWithheldReason, mayExposeToClients, mountPtcRuntimeIfAbsent, PTC_SERVICE, } from "./ptc-runtime.js";
+import { generateProgramTypes } from "./ptc-authority.js";
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** Create the per-call external grant carrier. */
+export function createExternalGrantContext() {
+    const store = new AsyncLocalStorage();
+    return {
+        run(grant, work, profiles = [], remoteDestinations = []) {
+            return store.run({ grant, profiles, remoteDestinations }, work);
+        },
+        current() {
+            return store.getStore()?.grant;
+        },
+        currentProfiles() {
+            return store.getStore()?.profiles;
+        },
+        currentRemoteDestinations() {
+            return store.getStore()?.remoteDestinations;
+        },
+    };
+}
+/** How many sub-calls a trace keeps; the count itself is never truncated. */
+const MAX_TRACE_CALLS = 50;
+/** How much of one argument/result value a trace keeps. */
+const PREVIEW_CHARS = 160;
+/** A bounded, JSON-safe preview of one value. Never throws on a cycle. */
+function preview(value) {
+    let text;
+    try {
+        text = typeof value === 'string' ? value : JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        // A circular argument is still a value the program passed; name what it is rather
+        // than failing the run that already happened.
+        text = '[unserialisable]';
+    }
+    return text.length > PREVIEW_CHARS ? `${text.slice(0, PREVIEW_CHARS)}…` : text;
+}
+/** Nested programs allowed in one call chain (AT-10/AT-15). */
+const MAX_PROGRAM_DEPTH = 4;
+/** Identical tool calls allowed before the composition loop detector fires. */
+const MAX_IDENTICAL_TOOL_CALLS = 32;
+/** The depth of the program chain currently executing on this async chain. */
+const programDepth = new AsyncLocalStorage();
+/**
+ * Create the runner.
+ *
+ * @param environment - how to reach tools and the runtime.
+ * @returns the runner.
+ */
+export function createProgramRunner(environment) {
+    let prepared;
+    /** Materialized backend, resolved lazily at most once. */
+    let backend;
+    const materializeBackend = () => {
+        backend ??= (async () => {
+            // A FUNCTION backend is a lazy resolver; a CLASS is a plugin constructor and
+            // must not be invoked here (the mount does the construction). The source
+            // prefix distinguishes the two, which is exact for native classes. Wrapped
+            // constructors (bound/proxied/transpiled) can slip through as resolvers; the
+            // try/catch converts their invocation error into the SAME undefined the
+            // designed 'backend-unavailable' refusal reports, so no caller sees an
+            // opaque TypeError instead of the documented deployment fact.
+            const value = environment.backend;
+            const isClass = typeof value === 'function' && /^class\s/.test(Function.prototype.toString.call(value));
+            if (typeof value !== 'function' || isClass)
+                return value;
+            try {
+                return await value();
+            }
+            catch {
+                // The failure is reported through prepare()'s 'backend-unavailable'
+                // reason, which is the designed channel; the detail does not need a
+                // second logger the runner does not own.
+                return undefined;
+            }
+        })();
+        return backend;
+    };
+    return {
+        async prepare() {
+            // Idempotent: the guard is inside, and re-running it must not double-mount.
+            if (prepared !== undefined)
+                return prepared;
+            prepared = await mountPtcRuntimeIfAbsent(environment.context, await materializeBackend(), {
+                timeoutMs: 120_000,
+                maxTimeoutMs: 600_000,
+            });
+            return prepared;
+        },
+        externalExposurePermitted() {
+            return mayExposeToClients(environment.operatorGranted());
+        },
+        externalExposureReason() {
+            return exposureWithheldReason(environment.operatorGranted());
+        },
+        async run(request) {
+            const depth = programDepth.getStore() ?? 0;
+            if (depth >= MAX_PROGRAM_DEPTH) {
+                return {
+                    ok: false,
+                    code: 'failed',
+                    message: `MODEL_NESTED_DEPTH_EXCEEDED: a program chain may nest at most ${MAX_PROGRAM_DEPTH} composed run(s)`,
+                };
+            }
+            const runtime = environment.runtime();
+            if (runtime === undefined) {
+                return {
+                    ok: false,
+                    code: 'unavailable',
+                    message: 'no PTC runtime is mounted, so no program can run',
+                };
+            }
+            /**
+             * THE AUTHORIZED PIPELINE, and the only place bindings are built.
+             *
+             * `buildToolBindings` intersects the request with the GRANT and the live registry and
+             * refuses the whole thing if any name is unattainable. Both doors — native PTC and any
+             * external surface — come through here, which is what makes them the same pipeline
+             * rather than two implementations that happen to agree today.
+             */
+            let toolCalls = 0;
+            let harnessModelCalls = 0;
+            const calls = [];
+            /** Identical call counts for the composition loop detector (AT-10/AT-15). */
+            const repeatedCalls = new Map();
+            const countedResolve = (name) => {
+                const binding = environment.resolve(name);
+                if (binding === undefined)
+                    return undefined;
+                // A counter wrapper, not a permission change: the program's binding call is
+                // counted so the CODE-02 meta reports real usage rather than a fabricated 0.
+                // It also RECORDS a bounded trace, because a count alone cannot say which tools a
+                // program combined or in what order.
+                return async (args) => {
+                    // CODE-11: the ROOT budget is charged here, so a nested call cannot reset
+                    // the counters by invoking another tool.
+                    const maxToolCalls = environment.budgets?.maxToolCalls;
+                    if (maxToolCalls !== undefined && toolCalls >= maxToolCalls) {
+                        throw new Error(`MODEL_BUDGET_EXCEEDED: the program's root tool-call budget of ${maxToolCalls} was exhausted`);
+                    }
+                    const harness = environment.budgets?.isHarnessTool?.(name) === true;
+                    const maxHarnessCalls = environment.budgets?.maxHarnessModelCalls;
+                    if (harness && maxHarnessCalls !== undefined && harnessModelCalls >= maxHarnessCalls) {
+                        throw new Error(`MODEL_BUDGET_EXCEEDED: the program's root harness-model-call budget of ${maxHarnessCalls} was exhausted`);
+                    }
+                    const loopKey = `${name}\u0000${preview(args)}`;
+                    const repeated = (repeatedCalls.get(loopKey) ?? 0) + 1;
+                    if (repeated > MAX_IDENTICAL_TOOL_CALLS) {
+                        throw new Error(`MODEL_LOOP_DETECTED: ${name} was called ${repeated} times with the same arguments `
+                            + `(limit ${MAX_IDENTICAL_TOOL_CALLS}); the program is looping without progress`);
+                    }
+                    repeatedCalls.set(loopKey, repeated);
+                    toolCalls += 1;
+                    if (harness)
+                        harnessModelCalls += 1;
+                    const started = Date.now();
+                    const argumentsPreview = preview(args);
+                    try {
+                        const value = await binding(args);
+                        if (calls.length < MAX_TRACE_CALLS) {
+                            calls.push({
+                                name,
+                                ok: true,
+                                elapsedMs: Date.now() - started,
+                                argumentsPreview,
+                                resultPreview: preview(value),
+                            });
+                        }
+                        return value;
+                    }
+                    catch (error) {
+                        if (calls.length < MAX_TRACE_CALLS) {
+                            calls.push({
+                                name,
+                                ok: false,
+                                elapsedMs: Date.now() - started,
+                                argumentsPreview,
+                                error: error instanceof Error ? error.message : String(error),
+                            });
+                        }
+                        throw error;
+                    }
+                };
+            };
+            const bindings = buildToolBindings({
+                requested: request.requested,
+                // THE GRANT IS READ PER RUN: an external client's call composes under the
+                // CLIENT's grant (SEC-04), the host path under the host's own.
+                authority: {
+                    granted: environment.grant(),
+                    visible: environment.visible(),
+                    confidential: environment.confidential?.() ?? [],
+                },
+                resolve: countedResolve,
+            });
+            if (!bindings.ok) {
+                return { ok: false, code: 'unauthorized', message: bindings.message };
+            }
+            try {
+                /**
+                 * CODE-04: program data crosses a JSON binding, never source interpolation.
+                 * The only source addition is the constant destructuring line below; the
+                 * value itself never appears in the program text.
+                 */
+                const inputNamespace = request.input === undefined
+                    ? undefined
+                    : {
+                        global: 'inputSource',
+                        functions: {
+                            read: async () => request.input,
+                        },
+                    };
+                const program = inputNamespace === undefined
+                    ? request.program
+                    : `const input = await inputSource.read(null);\n${request.program}`;
+                const result = await programDepth.run(depth + 1, () => runtime.run(runtime.resolve({
+                    program,
+                    bindings: inputNamespace === undefined ? [bindings.namespace] : [bindings.namespace, inputNamespace],
+                    // The budget is CLAMPED here, not passed through: `null` means "no deadline" in
+                    // the runtime's vocabulary, which is a request to opt out of budgeting entirely.
+                    timeoutMs: admitTimeout(request.timeoutMs),
+                    ...request.cwd === undefined ? {} : { cwd: request.cwd },
+                    ...request.signal === undefined ? {} : { signal: request.signal },
+                })));
+                if (result.error !== undefined && result.error !== null) {
+                    // A cancelled run is NOT a failure, and the distinction reaches the caller rather
+                    // than being flattened.
+                    const kind = result.error.kind;
+                    return {
+                        ok: false,
+                        code: kind === 'abort' ? 'cancelled' : 'failed',
+                        message: result.error.message ?? `the program ended with ${String(kind)}`,
+                    };
+                }
+                return { ok: true, value: result.value, logs: result.logs ?? [], toolCalls, calls };
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    code: 'failed',
+                    message: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+    };
+}
+/**
+ * The refusal an EXTERNAL caller receives (CODE-08).
+ *
+ * A separate function so the gate has a single enforcement point rather than a condition
+ * repeated at each call site — the shape that let the original gate go unused.
+ * @param runner - the runner.
+ * @returns the refusal, or undefined when exposure is permitted.
+ */
+export function externalRefusal(runner) {
+    if (runner.externalExposurePermitted())
+        return undefined;
+    return { message: runner.externalExposureReason() };
+}
+/** The service key the runner depends on, re-exported so a caller need not import both. */
+export { PTC_SERVICE };
+/**
+ * The `tool_mode_run` MCP contract, in the ToolContract shape (CODE-02).
+ *
+ * ONE definition serves the MCP export surface and the conformance test, so the
+ * two cannot drift the way an inline object at the export site would: the test
+ * validates this shape's MCP projection against the pinned schema before it ever
+ * ships on a live tools/list.
+ */
+export const TOOL_MODE_RUN_CONTRACT = {
+    contract: 'hosted.tool_mode_run',
+    version: '1.0.0',
+    toolName: 'tool_mode_run',
+    description: 'Run a program that calls Tool Mode tools (CODE-02).',
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        // `description` is ADVISORY: `serveProgram` accepts an omitted one (it is never
+        // interpolated into source), so advertising it as required made the literal
+        // CODE-02 payload `{ code, tools }` fail the advertised schema before execution.
+        required: ['code', 'tools'],
+        properties: {
+            description: { type: 'string' },
+            code: { type: 'string' },
+            input: {},
+            tools: { type: 'array', items: { type: 'string' } },
+            timeout_ms: { type: 'integer' },
+        },
+    },
+    outputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            result: {},
+            logs: { type: 'array', items: { type: 'string' } },
+            /**
+             * The meta envelope is declared CLOSED with every field the run reports. The host's
+             * output validator treats an object without an explicit `additionalProperties` as
+             * closed, so the sub-call trace must be named here or every run fails its own
+             * schema with `value.meta.calls is not a declared property`.
+             */
+            meta: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    receiptId: { type: 'string' },
+                    elapsedMs: { type: 'number' },
+                    toolCalls: { type: 'number' },
+                    catalogRevision: { type: 'string' },
+                    warnings: { type: 'array', items: { type: 'string' } },
+                    typescript: { type: 'string' },
+                    calls: { type: 'array', items: { type: 'object', additionalProperties: true } },
+                },
+            },
+        },
+    },
+    semantics: { deterministic: false, readsInputs: true },
+    limits: {},
+    unsupported: ['no access to management or installer bindings'],
+};
+/**
+ * Serve one CODE-02 request through the authorized pipeline (CODE-02/04).
+ *
+ * This is the `tool_mode_run` served path: the caller's arguments are validated
+ * into the CODE-02 shape, the program runs through the SAME runner native PTC
+ * uses, and the report carries the receipt, elapsed time, call count, catalog
+ * revision and warnings the interface promises.
+ *
+ * `input` is refused when the pinned runtime cannot bind it structurally: CODE-04
+ * forbids string interpolation into source, and the current PTC runtime has no
+ * data-global path, so an input-bearing program gets a precise refusal naming
+ * that limitation rather than a silently interpolated program.
+ * @param args - the caller's arguments.
+ * @param runner - the prepared runner.
+ * @param report - the report-shaped facts the host owns (receipt id, revision).
+ * @returns the report.
+ */
+export async function serveProgram(args, runner, report) {
+    const description = typeof args.description === 'string' ? args.description : '';
+    const code = typeof args.code === 'string' ? args.code : '';
+    if (code.trim().length === 0) {
+        throw new Error('`code` must be a non-empty program body');
+    }
+    void description;
+    const requested = Array.isArray(args.tools)
+        ? args.tools.filter((name) => typeof name === 'string')
+        : [];
+    if (requested.length === 0) {
+        throw new Error('`tools` must name at least one tool the program will call');
+    }
+    const prepared = await runner.prepare();
+    if (!prepared.mounted && prepared.reason === 'backend-unavailable') {
+        throw new Error('the Node PTC backend is unavailable on this deployment, so no program can run');
+    }
+    const started = Date.now();
+    const outcome = await runner.run({
+        program: code,
+        requested,
+        ...args.input === undefined ? {} : { input: args.input },
+        ...typeof args.timeout_ms === 'number' ? { timeoutMs: args.timeout_ms } : {},
+    });
+    if (!outcome.ok) {
+        throw new Error(`${outcome.code}: ${outcome.message}`);
+    }
+    return {
+        result: outcome.value ?? null,
+        // `logs` is part of the advertised output; `meta` is reserved by the tool
+        // runtime and dropped from the canonical value. The accounting line is how an
+        // MCP caller sees the host's own sub-call count and trace (AT-76).
+        logs: [
+            ...outcome.logs,
+            `tool_mode_accounting:${JSON.stringify({ toolCalls: outcome.toolCalls, calls: outcome.calls })}`,
+        ],
+        meta: {
+            receiptId: report.receiptId,
+            elapsedMs: Date.now() - started,
+            toolCalls: outcome.toolCalls,
+            calls: outcome.calls,
+            catalogRevision: report.catalogRevision,
+            warnings: [],
+            typescript: generateProgramTypes(requested),
+        },
+    };
+}
+//# sourceMappingURL=tool-mode-run.js.map

package/lib/tool-sources.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Tool owner attribution for Tool Insights (plan §3.2).
+ *
+ * The owner of a tool is resolved from LIVE data first — an active extension that
+ * declares the tool name owns it — and only then from deliberately static facts:
+ * Tool Mode's own names, the `mcp__<server>__<tool>` grammar the MCP client mounts,
+ * and a pinned first-party map. Anything else is `unattributed`: the page must be
+ * able to say "we do not know" instead of guessing a package.
+ *
+ * The projection fold cannot see the extension store (it must be a pure, replayable
+ * fold), so it uses {@link staticToolOwner}: pinned map, Tool Mode, MCP grammar, then
+ * `unattributed`. Extension-owned calls are re-attributed with the live store by the
+ * report/inventory readers.
+ *
+ * @module @try-works/dsh-tool-mode/tool-sources
+ */
+/** The owner label used when no fact attributes a tool. */
+export declare const UNATTRIBUTED_OWNER = "unattributed";
+/** The package that provides Tool Mode itself. */
+export declare const TOOL_MODE_OWNER = "@try-works/dsh-tool-mode";
+/** Tool Mode's own tool names (host-local management plus the composition door). */
+export declare const TOOL_MODE_TOOL_NAMES: readonly string[];
+/**
+ * Pinned first-party tool → npm package.
+ *
+ * Factual pairs verified against the DSH packages that register them
+ * (`D:\deepseek-harness\packages\**`). This map exists because a historical call can
+ * predate the live registry observation; it is intentionally NOT a guess at the whole
+ * catalogue — an unlisted name stays `unattributed`.
+ */
+export declare const PINNED_FIRST_PARTY_TOOLS: Readonly<Record<string, string>>;
+/** How a tool came to be registered. */
+export type ToolKind = 'built-in' | 'extension' | 'tool-mode' | 'mcp' | 'custom' | 'unknown';
+/** The grouped origin the inventory renders. */
+export type ToolOrigin = 'dsh-core' | 'extension' | 'tool-mode' | 'mcp' | 'custom' | 'unknown';
+/** One resolved owner fact. */
+export interface ToolOwner {
+    /** Package/extension id, `mcp:<server>`, or {@link UNATTRIBUTED_OWNER}. */
+    readonly owner: string;
+    readonly kind: ToolKind;
+    readonly origin: ToolOrigin;
+}
+/** An extension that may own tool names, as the store describes it. */
+export interface ExtensionToolOwner {
+    /** The extension package identity. */
+    readonly id: string;
+    /** Whether the store holds an installed copy. */
+    readonly installed: boolean;
+    /** Whether the host restored it on this load. */
+    readonly active: boolean;
+    /** Tool names the manifest declares. */
+    readonly tools: readonly string[];
+}
+/**
+ * The `mcp__<server>__<tool>` server name, or null when the name is not MCP-shaped.
+ * @param name - the tool name.
+ * @returns the server name, which is empty-safe.
+ */
+export declare function mcpServerOf(name: string): string | null;
+/**
+ * Resolve owner facts that need no live registry or store (pure, replayable).
+ * @param name - the tool name.
+ * @returns the owner fact; unknown names are explicitly `unattributed`.
+ */
+export declare function staticToolOwner(name: string): ToolOwner;
+/**
+ * Resolve the LIVE owner of a tool: an installed extension's declared tool wins,
+ * then the static facts.
+ * @param name - the tool name.
+ * @param extensions - the store's extensions, as `describe()` reports them.
+ * @returns the owner fact.
+ */
+export declare function resolveToolOwner(name: string, extensions: readonly ExtensionToolOwner[]): ToolOwner;
+/**
+ * Project the store's extensions onto a name → extension owner map.
+ * @param extensions - the store's extensions.
+ * @returns extension id per declared tool name (installed extensions only).
+ */
+export declare function extensionToolOwners(extensions: readonly ExtensionToolOwner[]): ReadonlyMap<string, string>;
+//# sourceMappingURL=tool-sources.d.ts.map

package/lib/tool-sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-sources.d.ts","sourceRoot":"","sources":["../src/tool-sources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,2DAA2D;AAC3D,eAAO,MAAM,kBAAkB,iBAAiB,CAAA;AAEhD,kDAAkD;AAClD,eAAO,MAAM,eAAe,6BAA6B,CAAA;AAEzD,oFAAoF;AACpF,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAAoD,CAAA;AAEtG;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAiCpE,CAAA;AAEF,wCAAwC;AACxC,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAA;AAE5F,gDAAgD;AAChD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAA;AAE9F,+BAA+B;AAC/B,MAAM,WAAW,SAAS;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAC5B;AAED,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAClC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGvD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CASvD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,CAOnG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAO1G"}

package/lib/tool-sources.js

@@ -0,0 +1,123 @@
+/**
+ * Tool owner attribution for Tool Insights (plan §3.2).
+ *
+ * The owner of a tool is resolved from LIVE data first — an active extension that
+ * declares the tool name owns it — and only then from deliberately static facts:
+ * Tool Mode's own names, the `mcp__<server>__<tool>` grammar the MCP client mounts,
+ * and a pinned first-party map. Anything else is `unattributed`: the page must be
+ * able to say "we do not know" instead of guessing a package.
+ *
+ * The projection fold cannot see the extension store (it must be a pure, replayable
+ * fold), so it uses {@link staticToolOwner}: pinned map, Tool Mode, MCP grammar, then
+ * `unattributed`. Extension-owned calls are re-attributed with the live store by the
+ * report/inventory readers.
+ *
+ * @module @try-works/dsh-tool-mode/tool-sources
+ */
+/** The owner label used when no fact attributes a tool. */
+export const UNATTRIBUTED_OWNER = 'unattributed';
+/** The package that provides Tool Mode itself. */
+export const TOOL_MODE_OWNER = '@try-works/dsh-tool-mode';
+/** Tool Mode's own tool names (host-local management plus the composition door). */
+export const TOOL_MODE_TOOL_NAMES = Object.freeze(['model_tools', 'tool_mode_run']);
+/**
+ * Pinned first-party tool → npm package.
+ *
+ * Factual pairs verified against the DSH packages that register them
+ * (`D:\deepseek-harness\packages\**`). This map exists because a historical call can
+ * predate the live registry observation; it is intentionally NOT a guess at the whole
+ * catalogue — an unlisted name stays `unattributed`.
+ */
+export const PINNED_FIRST_PARTY_TOOLS = Object.freeze({
+    read: '@deepseek-ai/dsh-tool-fs',
+    write: '@deepseek-ai/dsh-tool-fs',
+    edit: '@deepseek-ai/dsh-tool-fs',
+    read_image: '@deepseek-ai/dsh-tool-fs',
+    glob: '@deepseek-ai/dsh-tool-fs-search',
+    grep: '@deepseek-ai/dsh-tool-fs-search',
+    pwsh: '@deepseek-ai/dsh-tool-pwsh',
+    bash: '@deepseek-ai/dsh-tool-bash',
+    web_search: '@deepseek-ai/dsh-tool-web',
+    web_fetch: '@deepseek-ai/dsh-tool-web',
+    job_list: '@deepseek-ai/dsh-tool-jobs',
+    job_output: '@deepseek-ai/dsh-tool-jobs',
+    job_kill: '@deepseek-ai/dsh-tool-jobs',
+    todo_write: '@deepseek-ai/dsh-tool-todo',
+    skill: '@deepseek-ai/dsh-tool-skill',
+    present: '@deepseek-ai/dsh-tool-present',
+    ask_user_question: '@deepseek-ai/dsh-tool-ask-user',
+    lsp: '@deepseek-ai/dsh-tool-lsp',
+    working_directory: '@deepseek-ai/dsh-tool-working-directory',
+    schedule_create: '@deepseek-ai/dsh-tool-schedule',
+    schedule_delete: '@deepseek-ai/dsh-tool-schedule',
+    schedule_list: '@deepseek-ai/dsh-tool-schedule',
+    schedule_update: '@deepseek-ai/dsh-tool-schedule',
+    create_goal: '@deepseek-ai/dsh-tool-goal',
+    get_goal: '@deepseek-ai/dsh-tool-goal',
+    update_goal: '@deepseek-ai/dsh-tool-goal',
+    list_agents: '@deepseek-ai/dsh-tool-subagent-control',
+    send_message: '@deepseek-ai/dsh-tool-subagent-control',
+    interrupt_agent: '@deepseek-ai/dsh-tool-subagent-control',
+    list_subagent_models: '@deepseek-ai/dsh-tool-subagent',
+    subagent: '@deepseek-ai/dsh-tool-subagent',
+    workflow: '@deepseek-ai/dsh-tool-workflow',
+});
+/**
+ * The `mcp__<server>__<tool>` server name, or null when the name is not MCP-shaped.
+ * @param name - the tool name.
+ * @returns the server name, which is empty-safe.
+ */
+export function mcpServerOf(name) {
+    const match = /^mcp__(.+?)__(.+)$/.exec(name);
+    return match === null ? null : (match[1] ?? null);
+}
+/**
+ * Resolve owner facts that need no live registry or store (pure, replayable).
+ * @param name - the tool name.
+ * @returns the owner fact; unknown names are explicitly `unattributed`.
+ */
+export function staticToolOwner(name) {
+    if (TOOL_MODE_TOOL_NAMES.includes(name)) {
+        return { owner: TOOL_MODE_OWNER, kind: 'tool-mode', origin: 'tool-mode' };
+    }
+    const server = mcpServerOf(name);
+    if (server !== null)
+        return { owner: `mcp:${server}`, kind: 'mcp', origin: 'mcp' };
+    const pinned = PINNED_FIRST_PARTY_TOOLS[name];
+    if (pinned !== undefined)
+        return { owner: pinned, kind: 'built-in', origin: 'dsh-core' };
+    return { owner: UNATTRIBUTED_OWNER, kind: 'unknown', origin: 'unknown' };
+}
+/**
+ * Resolve the LIVE owner of a tool: an installed extension's declared tool wins,
+ * then the static facts.
+ * @param name - the tool name.
+ * @param extensions - the store's extensions, as `describe()` reports them.
+ * @returns the owner fact.
+ */
+export function resolveToolOwner(name, extensions) {
+    for (const extension of extensions) {
+        if (!extension.installed)
+            continue;
+        if (!extension.tools.includes(name))
+            continue;
+        return { owner: extension.id, kind: 'extension', origin: 'extension' };
+    }
+    return staticToolOwner(name);
+}
+/**
+ * Project the store's extensions onto a name → extension owner map.
+ * @param extensions - the store's extensions.
+ * @returns extension id per declared tool name (installed extensions only).
+ */
+export function extensionToolOwners(extensions) {
+    const owners = new Map();
+    for (const extension of extensions) {
+        if (!extension.installed)
+            continue;
+        for (const tool of extension.tools)
+            owners.set(tool, extension.id);
+    }
+    return owners;
+}
+//# sourceMappingURL=tool-sources.js.map