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

package/lib/title-proposal.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Title and description proposal (TOOL-06), with the language-evidence rule from
+ * TOOL-03.
+ *
+ * TOOL-06 is mostly a list of things a title generator must NOT do, and the sharpest of
+ * them is this: **a refusal or an incomplete generation must not become a valid empty
+ * title.** That failure is easy to ship and hard to notice, because the shape of the
+ * response is correct — `{ title: "" }` looks like a result — and a caller writing it
+ * into a document produces an empty heading rather than an error.
+ *
+ * The other rules here are enforced rather than described:
+ *
+ * - **No invented facts.** A number in a proposed title that does not appear in the
+ *   source is a claim the source does not support. This is checkable, so it is checked.
+ * - **No changed source meaning.** Enforced through the same provenance check plus a
+ *   refusal to accept a title with no overlap with the source.
+ * - **No calling another tool.** Structural: the response shape carries no tool-call
+ *   field, so there is nothing to dispatch.
+ * - **Maximum lengths in the schema**, which the contract states and this enforces.
+ *
+ * @module @try-works/dsh-tool-mode/title-proposal
+ */
+/** The lengths the contract states (TOOL-06). */
+export interface TitleLimits {
+    /** Maximum characters in a title. */
+    readonly maxTitleChars: number;
+    /** Maximum characters in a description. */
+    readonly maxDescriptionChars: number;
+    /** Maximum repair attempts permitted. Zero when repairs are disabled. */
+    readonly maxRepairs: number;
+}
+/**
+ * The evaluated defaults for a section title (TOOL-06).
+ *
+ * Stated in the contract rather than chosen per call, because "define maximum
+ * title/description lengths in the schema and evaluated recipe" means a caller cannot
+ * widen them by asking.
+ */
+export declare const SECTION_TITLE_LIMITS: TitleLimits;
+/**
+ * The contract limits for one configuration's CODE-11 repair ceiling.
+ *
+ * The title/description lengths stay contract-stated; the repair ceiling is
+ * the operator's configured number (an integer 0..8, default 1). An invalid
+ * ceiling is a REFUSAL, never a silent clamp — the recorded lineage must show
+ * the budget the operator actually approved.
+ * @param repairCeiling - the configured ceiling; absent means the default 1.
+ * @returns the limits the repair decision and lineage honor.
+ */
+export declare function titleLimitsFor(repairCeiling?: number): TitleLimits;
+/** What a title is being proposed for. */
+export type TitleKind = 'section' | 'page' | 'document';
+/** The raw response a text model produced (TOOL-06). */
+export interface RawTitleResponse {
+    /** The title text, when the model produced one. */
+    readonly title?: string;
+    /** The description text, when the model produced one. */
+    readonly description?: string;
+    /**
+     * Set when the model refused.
+     *
+     * Distinguishing a refusal from an empty generation is what stops the first becoming
+     * a valid empty title.
+     */
+    readonly refused?: boolean;
+    /** Why it refused, when it did. */
+    readonly refusalReason?: string;
+    /**
+     * Set when generation was cut short.
+     *
+     * A truncated generation is not a short one; reporting it as a title claims a
+     * complete answer from an incomplete one.
+     */
+    readonly incomplete?: boolean;
+}
+/** How a proposal ended. */
+export type TitleOutcome = 
+/** A usable title. */
+{
+    readonly kind: 'proposed';
+    readonly title: string;
+    readonly description: string;
+    /** How many repair attempts were consumed, for the accounting TOOL-06 asks for. */
+    readonly repairs: number;
+}
+/**
+ * The model refused.
+ *
+ * An ERROR for the caller, never an empty title.
+ */
+ | {
+    readonly kind: 'refused';
+    readonly reason: string;
+}
+/** The generation was cut short. An error, never a short title. */
+ | {
+    readonly kind: 'incomplete';
+    readonly reason: string;
+}
+/** The response could not be used as a title. */
+ | {
+    readonly kind: 'invalid';
+    readonly reason: string;
+}
+/** The response failed validation against a rule below. */
+ | {
+    readonly kind: 'rejected';
+    readonly reason: string;
+};
+/**
+ * Accept or refuse a title proposal (TOOL-06).
+ *
+ * @param response - the model's raw response.
+ * @param source - the text the title was proposed for, used for provenance.
+ * @param limits - the lengths the contract states.
+ * @returns the outcome, which is an error rather than an empty title whenever the
+ *   response was not a usable one.
+ */
+export declare function acceptTitle(response: RawTitleResponse, source: string, limits?: TitleLimits): TitleOutcome;
+/**
+ * Whether a repair attempt may run (TOOL-06).
+ *
+ * The requirement says to COUNT repair attempts when they are enabled, so the count is
+ * returned rather than kept internally — an uncounted retry is how a budget silently
+ * becomes unbounded.
+ * @param limits - the contract's limits.
+ * @param repairsSoFar - repairs already consumed.
+ * @param previous - what the previous attempt produced.
+ * @returns whether to repair, and how many repairs would then be consumed.
+ */
+export declare function mayRepairTitle(limits: TitleLimits, repairsSoFar: number, previous: TitleOutcome): {
+    readonly repair: boolean;
+    readonly repairs: number;
+    readonly reason?: string;
+};
+/**
+ * One repair-lineage entry (CODE-11): the traceable per-attempt record the
+ * budget lineage owes — which repair, the budget before and after the
+ * decision, and the outcome the decision produced. A COUNT alone cannot show
+ * WHERE a budget was spent; the lineage does.
+ */
+export interface RepairLineageEntry {
+    /** One-based repair attempt index. */
+    readonly repairIndex: number;
+    /** The repair budget before the decision. */
+    readonly budgetBefore: number;
+    /** The repair budget after the decision (one lower when a repair ran). */
+    readonly budgetAfter: number;
+    /** What the previous attempt produced, so the lineage names WHY. */
+    readonly previousKind: string;
+    /** The decision outcome for this attempt. */
+    readonly outcome: 'repaired' | 'exhausted' | 'not-needed';
+}
+/**
+ * Record one repair decision into the lineage (CODE-11, pure and testable).
+ * @param lineage - the lineage so far (mutated in place, then returned).
+ * @param decision - the `mayRepairTitle` decision for this attempt.
+ * @param previousKind - the previous outcome kind.
+ * @param budgetBefore - the budget the decision was made against.
+ * @returns the updated lineage.
+ */
+export declare function recordRepairLineage(lineage: RepairLineageEntry[], decision: {
+    readonly repair: boolean;
+    readonly repairs: number;
+}, previousKind: string, budgetBefore: number): RepairLineageEntry[];
+/**
+ * Whether a tool may call another tool to fulfil this contract (TOOL-06).
+ *
+ * It may not: "do not call another tool". Returns false so the prohibition is asserted,
+ * and the response shape carries no tool-call field for one to be dispatched from.
+ * @returns always false.
+ */
+export declare function mayCallAnotherTool(): boolean;
+/** What a language result actually examined (TOOL-03). */
+export type LanguageEvidence = 'text' | 'audio';
+/**
+ * Whether a language result may be cited as evidence for a medium (TOOL-03).
+ *
+ * A text detector's result is evidence about the TEXT it processed and nothing else.
+ * The requirement forbids using it as evidence of the language SPOKEN in audio it has
+ * not processed, and the refusal is per-medium rather than per-result because the result
+ * itself is sound — only its use as audio evidence is not.
+ * @param examined - what the result examined.
+ * @param claimed - the medium being claimed.
+ * @returns whether the claim is supported.
+ */
+export declare function supportsLanguageClaim(examined: LanguageEvidence, claimed: LanguageEvidence): boolean;
+/**
+ * Describe what a language result is evidence for (TOOL-03).
+ * @param examined - what the result examined.
+ * @returns a description that does not overstate the result.
+ */
+export declare function describeLanguageEvidence(examined: LanguageEvidence): string;
+//# sourceMappingURL=title-proposal.d.ts.map

