dsh-py-codeact 0.2.1 → 0.2.3

package/README.md

@@ -52,7 +52,7 @@ A dunder-named package reads as harness-owned, survives `%reset`, and leaves the
 
 ```
 In [1]: read?
-Signature: read(*, file_path: 'str', offset: 'int' = Ellipsis, limit: 'int' = Ellipsis) -> 'str'
+Signature: read(*, file_path: 'str', offset: 'int' = ..., limit: 'int' = ...) -> 'str'
 Docstring: Read a file from the workspace. Results include line numbers…
 ```
 
@@ -60,36 +60,61 @@ That is why the prompt block carries signatures only — the descriptions are on
 
 The **return** type comes from the tool's own `output` schema, by way of `ctx.tools.sdkSchemas(scope)` — the projection that carries it. It is the one annotation the model cannot recover by reading harder: a wrong argument fails loudly at the call, while an unknown return shape is only discoverable by calling once and printing the result, which costs a whole turn per tool. A tool that declares no output schema still renders `Any`; claiming a type nobody declared would be worse than admitting ignorance.
 
-Each object in that schema whose keys — and whose own generated class name — Python can take is declared as a named `TypedDict` above the signatures, because for an MCP tool the flat form is not merely vague — it is the whole message. dsh's MCP client resolves a call to the **envelope** `{ content, structuredContent }` and declares exactly that as the tool's output, so a model told only `dict[str, Any]` is not told the envelope exists: it reaches for the payload directly, gets nothing, and spends the turn printing the result to find the wrapper — the exact cost this annotation is here to remove.
+Each object in that schema whose keys — and whose own generated class name — Python can take is declared as a named `TypedDict` above the signatures. For a bridged MCP tool the schema described here is the payload, not the transport wrapper — see below; `dict[str, Any]` would say a dict arrives without saying which keys, which is the one thing a return annotation exists to say.
 
 ```python
-class McpCalendarListEventsOutputStructuredContent(TypedDict):
-    result: str
-
 class McpCalendarListEventsOutput(TypedDict):
-    content: list[Any]
-    structuredContent: McpCalendarListEventsOutputStructuredContent
+    result: str
 
-async def mcp__calendar__list_events(*, calendar_id: str) -> McpCalendarListEventsOutput: ...
+class _McpCalendar(Protocol):
+    async def list_events(self, *, calendar_id: str) -> McpCalendarListEventsOutput: ...
 ```
 
 `jsonSchemaToPy` cannot do this and says so — it is context-free, and naming a `TypedDict` needs the render context `renderToolsSdkPy` supplies. That renderer is not reusable here: it emits a whole document in Code Mode's own `tools.name(args)` contract. So only the object and array branches are handled locally, every leaf still going through `jsonSchemaToPy` — a place to hang the names, not a second JSON-Schema mapper. The binding set is resent with every cell, because restrictions and mid-conversation tool changes can move a tool in or out between calls.
 
+### The MCP wrapper does not reach the cell
+
+dsh's MCP client resolves a call to `{ content, structuredContent? }` — the protocol's block array plus the server's own payload — and declares exactly that as the tool's output. That wrapper is transport, not API: `content`'s text duplicates the payload, and an image inside it is re-attached to the conversation separately, so a cell can do nothing with it. Handed the wrapper, a model writes `r["structuredContent"]["result"]` — and spends a call discovering it has to.
+
+So the bridge unwraps, and the signature describes what the cell actually receives:
+
+```python
+async def mcp__review__search(*, q: str) -> McpReviewSearchOutput: ...   # the payload, not the wrapper
+async def mcp__email__ping() -> str: ...                                 # no declared payload: the text blocks, joined
+```
+
+A server that declares no output schema is the common case in the wild, and its result really is just text — one text block, in every one of the 4142 MCP results measured across six trials, which is why this is a `str` and not a `list[str]` that would cost an `r[0]` at every call site to preserve a boundary that never appears. A result carrying no text block at all resolves to the empty string: an image there is re-attached to the conversation and read on the next step, so there was never anything for the cell to receive. One divergence is possible and belongs to the server: a tool that declares an output schema but omits `structuredContent` on some call resolves to that call's text, where the signature promised the payload type.
+
+Unwrapping keys off the tool's declared output schema, not off the value that comes back: a tool whose own payload happens to be `{content: [...]}` is not wrapping anything, and replacing its value with joined text would change what that tool returns with nothing to say so. This deliberately differs from Code Mode, which hands the whole envelope to `tools.name(args)`.
+
 ### MCP tools work, with nothing special
 
-MCP servers register into the same `ctx.tools` registry as everything else, so they arrive in `__dsh__.tools` like any other binding and dispatch through the same pipeline:
+MCP servers register into the same `ctx.tools` registry as everything else, so they arrive in `__dsh__.tools` like any other binding and dispatch through the same pipeline. They are *presented* grouped, under one `mcp`:
 
 ```python
-from __dsh__.tools import mcp__gh__github_graphql as gh
+from __dsh__.tools import mcp
 
-data = await gh(query="{ viewer { login } }")
+data = await mcp.gh.github_graphql(query="{ viewer { login } }")
 ```
 
