Add Worker-compatible harness API for edge runtimes

[justrach]

Context

I’m trying to build an agentic email system on Cloudflare Workers:

• inbound email via Cloudflare Email Service / Agents SDK
• D1 for storing emails, summaries, drafts, and thread state
• Telegram bot/webhook for personal notifications and commands
• online draft/reply UI served by the Worker
• Codegraff as the agent harness for summarizing emails and drafting replies

The Worker side is a natural fit for email routing, D1, Telegram webhooks, and outbound send_email, but the current TypeScript SDK docs describe @codegraff/sdk as an in-process native Node addon. The docs also say Edge / Cloudflare Workers / Deno Deploy are unsupported because there is no N-API.

Question

Can we expose a Worker-compatible harness API so Cloudflare Workers can use Codegraff without embedding the native addon?

Something like one of these would work well:

1. Hosted harness HTTP API

   • POST /v1/harness/run or similar
   • accepts prompt/session/tools/config
   • streams the same event model as @codegraff/sdk (TaskMessage, ToolCallStart, TaskComplete, etc.) over SSE or newline-delimited JSON

2. Edge-safe TypeScript client

   • e.g. @codegraff/edge or an edge mode in @codegraff/sdk
   • uses only fetch, ReadableStream, Web Crypto, etc.
   • no native addon / no Node-only APIs

3. Documented pattern for remote harness proxy

   • recommended minimal Node service that runs the native SDK
   • Worker calls it over HTTP
   • preserves session IDs and streaming events

Why the OpenAI-compatible API is not quite enough

The OpenAI-compatible gateway is useful for plain model calls, and a Worker can call it directly with fetch. But for this use case we want the Codegraff agent harness semantics: sessions, tool events, structured event streaming, and a stable way to build workflows around email processing/drafting.

nodejs_compat question

Could Cloudflare nodejs_compat make the current SDK work? My understanding is probably no: nodejs_compat provides/polyfills a subset of Node.js built-ins, but it does not provide a native Node addon / N-API runtime inside Workers. Since @codegraff/sdk embeds the harness as a native addon, Workers still cannot load it even with nodejs_compat.

If that understanding is wrong, it would be great to document the exact wrangler.toml/compatibility-date setup that makes it work. If it is correct, we should probably document that nodejs_compat does not change the Cloudflare Worker limitation.

Desired outcome

A supported path for this architecture:

Cloudflare Email Worker + D1 + Telegram
        ↓
Worker-compatible Codegraff harness API/client
        ↓
Summaries, classifications, follow-up detection, and draft replies

This would make Codegraff much easier to use in edge/event-driven systems where the Worker is the natural integration point but cannot run native Node addons.

Acceptance ideas

• Add docs clarifying whether nodejs_compat can/cannot support @codegraff/sdk in Workers.
• Provide an edge-compatible harness API or recommended proxy pattern.
• Provide a small Cloudflare Worker example that streams harness events and stores results in D1.
• Preserve the SDK event model so Worker apps do not have to downgrade to plain chat completions.

[justrach]

Scoping / resolution

Core finding: the only missing piece is a gateway route for the harness — models and sandboxes are already there.

@codegraff/sdk bundles two different mechanisms:

Capability	How it's exposed	Worker / edge today?
Model calls	gateway HTTP (OpenAI-compatible)	✅
Sandboxes	plain fetch → gateway.codegraff.com/v1/sandboxes/* (no SDK, no addon)	✅
Agent harness (sessions + tool-event stream)	native N-API addon only	❌

So from a Worker today you already get models + sandboxes; the harness is the only capability still trapped behind the addon. (nodejs_compat confirmed doesn't help — V8 isolates have no N-API; it polyfills Node built-ins, not native addons.)

Two supported paths

1. Today, zero new code — run the agent loop as a Node process. A multi-turn streaming harness loop doesn't really belong on Workers anyway (stateless, ~10s ACK). Run the harness on a supervised Node box (Fly/systemd — N-API binds fine), use Workers for ingress + durable state (KV via the gateway), and drive sandboxes over HTTP. Recommended for the email-agent architecture; needs nothing new.

2. First-party edge path (the feature ask) — give the harness a gateway route. POST /v1/harness/runs shaped like async exec: returns { runId }, then poll GET /v1/harness/runs/:id for events. (Cloudflare's ~95s outbound cap rules out a single blocking call — the same reason sandbox exec already has an async mode.) Then a native-free @codegraff/sdk/edge client (fetch-only) — the Sandbox class is the exact template; it's just currently gated behind the top-level require("./index.js") in lib.js.

Acceptance items

• nodejs_compat docs note — confirmed it can't make the SDK work in Workers. Worth documenting.
• Edge client — @codegraff/sdk/edge, native-free; the sandbox client already proves the pattern.
• Harness route — the one backend piece; lives in the gateway service.

🤖 scoped with Claude Code