aiworkforce

v0.1.2

Published

10 days ago

Event-native runtime and orchestration plane for long-lived agents and software objectives.

0High
0Medium
0Low

sanagpal85

receipt cli agents orchestration factory bun

Receipt

Receipt is an event-native runtime and orchestration plane for long-lived agents and software objectives.

Instead of treating traces and job state as incidental logs, Receipt stores immutable, hash-linked receipts and derives runs, jobs, memory, objectives, replay, and operator views from them by folding the same receipts.

Core Concepts

What is "Receipt"?

Receipt is the event-native substrate. Everything durable—agent runs, jobs, memory, Factory objectives—is meant to be replayed by folding the same receipts, not by mutating hidden rows.

Primitives: Live in the published core package aiworkforce-core (packages/core/src/). Features include createRuntime, hashing, fold, branching, and Store / BranchStore contracts.
Persistence: Implemented via SQLite (src/adapters/jsonl.ts, backing receipts and streams tables). Projections are maintained for quick query access (drizzle/).
Domain Modules: Typed events, reducers, and decide functions sit in src/modules/ (notably agent.ts, job.ts, and the factory/ directory).

What is "Factory"?

Factory is the receipt-native control plane for software objectives on a repository. It provides the task DAG, worker dispatch, candidate review, integration, validation, and promotion. Each step is recorded as Factory receipts on streams under factory/objectives/<objectiveId>.

Code Plane: Git and worktrees remain the code plane.
Orchestration Plane: Receipt acts as the orchestration plane.
No Hidden State: The FactoryService orchestrates events but has no separate durable "service state". Everything is derived from the receipt streams.

Architecture Layers

flowchart TD
  subgraph Data
    RS[(Receipt Store / SQLite)]
    PS[(Projections / Drizzle)]
  end

  subgraph Workers
    CQ[Queue: Resonate / Local]
    CW[Workers: Factory, Codex]
    CQ --> CW
  end

  subgraph Application
    Srv[Hono Server]
    FS[Factory Service]
    AM[Agent Modules]
    Srv --> FS
    FS --> AM
    FS --> CQ
    FS --> RS
    RS --> PS
  end

  subgraph Presentation
    UI[Web UI / HTMX]
    CLI[Terminal UI / Ink]
    UI --> Srv
    CLI --> Srv
  end

The repository is built in stacked layers:

Layer A — Transport and Composition

src/server.ts: The Hono application that wires DATA_DIR, the job backend (local or resonate), and creates the core runtimes (agent, job, memory). It builds the queue, SseHub, OpenAI adapters, and FactoryService, attaches REST endpoints (/agents, /jobs, /healthz), and starts workers.

Layer B — HTTP Routes (Agents as Route Modules)

