feat(agent): allow manual tools to supply a wire input schema

[sambarnes]

Summary

Manual tools (execute: false) may now carry a caller-owned JSON Schema in wireInputSchema, which convertToolsToAPIFormat serializes instead of regenerating one from inputSchema.

The SDK never executes or input-validates a manual tool, so the Zod schema on such a tool exists only to be converted back to JSON Schema at serialization time. A caller that already holds the JSON Schema therefore pays a full round trip for nothing:

caller JSON Schema → Zod graph → z.toJSONSchema() → wire

That round trip is not free and not lossless. It allocates a Zod object graph per tool per request, and constructs Zod cannot represent (anyOf, oneOf) degrade on the way through. wireInputSchema short-circuits it:

-      parameters: convertZodToJsonSchema(tool.function.inputSchema),
+      parameters:
+        isManualTool(tool) && tool.function.wireInputSchema !== undefined
+          ? sanitizeJsonSchema(tool.function.wireInputSchema)
+          : convertZodToJsonSchema(tool.function.inputSchema),

sanitizeJsonSchema still runs, so ~-prefixed Standard Schema metadata never reaches a provider, and because it deep-copies, the caller's schema object is not mutated.

The knob is gated to manual tools on both sides. At runtime isManualTool excludes HITL (onToolCalled), unified (run), generator, regular and server tools, so every other path keeps its exact current behavior. At the type level ToolConfigWithSharedContext becomes an intersection with a two-branch union, so the field is available with execute: false and never with an execute function:

} & (
  | { execute: false; readonly wireInputSchema?: Readonly<Record<string, unknown>> }
  | { execute: (…) => unknown | (…) => AsyncGenerator<unknown>; readonly wireInputSchema?: never }
);

Motivation is a hot path in openrouter-web: the server-tools plugin rebuilt a Zod schema from each caller-supplied function tool on every request purely so the SDK could serialize it back, and it currently carries this behavior as a local patch against @openrouter/agent@0.10.0 (openrouter-web#36877, openrouter-web#36878). Upstreaming it lets that patch hunk be deleted at the next version bump. The win generalizes to any caller whose tool schemas originate as JSON Schema (proxies, MCP bridges, anything forwarding a downstream client's tools array).

API example

import { tool } from '@openrouter/agent';
import { z } from 'zod';

const confirmTool = tool({
  name: 'confirm_action',
  // still required, still the source of truth for types; never used on the wire here
  inputSchema: z.object({ action: z.string() }),
  // new: serialized verbatim (minus `~`-prefixed keys) instead of re-deriving
  // JSON Schema from `inputSchema`
  wireInputSchema: {
    type: 'object',
    properties: { action: { type: 'string' } },
    required: ['action'],
  },
  execute: false,
});

Additive and optional: a manual tool without wireInputSchema serializes exactly as before.

Tests

packages/agent/tests/unit/manual-tool-wire-schema.test.ts asserts against convertToolsToAPIFormat output — anyOf/oneOf survive, ~ keys are stripped at the root and nested under properties, the caller's object is neither mutated nor emitted by reference, a manual tool without the field still gets the Zod-derived schema, and an executable shared-context tool is unaffected. manual-tool-wire-schema.test-d.ts pins the type-level gate (accepted with execute: false, @ts-expect-error alongside an execute function).

pnpm run lint, pnpm run typecheck, and pnpm --filter @openrouter/agent test (104 files, 1221 tests, no type errors) pass locally.

Link to Devin session: https://openrouter.devinenterprise.com/sessions/acb44a847f1c4670b21a50fdfae26ef0
Requested by: @sambarnes

---

[devin-ai-integration]

Original prompt from sam

SYSTEM:
<latest_message>
sam (U06DJ8YS066) [ts=1787671064.572609]: @Devin could you review these two prs aiming to save cpu &amp; memory, give a rundown of the changes/rationale, and help me figure out if we should make them as an internal patch like this or upstream it to our agents sdk?

<https://github.com/OpenRouterTeam/openrouter-web/pull/36877|github.com/OpenRouterTeam/openrouter-web/pull/36877>
<https://github.com/OpenRouterTeam/openrouter-web/pull/36878|github.com/OpenRouterTeam/openrouter-web/pull/36878>
</latest_message>

=== BEGIN THREAD HISTORY (in #eng-devex-team) ===
sam (U06DJ8YS066) [ts=1787671064.572609]: @Devin could you review these two prs aiming to save cpu &amp; memory, give a rundown of the changes/rationale, and help me figure out if we should make them as an internal patch like this or upstream it to our agents sdk?

<https://github.com/OpenRouterTeam/openrouter-web/pull/36877|github.com/OpenRouterTeam/openrouter-web/pull/36877>
<https://github.com/OpenRouterTeam/openrouter-web/pull/36878|github.com/OpenRouterTeam/openrouter-web/pull/36878>
=== END THREAD HISTORY ===
Channel ID: C0BCDN7RHJM
Thread URL: https://openrouter.slack.com/archives/C0BCDN7RHJM/p1787671064572609?thread_ts=1787671064.572609&amp;cid=C0BCDN7RHJM

The <latest_message> is the message that you should use to guide your goals + task for this session, and you should use the rest of the slack thread as context.
A [ts=...] marker on a Slack message is that message's timestamp. To act on a specific message with the slack tool (e.g. adding an emoji reaction via the reaction command), pass that value as timestamp along with the Channel ID — no extra lookup call is needed.

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI' or '@devin'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.