@dsh-cc/tools 0.5.0

package/lib/runtime-registry.js

@@ -0,0 +1,269 @@
+/**
+ * ToolRuntime registry collaborators: registration, reservation, admission,
+ * restriction, guards, and per-scope view resolution. Every function takes
+ * the owning runtime as its `rt: ToolRuntimeCore` first parameter; bodies are
+ * verbatim moves from the former `ToolRuntime` methods with `this.` → `rt.`.
+ * @module
+ */
+import { scopeOf } from '@deepseek-ai/dsh-scope';
+import { assertSupportedJsonSchema } from "./json-schema.js";
+import { RUN_CODE_NAME } from "./code-mode.js";
+/**
+ * Register globally or in the calling agent scope. Scoped tools shadow
+ * globals; duplicates within one layer and the reserved `run_code` name fail.
+ * @param rt - the owning runtime.
+ * @param definition - tool schema, execution, and optional finalization/presentation callbacks.
+ * @returns the exact disposer that unregisters the tool.
+ */
+export function register(rt, definition) {
+    const name = definition.name;
+    const output = definition.output;
+    if (output === undefined || typeof output !== 'object'
+        || typeof output.render !== 'function'
+        || (output.presentationMeta !== undefined && typeof output.presentationMeta !== 'function')) {
+        throw new TypeError(`tool "${name}" must declare output { schema, render, presentationMeta? }`);
+    }
+    assertSupportedJsonSchema(output.schema);
+    const timeoutMs = definition.timeoutMs;
+    if (timeoutMs !== undefined
+        && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+        throw new TypeError(`tool "${name}" timeoutMs must be a positive finite number`);
+    }
+    // Reserved unconditionally: any agent may select a code mode for itself,
+    // so a name free to take under the deployment default would become a
+    // collision the moment a preset mounted.
+    if (name === RUN_CODE_NAME) {
+        throw new Error(`tool name "${RUN_CODE_NAME}" is reserved for the Code Mode presentation transport and cannot be registered or shadowed`);
+    }
+    return rt.layers.effect(rt.ctx, layer => layer.tools.insert(name, definition), { label: 'tools.register()' });
+}
+/**
+ * Reserve a capability NAME in the calling layer without registering a
+ * visible definition. A reserved name joins the known/restrictable universe
+ * — a scope may later `restrict()` it away, and `toolOrder` may list it — but
+ * it never reaches the model-facing schema until a real `register()` supplies
+ * the definition. This is how a deferred-tool registry seeds the names a
+ * composition may gate before their heavy definitions load.
+ *
+ * The name stays out of the runtime's `get` and `schemas` views (only
+ * registered definitions are visible). Duplicate reservations within one
+ * layer fail, matching the duplicate-name rule for `register`.
+ * @param rt - the owning runtime.
+ * @param name - the capability name to make known without presenting.
+ * @returns the exact disposer that clears the reservation.
+ */
+export function reserve(rt, name) {
+    if (name === RUN_CODE_NAME) {
+        throw new Error(`tool name "${RUN_CODE_NAME}" is reserved for the Code Mode presentation transport and cannot be registered or shadowed`);
+    }
+    return rt.layers.effect(rt.ctx, layer => layer.reserved.insert(name, undefined), { label: 'tools.reserve()' });
+}
+/**
+ * Whether a global tool name passes every scoped restriction on the viewing
+ * scope's chain. The answer ignores registration: a reserved or not-yet-loaded
+ * name is admitted if no `allow`/`deny` on the chain masks it, so a caller can
+ * gate whether a deferred capability may load for one agent. A name masked by
+ * an `allow` list it is absent from, or present in a `deny` list, is not
+ * admitted. When a name has multiple restrictions, they intersect (all must
+ * admit it), matching registration visibility.
+ * @param rt - the owning runtime.
+ * @param name - the capability name to test.
+ * @param scope - the viewing scope (the agent); omitted for the global view, which has no restrictions.
+ * @returns whether the name may load for that scope.
+ */
+export function isAdmitted(rt, name, scope) {
+    return rt.layers.chainLayers(scope).every(layer => layer.admits(name));
+}
+/**
+ * Restrict global tools for the calling agent scope. Empty filters, unknown
+ * names, scope-local names, and reserved transport names fail. Restrictions
+ * intersect; scoped registrations remain visible.
+ * @param rt - the owning runtime.
+ * @param filter - global-tool mask: `allow` (keep only) and/or `deny` (remove).
+ * @returns the exact disposer that lifts this restriction.
+ */
+export function restrict(rt, filter) {
+    const scope = scopeOf(rt.ctx);
+    if (scope === undefined) {
+        throw new Error('tools.restrict() requires a scoped context (agent.ctx): a context-global restriction would mask every agent — deny the tool for the intended agent instead');
+    }
+    const allow = filter.allow;
+    const deny = filter.deny;
+    if (allow === undefined && deny === undefined) {
+        throw new Error('tools.restrict({}) is a no-op: pass `allow` and/or `deny` (an empty filter is almost always a materialized-empty-config bug)');
+    }
+    const compiled = {
+        ...allow !== undefined ? { allow: new Set(allow) } : {},
+        ...deny !== undefined ? { deny: new Set(deny) } : {},
+    };
+    if ([...allow ?? [], ...deny ?? []].includes(RUN_CODE_NAME)) {
+        throw new Error(`tools.restrict() cannot name reserved Code Mode presentation transport "${RUN_CODE_NAME}"; restrict end-capability tools instead`);
+    }
+    const known = rt.view(scope).restrictableNames;
+    const unknown = [...allow ?? [], ...deny ?? []].filter(name => !known.has(name));
+    if (unknown.length > 0) {
+        throw new Error(`tools.restrict() names unknown global tool${unknown.length > 1 ? 's' : ''} ${unknown.map(n => `"${n}"`).join(', ')}; known global tools: ${[...known].sort().join(', ') || '(none)'}`);
+    }
+    return rt.layers.effect(rt.ctx, layer => layer.restrictions.append(compiled), { label: 'tools.restrict()' });
+}
+/**
+ * Register a monotonic guard after the extensible `tools/pre-execute`
+ * waterfall. A plain-context guard applies globally; one registered through
+ * `agent.ctx` applies only to that agent. Any matching guard may deny by
+ * returning a reason, while no guard can force-allow a call another guard
+ * denied. The exact effect disposer is returned for ordered ownership and
+ * HMR cleanup.
+ * @param rt - the owning runtime.
+ * @param guard - synchronous check; a returned string denies the execution.
+ * @returns the exact disposer that unregisters the guard.
+ */
+export function guard(rt, guard) {
+    return rt.layers.effect(rt.ctx, layer => layer.guards.append(guard), { label: 'tools.guard()', notify: false });
+}
+/** First monotonic denial from the global then the scope chain's guard layers, farthest first. */
+export function guardReason(rt, exec) {
+    const globalReason = rt.layers.global.guardReason(exec);
+    if (globalReason !== undefined)
+        return globalReason;
+    if (exec.agent === undefined)
+        return undefined;
+    for (const layer of rt.layers.chainLayers(exec.agent)) {
+        const reason = layer.guardReason(exec);
+        if (reason !== undefined)
+            return reason;
+    }
+    return undefined;
+}
+/**
+ * Resolve every registry fact one scope needs in one layer traversal. The
+ * visible map applies restrictions to the INHERITED surface, then the
+ * scope's own registrations and the reserved presentation transport; the
+ * other sets retain the pre-restriction facts needed by restriction and
+ * prompt-order validation.
+ *
+ * A restriction filters what a scope inherits — the global layer and every
+ * ancestor layer on its chain — and never what its OWN layer registers.
+ * That exemption is what a per-child capability filter has to keep intact:
+ * the delegation runtime registers a child's reporting and structured-output
+ * tools into the child's own layer, and a filter naming the capabilities the
+ * child may use must not strip the machinery it answers through.
+ *
+ * Reading the exempt set as "the global layer" instead of "not mine" held
+ * only while every model-facing tool sat in the host composition. Once
+ * presets moved them onto the agent plane they became an ANCESTOR
+ * contribution, so a child's filter silently stopped constraining anything
+ * it was given.
+ * @param rt - the owning runtime.
+ * @param scope - the viewing scope (the agent), or undefined for the global view.
+ * @returns the complete derived view for that scope.
+ */
+export function view(rt, scope) {
+    // Scope-chain layers, farthest ancestor first, the exact scope last.
+    const layers = rt.layers.chainLayers(scope);
+    // Chain-blind on purpose: this is the ONE layer whose registrations the
+    // scope owns rather than inherits, and it is absent until the scope
+    // contributes something.
+    const own = rt.layers.peek(scope);
+    // Inherited surface, nearest ancestor last: a nearer scope's same-name
+    // entry shadows a farther one, and the global layer is the farthest.
+    const inherited = new Map(rt.layers.global.tools.entries());
+    for (const layer of layers) {
+        if (layer === own)
+            continue;
+        for (const [name, definition] of layer.tools.entries())
+            inherited.set(name, definition);
+    }
+    const visible = new Map();
+    const knownNames = new Set();
+    const restrictableNames = new Set();
+    for (const [name, definition] of inherited) {
+        knownNames.add(name);
+        restrictableNames.add(name);
+        // Restrictions intersect across the whole chain: any scope on it may
+        // mask an inherited name for everything nested inside it.
+        if (layers.every(layer => layer.admits(name)))
+            visible.set(name, definition);
+    }
+    // The scope's own registrations last, shadowing an inherited name and
+    // outside the filter above.
+    if (own !== undefined) {
+        for (const [name, definition] of own.tools.entries()) {
+            knownNames.add(name);
+            visible.set(name, definition);
+        }
+    }
+    // Reserved names are known and restrictable but never visible: they enter
+    // the inherited universe (so a scope may gate them before load) without a
+    // definition to present. Chain + global, same inheritance shape as tools.
+    for (const { reserved } of [rt.layers.global, ...layers]) {
+        for (const name of reserved.keys()) {
+            knownNames.add(name);
+            restrictableNames.add(name);
+        }
+    }
+    // Presentation infrastructure is resolved last and outside capability
+    // filtering. Registration rejects this reserved name, so the insertion is
+    // an invariant assertion as well as protection against future layer
+    // changes. Per scope: a native agent must not find `run_code` in its
+    // dispatch table because some other agent in the process presents it.
+    if (rt.modeFor(scope) !== 'native') {
+        visible.set(RUN_CODE_NAME, rt.requireCodeTransport());
+    }
+    return { visible, knownNames, restrictableNames };
+}
+/**
+ * Look up a tool as one scope sees it (scoped
+ * shadows global; a restricted-away global reads as absent). Presenters pass
+ * the calling agent so the rendered card matches the definition that
+ * actually executed.
+ * @param rt - the owning runtime.
+ * @param name - the tool name as registered.
+ * @param scope - the viewing scope (the agent); omitted = the global view.
+ * @returns the definition the scope resolves, or undefined when none is visible.
+ */
+export function get(rt, name, scope) {
+    return rt.view(scope).visible.get(name);
+}
+/**
+ * Resolve the definition that MAY EXECUTE for a call, applying the mode
+ * collapse at the operation boundary that owns it. The registry view
+ * (`get`) is presentation-agnostic; here a MODEL-DIRECT call under `code`
+ * may only name the reserved `run_code` transport, while a nested
+ * sub-dispatch (a `parent` token set — the `run_code` SDK calling a tool
+ * it bound) may call any visible tool. Denial surfaces as `UNKNOWN_TOOL`
+ * through the executor, matching an absent definition.
+ * @param rt - the owning runtime.
+ * @param name - the tool name as registered.
+ * @param scope - the viewing scope (the agent); omitted = the global view.
+ * @param nested - whether the call is a transport sub-dispatch, not a model-direct call.
+ * @returns the definition that may run, or undefined when the call must be rejected.
+ */
+export function resolveExecution(rt, name, scope, nested) {
+    const tool = rt.get(name, scope);
+    if (tool === undefined)
+        return undefined;
+    if (rt.collapses(name, scope, nested))
+        return undefined;
+    return tool;
+}
+/**
+ * Classify a pending call through the caller's visible tool definition. Only
+ * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or
+ * throwing classifiers are exclusive.
+ * @param rt - the owning runtime.
+ * @param exec - call name, parsed arguments, and optional agent scope.
+ * @returns the fail-closed scheduling mode.
+ */
+export function executionMode(rt, exec) {
+    const tool = rt.resolveExecution(exec.name, exec.agent, exec.parent !== undefined);
+    if (!tool?.isConcurrencySafe)
+        return { kind: 'exclusive' };
+    try {
+        const concurrencySafe = tool.isConcurrencySafe(exec.arguments);
+        return concurrencySafe === true ? { kind: 'parallel' } : { kind: 'exclusive' };
+    }
+    catch {
+        return { kind: 'exclusive' };
+    }
+}
+//# sourceMappingURL=runtime-registry.js.map

