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

package/lib/discovery-contracts.js

@@ -0,0 +1,90 @@
+/**
+ * DECL-07 read-only discovery contracts.
+ *
+ * These tools were registered natively but withheld from MCP, so an authorized
+ * external caller could not read the catalogue or per-tool schemas. Their contracts
+ * are published independently of any model package; the execution path is the ordinary
+ * DSH tool runtime, not a private MCP-only handler.
+ */
+/** The result shape both discovery tools return. */
+const discoveryOutputSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['catalogRevision', 'tools'],
+    properties: {
+        catalogRevision: { type: 'string' },
+        tools: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: true,
+            },
+        },
+    },
+};
+/**
+ * `tool_mode_describe` advertises the two contract facts its result already carries.
+ *
+ * `tool_mode_list` has a different per-tool shape (readiness, no semantics), so the
+ * two tools do not share one open item schema. Both fields are declared here so an
+ * MCP client can rely on them; the item stays open for implementation-specific facts.
+ */
+const describeOutputSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['catalogRevision', 'tools'],
+    properties: {
+        catalogRevision: { type: 'string' },
+        tools: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: true,
+                properties: {
+                    name: { type: 'string' },
+                    semantics: { type: 'object', additionalProperties: true },
+                    unsupported: { type: 'array', items: { type: 'string' }, maxItems: 64 },
+                },
+            },
+        },
+    },
+};
+/** `tool_mode_list` — permitted tools, readiness and catalog revision. */
+export const TOOL_MODE_LIST_CONTRACT = {
+    contract: 'host.tool_mode_list',
+    version: '1.0.0',
+    toolName: 'tool_mode_list',
+    description: 'List the tools this caller is permitted to use, with readiness summaries and the current catalog '
+        + 'revision. Read-only discovery (DECL-07): it never installs, prepares, activates or changes anything.',
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {},
+        required: [],
+    },
+    outputSchema: discoveryOutputSchema,
+    semantics: { readOnly: true, sideEffects: false },
+    limits: {},
+    unsupported: ['Mutating the catalog or model selection.'],
+};
+/** `tool_mode_describe` — schemas, model facts, limits and catalog revision. */
+export const TOOL_MODE_DESCRIBE_CONTRACT = {
+    contract: 'host.tool_mode_describe',
+    version: '1.0.0',
+    toolName: 'tool_mode_describe',
+    description: 'Describe one or more tools by name: the selected input/output schemas, the resolved model, limits and '
+        + 'the catalog revision. Read-only discovery (DECL-07): it never installs, prepares, activates or changes anything.',
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['tools'],
+        properties: {
+            tools: { type: 'array', minItems: 1, items: { type: 'string', minLength: 1 } },
+        },
+    },
+    outputSchema: describeOutputSchema,
+    semantics: { readOnly: true, sideEffects: false },
+    limits: { maxTools: 64 },
+    unsupported: ['Mutating the catalog or model selection.'],
+};
+//# sourceMappingURL=discovery-contracts.js.map

package/lib/discovery-describe.d.ts

@@ -0,0 +1,35 @@
+/**
+ * DECL-07 describe helpers: turn a tool's selected JSON schemas into the TypeScript
+ * bindings, examples and skill instructions a tool-only MCP client can consume.
+ *
+ * The helpers are deliberately small and schema-driven: the described tool's own
+ * schemas are the source, so a changed schema changes the binding and example rather
+ * than leaving hand-written prose to drift.
+ */
+/**
+ * Render TypeScript bindings for one schema.
+ * @param name - the tool name.
+ * @param suffix - `Input` or `Output`.
+ * @param schema - the selected JSON schema.
+ * @returns an exported interface/type declaration.
+ */
+export declare function typescriptBindings(name: string, suffix: 'Input' | 'Output', schema: unknown): string;
+/** Build one example value from a JSON schema (required and optional fields included). */
+export declare function exampleFromSchema(schema: unknown): unknown;
+/** The skill facts a model-backed tool advertises (DECL-07). */
+export interface DescribeSkill {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse: string;
+}
+/**
+ * Project a catalog skill declaration into the describe payload.
+ * @param skill - the declaration, if the tool has one.
+ * @returns the skill facts, or undefined.
+ */
+export declare function describeSkill(skill: {
+    readonly name?: unknown;
+    readonly description?: unknown;
+    readonly whenToUse?: unknown;
+} | undefined): DescribeSkill | undefined;
+//# sourceMappingURL=discovery-describe.d.ts.map

package/lib/discovery-describe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery-describe.d.ts","sourceRoot":"","sources":["../src/discovery-describe.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAsCH;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAMpG;AAED,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAoB1D;AAED,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAC7B,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,CAOxC"}

