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

package/lib/catalog.js

@@ -0,0 +1,274 @@
+/**
+ * Loads and validates the Desert Ant Labs model catalog.
+ *
+ * The catalog is plain JSON shipped beside the plugin so that a deployment can
+ * inspect or override it without rebuilding: `catalogFile` points at another
+ * document with the same shape.
+ *
+ * @module @try-works/dsh-tool-mode/catalog
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+/** Absolute path of the catalog document shipped with this package. */
+export const DEFAULT_CATALOG_FILE = fileURLToPath(new URL('../catalog/desert-ant-models.json', import.meta.url));
+const INPUTS = ['text', 'audio', 'image', 'video', 'stroke', 'transcript'];
+const WINDOWS_SUPPORT = [
+    'native-node',
+    'onnxruntime-node',
+    'apple-only',
+    'browser-only',
+    'no-sdk',
+];
+/** Raised when the catalog document is missing, unparseable, or malformed. */
+export class CatalogError extends Error {
+    name = 'CatalogError';
+}
+function fail(source, message) {
+    throw new CatalogError(`${source}: ${message}`);
+}
+function requireString(entry, key, source) {
+    const value = entry[key];
+    if (typeof value !== 'string' || value.length === 0) {
+        fail(source, `entry "${String(entry.id ?? '?')}" field "${key}" must be a non-empty string`);
+    }
+    return value;
+}
+const PARAM_TYPES = ['string', 'number', 'integer', 'boolean', 'string[]'];
+/**
+ * Normalize one parameter declaration.
+ *
+ * The string shorthand exists because most parameters are prose descriptions of
+ * a string argument; accepting it here keeps the catalog readable while the
+ * registrar still receives one resolved shape.
+ * @param raw - the declaration as written in the document.
+ * @param scope - entry description for error messages.
+ * @param key - parameter name.
+ * @returns the normalized parameter.
+ */
+function parseParam(raw, scope, key) {
+    if (typeof raw === 'string' && raw.length > 0)
+        return { description: raw, type: 'string' };
+    if (typeof raw === 'object' && raw !== null && !Array.isArray(raw)) {
+        const spec = raw;
+        const description = spec.description;
+        if (typeof description !== 'string' || description.length === 0) {
+            throw new CatalogError(`${scope} tool.params.${key}.description must be a non-empty string`);
+        }
+        const type = spec.type;
+        if (type !== undefined && !PARAM_TYPES.includes(type)) {
+            throw new CatalogError(`${scope} tool.params.${key}.type must be one of ${PARAM_TYPES.join(', ')}`);
+        }
+        return { description, type: type ?? 'string' };
+    }
+    throw new CatalogError(`${scope} tool.params.${key} must be a description string or a parameter object`);
+}
+/**
+ * Validate the optional `contract` binding.
+ *
+ * A model without a contract is legitimate — it keeps a per-model tool — but a
+ * malformed contract identity would bind a tool to a name no caller can address,
+ * so it fails at load rather than at registration.
+ * @param value - the raw field.
+ * @param scope - entry description for error messages.
+ * @param source - document description for error messages.
+ * @returns the contract id, or null when unbound.
+ */
+/**
+ * Parse a model's extension provider binding (BASE-09).
+ *
+ * The binding names the package that implements the model. It is validated here
+ * rather than trusted, because it decides which package's code the host will
+ * import: a malformed binding must fail the catalog load rather than surface later
+ * as an import of something unintended.
+ * @param raw - the raw `provider` field.
+ * @param source - the catalog source, for error messages.
+ * @returns the binding field, or an empty object when absent.
+ */
+function parseProvider(raw, source) {
+    if (raw === undefined || raw === null)
+        return {};
+    const value = raw;
+    const extension = value.extension;
+    const modelId = value.modelId;
+    if (typeof extension !== 'string' || extension.length === 0) {
+        throw new Error(`${source}: provider.extension must be a non-empty package name`);
+    }
+    if (typeof modelId !== 'string' || modelId.length === 0) {
+        throw new Error(`${source}: provider.modelId must be a non-empty string`);
+    }
+    // A relative path is admitted so a first-party package can be exercised from a
+    // checkout; anything else must look like a package specifier.
+    const packageLike = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(extension);
+    const relativeLike = extension.startsWith('./') || extension.startsWith('../');
+    if (!packageLike && !relativeLike) {
+        throw new Error(`${source}: provider.extension ${JSON.stringify(extension)} is neither a package specifier nor a relative path`);
+    }
+    return { provider: { extension, modelId } };
+}
+function parseContract(value, scope, source) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== 'string') {
+        throw new CatalogError(`${source}: ${scope} field "contract" must be a contract id or null`);
+    }
+    if (!/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/.test(value)) {
+        throw new CatalogError(`${source}: ${scope} field "contract" ${JSON.stringify(value)} must be a dotted lower-case `
+            + 'contract identity (for example "stt.transcribe")');
+    }
+    return value;
+}
+/**
+ * Parse and validate one catalog entry. Validation is strict on purpose: every
+ * downstream decision (which tool to register, whether it can run, what the
+ * model sees) reads these fields, so a malformed entry must fail at load rather
+ * than become a silently missing tool.
+ * @param raw - one decoded JSON object.
+ * @param source - description of where the document came from, for messages.
+ * @param index - position in the array, for entries with no usable id.
+ * @returns the validated entry.
+ */
+export function parseCatalogEntry(raw, source, index) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        fail(source, `entry ${String(index)} must be an object`);
+    }
+    const entry = raw;
+    const id = requireString(entry, 'id', source);
+    const scope = `entry "${id}"`;
+    const input = requireString(entry, 'input', source);
+    if (!INPUTS.includes(input)) {
+        fail(source, `${scope} has unsupported input ${JSON.stringify(input)} (expected one of ${INPUTS.join(', ')})`);
+    }
+    const windowsSupport = requireString(entry, 'windowsSupport', source);
+    if (!WINDOWS_SUPPORT.includes(windowsSupport)) {
+        fail(source, `${scope} has unsupported windowsSupport ${JSON.stringify(windowsSupport)} (expected one of ${WINDOWS_SUPPORT.join(', ')})`);
+    }
+    const tool = entry.tool;
+    if (typeof tool !== 'object' || tool === null)
+        fail(source, `${scope} is missing its "tool" object`);
+    const skill = entry.skill;
+    if (typeof skill !== 'object' || skill === null)
+        fail(source, `${scope} is missing its "skill" object`);
+    const toolSpec = tool;
+    const skillSpec = skill;
+    const params = toolSpec.params;
+    if (typeof params !== 'object' || params === null || Array.isArray(params)) {
+        fail(source, `${scope} tool.params must be an object`);
+    }
+    const bool = (key) => {
+        const value = entry[key];
+        if (typeof value !== 'boolean')
+            fail(source, `${scope} field "${key}" must be a boolean`);
+        return value;
+    };
+    const nullableNumber = (key) => {
+        const value = entry[key];
+        if (value !== null && (typeof value !== 'number' || !Number.isFinite(value))) {
+            fail(source, `${scope} field "${key}" must be a finite number or null`);
+        }
+        return value;
+    };
+    const nullableString = (key) => {
+        const value = entry[key];
+        if (value !== null && typeof value !== 'string') {
+            fail(source, `${scope} field "${key}" must be a string or null`);
+        }
+        return value;
+    };
+    const strings = (key) => {
+        const value = entry[key];
+        if (!Array.isArray(value) || value.some(item => typeof item !== 'string')) {
+            fail(source, `${scope} field "${key}" must be an array of strings`);
+        }
+        return value;
+    };
+    const toolName = requireString(toolSpec, 'name', source);
+    if (!/^[a-z][a-z0-9_]*$/.test(toolName)) {
+        fail(source, `${scope} tool.name ${JSON.stringify(toolName)} must be lower snake_case starting with a letter`);
+    }
+    const skillName = requireString(skillSpec, 'name', source);
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(skillName)) {
+        fail(source, `${scope} skill.name ${JSON.stringify(skillName)} must be kebab-case`);
+    }
+    return {
+        id,
+        name: requireString(entry, 'name', source),
+        summary: requireString(entry, 'summary', source),
+        capability: requireString(entry, 'capability', source),
+        contract: parseContract(entry.contract, scope, source),
+        ...parseProvider(entry.provider, source),
+        input: input,
+        output: requireString(entry, 'output', source),
+        languages: nullableNumber('languages'),
+        modelSizeMB: nullableNumber('modelSizeMB'),
+        appleOnly: bool('appleOnly'),
+        closedBeta: bool('closedBeta'),
+        verifiedRunnableOnWindows: bool('verifiedRunnableOnWindows'),
+        windowsSupport: windowsSupport,
+        npmPackage: nullableString('npmPackage'),
+        npmSubpath: nullableString('npmSubpath'),
+        requiresRuntime: strings('requiresRuntime'),
+        cliVerb: nullableString('cliVerb'),
+        license: requireString(entry, 'license', source),
+        docsUrl: requireString(entry, 'docsUrl', source),
+        hfRepo: requireString(entry, 'hfRepo', source),
+        tool: {
+            name: toolName,
+            description: requireString(toolSpec, 'description', source),
+            params: Object.fromEntries(Object.entries(params).map(([key, value]) => [
+                key,
+                parseParam(value, scope, key),
+            ])),
+            returns: requireString(toolSpec, 'returns', source),
+        },
+        skill: {
+            name: skillName,
+            description: requireString(skillSpec, 'description', source),
+            ...typeof skillSpec.whenToUse === 'string' ? { whenToUse: skillSpec.whenToUse } : {},
+        },
+    };
+}
+/**
+ * Load the catalog from a JSON document.
+ * @param file - absolute path of the catalog document.
+ * @returns every validated entry, in document order.
+ * @throws CatalogError when the file cannot be read, is not valid JSON, is not an array, or holds a malformed entry.
+ */
+export function loadCatalog(file = DEFAULT_CATALOG_FILE) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        // Node errors are not stable enough to switch on; the message is the point.
+        throw new CatalogError(`cannot read model catalog ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new CatalogError(`${file} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!Array.isArray(parsed))
+        throw new CatalogError(`${file} must contain a JSON array of model entries`);
+    const entries = parsed.map((raw, index) => parseCatalogEntry(raw, file, index));
+    const seen = new Set();
+    for (const entry of entries) {
+        if (seen.has(entry.id))
+            throw new CatalogError(`${file} declares model id "${entry.id}" more than once`);
+        seen.add(entry.id);
+    }
+    const toolNames = new Set();
+    for (const entry of entries) {
+        if (toolNames.has(entry.tool.name)) {
+            throw new CatalogError(`${file} maps tool name "${entry.tool.name}" to more than one model`);
+        }
+        toolNames.add(entry.tool.name);
+    }
+    return entries;
+}
+/** Index a catalog by model id. */
+export function indexCatalog(entries) {
+    return new Map(entries.map(entry => [entry.id, entry]));
+}
+//# sourceMappingURL=catalog.js.map

