@forked-reality/agent-sdk

Framework-neutral TypeScript client and AI SDK tool adapter for the Forked Reality transaction firewall.

The SDK accepts EIP-5792-style calls shaped as { to, data, value }, discovers the exact actions supported by a deployment, starts a run with an idempotency key, and streams real policy events until a terminal decision. It never accepts a private key and does not broadcast transactions itself.

Install

npm install @forked-reality/agent-sdk

The framework-neutral client requires no AI framework. Install ai@^7 only when using the optional @forked-reality/agent-sdk/ai adapter.

Enforcement boundary

• advisory means the firewall observes or evaluates the request, but the account can still be used through another path. This is the honest mode for the exposed EOA-style lane.
• enforced means the configured account can release funds only through Forked Reality's proof-gated executor. The current implementation provides this guarantee for the protected treasury.
• An SDK call alone cannot turn an arbitrary EOA into an enforced account. A future ERC-4337/module adapter can provide the same boundary for compatible smart accounts.

The current gateway is intentionally fail-closed and allow-listed. It recognizes seven exact swap and vault call templates used by the working demo. A changed target, account, calldata byte, call order, value, capability, policy ID, chain, evidence mode, or enforcement claim is rejected. Arbitrary-call proof enforcement is roadmap work, not a current claim.

Discover and run a supported action

import { ForkedRealityClient } from "@forked-reality/agent-sdk"

const firewall = new ForkedRealityClient({
  baseUrl: "https://your-forked-reality-host.example",
})

const capabilities = await firewall.capabilities()
console.log(capabilities.actions.map(({ id }) => id))

const { runId } = await firewall.startAction("protected.buy-poison", {
  evidenceMode: "snapshot",
})

for await (const event of firewall.events(runId)) {
  console.log(event.stage, event.message)
}

Use firewall.run(request, { onEvent }) when the agent already has a supported call template and should wait for the terminal policy event.

Base SSE events are validated before they reach the caller. A malformed event, mismatched run ID, unsupported action, invalid response, or prematurely closed stream fails closed with FirewallClientError. Deployments that add event fields can pass a stricter parseEvent function when constructing ForkedRealityClient<YourEvent>; unknown server fields are preserved by the default schema.

AI SDK tool

import { ForkedRealityClient } from "@forked-reality/agent-sdk"
import { createForkedRealityTool } from "@forked-reality/agent-sdk/ai"

const client = new ForkedRealityClient({ baseUrl: "http://127.0.0.1:3000" })
const action = (await client.capabilities()).actions.find(
  ({ id }) => id === "protected.buy-poison",
)!

export const protectedTransaction = createForkedRealityTool({
  runner: client,
  policyId: action.request.policyId,
  capability: action.request.capability,
  chainId: action.request.chainId,
  account: action.request.account,
  enforcement: action.request.enforcement,
})

Only calls and evidenceMode are model-controlled tool inputs. The host application fixes the policy, capability, chain, account, and enforcement mode. The server still checks the complete request against its exact supported template.

HTTP surface

• GET /api/firewall/capabilities returns supported action templates and evidence modes.
• POST /api/firewall/run validates and starts an idempotent policy run.
• GET /api/firewall/events?runId=... streams controller events as SSE.

See examples/protected-agent.ts for a small external-agent integration.

Release check

From the repository root:

pnpm --filter @forked-reality/agent-sdk check:release
pnpm --filter @forked-reality/agent-sdk pack

check:release runs the unit tests, source typecheck, clean ESM/declaration build, and a consumer-style typecheck of the packaged imports. The package publishes only dist, this README, and the example. When the tarball is ready, publish the scoped package with:

pnpm --filter @forked-reality/agent-sdk publish --access public