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

package/lib/skills.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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-tool-mode/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;
+/**
+ * A locally useful data-handling statement derived from the catalog route (DECL-05).
+ * @param entry - the catalog entry.
+ * @returns one sentence about where the input goes.
+ */
+export declare function describeDataHandling(entry: ModelCatalogEntry): 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,CA2G1F;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAcrE"}

package/lib/skills.js

@@ -0,0 +1,170 @@
+/**
+ * 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-tool-mode/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('');
+    }
+    /**
+     * Native AND Code Mode examples, generated from the tool's parameter map so a
+     * changed parameter changes the example rather than leaving hand-written prose to
+     * drift (DECL-05).
+     */
+    lines.push('## Examples', '');
+    const example = exampleArguments(entry);
+    lines.push('Native call:', '');
+    lines.push('```json', JSON.stringify({ tool: entry.tool.name, arguments: example }, null, 2), '```', '');
+    lines.push('Code Mode:', '');
+    lines.push('```js');
+    lines.push(`const result = await tools.${entry.tool.name}(${JSON.stringify(example)});`);
+    lines.push('return result;');
+    lines.push('```', '');
+    lines.push('## Unsupported', '');
+    const unsupported = playbook?.whenNotToUse ?? [];
+    if (unsupported.length === 0) {
+        lines.push('- No additional unsupported cases are declared for this tool.');
+    }
+    else {
+        for (const item of unsupported)
+            lines.push(`- ${item}`);
+    }
+    lines.push('');
+    lines.push('## Data handling', '');
+    lines.push(`- ${describeDataHandling(entry)}`);
+    lines.push('');
+    lines.push('## Recovery', '');
+    lines.push('- If the tool is unavailable, prepare and enable the model through the operator surface; do not install an '
+        + 'arbitrary package to work around it.');
+    lines.push('- If the call reports a validation error, fix the named argument; do not retry the same input unchanged.');
+    lines.push('- If the model returns a refusal or a model error, surface it to the caller. Do not silently fall back to a '
+        + 'remote provider or convert the input to another modality.');
+    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 locally useful data-handling statement derived from the catalog route (DECL-05).
+ * @param entry - the catalog entry.
+ * @returns one sentence about where the input goes.
+ */
+export function describeDataHandling(entry) {
+    switch (entry.windowsSupport) {
+        case 'native-node':
+        case 'onnxruntime-node':
+        case 'browser-only':
+            return `Runs in-process through ${entry.npmPackage}; this tool does not send the input to a remote service.`;
+        case 'apple-only':
+            return 'Runs on an Apple device through the Swift SDK; this Node process cannot execute it without an explicitly configured bridge.';
+        case 'no-sdk':
+            return 'No runtime is available here, so the tool cannot receive input at all.';
+        /* v8 ignore next -- closed union; a new member must fail compilation here. */
+        default:
+            return 'The execution route does not declare where input goes; treat that as unknown rather than as local.';
+    }
+}
+/** A schema-shaped example argument object from the catalog parameter map. */
+function exampleArguments(entry) {
+    return Object.fromEntries(Object.entries(entry.tool.params).map(([name, param]) => [name, sampleValue(param.type)]));
+}
+/** One representative value per declared JSON type. */
+function sampleValue(type) {
+    switch (type) {
+        case 'integer':
+        case 'number': return 1;
+        case 'boolean': return true;
+        case 'string[]': return ['example'];
+        default: return 'example';
+    }
+}
+/** 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/speech-bridge.d.ts

@@ -0,0 +1,74 @@
+/**
+ * ARCH-04 — the local Voz deployment as a shared `speechToText` provider.
+ *
+ * DSH exposes an experimental `speechToText` registry. This bridge registers a
+ * host-local provider whose `transcribe()` dispatches to the SAME `stt_transcribe`
+ * tool the native and MCP surfaces already use, so a speech request never starts
+ * a second Voz instance merely because another transport connected.
+ *
+ * The bridge is deliberately structural: the harness speech package is not a
+ * hard dependency, and an older DSH without the service simply gets no bridge.
+ */
+/** The provider facts the DSH speech registry reads. */
+export interface SpeechProviderInfoLike {
+    readonly id: string;
+    readonly name: string;
+    readonly location: 'host-local' | 'cloud';
+    readonly languages: readonly string[];
+}
+/** One provider the DSH speech registry accepts. */
+export interface SpeechProviderLike {
+    readonly info: SpeechProviderInfoLike;
+    transcribe(input: {
+        readonly audio: Uint8Array;
+        readonly language: string;
+    }, signal: AbortSignal): Promise<{
+        readonly text: string;
+        readonly audioSeconds: number;
+        readonly inferenceSeconds: number;
+    }>;
+}
+/** The slice of the DSH speech service this bridge uses. */
+export interface SpeechRegistryLike {
+    register(provider: SpeechProviderLike): () => Promise<void>;
+    /** The live provider roster, when the host exposes it. */
+    listProviders?(): readonly {
+        readonly id: string;
+    }[];
+}
+/** The slice of the host tool runtime this bridge uses. */
+export interface ToolExecutorLike {
+    execute(request: {
+        readonly name: string;
+        readonly arguments: Readonly<Record<string, unknown>>;
+        readonly signal: AbortSignal;
+    }): Promise<{
+        readonly isError?: boolean;
+        readonly value?: unknown;
+    }>;
+}
+/** Options for {@link installVozSpeechProvider}. */
+export interface VozSpeechBridgeOptions {
+    /** Directory owned by the host for the short-lived WAV handoff. */
+    readonly stateDir: string;
+    /** The already-published Voz tool; defaults to `stt_transcribe`. */
+    readonly toolName?: string;
+    /** Provider id shown to the speech UI. */
+    readonly providerId?: string;
+    /**
+     * Called when the bridge contributes nothing because the provider is already
+     * served (either visible through `listProviders()` or refused by `register()`).
+     * A skip is not an error: the existing provider remains the one deployment, and
+     * the caller can record the reason at the same level it would log one.
+     */
+    readonly onSkipped?: (reason: string) => void;
+}
+/**
+ * Register the Voz-backed speech provider.
+ * @param registry - the DSH speech service.
+ * @param tools - the host tool runtime that owns the one Voz deployment.
+ * @param options - local state directory and names.
+ * @returns the idempotent unregister function.
+ */
+export declare function installVozSpeechProvider(registry: SpeechRegistryLike, tools: ToolExecutorLike, options: VozSpeechBridgeOptions): () => Promise<void>;
+//# sourceMappingURL=speech-bridge.d.ts.map