package/lib/discovery-describe.js

@@ -0,0 +1,99 @@
+/**
+ * DECL-07 describe helpers: turn a tool's selected JSON schemas into the TypeScript
+ * bindings, examples and skill instructions a tool-only MCP client can consume.
+ *
+ * The helpers are deliberately small and schema-driven: the described tool's own
+ * schemas are the source, so a changed schema changes the binding and example rather
+ * than leaving hand-written prose to drift.
+ */
+/** Convert a JSON-schema type to a TypeScript type expression. */
+function schemaType(schema) {
+    if (schema === null || typeof schema !== 'object')
+        return 'unknown';
+    const value = schema;
+    if (Array.isArray(value.enum) && value.enum.length > 0) {
+        return value.enum.map(entry => JSON.stringify(entry)).join(' | ');
+    }
+    if (value.const !== undefined)
+        return JSON.stringify(value.const);
+    const type = value.type;
+    if (Array.isArray(type))
+        return type.map(single => schemaType({ ...value, type: single })).join(' | ');
+    switch (type) {
+        case 'string': return 'string';
+        case 'integer':
+        case 'number': return 'number';
+        case 'boolean': return 'boolean';
+        case 'null': return 'null';
+        case 'array': return `Array<${schemaType(value.items)}>`;
+        case 'object': {
+            const properties = value.properties;
+            if (properties === null || typeof properties !== 'object')
+                return 'Record<string, unknown>';
+            const required = new Set(Array.isArray(value.required) ? value.required : []);
+            const fields = Object.entries(properties)
+                .map(([key, property]) => `${JSON.stringify(key)}${required.has(key) ? '' : '?'}: ${schemaType(property)}`);
+            return fields.length === 0 ? 'Record<string, never>' : `{ ${fields.join('; ')} }`;
+        }
+        default: return 'unknown';
+    }
+}
+/** Pascal-case a tool name for an interface identifier. */
+function pascalCase(name) {
+    return name.split(/[^A-Za-z0-9]+/).filter(Boolean)
+        .map(part => `${part[0].toUpperCase()}${part.slice(1)}`)
+        .join('') || 'Tool';
+}
+/**
+ * Render TypeScript bindings for one schema.
+ * @param name - the tool name.
+ * @param suffix - `Input` or `Output`.
+ * @param schema - the selected JSON schema.
+ * @returns an exported interface/type declaration.
+ */
+export function typescriptBindings(name, suffix, schema) {
+    const identifier = `${pascalCase(name)}${suffix}`;
+    if (schema === null || typeof schema !== 'object' || schema.type !== 'object') {
+        return `export type ${identifier} = ${schemaType(schema)}`;
+    }
+    return `export interface ${identifier} ${schemaType(schema)}`;
+}
+/** Build one example value from a JSON schema (required and optional fields included). */
+export function exampleFromSchema(schema) {
+    if (schema === null || typeof schema !== 'object')
+        return null;
+    const value = schema;
+    if (Array.isArray(value.enum) && value.enum.length > 0)
+        return value.enum[0];
+    if (value.const !== undefined)
+        return value.const;
+    switch (value.type) {
+        case 'object': {
+            const properties = value.properties;
+            if (properties === null || typeof properties !== 'object')
+                return {};
+            return Object.fromEntries(Object.entries(properties).map(([key, property]) => [key, exampleFromSchema(property)]));
+        }
+        case 'array': return [exampleFromSchema(value.items)];
+        case 'string': return 'example';
+        case 'integer':
+        case 'number': return 1;
+        case 'boolean': return true;
+        default: return null;
+    }
+}
+/**
+ * Project a catalog skill declaration into the describe payload.
+ * @param skill - the declaration, if the tool has one.
+ * @returns the skill facts, or undefined.
+ */
+export function describeSkill(skill) {
+    if (skill === undefined || typeof skill.name !== 'string' || skill.name.length === 0)
+        return undefined;
+    return {
+        name: skill.name,
+        description: typeof skill.description === 'string' ? skill.description : '',
+        whenToUse: typeof skill.whenToUse === 'string' ? skill.whenToUse : '',
+    };
+}
+//# sourceMappingURL=discovery-describe.js.map

