Skip to content

feat: platform-agnostic orchestrator + crypto-payments example - #8

Merged
papismurf merged 7 commits into
mainfrom
feat/platform-agnostic-impl
Jul 7, 2026
Merged

feat: platform-agnostic orchestrator + crypto-payments example#8
papismurf merged 7 commits into
mainfrom
feat/platform-agnostic-impl

Conversation

@papismurf

@papismurf papismurf commented Jul 7, 2026

Copy link
Copy Markdown
Owner

Summary

Converts the Cloudflare-only Dynamic Workers orchestrator into a
platform-agnostic, ports-and-adapters architecture (backward compatible with
the existing Cloudflare deploy) and adds a new modular crypto-payments example.

  • LLM provider layer (src/providers/llm/): Anthropic + OpenAI-compatible
    (OpenAI/DeepSeek/Ollama/self-hosted), selected by a registry, with pricing and
    retry helpers and an injectable fetchImpl for egress control. bindings/llm.ts
    now delegates here without changing its public contract.
  • Runtime-neutral orchestration core (src/core/): pure state machine, task
    decomposition, bounded-concurrency semaphore, cost-accurate self-heal, and an
    in-memory StateStore — no Cloudflare primitives.
  • Local no-Cloudflare runtime (src/runtime/, src/local/): EgressPolicy
    (domain allowlist + credential injection), LocalRuntime, and a Node HTTP
    server with SSE log streaming (npm run dev:local).
  • New example examples/crypto-payments/: one PaymentProvider port with
    swappable Stripe / PayPal / Coinbase / Mock adapters selected purely via
    PAYMENT_PROVIDER. Signature-verified webhooks (timing-safe HMAC; Stripe
    replay tolerance; PayPal server-side verify), currency-aware integer money,
    and error paths that don't leak upstream responses.
  • Docs: docs/platform-agnostic-feasibility.md, ADRs 0001–0004,
    docs/technical-summary.md.
  • Enhancers: Principal Software Engineer agent skill, per-commit
    review-agent gate, and a CI quality gate for the example
    (.github/workflows/crypto-payments-ci.yml).

Test plan

  • examples/crypto-payments: npm run typecheck clean; npm test 15/15 passing
  • New core/runtime/LLM modules covered by unit tests (orchestrator, semaphore, egress, local runtime, registry, pricing, retry, config, server)
  • Independent review-agent gate: REQUEST-CHANGES → fixes → APPROVE on the example
  • CI workflow runs on PR (typecheck + tests + npm audit)

Notes / known pre-existing issues (out of scope)

  • Root npm run typecheck is red because the root tsconfig.json includes
    *.test.ts without Jest types (tests still compile via ts-jest). Follow-up:
    exclude tests from root tsc or add a tsconfig.test.json-based script.
  • A few root unit tests fail locally due to missing WebSocketPair shims /
    Node 24 fake-timer flakiness — environmental, not caused by this change.

Made with Cursor

David Brown and others added 7 commits July 7, 2026 20:56
David Brown @cursoragent
docs: add platform-agnostic feasibility deep-dive and ADRs
fa82300 
Task 1 deliverable on the analysis branch. Assesses decoupling the
orchestrator from Cloudflare Dynamic Workers so it can run on any host
against any concurrent-capable LLM backend (Anthropic, OpenAI, DeepSeek,
open-source/self-hosted).

- docs/platform-agnostic-feasibility.md: verdict (yes-with-constraints),
  Cloudflare coupling map, target ports-and-adapters architecture
  (AgentRuntime, LlmProvider, StateStore), concurrency implications per
  backend, phased migration plan, risks, effort estimate.
- docs/adr/0001..0004: runtime/compute abstraction, LLM provider
  abstraction, payment provider abstraction (example), state &
  observability portability.

Verified against source by an independent review agent.

Co-authored-by: Cursor <cursoragent@cursor.com>
David Brown @cursoragent
feat(llm): provider-agnostic LLM layer (Anthropic/OpenAI/DeepSeek/Ope…
762ab48 
…nAI-compatible)

Phase B of the platform-agnostic refactor (ADR-0002). Extracts the
hardcoded two-provider switch in the Cloudflare LLM binding into a
runtime-neutral provider layer usable both inside Workers and in the
local Node runtime.

- src/providers/llm/: LlmProvider port, AnthropicProvider,
  OpenAiCompatibleProvider (powers OpenAI, DeepSeek, and any
  self-hosted/open-source OpenAI-compatible endpoint), a registry
  factory, a shared withRetry helper, and a per-model pricing table.
- src/bindings/llm.ts now delegates provider selection to
  createLlmProvider and retry/backoff to withRetry (single source of
  truth). Wire format, headers, error strings, and return shape are
  preserved; existing llm.test.ts passes unchanged.
