Felix

Felix Orchestrator

[](LICENSE) [](https://docs.felix.run) [](https://workers.cloudflare.com/) [](tsconfig.json)

A managed agents harness on Cloudflare Workers, shaped after Anthropic's Managed Agents architecture: Session, Pattern/Provider registries, and ToolExecutor are decoupled abstractions that can be swapped without touching the others. TypeScript on Hono, with Durable Objects, Neon Postgres via Hyperdrive (pgvector included), R2, KV, Queues, Workflows, Analytics Engine, and AI Gateway.

An apiVersion: orchestrator/v1 manifest compiles into a runnable agent exposing /v1/* (OpenAI-compatible), /chat, /a2a, /mcp, /jobs, /plans, /audit, /approvals, /manifests, /eval, and /.well-known/agent-card.json. Manifests can be bundled at build time, dropped into R2, or managed per-tenant through the /manifests REST surface (append-only versions with active-pointer rollback; reads/writes gated by manifests:read / manifests:write scopes). Two Felix deployments can act as A2A peers and share a federation PolicyBundle via R2.

On top of the harness sits Felix Commerce, an agentic-commerce layer: conversational catalog → cart → approval-gated Stripe checkout as ordinary agent tools, an Agentic Commerce Protocol merchant endpoint (/acp), a Universal Commerce Protocol merchant endpoint (/ucp + /.well-known/ucp), per-brand D2C storefronts with an embeddable widget (/shop, /widget, /brands), schema.org / AI-discoverability surfaces (/structured, /geo), B2B quote-to-cash (/b2b), a pluggable entity data-source seam (/entities), and consent + attribution. See [Agentic commerce](#agentic-commerce) below.

> Full OpenAPI 3.1 spec at /openapi.json · interactive Scalar reference at /docs. The core routes are documented with Zod-derived schemas, examples, and the bearer security scheme; the commerce routers are documented in [packages/commerce/docs/index.md](packages/commerce/docs/index.md).

Three seams

| Seam | What it is | Where to find it | |---|---|---| | Session | Append-only event log per thread (seq, kind, message payload, optional metadata — including pinned: true anchor messages). The harness asks a SessionStrategy (full_replay / windowed:N / summarizing:N / semantic:N) to render the working-set messages instead of mutating an in-memory history. | packages/harness/src/session/ | | Pattern / model registries | react, deep, router, parallel, groupchat, reflect, plan_execute and the Anthropic / OpenAI / Workers AI providers self-register at module load; getPattern(name) and getModelProvider(name) resolve them at build time. New loops / providers register with one line in composition.ts or a sibling module. | packages/harness/src/patterns/registry.ts, packages/harness/src/patterns/model-registry.ts | | ToolExecutor | Every Tool carries a transport-labelled executor (local / mcp / a2a / container / queue / sandbox / browser). The model loop dispatches by name; the harness routes to whichever transport the tool was built with. Failures use a stable ToolErrorCode taxonomy (invalid_arguments, provider_error, timeout, rate_limited, …). Governance wrappers preserve the inner transport label. | packages/harness/src/tools/executor.ts, packages/harness/src/tools/{container,sandbox,browser,queue}-executor.ts, packages/harness/src/mcp/client.ts, packages/harness/src/a2a/client.ts |

Full documentation lives in [packages/harness/docs/](packages/harness/docs/README.md) — user guide under [packages/harness/docs/guide/](packages/harness/docs/guide/), contributor reference under [packages/harness/docs/internals/](packages/harness/docs/internals/).

Layout

packages/harness/src/
  manifests/    schema (Zod) · loader (bundled JSON) · validate · builder · resolver (4-layer chain + canary hash routing)
  tools/        ToolProvider · ToolExecutor seam (local / container / sandbox / browser / queue) · errors taxonomy · artifacts · retrieval (JIT tool filter)
  patterns/     react · deep · router · parallel · groupchat · reflect · plan_execute + AI Gateway model client (fallbacks + confidence escalation) + pattern/model registries
  session/      Session + SessionStrategy (full_replay / windowed / summarizing / semantic) · DO-backed store · anchor messages
  policy/       declarative scope policies · command screening (shell-aware projection + rule match) · federated PolicyBundle (R2)
  limits/       per-run caps via AsyncLocalStorage
  guardrails/   PII regex pipeline + llm_judge wrapper (Workers AI) + AI Gateway hook
  screening/    content screening — Workers-AI injection classifier over untrusted tool output (quarantine / block)
  approvals/    HITL store (Postgres) + ApprovalsDO critical section
  audit/        append-only event log (Postgres, batched via AUDIT_QUEUE + DLQ drain) + /audit/metrics aggregator
  eval/         golden datasets · pluggable Judge (workersAI / panel / deterministic) · trajectory rubrics · adversarial seeds · runner
  plans/        plan_create/plan_get/plan_update_step (Postgres)
  skills/       SKILL.md loader + per-tenant activation overlay (Postgres)
  db/           getDb (postgres.js over Hyperdrive, request-scoped) + pgvector helpers
  a2a/          JSON-RPC tasks/send|get|sendSubscribe|cancel + agent card + A2AExecutor (transport: a2a) + A2ATaskDO
  mcp/          MCP server + remote MCP client (McpExecutor — transport: mcp)
  memory/       ConversationDO (session event log) + pgvector semantic store + post-turn capture + periodic consolidation + procedural memory (recall_procedure tool)
  workflows/    AgentWorkflow entrypoint (Cloudflare Workflows-backed durable execution)
  auth/         JWT verifiers (Cloudflare Access + Cognito + self-issued JWKS) + requireScope + outbound OAuth registry + Hono middleware
  jobs/         Workers Cron Triggers + persistent registry + anomaly-detector + continuous-eval + abandoned-cart scan + GEO monitor
  observability/ counters (Analytics Engine) + spans (OTel-shaped)
  security/     SSRF allow-list, rate limit, AES-256-GCM at-rest helpers, constant-time compare, expr eval, redaction
  api/          OpenAPI spec + Scalar docs UI + /eval + /geo + consent/attribution surfaces
  composition.ts  wires Felix tools into a ToolProvider; deployment-time seat for registerPattern / registerModelProvider extensions
  app.ts          Hono app factory
  index.ts        Worker entry + DO exports + scheduled handler (cron: federation refresh + memory consolidation + jobs + retention sweep + queue orphan sweep + anomaly scan + continuous eval, then each plugin's cron tasks: abandoned-cart scan + GEO monitor)
packages/commerce/src/
  (Felix Commerce plugin, @felix/commerce)
  catalog/cart/orders · Stripe checkout + webhook · ACP merchant endpoint · brands/storefront/widget · structured-data (schema.org) · B2B quote-to-cash + billing seam · personalization · visual search · dynamic pricing · consent
  entities/     entity data-source seam (native / federated / synced; http + mcp connectors, webhook push)
  geo/          GEO/AEO brand-visibility models + store (answer-engine monitoring)
apps/api/migrations/           applied with node-pg-migrate over a DIRECT Neon connection, never through Hyperdrive
  0001_baseline.sql   the single Postgres baseline — harness core (audit_events, plans, jobs, approvals,
                      skill_activation, oauth_token_cache, manifests + manifest_active, eval_*) plus the
                      commerce tables and the 768-dim pgvector `memory_vectors` table. Collapses the 22
                      D1-era migrations at their net shape (fresh-start cutover; no data was migrated).
  0002_commerce_ucp_checkout_sessions.sql  UCP merchant checkout sessions
  0003_jobs_enabled.sql                    jobs.enabled gate (DEFAULT false) for cron job execution
  0004_memory_pool_index.sql               memory_vectors pool index for consolidation reads
packages/harness/scripts/
  bundle-manifests.ts   YAML → JSON build step (reads packages/harness/manifests/*.yaml + packages/harness/skills/*/SKILL.md)
