@dsh-cc/tools 0.5.0

package/lib/index.d.ts

@@ -0,0 +1,348 @@
+/**
+ * Tool registry, model presentation modes, and pre/guard/around/post/result
+ * execution pipeline.
+ * @module @dsh-cc/tools
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { ScopedLayers } from '@deepseek-ai/dsh-scope';
+import type { ScopeKey, Scoped } from '@deepseek-ai/dsh-scope';
+import type { ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm';
+import type { UserMessage } from '@deepseek-ai/dsh-session';
+import type { ToolProviderResult } from '@deepseek-ai/dsh-system-prompt';
+import type { CodeRuntime } from '@deepseek-ai/dsh-code-runtime';
+import { TOOL_RUNTIME_SCHEDULER } from './scheduler.ts';
+import { ToolLayer } from './tool-layer.ts';
+import type { ToolAskResolution, ToolCancellationState } from './tool-layer.ts';
+import type { CodeDispatchLog, Config, MutableToolRunContext, PostToolDecision, PreToolDecision, ScheduledToolDispatch, ScheduledToolPreparation, ToolDefinition, ToolDispatchExecution, ToolExecution, ToolExecutionInput, ToolExecutionMode, ToolExecutionResult, ToolExecutionSuccess, ToolExecutionToken, ToolGuard, ToolPresentationMode, ToolRestriction, ToolRunContext, ToolRuntimeScheduler, ToolView } from './tool-types.ts';
+import type { ToolSdkSchema } from './ts-types.ts';
+import type { ToolRuntimeCore } from './runtime-core.ts';
+export { defineTool, valueSchemaSpecToJsonSchema, parameterSchemaSpecToJsonSchema, validateArgs, ToolArgsError, type ValueSchemaAnnotations, type StringValueSchemaSpec, type NumberValueSchemaSpec, type IntegerValueSchemaSpec, type BooleanValueSchemaSpec, type NullValueSchemaSpec, type ArrayValueSchemaSpec, type ObjectValueSchemaSpec, type JsonValueSchemaSpec, type OneOfValueSchemaSpec, type ValueSchemaSpec, type ParameterPropertySpec, type ParameterSchemaSpec, type ParameterJsonSchema, type InferValue, type InferArgs, type DefineToolOptions, } from './schema.ts';
+export { assertSupportedJsonSchema, assertObjectJsonSchema, validateJsonSchemaValue, JsonSchemaError, type JsonSchemaNode, type ObjectJsonSchema, type JsonSchemaType, type JsonSchemaScalar, } from './json-schema.ts';
+export type { JsonValue } from '@deepseek-ai/dsh-session';
+export type { CodeDispatchEventData, CodeDispatchStartEventData } from './types.ts';
+export { CodeRunFailedError, RUN_CODE_NAME } from './code-mode.ts';
+export { CC_TO_HARNESS_TOOLS, KNOWN_HARNESS_TOOLS, translateToolNames, ccToolAliases, ccCanonicalToolName, type ToolNameTranslationPolicy, } from './cc-names.ts';
+export { jsonSchemaToTs, renderToolsSdk } from './ts-types.ts';
+export { jsonSchemaToPy, renderToolsSdkPy } from './py-types.ts';
+export { defineContentToolFixture, type ContentToolFixtureOptions } from './testing.ts';
+export type { ToolCallKind, FileLocation, FileDiff, ReadFileLine, ToolCallView, GenericCallView, TerminalCallView, DiffCallView, ToolResultView, GenericResultView, TerminalResultView, DiffResultView, SearchResultView, SearchMatchesResultView, SearchPathsResultView, SearchFileMatches, SearchLineMatch, ReadResultView, WebResultView, WebSearchResultView, WebFetchResultView, WebSource, } from './presentation.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tools: ToolRuntime;
+    }
+    interface Events {
+        /**
+         * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing
+         * approval support turns `ask` into denial. Async gates must observe
+         * `exec.signal`; the registry rechecks cancellation after they settle but
+         * never abandons their promise.
+         * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+         * @param exec - the pending call (name, parsed arguments, caller agent).
+         * @mode waterfall
+         */
+        'tools/pre-execute'(this: Scoped<ToolRuntime | ToolRuntimeCore>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>;
+        /**
+         * Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns
+         * a normalized result; wrappers may change only `exec.signal`, while call
+         * identity remains immutable. The registry re-fuses the original caller
+         * signal before the body, so replacement cannot detach caller cancellation;
+         * wrappers must still restore their signal and reach quiescence.
+         * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+         * @param exec - the allowed call about to dispatch (name, parsed arguments, caller agent, signal).
+         * @mode waterfall
+         */
+        'tools/execute'(this: Scoped<ToolRuntime | ToolRuntimeCore>, exec: ToolDispatchExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>;
+        /**
+         * Accept, replace, enrich, or block a normalized dispatch result. `next()`
+         * accepts it unchanged; thrown tools still reach this waterfall as errors. Async
+         * listeners must observe `exec.signal`; after they settle, caller
+         * cancellation replaces only a successful accepted outcome with the code
+         * selected by whether the tool body was invoked.
+         * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+         * @param exec - the call that just ran (name, parsed arguments, caller agent).
+         * @param result - the dispatch outcome a listener may accept, replace, or block.
+         * @mode waterfall
+         */
+        'tools/post-execute'(this: Scoped<ToolRuntime | ToolRuntimeCore>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>;
+        /**
+         * Allow a listener to replace content in the DURABLE LOG COPY of one
+         * `run_code` sub-dispatch outcome before the bridge appends its
+         * `tool/code-dispatch` event. `next()` keeps the
+         * content unchanged; a listener may return replacement blocks (e.g. the
+         * spill policy's preview + locator for an oversized text result). Only the
+         * logged copy is affected — the program already received the complete
+         * value, and the model sees neither. A throwing listener is contained:
+         * the bridge falls back to logging the original settled content.
+         * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's dispatches.
+         * @param dispatch - the parent execution, sub-call identity, and the settled content to log.
+         * @mode waterfall
+         */
+        'tools/code-dispatch-log'(this: Scoped<ToolRuntime | ToolRuntimeCore>, dispatch: CodeDispatchLog, next: () => Promise<ContentBlock[]>): Promise<ContentBlock[]>;
+        /**
+         * Observe the frozen, lossless-JSON final outcome. Listener failures are contained.
+         * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
+         * @param exec - the execution object that traversed the pipeline.
+         * @param result - a deep-frozen snapshot of the final returned result.
+         * @mode emit
+         */
+        'tools/result'(this: Scoped<ToolRuntime | ToolRuntimeCore>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined;
+        /**
+         * A tool was registered or unregistered, or a scoped restriction changed
+         * (the available tool set changed — possibly for one scope only). An
+         * UNFILTERED registry-subject notification, deliberately not scope-filtered
+         * dispatch: a global change concerns every agent's next assembly, so a
+         * scoped listener subscribing here sees every change, not just its own
+         * scope's.
+         * @mode emit
+         */
+        'tools/change'(): void;
+    }
+}
+export type { CodeDispatchLog, Config, PostToolDecision, PreToolDecision, ScheduledToolDispatch, ScheduledToolPreparation, ToolDefinition, ToolDispatchExecution, ToolExecution, ToolExecutionFailure, ToolExecutionInput, ToolExecutionMode, ToolExecutionResult, ToolExecutionSuccess, ToolExecutionToken, ToolGuard, ToolOutputDefinition, ToolPresentationMode, ToolRestriction, ToolResult, ToolRunContext, ToolRuntimeScheduler, } from './tool-types.ts';
+export type { ToolErrorInfo, ToolFailure } from './abort-utils.ts';
+export { TOOL_ABORTED, TOOL_ABORTED_BEFORE_DISPATCH, ToolNotFoundError, ToolOutputError } from './abort-utils.ts';
+/**
+ * Scheduler entry point omitted from the generated named service API.
+ * The value MUST be the upstream symbol instance: the in-box agent loop reads
+ * the staged scheduler off the registry through the symbol exported by
+ * `@deepseek-ai/dsh-tools`, and a `Symbol()` is identity-unique — minting a
+ * private one here leaves the loop reading `undefined` and crashing every
+ * turn's first tool call (`undefined.prepare`). The binding is a type-erased
+ * `createRequire` rather than a static import so upstream's declaration graph
+ * (its own `Context` augmentation, whose vendored copy this package also
+ * ships) never enters downstream type programs; the dependency stays
+ * runtime-only (peer-declared). Declared in the {@link ./scheduler.ts} leaf
+ * module; re-exported here to keep the public barrel surface unchanged.
+ * @internal
+ */
+export { TOOL_RUNTIME_SCHEDULER };
+/**
+ * Tool registry and execution pipeline. Scoped registrations shadow globals;
+ * one visibility resolver feeds presentation, lookup, and dispatch.
+ *
+ * The implementation lives in the `runtime-*.ts` collaborator modules behind
+ * the `ToolRuntimeCore` structural interface; this class is the constructed
+ * facade — configuration, state fields, scheduler staging, and one-line
+ * delegations.
+ */
+export declare class ToolRuntime extends Service {
+    /** Cordis context; `Service` keeps it protected — declaration-only re-exposure for the `ToolRuntimeCore` interface. @internal */
+    readonly ctx: Context;
+    static inject: string[];
+    static Config: z<Config>;
+    /** Internal staged view consumed by `dsh-agent-loop`'s parallel scheduler. */
+    readonly [TOOL_RUNTIME_SCHEDULER]: ToolRuntimeScheduler;
+    /** @internal Context deferred by a running tool body, keyed by its scheduler-owned execution. */
+    readonly deferredContexts: WeakMap<ToolRunContext, UserMessage[]>;
+    /** @internal Executions whose tool body declared the current turn complete. */
+    readonly concludingExecutions: WeakSet<ToolExecution>;
+    /** @internal Original caller cancellation, kept outside the wrapper-mutable execution object. */
+    readonly cancellationStates: WeakMap<ToolRunContext, ToolCancellationState>;
+    /** @internal Definition-owned final content transform snapshotted before policy begins. */
+    readonly contentFinalizers: WeakMap<ToolRunContext, ((exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>) => ContentBlock[] | undefined) | undefined>;
+    /** @internal Visibility layers: registration, reservation, restriction, guards. */
+    readonly layers: ScopedLayers<ToolLayer>;
+    /** @internal Presentation for scopes that declare none; {@link modeFor} shadows it per scope. */
+    readonly defaultMode: ToolPresentationMode;
+    /** @internal */
+    readonly maxParallelSubCalls: number;
+    /**
+     * Reserved presentation transport, kept outside the filterable registration
+     * layers. Built on first need rather than at construction: which agents run
+     * a code mode is no longer known when the service is constructed, and the
+     * transport is stateless beyond its closures over the runtime.
+     * @internal
+     */
+    codeTransport: ToolDefinition | undefined;
+    /** @internal Registry-normalized results and the exact dispatch that validated each value. */
+    readonly canonicalResults: WeakMap<object, ToolExecutionToken>;
+    constructor(ctx: Context, config?: Config);
+    /**
+     * 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 mode - the presentation the covered agents' models see.
+     * @returns the exact disposer that restores the deployment default.
+     */
+    presentAs(mode: ToolPresentationMode): () => void;
+    /**
+     * Register globally or in the calling agent scope. Scoped tools shadow
+     * globals; duplicates within one layer and the reserved `run_code` name fail.
+     * @param definition - tool schema, execution, and optional finalization/presentation callbacks.
+     * @returns the exact disposer that unregisters the tool.
+     */
+    register(definition: ToolDefinition): () => void;
+    /**
+     * 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 {@link ToolRuntime.get} and {@link ToolRuntime.schemas}
+     * (only registered definitions are visible). Duplicate reservations within one
+     * layer fail, matching the duplicate-name rule for {@link ToolRuntime.register}.
+     * @param name - the capability name to make known without presenting.
+     * @returns the exact disposer that clears the reservation.
+     */
+    reserve(name: string): () => void;
+    /**
+     * 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 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.
+     */
+    isAdmitted(name: string, scope?: ScopeKey): boolean;
+    /**
+     * 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 filter - global-tool mask: `allow` (keep only) and/or `deny` (remove).
+     * @returns the exact disposer that lifts this restriction.
+     */
+    restrict(filter: ToolRestriction): () => void;
+    /**
+     * 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 guard - synchronous check; a returned string denies the execution.
+     * @returns the exact disposer that unregisters the guard.
+     */
+    guard(guard: ToolGuard): () => void;
+    /**
+     * 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 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.
+     */
+    get(name: string, scope?: ScopeKey): ToolDefinition | undefined;
+    /**
+     * Project visible definitions onto the allowlisted model-facing schema fields,
+     * excluding execution and presentation callbacks.
+     * @param scope - the viewing scope (the agent); omitted = the global view.
+     * @returns one deep-cloned schema per visible tool.
+     */
+    schemas(scope?: ScopeKey): ToolSchema[];
+    /**
+     * 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 exec - call name, parsed arguments, and optional agent scope.
+     * @returns the fail-closed scheduling mode.
+     */
+    executionMode(exec: ToolExecutionInput): ToolExecutionMode;
+    /**
+     * Execute through pre-policy, guards, around-dispatch, post-policy,
+     * definition-owned content finalization, and final notification. Tool and
+     * listener failures resolve as materialized error results; an invisible tool
+     * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen
+     * snapshot final observers receive. Cancellation
+     * arriving after entry and before final result materialization skips a
+     * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a
+     * successful started outcome with `ABORTED`; already-started work is still
+     * drained and may retain a tool-owned structured error.
+     * @param exec - the typed same-process call input. The registry assigns its
+     *   correlation token before policy begins.
+     * @returns the materialized final result.
+     */
+    execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>;
+    /** @internal */
+    guardReason(exec: ToolExecution): string | undefined;
+    /** @internal */
+    view(scope?: ScopeKey): ToolView;
+    /** @internal */
+    resolveExecution(name: string, scope: ScopeKey | undefined, nested: boolean): ToolDefinition | undefined;
+    /** @internal */
+    collapseSection(): {
+        name: string;
+        order: number;
+        text: (context: {
+            scope?: ScopeKey;
+        }) => string;
+    };
+    /** @internal */
+    sdkSection(): {
+        name: string;
+        order: number;
+        text: (context: {
+            scope?: ScopeKey;
+        }) => string;
+    };
+    /** @internal */
+    modeFor(scope?: ScopeKey): ToolPresentationMode;
+    /** @internal */
+    wireSchemas(scope?: ScopeKey): ToolProviderResult;
+    /** @internal */
+    sdkSchemas(scope?: ScopeKey): ToolSdkSchema[];
+    /** @internal */
+    schemaOf(definition: ToolDefinition, detachParameters: boolean): ToolSchema;
+    /** @internal */
+    collapses(name: string, scope: ScopeKey | undefined, nested: boolean): boolean;
+    /** @internal */
+    completeScheduledExecution(prepared: ScheduledToolPreparation): Promise<ToolExecutionResult>;
+    /** @internal */
+    createExecution(exec: ToolExecutionInput): ScheduledToolPreparation | {
+        kind: 'ready';
+        exec: MutableToolRunContext;
+    };
+    /** @internal */
+    prepareScheduledExecution(input: ToolExecutionInput): Promise<ScheduledToolPreparation>;
+    /** @internal */
+    prepareExecution<T>(input: ToolExecutionInput, next: (prepared: ScheduledToolPreparation) => T | PromiseLike<T>): Promise<T>;
+    /** @internal */
+    callerCancelled(exec: ToolRunContext): boolean;
+    /** @internal */
+    cancellationResult(exec: ToolRunContext, prior?: ToolExecutionResult): ToolExecutionResult;
+    /** @internal */
+    dispatchToolBody(exec: MutableToolRunContext): Promise<ToolExecutionResult>;
+    /** @internal */
+    dispatchScheduledExecution(exec: ToolRunContext): Promise<ScheduledToolDispatch>;
+    /** @internal */
+    finalizeScheduledExecution(exec: ToolRunContext, result: ToolExecutionResult): Promise<ToolExecutionResult>;
+    /** @internal */
+    finishScheduledExecution(exec: ToolRunContext, result: ToolExecutionResult): ToolExecutionResult;
+    /** @internal */
+    applyFinalContent(exec: ToolRunContext, result: ToolExecutionResult): ToolExecutionResult;
+    /** @internal */
+    notifyResult(exec: ToolExecution, result: ToolExecutionResult): void;
+    /** @internal */
+    postExecute(exec: ToolExecution, result: ToolExecutionResult): Promise<ToolExecutionResult>;
+    /** @internal */
+    markCanonical<T extends ToolExecutionResult>(exec: ToolExecution, result: T): T;
+    /** @internal */
+    createSuccessResult(exec: ToolExecution, tool: ToolDefinition, candidate: unknown): ToolExecutionSuccess;
+    /** @internal */
+    normalizeDispatchResult(exec: ToolExecution, result: ToolExecutionResult): ToolExecutionResult;
+    /** @internal */
+    materializeFinalResult(result: ToolExecutionResult): ToolExecutionResult;
+    /** @internal */
+    requireCodeTransport(): ToolDefinition;
+    /** @internal */
+    requireCodeRuntime(mode: ToolPresentationMode): CodeRuntime;
+    /** @internal */
+    shapeDispatchLog(dispatch: CodeDispatchLog): Promise<ContentBlock[]>;
+    /** @internal */
+    serviceAsk(exec: ToolExecution, ask: Extract<PreToolDecision, {
+        kind: 'ask';
+    }>): Promise<ToolAskResolution>;
+}
+export default ToolRuntime;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

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

package/lib/index.js

@@ -0,0 +1,289 @@
+/**
+ * Tool registry, model presentation modes, and pre/guard/around/post/result
+ * execution pipeline.
+ * @module @dsh-cc/tools
+ */
+import { Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { ScopedLayers } from '@deepseek-ai/dsh-scope';
+import { TOOL_RUNTIME_SCHEDULER } from "./scheduler.js";
+import { ToolLayer, resolveMaxParallelSubCalls } from "./tool-layer.js";
+import { executionMode, get, guard as registerGuard, guardReason, isAdmitted, register, reserve, resolveExecution, restrict, view } from "./runtime-registry.js";
+import { collapses, collapseSection, modeFor, presentAs, schemaOf, schemas, sdkSchemas, sdkSection, wireSchemas } from "./runtime-schemas.js";
+import { applyFinalContent, callerCancelled, cancellationResult, completeScheduledExecution, createExecution, dispatchScheduledExecution, dispatchToolBody, execute, finalizeScheduledExecution, finishScheduledExecution, prepareExecution, prepareScheduledExecution } from "./runtime-execute.js";
+import { createSuccessResult, markCanonical, materializeFinalResult, normalizeDispatchResult, notifyResult, postExecute } from "./runtime-results.js";
+import { requireCodeRuntime, requireCodeTransport, serviceAsk, shapeDispatchLog } from "./runtime-code.js";
+export { defineTool, valueSchemaSpecToJsonSchema, parameterSchemaSpecToJsonSchema, validateArgs, ToolArgsError, } from "./schema.js";
+export { assertSupportedJsonSchema, assertObjectJsonSchema, validateJsonSchemaValue, JsonSchemaError, } from "./json-schema.js";
+export { CodeRunFailedError, RUN_CODE_NAME } from "./code-mode.js";
+export { CC_TO_HARNESS_TOOLS, KNOWN_HARNESS_TOOLS, translateToolNames, ccToolAliases, ccCanonicalToolName, } from "./cc-names.js";
+export { jsonSchemaToTs, renderToolsSdk } from "./ts-types.js";
+export { jsonSchemaToPy, renderToolsSdkPy } from "./py-types.js";
+export { defineContentToolFixture } from "./testing.js";
+export { TOOL_ABORTED, TOOL_ABORTED_BEFORE_DISPATCH, ToolNotFoundError, ToolOutputError } from "./abort-utils.js";
+/**
+ * Scheduler entry point omitted from the generated named service API.
+ * The value MUST be the upstream symbol instance: the in-box agent loop reads
+ * the staged scheduler off the registry through the symbol exported by
+ * `@deepseek-ai/dsh-tools`, and a `Symbol()` is identity-unique — minting a
+ * private one here leaves the loop reading `undefined` and crashing every
+ * turn's first tool call (`undefined.prepare`). The binding is a type-erased
+ * `createRequire` rather than a static import so upstream's declaration graph
+ * (its own `Context` augmentation, whose vendored copy this package also
+ * ships) never enters downstream type programs; the dependency stays
+ * runtime-only (peer-declared). Declared in the {@link ./scheduler.ts} leaf
+ * module; re-exported here to keep the public barrel surface unchanged.
+ * @internal
+ */
+export { TOOL_RUNTIME_SCHEDULER };
+/**
+ * Tool registry and execution pipeline. Scoped registrations shadow globals;
+ * one visibility resolver feeds presentation, lookup, and dispatch.
+ *
+ * The implementation lives in the `runtime-*.ts` collaborator modules behind
+ * the `ToolRuntimeCore` structural interface; this class is the constructed
+ * facade — configuration, state fields, scheduler staging, and one-line
+ * delegations.
+ */
+export class ToolRuntime extends Service {
+    static inject = ['systemPrompt'];
+    static Config = z.object({
+        mode: z.union(['native', 'code', 'both']).default('native'),
+        maxParallelSubCalls: z.natural().min(1).default(10),
+    });
+    /** Internal staged view consumed by `dsh-agent-loop`'s parallel scheduler. */
+    [TOOL_RUNTIME_SCHEDULER] = {
+        prepare: exec => this.prepareScheduledExecution(exec),
+        dispatch: exec => this.dispatchScheduledExecution(exec),
+        finalize: (exec, result) => this.finalizeScheduledExecution(exec, result),
+        finish: (exec, result) => this.finishScheduledExecution(exec, result),
+    };
+    /** @internal Context deferred by a running tool body, keyed by its scheduler-owned execution. */
+    deferredContexts = new WeakMap();
+    /** @internal Executions whose tool body declared the current turn complete. */
+    concludingExecutions = new WeakSet();
+    /** @internal Original caller cancellation, kept outside the wrapper-mutable execution object. */
+    cancellationStates = new WeakMap();
+    /** @internal Definition-owned final content transform snapshotted before policy begins. */
+    contentFinalizers = new WeakMap();
+    /** @internal Visibility layers: registration, reservation, restriction, guards. */
+    layers = new ScopedLayers(scope => new ToolLayer(scope), () => { this.ctx.emit('tools/change'); });
+    /** @internal Presentation for scopes that declare none; {@link modeFor} shadows it per scope. */
+    defaultMode;
+    /** @internal */
+    maxParallelSubCalls;
+    /**
+     * Reserved presentation transport, kept outside the filterable registration
+     * layers. Built on first need rather than at construction: which agents run
+     * a code mode is no longer known when the service is constructed, and the
+     * transport is stateless beyond its closures over the runtime.
+     * @internal
+     */
+    codeTransport;
+    /** @internal Registry-normalized results and the exact dispatch that validated each value. */
+    canonicalResults = new WeakMap();
+    constructor(ctx, config = {}) {
+        super(ctx, 'tools');
+        // The schema already defaulted an omitted mode; the ?? narrows the
+        // optional-input type for direct (non-Loader) construction in tests.
+        this.defaultMode = config.mode ?? 'native';
+        this.maxParallelSubCalls = resolveMaxParallelSubCalls(config.maxParallelSubCalls);
+        ctx.systemPrompt.tools(context => this.wireSchemas(context.scope));
+        if (this.defaultMode !== 'native') {
+            ctx.systemPrompt.section(this.collapseSection());
+            ctx.systemPrompt.section(this.sdkSection());
+        }
+    }
+    /**
+     * 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 mode - the presentation the covered agents' models see.
+     * @returns the exact disposer that restores the deployment default.
+     */
+    presentAs(mode) {
+        return presentAs(this, mode);
+    }
+    /**
+     * Register globally or in the calling agent scope. Scoped tools shadow
+     * globals; duplicates within one layer and the reserved `run_code` name fail.
+     * @param definition - tool schema, execution, and optional finalization/presentation callbacks.
+     * @returns the exact disposer that unregisters the tool.
+     */
+    register(definition) {
+        return register(this, definition);
+    }
+    /**
+     * 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 {@link ToolRuntime.get} and {@link ToolRuntime.schemas}
+     * (only registered definitions are visible). Duplicate reservations within one
+     * layer fail, matching the duplicate-name rule for {@link ToolRuntime.register}.
+     * @param name - the capability name to make known without presenting.
+     * @returns the exact disposer that clears the reservation.
+     */
+    reserve(name) {
+        return reserve(this, name);
+    }
+    /**
+     * 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 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.
+     */
+    isAdmitted(name, scope) {
+        return isAdmitted(this, name, scope);
+    }
+    /**
+     * 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 filter - global-tool mask: `allow` (keep only) and/or `deny` (remove).
+     * @returns the exact disposer that lifts this restriction.
+     */
+    restrict(filter) {
+        return restrict(this, filter);
+    }
+    /**
+     * 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 guard - synchronous check; a returned string denies the execution.
+     * @returns the exact disposer that unregisters the guard.
+     */
+    guard(guard) {
+        return registerGuard(this, guard);
+    }
+    /**
+     * 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 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.
+     */
+    get(name, scope) {
+        return get(this, name, scope);
+    }
+    /**
+     * Project visible definitions onto the allowlisted model-facing schema fields,
+     * excluding execution and presentation callbacks.
+     * @param scope - the viewing scope (the agent); omitted = the global view.
+     * @returns one deep-cloned schema per visible tool.
+     */
+    schemas(scope) {
+        return schemas(this, scope);
+    }
+    /**
+     * 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 exec - call name, parsed arguments, and optional agent scope.
+     * @returns the fail-closed scheduling mode.
+     */
+    executionMode(exec) {
+        return executionMode(this, exec);
+    }
+    /**
+     * Execute through pre-policy, guards, around-dispatch, post-policy,
+     * definition-owned content finalization, and final notification. Tool and
+     * listener failures resolve as materialized error results; an invisible tool
+     * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen
+     * snapshot final observers receive. Cancellation
+     * arriving after entry and before final result materialization skips a
+     * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a
+     * successful started outcome with `ABORTED`; already-started work is still
+     * drained and may retain a tool-owned structured error.
+     * @param exec - the typed same-process call input. The registry assigns its
+     *   correlation token before policy begins.
+     * @returns the materialized final result.
+     */
+    async execute(exec) {
+        return execute(this, exec);
+    }
+    /** @internal */
+    guardReason(exec) { return guardReason(this, exec); }
+    /** @internal */
+    view(scope) { return view(this, scope); }
+    /** @internal */
+    resolveExecution(name, scope, nested) { return resolveExecution(this, name, scope, nested); }
+    /** @internal */
+    collapseSection() { return collapseSection(this); }
+    /** @internal */
+    sdkSection() { return sdkSection(this); }
+    /** @internal */
+    modeFor(scope) { return modeFor(this, scope); }
+    /** @internal */
+    wireSchemas(scope) { return wireSchemas(this, scope); }
+    /** @internal */
+    sdkSchemas(scope) { return sdkSchemas(this, scope); }
+    /** @internal */
+    schemaOf(definition, detachParameters) { return schemaOf(this, definition, detachParameters); }
+    /** @internal */
+    collapses(name, scope, nested) { return collapses(this, name, scope, nested); }
+    /** @internal */
+    completeScheduledExecution(prepared) { return completeScheduledExecution(this, prepared); }
+    /** @internal */
+    createExecution(exec) { return createExecution(this, exec); }
+    /** @internal */
+    prepareScheduledExecution(input) { return prepareScheduledExecution(this, input); }
+    /** @internal */
+    prepareExecution(input, next) {
+        return prepareExecution(this, input, next);
+    }
+    /** @internal */
+    callerCancelled(exec) { return callerCancelled(this, exec); }
+    /** @internal */
+    cancellationResult(exec, prior) { return cancellationResult(this, exec, prior); }
+    /** @internal */
+    dispatchToolBody(exec) { return dispatchToolBody(this, exec); }
+    /** @internal */
+    dispatchScheduledExecution(exec) { return dispatchScheduledExecution(this, exec); }
+    /** @internal */
+    finalizeScheduledExecution(exec, result) { return finalizeScheduledExecution(this, exec, result); }
+    /** @internal */
+    finishScheduledExecution(exec, result) { return finishScheduledExecution(this, exec, result); }
+    /** @internal */
+    applyFinalContent(exec, result) { return applyFinalContent(this, exec, result); }
+    /** @internal */
+    notifyResult(exec, result) { return notifyResult(this, exec, result); }
+    /** @internal */
+    postExecute(exec, result) { return postExecute(this, exec, result); }
+    /** @internal */
+    markCanonical(exec, result) { return markCanonical(this, exec, result); }
+    /** @internal */
+    createSuccessResult(exec, tool, candidate) { return createSuccessResult(this, exec, tool, candidate); }
+    /** @internal */
+    normalizeDispatchResult(exec, result) { return normalizeDispatchResult(this, exec, result); }
+    /** @internal */
+    materializeFinalResult(result) { return materializeFinalResult(this, result); }
+    /** @internal */
+    requireCodeTransport() { return requireCodeTransport(this); }
+    /** @internal */
+    requireCodeRuntime(mode) { return requireCodeRuntime(this, mode); }
+    /** @internal */
+    shapeDispatchLog(dispatch) { return shapeDispatchLog(this, dispatch); }
+    /** @internal */
+    serviceAsk(exec, ask) { return serviceAsk(this, exec, ask); }
+}
+export default ToolRuntime;
+//# sourceMappingURL=index.js.map