package/lib/contract-payload.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Translation from a model's native result to a contract's payload.
+ *
+ * The spec puts this responsibility on adapters: they "translate between the
+ * capability's canonical representation and the model's native interface". It is
+ * a separate module from the invoke adapters because the two change for different
+ * reasons — an adapter changes when the vendor SDK does, a translator changes when
+ * the contract does — and conflating them is how a contract silently drifts to
+ * match whatever the SDK happened to return.
+ *
+ * The contract is the authority. When a translation cannot supply a field the
+ * contract requires, that is reported rather than faked; TOOL-01 is explicit that
+ * an incomplete clip must not be presented as fully transcribed.
+ *
+ * @module @try-works/dsh-tool-mode/contract-payload
+ */
+import type { JsonValue } from './adapters/index.ts';
+/** Raised when a native result cannot be expressed under its contract. */
+export declare class PayloadTranslationError extends Error {
+    readonly name = "PayloadTranslationError";
+}
+/**
+ * Translate the contract's caller-facing arguments into the implementation's
+ * native vocabulary.
+ * @param contractId - the contract the implementation was selected for.
+ * @param contractArgs - the validated contract arguments.
+ * @returns the native argument shape.
+ */
+export declare function toNativeArgs(contractId: string, contractArgs: Readonly<Record<string, unknown>>): Record<string, unknown>;
+/**
+ * Translate a native implementation result into the payload its contract declares.
+ * @param contractId - the contract the implementation was selected for.
+ * @param native - the adapter's native result.
+ * @param args - the validated arguments, for contract-conditional translation.
+ * @returns the contract payload.
+ * @throws PayloadTranslationError when the native result cannot satisfy the contract.
+ */
+export declare function toContractPayload(contractId: string, native: Record<string, JsonValue>, args?: Readonly<Record<string, unknown>>): Record<string, JsonValue>;
+//# sourceMappingURL=contract-payload.d.ts.map