apps/api/scripts/
  eval.ts               CI gate — runs an eval dataset, compares pass_rate / mean_tokens to a baseline file, exits non-zero on regression
  mint-jwt.ts           self-issued JWT minter for the scoped management APIs
  deploy.md             deploy runbook
apps/
  chat-ui/          React + Vite chat UI; proxy Worker streaming /chat/stream over a service binding
  docs/             Starlight docs site (docs.felix.run), aggregates packages/*/docs
examples/
  queue-consumer/   reference consumer for the queue transport
  python-sandbox/   container-transport demo (mock gateway + manifest)
  sandbox-worker/   adapter Worker bridging the sandbox transport to @cloudflare/sandbox
  browser-worker/   adapter Worker bridging the browser transport to @cloudflare/puppeteer

Topology

| Concern | Implementation | |---|---| | HTTP | Hono on Workers | | LLM | AI Gateway → Anthropic / OpenAI / Workers AI (logical id resolved via MODEL_ROUTES env var) with ordered fallback chain on provider_error and optional confidence-routed escalation on low-confidence responses | | Agent runtime | Manual tool-loop (react) + dedicated DOs for multi-agent patterns. spec.execution.mode: durable wraps every invocation in a Cloudflare Workflow (AGENT_WORKFLOW) so worker eviction mid-run replays cleanly. | | Per-request limit state | AsyncLocalStorage populated by Hono auth middleware | | Audit / Plans / Jobs / Approvals / Eval | Neon Postgres via Hyperdrive (getDb, postgres.js, request-scoped client) with composite (tenantid, id) keys + tenant-scoped ORDER BY | | Semantic / procedural memory | memory_vectors (768-dim pgvector, HNSW cosine) in the same Postgres; optional post-turn capture + periodic consolidation | | Approvals critical section | ApprovalsDO serializes concurrent decide writes | | A2A task state | A2ATaskDO (one DO per tenant#task id) | | Session event log | ConversationDO (one DO per thread id); /events slice + cursor API | | Federation PolicyBundle | R2 + FederationDO (cron-refreshed singleton) | | Canary rollouts | manifest_active.{canary_version, canary_weight} + deterministic hash routing in the resolver. Anomaly detector cron auto-rolls-back on flagged manifests; x-manifest-variant: stable\|canary response header on chat / OpenAI surfaces | | Inbound JWT | jose + JWKS cache. Verifiers: Cloudflare Access, Cognito. | | Outbound OAuth | Postgres-cached client-credentials tokens, AES-256-GCM-encrypted at rest via OAUTH_CACHE_KEY | | Governance pipeline | mergeWithManifest → policies → command screening → content screening → limits → guardrails → judges → approvals; each stage replaces tool.executor and preserves the inner transport label | | Background jobs | Workers Cron Triggers (*/10 * * * *) → federation refresh + memory consolidation + runScheduledJobs (invokes each due, enabled job's manifest under an UNATTENDED context, at-most-once via CAS) + retention sweep + queue-orphan sweep + anomaly detector + continuous-eval (canary online benchmarking) + plugin cron tasks (abandoned-cart scan, GEO monitor) | | Commerce | Stripe (hosted Checkout + Shared Payment Tokens, signature-verified webhooks, idempotent completion) · Postgres catalog/orders · session-log cart · approval-gated checkout · ACP merchant endpoint keyed by ACP_API_KEY · UCP merchant endpoint keyed by UCP_API_KEY | | Observability | Analytics Engine sink for counters (METRICS binding); structured-log spans with duration + attributes; judge_score, anomaly_detected, auto_rollback, manifest_canary_*, model_switch, eval_run audit event types in addition to the pre-existing tool_call / policy_decision / etc. | | Eval harness | Postgres-backed golden datasets, deterministic + Workers-AI + panel judges, trajectory rubrics scoring the tool-call sequence, adversarial seed dataset, pnpm eval CI gate (passrate + cost-tolerance + adversarial floor) | | Durable execution | spec.execution.mode: durable → AgentWorkflow (Cloudflare Workflows). Survives worker eviction mid-run; retries on transient errors; pairs with A2A tasks/resubscribe |

Bootstrapping

pnpm install
cp apps/api/wrangler.example.jsonc apps/api/wrangler.jsonc   # wrangler.jsonc is gitignored; fill in your ids

pnpm db:up                                     # local Postgres (pgvector/pgvector:pg17) via docker compose

cd apps/api                                       # bare wrangler commands run from the API app
pnpm wrangler kv namespace create CACHE        # paste the id into wrangler.jsonc
pnpm wrangler r2 bucket create felix-orchestrator-bundles
pnpm wrangler queues create felix-audit
cd ../..

pnpm build:manifests                           # produces packages/harness/src/manifests/bundled.ts + packages/harness/src/skills/bundled.ts
pnpm migrate:local                             # node-pg-migrate → the Docker Postgres
cp apps/api/.dev.vars.example apps/api/.dev.vars && $EDITOR apps/api/.dev.vars   # local secrets for `wrangler dev`
pnpm dev                                       # root scripts delegate to @felix/api

Local wrangler dev routes the HYPERDRIVE binding at the Docker Postgres via localConnectionString, so no Hyperdrive config is needed to develop. Staging and production each need one, created against the Neon DIRECT endpoint (no -pooler suffix — Hyperdrive owns pooling) with caching disabled, since Felix depends on read-after-write:

pnpm wrangler hyperdrive create felix-hyperdrive-staging \
  --connection-string='postgresql://:@/' --caching-disabled

Migrations run against the Neon direct URL, never through Hyperdrive and never with wrangler:

DATABASE_URL= pnpm migrate:staging      # or migrate:production

For deployed envs, set secrets via pnpm exec wrangler secret put --env staging|production (run from apps/api/, where wrangler.jsonc lives). The worker reads:

• ANTHROPIC_API_KEY — required for any provider: anthropic route
• OPENAI_API_KEY — required for any provider: openai route
• CF_AIG_TOKEN — Authenticated Gateway bearer; required when the AI Gateway slug enables Authenticated Gateway
• OAUTH_CACHE_KEY — base64 32-byte AES-256 key for encrypting oauth_token_cache.access_token; required in staging/production
• POLICY_BUNDLE_PUBKEY — base64 Ed25519 raw public key for verifying the federation PolicyBundle signature; required in staging/production
• CONSUMER_SHARED_SECRET — fleet-global bearer for the queue-transport write-back at POST /internal/sessions/:thread_id/events; required to run the queue transport
• ACP_API_KEY / UCP_API_KEY — bearer keys for the ACP and UCP merchant endpoints (optional; absent, those mounts report not-configured)

AI_GATEWAY_SLUG and AI_GATEWAY_ACCOUNT_ID are vars in apps/api/wrangler.jsonc, one per env.

Open-source / hybrid model routing

Anthropic/OpenAI keys are optional — both providers are read lazily at call time, so an agent that only routes to provider: workers-ai needs neither (and skips the AI Gateway entirely; Workers AI uses the native env.AI binding, so no CF_AIG_TOKEN/AI_GATEWAY_* either). Embeddings (BGE), the eval/guardrail judges, and procedural/semantic memory already run on Workers AI regardless of the chat model.

Three bundled manifests demonstrate the spectrum (packages/harness/manifests/oss-only.yaml, oss-fast.yaml, hybrid-router.yaml):

• Fully OSS — oss-only runs react on llama-3-pro (@cf/meta/llama-3.3-70b-instruct-fp8-fast, one of the tool-capable Workers AI models). Set DEFAULT_MODEL_ID to an OSS route and leave the proprietary keys unset to run key-free.
• Hybrid — hybrid-router puts inten

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: blakebauman
• Source: blakebauman/felix
• License: MIT
• Homepage: https://docs.felix.run

Install and usage instructions live in the source repository linked above.