dsh-py-codeact 0.2.1 → 0.2.2

package/README.md

@@ -60,21 +60,32 @@ 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: ...
 ```
 
 `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:

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,7 +124,20 @@ function toolSpec(schema, declarations) {
  */
 function toolSpecs(schemas) {
   const declarations = new Map()
-  return { specs: [...schemas].sort(byName).map((schema) => toolSpec(schema, declarations)), declarations }
+  const sorted = [...schemas].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)
 }
 
 /** Deterministic (lexicographic) order, so an unchanged tool set renders byte-identically. */
@@ -383,9 +425,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 +460,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 +492,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.2",
   "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": {