package/lib/title-proposal.d.ts.map

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

package/lib/title-proposal.js

@@ -0,0 +1,244 @@
+/**
+ * Title and description proposal (TOOL-06), with the language-evidence rule from
+ * TOOL-03.
+ *
+ * TOOL-06 is mostly a list of things a title generator must NOT do, and the sharpest of
+ * them is this: **a refusal or an incomplete generation must not become a valid empty
+ * title.** That failure is easy to ship and hard to notice, because the shape of the
+ * response is correct — `{ title: "" }` looks like a result — and a caller writing it
+ * into a document produces an empty heading rather than an error.
+ *
+ * The other rules here are enforced rather than described:
+ *
+ * - **No invented facts.** A number in a proposed title that does not appear in the
+ *   source is a claim the source does not support. This is checkable, so it is checked.
+ * - **No changed source meaning.** Enforced through the same provenance check plus a
+ *   refusal to accept a title with no overlap with the source.
+ * - **No calling another tool.** Structural: the response shape carries no tool-call
+ *   field, so there is nothing to dispatch.
+ * - **Maximum lengths in the schema**, which the contract states and this enforces.
+ *
+ * @module @try-works/dsh-tool-mode/title-proposal
+ */
+/**
+ * The evaluated defaults for a section title (TOOL-06).
+ *
+ * Stated in the contract rather than chosen per call, because "define maximum
+ * title/description lengths in the schema and evaluated recipe" means a caller cannot
+ * widen them by asking.
+ */
+export const SECTION_TITLE_LIMITS = {
+    // A heading is scanned, not read; beyond this it wraps and stops being a heading.
+    maxTitleChars: 80,
+    maxDescriptionChars: 240,
+    maxRepairs: 1,
+};
+/**
+ * The contract limits for one configuration's CODE-11 repair ceiling.
+ *
+ * The title/description lengths stay contract-stated; the repair ceiling is
+ * the operator's configured number (an integer 0..8, default 1). An invalid
+ * ceiling is a REFUSAL, never a silent clamp — the recorded lineage must show
+ * the budget the operator actually approved.
+ * @param repairCeiling - the configured ceiling; absent means the default 1.
+ * @returns the limits the repair decision and lineage honor.
+ */
+export function titleLimitsFor(repairCeiling) {
+    const ceiling = repairCeiling ?? SECTION_TITLE_LIMITS.maxRepairs;
+    if (!Number.isInteger(ceiling) || ceiling < 0 || ceiling > 8) {
+        throw new Error(`the repair ceiling must be an integer between 0 and 8 (CODE-11); received ${JSON.stringify(ceiling)}`);
+    }
+    return {
+        maxTitleChars: SECTION_TITLE_LIMITS.maxTitleChars,
+        maxDescriptionChars: SECTION_TITLE_LIMITS.maxDescriptionChars,
+        maxRepairs: ceiling,
+    };
+}
+/** Every number appearing in a string, as written. */
+function numbersIn(text) {
+    return text.match(/\d+(?:[.,]\d+)*/g) ?? [];
+}
+/** Content words, lowercased, for the overlap check. */
+function contentWords(text) {
+    const stop = new Set([
+        'a', 'an', 'the', 'and', 'or', 'of', 'to', 'in', 'on', 'for', 'with', 'your', 'you',
+        'this', 'that', 'is', 'are', 'be', 'it', 'at', 'by', 'as', 'how', 'what', 'why',
+    ]);
+    return new Set(text.toLowerCase().match(/[a-z][a-z'-]{2,}/g)?.filter(word => !stop.has(word)) ?? []);
+}
+/**
+ * Accept or refuse a title proposal (TOOL-06).
+ *
+ * @param response - the model's raw response.
+ * @param source - the text the title was proposed for, used for provenance.
+ * @param limits - the lengths the contract states.
+ * @returns the outcome, which is an error rather than an empty title whenever the
+ *   response was not a usable one.
+ */
+export function acceptTitle(response, source, limits = SECTION_TITLE_LIMITS) {
+    // A REFUSAL IS AN ERROR. This is the rule the requirement states most sharply, and it
+    // is checked first so a refusal can never fall through to the empty-title path.
+    if (response.refused === true) {
+        return {
+            kind: 'refused',
+            reason: response.refusalReason ?? 'the model declined to propose a title',
+        };
+    }
+    if (response.incomplete === true) {
+        return { kind: 'incomplete', reason: 'the generation was cut short, so no title was completed' };
+    }
+    const title = response.title;
+    if (typeof title !== 'string') {
+        return { kind: 'invalid', reason: 'the response carried no title field' };
+    }
+    // AN EMPTY TITLE IS NOT A VALID EMPTY TITLE. A caller writing one into a document
+    // produces a blank heading rather than an error, which is why this is refused.
+    if (title.trim().length === 0) {
+        return {
+            kind: 'rejected',
+            reason: 'the title is empty; an empty title is an error, not a valid empty result',
+        };
+    }
+    if (title.length > limits.maxTitleChars) {
+        return {
+            kind: 'rejected',
+            reason: `the title is ${title.length} characters, over the ${limits.maxTitleChars} the contract states`,
+        };
+    }
+    const description = response.description ?? '';
+    if (description.length > limits.maxDescriptionChars) {
+        return {
+            kind: 'rejected',
+            reason: `the description is ${description.length} characters, over the ${limits.maxDescriptionChars} the contract states`,
+        };
+    }
+    /**
+     * NO INVENTED FACTS: a number in the title must appear in the source.
+     *
+     * "10 Ways to Improve Performance" over a source that never says ten is a claim the
+     * source does not support, and it is exactly the kind of plausible embellishment a
+     * summariser adds. This is checkable, so it is checked rather than requested.
+     */
+    const sourceNumbers = new Set(numbersIn(source));
+    for (const number of numbersIn(title)) {
+        if (!sourceNumbers.has(number)) {
+            return {
+                kind: 'rejected',
+                reason: `the title states "${number}", which does not appear in the source`,
+            };
+        }
+    }
+    for (const number of numbersIn(description)) {
+        if (!sourceNumbers.has(number)) {
+            return {
+                kind: 'rejected',
+                reason: `the description states "${number}", which does not appear in the source`,
+            };
+        }
+    }
+    /**
+     * NO CHANGED SOURCE MEANING, approximated as a real overlap requirement.
+     *
+     * A title sharing no content word with its source is not a title FOR that source; it
+     * is a different claim wearing the shape of one.
+     */
+    const sourceWords = contentWords(source);
+    const titleWords = contentWords(title);
+    if (sourceWords.size > 0 && titleWords.size > 0) {
+        const overlap = [...titleWords].some(word => sourceWords.has(word));
+        if (!overlap) {
+            return {
+                kind: 'rejected',
+                reason: 'the title shares no content word with the source, so it is not a title for it',
+            };
+        }
+    }
+    return { kind: 'proposed', title: title.trim(), description: description.trim(), repairs: 0 };
+}
+/**
+ * Whether a repair attempt may run (TOOL-06).
+ *
+ * The requirement says to COUNT repair attempts when they are enabled, so the count is
+ * returned rather than kept internally — an uncounted retry is how a budget silently
+ * becomes unbounded.
+ * @param limits - the contract's limits.
+ * @param repairsSoFar - repairs already consumed.
+ * @param previous - what the previous attempt produced.
+ * @returns whether to repair, and how many repairs would then be consumed.
+ */
+export function mayRepairTitle(limits, repairsSoFar, previous) {
+    if (previous.kind === 'proposed') {
+        return { repair: false, repairs: repairsSoFar };
+    }
+    if (repairsSoFar >= limits.maxRepairs) {
+        // Reported as an exhausted budget rather than as a failure to produce a title, so
+        // the caller can tell the two apart.
+        return {
+            repair: false,
+            repairs: repairsSoFar,
+            reason: `the repair budget of ${limits.maxRepairs} is exhausted; the last outcome was ${previous.kind}`,
+        };
+    }
+    return { repair: true, repairs: repairsSoFar + 1 };
+}
+/**
+ * Record one repair decision into the lineage (CODE-11, pure and testable).
+ * @param lineage - the lineage so far (mutated in place, then returned).
+ * @param decision - the `mayRepairTitle` decision for this attempt.
+ * @param previousKind - the previous outcome kind.
+ * @param budgetBefore - the budget the decision was made against.
+ * @returns the updated lineage.
+ */
+export function recordRepairLineage(lineage, decision, previousKind, budgetBefore) {
+    const outcome = decision.repair
+        ? 'repaired'
+        : decision.repairs >= budgetBefore && previousKind !== 'proposed'
+            ? 'exhausted'
+            : 'not-needed';
+    lineage.push({
+        repairIndex: lineage.length + 1,
+        budgetBefore,
+        // The budget AFTER the decision is the budget before minus the one
+        // attempt a repair consumed — the lineage's own contract ("one lower
+        // when a repair ran"), never the consumed count relabelled.
+        budgetAfter: budgetBefore - (decision.repair ? 1 : 0),
+        previousKind,
+        outcome,
+    });
+    return lineage;
+}
+/**
+ * Whether a tool may call another tool to fulfil this contract (TOOL-06).
+ *
+ * It may not: "do not call another tool". Returns false so the prohibition is asserted,
+ * and the response shape carries no tool-call field for one to be dispatched from.
+ * @returns always false.
+ */
+export function mayCallAnotherTool() {
+    return false;
+}
+/**
+ * Whether a language result may be cited as evidence for a medium (TOOL-03).
+ *
+ * A text detector's result is evidence about the TEXT it processed and nothing else.
+ * The requirement forbids using it as evidence of the language SPOKEN in audio it has
+ * not processed, and the refusal is per-medium rather than per-result because the result
+ * itself is sound — only its use as audio evidence is not.
+ * @param examined - what the result examined.
+ * @param claimed - the medium being claimed.
+ * @returns whether the claim is supported.
+ */
+export function supportsLanguageClaim(examined, claimed) {
+    return examined === claimed;
+}
+/**
+ * Describe what a language result is evidence for (TOOL-03).
+ * @param examined - what the result examined.
+ * @returns a description that does not overstate the result.
+ */
+export function describeLanguageEvidence(examined) {
+    return examined === 'text'
+        ? 'the language of the supplied text; this is not evidence of the language spoken in audio'
+        : 'the language of the supplied audio';
+}
+//# sourceMappingURL=title-proposal.js.map

package/lib/tool-inventory.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The live Tool Inventory snapshot (plan §3.3).
+ *
+ * Inventory is deliberately NOT a projection: it reads the registry's model-facing
+ * schemas and the extension store's `describe()` live, so a tool that was never called
+ * still appears, and an installed-but-inactive extension's tools appear with their
+ * derived state instead of vanishing. Usage columns join from the report by name; a
+ * tool with no row is `never called` (zeros), never hidden.
+ *
+ * No payload reaches a row: the registry contributes name/description/argument count,
+ * never a schema body, and nothing here carries arguments, results, tokens or paths.
+ *
+ * @module @try-works/dsh-tool-mode/tool-inventory
+ */
+import { type ToolKind, type ToolOrigin } from './tool-sources.ts';
+/** What an inventory row says about availability. */
+export type InventoryState = 'active' | 'prepared-cold' | 'failed';
+/** One requirement fact the state derivation reads (structural subset of `ExtensionRequirement`). */
+export interface InventoryRequirement {
+    readonly kind: string;
+    readonly satisfied: boolean;
+}
+/** One extension, as the store's `describe()` reports it (structural subset). */
+export interface InventoryExtension {
+    readonly id: string;
+    readonly installed: boolean;
+    readonly active: boolean;
+    readonly tools: readonly string[];
+    /** Installed version, when the input carries it. */
+    readonly version?: string | null;
+    readonly requirements?: readonly InventoryRequirement[];
+}
+/** One registered tool's model-facing schema projection (structural subset of `ToolSchema`). */
+export interface RegistryToolDescription {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Readonly<Record<string, unknown>>;
+}
+/** The usage columns the report joins by name. */
+export interface InventoryUsageRow {
+    readonly name: string;
+    readonly calls: number;
+    readonly errors: number;
+    readonly lastUsed: number | null;
+}
+/** Everything the snapshot needs. */
+export interface InventoryInput {
+    readonly registry: readonly RegistryToolDescription[];
+    readonly extensions: readonly InventoryExtension[];
+    readonly usage: readonly InventoryUsageRow[];
+    /** Tool names the MCP export surface actually publishes. */
+    readonly mcpExposed: readonly string[];
+    /** User-authored tools, attributed to their owning profile record. */
+    readonly customTools?: readonly {
+        readonly name: string;
+        readonly id: string;
+        readonly title: string;
+    }[];
+}
+/** One inventory row. */
+export interface ToolInventoryRow {
+    readonly name: string;
+    readonly description: string;
+    readonly owner: string;
+    readonly kind: ToolKind;
+    readonly origin: ToolOrigin;
+    readonly state: InventoryState;
+    /** The owning extension id, when an extension declares the tool. */
+    readonly extension: string | null;
+    readonly version: string | null;
+    /** Alias of {@link ToolInventoryRow.version} for the client's flat contract. */
+    readonly extensionVersion: string | null;
+    /** The implementation contract version, when the host knows one (not derivable from `describe()`). */
+    readonly contractVersion: string | null;
+    /** The number of declared argument properties, never the schema body. */
+    readonly argumentCount: number;
+    /** When the tool was last registered; null when the host cannot observe it. */
+    readonly lastRegistered: number | null;
+    readonly mcpExposed: boolean;
+    readonly calls: number;
+    readonly success: number;
+    readonly lastUsed: number | null;
+}
+/**
+ * Build the inventory snapshot.
+ * @param input - the live registry, store rows, usage join and MCP surface.
+ * @returns every row, sorted by name for a deterministic page.
+ */
+export declare function buildToolInventory(input: InventoryInput): readonly ToolInventoryRow[];
+//# sourceMappingURL=tool-inventory.d.ts.map

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

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

package/lib/tool-inventory.js

@@ -0,0 +1,102 @@
+/**
+ * The live Tool Inventory snapshot (plan §3.3).
+ *
+ * Inventory is deliberately NOT a projection: it reads the registry's model-facing
+ * schemas and the extension store's `describe()` live, so a tool that was never called
+ * still appears, and an installed-but-inactive extension's tools appear with their
+ * derived state instead of vanishing. Usage columns join from the report by name; a
+ * tool with no row is `never called` (zeros), never hidden.
+ *
+ * No payload reaches a row: the registry contributes name/description/argument count,
+ * never a schema body, and nothing here carries arguments, results, tokens or paths.
+ *
+ * @module @try-works/dsh-tool-mode/tool-inventory
+ */
+import { resolveToolOwner } from "./tool-sources.js";
+/** The number of top-level declared argument properties. */
+function argumentCount(parameters) {
+    const properties = parameters['properties'];
+    if (typeof properties !== 'object' || properties === null || Array.isArray(properties))
+        return 0;
+    return Object.keys(properties).length;
+}
+/** Whether an installed extension has its declared assets prepared. */
+function assetsReady(extension) {
+    return (extension.requirements ?? []).some(requirement => requirement.kind === 'assets' && requirement.satisfied);
+}
+/** Derive the availability state of an installed, unregistered extension tool. */
+function extensionState(extension) {
+    if (extension.active)
+        return 'active';
+    return assetsReady(extension) ? 'prepared-cold' : 'failed';
+}
+/** Usage columns for a name, with never-called expressed as zeros and null. */
+function usageFor(usage, name) {
+    const row = usage.get(name);
+    if (row === undefined)
+        return { calls: 0, success: 0, lastUsed: null };
+    return { calls: row.calls, success: Math.max(0, row.calls - row.errors), lastUsed: row.lastUsed };
+}
+/**
+ * Build the inventory snapshot.
+ * @param input - the live registry, store rows, usage join and MCP surface.
+ * @returns every row, sorted by name for a deterministic page.
+ */
+export function buildToolInventory(input) {
+    const rows = new Map();
+    const usage = new Map(input.usage.map(row => [row.name, row]));
+    const exposed = new Set(input.mcpExposed);
+    const custom = new Map((input.customTools ?? []).map(tool => [tool.name, tool]));
+    for (const tool of input.registry) {
+        const customTool = custom.get(tool.name);
+        const owner = customTool === undefined
+            ? resolveToolOwner(tool.name, input.extensions)
+            : { owner: customTool.id, kind: 'custom', origin: 'custom' };
+        const extension = owner.kind === 'extension' ? input.extensions.find(candidate => candidate.id === owner.owner) : undefined;
+        rows.set(tool.name, {
+            name: tool.name,
+            description: tool.description,
+            owner: owner.owner,
+            kind: owner.kind,
+            origin: owner.origin,
+            state: 'active',
+            extension: extension?.id ?? null,
+            version: extension?.version ?? null,
+            extensionVersion: extension?.version ?? null,
+            contractVersion: null,
+            lastRegistered: null,
+            argumentCount: argumentCount(tool.parameters),
+            // model_tools is host-local by design; the surface can never expose it.
+            mcpExposed: tool.name !== 'model_tools' && exposed.has(tool.name),
+            ...usageFor(usage, tool.name),
+        });
+    }
+    for (const extension of input.extensions) {
+        if (!extension.installed)
+            continue;
+        for (const name of extension.tools) {
+            if (rows.has(name))
+                continue;
+            rows.set(name, {
+                name,
+                // The store reports tool NAMES, not their descriptions; inventing prose would
+                // be worse than the empty string the schema has no registry row for.
+                description: '',
+                owner: extension.id,
+                kind: 'extension',
+                origin: 'extension',
+                state: extensionState(extension),
+                extension: extension.id,
+                version: extension.version ?? null,
+                extensionVersion: extension.version ?? null,
+                contractVersion: null,
+                lastRegistered: null,
+                argumentCount: 0,
+                mcpExposed: name !== 'model_tools' && exposed.has(name),
+                ...usageFor(usage, name),
+            });
+        }
+    }
+    return [...rows.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+//# sourceMappingURL=tool-inventory.js.map