+dsh names them `mcp__<server>__<rawName>`, and with a hundred mounted that import line was most of the prompt block while every call site respelled its server. The flat names stay bound — `mcp` is how they are shown, not what they are — so a cell written before this still runs, `import *` still binds them, and only the listings drop them. A name the grouping cannot serve is still shown: dsh hashes a public name that needed normalising and the cut can land before the second `__`, and a raw name that is a true dunder is refused by `__getattr__`; either way the flat name is the only one that works. They are kept out of `dir(__dsh__.tools)` for the same reason the block stopped printing them; a name the grouping cannot reach (dsh hashes a public name that needed normalising, and the cut can land before the second `__`) stays listed, because `mcp` is not another way to say it. The block declares the grouping as `Protocol` stubs, one per server, which is the shape dsh's own SDK renderer uses for the same problem.
+
+It is a real package, so a server can be imported as a module — which reads better than `mcp.` at every call site when a cell leans on one server:
+
+```python
+from __dsh__.tools.mcp.calendar import list_events, create_event
+from __dsh__.tools.mcp import calendar          # or the server itself
+```
+
+The deep form is why each server gets a `sys.modules` entry of its own: `__getattr__` can serve `from __dsh__.tools.mcp import calendar`, but not `from __dsh__.tools.mcp.calendar import list_events` — the import machinery looks that one up as a module. No meta path finder is needed; registration is enough.
+
+`mcp` and its server modules are live views of the catalogue, not snapshots of the cell they were imported in: a restriction or a reconnecting server moves tools in and out between calls, and unlike a single tool the model has no reason to ever import the namespace twice. (A name pulled OUT with `from ... import` is a snapshot, as it is for any Python import.) The name is reserved — a native tool called `mcp` is not bound.
+
 dsh's MCP client is explicitly aware of this route — its canonical value "retains the complete JSON MCP blocks and optional structured content for programmatic and Code Mode callers" — and the sub-call logs a `SUBTOOL` row like any other.
 
 Worth contrasting: Anthropic's server-side [programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) is *not* compatible with MCP tools. Owning the bridge host-side is what buys this.
 
