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

package/lib/custom-tools/service.js

@@ -0,0 +1,203 @@
+/**
+ * Host service for authoring, testing and registering custom tools.
+ *
+ * This is the single seam behind the Remote methods and the plugin's startup
+ * restore. It owns no UI and no transport; every external dependency (model,
+ * credential store, tool dispatcher, fetch) is injected.
+ *
+ * @module @try-works/dsh-tool-mode/custom-tools/service
+ */
+import { executeCustomTool } from "./dispatch.js";
+import { normalizeCustomToolDraft } from "./schema.js";
+function summary(record) {
+    return {
+        id: record.id,
+        name: record.name,
+        title: record.title,
+        description: record.description,
+        kind: record.execution.kind,
+        version: record.version,
+        enabled: record.enabled,
+        agentExpose: record.policy.agentExpose,
+        mcpExpose: record.policy.mcpExpose,
+        updatedAt: record.updatedAt,
+    };
+}
+/** The service used by Remote and startup restore. */
+export class CustomToolsService {
+    store;
+    registrar;
+    dispatch;
+    draftModel;
+    constructor(options) {
+        this.store = options.store;
+        this.registrar = options.registrar;
+        this.draftModel = options.draftModel;
+        this.dispatch = {
+            ...options.dispatch,
+            ...options.resolveCredential === undefined
+                ? {}
+                : {
+                    http: {
+                        ...options.dispatch?.http,
+                        resolveCredential: options.resolveCredential,
+                    },
+                },
+        };
+    }
+    /** Read the list model without exposing definitions or secrets. */
+    describe() {
+        const tools = this.store.list().map(summary);
+        return { store: this.store.rootDir, writable: true, tools };
+    }
+    /** Read one full record for editing; header secret values are references only. */
+    get(id) {
+        return this.store.read(id);
+    }
+    /** Restore every enabled, agent-exposed tool at startup. */
+    sync() {
+        return this.registrar.sync();
+    }
+    /** Validate a draft without persisting it. */
+    validate(raw) {
+        try {
+            normalizeCustomToolDraft(raw);
+            return { ok: true, issues: [] };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                issues: error.issues ?? [{
+                        path: '',
+                        message: error instanceof Error ? error.message : String(error),
+                    }],
+            };
+        }
+    }
+    /** Execute a draft once; never persists or registers it. */
+    async test(raw, args) {
+        let draft;
+        try {
+            draft = normalizeCustomToolDraft(raw);
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: {
+                    code: 'custom-tool-invalid',
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            };
+        }
+        // A test record has no durable identity/version; use a synthetic record with
+        // the draft's shape so the compiler/executor contract is identical.
+        const now = new Date().toISOString();
+        const record = {
+            schemaVersion: 1,
+            ...draft,
+            version: 0,
+            enabled: true,
+            createdAt: now,
+            updatedAt: now,
+        };
+        try {
+            const value = await executeCustomTool(record, args, {
+                signal: new AbortController().signal,
+            }, this.dispatch);
+            return { ok: true, value };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: {
+                    code: error.code ?? 'custom-tool-test-failed',
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            };
+        }
+    }
+    /**
+     * Ask the host model for a draft from a natural-language description. The
+     * result is validated but never saved, registered or executed.
+     */
+    async draft(description) {
+        if (this.draftModel === undefined) {
+            return { ok: false, error: { code: 'custom-tool-draft-unavailable', message: 'no host model is composed for drafting' } };
+        }
+        if (description.trim().length === 0) {
+            return { ok: false, error: { code: 'custom-tool-draft-invalid', message: 'describe the tool you want before drafting' } };
+        }
+        const prompt = [
+            'You are drafting one DSH custom tool definition. Return ONLY a JSON object, no markdown.',
+            'The object MUST have these fields: id ("custom.<slug>"), name ("custom_<slug>"), title,',
+            'description, parameters (JSON Schema object), execution, policy, examples.',
+            'execution is one of:',
+            '{"kind":"http","http":{"method":"GET","url":"https://...","headers":{}}}',
+            '{"kind":"prompt","prompt":{"template":"...","maxOutputTokens":512}}',
+            '{"kind":"composite","composite":{"steps":[{"tool":"lang_detect","args":{"text":"{{text}}"}}]}}',
+            'policy MUST contain timeoutMs, readOnly, networkOrigins (exact https origins; [] unless http),',
+            'agentExpose (default true) and mcpExpose (default false).',
+            'Never put a secret value in the object; use {"secret":"ENV_NAME"} in HTTP headers.',
+            'The description field must explain when an agent should call the tool.',
+            'User description:',
+            description,
+        ].join('\n');
+        let text;
+        try {
+            text = await this.draftModel(prompt, new AbortController().signal);
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: { code: 'custom-tool-draft-failed', message: error instanceof Error ? error.message : String(error) },
+            };
+        }
+        const start = text.indexOf('{');
+        const end = text.lastIndexOf('}');
+        if (start < 0 || end <= start) {
+            return { ok: false, error: { code: 'custom-tool-draft-invalid', message: 'the model did not return a JSON object' } };
+        }
+        try {
+            const draft = normalizeCustomToolDraft(JSON.parse(text.slice(start, end + 1)));
+            return { ok: true, draft };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: {
+                    code: 'custom-tool-draft-invalid',
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            };
+        }
+    }
+    /** Validate, persist a new immutable version and register it when exposed. */
+    save(raw) {
+        const draft = normalizeCustomToolDraft(raw);
+        const record = this.store.save(draft);
+        if (record.enabled && record.policy.agentExpose) {
+            this.registrar.register(record);
+        }
+        else {
+            this.registrar.dispose(record.id);
+        }
+        return record;
+    }
+    /** Enable/disable one tool and reconcile the live registration. */
+    setEnabled(id, enabled) {
+        const record = this.store.setEnabled(id, enabled);
+        if (enabled && record.policy.agentExpose) {
+            this.registrar.register(record);
+        }
+        else {
+            this.registrar.dispose(id);
+        }
+        return record;
+    }
+    /** Delete the active pointer and remove the live tool. */
+    delete(id) {
+        this.registrar.dispose(id);
+        return this.store.delete(id);
+    }
+}
+//# sourceMappingURL=service.js.map

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

