dsh-py-codeact 0.3.0 → 0.3.1

package/lib/index.js

@@ -49,16 +49,16 @@ const INSTRUCTIONS = `## Writing code for the \`python\` tool
 Your action space is Python. Each call runs one cell in a **persistent IPython session**: names you bind stay bound for the rest of the session, so build state up across calls instead of re-deriving it. Imports, dataframes, open handles, connections all survive — and so does execution history (\`_\`, \`__\`, \`Out[n]\`).
 
 - Top-level \`await\` works. So do IPython magics: \`%whos\` to see what you have bound, \`%timeit\`, \`%run script.py\`, \`%%writefile\`, \`obj?\` / \`obj??\`, \`%cd\`.
-- The cell's LAST expression is echoed back to you, like a REPL prompt — that is the return channel, and reaching for it first keeps cells short. A cell that is one tool call needs no \`print\` at all: end it with \`await read(file_path=p)\` and you get the result. Use \`print(...)\` when you want to RESHAPE what comes back — label several values, format a table, show a slice of something large — not to hand over a value the last line would have echoed anyway.
+- The cell's LAST expression is echoed back to you, like a REPL prompt — that is the return channel, and reaching for it first keeps cells short. Use \`print(...)\` when you want to RESHAPE what comes back — label several values, format a table, show a slice of something large — not to hand over a value the last line would have echoed anyway.
 - Mind what the last line evaluates TO. Ending on \`Path(p).write_text(text)\` echoes the byte count; ending on \`d[k] = v\` echoes nothing. Put the thing worth seeing last, or end with an explicit \`None\` when the cell has nothing to report.
 - Tools are awaitable functions: \`from __dsh__.tools import read\`, then \`await read(file_path=...)\`. Keyword arguments only. Each returns that tool's canonical JSON value. The import survives, so import once and reuse.
 - Compose them with ordinary Python — that is the whole point of this loop. Discover targets in code and feed them straight in rather than naming each one literally: \`for p in Path('src').rglob('*.py'): await read(file_path=p)\`, or \`await asyncio.gather(*(read(file_path=p) for p in paths))\`. Arguments are serialized for you, so \`Path\`, \`datetime\` and friends can be passed as they are.
 - You also have DIRECT filesystem access, and for bulk work it is the better tool: \`Path(p).read_text()\` is one syscall, while \`read\` is a full round-trip through the harness plus a row in the trajectory. Walking a tree, counting matches, reading fifty files to keep three — do it with \`pathlib\`/\`re\` and surface only the conclusion. Reach for the bridged \`read\` when you want what it adds on top: \`offset\`/\`limit\` windowing and its truncation budget for a file too big to hold, or \`read_image\`. An image cannot come back through the cell — a tool result carrying one is attached to the conversation AFTER the run, so call it, end the cell, and look at the image on your next step. What the cell itself receives is only the metadata (path, dimensions), which is not something you can read.
-- \`!uv pip install <pkg>\` installs into this interpreter's environment and the package imports in the same session. Shell escapes (\`!cmd\`) do not fail the cell on a non-zero exit — check the output, or use \`subprocess.run(..., check=True)\`.
+- \`!uv pip install <pkg>\` installs into this interpreter's environment and the package imports in the SAME CELL — no restart, no second cell to pick it up. Shell escapes (\`!cmd\`) do not fail the cell on a non-zero exit — check the output, or use \`subprocess.run(..., check=True)\`.
 - Delegating? A subagent runs in this same interpreter with its OWN globals, so it cannot see your variables. \`__dsh__.shared\` is the exception: set an attribute on it and every agent here can read that live object — hand over a dataframe or an index by name instead of describing it in the prompt.
 - A FAILED tool call raises \`ToolCallError\` (\`.tool_name\`, plus the message); catch it and continue.
-- Independent calls may overlap with \`asyncio.gather\`. Sequence dependent work with plain \`await\`.
-- ONLY the cell's output and its final expression come back to you. Tool results consumed inside the cell never enter the conversation, so filter and aggregate in code and surface just the conclusion.
+- Independent calls may overlap with \`asyncio.gather\`. Sequence dependent work with plain \`await\`. A gather hands back every answer in FULL, so the line AFTER it decides what the batch costs: end on what you pulled out of \`res\`, never on \`res\` itself.
+- ONLY the cell's output and its final expression come back to you. Tool results consumed inside the cell never enter the conversation, so filter and aggregate in code and surface just the conclusion. Don't know the shape yet? Ask for the SHAPE, not the payload — \`r.keys()\`, \`len(r["results"])\`, \`r["results"][0]\` — then extract on the next line.
 - A cell that raises returns the traceback and the session keeps every prior binding — fix it in the next cell rather than starting over.
 - Only \`await\` points are interruptible. Prefer async APIs over blocking ones, and avoid unbounded CPU loops: they can only be stopped by killing the interpreter, which loses all state.
 
@@ -116,27 +116,28 @@ function narrowed(node) {
 }
 
 /**
- * Project one tool schema onto the wire spec the kernel builds a binding from: dsh's description becomes the function's docstring, its parameters become a keyword-only signature. Parameter annotations are rendered here with dsh's own `jsonSchemaToPy`, and the return type comes from {@link renderOutputTypes}, so the kernel needs no JSON-Schema mapper of its own.
+ * Project one tool schema onto the wire spec the kernel builds a binding from: dsh's description becomes the function's docstring, its parameters become a keyword-only signature. Both the parameter annotations and the return type come from {@link renderTypes}, which reads them out of dsh's own render, so the kernel needs no JSON-Schema mapper of its own.
  *
  * The return type comes from the tool's own `output` schema — the shape of the canonical value the call actually resolves to. It is the one annotation a model cannot recover by reading harder: a parameter it gets wrong fails loudly at the call, while an unknown return shape is only discoverable by calling once and printing the result, which is a whole extra turn per tool.
  */
-function toolSpec(schema, returns) {
+function toolSpec(schema, returns, annotated) {
   const parameters = schema.parameters ?? {}
   const properties = parameters.properties ?? {}
   const required = new Set(Array.isArray(parameters.required) ? parameters.required : [])
   return {
     name: schema.name,
     doc: schema.description,
-    // Absent only if the render dropped this tool, which it does not: `renderOutputTypes` emits one
+    // Absent only if the render dropped this tool, which it does not: `renderTypes` emits one
     // entry per schema, and a schema with no `output` at all comes back as `Any` from there.
     returns: returns.get(schema.name) ?? 'Any',
-    params: Object.entries(properties).map(([name, node]) => ({
+    params: spellParams(Object.entries(properties).map(([name, node]) => ({
       name,
-      type: jsonSchemaToPy(narrowed(node)),
+      // `annotated` is dsh's own render of this parameter, read back from the block it names its classes in; `jsonSchemaToPy` is the fallback for what that render degrades — a `oneOf` at any property collapses the whole args type, and it has no name to give an object anyway.
+      type: annotated.get(name) ?? jsonSchemaToPy(narrowed(node)),
       required: required.has(name),
       // What the parameter MEANS, which its type cannot say — `queries` is `list[str]` either way, and only the prose says 1–4 of them. Rendered beside the parameter as a comment AND carried to the kernel, so `read?` agrees with the block instead of being the poorer of the two. `undefined` drops out of `JSON.stringify`, so a parameter without one costs the wire and `specsKey` nothing.
       doc: node?.description,
-    })),
+    }))),
   }
 }
 
@@ -164,8 +165,8 @@ export function toolSpecs(schemas) {
   // a tool whose own payload happens to be `{content: [...]}` is not wrapping anything, and
   // replacing its value with the joined text would change what it returns with nothing to say so.
   const envelopes = new Set(sorted.filter((schema) => mcpPayloadSchema(schema.output) !== null).map((schema) => schema.name))
-  const { returns, declarations } = renderOutputTypes(sorted)
-  return { specs: sorted.map((schema) => toolSpec(schema, returns)), declarations, envelopes }
+  const { returns, params, declarations } = renderTypes(sorted)
+  return { specs: sorted.map((schema) => toolSpec(schema, returns, params.get(schema.name) ?? new Map())), declarations, envelopes }
 }
 
 /**
@@ -201,7 +202,9 @@ let pythonEnv
 function renderEnvironment() {
   if (pythonEnv === undefined) return 'The session runs in its own Python interpreter, with `uv pip install <pkg>` available in a cell.'
   const where = pythonEnv.venv ? `in the environment at \`${pythonEnv.prefix}\`` : `at \`${pythonEnv.executable}\``