-(A tool whose name is not a valid Python identifier cannot be `import`ed, but is still reachable as `getattr(__dsh__.tools, "odd-name")`. dsh's MCP naming — `mcp__<server>__<tool>` — always is one.)
+(A tool whose name is not a valid Python identifier cannot be `import`ed, but is still reachable with `getattr` — `getattr(__dsh__.tools, "odd-name")`, or one level deeper for an MCP tool, `getattr(mcp.notion, "API-patch-block-children")`. A raw MCP name is a routine place to find a hyphen.)
 
 ## Exclusive mode
 
@@ -163,7 +188,7 @@ Sub-dispatches carry the outer execution's `parent` token, so they re-enter the
 - **Redundant-import hints.** When an `import` rebinds a name to the object it already held, the result carries `` `json` is already imported in this session — no need to re-import it. `` A model driving a persistent REPL re-imports constantly; telling it is cheaper than letting it burn a line every cell. (Implemented with a `dict` subclass that watches top-level `STORE_NAME` and checks the preceding opcode was `IMPORT_NAME`/`IMPORT_FROM`, so `x = x` does not trip it.)
 - **Readable reprs.** `objprint` + IPython's `pretty` for objects whose own `__repr__` is `object.__repr__` — an agent reading values needs structure, not `<Foo object at 0x…>`.
 - **Tagged observations.** `<stdout>`, `<stderr>`, `<return>`, `<traceback>`, `<note>` — with four things possibly present at once, the model needs to know which is which. A plain successful value stays bare.
-- **Introspection over prompt text.** `read?` for one tool's full description, `dir(__dsh__.tools)` for the whole list, `%whos` for its own bindings.
+- **Introspection over prompt text.** `read?` for one tool's full description, `dir(__dsh__.tools)` for the list — `mcp` rather than the hundred flat names under it, matching what the block printed — then `dir(mcp)` and `dir(mcp.<server>)` for those, and `%whos` for its own bindings. `__all__` is left alone: it is what `import *` binds, not what the model is shown. What it introspects matches what the block showed it: the listing carries `mcp` rather than the hundred flat names under it, and an optional parameter renders `= ...` there as it does here — `inspect.signature` uses `repr`, and `repr(...)` is `Ellipsis`, which is what `read?` used to say.
 
 ## Cancellation
 

package/lib/index.js

@@ -62,6 +62,32 @@ Your action space is Python. Each call runs one cell in a **persistent IPython s
 
 The available tools:`
 
+/**
+ * The wrapper dsh's MCP client puts around every result: `{ content, structuredContent? }`, with
+ * `content` the protocol's block array and `structuredContent` the server's own payload. Detected
+ * by shape rather than by an `mcp__` name, because the shape IS the declared contract — the client
+ * builds exactly this schema, `additionalProperties: false` and all.
+ *
+ * @returns the payload's schema when the server declares one, `null` when this is not an envelope,
+ *   and `undefined` for an envelope carrying only text.
+ */
+function mcpPayloadSchema(schema) {
+  if (schema?.type !== 'object' || schema.additionalProperties !== false) return null
+  const keys = Object.keys(schema.properties ?? {})
+  if (keys.length !== 2 || !keys.includes('content') || !keys.includes('structuredContent')) return null
+  if (schema.properties.content?.type !== 'array') return null
+  return (schema.required ?? []).includes('structuredContent') ? schema.properties.structuredContent : undefined
+}
+
+/** @internal exported for the suite. The same wrapper at run time. A value is only unwrapped when it carries nothing but the wrapper's own keys. */
+export function mcpPayload(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const keys = Object.keys(value)
+  if (!keys.includes('content') || !Array.isArray(value.content)) return undefined
+  if (keys.some((k) => k !== 'content' && k !== 'structuredContent')) return undefined
+  return 'structuredContent' in value ? { value: value.structuredContent } : { value: contentText(value.content) }
+}
+
 /**
  * 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. Annotations are rendered here with dsh's own `jsonSchemaToPy`, so the kernel needs no second JSON-Schema mapper.
  *
@@ -75,7 +101,10 @@ function toolSpec(schema, declarations) {
     name: schema.name,
     doc: schema.description,
     // `output` is absent only if the caller passed a `schemas()` projection; `sdkSchemas()` always carries it.
-    returns: schema.output === undefined ? 'Any' : declareType(schema.output, `${pascal(schema.name)}Output`, declarations),
+    // An MCP tool is annotated by what the CELL receives, which is the payload the bridge unwraps
+    // to — never the transport wrapper. Describing the wrapper is accurate and useless: the model
+    // then hand-writes `r["structuredContent"]["result"]`, and calls once just to learn that.
+    returns: schema.output === undefined ? 'Any' : mcpReturn(schema, declarations),
     params: Object.entries(properties).map(([name, node]) => ({
       name,
       type: jsonSchemaToPy(node),
@@ -95,11 +124,41 @@ function toolSpec(schema, declarations) {
  */
 function toolSpecs(schemas) {
   const declarations = new Map()
-  return { specs: [...schemas].sort(byName).map((schema) => toolSpec(schema, declarations)), declarations }
+  // The kernel reserves `mcp` for the namespace, so a tool of that name is never bound. Dropped
+  // here rather than at the render, which is downstream of the declarations: one with an object
+  // output still had its `TypedDict` emitted, referenced by nothing.
+  const sorted = [...schemas].filter((schema) => schema.name !== 'mcp').sort(byName)
+  // Which tools DECLARE the wrapper. Unwrapping keys off this rather than the returned value:
+  // 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))
+  return { specs: sorted.map((schema) => toolSpec(schema, declarations)), declarations, envelopes }
+}
+
+/** The annotation for one tool's output: an MCP payload if it is an envelope, else the schema as declared. */
+function mcpReturn(schema, declarations) {
+  const payload = mcpPayloadSchema(schema.output)
+  if (payload === null) return declareType(schema.output, `${pascal(schema.name)}Output`, declarations)
+  // An envelope with no declared payload resolves to the text blocks joined, so it really is a `str`.
+  return payload === undefined ? 'str' : declareType(payload, `${pascal(schema.name)}Output`, declarations)
+}
+
+/**
+ * `mcp__calendar__list_events` -> `{ server: 'calendar', tool: 'list_events' }`, matching the
+ * kernel's own split. Only the first two separators are consumed: dsh's name is
+ * `mcp__<serverName>__<rawName>` and a raw name may itself contain `__`.
+ */
+function splitMcp(name) {
+  if (!name.startsWith('mcp__')) return null
+  const rest = name.slice(5)
+  const at = rest.indexOf('__')
+  if (at <= 0 || at + 2 >= rest.length) return null
+  return { server: rest.slice(0, at), tool: rest.slice(at + 2) }
 }
 
 /** Deterministic (lexicographic) order, so an unchanged tool set renders byte-identically. */
-const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
+const by = (key) => (a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0)
+const byName = by((spec) => spec.name)
 
 /** The kernel's own wording for a shell whose previous cell has not finished. Matched, not parsed: it is the one failure that leaves the bindings uninstalled. */
 const KERNEL_BUSY = 'kernel busy: a previous cell is still running'
@@ -195,45 +254,105 @@ export function renderToolsSection(schemas) {
   // MCP tools are named `mcp__<server>__<rawName>` over a `[A-Za-z0-9_-]` alphabet, so hyphens are routine — and legal nowhere in `import` or `def`. One such tool used to make the ENTIRE block a SyntaxError, so not a single line in it could be copied, with nothing saying why.
   //
   // A keyword is the same failure wearing a legal shape: `class` and `None` match the identifier pattern and then break `import` and `def` just as hard. `_` and the soft keywords (`match`, `case`, `type`) are in the list because they are legal identifiers everywhere EXCEPT where this block puts them.
-  const importable = specs.filter((spec) => isUsableName(spec.name))
-  const awkward = specs.filter((spec) => !isUsableName(spec.name))
-  const signature = (spec) => {
+  // MCP tools are grouped under one `mcp` binding instead of being listed individually. With a
+  // hundred of them the import line was most of this block, and `mcp__calendar__list_events`
+  // carried its server in the name at every call site; `mcp.calendar.list_events` says the same
+  // thing once. The flat names stay bound — this is how they are PRESENTED, not what they are.
+  const grouped = new Map()
+  const plain = []
+  for (const spec of specs) {
+    const parts = splitMcp(spec.name)
+    if (parts === null) { plain.push(spec); continue }
+    if (!grouped.has(parts.server)) grouped.set(parts.server, [])
+    grouped.get(parts.server).push({ ...spec, tool: parts.tool, server: parts.server })
+  }
+  const importable = plain.filter((spec) => isUsableName(spec.name))
+  const awkward = plain.filter((spec) => !isUsableName(spec.name))
+  // A server or tool whose name Python cannot take keeps its `getattr` route, one level deeper.
+  const servers = [...grouped].filter(([server]) => isUsableName(server)).sort(by(([server]) => server))
+  const oddMcp = [...grouped].flatMap(([server, tools]) =>
+    (isUsableName(server) ? tools.filter((t) => !isUsableName(t.tool)) : tools).map((t) => ({ server, tool: t.tool, usableServer: isUsableName(server) })))
+  // `self` is a parameter here rather than a splice into the finished line, because a Protocol
+  // method needs it in front of BOTH shapes below — and `async def f(*, ) -> T` is a SyntaxError:
+  // a `*` needs at least one name after it, and a parameterless tool takes no keywords at all.
+  // `head` has NO default, so this can never be handed to `.map` — whose second argument is the
+  // index, which a default would silently accept and which is not iterable.
+  const signature = (spec, head) => {
     // 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 `async def ${spec.name}(**kwargs: Any) -> ${spec.returns}: ...  # parameter names are not all valid Python; see ${spec.name}?`
+    if (!spec.params.every((p) => isUsableName(p.name))) return `async def ${spec.name}(${[...head, '**kwargs: Any'].join(', ')}) -> ${spec.returns}: ...  # parameter names are not all valid Python; see ${spec.name}?`
     const fields = spec.params.map((p) => (p.required ? `${p.name}: ${p.type}` : `${p.name}: ${p.type} = ...`))
-    // `async def f(*, ) -> T` is a SyntaxError: a `*` needs at least one name after it, and a parameterless tool takes no keywords at all.
-    return `async def ${spec.name}(${fields.length === 0 ? '' : `*, ${fields.join(', ')}`}) -> ${spec.returns}: ...`
+    return `async def ${spec.name}(${[...head, ...(fields.length === 0 ? [] : [`*, ${fields.join(', ')}`])].join(', ')}) -> ${spec.returns}: ...`
   }
   // `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
   // lists exactly what the render used. `Any` has always been reachable from a signature
   // (`**kwargs: Any`, and any degraded annotation) and was never imported at all.
