the-citadel 0.12.7

package/.citadel/instructions/tag-planning.md

@@ -0,0 +1,14 @@
+# PLANNING BEAD INSTRUCTIONS
+
+You are working on a PLANNING task.
+
+## Acceptance Criteria Requirement
+When submitting your plan (via `submit_work`), you **MUST** include a `verification_plan` or `acceptance_criteria` section in your output.
+- This defines EXACTLY how the Gatekeeper will verify your work (e.g., "Run `npm test`", "Check file X exists").
+- **Failure to include this will result in immediate rejection** by the Gatekeeper.
+
+## Plan Structure
+Your plan should generally include:
+1.  **Problem Analysis**: What are we solving?
+2.  **Proposed Changes**: What files will change?
+3.  **Verification Plan**: How do we know it works? (CRITICAL)

package/README.md

@@ -0,0 +1,132 @@
+# The Citadel
+
+**Deterministic Agent Orchestration System** – a lightweight engine that turns chaotic agent swarms into an auditable, deterministic **Knowledge Factory**.
+
+---
+ 
+> [!IMPORTANT]
+> **🚀 NEW FOR 0.12: Context-Aware Reasoning & Tool Result Offloading**
+> The Citadel now automatically handles industrial-scale tool outputs by offloading large buffers to disk and providing sub-agent reasoning via the `inspect_result` tool. Prevents context bloat and scale your agents beyond the context window.
+ 
+---
+
+Use The Citadel for complex, multi-step objectives: **building software features**, **conducting deep research**, **synthesizing market reports**, or **managing content pipelines**. By decoupling the *process* (SOPs) from the *execution* (Agents), it ensures that even creative work follows a reliable, auditable path.
+
+---
+
+## Installation
+
+```bash
+npm install the-citadel@0.12.0
+```
+
+---
+
+## Features
+
+- **Foundry (Workflow Engine)** – Compile standard operating procedures (SOPs) into dynamic **Molecules** (task DAGs).
+- **Process Integrity** – The *state machine* guarantees `Open → In Progress → Verify → Done` transitions for every task.
+- **Dynamic Bonding** – Agents can spawn sub‑tasks in parallel to handle complex objectives (research, coding, analysis).
+- **Resilient Recovery** – Automated `on_failure` handling with conditional skips.
+- **Durable State** – All context is stored in Git‑backed SQLite **Pearls** (audit‑ready, restartable).
+- **Parallel Execution** – Configurable `max_workers` and `load_factor` for high-throughput concurrency.
+- **Provider‑agnostic** – Works with Ollama, OpenAI, Anthropic, and more.
+- **Context Aware** – Adheres to specific project rules and style guides (`AGENTS.md`) automatically. Supports [YAML Frontmatter](docs/agent/AGENTS.md.frontmatter.md) for strict `ignore`, `read_only`, and `forbidden` file constraints.
+- **Dynamic Data Piping** – Pass rich inputs (`context`) to tasks and pipe outputs between steps (`{{steps.foo.output.bar}}`).
+- **Context-Aware Reasoning** – Scale beyond the context window with **Tool Result Offloading** and sub-agent inspection (`inspect_result`).
+
+---
+
+## Quick Start
+
+```bash
+# 1️⃣ Install globally
+npm install -g the-citadel@0.12.0
+
+# 2️⃣ Bootstrap a new project
+citadel init   # creates .citadel/ + config + sample formula
+
+# 3️⃣ Run a workload
+# Option A: Simple Task
+citadel create "Hello world"
+
+# Option B: Run a Formula
+citadel create "My Release" --formula feature_release --vars name="Dark Mode"
+
+citadel start
+```
+
+⚙️ The **Conductor** will orchestrate agents automatically. Log output is written to `log.txt` courtesy of the shared `CitadelLogger`.
+
+---
+
+## Documentation
+
+For detailed usage instructions, including advanced configuration, formula creation, and troubleshooting, please refer to the **[User Guide](wiki/USER-GUIDE.md)**.
+
+---
+
+
+## Bridge TUI
+
+The **Bridge** is the lightweight terminal dashboard built with **Ink** that shows the orchestration in real time.
+
+```bash
+# Launch the Bridge (Conductor + UI)
+citadel bridge   # or
+bun run script:bridge
+```
+
+The dashboard remains open until you hit **Ctrl+C**.
+
+---
+
+## Project Structure
+
+```
+├─ src/                      # Source code
+│   ├─ bridge/               # Terminal UI (Ink)
+│   │  ├─ index.tsx          # Entry point
+│   │  └─ components/         # Dashboard panes
+│   ├─ core/                 # Core engine (queue, logger, pearls)
+│   ├─ config/               # Config handling
+│   ├─ services/              # Conductor & agent services
+│   └─ types/                # Shared TS types
+├─ docs/                     # Documentation (this file included)
+├─ tests/                     # Unit tests
+└─ README.md                  # This file
+```
+
+---
+
+## Extending & Customising
+
+- **New panels** – Add a component under `src/bridge/components` and import it into `Dashboard.tsx`.
+- **Event‑driven UI** – Replace polling in `AgentMatrix` / `MoleculeTree` with Conductor events.
+- **Custom loggers** – Hook into the global `CitadelLogger` to emit richer data.
+
+---
+
+## Build / Test / Lint
+
+```bash
+# TypeScript type-check
+bun run tsc --noEmit
+
+# Lint
+bunx biome lint .
+
+# Tests
+bun test tests/
+```
+
+---
+
+## Contribution
+
+1. `prl ready` → Find a work item.
+2. `prl update <id> --status in_progress` → Claim it.
+3. execute & verify → Pass all checks.
+4. `prl close <id>` → Ship it.
+
+Love to see you play around!

