@dsh-cc/tools 0.5.0

package/lib/ts-types.js

@@ -0,0 +1,265 @@
+/**
+ * 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 { assertSupportedJsonSchema } from "./json-schema.js";
+/** Property names that are valid bare TS identifiers; anything else is quoted. */
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** Render an object key: bare when it is a valid identifier, quoted otherwise (every name stays reachable, no aliasing). */
+function renderKey(name) {
+    return IDENTIFIER.test(name) ? name : JSON.stringify(name);
+}
+/** One `indent`-deep line prefix (two spaces per level). */
+function pad(indent) {
+    return '  '.repeat(indent);
+}
+/** A one-line JSDoc block for a schema `description`, or no lines when there is none. */
+function docLines(description, indent) {
+    if (typeof description !== 'string' || description.length === 0)
+        return [];
+    // Collapse prose to stable one-line docs and escape comment closers so a
+    // schema description cannot terminate generated JSDoc.
+    const collapsed = description.replace(/\s+/g, ' ').trim();
+    return [`${pad(indent)}/** ${collapsed.replaceAll('*/', String.raw `*\/`)} */`];
+}
+/** Render one scalar already validated by the unified schema boundary. */
+function renderScalar(value) {
+    return JSON.stringify(value);
+}
+/** Render a validated scalar `const`/`enum`, falling back to the broad type. */
+function renderConstrainedScalar(node, type) {
+    const broad = type === 'integer' ? 'number' : type;
+    if (Object.hasOwn(node, 'const'))
+        return renderScalar(node.const);
+    if (Object.hasOwn(node, 'enum')) {
+        return node.enum.map(renderScalar).join(' | ');
+    }
+    return broad;
+}
+/** Build one document from captured parts while retaining the legacy array-parenthesization test. */
+function typeDocumentFrom(parts) {
+    return {
+        parts,
+        containsUnionOrIntersection: parts.some(part => typeof part === 'string'
+            ? part.includes('|') || part.includes('&')
+            : part.containsUnionOrIntersection),
+    };
+}
+/** Build a small document without an intermediate array at each call site. */
+function typeDocument(...parts) {
+    return typeDocumentFrom(parts);
+}
+/** Flatten a nested document with an explicit work stack. */
+function flattenTypeDocument(document) {
+    const chunks = [];
+    const tasks = [document];
+    for (let task = tasks.pop(); task !== undefined; task = tasks.pop()) {
+        if (typeof task === 'string') {
+            chunks.push(task);
+            continue;
+        }
+        for (let index = task.parts.length - 1; index >= 0; index--) {
+            const part = task.parts[index];
+            /* v8 ignore next -- the loop is bounded by the captured part count. */
+            if (part !== undefined)
+                tasks.push(part);
+        }
+    }
+    return chunks.join('');
+}
+/** Initialize one schema-render frame with empty aggregation state. */
+function schemaRenderFrame(node, indent) {
+    return { node, indent, phase: 'start', children: [], childIndex: 0, childDocuments: [], entries: [] };
+}
+/** Render an already asserted schema to a composable document. */
+function renderSupportedSchema(schema, indent) {
+    const frames = [schemaRenderFrame(schema, indent)];
+    let rootDocument;
+    const finish = (document) => {
+        frames.pop();
+        const parent = frames.at(-1);
+        if (parent === undefined)
+            rootDocument = document;
+        else
+            parent.childDocuments.push(document);
+    };
+    while (frames.length > 0) {
+        const frame = frames.at(-1);
+        /* v8 ignore next -- the loop condition guarantees a current frame. */
+        if (frame === undefined)
+            break;
+        if (frame.phase === 'children') {
+            if (frame.childIndex < frame.children.length) {
+                const child = frame.children[frame.childIndex];
+                /* v8 ignore next -- childIndex is bounded by children.length. */
+                if (child === undefined)
+                    throw new Error('missing schema render child');
+                frame.childIndex++;
+                frames.push(schemaRenderFrame(child.node, child.indent));
+                continue;
+            }
+            if (frame.kind === 'oneOf') {
+                const parts = [];
+                for (let index = 0; index < frame.childDocuments.length; index++) {
+                    if (index > 0)
+                        parts.push(' | ');
+                    const child = frame.childDocuments[index];
+                    /* v8 ignore next -- child documents correspond one-to-one with children. */
+                    if (child !== undefined)
+                        parts.push(child);
+                }
+                finish(typeDocumentFrom(parts));
+                continue;
+            }
+            if (frame.kind === 'array') {
+                const child = frame.childDocuments[0];
+                /* v8 ignore next -- array frames always schedule exactly one child. */
+                if (child === undefined)
+                    throw new Error('missing array item type');
+                finish(child.containsUnionOrIntersection
+                    ? typeDocument('(', child, ')[]')
+                    : typeDocument(child, '[]'));
+                continue;
+            }
+            const required = new Set(frame.node.required);
+            const parts = ['{'];
+            for (let index = 0; index < frame.entries.length; index++) {
+                const entry = frame.entries[index];
+                const child = frame.childDocuments[index];
+                /* v8 ignore next -- object entries and child documents have the same length. */
+                if (entry === undefined || child === undefined)
+                    throw new Error('missing object property type');
+                const [name, prop] = entry;
+                for (const line of docLines(prop.description, frame.indent + 1))
+                    parts.push('\n', line);
+                parts.push('\n', `${pad(frame.indent + 1)}${renderKey(name)}${required.has(name) ? '' : '?'}: `, child, ';');
+            }
+            parts.push('\n', `${pad(frame.indent)}}`);
+            const declared = typeDocumentFrom(parts);
+            finish(frame.node.additionalProperties === false
+                ? declared
+                : typeDocument(declared, ' & Record<string, JsonValue>'));
+            continue;
+        }
+        const node = frame.node;
+        if (node.oneOf !== undefined) {
+            frame.kind = 'oneOf';
+            frame.children = Array.from(node.oneOf, child => ({ node: child, indent: frame.indent }));
+            frame.childIndex = 0;
+            frame.childDocuments = [];
+            frame.phase = 'children';
+            continue;
+        }
+        if (node.type === undefined) {
+            finish(typeDocument('JsonValue'));
+            continue;
+        }
+        switch (node.type) {
+            case 'string':
+            case 'number':
+            case 'integer':
+            case 'boolean':
+            case 'null':
+                finish(typeDocument(renderConstrainedScalar(node, node.type)));
+                break;
+            case 'array':
+                if (node.items === undefined) {
+                    finish(typeDocument('JsonValue[]'));
+                }
+                else {
+                    frame.kind = 'array';
+                    frame.children = [{ node: node.items, indent: frame.indent }];
+                    frame.childIndex = 0;
+                    frame.childDocuments = [];
+                    frame.phase = 'children';
+                }
+                break;
+            case 'object': {
+                const open = node.additionalProperties !== false;
+                const entries = Object.entries(node.properties ?? {});
+                if (entries.length === 0) {
+                    finish(typeDocument(open ? 'Record<string, JsonValue>' : 'Record<string, never>'));
+                }
+                else {
+                    frame.kind = 'object';
+                    frame.entries = entries;
+                    frame.children = entries.map(([, child]) => ({ node: child, indent: frame.indent + 1 }));
+                    frame.childIndex = 0;
+                    frame.childDocuments = [];
+                    frame.phase = 'children';
+                }
+                break;
+            }
+            /* v8 ignore next -- assertSupportedJsonSchema narrowed this closed type union. */
+            default:
+                finish(typeDocument('unknown'));
+        }
+    }
+    /* v8 ignore next -- every root frame produces one document. */
+    return rootDocument ?? typeDocument('unknown');
+}
+/**
+ * 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 function jsonSchemaToTs(schema, indent = 0) {
+    try {
+        assertSupportedJsonSchema(schema);
+        return flattenTypeDocument(renderSupportedSchema(schema, indent));
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** The fixed model-facing usage contract rendered above the declarations (see the Code Mode Agent Note's "What the model sees"). */
+const SDK_INSTRUCTIONS = `## Writing code for run_code
+
+\`run_code\` takes two required arguments: \`code\` — the body of an async TypeScript function (erasable syntax only — no \`enum\` or namespaces; type annotations are advisory, the code runs type-stripped) — and \`description\`, a short summary of what the program does. Inside the program:
+
+- Call tools as \`await tools.name(args)\` — quoted access for exotic names: \`tools["my-tool"](args)\`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.
+- A FAILED tool call rejects with \`ToolCallError\`, whose \`toolName\` identifies the failed tool and whose \`message\` is human-readable — \`try/catch\` it to handle and continue.
+- Independent read-only calls MAY overlap under \`Promise.all\` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with \`await\`.
+- Emit results with \`return\` and/or \`console.log(...)\`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.
+
+The available tools:`;
+/**
+ * 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 function renderToolsSdk(schemas) {
+    const sorted = [...schemas].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    const argsMembers = [];
+    const outputMembers = [];
+    for (const schema of sorted) {
+        argsMembers.push(...docLines(schema.description, 1));
+        argsMembers.push(`${pad(1)}${renderKey(schema.name)}: ${jsonSchemaToTs(schema.parameters, 1)};`);
+        outputMembers.push(`${pad(1)}${renderKey(schema.name)}: ${jsonSchemaToTs(schema.output, 1)};`);
+    }
+    const argsMap = `interface ToolArgsMap {${argsMembers.length > 0 ? `\n${argsMembers.join('\n')}\n` : ''}}`;
+    const outputMap = `interface ToolOutputMap {${outputMembers.length > 0 ? `\n${outputMembers.join('\n')}\n` : ''}}`;
+    const declaration = [
+        argsMap,
+        outputMap,
+        'type ToolName = keyof ToolOutputMap',
+        ['declare class ToolCallError extends Error {', '  readonly name: "ToolCallError";', '  readonly toolName: ToolName;', '}'].join('\n'),
+        ['declare const tools: {', '  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;', '}'].join('\n'),
+    ].join('\n\n');
+    const jsonValue = 'type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }';
+    return `${SDK_INSTRUCTIONS}\n\n\`\`\`ts\n${jsonValue}\n\n${declaration}\n\`\`\``;
+}
+//# sourceMappingURL=ts-types.js.map

package/lib/ts-types.js.map

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

package/lib/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Durable Tool event vocabulary shared with type-only consumers.
+ *
+ * @module @dsh-cc/tools/types
+ */
+import type { CallId } from '@deepseek-ai/dsh-llm/brand';
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types';
+/** Payload recorded when one nested Code Mode Tool dispatch starts. */
+export interface CodeDispatchStartEventData {
+    rootCallId: CallId;
+    parentCallId: CallId;
+    subCallId: CallId;
+    name: string;
+    arguments: unknown;
+}
+/** Payload recorded when one nested Code Mode Tool dispatch settles. */
+export interface CodeDispatchEventData extends CodeDispatchStartEventData {
+    isError: boolean;
+    content: ContentBlock[];
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * One sub-dispatch STARTING inside a `run_code` program: the parent
+         * `run_code` call id, the deterministic sub-call id (`<parent>:code:<n>`,
+         * numbered in submission order), and the tool `name` with its
+         * JSON-normalized `arguments` — the exact value dispatched, normalized
+         * BEFORE dispatch, so this append can never fail on payload shape.
+         * Appended when the scheduler actually starts the call (not at
+         * submission), so a start means the tool body pipeline was entered; a
+         * call abandoned in the queue logs nothing. Log-only: `deriveMessages()`
+         * ignores it; UIs use it for live per-sub-call running state and pair it
+         * with `tool/code-dispatch` by `subCallId` (timing = the two events'
+         * `time` fields).
+         */
+        'tool/code-dispatch-start': CodeDispatchStartEventData;
+        /**
+         * One bridged sub-dispatch SETTLING: the pairing ids (matching the
+         * `tool/code-dispatch-start` with the same `subCallId`), the tool `name`
+         * with the same JSON-normalized `arguments`, and the sub-call's complete
+         * model-facing outcome in `tool/result`'s own vocabulary
+         * (`content` + `isError`), so UIs render a sub-call through the exact
+         * code path that renders a native call. Every started sub-call settles
+         * with exactly one of these (abort included: the aborted pipeline result
+         * is an `isError` outcome).
+         * Log-only: `deriveMessages()` ignores it, so sub-calls never re-enter
+         * model context; persistence and UIs get every call. Appended inside the
+         * parent `run_code`'s execution (the bridge drains in-flight dispatches
+         * before returning), so its execution-enclosure relation holds by
+         * construction.
+         */
+        'tool/code-dispatch': CodeDispatchEventData;
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAA;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAE9D,uEAAuE;AACvE,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,wEAAwE;AACxE,MAAM,WAAW,qBAAsB,SAAQ,0BAA0B;IACvE,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,YAAY,EAAE,CAAA;CACxB;AAED,OAAO,QAAQ,gCAAgC,CAAC;IAC9C,UAAU,eAAe;QACvB;;;;;;;;;;;;WAYG;QACH,0BAA0B,EAAE,0BAA0B,CAAA;QACtD;;;;;;;;;;;;;;WAcG;QACH,oBAAoB,EAAE,qBAAqB,CAAA;KAC5C;CACF"}

package/lib/types.js

@@ -0,0 +1,7 @@
+/**
+ * Durable Tool event vocabulary shared with type-only consumers.
+ *
+ * @module @dsh-cc/tools/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@dsh-cc/tools",
+  "description": "Tool registry and execution pipeline for the DeepSeek Harness",
+  "version": "0.5.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dsh-cc/dsh-cc.git",
+    "directory": "packages/core/tools"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types.d.ts",
+      "default": "./lib/types.js"
+    },
+    "./presentation": {
+      "types": "./lib/presentation.d.ts",
+      "default": "./lib/presentation.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-code-runtime": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-scope": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-user-approval": ">=0.1.1-rc.2",
+    "@deepseek-ai/cordis": ">=0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "link:../../../../deepseek-harness/packages/core/agent",
+    "@deepseek-ai/dsh-code-runtime": "link:../../../../deepseek-harness/packages/code-runtime/code-runtime",
+    "@deepseek-ai/dsh-invariants": "link:../../../../deepseek-harness/packages/runtime-diagnostics/invariants",
+    "@deepseek-ai/dsh-llm": "link:../../../../deepseek-harness/packages/llm/llm",
+    "@deepseek-ai/dsh-scope": "link:../../../../deepseek-harness/packages/core/scope",
+    "@deepseek-ai/dsh-session": "link:../../../../deepseek-harness/packages/core/session",
+    "@deepseek-ai/dsh-system-prompt": "link:../../../../deepseek-harness/packages/core/system-prompt",
+    "@deepseek-ai/dsh-tools": "link:../../../../deepseek-harness/packages/core/tools",
+    "@deepseek-ai/dsh-user-approval": "link:../../../../deepseek-harness/packages/interaction/user-approval",
+    "@deepseek-ai/cordis": "link:../../../../deepseek-harness/vendor/cordis",
+    "@deepseek-ai/schemastery": "link:../../../../deepseek-harness/vendor/schemastery",
+    "fast-check": "4.8.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}