package/lib/runtime-registry.js.map

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

package/lib/runtime-results.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ToolRuntime result collaborators: post-execute policy, canonical-result
+ * marking, success/normalization projection, content finalization, and final
+ * notification. Bodies are verbatim moves from the former `ToolRuntime`
+ * methods with `this.` → `rt.`.
+ * @module
+ */
+import type { ToolDefinition, ToolExecution, ToolExecutionResult, ToolExecutionSuccess } from './tool-types.ts';
+import type { ToolRuntimeCore } from './runtime-core.ts';
+/** Notify observers without exposing a mutation or error channel into the outcome. */
+export declare function notifyResult(rt: ToolRuntimeCore, exec: ToolExecution, result: ToolExecutionResult): void;
+/**
+ * Run the `tools/post-execute` waterfall over a dispatched `result` and apply
+ * its `PostToolDecision`: `accept` keeps the call successful (replacing
+ * `content` when given), `block` turns it into an `isError` whose content is
+ * the corrective `feedback`. Either decision may attach `additionalContexts`,
+ * which are ferried on the returned result for the loop's active-batch FIFO.
+ * Context deferred by the tool body survives an accepted result but is
+ * discarded when the outer call is blocked; a block exposes only context the
+ * blocking decision explicitly supplied.
+ * Runs inside `execute`'s outer try/catch (a throwing listener → isError).
+ */
+export declare function postExecute(rt: ToolRuntimeCore, exec: ToolExecution, result: ToolExecutionResult): Promise<ToolExecutionResult>;
+/** Mark one registry-normalized result as canonical only for its owning dispatch. */
+export declare function markCanonical<T extends ToolExecutionResult>(rt: ToolRuntimeCore, exec: ToolExecution, result: T): T;
+/** Snapshot, validate, render, and optionally project one successful body value. */
+export declare function createSuccessResult(rt: ToolRuntimeCore, exec: ToolExecution, tool: ToolDefinition, candidate: unknown): ToolExecutionSuccess;
+/** Normalize an around-dispatch wrapper's authored result through the owning output contract. */
+export declare function normalizeDispatchResult(rt: ToolRuntimeCore, exec: ToolExecution, result: ToolExecutionResult): ToolExecutionResult;
+/** Materialize the authoritative commit outcome once, immediately before `tools/result`. */
+export declare function materializeFinalResult(_rt: ToolRuntimeCore, result: ToolExecutionResult): ToolExecutionResult;
+//# sourceMappingURL=runtime-results.d.ts.map