package/dist/agents/evaluator.d.ts

@@ -0,0 +1,8 @@
+import type { LanguageModel } from "ai";
+import { type AgentContext, CoreAgent } from "../core/agent";
+import type { PearlsClient } from "../core/pearls";
+export declare class EvaluatorAgent extends CoreAgent {
+    constructor(model?: LanguageModel, pearlsClient?: PearlsClient);
+    protected getDynamicTools(context?: AgentContext): Promise<Record<string, import("ai").Tool>>;
+    protected getSystemPrompt(defaultPrompt: string, context?: AgentContext): string;
+}

package/dist/agents/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./evaluator";
+export * from "./worker";

package/dist/agents/worker.d.ts

@@ -0,0 +1,10 @@
+import type { LanguageModel } from "ai";
+import { type AgentContext, CoreAgent } from "../core/agent";
+import { type AgentRole } from "../config/schema";
+import { type PearlsClient } from "../core/pearls";
+export declare class WorkerAgent extends CoreAgent {
+    constructor(role?: AgentRole, model?: LanguageModel, pearlsClient?: PearlsClient);
+    protected getDynamicTools(context?: AgentContext): Promise<Record<string, import("ai").Tool>>;
+    run(prompt: string, context?: Record<string, unknown>): Promise<string>;
+    protected getSystemPrompt(defaultPrompt: string): string;
+}

package/dist/bridge/components/Dashboard.d.ts

@@ -0,0 +1 @@
+export declare const Dashboard: () => import("react/jsx-runtime").JSX.Element;

package/dist/bridge/components/MoleculeTree.d.ts

@@ -0,0 +1 @@
+export declare const MoleculeTree: () => import("react/jsx-runtime").JSX.Element;

package/dist/bridge/index.d.ts

@@ -0,0 +1 @@
+export declare function startBridge(): Promise<void>;

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env bun
+import { Command } from "commander";
+import { loadConfig } from "./config";
+import { getPearls } from "./core/pearls";
+import { getQueue } from "./core/queue";
+import { Conductor } from "./services/conductor";
+import { getWorkflowEngine } from "./services/workflow-engine";
+export { loadConfig, getPearls, getQueue, Conductor, getWorkflowEngine };
+export declare const program: Command;
+export declare function runCLI(): void;