@citadel-labs/citadel 0.1.0

package/README.md

@@ -0,0 +1,145 @@
+# CITADEL
+
+Cold-start, hub-and-spoke orchestration for autonomous LLM agents.
+
+CITADEL coordinates multiple LLM "Citizens" across independent code repositories ("Outposts"). Agents don't idle -- they are summoned, work in isolated git worktrees, deliver Tribute, and go dark. Everything persists in append-only JSONL records called Beads. Sessions are ephemeral; state survives.
+
+## How It Works
+
+```
+Commander (you)
+    |  issues orders via CLI
+    v
+First Officer (persistent LLM agent, agent-agnostic)
+    |  selects archetype, mints citizen_id, writes Mail
+    v
+Courier (daemon)
+    |  watches filesystem, manages worktrees, spawns Citizens
+    v
+Citizens (cold-start LLM agents in isolated git worktrees)
+    |  read Mail, do work, write Tribute
+    v
+First Officer receives Tribute, validates, broadcasts, retries or escalates
+```
+
+## Install
+
+```bash
+npm install -g @citadel-labs/citadel
+```
+
+Requires Node.js v20+. Works on macOS, Linux, and Windows.
+
+## Quick Start
+
+```bash
+citadel init my-project
+cd my-project
+
+citadel outpost register --slug api-gateway --path ../api-gateway
+citadel start
+citadel dispatch --outpost api-gateway --task "Implement GET /health endpoint"
+citadel status
+citadel tribute --task <task-id>
+citadel trace --task <task-id>
+```
+
+See [Getting Started](docs/getting-started.md) for a full walkthrough.
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `citadel init [dir]` | Scaffold workspace |
+| `citadel start [--agent <runtime>]` | Boot the First Officer |
+| `citadel stop` | Graceful shutdown |
+| `citadel status` | Session info and outpost overview |
+| `citadel outpost register --slug <name> --path <path>` | Register a repo |
+| `citadel dispatch --outpost <slug> --task <text>` | Assign a task |
+| `citadel note --outpost <slug> --body <text>` | Send guidance |
+| `citadel resolve --task-id <id> --action <action>` | Resolve escalation |
+| `citadel command retry --task <id>` | Force retry |
+| `citadel tribute --task <id>` | View tribute attempts |
+| `citadel trace --task <id>` | Full event timeline |
+| `citadel reset [--hard]` | Clear state (hard removes `.citadel/`) |
+| `citadel worktree list/prune` | Manage worktrees |
+
+Full details: [CLI Reference](docs/cli-reference.md)
+
+## Architecture
+
+| Role | What It Does | Writes |
+|---|---|---|
+| **Commander** | Issues orders, reviews Broadcasts | Command Beads |
+| **First Officer** | Orchestrates -- dispatch, retry, escalate | Mail Beads (downward) |
+| **Courier** | Watches filesystem, spawns Citizens | Nudge Beads only |
+| **Citizens** | Execute tasks in isolated worktrees | Tribute + Mail (upward) |
+
+All state lives in append-only JSONL Beads, written through `appendBead()` with lockfile serialization. Mail is the sole wake trigger. Nudges are disposable signals. Full details: [Architecture](docs/architecture.md)
+
+## Workspace Layout
+
+```
+my-project/
+  courier.config.yaml
+  .citadel/
+    identity.jsonl
+    outposts.json
+    nudges.jsonl
+    commands/
+    logs/
+  grand-archives/
+    first-officer/
+    archetypes/
+    shared/
+  outposts/
+```
+
+## Configuration
+
+`courier.config.yaml` at the workspace root:
+
+```yaml
+citadel_root: .
+poll_interval_ms: 500
+debounce_ms: 200
+default_max_citizens: 3
+citizen_timeout_seconds: 1800
+log_level: INFO
+```
+
+Full details: [Configuration](docs/configuration.md)
+
+## Design Principles
+
+- **Mail is the universal envelope.** Every activation begins with a Mail Bead.
+- **Beads are state. Nudges are signals.** Full state from Mail + Tribute only.
+- **Write authority is strict.** FO writes down. Citizens write up. Courier writes Nudge only.
+- **Writes are serialized via lockfiles.** Cross-platform safe.
+- **Identity persists. Sessions are cattle.** Kill and restart freely.
+- **Everything communicates via files.** No PIDs, no pipes, no tight coupling.
+
+## Development
+
+```bash
+git clone <repo>
+cd citadel
+npm install
+npm run build
+npm test
+```
+
+See [Contributing](docs/contributing.md) for full guidelines.
+
+## Current Status
+
+Milestones 0-3 implemented.
+
+- **M0** -- Scaffold: Types, Grand Archives, CLI entrypoint
+- **M1** -- Foundation: Bead I/O, Courier, WorktreeManager, ProcessRegistry, CLI
+- **M2** -- Labor & Tribute: First Officer, Citizen lifecycle, retry, escalation
+- **M3** -- Broadcast & Routing: Dependencies, relay, task reports, webhook
+
+## License
+
+MIT

