npm package: @kentronai/receipt-cli
Description: Event-native runtime and orchestration plane for long-lived agents
Latest version: 0.1.1

# 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.

## Install

**Prerequisite**: Receipt requires the [Bun](https://bun.sh) runtime (v1.0+).

```bash
# Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash

# Install Receipt globally
npm install -g @kentronai/receipt-cli
# OR
bun add -g @kentronai/receipt-cli

# Verify
receipt --help
```

## Configuration

Receipt reads environment variables directly and also loads `.env` files from your working directory automatically (built-in Bun behavior).

### Required

| Variable | Description |
|----------|-------------|
| `OPENAI_API_KEY` | OpenAI API key for LLM and embedding calls. Get one at [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |

### Optional

| Variable | Default | Description |
|----------|---------|-------------|
| `OPENAI_MODEL` | `gpt-5.2` | Default model for agent calls |
| `PORT` | `8787` | HTTP server port |
| `JOB_BACKEND` | `local` | Job backend: `local` (SQLite queue) or `resonate` |
| `RECEIPT_DATA_DIR` | `.receipt/data` | Custom data directory |
| `RECEIPT_CODEX_BIN` | `codex` | Path to codex binary |
| `AWS_ACCESS_KEY_ID` | — | AWS credentials for Factory cloud features |
| `AWS_SECRET_ACCESS_KEY` | — | AWS credentials for Factory cloud features |
| `AWS_REGION` | — | AWS region override |

Copy the included `.env.example` to `.env` in your project directory and fill in your keys:

```bash
cp .env.example .env
# Edit .env with your OPENAI_API_KEY
```

## Quick Start

```bash
# Set your API key
export OPENAI_API_KEY=sk-...

# Start the Receipt server (opens Factory UI at http://localhost:8787/factory)
receipt dev

# Or use the interactive Factory CLI
receipt factory

# Scaffold a new agent
receipt new my-agent --template basic

# Run an agent
receipt run my-agent --problem "Hello world"

# Create a Factory objective
receipt factory create --prompt "Plan a README refresh"
```

## Common Commands

```bash
# Factory operations
receipt factory                     # Interactive Factory CLI
receipt factory create --prompt "..." # Create objective
receipt factory run --prompt "..."    # Create and run objective
receipt factory steer <job-id> --message "..." # Redirect a running job
receipt factory follow-up <job-id> --message "..." # Add context to a job

# Agent operations
receipt new <agent-id> --template basic  # Scaffold agent
receipt run <agent-id> --problem "..."   # Run agent

# Inspection
receipt jobs --status running --limit 20
receipt inspect <run-id-or-stream>
receipt trace <run-id-or-stream>
receipt replay <run-id-or-stream>
receipt fork <run-id-or-stream> --at 12

# Memory
receipt memory read <scope> --limit 5
receipt memory search <scope> --query "search term"
```

## Web Surfaces

When the server is running (`receipt dev` or `receipt start`):

| URL | Description |
|-----|-------------|
| `/factory` | Main operator UI — chats, objectives, task state, live output |
| `/receipt` | Receipt stream browser |
| `/healthz` | Runtime health check |
| `/jobs` | Queue inspection and live updates |
| `/memory/*` | Memory read/search/summarize APIs |

## Troubleshooting

**`command not found: bun`** — Install Bun: `curl -fsSL https://bun.sh/install | bash`

**`OPENAI_API_KEY is not set`** — Set the key via `export OPENAI_API_KEY=sk-...` or add it to a `.env` file in your project directory.

**`receipt: command not found`** — Ensure the npm global bin directory is on your PATH. Run `npm bin -g` to find the location.

**Windows** — The `receipt` binary uses a `#!/usr/bin/env bun` shebang which may not work natively on Windows. Use `bun receipt <command>` directly instead.

---

## Out of Scope (v1)

- Node.js runtime support (Receipt requires Bun due to `bun:sqlite`, `Bun.serve()`)
- Windows native support
- Docker image publishing
- Resonate distributed mode auto-setup

---

## Development

The sections below are for contributors working on Receipt itself.

### Prerequisites (Development)

- `bun` for development and CLI execution
- `codex` on `PATH` for Factory task execution
- `resonate` on `PATH` for the optional distributed runtime
- `OPENAI_API_KEY` for model-backed features

### Dev Setup

```bash
git clone <repo-url>
cd receipt
bun install
bun run build

# Local SQLite mode (default)
bun run dev

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

### Core Concepts

**Receipt** is the event-native substrate. Everything durable — agent runs, jobs, memory, Factory objectives — is replayed by folding the same receipts.

- **Primitives**: `src/core/` — `createRuntime`, hashing, `fold`, branching, and `Store` / `BranchStore` contracts.
- **Persistence**: SQLite (`src/adapters/jsonl.ts`, backing `receipts` and `streams` tables). Projections via Drizzle ORM (`drizzle/`).
- **Domain Modules**: Typed events, reducers, and decide functions in `src/modules/`.

**Factory** is the receipt-native control plane for software objectives. It provides task DAG, worker dispatch, candidate review, integration, validation, and promotion — all recorded as Factory receipts.

### Architecture Layers

```mermaid
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
```

### Technologies

| 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 SQLite Queue |
| **LLM** | OpenAI SDK |
| **CLI / Workers** | Ink, React, `@clack/prompts` |
| **Web UI** | HTMX, `htmx-ext-sse`, Vanilla JS/TS |
| **Styling** | Tailwind CSS v4 |

### Repository Map

| Path | Responsibility |
|------|----------------|
| `src/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 |

### Runtime Modes

**Local SQLite (default)** — single-process, persists in `${DATA_DIR}/receipt.db`:
```bash
bun run dev
bun run start
```

**Resonate (optional)** — multi-process with distributed job dispatch:
```bash
bun run dev:resonate
bun run start:resonate
```

### Docker

```bash
# Dev container (bind-mounts repo)
bun run docker:dev:up
bun run docker:dev:down

# Prod-style container
bun run docker:prod:up
bun run docker:prod:down
```

### Testing

```bash
bun run build
bun run test:smoke
bun run verify        # build + type check + smoke tests
```

### Docs

- [architecture.md](./architecture.md)
- [docs/api/README.md](./docs/api/README.md)
- [docs/agent-framework.md](./docs/agent-framework.md)
- [docs/context-management.md](./docs/context-management.md)
- [docs/create-agent.md](./docs/create-agent.md)
- [docs/factory-on-receipt.md](./docs/factory-on-receipt.md)
- [docs/factory-agent-orchestration.md](./docs/factory-agent-orchestration.md)
- [docs/factory-profile-orchestration.md](./docs/factory-profile-orchestration.md)
- [docs/factory-infrastructure-engineer.md](./docs/factory-infrastructure-engineer.md)
- [docs/factory-self-improvement.md](./docs/factory-self-improvement.md)