@inflexa-ai/harness 0.36.2 → 0.36.3

package/dist/execution/step-summary-metrics.d.ts

@@ -1,5 +1,5 @@
 /**
- * Step-summary OTel metrics — Middleware.io routing follows the global
+ * Step-summary OTel metrics — export follows the global
  * meter provider (see `harness/lib/otel.ts`).
  *
  * cortex.summary.null_count — counter, incremented when a step-summary

package/dist/execution/step-summary-metrics.js

@@ -1,5 +1,5 @@
 /**
- * Step-summary OTel metrics — Middleware.io routing follows the global
+ * Step-summary OTel metrics — export follows the global
  * meter provider (see `harness/lib/otel.ts`).
  *
  * cortex.summary.null_count — counter, incremented when a step-summary

package/dist/lib/zod-issue-shape.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The shape of a Zod validation failure, with no value of the input in it.
+ *
+ * The span and the log of a rejected tool call may not carry the arguments of
+ * the model. A Zod `message` can quote the input, and so can the `keys` of an
+ * `unrecognized_keys` issue and the string segments of a path under a record.
+ * Thus each entry is built only from parts that the schema defines:
+ *
+ *  - the path, where a string segment is kept only when the schema declares
+ *    that key, and each other string segment becomes `*`. An array index is
+ *    kept as a number.
+ *  - the issue `code`.
+ *  - schema-side detail: the `expected` type, the `origin` and bound of a size
+ *    check, the string `format`, the divisor, the allowed literals, and the
+ *    discriminator of a union. For `unrecognized_keys`, only the count of keys.
+ *
+ * Example: `runId: invalid_type (expected string)`.
+ */
+import type { z } from "zod";
+/** Describe the issues of `error` against `schema`, one entry for each issue. */
+export declare function describeZodIssueShapes(error: z.ZodError, schema: z.ZodType): string[];

package/dist/lib/zod-issue-shape.js

