@dsh-cc/tools 0.5.0

package/lib/tool-layer.js

@@ -0,0 +1,57 @@
+/**
+ * One scope's tool-registry contribution: visibility, reservations,
+ * restrictions, guards, and per-scope presentation shadowing.
+ * @module tool-layer
+ */
+import { AnonymousEntries, NamedEntries } from '@deepseek-ai/dsh-scope';
+/** One scope's complete tool-registry contribution. */
+export class ToolLayer {
+    tools;
+    /** Known-but-invisible capability names, so a scoped restriction can gate a tool before it loads. */
+    reserved = new NamedEntries(name => new Error(`tool name "${name}" is already reserved in this scope`));
+    restrictions = new AnonymousEntries();
+    guards = new AnonymousEntries();
+    /**
+     * Presentation this scope's agent declared for itself, shadowing the
+     * deployment default. One cell rather than an entry table: two answers to
+     * "which form does the model see" is a contradiction, not a merge.
+     */
+    mode;
+    constructor(scope) {
+        this.tools = new NamedEntries(name => new Error(scope === undefined
+            ? `tool "${name}" is already registered (for a per-agent variant, register through that agent's \`agent.ctx\` instead)`
+            : `tool "${name}" is already registered in this scope`));
+    }
+    /** Whether every contribution table in this aggregate layer is empty. */
+    isEmpty() {
+        return this.tools.isEmpty() && this.reserved.isEmpty() && this.restrictions.isEmpty()
+            && this.guards.isEmpty() && this.mode === undefined;
+    }
+    /** Whether every compiled restriction in this layer admits a global tool name. */
+    admits(name) {
+        for (const filter of this.restrictions.values()) {
+            if ((filter.allow !== undefined && !filter.allow.has(name))
+                || (filter.deny !== undefined && filter.deny.has(name)))
+                return false;
+        }
+        return true;
+    }
+    /** First monotonic denial from this layer's live guard registrations. */
+    guardReason(exec) {
+        for (const guard of this.guards.values()) {
+            const reason = guard(exec);
+            if (reason !== undefined)
+                return reason;
+        }
+        return undefined;
+    }
+}
+/** Resolve the run_code overlap cap at the owning config boundary (direct construction bypasses the Loader schema). */
+export function resolveMaxParallelSubCalls(value) {
+    const maxParallelSubCalls = value ?? 10;
+    if (!Number.isInteger(maxParallelSubCalls) || maxParallelSubCalls < 1) {
+        throw new Error('maxParallelSubCalls must be a positive integer');
+    }
+    return maxParallelSubCalls;
+}
+//# sourceMappingURL=tool-layer.js.map

package/lib/tool-layer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-layer.js","sourceRoot":"","sources":["../src/tool-layer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAIvE,uDAAuD;AACvD,MAAM,OAAO,SAAS;IACX,KAAK,CAA8B;IAC5C,qGAAqG;IAC5F,QAAQ,GAAG,IAAI,YAAY,CAAY,IAAI,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC,cAAc,IAAI,qCAAqC,CAAC,CAAC,CAAA;IAClH,YAAY,GAAG,IAAI,gBAAgB,EAA2B,CAAA;IAC9D,MAAM,GAAG,IAAI,gBAAgB,EAAa,CAAA;IACnD;;;;OAIG;IACH,IAAI,CAAkC;IAEtC,YAAY,KAA2B;QACrC,IAAI,CAAC,KAAK,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;YACjE,CAAC,CAAC,SAAS,IAAI,wGAAwG;YACvH,CAAC,CAAC,SAAS,IAAI,uCAAuC,CAAC,CAAC,CAAA;IAC5D,CAAC;IAED,yEAAyE;IACzE,OAAO;QACL,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE;eAChF,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,CAAA;IACvD,CAAC;IAED,kFAAkF;IAClF,MAAM,CAAC,IAAY;QACjB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,EAAE,CAAC;YAChD,IAAI,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;mBACtD,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAA;QACzE,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,yEAAyE;IACzE,WAAW,CAAC,IAAmB;QAC7B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACzC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,CAAA;YAC1B,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,MAAM,CAAA;QACzC,CAAC;QACD,OAAO,SAAS,CAAA;IAClB,CAAC;CACF;AAoBD,uHAAuH;AACvH,MAAM,UAAU,0BAA0B,CAAC,KAAyB;IAClE,MAAM,mBAAmB,GAAG,KAAK,IAAI,EAAE,CAAA;IACvC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,mBAAmB,CAAC,IAAI,mBAAmB,GAAG,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAA;IACnE,CAAC;IACD,OAAO,mBAAmB,CAAA;AAC5B,CAAC"}

