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

package/lib/tool-mode-run.js

@@ -0,0 +1,283 @@
+/**
+ * The ONE authorized program-execution pipeline (CODE-02, CODE-03, CODE-08, ARCH-05).
+ *
+ * THE DEFECT THIS FIXES, found by adversarial review rather than by a test:
+ * `ptc-authority.ts` and `ptc-runtime.ts` had **zero callers outside tests**. Everything in
+ * them was correct and thoroughly covered — `buildToolBindings`, the guarded mount,
+ * `mayExposeToClients()` — and none of it ran in production. `tool_mode_run` did not exist,
+ * the mount guard never executed, and the exposure gate guarded nothing because there was
+ * no caller to refuse.
+ *
+ * A security control with no callers is not a control; it is a symbol. This module is the
+ * caller.
+ *
+ * The wiring enforces three things the directive requires and nothing else did:
+ *
+ * 1. **ONE pipeline.** Native PTC and any external `tool_mode_run` reach tools through the
+ *    SAME `buildToolBindings` call, so authorization cannot differ between the two doors.
+ * 2. **The grant is the grant.** The requested names are intersected with the host's own
+ *    `allowedTools` and the live registry, and the whole request is refused if anything is
+ *    unattainable.
+ * 3. **The exposure gate has a caller.** `mayExposeToClients()` returning false now
+ *    actually refuses something, with the reason attached.
+ *
+ * @module @try-works/dsh-model-as-tool/tool-mode-run
+ */
+import { admitTimeout, buildToolBindings, exposureWithheldReason, mayExposeToClients, mountPtcRuntimeIfAbsent, PTC_SERVICE, } from "./ptc-runtime.js";
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** Create the per-call external grant carrier. */
+export function createExternalGrantContext() {
+    const store = new AsyncLocalStorage();
+    return {
+        run(grant, work) {
+            return store.run(grant, work);
+        },
+        current() {
+            return store.getStore();
+        },
+    };
+}
+/**
+ * Create the runner.
+ *
+ * @param environment - how to reach tools and the runtime.
+ * @returns the runner.
+ */
+export function createProgramRunner(environment) {
+    let prepared;
+    /** Materialized backend, resolved lazily at most once. */
+    let backend;
+    const materializeBackend = () => {
+        backend ??= (async () => {
+            // A FUNCTION backend is a lazy resolver; a CLASS is a plugin constructor and
+            // must not be invoked here (the mount does the construction). The source
+            // prefix distinguishes the two, which is exact for native classes. Wrapped
+            // constructors (bound/proxied/transpiled) can slip through as resolvers; the
+            // try/catch converts their invocation error into the SAME undefined the
+            // designed 'backend-unavailable' refusal reports, so no caller sees an
+            // opaque TypeError instead of the documented deployment fact.
+            const value = environment.backend;
+            const isClass = typeof value === 'function' && /^class\s/.test(Function.prototype.toString.call(value));
+            if (typeof value !== 'function' || isClass)
+                return value;
+            try {
+                return await value();
+            }
+            catch {
+                // The failure is reported through prepare()'s 'backend-unavailable'
+                // reason, which is the designed channel; the detail does not need a
+                // second logger the runner does not own.
+                return undefined;
+            }
+        })();
+        return backend;
+    };
+    return {
+        async prepare() {
+            // Idempotent: the guard is inside, and re-running it must not double-mount.
+            if (prepared !== undefined)
+                return prepared;
+            prepared = await mountPtcRuntimeIfAbsent(environment.context, await materializeBackend(), {
+                timeoutMs: 120_000,
+                maxTimeoutMs: 600_000,
+            });
+            return prepared;
+        },
+        externalExposurePermitted() {
+            return mayExposeToClients(environment.operatorGranted());
+        },
+        externalExposureReason() {
+            return exposureWithheldReason(environment.operatorGranted());
+        },
+        async run(request) {
+            const runtime = environment.runtime();
+            if (runtime === undefined) {
+                return {
+                    ok: false,
+                    code: 'unavailable',
+                    message: 'no PTC runtime is mounted, so no program can run',
+                };
+            }
+            /**
+             * THE AUTHORIZED PIPELINE, and the only place bindings are built.
+             *
+             * `buildToolBindings` intersects the request with the GRANT and the live registry and
+             * refuses the whole thing if any name is unattainable. Both doors — native PTC and any
+             * external surface — come through here, which is what makes them the same pipeline
+             * rather than two implementations that happen to agree today.
+             */
+            let toolCalls = 0;
+            const countedResolve = (name) => {
+                const binding = environment.resolve(name);
+                if (binding === undefined)
+                    return undefined;
+                // A counter wrapper, not a permission change: the program's binding call is
+                // counted so the CODE-02 meta reports real usage rather than a fabricated 0.
+                return async (args) => {
+                    toolCalls += 1;
+                    return binding(args);
+                };
+            };
+            const bindings = buildToolBindings({
+                requested: request.requested,
+                // THE GRANT IS READ PER RUN: an external client's call composes under the
+                // CLIENT's grant (SEC-04), the host path under the host's own.
+                authority: { granted: environment.grant(), visible: environment.visible() },
+                resolve: countedResolve,
+            });
+            if (!bindings.ok) {
+                return { ok: false, code: 'unauthorized', message: bindings.message };
+            }
+            try {
+                const result = await runtime.run(runtime.resolve({
+                    program: request.program,
+                    bindings: [bindings.namespace],
+                    // The budget is CLAMPED here, not passed through: `null` means "no deadline" in
+                    // the runtime's vocabulary, which is a request to opt out of budgeting entirely.
+                    timeoutMs: admitTimeout(request.timeoutMs),
+                    ...request.cwd === undefined ? {} : { cwd: request.cwd },
+                    ...request.signal === undefined ? {} : { signal: request.signal },
+                }));
+                if (result.error !== undefined && result.error !== null) {
+                    // A cancelled run is NOT a failure, and the distinction reaches the caller rather
+                    // than being flattened.
+                    const kind = result.error.kind;
+                    return {
+                        ok: false,
+                        code: kind === 'abort' ? 'cancelled' : 'failed',
+                        message: result.error.message ?? `the program ended with ${String(kind)}`,
+                    };
+                }
+                return { ok: true, value: result.value, logs: result.logs ?? [], toolCalls };
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    code: 'failed',
+                    message: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+    };
+}
+/**
+ * The refusal an EXTERNAL caller receives (CODE-08).
+ *
+ * A separate function so the gate has a single enforcement point rather than a condition
+ * repeated at each call site — the shape that let the original gate go unused.
+ * @param runner - the runner.
+ * @returns the refusal, or undefined when exposure is permitted.
+ */
+export function externalRefusal(runner) {
+    if (runner.externalExposurePermitted())
+        return undefined;
+    return { message: runner.externalExposureReason() };
+}
+/** The service key the runner depends on, re-exported so a caller need not import both. */
+export { PTC_SERVICE };
+/**
+ * The `tool_mode_run` MCP contract, in the ToolContract shape (CODE-02).
+ *
+ * ONE definition serves the MCP export surface and the conformance test, so the
+ * two cannot drift the way an inline object at the export site would: the test
+ * validates this shape's MCP projection against the pinned schema before it ever
+ * ships on a live tools/list.
+ */
+export const TOOL_MODE_RUN_CONTRACT = {
+    contract: 'hosted.tool_mode_run',
+    version: '1.0.0',
+    toolName: 'tool_mode_run',
+    description: 'Run a program that calls Tool Mode tools (CODE-02).',
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['description', 'code', 'tools'],
+        properties: {
+            description: { type: 'string' },
+            code: { type: 'string' },
+            input: {},
+            tools: { type: 'array', items: { type: 'string' } },
+            timeout_ms: { type: 'integer' },
+        },
+    },
+    outputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            result: {},
+            logs: { type: 'array', items: { type: 'string' } },
+            meta: { type: 'object' },
+        },
+    },
+    semantics: { deterministic: false, readsInputs: true },
+    limits: {},
+    unsupported: ['no access to management or installer bindings'],
+};
+/**
+ * Serve one CODE-02 request through the authorized pipeline (CODE-02/04).
+ *
+ * This is the `tool_mode_run` served path: the caller's arguments are validated
+ * into the CODE-02 shape, the program runs through the SAME runner native PTC
+ * uses, and the report carries the receipt, elapsed time, call count, catalog
+ * revision and warnings the interface promises.
+ *
+ * `input` is refused when the pinned runtime cannot bind it structurally: CODE-04
+ * forbids string interpolation into source, and the current PTC runtime has no
+ * data-global path, so an input-bearing program gets a precise refusal naming
+ * that limitation rather than a silently interpolated program.
+ * @param args - the caller's arguments.
+ * @param runner - the prepared runner.
+ * @param report - the report-shaped facts the host owns (receipt id, revision).
+ * @returns the report.
+ */
+export async function serveProgram(args, runner, report) {
+    const description = typeof args.description === 'string' ? args.description : '';
+    const code = typeof args.code === 'string' ? args.code : '';
+    if (code.trim().length === 0) {
+        throw new Error('`code` must be a non-empty program body');
+    }
+    void description;
+    const requested = Array.isArray(args.tools)
+        ? args.tools.filter((name) => typeof name === 'string')
+        : [];
+    if (requested.length === 0) {
+        throw new Error('`tools` must name at least one tool the program will call');
+    }
+    if (args.input !== undefined && args.input !== null) {
+        /**
+         * CODE-04: `input` is bound through a supported structured-data path, never
+         * interpolated into source. The pinned PTC runtime materialises FUNCTION
+         * namespaces only, so there is no data path to bind it through today. Refusing
+         * with that fact is the honest outcome; interpolating JSON into the program
+         * would be the silent violation the requirement names.
+         */
+        throw new Error('`input` cannot be bound: the pinned PTC runtime has no structured-data path, '
+            + 'and CODE-04 forbids interpolating it into source. Use a program that takes '
+            + 'no input data, or run against a runtime that supports data binding.');
+    }
+    const prepared = await runner.prepare();
+    if (!prepared.mounted && prepared.reason === 'backend-unavailable') {
+        throw new Error('the Node PTC backend is unavailable on this deployment, so no program can run');
+    }
+    const started = Date.now();
+    const outcome = await runner.run({
+        program: code,
+        requested,
+        ...typeof args.timeout_ms === 'number' ? { timeoutMs: args.timeout_ms } : {},
+    });
+    if (!outcome.ok) {
+        throw new Error(`${outcome.code}: ${outcome.message}`);
+    }
+    return {
+        result: outcome.value ?? null,
+        logs: outcome.logs,
+        meta: {
+            receiptId: report.receiptId,
+            elapsedMs: Date.now() - started,
+            toolCalls: outcome.toolCalls,
+            catalogRevision: report.catalogRevision,
+            warnings: [],
+        },
+    };
+}
+//# sourceMappingURL=tool-mode-run.js.map