package/lib/contract-payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-payload.d.ts","sourceRoot":"","sources":["../src/contract-payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAEpD,0EAA0E;AAC1E,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,SAAkB,IAAI,6BAA4B;CACnD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC9C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWzB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EACjC,IAAI,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM,GAC3C,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAO3B"}

package/lib/contract-payload.js

@@ -0,0 +1,56 @@
+/**
+ * Translation from a model's native result to a contract's payload.
+ *
+ * The spec puts this responsibility on adapters: they "translate between the
+ * capability's canonical representation and the model's native interface". It is
+ * a separate module from the invoke adapters because the two change for different
+ * reasons — an adapter changes when the vendor SDK does, a translator changes when
+ * the contract does — and conflating them is how a contract silently drifts to
+ * match whatever the SDK happened to return.
+ *
+ * The contract is the authority. When a translation cannot supply a field the
+ * contract requires, that is reported rather than faked; TOOL-01 is explicit that
+ * an incomplete clip must not be presented as fully transcribed.
+ *
+ * @module @try-works/dsh-tool-mode/contract-payload
+ */
+/** Raised when a native result cannot be expressed under its contract. */
+export class PayloadTranslationError extends Error {
+    name = 'PayloadTranslationError';
+}
+/**
+ * Translate the contract's caller-facing arguments into the implementation's
+ * native vocabulary.
+ * @param contractId - the contract the implementation was selected for.
+ * @param contractArgs - the validated contract arguments.
+ * @returns the native argument shape.
+ */
+export function toNativeArgs(contractId, contractArgs) {
+    void contractId;
+    /**
+     * TASK-115/120/121: the extension implementations now speak the CONTRACT
+     * vocabulary on BOTH sides (the tongue/voz mappings published in 0.1.3 and
+     * 0.1.5 read {audio:{path}} and emit the contract payloads), so the host's
+     * argument translation is a PASS-THROUGH — the old audio_path/include_words
+     * native vocabulary no longer exists on the wire. A future implementation
+     * with a genuinely different native vocabulary re-introduces its case here.
+     */
+    return { ...contractArgs };
+}
+/**
+ * Translate a native implementation result into the payload its contract declares.
+ * @param contractId - the contract the implementation was selected for.
+ * @param native - the adapter's native result.
+ * @param args - the validated arguments, for contract-conditional translation.
+ * @returns the contract payload.
+ * @throws PayloadTranslationError when the native result cannot satisfy the contract.
+ */
+export function toContractPayload(contractId, native, args = {}) {
+    void contractId;
+    void args;
+    // TASK-115/120/121: the extension implementations emit the CONTRACT payloads
+    // directly, so the result translation is the identity; the output schema's
+    // validation is the authority that accepts or rejects the payload.
+    return native;
+}
+//# sourceMappingURL=contract-payload.js.map