-  const head = `Python ${pythonEnv.version} ${where}, working directory \`${pythonEnv.cwd}\`. ` + '`!uv pip install <pkg>` installs there and imports immediately. '
+  // No working directory here: dsh states it in its own section, and `installs there` must point at the environment named just before it — with the cwd in between, `there` read as the cwd, which is the one place an install does NOT land.
+  // No install clause here either: the bullet list already carries it, and said it better — `installs there and imports immediately` never says immediately after WHAT, and reads as though the install does an import. Two statements of one fact is how the two drift. What this line is for is naming the environment; `nothing you install escapes` below already implies where an install goes.
+  const head = `Python ${pythonEnv.version} ${where}. `
   // Only true on the throwaway-venv route. Under `config.python` the interpreter is one the user pointed at — often their own project venv — and every clause of the sentence below is false there, while the prompt still invites the model to install into it.
   return pythonEnv.disposable
     ? `${head}That environment is this session's alone — it inherits the base packages, nothing you install escapes to the project or to another session, and it is discarded when the session ends.`
@@ -254,6 +257,41 @@ const serverName = (server, grouped) => (fold(server) !== server && grouped.has(
 /** A name this block can put in an `import`, a `def`, or a `TypedDict` field. */
 const isUsableName = (name) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && !PY_KEYWORDS.has(name)
 
+/** The 35 names a parameter genuinely cannot take — `keyword.kwlist`, verified to have 35 entries on 3.12, 3.13 and 3.14. The header's floor is open-ended, so a later release may add one; the suite catches that rather than this comment, by taking the list from the interpreter that is about to compile the block. The other four in {@link PY_KEYWORDS} are `keyword.softkwlist`: `_`, `case`, `match`, `type` — `def f(*, type: str)` compiles, and rejecting them cost a tool its whole signature over a parameter name as ordinary as `type`. They stay refused as TOOL names, where the block imports them and `type` would shadow the builtin for the rest of the session. (`type` only joined `softkwlist` in 3.12, which is where the header's floor is.) */
+const PY_HARD_KEYWORDS = new Set([...PY_KEYWORDS].filter((word) => !['_', 'case', 'match', 'type'].includes(word)))
+
+/**
+ * The name a parameter can be CALLED by, or `null` when Python has none to offer.
+ *
+ * A parameter name travels to the tool as a JSON key, so unlike a tool name this cannot simply be renamed: the kernel maps the spelling back before dispatch, and `raw` below is what it maps to. Two normalisations, mirroring the two shapes that occur: `-` is legal in an MCP name and in no identifier, and a hard keyword takes the trailing underscore Python programmers already write for it (PEP 8's `class_`).
+ */
+const paramName = (raw) => {
+  if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(raw)) return PY_HARD_KEYWORDS.has(raw) ? `${raw}_` : raw
+  const folded = fold(raw)
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(folded) && !PY_HARD_KEYWORDS.has(folded) ? folded : null
+}
+
+/**
+ * Spell every parameter of one tool, refusing any normalisation that would displace a sibling.
+ *
+ * The lesson from folding MCP names one level up: an alias must never take a name that something real answers to. A tool declaring both `file-path` and `file_path` keeps `file_path` meaning `file_path`, and the hyphenated one falls back to `**kwargs` rather than quietly stealing it.
+ */
+function spellParams(params) {
+  const taken = new Set(params.map((p) => p.name))
+  const claimed = new Set()
+  return params.map((p) => {
+    const name = paramName(p.name)
+    if (name === null || name === p.name) return p
+    // `raw` is the wire key, present only where the two differ — which is also how both halves tell a renamed parameter from one that simply cannot be spelled.
+    if (taken.has(name) || claimed.has(name)) return p
+    claimed.add(name)
+    return { ...p, name, raw: p.name }
+  })
+}
+
+/** Whether the block can put this parameter in a signature: it was renamed, or it needed no renaming. */
+const isSpelled = (p) => p.raw !== undefined || paramName(p.name) === p.name
+
 /** `mcp__calendar__list_events` -> `McpCalendarListEvents`, for naming that tool's declarations. */
 const pascal = (name) => name.split(/[_\-]+/).filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1)).join('')
 