package/lib/types.d.ts

@@ -107,8 +107,10 @@ export interface ModelCatalogEntry {
 }
 /** How an adapter reaches a model at run time. */
 export type ModelRoute = 
+/** A Tool Mode extension package loaded in this process. */
+'extension'
 /** An npm package loaded in this process. */
-'npm-native'
+ | 'npm-native'
 /** An npm package plus a caller-supplied ONNX Runtime module. */
  | 'npm-onnxruntime'
 /** The Desert Ant CLI, run as a child process (macOS and Linux). */

package/lib/types.d.ts.map

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

package/lib/update-surface.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The host's UpdateHostSurface (EXT-30, slice 3): the operator approval
+ * surface, the two-phase commit with quiesce/rebind hooks, and the standalone
+ * rollback with a bounded rebindRestored.
+ *
+ * The SDK owns the durable mechanics (staging, validation reports, approval
+ * RECORDS, the atomic pointer, the auto-rollback); this module owns the HOST
+ * decisions the SDK refuses to invent (design doc §6):
+ *
+ * - the pending listing + approve/deny over the SDK's approval records;
+ * - the quiesce (stop old-generation admissions) and the rebind (republish the
+ *   new generation) — supplied as closures so the index wiring passes the
+ *   lifecycle/registrar pair and tests can pass recorded fakes;
+ * - the ALL-OR-NOTHING rebind wrapper: the SDK's auto-rollback re-runs NO
+ *   hooks (the REBIND-REVERT contract), so a rebind failure restores the
+ *   previous surface HERE, before the pointer rollback lands;
+ * - the host-side timeout bound on rebindRestored (the SDK awaits it with no
+ *   bound; only the management caller must not hang).
+ *
+ * The management channel stays the ONLY caller of this surface (AT-39).
+ *
+ * @module @dsh-model-as-tool/update-surface
+ */
+import type { UpdateCommitResult, UpdateRollbackResult, UpdateValidationReport } from '@try-works/tool-mode-extension-sdk';
+/** One pending staged update, from the staging directory + the approval record. */
+export interface PendingUpdateEntry {
+    readonly extensionId: string;
+    readonly stagedVersion: string;
+    /** The version the report was computed against. */
+    readonly currentVersion: string;
+    readonly stagedAt: string;
+    readonly report: UpdateValidationReport;
+    /** The persisted approval, when one was recorded. */
+    readonly approval?: {
+        readonly approved: boolean;
+        readonly reason?: string;
+    };
+}
+/** The host-side lifecycle closures the surface drives. */
+export interface UpdateHostHooks {
+    /** Stop old-generation admissions (withdraw handles, stop admitting). */
+    readonly quiesce: (extensionId: string) => Promise<void>;
+    /** Publish the new generation's surface (must be all-or-nothing per the SDK contract). */
+    readonly rebind: (extensionId: string, version: string) => Promise<void>;
+}
+/** The operator approval surface + commit/rollback. */
+export interface UpdateHostSurface {
+    /** The pending staged updates with their reports and approval records. */
+    listPendingUpdates(): PendingUpdateEntry[];
+    /** Record ONE approval decision (write-once per staged version). */
+    decide(extensionId: string, stagedVersion: string, decision: {
+        approved: true;
+    } | {
+        approved: false;
+        reason: string;
+    }): void;
+    /**
+     * Commit a staged update through the two-phase seam.
+     * @throws when the SDK refuses (no approved record, integrity, quiesce, rebind).
+     */
+    commit(extensionId: string, stagedVersion: string): Promise<UpdateCommitResult>;
+    /** Roll the pointer back with a TIME-BOUNDED rebindRestored. */
+    rollback(extensionId: string): Promise<UpdateRollbackResult>;
+}
+/** The surface options. */
+export interface UpdateHostSurfaceOptions {
+    readonly storeDir: string;
+    readonly profile: string;
+    readonly hooks: UpdateHostHooks;
+    /** The host-side bound on rebindRestored; default 30 s. */
+    readonly rebindTimeoutMs?: number;
+}
+/**
+ * Create the host update surface.
+ * @param options - the store location, profile, lifecycle hooks and the timeout bound.
+ * @returns the surface.
+ */
+export declare function createUpdateHostSurface(options: UpdateHostSurfaceOptions): UpdateHostSurface;
+//# sourceMappingURL=update-surface.d.ts.map

