@dsh-cc/tools 0.5.0

package/lib/py-render.js

@@ -0,0 +1,434 @@
+/**
+ * The Python type-expression renderer: {@link renderType}, the explicit-stack
+ * walker that maps one validated JSON-Schema node to a Python type expression
+ * while threading a {@link RenderState} to collect the `TypedDict` class
+ * declarations and `typing` symbols a full render needs. Split out of
+ * `py-types.ts` for the line budget; `jsonSchemaToPy` and `renderToolsSdkPy`
+ * remain the public entries, re-exported from `py-types.ts`.
+ * @module @dsh-cc/tools/src/py-render
+ */
+import { assertSupportedJsonSchema } from "./json-schema.js";
+import { describe, camelCase, isBareIdentifier, pad, RESERVED } from "./py-names.js";
+/** Class-name base cap keeping each emitted name — and total text — linear in schema depth. */
+const MAX_CLASS_NAME_BASE = 120;
+/**
+ * Deepest `list[…]` nesting emitted into one annotation before the item type
+ * degrades to `Any`. CPython's tokenizer rejects a logical line holding more
+ * than 200 simultaneously-open brackets (`MAXLEVEL`, `SyntaxError: too many
+ * nested parentheses`), so an array chain deeper than that would render an SDK
+ * block that is not valid Python at all — the same failure the docstring
+ * escaping in the SDK doc renderer exists to prevent. 180 leaves headroom for
+ * the few brackets an annotation can add around the chain, all of which count
+ * toward the same limit. Per emission site, counting brackets open at the
+ * chain's innermost point:
+ *
+ * - Return annotation, `async def f(self, args: X) -> chain:` — 180 `list[`
+ *   plus an innermost `Literal[`. The parameter list's `(` closed at the `)`
+ *   before the `->`, so it is NOT open here: 181.
+ * - TypedDict field, `field: NotRequired[chain]` — a class-body line with no
+ *   other open bracket, and its children start at `listDepth: 1` to reserve
+ *   the `NotRequired[`, so 179 `list[` plus `Literal[`: 181. Required fields
+ *   share that start for uniformity, spending one level of representable depth
+ *   on a bracket they never emit.
+ * - Argument annotation, `async def f(self, args: chain) -> Y:` — the `(` IS
+ *   still open around it: 180 `list[` plus `Literal[` plus the paren, 182, the
+ *   worst case. Reachable only through a raw `register()` whose `parameters`
+ *   is an array reached from the root through `oneOf` arms alone — the root
+ *   array itself, or one nested under any depth of unions, since an arm
+ *   inherits the enclosing depth unchanged (`A | B` opens no bracket). An
+ *   object ancestor takes it out of this case: its fields restart the chain at
+ *   the 181 site. `defineTool` compiles an object root, so the annotation is a
+ *   bare TypedDict class name or a one-bracket `dict[str, Any]` when that
+ *   object degrades — never a chain.
+ *
+ * A CPython grammar limit, not a deployment choice, so it is fixed rather than
+ * configurable. The sibling `ts-types` renderer needs no counterpart: nothing
+ * in the TypeScript grammar bounds nesting, and its SDK block is never type-
+ * checked. Only bracket nesting counts — a `oneOf` renders as a flat `A | B`
+ * chain and nested objects render as separate `class` statements, so neither
+ * accumulates open brackets at any depth. The invariant this cap serves is
+ * grammatical validity; see the `oneOf` arm in {@link renderType} for the one
+ * interpreter limit deliberately left uncapped.
+ */
+const MAX_LIST_NESTING = 180;
+/**
+ * Cap a class-name base at {@link MAX_CLASS_NAME_BASE} (see the callers for
+ * why capping keeps the render linear). `slice` counts UTF-16 code units, so
+ * an astral character straddling the boundary would be cut in half and leave a
+ * lone surrogate — not an identifier character, and not even well-formed text;
+ * drop it rather than emit it.
+ */
+function capClassNameBase(base) {
+    if (base.length <= MAX_CLASS_NAME_BASE)
+        return base;
+    const capped = base.slice(0, MAX_CLASS_NAME_BASE);
+    return /[\uD800-\uDBFF]$/.test(capped) ? capped.slice(0, -1) : capped;
+}
+/**
+ * Reserve a unique class name from a base, suffixing `2`, `3`, … on collision.
+ * The base is capped at {@link MAX_CLASS_NAME_BASE} first: child class names
+ * derive from their parent's allocated name (`ParentChild`), so an unbounded
+ * schema of single-field objects would otherwise grow each name by one field
+ * per level and the sum of all names to Θ(depth²). Capping the base keeps each
+ * name — and the total emitted text — linear in depth. Collisions resume from
+ * the per-base counter in `state.nextClassCounter` rather than rescanning from
+ * `2`, so a deep chain sharing one capped base stays O(1) per allocation
+ * (amortized) instead of Θ(depth²) in time.
+ */
+function allocateClassName(base, state) {
+    const capped = capClassNameBase(base);
+    let name = capped;
+    if (state.usedClassNames.has(name)) {
+        let n = state.nextClassCounter.get(capped) ?? 2;
+        while (state.usedClassNames.has(`${capped}${n}`))
+            n++;
+        name = `${capped}${n}`;
+        state.nextClassCounter.set(capped, n + 1);
+    }
+    state.usedClassNames.add(name);
+    return name;
+}
+/**
+ * Append a child-name segment to a parent class-name base, capping the result
+ * at {@link MAX_CLASS_NAME_BASE}. Capping AT PROPAGATION (not only inside
+ * {@link allocateClassName}) keeps each level O(1): a deep `oneOf`- or
+ * object-chain would otherwise carry an ever-growing ConsString down the tree
+ * and re-materialize it (via `.length`/`.slice`) at every level — Θ(depth²).
+ * The bounded base plus the collision counter still yields unique names.
+ *
+ * The join is NFKC-normalized because both sides are separately normalized yet
+ * their concatenation need not be: a base ending in a Hangul L jamo or LV
+ * syllable composes with a following V or T jamo head (`가` + `ᆨ` gives `각`),
+ * so the emitted class name would differ from the symbol CPython compiles, and
+ * two byte-distinct names could fold onto one — `usedClassNames` dedupes by the
+ * raw bytes, so the collision counter would not see it. Normalizing costs
+ * O(cap + segment) per level, the same order as the `slice` it feeds. The other
+ * two join points need no counterpart: `Args`/`Output` start with `A`/`O` and
+ * {@link allocateClassName}'s suffix is digits, none of which compose backwards.
+ */
+function childClassName(base, segment) {
+    return capClassNameBase(`${base}${segment}`.normalize('NFKC'));
+}
+/**
+ * Render one validated scalar as Python literal text (`True`/`False`,
+ * JSON-quoted strings, bare numbers). `null` cannot reach here: the `null`
+ * type renders directly as `None`, and the unified validator rejects a null
+ * `const`/`enum` entry on every other scalar type.
+ *
+ * A beyond-safe-range integral number takes `BigInt` digits rather than
+ * `String`: Python integers are arbitrary-precision, so the emitted digits ARE
+ * the value the model programs against, and `String` can give a different
+ * integer than the double holds (`2 ** 60` prints the rounded `...847000`, not
+ * the exact `...846976`) or no integer literal at all (`1e21` prints `1e+21`).
+ * `String`'s rounding is not a bug in it: `Number::toString` emits the shortest
+ * decimal string that re-reads to the same double, then pads to the exponent
+ * with zeros (1 significant digit for `1e20`, 16 for `2 ** 60`) — and when the
+ * shortest string is shorter than the double's exact value, those padded digits
+ * name an integer no double holds. Passing one back would have to cross the
+ * argument boundary as a JSON number — a double again — so the SDK would
+ * document a value no program can pass. `BigInt` needs no case split: where
+ * `String` is already exact (`2 ** 53`, `1e20`) the two agree byte for byte,
+ * and where it is not, `BigInt` is the exact one. The TS flavor needs no
+ * counterpart at all: its literal is re-read by a JS parser back into the same
+ * double.
+ *
+ * `JSON.stringify` is also what keeps this path's output parseable, and it is
+ * the only thing that does. It covers both classes of hazard: the two kinds of
+ * code point CPython refuses anywhere in source — NUL among the C0 controls,
+ * and the whole D800–DFFF unpaired-surrogate block, escaped under ES2019
+ * well-formed stringification, which the engines range guarantees — and the
+ * ones that break this line in particular, a bare `"` closing the literal
+ * early, a trailing odd backslash eating the closing quote, and a bare LF/CR
+ * ending it before its terminator. The `description` path carries
+ * the unprintable-character and lone-surrogate rules because nothing quotes it,
+ * and folds newlines in {@link describe}.
+ *
+ * That leans on a coincidence worth naming: every escape `JSON.stringify` can
+ * emit (`\"`, `\\`, `\b`, `\f`, `\n`, `\r`, `\t`, `\uXXXX`) is also a Python
+ * escape denoting the same character, so the emitted `Literal[...]` both
+ * parses and decodes back to the value the schema declared. DEL, the C1
+ * controls (NEL among them), and LS/PS (U+2028/U+2029) do reach it raw —
+ * legal but invisible, byte-for-byte as in the TS flavor; escaping them is a
+ * both-flavors change. Those last three are legal here for the reason
+ * the unprintable rule records: they are `str.splitlines()` boundaries, not
+ * tokenizer line terminators. The subscript tool-name comment quotes its name
+ * through its own call to the same `JSON.stringify`, never through this
+ * function, and inherits both halves — escapes and pass-throughs alike.
+ */
+function pyScalar(value) {
+    if (value === true)
+        return 'True';
+    if (value === false)
+        return 'False';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number' && Number.isInteger(value) && !Number.isSafeInteger(value)) {
+        return BigInt(value).toString();
+    }
+    return String(value);
+}
+/**
+ * Render a validated scalar `const`/`enum` as `Literal[...]`, falling back to
+ * the broad type. Deliberately deviates from PEP 586, which restricts `Literal`
+ * parameters to int/bool/str/bytes/enum/None: a non-integral number
+ * `const`/`enum` emits a float literal (`Literal[1.5]`) a strict checker would
+ * reject. An integral one does not deviate — {@link pyScalar} emits int digits,
+ * including for the beyond-safe-range values it widens through `BigInt`, and
+ * PEP 586 admits int parameters. Harmless either way — the stub is advisory
+ * prompt text, only required to parse — and keeping the exact value
+ * communicates the constraint to the model.
+ */
+function renderConstrainedScalar(node, broad, state) {
+    if (node.const !== undefined) {
+        state.typing.add('Literal');
+        return `Literal[${pyScalar(node.const)}]`;
+    }
+    if (node.enum !== undefined) {
+        state.typing.add('Literal');
+        return `Literal[${node.enum.map(pyScalar).join(', ')}]`;
+    }
+    return broad;
+}
+/**
+ * Map one JSON-Schema node to a Python type expression, threading `state` to
+ * collect the `TypedDict` declarations and `typing` symbols a full render
+ * needs. `className` is the name to give an object node with properties (and
+ * the prefix for its nested objects). Handles every unified schema construct —
+ * `oneOf` (→ `X | Y`), `const`/`enum` (→ `Literal[...]`), `integer` (→ `int`),
+ * `null` (→ `None`) — and degrades an unsupported or malformed schema to `Any`
+ * without throwing, the same trusted-after-validation stance as the sibling
+ * {@link ./ts-types.ts | ts-types} renderer. `jsonSchemaToPy` is the
+ * context-free entry point; this is the collecting core.
+ */
+export function renderType(schema, className, state) {
+    const newFrame = (schema, className, listDepth) => ({ schema, className, phase: 'start', listDepth, children: [], childIndex: 0, childTypes: [], entries: [] });
+    try {
+        // Validate the WHOLE tree once, then trust it — the same contract the
+        // sibling ts-types renderer follows at a typed same-process boundary. Every
+        // node past this point is a validated JSON-schema node, so the walk reads
+        // its fields without re-checking. An unsupported or malformed schema throws
+        // here (before anything is emitted) and degrades to `Any`, the Python
+        // counterpart of the TS flavor's `unknown`.
+        assertSupportedJsonSchema(schema);
+        const frames = [newFrame(schema, className, 0)];
+        let result;
+        /* jscpd:ignore-start -- the explicit-stack walk skeleton deliberately parallels
+           ts-types.ts's renderSupportedSchema; the two sibling renderers keep symmetric shapes. */
+        const finish = (type) => {
+            frames.pop();
+            const parent = frames.at(-1);
+            if (parent === undefined)
+                result = type;
+            else
+                parent.childTypes.push(type);
+        };
+        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 python render child');
+                    frame.childIndex++;
+                    frames.push(newFrame(child.schema, child.className, child.listDepth));
+                    continue;
+                }
+                if (frame.kind === 'oneOf') {
+                    // Concatenate incrementally (template literal, not `Array.join`): V8
+                    // builds a lazy ConsString, so a deep oneOf chain materializes once
+                    // at the root instead of re-materializing the accumulated string at
+                    // every level (which `join` would, making it Θ(depth²)). This matches
+                    // the array arm's template-literal laziness and ts-types' composable-
+                    // document approach — the whole walk stays linear in schema depth.
+                    let union = '';
+                    for (const [index, childType] of frame.childTypes.entries()) {
+                        union = index === 0 ? childType : `${union} | ${childType}`;
+                    }
+                    finish(union);
+                    continue;
+                }
+                /* jscpd:ignore-end */
+                if (frame.kind === 'array') {
+                    // `list[A | B]` needs no parentheses in Python. Array frames always
+                    // schedule exactly one child, so its type is present.
+                    /* v8 ignore next -- the ?? arm needs a childless array frame, which start never builds. */
+                    finish(`list[${frame.childTypes[0] ?? 'Any'}]`);
+                    continue;
+                }
+                // typeddict: assemble AFTER the children so any nested class this one
+                // references is already declared (declaration order = reference order).
+                const node = frame.node;
+                const name = frame.allocated;
+                /* v8 ignore next -- typeddict frames always set node and allocated at start. */
+                if (node === undefined || name === undefined)
+                    throw new Error('missing typeddict frame state');
+                const required = new Set(node.required);
+                const lines = [`class ${name}(TypedDict):`];
+                for (let index = 0; index < frame.entries.length; index++) {
+                    const entry = frame.entries[index];
+                    const fieldType = frame.childTypes[index];
+                    /* v8 ignore next -- entries and childTypes correspond one-to-one. */
+                    if (entry === undefined || fieldType === undefined)
+                        throw new Error('missing typeddict field type');
+                    const [field, fieldSchema] = entry;
+                    // The parent node passed assertSupportedJsonSchema, so every property
+                    // value is a validated schema node.
+                    const description = describe(fieldSchema);
+                    if (description !== undefined)
+                        lines.push(`${pad(1)}# ${description}`);
+                    if (required.has(field)) {
+                        lines.push(`${pad(1)}${field}: ${fieldType}`);
+                    }
+                    else {
+                        state.typing.add('NotRequired');
+                        lines.push(`${pad(1)}${field}: NotRequired[${fieldType}]`);
+                    }
+                }
+                // TypedDict syntax cannot express openness, so an open object states it
+                // in-band: the annotation is advisory either way, and `mode: 'code'`
+                // omits the native schemas, making this line the model's only signal
+                // that extra keys are accepted.
+                if (node.additionalProperties !== false) {
+                    lines.push(`${pad(1)}# Additional keys beyond those declared are allowed.`);
+                }
+                // A closed empty object still needs a class body (`pass`) to be valid
+                // Python; the declared emptiness is the information.
+                if (lines.length === 1)
+                    lines.push(`${pad(1)}pass`);
+                state.classes.push(lines.join('\n'));
+                finish(name);
+                continue;
+            }
+            frame.phase = 'children';
+            const node = frame.schema;
+            if (node.oneOf !== undefined) {
+                frame.kind = 'oneOf';
+                // A union renders as `A | B` — no brackets of its own, so the branches
+                // inherit the enclosing depth unchanged.
+                //
+                // Union LENGTH is deliberately uncapped, unlike list nesting. The two
+                // limits are different in kind: >200 open brackets is a SyntaxError
+                // from the tokenizer, so the text is not Python; a long `A | B | …`
+                // chain is grammatically valid at any length and only defeats CPython's
+                // C-recursion when `compile()` walks the left-nested BinOp spine
+                // (measured: 1,000 branches compile, 5,000 raise RecursionError). This
+                // block is prompt text — nothing compiles it — so that limit costs
+                // nothing here, while capping would retire the deep-chain tests that
+                // pin the walk's linear time and the class-name propagation cap. The
+                // standard this renderer holds is grammatical validity, not
+                // compilability under one interpreter's stack.
+                frame.children = node.oneOf.map((branch, index) => ({ schema: branch, className: childClassName(frame.className, `${index + 1}`), listDepth: frame.listDepth }));
+                continue;
+            }
+            if (node.type === undefined) {
+                state.typing.add('Any');
+                finish('Any');
+                continue;
+            }
+            switch (node.type) {
+                case 'string':
+                    finish(renderConstrainedScalar(node, 'str', state));
+                    break;
+                case 'number':
+                    finish(renderConstrainedScalar(node, 'float', state));
+                    break;
+                case 'integer':
+                    finish(renderConstrainedScalar(node, 'int', state));
+                    break;
+                case 'boolean':
+                    finish(renderConstrainedScalar(node, 'bool', state));
+                    break;
+                case 'null':
+                    finish('None');
+                    break;
+                case 'array': {
+                    if (node.items === undefined) {
+                        state.typing.add('Any');
+                        finish('list[Any]');
+                        break;
+                    }
+                    // Past MAX_LIST_NESTING another `list[` would push the annotation
+                    // beyond CPython's open-bracket limit and make the whole SDK block
+                    // unparseable, so the chain degrades here instead — an unusable
+                    // annotation either way, and this one is valid Python.
+                    if (frame.listDepth >= MAX_LIST_NESTING) {
+                        state.typing.add('Any');
+                        finish('Any');
+                        break;
+                    }
+                    // An array of objects names its item type after the array field.
+                    frame.kind = 'array';
+                    frame.children = [{ schema: node.items, className: frame.className, listDepth: frame.listDepth + 1 }];
+                    break;
+                }
+                case 'object': {
+                    // A missing `properties` is an empty property map, exactly as the
+                    // unified validator and the TS renderer read it — NOT an unknown
+                    // shape. The openness of the resulting empty object is decided below,
+                    // so a closed empty object still declares an empty TypedDict rather
+                    // than a permissive `dict[str, Any]`.
+                    const entries = Object.entries(node.properties ?? {});
+                    // An empty `className` marks the context-free `jsonSchemaToPy` entry:
+                    // there is no naming context to declare into, so degrade. This reads
+                    // the CALL's className, not `frame.className`: the marker belongs to
+                    // the whole walk, and frames propagate a derived name (a `oneOf`
+                    // branch of the context-free root gets the index-derived name `1` —
+                    // `childClassName` concatenates and caps, it does not go through
+                    // `camelCase`), so a per-frame read would declare classes the caller
+                    // has no way to receive, under a name that is not even a legal
+                    // identifier: `class 1(TypedDict):`. A field
+                    // name that is not a legal Python attribute is inexpressible as a
+                    // class-syntax `TypedDict` field, so such an object degrades whole.
+                    // A leading-double-underscore non-dunder field (`__token`) would be
+                    // NAME-MANGLED inside class syntax (`_ClassName__token`), describing a
+                    // different JSON key than the registered schema — degrade like any
+                    // other inexpressible field name.
+                    if (className === '' || !entries.every(([name]) => isBareIdentifier(name) && !RESERVED.has(name) && !(name.startsWith('__') && !name.endsWith('__')))) {
+                        state.typing.add('Any');
+                        finish('dict[str, Any]');
+                        break;
+                    }
+                    // An OPEN empty object is any dict; a CLOSED empty object declares an
+                    // empty TypedDict so "no keys accepted" survives into the SDK.
+                    if (entries.length === 0 && node.additionalProperties !== false) {
+                        state.typing.add('Any');
+                        finish('dict[str, Any]');
+                        break;
+                    }
+                    frame.kind = 'typeddict';
+                    frame.node = node;
+                    frame.allocated = allocateClassName(frame.className, state);
+                    state.typing.add('TypedDict');
+                    frame.entries = entries;
+                    // A field annotation is its own logical line, so nesting restarts —
+                    // at 1, reserving the bracket an optional field's `NotRequired[…]`
+                    // wraps around it. frame.allocated was assigned three statements up;
+                    // the ?? arm is for the type system only.
+                    /* v8 ignore next -- allocated is always set before children are built. */
+                    frame.children = entries.map(([field, child]) => ({ schema: child, className: childClassName(frame.allocated ?? '', camelCase(field)), listDepth: 1 }));
+                    break;
+                }
+                /* v8 ignore next 4 -- assertSupportedJsonSchema narrowed this closed type union. */
+                default: {
+                    state.typing.add('Any');
+                    finish('Any');
+                }
+            }
+        }
+        /* v8 ignore next -- every root frame produces one expression. */
+        return result ?? 'Any';
+    }
+    catch {
+        // An unsupported or malformed schema failed validation (before any
+        // emission), or an unreachable internal invariant tripped. Either degrades
+        // the node to `Any` rather than crashing prompt assembly — the Python
+        // counterpart of the TS flavor's `unknown` fallback.
+        state.typing.add('Any');
+        return 'Any';
+    }
+}
+//# sourceMappingURL=py-render.js.map

