CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.9.0] - 2026-04-10

Added

• Tool Result Offloading: Automatically offload industrial-scale tool outputs (>50k chars) to disk.
• Sub-Agent Reasoning (inspect_result): Use non-autonomous reasoning agents to analyze offloaded data without bloating the main context window.
• Deep Dependency Injection: Fully refactored core orchestration (Conductor, InstructionService, MCPResourceProvider) to use constructor injection, eliminating race conditions in parallel environments.

Fixed

• Parallel Test Stability: Resolved deep-seated race conditions in global singleton management.
• Schema Compliance: Updated core agents and test configs to match the latest configuration schema.

[0.5.0] - 2026-02-07

Added

• Migration to Pearls: Successfully migrated the iteration engine from pearls (bd) to pearls (prl).
  • Improved data stability with JSONL-only storage (issues.jsonl).
  • Simplified CLI interaction by removing daemon dependency and complex sync logic.
  • Adopted P0-P4 priority system and native Pearls status flow.
  • Native support for Pearls comments and link-based dependencies.
• Improved Performance: Reduced latency in task transitions by moving to direct file-based state management.

[0.4.5] - 2026-02-06

Added

• Automatic MCP Resource Injection:
  • Implemented MCPResourceProvider to automatically inject contextual data from MCP servers into agent prompts.
  • Added support for resource declaration in citadel.config.ts, workflow formulas (.toml), and dynamic pearl context.
  • Extended MCPService with full resource reading capabilities including binary content filtering.
  • Integrated resource injection into the InstructionService pipeline.

Fixed

• Test Suite Stability: Resolved test regressions and flakiness caused by global state leakage in CoreAgent.
• CoreAgent Refactor: Implemented Dependency Injection for PearlsClient in CoreAgent to isolate tests from the global singleton.
• E2E Testing: Fixed bd doctor mock in E2E tests to bypass git working tree checks.
• Conductor Tests: Added missing mocks (getLatestTicket) to fix TypeErrors in Conductor integration tests.

[0.4.3] - 2026-02-06

Fixed

• Critical Crash Fix: Enforced --no-db mode for all bd logic to prevent "Split Stack Overflow" crashes in the underlying Go SQLite driver. This eliminates potential database corruption during high-load state transitions.
• Robustness: bd interactions now rely exclusively on issues.jsonl (JSONL-only mode), ensuring stability across all environments.

[0.4.2] - 2026-02-06

Added

• Token Usage Counting:
  • CoreAgent now tracks input, output, and total tokens across all LLM steps in a task execution.
  • Automatically posts a summary comment to the associated Pearl via the bd CLI upon task completion.

[0.4.1] - 2026-02-06

Added

• Context Management Strategy: Implemented configurable limits for agent history and message sizes to prevent context window overflow and reduce costs.
  • Added context configuration object to citadel.config.ts.
  • History Pruning: CoreAgent now automatically prunes message history exceeding maxHistoryMessages (default: 20/30) while intelligently preserving the system prompt and tool-call/result pairs.
  • Output Truncation: Large tool outputs are now truncated if they exceed maxToolResponseSize (default: 50k/100k chars), preventing agents from choking on massive file reads or command outputs.
  • Message Size Safety: Added safeguards against excessively large single messages.

[0.4.0] - 2026-02-06

Added

• Dynamic Tool Injection Architecture:
  • Refactored CoreAgent and role-specific agents to use factory-based tool creation with injected AgentContext.
  • Tools now implicitly handle mandatory parameters like pearlId and parentPearlId, significantly reducing LLM cognitive load and omission errors.
  • Implemented async dynamic tool loading to support formula-defined output schemas.
• Project Health Sweep:
  • Achieved a perfectly clean Biome lint report across the entire codebase.
  • Hardened type safety by eliminating any usage in WorkerPool and CoreAgent.
  • Standardized modern Node.js imports and role-specific tool consolidation.

Improved

• AI SDK v6 Alignment: Migrated all tool definitions and registration logic to the new inputSchema pattern required by AI SDK 6.0.
• Instruction Precision: Audited and updated all system prompts and instruction templates to remove stale requirements for agents to provide pearlId manually.

[0.3.2] - 2026-02-06

Added

• Stricter filesystem operations filtering

[0.3.1] - 2026-02-06

Added

• Retry on Crash: Added retry logic for `` tool to automatically retry the command if it crashes.

[0.1.35] - 2026-02-04

Improved

