Skip to content

Commit b8fca85

Browse files
k1ytZoo (VP)
authored andcommitted
feat(error-interception): add deterministic error interception middleware
Implements a middleware layer that intercepts, classifies, and transforms tool execution errors into structured WHAT/WHY/NEXT guidance messages, enabling AI models to self-correct without user intervention. New modules: - errorPatterns.ts: 11-category pattern DB with variant entries - ErrorClassifier.ts: Two-pass deterministic classifier - MessageTransformer.ts: Versioned JSON guidance serializer - ToolErrorInterceptor.ts: Interceptor facade with per-task state - TaskErrorState.ts: WeakMap-based task-scoped persistent state - StructuralValidator.ts: CWD + nested parameter preflight validator - DIFF_MATCH_FAILED pattern for apply_diff near-miss errors - Improved parallel tool call guidance for CWD_OBJECT_MISUSE and NESTED_PARAM_OVERFLOW Closes Zoo-Code-Org#1000
1 parent 1ceb4e6 commit b8fca85

16 files changed

Lines changed: 3210 additions & 26 deletions

‎src/core/assistant-message/__tests__/presentAssistantMessage-images.spec.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -179,7 +179,7 @@ describe("presentAssistantMessage - Image Handling in Native Tool Calling", () =
179179

180180
const textBlocks = mockTask.userMessageContent.filter((item: any) => item.type === "text")
181181
expect(textBlocks.length).toBeGreaterThan(0)
182-
expect(textBlocks.some((b: any) => String(b.text).includes("XML tool calls are no longer supported"))).toBe(
182+
expect(textBlocks.some((b: any) => String(b.text).includes("guided_tool_error"))).toBe(
183183
true,
184184
)
185185
// Should not proceed to execute tool or add images as tool output.
@@ -283,7 +283,7 @@ describe("presentAssistantMessage - Image Handling in Native Tool Calling", () =
283283
await presentAssistantMessage(mockTask)
284284

285285
const textBlocks = mockTask.userMessageContent.filter((item: any) => item.type === "text")
286-
expect(textBlocks.some((b: any) => String(b.text).includes("XML tool calls are no longer supported"))).toBe(
286+
expect(textBlocks.some((b: any) => String(b.text).includes("guided_tool_error"))).toBe(
287287
true,
288288
)
289289
// Ensure no tool_result blocks were added

‎src/core/assistant-message/__tests__/presentAssistantMessage-unknown-tool.spec.ts‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -93,9 +93,8 @@ describe("presentAssistantMessage - Unknown Tool Handling", () => {
9393

9494
expect(toolResult).toBeDefined()
9595
expect(toolResult.tool_use_id).toBe(toolCallId)
96-
// The error is wrapped in JSON by formatResponse.toolError
97-
expect(toolResult.content).toContain("nonexistent_tool")
98-
expect(toolResult.content).toContain("does not exist")
96+
// The error is transformed into a guided payload by the error interceptor
97+
expect(toolResult.content).toContain("guided_tool_error")
9998
expect(toolResult.content).toContain("error")
10099

101100
// Verify consecutiveMistakeCount was incremented
@@ -128,7 +127,7 @@ describe("presentAssistantMessage - Unknown Tool Handling", () => {
128127
// Should not execute tool; should surface a clear error message.
129128
const textBlocks = mockTask.userMessageContent.filter((item: any) => item.type === "text")
130129
expect(textBlocks.length).toBeGreaterThan(0)
131-
expect(textBlocks.some((b: any) => String(b.text).includes("XML tool calls are no longer supported"))).toBe(
130+
expect(textBlocks.some((b: any) => String(b.text).includes("guided_tool_error"))).toBe(
132131
true,
133132
)
134133

‎src/core/assistant-message/presentAssistantMessage.ts‎

Lines changed: 232 additions & 20 deletions
Large diffs are not rendered by default.
Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
import { ERROR_PATTERNS } from "./errorPatterns"
2+
import type { ClassifyOptions, ErrorClassification, ErrorPattern, InterceptionSignal } from "./types"
3+
4+
const SAFE_FACT_KEYS = new Set<string>([
5+
"category",
6+
"code",
7+
"commandSubmitted",
8+
"contextLengthExceeded",
9+
"contextOverflow",
10+
"contextWindowExceeded",
11+
"errorCode",
12+
"errorName",
13+
"errorSource",
14+
"errorStage",
15+
"errorType",
16+
"fileNotFound",
17+
"invalidProtocol",
18+
"missingNativeArgs",
19+
"missingParameter",
20+
"pathEmpty",
21+
"repetitionCount",
22+
"retryDisposition",
23+
"server",
24+
"shellIntegrationError",
25+
"status",
26+
"tool",
27+
"toolName",
28+
"type",
29+
"typeMismatch",
30+
"xmlToolCall",
31+
])
32+
33+
const SENSITIVE_KEYS = new Set<string>([
34+
"command",
35+
"commandText",
36+
"cwd",
37+
"env",
38+
"environmentVariable",
39+
"path",
40+
"absolutePath",
41+
"homePath",
42+
"apiKey",
43+
"api_key",
44+
"token",
45+
"secret",
46+
"password",
47+
"prompt",
48+
"response",
49+
"resultText",
50+
"mcpArguments",
51+
"arguments",
52+
"args",
53+
])
54+
55+
function isSafeFactKey(key: string): boolean {
56+
if (!SAFE_FACT_KEYS.has(key)) return false
57+
return !SENSITIVE_KEYS.has(key)
58+
}
59+
60+
function sanitizeFacts(signal: InterceptionSignal, pattern: ErrorPattern): Readonly<Record<string, unknown>> {
61+
const facts: Record<string, unknown> = {}
62+
63+
for (const key of Object.keys(signal.metadata)) {
64+
if (!isSafeFactKey(key)) continue
65+
66+
const value = signal.metadata[key]
67+
if (value === undefined || value === null) continue
68+
69+
if (typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
70+
facts[key] = value
71+
continue
72+
}
73+
74+
// Arrays of primitive tool/server identifiers only.
75+
if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
76+
facts[key] = value
77+
}
78+
}
79+
80+
facts.pattern = pattern.id
81+
facts.category = pattern.category
82+
facts.errorSource = signal.source
83+
84+
return Object.freeze(facts)
85+
}
86+
87+
export function classifyError(signal: InterceptionSignal, _options?: ClassifyOptions): ErrorClassification {
88+
// First pass: exact/structural matchers only.
89+
for (const pattern of ERROR_PATTERNS) {
90+
if (pattern.category === "UNCLASSIFIED") continue
91+
if (pattern.matches(signal)) {
92+
return {
93+
category: pattern.category,
94+
patternId: pattern.id,
95+
confidence: "exact",
96+
retryPolicy: pattern.retryPolicy,
97+
facts: sanitizeFacts(signal, pattern),
98+
}
99+
}
100+
}
101+
102+
// Second pass: heuristic fallback matchers, excluding the UNCLASSIFIED
103+
// catch-all at the end of the list.
104+
for (const pattern of ERROR_PATTERNS) {
105+
if (pattern.category === "UNCLASSIFIED") continue
106+
if (pattern.fallback?.(signal)) {
107+
return {
108+
category: pattern.category,
109+
patternId: pattern.id,
110+
confidence: "heuristic",
111+
retryPolicy: pattern.retryPolicy,
112+
facts: sanitizeFacts(signal, pattern),
113+
}
114+
}
115+
}
116+
117+
// UNCLASSIFIED catch-all.
118+
const fallback = ERROR_PATTERNS[ERROR_PATTERNS.length - 1]
119+
return {
120+
category: fallback.category,
121+
patternId: fallback.id,
122+
confidence: "heuristic",
123+
retryPolicy: fallback.retryPolicy,
124+
facts: sanitizeFacts(signal, fallback),
125+
}
126+
}
127+
128+
/** Convenience helper to classify a structured tool result directly. */
129+
export function classifyToolResult(
130+
result: InterceptionSignal["result"],
131+
taskId: string,
132+
toolCallId?: string,
133+
): ErrorClassification {
134+
const metadata: Record<string, unknown> = {}
135+
if (result && typeof result === "object") {
136+
if (result.status) metadata.status = result.status
137+
if (result.type) metadata.type = result.type
138+
}
139+
140+
const signal: InterceptionSignal = {
141+
source: "tool_result",
142+
stage: "result",
143+
taskId,
144+
toolCallId,
145+
result: result ?? undefined,
146+
metadata,
147+
}
148+
return classifyError(signal)
149+
}
Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
import {
2+
ERROR_PATTERNS,
3+
GUIDANCE_VERSION,
4+
MODEL_PAYLOAD_BYTE_LIMIT,
5+
NEXT_ITEM_CHAR_LIMIT,
6+
NEXT_ITEM_COUNT_LIMIT,
7+
} from "./errorPatterns"
8+
import type { ErrorCategory, ErrorClassification, ErrorSource, GuidancePayload, TransformOptions } from "./types"
9+
10+
function countUtf8Bytes(text: string): number {
11+
let count = 0
12+
for (let i = 0; i < text.length; i++) {
13+
const code = text.charCodeAt(i)
14+
if (code <= 0x7f) {
15+
count += 1
16+
} else if (code <= 0x7ff) {
17+
count += 2
18+
} else if (code >= 0xd800 && code <= 0xdbff) {
19+
// Surrogate pair: count 4 bytes for the pair.
20+
count += 4
21+
i++
22+
} else {
23+
count += 3
24+
}
25+
}
26+
return count
27+
}
28+
29+
function clampNextItems(next: string[]): string[] {
30+
const clamped: string[] = []
31+
for (const item of next) {
32+
if (clamped.length >= NEXT_ITEM_COUNT_LIMIT) break
33+
let candidate = item
34+
if (candidate.length > NEXT_ITEM_CHAR_LIMIT) {
35+
candidate = candidate.slice(0, NEXT_ITEM_CHAR_LIMIT)
36+
}
37+
candidate = candidate.replace(/[\udc00-\udfff]/g, "")
38+
if (candidate.length === 0) continue
39+
clamped.push(candidate)
40+
}
41+
return clamped
42+
}
43+
44+
function isRetryable(retryPolicy: ErrorClassification["retryPolicy"], category: ErrorCategory): boolean {
45+
if (category === "DUPLICATE_CALL" || category === "INVALID_TOOL_PROTOCOL") return false
46+
if (retryPolicy === "do-not-retry") return false
47+
if (retryPolicy === "auto-recover") return true
48+
return true
49+
}
50+
51+
function payloadType(source: ErrorSource | undefined): GuidancePayload["type"] {
52+
return source === "api_request" ? "guided_runtime_error" : "guided_tool_error"
53+
}
54+
55+
function resolveTemplate(patternId: string) {
56+
const pattern = ERROR_PATTERNS.find((p) => p.id === patternId)
57+
if (!pattern) {
58+
return {
59+
what: "The tool or request failed with a recognized error.",
60+
why: "The failure matches a known pattern.",
61+
next: [] as string[],
62+
}
63+
}
64+
return pattern.template
65+
}
66+
67+
function buildPayload(classification: ErrorClassification, occurrence: number): GuidancePayload {
68+
const { category, patternId, retryPolicy } = classification
69+
const template = resolveTemplate(patternId)
70+
71+
return {
72+
version: GUIDANCE_VERSION,
73+
status: "error",
74+
type: payloadType(classification.facts["errorSource"] as ErrorSource | undefined),
75+
category,
76+
what: template.what,
77+
why: template.why,
78+
next: clampNextItems(template.next),
79+
retryable: isRetryable(retryPolicy, category),
80+
occurrence: Math.max(1, occurrence),
81+
pattern_id: patternId,
82+
}
83+
}
84+
85+
function serializePayload(payload: GuidancePayload): string {
86+
return JSON.stringify(payload)
87+
}
88+
89+
function truncateString(text: string, maxBytes: number): string {
90+
if (countUtf8Bytes(text) <= maxBytes) return text
91+
92+
let low = 0
93+
let high = text.length
94+
while (low < high) {
95+
const mid = Math.floor((low + high + 1) / 2)
96+
if (countUtf8Bytes(text.slice(0, mid)) <= maxBytes) {
97+
low = mid
98+
} else {
99+
high = mid - 1
100+
}
101+
}
102+
103+
let result = text.slice(0, low)
104+
result = result.replace(/[\ud800-\udbff]$/, "")
105+
return result
106+
}
107+
108+
function fitPayloadWithinByteLimit(payload: GuidancePayload, byteLimit: number): string {
109+
const fullJson = serializePayload(payload)
110+
if (countUtf8Bytes(fullJson) <= byteLimit) return fullJson
111+
112+
let candidate = { ...payload }
113+
const type = payload.type
114+
115+
for (let nextCount = payload.next.length; nextCount >= 0; nextCount--) {
116+
candidate = {
117+
...candidate,
118+
next: payload.next.slice(0, nextCount),
119+
}
120+
121+
let json = serializePayload(candidate)
122+
if (countUtf8Bytes(json) <= byteLimit) return json
123+
124+
for (const targetBytes of [80, 50, 30]) {
125+
candidate = { ...candidate, why: truncateString(candidate.why, targetBytes) }
126+
json = serializePayload(candidate)
127+
if (countUtf8Bytes(json) <= byteLimit) return json
128+
}
129+
130+
for (const targetBytes of [120, 80, 50, 30]) {
131+
candidate = { ...candidate, what: truncateString(candidate.what, targetBytes) }
132+
json = serializePayload(candidate)
133+
if (countUtf8Bytes(json) <= byteLimit) return json
134+
}
135+
}
136+
137+
const minimal: GuidancePayload = {
138+
version: GUIDANCE_VERSION,
139+
status: "error",
140+
type,
141+
category: payload.category,
142+
what: "Error.",
143+
why: "Error.",
144+
next: [],
145+
retryable: payload.retryable,
146+
occurrence: payload.occurrence,
147+
pattern_id: payload.pattern_id,
148+
}
149+
return serializePayload(minimal)
150+
}
151+
152+
/**
153+
* Transform a classification into a bounded, model-facing JSON string.
154+
*
155+
* The result is guaranteed to be valid UTF-8 JSON with total byte length <=
156+
* byteLimit (default 1,024). It never contains raw errors, stacks, command
157+
* text, absolute paths, or secrets.
158+
*/
159+
export function transformErrorToMessage(classification: ErrorClassification, options?: TransformOptions): string {
160+
const occurrence = Math.max(1, options?.occurrence ?? 1)
161+
const byteLimit = options?.byteLimit ?? MODEL_PAYLOAD_BYTE_LIMIT
162+
163+
const payload = buildPayload(classification, occurrence)
164+
return fitPayloadWithinByteLimit(payload, byteLimit)
165+
}
166+
167+
/** Convenience helper to encode a JSON string into UTF-8 bytes for length checks. */
168+
export function encodeUtf8Bytes(text: string): Uint8Array {
169+
return new TextEncoder().encode(text)
170+
}
171+
172+
export function getPayloadByteLength(text: string): number {
173+
return encodeUtf8Bytes(text).length
174+
}

0 commit comments

Comments
 (0)