package/lib/py-render.js.map

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

package/lib/py-sdk-doc.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The Python SDK document renderer: `renderToolsSdkPy`, the `tools:sdk` prompt
+ * section rendered under `runtime.language === 'python'` — the fixed usage
+ * instructions plus one named `TypedDict` per tool argument or output object
+ * and one awaitable method per visible tool on a `Tools` protocol. Split out
+ * of `py-types.ts` for the line budget; re-exported from `py-types.ts`.
+ * @module @dsh-cc/tools/src/py-sdk-doc
+ */
+import type { ToolSdkSchema } from './ts-types.ts';
+/**
+ * Render the full `tools:sdk` prompt section under `runtime.language ===
+ * 'python'`: the Python-flavored usage instructions plus one named `TypedDict`
+ * per tool argument or output object (and per nested object) and one awaitable
+ * method per visible tool on a `Tools` protocol — typed args in, the tool's
+ * canonical output value out — with a `tools: Tools` singleton the model calls
+ * into. The `typing` import line lists exactly the symbols the render used.
+ * Deterministic — tools are emitted in lexicographic name order, and class
+ * declarations precede the protocol in that same order (nested classes before
+ * the parent that references them), 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 plus canonical output schemas to declare
+ *   (the caller excludes `run_code` itself).
+ * @returns the complete section text.
+ */
+export declare function renderToolsSdkPy(schemas: ToolSdkSchema[]): string;
+//# sourceMappingURL=py-sdk-doc.d.ts.map