package/lib/update-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-surface.d.ts","sourceRoot":"","sources":["../src/update-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,oCAAoC,CAAA;AAI3C,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAA;IACvC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC7E;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACxD,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACzE;AAED,uDAAuD;AACvD,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,kBAAkB,IAAI,kBAAkB,EAAE,CAAA;IAC1C,oEAAoE;IACpE,MAAM,CACJ,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE;QAAE,QAAQ,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,QAAQ,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GACjE,IAAI,CAAA;IACP;;;OAGG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAC/E,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;CAC7D;AAED,2BAA2B;AAC3B,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAClC;AA6CD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAsJ5F"}

package/lib/update-surface.js

@@ -0,0 +1,224 @@
+/**
+ * The host's UpdateHostSurface (EXT-30, slice 3): the operator approval
+ * surface, the two-phase commit with quiesce/rebind hooks, and the standalone
+ * rollback with a bounded rebindRestored.
+ *
+ * The SDK owns the durable mechanics (staging, validation reports, approval
+ * RECORDS, the atomic pointer, the auto-rollback); this module owns the HOST
+ * decisions the SDK refuses to invent (design doc §6):
+ *
+ * - the pending listing + approve/deny over the SDK's approval records;
+ * - the quiesce (stop old-generation admissions) and the rebind (republish the
+ *   new generation) — supplied as closures so the index wiring passes the
+ *   lifecycle/registrar pair and tests can pass recorded fakes;
+ * - the ALL-OR-NOTHING rebind wrapper: the SDK's auto-rollback re-runs NO
+ *   hooks (the REBIND-REVERT contract), so a rebind failure restores the
+ *   previous surface HERE, before the pointer rollback lands;
+ * - the host-side timeout bound on rebindRestored (the SDK awaits it with no
+ *   bound; only the management caller must not hang).
+ *
+ * The management channel stays the ONLY caller of this surface (AT-39).
+ *
+ * @module @dsh-model-as-tool/update-surface
+ */
+import { commitUpdate, recordApproval, rollback, ExtensionStore } from '@try-works/tool-mode-extension-sdk';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/** The current pointer for one extension, read from the profile pointers. */
+function currentPointer(store, profile, extensionId) {
+    const pointers = store.readProfilePointers(profile);
+    if (pointers.corrupt) {
+        throw new Error(`the profile pointers are unreadable: ${pointers.diagnostic ?? 'unknown reason'}`);
+    }
+    return pointers.value.activeVersions[extensionId];
+}
+/** The staged-update metadata file for one staged directory. */
+const stageMetadataPath = (stagedDir) => join(stagedDir, 'update-stage.json');
+/**
+ * A rebind failure whose PREVIOUS surface the wrapper already restored.
+ *
+ * The commit catch would otherwise restore the previous surface a second time
+ * (the REBIND-REVERT contract: the wrapper owns the revert; the catch owns the
+ * post-quiesce-failure restore, which is a different situation).
+ */
+class RebindRestoredFailure extends Error {
+    constructor(message, cause) {
+        super(message, { cause });
+        this.name = 'RebindRestoredFailure';
+    }
+}
+/** Bound one promise host-side: the caller stops waiting, the work may continue. */
+async function withTimeout(promise, timeoutMs, label) {
+    let timer;
+    const bound = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs} ms (host-side bound)`)), timeoutMs);
+        if (typeof timer === 'object' && timer !== null && 'unref' in timer && typeof timer.unref === 'function') {
+            // Kept REFERENCED deliberately: a hanging rebind must not let the process
+            // exit mid-update; the timeout is what bounds it.
+        }
+    });
+    try {
+        return await Promise.race([promise, bound]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Create the host update surface.
+ * @param options - the store location, profile, lifecycle hooks and the timeout bound.
+ * @returns the surface.
+ */
+export function createUpdateHostSurface(options) {
+    const store = new ExtensionStore(options.storeDir);
+    const timeoutMs = options.rebindTimeoutMs ?? 30_000;
+    const { profile, hooks } = options;
+    /**
+     * The surfaces the rebind wrapper ALREADY restored. The SDK wraps a failed
+     * rebind into its own ManagementError, so the commit catch cannot see the
+     * marker on the error itself; this in-surface set carries it instead (the
+     * REBIND-REVERT contract: the wrapper's revert is never duplicated).
+     */
+    const wrapperRestored = new Set();
+    return {
+        listPendingUpdates() {
+            const staging = join(options.storeDir, 'staging');
+            if (!existsSync(staging))
+                return [];
+            const entries = [];
+            for (const name of readdirSync(staging)) {
+                if (!name.endsWith('.staged'))
+                    continue;
+                const stagedDir = join(staging, name);
+                const metadataPath = stageMetadataPath(stagedDir);
+                if (!existsSync(metadataPath))
+                    continue; // an aborted stage attempt; never listed
+                let metadata;
+                try {
+                    metadata = JSON.parse(readFileSync(metadataPath, 'utf8'));
+                }
+                catch {
+                    continue; // a corrupt metadata record fails closed: not listed, never committed
+                }
+                if (typeof metadata.extensionId !== 'string' || typeof metadata.stagedVersion !== 'string'
+                    || typeof metadata.report !== 'object' || metadata.report === null) {
+                    continue;
+                }
+                const approval = store.readApproval(metadata.extensionId, metadata.stagedVersion);
+                if (approval.corrupt) {
+                    entries.push({ ...metadata, approval: { approved: false, reason: `the approval record is unreadable: ${approval.diagnostic ?? 'unknown reason'}` } });
+                    continue;
+                }
+                entries.push({
+                    extensionId: metadata.extensionId,
+                    stagedVersion: metadata.stagedVersion,
+                    currentVersion: metadata.currentVersion,
+                    stagedAt: metadata.stagedAt,
+                    report: metadata.report,
+                    ...approval.value === undefined ? {} : {
+                        approval: {
+                            approved: approval.value.approved,
+                            ...('reason' in approval.value && typeof approval.value.reason === 'string'
+                                ? { reason: approval.value.reason }
+                                : {}),
+                        },
+                    },
+                });
+            }
+            return entries;
+        },
+        decide(extensionId, stagedVersion, decision) {
+            recordApproval({ storeDir: options.storeDir, extensionId, stagedVersion, decision });
+        },
+        async commit(extensionId, stagedVersion) {
+            // The pointer BEFORE the commit: the restore target when a post-quiesce
+            // failure withdraws the old surface.
+            const previous = currentPointer(store, profile, extensionId);
+            /** True once the quiesce hook was INVOKED: after that a failure owes a restore. */
+            let quiesced = false;
+            const quiescePrevious = async () => {
+                // Set BEFORE the hook runs: a quiesce that threw may have withdrawn the
+                // surface partially, and the restore is the safe recovery either way.
+                quiesced = true;
+                await hooks.quiesce(extensionId);
+            };
+            /**
+             * ALL-OR-NOTHING with the revert INSIDE the wrapper (the REBIND-REVERT
+             * contract): the SDK's auto-rollback re-runs no hooks, so a rebind that
+             * partially published must restore the previous surface itself before
+             * rethrowing. The previous pointer is still recorded under the rolled-back
+             * value after the SDK's auto-rollback, so re-activating it lands on the
+             * version the pointer will name.
+             */
+            const rebindNext = async (nextVersion) => {
+                try {
+                    await withTimeout(hooks.rebind(extensionId, nextVersion), timeoutMs, `rebind ${extensionId}@${nextVersion}`);
+                }
+                catch (error) {
+                    if (previous !== undefined) {
+                        try {
+                            await withTimeout(hooks.rebind(extensionId, previous), timeoutMs, `rebind-restore ${extensionId}@${previous}`);
+                            wrapperRestored.add(`${extensionId}@${previous}`);
+                        }
+                        catch (restoreError) {
+                            // The restore failure rides along: the primary rebind error is the
+                            // named reason; the restore failure is recorded in the message.
+                            throw new Error(`${error instanceof Error ? error.message : String(error)} (and restoring ${extensionId}@${previous} also failed: `
+                                + `${restoreError instanceof Error ? restoreError.message : String(restoreError)})`);
+                        }
+                    }
+                    // The previous surface is restored; the commit catch must NOT restore
+                    // it again — the marker distinguishes this path.
+                    throw new RebindRestoredFailure(error instanceof Error ? error.message : String(error), error);
+                }
+            };
+            try {
+                return await commitUpdate({
+                    storeDir: options.storeDir,
+                    profile,
+                    extensionId,
+                    stagedVersion,
+                    hooks: { quiescePrevious, rebindNext },
+                });
+            }
+            catch (error) {
+                /**
+                 * A failure AFTER the quiesce (pointer write failure, an integrity
+                 * refusal after the quiesce, or the auto-rollback after a rebind the
+                 * wrapper could NOT restore) left the old surface withdrawn while the
+                 * pointer names a version nothing republished. Restore the recorded
+                 * pointer's surface here; when the restore itself fails, name BOTH
+                 * failures. A rebind the wrapper ALREADY restored is skipped — it was
+                 * the wrapper's own revert (the REBIND-REVERT contract).
+                 */
+                if (quiesced && !(error instanceof RebindRestoredFailure)) {
+                    const restored = currentPointer(store, profile, extensionId);
+                    if (restored !== undefined && !wrapperRestored.delete(`${extensionId}@${restored}`)) {
+                        try {
+                            await withTimeout(hooks.rebind(extensionId, restored), timeoutMs, `commit-restore ${extensionId}@${restored}`);
+                        }
+                        catch (restoreError) {
+                            throw new Error(`${error instanceof Error ? error.message : String(error)} (and restoring ${extensionId}@${restored} also failed: `
+                                + `${restoreError instanceof Error ? restoreError.message : String(restoreError)})`);
+                        }
+                    }
+                }
+                throw error;
+            }
+        },
+        async rollback(extensionId) {
+            // rebindRestored is bound HOST-side (the SDK awaits it unbounded after the
+            // restore is durable); a timeout surfaces as the SDK's hookFailure.
+            return await rollback({
+                storeDir: options.storeDir,
+                profile,
+                extensionId,
+                rebindRestored: async (restoredVersion) => {
+                    await withTimeout(hooks.rebind(extensionId, restoredVersion), timeoutMs, `rebind-restored ${extensionId}@${restoredVersion}`);
+                },
+            });
+        },
+    };
+}
+//# sourceMappingURL=update-surface.js.map

package/node_modules/@try-works/tool-mode-contracts/lib/contracts/standard.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The remaining standard tool contracts (EXT-21, task-69).
+ *
+ * These descriptors are SCHEMAS AND SEMANTICS ONLY — no model bindings, no
+ * weights, no host code (EXT-17). Each is a closed schema with honest
+ * `semantics`, `limits` and `unsupported` records, matching the vocabulary the
+ * host registers and the extension packages implement against.
+ *
+ * @module @try-works/tool-mode-contracts/contracts/standard
+ */
+import type { ToolContract } from '../registry.ts';
+/** The `text.title` contract at version 1.0.0 (RCP-12). */
+export declare const textTitle: ToolContract;
+/** The `image.describe` contract at version 1.0.0 (HLM-12). */
+export declare const imageDescribe: ToolContract;
+/** The `embed.multimodal` contract at version 1.0.0 (EmbeddingGemma family). */
+export declare const multimodalEmbed: ToolContract;
+/** The `semantic.similarity` contract at version 1.0.0. */
+export declare const semanticSimilarity: ToolContract;
+/** The `semantic.rank` contract at version 1.0.0. */
+export declare const semanticRank: ToolContract;
+/** The `semantic.classify` contract at version 1.0.0. */
+export declare const semanticClassify: ToolContract;
+/** The `semantic.deduplicate` contract at version 1.0.0. */
+export declare const semanticDeduplicate: ToolContract;
+/** The `media.find_moments` contract at version 1.0.0. */
+export declare const mediaFindMoments: ToolContract;
+/** The `decision.choose` contract at version 1.0.0 (Laya family). */
+export declare const decisionChoose: ToolContract;
+/** The `decision.test` contract at version 1.0.0. */
+export declare const decisionTest: ToolContract;
+/** The `decision.score` contract at version 1.0.0. */
+export declare const decisionScore: ToolContract;
+/** The `structured.extract` contract at version 1.0.0 (Needle family). */
+export declare const structuredExtract: ToolContract;
+/** The `plan.tools` contract at version 1.0.0 (Needle family). */
+export declare const toolsPlan: ToolContract;
+//# sourceMappingURL=standard.d.ts.map

package/node_modules/@try-works/tool-mode-contracts/lib/contracts/standard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard.d.ts","sourceRoot":"","sources":["../../src/contracts/standard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAElD,2DAA2D;AAC3D,eAAO,MAAM,SAAS,EAAE,YAuCvB,CAAA;AAED,+DAA+D;AAC/D,eAAO,MAAM,aAAa,EAAE,YAmC3B,CAAA;AAGD,gFAAgF;AAChF,eAAO,MAAM,eAAe,EAAE,YAwC7B,CAAA;AAED,2DAA2D;AAC3D,eAAO,MAAM,kBAAkB,EAAE,YA0BhC,CAAA;AAED,qDAAqD;AACrD,eAAO,MAAM,YAAY,EAAE,YAuC1B,CAAA;AAED,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,EAAE,YA8B9B,CAAA;AAED,4DAA4D;AAC5D,eAAO,MAAM,mBAAmB,EAAE,YAmCjC,CAAA;AAED,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB,EAAE,YAwC9B,CAAA;AAED,qEAAqE;AACrE,eAAO,MAAM,cAAc,EAAE,YA8B5B,CAAA;AAED,qDAAqD;AACrD,eAAO,MAAM,YAAY,EAAE,YA8B1B,CAAA;AAED,sDAAsD;AACtD,eAAO,MAAM,aAAa,EAAE,YAoC3B,CAAA;AAED,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,EAAE,YA4B/B,CAAA;AAED,kEAAkE;AAClE,eAAO,MAAM,SAAS,EAAE,YAwCvB,CAAA"}