@@ -0,0 +1,122 @@
+/**
+ * The shape of a Zod validation failure, with no value of the input in it.
+ *
+ * The span and the log of a rejected tool call may not carry the arguments of
+ * the model. A Zod `message` can quote the input, and so can the `keys` of an
+ * `unrecognized_keys` issue and the string segments of a path under a record.
+ * Thus each entry is built only from parts that the schema defines:
+ *
+ *  - the path, where a string segment is kept only when the schema declares
+ *    that key, and each other string segment becomes `*`. An array index is
+ *    kept as a number.
+ *  - the issue `code`.
+ *  - schema-side detail: the `expected` type, the `origin` and bound of a size
+ *    check, the string `format`, the divisor, the allowed literals, and the
+ *    discriminator of a union. For `unrecognized_keys`, only the count of keys.
+ *
+ * Example: `runId: invalid_type (expected string)`.
+ */
+/** The most issues that one failure describes. */
+const MAX_ISSUES = 10;
+/** The cap of one entry, in characters. */
+const MAX_ENTRY_CHARS = 200;
+/** Describe the issues of `error` against `schema`, one entry for each issue. */
+export function describeZodIssueShapes(error, schema) {
+    const entries = error.issues.slice(0, MAX_ISSUES).map((issue) => {
+        const detail = issueDetail(issue);
+        const entry = `${schemaPath(schema, issue.path)}: ${issue.code}${detail === undefined ? "" : ` (${detail})`}`;
+        return entry.length > MAX_ENTRY_CHARS ? `${entry.slice(0, MAX_ENTRY_CHARS - 1)}…` : entry;
+    });
+    const rest = error.issues.length - MAX_ISSUES;
+    if (rest > 0)
+        entries.push(`+${rest} more issues`);
+    return entries;
+}
+function issueDetail(issue) {
+    switch (issue.code) {
+        case "invalid_type":
+            return `expected ${issue.expected}`;
+        case "too_small":
+            return `${issue.origin} ${issue.exact === true ? "exactly" : "min"} ${issue.minimum}`;
+        case "too_big":
+            return `${issue.origin} ${issue.exact === true ? "exactly" : "max"} ${issue.maximum}`;
+        case "invalid_format":
+            return `format ${issue.format}`;
+        case "not_multiple_of":
+            return `divisor ${issue.divisor}`;
+        case "unrecognized_keys":
+            return `${issue.keys.length} keys`;
+        case "invalid_value":
+            return `expected ${issue.values.map(String).join("|")}`;
+        case "invalid_union":
+            return issue.discriminator === undefined ? undefined : `discriminator ${issue.discriminator}`;
+        default:
+            return undefined;
+    }
+}
+/** The path of an issue, with each string segment that the schema does not declare replaced by `*`. */
+function schemaPath(schema, path) {
+    if (path.length === 0)
+        return "(root)";
+    let current = schema;
+    const segments = path.map((segment) => {
+        if (typeof segment === "number") {
+            current = current === undefined ? undefined : elementOf(current, segment);
+            return String(segment);
+        }
+        const field = current === undefined || typeof segment !== "string" ? undefined : fieldOf(current, segment);
+        current = field;
+        return field === undefined ? "*" : String(segment);
+    });
+    return segments.join(".");
+}
+/** The schema of the declared field `key`, looking through wrappers and unions. */
+function fieldOf(schema, key) {
+    const def = unwrap(schema)._zod.def;
+    if (def.type === "object")
+        return Object.hasOwn(def.shape, key) ? def.shape[key] : undefined;
+    if (def.type === "union") {
+        for (const option of def.options) {
+            const field = fieldOf(option, key);
+            if (field !== undefined)
+                return field;
+        }
+    }
+    if (def.type === "intersection")
+        return fieldOf(def.left, key) ?? fieldOf(def.right, key);
+    return undefined;
+}
+function elementOf(schema, index) {
+    const def = unwrap(schema)._zod.def;
+    if (def.type === "array")
+        return def.element;
+    if (def.type === "tuple")
+        return def.items[index] ?? def.rest ?? undefined;
+    return undefined;
+}
+function unwrap(schema) {
+    let current = schema;
+    for (let depth = 0; depth < 16; depth++) {
+        const def = current._zod.def;
+        switch (def.type) {
+            case "optional":
+            case "nullable":
+            case "default":
+            case "prefault":
+            case "nonoptional":
+            case "catch":
+            case "readonly":
+                current = def.innerType;
+                break;
+            case "pipe":
+                current = def.in;
+                break;
+            case "lazy":
+                current = def.getter();
+                break;
+            default:
+                return current;
+        }
+    }
+    return current;
+}

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

@@ -31,4 +31,9 @@ export declare function recordToolException(err: Error): void;
  * span. `message` is text that our tool wrote, never text from the model.
  */
 export declare function labelToolFailure(type: string, message?: string): void;
+/**
+ * Label a tool call whose input failed validation on the active `execute_tool`
+ * span. `issues` is the shape of the failure, with no value of the input.
+ */
+export declare function labelToolValidationFailure(issues: readonly string[]): void;
 export {};

package/dist/loop/genai-spans.js

@@ -55,6 +55,16 @@ export function labelToolFailure(type, message) {
     if (message !== undefined)
         span.setAttribute("inflexa.tool.error", message.slice(0, TOOL_ERROR_MAX_CHARS));
 }
