@try-works/dsh-model-as-tool 0.0.0-stage → 0.1.1

package/lib/registrar.js

@@ -0,0 +1,136 @@
+/**
+ * The registrar: turns each runnable catalog model into a DSH tool.
+ *
+ * The registrar owns the translation from the catalog's declarative tool spec
+ * into a `defineTool` definition, including the parameter schema, the canonical
+ * output contract and the model-facing rendering. Registration goes through
+ * `ctx.tools.register`, whose returned disposer is the only unregister API, so
+ * the plugin can add or drop a model's tool at runtime as capability changes.
+ *
+ * @module @try-works/dsh-model-as-tool/registrar
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+/**
+ * Compile one declared parameter into the registry's parameter spec.
+ * @param type - the declared JSON-level type.
+ * @param description - the model-facing description.
+ * @param required - whether the parameter must be supplied.
+ * @returns the parameter property spec.
+ */
+function parameterSpec(type, description, required) {
+    const base = type === 'string[]'
+        ? { type: 'array', items: { type: 'string' } }
+        : { type };
+    return {
+        ...base,
+        description,
+        ...required ? { required: true } : {},
+    };
+}
+/**
+ * Build the parameter schema for one model's tool.
+ *
+ * Every catalog parameter is optional except the model's primary input, which
+ * the adapter validates as a required non-empty value. Types come from the
+ * catalog declaration, so a numeric or list parameter reaches the model as the
+ * type it actually is rather than as a string it has to re-parse.
+ * @param entry - the catalog entry.
+ * @returns the DSH parameter schema spec.
+ */
+export function buildParameters(entry) {
+    const params = entry.tool.params;
+    const names = Object.keys(params);
+    // The first documented parameter is the model's primary input.
+    const primary = names[0];
+    const schema = {};
+    for (const name of names) {
+        const param = params[name];
+        if (param === undefined)
+            continue;
+        schema[name] = parameterSpec(param.type ?? 'string', param.description, name === primary);
+    }
+    return schema;
+}
+/**
+ * Render the tool result for the model.
+ *
+ * The canonical value is the source of truth; this projection only chooses how
+ * to present it. Tongue's shaped result gets a sentence the model can act on
+ * directly, while everything else falls back to stable JSON so no information
+ * is lost to a lossy humanization.
+ * @param entry - the catalog entry.
+ * @param value - the canonical value the adapter returned.
+ * @returns the model-facing content blocks.
+ */
+export function renderResult(entry, value) {
+    if (entry.id === 'tongue' && typeof value.language === 'string') {
+        const candidates = Array.isArray(value.candidates) ? value.candidates : [];
+        const detail = candidates
+            .filter((candidate) => typeof candidate === 'object' && candidate !== null
+            && typeof candidate.language === 'string')
+            .map(candidate => `${candidate.language} ${(candidate.probability * 100).toFixed(1)}%`)
+            .join(', ');
+        const tooClose = value.isTooCloseToCall === true ? ' (too close to call)' : '';
+        return [{
+                type: 'text',
+                text: `Detected language: ${value.language}${tooClose}`
+                    + (detail.length > 0 ? `\nCandidates: ${detail}` : ''),
+            }];
+    }
+    if (entry.id === 'voz' && typeof value.text === 'string') {
+        const wordCount = typeof value.wordCount === 'number' ? value.wordCount : 0;
+        return [{
+                type: 'text',
+                text: value.text.length > 0
+                    ? value.text
+                    : `(no speech recognized; ${wordCount} words)`,
+            }];
+    }
+    return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+}
+/** The JSON-Schema type of the canonical value a model tool returns. */
+function outputSchemaFor(entry) {
+    // One open object schema for every model: the adapters return model-specific
+    // fields, and the registry validates the declared shape without forbidding a
+    // field a future adapter adds.
+    void entry;
+    return { type: 'object', additionalProperties: true };
+}
+/**
+ * Register one model's tool on the calling context.
+ * @param ctx - the context whose tool registry receives the definition; its scope decides visibility.
+ * @param entry - the catalog entry to expose.
+ * @param adapter - the adapter that invokes the model.
+ * @returns the model id, the tool name, and the disposer returned by the registry.
+ */
+export function registerModelTool(ctx, entry, adapter) {
+    const definition = defineTool({
+        name: entry.tool.name,
+        description: entry.tool.description,
+        parameters: buildParameters(entry),
+        output: {
+            schema: outputSchemaFor(entry),
+            render: (_args, value) => renderResult(entry, value),
+        },
+        async execute(args, exec) {
+            const value = await adapter.invoke({
+                args: args,
+                signal: exec.signal,
+            });
+            return value;
+        },
+        presentCall(args) {
+            const primary = Object.values(args)[0];
+            const preview = typeof primary === 'string' ? primary : undefined;
+            return {
+                card: 'generic',
+                title: `${entry.name}${entry.input === 'text' ? '' : ` (${entry.input})`}`,
+                kind: 'read',
+                ...preview !== undefined && entry.input === 'text' ? { rawInput: preview } : {},
+            };
+        },
+    });
+    const dispose = ctx.tools.register(definition);
+    return { modelId: entry.id, toolName: entry.tool.name, dispose };
+}
+//# sourceMappingURL=registrar.js.map

