@try-works/dsh-model-as-tool 0.1.3 → 0.4.0

package/lib/extension-dispatch.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Provider-backed dispatch for extension-declared tools (EXT-19, EXT-21, EXT-22, ARCH-05).
+ *
+ * The TMX runtime API has **no tool-invocation surface**. `ExtensionInstanceV1` exposes
+ * exactly `createProvider` and `dispose` — nothing else. So an extension's tool is not
+ * something the host calls directly; the tool is a caller-facing NAME whose contract is
+ * bound to an IMPLEMENTATION, and the implementation is a model PROVIDER.
+ *
+ *     manifest.tools[]          -> the caller-facing name and its contract
+ *     manifest.implementations[] -> which contract, served by which model
+ *     instance.createProvider() -> the thing that actually runs
+ *
+ * That chain is what this module walks. An earlier version of the host registrar
+ * registered a tool whose `execute` simply REFUSED, which was honest about there being no
+ * implementation bound but left the bridge functionally incomplete: the name appeared in
+ * the registry and could never be called.
+ *
+ * The context is INJECTED so the chain is testable without a real extension on disk.
+ *
+ * @module @try-works/dsh-model-as-tool/extension-dispatch
+ */
+import type { PreparedAssetMap } from './prepared-assets.ts';
+/** What a manifest declares about one tool. */
+export interface DeclaredTool {
+    readonly name: string;
+    readonly contractId: string;
+    readonly contractVersion: string;
+}
+/** What a manifest declares about one implementation. */
+export interface DeclaredImplementation {
+    readonly id: string;
+    readonly contractId: string;
+    readonly contractVersion: string;
+    /** The model that serves the contract. */
+    readonly modelId: string;
+}
+/** The parts of a manifest this module needs. */
+export interface DispatchManifest {
+    readonly tools: readonly DeclaredTool[];
+    readonly implementations: readonly DeclaredImplementation[];
+}
+/** A provider, narrowed to what dispatch needs. */
+export interface DispatchProvider {
+    load(request: {
+        readonly assets: unknown;
+        readonly signal: AbortSignal;
+        /** The manifest model id; the managed worker's load keys by it. */
+        readonly modelId?: string;
+    }): Promise<void>;
+    invoke(request: {
+        readonly implementationId: string;
+        readonly input: Readonly<Record<string, unknown>>;
+        readonly context: unknown;
+    }): Promise<Record<string, unknown>>;
+}
+/** What dispatch needs from the host to reach an extension. */
+export interface DispatchEnvironment {
+    /** The manifest of the activated extension that declared the tool. */
+    getManifest(): DispatchManifest;
+    /** Create (or return a cached) provider for a model deployment. */
+    providerFor(modelId: string): Promise<DispatchProvider>;
+    /** Build the invocation context, which carries host-issued identity. */
+    contextFor(implementationId: string, signal: AbortSignal): unknown;
+    /**
+     * The host's verified prepared-asset map for THIS extension, or undefined
+     * when nothing was prepared (the load then receives the EMPTY map — an
+     * extension needing assets refuses by name inside its own load, which is the
+     * honest MOD-02 behavior rather than an invented verification). Closes over
+     * the extension the environment was built for.
+     */
+    assetsFor?(): PreparedAssetMap | undefined;
+}
+/** Why a tool could not be dispatched. */
+export interface DispatchFailure {
+    readonly code: 'not-declared' | 'no-implementation' | 'unsupported';
+    readonly message: string;
+    readonly remedy: string;
+}
+/**
+ * Resolve the implementation chain for a declared tool.
+ *
+ * @param manifest - the activated extension's manifest.
+ * @param toolName - the caller-facing name.
+ * @returns the tool, its implementation, or why the chain is incomplete.
+ */
+export declare function resolveImplementation(manifest: DispatchManifest, toolName: string): {
+    readonly ok: true;
+    readonly tool: DeclaredTool;
+    readonly implementation: DeclaredImplementation;
+} | {
+    readonly ok: false;
+    readonly failure: DispatchFailure;
+};
+/**
+ * Build an `execute` for one declared tool.
+ *
+ * The provider is created lazily on first call, so ACTIVATION stays lightweight as EXT-19
+ * requires: nothing is loaded until a caller actually invokes the tool.
+ *
+ * @param environment - how to reach the extension.
+ * @param toolName - the caller-facing name.
+ * @returns the execute function, or the failure that prevents one.
+ */
+export declare function createDispatch(environment: DispatchEnvironment, toolName: string): Promise<{
+    readonly ok: true;
+    readonly execute: (args: Record<string, unknown>, signal: AbortSignal) => Promise<Record<string, unknown>>;
+} | {
+    readonly ok: false;
+    readonly failure: DispatchFailure;
+}>;
+/**
+ * Describe a dispatch failure for a caller (EXT-30).
+ * @param failure - the failure.
+ * @returns a readable message naming what to do.
+ */
+export declare function describeDispatchFailure(failure: DispatchFailure): string;
+//# sourceMappingURL=extension-dispatch.d.ts.map