@@ -269,8 +307,9 @@ const PROTOCOL_HEAD = 'class Tools(Protocol):\n'
 const PROTOCOL_TAIL = '\n\ntools: Tools'
 
 /**
- * dsh's own Code Mode render, read back for the two things `jsonSchemaToPy` cannot produce: a NAMED
- * `TypedDict` per output object, and the union of named branches a `oneOf` output resolves to.
+ * dsh's own Code Mode render, read back for the things `jsonSchemaToPy` cannot produce: a NAMED
+ * `TypedDict` per object — on either side of the call — and the union of named branches a `oneOf`
+ * output resolves to.
  *
  * `jsonSchemaToPy` is context-free and says so — "naming a `TypedDict` requires the render context
  * that `renderToolsSdkPy` supplies" — so with nowhere to hang a declaration it degrades every object
@@ -281,12 +320,18 @@ const PROTOCOL_TAIL = '\n\ntools: Tools'
  * exists to remove. `renderType`, the context-carrying core, is not exported and its `src/` is not
  * shipped, so `renderToolsSdkPy` is the only door to it.
  *
- * The context is therefore borrowed rather than rebuilt. Parameters are stripped before the call —
- * `{}` is the one input that renders as `Any` without allocating a class, so every class in the
- * returned block belongs to an OUTPUT — and descriptions are dropped so the `Tools` body is exactly
- * one line per tool. MCP envelopes are unwrapped first, because the cell receives the payload and
- * annotating the transport wrapper is accurate and useless: the model then hand-writes
- * `r["structuredContent"]["result"]`, and calls once just to learn that.
+ * The context is therefore borrowed rather than rebuilt, for both halves in ONE call — so dsh's own
+ * collision suffixing settles a parameter class and an output class that would otherwise pick the
+ * same name. Descriptions are dropped so the `Tools` body is exactly one line per tool. MCP envelopes
+ * are unwrapped first, because the cell receives the payload and annotating the transport wrapper is
+ * accurate and useless: the model then hand-writes `r["structuredContent"]["result"]`, and calls once
+ * just to learn that.
+ *
+ * The parameter side arrives as a `<Tool>Args` wrapper, dsh's one-dict-per-call convention. This
+ * block spells parameters out instead, so the wrapper is read for its members and then dropped,
+ * while anything it references stays. Two shapes still degrade and fall back to `jsonSchemaToPy`: a
+ * `oneOf` at any property collapses the whole args type, and so does a stray `$schema` key — which
+ * is why `narrowed` runs on parameters too, not only on outputs.
  *
  * Reading generated text back is the seam, and it buys the alternative's absence: the `Literal`s,
  * nested classes, collision suffixes and Unicode identifier rules stay dsh's own instead of a second
@@ -294,28 +339,50 @@ const PROTOCOL_TAIL = '\n\ntools: Tools'
  * miss and every tool falls back to `Any` — a visible annotation the suite asserts against, not a
  * silently wrong one.
  *
- * @returns the return annotation per tool name, and the class declarations they reference as text.
+ * @returns the return annotation per tool name, the parameter annotations per tool name, and the class declarations both reference as text.
  */