• Pearls and Git Integration:
  • Implemented auto-synchronization for the Pearls database to handle staleness after Git operations.
  • Added proactive sync in WorkerAgent and EvaluatorAgent after run_command executes git commands.
  • Added automated recovery in PearlsClient to catch staleness errors and performing auto-sync before retrying.

[0.1.21] - 2026-01-31

Fixed

• Conductor Hook Dependency Injection (Critical): Fixed a bug where WorkerPool and GatekeeperPool hooks were falling back to the global singleton WorkQueue instead of using the isolated queue instance passed to Conductor. This caused test failures (claim is not a function) and prevented proper multi-queue isolation.
• Robust Error Handling: Added null checks for pearl access in Conductor's error handling block to prevent secondary crashes during failure recovery.
• Output Capture: Ensuring Conductor hooks return the agent's execution result so it gets persisted to the queue ticket output, fixing data flow to Gatekeepers.

[0.1.22] - 2026-01-31

Fixed

• Submit Work Schema Regression: Fixed an issue where agents providing structured output without a top-level summary were failing validation. submit_work now robustly extracts summaries from output.summary, output.analysis, or generates a fallback summary from keys.

[0.1.23] - 2026-01-31

Fixed

• Output Persistence Bug: Fixed a critical "double-complete" race condition where agent tools (like submit_work) would save structured JSON, but the task runner would later overwrite it with a narration string. WorkQueue.complete() and fail() are now idempotent.

[0.1.24] - 2026-01-31

Changed

• Documentation Update: Fully synchronized docs/CITADEL-FSM.md with the latest FSM implementation, including new rejection transitions, recovery labels, and the v0.1.23 Persistence Guard details.

[0.1.20] - 2026-01-31

Fixed

• Persistence Overwrite Bug (Critical): Fixed a bug in WorkQueue.complete() where the standard Hook cleanup logic (which calls complete with no output) was unconditionally overwriting the existing output with null. Modified complete() to conditionally update the output field only if a non-null value is provided, ensuring that the WorkerAgent's submission is preserved.

[0.1.19] - 2026-01-31

Fixed

• Gatekeeper Null Context (Critical): Fixed a bug where the Gatekeeper received null as submitted_work because it was reading from the active verification ticket instead of the completed worker ticket. The Conductor now explicitly fetches the latest completed output from the Queue, ensuring proper context for verification.

[0.1.18] - 2026-01-31

Improved

• Submission Feedback: The submit_work tool now returns an explicit "message": "Work submitted successfully." in its JSON response. This provides clearer feedback to agents (especially after auto-extraction), preventing confusion and unnecessary retries.

[0.1.17] - 2026-01-31

Fixed

• Crash Loop Recovery: Enhanced submission idempotency to handle "Partial Failure" states. If a workspace Ticket is marked completed but the Pearl state update fails (leaving it in_progress), the Worker now automatically detects this inconsistency, forces the Pearl transition to verify, and returns success instead of crashing with "No active ticket".

[0.1.16] - 2026-01-31

Fixed

• Submission Idempotency: Fixed a regression in v0.1.15 where agents crashed with "No active ticket" when retrying submit_work after an auto-extracted submission. submit_work now idempotently returns success if the pearl is already in verify or done states.

[0.1.15] - 2026-01-31

Fixed

• Agent Summary Conflation: Relaxed submit_work schema to make summary optional and implemented smart extraction logic in WorkerAgent. This fixes a common issue where agents placed the summary inside the structured output object, causing validation failures.

[0.1.14] - 2026-01-31

Fixed

• Evaluator State & Validation Fixes:
  • Relaxed FSM to allow verify -> open transitions, enabling Gatekeepers to reject work back to the pool.
  • Updated validation logic to skip strict acceptance_test checks for tasks marked failed, enabling Gatekeepers to fail work (terminal failure).
  • Updated Evaluator system prompt to strictly enforce providing a reason when rejecting work.
  • Added new integration tests (tests/integration/evaluator_state.test.ts) covering these edge cases.

[0.1.13] - 2026-01-31

Fixed

• Fixed critical race condition in Conductor where dependent tasks were routed before their blockers were complete. Added "Double Check" validation logic to cycleRouter.
• Fixed test leakage in integration tests by replacing global mock.module with prototype patching in conductor_race.test.ts.

[0.1.12] - 2026-01-31

Fixed

• Summary Validation Fix: Addressed an issue where agents (especially in planning mode) misplaced the summary field inside the structured output object.
  • Made summary optional in submit_work schema to prevent immediate validation failure.
  • Added auto-extraction logic in WorkerAgent to recover the summary from output.summary if missing at the top level.
  • Improves robustness against common agent "envelope conflation" errors.