src/framework/agent-loader.ts: Discovers src/agents/*.agent.ts and loads each default export.
Factory Route: src/agents/factory.agent.ts re-exports the extensive Factory surface (/factory, HTMX islands, SSE, chat, workbench) from src/agents/factory/route.ts.

Layer C — Factory Execution Seam

src/services/factory-service.ts: The central orchestrator class. It reads/writes Factory streams via createRuntime, enqueues jobs, talks to Codex/Git/memory/SSE, and manages objective control and promotion.
Worker Handlers: src/services/factory-runtime.ts exposes createFactoryWorkerHandlers, mapping job agentId (factory-control, codex) to their respective execution paths (runObjectiveControl, runTask).

Layer D — Semantic / LLM Orchestration

src/agents/orchestrator.ts: The entry point for chat and supervisor interactions. It branches between runFactoryChat (for Factory-specific chats) and runCodexSupervisor.

Layer E — Generic Agent Run Loop

SDK: src/sdk/agent.ts provides defineAgent and runDefinedAgent.
CLI Delegation: src/cli/commands.ts handles receipt new, run, trace, replay, inspect, delegating Factory commands to handleFactoryCommand.

Layer F — UI (Server-Rendered Projections)

Views: Server-rendered HTML from src/views/*.
Client Behavior: src/client/factory-client.ts boots HTMX, chat, workbench, and receipt browser from DOM markers.
Principle: The UI is purely a projection of Receipt state. It refreshes via SSE/HTMX invalidations. There is no second client source of truth.

Layer G — Factory CLI / TUI

Terminal UI: src/factory-cli/* uses Ink and React for terminal-based dashboards, utilizing the exact same fold-over-receipts pattern as the server for local inspection.

Data Flow (Factory Loop)

Initiation: An operator or API creates/runs an objective. Factory receipts are appended to factory/objectives/... via FactoryService.
Derivation: The reducer (reduceFactory) and selectors derive what actions are legally permitted next.
Dispatch: The service enqueues jobs onto jobs / jobs/<jobId>.
Execution: Workers run handlers (factory-control for objectives, codex for task execution/polling).
Normalization: Results are normalized back into Factory receipts. Git is updated through HubGit. SSE publishes topics causing HTMX islands to refresh.
Projection: SQLite projectors maintain query-friendly projections for UI and DB features.

Technologies Used

| Area | Stack | |------|--------| | Runtime | Bun (bun:sqlite), TypeScript | | HTTP Framework| Hono | | Validation | Zod, @hono/zod-validator | | Database | Drizzle ORM + SQLite | | Queue | Resonate (@resonatehq/sdk, optional) or Local JSONL Queue | | LLM | OpenAI SDK | | CLI / Workers | Ink, React, @clack/prompts | | Web UI | HTMX, htmx-ext-sse, Vanilla JS/TS | | Styling | Tailwind CSS v4 | | Monorepo | Workspace package aiworkforce-core |

Repository Map

| Path | Responsibility | |------|----------------| | packages/core/ | Receipt chain, runtime, graph types | | src/sdk/ | Agent authoring API | | src/modules/ | Agent, job, factory reducers/events | | src/engine/runtime/| Agent loop, job worker, control receipts, Resonate actions | | src/adapters/ | SQLite store, queue, Codex, OpenAI, memory, Git helpers | | src/services/ | Factory service, planners, artifacts, workers | | src/agents/ | Orchestrator, factory route, capabilities, codex supervisor | | src/factory-cli/ | Factory-focused CLI/TUI | | src/views/, src/client/, src/styles/| Server HTML, browser TS, Tailwind assets | | src/db/ | Schema, client, projectors, importer | | src/framework/ | Agent loader, HTTP helpers, SSE hub | | .receipt/ | Repo-local config and data roots | | docs/ | Deep documentation and architecture records |

Prerequisites

bun for development and CLI execution
codex on PATH for Factory task execution
resonate on PATH for the default dev and start runtime
OPENAI_API_KEY for model-backed features such as chat, planning, and embeddings

Quick Start

bun install
bun run build

# default: single-process runtime backed by local SQLite
bun run dev

# optional: multi-process runtime + local Resonate
bun run dev:resonate

Inside this repo, prefer:

bun run factory
bun src/cli.ts <command>

npm Package

Receipt is published as a Bun-native CLI. End users should have Bun installed before invoking the package binary.

npm install -g aiworkforce
aiworkforce --help

Because the repo is a workspace, publish the internal core package first and the CLI package second:

npm publish --workspace aiworkforce-core --access public
npm publish --access public

You can preview the root package contents before publishing with:

npm run pack:dry-run

Common Commands

# scaffold a new agent
bun src/cli.ts new my-agent --template basic

# open the Factory operator surface
bun run factory

# create or run Factory objectives
bun src/cli.ts factory create --prompt "Plan a README refresh"
bun src/cli.ts factory run --prompt "Update the architecture docs"

# steer or follow up on a live Factory job
bun src/cli.ts factory steer job_demo --message "Retarget this run to the live-output bug"
bun src/cli.ts factory follow-up job_demo --message "Keep the receipt links stable"

# inspect jobs and receipts
bun src/cli.ts jobs --status running --limit 20
bun src/cli.ts inspect <run-id-or-stream>
bun src/cli.ts trace <run-id-or-stream>
bun src/cli.ts replay <run-id-or-stream>
bun src/cli.ts fork <run-id-or-stream> --at 12

# work with receipt-backed memory
bun src/cli.ts memory read factory/objectives/<objective-id> --limit 5
bun src/cli.ts memory search factory/repo/shared --query "integration failure"

The live guidance commands target a Factory-visible job directly:

receipt factory steer <job-id> --message "<updated direction>" retargets the active run when the operator needs to correct the plan.
receipt factory follow-up <job-id> --message "<extra context>" adds constraints or extra evidence without replacing the original task.

In the Factory chat composer, the same actions are available as slash commands:

/steer Retarget this run to the live-output bug.
/follow-up Keep the receipt links stable.

Runtime Modes

Receipt currently supports two runtime topologies.

Local SQLite Default

Starts the local Receipt server directly and persists runtime state in ${DATA_DIR}/receipt.db.

bun run dev
bun run start

Resonate Optional Dispatch

Starts the Receipt API, Resonate driver, workers (chat, control, codex), and a local Resonate server.

bun run dev:resonate
bun run start:resonate
JOB_BACKEND=resonate receipt dev

Repo-local State

The checked-in config currently points Receipt at:

config: .receipt/config.json
receipt data: .receipt/data
Resonate SQLite state: .receipt/resonate

Web and API Surfaces

/factory: Main web operator shell for chats, objectives, task state, live output.
/receipt: Browser for raw receipt streams and folds.
/healthz: Runtime health snapshot.
/jobs, /jobs/:id: Queue inspection and live updates.
/memory/*: Memory read/search/summarize APIs.

UI rule of thumb: Receipt is the source of truth. UI islands are projections that refresh on live invalidation.

Docker

Dev Container

Bind-mounts the repo, uses repo-local .receipt/ state. Best for iterative work.

bun run docker:dev:up
bun run docker:dev:down

Prod-style Container

Runs from an image without bind-mounting the full repo.

bun run docker:prod:up
bun run docker:prod:down

Both modes expose: http://localhost:8787 (Receipt), http://localhost:8001 (Resonate HTTP), http://localhost:9090/metrics (Resonate metrics).

Development

bun run build
bun run test:smoke
bun run verify

Docs

Start here: