Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix(skillopt): rollout tool errors carry the MCP error text (code, suggestion, fix) (GST-1054)
garrytan690e9ab37e13
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 85c12b390a..d60d8051ce 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -10,6 +10,16 @@ credits are retained; no result has been reassigned to another provider. Originaidentifiers and attribution are available in the pre-removal Git revision`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).+## [Unreleased]++**SkillOpt rollouts now see the same tool errors MCP callers get.** When a read tool refused or failed during a SkillOpt rollout, the model saw only the error's one-line message. MCP callers get the full error for the same call: its code, the suggestion and a runnable `fix`. So skills were tuned against a weaker error surface than real callers read. Both SkillOpt registries (the read-only rollout registry and write-capture) now hand the model the exact error text an HTTP MCP caller receives, and they keep `code` for callers that branch on it. MCP output is unchanged. Write ops keep refusing as before.++### Itemized changes++- `src/mcp/dispatch.ts` (`asAgentToolError`): turns a failed read into an error whose message is the MCP error text for the same call. An AI invocation policy stop passes through unchanged, because the tool loop rethrows it.+- `src/core/skillopt/rollout.ts`, `src/core/skillopt/write-capture.ts`: read handlers throw that error.+- `test/skillopt-rollout-agent-errors.test.ts`: on both registries, a two-selector refusal and a missing-page error read exactly as MCP returns them, including the suggestion and the fix argv. All four cases fail on master.+## [0.60.553.0] - 2026-11-02**GPT models that fill every optional tool argument with an empty value can now read pages and walk the graph.** GPT-6.1 Sol fills optional arguments with `0`, `[]`, `{}` or `false` as well as `""` and `null`. The `""` and `null` case was fixed in v0.60.549.0, but read operations still refused the others. `get_page` refused `around_chunk_id: 0`, `lines: {}` and a `context` sent without `grep`. `traverse_graph` refused `hops: []` sent beside `depth`, `link_type` and `direction`. Twenty-seven other optional arguments refused the same way (`limit: 0` on nine read operations, `types: []`, `only: []`, `schema_version: 0`, `get_versions` `diff: false` and more). gbrain now reads these as not provided, but only where the argument's own schema rules the value out: `0` when the valid range starts above zero, `[]` when the list must not be empty, `{}` when the object needs a field, `false` on a flag that only acts when true, and `context` when there is no `grep`, since it has no effect without it. Any value inside the valid range is kept, and so is any value on an argument that declares no such rule. So the normalized call is always one the caller could have sent by leaving the argument out, and it never reads more than that call would. This runs on every path that hands model arguments to an operation: MCP over HTTP and stdio, `gbrain call`, the subagent tool registry and both SkillOpt registries.diff --git a/src/core/skillopt/rollout.ts b/src/core/skillopt/rollout.tsindex 8cbd00f509..16c3e10a57 100644--- a/src/core/skillopt/rollout.ts+++ b/src/core/skillopt/rollout.ts@@ -20,6 +20,7 @@ import { chat as gatewayChat, toolLoop, type ChatMessage, type ChatToolDef, typeimport { BRAIN_TOOL_ALLOWLIST } from '../minions/tools/brain-allowlist.ts';import { paramDefToSchema } from '../../mcp/tool-defs.ts';import { findInvalidParam, normalizeOptionalParams, schemaInvalidParams } from '../../mcp/validate-params.ts';+import { asAgentToolError } from '../../mcp/dispatch.ts';import { operations, type OperationContext } from '../operations.ts';import { loadConfig } from '../config.ts';import type { BrainEngine } from '../engine.ts';@@ -225,11 +226,15 @@ function buildReadOnlyToolRegistry(ctx: OperationContext, offered: ReadonlySet<shandlers.set(toolName, {idempotent: true, // All read-only ops are idempotent by construction.execute: async (input: unknown) => {- const active = original?.remote !== false && original ? await authorizeSkillRead(original, op.name) : ctx;- const params = normalizeOptionalParams(op, (input as Record<string, unknown>) ?? {});- const failure = findInvalidParam(op, params);- if (failure) throw schemaInvalidParams(op, failure, { remote: true }, params);- return op.handler({ ...active, remote: true }, params);+ try {+ const active = original?.remote !== false && original ? await authorizeSkillRead(original, op.name) : ctx;+ const params = normalizeOptionalParams(op, (input as Record<string, unknown>) ?? {});+ const failure = findInvalidParam(op, params);+ if (failure) throw schemaInvalidParams(op, failure, { remote: true }, params);+ return await op.handler({ ...active, remote: true }, params);+ } catch (e) {+ throw asAgentToolError(e, op.name, ctx.sourceId);+ }},});}diff --git a/src/core/skillopt/write-capture.ts b/src/core/skillopt/write-capture.tsindex 68c22ec8c5..c1d6c12d1e 100644--- a/src/core/skillopt/write-capture.ts+++ b/src/core/skillopt/write-capture.ts@@ -24,6 +24,7 @@ import type { ChatToolDef, ToolHandler } from '../ai/gateway.ts';import { operations, type OperationContext, type ParamDef } from '../operations.ts';import { paramDefToSchema } from '../../mcp/tool-defs.ts';import { findInvalidParam, normalizeOptionalParams, schemaInvalidParams } from '../../mcp/validate-params.ts';+import { asAgentToolError } from '../../mcp/dispatch.ts';import { loadConfig } from '../config.ts';import { BRAIN_TOOL_ALLOWLIST } from '../minions/tools/brain-allowlist.ts';import type { BrainEngine } from '../engine.ts';@@ -87,10 +88,14 @@ export function buildWriteCaptureRegistry(engine: BrainEngine): WriteCaptureRegibaseHandlers.set(toolName, {idempotent: true,execute: async (input: unknown) => {- const params = normalizeOptionalParams(op, (input as Record<string, unknown>) ?? {});- const failure = findInvalidParam(op, params);- if (failure) throw schemaInvalidParams(op, failure, { remote: true }, params);- return op.handler(ctx, params);+ try {+ const params = normalizeOptionalParams(op, (input as Record<string, unknown>) ?? {});+ const failure = findInvalidParam(op, params);+ if (failure) throw schemaInvalidParams(op, failure, { remote: true }, params);+ return await op.handler(ctx, params);+ } catch (e) {+ throw asAgentToolError(e, op.name, ctx.sourceId);+ }},});}diff --git a/src/mcp/dispatch.ts b/src/mcp/dispatch.tsindex c1918c969b..ec057932fd 100644--- a/src/mcp/dispatch.ts+++ b/src/mcp/dispatch.ts@@ -60,6 +60,7 @@ import { isEngineDegraded } from '../core/degraded-marker.ts';import { admittedPendingReceipt, type WriteReceipt } from '../core/persistence/types.ts';import { currentVerifiedLocalWriter, readLocalWriter, verifyLocalWriter, withRequestIdentityMemo, withVerifiedLocalRegistration } from '../core/persistence/identity.ts';import { frameOverCap, resultTooLargeError } from '../core/egress-budget.ts';+import { isAIInvocationPolicyError } from '../core/ai/invocation-guard.ts';// WP3: normalization + validation moved to validate-params.ts (direct unit// surface). Re-exported here so existing imports/tests keep working.@@ -811,6 +812,17 @@ export function errorResult(e: unknown, opts: DispatchOpts, extra: { op?: stringreturn toolErrorResult({ ...rest, notices: orderNotices([...(envelope.notices ?? []), ...added]), contract_version });}+/**+ * GST-1054: SkillOpt's tool loops hand the model a thrown error's message, so their read handlers throw this: the+ * error text an MCP caller reads for the same failed read (code, message, suggestion, fix), with `code` kept for+ * callers that branch on it. An AI invocation policy stop passes through unchanged, because the loop rethrows it.+ */+export function asAgentToolError(e: unknown, op: string, sourceId?: string): unknown {+ if (isAIInvocationPolicyError(e)) return e;+ const text = errorResult(e, { remote: true, transport: 'http', sourceId }, { op, mutating: false, idempotent: true }).content[0]!.text;+ return Object.assign(new Error(text), { code: (JSON.parse(text) as { code?: string }).code });+}+const stderrLogger: OperationContext['logger'] = {info: (msg: string) => process.stderr.write(`[info] ${msg}\n`),warn: (msg: string) => process.stderr.write(`[warn] ${msg}\n`),diff --git a/test/skillopt-rollout-agent-errors.test.ts b/test/skillopt-rollout-agent-errors.test.tsnew file mode 100644index 0000000000..7121dac5a1--- /dev/null+++ b/test/skillopt-rollout-agent-errors.test.ts@@ -0,0 +1,79 @@+/**+ * GST-1054: a SkillOpt rollout's tool loop hands the model a thrown error's message. That message is the error text+ * an MCP caller reads for the same call (code, message, suggestion, fix), so rollouts optimize skills against the+ * error surface real callers get.+ */+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+import { PGLiteEngine } from '../src/core/pglite-engine.ts';+import { dispatchToolCall } from '../src/mcp/dispatch.ts';+import { runRollout } from '../src/core/skillopt/rollout.ts';+import { buildWriteCaptureRegistry } from '../src/core/skillopt/write-capture.ts';+import type { ToolHandler } from '../src/core/ai/gateway.ts';+import type { BenchmarkTask } from '../src/core/skillopt/types.ts';++const SLUG = 'notes/alpha-example';+let engine: PGLiteEngine;+let rollout: Map<string, ToolHandler>;+let writeCapture: Map<string, ToolHandler>;++async function rolloutHandlers(): Promise<Map<string, ToolHandler>> {+ let captured: Map<string, ToolHandler> | undefined;+ const task: BenchmarkTask = { task_id: 'errors', task: 'read a page', judge: { kind: 'rule', checks: [] } };+ await runRollout({+ engine, skillText: 'skill', task, targetModel: 'openai:gpt-6.1-sol', allowedTools: new Set(['get_page']),+ toolLoopFn: (async (o: { toolHandlers: Map<string, ToolHandler> }) => {+ captured = o.toolHandlers;+ return { messages: [], totalUsage: { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_creation_tokens: 0 }, totalTurns: 1, stopReason: 'end' };+ }) as never,+ });+ return captured!;+}++async function mcpText(args: Record<string, unknown>): Promise<string> {+ const r = await dispatchToolCall(engine, 'get_page', args, { remote: true, transport: 'http', sourceId: 'default' });+ expect(r.isError).toBe(true);+ return (r.content as Array<{ text: string }>)[0]!.text;+}++async function thrownMessage(handlers: Map<string, ToolHandler>, args: Record<string, unknown>): Promise<string> {+ try {+ await handlers.get('brain_get_page')!.execute(args, new AbortController().signal);+ } catch (e) {+ return (e as Error).message;+ }+ throw new Error('expected the tool call to refuse');+}++beforeAll(async () => {+ engine = new PGLiteEngine();+ await engine.connect({});+ await engine.initSchema();+ const put = await dispatchToolCall(engine, 'put_page', { slug: SLUG, content: '---\ntitle: Alpha Example\n---\n# Alpha Example\n\nline one\nline two\n' }, { remote: false, sourceId: 'default' });+ expect(put.isError).toBeFalsy();+ rollout = await rolloutHandlers();+ writeCapture = buildWriteCaptureRegistry(engine).handlers;+}, 120_000);++afterAll(async () => {+ await engine.disconnect();+});++describe('GST-1054: SkillOpt rollout tool errors carry the MCP error text', () => {+ const twoSelectors = { slug: SLUG, lines: { from: 1, count: 1 }, bytes: { offset: 0, length: 8 } };+ const missing = { slug: 'notes/missing-example' };++ for (const [name, handlers] of [['rollout', () => rollout], ['write-capture', () => writeCapture]] as const) {+ test(name + ': a refusal reaches the model with its code, suggestion and runnable fix, as MCP returns it', async () => {+ const message = await thrownMessage(handlers(), twoSelectors);+ expect(message).toBe(await mcpText(twoSelectors));+ const body = JSON.parse(message) as { code: string; suggestion?: string; fix?: { argv?: string[] } };+ expect(body.code).toBe('invalid_params');+ expect(body.suggestion).toContain('Drop `bytes`');+ expect(body.fix?.argv).toEqual(['gbrain', 'get', '--lines', '1-1', '--body', 'window', '--source', 'default', '--', SLUG]);+ });++ test(name + ': a handler error reads the same as the MCP error', async () => {+ expect(await thrownMessage(handlers(), missing)).toBe(await mcpText(missing));+ });+ }+});