package/lib/tool-types.d.ts

@@ -0,0 +1,385 @@
+/**
+ * Public tool type vocabulary: definitions, results, execution contexts,
+ * scheduler contracts, restriction/config shapes, and value projection
+ * helpers shared by the registry and its pipeline.
+ * @module tool-types
+ */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { CallId, ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm';
+import type { JsonValue, UserMessage } from '@deepseek-ai/dsh-session';
+import type { ToolCallView, ToolResultView } from './presentation.ts';
+import type { ToolFailure } from './abort-utils.ts';
+import type { JsonSchemaNode } from './json-schema.ts';
+/** Tool-owned canonical output contract used after the body returns a JSON value. */
+export interface ToolOutputDefinition {
+    /** Raw supported JSON Schema enforced against every successful canonical value. */
+    readonly schema: JsonSchemaNode;
+    /** Pure projection from validated arguments and value to Native/model content. */
+    render(args: unknown, value: JsonValue): ContentBlock[];
+    /** Pure replayable presentation projection, computed only for top-level calls. */
+    presentationMeta?(args: unknown, value: JsonValue): JsonValue;
+}
+/** A registered tool: its schema plus the execution function. */
+export interface ToolDefinition extends ToolSchema {
+    /** Mandatory canonical output declaration. */
+    readonly output: ToolOutputDefinition;
+    /**
+     * Run one accepted call and return only its canonical lossless-JSON value.
+     * Async work must observe or forward `exec.signal` and settle only after its
+     * owned work reaches quiescence. The registry preserves caller cancellation
+     * through around-dispatch signal replacement and does not abandon this
+     * promise, but it cannot hard-kill same-process code.
+     * @param args - losslessly snapshotted, frozen model arguments.
+     * @param exec - execution identity, cancellation signal, and context deferral.
+     * @returns the canonical value declared by `output.schema`.
+     */
+    execute(args: unknown, exec: ToolRunContext): Promise<unknown>;
+    /**
+     * Synchronous last-mile transform for model-facing content. The registry
+     * snapshots this callback when execution starts and invokes it exactly once
+     * for every normalized outcome, including pipeline failures that bypass
+     * `tools/post-execute`, immediately before lossless materialization.
+     * Returning `undefined` preserves the content; every other result field
+     * remains registry-owned. The callback must be total and must not throw.
+     * @param exec - immutable execution identity and arguments.
+     * @param result - complete normalized outcome before materialization.
+     * @returns replacement content, or `undefined` to preserve it.
+     */
+    finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined;
+    /**
+     * Cooperative tool-call timeout budget in milliseconds. Omit for no deadline.
+     * Enforced by `@deepseek-ai/dsh-tool-call-timeout-policy` (a `tools/execute` wrapper); it
+     * is NEVER sent to the model — `schemas()` whitelists only name/description/
+     * parameters. Declaring it asserts this tool forwards `exec.signal` to a
+     * cooperative implementation that can reach quiescence when the signal aborts.
+     */
+    timeoutMs?: number;
+    /**
+     * Pure synchronous classifier for overlap with sibling tool calls. Only
+     * `true` opts in; omission, exceptions, non-`true` returns, and invalid
+     * `defineTool` arguments are exclusive. This metadata is never model-visible.
+     *
+     * Opted-in executions must not mutate parent-owned state. Shared state must
+     * tolerate concurrent dispatch; recorder races are permitted only when they
+     * commute or fail closed. See the
+     * [parallel-tool-call Agent Note](../../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)
+     * for the full contract.
+     * @param args - parsed arguments; `defineTool` validates before calling.
+     * @returns Whether this call may join a parallel group.
+     */
+    isConcurrencySafe?(args: unknown): boolean;
+    /**
+     * Optional: how to present the PENDING state of one call in a UI, derived from
+     * the call's `args` (parsed arguments, `unknown` — the tool validates/narrows
+     * its own input). Returns a {@link ToolCallView} (a `card`-tagged render intent),
+     * or `undefined` (or omit the method) to fall back to a generic presentation
+     * (title = tool name, raw args as input). Pure and side-effect-free: a UI may
+     * call it during live streaming AND a session-log replay, so it must depend
+     * only on `args`.
+     */
+    presentCall?(args: unknown): ToolCallView | undefined;
+    /**
+     * Optional: how to present the COMPLETED state, given the same `args` and the
+     * durable result projection (`content`, failure state, and optional `meta`). Returns a
+     * {@link ToolResultView}, or `undefined` (or omit the method) to keep the
+     * pending title and render the raw result content. Pure and side-effect-free
+     * for the same replay reason.
+     */
+    presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;
+}
+/** The completed outcome handed to {@link ToolDefinition.presentResult}. */
+export interface ToolResult {
+    /** The final model-facing content (or the rendered error text on failure). */
+    content: ContentBlock[];
+    /** Whether the call failed. */
+    isError: boolean;
+    /**
+     * The tool-private presentation payload projected by its output declaration
+     * and threaded verbatim from the `tool/result` event. Absent when the tool
+     * declared no projector or the call was nested under a composite transport.
+     */
+    meta?: JsonValue;
+}
+declare const toolExecutionTokenBrand: unique symbol;
+/** Opaque call identity that permits correlation without exposing mutable execution state. */
+export type ToolExecutionToken = symbol & {
+    readonly [toolExecutionTokenBrand]: true;
+};
+/**
+ * Caller-supplied description of one tool call. {@link ToolRuntime.execute}
+ * adds the registry-owned token to form a pipeline {@link ToolExecution};
+ * callers do not choose that token.
+ */
+export interface ToolExecutionInput {
+    readonly callId: CallId;
+    /**
+     * Root model-requested call owning this execution tree. Callers omit it for
+     * a root execution; nested dispatchers propagate the enclosing value.
+     */
+    readonly rootCallId?: CallId;
+    readonly name: string;
+    /** Losslessly JSON-serializable parsed arguments (tools validate their own schema). */
+    readonly arguments: unknown;
+    /** The agent on whose behalf the call runs (set by the agent loop). */
+    readonly agent?: Agent;
+    /**
+     * Opaque token of the enclosing transport execution, when one exists. Code
+     * Mode sets this on SDK sub-dispatches so commit-style observers can wait for
+     * the outer `run_code` outcome without receiving its live mutable execution.
+     * The token also marks the call as a transport sub-dispatch rather than a
+     * model-direct call: under `mode: 'code'`, only calls WITH a parent may
+     * execute a native tool name — a model-direct call (no parent) is denied as
+     * `UNKNOWN_TOOL` before the policy pipeline. See {@link ToolRuntime.execute}.
+     */
+    readonly parent?: ToolExecutionToken;
+    /** Required caller-owned cancellation for this invocation. */
+    readonly signal: AbortSignal;
+}
+/**
+ * Scheduling mode for one pending call. `parallel` may overlap with siblings;
+ * `exclusive` runs alone and forms an ordering barrier.
+ */
+export type ToolExecutionMode = {
+    kind: 'parallel';
+} | {
+    kind: 'exclusive';
+};
+/**
+ * One settled `run_code` sub-dispatch about to be logged, as seen by the
+ * `tools/code-dispatch-log` waterfall: the parent execution (session owner,
+ * outer call identity), the sub-call identity, and the outcome whose durable
+ * copy a listener may reshape. `content` is the RENDERED result projection
+ * (what a native `tool/result` would carry) — the program itself received
+ * the structured `value` (or just the error message on failure); only the
+ * `tool/code-dispatch` event's copy changes.
+ */
+export interface CodeDispatchLog {
+    /** The outer `run_code` execution. */
+    readonly exec: ToolExecution;
+    /** The calling agent (the scope routing key and the spill owner), when the outer call has one. */
+    readonly agent?: Agent;
+    /** Deterministic sub-call id (`<parent>:code:<n>`). */
+    readonly subCallId: CallId;
+    /** The dispatched sub-tool name. */
+    readonly name: string;
+    /** Whether the sub-call settled as an error. */
+    readonly isError: boolean;
+    /** The sub-call's complete model-facing content (the settle event's default payload). */
+    readonly content: ContentBlock[];
+}
+/**
+ * One pending tool call inside the registry pipeline. Parsed arguments cross
+ * one lossless-JSON materialization boundary before policy and are deep-frozen;
+ * call identity, the caller signal, and the registry-assigned {@link token} are
+ * readonly. The registry freezes the complete object before `tools/result`
+ * observers run.
+ */
+export interface ToolExecution extends ToolExecutionInput {
+    /** Root model-requested call, resolved for every root and nested execution. */
+    readonly rootCallId: CallId;
+    /** Registry-assigned identity shared with nested calls only as their opaque `parent` token. */
+    readonly token: ToolExecutionToken;
+}
+/**
+ * Around-dispatch view of a {@link ToolExecution}. A `tools/execute` wrapper
+ * may replace the signal for its delegated lifetime, but it cannot remove it.
+ * The registry fuses every replacement with the captured caller signal.
+ */
+export interface ToolDispatchExecution extends Omit<ToolExecution, 'signal'> {
+    /** Cancellation signal visible to the next wrapper or tool body. */
+    signal: AbortSignal;
+}
+/**
+ * Runtime context handed to a tool implementation after the registry has
+ * accepted a {@link ToolExecution}. {@link deferContext} attaches context to
+ * this execution's own result — a composite tool ferries nested-dispatch
+ * context back to the outer result, and a leaf tool may mint a fresh
+ * plugin-sourced instruction; the loop appends it only after the
+ * `tool/result`.
+ */
+export interface ToolRunContext extends ToolExecution {
+    /**
+     * Defer one context — typically a nested-dispatch context ferried by a
+     * composite tool, or a fresh plugin-sourced instruction — until this tool's
+     * final result reaches the agent loop. Contexts retain their individual
+     * source and metadata and are emitted in call order.
+     */
+    deferContext(context: UserMessage): void;
+    /**
+     * Mark a successful final result as terminal for the current agent turn.
+     * The marker rides this execution's own result (`concludesTurn` exists only
+     * on {@link ToolExecutionSuccess}); a composite that dispatches nested
+     * calls forwards it from the nested result, exactly like
+     * `additionalContexts`, so only an authoritative nested success can
+     * conclude the enclosing run.
+     */
+    concludeTurn(): void;
+}
+/** Registry-owned live execution object; public pipeline views stay readonly. */
+export type MutableToolRunContext = Omit<ToolRunContext, 'signal'> & {
+    signal: AbortSignal;
+};
+/**
+ * Scheduler-only result after ordered pre-execute and guards. A `post-result`
+ * still receives post-execute; a `final-result` bypasses it.
+ * @internal
+ */
+export type ScheduledToolPreparation = {
+    kind: 'dispatch';
+    exec: ToolRunContext;
+} | {
+    kind: 'post-result';
+    exec: ToolRunContext;
+    result: ToolExecutionResult;
+} | {
+    kind: 'final-result';
+    exec: ToolRunContext;
+    result: ToolExecutionResult;
+};
+/**
+ * Scheduler-only dispatch result. A `post-result` still receives post-execute;
+ * a `final-result` already matches {@link ToolRuntime.execute} failure semantics.
+ * @internal
+ */
+export type ScheduledToolDispatch = {
+    kind: 'post-result';
+    result: ToolExecutionResult;
+} | {
+    kind: 'final-result';
+    result: ToolExecutionResult;
+};
+/**
+ * Symbol-keyed scheduler view that keeps pre/post policy ordered while
+ * overlapping dispatch. Ordinary callers use {@link ToolRuntime.execute};
+ * this is not a plugin extension point.
+ * @internal
+ */
+export interface ToolRuntimeScheduler {
+    /** Materialize input, run the ordered pre-execute/guard gate, and decide what stage follows. */
+    prepare(exec: ToolExecutionInput): Promise<ScheduledToolPreparation>;
+    /** Run only the around-dispatch/body stage. */
+    dispatch(exec: ToolRunContext): Promise<ScheduledToolDispatch>;
+    /** Run post-execute and definition-owned content finalization, then materialize and notify. */
+    finalize(exec: ToolRunContext, result: ToolExecutionResult): Promise<ToolExecutionResult>;
+    /** Run definition-owned content finalization, then materialize and notify without post-execute. */
+    finish(exec: ToolRunContext, result: ToolExecutionResult): ToolExecutionResult;
+}
+/** Successful canonical tool execution, including its Native/model projection. */
+export interface ToolExecutionSuccess {
+    readonly isError: false;
+    /** Execution-local canonical value; deliberately omitted from durable events. */
+    readonly value: JsonValue;
+    readonly content: ContentBlock[];
+    readonly error?: never;
+    readonly meta?: JsonValue;
+    readonly additionalContexts?: UserMessage[];
+    /** The agent loop stops after committing this successful result batch. */
+    readonly concludesTurn?: true;
+}
+/** Failed canonical tool execution; failures never carry a successful value. */
+export interface ToolExecutionFailure {
+    readonly isError: true;
+    readonly error: ToolFailure;
+    readonly value?: never;
+    readonly content: ContentBlock[];
+    readonly meta?: JsonValue;
+    readonly additionalContexts?: UserMessage[];
+    readonly concludesTurn?: never;
+}
+/** The discriminated, execution-local outcome of one tool call. */
+export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;
+/**
+ * Pre-dispatch decision. `allow` runs the call; `deny` materializes an error;
+ * `ask` runs only after an approval service returns `allowed-once` and otherwise
+ * denies. Input rewriting is excluded because arguments are already logged and
+ * presented.
+ */
+export type PreToolDecision = {
+    kind: 'allow';
+} | {
+    kind: 'deny';
+    reason: string;
+} | {
+    kind: 'ask';
+    reason?: string;
+};
+/**
+ * Post-dispatch decision: accept, replace one projection, attach context for the
+ * next request, or block by turning corrective feedback into an error result.
+ */
+export type PostToolDecision = {
+    kind: 'accept';
+    content?: ContentBlock[];
+    value?: never;
+    additionalContexts?: UserMessage[];
+} | {
+    kind: 'accept';
+    value: JsonValue;
+    content?: never;
+    additionalContexts?: UserMessage[];
+} | {
+    kind: 'block';
+    feedback: ContentBlock[];
+    additionalContexts?: UserMessage[];
+};
+/** Snapshot and freeze one durable tool-result projection or reject lossy data. */
+export declare function materializePresentation<T>(candidate: T): T;
+/** How the registry presents its tools to the model (see {@link Config.mode}). */
+export type ToolPresentationMode = 'native' | 'code' | 'both';
+/** Plugin config: how the registered tools are presented to the model. */
+export interface Config {
+    /**
+     * Model presentation. `native` (default) sends every visible schema; `code`
+     * sends only `run_code` plus a generated SDK prompt and collapses the
+     * executor to the same surface (a model-direct call may only name
+     * `run_code`; `run_code` SDK sub-dispatches keep every visible tool); `both`
+     * sends both forms. Code modes require a `ctx.codeRuntime` whose `language`
+     * has a registered SDK renderer (TypeScript or Python) and fail prompt
+     * assembly when it is absent or has no renderer. Under `code`, native names
+     * in `toolOrder` are invalid.
+     */
+    mode?: ToolPresentationMode;
+    /**
+     * Concurrency cap for a `run_code` program's overlapping sub-calls
+     * (default 10, the loop scheduler's own default). Sub-calls follow the
+     * native scheduling contract — only calls whose tools classify
+     * concurrency-safe overlap; exclusive calls form barriers — so `1`
+     * restores strictly serial dispatch. Must be a positive integer.
+     */
+    maxParallelSubCalls?: number;
+}
+/**
+ * Per-scope filter over global tools. Restrictions intersect and do not affect
+ * scoped registrations or the reserved Code Mode transport.
+ */
+export interface ToolRestriction {
+    /** Global tool names that stay visible; everything else is removed. */
+    readonly allow?: readonly string[];
+    /** Global tool names removed from visibility. */
+    readonly deny?: readonly string[];
+}
+/** One restriction compiled at registration for repeated live-global lookup. */
+export interface CompiledToolRestriction {
+    readonly allow?: ReadonlySet<string>;
+    readonly deny?: ReadonlySet<string>;
+}
+/** One scope's complete registry view, derived in a single layer traversal. */
+export interface ToolView {
+    /** Visible definitions after restrictions, scoped shadowing, and transport insertion. */
+    readonly visible: ReadonlyMap<string, ToolDefinition>;
+    /** Pre-restriction capability names used by prompt-order validation. */
+    readonly knownNames: ReadonlySet<string>;
+    /** Current global names that a scoped restriction may name. */
+    readonly restrictableNames: ReadonlySet<string>;
+}
+/**
+ * A monotonic execution guard evaluated after every `tools/pre-execute`
+ * listener and before the tool body. Returning a reason denies the call;
+ * returning `undefined` leaves it unchanged. Because guards have no allow
+ * result, listener ordering cannot turn a denial back into permission.
+ * @param execution - the identity-protected call after extensible pre-execute policy completed.
+ * @returns a final denial reason, or `undefined` to leave the call allowed.
+ */
+export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined;
+export {};
+//# sourceMappingURL=tool-types.d.ts.map

package/lib/tool-types.d.ts.map

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

package/lib/tool-types.js

@@ -0,0 +1,11 @@
+import { deepFreeze } from '@deepseek-ai/dsh-llm';
+import { snapshotJsonValue } from '@deepseek-ai/dsh-session';
+/** Snapshot and freeze one durable tool-result projection or reject lossy data. */
+export function materializePresentation(candidate) {
+    const detached = snapshotJsonValue(candidate);
+    if (detached === undefined) {
+        throw new TypeError('tool result must be losslessly JSON-serializable');
+    }
+    return deepFreeze(detached);
+}
+//# sourceMappingURL=tool-types.js.map

package/lib/tool-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-types.js","sourceRoot":"","sources":["../src/tool-types.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AA+S5D,mFAAmF;AACnF,MAAM,UAAU,uBAAuB,CAAI,SAAY;IACrD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAA;IAC7C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,IAAI,SAAS,CAAC,kDAAkD,CAAC,CAAA;IACzE,CAAC;IACD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAA;AAC7B,CAAC"}

package/lib/ts-types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Code Mode codegen: the pure projection from registered tool schemas to the TypeScript SDK
+ * text the model programs against (the `tools:sdk` prompt section). Sibling of
+ * `json-schema.ts` — `schemas()` (native function calling) and this module (the generated
+ * `declare const tools` API) are two projections of the same store.
+ * @module @dsh-cc/tools/src/ts-types
+ */
+import type { ToolSchema } from '@deepseek-ai/dsh-llm';
+import type { JsonSchemaNode } from './json-schema.ts';
+/** Internal Code Mode projection: the model-facing schema plus the canonical output schema. */
+export interface ToolSdkSchema extends ToolSchema {
+    /** Validated canonical value returned by the tool binding. */
+    output: JsonSchemaNode;
+}
+/**
+ * Map one enforced JSON-Schema node to a TypeScript type literal. Supports
+ * every unified schema construct and returns `unknown` for malformed or
+ * unsupported inputs without throwing.
+ * @param schema - the JSON-Schema node (any shape; hostile inputs degrade).
+ * @param indent - the indentation level for nested object members.
+ * @returns the TS type text (multi-line for objects with properties).
+ */
+export declare function jsonSchemaToTs(schema: unknown, indent?: number): string;
+/**
+ * Render the full `tools:sdk` prompt section: the fixed usage instructions
+ * plus one `declare const tools` interface covering every given tool.
+ * Deterministic — tools are emitted in lexicographic name order, so an
+ * unchanged tool set produces byte-identical text across assemblies. The sort
+ * is not a total order on byte-equal names, so two schemas sharing a name
+ * would render in argument order; the caller's visible-capability map is keyed
+ * by name, so the input never carries a duplicate.
+ * @param schemas - the tool schemas to declare (the caller excludes
+ *   `run_code` itself).
+ * @returns the complete section text.
+ */
+export declare function renderToolsSdk(schemas: ToolSdkSchema[]): string;
+//# sourceMappingURL=ts-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ts-types.d.ts","sourceRoot":"","sources":["../src/ts-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAoB,MAAM,kBAAkB,CAAA;AACxE,+FAA+F;AAC/F,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C,8DAA8D;IAC9D,MAAM,EAAE,cAAc,CAAA;CACvB;AAwND;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,SAAI,GAAG,MAAM,CAOlE;AAcD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,MAAM,CAoB/D"}