-function renderOutputTypes(sorted) {
+function renderTypes(sorted) {
   const declared = (schema) => {
     const payload = mcpPayloadSchema(schema.output)
     // An envelope with no declared payload resolves to the text blocks joined, so it really is a `str`.
     return narrowed(payload === null ? schema.output : (payload ?? { type: 'string' }))
   }
-  const text = renderToolsSdkPy(sorted.map((schema) => ({ name: schema.name, parameters: {}, output: declared(schema) })))
+  // Parameters go through `narrowed` for the same reason outputs do, plus one of their own: a `$schema` key — which real MCP catalogues carry — makes dsh degrade the WHOLE args type to `Any`, taking every sibling parameter's annotation down with it. Dropping it is the difference between `window: ReadArgsWindow` and `window: dict[str, Any]`.
+  const text = renderToolsSdkPy(sorted.map((schema) => ({ name: schema.name, parameters: narrowed(schema.parameters ?? {}), output: declared(schema) })))
   const at = text.indexOf(ERROR_STUB)
   const to = text.indexOf(PROTOCOL_HEAD, at)
   const returns = new Map()
+  const wrapperOf = new Map()
   for (const line of text.slice(to + PROTOCOL_HEAD.length, text.indexOf(PROTOCOL_TAIL, to)).split('\n')) {
     // Two shapes, because dsh routes a name Python cannot take to a subscript COMMENT rather than a
     // method. Both are read: this block reaches such a tool through `getattr`, so its return type is
     // as real as any other's.
-    const method = / {4}async def ([^(]+)\(self, args: Any\) -> (.+): \.\.\.$/.exec(line)
-    if (method !== null) { returns.set(method[1], method[2]); continue }
-    const subscript = / {4}# tools\[(".*")\]\(args: Any\) -> (.+)$/.exec(line)
-    if (subscript !== null) returns.set(JSON.parse(subscript[1]), subscript[2])
+    const method = / {4}async def ([^(]+)\(self, args: ([^)]+)\) -> (.+): \.\.\.$/.exec(line)
+    if (method !== null) { returns.set(method[1], method[3]); wrapperOf.set(method[1], method[2]); continue }
+    const subscript = / {4}# tools\[(".*")\]\(args: ([^)]+)\) -> (.+)$/.exec(line)
+    if (subscript !== null) { const name = JSON.parse(subscript[1]); returns.set(name, subscript[3]); wrapperOf.set(name, subscript[2]) }
+  }
+  // `<Tool>Args` exists for dsh's calling convention — one `args` dict per call. This block spells
+  // parameters out instead, so the wrapper is read for its members and then dropped, while anything
+  // it REFERENCES (a nested object's own class) is declared separately and stays. Reading it back is
+  // what makes `window: ReadArgsWindow` possible at all: `jsonSchemaToPy` is context-free and has
+  // nowhere to hang a declaration, so on its own it degrades every parameter object to
+  // `dict[str, Any]` — the same erasure #16 fixed on the return side, still standing on this one.
+  const blocks = text.slice(at + ERROR_STUB.length, to).split('\n\n').filter((block) => block.trim() !== '')
+  const wrappers = new Set(wrapperOf.values())
+  const isWrapper = (block) => wrappers.has(/^class (\w+)\(TypedDict\):$/.exec(block.split('\n')[0])?.[1])
+  const members = new Map()
+  for (const block of blocks.filter(isWrapper)) {
+    const fields = new Map()
+    for (const line of block.split('\n').slice(1)) {
+      const field = / {4}(\w+): (.+)$/.exec(line)
+      // `NotRequired[...]` is what `required` already says here, and the signature spells optionality with a default instead.
+      if (field !== null) fields.set(field[1], /^NotRequired\[(.+)\]$/.exec(field[2])?.[1] ?? field[2])
+    }
+    members.set(/^class (\w+)/.exec(block)[1], fields)
   }
-  return { returns, declarations: text.slice(at + ERROR_STUB.length, to).trimEnd() }
+  const params = new Map([...wrapperOf].map(([tool, wrapper]) => [tool, members.get(wrapper) ?? new Map()]))
+  return { returns, params, declarations: blocks.filter((block) => !isWrapper(block)).join('\n\n').trimEnd() }
 }
 
 /**
@@ -352,24 +419,34 @@ export function renderToolsSection(schemas) {
   const docstring = (doc) => {
     if (!doc) return ['    ...']
     const text = doc.trim().replaceAll('\\', '\\\\').replaceAll('"""', '\\"\\"\\"')
-    const lines = text.split('\n')
+    // Split on every terminator Python's tokenizer honours, not just `\n`: CPython applies universal-newline translation to source, so a lone `\r` reaching the render becomes a real line break. Inside a COMMENTED MCP entry that break escapes the `# ` prefix and the rest of the description becomes live code.
+    //
+    // EXACTLY these three, which is narrower than it looks like it should be. `str.splitlines()` splits on eight more (`\v`, `\f`, `\x1c`-`\x1e`, `\x85`, `\u2028`, `\u2029`) and PCRE's `\R` on five of those — and every one of them stays INSIDE a `#` comment as far as the tokenizer is concerned, verified by compiling `# comment<ch>x = 1`. Widening to either would break descriptions apart at characters that never needed it.
+    const lines = text.split(/\r\n?|\n/)
     return lines.length === 1 ? [`    """${lines[0]}"""`] : ['    """', ...lines.map((line) => `    ${line}`.trimEnd()), '    """']
   }
   // A `#` comment cannot span lines, so a description that carries newlines is collapsed rather than emitted: left alone its second line parses as code.
-  const trailing = (doc) => (doc ? `  # ${doc.trim().replace(/\s*\n\s*/g, ' ')}` : '')
+  const trailing = (doc) => (doc ? `  # ${doc.trim().replace(/\s*(?:\r\n?|\n)\s*/g, ' ')}` : '')
   /** @returns the lines to emit, and — separately — the type expressions they spell, which is what the `typing` import is derived from. Kept apart because prose is now emitted too: a description mentioning "Any file" must not import `Any`. */
   const signature = (spec) => {
     const body = docstring(spec.doc)
-    // The same rule applies one level down, and used to not be applied at all: `file-path` is routine for MCP tools, and one such PARAMETER made every other tool's signature unusable too. The binding still takes it — the kernel folds unnameable parameters into `**kwargs` — so the tool stays importable and only its signature goes vague; `name?` still shows the real one.
-    if (!spec.params.every((p) => isUsableName(p.name))) {
-      return { lines: [`async def ${spec.name}(**kwargs: Any) -> ${spec.returns}:  # not every parameter name can be spelled here; see ${spec.name}?`, ...body], types: ['Any', spec.returns] }
-    }
-    const types = [spec.returns, ...spec.params.map((p) => p.type)]
+    // One unspellable PARAMETER used to cost the tool its whole signature — `file-path` is routine one level up, so it is routine here. Now only that parameter goes to `**kwargs`, which is what the kernel has always done with it: the two halves show the same picture instead of the block being the vaguer one.
+    const named = spec.params.filter((p) => isSpelled(p))
+    const rest = spec.params.filter((p) => !isSpelled(p))
+    const types = [spec.returns, ...named.map((p) => p.type), ...(rest.length === 0 ? [] : ['Any'])]
     // `async def f(*, ) -> T` is still a SyntaxError, which is why a parameterless tool emits no `*`.
     if (spec.params.length === 0) return { lines: [`async def ${spec.name}() -> ${spec.returns}:`, ...body], types }
     // One parameter per line, so each can carry what it MEANS beside what it is: `queries` is `list[str]` either way, and only the comment says 1–4 of them.
-    const fields = spec.params.map((p) => `    ${p.name}: ${p.type}${p.required ? '' : ' = ...'},${trailing(p.doc)}`)
-    return { lines: [`async def ${spec.name}(`, '    *,', ...fields, `) -> ${spec.returns}:`, ...body], types }
+    const fields = named.map((p) => `    ${p.name}: ${p.type}${p.required ? '' : ' = ...'},${trailing(p.doc)}`)
+    // Named, because nothing else lists them and a required argument the model never sees is one the host rejects it for. `**kwargs` takes no trailing comma, and a lone `*` before it is a SyntaxError — hence the two shapes below.
+    if (rest.length > 0) {
+      // The overflow must not collide with a parameter that is really called `kwargs`, or the block stops compiling — for every tool, not just this one. Same rule the kernel uses for its own overflow, so the two agree without coordinating.
+      let overflow = 'kwargs'
+      while (named.some((p) => p.name === overflow)) overflow = `_${overflow}`
+      fields.push(`    **${overflow}: Any  # spell as dict keys: ${rest.map((p) => JSON.stringify(p.name)).join(', ')}`)
+    }
+    const open = named.length === 0 ? [`async def ${spec.name}(`] : [`async def ${spec.name}(`, '    *,']
+    return { lines: [...open, ...fields, `) -> ${spec.returns}:`, ...body], types }
   }
   // `ToolCallError` leads the import because the instructions tell the model to catch it; without it here the natural `except ToolCallError` NameErrors on the failure path, masking the tool failure it was meant to handle. It also keeps the line valid when no tool is importable.
   // The declarations are stubs, not runtime objects — nothing constructs them — so the import line