package/lib/extension-dispatch.d.ts.map

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

package/lib/extension-dispatch.js

@@ -0,0 +1,124 @@
+/**
+ * Provider-backed dispatch for extension-declared tools (EXT-19, EXT-21, EXT-22, ARCH-05).
+ *
+ * The TMX runtime API has **no tool-invocation surface**. `ExtensionInstanceV1` exposes
+ * exactly `createProvider` and `dispose` — nothing else. So an extension's tool is not
+ * something the host calls directly; the tool is a caller-facing NAME whose contract is
+ * bound to an IMPLEMENTATION, and the implementation is a model PROVIDER.
+ *
+ *     manifest.tools[]          -> the caller-facing name and its contract
+ *     manifest.implementations[] -> which contract, served by which model
+ *     instance.createProvider() -> the thing that actually runs
+ *
+ * That chain is what this module walks. An earlier version of the host registrar
+ * registered a tool whose `execute` simply REFUSED, which was honest about there being no
+ * implementation bound but left the bridge functionally incomplete: the name appeared in
+ * the registry and could never be called.
+ *
+ * The context is INJECTED so the chain is testable without a real extension on disk.
+ *
+ * @module @try-works/dsh-model-as-tool/extension-dispatch
+ */
+import { assertNoReservedMeta } from '@try-works/tool-mode-extension-sdk';
+/**
+ * Resolve the implementation chain for a declared tool.
+ *
+ * @param manifest - the activated extension's manifest.
+ * @param toolName - the caller-facing name.
+ * @returns the tool, its implementation, or why the chain is incomplete.
+ */
+export function resolveImplementation(manifest, toolName) {
+    const tool = manifest.tools.find(candidate => candidate.name === toolName);
+    if (tool === undefined) {
+        return {
+            ok: false,
+            failure: {
+                code: 'not-declared',
+                message: `${toolName} is not declared by this extension's manifest`,
+                remedy: 'A registered tool must be declared in the manifest it was published from.',
+            },
+        };
+    }
+    const implementation = manifest.implementations.find(candidate => candidate.contractId === tool.contractId && candidate.contractVersion === tool.contractVersion);
+    if (implementation === undefined) {
+        /**
+         * THE HONEST REFUSAL, and the case the earlier stub conflated with every other.
+         *
+         * An extension may DECLARE a tool it does not yet serve — EmbeddingGemma does exactly
+         * this, listing contracts whose ONNX path is not wired. The name is legitimately
+         * registered and legitimately uncallable, and the caller must be told WHICH of those
+         * two situations they are in.
+         */
+        return {
+            ok: false,
+            failure: {
+                code: 'no-implementation',
+                message: `${toolName} declares contract ${tool.contractId}, which no implementation serves`,
+                remedy: 'The extension declares this tool but binds no model to it yet; it is not callable in this build.',
+            },
+        };
+    }
+    return { ok: true, tool, implementation };
+}
+/**
+ * Build an `execute` for one declared tool.
+ *
+ * The provider is created lazily on first call, so ACTIVATION stays lightweight as EXT-19
+ * requires: nothing is loaded until a caller actually invokes the tool.
+ *
+ * @param environment - how to reach the extension.
+ * @param toolName - the caller-facing name.
+ * @returns the execute function, or the failure that prevents one.
+ */
+export async function createDispatch(environment, toolName) {
+    const resolved = resolveImplementation(environment.getManifest(), toolName);
+    if (!resolved.ok)
+        return resolved;
+    const { implementation } = resolved;
+    return {
+        ok: true,
+        async execute(args, signal) {
+            // Resolved per call rather than captured, so a provider that was unloaded — or an
+            // extension that was deactivated and reactivated — is not served from a stale handle.
+            const provider = await environment.providerFor(implementation.modelId);
+            /**
+             * The HOST-VERIFIED prepared-asset map, when a preparation completed.
+             * An absent map means the empty map — the extension's own load refuses a
+             * missing group by name (MOD-02), which is the honest outcome rather than
+             * a host that invents a verification that never happened. The same map
+             * reaches BOTH provider routes here: the in-process module provider and
+             * the managed worker (its load forwards the assets to the child).
+             */
+            const prepared = environment.assetsFor?.();
+            await provider.load({ assets: prepared ?? { get: () => undefined, assetIds: [] }, signal, modelId: implementation.modelId });
+            const value = await provider.invoke({
+                implementationId: implementation.id,
+                input: args,
+                context: environment.contextFor(implementation.id, signal),
+            });
+            /**
+             * THE EXT-17 META RESERVATION IS ENFORCED HERE, AT THE DISPATCH BOUNDARY.
+             *
+             * The reserved root `meta` is HOST-authored provenance; an extension supplying one
+             * is asserting who ran it and under what receipt, which it does not get to do. The
+             * ProviderBridge asserts this on the CATALOG path, but the contribution path
+             * (module and declarative providers alike) went unasserted — so a provider that
+             * smuggled a `meta` key reached callers whenever its declared output schema did not
+             * require the envelope. Asserting at the boundary the two provider routes share
+             * closes the gap for both, and it runs BEFORE any host stamping, so a forged
+             * envelope is refused rather than overwritten.
+             */
+            assertNoReservedMeta(value, implementation.id);
+            return value;
+        },
+    };
+}
+/**
+ * Describe a dispatch failure for a caller (EXT-30).
+ * @param failure - the failure.
+ * @returns a readable message naming what to do.
+ */
+export function describeDispatchFailure(failure) {
+    return `${failure.message}. ${failure.remedy}`;
+}
+//# sourceMappingURL=extension-dispatch.js.map