package/lib/custom-tools/compile.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Compile a validated custom-tool record into a real DSH tool definition.
+ *
+ * The authoring record is data; this module is the only place that turns it into
+ * the executable definition the registry consumes. Executors are injected so the
+ * HTTP/prompt/composite slices can be tested independently.
+ *
+ * @module @try-works/dsh-tool-mode/custom-tools/compile
+ */
+import type { CustomToolRecord } from './types.ts';
+/** Execution context a custom-tool executor needs. */
+export interface CustomToolExecContext {
+    readonly signal: AbortSignal;
+}
+/** The executor contract shared by all three kinds. */
+export type CustomToolExecutor = (record: CustomToolRecord, args: Readonly<Record<string, unknown>>, context: CustomToolExecContext) => Promise<unknown>;
+/**
+ * Compile one record. Validation is the caller's responsibility; the store and
+ * save path validate before calling this.
+ * @param record - validated authoring record.
+ * @param execute - kind-specific executor.
+ * @returns the definition accepted by `ctx.tools.register`.
+ */
+export declare function compileCustomTool(record: CustomToolRecord, execute: CustomToolExecutor): import("@deepseek-ai/dsh-tools").ToolDefinition;
+//# sourceMappingURL=compile.d.ts.map

package/lib/custom-tools/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/custom-tools/compile.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD,sDAAsD;AACtD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC7B;AAED,uDAAuD;AACvD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,OAAO,EAAE,qBAAqB,KAC3B,OAAO,CAAC,OAAO,CAAC,CAAA;AAErB;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,kBAAkB,mDAyCtF"}