package/lib/runtime-results.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-results.d.ts","sourceRoot":"","sources":["../src/runtime-results.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,OAAO,KAAK,EAAoB,cAAc,EAAE,aAAa,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AACjI,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAExD,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAmBxG;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAuCrI;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,CAAC,SAAS,mBAAmB,EAAE,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAGnH;AAED,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,cAAc,EAAE,SAAS,EAAE,OAAO,GAAG,oBAAoB,CA8B5I;AAED,iGAAiG;AACjG,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,CAkBlI;AAED,4FAA4F;AAC5F,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,CAe7G"}

package/lib/runtime-results.js

@@ -0,0 +1,163 @@
+/**
+ * ToolRuntime result collaborators: post-execute policy, canonical-result
+ * marking, success/normalization projection, content finalization, and final
+ * notification. Bodies are verbatim moves from the former `ToolRuntime`
+ * methods with `this.` → `rt.`.
+ * @module
+ */
+import { scopeTarget } from '@deepseek-ai/dsh-scope';
+import { deepFreeze } from '@deepseek-ai/dsh-llm';
+import { errorMessage, failureMessageFromContent, projectionError, snapshotProjection, snapshotToolValue, ToolNotFoundError, ToolOutputError } from "./abort-utils.js";
+import { validateJsonSchemaValue } from "./json-schema.js";
+import { materializePresentation } from "./tool-types.js";
+/** Notify observers without exposing a mutation or error channel into the outcome. */
+export function notifyResult(rt, exec, result) {
+    // Freeze the registry's live object before observers receive its readonly
+    // WeakMap-keyable view.
+    Object.freeze(exec);
+    const { name: toolName, callId } = exec;
+    const reportFailure = (error) => {
+        rt.ctx.logger.warn(`tool "${toolName}" (${callId}): tools/result observer failed: ${errorMessage(error)}`);
+    };
+    const callbacks = rt.ctx.events.dispatch('emit', [
+        scopeTarget(rt, exec.agent), 'tools/result', exec, result,
+    ]);
+    for (const callback of callbacks) {
+        try {
+            const returned = callback(exec, result);
+            void Promise.resolve(returned).catch(reportFailure);
+        }
+        catch (error) {
+            reportFailure(error);
+        }
+    }
+}
+/**
+ * Run the `tools/post-execute` waterfall over a dispatched `result` and apply
+ * its `PostToolDecision`: `accept` keeps the call successful (replacing
+ * `content` when given), `block` turns it into an `isError` whose content is
+ * the corrective `feedback`. Either decision may attach `additionalContexts`,
+ * which are ferried on the returned result for the loop's active-batch FIFO.
+ * Context deferred by the tool body survives an accepted result but is
+ * discarded when the outer call is blocked; a block exposes only context the
+ * blocking decision explicitly supplied.
+ * Runs inside `execute`'s outer try/catch (a throwing listener → isError).
+ */
+export async function postExecute(rt, exec, result) {
+    const decision = await rt.ctx.waterfall(scopeTarget(rt, exec.agent), 'tools/post-execute', exec, result, () => Promise.resolve({ kind: 'accept' }));
+    const decisionContexts = decision.additionalContexts ?? [];
+    if (decision.kind === 'block') {
+        const message = failureMessageFromContent(decision.feedback);
+        return rt.markCanonical(exec, {
+            content: decision.feedback,
+            isError: true,
+            error: { message },
+            ...decisionContexts.length > 0 ? { additionalContexts: decisionContexts } : {},
+        });
+    }
+    if (Object.hasOwn(decision, 'content') && Object.hasOwn(decision, 'value')) {
+        throw new TypeError('tools/post-execute accept decision cannot replace both value and content');
+    }
+    const additionalContexts = [
+        ...result.additionalContexts ?? [],
+        ...decisionContexts,
+    ];
+    if (Object.hasOwn(decision, 'value')) {
+        if (result.isError) {
+            throw new TypeError('tools/post-execute cannot replace the value of a failed result');
+        }
+        const tool = rt.resolveExecution(exec.name, exec.agent, exec.parent !== undefined);
+        if (tool === undefined)
+            throw new ToolNotFoundError(exec.name);
+        const replaced = rt.createSuccessResult(exec, tool, decision.value);
+        return rt.markCanonical(exec, {
+            ...replaced,
+            ...additionalContexts.length > 0 ? { additionalContexts } : {},
+        });
+    }
+    return rt.markCanonical(exec, {
+        ...result,
+        ...decision.content !== undefined ? { content: decision.content } : {},
+        ...additionalContexts.length > 0 ? { additionalContexts } : {},
+    });
+}
+/** Mark one registry-normalized result as canonical only for its owning dispatch. */
+export function markCanonical(rt, exec, result) {
+    rt.canonicalResults.set(result, exec.token);
+    return result;
+}
+/** Snapshot, validate, render, and optionally project one successful body value. */
+export function createSuccessResult(rt, exec, tool, candidate) {
+    const detached = snapshotToolValue(tool.name, candidate);
+    const violations = validateJsonSchemaValue(tool.output.schema, detached, 'value');
+    if (violations.length > 0)
+        throw new ToolOutputError(tool.name, violations);
+    const value = deepFreeze(detached);
+    let rendered;
+    try {
+        rendered = tool.output.render(exec.arguments, value);
+    }
+    catch (error) {
+        throw projectionError(tool.name, 'render', error);
+    }
+    const content = snapshotProjection(tool.name, 'render', rendered);
+    let meta;
+    if (exec.parent === undefined && tool.output.presentationMeta !== undefined) {
+        let projected;
+        try {
+            projected = tool.output.presentationMeta(exec.arguments, value);
+        }
+        catch (error) {
+            throw projectionError(tool.name, 'presentationMeta', error);
+        }
+        meta = snapshotProjection(tool.name, 'presentationMeta', projected);
+    }
+    const concludesTurn = rt.concludingExecutions.has(exec);
+    return rt.markCanonical(exec, rt.materializeFinalResult({
+        isError: false,
+        value,
+        content,
+        ...meta !== undefined ? { meta } : {},
+        ...concludesTurn ? { concludesTurn: true } : {},
+    }));
+}
+/** Normalize an around-dispatch wrapper's authored result through the owning output contract. */
+export function normalizeDispatchResult(rt, exec, result) {
+    if (rt.canonicalResults.get(result) === exec.token)
+        return result;
+    if (result.isError) {
+        return rt.markCanonical(exec, {
+            isError: true,
+            error: result.error,
+            content: result.content,
+            ...result.meta !== undefined ? { meta: result.meta } : {},
+            ...result.additionalContexts !== undefined ? { additionalContexts: result.additionalContexts } : {},
+        });
+    }
+    const tool = rt.resolveExecution(exec.name, exec.agent, exec.parent !== undefined);
+    if (tool === undefined)
+        throw new ToolNotFoundError(exec.name);
+    const normalized = rt.createSuccessResult(exec, tool, result.value);
+    return rt.markCanonical(exec, {
+        ...normalized,
+        ...result.additionalContexts !== undefined ? { additionalContexts: result.additionalContexts } : {},
+    });
+}
+/** Materialize the authoritative commit outcome once, immediately before `tools/result`. */
+export function materializeFinalResult(_rt, result) {
+    const presentation = {
+        content: result.content,
+        ...result.meta !== undefined ? { meta: result.meta } : {},
+        ...result.additionalContexts !== undefined ? { additionalContexts: result.additionalContexts } : {},
+    };
+    if (result.isError) {
+        return materializePresentation({ isError: true, error: result.error, ...presentation });
+    }
+    const detached = materializePresentation({
+        isError: false,
+        ...presentation,
+        ...result.concludesTurn === true ? { concludesTurn: true } : {},
+    });
+    return deepFreeze({ ...detached, value: result.value });
+}
+//# sourceMappingURL=runtime-results.js.map

