@yolk-sdk/codemode 0.1.0-canary.124 → 0.1.0-canary.126

package/src/node.ts

@@ -121,7 +121,7 @@ const maxArgumentDepth = 64
  * proxy (close-match suggestions). Not a security boundary (`globalThis.tools` is unguarded):
  * arguments are still decoded by the host.
  */
-const toolsGuardSource = `(function (tools, labels, unbound) {
+const toolsGuardSource = `(function (tools, labels, unbound, rejectionPrefix) {
   // Captured before the script runs, so a script that changes built-ins cannot change the checks.
   const { apply, getPrototypeOf, setPrototypeOf } = Reflect
   const isFinite = Number.isFinite
@@ -136,6 +136,10 @@ const toolsGuardSource = `(function (tools, labels, unbound) {
   const ObjectProto = Object.prototype
   const { trunc, min } = Math
   const stringify = JSON.stringify
+  const parse = JSON.parse
+  const ErrorCtor = Error
+  const startsWith = String.prototype.startsWith
+  const sliceString = String.prototype.slice
   const plainJson = 'pass plain JSON (objects, arrays, strings, finite numbers, booleans, null)'
   const maxValues = ${maxArgumentValues}
   const maxDepth = ${maxArgumentDepth}
@@ -236,6 +240,24 @@ const toolsGuardSource = `(function (tools, labels, unbound) {
     apply(setDelete, walk.ancestors, [value])
     return copy
   }
+  // The host sends every rejection of a tool call as the prefix and the JSON of { message, code? }
+  // (pi only carries a message): rebuild the Error with its code.
+  const restored = error => {
+    const message = error instanceof ErrorCtor ? error.message : undefined
+    if (typeof message !== 'string' || !apply(startsWith, message, [rejectionPrefix])) return error
+    let payload
+    try {
+      payload = parse(apply(sliceString, message, [rejectionPrefix.length]))
+    } catch {
+      return error
+    }
+    if (payload === null || typeof payload !== 'object') return error
+    const rebuilt = new ErrorCtor(typeof payload.message === 'string' ? payload.message : '')
+    if (typeof payload.code === 'string') {
+      defineProperty(rebuilt, 'code', { value: payload.code, writable: true, configurable: true })
+    }
+    return rebuilt
+  }
   const wrap = (label, call) => async (...args) => {
     let json
     try {
@@ -244,7 +266,11 @@ const toolsGuardSource = `(function (tools, labels, unbound) {
       if (error instanceof Rejected) throw new TypeErrorCtor(label + ': argument ' + error.message)
       throw error
     }
-    return call(json)
+    try {
+      return await call(json)
+    } catch (error) {
+      throw restored(error)
+    }
   }
   // Each tool's function sits at tools[name] unless an earlier tool holds that key, in which case
   // that earlier function is already wrapped.
@@ -295,7 +321,7 @@ const guardSuffix = (
 
   const rejected = (unbound ?? []).map(entry => [entry.key, entry.message])
 
-  return `\n})(${toolsGuardSource}(tools, ${jsonSource(pairs)}, ${jsonSource(rejected)}), console)`
+  return `\n})(${toolsGuardSource}(tools, ${jsonSource(pairs)}, ${jsonSource(rejected)}, ${jsonSource(rejectionPrefix)}), console)`
 }
 
 const lineTerminators = /\r\n?|[\n\u2028\u2029]/g
@@ -373,12 +399,37 @@ const stripTypes = (code: string): Stripped => {
   }
 }
 
-const piTool = (tool: CodeModeExecutorTool): CodemodeTool => {
-  const converted: CodemodeTool = {
-    name: tool.name,
-    execute: (args, context) => tool.execute(args, context)
+/**
+ * pi passes only the message of a rejected tool call into the VM. Every tool rejection crosses as
+ * this prefix and the JSON of `{ message, code? }`, which the tools guard turns back into an
+ * `Error` with its `code`. Calls through the unguarded `globalThis.tools` see the encoded message.
+ */
+const rejectionPrefix = '\u0000yolk-tool-rejection:'
+
+type EncodedRejection = { message: string; code?: string }
+
+const RejectionCode = Schema.Struct({ code: Schema.String })
+
+const encodedRejection = (error: unknown) => {
+  const payload: EncodedRejection = {
+    message: error instanceof Error ? error.message : String(error)
   }
 
+  const code = Option.getOrUndefined(
+    Option.map(Schema.decodeUnknownOption(RejectionCode)(error), found => found.code)
+  )
+
+  if (code !== undefined) payload.code = code
+
+  return new Error(`${rejectionPrefix}${JSON.stringify(payload)}`)
+}
+
+const piCallable = (
+  tool: CodeModeExecutorTool | CodeModeExecutorGlobal,
+  execute: CodemodeTool['execute']
+): CodemodeTool => {
+  const converted: CodemodeTool = { name: tool.name, execute }
+
   if (tool.description !== undefined) converted.description = tool.description
 
   if (tool.inputSchema !== undefined) converted.inputSchema = tool.inputSchema
@@ -388,8 +439,15 @@ const piTool = (tool: CodeModeExecutorTool): CodemodeTool => {
   return converted
 }
 
+const piTool = (tool: CodeModeExecutorTool): CodemodeTool =>
+  piCallable(tool, (args, context) =>
+    tool.execute(args, context).catch((error: unknown) => {
+      throw encodedRejection(error)
+    })
+  )
+
 const piGlobal = (global: CodeModeExecutorGlobal): CodemodeTool => {
-  const converted = piTool(global)
+  const converted = piCallable(global, (args, context) => global.execute(args, context))
 
   if (global.spread !== undefined) converted.spread = global.spread
 

package/src/tool.ts

@@ -22,7 +22,6 @@ import {
   nestedToolCallResultFields,
   recordNestedToolCall,
   truncateCodePoints,
-  contentPartText,
   ToolCall,
   ToolResult,
   type AgentUsage,
@@ -207,47 +206,61 @@ class CodeModeExecutorRejected extends Data.TaggedError('CodeModeExecutorRejecte
 const errorMessage = (error: unknown) =>
   error instanceof Error ? error.message : Predicate.isString(error) ? error : 'unknown error'
 
+// The text a script sees of a result: its text parts only. File, image, document and audio parts
+// (and the labels providers render for them) never enter scripts (ADR 0013).
 const nestedText = (content: Content) =>
   Predicate.isString(content)
     ? content
     : content
-        .map(contentPartText)
+        .flatMap(part => (Predicate.isTagged(part, 'Text') ? [part.text] : []))
         .filter(text => text.length > 0)
         .join('\n')
 
 type NestedResolution =
   | { readonly ok: true; readonly value: unknown }
-  | { readonly ok: false; readonly message: string }
-
-/** What a nested call resolves to: `structuredContent` for tools with an output schema (when
- * present), text content otherwise; error results reject with their text. A tool that declares an
- * output schema but returns no `structuredContent` resolves to its text: that is a tool bug, kept
- * readable rather than turned into a failure. When the result captured files (ADR 0009), the
- * script also gets their descriptors as `files`: merged into an object `structuredContent`,
- * otherwise as `{ text, files }`.
+  | { readonly ok: false; readonly message: string; readonly code?: string }
+
+// The `code` of an error result: a model-visible error's (`ModelVisibleToolError.code`) or any
+// structured error with a string `code` (a connector's `ProviderFailure`).
+const decodeErrorCode = Schema.decodeUnknownOption(Schema.Struct({ code: Schema.String }))
+
+const errorCode = (result: ToolResult) =>
+  Option.getOrUndefined(
+    Option.map(decodeErrorCode(result.structuredContent), envelope => envelope.code)
+  )
+
+/** A typed tool's successful result without its value: the script never falls back to text. */
+const isInvalidTypedResult = (tool: CodeModeCatalogTool, result: ToolResult) =>
+  tool.structured && result.isError !== true && result.structuredContent === undefined
+
+/**
+ * What a nested call resolves to (ADR 0013). A typed tool (one with an output schema) resolves to
+ * its value as declared, file fields as `FileRef` or `FileUnavailable`; a typed result without a
+ * value rejects ("returned an invalid result"). An untyped tool resolves to its text parts joined
+ * with newlines. Error results reject with their text and the `code` of their structured error
+ * (a model-visible error's code, a connector failure's code). Files never reach scripts as labels.
  */
 const resolveNestedResult = (tool: CodeModeCatalogTool, result: ToolResult): NestedResolution => {
-  const text = nestedText(result.content)
-
   if (result.isError === true) {
-    return { ok: false, message: text.length > 0 ? text : `Tool ${tool.name} failed.` }
+    const text = nestedText(result.content)
+    const message = text.length > 0 ? text : `Tool ${tool.name} failed.`
+    const code = errorCode(result)
+
+    return code === undefined ? { ok: false, message } : { ok: false, message, code }
   }
 
-  const value =
-    tool.structured && result.structuredContent !== undefined ? result.structuredContent : text
+  if (!tool.structured) return { ok: true, value: nestedText(result.content) }
 
-  if (result.files === undefined || result.files.length === 0) return { ok: true, value }
+  return result.structuredContent === undefined
+    ? { ok: false, message: 'returned an invalid result' }
+    : { ok: true, value: result.structuredContent }
+}
 
-  const files = result.files.map(file => ({
-    fileId: file.fileId,
-    name: file.name,
-    mimeType: file.mimeType,
-    size: file.size
-  }))
+/** The script-visible rejection of a nested call, with the tool's error `code` when it has one. */
+const nestedCallError = (label: string, resolution: { message: string; code?: string }) => {
+  const error = new Error(`${label}: ${resolution.message}`)
 
-  return Predicate.isObject(value) && !Array.isArray(value)
-    ? { ok: true, value: { ...value, files } }
-    : { ok: true, value: { text, files } }
+  return resolution.code === undefined ? error : Object.assign(error, { code: resolution.code })
 }
 
 type CallOutcome = {
@@ -642,6 +655,13 @@ const runScript = <Context>(input: RunInput<Context>): Effect.Effect<ToolResult,
                     Effect.map(Clock.currentTimeMillis, finished => {
                       record.outcome = recordedOutcome(exit, finished - started)
                     })
+                  ),
+                  Effect.tap(result =>
+                    isInvalidTypedResult(tool, result)
+                      ? Effect.logWarning(
+                          `Code mode: ${tool.name} declares an output schema but returned no value (call ${nestedCall.id}).`
+                        )
+                      : Effect.void
                   )
                 )
               })
@@ -666,7 +686,7 @@ const runScript = <Context>(input: RunInput<Context>): Effect.Effect<ToolResult,
                     resolve(resolution.value)
                   } else {
                     // The script sees which call failed; the nested-call record keeps the raw text.
-                    reject(new Error(`${tool.callLabel}: ${resolution.message}`))
+                    reject(nestedCallError(tool.callLabel, resolution))
                   }
                 })
               })