AGENTS.md@.agents git:20261013.af8985dB

Immutable. This exact content never changes and is served at /api/v1/blob/fb89130ae39072f5.

# Project-Scoped Rules (Superagent Workspace)

## Response Formatting

- **No markdown decoration in AI responses**: Do NOT use `**bold**`, `##` headings, `*italic*`, `__underline__`, or any other markdown formatting syntax in AI-generated responses or tool output intended for the terminal. Plain prose and single-level bullet points (`-`) are allowed. This applies to all agents (Master, Superagent, Subagent) and all user-facing text.
- **Display File Changes**: In every superagent process, if there are file changes (created, modified, or deleted files), they MUST always be displayed at the end of the response.
- **Project Completion Conclusion**: Every time a project, feature, or multi-step task is completed, the final response MUST include a clear conclusion/summary outlining the outcome, key changes, verification results, and next steps before listing changed files.

## Mandatory Skills

- **Design Tasks**: When building, designing, or refactoring user interfaces, layouts, components, or web applications, you MUST treat the hallmark skill (.agents/skills/hallmark/SKILL.md) as a mandatory skill and read its instructions using the view_file tool before proceeding.
- **Debugging Tasks**: When investigating bugs, runtime errors, failures, or diagnosing issues, you MUST treat the non-linear-debugging skill (.agents/skills/non-linear-debugging/SKILL.md) as a mandatory skill and read its instructions using the view_file tool before proceeding.

# Project Specifications (agents.md) 

This file contains key information about the project for AI agents to study and align with when working on Superagent.