[0.1.11] - 2026-01-30

Fixed

• Persistent Schema Validation Fix: Fixed issue where dynamic schema validation in run() defaulted to z.string() when no formula was present, blocking structured output even with the v0.1.10 fix.
  • Updated default outputSchema in WorkerAgent.run() to z.record(z.string(), z.unknown()) to explicitly allow structured objects by default.
  • Ensures backward compatibility for agents not using formula-enforced schemas.

[0.1.10] - 2026-01-30

Fixed

• Planning Workflow Schema Fix: Fixed critical bug where submit_work tool rejected structured JSON output from planning steps
  • Updated initial schema to accept both strings and objects: z.union([z.string(), z.record(z.unknown())])
  • Planning workflows can now submit structured output with affected_files, analysis, and steps
  • Preserves backward compatibility with string outputs and dynamic schema enforcement

[0.1.9] - 2026-01-29

Fixed

• Critical Deadlock Fix: Resolved a system deadlock caused by agent parameter omission and premature state transitions:
  • handleSubmitWork now validates ticket existence and saves output before transitioning to verify status
  • reject_work now resets pearl to open (with rejected label) instead of in_progress, preventing orphaned pearls
  • Added stuck pearl recovery to Router: automatically resets in_progress pearls with no active ticket
  • Added REQUIRED hints to mandatory tool parameters to reduce LLM omission

Changed

• Updated docs/CITADEL-FSM.md to reflect new rejection behavior, stuck pearl recovery, and new labels

[0.1.8] - 2026-01-29

Fixed

• Gatekeeper Awareness: The EvaluatorAgent now receives the Worker's submitted output (submitted_work) in its context. Updated the Evaluator's system prompt to correctly handle planning tasks, reducing false rejections for non-filesystem work.

[0.1.7] - 2026-01-29

Fixed

• Tool Tolerance: Improved report_progress tool in WorkerAgent to be more tolerant of missing parameters. It now accepts reasoning as a fallback for message and supports extra parameters without failing validation.

[0.1.6] - 2026-01-29

Fixed

• Docker Compatibility: Added --sandbox flag to all pearls commands to enable direct mode operation without daemon dependency. Fixes Unix socket permission errors in Docker containers that prevented Citadel from running.

[0.1.5] - 2026-01-29

Fixed

• Router Queue Assignment: Removed default value from queue parameter in enqueue_task to prevent infinite loops where verify pearls were incorrectly routed to worker queue instead of gatekeeper queue.

Added

• Smart Tool Name Matching: Agents can now call tools by suffix (e.g., list_skills instead of mcp_list_skills). Auto-resolves if exactly one match is found and name is >= 5 characters.

[0.1.4] - 2026-01-29

Fixed

• Conductor Resilience: Implemented exponential backoff for the main router loop to prevent log flooding and CPU spikes during infrastructure outages (e.g., database synchronization errors).
• Environment Validation: Added a startup check (bd doctor) to ensure the Conductor only starts when the pearls database is in a healthy state.

[0.1.3] - 2026-01-29

Fixed

• Zombie Task Prevention: Added error handling and state recovery to worker and gatekeeper hooks. If an agent exits without calling a terminal tool (submit_work, approve_work, reject_work), the pearl is automatically returned to an actionable state with appropriate labels (agent-incomplete, agent-error, evaluator-incomplete, evaluator-error) for retry. This prevents tasks from getting permanently stuck in in_progress or verify states.

[0.1.2] - 2026-01-29

Fixed

• Dependency-Aware Task Routing: The Conductor now uses pearlsClient.ready() instead of list('open') to ensure only pearls with satisfied dependencies (all blockers closed) are routed to workers. This prevents wasting resources on tasks that cannot proceed due to missing dependencies.
• Recovery Logic: Re-added recovery pearl handling to correctly skip recovery tasks when their dependencies succeed.

[0.1.1] - 2026-01-29

Added

• Parameter Auto-Injection: Citadel now automatically injects mandatory parameters like pearlId and parentPearlId from the agent's context into tool calls if they are missing. This significantly improves reliability for weaker local models (e.g., 20B class models) that sometimes fail to extract context into tool arguments.

[0.1.0] - 2026-01-28

Fixed

• CRITICAL: Tool Execution Context Shadowing: Fixed a major bug where AgentContext (including pearlId) was being ignored during tool execution. This now correctly passes the agent's run-time context to all tools, enabling enqueue_task, submit_work, and report_progress to function correctly without explicit pearlId parameters.
• WorkerAgent Typo: Fixed a minor syntax typo in the run_command handler.