- Adds 429 to the retryable set (fixes a prior duplicated-529 typo that
  made 429 non-retryable).
- Tests: registry/adapter wire-format, pricing prefix matching, retry
  semantics. 20 new assertions, all green.

Reviewed by an independent review agent (APPROVE-WITH-NITS; nits fixed:
withRetry adoption, baseUrl trailing-slash normalization, usage optional
chaining, pricing token-boundary matching).

Co-authored-by: Cursor <cursoragent@cursor.com>
David Brown @cursoragent
feat(core): runtime-neutral orchestration core + local no-Cloudflare …
964bdb7 
…runtime

Phases A/C/D of the platform-agnostic refactor (ADR-0001, ADR-0004).
Adds a runtime-neutral orchestration engine and a local execution path
that runs concurrent multi-agent orchestration with no Cloudflare
account (only an LLM API key).

Core (src/core):
- Ports: StateStore, AgentRuntime.
- Orchestrator engine: dependency-wave scheduling with a bounded
  Semaphore, self-heal retries (cost accumulated across attempts),
  failed-dependency skipping, review/cost flow. Injectable decompose.
- InMemoryStateStore, pure state-machine (transition table + cost
  aggregation), decomposeTask.

Runtime (src/runtime):
- EgressPolicy: domain allowlist + credential injection + guardedFetch,
  the shared implementation of the Cloudflare HttpGateway policy.
- LocalRuntime: runs agents in-process against injected capability
  bindings (in-memory FS + provider-layer LLM), egress enforced via
  guardedFetch threaded into the provider (fetchImpl).

Agents (src/agents/runners.ts): in-process codegen/test/review logic,
the runtime-neutral counterpart of the embedded Dynamic Worker sources.

Local server (src/local): env-driven config, LogHub (SSE fan-out),
node:http REST + SSE server exposing the same API surface, plus a
`dev:local`/`start:local` entry via tsx.

Tooling: add ts-node (required by jest.config.ts but previously missing)
and tsx (local runtime). 48 new unit tests; full suite unchanged at the
pre-existing 9 env-flaky failures.

Reviewed by an independent review agent across two rounds
(REQUEST-CHANGES -> APPROVE-WITH-NITS); all must-fix items resolved:
egress wiring, self-heal cost accounting, revise result-clearing,
failed-dependency skipping, and scheduler concurrency tests.

Co-authored-by: Cursor <cursoragent@cursor.com>
David Brown @cursoragent
feat(examples): add platform-agnostic crypto-payments example
d8eeab2 
Streamlined payment service demonstrating the same ports-and-adapters
pattern as the orchestrator's LLM layer: one PaymentProvider port with
interchangeable Stripe, PayPal, Coinbase Commerce, and Mock adapters
selected purely by configuration.

- Webhook signatures verified per provider (timing-safe HMAC-SHA256;
  Stripe replay tolerance; PayPal server-side verification) before any
  event data is trusted.
- Currency-aware money handling in integer minor units (JPY/crypto safe).
- Node HTTP server exposes health/charge/status/webhook endpoints; error
  paths avoid leaking upstream provider responses.
- Tests (Node test runner via tsx) cover provider selection, charge
  mapping, money conversion, and valid/tampered/replayed webhooks.

Reviewed by the review-agent quality gate (APPROVE); tsc --noEmit clean,
15/15 tests passing.

Co-authored-by: Cursor <cursoragent@cursor.com>
David Brown @cursoragent
chore(skill): add Principal Software Engineer agent skill
f0ba111 
Encapsulates the engineering standards used throughout this work: plan-first,
respect conventions, a per-change quality gate (typecheck/tests/security), a
design/architecture review checklist, and a mandatory independent review-agent
workflow with blocking findings.

Co-authored-by: Cursor <cursoragent@cursor.com>
David Brown @cursoragent
docs(summary): add technical summary and crypto-payments CI gate
dfb6e72 
Summarize the platform-agnostic feasibility outcome and Task 2 implementation
(runtime/LLM/state ports, local Node runtime, crypto-payments example), and
add a GitHub Actions quality gate (typecheck + tests + npm audit) scoped to the
new example. Documents known pre-existing root typecheck/test issues as
follow-ups.

Co-authored-by: Cursor <cursoragent@cursor.com>
David Brown @cursoragent
ci(crypto-payments): run on Node 22 so the test glob expands
942ec98 
Node's built-in test runner only expands glob patterns (src/**/*.test.ts)
from Node 21+. On Node 20 the pattern was treated as a literal path, so
`npm test` failed with "Could not find .../src/**/*.test.ts".

Co-authored-by: Cursor <cursoragent@cursor.com>
@papismurf
papismurf merged commit 9fe7eda into main Jul 7, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@papismurf