@@ -0,0 +1,61 @@
+/**
+ * Profile-scoped durable custom-tool store.
+ *
+ * The index is the only mutable document; each record version is immutable.
+ * Writes use a temp file + rename so a crash cannot leave a half-written active
+ * pointer, and an unreadable index fails closed instead of being treated as
+ * empty.
+ *
+ * @module @try-works/dsh-tool-mode/custom-tools/store
+ */
+import { CustomToolSchemaError } from './schema.ts';
+import type { CustomToolDraft, CustomToolIndex, CustomToolRecord } from './types.ts';
+/** The current store/index schema. */
+export declare const CUSTOM_TOOLS_SCHEMA_VERSION: 1;
+/** A named refusal from the custom-tool store. */
+export declare class CustomToolStoreError extends Error {
+    readonly name = "CustomToolStoreError";
+    readonly code: 'custom-tool-store-corrupt' | 'custom-tool-not-found' | 'custom-tool-id-invalid';
+    constructor(code: CustomToolStoreError['code'], message: string, options?: ErrorOptions);
+}
+/** Options for the store. */
+export interface CustomToolStoreOptions {
+    /** Root directory holding the index and one directory per tool. */
+    readonly rootDir: string;
+    /** Clock seam for deterministic tests. */
+    readonly now?: () => Date;
+}
+/** Durable custom-tool records. */
+export declare class CustomToolStore {
+    readonly rootDir: string;
+    readonly indexPath: string;
+    private readonly now;
+    constructor(options: CustomToolStoreOptions);
+    /** Read the index; a missing file is the only empty store. */
+    readIndex(): CustomToolIndex;
+    /** The active record ids, sorted for deterministic UI output. */
+    listIds(): readonly string[];
+    /** Read one active record; absent means the id is not active. */
+    read(id: string): CustomToolRecord | undefined;
+    /** Read a specific immutable version. */
+    readVersion(id: string, version: number, enabledOverride?: boolean): CustomToolRecord;
+    /** All active records, sorted by id. */
+    list(): readonly CustomToolRecord[];
+    /**
+     * Validate and persist a new version. The previous version is never mutated.
+     * @param draft - user-authored draft.
+     * @returns the persisted record.
+     */
+    save(draft: CustomToolDraft): CustomToolRecord;
+    /** Enable or disable one active tool. */
+    setEnabled(id: string, enabled: boolean): CustomToolRecord;
+    /** Remove the active pointer; immutable version files remain for audit. */
+    delete(id: string): boolean;
+    /** Version files present for one id (diagnostics/history). */
+    versions(id: string): readonly number[];
+    /** The absolute file for one version. */
+    versionPath(id: string, version: number): string;
+    private assertId;
+}
+export { CustomToolSchemaError };
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/custom-tools/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAA4B,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAC7E,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAEf,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAEnB,sCAAsC;AACtC,eAAO,MAAM,2BAA2B,EAAG,CAAU,CAAA;AAErD,kDAAkD;AAClD,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,SAAkB,IAAI,0BAAyB;IAC/C,QAAQ,CAAC,IAAI,EAAE,2BAA2B,GAAG,uBAAuB,GAAG,wBAAwB,CAAA;gBAEnF,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIxF;AAED,6BAA6B;AAC7B,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CAC1B;AA6CD,mCAAmC;AACnC,qBAAa,eAAe;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;gBAEpB,OAAO,EAAE,sBAAsB;IAM3C,8DAA8D;IAC9D,SAAS,IAAI,eAAe;IAU5B,iEAAiE;IACjE,OAAO,IAAI,SAAS,MAAM,EAAE;IAI5B,iEAAiE;IACjE,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAQ9C,yCAAyC;IACzC,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,OAAO,GAAG,gBAAgB;IA4CrF,wCAAwC;IACxC,IAAI,IAAI,SAAS,gBAAgB,EAAE;IASnC;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB;IAgC9C,yCAAyC;IACzC,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,gBAAgB;IAiB1D,2EAA2E;IAC3E,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAU3B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE;IAYvC,yCAAyC;IACzC,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;IAIhD,OAAO,CAAC,QAAQ;CAKjB;AAED,OAAO,EAAE,qBAAqB,EAAE,CAAA"}