-  const signatures = importable.map(signature)
+  const signatures = importable.map((spec) => signature(spec, []))
+  // A Protocol, not a class of `staticmethod`s: `mcp` is an INSTANCE, so `mcp.calendar.list_events(...)`
+  // binds `self` on its own and the stub says exactly what the call site does. It is also the shape
+  // dsh's own SDK renderer uses for the same problem.
+  const method = (spec) => `    ${signature({ ...spec, name: spec.tool }, ['self'])}`
+  const protocols = servers.flatMap(([server, tools]) => {
+    const body = tools.filter((t) => isUsableName(t.tool)).sort(by((t) => t.tool)).map(method)
+    // A server whose every tool name Python refuses would otherwise emit a class with an empty
+    // body — a SyntaxError that takes the whole block with it. The attribute still has to exist:
+    // the `getattr` line below reaches its tools through it.
+    return ['', `class _Mcp${pascal(server)}(Protocol):`, ...(body.length === 0 ? ['    ...'] : body)]
+  })
+  const mcpBlock = servers.length === 0 ? [] : [
+    ...protocols,
+    '',
+    'class _Mcp(Protocol):',
+    ...servers.map(([server]) => `    ${server}: _Mcp${pascal(server)}`),
+    '',
+    'mcp: _Mcp',
+  ]
   const classes = [...declarations].flatMap(([name, body]) => ['', `class ${name}(TypedDict):`, ...body.split('\n')])
   const typing = [
     // Whole identifiers: `AnyReportOutput` is a class name, not a use of `Any`, and a bare
     // `includes` imports a symbol a tool can spell into existence without ever needing it.
-    signatures.concat(classes).some((line) => /\bAny\b/.test(line)) && 'Any',
+    signatures.concat(classes, mcpBlock).some((line) => /\bAny\b/.test(line)) && 'Any',
     classes.some((line) => line.includes('NotRequired[')) && 'NotRequired',
     declarations.size > 0 && 'TypedDict',
   ].filter(Boolean)