package/dist/__tests__/append-bead.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=append-bead.test.d.ts.map

package/dist/__tests__/append-bead.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"append-bead.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/append-bead.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/append-bead.test.js

@@ -0,0 +1,88 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { appendBead, readBeads, mintBeadId } from '../core/append-bead.js';
+import { SCHEMA_VERSION } from '../types/index.js';
+function makeBead(overrides = {}) {
+    return {
+        bead_id: mintBeadId(),
+        bead_type: 'NUDGE',
+        schema_version: SCHEMA_VERSION,
+        created_at: new Date().toISOString(),
+        ...overrides,
+    };
+}
+describe('appendBead', () => {
+    let tmpDir;
+    beforeEach(async () => {
+        tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'citadel-test-'));
+    });
+    afterEach(async () => {
+        await fs.rm(tmpDir, { recursive: true, force: true });
+    });
+    it('appends a bead and reads it back with matching fields', async () => {
+        const filePath = path.join(tmpDir, 'beads.jsonl');
+        const bead = makeBead();
+        const returned = await appendBead(filePath, bead);
+        expect(returned).toEqual(bead);
+        const beads = await readBeads(filePath);
+        expect(beads).toHaveLength(1);
+        expect(beads[0].bead_id).toBe(bead.bead_id);
+        expect(beads[0].bead_type).toBe(bead.bead_type);
+        expect(beads[0].schema_version).toBe(bead.schema_version);
+        expect(beads[0].created_at).toBe(bead.created_at);
+    });
+    it('handles 10 rapid sequential appends without data loss', async () => {
+        const filePath = path.join(tmpDir, 'concurrent.jsonl');
+        const beads = Array.from({ length: 10 }, () => makeBead());
+        // Append all beads sequentially in rapid succession
+        for (const b of beads) {
+            await appendBead(filePath, b);
+        }
+        const written = await readBeads(filePath);
+        expect(written).toHaveLength(10);
+        // Verify each bead is on its own line (no partial/merged lines)
+        const raw = await fs.readFile(filePath, 'utf-8');
+        const lines = raw.split('\n').filter((l) => l.trim() !== '');
+        expect(lines).toHaveLength(10);
+        // Each line must parse as valid JSON
+        for (const line of lines) {
+            expect(() => JSON.parse(line)).not.toThrow();
+        }
+        // All original bead_ids are present
+        const writtenIds = new Set(written.map((b) => b.bead_id));
+        for (const bead of beads) {
+            expect(writtenIds.has(bead.bead_id)).toBe(true);
+        }
+    });
+});
+describe('readBeads', () => {
+    let tmpDir;
+    beforeEach(async () => {
+        tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'citadel-test-'));
+    });
+    afterEach(async () => {
+        await fs.rm(tmpDir, { recursive: true, force: true });
+    });
+    it('returns empty array for an empty file', async () => {
+        const filePath = path.join(tmpDir, 'empty.jsonl');
+        await fs.writeFile(filePath, '');
+        const beads = await readBeads(filePath);
+        expect(beads).toEqual([]);
+    });
+    it('returns empty array for a missing file', async () => {
+        const filePath = path.join(tmpDir, 'nonexistent.jsonl');
+        const beads = await readBeads(filePath);
+        expect(beads).toEqual([]);
+    });
+});
+describe('mintBeadId', () => {
+    it('returns a string starting with "bead-" of reasonable length', () => {
+        const id = mintBeadId();
+        expect(id).toMatch(/^bead-.+$/);
+        expect(id.length).toBeGreaterThanOrEqual(10);
+        expect(id.length).toBeLessThanOrEqual(50);
+    });
+});
+//# sourceMappingURL=append-bead.test.js.map