package/lib/runtime-results.js.map

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

package/lib/runtime-schemas.d.ts

@@ -0,0 +1,112 @@
+/**
+ * ToolRuntime presentation collaborators: the presentation-mode resolver, the
+ * `code` collapse statement, prompt-section assembly, and the model-facing
+ * schema projections. Bodies are verbatim moves from the former `ToolRuntime`
+ * methods with `this.` → `rt.`.
+ * @module
+ */
+import type { ScopeKey } from '@deepseek-ai/dsh-scope';
+import type { ToolSchema } from '@deepseek-ai/dsh-llm';
+import type { ToolProviderResult } from '@deepseek-ai/dsh-system-prompt';
+import type { ToolSdkSchema } from './ts-types.ts';
+import type { ToolDefinition, ToolPresentationMode } from './tool-types.ts';
+import type { ToolRuntimeCore } from './runtime-core.ts';
+/**
+ * The prompt statement of the `code` executor collapse, registered wherever
+ * `sdkSection` is and rendering empty outside an effective `code`.
+ *
+ * Every tool contributes its own guidance section naming its tool, none of
+ * them qualify how that tool is reached, and they all render before the SDK
+ * (orders 100-199 against `SDK_SECTION_ORDER`). Without this the model
+ * reads a catalog of tools it is told to use and no statement that only
+ * `run_code` may be called, so it emits a native call, receives
+ * `UNKNOWN_TOOL` for a tool the prompt just declared, and concludes the
+ * deployment is inconsistent. `COLLAPSE_SECTION_ORDER` places the rule
+ * before that guidance rather than after it.
+ *
+ * `both` renders empty: native calls do execute there, so the rule is false.
+ * @param rt - the owning runtime.
+ * @returns the section registration.
+ */
+export declare function collapseSection(rt: ToolRuntimeCore): {
+    name: string;
+    order: number;
+    text: (context: {
+        scope?: ScopeKey;
+    }) => string;
+};
+/**
+ * The generated-SDK prompt section, registered globally by a code-mode
+ * deployment and per scope by `presentAs`.
+ *
+ * The body regenerates from the CALLING scope, and renders empty for an
+ * agent presenting natively — an agent that opted out under a code-mode
+ * deployment still sees the global registration, and an empty section is
+ * dropped from the rendered prompt.
+ * @param rt - the owning runtime.
+ * @returns the section registration.
+ */
+export declare function sdkSection(rt: ToolRuntimeCore): {
+    name: string;
+    order: number;
+    text: (context: {
+        scope?: ScopeKey;
+    }) => string;
+};
+/**
+ * The presentation one scope's agent sees: its own declaration, else the
+ * deployment default.
+ * @param rt - the owning runtime.
+ * @param scope - the calling agent, or undefined for the global view.
+ * @returns the resolved presentation mode.
+ */
+export declare function modeFor(rt: ToolRuntimeCore, scope?: ScopeKey): ToolPresentationMode;
+/**
+ * Present the calling scope's tools in `mode` instead of the deployment
+ * default. Nearest scope on the chain wins, so a preset's standing
+ * declaration covers every agent joined under it.
+ *
+ * Scoped only, and one declaration per scope: this is how an agent preset
+ * composes Code Mode agents beside native ones in the same process, and a
+ * process-global override would be the `mode` config field instead.
+ * @param rt - the owning runtime.
+ * @param mode - the presentation the covered agents' models see.
+ * @returns the exact disposer that restores the deployment default.
+ */
+export declare function presentAs(rt: ToolRuntimeCore, mode: ToolPresentationMode): () => void;
+/**
+ * Build one scope's wire schemas and names for prompt-order validation.
+ * Restrictions do not make known tools invalid, but a mode collapse does.
+ */
+export declare function wireSchemas(rt: ToolRuntimeCore, scope?: ScopeKey): ToolProviderResult;
+/**
+ * Project visible definitions onto the allowlisted model-facing schema fields,
+ * excluding execution and presentation callbacks.
+ * @param rt - the owning runtime.
+ * @param scope - the viewing scope (the agent); omitted = the global view.
+ * @returns one deep-cloned schema per visible tool.
+ */
+export declare function schemas(rt: ToolRuntimeCore, scope?: ScopeKey): ToolSchema[];
+/** Project visible callable tools onto the generated Code Mode SDK contract. */
+export declare function sdkSchemas(rt: ToolRuntimeCore, scope?: ScopeKey): ToolSdkSchema[];
+/** Project one definition onto the model-facing schema fields. */
+export declare function schemaOf(_rt: ToolRuntimeCore, definition: ToolDefinition, detachParameters: boolean): ToolSchema;
+/**
+ * Whether the `code` mode collapse denies a model-direct call: only the
+ * reserved `run_code` transport may be named. Nested sub-dispatches (a
+ * `parent` token set) bypass the collapse. One home for the
+ * security-relevant predicate, shared by `resolveExecution` and
+ * `createExecution` so the two can never drift apart.
+ *
+ * Resolved through `modeFor`, NOT `defaultMode`: an agent given `code`
+ * by an agent preset under a native deployment is the composition
+ * `dsh-agent-tool-presentation` exists for, and reading the deployment default would
+ * leave exactly that agent uncollapsed — announcing one surface while
+ * executing another, which is the bypass this collapse closes.
+ * @param rt - the owning runtime.
+ * @param name - the tool name as registered.
+ * @param scope - the viewing scope whose effective presentation mode applies.
+ * @param nested - whether the call is a transport sub-dispatch, not a model-direct call.
+ */
+export declare function collapses(rt: ToolRuntimeCore, name: string, scope: ScopeKey | undefined, nested: boolean): boolean;
+//# sourceMappingURL=runtime-schemas.d.ts.map

package/lib/runtime-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-schemas.d.ts","sourceRoot":"","sources":["../src/runtime-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAExE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAE3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAgBxD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,CAAC,EAAE,QAAQ,CAAA;KAAE,KAAK,MAAM,CAAA;CAAE,CAQrI;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,CAAC,EAAE,QAAQ,CAAA;KAAE,KAAK,MAAM,CAAA;CAAE,CAiBhI;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,eAAe,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,oBAAoB,CAWnF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE,oBAAoB,GAAG,MAAM,IAAI,CA2BrF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,eAAe,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,kBAAkB,CAqBrF;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,eAAe,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,UAAU,EAAE,CAE3E;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,EAAE,EAAE,eAAe,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,aAAa,EAAE,CAcjF;AAED,kEAAkE;AAClE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,eAAe,EAAE,UAAU,EAAE,cAAc,EAAE,gBAAgB,EAAE,OAAO,GAAG,UAAU,CAWhH;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,SAAS,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAElH"}