+  const protocolImport = servers.length === 0 ? [] : ['Protocol']
   const lines = [
     INSTRUCTIONS,
     '',
     renderEnvironment(),
     '',
     '```python',
-    ...(typing.length === 0 ? [] : [`from typing import ${typing.join(', ')}`]),
-    `from __dsh__.tools import ToolCallError${importable.map((spec) => `, ${spec.name}`).join('')}`,
+    ...(typing.concat(protocolImport).length === 0 ? [] : [`from typing import ${typing.concat(protocolImport).sort().join(', ')}`]),
+    // `grouped`, not `servers`: a server whose own name Python refuses has no Protocol stub, but its
+    // tools are still reached through `mcp` — the `getattr` line below names it. Keyed on the stubs,
+    // a catalogue of nothing but such servers advertised `getattr(getattr(mcp, …))` without ever
+    // importing `mcp`. The kernel binds it whenever an MCP tool exists, which is this condition.
+    `from __dsh__.tools import ToolCallError${grouped.size === 0 ? '' : ', mcp'}${importable.map((spec) => `, ${spec.name}`).join('')}`,
     ...classes,
+    ...mcpBlock,
     '',
     ...signatures,
     '```',
   ]
+  if (oddMcp.length > 0) {
+    lines.push('', `Under \`mcp\`, but not valid Python identifiers — reach these with \`getattr\`: ${oddMcp.map(({ server, tool, usableServer }) => (usableServer ? `\`getattr(mcp.${server}, ${JSON.stringify(tool)})\`` : `\`getattr(getattr(mcp, ${JSON.stringify(server)}), ${JSON.stringify(tool)})\``)).join(', ')}.`)
+  }
   if (awkward.length > 0) {
     lines.push('', `Not valid Python identifiers — reach these with \`getattr\`: ${awkward.map((spec) => `\`getattr(__dsh__.tools, ${JSON.stringify(spec.name)})\``).join(', ')}.`)
   }
-  lines.push('', 'Each is a real function: `name?` shows its full description, `dir(__dsh__.tools)` lists them.')
+  // The grouping is a real package, so a server can also be imported as a module — which reads
+  // better than `mcp.` at every call site when a cell leans on one server. The example is built
+  // from a server that HAS an importable tool, not just the first one: a server whose every tool
+  // name Python refuses would have put `import ...` in the line, handing the model a SyntaxError
+  // as its example. If no server has one, the `getattr` route above is the only honest advice.
+  const example = servers.flatMap(([server, tools]) => tools.filter((t) => isUsableName(t.tool)).map((t) => [server, t.tool])).at(0)
+  if (example !== undefined) {
+    lines.push('', `Each server is also a module: \`from __dsh__.tools.mcp.${example[0]} import ${example[1]}\` binds its tools directly.`)
+  }
+  // Naming the second level matters once the grouping exists: `dir(__dsh__.tools)` shows `mcp`,
+  // not the hundred tools under it, so a model told only the first level reads a real catalogue as
+  // a broken mount.
+  lines.push('', `Each is a real function: \`name?\` shows its full description, \`dir(__dsh__.tools)\` lists them${servers.length === 0 ? '' : ', and `dir(mcp)` / `dir(mcp.<server>)` the ones under `mcp`'}.`)
   return lines.join('\n')
 }
 
@@ -383,9 +502,12 @@ export function apply(ctx, config = {}) {
         exec.deferContext(createUserMessage({ content: outcome.content, source: { kind: 'plugin', plugin: 'dsh-py-codeact' } }))
       }
       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: outcome.value }
+        : { ok: true, value: unwrapped === undefined ? outcome.value : unwrapped.value }
     } catch (error) {
       session?.append('tool/code-dispatch', { ...trace, isError: true, content: [{ type: 'text', text: String(error?.message ?? error) }] })
       throw error
@@ -415,7 +537,7 @@ export function apply(ctx, config = {}) {
       } catch { /* it never came up — fall through and replace it */ }
     }
     // One entry backs every shell in the conversation tree, so `sent` is keyed BY SHELL. `calls` is the exception: it only has to make `subCallId` unique, so process-wide is right.