package/lib/embedding-index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * AT-52 — a persistent embedding index that records its space and model identity.
+ *
+ * There was no vector store in this repository, so a consumer had no safe way to
+ * persist vectors across an upgrade. This index is deliberately small but it makes
+ * the compatibility rule structural instead of documentary:
+ *   - the space id, dimensions, model id and model generation are persisted;
+ *   - a record whose space differs is refused (no 384→768 reuse);
+ *   - an upgrade bumps the index schema and keeps every vector and its space;
+ *   - a memory-only index is explicit and never writes.
+ */
+export interface EmbeddingSpaceIdentity {
+    readonly spaceId: string;
+    readonly dimensions: number;
+    readonly modelId: string;
+    readonly modelGeneration: number | string;
+}
+export interface EmbeddingRecord {
+    readonly id: string;
+    readonly vector: readonly number[];
+    readonly metadata?: Readonly<Record<string, string | number | boolean>>;
+}
+export interface EmbeddingIndexFile {
+    readonly schemaVersion: number;
+    readonly space: EmbeddingSpaceIdentity;
+    readonly records: Readonly<Record<string, EmbeddingRecord>>;
+}
+export declare class IncompatibleEmbeddingSpace extends Error {
+    readonly code = "INCOMPATIBLE_EMBEDDING_SPACE";
+    constructor(message: string);
+}
+/**
+ * A file-backed embedding index. `open` adopts the persisted space; it never
+ * silently reinterprets existing vectors in a different space.
+ */
+export declare class EmbeddingIndex {
+    #private;
+    private constructor();
+    static open(file: string | null, expected?: EmbeddingSpaceIdentity): EmbeddingIndex;
+    get space(): EmbeddingSpaceIdentity;
+    get size(): number;
+    upsert(record: EmbeddingRecord): void;
+    get(id: string): EmbeddingRecord | undefined;
+    all(): readonly EmbeddingRecord[];
+    /** Persist with the current schema version and the SAME space. */
+    save(): void;
+    /**
+     * Upgrade the index schema without touching the space or the vectors.
+     * A target space is refused unless it is identical.
+     */
+    upgrade(targetSchemaVersion: number, targetSpace?: EmbeddingSpaceIdentity): void;
+}
+/** A memory-only index: explicit, bounded to the process, never writes. */
+export declare function openMemoryEmbeddingIndex(space: EmbeddingSpaceIdentity): EmbeddingIndex;
+//# sourceMappingURL=embedding-index.d.ts.map

package/lib/embedding-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-index.d.ts","sourceRoot":"","sources":["../src/embedding-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAAA;CAC1C;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,CAAA;CACxE;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAA;IACtC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAA;CAC5D;AAED,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,kCAAiC;gBAClC,OAAO,EAAE,MAAM;CAI5B;AA+BD;;;GAGG;AACH,qBAAa,cAAc;;IAMzB,OAAO;IAOP,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,CAAC,EAAE,sBAAsB,GAAG,cAAc;IAyBnF,IAAI,KAAK,IAAI,sBAAsB,CAAuB;IAC1D,IAAI,IAAI,IAAI,MAAM,CAA8B;IAEhD,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAKrC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAC5C,GAAG,IAAI,SAAS,eAAe,EAAE;IAEjC,kEAAkE;IAClE,IAAI,IAAI,IAAI;IAYZ;;;OAGG;IACH,OAAO,CAAC,mBAAmB,EAAE,MAAM,EAAE,WAAW,GAAE,sBAAoC,GAAG,IAAI;CAY9F;AAED,2EAA2E;AAC3E,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,sBAAsB,GAAG,cAAc,CAEtF"}

package/lib/embedding-index.js