package/lib/extension-registrar.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The host-side contribution registrar (EXT-21..EXT-30, ARCH-06).
+ *
+ * This is the bridge that was MISSING: `ExtensionLifecycle` could install, activate and
+ * publish contributions, and the SDK was fully tested doing so — but the HOST never
+ * mounted the lifecycle, so **no extension's tools ever reached the DSH registry**. An
+ * extension could be installed, activated and reported `observedActivation: 'active'` with
+ * its tool listed, and a caller still could not invoke it.
+ *
+ * The registrar is the other half: it turns a published contribution into a real registry
+ * entry, and withdraws it again on deactivation.
+ *
+ * Four rules, each of which has been a real defect somewhere:
+ *
+ * - **Handles are opaque and unguessable.** An extension must not be able to construct a
+ *   handle and withdraw a contribution it does not own. A sequence number is guessable;
+ *   the handle is a branded object the caller never sees the inside of.
+ * - **Withdrawing is idempotent.** A deactivation that runs twice must not throw the
+ *   second time, and must not withdraw a DIFFERENT contribution that reused the handle.
+ * - **A name collision is refused, not silently overwritten.** Two extensions contributing
+ *   `transcribe` is a configuration error; letting the second win would silently change
+ *   what an existing caller reaches.
+ * - **The host stamps identity.** The contribution carries an extension id, but the HOST
+ *   decides what that means; a package claiming another's id is refused rather than
+ *   trusted.
+ *
+ * @module @try-works/dsh-model-as-tool/extension-registrar
+ */
+import type { Contribution, ContributionRegistrar } from '@try-works/tool-mode-extension-sdk';
+/** One thing the registrar can put into the DSH registry. */
+export interface RegistrableTool {
+    /** The caller-facing tool name. */
+    readonly name: string;
+    /** The extension that owns it, as the HOST resolved it. */
+    readonly ownerExtension: string;
+    /** The contract it implements, when it declares one. */
+    readonly contractId?: string;
+}
+/** What the registrar needs from the host registry. */
+export interface HostRegistrySurface {
+    /**
+     * Register one tool.
+     * @param tool - the tool, with identity already stamped by the host.
+     * @returns a disposer that removes it.
+     */
+    registerTool(tool: RegistrableTool): () => void;
+    /** Register one skill, returning a disposer. */
+    registerSkill?(skill: {
+        readonly name: string;
+        readonly ownerExtension: string;
+    }): () => void;
+    /**
+     * Register the CALLER-FACING tools of one declarative implementation (RCP-01).
+     *
+     * A declarative package declares implementations only — its manifest has no
+     * `tools` array — so the tool names and schemas come from the RESOLVED RECIPES,
+     * which only the host can turn into registry entries (the recipes need the
+     * deployment's harness provider to be served at all). The contribution arrives
+     * per implementation; the host resolves the package's recipes and registers the
+     * matching tool, returning its disposer. Absent (or a non-declarative package)
+     * keeps the earlier behavior: implementations publish nothing.
+     */
+    registerDeclarative?(contribution: {
+        readonly extensionId: string;
+        readonly name: string;
+        readonly contractId?: string;
+    }): () => void;
+}
+/** Raised when a contribution cannot be published. */
+export declare class ContributionError extends Error {
+    readonly name = "ContributionError";
+    readonly code: 'name-collision' | 'unsupported-kind' | 'unknown-extension';
+    constructor(code: ContributionError['code'], message: string);
+}
+/**
+ * The published contributions, keyed by handle id.
+ *
+ * A Map rather than a field on the handle, so an extension that receives a handle cannot
+ * reach the disposer or another extension's entry through it.
+ */
+export interface RegistrarOptions {
+    readonly registry: HostRegistrySurface;
+    /**
+     * The extensions the host has ACTIVATED.
+     *
+     * A contribution from an extension not in this set is refused: publishing is a privilege
+     * of activation, and without this check any code holding the registrar could register a
+     * tool under an extension that was never installed.
+     */
+    readonly activated: ReadonlySet<string>;
+    /** Called when a contribution is refused, so the reason is recorded rather than lost. */
+    readonly onRefused?: (contribution: Contribution, error: ContributionError) => void;
+}
+/**
+ * Create the registrar the lifecycle publishes through.
+ * @param options - the registry surface and the activated set.
+ * @returns the registrar.
+ */
+export declare function createContributionRegistrar(options: RegistrarOptions): ContributionRegistrar;
+//# sourceMappingURL=extension-registrar.d.ts.map

