@inflexa-ai/harness 0.36.0 → 0.36.1

package/dist/loop/genai-spans.d.ts

@@ -3,6 +3,10 @@
  * `runAgent`, and `execute_tool` around each tool call that it dispatches. The AI
  * SDK traces the model calls (`providers/ai-sdk.ts`). It never sees the loop or
  * the tools, because the harness runs both itself.
+ *
+ * An `execute_tool` span is ERROR when our code fails the call. A failure that a
+ * tool returns as data, for example a sandbox command that exits non-zero, is
+ * normal iteration of the agent, and its span stays OK.
  */
 import type { ToolCallPart } from "ai";
 import type { AgentSession } from "../auth/types.js";
@@ -17,4 +21,14 @@ interface AgentRun {
 export declare function traceAgentRun<T extends AgentRun>(agentName: string, session: AgentSession, run: () => Promise<T>): Promise<T>;
 /** Run one tool call under an `execute_tool` span that records how the call ended. */
 export declare function traceToolCall<T>(call: Pick<ToolCallPart, "toolName" | "toolCallId">, run: () => Promise<T>, outcomeOf: (value: T) => ToolOutcome): Promise<T>;
+/**
+ * Record an exception that a tool threw on the active `execute_tool` span.
+ * `error.type` is the code of the error when it has one, else its name.
+ */
+export declare function recordToolException(err: Error): void;
+/**
+ * Label a tool failure that is not an exception on the active `execute_tool`
+ * span. `message` is text that our tool wrote, never text from the model.
+ */
+export declare function labelToolFailure(type: string, message?: string): void;
 export {};

package/dist/loop/genai-spans.js

@@ -3,6 +3,10 @@
  * `runAgent`, and `execute_tool` around each tool call that it dispatches. The AI
  * SDK traces the model calls (`providers/ai-sdk.ts`). It never sees the loop or
  * the tools, because the harness runs both itself.
+ *
+ * An `execute_tool` span is ERROR when our code fails the call. A failure that a
+ * tool returns as data, for example a sandbox command that exits non-zero, is
+ * normal iteration of the agent, and its span stays OK.
  */
 import { SpanStatusCode, trace } from "@opentelemetry/api";
 /** Run one agent loop under an `invoke_agent` span. */
@@ -26,6 +30,37 @@ export function traceToolCall(call, run, outcomeOf) {
         return value;
     });
 }