package/lib/custom-tools/compile.js

@@ -0,0 +1,61 @@
+/**
+ * Compile a validated custom-tool record into a real DSH tool definition.
+ *
+ * The authoring record is data; this module is the only place that turns it into
+ * the executable definition the registry consumes. Executors are injected so the
+ * HTTP/prompt/composite slices can be tested independently.
+ *
+ * @module @try-works/dsh-tool-mode/custom-tools/compile
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { projectSchemaToDsh } from '@try-works/tool-mode-contracts';
+/**
+ * Compile one record. Validation is the caller's responsibility; the store and
+ * save path validate before calling this.
+ * @param record - validated authoring record.
+ * @param execute - kind-specific executor.
+ * @returns the definition accepted by `ctx.tools.register`.
+ */
+export function compileCustomTool(record, execute) {
+    const outputSchema = record.outputSchema === undefined
+        ? undefined
+        : {
+            type: 'object',
+            properties: projectSchemaToDsh(record.outputSchema).parameters,
+            additionalProperties: false,
+        };
+    const parameters = projectSchemaToDsh(record.parameters).parameters;
+    const declaredOutput = outputSchema === undefined
+        ? { type: 'object', additionalProperties: true }
+        : outputSchema;
+    return defineTool({
+        name: record.name,
+        description: record.description,
+        parameters: parameters,
+        output: {
+            schema: declaredOutput,
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: typeof value === 'string' ? value : JSON.stringify(value),
+                }],
+        },
+        timeoutMs: record.policy.timeoutMs,
+        async execute(args, exec) {
+            const value = await execute(record, args, { signal: exec.signal });
+            // With no declared output schema the registry advertises an open object.
+            // Preserve a scalar/list result inside that envelope instead of dropping it.
+            if (outputSchema === undefined && (typeof value !== 'object' || value === null || Array.isArray(value))) {
+                return { result: value };
+            }
+            return value;
+        },
+        presentCall() {
+            return {
+                card: 'generic',
+                title: record.title,
+                kind: record.policy.readOnly ? 'read' : 'execute',
+            };
+        },
+    });
+}
+//# sourceMappingURL=compile.js.map

package/lib/custom-tools/composite-executor.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Composite custom-tool executor.
+ *
+ * A bounded sequential pipeline over existing tools. It never loops, never calls
+ * itself, and requires an explicit approval seam for steps marked destructive.
+ *
+ * @module @try-works/dsh-tool-mode/custom-tools/composite-executor
+ */
+import type { CustomToolExecContext } from './compile.ts';
+import type { CustomToolRecord } from './types.ts';
+/** A named composite-execution refusal. */
+export declare class CustomToolCompositeError extends Error {
+    readonly name = "CustomToolCompositeError";
+    readonly code: 'custom-tool-composite-unavailable' | 'custom-tool-composite-step-invalid' | 'custom-tool-composite-approval-denied' | 'custom-tool-composite-failed';
+    constructor(code: CustomToolCompositeError['code'], message: string, options?: ErrorOptions);
+}
+/** One call into the real tool registry. */
+export type CompositeToolCall = (name: string, args: Readonly<Record<string, unknown>>, signal: AbortSignal) => Promise<unknown>;
+/** Optional approval for a destructive step. */
+export type CompositeApproval = (step: {
+    readonly tool: string;
+    readonly index: number;
+}) => Promise<boolean>;
+/** Composite executor seams. */
+export interface CompositeExecutorDeps {
+    readonly callTool?: CompositeToolCall;
+    readonly approve?: CompositeApproval;
+    /** The tool name owning this record; self-calls are refused. */
+    readonly selfName?: string;
+}
+declare function asRecord(value: unknown): Record<string, unknown>;
+/**
+ * Execute one composite tool.
+ * @param record - validated composite record.
+ * @param args - arguments.
+ * @param context - cancellation.
+ * @param deps - registry and approval seams.
+ * @returns the selected final value.
+ */
+export declare function executeCompositeCustomTool(record: CustomToolRecord, args: Readonly<Record<string, unknown>>, context: CustomToolExecContext, deps?: CompositeExecutorDeps): Promise<unknown>;
+export { asRecord };
+//# sourceMappingURL=composite-executor.d.ts.map