package/dist/__tests__/append-bead.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"append-bead.test.js","sourceRoot":"","sources":["../../src/__tests__/append-bead.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/blocked-outposts.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=blocked-outposts.test.d.ts.map

package/dist/__tests__/blocked-outposts.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocked-outposts.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/blocked-outposts.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/blocked-outposts.test.js

@@ -0,0 +1,142 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import { getBlockedOutposts } from '../core/blocked-outposts.js';
+describe('getBlockedOutposts', () => {
+    let tmpDir;
+    let alphaPath;
+    let betaPath;
+    beforeEach(async () => {
+        tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'citadel-blocked-'));
+        alphaPath = path.join(tmpDir, 'outposts', 'alpha');
+        betaPath = path.join(tmpDir, 'outposts', 'beta');
+        // Create dirs
+        await fs.mkdir(path.join(tmpDir, '.citadel'), { recursive: true });
+        await fs.mkdir(path.join(alphaPath, '.beads', 'mail'), { recursive: true });
+        await fs.mkdir(path.join(alphaPath, '.beads', 'tribute'), { recursive: true });
+        await fs.mkdir(path.join(betaPath, '.beads', 'mail'), { recursive: true });
+        await fs.mkdir(path.join(betaPath, '.beads', 'tribute'), { recursive: true });
+        // Write registry
+        const registry = {
+            schema_version: '1.0',
+            outposts: [
+                { slug: 'alpha', path: alphaPath, status: 'ACTIVE', registered_at: '2026-01-01T00:00:00Z' },
+                { slug: 'beta', path: betaPath, status: 'ACTIVE', registered_at: '2026-01-02T00:00:00Z' },
+            ],
+        };
+        await fs.writeFile(path.join(tmpDir, '.citadel', 'outposts.json'), JSON.stringify(registry));
+    });
+    afterEach(async () => {
+        await fs.rm(tmpDir, { recursive: true, force: true });
+    });
+    const makeMail = (taskId, to, deps) => ({
+        bead_id: `bead-${taskId}`,
+        bead_type: 'MAIL',
+        schema_version: '9.0',
+        created_at: '2026-01-01T00:00:00Z',
+        task_id: taskId,
+        mail_type: 'TASK_ASSIGNMENT',
+        from: 'citadel',
+        to,
+        subject: `Task ${taskId}`,
+        read: false,
+        retry_of: null,
+        payload: {
+            archetype: 'software-engineer',
+            citizen_id: `citizen-${taskId}`,
+            priority: 'MEDIUM',
+            title: `Task ${taskId}`,
+            description: 'test',
+            acceptance_criteria: [],
+            context_refs: [],
+            dependencies: deps,
+            timeout_seconds: 1800,
+        },
+    });
+    const makeTribute = (taskId, outpost, status) => ({
+        bead_id: `tribute-${taskId}`,
+        bead_type: 'TRIBUTE',
+        schema_version: '9.0',
+        created_at: '2026-01-01T01:00:00Z',
+        citizen_id: `citizen-${taskId}`,
+        task_id: taskId,
+        originating_mail_ref: `bead-${taskId}`,
+        archetype: 'software-engineer',
+        outpost,
+        worktree: `worktrees/citizen/${taskId}`,
+        attempt: 1,
+        status,
+        summary: 'done',
+        artifacts: [],
+        acceptance_met: [],
+        elapsed_seconds: 60,
+    });
+    const writeMail = async (outpostPath, taskId, mail) => {
+        await fs.writeFile(path.join(outpostPath, '.beads', 'mail', `${taskId}.jsonl`), JSON.stringify(mail) + '\n');
+    };
+    const writeTribute = async (outpostPath, taskId, tribute) => {
+        await fs.writeFile(path.join(outpostPath, '.beads', 'tribute', `${taskId}.jsonl`), JSON.stringify(tribute) + '\n');
+    };
+    it('finds tasks blocked on the resolved task_id', async () => {
+        // alpha has task-A depending on task-X
+        await writeMail(alphaPath, 'task-A', makeMail('task-A', 'alpha', ['task-X']));
+        // beta has task-B depending on task-X
+        await writeMail(betaPath, 'task-B', makeMail('task-B', 'beta', ['task-X']));
+        const blocked = await getBlockedOutposts(tmpDir, 'task-X');
+        expect(blocked).toHaveLength(2);
+        expect(blocked.map(b => b.outpost).sort()).toEqual(['alpha', 'beta']);
+        expect(blocked.map(b => b.taskId).sort()).toEqual(['task-A', 'task-B']);
+    });
+    it('excludes tasks that already have a SUCCESS tribute', async () => {
+        await writeMail(alphaPath, 'task-A', makeMail('task-A', 'alpha', ['task-X']));
+        await writeTribute(alphaPath, 'task-A', makeTribute('task-A', 'alpha', 'SUCCESS'));
+        await writeMail(betaPath, 'task-B', makeMail('task-B', 'beta', ['task-X']));
+        const blocked = await getBlockedOutposts(tmpDir, 'task-X');
+        expect(blocked).toHaveLength(1);
+        expect(blocked[0].outpost).toBe('beta');
+        expect(blocked[0].taskId).toBe('task-B');
+    });
+    it('includes tasks with PARTIAL tribute (not yet succeeded)', async () => {
+        await writeMail(alphaPath, 'task-A', makeMail('task-A', 'alpha', ['task-X']));
+        await writeTribute(alphaPath, 'task-A', makeTribute('task-A', 'alpha', 'PARTIAL'));
+        const blocked = await getBlockedOutposts(tmpDir, 'task-X');
+        expect(blocked).toHaveLength(1);
+        expect(blocked[0].taskId).toBe('task-A');
+    });
+    it('returns empty when no tasks depend on the resolved task', async () => {
+        await writeMail(alphaPath, 'task-A', makeMail('task-A', 'alpha', ['task-Y']));
+        const blocked = await getBlockedOutposts(tmpDir, 'task-X');
+        expect(blocked).toHaveLength(0);
+    });
+    it('ignores non-TASK_ASSIGNMENT mail', async () => {
+        // Write an OPERATOR_NOTE mail (no dependencies field used for matching)
+        const note = {
+            bead_id: 'bead-note-1',
+            bead_type: 'MAIL',
+            schema_version: '9.0',
+            created_at: '2026-01-01T00:00:00Z',
+            task_id: 'task-A',
+            mail_type: 'OPERATOR_NOTE',
+            from: 'citadel',
+            to: 'alpha',
+            subject: 'Note',
+            read: false,
+            retry_of: null,
+            payload: { body: 'hello' },
+        };
+        await fs.writeFile(path.join(alphaPath, '.beads', 'mail', 'note-1.jsonl'), JSON.stringify(note) + '\n');
+        const blocked = await getBlockedOutposts(tmpDir, 'task-X');
+        expect(blocked).toHaveLength(0);
+    });
+    it('handles missing mail/tribute directories gracefully', async () => {
+        // Remove alpha's mail dir
+        await fs.rm(path.join(alphaPath, '.beads', 'mail'), { recursive: true });
+        await fs.rm(path.join(alphaPath, '.beads', 'tribute'), { recursive: true });
+        await writeMail(betaPath, 'task-B', makeMail('task-B', 'beta', ['task-X']));
+        const blocked = await getBlockedOutposts(tmpDir, 'task-X');
+        expect(blocked).toHaveLength(1);
+        expect(blocked[0].outpost).toBe('beta');
+    });
+});
+//# sourceMappingURL=blocked-outposts.test.js.map

package/dist/__tests__/blocked-outposts.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocked-outposts.test.js","sourceRoot":"","sources":["../../src/__tests__/blocked-outposts.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/bugfixes.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bugfixes.test.d.ts.map

package/dist/__tests__/bugfixes.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bugfixes.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/bugfixes.test.ts"],"names":[],"mappings":""}