sengac/fspec

This system is an AI agent orchestration platform, primarily implemented in Rust, that manages interactive coding sessions through a command-line interface and a terminal-based UI. It features a modular architecture with a dedicated agent loop capable of recursive deep search, streaming loop detection, and automatic context compaction to handle long-running conversations. The platform extends its reach via a bridge server that connects sessions to external clients like Telegram and WebSocket relays, while also providing a local server for viewing markdown attachments and diagrams.

8 changes.

The project initiated a migration to a Rust-based architecture by establishing a new workspace, adding comprehensive build and cross-compilation scripts, and removing legacy TypeScript CLI components. Concurrently, the team expanded test coverage for new Rust commands and documented architectural designs for future agent orchestration features.

9 changes.

This period focused on migrating core functionality from TypeScript to Rust, including the extraction of the agent loop, session management, and CLI commands into dedicated crates. Significant enhancements were made to agent capabilities, introducing context compaction, auto-continue logic, and recursive deep search features. The work also expanded external connectivity through a new bridge server and improved the attachment viewer with a Rust-based implementation.

The background-session agent loop has been extracted from the NAPI adapter into a new \rust/agent-loop\ crate, establishing a NAPI-free core for session management. This change introduces a streaming loop detector that monitors LLM output for degenerate patterns and can automatically abort and retry in-flight streams based on per-profile settings. It also enables recursive DeepSearch sub-agents, allowing the agent to spawn ephemeral child sessions that can themselves perform deep searches up to a configurable depth. The extraction includes dedicated handlers for AgentManager and DeepSearch operations, bridge wiring to capture provider and model context, and configuration for provider-specific request parameters (e.g., streaming requirements for Codex/ZAI).

rust · high confidence

The interactive CLI now features a comprehensive context compaction system that automatically summarizes conversation history to prevent context-window overflow. This includes a DAG-based compaction structure with fresh and incremental strategies, configurable per-model thresholds (e.g., 80% for Gemini/OpenAI), and an escalation sub-agent that runs in a fresh session to recover from overflow errors. Additionally, an auto-continue engine has been introduced, allowing the CLI to automatically nudge the model to continue working if it stops without calling 'done()', with configurable budgets and goal-mode escalation for stalled tasks. Error handling has also been improved with better classification for context overflows, image content errors, and truncated tool calls, along with user-friendly error formatting.

rust/cli/src/interactive · high confidence

Users can now connect fspec AI sessions to external clients via the new bridge server. This includes a Telegram endpoint that allows remote monitoring and interaction through a bot (supporting slash commands like /stop and /clear, pause state management, and content-aware chunking for streaming messages) and a platform-agnostic Relay endpoint that connects to a standalone WebSocket relay server for mobile or custom client integration.

bridge · high confidence

A new local HTTP server (attachment-viewer) has been added to serve markdown attachments and other files, replacing the previous TypeScript implementation. It renders markdown to HTML with GFM extensions (tables, strikethrough, task lists), supports mermaid diagrams with a fullscreen zoom/pan modal, and provides a dark/light theme toggle with font-size controls. The server enforces directory-traversal guards to confine file access to a specified base directory, handles path validation, and serves raw files with appropriate content types. It exposes /health and /view/{\*path} endpoints, uses axum for routing, and includes client-side scripts for syntax highlighting (Prism) and diagram interaction (Panzoom).

(repo-wide) · high confidence

The \examples/hooks/\ directory now provides ready-to-use scripts and configuration for all six agent lifecycle events (session start/end, user prompt submission, pre/post tool use, and notifications). These examples demonstrate how to enforce security policies (blocking destructive commands or prompt injection), integrate linting results as context, send Slack notifications, and validate feature files, helping users quickly adopt hook-based automation and safety controls.

examples · high confidence

The repository now includes a comprehensive set of scripts to build, install, and cross-compile the fspec binary. Users can build from source using \build-install.sh\ (macOS/Linux) or \build-install.ps1\ (Windows), which handle prerequisites, build the Rust binary, and install it to a specified directory. For prebuilt binaries, \install.sh\ and \install.ps1\ download the latest release from GitHub, verify checksums, and install the binary. Cross-compilation is supported via \build-cross.sh\, which uses \cargo-xwin\ for Windows and \cargo-zigbuild\ for Linux/macOS, including a helper proxy script (\ipv4-proxy.py\) to resolve IPv6 connectivity issues during Windows builds. Native builds are handled by \build.sh\ and \build.ps1\, which also support packaging the binary into distribution archives. The legacy \install-local.sh\ script has been removed.

scripts · high confidence

A new context compaction module has been added to rust/core, introducing a Layer 0 structurally lossless trimmer, per-turn structural annotation detection (identifying Fspec milestones, error resolutions, and file modifications), and a parser for structured DAG node formats. The module also includes a cache-aware TokenTracker that preserves session-cumulative reasoning tokens across compaction cycles, along with comprehensive property-based and unit tests validating these components.

rust/core · high confidence

The \fspec-core\ library now includes Rust implementations for a batch of fspec CLI commands (including \add-aggregate\, \add-aggregate-to-foundation\, \add-architecture\, \add-architecture-note\, \add-assumption\, \add-attachment\, and \add-background\), replacing the previous TypeScript-only execution path. A canonical command registry has been added to track these 162 commands and their corresponding work-unit IDs. These new Rust modules provide the core logic for managing work units, appending Event Storm items, and mutating Gherkin feature files, ensuring behavioral parity with the existing TypeScript sources while introducing atomic file writes and stricter validation for operations like attachment handling.

rust/fspec-core · high confidence