@@ -0,0 +1,126 @@
+/**
+ * AT-52 — a persistent embedding index that records its space and model identity.
+ *
+ * There was no vector store in this repository, so a consumer had no safe way to
+ * persist vectors across an upgrade. This index is deliberately small but it makes
+ * the compatibility rule structural instead of documentary:
+ *   - the space id, dimensions, model id and model generation are persisted;
+ *   - a record whose space differs is refused (no 384→768 reuse);
+ *   - an upgrade bumps the index schema and keeps every vector and its space;
+ *   - a memory-only index is explicit and never writes.
+ */
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+export class IncompatibleEmbeddingSpace extends Error {
+    code = 'INCOMPATIBLE_EMBEDDING_SPACE';
+    constructor(message) {
+        super(message);
+        this.name = 'IncompatibleEmbeddingSpace';
+    }
+}
+const INDEX_SCHEMA_VERSION = 2;
+function sameSpace(left, right) {
+    return left.spaceId === right.spaceId
+        && left.dimensions === right.dimensions
+        && left.modelId === right.modelId
+        && String(left.modelGeneration) === String(right.modelGeneration);
+}
+function validateSpace(space) {
+    if (space.spaceId.trim() === '')
+        throw new IncompatibleEmbeddingSpace('the embedding space id is empty');
+    if (!Number.isInteger(space.dimensions) || space.dimensions <= 0) {
+        throw new IncompatibleEmbeddingSpace(`invalid embedding dimensions: ${space.dimensions}`);
+    }
+    if (space.modelId.trim() === '')
+        throw new IncompatibleEmbeddingSpace('the model id is empty');
+}
+function validateRecord(record, space) {
+    if (record.id.trim() === '')
+        throw new IncompatibleEmbeddingSpace('the record id is empty');
+    if (record.vector.length !== space.dimensions) {
+        throw new IncompatibleEmbeddingSpace(`record ${record.id} has ${record.vector.length} dimensions, but space ${space.spaceId} is ${space.dimensions}-dimensional`);
+    }
+    if (!record.vector.every(value => Number.isFinite(value))) {
+        throw new IncompatibleEmbeddingSpace(`record ${record.id} contains a non-finite value`);
+    }
+}
+/**
+ * A file-backed embedding index. `open` adopts the persisted space; it never
+ * silently reinterprets existing vectors in a different space.
+ */
+export class EmbeddingIndex {
+    #file;
+    #space;
+    #schemaVersion;
+    #records = new Map();
+    constructor(file, space, schemaVersion = INDEX_SCHEMA_VERSION) {
+        validateSpace(space);
+        this.#file = file;
+        this.#space = space;
+        this.#schemaVersion = schemaVersion;
+    }
+    static open(file, expected) {
+        if (file === null) {
+            if (expected === undefined)
+                throw new IncompatibleEmbeddingSpace('a memory-only index needs an explicit space');
+            return new EmbeddingIndex(null, expected);
+        }
+        if (!existsSync(file)) {
+            if (expected === undefined)
+                throw new IncompatibleEmbeddingSpace(`the index ${file} does not exist and no space was given`);
+            return new EmbeddingIndex(file, expected);
+        }
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        if (parsed.space === undefined)
+            throw new IncompatibleEmbeddingSpace(`the index ${file} has no recorded embedding space`);
+        if (expected !== undefined && !sameSpace(parsed.space, expected)) {
+            throw new IncompatibleEmbeddingSpace(`the index ${file} records space ${parsed.space.spaceId}/${parsed.space.dimensions} model ${parsed.space.modelId}#${parsed.space.modelGeneration}, `
+                + `not ${expected.spaceId}/${expected.dimensions} model ${expected.modelId}#${expected.modelGeneration}`);
+        }
+        const index = new EmbeddingIndex(file, parsed.space, parsed.schemaVersion ?? 1);
+        for (const [id, record] of Object.entries(parsed.records ?? {})) {
+            validateRecord(record, parsed.space);
+            index.#records.set(id, record);
+        }
+        return index;
+    }
+    get space() { return this.#space; }
+    get size() { return this.#records.size; }
+    upsert(record) {
+        validateRecord(record, this.#space);
+        this.#records.set(record.id, record);
+    }
+    get(id) { return this.#records.get(id); }
+    all() { return [...this.#records.values()]; }
+    /** Persist with the current schema version and the SAME space. */
+    save() {
+        if (this.#file === null)
+            return;
+        const payload = {
+            schemaVersion: this.#schemaVersion,
+            space: this.#space,
+            records: Object.fromEntries(this.#records),
+        };
+        const temporary = `${this.#file}.tmp`;
+        writeFileSync(temporary, `${JSON.stringify(payload, null, 2)}\n`);
+        renameSync(temporary, this.#file);
+    }
+    /**
+     * Upgrade the index schema without touching the space or the vectors.
+     * A target space is refused unless it is identical.
+     */
+    upgrade(targetSchemaVersion, targetSpace = this.#space) {
+        if (!sameSpace(targetSpace, this.#space)) {
+            throw new IncompatibleEmbeddingSpace(`refusing to upgrade a ${this.#space.spaceId}/${this.#space.dimensions} index to ${targetSpace.spaceId}/${targetSpace.dimensions}`);
+        }
+        if (!Number.isInteger(targetSchemaVersion) || targetSchemaVersion < 1) {
+            throw new IncompatibleEmbeddingSpace(`invalid index schema version: ${targetSchemaVersion}`);
+        }
+        this.#schemaVersion = targetSchemaVersion;
+        this.save();
+    }
+}
+/** A memory-only index: explicit, bounded to the process, never writes. */
+export function openMemoryEmbeddingIndex(space) {
+    return EmbeddingIndex.open(null, space);
+}
+//# sourceMappingURL=embedding-index.js.map