[0.0.9] - 2026-01-28

Improved

• Tool Parameter Tolerance: Made tools more forgiving of LLM variations:
  • run_command now accepts both command (string) and cmd (string or array), automatically converting arrays to space-separated strings
  • run_command uses .passthrough() to allow extra parameters like timeout that LLMs might add
  • enqueue_task now makes pearlId optional, falling back to context if not provided
  • Reduces wasted API calls from agents learning tool schemas through trial and error

[0.0.8] - 2026-01-28

Fixed

• Bug #1 - Invalid State Transition: Fixed the Conductor to properly move pearls to in_progress status when workers start processing tasks, not when they finish. This prevents the invalid open → verify transition that was occurring in submit_work.
• Bug #2 - Output Schema Mismatch: Updated submit_work to accept both string and object types for the output parameter, allowing agents to submit structured data naturally without manual stringification.
• Bug #3 - Tool Schema Ambiguity: Improved run_command tool description to explicitly clarify that command must be a single string, not an array, reducing agent confusion and wasted API calls.

[0.0.7] - 2026-01-28

Fixed

• JSON Schema Validation Error (Complete Fix): Fixed the root cause in jsonSchemaToZod function that was converting empty JSON Schema objects to z.record(), which generates invalid schemas. Now uses z.object({}).passthrough() for dynamic objects. This resolves production errors when using workflow formulas with output schemas.
• RouterAgent Schema: Also fixed instantiate_formula tool's variables parameter (from v0.0.6).

[0.0.6] - 2026-01-28

Fixed

• JSON Schema Validation Error: Fixed RouterAgent's instantiate_formula tool generating invalid JSON schemas. Replaced z.record() with z.object({}).passthrough() to properly support dynamic variable objects in workflow formulas.

[0.0.5] - 2026-01-28

Added

• 100% WorkerAgent Test Coverage: Achieved full line and function coverage for src/agents/worker.ts.
• Agent Dependency Injection: Refactored CoreAgent, WorkerAgent, and EvaluatorAgent to support LanguageModel injection, eliminating reliance on global mocks.

Changed

• Test Suite Modernization: Removed all cache-busting hacks (?t=...) and broad module mocks to unify coverage reporting and improve test reliability.
• Lint & Type Safety: Resolved all any warnings in agent constructors and optimized import styles (import type).

Fixed

• Coverage Shadowing: Fixed issues where global mocks were interfering with coverage tracking across different test files.
• LLM Mocking Stability: Implemented role-validated LLM mocks in integration tests to prevent unauthorized API calls during testing.

[0.0.4] - 2026-01-28

Added

• 100% Biome Lint Compliance: Achieved full compliance across src/ directory, resolving 18 warnings without ignore comments.
• Strict Tool Validation: CoreAgent now performs explicit Zod schema validation on all tool inputs.
• Improved Test Isolation: Switched to dynamic imports for WorkerAgent in integration tests to prevent singleton leakage.

Fixed

• enqueue_task Constraint Failure: Resolved NOT NULL constraint errors by providing default values in WorkQueue and marking RouterAgent parameters as optional.
• Build Compilation Errors: Fixed several TypeScript "possibly undefined" and type mismatch errors in core logic and tests.
• AI Mocking: Repaired incomplete ai module mocks in unit tests.

[0.0.3] - 2026-01-28

Added

• Dynamic Data Piping (DDP): Enabled structured data flow between workflow steps using {{steps.ID.output.KEY}} syntax.
• Dynamic Schema Enforcement: Worker Agents now rigidly enforce Formula-defined output_schema using Zod validation.
• Context Preservation: Pearls now support a structured context property persisted in description frontmatter.
• Data Piper Service: Just-in-time dependency resolution and context injection.

[0.0.2] - 2026-01-27

Fixed

• Configuration State Duplication: Resolved a critical bug where bundled CLI state was duplicated, causing "Config not loaded" errors. Corrected by implementing a global singleton registry using globalThis and Symbol.for.

[0.0.1] - 2026-01-24

Added

• Parallel Multi-Worker Support: Introduced WorkerPool for dynamic scaling.
• Workflow Engine: Implemented TOML-based "Formulas".
• Dynamic Task Decomposition: Enabled Worker Agents to delegate subtasks.
• NPM Package Readiness: Configured package metadata and CLI entry points.

Changed

• Documentation: Comprehensive update to USER-GUIDE.md and technical docs.