package/lib/skills.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Skill publication: teaches an agent when and how to use each model tool.
+ *
+ * A tool schema tells the model what it *can* call; a skill tells it when the
+ * call is the right move, when it is the wrong one, and how the result should be
+ * used downstream. This module renders one skill body per registered model from
+ * the catalog plus that model's playbook entry.
+ *
+ * @module @try-works/dsh-model-as-tool/skills
+ */
+import type { ModelCatalogEntry } from './types.ts';
+import type { ModelPlaybook } from './playbook.ts';
+/**
+ * Render the instruction body for one model's skill.
+ *
+ * The body is deliberately procedural: it names the tool, states the trigger
+ * conditions, states the anti-triggers, and describes what to do with the
+ * result. Sections with no content are omitted rather than rendered empty, so a
+ * sparse playbook still produces a clean skill.
+ * @param entry - the catalog entry.
+ * @param playbook - the model's playbook, when one is authored.
+ * @returns the markdown skill body.
+ */
+export declare function renderSkillBody(entry: ModelCatalogEntry, playbook?: ModelPlaybook): string;
+//# sourceMappingURL=skills.d.ts.map

package/lib/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAElD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,iBAAiB,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,MAAM,CAiE1F"}

package/lib/skills.js

@@ -0,0 +1,102 @@
+/**
+ * Skill publication: teaches an agent when and how to use each model tool.
+ *
+ * A tool schema tells the model what it *can* call; a skill tells it when the
+ * call is the right move, when it is the wrong one, and how the result should be
+ * used downstream. This module renders one skill body per registered model from
+ * the catalog plus that model's playbook entry.
+ *
+ * @module @try-works/dsh-model-as-tool/skills
+ */
+/**
+ * Render the instruction body for one model's skill.
+ *
+ * The body is deliberately procedural: it names the tool, states the trigger
+ * conditions, states the anti-triggers, and describes what to do with the
+ * result. Sections with no content are omitted rather than rendered empty, so a
+ * sparse playbook still produces a clean skill.
+ * @param entry - the catalog entry.
+ * @param playbook - the model's playbook, when one is authored.
+ * @returns the markdown skill body.
+ */
+export function renderSkillBody(entry, playbook) {
+    const lines = [];
+    lines.push(`# ${entry.name}`, '');
+    lines.push(entry.summary, '');
+    lines.push(`Call the \`${entry.tool.name}\` tool. ${entry.tool.returns}`, '');
+    lines.push('## When to use', '');
+    if (playbook !== undefined && playbook.whenToUse.length > 0) {
+        for (const item of playbook.whenToUse)
+            lines.push(`- ${item}`);
+    }
+    else if (entry.skill.whenToUse !== undefined) {
+        lines.push(`- ${entry.skill.whenToUse}`);
+    }
+    else {
+        lines.push(`- ${entry.summary}`);
+    }
+    lines.push('');
+    if (playbook !== undefined && playbook.whenNotToUse.length > 0) {
+        lines.push('## When not to use', '');
+        for (const item of playbook.whenNotToUse)
+            lines.push(`- ${item}`);
+        lines.push('');
+    }
+    if (playbook !== undefined && playbook.useCases.length > 0) {
+        lines.push('## Use cases', '');
+        for (const item of playbook.useCases)
+            lines.push(`- ${item}`);
+        lines.push('');
+    }
+    lines.push('## Calling it', '');
+    lines.push(`- Tool: \`${entry.tool.name}\``);
+    lines.push(`- Primary input: ${entry.input}`);
+    lines.push(`- Runs: ${describeRoute(entry)}`);
+    lines.push('');
+    for (const [name, param] of Object.entries(entry.tool.params)) {
+        lines.push(`- \`${name}\` (${param.type ?? 'string'}): ${param.description}`);
+    }
+    lines.push('');
+    if (playbook !== undefined && playbook.workflow.length > 0) {
+        lines.push('## Workflow', '');
+        playbook.workflow.forEach((step, index) => lines.push(`${index + 1}. ${step}`));
+        lines.push('');
+    }
+    if (playbook !== undefined && playbook.pairsWith.length > 0) {
+        lines.push('## Pairs with', '');
+        for (const item of playbook.pairsWith)
+            lines.push(`- ${item}`);
+        lines.push('');
+    }
+    if (playbook !== undefined && playbook.caveats.length > 0) {
+        lines.push('## Caveats', '');
+        for (const item of playbook.caveats)
+            lines.push(`- ${item}`);
+        lines.push('');
+    }
+    lines.push('## Licensing', '');
+    lines.push(`The ${entry.name} weights are licensed under the Desert Ant Labs Source-Available License `
+        + `(https://license.desertant.com/1.0), not an open-source license. Inference is unlimited and free below `
+        + '100,000 monthly active devices per platform per model; attribution is required and the models may not be '
+        + 'redistributed or re-hosted as a service. Run it locally through this tool rather than proxying it to others.', '');
+    return lines.join('\n');
+}
+/** A short human description of how this model reaches its runtime. */
+function describeRoute(entry) {
+    switch (entry.windowsSupport) {
+        case 'native-node':
+            return `in-process through ${entry.npmPackage}`;
+        case 'onnxruntime-node':
+            return `in-process through ${entry.npmPackage} with ${entry.requiresRuntime.join(', ')}`;
+        case 'browser-only':
+            return `in-process through ${entry.npmPackage}${entry.npmSubpath ?? ''} on linux-x64, linux-arm64 and darwin-arm64`;
+        case 'apple-only':
+            return 'on Apple platforms only, through the Swift SDK; not available to this process';
+        case 'no-sdk':
+            return 'nowhere yet: the weights are published but no SDK ships them';
+        /* v8 ignore next -- closed union; a new member must fail compilation here. */
+        default:
+            return 'by an unspecified route';
+    }
+}
+//# sourceMappingURL=skills.js.map