## Project Overview
- **Name**: Superagent
- **Description**: An interactive, terminal-based AI coding assistant featuring a cyberpunk style terminal UI, context token tracking, and a 3-tier multi-agent orchestration system (Master Agent → Superagent → Subagent).
- **Technology Stack**: Node.js, TypeScript, React, Ink (Terminal UI Components), Vercel AI SDK, Execa, Vitest
- **Desktop Client Integration (t-line)**: Superagent integrates with [t-line](file:///D:/backup%20from%20pc%20asus/Documents%20Development/t-line), which is the desktop version of the superagent CLI. This is supported via a client/server bridge mode (`superagent --server [port] --client-mode tline`).

## 3-Tier Multi-Agent Architecture

Superagent supports a full 3-tier agent hierarchy activated via `superagent --multi`:

```
Master Agent  (orchestrator)
  └── Superagent  (per-feature, isolated in git worktree)
        └── Subagent  (atomic ops, ephemeral)
```

### Tier Responsibilities
| Tier | Role | Toolset | Isolation |
|------|------|---------|-----------|
| **Master Agent** | Orchestration, planning, result merging | `invokeSuperagentTool`, `awaitSuperagentsTool`, `mergeSuperagentsTool`, `manageSuperagentsTool`, `manageSubagentsTool`, `gitWorktreeTool` | Main repo |
| **Superagent** | Feature-level development | Shell + File tools + `invokeSubagentTool`, `manageSubagentsTool`, `gitWorktreeTool` | Isolated git worktree (`~/.superagent-r/worktrees/<name>`) |
| **Subagent** | Ephemeral subagent types (e.g. `researcher`, `coder`, `reviewer`, `software-tester`, `chrome-agent`). Note that Chrome/browser control is isolated to `chrome-agent`. | Tools allowed per subagent type | Ephemeral, within parent worktree |

### Key Files
- `src/core/masterAgent.ts` — Master Agent entry point and orchestrator logic
- `src/core/tools/types.ts` — Shared types: `AgentTier`, `SubagentInstance`, `ToolSet`
- `src/core/tools/toolsets.ts` — ToolSet definitions keyed per tier (`masterToolset`, `superagentToolsets`, `subagentToolsets`)
- `src/core/tools/prompts.ts` — System prompts per tier with dynamic context injection
- `src/core/tools/state.ts` — Shared subagent registry, instances map, event emitters
- `src/core/tools/superagentTools.ts` — Master tier tools: invoke/list/merge/manage Superagents
- `src/core/tools/subagentTools.ts` — Superagent tier tools: spawn ephemeral Subagents
- `src/core/context/ContextManager.ts` — Central orchestrator for context window management (state machine, strategy selection, recovery)
- `src/core/context/TokenTracker.ts` — Model-specific token counting via tiktoken (includes tool calls/results)
- `src/core/context/CompactionStrategy.ts` — Pluggable strategy interface for compaction algorithms
- `src/core/context/strategies/SummarizationStrategy.ts` — LLM-based summarization (with heuristic fallback)
- `src/core/context/strategies/PruningStrategy.ts` — Emergency pruning with summary preservation (never silent context loss)
- `src/core/context/strategies/PinningStrategy.ts` — Preserve critical pinned messages during compaction
- `src/core/context/SemanticAnalyzer.ts` — Topic boundary detection, importance scoring, key point extraction
- `chrome-extension-remote/` — Standalone lightweight Chrome Extension (Manifest V3) for remote-controlling any Chrome profile/browser from Superagent CLI via serverless WebSocket bridge (port 9223). No sidepanel GUI; minimal footprint, multi-profile capable.
- `chrome-extension/` — Full Superagent AI assistant Chrome Extension (Manifest V3) with sidepanel GUI for browser control, tab/DOM management, text/markdown extraction, console/network logs, storage/cookies management, device emulation, and more. Installed directly in target browser it controls (`clientMode = "chrome-extension"`). Must NOT be confused with `chrome-extension-remote/` or port 9223.
- `src/core/tools/remoteChromeBridge.ts` — Serverless WebSocket server (port 9223) auto-initialized on-demand by Superagent CLI; communication backbone for `chrome-extension-remote/`.
- `src/core/gateway/` — Omnichannel Messaging Gateway supporting Telegram, Discord, Slack, and Webhooks with session routing and outbound chunking.
- `src/core/daemon/` — Autonomous Headless Daemon & Cron Scheduler (`daemonScheduler.ts`, `cronParser.ts`, `daemonCli.ts`) with 5-field cron parsing.
- `src/core/skills/` — Autonomous Skill Synthesizer (`synthesizer.ts`, `skillValidator.ts`, `trajectoryExtractor.ts`) and `synthesizeSkillTool.ts`.
- `src/core/config/systemCache.ts` — Persistent 24-hour system check cache (`~/.superagent-r/system-cache.json`) for binary resolution.
- `src/components/startup-checker.tsx` — Parallelized dependency validator with decoupled background model warming.
- `src/components/startup-prompt.tsx` — First-run interactive choice dialog when no AI provider is configured.

## Recent Features (v1.5.146-v1.13.53)

- **Chrome Screen Sharing & Display Media Capture Automation** (`src/core/tools/chromeCdpMedia.ts`, `src/core/tools/chromeCdpTools.ts`, `scripts/chrome-debug.bat`, v1.13.53):
  - Added `mock_display_media` (aliases `mock_screen_share`, `bypass_screen_share`) to `control_chrome_cdp` to intercept `navigator.mediaDevices.getDisplayMedia` and return a synthetic stream without triggering native browser dialogs.
  - Added `handle_screen_share` (aliases `accept_screen_share`, `dismiss_screen_share`) to `control_chrome_cdp` to automate OS-level tab selection and confirmation on active Windows `DesktopMediaPicker` dialogs.
  - Added `--auto-select-desktop-capture-source="Entire screen"`, `--use-fake-ui-for-media-stream`, and `--enable-usermedia-screen-capturing` flags to `scripts/chrome-debug.bat` and `chromeCommon.ts`.
  - Added `displayCapture` to `Browser.grantPermissions` in `executeInspectMediaDevices`.
- **CDP Responsive Device Emulation & Kinematic Drag-and-Drop** (`src/core/tools/chromeCdpTools.ts`, v1.13.43):
  - Added `emulate_device` command to `control_chrome_cdp` supporting built-in presets (`mobile` / iPhone 14, `tablet` / iPad, `desktop` / 1920x1080, and `reset`) with metrics override, touch emulation, and optional user-agent overrides.
  - Added realistic `drag_and_drop` (alias `drag`) with Bezier trajectory interpolation, customizable duration and steps, and automated DOM drag/drop events.
  - Added explicit schema parameters (`preset`, `device`, `orientation`, `width`, `height`, `scale`, `touch`, `userAgent`) to `control_chrome_cdp` for full model visibility and `describe_tool` introspection.
- **Interactive Tool Discovery & Inspection** (`src/core/commands/coreCommands.ts`, `src/core/tools/toolDiscoveryTools.ts`, `src/core/tools/index.ts`, v1.13.43):
  - Added `/tools` slash command supporting interactive tool listing (`/tools [list]`), tool schema inspection (`/tools describe <name>`), and fuzzy tool search (`/tools search <query>`).
  - Added resilient tool aliases: `get_tools`, `describe_tools`, `get_tool`, `cdp`, `emulate_device`, `drag_and_drop` to prevent invocation errors when models use alternate phrasing.
  - Updated `/help` listing and system prompts across all tiers and configurations to enforce `TOOL_FIRST` discipline and responsive browser testing workflows.
- **Set-of-Mark (SoM) Vision & Layout Audit Engine** (`src/core/tools/chromeVisionTools.ts`, `scripts/vision_server.py`, v1.13.30+):
  - Unified vision stack exclusively on `racineai/UI-DETR-1` (~535MB RF-DETR Medium); completely eliminated legacy Microsoft OmniParser.
  - Implemented Set-of-Mark (SoM) perception (`perceive_page`): draws prominent numeric badge labels (`[1]`, `[2]`, `[3]...`) and color-coded bounding boxes on screenshots.
  - Added direct coordinate interaction (`click_id`, `type_id`) via native CDP input dispatch to element centers, bypassing brittle CSS selectors, shadow-DOM, and canvas barriers.
  - Added visual layout auditor (`audit_layout`): detects element collisions (>40%), touch-target defects (<24px), off-screen elements, and unlabeled interactive controls.
  - Added visual state verification (`verify_visual_state`): computes before/after screenshot pixel diffs via `/diff`.
  - Added interactive canvas and category filtering in Chrome Extension sidepanel (`chrome-extension/sidepanel-vision.js`).
- **Chrome process tools** (`src/core/tools/chromeProcessTools.ts`, v1.5.146): `list_running_chrome` (EnumWindows multi-window enumeration, profile display names from Local State, per-window tab lists via UI Automation) and `close_chrome_profile` (kills only the exact `--profile-directory` match). See README.
- **Tunnel chat + ESC menu** (v1.5.147): `ESC` at the main input while a tunnel is active opens a menu (stop tunnel / message Muse / continue); `/muse tunnel msg <text>` sends a `chat` envelope via the active WS socket. Muse side: `listener.py` writes to `bridges/<name>/chat_inbox/` and the `ws-chat-inbox` hook wakes an agent to reply.
- **MCP via tunnel** (`src/core/mcp/mcpHttpTransport.ts`, v1.6.0): `/muse tunnel start --mcp` serves MCP over Streamable HTTP on 127.0.0.1:9227 through the tunnel (MCP only, no WSS). Separate Bearer token (printed once, transient), 16-tool safe allowlist by default (`--allow-dangerous` opts into 21 destructive tools), JSONL audit log.
- **Bridge kit** (`bridge/`): sanitized publishable copy of the Muse-side WS bridge (`listener.py`, `bridge.sh`, `hooks/`, `bridges.json.example`, `SETUP.md`). Keep in sync with the live instance (`~/workspace/ws-bridge/` on the Muse machine) — never copy it raw, it contains real URLs/tokens.

## Coding Guidelines & Constraints
- **Language — English Only**: All user-facing text strings, UI labels, log messages, comments, variable names, documentation, and any other text content MUST be written in English. No exceptions.
- **Shell Commands**: On Windows, the actual shell is auto-detected (Git Bash is preferred over PowerShell). If using PowerShell, use `;` to separate commands instead of `&&`. Git Bash supports `&&` normally. The system prompt reports the detected shell accurately.
- **Strict Naming Rules**: Do NOT mention proprietary brand names like "Claude Code" or generic "CLI" terms in user-facing documentation or UI descriptions. Refer to the project as a terminal-based AI coding assistant.
- **Workspace Isolation & Database**: Session history, metadata, and cross-session search are indexed using SQLite (`~/.superagent-r/history.db` via `src/core/storage/historyDb.ts`). **SQLite is the single source of truth for chat transcripts** — messages are stored in the `messages` table with FTS5 full-text search. Artifacts (plans, tasks, walkthroughs) are stored in `~/.superagent-r/history/<mode>/<sessionId>/`. Superagent worktrees are stored under `~/.superagent-r/worktrees/<name>`. Configuration (`model-config.json`) and logs (`superagent.log`) remain in `~/.superagent-r/`.
  - **IMPORTANT**: The `.json` file at `~/.superagent-r/history/<mode>/<sessionId>/sess_*.json` is **NOT** a transcript storage file. It is a **0-byte placeholder** — its filePath is used only as a session key/identifier and for deriving plan/task/walkthrough file paths. **Do NOT read or write transcript data to/from the JSON file.** Always use SQLite (`loadSessionFromDb()` / `saveSessionToDb()` from `src/core/storage/historyDb.ts`) for chat transcript operations.
- **Model Config & Credentials — JSON ONLY, NO process.env**: All provider credentials, model configurations, active presets, tier models, profiles, and system settings are stored exclusively in `~/.superagent-r/model-config.json`. There is **NO** use of `process.env` for model, provider, or settings data anywhere in production code. This is a hard rule with NO exceptions:
  - **Reading models**: Use helper functions from `src/core/config/providers.ts`:
    - `getEffectiveMasterModel(mode)` — returns the primary model name for the given mode (`"multi"`, `"single"`, or `"auto"`)
    - `getTierModel(mode, tier)` — returns a specific tier's model (`tier`: `"master"`, `"superagent"`, `"subagent"`, `"researcher"`, `"coder"`, `"reviewer"`, or any custom subagent name)
    - `getAllTierModels(mode)` — returns a `Record<string, string>` of all tier models including subagent details
  - **Writing models**: Use helper functions from `src/core/config/providers.ts`:
    - `setTierModel(mode, tier, modelName, providerProfileId?)` — writes a specific tier's model to JSON and persists
    - `setAllTierModels(mode, modelName, providerProfileId?)` — writes ALL tiers at once to JSON and persists
    - `clearTierModel(mode, tier)` — clears a tier's model override
  - **Provider info**: Use `getActiveProviderName()` and `getConfiguredProviders()` — both read from JSON, never from env vars.
  - **System settings** (concurrency, rate limit, streaming, context window, max iterations): Use `getSettings()` to read and `updateSettings()` to write — both from `src/core/config/jsonConfig.ts`. These functions read/write directly to `model-config.json`. **NEVER use `process.env` to read or write settings.**
  - `/login` (add provider wizard): use `addProvider()` to save to JSON, then `switchActiveProvider()` to activate.
  - `/model` (model/preset wizard): use `savePreset()`, `applyModelPreset()`, `setTierModel()`, `setAllTierModels()` — all JSON.
  - `/settings` (settings commands): use `getSettings()` to display and `updateSettings()` to persist — all JSON.
  - **NEVER read or write `process.env.MODEL`, `process.env.MODEL_*`, `process.env.ACTIVE_PROVIDER`, `process.env.ANTHROPIC_API_KEY`, `process.env.CUSTOM_BASE_URL`, `process.env.OPENAI_API_KEY`, `process.env.SUPERAGENT_MAX_CONCURRENCY`, `process.env.SUPERAGENT_RATE_LIMIT_*`, `process.env.DISABLE_STREAMING`, `process.env.CONTEXT_WINDOW_LIMIT`, or `process.env.MAX_ITERATIONS`** — all of these have been fully migrated to JSON config helpers (`getSettings()`, `getTierModel()`, `getConfiguredProviders()`, etc.).
  - **`updateEnvFile()` has been removed** — it no longer exists. The file `src/core/config/env.ts` has been deleted. All config flows through `jsonConfig.ts` functions.
- **Interactive Prompts**: Ensure any executed shell command processes are monitored for interactive inputs (such as asking for yes/no confirmation) to alert the user rather than hanging in the background.
- **Test Location**: Always create and place all test files inside the `tests/` directory at the project root. Do not place test files under the `src/` directory.
- **Circular Dependency Prevention**: `toolsets.ts` and `prompts.ts` are imported by multiple tool files. Any tool file that needs to import from `toolsets.ts` or `prompts.ts` MUST use dynamic `import()` inside the `execute()` function body — never a top-level static import — to avoid circular module dependency errors.
- **Tier Enforcement**: Do NOT add orchestration tools (e.g., `invokeSubagentTool`) to Superagent or Subagent toolsets. Each tier must only have the tools listed in `toolsets.ts` for that tier.
- **Master Agent Planning**: The Master Agent is restricted from directly modifying codebase files and MUST delegate all feature implementation to Superagents. Therefore, the Master Agent's Implementation Plan and Task Tracking files MUST explicitly focus on spawning, monitoring, and merging Superagents (specifying their roles, git branches, and feature tasks) rather than detailing direct file edits as if it were performing them itself.
- **Commit, Versioning, and Changelog**: Every change, task, or completed feature must be staged and committed to the git repository. You must also bump the package version in `package.json` and document the changes in `CHANGELOG.md`.
- **Code Limits & Architecture**: Keep all code files strictly under 1000 lines to ensure readability. Always design with a single source of truth, focus on modularity, maintainability, scalability, optimization, and strictly adhere to industry best practices.
- **Best Practices, Maintainability, Scalability, and Modularity**: Follow industry best practices. Design codebase changes to be maintainable, scalable, and modular. Maintain separation of concerns, maximize code reuse, eliminate duplication, and document code effectively.
- **Exploration & Research**: When performing codebase exploration, investigation, or research, always spawn a subagent to handle the task.
- **Mandatory Skill Reading**: At the very start of the workflow to solve any user request (such as debugging, testing, QA, refactoring, new feature development, or any other task supported by our comprehensive skills), you MUST identify all relevant skills and read their `SKILL.md` instructions using the `view_file` tool before making plans or taking action.
- **Terminal Preset Names**: When creating or setting up terminal presets (e.g. via `/terminal init` or by writing to `terminal-presets.json`), preset names (keys in the JSON configuration) MUST be short, simple, lowercase, alphanumeric characters, and may use hyphens or underscores (e.g., `'dev'`, `'build'`, `'start'`, `'test'`). Emojis are strictly prohibited in preset names to ensure they are easy for users to type in the terminal when running `/terminal <preset_name>` or `/terminal preset <preset_name>`.
- **Chrome Extension Styling (chrome-extension/)**: The sidepanel GUI in `chrome-extension/` MUST adhere strictly to a clean, premium Material-inspired Design style (similar to modern cloud consoles) with light and dark theme options. This includes using modern styling: light theme with clean cool white/grey backgrounds (#ffffff, #f0f4f9, #f8f9fa), dark theme with dark grey/charcoal backgrounds (#1e1f20, #0f0f0f, #2d2f31), clean Material blue buttons/accents (#1a73e8 or #0b57d0 in light mode, #8ab4f8 or #a8c7fa in dark mode), Outfit or Product Sans/Roboto typography for UI elements (fallback to Inter/Segoe UI), and JetBrains Mono/Roboto Mono for terminal or code outputs. Interactive elements must use soft box-shadows, modern flat styles, and generous rounded corners (typically 8px to 16px, or rounded pills for buttons) to achieve a modern, premium look.
- **Startup Optimization & Fast-Path**: Startup time must remain sub-second. Binary checks must be cached using `systemCache.ts` (`getSystemCheckCache()` / `updateSystemCheckCache()`). Heavy native imports (e.g. `r-memory`, ONNX runtime, transformers) MUST NOT be loaded on the critical startup path; use lightweight disk package resolution (`createRequire`) and warm up ML models asynchronously in the background. Interactive startup progress UI is bypassed for one-shot prompts or when `--quick` / `-q` is provided.
- **Project Completion Conclusion**: System prompts across all tiers and configurations MUST mandate a structured completion conclusion whenever completing a project, feature, or multi-step task. The conclusion must summarize final outcomes, key implementation highlights, verification status, and next steps before listing changed files.

## System Prompt Guidelines (Concept A, B, and C)
All system prompts in the codebase (e.g., in [prompts.ts](file:///d:/backup%20from%20pc%20asus/Documents%20Development/superagent/src/core/prompts.ts)) must be designed and optimized using the following guidelines:
- **Concept A: Telegraphic English (Minified Prose)**
  - Remove conversational filler, pronouns, polite phrasing, and redundant verbs.
  - Use brief, direct imperative statements.
- **Concept B: Markdown Structure**
  - Organize rules, context, workflows, and rules under clear Markdown headers (e.g., `# ROLE`, `# CRITICAL RULES`, `# WORKFLOW`).
  - Use bullet points and lists to establish a clean hierarchy.
- **Concept C: Pseudocode & Logic Gates**
  - Structure conditional flows, decision gates, or self-verification routines using programming-like logic statements (e.g., `if decision_point: CALL ask_question()`).
  - Avoid verbose natural language paragraphs for branching paths.

## Operational Notes

- **Restart `/muse watch` after code changes**: the watch-mode process keeps old modules loaded; code delivered via the bridge only takes effect after the user Ctrl+C's and re-runs `/muse watch`. Never claim a feature is live before this restart plus a live probe.
- **`get_active_browser_tabs` can hang**: if the Chrome extension bridge is not connected, the tool has no effective timeout and blocks the entire sequential batch queue (observed 5+ min). Always check `chrome_extension_status` first; never send other batches until it returns.
- **MUSEBUS chunking**: wire format of the Telegram bridge. The WS transport gained reassembly in v1.5.148, but for WS just send plain JSON (16 MB limit — chunking not needed).
- **Network-exposed mode security checklist** (MCP via tunnel, and any future mode): (1) separate credential per mode (crypto-random, transient, never reused); (2) allowlist default-deny — destructive tools opt-in only; (3) audit-log every call; (4) bind 127.0.0.1, only the tunnel faces the network; (5) treat tunnel URLs as public — security from the token, not obscurity.

## Verification Checklist
- Run `bun test` to verify that all unit tests pass before committing.
- Build the project using `bun run build` to verify there are no TypeScript compilation errors.
- **Build After Changes**: Always run `bun run build` immediately after making any changes to the source files to ensure the compiled outputs in `dist/` are up to date and there are no compilation errors.
- After adding new tools, verify they are added to the correct tier toolset in `toolsets.ts` and not to other tiers.
- After modifying `subagentTools.ts` or `superagentTools.ts`, check for circular dependency issues — imports of `toolsets.ts`/`prompts.ts` must be dynamic.

- **Chrome debug launcher** (`scripts/chrome-debug.bat`): Windows launcher that opens Chrome with `--remote-debugging-port=9222` for extension-free CDP automation via `control_chrome_cdp`. Warns (does not kill) if Chrome is already running. **Chrome singleton limitation**: the flag is silently ignored when any Chrome window is already running from the same user-data-dir — the browser must be fully closed first. Debug port is 127.0.0.1-only.
- **UI-DETR-1 Vision Service & Set-of-Mark (SoM) Engine** (`scripts/vision_server.py`): Local AI (RF-DETR Medium ~535MB) for vision-based UI automation via `control_chrome_vision` (port 8095) and Chrome Extension Vision panel (`/api/browser/detect-ui`). **Auto-started by the tool on demand** — spawns `python scripts/vision_server.py 8095` as a background process and polls `/health`. Fast single-pass detection for button, field, link, text, heading, etc. Service binds 127.0.0.1 only. Model weights cached automatically via HuggingFace Hub (`~/.cache/huggingface/hub/models--racineai--UI-DETR-1`). Powers Set-of-Mark perception (`perceive_page`), direct coordinate interaction (`click_id`, `type_id`), automated layout auditing (`audit_layout`), and before/after visual diff validation (`verify_visual_state`). Legacy OmniParser has been completely removed in favor of this single lightweight model.