docs(agents): fix audit findings across AgentKit and Human-in-the-Loop - #193
Conversation
- agents/human-in-the-loop/integrate.mdx: fix DurableAgent import to '@workflow/ai/agent' (it does not exist under 'workflow/ai'), add @workflow/ai to the install command, and pin ai to ^5 (the major actually supported) - agents/human-in-the-loop/integrate.mdx: add explicit prose + a second example tool showing that the action-performing tool must derive its own `action` string and independently re-verify the World ID proof, not just the approval tool - agents/agent-kit/ecosystem.mdx: replace the dead agentbook.world link (Vercel deployment not found) with the live AgentBook GitHub registry and the agentkit-cli status check - agents/hats/index.mdx: same dead-link fix for the AgentBook link used in the discount-unlock copy - agents/agent-kit/sdk-reference.mdx: document that omitting `uses` in `discount` mode defaults to unlimited uses (not a bounded trial) - agents/agent-kit/sdk-reference.mdx: document that AgentBook lookup failures are indistinguishable from "not registered" (both surface as `agent_not_verified` / a `null` return from `lookupHuman`) - agents/agent-kit/sdk-reference.mdx: document the `rpcUrls` per-chain override map on `createAgentkitHooks` and `verifyAgentkitSignature`, and the `resolveAgentkitSignatureRpcUrl` / `getDefaultPublicRpcUrl` helper exports
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
|
@codex review |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6cd00d9bf9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| }, | ||
| bookFlight: { | ||
| description: 'Book the flight after approval.', | ||
| inputSchema: z.object({ flightNumber: z.string() }), |
There was a problem hiding this comment.
In this example, bookFlight accepts only flightNumber, so its execute function has no IDKitResult to independently re-verify as required by the new warning. A model can invoke this tool without first calling approveAction, and the implementation cannot distinguish that path or validate the approval. Add the returned approval proof to this tool's input schema and execution parameters so the side-effecting tool can verify it against booking:${flightNumber} before booking.
Useful? React with 👍 / 👎.
De-duplicate the two "AgentBook registry" link mentions in ecosystem.mdx, and trim the audit-pass prose across agent-kit and human-in-the-loop docs to match the repo's terser Mintlify style.
|
Follow-up style pass on this PR's own changes: tightened the verbose audit-pass prose (AgentKit SDK reference, ecosystem/hats pages, human-in-the-loop warning + code comments) to match the repo's terser house style, and de-duplicated the back-to-back "AgentBook registry" link text in |
2803de3 to
f58e52a
Compare
Addresses a Codex review comment on PR #193: bookFlight's inputSchema only took flightNumber, so there was nowhere to pass the approval proof the adjacent Warning says must be independently re-verified — a model could call bookFlight directly without ever calling approveAction, and the implementation had no way to detect that. Added a required `approval` field to bookFlight's schema and a stub check that its `action` matches the same derivation approveAction uses, matching the real pattern in the linked flight-booking example (github.com/worldcoin/human-in-the-loop/tree/main/examples/flight-booking). Updated the system prompt to tell the model to pass the approval through, since the tool now requires it.
- integrate: pin ai@^6 on both install lines (current @workflow/ai requires ai@^6 as a peer) and add zod - integrate: import the ModelMessage/UIMessageChunk types; use instructions, since @workflow/ai 4.2.1 deprecates system - integrate: bookFlight re-verifies the proof with the World ID verify endpoint and consumes each approval once, keyed on the 4.0 nonce - sdk-reference: suggest a custom viem client with a timeout to surface AgentBook lookup failures - ecosystem, hats: replace outage wording with the CLI status check
…onment - bookFlight accepts the 3.0 proofs the approval UI produces (orbLegacy, the HumanApproval default) instead of requiring 4.0 - one-time use is keyed on the proof's nullifier, parsed with BigInt as the verifier does, so re-encodings like 0x01/0x1 can't mint new keys - pin environment: production on the verify call so an untrusted approval can't select staging/sandbox test proofs
The 3.0 verifier pads the nullifier to 64 hex chars and ABI-decodes a uint256, so bytes past the first 32 are ignored: N+"00" still verifies as N but BigInt() gives a new one-time-use key. Require a 0x-prefixed nullifier of at most 64 hex chars, matching the portal's v2 bound.
This branch was successfully deployed
2 participants
Fix AgentKit and Human-in-the-Loop docs.
agents/human-in-the-loop/integrate.mdx: fix theDurableAgentimport path, pinai@^6(the current@workflow/aipeer), and type the approval and booking examples from shared Zod schemas. The booking tool checks the operation binding, re-verifies the proof against the pinnedproductionenvironment, and consumes each approval once (keyed on the proof's nullifier, capped at 32 bytes and parsed as the verifier parses it), so an LLM-generated approval object is never treated as authorization.agents/agent-kit/ecosystem.mdx,agents/hats/index.mdx: replace the dead agentbook.world link with the GitHub registry + CLI status command.agents/agent-kit/sdk-reference.mdx: documentdiscount.uses's default, theagent_not_verified/lookup-failure ambiguity, therpcUrlsoption, and accurate RPC-helper contracts.