+/**
+ * Label a tool call whose input failed validation on the active `execute_tool`
+ * span. `issues` is the shape of the failure, with no value of the input.
+ */
+export function labelToolValidationFailure(issues) {
+    const span = trace.getActiveSpan();
+    if (span === undefined)
+        return;
+    span.setAttributes({ "error.type": "validation", "inflexa.tool.validation.issues": [...issues] });
+}
 function errorTypeOf(err) {
     const code = "code" in err ? err.code : undefined;
     if ((typeof code === "string" && code !== "") || typeof code === "number")

package/dist/loop/metrics.d.ts

@@ -1,5 +1,5 @@
 /**
- * Agent-loop OTel metrics → Middleware.io.
+ * Agent-loop OTel metrics, exported through the global MeterProvider.
  *
  * Every `runAgent` completion records, keyed by `agent_id`:
  *   - cortex.harness.agent.iterations — histogram of LLM iterations per run.

package/dist/loop/metrics.js

@@ -1,5 +1,5 @@
 /**
- * Agent-loop OTel metrics → Middleware.io.
+ * Agent-loop OTel metrics, exported through the global MeterProvider.
  *
  * Every `runAgent` completion records, keyed by `agent_id`:
  *   - cortex.harness.agent.iterations — histogram of LLM iterations per run.

package/dist/loop/run-agent.js

@@ -5,6 +5,7 @@ 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 { describeZodIssueShapes } from "../lib/zod-issue-shape.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";
@@ -14,7 +15,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 { labelToolFailure, recordToolException, traceAgentRun, traceToolCall } from "./genai-spans.js";
+import { labelToolFailure, labelToolValidationFailure, 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";
@@ -617,8 +618,10 @@ 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");
+    // The Zod text can quote the input, thus the span and the log get only the shape of the failure.
+    const issues = describeZodIssueShapes(parsed.error, tool.inputSchema);
+    labelToolValidationFailure(issues);
+    encoding.log.warn("tool call rejected", { tool: tool.id, toolCallId: tu.toolCallId, issues });
     return { result: errorResult(tu, `input validation failed: ${formatZodIssues(parsed.error, tu.input)}`) };
 }
 async function execute(tu, tool, input, ctx, isFatalLoopError, encoding) {

package/dist/tools/lib/alphafold-client.d.ts

@@ -14,8 +14,9 @@
  * identifier that does not parse as a UniProt accession or an AlphaFold DB id
  * gives 400 with an `Invalid identifier format` body. A well-formed accession
  * that AlphaFold holds no model for gives 404 with an empty object. Both are
- * the same outcome for a caller, and `isUnexpectedApiError` classifies each
- * `http_status` in the 4xx range as expected, thus one branch answers both.
+ * the same outcome for a caller, thus one branch answers both. Only these two
+ * codes mean absence. A different 4xx, such as a 403 refusal, throws, because
+ * `found: false` tells the agent to report the absence and not to retry.
  */
 import { z } from "zod";
 /**
@@ -46,7 +47,8 @@ export type AlphaFoldPrediction = z.infer<typeof AlphaFoldPredictionSchema>;
  * Fetch the AlphaFold structure prediction for one UniProt accession.
  *
  * Gives `null` when AlphaFold holds no model for the accession, and `null` for
- * an identifier it cannot parse. When the array holds more than one entry —
+ * an identifier it cannot parse. Throws on each other failure. When the array
+ * holds more than one entry —
  * the isoforms of one canonical accession — the entry whose own
  * `uniprotAccession` matches the queried accession wins. A query that names no
  * exact isoform falls back to the first entry, which AlphaFold orders

package/dist/tools/lib/alphafold-client.js

@@ -14,11 +14,12 @@
  * identifier that does not parse as a UniProt accession or an AlphaFold DB id
  * gives 400 with an `Invalid identifier format` body. A well-formed accession
  * that AlphaFold holds no model for gives 404 with an empty object. Both are
- * the same outcome for a caller, and `isUnexpectedApiError` classifies each
- * `http_status` in the 4xx range as expected, thus one branch answers both.
+ * the same outcome for a caller, thus one branch answers both. Only these two
+ * codes mean absence. A different 4xx, such as a 403 refusal, throws, because
+ * `found: false` tells the agent to report the absence and not to retry.
  */
 import { z } from "zod";
-import { apiFetchValidated, describeApiError, isUnexpectedApiError } from "./api-utils.js";
+import { apiFetchValidated, describeApiError } from "./api-utils.js";
 const ALPHAFOLD_BASE = "https://alphafold.ebi.ac.uk/api/prediction";
 /**
  * One entry of the AlphaFold DB prediction array. A query by a canonical
@@ -50,7 +51,8 @@ export const AlphaFoldPredictionSchema = z.object({
  * Fetch the AlphaFold structure prediction for one UniProt accession.
  *
  * Gives `null` when AlphaFold holds no model for the accession, and `null` for
- * an identifier it cannot parse. When the array holds more than one entry —
+ * an identifier it cannot parse. Throws on each other failure. When the array
+ * holds more than one entry —
  * the isoforms of one canonical accession — the entry whose own
  * `uniprotAccession` matches the queried accession wins. A query that names no
  * exact isoform falls back to the first entry, which AlphaFold orders
@@ -60,9 +62,9 @@ export async function fetchAlphaFoldPrediction(uniprotAccession) {
     const accession = uniprotAccession.trim();
     const res = await apiFetchValidated(`${ALPHAFOLD_BASE}/${encodeURIComponent(accession)}`, z.array(AlphaFoldPredictionSchema));
     if (res.isErr()) {
-        if (isUnexpectedApiError(res.error))
-            throw new Error(describeApiError(res.error));
-        return null;
+        if (isAbsence(res.error))
+            return null;
+        throw new Error(describeApiError(res.error));
     }
     const entries = res.value;
     if (entries.length === 0)
@@ -70,3 +72,6 @@ export async function fetchAlphaFoldPrediction(uniprotAccession) {
     const exact = entries.find((entry) => entry.uniprotAccession.toUpperCase() === accession.toUpperCase());
     return exact ?? entries[0];
 }
+function isAbsence(e) {
+    return e.type === "http_status" && (e.status === 400 || e.status === 404);
+}

package/dist/tools/lib/api-utils.d.ts

@@ -48,6 +48,7 @@ export type ApiError = {
     readonly type: "invalid_response";
     readonly issues: string;
 };
+export declare const HARNESS_USER_AGENT = "inflexa-harness (+https://inflexa.ai)";
 /**
  * Fetch a URL with retry on 429/502/503/504, exponential backoff, and timeout.
  * `err` carries the structured failure; a non-ok HTTP status is reported as
@@ -61,6 +62,8 @@ export type ApiError = {
  *
  * Between two attempts the wait obeys `Retry-After` when the response carries it,
  * and every wait stays at or below `maxRetryDelayMs`.
+ *
+ * Each request sends `HARNESS_USER_AGENT`, unless `headers` sets a User-Agent.
  */
 export declare function apiFetch<T = unknown>(url: string, options?: ApiFetchOptions): ResultAsync<T, ApiError>;
 /**

package/dist/tools/lib/api-utils.js

@@ -15,6 +15,9 @@ import { sleep } from "../../lib/async-utils.js";
 // provider answers with one of them while the origin restarts, and it sends an
 // HTML body. That answer is transient, thus a retry gets the real payload.
 const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
+// AlphaFold DB answers 403 to the default User-Agent of the runtime (`node`,
+// `Bun/<version>`, or none), and a descriptive value passes.
+export const HARNESS_USER_AGENT = "inflexa-harness (+https://inflexa.ai)";
 /**
  * Fetch a URL with retry on 429/502/503/504, exponential backoff, and timeout.
  * `err` carries the structured failure; a non-ok HTTP status is reported as
@@ -28,6 +31,8 @@ const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
  *
  * Between two attempts the wait obeys `Retry-After` when the response carries it,
  * and every wait stays at or below `maxRetryDelayMs`.
+ *
+ * Each request sends `HARNESS_USER_AGENT`, unless `headers` sets a User-Agent.
  */
 export function apiFetch(url, options = {}) {
     return new ResultAsync(runFetch(url, options));
@@ -92,12 +97,15 @@ function retryAfterMilliseconds(res) {
 }
 async function runFetch(url, options) {
     const { method = "GET", headers = {}, body, maxRetries = 3, retryDelayMs = 1000, maxRetryDelayMs = 30_000, sleep: wait = sleep, timeoutMs = 90_000, parseAs = "json", } = options;
+    const requestHeaders = new Headers(headers);
+    if (!requestHeaders.has("user-agent"))
+        requestHeaders.set("User-Agent", HARNESS_USER_AGENT);
     let lastError = "";
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
             const res = await fetch(url, {
                 method,
-                headers,
+                headers: requestHeaders,
                 body,
                 signal: AbortSignal.timeout(timeoutMs),
             });

package/package.json

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