package/lib/py-sdk-doc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"py-sdk-doc.d.ts","sourceRoot":"","sources":["../src/py-sdk-doc.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAkClD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,MAAM,CAuDjE"}

package/lib/py-sdk-doc.js

@@ -0,0 +1,114 @@
+/**
+ * The Python SDK document renderer: `renderToolsSdkPy`, the `tools:sdk` prompt
+ * section rendered under `runtime.language === 'python'` — the fixed usage
+ * instructions plus one named `TypedDict` per tool argument or output object
+ * and one awaitable method per visible tool on a `Tools` protocol. Split out
+ * of `py-types.ts` for the line budget; re-exported from `py-types.ts`.
+ * @module @dsh-cc/tools/src/py-sdk-doc
+ */
+import { describe, camelCase, isBareIdentifier, pad, RESERVED } from "./py-names.js";
+import { renderType } from "./py-render.js";
+/** `typing` symbols this module may emit, in the deterministic import order. */
+const TYPING_ORDER = ['Any', 'Literal', 'NotRequired', 'Protocol', 'TypedDict'];
+/**
+ * One-line docstring for a tool `description`, or no lines when there is none.
+ * Backslashes are doubled first, every quote is escaped, and a trailing
+ * backslash cannot survive: a description ending in `"` or an odd backslash
+ * would otherwise merge with (or escape) the closing triple quote and make
+ * the generated block — Code Mode's only SDK — syntactically invalid Python.
+ */
+function docLines(description, indent) {
+    const collapsed = describe({ description });
+    if (collapsed === undefined)
+        return [];
+    const escaped = collapsed.replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+    return [`${pad(indent)}"""${escaped}"""`];
+}
+/** The fixed model-facing usage contract rendered above the declarations. */
+const SDK_INSTRUCTIONS = `## Writing code for run_code
+
+\`run_code\` takes two required arguments: \`code\` — the body of an async Python function (top-level \`await\` and \`return\` both work) — and \`description\`, a short summary of what the program does. At run time exactly two of the names declared below are bound: \`tools\` and \`ToolCallError\`. Everything else is a STATIC STUB describing argument and return types — in particular the \`TypedDict\` classes do NOT exist at run time, so build arguments as plain \`dict\`/\`list\` JSON values: \`await tools.name({"field": 1})\`, never \`FooArgs(field=1)\`, which raises \`NameError\`. Inside the program:
+
+- Call tools as \`await tools.name(args)\` — subscript access for exotic, reserved, or underscore-leading names: \`await tools["my-tool"](args)\`. Every call resolves to the tool's typed canonical JSON value (each method's return type below). Tool arguments must be lossless JSON.
+- A FAILED tool call raises \`ToolCallError\`, whose \`toolName\` identifies the failed tool and whose message is human-readable — wrap in \`try/except\` to handle and continue.
+- Independent read-only calls MAY overlap under \`asyncio.gather\` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with \`await\`.
+- Emit the run's answer with \`print(...)\` and/or a top-level \`return <value>\`; the returned value must be lossless JSON. ONLY what you print and the returned value come back — intermediate tool results never enter the conversation, so extract just what you need.
+
+The available tools:`;
+/**
+ * Render the full `tools:sdk` prompt section under `runtime.language ===
+ * 'python'`: the Python-flavored usage instructions plus one named `TypedDict`
+ * per tool argument or output object (and per nested object) and one awaitable
+ * method per visible tool on a `Tools` protocol — typed args in, the tool's
+ * canonical output value out — with a `tools: Tools` singleton the model calls
+ * into. The `typing` import line lists exactly the symbols the render used.
+ * Deterministic — tools are emitted in lexicographic name order, and class
+ * declarations precede the protocol in that same order (nested classes before
+ * the parent that references them), 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 plus canonical output schemas to declare
+ *   (the caller excludes `run_code` itself).
+ * @returns the complete section text.
+ */
+export function renderToolsSdkPy(schemas) {
+    const sorted = [...schemas].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    const state = { classes: [], usedClassNames: new Set(), nextClassCounter: new Map(), typing: new Set(['Protocol']) };
+    // ONE ordered member stream, matching the documented lexicographic contract
+    // and the TypeScript flavor (which quotes exotic keys in place rather than
+    // partitioning them out). Interleaving is free here: a comment line between
+    // two `async def` lines is not a statement, so it changes nothing about how
+    // the class body parses.
+    const members = [];
+    let statements = 0;
+    for (const schema of sorted) {
+        const argType = renderType(schema.parameters, `${camelCase(schema.name)}Args`, state);
+        const outputType = renderType(schema.output, `${camelCase(schema.name)}Output`, state);
+        if (isBareIdentifier(schema.name) && !RESERVED.has(schema.name) && !schema.name.startsWith('_')) {
+            // A docstring only documents its method when it is the FIRST statement
+            // of that method's body. Emitted before the `async def` it would instead
+            // become the `Tools` class docstring (for the first tool) or a dead
+            // expression (for every later one), leaving every method undocumented —
+            // and under `mode: 'code'` this SDK is the model's only description of
+            // what a tool does. A docstring is a complete body, so the `...` stub is
+            // only for the description-less case.
+            const doc = docLines(schema.description, 2);
+            members.push(doc.length > 0
+                ? `${pad(1)}async def ${schema.name}(self, args: ${argType}) -> ${outputType}:`
+                : `${pad(1)}async def ${schema.name}(self, args: ${argType}) -> ${outputType}: ...`);
+            members.push(...doc);
+            statements += 1;
+        }
+        else {
+            // Not reachable as ``tools.name`` — the model reaches it via
+            // ``tools[name]``. Exotic names and hard keywords are not legal
+            // attributes at all; an underscore-leading name (``_foo``) IS a legal
+            // attribute and is routed here anyway, because the forms that break
+            // split three ways — a non-dunder ``__token`` name-mangles at the CALL
+            // site, a dunder that exists on ``object``/``type`` (``__class__``,
+            // ``__doc__``) resolves before ``__getattr__`` ever runs, and implicit
+            // special-method lookup skips the hook entirely — and one rule over the
+            // whole family costs nothing while a per-form rule would have to
+            // enumerate them (see {@link RESERVED}). The stub lists it as a subscript comment
+            // (referencing the named TypedDicts too) so a reader sees what is
+            // accessible; runtime resolution goes through the proxy's __getitem__.
+            members.push(`${pad(1)}# tools[${JSON.stringify(schema.name)}](args: ${argType}) -> ${outputType}`);
+            const description = describe(schema);
+            if (description !== undefined)
+                members.push(`${pad(1)}#   ${description}`);
+        }
+    }
+    // Subscript entries are COMMENTS, not statements: a class body of only
+    // comments fails to parse, so `pass` is required whenever no method was
+    // emitted — including the subscript-only tool set.
+    const bodyLines = statements > 0 ? members : [`${pad(1)}pass`, ...members];
+    const body = bodyLines.join('\n');
+    const imports = TYPING_ORDER.filter(symbol => state.typing.has(symbol));
+    const classBlock = state.classes.length > 0 ? `${state.classes.join('\n\n')}\n\n` : '';
+    const errorDeclaration = 'class ToolCallError(Exception):\n    toolName: str';
+    const declaration = `from typing import ${imports.join(', ')}\n\n${errorDeclaration}\n\n${classBlock}class Tools(Protocol):\n${body}\n\ntools: Tools`;
+    return `${SDK_INSTRUCTIONS}\n\n\`\`\`python\n${declaration}\n\`\`\``;
+}
+//# sourceMappingURL=py-sdk-doc.js.map

package/lib/py-sdk-doc.js.map

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