@@ -387,18 +464,19 @@ export function renderToolsSection(schemas) {
   // A blank line between definitions, or a docstring runs straight into the next `async def`.
   const spaced = (blocks) => blocks.flatMap((block, index) => (index === 0 ? block : ['', ...block]))
   const nativeBlock = listing(TOOLS_MODULE, spaced(nativeSigs.map((sig) => sig.lines)))
-  // Commented, and spelled the way the call site spells them, because these names are NOT bound at
-  // the top level — only `mcp` is. A bare `async def read(...)` under a server header claims a
-  // top-level `read` that does not exist, and worse, it BINDS one: three tools named `read` (a
-  // native one and two servers') left the last stub shadowing the imported function, so the block
-  // executed as written broke the very tool its first section had just declared.
+  // Rendered exactly like the native ones. These names are not bound at the top level — only `mcp`
+  // is — and the header above each section is what says so, the same way it does for `__dsh__.tools`.
+  // Commenting them out was meant to stop a bare `async def read(...)` from shadowing the imported
+  // `read`, but the native section is bare too and shadows it just as thoroughly: running this block
+  // is not something the shape of the MCP half can make safe. It is a signature listing, read for
+  // the signatures.
   // A server whose every tool name Python refuses gets no section: nothing here would be callable
   // as written, and the `getattr` line below is where those tools actually live.
   const mcpSigs = servers.flatMap(([server, tools]) => tools.filter((t) => isUsableName(fold(t.tool))).sort(by((t) => t.tool))
     .map((t) => ({ server, ...signature({ ...t, name: fold(t.tool) }) })))
   const mcpBlock = servers.flatMap(([server]) =>
     listing(`${TOOLS_MODULE}.mcp.${serverName(server, grouped)}`, spaced(mcpSigs.filter((sig) => sig.server === server)
-      .map((sig) => sig.lines.map((line, index) => `# ${index === 0 ? line.replace(/^async def /, `mcp.${serverName(server, grouped)}.`) : line}`.trimEnd())))))
+      .map((sig) => sig.lines))))
   const signatures = nativeBlock.concat(mcpBlock)
   const classes = declarations === '' ? [] : ['', ...declarations.split('\n')]
   // Whatever the emitted lines actually spell, rather than a condition per symbol: the conditions