package/lib/extension-registrar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-registrar.d.ts","sourceRoot":"","sources":["../src/extension-registrar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAA;AAE7F,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,uDAAuD;AACvD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,IAAI,CAAA;IAC/C,gDAAgD;IAChD,aAAa,CAAC,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,IAAI,CAAA;IAC7F;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,CAAC,YAAY,EAAE;QACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;QAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAC7B,GAAG,MAAM,IAAI,CAAA;CACf;AAED,sDAAsD;AACtD,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAkB,IAAI,uBAAsB;IAC5C,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,kBAAkB,GAAG,mBAAmB,CAAA;gBAC9D,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM;CAI7D;AAUD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAA;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACvC,yFAAyF;IACzF,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAA;CACpF;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,gBAAgB,GAAG,qBAAqB,CAkG5F"}

package/lib/extension-registrar.js

@@ -0,0 +1,134 @@
+/**
+ * The host-side contribution registrar (EXT-21..EXT-30, ARCH-06).
+ *
+ * This is the bridge that was MISSING: `ExtensionLifecycle` could install, activate and
+ * publish contributions, and the SDK was fully tested doing so — but the HOST never
+ * mounted the lifecycle, so **no extension's tools ever reached the DSH registry**. An
+ * extension could be installed, activated and reported `observedActivation: 'active'` with
+ * its tool listed, and a caller still could not invoke it.
+ *
+ * The registrar is the other half: it turns a published contribution into a real registry
+ * entry, and withdraws it again on deactivation.
+ *
+ * Four rules, each of which has been a real defect somewhere:
+ *
+ * - **Handles are opaque and unguessable.** An extension must not be able to construct a
+ *   handle and withdraw a contribution it does not own. A sequence number is guessable;
+ *   the handle is a branded object the caller never sees the inside of.
+ * - **Withdrawing is idempotent.** A deactivation that runs twice must not throw the
+ *   second time, and must not withdraw a DIFFERENT contribution that reused the handle.
+ * - **A name collision is refused, not silently overwritten.** Two extensions contributing
+ *   `transcribe` is a configuration error; letting the second win would silently change
+ *   what an existing caller reaches.
+ * - **The host stamps identity.** The contribution carries an extension id, but the HOST
+ *   decides what that means; a package claiming another's id is refused rather than
+ *   trusted.
+ *
+ * @module @try-works/dsh-model-as-tool/extension-registrar
+ */
+/** Raised when a contribution cannot be published. */
+export class ContributionError extends Error {
+    name = 'ContributionError';
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/**
+ * Create the registrar the lifecycle publishes through.
+ * @param options - the registry surface and the activated set.
+ * @returns the registrar.
+ */
+export function createContributionRegistrar(options) {
+    const published = new Map();
+    /** Names currently taken, so a collision is detected rather than overwritten. */
+    const takenNames = new Map();
+    let nextId = 1;
+    const refuse = (contribution, error) => {
+        options.onRefused?.(contribution, error);
+        throw error;
+    };
+    return {
+        publish(contribution) {
+            // ACTIVATION IS A PRECONDITION. A contribution from a package that was never
+            // activated is refused rather than registered.
+            if (!options.activated.has(contribution.extensionId)) {
+                return refuse(contribution, new ContributionError('unknown-extension', `${contribution.extensionId} is not activated, so it cannot publish ${contribution.name}`));
+            }
+            /**
+             * A COLLISION IS REFUSED. Letting the second registration win would silently change
+             * what an existing caller reaches — the same name would resolve to a different tool
+             * with no signal.
+             */
+            const existing = takenNames.get(contribution.name);
+            if (existing !== undefined) {
+                return refuse(contribution, new ContributionError('name-collision', `${contribution.name} is already published by ${existing}; `
+                    + `${contribution.extensionId} cannot take the name over`));
+            }
+            const handle = {
+                __contributionHandle: true,
+                id: nextId++,
+                extensionId: contribution.extensionId,
+                name: contribution.name,
+            };
+            let dispose;
+            if (contribution.kind === 'tool') {
+                dispose = options.registry.registerTool({
+                    name: contribution.name,
+                    // The HOST stamps the owner from the contribution it validated, so a package
+                    // cannot claim another's provenance.
+                    ownerExtension: contribution.extensionId,
+                    ...contribution.contractId === undefined ? {} : { contractId: contribution.contractId },
+                });
+            }
+            else if (contribution.kind === 'skill' && options.registry.registerSkill !== undefined) {
+                dispose = options.registry.registerSkill({
+                    name: contribution.name,
+                    ownerExtension: contribution.extensionId,
+                });
+            }
+            else if (contribution.kind === 'implementation' && options.registry.registerDeclarative !== undefined) {
+                // An `implementation` of a MODULE package is not a caller-facing tool: the model
+                // catalogue binds it. An implementation of a DECLARATIVE package, however, IS the
+                // whole package: the host turns its resolved recipe into the caller-facing tool
+                // here (RCP-01), and the returned disposer is tracked like any other handle.
+                dispose = options.registry.registerDeclarative({
+                    extensionId: contribution.extensionId,
+                    name: contribution.name,
+                    ...contribution.contractId === undefined ? {} : { contractId: contribution.contractId },
+                });
+            }
+            else {
+                dispose = () => { };
+            }
+            takenNames.set(contribution.name, contribution.extensionId);
+            published.set(handle.id, { handle, dispose });
+            // The SDK types the handle as a string; the runtime value is a branded object, which
+            // is what makes it unforgeable. The cast is the boundary between the two.
+            return handle;
+        },
+        withdraw(rawHandle) {
+            const handle = rawHandle;
+            // A handle that is not ours — a string, a number, a forged object — is ignored
+            // rather than treated as a lookup that might match something.
+            if (handle === null || typeof handle !== 'object' || handle.__contributionHandle !== true)
+                return;
+            const entry = published.get(handle.id);
+            if (entry === undefined) {
+                // IDEMPOTENT: withdrawing twice is not an error, and must not withdraw whatever
+                // might have reused the id.
+                return;
+            }
+            // The handle must be the SAME one that was issued, not merely an object with the
+            // right id, so a reconstructed handle cannot withdraw someone else's tool.
+            if (entry.handle !== handle)
+                return;
+            // Failed cleanup retains ownership and the handle for an explicit retry.
+            entry.dispose();
+            published.delete(handle.id);
+            takenNames.delete(handle.name);
+        },
+    };
+}
+//# sourceMappingURL=extension-registrar.js.map