package/lib/custom-tools/composite-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite-executor.d.ts","sourceRoot":"","sources":["../../src/custom-tools/composite-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD,2CAA2C;AAC3C,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,SAAkB,IAAI,8BAA6B;IACnD,QAAQ,CAAC,IAAI,EACT,mCAAmC,GACnC,oCAAoC,GACpC,uCAAuC,GACvC,8BAA8B,CAAA;gBAEtB,IAAI,EAAE,wBAAwB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAI5F;AAED,4CAA4C;AAC5C,MAAM,MAAM,iBAAiB,GAAG,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,MAAM,EAAE,WAAW,KAChB,OAAO,CAAC,OAAO,CAAC,CAAA;AAErB,gDAAgD;AAChD,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;AAE7G,gCAAgC;AAChC,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAA;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAA;IACpC,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,iBAAS,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIzD;AAoCD;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,OAAO,EAAE,qBAAqB,EAC9B,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,OAAO,CAAC,CA2ClB;AAED,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/lib/custom-tools/composite-executor.js

@@ -0,0 +1,113 @@
+/**
+ * Composite custom-tool executor.
+ *
+ * A bounded sequential pipeline over existing tools. It never loops, never calls
+ * itself, and requires an explicit approval seam for steps marked destructive.
+ *
+ * @module @try-works/dsh-tool-mode/custom-tools/composite-executor
+ */
+/** A named composite-execution refusal. */
+export class CustomToolCompositeError extends Error {
+    name = 'CustomToolCompositeError';
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function readPath(value, path) {
+    let current = value;
+    for (const segment of path) {
+        if (Array.isArray(current))
+            current = current[Number(segment)];
+        else if (typeof current === 'object' && current !== null)
+            current = current[segment];
+        else
+            return undefined;
+    }
+    return current;
+}
+/** Resolve `{{arg}}`, `{{steps.N.result}}` and `{{steps.N.result.path}}`. */
+function interpolate(template, args, results) {
+    return template.replace(/\{\{([^}]+)\}\}/g, (_whole, expression) => {
+        const trimmed = expression.trim();
+        if (trimmed.startsWith('steps.')) {
+            const segments = trimmed.split('.');
+            const index = Number(segments[1]);
+            if (!Number.isInteger(index) || index < 0 || index >= results.length) {
+                throw new CustomToolCompositeError('custom-tool-composite-step-invalid', `${trimmed} does not name a previous step`);
+            }
+            const value = readPath(results[index], segments.slice(3));
+            if (value === undefined) {
+                throw new CustomToolCompositeError('custom-tool-composite-step-invalid', `${trimmed} resolved to no value`);
+            }
+            return typeof value === 'string' ? value : JSON.stringify(value);
+        }
+        const value = args[trimmed];
+        if (value === undefined) {
+            throw new CustomToolCompositeError('custom-tool-composite-step-invalid', `argument ${JSON.stringify(trimmed)} is missing`);
+        }
+        return String(value);
+    });
+}
+/**
+ * Execute one composite tool.
+ * @param record - validated composite record.
+ * @param args - arguments.
+ * @param context - cancellation.
+ * @param deps - registry and approval seams.
+ * @returns the selected final value.
+ */
+export async function executeCompositeCustomTool(record, args, context, deps = {}) {
+    if (record.execution.kind !== 'composite') {
+        throw new CustomToolCompositeError('custom-tool-composite-step-invalid', `${record.id} is not a composite tool`);
+    }
+    if (deps.callTool === undefined) {
+        throw new CustomToolCompositeError('custom-tool-composite-unavailable', 'no tool dispatcher is mounted for composite tools');
+    }
+    const results = [];
+    const selfName = deps.selfName ?? record.name;
+    for (const [index, step] of record.execution.composite.steps.entries()) {
+        if (step.tool === selfName) {
+            throw new CustomToolCompositeError('custom-tool-composite-step-invalid', `${record.id} may not call itself`);
+        }
+        if (step.requiresApproval === true) {
+            if (deps.approve === undefined) {
+                throw new CustomToolCompositeError('custom-tool-composite-approval-denied', `step ${index} (${step.tool}) requires approval, but no approval surface is mounted`);
+            }
+            if (!await deps.approve({ tool: step.tool, index })) {
+                throw new CustomToolCompositeError('custom-tool-composite-approval-denied', `step ${index} (${step.tool}) was not approved`);
+            }
+        }
+        const stepArgs = {};
+        for (const [key, template] of Object.entries(step.args)) {
+            stepArgs[key] = interpolate(template, args, results);
+        }
+        try {
+            results.push(await deps.callTool(step.tool, stepArgs, context.signal));
+        }
+        catch (error) {
+            throw new CustomToolCompositeError('custom-tool-composite-failed', `step ${index} (${step.tool}) failed`, { cause: error });
+        }
+    }
+    const output = record.execution.composite.output;
+    if (output === undefined)
+        return results[results.length - 1];
+    if (output.startsWith('steps.')) {
+        const segments = output.split('.');
+        const index = Number(segments[1]);
+        if (!Number.isInteger(index) || index < 0 || index >= results.length) {
+            throw new CustomToolCompositeError('custom-tool-composite-step-invalid', `${output} does not name a previous step`);
+        }
+        const value = readPath(results[index], segments.slice(3));
+        return value;
+    }
+    return interpolate(output, args, results);
+}
+export { asRecord };
+//# sourceMappingURL=composite-executor.js.map