-    const entry = { kernel: undefined, current: new Map(), calls: 0, sent: new Map(), started: undefined }
+    const entry = { kernel: undefined, current: new Map(), calls: 0, sent: new Map(), envelopes: new Map(), started: undefined }
     entry.kernel = new PythonKernel({
       command: config.command ?? (config.python === undefined ? undefined : [config.python, KERNEL_PY]),
       cwd: exec.agent?.session?.header?.cwd ?? process.cwd(),
@@ -447,9 +569,10 @@ export function apply(ctx, config = {}) {
     },
     // No `isConcurrencySafe`: cells mutate the shell's namespace, so this agent's cells must stay exclusive ordering barriers. That is a per-AGENT constraint, not a per-process one — the kernel tracks one in-flight task per shell, so a subagent's cell runs alongside its parent's just fine.
     async execute(args, exec) {
-      const { specs } = toolSpecs(visibleSchemas(exec.agent))
+      const { specs, envelopes } = toolSpecs(visibleSchemas(exec.agent))
       const { entry, shell, restarted: wasRestarted } = await kernelFor(exec, specs)
       entry.current.set(shell, exec)
+      entry.envelopes.set(shell, envelopes)
       try {
         // Only resend the bindings when the visible set actually moved — an unchanged catalogue is the norm, and it is 30+ schemas on the wire.
         const key = specsKey(specs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-py-codeact",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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

@@ -2,7 +2,7 @@
 # /// script
 # requires-python = ">=3.12"
 # dependencies = [
-#     "ipython~=9.16.0",
+#     "ipython~=9.17.0",
 #     "objprint~=0.3.0",
 # ]
 # # Checked with `TY_UV=scripts ty check py/kernel.py` — that prefix is what hands ty this script's venv. A `ty.toml` would be found and then silently ignored for PEP 723 scripts (astral-sh/ty#4083), so any ty config has to live here.
@@ -238,6 +238,12 @@ def _make_binding(bridge: Bridge, spec):
     return call
 
 
+def bound_tools() -> dict:
+    """The calling shell's catalogue, or nothing outside a cell."""
+    session = _current_session.get()
+    return {} if session is None else session.bindings
+
+
 class ToolsModule(types.ModuleType):
     """`__dsh__.tools` — the bridged tool surface of the CALLING shell.
 
@@ -245,38 +251,211 @@ class ToolsModule(types.ModuleType):
 
     def __init__(self) -> None:
         super().__init__("__dsh__.tools", "Harness tools, bridged into this session as awaitables.")
+        self.__path__ = []  # a package, so `__dsh__.tools.mcp` resolves under it
         self.ToolCallError = ToolCallError
 
-    @staticmethod
-    def _bindings():
-        session = _current_session.get()
-        return {} if session is None else session.bindings
-
     def __getattr__(self, name):  # only reached when the attribute is absent
         if name.startswith("__"):
             raise AttributeError(name)  # import/introspection probing — never answer with a tool
-        bindings = ToolsModule._bindings()
+        bindings = bound_tools()
         if name in bindings:
             return bindings[name]
-        available = ", ".join(sorted(bindings)) or "(none)"
+        # The shown listing, not the bound one: a typo used to push the whole flat catalogue into
+        # the trajectory at the one moment the model is guaranteed to be reading it.
+        available = ", ".join(sorted(listed_tools())) or "(none)"
         raise AttributeError(f"no such tool: {name!r}. Available: {available}")
 
     def __dir__(self):
-        return sorted(ToolsModule._bindings())
+        return sorted(listed_tools())
+
+    # NOT `listed_tools()`: `__all__` is what `from __dsh__.tools import *` BINDS, and narrowing it
+    # left `mcp__gh__ok` undefined in a cell that used to work. Display is `__dir__`'s job.
+    @property
+    def __all__(self):
+        return sorted(bound_tools())
+
+    def __repr__(self) -> str:
+        # The cell's trailing expression is echoed back, so ending on `__dsh__.tools` is the
+        # cheapest "what do I have" move there is — and it used to re-emit the whole flat catalogue.
+        return f"<module '__dsh__.tools': {', '.join(sorted(listed_tools())) or 'no tools bound'}>"
+
+
+MCP_PREFIX = "mcp__"
+
+
+def split_mcp(name: str) -> tuple[str, str] | None:
+    """`mcp__calendar__list_events` -> `("calendar", "list_events")`.
+
+    dsh names every MCP tool `mcp__<serverName>__<rawName>`, and a raw name may itself contain
+    `__` — `split("__")` would tear such a tool apart and file it under a server that does not
+    exist, so only the first two separators are ever consumed.
+
+    PRESENTATION ONLY. dsh's own naming contract says the public name "is never parsed to recover"
+    the raw one, and it is right: a name that needed normalizing, or that ran past 64 characters,
+    becomes `<truncated>_<12 hex of sha256>`, and the cut can land anywhere — including before the
+    second `__`. That case returns `None` here and the tool simply stays flat, reachable under its
+    full public name, which is the only name dispatch ever uses.
+    """
+    if not name.startswith(MCP_PREFIX):
+        return None
+    server, sep, raw = name[len(MCP_PREFIX) :].partition("__")
+    return (server, raw) if sep and server and raw else None
+
+
+def servable(name: str) -> tuple[str, str] | None:
+    """`(server, tool)` when `mcp.<server>.<tool>` can actually ANSWER, else `None`.
+
+    Not `split_mcp` alone. Two ways a name splits cleanly and the grouping still cannot serve it:
+    `McpModule.__getattr__` refuses a true dunder — import and introspection probing (`__path__`,
+    `__all__`, `__spec__`) all wear that shape — and dsh hashes a public name that needed
+    normalising, where the cut can land before the second `__` and `split_mcp` returns `None`.
+
+    The one predicate for the whole file, because the listing and the lookup have to agree: hiding
+    a flat name on the strength of the split alone left `mcp__gh____weird__` in no listing the
+    model ever reads, while `mcp.gh.__weird__` raised `AttributeError`.
+    """
+    parts = split_mcp(name)
+    if parts is None or (parts[1].startswith("__") and parts[1].endswith("__")):
+        return None
+    return parts
+
+
+def listed_tools() -> dict:
+    """What the model is SHOWN: `dir()`, `repr()`, and the `Available:` list of a failed lookup.
+
+    Not `__all__` — that is the star-import BINDING contract, and narrowing it unbound every flat
+    name from `from __dsh__.tools import *`, which is a regression on running code rather than a
+    quieter listing.
+
+    Every flat `mcp__server__tool` name stays bound; showing them contradicted the prompt block,
+    which stopped printing them. Of 103 entries 86 were flat MCP names, and a model asked to
+    introspect its own tools filtered them out by hand. A name the grouping cannot serve stays
+    shown — it is then the only name that works.
+    """
+    return {name: call for name, call in bound_tools().items() if servable(name) is None}
+
+
+def mcp_servers(bindings: dict) -> dict[str, dict]:
+    """Group the flat `mcp__server__tool` bindings into `{server: {tool: call}}`.
+
+    The flat names stay bound too. They are what dsh dispatches on and what an older session may
+    already have imported; dropping them to tidy the surface would break a cell mid-conversation.
+    """
+    servers: dict[str, dict] = {}
+    for name, call in bindings.items():
+        if (parts := split_mcp(name)) is not None:
+            servers.setdefault(parts[0], {})[parts[1]] = call
+    return servers
+
+
+MCP_MODULE = "__dsh__.tools.mcp"
+
+
+def mcp_members(module_name: str) -> dict:
+    """One level of the `mcp` tree, resolved against the catalogue in force NOW.
+
+    Deliberately not a method: a non-dunder attribute on the class would shadow a tool or a server
+    of that name, and a raw MCP name is the server's to choose — `_private` is a legal one.
+    """
+    servers = mcp_servers({name: call for name, call in bound_tools().items() if servable(name) is not None})
+    if module_name == MCP_MODULE:
+        return {server: mcp_server_module(server) for server in servers}
+    # `removeprefix`, not `rpartition`: a raw server name is not guaranteed dot-free, and taking
+    # the last segment of one would look up a server that does not exist and resolve it empty.
+    return servers.get(module_name.removeprefix(f"{MCP_MODULE}."), {})
+
+
+class McpModule(types.ModuleType):
+    """`__dsh__.tools.mcp`, and one of these per server under it.
+
+    Real modules, so every import form the model might reach for resolves the way it does for
+    `__dsh__.tools` itself — including `from __dsh__.tools.mcp.calendar import list_events`, which
+    needs a `sys.modules` entry of its own (the shallower forms can be served by `__getattr__`,
+    that one cannot).
+
+    Their CONTENTS still come from the ContextVar, because `sys.modules` is process-global while
+    the catalogue is per shell — and because a restriction or a reconnecting server moves tools in
+    and out between cells. A name pulled OUT with `from ... import` is a snapshot, as it is for any
+    Python import; the module itself stays live.
+    """
+
+    def __getattr__(self, name):
+        # True dunders only. The guard is here to refuse import and introspection probing
+        # (`__path__`, `__all__`, `__spec__`, `__deepcopy__`), which always ends in `__` too —
+        # and a leading-`__` raw tool name is the server's to choose, so `startswith` alone
+        # advertised `mcp.<server>.__weird` in `dir()` and then refused the call.
+        if name.startswith("__") and name.endswith("__"):
+            raise AttributeError(name)
+        members = mcp_members(self.__name__)
+        if name not in members:
+            available = ", ".join(sorted(members)) or "(none)"
+            raise AttributeError(f"no such tool: {self.__name__.removeprefix('__dsh__.tools.')}.{name}. Available: {available}")
+        return members[name]
+
+    def __setattr__(self, name, value):
+        # One module per server for the whole PROCESS, so a write here would shadow that name for
+        # every other agent in it — permanently, and invisibly to `dir()`, which keeps reporting
+        # the tool it no longer reaches. The old per-call `Namespace` made this a local mistake.
+        if not (name.startswith("__") and name.endswith("__")):
+            raise AttributeError(f"{self.__name__.removeprefix('__dsh__.tools.')} belongs to the harness and is shared by every agent in this process — bind your own name instead of writing to it")
+        super().__setattr__(name, value)
+
+    def __dir__(self):
+        return sorted(mcp_members(self.__name__))
 
+    # Star-import reads `__all__` (or `vars()`), never `__getattr__` or `__dir__`, and nothing ever
+    # lands in these modules' `__dict__` — so without this `from __dsh__.tools.mcp.x import *`
+    # succeeded and bound nothing. `ToolsModule` carries the same property for the same reason.
     @property
     def __all__(self):
-        return sorted(ToolsModule._bindings())
+        return sorted(mcp_members(self.__name__))
 
     def __repr__(self) -> str:
-        return f"<module '__dsh__.tools': {', '.join(sorted(ToolsModule._bindings())) or 'no tools bound'}>"
+        members = mcp_members(self.__name__)
+        return f"<module {self.__name__!r}: {', '.join(sorted(members)) or 'empty'}>"
+
+
+MCP_ROOT = McpModule(MCP_MODULE, "MCP tools, one module per server.")
+MCP_ROOT.__path__ = []  # a package, like `__dsh__` and `__dsh__.tools`, so its server modules resolve
+sys.modules[MCP_MODULE] = MCP_ROOT
+
+
+def mcp_server_module(server: str) -> McpModule:
+    """The one module for `server`, made on first ask.
+
+    The single construction site, so a module that went missing — a cell can `del sys.modules[…]`
+    — comes back instead of leaving `dir(mcp)` raising `KeyError` for the rest of the session.
+    """
+    name = f"{MCP_MODULE}.{server}"
+    if not isinstance(module := sys.modules.get(name), McpModule):
+        module = McpModule(name, f"Tools bridged from the `{server}` MCP server.")
+        sys.modules[name] = module
+    return module
+
+
+def install_mcp_modules(bindings: dict) -> None:
+    """Register a module per visible MCP server.
+
+    Eager, because the deep import form never reaches `mcp_members`: `from __dsh__.tools.mcp.x
+    import y` is resolved by the import machinery against `sys.modules`, before any attribute
+    lookup happens.
+
+    `sys.modules` only ever gains entries: a server another shell can see costs this one an unused
+    module, while removing it would break an import that shell is mid-conversation with. What a
+    shell can actually reach is decided by `mcp_members`, not by what is registered.
+    """
+    for server in mcp_servers(bindings):
+        mcp_server_module(server)
 
 
 def build_bindings(bridge: Bridge, specs) -> dict:
     """Project one agent's visible tools into awaitables for its shell."""
-    # A tool named `ToolCallError` or `_bindings` would be shadowed by the module's own attributes, and one named `_rebind` used to overwrite a bound method outright. dsh's own SDK renderer refuses `_`-leading tool names for exactly this collision class.
-    reserved = set(vars(ToolsModule)) | set(vars(types.ModuleType)) | {"ToolCallError"}
-    return {spec["name"]: _make_binding(bridge, spec) for spec in specs if not spec["name"].startswith("_") and spec["name"] not in reserved}
+    # A tool named `ToolCallError` would be shadowed by the module's own attributes, and one named `_rebind` used to overwrite a bound method outright. dsh's own SDK renderer refuses `_`-leading tool names for exactly this collision class.
+    # `mcp` joins them, and unconditionally: it used to be bound and then overwritten by the namespace, so the tool was uncallable anyway — but only when an MCP server happened to be mounted. A name that means the namespace in one catalogue and a tool in the next is worse than one that always means the same thing.
+    reserved = set(vars(ToolsModule)) | set(vars(types.ModuleType)) | {"ToolCallError", "mcp"}
+    flat = {spec["name"]: _make_binding(bridge, spec) for spec in specs if not spec["name"].startswith("_") and spec["name"] not in reserved}
+    # `mcp` only when something is under it: an empty namespace in `dir()` reads as a broken mount.
+    return {**flat, "mcp": MCP_ROOT} if mcp_servers(flat) else flat
 
 
 def install_bridge_modules() -> ToolsModule:
@@ -386,7 +565,7 @@ class Session:
         history = Config()
         history.HistoryAccessor.hist_file = ":memory:"
         self.shell = InteractiveShell(user_ns=namespace, config=history)
-        self.bindings = build_bindings(bridge, specs)
+        self.rebind(bridge, specs)
         self.sinks: list = [None, None]  # the Capped buffers of the cell in flight
         install_bridge_modules()
 
@@ -434,7 +613,14 @@ class Session:
             self.sinks[:] = previous
 
     def rebind(self, bridge: Bridge, specs) -> None:
+        """Swap in a catalogue — a restriction or a reconnecting server moves tools between cells.
+
+        The one place the `sys.modules` registration lives, so `build_bindings` stays the pure
+        projection its name promises and no caller can produce bindings the import machinery
+        cannot follow.
+        """
         self.bindings = build_bindings(bridge, specs)
+        install_mcp_modules(self.bindings)
 
     def format_exc(self) -> str:
         """IPython's own traceback, rendered without ANSI colors."""