package/lib/state.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Durable install state: which models the user has enabled or disabled.
+ *
+ * A plugin's `config` states the *deployment* default — what a profile ships
+ * with. This store records the *user's* runtime choices on top of it, so an
+ * `enable`/`disable` survives a restart instead of evaporating with the session.
+ *
+ * The two layers are kept distinct on purpose:
+ *
+ * - `disabled` always wins, so a user can turn off something the config ships.
+ * - `enabled` adds to the config selection, so a user can turn on something the
+ *   config omitted without editing YAML.
+ *
+ * Writing to a file rather than back into the profile's `cordis.patch.yml` keeps
+ * the plugin out of the user's configuration: a rewrite there would fight the
+ * HMR reload and could clobber comments the user wrote.
+ *
+ * @module @try-works/dsh-model-as-tool/state
+ */
+/** The persisted user choices. */
+export interface PersistedState {
+    /** Model ids the user turned on beyond the configured selection. */
+    readonly enabled: readonly string[];
+    /** Model ids the user turned off, overriding the configured selection. */
+    readonly disabled: readonly string[];
+}
+/** An empty state. */
+export declare const EMPTY_STATE: PersistedState;
+/** Read and write the durable state. Injectable so tests need no filesystem. */
+export interface StateStore {
+    /** Read the current state; an absent or unreadable store is empty, not an error. */
+    read(): PersistedState;
+    /** Replace the state, durably. */
+    write(state: PersistedState): void;
+}
+/** Raised when a state file exists but cannot be understood. */
+export declare class StateError extends Error {
+    readonly name = "StateError";
+}
+/**
+ * Normalize a decoded state document.
+ *
+ * Unknown keys are dropped and non-string entries are rejected rather than
+ * silently ignored: a corrupted list is a bug worth surfacing, while a
+ * forward-compatible extra key is not.
+ * @param raw - the decoded JSON value.
+ * @param source - description of the origin, for messages.
+ * @returns the normalized state.
+ * @throws StateError when the document is not a valid state.
+ */
+export declare function parseState(raw: unknown, source: string): PersistedState;
+/**
+ * Derive the default state file from the environment.
+ *
+ * DSH sets `DSH_HOME`; falling back to `~/.dsh` matches the launcher's own
+ * convention for a process started without it.
+ * @param env - the environment to read; defaults to the process environment.
+ * @returns the absolute path of the state file.
+ */
+export declare function defaultStateFile(env?: NodeJS.ProcessEnv): string;
+/**
+ * Build a file-backed store.
+ *
+ * Writes go through a temporary file and a rename, so a crash mid-write leaves
+ * the previous state intact rather than a truncated document that would read as
+ * "everything the user configured is gone".
+ * @param file - absolute path of the state file.
+ * @returns the store.
+ */
+export declare function createFileStateStore(file: string): StateStore;
+/**
+ * Build an in-memory store, for tests and for deployments that asked for no
+ * persistence.
+ * @param initial - the starting state.
+ * @returns the store.
+ */
+export declare function createMemoryStateStore(initial?: PersistedState): StateStore;
+/**
+ * Apply one enable/disable choice to a state.
+ *
+ * The two lists are kept mutually exclusive so the merge rule never has to
+ * break a tie: enabling a model removes it from `disabled` and vice versa.
+ * @param state - the current state.
+ * @param modelId - the model the user acted on.
+ * @param enabled - true to turn on, false to turn off.
+ * @returns the updated state.
+ */
+export declare function withChoice(state: PersistedState, modelId: string, enabled: boolean): PersistedState;
+/**
+ * Decide the effective installed set from the configured selection and the
+ * user's persisted choices.
+ * @param configured - model ids the config selects (already intersected with what can run).
+ * @param state - the persisted user choices.
+ * @returns the model ids to install, and those the user turned off.
+ */
+export declare function resolveSelection(configured: readonly string[], state: PersistedState): {
+    install: Set<string>;
+    disabled: Set<string>;
+};
+//# sourceMappingURL=state.d.ts.map

