# Felix

> Managed agents harness on Cloudflare Workers — manifest-defined AI agents with swappable session strategies, agent patterns, and tool transports (MCP, A2A, sandbox, browser), plus an agentic commerce layer (ACP, Stripe, B2B).

- **Type:** MCP server
- **Install:** `agentstack add mcp-blakebauman-felix`
- **Verified:** Pending review
- **Seller:** [blakebauman](https://agentstack.voostack.com/s/blakebauman)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [blakebauman](https://github.com/blakebauman)
- **Source:** https://github.com/blakebauman/felix
- **Website:** https://docs.felix.run

## Install

```sh
agentstack add mcp-blakebauman-felix
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://www.anthropic.com/engineering/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](https://developers.openai.com/commerce) 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 (tenant_id, 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 (pass_rate + 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

```bash
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:

```bash
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:

```bash
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](https://github.com/blakebauman)
- **Source:** [blakebauman/felix](https://github.com/blakebauman/felix)
- **License:** MIT
- **Homepage:** https://docs.felix.run

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** yes

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-blakebauman-felix
- Seller: https://agentstack.voostack.com/s/blakebauman
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.