The legacy TypeScript-based CLI entry point (src/index.ts) and its associated file helper utilities (src/utils/file-helpers.ts) have been removed. This deletes the original Commander.js-based command structure for features like validate, create-feature, list-features, and format, along with the toKebabCase utility, indicating a shift away from this specific implementation layer.

src · high confidence

The CLI no longer includes the \create-feature\, \format\, \list-features\, and \validate\ commands. These commands previously allowed users to generate new feature files, format Gherkin syntax using Prettier, list existing features with tag filtering, and validate Gherkin syntax with detailed error reporting. Their removal indicates a shift away from these specific file-management capabilities within this command set.

src/commands · high confidence

The \rust/fspec-tui\ application's core logic has been reorganized into a set of specialized modules to improve maintainability and enforce a single-mutation architecture. The main \App::dispatch\ orchestrator is now supported by dedicated handlers for specific features: \bootstrap.rs\ manages startup initialization (including lazy session creation, model resolution, and mux config loading); \dispatch.rs\ serves as the central action router; and feature-specific behaviors are isolated in \dispatch\_agent\_exit.rs\ (session close/detach), \dispatch\_attach.rs\ (session resumption and durable restore), \dispatch\_blocklist.rs\ (blocklist view management), \dispatch\_board\_keybinding.rs\ (board help dialogs), \dispatch\_capability.rs\ (fallback routing and post-dispatch housekeeping), \dispatch\_changed\_files.rs\ (changed files and diff loading), and \continue\_parser.rs\ (parsing and applying the \/continue\ slash command). This structure ensures that all state mutations flow through a single path while keeping complex feature logic contained in its own file.

rust/fspec-tui · high confidence

The session management logic has been moved from the NAPI bindings into a dedicated Rust crate (\rust/sessions\), introducing a new \BackgroundSession\ that runs the agent loop in a Tokio task and a \ChainOfCommand\ module that now supports one supervisor managing multiple subordinates (previously limited to a single subordinate). The module also ports the cloud model catalog population to Rust, ensuring the Rust TUI model selector displays tool-capable models from the \models.dev\ catalog instead of empty rows, and adds a Codex model allowlist that filters and re-parents OpenAI models under a synthetic "Codex (ChatGPT)" section when Codex credentials are present. Credential resolution has been lifted to this crate with a priority chain (credentials file, environment variables, project \.env\, and Claude OAuth tokens) and an in-memory store with mtime-based change detection to keep active sessions updated without a restart.

rust/sessions · high confidence

Added AST research and design specifications for agent orchestration and session management; Added feature specifications and test coverage for prioritize-work-unit, ACDD workflow, TUI session chips, and Rust CLI ports; Added test coverage for Telegram bridge and relay server components; Removed obsolete fspec command tests.

This change adds the initial dependency manifests for the new Rust workspace (rust/Cargo.toml, rust/Cargo.lock, and per-crate Cargo.toml files) and the bridge server (bridge/package.json). The Rust workspace establishes the core architecture with crates for the agent loop, CLI, TUI, git operations, graph database, and providers, pinning key libraries such as ratatui 0.29, axum 0.8, and rig-core 0.28.0. The bridge server manifest defines the WebSocket relay hub and Telegram endpoint bridges, depending on node-telegram-bot-api 0.66.0 and ws 8.18.0.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 54.

• Code Health 52
• Architecture 96
• Maturity 84
• Readiness 43
• Security 57
• Event Sourcing 100
• Performance 89

• 300 commits — 204 feature/other, 96 fixes

• codelet/fspec-tui — 49 commits
• spec/features — 41 commits
• codelet/napi — 28 commits
• spec/attachments — 25 commits
• (root) — 22 commits
• codelet/tools — 21 commits
• .github/workflows — 15 commits
• codelet/fspec-core — 15 commits
• rust/fspec-tui — 15 commits
• src/tui — 15 commits
• codelet/providers — 9 commits
• codelet/cli — 7 commits
• codelet/fspec — 5 commits
• codelet/sessions — 4 commits
• src/utils — 3 commits
• codelet/graph — 2 commits
• codelet/patches — 2 commits
• rust/Cargo.lock — 2 commits
• rust/core — 2 commits
• rust/tools — 2 commits

• fix: fix(agent-manager): fix provider name mapping for spawn and improve handler
• fix: fix(build): bound rustc parallelism to prevent OOM in local builds
• fix: fix(cli): downgrade verbose debug logging from warn to debug level
• fix: fix(cli): improve list-feature-tags command parity
• fix: fix(cli): skip project agent instruction files during context gathering
• fix: fix(clippy): resolve all workspace clippy warnings
• fix: fix(codex): fix stdin handling for exec tool calls
• fix: fix(codex): wire view_image through OpenAI responses API and codex facade
• fix: fix(compaction): handle ESC interrupt during compaction with tests
• fix: fix(compaction): implement LCM algorithm with convergence watchdog and file ID propagation
• fix: fix(compaction): resolve issues found from formal verification
• fix: fix(deep-search): add fix for qwen model compatibility
• fix: fix(deep-search): add provider request configuration and codex streaming support
• fix: fix(deep-search): fix deepsearch streaming for GLM provider
• fix: fix(formatter): bound prose-only Background description to stop scenario duplication (BUG-157)
• fix: fix(formatter): bound step-less scenario description to stop scenario duplication (BUG-158)
• fix: fix(fspec): add argument validation and auto-generated command usage docs
• fix: fix(fspec): prevent output capture leaking into tool call results
• fix: fix(graph): fix code search with dead code detection and entity deduplication
• fix: fix(graph): improve AST dead code detection edge cases
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

sengac/fspec was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.