package/lib/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC;AAED,sBAAsB;AACtB,eAAO,MAAM,WAAW,EAAE,cAA8C,CAAA;AAExE,gFAAgF;AAChF,MAAM,WAAW,UAAU;IACzB,oFAAoF;IACpF,IAAI,IAAI,cAAc,CAAA;IACtB,kCAAkC;IAClC,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAA;CACnC;AAED,gEAAgE;AAChE,qBAAa,UAAW,SAAQ,KAAK;IACnC,SAAkB,IAAI,gBAAe;CACtC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CAavE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAK7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAkC7D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,cAA4B,GAAG,UAAU,CAMxF;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,cAAc,CAKnG;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,KAAK,EAAE,cAAc,GACpB;IAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,CAMjD"}

package/lib/state.js

@@ -0,0 +1,160 @@
+/**
+ * Durable install state: which models the user has enabled or disabled.
+ *
+ * A plugin's `config` states the *deployment* default — what a profile ships
+ * with. This store records the *user's* runtime choices on top of it, so an
+ * `enable`/`disable` survives a restart instead of evaporating with the session.
+ *
+ * The two layers are kept distinct on purpose:
+ *
+ * - `disabled` always wins, so a user can turn off something the config ships.
+ * - `enabled` adds to the config selection, so a user can turn on something the
+ *   config omitted without editing YAML.
+ *
+ * Writing to a file rather than back into the profile's `cordis.patch.yml` keeps
+ * the plugin out of the user's configuration: a rewrite there would fight the
+ * HMR reload and could clobber comments the user wrote.
+ *
+ * @module @try-works/dsh-model-as-tool/state
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** An empty state. */
+export const EMPTY_STATE = { enabled: [], disabled: [] };
+/** Raised when a state file exists but cannot be understood. */
+export class StateError extends Error {
+    name = 'StateError';
+}
+/**
+ * Normalize a decoded state document.
+ *
+ * Unknown keys are dropped and non-string entries are rejected rather than
+ * silently ignored: a corrupted list is a bug worth surfacing, while a
+ * forward-compatible extra key is not.
+ * @param raw - the decoded JSON value.
+ * @param source - description of the origin, for messages.
+ * @returns the normalized state.
+ * @throws StateError when the document is not a valid state.
+ */
+export function parseState(raw, source) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new StateError(`${source} must contain a JSON object`);
+    }
+    const record = raw;
+    const list = (key) => {
+        const value = record[key] ?? [];
+        if (!Array.isArray(value) || value.some(item => typeof item !== 'string')) {
+            throw new StateError(`${source} field "${key}" must be an array of model ids`);
+        }
+        return value;
+    };
+    return { enabled: list('enabled'), disabled: list('disabled') };
+}
+/**
+ * Derive the default state file from the environment.
+ *
+ * DSH sets `DSH_HOME`; falling back to `~/.dsh` matches the launcher's own
+ * convention for a process started without it.
+ * @param env - the environment to read; defaults to the process environment.
+ * @returns the absolute path of the state file.
+ */
+export function defaultStateFile(env = process.env) {
+    const home = env.DSH_HOME !== undefined && env.DSH_HOME.length > 0
+        ? env.DSH_HOME
+        : join(homedir(), '.dsh');
+    return join(home, 'model-as-tool', 'state.json');
+}
+/**
+ * Build a file-backed store.
+ *
+ * Writes go through a temporary file and a rename, so a crash mid-write leaves
+ * the previous state intact rather than a truncated document that would read as
+ * "everything the user configured is gone".
+ * @param file - absolute path of the state file.
+ * @returns the store.
+ */
+export function createFileStateStore(file) {
+    return {
+        read() {
+            let text;
+            try {
+                text = readFileSync(file, 'utf8');
+            }
+            catch {
+                // No file yet is the normal first-run case.
+                return EMPTY_STATE;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch (error) {
+                throw new StateError(`${file} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return parseState(parsed, file);
+        },
+        write(state) {
+            const normalized = {
+                enabled: [...new Set(state.enabled)].sort(),
+                disabled: [...new Set(state.disabled)].sort(),
+            };
+            mkdirSync(dirname(file), { recursive: true });
+            const temporary = `${file}.tmp`;
+            writeFileSync(temporary, `${JSON.stringify(normalized, null, 2)}\n`, 'utf8');
+            try {
+                renameSync(temporary, file);
+            }
+            catch (error) {
+                rmSync(temporary, { force: true });
+                throw new StateError(`cannot write ${file}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    };
+}
+/**
+ * Build an in-memory store, for tests and for deployments that asked for no
+ * persistence.
+ * @param initial - the starting state.
+ * @returns the store.
+ */
+export function createMemoryStateStore(initial = EMPTY_STATE) {
+    let current = initial;
+    return {
+        read: () => current,
+        write: (state) => { current = state; },
+    };
+}
+/**
+ * Apply one enable/disable choice to a state.
+ *
+ * The two lists are kept mutually exclusive so the merge rule never has to
+ * break a tie: enabling a model removes it from `disabled` and vice versa.
+ * @param state - the current state.
+ * @param modelId - the model the user acted on.
+ * @param enabled - true to turn on, false to turn off.
+ * @returns the updated state.
+ */
+export function withChoice(state, modelId, enabled) {
+    const without = (list) => list.filter(id => id !== modelId);
+    return enabled
+        ? { enabled: [...without(state.enabled), modelId], disabled: without(state.disabled) }
+        : { enabled: without(state.enabled), disabled: [...without(state.disabled), modelId] };
+}
+/**
+ * Decide the effective installed set from the configured selection and the
+ * user's persisted choices.
+ * @param configured - model ids the config selects (already intersected with what can run).
+ * @param state - the persisted user choices.
+ * @returns the model ids to install, and those the user turned off.
+ */
+export function resolveSelection(configured, state) {
+    const disabled = new Set(state.disabled);
+    const install = new Set(configured);
+    for (const id of state.enabled)
+        install.add(id);
+    for (const id of disabled)
+        install.delete(id);
+    return { install, disabled };
+}
+//# sourceMappingURL=state.js.map