package/lib/custom-tools/dispatch.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Kind dispatch for custom tools.
+ *
+ * @module @try-works/dsh-tool-mode/custom-tools/dispatch
+ */
+import type { CustomToolExecContext, CustomToolExecutor } from './compile.ts';
+import { type CompositeExecutorDeps } from './composite-executor.ts';
+import { type HttpExecutorDeps } from './http-executor.ts';
+import { type PromptExecutorDeps } from './prompt-executor.ts';
+import type { CustomToolRecord } from './types.ts';
+/** One deps object for all three kinds. */
+export interface CustomToolDispatchDeps {
+    readonly http?: HttpExecutorDeps;
+    readonly prompt?: PromptExecutorDeps;
+    readonly composite?: CompositeExecutorDeps;
+}
+/**
+ * Execute a record according to its validated kind.
+ * @param record - validated record.
+ * @param args - model-supplied arguments.
+ * @param context - cancellation.
+ * @param deps - kind-specific seams.
+ * @returns the canonical result value.
+ */
+export declare function executeCustomTool(record: CustomToolRecord, args: Readonly<Record<string, unknown>>, context: CustomToolExecContext, deps?: CustomToolDispatchDeps): Promise<unknown>;
+/** Adapt dispatch deps into the registrar's executor signature. */
+export declare function customToolExecutor(deps: CustomToolDispatchDeps): CustomToolExecutor;
+//# sourceMappingURL=dispatch.d.ts.map

package/lib/custom-tools/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/custom-tools/dispatch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAC7E,OAAO,EAA8B,KAAK,qBAAqB,EAAE,MAAM,yBAAyB,CAAA;AAChG,OAAO,EAAyB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACjF,OAAO,EAA2B,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AACvF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAA;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAA;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,qBAAqB,CAAA;CAC3C;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,OAAO,EAAE,qBAAqB,EAC9B,IAAI,GAAE,sBAA2B,GAChC,OAAO,CAAC,OAAO,CAAC,CAYlB;AAED,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG,kBAAkB,CAEnF"}