feat(tools): add client-side tool helper

[iroiro147]

Summary

• add defineClientTool for authored tools that park a run through input.requested instead of executing app-runtime code
• carry client-tool inputRequest metadata through authored normalization, runtime resolution, and harness tool registration
• convert client-side tool calls into input requests and resume them as normal JSON tool results
• document the authoring API and add a patch changeset

Refs #593.

Tests

• PATH="$HOME/Library/pnpm/bin:$PATH" pnpm --filter eve exec vitest run --config vitest.unit.config.ts src/public/definitions/tool-auth.test.ts src/internal/authored-definition/schema-backed.test.ts src/harness/input-extraction.test.ts src/harness/input-requests.test.ts src/harness/tools.test.ts (92 passed)
• PATH="$HOME/Library/pnpm/bin:$PATH" pnpm --filter eve run test:unit (440 files, 4648 passed, 1 skipped)
• PATH="$HOME/Library/pnpm/bin:$PATH" pnpm --filter eve run typecheck
• PATH="$HOME/Library/pnpm/bin:$PATH" pnpm --filter eve run build:js
• PATH="$HOME/Library/pnpm/bin:$PATH" pnpm docs:check
• PATH="$HOME/Library/pnpm/bin:$PATH" pnpm guard:invariants
• PATH="$HOME/Library/pnpm/bin:$PATH" pnpm exec oxfmt --check ...
• PATH="$HOME/Library/pnpm/bin:$PATH" pnpm exec oxlint --deny-warnings ...
• PATH="$HOME/Library/pnpm/bin:$PATH" pnpm changeset status --since origin/main
• git diff --check

[vercel]

@iroiro147 is attempting to deploy a commit to the Vercel Team on Vercel.

A member of the Team first needs to authorize it.

[iroiro147]

Rebased onto current main and preserved the newer ChatGPT model documentation and HITL accumulated-response flow. I also hardened client-side tools so invalid AI SDK calls cannot park the run, and added an explicit persisted response discriminator so client choices named approve/deny still resolve as normal JSON tool results rather than approval protocol messages.\n\nValidated with 252 focused unit tests, the eve package typecheck, invariant guard, docs checks, and changed-file formatting.

[iroiro147]

Fixed the failing schema-derivation expectation on the new head. The optional responseType field is now covered without changing the required input fields.

Verified locally under Node 24:

• full EVE unit suite: 445 files, 4,690 passed, 1 skipped
• EVE typecheck
• invariant checks
• git diff --check

Fresh CI is running on 6ab735a9.

[jbreite]

Curious if this, or something like it, is planned to be merged?

We’re integrating Eve into an agent we’re building and need installable tools that can accept Zod-validated structured input, durably pause for a custom user decision, and then resume server-side execution with both the original validated input and the user’s response.

A concrete example is a versioned document tool. The model would call it with something like:

z.object({
  documentId: z.string(),
  baseVersion: z.number(),
  document: documentSchema,
})

Eve would then durably pause and present three possible responses:

• Save — resume the tool server-side and persist the validated document as a new version under documentId.
• Cancel — resume without mutating anything.
• Freeform feedback — return revision instructions to the model without saving, so it can revise the document and call the tool again.

The important part is that Save operates on the exact structured input that originally caused the pause, including its document ID and base version. That avoids asking the model or client to reconstruct the document in a separate tool call and allows the server to perform version/conflict checks before writing.

Today, defineTool provides typed input and server-side execution after durable approval, but approval is binary and its response is not available to the tool. ask_question supports choices and freeform input, but it is a separate built-in tool and is not coupled to the original typed document or its server-side execution.

defineClientTool appears to cover typed custom input requests and durable responses, but because it has no execute, I’m unclear whether it supports the Save path above. Is post-response server execution part of the intended design, or is another extension point planned for this lifecycle?

We’d prefer to build this as an installable tool rather than maintain a fork of Eve. If this direction makes sense, is there anything useful we can contribute to help move it forward?

If this aligns with Eve’s intended direction, would be happy to build out the post-response execution path on a branch or coordinate with to contribute