package/lib/custom-tools/store.js

@@ -0,0 +1,240 @@
+/**
+ * Profile-scoped durable custom-tool store.
+ *
+ * The index is the only mutable document; each record version is immutable.
+ * Writes use a temp file + rename so a crash cannot leave a half-written active
+ * pointer, and an unreadable index fails closed instead of being treated as
+ * empty.
+ *
+ * @module @try-works/dsh-tool-mode/custom-tools/store
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { normalizeCustomToolDraft, CustomToolSchemaError } from "./schema.js";
+/** The current store/index schema. */
+export const CUSTOM_TOOLS_SCHEMA_VERSION = 1;
+/** A named refusal from the custom-tool store. */
+export class CustomToolStoreError extends Error {
+    name = 'CustomToolStoreError';
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function emptyIndex() {
+    return { schemaVersion: CUSTOM_TOOLS_SCHEMA_VERSION, tools: {} };
+}
+function defaultIndexPath(rootDir) {
+    return join(rootDir, 'index.json');
+}
+function idPattern() {
+    return /^custom\.[a-z0-9][a-z0-9-]*$/;
+}
+function writeJsonAtomic(file, value) {
+    mkdirSync(dirname(file), { recursive: true });
+    const temp = `${file}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    renameSync(temp, file);
+}
+function parseIndex(raw, source) {
+    if (!isRecord(raw) || raw['schemaVersion'] !== CUSTOM_TOOLS_SCHEMA_VERSION || !isRecord(raw['tools'])) {
+        throw new CustomToolStoreError('custom-tool-store-corrupt', `${source} is not a custom-tool index`);
+    }
+    const tools = {};
+    for (const [id, entry] of Object.entries(raw['tools'])) {
+        if (!idPattern().test(id) || !isRecord(entry)) {
+            throw new CustomToolStoreError('custom-tool-store-corrupt', `${source} has an invalid tool entry ${JSON.stringify(id)}`);
+        }
+        const activeVersion = entry['activeVersion'];
+        const updatedAt = entry['updatedAt'];
+        if (typeof activeVersion !== 'number' || !Number.isInteger(activeVersion) || activeVersion < 1
+            || typeof updatedAt !== 'string' || typeof entry['enabled'] !== 'boolean') {
+            throw new CustomToolStoreError('custom-tool-store-corrupt', `${source} has an invalid index entry for ${id}`);
+        }
+        tools[id] = { activeVersion, enabled: entry['enabled'], updatedAt };
+    }
+    return { schemaVersion: CUSTOM_TOOLS_SCHEMA_VERSION, tools };
+}
+/** Durable custom-tool records. */
+export class CustomToolStore {
+    rootDir;
+    indexPath;
+    now;
+    constructor(options) {
+        this.rootDir = options.rootDir;
+        this.indexPath = defaultIndexPath(options.rootDir);
+        this.now = options.now ?? (() => new Date());
+    }
+    /** Read the index; a missing file is the only empty store. */
+    readIndex() {
+        if (!existsSync(this.indexPath))
+            return emptyIndex();
+        try {
+            return parseIndex(JSON.parse(readFileSync(this.indexPath, 'utf8')), this.indexPath);
+        }
+        catch (error) {
+            if (error instanceof CustomToolStoreError)
+                throw error;
+            throw new CustomToolStoreError('custom-tool-store-corrupt', `${this.indexPath} could not be read: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    /** The active record ids, sorted for deterministic UI output. */
+    listIds() {
+        return Object.keys(this.readIndex().tools).sort();
+    }
+    /** Read one active record; absent means the id is not active. */
+    read(id) {
+        this.assertId(id);
+        const index = this.readIndex();
+        const entry = index.tools[id];
+        if (entry === undefined)
+            return undefined;
+        return this.readVersion(id, entry.activeVersion, entry.enabled);
+    }
+    /** Read a specific immutable version. */
+    readVersion(id, version, enabledOverride) {
+        this.assertId(id);
+        const file = this.versionPath(id, version);
+        if (!existsSync(file)) {
+            throw new CustomToolStoreError('custom-tool-store-corrupt', `${id}@${version} is referenced but missing at ${file}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch (error) {
+            throw new CustomToolStoreError('custom-tool-store-corrupt', `${file} could not be read: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        if (!isRecord(parsed)
+            || parsed['schemaVersion'] !== CUSTOM_TOOLS_SCHEMA_VERSION
+            || parsed['id'] !== id
+            || parsed['version'] !== version
+            || typeof parsed['name'] !== 'string'
+            || typeof parsed['createdAt'] !== 'string'
+            || typeof parsed['updatedAt'] !== 'string') {
+            throw new CustomToolStoreError('custom-tool-store-corrupt', `${file} is not a valid ${id}@${version} record`);
+        }
+        // Validate the persisted draft fields again; a tampered record must not be
+        // registered merely because it is syntactically JSON.
+        let draft;
+        try {
+            draft = normalizeCustomToolDraft(parsed);
+        }
+        catch (error) {
+            throw new CustomToolStoreError('custom-tool-store-corrupt', `${file} contains an invalid draft: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        const enabled = enabledOverride ?? parsed['enabled'] === true;
+        return {
+            schemaVersion: CUSTOM_TOOLS_SCHEMA_VERSION,
+            ...draft,
+            version,
+            enabled,
+            createdAt: parsed['createdAt'],
+            updatedAt: parsed['updatedAt'],
+        };
+    }
+    /** All active records, sorted by id. */
+    list() {
+        const index = this.readIndex();
+        return this.listIds().map(id => {
+            const entry = index.tools[id];
+            if (entry === undefined)
+                throw new CustomToolStoreError('custom-tool-store-corrupt', `${id} disappeared from the index`);
+            return this.readVersion(id, entry.activeVersion, entry.enabled);
+        });
+    }
+    /**
+     * Validate and persist a new version. The previous version is never mutated.
+     * @param draft - user-authored draft.
+     * @returns the persisted record.
+     */
+    save(draft) {
+        const normalized = normalizeCustomToolDraft(draft);
+        this.assertId(normalized.id);
+        const index = this.readIndex();
+        const existing = index.tools[normalized.id];
+        const version = existing === undefined ? 1 : existing.activeVersion + 1;
+        const now = this.now().toISOString();
+        const record = {
+            schemaVersion: CUSTOM_TOOLS_SCHEMA_VERSION,
+            ...normalized,
+            version,
+            enabled: existing?.enabled ?? true,
+            createdAt: existing === undefined ? now : this.readVersion(normalized.id, existing.activeVersion).createdAt,
+            updatedAt: now,
+        };
+        const recordFile = this.versionPath(normalized.id, version);
+        writeJsonAtomic(recordFile, record);
+        const next = {
+            schemaVersion: CUSTOM_TOOLS_SCHEMA_VERSION,
+            tools: {
+                ...index.tools,
+                [normalized.id]: {
+                    activeVersion: version,
+                    enabled: record.enabled,
+                    updatedAt: now,
+                },
+            },
+        };
+        writeJsonAtomic(this.indexPath, next);
+        return record;
+    }
+    /** Enable or disable one active tool. */
+    setEnabled(id, enabled) {
+        this.assertId(id);
+        const index = this.readIndex();
+        const entry = index.tools[id];
+        if (entry === undefined)
+            throw new CustomToolStoreError('custom-tool-not-found', `${id} is not a custom tool`);
+        const now = this.now().toISOString();
+        const next = {
+            schemaVersion: CUSTOM_TOOLS_SCHEMA_VERSION,
+            tools: {
+                ...index.tools,
+                [id]: { ...entry, enabled, updatedAt: now },
+            },
+        };
+        writeJsonAtomic(this.indexPath, next);
+        return this.readVersion(id, entry.activeVersion, enabled);
+    }
+    /** Remove the active pointer; immutable version files remain for audit. */
+    delete(id) {
+        this.assertId(id);
+        const index = this.readIndex();
+        if (index.tools[id] === undefined)
+            return false;
+        const tools = { ...index.tools };
+        delete tools[id];
+        writeJsonAtomic(this.indexPath, { schemaVersion: CUSTOM_TOOLS_SCHEMA_VERSION, tools });
+        return true;
+    }
+    /** Version files present for one id (diagnostics/history). */
+    versions(id) {
+        this.assertId(id);
+        const dir = join(this.rootDir, id);
+        if (!existsSync(dir))
+            return [];
+        return readdirSync(dir)
+            .map(name => /^(\d+)\.json$/.exec(name)?.[1])
+            .filter((value) => value !== undefined)
+            .map(Number)
+            .filter(version => Number.isInteger(version) && version > 0)
+            .sort((a, b) => a - b);
+    }
+    /** The absolute file for one version. */
+    versionPath(id, version) {
+        return join(this.rootDir, id, `${version}.json`);
+    }
+    assertId(id) {
+        if (!idPattern().test(id)) {
+            throw new CustomToolStoreError('custom-tool-id-invalid', `${JSON.stringify(id)} is not a valid custom tool id`);
+        }
+    }
+}
+export { CustomToolSchemaError };
+//# sourceMappingURL=store.js.map

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

@@ -0,0 +1,131 @@
+/**
+ * Durable custom-tool authoring records.
+ *
+ * These are NOT runtime tool definitions. A record is validated, versioned and
+ * compiled into a `defineTool` definition by the host. Keeping the two separate
+ * lets the store reject a bad draft without ever exposing a partial tool.
+ *
+ * @module @try-works/dsh-tool-mode/custom-tools/types
+ */
+/** The safe execution kinds supported in v1. */
+export type CustomToolKind = 'http' | 'prompt' | 'composite';
+/** One literal or credential-reference HTTP header. */
+export type HttpHeaderValue = string | {
+    readonly secret: string;
+};
+/** The supported HTTP execution definition. */
+export interface HttpExecution {
+    readonly method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Template URL; only `{{argument}}` leaves are interpolated. */
+    readonly url: string;
+    readonly headers: Readonly<Record<string, HttpHeaderValue>>;
+    /** Optional JSON body template with `{{argument}}` leaves. */
+    readonly bodyTemplate?: string;
+    /** Dot-path extraction from the JSON response; empty means the whole body. */
+    readonly extract?: string;
+}
+/** The supported prompt execution definition. */
+export interface PromptExecution {
+    /** Template; only `{{argument}}` leaves are interpolated. */
+    readonly template: string;
+    /** Optional model id; absent means the deployment default. */
+    readonly model?: string;
+    readonly maxOutputTokens?: number;
+}
+/** One composite step. `{{steps.N.result}}` addresses a previous result. */
+export interface CompositeStep {
+    readonly tool: string;
+    readonly args: Readonly<Record<string, string>>;
+    readonly requiresApproval?: boolean;
+}
+/** The supported composite execution definition. */
+export interface CompositeExecution {
+    readonly steps: readonly CompositeStep[];
+    /** Optional selector for the final result; default is the last step. */
+    readonly output?: string;
+}
+/** The execution union carried by a record. */
+export type CustomToolExecution = {
+    readonly kind: 'http';
+    readonly http: HttpExecution;
+} | {
+    readonly kind: 'prompt';
+    readonly prompt: PromptExecution;
+} | {
+    readonly kind: 'composite';
+    readonly composite: CompositeExecution;
+};
+/** Governance carried by every custom tool. */
+export interface CustomToolPolicy {
+    /** Cooperative execution deadline. */
+    readonly timeoutMs: number;
+    /** Advisory read-only hint for the agent/UI. */
+    readonly readOnly: boolean;
+    /** Exact HTTPS origins the HTTP executor may reach. */
+    readonly networkOrigins: readonly string[];
+    /** Whether the tool is exposed to agents. */
+    readonly agentExpose: boolean;
+    /** Whether the tool is exposed over MCP. Default false. */
+    readonly mcpExpose: boolean;
+}
+/** One example shown in the form and used by the test panel. */
+export interface CustomToolExample {
+    readonly title: string;
+    readonly arguments: Readonly<Record<string, unknown>>;
+}
+/** A complete, validated authoring record. */
+export interface CustomToolRecord {
+    readonly schemaVersion: 1;
+    /** Stable id; also the directory name. */
+    readonly id: string;
+    /** DSH tool name (`custom_...`). */
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    /** JSON Schema object for arguments. */
+    readonly parameters: Readonly<Record<string, unknown>>;
+    /** Optional JSON Schema for the canonical result. */
+    readonly outputSchema?: Readonly<Record<string, unknown>>;
+    readonly execution: CustomToolExecution;
+    readonly policy: CustomToolPolicy;
+    readonly examples: readonly CustomToolExample[];
+    readonly version: number;
+    readonly enabled: boolean;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+/** A user-editable draft before it has an id/version/timestamps. */
+export interface CustomToolDraft {
+    readonly id: string;
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    readonly parameters: Readonly<Record<string, unknown>>;
+    readonly outputSchema?: Readonly<Record<string, unknown>>;
+    readonly execution: CustomToolExecution;
+    readonly policy: CustomToolPolicy;
+    readonly examples: readonly CustomToolExample[];
+}
+/** The active entry for one custom tool. */
+export interface CustomToolIndexEntry {
+    readonly activeVersion: number;
+    readonly enabled: boolean;
+    readonly updatedAt: string;
+}
+/** The durable index document. */
+export interface CustomToolIndex {
+    readonly schemaVersion: 1;
+    readonly tools: Readonly<Record<string, CustomToolIndexEntry>>;
+}
+/** One validation issue, safe to render in the form. */
+export interface CustomToolIssue {
+    /** Dot path into the draft. */
+    readonly path: string;
+    readonly message: string;
+}
+/** The validation verdict for a draft. */
+export interface CustomToolValidation {
+    readonly ok: boolean;
+    readonly issues: readonly CustomToolIssue[];
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/lib/custom-tools/types.js

@@ -0,0 +1,11 @@
+/**
+ * Durable custom-tool authoring records.
+ *
+ * These are NOT runtime tool definitions. A record is validated, versioned and
+ * compiled into a `defineTool` definition by the host. Keeping the two separate
+ * lets the store reject a bad draft without ever exposing a partial tool.
+ *
+ * @module @try-works/dsh-tool-mode/custom-tools/types
+ */
+export {};
+//# sourceMappingURL=types.js.map