@@ -444,12 +522,19 @@ export function renderToolsSection(schemas) {
   return lines.join('\n')
 }
 
-/** Flatten model-facing content blocks to the text a program-visible error carries. */
+/** Flatten model-facing content blocks when an MCP result has no structured payload. */
 function contentText(content) {
   if (!Array.isArray(content)) return ''
   return content.filter((block) => block?.type === 'text').map((block) => block.text).join('\n\n')
 }
 
+/** @internal exported for the suite. The program-visible reply for one completed sub-call. */
+export function toolCallReply(outcome, unwrapMcp = false) {
+  if (outcome.isError) return { ok: false, message: outcome.error.message }
+  const unwrapped = unwrapMcp ? mcpPayload(outcome.value) : undefined
+  return { ok: true, value: unwrapped === undefined ? outcome.value : unwrapped.value }
+}
+
 /**
  * Shape one finished cell into the model's observation.
  *
@@ -592,10 +677,7 @@ export function apply(ctx, config = {}) {
       for (const context of outcome.additionalContexts ?? []) exec.deferContext(context)
       // `=== undefined` rather than `??`: a payload that IS `null` is the server's answer, and
       // falling back to the wrapper there would hand the cell the one shape it was promised not to see.
-      const unwrapped = entry.envelopes.get(from)?.has(name) ? mcpPayload(outcome.value) : undefined
-      return outcome.isError
-        ? { ok: false, message: contentText(outcome.content) || 'tool call failed' }
-        : { ok: true, value: unwrapped === undefined ? outcome.value : unwrapped.value }
+      return toolCallReply(outcome, entry.envelopes.get(from)?.has(name))
     } catch (error) {
       session?.append('tool/code-dispatch', { ...trace, isError: true, content: [{ type: 'text', text: String(error?.message ?? error) }] })
       throw error

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-py-codeact",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "CodeAct agent loop for the DeepSeek Harness: a persistent IPython session as the model's action space, with harness tools bridged in as a virtual `__dsh__.tools` module.",
   "license": "MIT",
   "repository": {

package/py/kernel.py

@@ -211,8 +211,11 @@ def _make_binding(bridge: Bridge, spec):
     """One tool as a real `async def`: dsh's description becomes its docstring and its parameters become a keyword-only signature, so `read?`, `help(read)`, and tab-completion all work inside the REPL. The annotations arrive pre-rendered from the host, which projects them with dsh's own `jsonSchemaToPy` — no second mapper to drift out of sync."""
     name = spec["name"]
 
+    # A parameter name travels to the tool as a JSON key, so a renamed one has to travel back: the block spells `file_path` and `from_`, the tool still expects `file-path` and `from`. A raw key passed straight through is left alone, which is what a cell written before the rename does.
+    renames = {p["name"]: p["raw"] for p in spec.get("params") or [] if p.get("raw")}
+
     async def call(**kwargs):
-        return await bridge.call(name, kwargs)
+        return await bridge.call(name, {renames.get(key, key): value for key, value in kwargs.items()} if renames else kwargs)
 
     call.__name__ = name if name.isidentifier() else "call"
     call.__qualname__ = f"__dsh__.tools.{name}"