package/lib/speech-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speech-bridge.d.ts","sourceRoot":"","sources":["../src/speech-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,wDAAwD;AACxD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAA;IACzC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;CACtC;AAED,oDAAoD;AACpD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAA;IACrC,UAAU,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC;QACzG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;QAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;KAClC,CAAC,CAAA;CACH;AAED,4DAA4D;AAC5D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3D,0DAA0D;IAC1D,aAAa,CAAC,IAAI,SAAS;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CACrD;AAED,2DAA2D;AAC3D,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,OAAO,EAAE;QACf,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;QACrD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;KAC7B,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CACtE;AAED,oDAAoD;AACpD,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;CAC9C;AAiCD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,sBAAsB,GAC9B,MAAM,OAAO,CAAC,IAAI,CAAC,CA+DrB"}

package/lib/speech-bridge.js

@@ -0,0 +1,115 @@
+/**
+ * ARCH-04 — the local Voz deployment as a shared `speechToText` provider.
+ *
+ * DSH exposes an experimental `speechToText` registry. This bridge registers a
+ * host-local provider whose `transcribe()` dispatches to the SAME `stt_transcribe`
+ * tool the native and MCP surfaces already use, so a speech request never starts
+ * a second Voz instance merely because another transport connected.
+ *
+ * The bridge is deliberately structural: the harness speech package is not a
+ * hard dependency, and an older DSH without the service simply gets no bridge.
+ */
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+/** The registration refusal DSH's speech registry raises for a duplicate id. */
+const DUPLICATE_REGISTRATION_PREFIX = 'Speech provider already registered';
+/**
+ * Whether an error is the registry's duplicate-provider refusal for THIS id.
+ *
+ * Only that one fault is recoverable. A registry that is unavailable, a malformed
+ * provider or any other throw is a real failure and must keep propagating: swallowing
+ * it would silently disable speech for the whole process.
+ * @param error - the thrown value.
+ * @param providerId - the id this bridge tried to register.
+ * @returns true only for the duplicate refusal naming this provider.
+ */
+function isDuplicateProviderError(error, providerId) {
+    return error instanceof Error
+        && error.message.startsWith(DUPLICATE_REGISTRATION_PREFIX)
+        && error.message.includes(providerId);
+}
+/** The one-line reason recorded when the bridge yields to an existing provider. */
+function skipReason(providerId) {
+    return `speech provider "${providerId}" is already registered; keeping the existing provider `
+        + '(the Voz tool bridge contributes nothing and is not needed)';
+}
+/** Languages the local Voz model accepts as hints; `auto` is the model's own mode. */
+const VOZ_LANGUAGES = [
+    'auto', 'en', 'de', 'fr', 'es', 'it', 'pt', 'nl', 'pl', 'ru', 'uk', 'tr',
+    'zh', 'ja', 'ko', 'ar', 'hi', 'vi', 'th', 'id',
+];
+/**
+ * Register the Voz-backed speech provider.
+ * @param registry - the DSH speech service.
+ * @param tools - the host tool runtime that owns the one Voz deployment.
+ * @param options - local state directory and names.
+ * @returns the idempotent unregister function.
+ */
+export function installVozSpeechProvider(registry, tools, options) {
+    const toolName = options.toolName ?? 'stt_transcribe';
+    const providerId = options.providerId ?? 'voz-local';
+    /*
+     * A profile may also mount the standalone STT plugin, which registers the same
+     * `voz-local` id. The speech registry refuses duplicates, and an uncaught throw
+     * here aborts the WHOLE model-tools plugin apply (settings, MCP, every tool).
+     * If the id is already served, this bridge contributes nothing; the existing
+     * provider remains the one headless deployment.
+     */
+    if (registry.listProviders?.().some(provider => provider.id === providerId) === true) {
+        options.onSkipped?.(skipReason(providerId));
+        return async () => { };
+    }
+    const provider = {
+        info: {
+            id: providerId,
+            name: 'Desert Ant Voz (local)',
+            location: 'host-local',
+            languages: VOZ_LANGUAGES,
+        },
+        async transcribe(input, signal) {
+            signal.throwIfAborted();
+            mkdirSync(options.stateDir, { recursive: true });
+            const dir = mkdtempSync(join(options.stateDir, 'voz-speech-'));
+            const path = join(dir, 'recording.wav');
+            try {
+                writeFileSync(path, input.audio);
+                const started = Date.now();
+                const result = await tools.execute({
+                    name: toolName,
+                    arguments: { audio: { path }, language: input.language },
+                    signal,
+                });
+                if (result.isError === true) {
+                    throw new Error(`the local Voz provider refused the recording: ${JSON.stringify(result.value)}`);
+                }
+                const value = (result.value ?? {});
+                const coverage = (value.coverage ?? {});
+                const audioSeconds = typeof coverage.transcribedSeconds === 'number' ? coverage.transcribedSeconds : 0;
+                return {
+                    text: typeof value.text === 'string' ? value.text : '',
+                    audioSeconds,
+                    inferenceSeconds: (Date.now() - started) / 1000,
+                };
+            }
+            finally {
+                rmSync(dir, { recursive: true, force: true });
+            }
+        },
+    };
+    /*
+     * The roster is not authoritative for the outcome: it can lag a provider that
+     * registered after the fast-path check (a standalone STT plugin, or a race). The
+     * registry then refuses OUR registration with the duplicate message, and that ONE
+     * refusal is a skip, not a plugin failure. Every other throw propagates.
+     */
+    try {
+        return registry.register(provider);
+    }
+    catch (error) {
+        if (!isDuplicateProviderError(error, providerId))
+            throw error;
+        options.onSkipped?.(skipReason(providerId));
+        return async () => { };
+    }
+}
+//# sourceMappingURL=speech-bridge.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-tool-mode/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-tool-mode/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