@axlsdk/axl 0.19.0 → 0.19.1

package/README.md

@@ -162,9 +162,14 @@ const calculator = tool({
   // handler also accepts (input, ctx) for nested agent invocations — see below
   retry: { attempts: 3, backoff: 'exponential' },
   sensitive: false,
+  // Keep the complete handler result for the host while sending only this
+  // allowlisted projection back to the model:
+  toModelOutput: (result) => ({ answer: result.result }),
 });
 ```
 
+`toModelOutput` is an opt-in, synchronous mapper for successful agent-invoked local tools. Strings are sent verbatim; JSON-compatible values are strictly validated and serialized once. The full post-hook result stays on `tool_call_end.data.result` for host rendering (subject to `trace.redact`). `sensitive: true` and thrown handler/hook/mock failures skip projection, and projection errors fail closed with `ToolModelOutputError`—there is no raw fallback. Direct `tool.run()`/`_execute()`, MCP tools, and handoffs are unchanged. See the [API reference](../../docs/api-reference.md#model-facing-tool-output) for the exact type, validation, mock, and delivery contract.
+
 Tool handlers receive a second parameter `ctx: WorkflowContext` (a child context), enabling the "agent-as-tool" composition pattern:
 
 ```typescript

package/dist/index.cjs

@@ -159,6 +159,7 @@ __export(index_exports, {
   ThinkTagScanner: () => ThinkTagScanner,
   TimeoutError: () => TimeoutError,
   ToolDenied: () => ToolDenied,
+  ToolModelOutputError: () => ToolModelOutputError,
   VLLM_PROFILE: () => VLLM_PROFILE,
   ValidationError: () => ValidationError,
   VerifyError: () => VerifyError,
@@ -272,6 +273,7 @@ function tool(config) {
     retry: retryPolicy,
     requireApproval: config.requireApproval ?? false,
     hooks: config.hooks,
+    ...config.toModelOutput !== void 0 ? { toModelOutput: config.toModelOutput } : {},
     async run(ctx, input) {
       const startTime = Date.now();
       try {
@@ -333,6 +335,17 @@ var AxlError = class extends Error {
     this.code = code;
   }
 };
+var ToolModelOutputError = class extends AxlError {
+  toolName;
+  cause;
+  constructor(toolName, cause) {
+    super("TOOL_MODEL_OUTPUT_ERROR", `Failed to prepare model output for tool "${toolName}"`);
+    this.name = "ToolModelOutputError";
+    this.toolName = toolName;
+    this.cause = cause;
+    Object.defineProperty(this, "cause", { enumerable: false });
+  }
+};
 var VerifyError = class extends AxlError {
   lastOutput;
   zodError;
@@ -2353,6 +2366,15 @@ function sanitizeSchemaForGemini(schema) {
   }
   return out;
 }
+function parseGeminiFunctionResponse(content) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return { result: content };
+  }
+  return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : { result: parsed };
+}
 var GEMINI_PRICING = {
   "gemini-2.5-pro": [125e-8, 1e-5],
   "gemini-2.5-flash": [3e-7, 25e-7],
@@ -2688,15 +2710,9 @@ var GeminiProvider = class {
         }
       } else if (msg.role === "tool") {
         const functionName = toolCallIdToName.get(msg.tool_call_id) ?? "unknown";
-        let responseData;
-        try {
-          responseData = JSON.parse(msg.content);
-        } catch {
-          responseData = { result: msg.content };
-        }
         const functionResponse = {
           name: functionName,
-          response: responseData
+          response: parseGeminiFunctionResponse(msg.content)
         };
         if (msg.tool_call_id && geminiNativeIds.has(msg.tool_call_id)) {
           functionResponse.id = msg.tool_call_id;
@@ -4926,8 +4942,191 @@ function resolveConfig(config) {
   return resolved;
 }
 
+// src/tool-model-output.ts
+var import_node_util = require("util");
+function invalid(path, reason) {
+  return new Error(`Invalid tool model output at ${path}: ${reason}`);
+}
+function propertyPath(parent, key) {
+  if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)) return `${parent}.${key}`;
+  let escaped = "";
+  for (const character of key) {
+    const code = character.charCodeAt(0);
+    if (character === "\\" || character === '"') escaped += `\\${character}`;
+    else if (code <= 31 || code === 8232 || code === 8233) {
+      escaped += `\\u${code.toString(16).padStart(4, "0")}`;
+    } else escaped += character;
+  }
+  return `${parent}["${escaped}"]`;
+}
+function normalize(value, path, stack) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw invalid(path, "number must be finite");
+    return value;
+  }
+  if (value === void 0) throw invalid(path, "undefined is only allowed on object properties");
+  if (typeof value === "bigint" || typeof value === "function" || typeof value === "symbol") {
+    throw invalid(path, `unsupported ${typeof value}`);
+  }
+  if (typeof value !== "object") throw invalid(path, `unsupported ${typeof value}`);
+  let prototype;
+  let descriptors;
+  try {
+    prototype = Object.getPrototypeOf(value);
+    descriptors = Object.getOwnPropertyDescriptors(value);
+    Object.setPrototypeOf(descriptors, null);
+  } catch (cause) {
+    throw invalid(
+      path,
+      `object inspection failed (${cause instanceof Error ? cause.name : "error"})`
+    );
+  }
+  if (stack.has(value)) throw invalid(path, "cyclic reference");
+  for (const key of Reflect.ownKeys(descriptors)) {
+    const descriptor = descriptors[key];
+    if (descriptor && !("value" in descriptor)) {
+      throw invalid(
+        typeof key === "string" ? propertyPath(path, key) : `${path}[symbol]`,
+        "accessor properties are not supported"
+      );
+    }
+    if (typeof key === "symbol" && descriptor?.enumerable) {
+      throw invalid(`${path}[symbol]`, "enumerable symbol keys are not supported");
+    }
+  }
+  if (typeof descriptors.toJSON?.value === "function") {
+    throw invalid(propertyPath(path, "toJSON"), "custom toJSON is not supported");
+  }
+  const array = Array.isArray(value);
+  if (array && prototype !== Array.prototype && prototype !== null) {
+    throw invalid(path, "array subclasses are not supported");
+  }
+  const inheritedToJSON = prototype === Array.prototype || prototype === Object.prototype ? Object.getOwnPropertyDescriptor(prototype, "toJSON") : void 0;
+  if (typeof inheritedToJSON?.value === "function") {
+    throw invalid(propertyPath(path, "toJSON"), "inherited custom toJSON is not supported");
+  }
+  const inheritedThen = prototype === Array.prototype || prototype === Object.prototype ? Object.getOwnPropertyDescriptor(prototype, "then") : void 0;
+  if (typeof descriptors.then?.value === "function" || inheritedThen !== void 0 && (!("value" in inheritedThen) || typeof inheritedThen.value === "function")) {
+    throw invalid(path, "thenable output is not supported");
+  }
+  stack.add(value);
+  try {
+    if (array) {
+      const normalized2 = [];
+      const length = descriptors.length?.value;
+      if (!Number.isSafeInteger(length) || length < 0) {
+        throw invalid(propertyPath(path, "length"), "array length is invalid");
+      }
+      for (let index = 0; index < length; index++) {
+        const descriptor = descriptors[String(index)];
+        if (!descriptor || !("value" in descriptor)) {
+          throw invalid(`${path}[${index}]`, "arrays must be dense data properties");
+        }
+        if (descriptor.value === void 0) {
+          throw invalid(`${path}[${index}]`, "array values cannot be undefined");
+        }
+        normalized2.push(normalize(descriptor.value, `${path}[${index}]`, stack));
+      }
+      for (const key of Object.keys(descriptors)) {
+        const descriptor = descriptors[key];
+        if (!descriptor?.enumerable) continue;
+        const index = Number(key);
+        if (!Number.isInteger(index) || index < 0 || index >= length || String(index) !== key) {
+          throw invalid(propertyPath(path, key), "non-index array properties are not supported");
+        }
+      }
+      Object.setPrototypeOf(normalized2, null);
+      return normalized2;
+    }
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw invalid(path, "only plain objects and null-prototype records are supported");
+    }
+    const normalized = /* @__PURE__ */ Object.create(null);
+    for (const key of Object.keys(descriptors)) {
+      const descriptor = descriptors[key];
+      if (!descriptor?.enumerable) continue;
+      if (!("value" in descriptor)) {
+        throw invalid(propertyPath(path, key), "accessor properties are not supported");
+      }
+      if (descriptor.value === void 0) continue;
+      normalized[key] = normalize(descriptor.value, propertyPath(path, key), stack);
+    }
+    return normalized;
+  } finally {
+    stack.delete(value);
+  }
+}
+function serializeToolModelOutput(toolName, output) {
+  try {
+    if (import_node_util.types.isPromise(output)) {
+      void Promise.prototype.then.call(output, void 0, () => void 0);
+    }
+    if (typeof output === "string") return output;
+    return JSON.stringify(normalize(output, "$", /* @__PURE__ */ new WeakSet()));
+  } catch (cause) {
+    throw new ToolModelOutputError(toolName, cause);
+  }
+}
+
 // src/context.ts
 var signalStorage = new import_node_async_hooks.AsyncLocalStorage();