+/** The cap of `inflexa.tool.error`, in characters. */
+const TOOL_ERROR_MAX_CHARS = 1_000;
+/**
+ * Record an exception that a tool threw on the active `execute_tool` span.
+ * `error.type` is the code of the error when it has one, else its name.
+ */
+export function recordToolException(err) {
+    const span = trace.getActiveSpan();
+    if (span === undefined)
+        return;
+    span.recordException(err);
+    span.setAttribute("error.type", errorTypeOf(err));
+}
+/**
+ * Label a tool failure that is not an exception on the active `execute_tool`
+ * span. `message` is text that our tool wrote, never text from the model.
+ */
+export function labelToolFailure(type, message) {
+    const span = trace.getActiveSpan();
+    if (span === undefined)
+        return;
+    span.setAttribute("error.type", type);
+    if (message !== undefined)
+        span.setAttribute("inflexa.tool.error", message.slice(0, TOOL_ERROR_MAX_CHARS));
+}
+function errorTypeOf(err) {
+    const code = "code" in err ? err.code : undefined;
+    if ((typeof code === "string" && code !== "") || typeof code === "number")
+        return String(code);
+    return err.name === "" ? "_OTHER" : err.name;
+}
 function withSpan(name, attributes, run) {
     return trace.getTracer("@inflexa-ai/harness").startActiveSpan(name, { attributes }, async (span) => {
         try {

package/dist/loop/run-agent.js

@@ -4,6 +4,7 @@ import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { stripNulCharacters } from "../input-sanitization.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { ATTR_INFLEXA_TOOL_USE_ID, stableSpan } from "../lib/otel-spans.js";
+import { ResultError } from "../lib/result.js";
 import { hintForZodIssue, repairToolInput } from "../lib/zod-issues.js";
 import { markInterruptedMessage, syntheticUserMessage } from "../memory/ai-sdk-message-storage.js";
 import { stripUnansweredToolCalls } from "../memory/tool-call-integrity.js";
@@ -13,7 +14,7 @@ import { DEFAULT_REASONING } from "../providers/reasoning.js";
 import { resultStep } from "./run-step.js";
 import { AskRejectedError, UnavailableAsk } from "../tools/approval/contract.js";
 import { isToolError, readToolResultImages } from "../tools/define-tool.js";
-import { traceAgentRun, traceToolCall } from "./genai-spans.js";
+import { labelToolFailure, recordToolException, traceAgentRun, traceToolCall } from "./genai-spans.js";
 import { addChatUsage, hasReportedUsage, recordAgentRun } from "./metrics.js";
 import { computeDetail, computeResultDetail } from "./tool-detail.js";
 import { toolOutcomeForOutputType } from "./tool-outcome.js";
@@ -602,6 +603,7 @@ function readDispatchedStep(settled) {
 async function dispatchTool(tu, toolsById, ctx, isFatalLoopError, encoding) {
     const tool = toolsById.get(tu.toolName);
     if (tool === undefined) {
+        labelToolFailure("unknown_tool");
         return { result: errorResult(tu, `unknown tool: ${tu.toolName}`) };
     }
     const parsed = tool.inputSchema.safeParse(tu.input);
@@ -615,13 +617,17 @@ async function dispatchTool(tu, toolsById, ctx, isFatalLoopError, encoding) {
     const repaired = repairedInput === undefined ? undefined : tool.inputSchema.safeParse(repairedInput);
     if (repaired?.success === true)
         return execute(tu, tool, repaired.data, ctx, isFatalLoopError, encoding);
+    // The Zod text can quote the input, thus the span gets no message.
+    labelToolFailure("validation");
     return { result: errorResult(tu, `input validation failed: ${formatZodIssues(parsed.error, tu.input)}`) };
 }
 async function execute(tu, tool, input, ctx, isFatalLoopError, encoding) {
     try {
         const output = await tool.execute(input, ctx);
-        if (output.isErr())
+        if (output.isErr()) {
+            markToolFailure(tu, tool, output.error, encoding.log);
             return { result: errorResult(tu, toolErrorContent(output.error)) };
+        }
         // The one place a result description runs: the ok value in hand, the
         // input already validated, and the guard inside the compute.
         const detail = computeResultDetail(tool, input, output.value, encoding.log);
@@ -633,9 +639,35 @@ async function execute(tu, tool, input, ctx, isFatalLoopError, encoding) {
             throw err;
         if (isAskRejected(err))
             return { result: deniedResult(tu, err.feedback) };
+        markToolFailure(tu, tool, err, encoding.log);
         return { result: errorResult(tu, toolErrorContent(err)) };
     }
 }
+/**
+ * Label the span of a tool call that our tool code failed. A `ToolError` is a
+ * failure that the tool modeled, thus its own text is the account, with no
+ * exception and no log. Any other `Error` is a fault that the tool did not
+ * model: the span records the exception, and the log gets one warn.
+ */
+function markToolFailure(tu, tool, failure, log) {
+    const toolError = modeledToolError(failure);
+    if (toolError !== undefined) {
+        labelToolFailure("tool_error", toolError.error);
+    }
+    else if (failure instanceof Error) {
+        recordToolException(failure);
+        log.warn("tool call threw", { tool: tool.id, toolCallId: tu.toolCallId, ...log.errorFields(failure) });
+    }
+    else {
+        labelToolFailure("_OTHER");
+    }
+}
+/** The `ToolError` of a failure: the value itself, or the value that `unwrapOrThrow` wrapped in a `ResultError`. */
+function modeledToolError(failure) {
+    if (isToolError(failure))
+        return failure;
+    return failure instanceof ResultError && isToolError(failure.value) ? failure.value : undefined;
+}
 /**
  * Normalize a tool's return value to plain JSON, stripping NUL from every string
  * it holds ({@link stripNulCharacters}). The reviver sees values, not keys — a
@@ -700,8 +732,9 @@ function successResult(toolCall, value, encoding) {
 // is the six-character escape \u0000 — legitimate JSON text, and no longer
 // distinguishable from an error that happens to quote that escape.
 function toolErrorContent(value) {
-    if (isToolError(value)) {
-        return JSON.stringify({ error: stripNulCharacters(value.error), retryable: value.retryable });
+    const toolError = modeledToolError(value);
+    if (toolError !== undefined) {
+        return JSON.stringify({ error: stripNulCharacters(toolError.error), retryable: toolError.retryable });
     }
     const { retryable } = classifyProviderError(value);
     const error = stripNulCharacters(value instanceof Error ? value.message : String(value));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.36.0",
+    "version": "0.36.1",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",