+function isErrorShaped(value) {
+  return value !== null && typeof value === "object" && "error" in value;
+}
+function isErrorShapedSafely(value) {
+  try {
+    return isErrorShaped(value);
+  } catch {
+    return false;
+  }
+}
+function recordToolSpanResult(span, value, suppressInspectionErrors) {
+  let isError = false;
+  let errorMessage;
+  const inspect = () => {
+    if (isErrorShaped(value)) {
+      isError = true;
+      errorMessage = value.error;
+    } else {
+      isError = false;
+    }
+  };
+  if (suppressInspectionErrors) {
+    try {
+      inspect();
+    } catch {
+      isError = false;
+      errorMessage = void 0;
+    }
+  } else {
+    inspect();
+  }
+  span.setAttribute("axl.tool.success", !isError);
+  if (isError) span.setStatus("error", errorMessage);
+}
+function prepareToolModelOutput(toolName, project) {
+  let output;
+  try {
+    output = project();
+  } catch (cause) {
+    throw new ToolModelOutputError(toolName, cause);
+  }
+  return serializeToolModelOutput(toolName, output);
+}
+function finalizeToolResult(options) {
+  const { toolName, configuredTool, outcome, legacyContent, emitEnd, beforeProjection } = options;
+  const projectionEligible = configuredTool !== void 0 && !configuredTool.sensitive && outcome.kind === "returned" && configuredTool.toModelOutput !== void 0;
+  if (projectionEligible) {
+    emitEnd();
+    beforeProjection();
+    const project = configuredTool.toModelOutput;
+    return prepareToolModelOutput(toolName, () => project(outcome.value));
+  }
+  const content = legacyContent();
+  emitEnd();
+  return content;
+}
 var askStorage = new import_node_async_hooks.AsyncLocalStorage();
 var inlineSchemaCache = /* @__PURE__ */ new WeakMap();
 function zodToJsonSchema(schema) {
@@ -5622,6 +5821,7 @@ ${appendedSchemaText}`;
     let lastStartAttempt = 1;
     let lastStartMaxAttempts = 1;
     while (turns < maxTurns) {
+      this.currentSignal?.throwIfAborted();
       if (Date.now() - startTime > timeoutMs) {
         throw new TimeoutError("ctx.ask()", timeoutMs);
       }
@@ -5723,6 +5923,7 @@ ${appendedSchemaText}`;
       this.onAgentStart?.({ agent: agent2._name, model: modelUri }, callbackMeta);
       let response;
       try {
+        this.currentSignal?.throwIfAborted();
         if (this._streamingEnabled) {
           let content2 = "";
           const toolCalls = [];
@@ -6024,6 +6225,8 @@ ${appendedSchemaText}`;
               return await handoffFn();
             }
           }
+          const tool2 = agent2._config.tools?.find((candidate) => candidate.name === toolName);
+          const isMcpTool = !tool2 && this.mcpManager?.isMcpTool(toolName);
           const toolOverride = this.toolOverrides?.get(toolName);
           if (toolOverride) {
             let toolArgs2;
@@ -6048,38 +6251,47 @@ ${appendedSchemaText}`;
               callbackMeta
             );
             const toolStart2 = Date.now();
+            const suppressErrorShapeInspection2 = tool2?.sensitive === true || tool2?.toModelOutput !== void 0;
             const executeOverride = async () => {
-              let toolResult3;
               try {
-                toolResult3 = await toolOverride(toolArgs2);
+                return { kind: "returned", value: await toolOverride(toolArgs2) };
               } catch (err) {
-                toolResult3 = { error: err instanceof Error ? err.message : String(err) };
+                return {
+                  kind: "thrown",
+                  value: { error: err instanceof Error ? err.message : String(err) }
+                };
               }
-              return toolResult3;
             };
-            const toolResult2 = this.spanManager ? await this.spanManager.withSpanAsync(
+            const outcome = this.spanManager ? await this.spanManager.withSpanAsync(
               "axl.tool.call",
               {
                 "axl.tool.name": toolName,
                 "axl.agent.name": agent2._name
               },
               async (span) => {
-                const r = await executeOverride();
+                const result = await executeOverride();
                 span.setAttribute("axl.tool.duration", Date.now() - toolStart2);
-                const isError = r && typeof r === "object" && "error" in r;
-                span.setAttribute("axl.tool.success", !isError);
-                if (isError)
-                  span.setStatus("error", r.error);
-                return r;
+                recordToolSpanResult(span, result.value, suppressErrorShapeInspection2);
+                return result;
               }
             ) : await executeOverride();
-            const resultContent2 = JSON.stringify(toolResult2);
-            this.emitEvent({
-              type: "tool_call_end",
-              agent: agent2._name,
-              tool: toolName,
-              duration: Date.now() - toolStart2,
-              data: { args: toolArgs2, result: toolResult2, callId: toolCall.id }
+            const toolResult2 = outcome.value;
+            const resultContent2 = finalizeToolResult({
+              toolName,
+              configuredTool: tool2,
+              outcome,
+              legacyContent: () => tool2?.sensitive ? "[REDACTED - sensitive tool output]" : JSON.stringify(toolResult2),
+              emitEnd: () => {
+                const toolDuration2 = Date.now() - toolStart2;
+                this.emitEvent({
+                  type: "tool_call_end",
+                  agent: agent2._name,
+                  tool: toolName,
+                  duration: toolDuration2,
+                  data: { args: toolArgs2, result: toolResult2, callId: toolCall.id }
+                });
+              },
+              beforeProjection: () => this.currentSignal?.throwIfAborted()
             });
             currentMessages.push({
               role: "tool",
@@ -6088,8 +6300,6 @@ ${appendedSchemaText}`;
             });
             continue;
           }
-          const tool2 = agent2._config.tools?.find((t) => t.name === toolName);
-          const isMcpTool = !tool2 && this.mcpManager?.isMcpTool(toolName);
           if (!tool2 && !isMcpTool) {
             this.emitEvent({ type: "tool_denied", agent: agent2._name, tool: toolName });
             currentMessages.push({
@@ -6118,6 +6328,7 @@ ${appendedSchemaText}`;
           });
           this.onToolCall?.({ name: toolName, args: toolArgs, callId: toolCall.id }, callbackMeta);
           const toolStart = Date.now();
+          const suppressErrorShapeInspection = tool2?.sensitive === true || tool2?.toModelOutput !== void 0;
           if (tool2 && tool2.requireApproval) {
             const approvalFn = async () => {
               const decision = await this.awaitHuman({
@@ -6179,12 +6390,12 @@ ${appendedSchemaText}`;
             }
           }
           const executeTool = async () => {
-            let toolResult2;
+            let outcome;
             let resultContent2;
             if (isMcpTool && this.mcpManager) {
               try {
                 const mcpResult = await this.mcpManager.callTool(toolName, toolArgs);
-                toolResult2 = mcpResult;
+                outcome = { kind: "returned", value: mcpResult };
                 resultContent2 = mcpResult.content.map(
                   (c) => c.type === "text" ? c.text : `[${c.type}]`
                 ).join("\n");
@@ -6192,34 +6403,50 @@ ${appendedSchemaText}`;
                   resultContent2 = `Error: ${resultContent2}`;
                 }
               } catch (err) {
-                toolResult2 = { error: err instanceof Error ? err.message : String(err) };
-                resultContent2 = JSON.stringify(toolResult2);
+                outcome = {
+                  kind: "thrown",
+                  value: { error: err instanceof Error ? err.message : String(err) }
+                };
+                resultContent2 = JSON.stringify(outcome.value);
               }
             } else if (tool2) {
               const childCtx = this.createChildContext();
               try {
-                toolResult2 = await tool2._execute(toolArgs, childCtx);
+                outcome = { kind: "returned", value: await tool2._execute(toolArgs, childCtx) };
               } catch (err) {
-                toolResult2 = { error: err instanceof Error ? err.message : String(err) };
+                outcome = {
+                  kind: "thrown",
+                  value: { error: err instanceof Error ? err.message : String(err) }
+                };
               }
-              if (tool2.hooks?.after && !(toolResult2 && typeof toolResult2 === "object" && "error" in toolResult2)) {
+              if (outcome.kind === "returned" && tool2.hooks?.after && !(suppressErrorShapeInspection ? isErrorShapedSafely(outcome.value) : isErrorShaped(outcome.value))) {
                 try {
-                  toolResult2 = await tool2.hooks.after(toolResult2, this);
+                  outcome = {
+                    kind: "returned",
+                    value: await tool2.hooks.after(outcome.value, this)
+                  };
                 } catch (err) {
-                  toolResult2 = {
-                    error: `After hook error: ${err instanceof Error ? err.message : String(err)}`
+                  outcome = {
+                    kind: "thrown",
+                    value: {
+                      error: `After hook error: ${err instanceof Error ? err.message : String(err)}`
+                    }
                   };
                 }
               }
-              resultContent2 = tool2.sensitive ? "[REDACTED - sensitive tool output]" : JSON.stringify(toolResult2);
+              if (tool2.sensitive) {
+                resultContent2 = "[REDACTED - sensitive tool output]";
+              } else if (outcome.kind === "thrown" || tool2.toModelOutput === void 0) {
+                resultContent2 = JSON.stringify(outcome.value);
+              }
             } else {
-              toolResult2 = void 0;
+              outcome = { kind: "returned", value: void 0 };
               resultContent2 = "Tool execution error";
             }
-            return { toolResult: toolResult2, resultContent: resultContent2 };
+            return { outcome, resultContent: resultContent2 };
           };
           const traceName = isMcpTool && this.mcpManager ? this.mcpManager.getQualifiedName(toolName) ?? toolName : toolName;
-          const { toolResult, resultContent } = this.spanManager ? await this.spanManager.withSpanAsync(
+          const execution = this.spanManager ? await this.spanManager.withSpanAsync(
             "axl.tool.call",
             {
               "axl.tool.name": traceName,
@@ -6228,22 +6455,27 @@ ${appendedSchemaText}`;
             async (span) => {
               const r = await executeTool();
               span.setAttribute("axl.tool.duration", Date.now() - toolStart);
-              const isError = r.toolResult && typeof r.toolResult === "object" && "error" in r.toolResult;
-              span.setAttribute("axl.tool.success", !isError);
-              if (isError)
-                span.setStatus(
-                  "error",
-                  r.toolResult.error
-                );
+              recordToolSpanResult(span, r.outcome.value, suppressErrorShapeInspection);
               return r;
             }
           ) : await executeTool();
-          this.emitEvent({
-            type: "tool_call_end",
-            agent: agent2._name,
-            tool: traceName,
-            duration: Date.now() - toolStart,
-            data: { args: toolArgs, result: toolResult, callId: toolCall.id }
+          const toolResult = execution.outcome.value;
+          const toolDuration = Date.now() - toolStart;
+          const resultContent = finalizeToolResult({
+            toolName,
+            configuredTool: tool2,
+            outcome: execution.outcome,
+            legacyContent: () => execution.resultContent,
+            emitEnd: () => {
+              this.emitEvent({
+                type: "tool_call_end",
+                agent: agent2._name,
+                tool: traceName,
+                duration: toolDuration,
+                data: { args: toolArgs, result: toolResult, callId: toolCall.id }
+              });
+            },
+            beforeProjection: () => this.currentSignal?.throwIfAborted()
           });
           currentMessages.push({
             role: "tool",
@@ -12108,6 +12340,7 @@ function cosineSimilarity2(a, b) {
   ThinkTagScanner,
   TimeoutError,
   ToolDenied,
+  ToolModelOutputError,
   VLLM_PROFILE,
   ValidationError,
   VerifyError,