# What is this?

This document provides a detailed examination of Captain Claw's source code as of February 23rd, 2026 — generated using Captain Claw itself.

---

# User:
there are python (.py), html (.html) and javascript (.js) files in folder captain-claw-src (and its subfolders). go through all of them, write for each of them: description (10 sentences), purpose (10-20 sentences), key elements (methods, objects, calls), key logic (10-20 sentences). write that in one file, structure the file with file name as section title (relative path) and description, purpose, key elements and logic below. it has to be in markdown format


---

# Automatically rephrased task 

# Task
Analyze all Python (.py), HTML (.html) and JavaScript (.js) files in the folder captain-claw-src (including subfolders) and produce a single Markdown file with a structured section for each file containing a Description, Purpose, Key elements, and Key logic.

Instructions

Recursively locate every file with extension .py, .html, or .js inside the captain-claw-src folder and its subfolders.

For each file, create a section in the output Markdown file using the file's relative path (relative to captain-claw-src root or repository root — use the path you used to find the file) as the section title.

Under each file's section include these four subsections, in this exact order and with these exact headings:

1. Description — write exactly 10 sentences that describe what the file does.
2. Purpose — write between 10 and 20 sentences describing the file's role in the project and why it exists.
3. Key elements — provide a concise bullet list of the file's important methods, functions, classes, objects, and notable external calls or dependencies (each bullet names the element and a short parenthetical note if needed).
4. Key logic — write between 10 and 20 sentences explaining the main control flow, algorithms, and logic implemented in the file.
Use only information that can be determined from the file content and from other files in the repository if necessary to understand context. Do not invent external requirements.

Preserve the original relative path as the section title for each file.


Items to process

Folder: captain-claw-src (process all files within this folder and its subfolders)

File types: .py, .html, .js
Output

Produce a single Markdown file named captain-claw-src-analysis.md written to the repository root.

Structure the file as:

- For each file processed, a level-2 heading with the file's relative path (e.g., ## path/to/file.py).
- Under that heading include the four subsections (Description, Purpose, Key elements, Key logic) as plain text and bullet lists where indicated.
Ensure Markdown formatting is valid (headings, paragraphs, and bullet lists).

Do not create separate files per source file; all file analyses must be concatenated into the single Markdown file.


Constraints

Description must be exactly 10 sentences.

Purpose must be between 10 and 20 sentences (inclusive).

Key elements must be a bullet list naming methods, classes, objects, and notable calls/dependencies; keep each bullet concise.

Key logic must be between 10 and 20 sentences (inclusive).

Use the file's relative path as the section title.

If a requested field cannot be determined from the file or repository context, write Not determinable for that field (do not invent facts).

Process every .py, .html, and .js file found; do not skip files.

Output only the single Markdown file specified; do not produce additional files or auxiliary outputs.

---

# Captain Claw's Output

# Captain Claw Source Code Summary

This document contains autogenerated, human-readable summaries for every .py, .html, and .js file found under the captain-claw-src folder (and subfolders).

Format for each file:
- Relative path (section title)
- Description (10 sentences)
- Purpose (10-20 sentences)
- Key elements (methods, classes, objects, important calls)
- Key logic (10-20 sentences)

---

## captain-claw-src/captain_claw/logging.py

Description:
1. This module centralizes logging configuration for the Captain Claw application using structlog and Python's logging.
2. It provides a file-like sink wrapper to forward formatted log lines into a callback for an external system UI.
3. The module exposes functions to set a custom system log sink, configure structured logging, and obtain configured loggers.
4. It builds a pipeline of structlog processors to merge contextvars, add log levels, timestamp events, render stack info, and format exceptions.
5. Depending on configuration it chooses either a console renderer for human-friendly output or a JSON renderer for machine consumption.
6. A helper class _SinkWriter implements write/flush semantics to integrate structlog's PrintLoggerFactory with a callback sink.
7. The configure_logging function reads logging settings from the global configuration to determine logging level and format.
8. The module uses a module-level get_logger helper to simplify retrieving structlog bound loggers by name.
9. The log variable at module scope provides a ready-to-use logger instance for code that imports this module.
10. Overall, the module separates platform-specific log output handling from application code by providing pluggable sinks and standard configuration.

Purpose:
1. The primary purpose of this file is to provide a single place to define how structured logs are produced and delivered across Captain Claw components.
2. It aims to ensure consistent log formatting, context propagation, and error rendering across different runtime environments.
3. The module supports redirecting structured logs to both developer-friendly console output and machine-readable JSON for aggregation systems.
4. It enables integration with an external UI or system panel through a callback sink so logs can be displayed in an application console rather than only stderr.
5. By centralizing configuration, the module lets other components simply call get_logger and rely on configured processors and formatting.
6. The _SinkWriter class purposefully decouples structlog's interface from arbitrary sink implementations by providing a minimal file-like adapter.
7. configure_logging reads runtime configuration and applies it to structlog so operators can change log verbosity and format without code changes.
8. The module also enforces best practices such as attaching timestamps, log levels, and stack information to logs for improved observability.
9. Another important purpose is to make it easy to include structured context (via contextvars) in all log events which supports tracing across async tasks.
10. It serves as a small abstraction layer that ensures application code does not need to know about the logger factory, processors, or sinks—only how to get a logger.
11. Additionally, it provides a hook (set_system_log_sink) that higher-level UI or platform code can call to route logs into different renderers or live displays.
12. It thereby improves developer ergonomics and operational flexibility when running Captain Claw in different deployment contexts.

Key elements:
- _system_log_sink: module-level optional callback sink for routing log lines.
- class _SinkWriter: file-like adapter with write() and flush() used by structlog's PrintLoggerFactory.
- set_system_log_sink(sink): function to set the optional sink used by the sink writer.
- configure_logging(): main function that reads configuration and configures structlog processors, renderer and logger factory.
- get_logger(name=None): convenience function returning a structlog BoundLogger optionally named.
- log: module-level BoundLogger instance created with get_logger(__name__).
- structlog processors list: merge_contextvars, add_log_level, TimeStamper, StackInfoRenderer, format_exc_info, ConsoleRenderer/JSONRenderer.
- use of get_config() from captain_claw.config to obtain logging.level and logging.format.

Key logic:
1. The module begins by declaring a global _system_log_sink that may be set by other parts of the platform; this sink is used for forwarding lines.
2. _SinkWriter buffers text written to it and splits on newlines so that each complete log line is forwarded to the sink callback; partial lines are retained until completed.
3. The flush method ensures any buffered text is sent to the sink if the writer is flushed, preventing lost messages on shutdown or formatter flushes.
4. set_system_log_sink simply assigns the provided callable to the module-level variable, enabling runtime reconfiguration of the log destination.
5. configure_logging retrieves the configuration object, translates the configured level string to a logging.Level value, and constructs a list of structlog processors.
6. It conditionally appends either a human-friendly ConsoleRenderer or a JSONRenderer to the processor pipeline depending on configuration.
7. The structlog.configure call assembles processors, picks a wrapper class that filters by the configured level, sets a simple dict context class, and supplies a PrintLoggerFactory.
8. When creating the PrintLoggerFactory it passes either an instance of _SinkWriter wrapping the system sink or sys.stderr so logs flow to the chosen destination.
9. get_logger returns a structlog logger bound to an optional name, which allows other modules to call get_logger(__name__) and produce structured events consistently.
10. The combination of contextvars merging and processors ensures that contextual data (like request ids or trace ids) is included in every emitted event without manual passing.
11. By centralizing renderer selection and log level, the module allows runtime toggling between debug/production styles of logging without code modifications.
12. The module exposes a module-level log instance so typical modules can import log and use it immediately without explicitly obtaining a named logger.

---



---

## captain-claw-src/captain_claw/platform_lifecycle.py

Description:
1. This module provides helpers to initialize and tear down chat platform bridges for Telegram, Slack, and Discord.
2. It reads runtime configuration and uses it to enable or disable each platform and to obtain bot tokens and API base URLs.
3. For each enabled platform with a non-empty token it constructs a platform-specific Bridge object and a PlatformAdapter to load and save persisted state.
4. The initialization routine also cleans up expired pairings stored in platform state and starts background polling tasks for incoming updates.
5. Telegram initialization additionally registers bot commands and menu button commands before starting its long-poll loop.
6. Each platform's poll loop repeatedly requests updates from its bridge, updates stored offsets, and schedules asynchronous tasks to handle individual platform messages.
7. Polling loops catch and ignore cancellation to allow graceful shutdown and log other exceptions to the system UI, pausing briefly on errors.
8. The teardown function cancels any running poll tasks and attempts to close open bridge connections, suppressing exceptions during shutdown.
9. Throughout initialization and polling the module updates the UI with informational messages about enabled platforms, token problems, and registration results.
10. The module delegates actual message handling to a remote command handler and relies on external Bridge and PlatformAdapter implementations for platform-specific behavior.

Purpose:
1. The file centralizes lifecycle management for external chat platform integrations used by the application.
2. It exists to translate configuration state into running platform bridges, persistent adapter state, and background poll tasks.
3. By consolidating startup logic here, the rest of the codebase can assume a uniform platform state object and running poll loop for each enabled platform.
4. The module enforces a simple enablement check that considers both an explicit enabled flag and the presence of a bot token to avoid spurious starts.
5. It uses PlatformAdapter to load and save per-platform persistent state so that pairing information and offsets survive restarts.
6. Cleanup of expired pairings is performed during initialization to keep pairing lists current and to avoid leaking stale state.
7. Telegram receives extra setup by registering bot commands and menu buttons, reflecting platform-specific requirements placed in one location.
8. Background poll loops are started as asyncio tasks so updates are consumed concurrently and dispatched to the application's message handler.
9. The teardown routine provides a controlled shutdown path that cancels tasks and attempts to close network connections while tolerating errors.
10. The module reports status back to the user interface to make startup and error conditions visible to operators or users.
11. It intentionally delegates message processing to the remote_command_handler to keep platform polling separate from command execution logic.
12. Overall, this file exists to encapsulate the platform orchestration concerns—configuration interpretation, resource initialization, periodic polling, state persistence, error handling, and graceful shutdown—in a single well-defined place.

Key elements:
- init_platforms(ctx) (initializes Telegram, Slack, and Discord bridges and starts poll tasks)
- teardown_platforms(ctx) (cancels poll tasks and closes bridge connections)
- _register_telegram_commands(ctx) (registers Telegram bot commands and chat menu button commands)
- _telegram_poll_loop(ctx) (long-poll loop that fetches Telegram updates and dispatches them)
- _slack_poll_loop(ctx) (poll loop that fetches Slack updates and dispatches them)
- _discord_poll_loop(ctx) (poll loop that fetches Discord updates and dispatches them)
- get_config (external configuration provider used to read platform settings)
- PlatformAdapter (used to load and save per-platform persisted state)
- cleanup_expired_pairings (utility to remove stale pairing entries)
- TelegramBridge, SlackBridge, DiscordBridge (bridge classes instantiated for each platform)
- remote_command_handler.handle_platform_message (entry point for dispatched platform messages)
- ctx attributes used (ctx.telegram, ctx.slack, ctx.discord, ctx.ui, ctx.telegram_command_specs, ctx.platform_names)
- asyncio.create_task (used to run poll loops and to dispatch handlers concurrently)
- bridge.get_updates, bridge.set_my_commands, bridge.set_chat_menu_button_commands, bridge.close (bridge API surface used)

Key logic:
1. init_platforms begins by obtaining global configuration and then configures each platform by writing platform-specific config into the runtime context and computing an enabled flag from config.enabled or the presence of a bot token string.
2. For an enabled platform with a non-empty token the function constructs the appropriate Bridge (Telegram/Slack/Discord) passing token and API base URL, initializes offsets where applicable, and creates a PlatformAdapter for persistence.
3. The adapter's load_state method is awaited to restore persisted state, cleanup_expired_pairings is invoked to prune stale pairings, and the adapter's _save_state is awaited to persist any changes resulting from cleanup.
4. Telegram receives an extra registration step where the code calls set_my_commands and set_chat_menu_button_commands on the bridge and logs success or failure to the UI.
5. After initialization the module starts a background polling task for each platform via asyncio.create_task and appends a system message to the UI indicating the platform's polling status.
6. If a platform is marked enabled but its token string is empty, the code appends a UI message and deliberately skips constructing a bridge or starting polling for that platform.
7. teardown_platforms iterates over the available platform names, cancels any running poll_task, awaits the task while ignoring asyncio.CancelledError, and then attempts to close the bridge connection while suppressing exceptions to ensure a robust shutdown.
8. Each poll loop asserts the bridge exists and then enters an infinite loop that calls the bridge's get_updates API; Telegram uses an offset and timeout, while Slack and Discord receive updates plus next_offsets pairs.
9. Telegram's loop updates a numeric offset using update.update_id + 1 and preserves monotonic progression using max to combine offsets; Slack and Discord assign the returned next_offsets to the context offsets dictionary.
10. For each received update the loops schedule an asynchronous task to call the shared remote_command_handler.handle_platform_message with the platform name and update payload so message processing occurs concurrently and does not block polling.
11. Poll loops pause between iterations using either a configured poll timeout or a minimal sleep to control polling frequency and use brief sleeps after exceptions to avoid tight error loops.
12. All poll loops break cleanly on asyncio.CancelledError to support shutdown and log any other exceptions to the UI before sleeping and retrying.

---

## captain-claw-src/captain_claw/platform_adapter.py

Description:
1. This module provides a unified async wrapper around platform-specific chat bridges for Telegram, Slack, and Discord.  
2. It implements multiple small text and audio helper functions to sanitize, truncate, and analyze chat content.  
3. The module extracts and collects MP3 file paths produced by a pocket_tts tool from tool output and from session tool messages.  
4. It manages ephemeral pairing tokens and a pending/approved user mapping with expiration cleanup and token generation.  
5. The PlatformAdapter class encapsulates per-platform operations including sending messages, audio files, chat actions, and marking messages read.  
6. The adapter also records outgoing events as tool outputs into the agent session and persists platform-specific state via a session manager.  
7. A typing-heartbeat helper runs a periodic chat-action while awaiting long-running work to give users a typing indicator.  
8. The adapter can automatically request TTS via a pocket_tts tool when a remote user requests audio and then send generated audio files.  
9. There are methods to issue pairing tokens to unknown users and to approve pairing tokens, moving users into an approved map and notifying them.  
10. A top-level approve_chat_pairing_token function provides a convenience entry point to approve tokens for the supported platforms.

Purpose:
1. The module exists to consolidate duplicated platform-specific logic into a single, reusable adapter that standardizes interactions across Telegram, Slack, and Discord.  
2. It centralizes message sending, audio delivery, chat-action signaling, and read-marking so higher-level command handlers need not handle platform differences.  
3. The helper functions provide deterministic text normalization and audio-path extraction so that TTS outputs can be discovered and sent reliably.  
4. Pairing token management is implemented here to control which remote users may interact with the system, including issuance, expiration, and approval flows.  
5. Persisting approved and pending user state via the agent session manager allows pairing state to survive process restarts and be shared with the session-backed storage.  
6. The monitor_event method records platform interactions into the agent session as tool messages, enabling auditing and model-context enrichment.  
7. The run_with_typing facility improves user experience by periodically emitting a platform-specific typing indicator while asynchronous work completes.  
8. By routing platform-specific bridge calls via the adapter, the rest of the codebase can treat sending/receiving actions uniformly and avoid conditional platform code duplication.  
9. The adapter integrates with the agent tool execution flow to request and handle TTS generation when a user explicitly requests audio output.  
10. Error handling and UI notifications are concentrated here so failures in platform operations are surfaced consistently to the operator UI.  
11. The module also exposes a convenience function to approve tokens without needing to construct an adapter elsewhere, simplifying administrative commands.  
12. Overall, the file exists to both simplify cross-platform support and to provide consistent stateful behavior for pairing and tool-driven outputs.

Key elements:
- truncate_chat_text (function; trims and collapses whitespace, limits characters).  
- chat_user_display (function; formats user display name from user record).  
- remote_user_requested_audio (function; detects audio/tts request keywords in user text).  
- extract_audio_paths_from_tool_output (function; parses tool output lines beginning with "Path:" and returns resolved .mp3 Paths).  
- collect_turn_generated_audio_paths (function; scans session messages from a turn start index for pocket_tts tool outputs).  
- cleanup_expired_pairings (function; removes expired tokens using now_utc and ISO timestamps).  
- generate_pairing_token (function; produces unique 8-char token from restricted alphabet).  
- PlatformAdapter (class; primary adapter encapsulating platform operations and state).  
- PlatformAdapter.__init__ (constructor; binds RuntimeContext and platform name and loads platform state).  
- PlatformAdapter.send (async method; sends text messages via platform bridge and logs outgoing event).  
- PlatformAdapter.send_chat_action (async method; sends typing/upload indicators to platform).  
- PlatformAdapter.mark_read (async method; marks messages read with platform-specific bridge calls).  
- PlatformAdapter.monitor_event (async method; logs events to UI and writes tool messages to agent session).  
- PlatformAdapter.run_with_typing (async method; runs coroutine while periodically sending typing actions).  
- PlatformAdapter.send_audio_file (async method; uploads audio per-platform and records outgoing_audio or error).  
- PlatformAdapter.maybe_send_audio_for_turn (async method; orchestrates pocket_tts invocation, result handling, and sending audio).  
- PlatformAdapter.pair_unknown_user (async method; issues or reuses pairing tokens, persists pending_pairings, and notifies user).  
- PlatformAdapter.approve_pairing_token (async method; validates token, moves entry to approved_users, persists state, notifies user).  
- PlatformAdapter._save_state / load_state (async methods; persist and restore approved/pending maps via session_manager JSON).  
- _message_user_id, _message_channel_id, _message_reply_id, _channel_kwargs, _reply_kwargs (helpers; normalize platform-specific message fields).  
- approve_chat_pairing_token (async function; convenience wrapper that creates adapter and approves a token).  
- External dependencies (get_config, now_utc, to_utc_iso, asyncio, secrets, pathlib.Path, json via runtime import, runtime context and agent interfaces).

Key logic:
1. The top-level text helpers normalize incoming strings, truncate long messages for previews, and determine whether user input requests audio using keyword matching.  
2. Audio-path extraction scans tool output lines that start with "Path:", strips any appended "(requested:" annotations, resolves file paths, filters for existing .mp3 files, and deduplicates results.  
3. collect_turn_generated_audio_paths iterates session messages from a provided index, selects tool messages produced by pocket_tts that are not error lines, and aggregates MP3 paths found by the extractor.  
4. Pairing cleanup computes the current UTC timestamp and removes pending pairing tokens whose ISO-formatted expires_at timestamps are in the past or unparsable.  
5. generate_pairing_token produces an 8-character token from a restricted alphabet and ensures uniqueness against the current pending map by regenerating on collision.  
6. PlatformAdapter stores a reference to the runtime context, platform name, and platform-specific state obtained from the context for later operations.  
7. Sending text routes to platform-specific bridge methods with appropriate parameter names (e.g., chat_id vs channel_id, reply identifiers) and on success records an outgoing_message tool event; failures append a system UI line.  
8. send_chat_action and mark_read use platform-conditional branches to call bridge APIs with the correct parameter sets and handle exceptions with UI logging.  
9. monitor_event assembles a payload and body text, appends it to the UI tool output, and, if there is an active agent session, adds a tool message to that session and triggers session persistence.  
10. run_with_typing creates an asyncio task that periodically sends a chat action until an Event is set, awaits the provided work coroutine, and then cancels and awaits the heartbeat task to shut it down cleanly.  
11. send_audio_file adapts upload semantics per platform, records outgoing_audio metadata including size, and on exception records an outgoing_audio_error and notifies the UI.  
12. maybe_send_audio_for_turn first attempts to reuse any MP3 files already generated during the turn; if none, it checks whether the user requested audio and whether pocket_tts is available, truncates source text to tool limits, invokes pocket_tts via agent tool execution, treats the tool output as a session tool message, persists the session, and sends any resulting MP3 files; errors are monitored and reported.  
13. pair_unknown_user ensures expired tokens are cleaned, reuses existing tokens per user when present, otherwise generates a new token with an expiration derived from configuration or defaults, saves the pending pairing, persists state, and sends a pairing instruction message to the originating channel.  
14. approve_pairing_token canonicalizes the provided token, ensures it exists and contains a user_id, promotes the pending record into approved_users with metadata and approval timestamp, persists both maps, and notifies the approved chat if a bridge is available.  
15. State persistence is implemented by serializing approved_users and pending_pairings to JSON using the agent.session_manager.set_app_state and restored via get_app_state with defensive parsing.  
16. A small convenience function approve_chat_pairing_token validates platform argument, constructs an adapter, and delegates approval, centralizing administrative token approval behavior.

---

## captain-claw-src/captain_claw/agent_reasoning_mixin.py

Description:
1. This mixin provides helper methods for clarification handling, contract planning, and list-task reasoning used by an agent.  
2. It includes heuristics to detect when users request clarifications, ask to cover all sources, or request fresh fetches.  
3. It can merge a short follow-up user reply with a previous assistant anchor or assistant response to form an effective user input for planning.  
4. The mixin tracks clarification state in session metadata and updates pending or cleared flags based on assistant prompts and user replies.  
5. It supplies a source-report prefetch pipeline that iterates source URLs, invokes a web_fetch tool when available, and records tool outputs and success/failure counts.  
6. There are utilities to count per-source sections, detect a conclusion heading, and validate a source-by-source report for completeness.  
7. The module extracts JSON objects from noisy model outputs (including fenced code blocks) to interpret planner and critic responses.  
8. Contract generation uses LLM-based planner prompts with token-limit-aware retry logic, normalization of tasks and requirements, and a fallback default contract when needed.  
9. A critic pass evaluates candidate responses against contract requirements by calling the model, parsing JSON checks, and assembling completion judgments.  
10. The mixin also supports list-extraction, member normalization, execution-strategy selection (direct vs script), coverage evaluation, and feedback generation.

Purpose:
1. The file exists to centralize reasoning patterns and planning utilities that are shared across agent behaviors.  
2. It encapsulates clarification heuristics so the agent can avoid unnecessary re-research and sensibly merge short user replies into context.  
3. By tracking clarification state in session metadata the mixin enables multi-turn clarification workflows to persist across messages.  
4. It provides a structured contract generation flow so the agent can decompose complex requests into tasks, requirements, and prefetch URLs before execution.  
5. The normalized contract representation makes downstream execution, retries, and critic evaluation more deterministic and machine-readable.  
6. Prefetch and source-report helpers let the agent proactively fetch and record web sources when the web_fetch tool is available, improving evidence collection.  
7. The critic evaluation step enforces contract requirements and yields per-requirement checks so the agent can gate completion or produce targeted corrections.  
8. List-processing helpers support extracting list members from context, normalizing them, choosing an execution strategy, and verifying coverage after execution.  
9. Rephrasing logic reduces downstream parsing complexity by optionally rewriting complex free-form prompts into structured, extractable formats.  
10. Deterministic utilities—JSON extraction, id normalization, and simple regex-based detectors—stabilize LLM-driven workflows and reduce brittle parsing.  
11. The mixin integrates with instruction templates, model completion guards, and the tools subsystem to keep LLM interactions consistent and observable.  
12. Overall, it lets higher-level agent code focus on orchestration while delegating planning, validation, and list reasoning to a single reusable component.

Key elements:
- AgentReasoningMixin class (mixin container for reasoning helpers).  
- _request_references_all_sources (heuristic to detect "check all sources" intent).  
- _assistant_requests_clarification (heuristic to detect agent clarification questions).  
- _should_apply_pending_clarification (heuristic to decide whether to merge a pending clarification).  
- _resolve_effective_user_input (merges anchor/assistant text into the user's input when appropriate).  
- _update_clarification_state (updates session.metadata clarification_state).  
- _should_run_source_report_pipeline (decide whether to run per-source report).  
- _run_source_report_prefetch (async prefetch that iterates URLs, calls web_fetch via _execute_tool_with_guard, records outputs).  
- _count_source_sections / _has_conclusion_section / _validate_source_report_response (report validation helpers).  
- _extract_json_object (parses first JSON object from raw model text, including fenced blocks).  
- _should_use_contract_pipeline (mode/planning toggle logic).  
- _normalize_contract_tasks / _normalize_contract_requirements (normalize planner output into stable task DAG and requirement list).  
- _default_task_contract (fallback contract construction).  
- _generate_task_contract (async planner call with retries, token caps, normalization, and prefetch URL merging).  
- _evaluate_contract_completion (async critic that calls model and parses JSON checks).  
- _build_completion_feedback (compose retry guidance from critic output).  
- _should_rephrase_task / _rephrase_task (detect and perform prompt rephrasing via LLM).  
- _normalize_list_members / _generate_list_task_plan / _choose_list_execution_strategy (list extraction and strategy selection).  
- _collect_list_extraction_context / _evaluate_list_member_coverage / _build_list_coverage_feedback / _apply_list_requirements (list coverage evaluation and requirement augmentation).  
- External integrations: get_config (config access), Message (instruction/LLM message wrapper), self.tools (tool discovery and saved paths), self.instructions (template loading), and various self.* helpers (_complete_with_guards, _execute_tool_with_guard, _emit_tool_output, _add_session_message).

Key logic:
1. The mixin first applies lightweight regex-based heuristics to user text to detect intents like "check all sources," list-processing requests, explicit script generation, or requests to refetch data.  
2. For pending clarification flows it inspects session.metadata.clarification_state and, when the user's reply is short and not a command, merges either the original anchor or the last assistant response into an augmented effective input.  
3. The merge records whether the user explicitly requested a fresh fetch and annotates the merged prompt to allow re-research when requested.  
4. Clarification state is updated after assistant outputs: if the assistant asked clarifying questions the pending flag and anchor are set; otherwise any pending flag is cleared and timestamps updated.  
5. Source-report prefetching first checks for web_fetch availability, then iterates source URLs, calls a guarded tool execution, records tagged tool messages into the session, emits telemetry, and counts fetched/failed totals.  
6. Contract generation builds system and user prompt messages from instruction templates, configures max token budgets with first and retry attempts, calls the model via a guarded completion function, and attempts to parse an emitted JSON object.  
7. If planner output is invalid the logic falls back to a deterministic default contract and emits a planner_fallback tool output.  
8. Task normalization traverses planner-provided structures recursively, extracts titles, children, dependencies, retry limits, and timeouts, enforces depth and total-node caps, and assigns stable ids.  
9. Prefetch URL handling merges planner-provided URLs with recent sources and truncates to configured limits; when require_all_sources is set, missing URLs may be added to requirements.  
10. The critic evaluation constructs a critic prompt, calls the model with token limits, extracts JSON checks, maps checks to the original requirement ids, and derives a boolean completion result based on check outcomes.  
11. Feedback construction composes human-readable retry instructions by combining critic feedback and enumerating missing requirement reasons, instructing the agent to return only corrected final answers when appropriate.  
12. Rephrase logic computes complexity signals (multiple URLs, list-language markers, format mentions, line counts, list punctuation) and only calls the rephraser when the signal threshold is met; rephrased text is sanity-checked for length and stripped of code fences.  
13. List extraction calls an LLM extractor, normalizes and deduplicates members, selects a strategy (direct tool usage or script) based on explicit script requests or recommended strategy, and emits tool outputs summarizing the plan.  
14. After execution the mixin evaluates coverage by scanning assistant/tool messages and saved artifact filenames for aliases of each member, classifies covered vs missing members, and either adds per-member requirements or composes coverage feedback advising script regeneration or continued direct looping.  
15. Throughout the flows the mixin relies on small deterministic helpers (regex-based JSON/URL parsing, id normalization, alias generation) and emits structured telemetry via _emit_tool_output to integrate with the broader agent tooling and session systems.

---

## captain-claw-src/captain_claw/session_orchestrator.py

Description:
1. This module implements SessionOrchestrator, a coordinator that decomposes complex user requests into task graphs, dispatches tasks to worker agents, and synthesizes final results.  
2. It uses an LLM provider to decompose the user's input into a JSON plan and to synthesize a combined answer from task outputs.  
3. The orchestrator builds a TaskGraph from the plan and tracks task metadata, dependencies, statuses, retries, and results.  
4. An AgentPool is used to obtain per-task worker agents which run task-specific prompts and return outputs.  
5. The module manages session assignment by creating new sessions when tasks lack an existing session_id and can honor preview overrides.  
6. It executes tasks in parallel across sessions, monitoring progress, handling timeouts, retries, cancellations, and restart logic.  
7. A shared FileRegistry is provided so tasks can share and discover files produced by upstream dependencies within a run.  
8. The orchestrator supports saving and loading workflows to disk, extracting and substituting template variables in task text, and exporting run outputs as Markdown.  
9. It broadcasts structured events and emits tool output callbacks to inform external listeners of decomposition, execution progress, timeouts, and completion.  
10. Utility parsing logic extracts JSON blobs from noisy LLM responses, stripping code fences and searching for brace-delimited blocks.  

Purpose:
1. The purpose of this file is to provide a high-level orchestration layer that enables multi-session, parallel execution of decomposed tasks in Captain Claw.  
2. By splitting complex requests into a DAG of smaller tasks, it lets specialized worker agents run isolated subtasks while the orchestrator manages dependencies and ordering.  
3. This separation improves scalability and allows independent tasks to run concurrently without contaminating each other's session context.  
4. The orchestrator exists to coordinate interactions between the LLM provider, agent pool, session manager, instruction templates, and file registry so these components can work together.  
5. It exposes a prepare step for decomposition and preview, and an execute step that applies overrides, assigns sessions, and runs the full execution lifecycle, making it suitable for both synchronous and asynchronous use.  
6. Workflow save/load and variable extraction features let users persist reusable task plans and parameterize workflows without manual reconstruction.  
7. The module centralizes timeout handling, pause/edit/resume semantics, retry behavior, and restart cascades to provide robust execution control and to surface meaningful events to UI or API layers.  
8. It also collects usage and context metrics from workers and emits these through callbacks for telemetry or user feedback.  
9. By keeping a shared FileRegistry, the orchestrator enables cross-task file discovery and produces comprehensive manifests for synthesis and reporting.  
10. The JSON parsing utilities and prompt rendering protect downstream steps from noisy LLM output formats, improving resilience of the decomposition and synthesis stages.  
11. Finally, the orchestrator provides programmatic methods for task management (pause, edit, update, restart, resume, postpone) and lifecycle operations (reset, shutdown) that the rest of the application can call.  
12. Overall, this file exists to encapsulate the complex control flow, concurrency, and persistence concerns needed to run multi-step, multi-session workflows reliably.  

Key elements:
- SessionOrchestrator class (primary orchestrator implementing preparation, execution, synthesis, and lifecycle).  
- _decompose (method that builds prompts, calls LLM provider, and parses JSON plans).  
- _assign_sessions (method that assigns or creates sessions via session_manager).  
- _execute_graph (main execution loop driving parallel task execution and timeout handling).  
- _run_worker (per-task worker runner that uses AgentPool and agent.complete).  
- _synthesize (method that formats task results and calls provider.complete for final answer).  
- prepare / execute / orchestrate (public API methods for decomposition preview and full run).  
- pause_task, edit_task, update_task, restart_task, resume_task, postpone_task (task control methods).  
- save_workflow, load_workflow, list_workflows, delete_workflow, _save_run_output (persistence and reporting functions).  
- _parse_json_response (robust JSON extraction from LLM output including fence and brace handling).  
- _extract_variables, _substitute_variables, _safe_filename, _generate_workflow_name (utility functions for variable and filename handling).  
- AgentPool, InstructionLoader, FileRegistry, get_session_manager, LLMProvider/get_provider, TaskGraph/OrchestratorTask (notable external classes/dependencies).  
- Callbacks: status_callback, tool_output_callback, broadcast_callback (external integration hooks).  

Key logic:
1. prepare(user_input) first creates a FileRegistry for the run, calls _decompose to obtain a JSON plan from the LLM, validates the plan, and constructs a TaskGraph of OrchestratorTask objects for preview.  
2. The _decompose flow renders system and user prompts with InstructionLoader, appends an available-sessions summary, invokes the provider.complete call with a planner timeout, and parses the returned text with _parse_json_response.  
3. During graph construction the orchestrator skips invalid tasks (empty id), logs warnings, and assembles a previewable tasks list while extracting {{variable}} placeholders for templating.  
4. execute applies variable substitutions and per-task overrides, optionally applies a workflow-level model override, and then assigns sessions for tasks that lack session_id via _assign_sessions which may call session_manager.create_session.  
5. _execute_graph manages concurrency by activating ready tasks from the TaskGraph, creating asyncio tasks for _run_worker, and tracking them in _pending_futures while enforcing a poll loop using asyncio.wait with FIRST_COMPLETED.  
6. The execution loop uses graph.tick_timeouts to detect warning, restart, and failure conditions and broadcasts timeout events; it also supports waiting on a resume_event when no tasks are active to allow user-driven edits/postpones.  
7. _run_worker obtains an Agent from AgentPool, applies per-task model overrides, composes a worker prompt including a file manifest from FileRegistry, awaits agent.complete, and on success calls graph.complete_task with captured output and usage metrics.  
8. Worker exceptions, timeouts, and cancellations are handled to mark tasks failed, emit tool output and broadcast task_failed events, and always release the agent back to the pool in a finally block.  
9. Timeout-handling semantics include emitting warnings, cancelling and restarting timed-out attempts, and exhausting retries to mark tasks as failed when necessary.  
10. Task control methods (pause/edit/update/restart/resume/postpone) manipulate graph state, cancel or await pending worker futures, evict cached agents when descriptions change, and signal the execution loop to re-evaluate activatable tasks.  
11. After all tasks complete or fail, _synthesize collects formatted task results via _format_results_for_synthesis, attaches a file manifest if present, renders a synthesis prompt, and calls the provider for a final aggregated answer, falling back to raw results or timeout/failure messages on error.  
12. Workflow persistence writes and reads JSON files under a workspace workflows directory, serializing task definitions, variables, and model metadata, and rebuilding TaskGraph objects when loading.  
13. _parse_json_response implements a tiered strategy to recover a dict from LLM output: direct json.loads, stripping and parsing code fences, then extracting the first brace-delimited block as a last resort.

---

## captain-claw-src/captain_claw/config.py

Description:
1. This module defines typed configuration models and utilities for Captain Claw using Pydantic BaseModel and BaseSettings.  
2. It declares default filesystem locations for the user config YAML and session database and a local config filename.  
3. The file contains many nested configuration classes covering model, context, memory, tools, skills, guards, session, workspace, UI, logging, messaging integrations, and orchestration.  
4. The Config class centralizes application settings and configures environment variable handling via SettingsConfigDict with an env prefix and nested delimiter.  
5. Helper methods implement loading from YAML, sanitizing legacy YAML constructs, reading simple .env files, and mapping legacy top-level keys into the nested model.  
6. The load() method overlays environment variables and .env values onto the parsed YAML to ensure sensitive tokens can be injected securely.  
7. The save() method persists the active configuration to disk as JSON-safe YAML and ensures parent directories exist.  
8. A resolved_workspace_path() utility converts the workspace path into an absolute path anchored to a runtime base or the current working directory.  
9. The module exposes a module-level singleton pattern with get_config() and set_config() to share a global Config instance across the application.  
10. Several defaults, fallback behaviors, and provider compatibility rules are encoded so common environment variables are honored when appropriate.

Purpose:
1. The file exists to provide a single authoritative source of runtime configuration for Captain Claw and to enforce typing, defaults, and validation for all subsystems.  
2. It centralizes the mechanics of reading configuration from persistent YAML files while still allowing secure, operational overrides from environment variables or a .env file.  
3. By modeling each subsystem as its own Pydantic model, it makes defaults explicit and simplifies consumption by other modules that require structured settings.  
4. The legacy compatibility helpers allow the project to accept older flat configuration formats and sanitize legacy YAML serialization artifacts without forcing manual user migrations.  
5. Environment-overlay logic is specifically designed to keep secrets out of repository YAML by allowing tokens, API keys, and credentials to be provided at runtime instead.  
6. The module codifies provider-specific fallback rules (for example, mapping OPENAI_API_KEY to the model.api_key for OpenAI providers) to reduce operator configuration friction.  
7. The save method enables programmatic updates to configuration to be written back to disk in a stable, JSON-safe YAML format.  
8. resolved_workspace_path prevents ambiguous relative workspace references by anchoring non-absolute workspace paths to a given runtime base or CWD.  
9. The SettingsConfigDict configuration on the Config class standardizes environment variable prefixing and nested delimiter behavior for predictable env-driven overrides.  
10. Exposing get_config and set_config implements a straightforward global accessor pattern so modules can share a single config instance without repeated parsing.  
11. The module bundles many tool-, memory-, and integration-specific defaults so a freshly-installed environment has sensible behavior without extensive operator setup.  
12. Overall, this file reduces duplication, improves upgrade tolerance, and centralizes security-sensitive configuration concerns for the whole application.

Key elements:
- DEFAULT_CONFIG_PATH, DEFAULT_DB_PATH, LOCAL_CONFIG_FILENAME (module-level path constants).  
- ModelConfig (Pydantic model for LLM/provider settings; includes nested AllowedModelConfig).  
- ContextConfig, MemoryEmbeddingsConfig, MemorySearchConfig, MemoryConfig (memory-related settings and defaults).  
- ShellToolConfig (includes ExecPolicy StrEnum for shell execution policies).  
- WebFetchToolConfig, WebSearchToolConfig, PocketTTSToolConfig, SendMailToolConfig, TypesenseToolConfig (tool-specific configuration models).  
- ToolsConfig (aggregates enabled tools and tool-specific subconfigs).  
- SkillEntryConfig, SkillsLoadConfig, SkillsInstallConfig, SkillsConfig (skill subsystem configuration).  
- GuardTypeConfig, GuardConfig (guard behavior toggles for input/output/script tools).  
- SessionConfig, WorkspaceConfig, UIConfig, ExecutionQueueConfig, LoggingConfig (runtime and UI settings).  
- TelegramConfig, SlackConfig, DiscordConfig (messaging integration configs).  
- TodoConfig, AddressBookConfig, ScriptsMemoryConfig, ApisMemoryConfig (cross-session memory settings).  
- ScaleConfig, DeepMemoryConfig, OrchestratorConfig, GoogleOAuthConfig, WebConfig (advanced and integration settings).  
- Config (BaseSettings central settings class with methods: _apply_legacy_top_level_config, _read_dotenv_file, resolve_default_config_path, from_yaml, load, save, resolved_workspace_path).  
- _config (module-level singleton), get_config(), set_config() (singleton accessors).  
- External dependencies: yaml.safe_load/safe_dump, pydantic.BaseModel/BaseSettings, pydantic_settings.SettingsConfigDict, os, re, pathlib.Path.

Key logic:
1. Loading begins with Config.from_yaml which determines the config file path (local config in CWD preferred) and returns a default Config if no file exists.  
2. from_yaml reads the YAML file text and attempts yaml.safe_load; if a ConstructorError referencing python/object/apply appears it applies a regex-based sanitization to strip legacy python/object/apply tags and retries parsing.  
3. If sanitization changed the content, from_yaml attempts to write the sanitized YAML back to disk (best-effort, swallow exceptions).  
4. After parsing YAML, _apply_legacy_top_level_config is invoked to map legacy flat keys like openai_api_key and ollama_base_url into the nested model dict under "model", and to remove the old keys.  
5. Config.load first calls from_yaml then reads simple KEY=VALUE pairs from a .env file using _read_dotenv_file which strips comments, supports optional leading "export ", and unquotes quoted values.  
6. load builds an env_overlay = cls() instance so that Pydantic's SettingsConfigDict behavior can surface any environment-prefixed variables set in the runtime environment.  
7. The method then checks for sensitive values (Telegram, Slack, Discord tokens, Brave API key, Typesense key, and mail/SMPP credentials) and overlays non-empty environment/.env values into the loaded Config instance, preserving YAML values unless env values are present.  
8. For mail and other mapped keys, load iterates a small mapping and conditionally sets attributes, converting smtp_port to int when appropriate and ignoring invalid conversions.  
9. Provider compatibility logic checks the configured model.provider and if the model.api_key is empty it will look for common provider environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY/GOOGLE_API_KEY) and set model.api_key accordingly.  
10. Additional provider fallback logic sets an Ollama base_url from OLLAMA_BASE_URL if the provider is ollama and base_url is empty.  
11. Google OAuth environment overrides are applied for client id/secret/project id and GOOGLE_OAUTH_ENABLED is interpreted from truthy strings; google_oauth.enabled is auto-enabled if both client id and secret are present.  
12. The save() method converts the Pydantic model to a JSON-safe dict via model_dump(mode="json", exclude_none=True), ensures the parent directory exists, and writes YAML using yaml.safe_dump with consistent formatting.  
13. resolved_workspace_path converts the configured workspace.path into an absolute Path by expanding user and either returning it directly for absolute paths or joining it to a provided runtime_base or current working directory for relative paths.  
14. The module-level singleton uses get_config to lazily load and cache a Config instance via Config.load and set_config to replace it, providing a simple global accessor pattern for the rest of the application.

---

## captain-claw-src/captain_claw/agent_skills_mixin.py

Description:
1. This module provides a mixin class AgentSkillsMixin containing helpers for loading, ranking, invoking, and managing skills for an agent.  
2. It includes utilities to parse LLM payloads to extract selected candidate IDs.  
3. The mixin offers functions to resolve and cache a workspace skills snapshot with session-aware caching and optional watch/debounce behavior.  
4. There is logic to build a skills section suitable for inclusion in a system prompt that instructs the model how to pick and read SKILL.md files.  
5. It can list invocable skill command specifications and rewrite user prompts to direct the model to use a specific skill.  
6. The module supports invoking skill commands either by dispatching to a tool or running a script and handles tool execution results and session message recording.  
7. It includes workflows to install a skill from a GitHub URL and to install a skill's declared dependencies.  
8. A search routine queries a configured skill catalog, ranks candidates lexically, optionally reranks with an LLM, and returns top results.  
9. Helper methods handle applying and restoring environment overrides defined by skills before running tasks.  
10. The implementation relies on external helper functions and classes imported from captain_claw.skills, the runtime provider for LLM calls, session manager methods, and configuration utilities.  

Purpose:
1. The mixin centralizes skill-related functionality so an Agent implementation can manage skills without duplicating logic.  
2. It exists to bridge skill metadata, catalog search, and runtime dispatch mechanisms into a coherent API used by higher-level agent code.  
3. Snapshot resolution and caching reduce expensive filesystem or network operations by preserving a skills snapshot tied to workspace state and session metadata.  
4. Building a skills system prompt section ensures the agent can present available skills to an LLM in a consistent, constrained format so the model knows how to select and read skill documentation.  
5. The search and ranking facilities let the agent find relevant skills by combining fast lexical ranking with optional LLM-based semantic re-ranking for higher quality suggestions.  
6. Manual invocation and dispatch handling enable users to run skill commands as tools or scripts while the mixin builds commands, runs them through guarded execution, and records outputs.  
7. Installation helpers keep skill acquisition and dependency installation inside agent workflows, returning structured results and errors for the caller to surface.  
8. Environment override application makes skill-provided environment variables and API keys available during execution and provides a restore callback to confine their scope.  
9. Session-aware snapshot restoration allows agents to reuse previously computed skill snapshots stored in session metadata when appropriate.  
10. Error handling and fallbacks (for example when provider or catalog sources are unavailable) are included so higher-level code can present clear failure states.  
11. The mixin is provider-aware and only attempts LLM re-ranking when a configured provider exists, avoiding unnecessary exceptions.  
12. Overall, it exists to provide a reusable, testable surface for skill discovery, selection, invocation, installation, and environment management within the agent runtime.

Key elements:
- AgentSkillsMixin (class; central mixin providing all skill helpers).  
- _extract_skill_search_ids (method; parses LLM payloads to integer candidate IDs).  
- _rank_skill_search_entries_with_llm (async method; builds prompts and calls provider.complete to semantically rank candidates).  
- _resolve_skills_snapshot (method; computes, caches, and restores SkillSnapshot instances using session metadata and watch/debounce settings).  
- _build_skills_system_prompt_section (method; returns a formatted skills block for inclusion in system prompts).  
- list_user_invocable_skills (method; returns current SkillCommandSpec entries).  
- rewrite_prompt_for_skill (method; produces a prompt that instructs the model to use a specific skill).  
- _resolve_script_dispatch_command (static method; resolves script dispatch to a shell command and script path, handling interpreters and argument quoting).  
- invoke_skill_command (async method; dispatches commands to tools or scripts or returns a rewritten prompt).  
- install_skill_from_github (async method; wraps install_skill_from_github_url and returns metadata).  
- install_skill_dependencies (async method; calls install_skill_dependencies_for_entry and normalizes the result).  
- search_skill_catalog (async method; loads catalog, does lexical ranking, optional LLM re-ranking, and returns structured results).  
- _apply_skill_env_overrides_for_run (method; applies skill env overrides via apply_skill_env_overrides and returns a restore callback).  
- External dependencies (functions/classes used): get_config, Message, get_logger, build_workspace_skill_snapshot, compute_skills_snapshot_version, apply_skill_env_overrides, load_skill_catalog_entries, rank_skill_catalog_entries, install_skill_from_github_url, install_skill_dependencies_for_entry, find_skill_command, snapshot_from_dict, snapshot_to_dict.  
- Expected host attributes/methods referenced on self: provider (LLM provider), workspace_base_path, session, session_manager.save_session, _execute_tool_with_guard, _add_session_message, _emit_tool_output.

Key logic:
1. Payload extraction first collects several possible keys from an LLM response (selected_ids, top_ids, ids, selected, results) and normalizes values into positive integer IDs while ignoring invalid values.  
2. LLM-based ranking composes a candidate JSON payload and two prompts (system and user) instructing the model to return strict JSON with selected_ids, then calls provider.complete with low temperature and a token limit.  
3. The ranking method attempts to parse a JSON response and falls back to an internal _extract_json_object hook if the direct parse fails, then maps returned indices back to catalog entries within bounds.  
4. Snapshot resolution uses configuration-controlled watch behavior and debounce timing to decide whether to return a cached SkillSnapshot or recompute it by computing a version hash and building a workspace snapshot.  
5. When session metadata contains a stored snapshot, the resolution routine may restore the snapshot via snapshot_from_dict and reuse it if versions match or watch is disabled.  
6. After building a new snapshot with build_workspace_skill_snapshot the method caches it and writes a snapshot and timestamp into session.metadata["skills"] when a session exists.  
7. The skills system prompt section prepends mandatory instructions about scanning available skills and constraints, then appends the snapshot-provided prompt block if present.  
8. invoke_skill_command resolves a command by name and, depending on dispatch.kind, either constructs a tool call (packing command, commandName, skillName) or resolves a script command into a quoted shell command and delegates execution to _execute_tool_with_guard.  
9. Tool and script dispatch paths capture execution success or error, add a corresponding session message with role "tool", emit tool output events, and persist the session via session_manager.save_session when available.  
10. If a command is neither a tool nor a script dispatch, invoke_skill_command returns a rewritten prompt instructing the model to use the specified skill, enabling prompt-based skill invocation.  
11. The install_skill_from_github method calls install_skill_from_github_url and then refreshes the snapshot to list aliases for the newly installed skill, wrapping exceptions into structured error responses.  
12. install_skill_dependencies delegates to install_skill_dependencies_for_entry and returns either a detailed success dictionary including stdout/stderr/command info or a normalized error structure on failure.  
13. search_skill_catalog validates configuration for a source URL, loads catalog entries via load_skill_catalog_entries in a thread, constructs a lexical pool and fallback ranks with rank_skill_catalog_entries, optionally invokes the LLM reranker on an expanded pool, and assembles a deduplicated top-N result list to return.

---

## captain-claw-src/captain_claw/skills.py

Description:
1. This module implements skill discovery, parsing, metadata representation, and command invocation metadata for Captain Claw.  
2. It defines many dataclasses to model skill install specifications, metadata, invocation policies, command dispatch and snapshot structures.  
3. It parses SKILL.md frontmatter using YAML/JSON rules to extract skill name, description, metadata and invocation policies.  
4. The module discovers skills from multiple configured roots including bundled, managed, workspace, plugin and extra directories with ordered precedence.  
5. It can parse GitHub URLs to identify a skill folder or SKILL.md location and download skill content either through the GitHub Contents API or by cloning the repository.  
6. The code supports installing declared runtime dependencies using multiple installers (brew, node, go, uv, download) and can extract archives safely.  
7. It builds a prompt-friendly XML-like representation of available skills, constructs invocable command specs, and resolves slash-style command invocations.  
8. Snapshot utilities compute a deterministic snapshot version, serialize and restore snapshots, and assemble a prompt payload for model injection.  
9. Filtering routines evaluate metadata requirements, platform constraints, environment and config prerequisites to determine eligible skills.  
10. Various helper functions perform path normalization, security checks, archive normalization, GitHub API interactions, and environment override application.  

Purpose:
1. The module centralizes all logic required to locate, load, describe and expose skills to the rest of the application.  
2. It exists to discover SKILL.md files from a configurable set of roots so skills provided by the workspace, plugins, bundled packages and managed installs are available with a clear precedence.  
3. By parsing frontmatter and an embedded metadata block it extracts runtime requirements, install instructions and invocation controls that determine whether and how a skill may be used.  
4. The file supplies installation helpers that can fetch skill content from GitHub either by the API (directory download) or by cloning the repository and validating the selected SKILL.md.  
5. It implements dependency installation flows that choose an appropriate installer based on declared install specs and platform constraints, then run commands or extract archives and return structured results.  
6. Snapshot and serialization functions let the runtime build a compact representation of available skills and commands for injection into model prompts or storing in session metadata.  
7. Command-spec builders translate skill declarations into user-invocable commands and encode dispatch behavior to tool invocation or script execution as declared in frontmatter.  
8. Filtering and ranking helpers enforce configuration allowlists, platform compatibility and declared requirements so only usable skills are presented to users and models.  
9. Security-oriented utilities normalize repository subpaths, prevent path traversal, validate archive members and refuse extraction of symlinks or entries that escape the target directory.  
10. The module is shaped to integrate with the project's Config and logging layers so user preferences (installer selection, prompt size limits, plugin dirs) are honored and diagnostics are emitted.  
11. Lightweight HTTP interactions using httpx support catalog fetching and GitHub contents retrieval, while simple lexical ranking provides a fallback for catalog search.  
12. In sum, the module exists to make skill discovery, installation, dependency orchestration and runtime exposure robust, inspectable and configurable for the Captain Claw tooling.  

Key elements:
- SkillInstallSpec (dataclass representing a single installer option declared by a skill).  
- SkillRequires, SkillMetadata, SkillInvocationPolicy (dataclasses modeling metadata and invocation rules).  
- SkillEntry, SkillCommandDispatch, SkillCommandSpec, SkillSnapshot, SkillSnapshotSkill (dataclasses for loaded skill entries, command specs and snapshot structures).  
- GitHubSkillSource, SkillInstallResult, SkillDependencyInstallResult, SkillCatalogEntry (dataclasses for GitHub parsing and installation/catalog results).  
- parse_github_skill_source (parses supported GitHub URLs into owner/repo/ref/skill_path).  
- install_skill_from_github_url (high-level installer that downloads/clones and copies a skill into managed_dir).  
- install_skill_dependencies (selects and runs installers for a skill's declared install specs and returns structured results).  
- _install_download_spec, _run_install_command, _resolve_node_install_command (helpers for download/extract and running install commands).  
- _run_git_clone, _fetch_github_contents, _download_github_directory, _download_file_to_path (GitHub API and git fallbacks for fetching skill files).  
- _extract_zip_archive, _extract_tar_archive, _normalize_archive_member_path (safe archive extraction routines).  
- _parse_frontmatter, _parse_metadata_block, _parse_metadata, _parse_install_spec (frontmatter and metadata parsing utilities).  
- _resolve_skill_roots, _iter_skill_md_candidates, load_workspace_skill_entries, _load_skill_entry (discovery and loading of SKILL.md files from configured roots).  
- filter_skill_entries, _meets_requires, _is_config_path_truthy (filtering by requirements, env and config).  
- build_workspace_skill_command_specs, find_skill_command, resolve_skill_command_invocation (command spec construction and slash-invocation resolution).  
- build_workspace_skill_snapshot, compute_skills_snapshot_version, snapshot_to_dict, snapshot_from_dict (snapshot assembly, hashing and serialization).  
- apply_skill_env_overrides (applies temporary env/apiKey overrides for a snapshot run).  
- fetch_skill_catalog_markdown, parse_skill_catalog_entries, rank_skill_catalog_entries (catalog fetching and fallback lexical ranking).  
- External dependencies (httpx, yaml, shutil, subprocess, tarfile, zipfile, hashlib, os, re, json).  

Key logic:
1. The module first establishes an ordered set of skill roots by combining user-configured extra directories, plugin-inferred skill dirs, bundled package skills, managed installs, agent-specific directories and the workspace skills directory, while deduplicating results.  
2. For each root it enumerates candidate SKILL.md files by checking a top-level SKILL.md or scanning child directories up to configured limits, then it loads each candidate only if under configured size limits.  
3. Loading a SKILL.md involves parsing a YAML frontmatter block, extracting name and description (with fallbacks), parsing an embedded metadata block (JSON or YAML inline), and resolving an invocation policy.  
4. Filtering runs against the merged entries to remove skills that fail platform checks, bundled allowlists, explicit disabled config entries, or declared requirements for binaries, environment variables or config paths.  
5. Command specs are produced for user-invocable skills by sanitizing names, ensuring uniqueness, and reading frontmatter keys to choose tool dispatch or script dispatch, resolving absolute script paths safely against the skill base directory.  
6. Snapshot construction composes a prompt fragment by formatting available skills into an XML-like block, then applies character and item count limits via a binary-search truncation strategy to respect max chars while maximizing included items.  
7. GitHub URL parsing supports repository, /tree/<ref>/<path> and /blob/<ref>/<path-to-SKILL.md> forms; downloads prefer the GitHub Contents API for directory pulls and fall back to a shallow git clone when necessary.  
8. Dependency installation normalizes declared install specs, filters by current runtime platform, selects a preferred installer according to configuration and availability (e.g., prefer brew or node manager), and executes the corresponding command or download/extract flow returning a SkillDependencyInstallResult.  
9. Downloaded archives are written to controlled target directories and extracted with tight normalization: path components can be stripped, entries validated to avoid escapes, symlinks/hardlinks refused and file writes resolved relative to the target root.  
10. Error handling communicates failures either via raised exceptions for high-level install problems or through structured result objects that include stdout/stderr/code and human messages for installer failures.  
11. Snapshot versioning computes a deterministic SHA-1 hash over resolved SKILL.md file paths, sizes and modification times to detect changes across the set of discovered skill files.  
12. Environment overrides apply per-skill configured env values and API keys by setting missing variables temporarily and returning a reverter closure to restore the original environment after the run.  
13. Additional utilities support catalog fetching by attempting README.md candidates for a configured source URL, parsing markdown bullet lists into entries, and providing a simple lexical ranking fallback based on token matches in name and description.

---

## captain-claw-src/captain_claw/memory.py

Description:
1. This module implements layered and working memory primitives used by Captain Claw for managing conversational context.  
2. It defines a WorkingMemory class that stores a sequence of role/content messages and a text summary representing older context.  
3. A small WorkingMemorySnapshot dataclass is declared to serialize a summary plus a list of messages.  
4. The WorkingMemory provides simple token estimation, message counting, and logic to decide when compaction is needed.  
5. Compaction summarizes older messages into a short human-readable summary and retains a configurable recent window of messages.  
6. The snapshot method can inject the accumulated summary as an assistant message with a tool_name marker for later consumption.  
7. A LayeredMemory facade composes the WorkingMemory with an optional SemanticMemoryIndex to provide long-term, searchable memory.  
8. LayeredMemory exposes session management, recording of messages that triggers semantic sync scheduling, and delegates semantic search and note building.  
9. A factory function create_layered_memory builds the layered memory from runtime config and will attempt to initialize a semantic memory index.  
10. The module includes a Memory alias for backward compatibility and logs warnings if semantic memory initialization fails.

Purpose:
This file exists to centralize short-term and long-term conversational state handling for the application. It provides an in-turn working memory that retains recent turns and a consolidated summary of earlier context so prompts can include relevant history without exceeding token budgets. By offering token estimation and a threshold-based compaction policy, it helps prevent prompt size blowups while preserving salient context. The compaction routine produces concise human-readable snippets of dropped messages and merges them into the stored summary to maintain continuity. The snapshot functionality formats the summary as an assistant message so downstream components or the model can consume it explicitly. LayeredMemory integrates an optional SemanticMemoryIndex to allow persistent, searchable memory that can be synchronized in the background and used to build context notes for queries. The facade also manages an active session identifier and ensures that the semantic index is aware of the current session. Error handling in the factory function ensures the system continues operating with only working memory if semantic initialization fails, with a logged warning. This separation enables other parts of the system to record messages, request compaction, perform semantic searches, and schedule syncs through a simple, consistent API. Overall, the module exists to balance immediate conversation detail with scalable persistent memory while keeping interfaces small and robust.

Key elements:
- WorkingMemorySnapshot (dataclass) (serializable container for summary and messages).  
- WorkingMemory (class) (stores messages, summary; compaction and snapshot logic).  
- WorkingMemory.add_message(role, content) (append message to working buffer).  
- WorkingMemory.clear() (reset messages and summary).  
- WorkingMemory.estimate_tokens(text) (heuristic token estimator: len//4 with min 1).  
- WorkingMemory.get_token_count() (computes combined summary + messages token estimate).  
- WorkingMemory.should_compact(threshold=0.8) (decides if compaction is needed).  
- WorkingMemory.compact(keep_recent_ratio=0.4) (summarizes older messages and retains recent window).  
- WorkingMemory.snapshot(include_summary_message=True) (returns WorkingMemorySnapshot and can prepend summary as assistant message with tool_name).  
- LayeredMemory (class) (facade combining working and semantic memories; session management).  
- LayeredMemory.set_active_session(session_id) (sets active session and forwards to semantic index).  
- LayeredMemory.record_message(role, content) (adds to working memory and schedules semantic sync for user/assistant roles).  
- LayeredMemory.search_semantic(query, max_results) (delegates to semantic index or returns empty).  
- LayeredMemory.build_semantic_note(query, ...) (delegates to semantic.build_context_note).  
- LayeredMemory.schedule_background_sync(reason) (delegates schedule_sync to semantic index).  
- create_layered_memory(config, session_db_path, workspace_path) (factory to create WorkingMemory and optional SemanticMemoryIndex).  
- Memory (alias) (backward-compatible alias for WorkingMemory).  
- Dependencies: captain_claw.semantic_memory.create_semantic_memory_index and SemanticMemoryIndex, captain_claw.logging.get_logger, re module.

Key logic:
The module uses a simple length-based heuristic to estimate tokens by dividing character count by four and ensuring at least one token. WorkingMemory accumulates messages as dicts containing role and content and maintains a separate summary string representing older context. get_token_count sums an estimated token count for the summary (if present) and each message entry to produce a lightweight measure of memory size. should_compact compares that token count against a fraction of max_tokens to decide whether to trigger compaction. compact keeps a configurable recent fraction of messages and treats the rest as candidates for summarization; it limits summary sources to the last ten dropped messages and produces one-line snippets (up to 180 characters) per dropped message. New summary lines are prefixed with role and merged with any existing summary using a blank-line separator so historical summaries accumulate over multiple compactions. After compaction the internal messages list is replaced with the recent window and an info log records counts and whether a summary exists. snapshot optionally injects the stored summary as an assistant message with tool_name "working_memory_summary" before returning a WorkingMemorySnapshot containing the summary and current messages. LayeredMemory composes a WorkingMemory and an optional SemanticMemoryIndex; set_active_session updates an internal active_session_id and forwards it to the semantic index if present. record_message always appends to working memory and only schedules a semantic sync when the role is "user" or "assistant" to avoid indexing irrelevant tool/system logs. search_semantic and build_semantic_note return empty results or empty strings when no semantic index is configured, providing safe no-op behavior. schedule_background_sync and close are thin delegations to the semantic index when available. create_layered_memory reads configuration to determine whether to enable semantic memory, constructs WorkingMemory with a max_tokens value taken from config.context (or a default), and attempts to initialize the semantic index while catching exceptions and logging a warning to fall back to working-only memory.

---

## captain-claw-src/captain_claw/agent_pool.py

Description:
1. This module implements an AgentPool class that manages a collection of worker Agent instances for parallel session orchestration.  
2. The pool maps agents by session_id and tracks last-used timestamps to enable idle eviction.  
3. Agent creation is coordinated with a global lock for lookups and per-session locks to avoid duplicate concurrent creation for the same session.  
4. get_or_create provides a fast path for cached agents and a safe creation path that evicts idle agents when the pool hits capacity.  
5. The heavy work of instantiating and configuring a worker agent is performed outside the global lock to allow parallel creation for different sessions.  
6. _create_worker_agent constructs an Agent bound to a specific session, auto-approves tool calls, and shares provider, instruction cache, and optional file registry.  
7. Worker agents bypass the normal initialization flow, are marked as workers with tuned limits, and are flagged initialized to allow completion calls.  
8. The pool exposes explicit eviction, release (mark idle), and bulk idle eviction based on configurable idle timeout.  
9. Internal eviction logic iterates over last-used timestamps and removes agents that exceed the idle threshold while logging actions.  
10. A shutdown method clears the pool and logs the number of released agents.

Purpose:
This file exists to provide a concurrent-safe, bounded pool of worker Agents used by orchestration code that needs per-session workers. It centralizes lifecycle responsibilities such as creating, registering, and removing agents so other parts of the system can request a ready-to-use agent by session id without duplicating setup logic. The pool enforces a maximum number of active agents to control resource usage and implements eviction strategies to reclaim idle workers. Per-session locks prevent race conditions where multiple coroutines would otherwise create duplicate agents for the same session. Performing the expensive agent setup outside the global lock improves throughput by allowing different sessions to be provisioned in parallel. Sharing an InstructionLoader instance across workers reduces redundant template caching and conserves memory. The pool also coordinates sharing of the LLM provider instance and an optional file registry so worker agents can resolve files produced by other tasks during an orchestration run. Worker-specific configuration (auto-approval, lowered iteration limits, and skipping heavy pipelines) tailors agents for short-lived orchestration tasks rather than interactive sessions. The class exposes simple lifecycle operations (evict, release, evict_idle, shutdown) so the rest of the application can manage agent reclamation explicitly when needed. Logging calls provide operational visibility into pool events like creation, eviction, and shutdown. Overall, the module encapsulates concurrency, resource bounds, and worker specialization to make parallel session execution safe and efficient within the project.

Key elements:
- AgentPool class (core pool manager for worker agents).  
- __init__ (configures max_agents, idle_evict_seconds, provider, callbacks, and internal structures).  
- size property (returns current agent count).  
- get_or_create(session_id, file_registry) (public async entrypoint to obtain or create a worker agent).  
- _create_worker_agent(session_id, file_registry) (async helper that constructs and configures a bound Agent).  
- evict(session_id) (remove a specific agent from the pool).  
- release(session_id) (mark agent as recently used/idle reset).  
- evict_idle() (async method to evict agents unused beyond the idle threshold).  
- _evict_idle_locked() (internal eviction implementation that inspects last-used timestamps).  
- shutdown() (clear the pool and metadata).  
- _creating (per-session asyncio.Lock map to prevent duplicate creation).  
- _shared_instructions (InstructionLoader instance shared across workers).  
- External dependencies: InstructionLoader, get_provider (LLM provider getter), get_session_manager (session loader/creator), Agent import done inside method, logging via get_logger.

Key logic:
The pool uses a two-layer locking strategy: a global asyncio.Lock guards access to the agent and last-used dictionaries for quick atomic lookups and registrations, while a per-session lock in the _creating map ensures only one coroutine creates an agent for a given session. get_or_create first acquires the global lock and returns a cached agent immediately when present, updating the last-used timestamp and optionally refreshing the agent's file registry. If no agent exists, it ensures a per-session lock exists, releases the global lock, and awaits the per-session lock so other session creations may proceed concurrently. After acquiring the session lock it re-checks under the global lock to handle the race where another coroutine finished creation in the interim. When the pool is at capacity, the code invokes _evict_idle_locked to remove entries idle beyond the configured threshold; if that doesn't free space, it forcibly evicts the oldest agent by last-used timestamp. Heavy-weight agent construction is performed by _create_worker_agent outside the global lock to avoid blocking other operations; this method imports the Agent class lazily, creates an agent with auto-approval semantics, ensures a provider is set, and loads or creates the bound session via the session manager. The created agent receives shared resources: the provider, the instruction loader cache, and an optional file registry; it also synchronizes runtime flags from session metadata and registers default tools. Worker-specific flags and limits are applied (e.g., marking _is_worker, lowering max_iterations, setting _initialized) to tailor behavior for orchestration tasks. After creation, the agent is registered under the global lock and the per-session creation lock is removed. Eviction operations compute which sessions exceed the idle threshold by comparing monotonic timestamps and remove their agents and last-used entries while logging the number evicted. The evict method can explicitly remove a single session's agent (useful after edits), and release updates last-used to mark activity. Shutdown obtains the global lock, clears both agent and last-used mappings, and logs how many agents were released. Throughout, logging statements capture lifecycle events for observability.

---

## captain-claw-src/captain_claw/agent_guard_mixin.py

Description:
1. This module defines an AgentGuardMixin class that provides guard evaluation and guarded completion/tool execution helpers for an Agent.  
2. It includes utilities to build compact trace payloads for pipeline events and to truncate large text payloads for guard evaluation.  
3. The mixin can serialize outbound prompt messages into a concise text form used by input guards.  
4. It reads guard configuration from a central config and normalizes enabled flags and enforcement levels.  
5. The mixin implements parsing logic to interpret guard model outputs, attempting JSON parsing and heuristic fallbacks.  
6. It runs guard evaluations by rendering system and user prompt templates and calling the configured provider to get a classifier response.  
7. Depending on configuration, the mixin can block, allow, or request human approval for flagged content.  
8. The mixin wraps LLM completions with pre- and post-guard checks and emits diagnostic traces and session messages.  
9. It also enforces a script/tool guard before invoking tools and forwards context like session id and approval callbacks to the tools layer.  
10. Errors from guard enforcement are surfaced as GuardBlockedError exceptions when a guard blocks an action.

Purpose:
This mixin exists to centralize and standardize content-safety checks around LLM interactions and tool invocations for agents. It provides a single place to interpret guard configuration, run classifier-style guard checks, and enforce policy decisions consistently across completions and tool executions. By serializing messages and building compact payloads, it minimizes the amount of content sent to guard models while preserving relevant metadata for accurate decisions. It also captures trace data for debugging and monitoring by emitting LLM traces and compact pipeline traces as session tool outputs. The mixin integrates with the project's provider abstraction to perform guard model calls using template-based system and user prompts sourced from the instructions helper. When a guard flags content, the mixin supports different enforcement levels: automatic blocking or asking for human approval via a provided callback. This allows operators to tune strictness per guard type (input, output, script_tool) through configuration. The parsing logic aims to be resilient by handling structured JSON responses or falling back to text heuristics to determine allow/deny outcomes. When guards allow, the mixin records usage and proceeds with the requested operation; when they block, it raises a specific GuardBlockedError to signal callers. For tool calls, the mixin enforces script_tool guards before delegating to the tools layer and forwards contextual data like session id, policies, approval callbacks, and file registry. Overall, the mixin reduces duplication, centralizes guard-related side effects (traces, session messages, usage accumulation), and enforces safety policies consistently across the agent runtime.

Key elements:
- AgentGuardMixin (class; provides guard and guarded-execution utilities).  
- _build_pipeline_trace_payload (method; compacts pipeline/tool arguments into a small trace payload).  
- _emit_llm_trace (method; produces and emits a human-readable trace of an LLM response and tool calls).  
- _truncate_guard_text (static method; caps textual payload sizes with truncation marker).  
- _guard_settings (method; reads and normalizes guard configuration from get_config()).  
- guards_enabled (method; boolean check for any enabled guard type).  
- _serialize_messages_for_guard (method; converts Message objects into condensed text for input guards).  
- _parse_guard_decision (static method; attempts JSON parsing of guard output and applies heuristics).  
- _run_guard_decision (async method; renders guard prompts and calls provider.complete to evaluate content).  
- _request_guard_approval (method; invokes an approval_callback if present to get human approval).  
- _enforce_guard (async method; enforces configured policy per guard type and emits tool outputs).  
- _complete_with_guards (async method; performs input guard, provider completion, output guard, and tracing).  
- _execute_tool_with_guard (async method; enforces script_tool guard then calls tools.execute with context).  
- External dependencies (get_config, GuardBlockedError, Message type, provider.complete, tools.execute, instructions.load/render, get_logger, json, re, asyncio).

Key logic:
1. The mixin constructs compact payloads for pipeline traces by selecting a small set of keys for known sources like planning, completion_gate, or task_contract and otherwise including only primitive-valued entries.  
2. When emitting an LLM trace it collects basic metadata (model, message count, tool call count, usage) and formats the assistant response and any tool calls into a readable output, then records it via _emit_tool_output and as a session message.  
3. Long textual payloads destined for guard evaluation are truncated by _truncate_guard_text to a configurable maximum to avoid sending excessive content to guard models.  
4. Guard configuration is read from get_config(), where each guard type returns an enabled boolean and a normalized level that is either stop_suspicious or ask_for_approval.  
5. Outbound prompt messages are serialized into numbered lines with role and truncated content by _serialize_messages_for_guard to create an input guard payload.  
6. Guard classifier outputs are parsed by _parse_guard_decision which first attempts JSON parsing, then tries to extract a JSON object from surrounding text, and finally uses keyword heuristics to infer allow/deny when JSON is not available.  
7. _run_guard_decision composes system and user messages from instruction templates, truncates the content, calls provider.complete with those messages, accumulates usage into a provided turn_usage bucket, and returns the parsed decision including raw text.  
8. Enforcement via _enforce_guard checks whether the guard type is enabled and skips empty output checks, then evaluates the guard decision and either emits allow traces, requests human approval if configured, or emits suspicious traces and returns a block result.  
9. If a guard blocks and its level is ask_for_approval, the mixin calls the approval_callback and bases the final allow/deny on that callback while emitting the outcome.  
10. _complete_with_guards first runs the input guard on the serialized messages, then performs the provider.complete call if input is allowed, accumulates usage, runs the output guard on the LLM response, emits an LLM trace, and returns the response or raises GuardBlockedError on block.  
11. _execute_tool_with_guard JSON-encodes the tool invocation details, enforces the script_tool guard for the tool call, and upon allowance delegates to tools.execute while supplying session id, policies, abort events, workspace path, approval callback, and file registry.  
12. Throughout, usage accumulation and trace emission are used to record decisions and diagnostics, and GuardBlockedError is raised to communicate enforcement failures to callers.  
13. Error handling in guard evaluation returns conservative deny verdicts when provider calls fail or when parsing fails, ensuring safety by default.

---

## captain-claw-src/captain_claw/agent_pipeline_mixin.py

Description:
1. This module defines dataclasses and an AgentPipelineMixin that provide utilities for constructing and managing DAG-backed task pipelines.  
2. It includes a TaskStatus enum and helper functions to normalize statuses, parse ISO timestamps, and coerce various task configuration values like timeouts and tool policies.  
3. The mixin can sanitize and normalize arbitrary task contract input into a bounded DAG shape with unique task identifiers, validated execution contexts, and child relationships.  
4. It computes leaf tasks and builds a stable topological execution order that respects explicit dependencies and leaf priorities.  
5. Graph refresh and rollup functions propagate child states up to parents and maintain indexed collections such as task_graph, task_order, ready/blocked/active/completed/failed sets.  
6. Activation logic moves ready leaves into in-progress, enforces a configurable parallelism limit, and stamps tasks with start and heartbeat timestamps.  
7. Runtime ticking enforces per-task timeouts, applies retry policies, converts timed-out nodes to retried or failed states, and triggers downstream activations.  
8. Progress utilities compute per-leaf and per-scope ETA estimates, format human-readable monitor output, and build planning notes for model context injection.  
9. The mixin assembles a default pipeline from user input, optional overrides or extracted JSON contracts, and can append completion checks as final dependent tasks.  
10. It exposes helpers to set progress by index, advance tasks, cancel tasks with reasons, record token usage on active contexts, and finalize pipelines on success or failure.

Purpose:
This mixin centralizes pipeline and progress management for agents that plan and execute multi-step tasks. It exists to convert loosely-structured task contracts or free-text plans into a validated, DAG-shaped execution model with bounded size and consistent identifiers. By encapsulating normalization and sanitization logic, the mixin prevents malformed user input from breaking downstream executors and enforces sensible defaults for execution context and timeouts. The topological ordering and dependency expansion allow the agent to reason about which leaf tasks are eligible for execution and to schedule them deterministically. Runtime state refresh and rollup logic provide a single source of truth for task statuses, enabling monitoring, retries, and failure handling without scattering that logic across the codebase. Activation and concurrency controls ensure the agent can run multiple branches in parallel while respecting configured limits and tracking heartbeat/start times. Timeout/tick handling implements automated retry/backoff behavior and marks terminal failures consistently so higher-level controllers can react. Progress and ETA computation make pipeline state consumable by UIs or monitoring tools and support scope-aware reporting for nested task groups. The mixin also integrates with agent telemetry by emitting formatted monitor outputs and tool events, enabling observability of planning behavior. Utility functions for token usage accounting and compact progress snapshots aid in stuck detection and budget calculation for iterative turns. Overall, the mixin isolates complex pipeline semantics so agents can focus on task logic, tool integration, and policy enforcement while relying on consistent execution semantics.

Key elements:
- TaskStatus (enum) (defines supported lifecycle states like pending, ready, in_progress, completed, failed, cancelled, timed_out).  
- TERMINAL_TASK_STATUSES (set) (quick reference for terminal state checks).  
- TaskResult (dataclass) (structured payload for task outcomes).  
- ExecutionContext (dataclass) (per-task isolated context including token usage, spawn depth, and history).  
- TaskNode (dataclass) (node schema used for DAG-capable tasks, with children and execution context).  
- _normalize_task_status (static) (normalizes various inputs into a valid TaskStatus string).  
- _parse_pipeline_timestamp (static) (parses ISO timestamps and ensures UTC tzinfo).  
- _coerce_timeout_seconds (static) (coerces timeout values and enforces defaults).  
- _coerce_tool_policy (static) (validates/normalizes tool allow/deny policy structures).  
- _sanitize_pipeline_nodes (instance) (validates and normalizes incoming task lists into a bounded DAG).  
- _iter_pipeline_nodes / _iter_pipeline_leaves / _iter_pipeline_nodes_with_parent (static) (iterators for tree traversal).  
- _topological_task_order (static) (computes a stable topological order given leaves, dependencies and priorities).  
- _refresh_pipeline_graph_state / _refresh_pipeline_task_order (static) (rebuilds graph, dependencies, order, and ready/active/blocked sets).  
- _rollup_pipeline_status (static) (aggregates child statuses up to parents).  
- _activate_pipeline_tasks (instance) (moves ready tasks into in-progress honoring parallelism).  
- _tick_pipeline_runtime (instance) (enforces timeouts, retries, and computes activations/failures).  
- _build_task_pipeline (instance) (assembly of pipeline from free text, overrides, or extracted JSON; injects checks).  
- _build_pipeline_progress_details / _format_pipeline_monitor_output (static) (ETA and formatted monitor output).  
- _emit_pipeline_update (instance) (emits planning telemetry via self._emit_tool_output and self.instructions.load).  
- Integration touchpoints (self.session, self.instructions.load, self._emit_tool_output, self.planning_enabled) (depend on host agent environment).

Key logic:
1. Input normalization begins by coercing raw values—statuses, timestamps, timeouts and tool policy payloads—into predictable Python types and shapes so downstream code can assume consistency.  
2. Sanitization traverses user-supplied task trees depth-first, assigns unique alphanumeric ids, rejects nodes without titles, bounds total nodes, and constructs default execution contexts for each node.  
3. Leaf identification walks the normalized tree to produce leaf lists; a leaf priority map is derived from traversal order to bias topological sorting stability.  
4. Dependencies are expanded by walking parent chains and resolving referenced task ids; dependencies pointing to parent groups are translated to the corresponding descendant leaf ids.  
5. A topological order is produced using a Kahn-like approach: available (no-dependency) leaves are queued and popped in priority order, and dependents are released when all dependencies are satisfied; unresolved cycles fall back to appending remaining nodes deterministically.  
6. Refreshing the pipeline graph builds task_graph and task_dependencies structures, then classifies each leaf into completed/failed/active/ready/blocked sets by examining statuses and satisfaction of dependency completions.  
7. Rollup logic recursively computes parent node status from children, marking parents failed if any child failed/timed out, completed if all children completed, or in_progress/ready/blocked based on child mixes.  
8. Activation enforces a configurable max_parallel_branches limit, selects ready leaves in task_order order, marks them in_progress, records started_at and last_heartbeat_at, updates active lists, and triggers a subsequent graph refresh and status rollup.  
9. Runtime ticking iterates active tasks to check elapsed time against per-task timeout; on timeout it either retries (incrementing retries, clearing started_at, marking pending) or marks the task failed, and collects lists of timed_out, retried, and failed ids.  
10. After state changes from ticking or completion, the pipeline is refreshed, ready dependents are activated as slots permit, and pipeline state (including possible global failure) is updated.  
11. Utilities compute progress snapshots and detect meaningful progress by comparing tool successes, unique signatures, assistant outputs, and pipeline index transitions to help with stuck detection.  
12. Progress details calculate leaf indices, completed/ready/active counts, elapsed time since pipeline creation, and ETA by averaging seconds per completed leaf when possible; scope-level progress entries are produced by walking from root to current leaf.  
13. The mixin can advance a pipeline step-by-step by completing the current active task, creating a standardized result payload, activating ready dependents, and emitting a formatted planning event through agent telemetry hooks.  
14. Finalization either marks all tasks completed and emits a completed event or cancels/marks failed tasks, applies failure reasons, and emits a failed planning update so external orchestrators can react.

---

## captain-claw-src/captain_claw/agent_file_ops_mixin.py

Description:
1. This module implements AgentFileOpsMixin which provides utilities for extracting, synthesizing, writing, verifying, and executing script and file outputs produced by an assistant.  
2. It contains helpers to parse fenced code blocks from assistant text and infer appropriate script file extensions from language tags or shebangs.  
3. The mixin can wrap user-provided Python code in a structured-result wrapper that captures stdout and writes a JSON payload describing success/data/error.  
4. It constructs deterministic per-session paths for scripts and structured JSON result files using normalized session slugs and timestamps.  
5. The module synthesizes script content by calling the configured completion pipeline with a synthesis system prompt and falls back to a deterministic scaffold on failure.  
6. It implements logic to write files via an external "write" tool, then verify the file exists by checking a set of candidate filesystem locations and retrying when necessary.  
7. The mixin can auto-run scripts using appropriate runner commands (python/node/bash/ruby) and captures structured results produced by the wrapper or raw stdout.  
8. It extracts explicit requested write targets and filename blocks from assistant output, supports multi-file extraction, and can persist those file blocks automatically.  
9. Execution events and outputs are recorded back into the session via _add_session_message and tool outputs are emitted via _emit_tool_output.  
10. The mixin also persists assistant responses into session storage and triggers optional memory sync hooks.

Purpose:
1. The primary role of this mixin is to centralize and standardize file- and script-related operations an agent might need when responding to user requests that require producing, saving, or executing files.  
2. It exists to bridge model-generated textual outputs and concrete side effects on disk and execution environments, ensuring generated scripts can be saved, executed, and their results captured reliably.  
3. By inferring file extensions and building runner commands, the mixin enables consistent auto-execution behavior across multiple scripting languages while providing a safe structured-result protocol for Python.  
4. The structured-result wrapper ensures downstream systems can programmatically inspect script outcomes without brittle stdout parsing, improving robustness of automation workflows.  
5. The verification and retry mechanism around writing files protects against transient tool failures or mismatched write paths by scanning plausible candidate locations.  
6. The auto-write and auto-run flows allow the assistant to honor explicit user requests to save or execute code without requiring additional orchestration logic elsewhere in the agent.  
7. The mixin integrates with the agent’s session, tools, and execution guard mechanisms to enforce policies, record artifacts, and annotate execution context with result metadata.  
8. It also offers utilities for list-style task synthesis, generating a worker script prompt tailored to iterate over discovered list members and saving per-item outputs deterministically.  
9. The module reduces duplication by providing common path normalization, filename scaffolding, and parsing logic for filename-prefixed blocks that other agent components can rely upon.  
10. Logging and emitted tool outputs created here make debugging and monitoring script synthesis, write, and run actions straightforward in the broader system.  
11. The mixin’s APIs return structured dictionaries and annotate session messages so higher-level task orchestration code can interpret success/failure and evolve execution context.  
12. Overall, it exists to make file creation, verification, execution, and result ingestion predictable and auditable within the agent runtime.

Key elements:
- AgentFileOpsMixin (class - container for all file/script helpers).  
- _extract_code_block(text) (extracts the first fenced code block and language).  
- _infer_script_extension(language, code) (maps language/shebang to file extension).  
- _supported_script_extension(ext) (checks supported runner extensions).  
- _build_script_runner_command(script_path) (constructs runner command for non-python scripts).  
- _build_python_runner_command(script_path, result_path) (builds command using current Python interpreter).  
- _build_structured_result_wrapper(code) (wraps Python user code to emit structured JSON results).  
- _build_structured_result_path(script_path, session_slug) (deterministic result JSON path builder).  
- _read_structured_result_payload(path) (loads structured JSON result payload).  
- _build_script_relative_path(user_input, extension, session_slug) (creates per-session script relative paths).  
- _synthesize_script_content(user_input, turn_usage) (invokes LLM to create script code with fallback).  
- _run_python_worker_for_list_task(...) (synthesizes, writes, runs, and ingests a worker script for list tasks).  
- _write_file_with_verification(...) (executes write tool, verifies file presence across candidate paths, retry logic).  
- _maybe_auto_script_requested_output(...) (auto-writes and/or runs a script when explicitly requested).  
- _maybe_auto_write_requested_output(...) (auto-saves requested file outputs and multi-file blocks).  
- _extract_requested_write_paths(user_input) (parses requested target paths from user text).  
- _extract_named_file_blocks(output_text) (parses assistant "Filename:" blocks into (filename, content)).  
- _candidate_write_paths_for_verification(requested_path, parsed_written) (enumerates paths to check).  
- External dependencies/calls: Message (llm message wrapper), self._execute_tool_with_guard, self._complete_with_guards, self._add_session_message, self._emit_tool_output, self.tools.get_saved_base_path, self.session_manager.save_session, memory.schedule_background_sync, logging via get_logger.

Key logic:
1. The file parsing helpers first attempt to detect a fenced code block and return its language token and code body, falling back to None when absent.  
2. Script extension inference maps explicit language tags to extensions and inspects leading shebang lines to decide between Python, shell, JavaScript, and Ruby defaults.  
3. For Python code, the mixin can wrap arbitrary user code into a strict structured-result wrapper that executes the user code in a contained namespace, captures stdout, and writes a JSON payload to a result file path when provided.  
4. Script and result paths are deterministically built from a normalized session slug and a timestamp to avoid clashes and to scope artifacts per session.  
5. When synthesizing missing code the mixin issues a constrained LLM prompt (via _complete_with_guards) and extracts either a fenced code block or treats the entire response as code; if synthesis fails it emits a small deterministic scaffold.  
6. Writing a file is performed by invoking an external "write" tool through _execute_tool_with_guard, recording the tool output into the session, and parsing any returned path text for later verification.  
7. Verification enumerates candidate filesystem locations (absolute path, runtime base path, saved base path, and saved-prefix adjustments) and treats the first existing file as the verified result, with a configurable number of write attempts and retry emissions when missing.  
8. Auto-run flows decide whether to run scripts by checking whether the user explicitly requested a script action and whether prior write/run tool calls already occurred in the same turn; they construct appropriate runner commands depending on extension and may attach a structured result path for Python runs.  
9. After running a script, the mixin reads the structured JSON result if present and merges structured stdout or data into the shell tool output presentation so session messages contain both human-readable and machine-structured information.  
10. Execution context is updated with artifact lists, variables for output or error, and a recorded execution event that links task ids, script paths, and success status, allowing higher-level orchestrators to consume results.  
11. The module supports extracting multiple named file blocks from assistant output by locating "Filename:" headers, normalizing and deduplicating targets, and then saving each block using the same verified write logic.  
12. Auto-write behavior also honors explicit natural-language file requests parsed from the user prompt, attempting to save the assistant response itself when no inline file blocks were supplied and reporting summaries of saved vs failed files.  
13. Throughout the flows, all tool interactions are annotated into the session via _add_session_message and _emit_tool_output, while failures and exceptions are converted into user-facing notes or returned error structures for callers.  
14. Finally, assistant responses can be persisted into session storage and trigger optional background memory syncs, ensuring that created outputs and messages are durable within the broader agent runtime.

---

## captain-claw-src/captain_claw/session_export.py

Description:
1. This module provides utilities to export and render session history for Captain Claw.  
2. It normalizes session identifiers into filesystem-safe slugs.  
3. It can truncate long text fields to a maximum character length with an explicit truncation marker.  
4. It renders chat exports as Markdown including role, timestamp, and message content.  
5. It renders monitor/tool exports as Markdown including tool name, arguments, and content.  
6. It collects pipeline trace entries from tool messages and can fall back to other tool sources when explicit traces are absent.  
7. It serializes pipeline trace entries to newline-delimited JSON (JSONL).  
8. It produces a pipeline summary Markdown that aggregates counts by source, event, and step and produces a timeline.  
9. It writes selected export files to a structured directory path under a provided base path and timestamps filenames.  
10. Export functions create an isolated snapshot of messages before writing files to disk.  

Purpose:
1. The file exists to centralize logic for transforming internal session message records into human-readable and machine-friendly export artifacts.  
2. By providing dedicated renderers for chat, monitor, pipeline, and pipeline-summary outputs it keeps export formatting consistent across the application.  
3. Normalization and truncation helpers ensure exported filenames and content are safe and bounded for file systems and downstream consumers.  
4. Collecting pipeline trace entries allows other systems or analysts to ingest a concise sequence of pipeline events.  
5. The JSONL export is intended for programmatic consumption while the Markdown exports are optimized for human review and debugging.  
6. The module encapsulates fallback logic for pipeline traces so exports remain useful even when explicit pipeline_trace messages are not present.  
7. Timestamps and session metadata are embedded in every export header to provide context and ordering information.  
8. The export_session_history function coordinates which artifacts to produce and where to place them on disk, centralizing file IO behavior.  
9. Using a snapshot copy of messages before writing prevents accidental mutation of the source message list during export.  
10. The file's role is primarily utility-focused and stateless, making it safe to call from CLI commands, web handlers, or scheduled jobs.  
11. It depends only on simple data structures and datetime utilities to remain portable and testable.  
12. Overall it exists to make session data shareable, auditable, and analyzable outside the running application.  

Key elements:
- normalize_session_id (sanitizes a raw session id into a filesystem-safe slug).  
- truncate_history_text (limits message text to a maximum length and appends a truncation marker).  
- render_chat_export_markdown (renders chat messages to a Markdown document with headers and per-message sections).  
- render_monitor_export_markdown (renders 'tool' role messages to Markdown, including tool name and serialized arguments).  
- collect_pipeline_trace_entries (extracts pipeline_trace entries or falls back to specific tool sources and annotates payloads).  
- render_pipeline_export_jsonl (serializes collected pipeline entries into newline-delimited JSON).  
- render_pipeline_summary_markdown (aggregates counts, builds summary sections, and formats a timeline of pipeline entries).  
- export_session_history (coordinates export mode selection, directory creation, snapshotting messages, and writing files).  
- now_utc and to_utc_iso (timestamp helpers imported from captain_claw.cron used in export headers).  
- json (used for serializing tool arguments and pipeline entries).  
- pathlib.Path usage (creates directories and writes files with Path.mkdir and Path.write_text).  

Key logic:
1. normalize_session_id iterates characters of the input and builds a safe token that allows alphanumeric characters plus '.', '_', and '-', replacing all other characters with '-' then stripping surrounding hyphens and defaulting to "default" for empty results.  
2. truncate_history_text returns the original string when it is within the configured limit and otherwise truncates to max_chars, rstrips trailing whitespace, and appends "... [truncated]".  
3. render_chat_export_markdown filters messages to those whose role is one of user, assistant, or system, constructs a header with export timestamp, session id and name, and then writes each message as a numbered Markdown subsection containing role, timestamp, and content.  
4. When no chat messages are present the chat renderer emits a short placeholder indicating none were found.  
5. render_monitor_export_markdown filters messages to role "tool", attempts to JSON-serialize tool argument dicts (falling back to str on failure), and includes tool name, argument JSON, timestamp, and content for each entry.  
6. collect_pipeline_trace_entries first selects tool messages whose tool_name equals "pipeline_trace" (case-insensitive) and converts their tool_arguments into payload dictionaries augmented with seq, timestamp, session_id, and session_name.  
7. If no explicit pipeline_trace entries are found the collector scans tool messages for fallback sources ("planning", "task_contract", "completion_gate"), annotates the payload with a source field, and includes them in the returned entries.  
8. render_pipeline_export_jsonl simply joins JSON-serialized entries with newlines to produce a JSONL-formatted string suitable for programmatic consumption.  
9. render_pipeline_summary_markdown computes aggregates by source, step, and event, determines first and last timestamps, sorts aggregated lists by frequency and name, and emits sections for sources, planning events, completion/contract steps, and a timeline.  
10. The timeline formatting iterates entries and composes a concise single-line description per entry that may include seq, timestamp, source, event, step, progress (leaf_index/leaf_tasks), remaining count, current path, and eta text when those fields are present.  
11. export_session_history validates the requested mode against allowed keys, normalizes the session id for filesystem use, creates an export directory under saved_base_path/showcase/<safe_session>/exports, and snapshots messages into a shallow-copied list before rendering.  
12. Based on the mode it invokes the appropriate renderers to produce chat, monitor, pipeline (JSONL), and pipeline-summary Markdown files named with a timestamp stamp and writes them with Path.write_text, collecting and returning the list of written Paths.

---

## captain-claw-src/captain_claw/instructions.py

Description:
1. This module provides utilities to load and render LLM instruction templates from disk.  
2. It implements a two-layer override system where personal templates in a user directory take precedence over system defaults.  
3. A module-level default personal directory (~/.captain-claw/instructions) is defined and expanded to an absolute Path.  
4. The _SafeFormatDict helper class ensures that unknown format placeholders are left unchanged instead of raising KeyError.  
5. The InstructionLoader class encapsulates resolution of base and personal directories, caching, and file lookup logic.  
6. InstructionLoader._resolve_base_dir determines the system instructions directory from an explicit argument, an environment variable, or a package-relative default.  
7. The loader prefers a personal override file when returning the effective path for a named template.  
8. Loading a template reads the file text, strips surrounding whitespace, caches the content, and raises FileNotFoundError if the file does not exist.  
9. Rendering a template substitutes provided variables using str.format semantics while preserving unknown placeholders.  
10. The module is written to be simple, filesystem-driven, and to avoid altering system defaults when personal edits are made (e.g., via a web UI).

Purpose:
1. The file exists to centralize safe and predictable loading and rendering of instruction templates used by the application.  
2. It provides an explicit override mechanism so users can customize instructions locally without changing bundled defaults.  
3. By resolving base directories from arguments, an environment variable, or a package default it supports flexible deployment and developer workflows.  
4. The caching behavior reduces repeated disk reads for frequently used templates, improving performance.  
5. The SafeFormatDict approach prevents rendering failures when callers omit optional variables, making template usage more robust.  
6. Raising FileNotFoundError with a clear message informs callers when a requested template is missing and suggests where to place files.  
7. The loader preserves the original system templates intact by design, ensuring that automated updates or packaged defaults are not overwritten.  
8. Its responsibilities are limited to filesystem resolution, text loading, simple placeholder substitution, and override detection.  
9. The class-level API (is_overridden, load, render) offers a small surface for other parts of the project to reliably obtain instruction text.  
10. Support for CAPTAIN_CLAW_INSTRUCTIONS_DIR via environment variable allows CI, tests, or deployments to point to alternative instruction sets.  
11. The module intentionally avoids a complex templating engine to keep rendering behavior predictable and easy to inspect.  
12. Overall, it exists to make instruction templates discoverable, editable by users, and safe to render into LLM prompts.

Key elements:
- _PERSONAL_DIR (Path default for per-user instruction overrides).  
- _SafeFormatDict (dict subclass with __missing__ to return "{key}" for unknown placeholders).  
- InstructionLoader (main class encapsulating template discovery and rendering).  
- InstructionLoader.__init__ (initializes base_dir, personal_dir, and in-memory cache).  
- InstructionLoader._resolve_base_dir (static method to choose base instructions directory via arg, env var, or package default).  
- InstructionLoader._path (returns effective Path for a template, preferring personal override).  
- InstructionLoader.is_overridden (checks existence of a personal override file).  
- InstructionLoader.load (reads, strips, caches template content, raises FileNotFoundError if absent).  
- InstructionLoader.render (performs str.format_map substitution using _SafeFormatDict).  
- CAPTAIN_CLAW_INSTRUCTIONS_DIR (environment variable consulted when resolving base directory).  
- Path.read_text (used to read template file contents).

Key logic:
1. On instantiation the loader determines its base directory by checking an explicit argument first, then the CAPTAIN_CLAW_INSTRUCTIONS_DIR environment variable, and finally falling back to a package-relative instructions directory.  
2. The personal directory is resolved to an absolute path either from an explicit argument or the module-level default (~/.captain-claw/instructions).  
3. The loader maintains a simple in-memory cache keyed by template name to avoid repeated filesystem reads.  
4. When asked for a template path, the loader constructs the candidate personal file and returns it if it exists; otherwise it returns the corresponding file from the resolved base directory.  
5. is_overridden is a thin convenience that tests for the presence of a personal override file.  
6. load checks the cache and returns cached content when available, otherwise it determines the effective path and verifies the file exists.  
7. If the file does not exist load raises FileNotFoundError with a message that indicates where to add the missing template.  
8. When reading a template file, load uses Path.read_text with UTF-8 and strips surrounding whitespace before caching the result.  
9. render obtains the template via load, converts provided substitution variables to strings, and calls str.format_map with a _SafeFormatDict to perform placeholder substitution.  
10. _SafeFormatDict.__missing__ ensures that any placeholder without a provided value remains in the output wrapped by braces, preventing exceptions.  
11. This design makes rendering tolerant to missing variables while still allowing explicit substitutions to be expanded.  
12. The overall control flow is straightforward: resolve directories at init, prefer personal files at lookup, cache loaded contents, and render with safe placeholder handling.

---

## captain-claw-src/captain_claw/onboarding.py

Description:
1. This module implements an interactive onboarding workflow for first-time Captain Claw setup.  
2. It provides utilities to decide whether onboarding should run and to persist a completion marker.  
3. The module uses a JSON state file to record completion and reads/writes it under a ~/.captain-claw directory by default.  
4. It inspects local and global configuration files to avoid running onboarding when configuration already exists.  
5. A terminal-based wizard built with rich prompts the user to select config destination, model provider, model id, API keys, provider base URL, workspace path, safety guard settings, web search API key, and Telegram integration.  
6. Provider selection includes normalization and aliasing for common names and a default provider order and suggested models are presented.  
7. The wizard loads and saves a Config object from/to YAML and updates fields such as model provider, model id, API key, base URL, workspace, tools, telegram and guard settings.  
8. It supports storing sensitive tokens conditionally in the config file or leaving them to environment variables.  
9. Non-interactive terminals are handled by skipping or raising an error when interactive mode is required.  
10. At the end the wizard persists the configuration and marks onboarding as completed, printing a summary panel to the console.  

Purpose:
1. The file exists to guide users through initial setup of Captain Claw in a discoverable and consistent manner.  
2. It centralizes logic for deciding when onboarding should run so first-time and automated installs behave correctly.  
3. By detecting existing local or global configuration and a persisted onboarding marker it avoids redundant prompts.  
4. The interactive wizard ensures key runtime settings are captured in a user-editable YAML config file or left to environment variables as desired.  
5. Using the rich library the module presents tables, prompts, confirmations and summary panels for a user-friendly terminal experience.  
6. Provider normalization and defaults make it easier for users to choose a model provider without memorizing exact provider identifiers.  
7. The module encapsulates decisions about where to save configuration (global vs workspace) to fit different usage patterns.  
8. It also handles optional integrations like Brave Search and Telegram, letting users decide whether to store tokens in config or keep them in environment variables.  
9. Persisting onboarding completion avoids repeating the wizard and allows non-interactive environments to skip onboarding automatically.  
10. The code updates Config fields and writes YAML using Config.save to ensure settings are applied consistently with the rest of the application.  
11. The module is designed to be safe with secrets by prompting for password input and providing opt-out choices for storing credentials.  
12. Overall it provides a reproducible, interactive entrypoint for initial configuration and reduces friction for new users to get the application running.  

Key elements:
- _ONBOARDING_STATE_FILENAME (string constant; name of JSON file used to record onboarding completion)  
- _PROVIDER_ORDER (tuple; ordered list of supported providers)  
- _PROVIDER_LABELS (dict; human-readable labels for providers)  
- _PROVIDER_DEFAULT_MODELS (dict; suggested default model ids per provider)  
- _PROVIDER_ALIASES (dict; simple aliases mapping common names to canonical provider keys)  
- _resolve_state_path(state_path) (function; resolves and expands the path to the onboarding state file)  
- _resolve_global_config_path(global_config_path) (function; resolves global/default config path)  
- is_onboarding_completed(state_path) (function; checks and parses state JSON to determine completion)  
- mark_onboarding_completed(state_path) (function; writes completion payload with timestamp to state file)  
- has_existing_configuration(cwd, global_config_path) (function; checks for local or global config files)  
- should_run_onboarding(...) (function; central decision function combining flags and existence checks)  
- can_run_onboarding_interactively() (function; checks tty interactivity)  
- _normalize_provider(provider) (function; normalizes provider names and applies aliases)  
- _select_config_path(console, config_path) (function; interactive choice between global and local config paths)  
- _select_provider(console, current_provider) (function; interactive provider selection with suggested models)  
- run_onboarding_wizard(config_path, state_path, require_interactive) (function; main interactive wizard integrating all prompts and saving)  
- External dependencies: rich (Console, Panel, Prompt, Confirm, Table), captain_claw.config.Config, DEFAULT_CONFIG_PATH, LOCAL_CONFIG_FILENAME, json, datetime.UTC.  

Key logic:
1. Path resolution helpers first expand provided path arguments or fall back to default locations: the onboarding state file in ~/.captain-claw and the global config via DEFAULT_CONFIG_PATH.  
2. is_onboarding_completed loads the state JSON if present and returns True only when the payload contains a truthy "completed" key, guarding against read/parse errors.  
3. mark_onboarding_completed creates the parent directory as needed and writes a JSON payload containing a completed flag and an ISO8601 UTC timestamp.  
4. has_existing_configuration checks both the current working directory for a local config filename and the resolved global config path to determine pre-existing setup.  
5. should_run_onboarding combines explicit force, the onboarding state marker, an explicitly provided config_path existence, and presence of existing configuration to decide whether to run.  
6. can_run_onboarding_interactively uses sys.stdin.isatty and sys.stdout.isatty to ensure the wizard only runs in terminals, and callers may choose to raise if interactivity is required.  
7. Provider normalization maps aliases and lowercases input, defaulting to "openai" if an unrecognized provider is given; provider ordering and default models are used to set sensible defaults in prompts.  
8. _select_config_path constructs a two-row Table presenting global and local config destinations, computes a default option based on which paths already exist, and prompts the user to choose where to save configuration.  
9. _select_provider similarly shows provider options with labels and suggested model names, computes the default selection based on the current configured provider, and returns the selected canonical provider key.  
10. run_onboarding_wizard orchestrates the interactive flow: it checks interactivity, prints an intro Panel, selects the target config path, loads Config.from_yaml, then prompts for provider, model name, API key storage, base URL, workspace path, safety guards, Brave Search key, and Telegram configuration.  
11. The wizard conditionally prompts for sensitive values (API keys, Telegram token) using password-style Prompt when the user opts to store them, otherwise it leaves those fields blank to encourage environment variable usage.  
12. User responses are summarized in a Table; the wizard requires confirmation before applying changes and will abort without saving if the user declines.  
13. When saving, the code updates the Config object fields (model, workspace, tools, telegram, guards) according to collected answers, toggling guard enablement and levels based on the user's choice, then calls cfg.save to persist YAML.  
14. After persisting configuration, the wizard marks onboarding completed via mark_onboarding_completed, prints a completion Panel, and returns the path to the saved configuration or None if the user skipped saving.

---

## captain-claw-src/captain_claw/cron.py

Description:
1. This module provides utilities for parsing simple cron-like schedule expressions and for computing upcoming run times.  
2. It defines a mapping for weekday name variants to numeric weekday indices.  
3. It supplies helpers to obtain the current UTC time and to serialize/parse ISO datetimes with timezone normalization.  
4. A private helper parses HH:MM strings and validates their format using a regular expression.  
5. The parse_schedule_tokens function accepts tokenized schedule arguments and returns a normalized schedule dict plus how many tokens were consumed.  
6. Supported schedule forms are interval-based ("every <Nm|Nh>"), daily ("daily HH:MM"), and weekly ("weekly <day> HH:MM").  
7. The schedule_to_text function converts a schedule dict back into a compact human-readable string.  
8. The compute_next_run function computes the next UTC datetime for a given schedule, handling intervals, daily, and weekly schedules.  
9. The module consistently works with timezone-aware UTC datetimes and adjusts naive ISO inputs to UTC.  
10. It raises ValueError on invalid input formats or unsupported schedule types.

Purpose:
1. The file exists to centralize simple scheduling logic used by other parts of the project that need to run tasks on a regular cadence.  
2. It provides a small, self-contained parser so callers can accept human-friendly schedule specifications and turn them into machine-readable schedule dictionaries.  
3. By offering conversion to and from text, it supports both user-facing display and internal computation without duplicating formatting logic.  
4. The timezone-aware helpers ensure that schedules and computed run times are consistently treated in UTC, reducing ambiguity across environments.  
5. Validation and clear error messages prevent malformed schedules from propagating further into scheduling logic.  
6. The weekly weekday normalization accepts many common textual forms (e.g., "mon", "monday", "tues") to improve usability.  
7. Interval schedules allow simple repeating tasks specified in minutes or hours without needing a full cron expression parser.  
8. Daily and weekly schedules cover common scheduling needs for tasks that should run at specific times of day or on specific weekdays.  
9. The compute_next_run implementation handles edge cases like scheduling a time that has already passed today by advancing to the next valid occurrence.  
10. Keeping parsing, formatting, and next-run computation together makes it straightforward for callers to validate user input, show it back to users, and schedule execution.  
11. The module intentionally remains small and dependency-free (beyond the standard library) so it can be embedded or reused in different runtime contexts.  
12. Errors are expressed with exceptions to let calling code decide how to report or recover from invalid schedules.

Key elements:
- WEEKDAY_MAP (dict mapping many weekday name variants to weekday integers).  
- now_utc() (returns timezone-aware current UTC datetime).  
- to_utc_iso(value: datetime) (serializes a datetime to an ISO string in UTC).  
- parse_iso(value: str) (parses ISO datetime strings and normalizes to UTC, makes naive datetimes UTC-aware).  
- _parse_hhmm(text: str) (private helper that validates and parses "HH:MM" strings via regex).  
- parse_schedule_tokens(tokens: list[str]) -> (dict, int) (parses tokenized schedule input and returns schedule dict and tokens consumed).  
- schedule_to_text(schedule: dict) -> str (renders schedule dict to compact human-readable text like "every 15m" or "daily 09:00").  
- compute_next_run(schedule: dict, now: datetime | None) -> datetime (calculates the next run time in UTC for the given schedule).  
- re.fullmatch (regular expression use in time parsing and interval token validation).  
- datetime, timedelta, UTC (standard library datetime utilities used throughout).

Key logic:
1. The module normalizes time handling around UTC: now_utc returns a timezone-aware current instant and parse_iso guarantees parsed values are UTC-aware.  
2. _parse_hhmm uses a regular expression to strictly enforce hours between 0–23 and minutes between 00–59, raising ValueError on mismatch.  
3. parse_schedule_tokens inspects the first token to determine schedule type, supporting "every", "daily", and "weekly" branches; it raises informative ValueError messages for incorrect usage.  
4. For "every" schedules it expects a numeric interval followed by a unit character ('m' or 'h'), converts the numeric part to an integer, enforces interval > 0, and returns a dict with type "interval" and unit normalized to "minutes" or "hours".  
5. For "daily" schedules it parses a single HH:MM argument and returns a dict containing hour and minute.  
6. For "weekly" schedules it validates the weekday token against WEEKDAY_MAP, parses the HH:MM time, and stores both a numeric weekday and a three-letter day string.  
7. schedule_to_text inspects the schedule type and formats it back to a compact textual representation, choosing "m" or "h" suffixes for intervals and zero-padded HH:MM for daily/weekly entries.  
8. compute_next_run handles each schedule type distinctly: interval simply adds a timedelta based on minutes or hours to the current time.  
9. For daily schedules compute_next_run constructs a candidate datetime by replacing the current date's hour/minute and, if the candidate is earlier than or equal to the current time, advances it by one day.  
10. For weekly schedules it computes days_ahead with modulo arithmetic ((target_day - current.weekday()) % 7), builds a candidate by adding that many days and replacing hour/minute, and if the candidate is not strictly after current it advances by 7 days.  
11. All computed candidates are timezone-aware UTC datetimes; microseconds and seconds are zeroed when building candidate times to provide precise scheduling semantics.  
12. Unknown schedule types in parse_schedule_tokens or compute_next_run result in ValueError to ensure callers handle unsupported formats explicitly.

---

## captain-claw-src/captain_claw/runtime_context.py

Description:
1. This module defines shared mutable runtime state used by the interactive session components.  
2. It declares a PlatformState dataclass that groups per-platform bridge, user, and task metadata.  
3. It declares a RuntimeContext dataclass that aggregates the global agent, UI, command and followup queues, cron tracking, and per-platform PlatformState instances.  
4. RuntimeContext provides default factory values for command and followup queue managers and for three platform state instances (telegram, slack, discord).  
5. Each PlatformState contains fields for bridge objects, polling tasks, approval/pairing dictionaries, configuration, and enablement state.  
6. The file imports Agent and TerminalUI type hints and relies on CommandQueueManager and FollowupQueueManager for queue defaults.  
7. It initializes a telegram_command_specs list containing tuples of command names and help text used for Telegram integration.  
8. RuntimeContext exposes a get_platform_state method that returns the PlatformState for a given platform name and raises on unknown names.  
9. It also exposes a platform_names method that returns the list of supported platform names.  
10. The module is focused on in-memory structures and contains no I/O operations or network interactions itself.

Purpose:
1. The file exists to centralize and share mutable runtime state across modules that implement the interactive session and multi-platform bridges.  
2. By packaging state into dataclasses, it makes it easier to pass a single context object through different modules without relying on numerous global variables.  
3. The PlatformState dataclass isolates per-platform concerns like approved users, pending pairings, polling tasks, and platform-specific offsets and configuration.  
4. The RuntimeContext includes typed references to the core agent and terminal UI so modules can interact with those primary components consistently.  
5. Providing default factories for CommandQueueManager and FollowupQueueManager ensures queue instances are available wherever a context is instantiated.  
6. The predefined telegram_command_specs supplies a canonical set of Telegram command names and descriptions that multiple modules can reference for registration or help text generation.  
7. Centralizing cron-related fields (running job ids, poll interval, and last execution tracking) gives a common place to coordinate scheduled work across the application.  
8. The explicit mapping method get_platform_state enforces valid platform names and provides a single lookup point for platform-specific state.  
9. Returning a fixed platform_names list documents the supported platforms and can be used by UI or registration flows to enumerate available backends.  
10. The dataclass-based approach also simplifies serialization or snapshotting of runtime state if other modules implement persistence.  
11. The module separates structural state concerns from behavioral implementations such as bridges or queue processing, keeping responsibilities clear.  
12. Overall, the file provides a lightweight, type-annotated contract for how runtime components should access and mutate shared session state.

Key elements:
- PlatformState (dataclass grouping per-platform fields like bridge, poll_task, approved_users, pending_pairings, offsets, config).  
- RuntimeContext (dataclass aggregating agent, ui, command_queue, followup_queue, cron fields, and per-platform states).  
- telegram_command_specs (list of (command, description) tuples used for Telegram commands).  
- get_platform_state(platform: str) (method returning the matching PlatformState or raising ValueError).  
- platform_names() (method returning ["telegram", "slack", "discord"]).  
- CommandQueueManager (imported dependency used as default factory for command_queue).  
- FollowupQueueManager (imported dependency used as default factory for followup_queue).  
- Agent, TerminalUI (imported types referenced in the RuntimeContext signature).  
- asyncio.Task typing usage (poll_task typed as asyncio.Task or None).

Key logic:
1. The module's core logic is organizing runtime values into two dataclasses so that other modules receive a single context object containing all shared mutable state.  
2. PlatformState defaults create containers for bridge references, task handles, approval and pairing dictionaries, and platform keys without performing initialization beyond empty values.  
3. RuntimeContext constructs command and followup queue manager instances via default_factory, ensuring those queues exist whenever a context is created.  
4. The per-platform fields (telegram, slack, discord) are each initialized by a lambda default_factory that sets platform-specific name and persistent state keys.  
5. The telegram_command_specs list is created at module initialization and serves as a static reference for command names and help text rather than being computed at runtime.  
6. get_platform_state implements a simple mapping from the platform string to the corresponding PlatformState attribute and raises ValueError for unknown names, enforcing valid usage.  
7. platform_names returns a hard-coded list of supported platforms, providing a stable enumeration used by other code paths.  
8. Cron-related fields in RuntimeContext (cron_running_job_ids, cron_poll_seconds, last_exec_seconds, last_completed_at) are stored for coordination but are not manipulated in this file.  
9. The module uses type annotations to document expected object types (Agent, TerminalUI, asyncio.Task) without performing type enforcement at runtime.  
10. Default values for fields such as approved_users and pending_pairings use field(default_factory=...) to ensure separate mutable containers per context instance.  
11. No asynchronous logic or background task control is implemented here; poll_task fields are placeholders for tasks started and managed elsewhere.  
12. The design favors explicit, minimal behavior in this file: it provides state containers and simple accessors while delegating operational logic to other modules.

---

## captain-claw-src/captain_claw/orchestrator_cli.py

Description:
1. This module implements a headless orchestrator runner intended for CLI, cron, and programmatic invocation.  
2. It defines utility functions to print status updates and broadcast events to stderr for monitoring.  
3. The core async function run_orchestrator_headless prepares configuration, initializes an Agent, and constructs a SessionOrchestrator.  
4. The function supports running either a named saved workflow or an ad-hoc prompt, with optional model, provider, and parallelism overrides.  
5. It ensures workspace and session directories exist before execution and applies configuration overrides when provided.  
6. The module collects execution results into a structured dictionary containing ok, result, workflow_name, output_path, and error fields.  
7. It handles workflow loading, execution, and orchestration synthesis, and ensures orchestrator shutdown in a finally block.  
8. A synchronous CLI entrypoint cli_orchestrate is provided to parse arguments, configure logging, and invoke the async runner.  
9. An auxiliary async function _list_workflows_cli lists saved workflows and prints a simple table for the --list flag.  
10. When executed as a script, the module runs the CLI entrypoint to support command-line usage of the headless orchestrator.

Purpose:
1. The file exists to provide a lightweight, non-interactive way to run Captain Claw orchestrations outside of the web server or TUI.  
2. It enables scheduled or automated execution patterns such as cron jobs and CI tasks by exposing a stable CLI and a programmatic async API.  
3. The module centralizes startup concerns for headless runs, including loading and applying configuration, ensuring workspace directories, and configuring logging.  
4. It ties together higher-level components by creating and initializing an Agent for LLM interactions and a SessionOrchestrator for task orchestration.  
5. The design allows overriding model and provider settings, and adjusting parallel execution parameters without changing persistent configuration files.  
6. The module provides status and broadcast callbacks so that runtime events and task progress can be observed in stderr or suppressed for quiet operation.  
7. It returns structured results suitable for consumption by scripts or other programs, including JSON output when requested.  
8. Error handling and finalization logic ensure orchestrator.shutdown is always attempted, reducing resource leaks and leaving persistent state consistent.  
9. The CLI surface includes utility modes such as listing saved workflows, making it practical for operators to inspect available automations.  
10. By exposing both an asyncio-friendly function and a simple CLI wrapper, the file supports integration into other Python codebases or shell-based automation.  
11. The module limits its responsibilities to orchestration setup and invocation, delegating decomposition, execution, and persistence to Agent and SessionOrchestrator components.  
12. It exists to make headless orchestration accessible and scriptable while preserving the same orchestration semantics used in interactive modes.

Key elements:
- _print_status (function) (writes formatted status lines to stderr).  
- _print_event (function) (formats and writes broadcast event details to stderr).  
- run_orchestrator_headless (async function) (main headless orchestration runner; accepts workflow_name, prompt, config and overrides).  
- cli_orchestrate (function) (argparse-based CLI entrypoint that parses flags and invokes the async runner).  
- _list_workflows_cli (async function) (lists saved workflows and prints a simple table).  
- Config (captain_claw.config.Config) (used via Config.from_yaml and Config.load to obtain configuration).  
- set_config (function) (applies the loaded configuration globally).  
- Agent (captain_claw.agent.Agent) (instantiated and initialized to provide LLM provider and synthesis/decomposition).  
- SessionOrchestrator (captain_claw.session_orchestrator.SessionOrchestrator) (created to load and execute workflows or orchestrate prompts).  
- configure_logging and get_logger (captain_claw.logging) (used to configure and obtain a module logger).  
- asyncio.run, json.dumps, argparse, and sys.stderr (standard library utilities used for execution, output formatting, CLI parsing, and error reporting).  
- Orchestrator interactions: load_workflow, execute, orchestrate, list_workflows, and shutdown (methods invoked on SessionOrchestrator).

Key logic:
1. The module first validates inputs for the headless runner, ensuring either a workflow name or an ad-hoc prompt is provided.  
2. It loads configuration either from a provided YAML path or the default Config.load, and applies model/provider overrides if specified.  
3. The resolved workspace path and the session file parent directories are created to guarantee necessary filesystem state prior to execution.  
4. Status and broadcast callbacks are chosen based on the quiet flag; when not quiet, they point to functions that emit structured stderr messages.  
5. An Agent instance is constructed with the status callback and awaited for initialization so that provider information and LLM capabilities are ready.  
6. A SessionOrchestrator is created using configuration values (max_parallel, max_agents) and the agent's provider, and is configured with the same callbacks for status and broadcasts.  
7. The runner prepares a result_data dictionary to capture outcome metadata and uses try/except/finally to manage execution and cleanup.  
8. If a workflow_name is given, the orchestrator.load_workflow method is invoked and its success verified; failure short-circuits and returns an error result.  
9. For a loaded workflow, orchestrator.execute is awaited to perform the task execution and produce a synthesis string stored in result_data.  
10. For an ad-hoc prompt, orchestrator.orchestrate is called to both decompose and execute the prompt and produce synthesis output, with the orchestrator keeping track of an internal workflow name.  
11. Any exceptions raised during orchestration are logged via the module logger and their messages are placed into the result_data error field.  
12. The finally block always calls orchestrator.shutdown to ensure agents and worker tasks are cleaned up before returning.  
13. The synchronous CLI wrapper builds an argparse parser with a mutually exclusive group for workflow vs prompt and accepts flags for config, model, provider, parallelism, quiet, JSON output, and listing workflows.  
14. When invoked with --list, the CLI runs _list_workflows_cli which loads configuration, ensures workspace directories exist, constructs a SessionOrchestrator, and prints a table of saved workflows returned by list_workflows.  
15. Otherwise the CLI runs the async runner via asyncio.run, then either prints the raw synthesis result, outputs JSON when requested, or writes an error to stderr and exits with a non-zero status on failure.

---

## captain-claw-src/captain_claw/__init__.py

Description:
1. This module serves as the package initializer for the captain_claw package.  
2. It provides a short module docstring identifying the package.  
3. It defines a __version__ variable with the value "0.1.0".  
4. It defines an __author__ variable naming the package author.  
5. It imports Config from the captain_claw.config submodule.  
6. It imports main from the captain_claw.main submodule.  
7. It defines an __all__ list that explicitly exports Config, main, and __version__.  
8. The module does not define additional functions or classes.  
9. Its top-level code executes those imports when the package is imported.  
10. Overall, it centralizes a small set of public names and package metadata.

Purpose:
1. The file exists to establish the public API and basic metadata for the captain_claw package.  
2. By importing and re-exporting Config and main here, it allows consumers to access those names directly from the package root.  
3. Exposing __version__ at package level makes it easy for other code to check the package version.  
4. The module docstring and __author__ provide lightweight documentation about the package identity.  
5. Defining __all__ controls what is imported when users perform from captain_claw import *.  
6. Centralizing these exports reduces the need for consumers to import deeply from submodules.  
7. The file keeps the package surface minimal and intentional by only exposing specific symbols.  
8. It also ensures that importing the package triggers import of the referenced submodules, which may perform their own initialization.  
9. This behavior makes the root package a convenient entry point for code that relies on Config or main.  
10. The initializer is typically small and stable, so it changes infrequently compared to submodules.  
11. Placing metadata like __version__ here supports packaging tools and runtime introspection.  
12. Overall, the file exists to simplify access to core components and to provide basic package-level metadata.

Key elements:
- Module docstring (package description string).  
- __version__ (string constant "0.1.0").  
- __author__ (string constant with the author's name).  
- Config (re-exported symbol imported from captain_claw.config).  
- main (re-exported symbol imported from captain_claw.main).  
- __all__ (list controlling exported names for from ... import *).  
- Top-level import dependencies (captain_claw.config, captain_claw.main).

Key logic:
1. On import, the module-level docstring is available as package documentation.  
2. The assignment of __version__ and __author__ stores package metadata as module attributes.  
3. The from captain_claw.config import Config statement imports the Config symbol from the submodule and binds it in this module's namespace.  
4. The from captain_claw.main import main statement similarly imports main and binds it.  
5. These import statements execute at import time, causing the referenced submodules to be imported and initialized.  
6. The __all__ list is defined to explicitly list the public names that should be exported on from captain_claw import *.  
7. No functions or classes are defined here, so the module's runtime behavior is limited to these assignments and imports.  
8. Consumers importing Config or main from the package root will trigger these bindings without importing the submodules directly.  
9. Because the module re-exports names, it acts as an indirection layer between callers and the actual implementation modules.  
10. The file performs no error handling or conditional logic around the imports; import failures will propagate to the importer.  
11. Because it performs imports at top level, it should remain minimal to avoid heavy side effects during package import.  
12. Overall, the control flow is straightforward: evaluate docstring, assign metadata, import and bind exported names, and set the __all__ sequence.

---

## captain-claw-src/captain_claw/agent_model_mixin.py

Description:
1. This mixin provides runtime model resolution and session model selection helpers for an Agent class.  
2. It normalizes provider keys and maps common aliases to canonical provider names.  
3. It refreshes and stores runtime model details such as provider, model, temperature, max_tokens, base_url, source, and id.  
4. It exposes a method to retrieve a copy of the current runtime model details for UI or status display.  
5. It builds an allowlist of models from configuration with a fallback to the configured default model.  
6. It resolves a user-supplied selector to an allowed model by id, numeric index, or provider:model patterns.  
7. It applies a selected model option by instantiating a provider via create_provider and switching the global provider with set_provider.  
8. It reads and writes session metadata to persist session-specific model selections and includes timestamps for updates.  
9. It prevents leaking a default-configured base_url into a differently selected provider when applying a session option.  
10. It exposes an asynchronous method to set the session model, handle persistence, and return success/error messages.  

Purpose:
1. The file centralizes logic for choosing and activating LLM models at runtime for agents that can use different providers and model configurations.  
2. It exists to bridge static configuration (cfg.model) and dynamic session-level overrides, enabling per-session model selection.  
3. By normalizing provider keys and mapping aliases, it makes user input and config entries tolerant to common provider names.  
4. The mixin encapsulates the rules for constructing the allowed model list and for falling back to a default configuration when no allowlist is present.  
5. It provides deterministic resolution of selectors by id, index, or provider/model patterns so user commands can select models reliably.  
6. Applying a model option is centralized here to ensure consistent construction of provider instances with resolved temperature, max_tokens, and context size.  
7. The code contains safeguards around base_url handling to avoid accidentally reusing a default provider's base_url for other providers.  
8. Session metadata handling and optional persistence via a session manager allow selections to survive across restarts or be scoped to sessions.  
9. Exposing runtime model details supports status reporting and user feedback after changes are applied.  
10. Error handling in model activation is localized so callers receive clear messages when instantiation or switching fails.  
11. The mixin keeps provider creation and global provider switching responsibilities separate by delegating to create_provider and set_provider.  
12. Overall, it exists to make model selection robust, auditable, and easy to integrate into agent command workflows.  

Key elements:
- AgentModelMixin class (mixin providing model selection behavior)  
- _normalize_provider_key(provider) (maps aliases like "chatgpt" → "openai")  
- _refresh_runtime_model_details(source, model_id) (populates self._runtime_model_details from provider or config)  
- get_runtime_model_details() (returns copy of runtime model details)  
- get_allowed_models() (builds allowlist from cfg.model.allowed with fallback to cfg.model)  
- _resolve_allowed_model(selector) (resolves selector by id, #index, provider:model or model name)  
- _apply_model_option(option, source, model_id) (creates provider instance and switches runtime provider)  
- _session_model_selection() (reads model_selection from self.session.metadata if present)  
- _apply_default_config_model_if_needed() (applies configured default model unless an override is present)  
- set_session_model(selector, persist=True) (async; applies selection, updates session metadata, persists via session_manager)  
- get_config (external call to retrieve configuration)  
- create_provider (external call to instantiate provider)  
- set_provider (external call to set global provider)  
- self.provider, self.session, self.session_manager, self._provider_override, self._runtime_model_details (notable instance attributes used)  
- datetime.now(UTC).isoformat() (used to timestamp session metadata updates)  

Key logic:
1. The mixin begins by normalizing incoming provider names through a small aliases dictionary to map common names to canonical provider keys.  
2. Runtime model details are constructed by preferring runtime provider attributes when available and falling back to values from get_config, then stored in self._runtime_model_details.  
3. get_allowed_models iterates over cfg.model.allowed entries, extracts or derives id, provider, model, base_url, temperature, and max_tokens, and skips entries missing provider or model.  
4. If the configured allowlist yields no valid options, get_allowed_models returns a single default entry derived directly from cfg.model values.  
5. _resolve_allowed_model attempts multiple matching strategies: exact id match, numeric index when using a leading '#', and pattern/substring matching for provider:model, provider/model, or just the model name.  
6. When applying an option, _apply_model_option normalizes the chosen provider and the configured provider, and compares base_url values to determine whether to use, fallback, or drop base_url to avoid leaking a default-provider base_url into a different provider selection.  
7. Temperature and max_tokens resolution uses option-specific values when present or falls back to cfg.model values, converting to float and int respectively before provider instantiation.  
8. The provider is instantiated via create_provider with resolved parameters including api_key, base_url (or fallback), temperature, max_tokens, and num_ctx from cfg.context.max_tokens, then set_provider is called to switch runtime state.  
9. After provider creation and switch, runtime model details are refreshed and stored so callers can display current provider/model status.  
10. Session selection logic reads structured model_selection from session.metadata when present, validates provider and model, and returns a normalized dict for use in applying a session override.  
11. set_session_model orchestrates user-driven selection: handling empty selectors and "default"/"config" resets, resolving selectors, applying options inside a try/except to surface activation errors, updating session.metadata with model_selection and an ISO timestamp, and optionally persisting via session_manager.save_session.  
12. Throughout, the mixin returns clear boolean and message tuples for the async set_session_model flow, enabling callers to present success or failure feedback.

---

## captain-claw-src/captain_claw/execution_queue.py

Description:
1. This module implements lane-based asynchronous execution queue primitives for in-process task management.  
2. It defines built-in lane identifiers and specialized exceptions to indicate when a lane has been cleared or when a task result is stale.  
3. QueueEntry and LaneState dataclasses capture queued task callables, futures, timing metadata, and per-lane concurrency state.  
4. CommandQueueManager provides per-lane concurrency control, enqueueing, draining, task lifecycle handling, and introspection utilities.  
5. Tasks are scheduled and executed using asyncio.create_task and their completion or failure is propagated to associated futures.  
6. The manager assigns incremental task ids, tracks active_task_ids, and prevents stale completions via a generation counter.  
7. The file also defines follow-up queue primitives (QueueSettings, FollowupRun, FollowupQueueState, FollowupQueueManager) for deferred prompt handling.  
8. Followup queues support different modes (collect, steer, interrupt, steer-backlog) and drop policies including summarization of dropped items.  
9. Utilities are provided to normalize lane names, queue modes, and drop policies from various textual inputs.  
10. Logging hooks are used throughout to warn, debug, and report errors during enqueueing and draining operations.

Purpose:
1. The file centralizes robust asynchronous queuing behavior so different application components can schedule work independently and with predictable limits.  
2. It exists to provide a lightweight in-process mechanism for isolating contexts via lanes, each with its own queue and configurable concurrency.  
3. By modeling queued tasks and lane state explicitly, the module enables precise tracking of waiting and active work and supports warning callbacks for long waits.  
4. The generation mechanism and specialized exceptions exist to safely invalidate or ignore task completions after explicit lane resets or clears.  
5. CommandQueueManager offers convenience methods for common operations: enqueueing into a lane or the default main lane, adjusting concurrency, and clearing work.  
6. The follow-up queue manager complements the command queue by buffering and coalescing follow-up prompts when a session is busy, reducing noise.  
7. Drop policies and dedupe modes let callers balance responsiveness against resource limits, choosing whether to drop new items, old items, or summarize lost items.  
8. Debounce behavior and collect-mode composition are included to build aggregated prompts or summary prompts that reflect multiple queued follow-ups.  
9. The design leverages asyncio futures and create_task so callers can await results naturally while the manager handles scheduling and backpressure.  
10. Logging integration provides observability for wait warnings, task failures, and drain errors so higher-level code can monitor queue health.  
11. The utilities for normalizing textual mode and policy inputs make configuration more forgiving and consistent across different callers.  
12. Overall, the module exists to reduce duplication and complexity in higher-level code that needs reliable queuing, draining, and backpressure semantics.

Key elements:
- CommandLane (class constants) (predefined lane names: MAIN, CRON, SUBAGENT, NESTED, AGENT_RUNTIME).  
- CommandLaneClearedError (exception) (raised when queued tasks are rejected after a lane clear).  
- CommandLaneStaleTaskError (exception) (raised when a task finishes after lane generation changed).  
- QueueEntry (dataclass) (holds task callable, future, enqueue time, warn threshold, on_wait callback).  
- LaneState (dataclass) (per-lane queue, active_task_ids set, max_concurrent, draining flag, generation counter).  
- CommandQueueManager (class) (core manager with enqueue_in_lane, enqueue, _drain_lane, _run_entry, clear_lane, reset_all_lanes, etc.).  
- QueueSettings (dataclass) (mode, debounce_ms, cap, drop_policy configuration).  
- FollowupRun (dataclass) (prompt payload, enqueued timestamp, message id, summary line, metadata).  
- FollowupQueueState (dataclass) (per-key follow-up deque, debounce and cap settings, dropped/summarized tracking).  
- FollowupQueueManager (class) (enqueue_followup, schedule_drain, dedupe/drop policy logic, summary/collect builders).  
- resolve_session_lane / resolve_global_lane (functions) (normalize provided lane or session keys).  
- normalize_queue_mode / normalize_queue_drop_policy (functions) (map textual inputs to canonical modes/policies).  
- External dependencies and calls: asyncio (create_task, get_running_loop, sleep), captain_claw.logging.log (logging).

Key logic:
1. Enqueue operations create a QueueEntry with a future and timing metadata, append it to the appropriate lane deque, and call _schedule_drain to ensure processing begins.  
2. _schedule_drain marks a lane as draining and spawns an asyncio task to run _drain_lane unless the lane is already draining.  
3. _drain_lane pops entries while there is capacity (len(active_task_ids) < max_concurrent), warns on long waits, assigns a unique task_id, records the current generation, and starts _run_entry as a task.  
4. _run_entry awaits the queued callable, then uses _complete_task to remove the task id only if the task’s captured generation matches the lane’s current generation.  
5. If a generation mismatch is detected, completion is treated as stale: the code logs the event and sets a CommandLaneStaleTaskError on the entry future if it is not done.  
6. On normal completion, the result is set on the entry future and another drain is scheduled to continue processing queued items.  
7. On exceptions from the user task, the error is logged and the exception propagated onto the entry future unless the task is stale, in which case a stale-task exception is used.  
8. Clearing a lane removes all queued entries and sets CommandLaneClearedError on their futures so waiting callers are immediately notified of rejection.  
9. reset_all_lanes increments each lane’s generation, clears active_task_ids, and triggers drains for lanes that still have queued items; this prevents resumed completion of tasks started under prior generations.  
10. FollowupQueueManager enforces deduplication by message id or prompt text, applies drop policies (old/new/summarize), and updates summary_lines and dropped_count when items are evicted.  
11. When draining follow-up queues, debounce logic waits for a quiet period based on last_enqueued_at_ms before proceeding, optionally awaiting an external readiness callback.  
12. Follow-up drain behavior depends on mode: collect mode aggregates multiple queued items into a single composed prompt, summarize mode emits a summary prompt for dropped items, and interrupt/steer modes prioritize the most recent item while clearing backlog.

---

## captain-claw-src/captain_claw/web_server.py

Description:
1. This module implements the Web UI server for Captain Claw.  
2. It defines a WebServer class that manages an Agent, WebSocket clients, background tasks, and various auxiliary services.  
3. The WebServer exposes many HTTP endpoints and delegates request handling to specialized functions in the captain_claw.web package.  
4. It provides callbacks to broadcast agent status, thinking updates, tool outputs, and approval notices to connected WebSocket clients.  
5. The WebServer lazily initializes a SessionOrchestrator, an AgentPool for OpenAI-compatible API proxying, and a GoogleOAuthManager when configured.  
6. The module contains logic to integrate a Telegram bridge and queue inbound Telegram messages for processing.  
7. The create_app method registers routes for instructions, config, sessions, orchestrator, cron jobs, entities, workflows, loops, OAuth, and static assets.  
8. The _run_server coroutine handles event loop setup, signal handling, agent initialization, starting services (Telegram, cron scheduler), and graceful shutdown.  
9. A helper _get_web_runtime_context constructs a minimal RuntimeContext object suitable for running cron jobs in web mode.  
10. The file provides run_web_server and main entry points that configure logging, load configuration, ensure workspace/session directories, and start the server process.

Purpose:
1. The file centralizes web server orchestration so the Captain Claw application can be accessed via a browser and websocket clients.  
2. It exists to expose the application's capabilities (instructions, sessions, orchestrator controls, cron, entities, workflows, loops, OAuth and more) over HTTP and WebSocket endpoints.  
3. By delegating route handlers to the captain_claw.web package, it keeps HTTP routing and high-level lifecycle concerns separate from request-specific logic.  
4. The WebServer class unifies lifecycle management for core components (Agent, orchestrator, API agent pool, OAuth manager, Telegram bridge) and coordinates their initialization and shutdown.  
5. The broadcasting callbacks provide a simple mechanism for the agent and related components to push real-time updates to any connected UI clients.  
6. Conditional initialization (API pool, OAuth manager, static assets) allows the server to adapt to configuration and environment without modifying route code.  
7. The module also acts as the main program entry point for running the web UI, performing startup sequencing, workspace preparation, and top-level exception handling.  
8. Integrating the cron scheduler and providing a lightweight runtime context enables cron jobs to run within the same process while receiving agent-based utilities.  
9. Signal handling and the stop_event pattern implemented in _run_server support graceful termination initiated by external signals or user interrupt.  
10. The WebServer's helpers and delegated endpoints provide a stable interface that other modules (e.g., web handlers, orchestrator, telegram bridge) can rely on during runtime.  
11. The design keeps resource cleanup explicit: it cancels tasks, shuts down pools and orchestrators, stops Telegram, closes websockets, and calls runner.cleanup before exiting.  
12. Overall, this module ties together networking, async orchestration, authentication, real-time UI broadcasts, and lifecycle management for the web-facing part of Captain Claw.

Key elements:
- STATIC_DIR (Path) (static assets folder used when present).  
- COMMANDS (list[dict]) (help/suggestion command definitions surfaced to the UI).  
- class WebServer (main server class that holds state and methods).  
- WebServer.__init__ (initializes agent-related state, queues, tasks, and configuration-derived flags).  
- WebServer._init_agent (async; creates Agent, SessionOrchestrator, optional AgentPool, and GoogleOAuthManager).  
- WebServer._status_callback (broadcasts status updates).  
- WebServer._thinking_callback (broadcasts thinking/reasoning updates).  
- WebServer._tool_output_callback (broadcasts tool output; may emit rephrase chat messages and thinking summaries).  
- WebServer._approval_callback (handles tool approval requests and broadcasts notices).  
- WebServer._broadcast (serialize message to JSON and send to all connected websockets).  
- WebServer._send (send message to a single websocket).  
- WebServer._get_web_runtime_context (builds minimal RuntimeContext for cron).  
- Delegated async handlers (ws_handler, list_instructions, get_instruction, put_instruction, revert_instruction, many _* methods that import and forward to captain_claw.web.* modules).  
- WebServer.create_app (registers routes with aiohttp.web.Application, including conditional routes for API proxy and static pages).  
- _run_server (async entrypoint: setup, signal handling, start services, cron, and shutdown).  
- run_web_server and main (synchronous entrypoints that configure logging, load config, ensure directories, and start the server).  
- Integration points: imports of Agent, AgentPool, SessionOrchestrator, GoogleOAuthManager, InstructionLoader, TelegramBridge/TelegramMessage, aiohttp.web, and cron_scheduler_loop.

Key logic:
1. On instantiation, WebServer captures configuration, prepares state containers (websocket clients set, locks, queues), and computes flags for optional features like Telegram and API proxying.  
2. _init_agent asynchronously constructs the main Agent and then creates a SessionOrchestrator that shares provider and callbacks; if enabled it also creates an AgentPool and a GoogleOAuthManager, injecting stored tokens into the provider when applicable.  
3. Status, thinking, tool output, and approval callbacks are simple adapters that format messages and call _broadcast so all connected WebSocket clients receive real-time UI updates.  
4. _tool_output_callback applies a silent-tools filter, sends monitor messages, emits a rephrase chat message when the "task_rephrase" tool completes, and synthesizes brief thinking summaries for non-silent tools.  
5. _broadcast serializes the message to JSON and iterates over the clients set, scheduling asynchronous sends and pruning any closed or failing websockets to keep the client set clean.  
6. Many HTTP endpoints are thin delegators: each route handler imports the actual implementation from captain_claw.web.* on demand and awaits its result, keeping the router lightweight and lazily resolving dependencies.  
7. create_app wires a comprehensive set of routes for APIs, orchestrator controls, cron management, entity CRUD, workflow browsing, loop runner endpoints, OAuth flows, and optionally the OpenAI-compatible API endpoints and static file serving.  
8. _run_server prepares the asyncio event loop, installs signal handlers that set an asyncio.Event to trigger shutdown, initializes the agent and starts Telegram integration, then constructs and starts an aiohttp site on the configured host and port.  
9. If configured, it starts an in-process cron scheduler task using a minimal RuntimeContext that supplies non-blocking UI methods and auto-confirmation behavior for web-mode cron execution.  
10. The main server wait loop blocks on the stop_event; when signaled it cancels the cron worker, attempts graceful shutdown of orchestrator and agent pool, stops Telegram, closes active websockets, cleans up the aiohttp runner, and finally calls os._exit(0) to terminate the process.  
11. run_web_server wraps _run_server in asyncio.run and handles KeyboardInterrupt gracefully; main sets up logging, loads and applies configuration, ensures session and workspace directories exist, and invokes run_web_server while reporting fatal errors.  
12. Throughout, the module prefers defensive exception handling during startup and teardown so failures in auxiliary components do not prevent the web server from attempting best-effort cleanup.

---

## captain-claw-src/captain_claw/task_graph.py

Description:
1. This module implements a standalone directed acyclic graph (DAG) scheduler for orchestrating tasks.  
2. It defines an OrchestratorTask dataclass that represents a unit of work with metadata such as dependencies, status, retries, timeouts, and results.  
3. The TaskGraph class manages a collection of OrchestratorTask instances and maintains ordering, readiness, running, completed, failed, and held sets.  
4. A stable topological sort is implemented using a variant of Kahn's algorithm to produce deterministic activation order.  
5. The graph can activate ready tasks up to a configurable max_parallel concurrency limit while respecting editing and hold states.  
6. Task lifecycle operations include completing, failing with retry semantics, pausing, resuming, editing, restarting, and updating descriptions.  
7. Timeout management uses a two-phase approach where tasks that exceed timeout_seconds enter a TIMEOUT_WARNING grace period before being restarted or failed.  
8. The module exposes query methods to retrieve results, summaries, counts, and flags indicating completion or failures.  
9. State refresh recomputes topology and categorizes tasks as ready, blocked, running, completed, failed, or held based on dependency resolution and statuses.  
10. Overall, the code provides deterministic orchestration primitives suitable for session orchestration and parallel task management.  

Purpose:
1. The file exists to provide a focused, reusable scheduler component that can be used by higher-level orchestrators to run tasks with dependency and concurrency constraints.  
2. By encapsulating task state, ordering, activation, and timeout/retry logic, it separates orchestration mechanics from business logic.  
3. TaskGraph centralizes rules about when tasks become runnable, how failures propagate, and how retries are applied, reducing duplication in the codebase.  
4. The OrchestratorTask dataclass standardizes the task payload expected by the orchestrator and carries execution metadata needed for control decisions.  
5. The topological sort ensures tasks are started in a deterministic order consistent with declared dependencies, which aids reproducibility and debugging.  
6. Concurrency control via max_parallel lets the system limit resource usage and coordinate parallel workers without external coordination.  
7. Timeout handling with a warning grace period gives an operator or UI a chance to postpone restarts instead of immediately failing long-running tasks.  
8. Retry semantics allow transient errors to be retried automatically while still surfacing permanent failures after a configured number of attempts.  
9. Control methods such as pause, resume, edit, and restart provide interactive capabilities for human-in-the-loop workflows and editing of instructions.  
10. Graph-level query methods produce compact summaries and results suitable for dashboards, logging, or driving orchestration decisions.  
11. The module is written to be self-contained and deterministic, making it straightforward to test in isolation from other services.  
12. Its design supports use by a SessionOrchestrator or similar component that can poll activate_next, run tasks, report completions, and call tick_timeouts periodically.  

Key elements:
- PENDING, QUEUED, RUNNING, COMPLETED, FAILED, PAUSED, EDITING, TIMEOUT_WARNING (status constants).  
- TIMEOUT_GRACE_SECONDS (global grace period between warning and automatic restart).  
- OrchestratorTask (dataclass carrying id, title, description, depends_on, session info, status, retries, timeouts, timestamps, result, error, editing flag, etc.; includes is_terminal()).  
- TaskGraph class (core scheduler managing tasks, order, and state sets).  
- TaskGraph._topological_sort (static method implementing Kahn's algorithm for stable ordering).  
- TaskGraph.refresh (recomputes order and categorizes tasks into ready/blocked/running/completed/failed/held).  
- TaskGraph.activate_next (traffic-light activation up to max_parallel, honors editing/hold states).  
- TaskGraph.complete_task and fail_task (completion and failure with retry/reset behavior).  
- Task control methods: pause_task, resume_task, edit_task, update_task_description, restart_task.  
- TaskGraph.tick_timeouts and postpone_task (two-phase timeout handling with warning, grace countdown, restart/fail behavior, and postponement).  
- Query and summary methods: tasks, task_count, is_complete, has_failures, running_count, ready_count, get_results, get_summary.  
- Dependencies: time module for monotonic timestamps; dataclasses and typing for type and structure.  

Key logic:
1. Tasks are stored in a dictionary keyed by id and the graph maintains multiple derived sets (ready, blocked, running, completed, failed, held) that are recalculated by refresh.  
2. The _topological_sort method builds forward and reverse dependency maps, seeds a sorted ready list of zero-dependency tasks, and processes dependents in deterministic order, appending any cyclic leftovers at the end.  
3. refresh uses the topological order and each task's status and declared dependencies to determine whether dependencies are satisfied, failed, or still blocking, and it cascades failures to dependents when a dependency is in FAILED.  
4. activate_next first calls refresh, computes available slots from max_parallel minus currently running tasks, and then transitions ready tasks (in topological order) to RUNNING while skipping tasks marked editing.  
5. When a task is activated its started_at timestamp is set with time.monotonic(), and it is added to the running set; activate_next returns newly activated tasks for worker consumption.  
6. complete_task sets status to COMPLETED, records result and completion timestamp, and leaves activation of dependents to the orchestrator loop to avoid races.  
7. fail_task increments retries and resets tasks back to PENDING if retries remain, otherwise marks them FAILED and stamps completed_at; error messages encode retry counts or exhaustion.  
8. Pause/resume/edit/restart/update operations manipulate status, editing flags, timestamps, and error fields with guards to ensure valid transitions and to support human edits and interactive control.  
9. tick_timeouts iterates currently running tasks and implements a two-phase timeout: once elapsed > timeout_seconds a task enters TIMEOUT_WARNING and timeout_warning_at is set, and during the grace period a countdown is reported.  
10. If the grace period expires and retries remain the task is reset to PENDING with retries incremented and appropriate error text; if retries are exhausted the task is moved to FAILED and completed_at is recorded.  
11. postpone_task allows an externally triggered postponement by returning a TIMEOUT_WARNING task back to RUNNING with a fresh started_at, effectively granting another full timeout interval.  
12. Graph-level query methods recompute state as needed and return compact structures that summarize counts, completion/failure flags, and per-task result metadata for UI, logging, or orchestration decision-making.

---

## captain-claw-src/captain_claw/semantic_memory.py

Description:
1. This module implements a SQLite-backed semantic memory index with hybrid retrieval combining keyword full-text search and vector search.  
2. It defines dataclasses for search hits, documents, and chunks to represent indexed content and results.  
3. Multiple embedding provider implementations and a provider chain are provided to generate normalized vector embeddings, with failover behavior.  
4. The SemanticMemoryIndex class encapsulates configuration, database schema creation, indexing, background synchronization, caching, and search APIs.  
5. The indexer can walk a workspace directory and read a session SQLite DB to collect documents, applying include/exclude filters and size limits.  
6. Documents are chunked into overlapping line-based pieces, stored in memory_chunks and an FTS5 virtual table, and optionally have embeddings persisted.  
7. Keyword search uses FTS5 with a fallback LIKE query, returning BM25-based text scores for candidates.  
8. Vector search embeds queries, computes cosine similarity against stored embeddings, and ranks candidates by vector score.  
9. A hybrid merge routine combines text and vector scores with configurable weights, applies optional temporal decay, enforces a minimum score, and sorts results.  
10. Background synchronization runs in a separate daemon thread to keep the SQLite index in sync with workspace and session sources, while cache and locks manage concurrency and staleness.

Purpose:
1. The file exists to provide a durable, local semantic memory for the application so other components can retrieve contextually relevant text snippets from both workspace files and session histories.  
2. It centralizes the logic for scanning sources, creating and maintaining an index schema optimized for fast keyword and vector queries, and persisting both textual chunks and numeric embeddings.  
3. By supporting multiple embedding providers and a provider chain with automatic failover, the module enables semantic search when external models are available while falling back to a local hashing approach otherwise.  
4. The implementation exposes configuration knobs (chunk size, overlap, file limits, inclusion rules, caching and decay parameters) so different deployments can tune retrieval behavior.  
5. Background synchronization decouples indexing from search calls, allowing searches to trigger non-blocking updates and reducing latency in user-facing query operations.  
6. The class-level locking strategy isolates database access and sync state, providing safe concurrent use from multiple threads within the same process.  
7. The hybrid scoring and merging logic lets the system leverage complementary signals from keyword and vector matches to produce more relevant results than either approach alone.  
8. Temporal decay of scores biases results toward recent content, which helps prioritize up-to-date context in interactive sessions.  
9. The module offers utility methods to upsert ad-hoc documents (useful for tests or manual memory injection) and to format top hits into prompt-friendly context notes and debug strings.  
10. It provides a single factory function to construct a configured SemanticMemoryIndex from a higher-level memory configuration object, simplifying integration with application configuration systems.  
11. Error handling and fallbacks (FTS fallback, embedding provider fallbacks, and robust parsing) make the component resilient to partial failures in external dependencies or corrupt inputs.  
12. Overall, the file exists to make local textual context discoverable, ranked, and consumable by other parts of the system while remaining configurable and robust.

Key elements:
- SemanticMemoryResult (dataclass: represents a single search hit with scores and metadata).  
- _Document (dataclass: in-memory representation of a document to index).  
- _Chunk (dataclass: representation of a document chunk including line ranges).  
- _EmbeddingProvider (Protocol: interface describing embed_batch).  
- _LocalHashEmbeddingProvider (class: local hashing/token-based embedding fallback).  
- _OllamaEmbeddingProvider (class: HTTP-based embedding provider using Ollama).  
- _LiteLLMEmbeddingProvider (class: embedding provider integrating LiteLLM).  
- _EmbeddingProviderChain (class: manages multiple providers and failover rotation).  
- SemanticMemoryIndex (class: core index manager, syncing, search, and DB operations).  
- Methods on SemanticMemoryIndex: __init__, set_active_session, close, schedule_sync, upsert_text, search, build_context_note, _sync_worker, _ensure_db, _sync_once, _collect_workspace_documents, _collect_session_documents, _sync_documents, _upsert_document, _delete_document, _delete_chunks_for_doc, _chunk_document, _upsert_embeddings_for_chunks, _keyword_search, _vector_search, _merge_hybrid, _clear_cache.  
- Utility functions: _utcnow_iso, _normalize_embedding, _cosine_similarity, _tokenize_fts, _build_fts_query, _parse_iso_to_timestamp, _hash_text, _build_embedding_chain, create_semantic_memory_index.  
- External dependencies and notable calls: sqlite3 (persistent store and FTS5), httpx (HTTP client for Ollama), litellm (optional embedding client, imported lazily), math, json, re, threading, datetime, and logging via captain_claw.logging.get_logger.

Key logic:
1. Initialization ensures the SQLite database file and schema exist, configures parameters, builds an embedding provider chain, and schedules an initial background sync.  
2. Sync scheduling marks the index as dirty and spawns a daemon thread if no sync is running; the background thread runs _sync_worker which calls _sync_once until the index is clean.  
3. _sync_once collects document lists from the workspace (by walking the workspace_path with include/exclude rules and file size limits) and from the session DB (by reading session rows and converting messages into text), then delegates to _sync_documents.  
4. _sync_documents compares incoming documents against existing memory_documents rows using signatures; it upserts changed documents and deletes stale documents that are no longer present.  
5. Upserting a document stores metadata, deletes any prior chunks, chunks the document text into line-based pieces with a configurable character target and overlap, inserts chunks and their FTS entries, and triggers embedding upserts.  
6. Chunking iterates lines, accumulates characters until the chunk_chars target is reached, ensures at least one line per chunk, and computes overlap by walking backward to include overlap_chars worth of lines for the next chunk's start.  
7. Embedding upserts run in batches, call the embedding chain's embed_batch (which rotates providers and fails over across configured providers), normalize vectors, and store JSON-serialized embeddings with provider keys and dimensionality.  
8. Keyword search builds an FTS query from tokenized, filtered tokens, runs a MATCH query using bm25 ranking, and falls back to a LIKE-based search when FTS fails; results include a computed text_score derived from bm25.  
9. Vector search embeds the query, retrieves embeddings with the matching provider key and dimensionality, computes cosine similarity against each stored vector, sorts by vector_score, and will schedule a sync if there are no rows for the active provider (provider mismatch).  
10. The hybrid merge combines hits by chunk_id, fills missing text/vector scores, optionally replaces snippets with vector-provided text, and computes a combined score as a weighted sum of vector and text scores.  
11. If temporal decay is enabled the merged scores are multiplied by an exponential decay factor derived from document updated timestamps and a configurable half-life in days, which reduces scores for older content.  
12. Results below the configured min_score are filtered out, the remaining SemanticMemoryResult objects are sorted by score and truncated to max_results; search results are cached with a TTL to avoid recomputation on frequent identical queries.

---

## captain-claw-src/captain_claw/file_registry.py

Description:
1. This module implements a thread-safe registry mapping logical file paths to physical on-disk locations.
2. It defines a FileRegistry class that stores normalized logical paths, physical paths, and a filename index for fuzzy lookup.
3. The registry provides methods to register mappings, resolve logical paths to physical paths, and list or serialize entries.
4. Normalization removes surrounding quotes, trims whitespace, resolves path components, and strips leading slashes.
5. Resolution attempts an exact normalized match, a fallback after stripping common prefixes like "saved/", and a filename-only fuzzy match when unambiguous.
6. Registrations update both a mappings dictionary and a filename-to-logical-paths index under a threading lock.
7. The class supports merging mappings from another registry without overwriting existing entries (first-writer wins).
8. Helper methods allow building a human-readable manifest and serializing/deserializing registry state to and from dictionaries.
9. The module uses a logger for debug messages when files are registered.
10. Threading locks protect internal state to ensure safe concurrent access by multiple tasks.

Purpose:
The FileRegistry exists to decouple logical file references used by orchestration components or language model prompts from the actual session-scoped physical file locations on disk. It enables downstream tasks to access outputs produced by upstream tasks without needing to know session IDs or internal folder layouts. By maintaining normalized logical paths and a fuzzy filename index, the registry handles inconsistent or abbreviated file references that may appear across steps. Thread-safety allows a single registry instance to be shared across concurrent tasks within an orchestration run or a single-agent session. Serialization and deserialization methods permit registry state to be persisted, inspected, or included in diagnostics and tooling. The build_manifest method generates a human-readable list of available files that can be injected into prompts so an LLM knows what files are available from previous steps. The resolve_or_passthrough convenience method simplifies callers by returning the original path when no mapping is found, avoiding errors for unmapped references. Merging from another registry supports combining file sets from different contexts while preserving original writers' mappings. Normalization and prefix-stripping implement practical matching policies (e.g., removing "saved/") to increase match robustness. The compact public API (register, resolve, list_files, to_dict, from_dict, merge_from) keeps integration straightforward for orchestration components that need file lookup and provenance. Debug logging on registration assists in tracing file provenance and diagnosing mismatches during multi-step runs.

Key elements:
- FileRegistry (class) — central registry object managing mappings and index.
- __init__ (method) — initializes orchestration_id, lock, mappings dict, and filename index.
- register (method) — record a logical -> physical mapping and update filename index (logs debug).
- resolve (method) — resolve logical paths using exact match, prefix-stripped fallback, and filename-only fuzzy match.
- resolve_or_passthrough (method) — returns resolved path or original input if not found.
- list_files (method) — returns a list of registered entries as dicts with "logical" and "physical".
- build_manifest (method) — returns a human-readable, sorted manifest suitable for prompt injection.
- to_dict / from_dict (methods) — serialize and restore registry state.
- merge_from (method) — merge another registry's mappings without overwriting existing entries.
- __len__ / __bool__ (methods) — provide size and truthiness checks.
- _normalize (staticmethod) — normalizes input paths (strip quotes/whitespace, resolve components, strip leading slash).
- _strip_common_prefixes (staticmethod) — strips configured prefixes such as "saved/" for fallback matching.
- _mappings (dict) — internal normalized logical -> physical mapping store.
- _filename_index (dict) — filename -> list of logical keys for fuzzy lookup.
- _lock (threading.Lock) — protects concurrent access to internal state.
- get_logger from captain_claw.logging (external call) — used for debug logging.

Key logic:
The registry normalizes any provided logical path before use by trimming whitespace, removing surrounding quotes, splitting into path components via pathlib.Path, and stripping leading slashes to create a consistent lookup key. When register is called, the normalized logical path and the stringified physical path are stored under a lock; the filename (last path component) is used to populate a filename index that maps filenames to lists of logical keys for fuzzy resolution. register logs a debug message including the normalized logical and physical paths and an optional task_id. resolve first normalizes the input and then checks for an exact mapping in the mappings dictionary under the same lock to ensure thread safety. If no exact mapping exists, resolve attempts a fallback by stripping configured common prefixes (currently "saved/") and checking the mappings again. If still not found, resolve performs a filename-only fuzzy lookup: it retrieves the candidate logical keys from the filename index and returns a mapping only if there is exactly one candidate, avoiding ambiguous resolutions. resolve_or_passthrough simply calls resolve and returns the original path when resolve yields no mapping, providing a convenient no-op fallback for callers. list_files iterates the mappings under lock and returns a list of dictionaries containing logical and physical path pairs for inspection or consumption by other components. build_manifest constructs a sorted, human-readable multi-line string that lists available logical files alongside their on-disk hints, suitable for inclusion in LLM prompts. to_dict produces a snapshot containing the orchestration_id and a copy of mappings for persistence or debugging, while from_dict recreates a FileRegistry and re-registers entries to rebuild index structures. merge_from reads another registry's mappings while holding the other registry's lock, then inserts any keys that do not already exist in this registry (first-writer wins) and updates the filename index accordingly. Length and boolean checks are implemented to reflect the number of mappings and to allow easy truthiness testing of registry content. Overall, the logic prioritizes deterministic matching, safe concurrent updates, and simple, predictable fallbacks for LLM-driven file references.

---

## captain-claw-src/captain_claw/agent_orchestration_mixin.py

Description:
1. This module implements orchestration logic for an agent handling complete and streaming LLM requests.  
2. It defines multiple scale-advisory templates and a helper to build advisories tailored to different output strategies.  
3. It contains heuristics and regex patterns to detect inputs that suggest large-scale list or file-processing tasks.  
4. The AgentOrchestrationMixin class provides methods to run preflight scale checks and a comprehensive complete() coroutine that drives a multi-iteration agent turn.  
5. complete() initializes per-turn state, enforces guards, constructs messages, and manages planning pipelines and iteration budgets.  
6. The mixin integrates with a tools subsystem to retrieve tool definitions, detect explicit or embedded tool calls, and execute tools under session and task policies.  
7. It supports an early micro-loop and a scale micro-loop that process items incrementally to avoid blowing the LLM context window.  
8. The file implements completion gates, validation against task contracts, and mechanisms for auto-writing or running python workers for list tasks.  
9. The module emits structured telemetry/tool_output events, persists assistant responses, and auto-captures todos, scripts, contacts, and APIs.  
10. Robust error handling and logging are included for guard blocks, LLM failures, tool fallback behaviors, and environment restoration.

Purpose:
The file centralizes high-level orchestration so that agent classes can reuse consistent, scale-aware request handling logic. It exists to detect when a user request implies large or repetitive work and to inject explicit, machine-readable guidance (scale advisories) so the LLM adopts an incremental, safe processing strategy. By formalizing the detection of list tasks and inline URL lists, the mixin helps avoid context-window exhaustion and unnecessary repeated globbing or reprocessing. The complete() coroutine is the main entry point for a user turn and is responsible for combining prompt construction, policy/guard enforcement, tool discovery, and iterative LLM interaction. It also coordinates planning pipelines and can spawn subagent contexts to enable multi-step, managed workflows. Scale progress tracking and micro-loop facilities are provided so the agent can switch from a conversational LLM loop to a direct item-by-item processing loop when appropriate. The mixin supports fallback behaviors (e.g., friendly tool-output responses, python worker auto-run) to handle script-style or large-list jobs robustly. Completion gates and task-contract validation enforce that outputs satisfy explicit requirements before finalizing a turn. Iteration budgeting, stagnation detection, and controlled extensions prevent infinite loops while allowing additional iterations when measurable progress occurs. Overall, the module exists to encapsulate complex orchestration concerns—safety, tooling, scaling, planning, and telemetry—so higher-level agent implementations remain focused on domain logic.

Key elements:
- _SCALE_ADVISORY_SINGLE_FILE, _SCALE_ADVISORY_FILE_PER_ITEM, _SCALE_ADVISORY_NO_FILE (scale advisory text templates).  
- _build_scale_advisory(item_count, output_strategy, filename_template, final_action) (helper to format the correct advisory).  
- _LARGE_SCALE_INPUT_PATTERNS (list of compiled regex patterns for detecting large-scale input language).  
- _INLINE_URL_RE (regex to count inline URLs in input).  
- AgentOrchestrationMixin (class that provides orchestration methods to an agent).  
- AgentOrchestrationMixin._input_suggests_large_scale(user_input) (heuristic to detect list/large tasks).  
- AgentOrchestrationMixin._preflight_scale_check(effective_user_input, list_task_plan) (decides whether to inject scale advisory and emits task_contract events).  
- AgentOrchestrationMixin.complete(user_input) (async coroutine implementing the full turn lifecycle and main control flow).  
- Internal helpers defined inside complete(): _restore_skill_env_once, finish, attempt_finalize_response (manage environment, finalization, and auto-write behavior).  
- Calls to external subsystem methods (examples: self.tools.list_tools, self.tools.get_definitions, self._run_scale_micro_loop, self._generate_list_task_plan, self._generate_task_contract, self._build_task_pipeline, and various _emit_* / _add_session_message / _handle_tool_calls helpers).  
- External module dependencies: get_config (for scale thresholds), GuardBlockedError (error handling), Message (LLM message wrapper), get_logger (logging).

Key logic:
1. On entry complete() ensures the agent is initialized and sets up per-turn state including usage counters, cancel events, and duplicate tool-call tracking.  
2. The method normalizes the user input, applies clarification context or rephrasing when helpful, and enforces input guards before recording the user message.  
3. It attempts to extract a structured list_task_plan (or augments it by parsing raw URLs) so the orchestration layer can treat list-processing requests specially.  
4. A preflight scale check uses both explicit member counts and text-pattern heuristics (plus URL/list-line counting) to decide whether to append a scale advisory to the prompt.  
5. If a scale advisory is activated the mixin initializes _scale_progress metadata (items, done_items, output strategy) so subsequent logic can track progress and produce percentage updates.  
6. When prepopulated items and per-member actions are available the code may early-takeover and run a micro-loop that processes items directly without invoking the main LLM loop, producing a summary afterward.  
7. Otherwise the main loop constructs messages, fetches tool definitions, and calls the LLM repeatedly within an iteration budget that can be extended when observable progress occurs.  
8. Each LLM response is inspected for explicit tool_calls, embedded tool-call patterns in content, or inline commands; detected actions are executed via guarded tool invocation and their outputs are recorded into the session.  
9. After tool execution the mixin can trigger a scale micro-loop takeover if conditions are met (e.g., scale_progress active and first items done), or let the LLM continue and follow up on tool results when supported.  
10. Completion gating logic evaluates coverage of list members, cross-references scale-progress done_items, and runs contract validation checks; failing checks generate feedback and controlled retries rather than immediate finalization.  
11. The loop maintains progress snapshots and a stagnation detector; repeated non-progress behavior causes graceful termination with an explanatory message.  
12. Finalization handles optional auto-write behavior, running python-worker workflows if required, persisting assistant output, auto-capturing artifacts (todos, contacts, scripts, APIs), emitting telemetry events, and returning the final assistant text.

---

## captain-claw-src/captain_claw/local_command_dispatch.py

Description:
1. This module implements a large async command dispatcher for local console commands.  
2. It exposes a single coroutine, dispatch_local_command, which inspects a parsed command token and performs the associated action.  
3. The function consults the runtime context, agent, and UI objects to operate on sessions, cron jobs, to‑dos, contacts, scripts, APIs, skills, and monitor settings.  
4. It recognizes commands by exact matches and by prefix checks, parsing JSON payloads or tokenized arguments when needed.  
5. For session and resource operations it delegates persistence and lookup work to agent.session_manager and enqueues longer tasks via the project's task queue helpers.  
6. Cron-related commands compute scheduling information, trigger cron monitoring events and can execute saved scripts or tools in the context of a session.  
7. Skill installation and invocation paths call agent methods that may rewrite prompts or dispatch actions, sometimes resulting in nested prompt execution.  
8. Many branches return "continue" to indicate the main loop should prompt again, "break" to exit, or None to indicate the input should be treated as a normal prompt.  
9. The module uses the UI to display success, error, warning, and system messages and to populate monitor panes.  
10. It contains extensive input validation, error handling, and small helper flows such as session procreation, export, and compaction.  

Purpose:
The file centralizes the console command handling logic that was originally embedded in an interactive loop so the rest of the application can remain modular.  
By mapping textual command tokens to asynchronous side effects it provides a single place to interpret user directives and maintain consistent UI feedback.  
It exists to translate high-level user commands into operations on sessions, persisted objects (todos, contacts, scripts, APIs), scheduled jobs, and runtime flags.  
Because many operations involve I/O and background work the dispatcher coordinates enqueuing tasks and invoking utility functions that perform the heavy lifting.  
The dispatcher enforces preconditions such as the presence of an active session, valid payloads, or enabled integrations before delegating work.  
It also centralizes common parsing patterns like JSON payload decoding and shlex-based argument splitting to produce consistent error messages.  
Integration points with cron machinery, the session orchestrator, and skill management are exposed here so console commands can trigger project-level orchestration.  
Monitor and pipeline toggles are surfaced in the same place to provide immediate feedback and to persist runtime configuration through agent APIs.  
By returning explicit control signals ("continue", "break", or None) the coroutine cleanly informs the interactive loop how to proceed after handling a command.  
This separation improves testability and allows the interactive REPL to remain focused on prompt management rather than branching logic.  
The dispatcher also records structured tool output and monitor events so other subsystems can render or persist the results.  
Overall, it exists to be the authoritative translator between textual user requests typed in the local console and the asynchronous service operations they intend to perform.  

Key elements:
- dispatch_local_command (async function) — main entrypoint that maps parsed command results to actions and returns control tokens ("break", "continue", or None).  
- ctx / agent / ui (runtime objects) — environment used throughout to access session state, queues, and presentation methods.  
- agent.session_manager (object) — used extensively for listing, selecting, creating, updating, and deleting sessions, todos, contacts, scripts, APIs, and cron jobs.  
- enqueue_agent_task, run_cancellable, dispatch_prompt_in_session, run_prompt_in_active_session (prompt/task helpers) — used to schedule or run prompts and background tasks.  
- cron helpers: cron_monitor, cron_monitor_event, execute_cron_job, parse_cron_add_args, resolve_saved_file_for_kind (cron-related utilities).  
- scheduling utilities: compute_next_run, schedule_to_text, to_utc_iso (compute and format next-run timestamps).  
- CommandLane and resolve_session_lane (execution queue abstractions) — used when enqueuing or clearing lanes.  
- approve_chat_pairing_token (platform adapter) — validates and approves chat pairing tokens for integrations.  
- export_session_history (session export helper) — used to write and return exported session files.  
- shlex, json, datetime (standard libs) — used for argument parsing, payload decoding, and timestamping.  
- UI methods referenced: print_error, print_success, print_message, print_session_info, print_session_list, print_model_list, print_cron_jobs, print_cron_job_history, load_monitor_tool_output_from_session, append_tool_output, set_monitor_mode, clear_monitor_tool_output, clear_monitor_chat_output, scroll_monitor_pane, etc.  
- SessionOrchestrator (lazily imported) — used by the "ORCHESTRATE" flow to run higher-level orchestration logic.  

Key logic:
The coroutine receives a runtime context, a parsed command token (result), and the original user_input; it then enters a large chain of conditional branches that match exact tokens or prefixes.  
For each recognized command it validates preconditions (e.g., active session present, integrations enabled), attempts to parse any JSON payload or tokenized arguments, and then delegates to the appropriate subsystem.  
Most branches respond to success or failure by emitting UI messages (success, error, warning, or system) and typically return "continue" to signal the caller to prompt again.  
Exit is handled early by returning "break" when the EXIT token is seen.  
Session management branches create, select, rename, describe, export, run prompts in, procreate, and clear sessions while updating session runtime flags and monitor panes as needed.  
Cron flows parse schedules and payloads, validate saved script/tool paths, compute next-run times, create or modify cron job records, trigger monitor events, and can manually execute cron jobs or one-off prompts.  
Resource CRUD flows (todos, contacts, scripts, APIs) call into agent.session_manager for list/select/create/update/delete and format human-readable listings or detailed info blocks for the UI.  
Skill-related branches handle catalog search, installation (from GitHub or dependency installs), invocation (dispatch mode vs prompt rewrite), and surface errors returned by agent helper methods.  
Some operations that are potentially long-running are wrapped in enqueue_agent_task to run on appropriate lanes (often CommandLane.NESTED) and use run_cancellable to allow user cancellation of orchestrations.  
Argument parsing uses json.loads for structured payloads and shlex.split for shell-like tokenization (notably in the /cron run branch), with try/except blocks to provide friendly usage errors on malformed input.  
When manipulating queues the dispatcher interacts with followup_queue and command_queue through helper functions like resolve_session_lane and update_active_session_queue_settings to reflect per-session queue policies.  
Monitoring and tracing toggles call agent methods or UI setters to change runtime behavior and then confirm the change via a success message.  
If a command is not recognized by any branch the function returns None so the interactive loop can treat the original input as a normal prompt to be executed.

---

## captain-claw-src/captain_claw/discord_bridge.py

Description:
1. This module provides a minimal bridge to Discord's REST API for polling direct messages and guild text channels and for sending messages and files.  
2. It defines a DiscordMessage dataclass to normalize incoming message payloads into a consistent structure.  
3. It wraps an httpx.AsyncClient to perform authenticated GET and POST requests to the Discord API.  
4. It includes helper methods to list DM channels and to enumerate guild text channels accessible to the bot.  
5. It caches and exposes the bot user id to detect when the bot is mentioned in messages.  
6. Its get_updates coroutine polls channels, applies per-channel offsets, filters and normalizes incoming messages, and returns new updates with updated offsets.  
7. The send_message coroutine splits large text into chunks and posts them sequentially to a channel, optionally as a reply.  
8. It implements a send_chat_action method to send a typing indicator to a channel.  
9. The send_audio_file method uploads an MP3 file as a multipart POST with an optional caption and reply reference.  
10. Throughout the module it performs basic validation, error handling, and API response status checks using response.raise_for_status.  

Purpose:
1. The file exists to provide a compact, reusable abstraction over Discord's HTTP API for use by the larger Captain Claw application.  
2. It centralizes token handling, base URL configuration, and the asynchronous HTTP client so other parts of the project can interact with Discord without duplicating network code.  
3. By normalizing messages into the DiscordMessage dataclass it simplifies downstream processing and decouples application logic from Discord's raw JSON payloads.  
4. The polling-oriented get_updates method implements offset tracking so the application can resume polling without reprocessing already-seen messages.  
5. Low-level request helpers (_api_get and _api_post_json) isolate HTTP mechanics and response status checking from higher-level behaviors.  
6. Channel discovery helpers enable the module to discover both direct message channels and guild text channels the bot can access.  
7. The module intentionally suppresses mentions in outgoing messages via allowed_mentions to avoid unintentionally pinging users when relaying content.  
8. Chunking logic in send_message exists to respect Discord's message length limits while attempting to preserve readability by preferring newline splits.  
9. The send_audio_file method exists to support features that produce audio output by uploading attachments as multipart form data.  
10. Caching the bot user id reduces redundant API calls and enables correct handling of messages that explicitly mention the bot.  
11. The file raises explicit errors for missing audio files and relies on response.raise_for_status to surface HTTP errors for calling code to handle.  
12. Overall, the module provides a focused integration layer so other components can consume and produce Discord messages without managing HTTP details or Discord-specific formatting logic.

Key elements:
- DiscordMessage dataclass (id, channel_id, user_id, username, text, guild_id, mentioned_bot).  
- DiscordBridge class (primary integration class encapsulating Discord functionality).  
- __init__ (initializes token, api_base_url, httpx.AsyncClient, and bot user id cache).  
- enabled property (boolean indicating whether a token is configured).  
- close coroutine (closes the httpx.AsyncClient).  
- _url and _auth_headers (helpers to build API URLs and authentication headers).  
- _api_get and _api_post_json (HTTP helpers that raise on non-success and return parsed JSON).  
- _list_dm_channels (filters user channels by Discord types for DMs).  
- _get_bot_user_id (fetches and caches the bot's user id via users/@me).  
- _list_guild_text_channels (enumerates guilds and selects text channels by type).  
- _id_to_int, _format_username, _strip_leading_mentions (utility functions for id parsing and formatting).  
- get_updates coroutine (polls channels, applies offsets, filters/normalizes incoming messages).  
- send_message coroutine (chunks and posts textual messages, supports reply reference).  
- send_chat_action coroutine (posts typing indicator).  
- mark_read coroutine (no-op placeholder for read-marking).  
- send_audio_file coroutine (uploads audio as multipart with payload_json).  
- dependency on httpx.AsyncClient and standard json and pathlib APIs.

Key logic:
1. Initialization stores the provided token and base URL, creates an httpx.AsyncClient with a fixed timeout, and prepares an empty bot id cache.  
2. The enabled property simply checks whether a token string is present to allow conditional use of the bridge.  
3. Low-level API methods (_api_get and _api_post_json) construct full URLs, attach Bot authorization headers, perform requests, call raise_for_status to surface HTTP errors, and return parsed JSON or empty dicts for no content.  
4. Channel discovery for DMs calls users/@me/channels and filters channel entries by numeric type values representing DM-like channels.  
5. Guild channel discovery first lists guilds via users/@me/guilds, then queries each guild's channels and keeps channels whose type indicates standard text or announcement channels.  
6. The bot user id is fetched from users/@me, cached on success, and returned for use in mention detection to avoid repeated API calls.  
7. get_updates builds a list of channels from DM and optionally guild channels, tracks seen channel ids, and for each channel requests recent messages with a limit and an optional after parameter sourced from current offsets.  
8. Incoming message lists are sorted by numeric id using _id_to_int to order messages chronologically before processing and to compute the last seen id per channel for next_offsets.  
9. Message filtering excludes entries without a valid author or content and ignores messages flagged as sent by bots; mention detection uses the mentions array and the cached bot id.  
10. For guild messages where the bot is mentioned, leading mention tokens are stripped from content to produce a cleaner prompt text.  
11. Normalized DiscordMessage objects are created with formatted usernames produced by _format_username which prefers global_name and falls back to username#discriminator when appropriate.  
12. After processing channels, get_updates sorts the accumulated updates by numeric id and returns them along with updated per-channel offsets for subsequent polling.  
13. send_message enforces a maximum chunk size, attempts to split on the last newline before the limit for readability, and falls back to splitting at the hard limit if necessary; it posts each chunk and attaches a message_reference for the first chunk when replying.  
14. send_chat_action posts to the typing endpoint when the action equals "typing", while mark_read is implemented as a no-op because bots cannot mark messages read.  
15. send_audio_file validates the file path, constructs a payload_json field with caption and allowed_mentions, attaches the file under files[0] with audio/mpeg content type, posts the multipart request, and raises on non-successful responses.

---

## captain-claw-src/captain_claw/agent_session_mixin.py

Description:
1. This module defines AgentSessionMixin, a mixin that encapsulates session token accounting, message compaction, and runtime-flag synchronization for an agent.  
2. It provides utilities to count tokens using an optional provider and a safe fallback heuristic when provider counting fails.  
3. The mixin ensures per-message token metadata exists and can compute total token usage across a session.  
4. It formats conversation excerpts with truncation and total-character limits to prepare prompts for compaction summaries.  
5. The module offers both an LLM-driven summarization path using instruction templates and a deterministic fallback summary generator for resiliency.  
6. It implements destructive compaction that summarizes older messages, keeps recent context, updates compaction metadata, and persists the session.  
7. A non-destructive snapshot compaction routine performs the same summarization logic on a copied message list and returns compaction statistics.  
8. The mixin supports session memory protection toggles stored in session metadata and methods to enable or disable that protection.  
9. It can merge compacted memories from two parent sessions to create a new child session and emits monitoring/tool output throughout the process.  
10. The class also provisions isolated subagent child sessions for pipeline tasks, synchronizes runtime flags from session metadata, and exposes helpers to change pipeline and tracing modes.

Purpose:
1. The file exists to centralize and reuse session lifecycle mechanics required by agents, avoiding duplication across different agent implementations.  
2. It encapsulates token measurement and per-message bookkeeping so higher-level logic can make compaction and model-selection decisions based on accurate token accounting.  
3. By implementing both destructive and snapshot compaction, the mixin supports workflows that need to preview compaction results or actually reduce session memory.  
4. The LLM-integrated summarization path leverages instruction templates and guarded completions to produce compact conversation summaries while retaining a robust fallback path.  
5. Compaction logic is driven by configurable thresholds and ratios from the global configuration, enabling tunable memory management across deployments.  
6. The module records detailed compaction metadata to the session to assist auditing, monitoring, and potential undo/analysis operations.  
7. Procreation (merging) of sessions is provided so users or systems can create combined contexts from two existing sessions, with provenance recorded in metadata.  
8. Subagent context management ensures pipeline tasks can run in isolated or child sessions with controlled spawn depth, active-child caps, and execution-context defaults.  
9. Synchronizing runtime flags from session metadata allows per-session customization of pipeline behavior and monitoring verbosity without changing global runtime configuration.  
10. The mixin connects session-level settings to other subsystems (memory, model selection) by applying model choices or setting the active session in memory.  
11. It emits structured tool/monitoring messages during important operations to improve observability of compaction, procreation, and subagent provisioning.  
12. Overall, the module exists to provide a consistent, configurable, and resilient approach to session memory management and runtime configuration within the Captain Claw agent framework.

Key elements:
- AgentSessionMixin (class) — central mixin implementing session memory and flag helpers.  
- _count_tokens(text) — token counting with provider support and fallback heuristic.  
- _ensure_message_token_count(msg) — ensures a message dict has a token_count entry.  
- _session_token_count(messages=None) — totals tokens across a message list or current session.  
- _compact_role(role) — normalizes role labels for compaction output.  
- _format_compaction_messages(messages, max_total_chars, max_item_chars) — prepares truncated, size-limited conversation excerpts.  
- _fallback_compaction_summary(messages) — deterministic short summary generator for compaction fallback.  
- _summarize_for_compaction(messages) (async) — builds prompt and calls LLM completion with guards to produce a summary.  
- _limit_description_sentences(text, max_sentences) — sentence-capping utility for descriptions.  
- sanitize_session_description(text, max_sentences) — public wrapper for description normalization.  
- _fallback_session_description(session) — deterministic fallback session description builder.  
- generate_session_description(target_session=None, max_sentences) (async) — LLM-backed session description generator with fallback.  
- compact_session(force=False, trigger="manual") (async) — main destructive compaction routine that updates session, metadata and persists.  
- _compact_messages_snapshot(messages, trigger) (async) — non-destructive compaction returning new message list and stats.  
- is_session_memory_protected() — checks session metadata for memory protection.  
- set_session_memory_protection(enabled, persist) (async) — toggles protection metadata and persists.  
- procreate_sessions(parent_one, parent_two, new_name, persist) (async) — merges compacted memories to create a child session and persists.  
- ensure_pipeline_subagent_contexts(pipeline, task_ids) (async) — provisions per-task subagent sessions and execution_context defaults, may call session_manager.create_session.  
- _auto_compact_if_needed() (async) — convenience to trigger auto compaction when threshold exceeded.  
- _sync_runtime_flags_from_session() — loads pipeline and monitor runtime flags from session metadata and applies model selection.  
- refresh_session_runtime_flags() — public helper wrapper for runtime flag sync.  
- set_pipeline_mode(mode, persist) (async), set_planning_mode(enabled, persist) (async) — control pipeline execution mode.  
- set_monitor_trace_llm(enabled, persist) (async), set_monitor_trace_pipeline(enabled, persist) (async) — toggle monitoring trace options.  
- _add_session_message(...) — append a message to the session with token metadata and record it in memory.  
- External/dependent calls: get_config(), Message (captain_claw.llm), get_logger(), Session type hints, self.instructions.load/render, self._complete_with_guards, self.session_manager.create_session/save_session, self._emit_tool_output, self.memory, and model selection helpers (_session_model_selection, _apply_model_option, _apply_default_config_model_if_needed).

Key logic:
1. Token counting first attempts to use an injected provider's count_tokens method and falls back to a conservative length-based heuristic (len(text)//4) to ensure nonzero token estimates.  
2. Message-level token metadata is lazily populated by _ensure_message_token_count, which writes a token_count back into message dictionaries for later reuse.  
3. Formatting for compaction builds numbered, role-prefixed lines, trims internal whitespace, truncates individual items to a per-item char limit, and stops when a global max total character budget would be exceeded.  
4. Summarization uses instruction templates to construct system and user messages and invokes an async guarded completion call to an LLM, with exceptions triggering a deterministic fallback summary.  
5. Descriptive text normalization splits on sentence boundaries and caps the result to a configured maximum number of sentences to keep session descriptions concise.  
6. The compaction decision compares the session's total tokens to a threshold computed from configured max_tokens and a compaction_threshold; compaction proceeds only when the threshold is exceeded or when forced.  
7. When compacting, the algorithm iterates messages in reverse, accumulating token counts and ensuring a minimum number of recent messages are kept while respecting a target recent-token budget derived from a compaction_ratio.  
8. Old messages are summarized (via the summarization path), and a synthesized assistant message containing the summary plus compaction metadata is prepended to the kept recent messages; token counts and timestamps are updated accordingly.  
9. Session metadata for compaction counters, last trigger, before/after token counts, and message counts are updated and persisted through the session manager, and human-readable monitor output is emitted for observability.  
10. The snapshot compaction variant mirrors the destructive compaction flow but operates on a deep-copied list and returns the compacted list and statistics without mutating the original session.  
11. Procreation compacts each parent snapshot, merges the compacted message lists, creates a new child session via the session manager, sets child metadata documenting parents and stats, saves the child if requested, and emits stepwise tool output.  
12. Subagent provisioning walks a pipeline task graph, populates execution_context defaults (context id, spawn metadata, allowlists, timeouts), enforces spawn depth and active-child caps, and either assigns a virtual session id or creates a real child session using session_manager.create_session, tracking spawn state and errors.  
13. Runtime flag synchronization reads session.metadata (planning and monitor sections) to set in-memory pipeline_mode, planning_enabled, and tracing flags, updates the memory subsystem with the active session id, clears skill snapshot caches, and attempts to apply any session-specific model selection falling back to configuration defaults on failure.  
14. Several public async setters change pipeline and monitoring modes by updating session metadata timestamps and persisting through the session manager when requested.  
15. Throughout, the mixin coordinates with other agent subsystems via calls to self._emit_tool_output for monitoring, self.session_manager for persistence and creation, self.instructions for prompt templates, and self._complete_with_guards for LLM interactions, while using fallbacks and error handling to maintain resilience.

---

## captain-claw-src/captain_claw/cron_dispatch.py

Description:
1. This module implements cron scheduling, job execution, and cron history management for the application.  
2. It provides functions that emit monitoring events and chat-style history entries to both the UI and the session manager.  
3. The module resolves saved files for scripts and tools, enforcing a saved-root constraint and session-scoped directory conventions.  
4. It can enqueue and run scripts or tools inside a target agent session, temporarily switching the agent's active session and persisting tool output as session messages.  
5. A parser is included to parse the arguments for adding cron jobs, interpreting schedule tokens and distinguishing prompt, script, tool, and orchestrate kinds.  
6. There is a dedicated routine to run orchestrator workflows inline, creating a temporary SessionOrchestrator, loading a workflow, substituting variables, executing it, and shutting it down.  
7. The primary execute_cron_job function handles different job kinds, dispatching prompts, invoking scripts/tools, or running orchestrations, and it updates job status and next-run times.  
8. A background cron_scheduler_loop periodically polls for due jobs and invokes the executor for each due job.  
9. Throughout its operations the module logs events, manages a set of running job ids to avoid duplicates, and reports errors back to the UI.  
10. Error handling includes recording failures to job history and computing fallback next-run times when schedule computation is not possible.

Purpose:
The file centralizes cron-related responsibilities so scheduling decisions, job dispatching, execution, and history recording are implemented in one place. It exists to bridge stored cron job definitions in the session manager with runtime execution inside agent sessions and the UI monitoring surface. By providing saved-file resolution it enforces organization and containment rules for where scripts and tool files may be executed from, preventing paths outside the configured saved root. The module supplies higher-level primitives for enqueuing execution tasks (via enqueue_agent_task) while preserving session context and runtime flags so work runs under the correct agent session. It records structured monitor and chat events so cron activity appears both in tool-output streams and persistent cron job histories. Multiple cron job kinds are supported — prompts dispatched into sessions, shell scripts or tool runs executed in session context, and orchestrator workflows coordinating multiple agents. The orchestrate path is executed inline so the orchestrator component can manage parallelism while cron handles logging and history. Error handling and next-run computation ensure failures are recorded and jobs are rescheduled per their schedule or a safe fallback. The scheduler loop implements a lightweight polling mechanism suitable for embedding in the application loop without requiring an external cron service. The module avoids global mutable state by operating on a RuntimeContext object, making behavior explicit and testable. It interfaces with agent internals (token counting, guarded tool execution) so outputs are captured and saved back to sessions. Overall, it makes cron jobs first-class within the agent environment by integrating execution, persistence, monitoring, and safe file access.

Key elements:
- cron_monitor (function) — builds a simple payload and appends tool output to the UI for cron steps.  
- append_cron_history (async function) — forwards chat/monitor events to session_manager.append_cron_job_history.  
- cron_monitor_event (async function) — timestamped monitor event creator that records to UI and job history.  
- cron_chat_event (async function) — timestamped chat/history event creator for cron job messages.  
- resolve_saved_file_for_kind (function) — resolves and validates file paths inside the saved root; enforces category/session layout.  
- run_script_or_tool_in_session (async function) — resolves a file, composes a shell command, and enqueues execution inside a target session.  
- parse_cron_add_args (function) — parses raw /cron add arguments using shlex and parse_schedule_tokens to produce a kind and payload.  
- _run_orchestrate_cron (async function) — creates SessionOrchestrator, loads a workflow, prepares variable values, executes, and captures synthesis.  
- execute_cron_job (async function) — main job executor that routes by kind (prompt, script/tool, orchestrate), updates job status, and handles errors.  
- cron_scheduler_loop (async function) — background loop that polls get_due_cron_jobs and invokes execute_cron_job.  
- External dependencies / notable calls: get_logger, parse_schedule_tokens, compute_next_run, now_utc, to_utc_iso, schedule_to_text, truncate_history_text, CommandLane, normalize_session_id, agent.session_manager methods (load_session, save_session, append_cron_job_history, update_cron_job, get_due_cron_jobs), enqueue_agent_task, dispatch_prompt_in_session, SessionOrchestrator, agent._execute_tool_with_guard, agent._build_script_runner_command, ctx.ui methods (append_tool_output, print_message, set_runtime_status, append_tool_output, print_error).

Key logic:
Monitoring helpers build small payloads and route human-readable lines to the UI while also assembling structured events that are appended to per-job history via the session manager. Saved-file resolution first normalizes the session id, then canonicalizes the requested path; absolute paths are accepted as candidates but relative requests that begin with known categories are mapped into saved/<category>/<session>/..., while other relative requests are placed into default categories based on the requested kind. resolve_saved_file_for_kind computes candidate.resolve(), ensures the candidate is inside the saved base path, validates the category/session prefix, and rejects missing or non-file targets. Running a script/tool loads the target session, resolves the file path, attempts to derive a platform-aware runner command (falling back to a cd && ./name pattern), and defines an asynchronous inner _execute closure that performs the actual execution. The _execute closure may switch the global agent.session to the target session and refresh runtime flags, writes start messages to the session (including token counts), invokes the guarded shell tool via agent._execute_tool_with_guard, collects output or error, appends the output to the session and UI, and writes completion or failure messages back to session history. Script/tool runs are scheduled using enqueue_agent_task with a CRON lane so execution ordering and concurrency are controlled by the agent queue. Argument parsing for /cron add uses shlex.split, delegates schedule parsing to parse_schedule_tokens, converts schedule to textual form, then branches on the following token to produce structured payloads for prompt text, script/tool paths, or orchestrate workflow names. The orchestrate runner instantiates a temporary SessionOrchestrator configured from runtime config and the main agent, loads the named workflow, computes effective variable values by taking workflow defaults and overlaying provided cron variable values, executes the orchestrator to obtain a synthesis preview, records monitor/chat events, and ensures orchestrator.shutdown() is invoked. execute_cron_job guards against concurrent duplicates via ctx.cron_running_job_ids, determines the job kind, dispatches to the appropriate handler (dispatch_prompt_in_session, run_script_or_tool_in_session, or _run_orchestrate_cron), and sets success/queued flags accordingly. On success it logs and updates the job's last_run_at, next_run_at (via compute_next_run), last_status, and last_error; on failure it logs the error, records failure events, computes a fallback next-run time when necessary, and updates the job record as failed. The scheduler loop periodically sleeps for ctx.cron_poll_seconds, queries session_manager.get_due_cron_jobs with a limit, iterates over due jobs and calls execute_cron_job, and catches exceptions while supporting asyncio cancellation to stop cleanly.

---

## captain-claw-src/captain_claw/agent_context_mixin.py

Description:
1. This module defines AgentContextMixin, a collection of helper methods that assemble prompt and message context for model calls and manage related session-scoped context.  
2. It provides utilities to extract and merge URLs and domains from message text and tool outputs.  
3. The mixin normalizes and loads tool policy payloads from session and task metadata to control tool access.  
4. It maintains and initializes layered semantic memory and an optional deep (Typesense) index for long-term retrieval.  
5. Several "auto-capture" routines scan user and assistant text and certain tool calls to persist todos, contacts, scripts, and APIs into session-managed memory.  
6. The class discovers and registers built-in and plugin tools based on configuration and available plugin files.  
7. It constructs the system prompt and various injected context notes including memory continuity, semantic/deep memory, planning, todo, contacts, scripts, apis, and scale-progress notes.  
8. The mixin includes logic to normalize persisted tool call shapes for provider compatibility and to serialize tool calls for persistence.  
9. It contains provider-specific normalization that enforces strict assistant-tool message ordering required by some providers (notably OpenAI).  
10. The central build_messages method composes the final list of Message objects, performing token-budgeted selection, normalization, and bookkeeping of the last context window.

Purpose:
1. AgentContextMixin exists to centralize and encapsulate all logic required to assemble LLM input context for an agent, keeping message construction consistent across the codebase.  
2. It ensures that contextual signals—session history, tool outputs, semantic memory, and task planning—are combined and presented to the model in a controlled, token-budget-aware manner.  
3. The mixin prevents noisy or irrelevant data from polluting the prompt by filtering historical tool outputs, applying domain-aware URL selection, and shrinking the scan window when domain signals are absent.  
4. It supports session continuity by building compact memory continuity notes and optionally emitting debug telemetry about memory selection to external listeners.  
5. The auto-capture features reduce user friction by persistently saving salient items (todos, contacts, scripts, APIs) discovered in conversation or produced by tools, enabling later retrieval and injection.  
6. Provider compatibility code (normalizing tool call shapes and enforcing message ordering) allows the same session history and tool usage model to work across different LLM backends with differing protocol constraints.  
7. The layered memory initialization ties runtime configuration to concrete memory backends and gracefully degrades if memory services are unavailable, keeping agent initialization robust.  
8. Plugin discovery and registration enable extensibility by loading third-party tool implementations from configured directories, integrating them into the tools registry with metadata.  
9. The mixin also centralizes system prompt composition and skill injection, letting other components update or contribute skills without duplicating prompt-building logic.  
10. By performing token accounting and selective inclusion of messages, the mixin protects against exceeding model context limits while prioritizing critical content (latest user turn and scale-progress notes).  
11. The module records context window statistics back into session metadata so that downstream UI or telemetry can surface how context was constructed and pruned.  
12. Overall, AgentContextMixin exists to make the agent's LLM calls reproducible, efficient, and extensible while bridging between session storage, memory systems, tools, and LLM provider idiosyncrasies.

Key elements:
- AgentContextMixin (class): container for all context assembly and auto-capture methods.  
- _extract_urls(text) (static): finds unique URLs in appearance order.  
- _merge_unique_urls(*url_lists) (static): merges lists preserving first-seen order.  
- _normalize_tool_policy_payload(raw) (static): normalizes tool-policy dict shapes.  
- _session_tool_policy_payload(), _active_task_tool_policy_payload(planning_pipeline): load tool policy from session or task graph.  
- _extract_source_links(msg, content): extracts URLs from tool arguments and content with web-fetch exceptions.  
- _extract_mentioned_domains(text), _url_matches_domains(url, domains): domain extraction and matching helpers.  
- _collect_recent_source_urls(turn_start_idx, ...): collects recent source URLs with optional domain filtering.  
- _initialize_layered_memory(): initializes semantic memory and optional deep memory.  
- _build_todo_context_note(), _refresh_todo_context_cache(), _auto_capture_todos(...): todo injection and auto-capture.  
- _refresh_contacts_context_cache(), _build_contacts_context_note(), _auto_capture_contacts(...), _auto_capture_contacts_from_tool_call(...): contacts handling.  
- _refresh_scripts_context_cache(), _build_scripts_context_note(), _auto_capture_scripts(...), _auto_capture_scripts_from_tool_call(...): scripts memory handling.  
- _refresh_apis_context_cache(), _build_apis_context_note(), _auto_capture_apis(...), _auto_capture_apis_from_tool_call(...): APIs memory handling.  
- _build_semantic_memory_note(), _build_deep_memory_note(): integrate semantic and deep memory notes.  
- initialize(): agent initialization orchestration (provider, session, memory, tools, caches).  
- _register_default_tools(), _discover_plugin_tool_files(), _register_plugin_tools(): tool registration and plugin loading.  
- _build_system_prompt(): constructs base system prompt and optional skills section.  
- _build_tool_memory_note(): selects and formats compact memory continuity note.  
- _requires_strict_tool_message_order(), _normalize_session_tool_calls(), _serialize_tool_calls_for_session(), _normalize_selected_messages_for_provider(): tool call normalization and provider-specific ordering.  
- _build_messages(...): main routine to assemble and token-budget messages into final Message objects.  
- External dependencies referenced: get_config, get_provider, set_provider, Message, ToolCall, get_logger, Tool, create_layered_memory, DeepMemoryIndex, session_manager interface methods (load_last_active_session, get_or_create_session, list_contacts, create_todo, etc.), instructions.render/load.

Key logic:
1. URL and domain utilities extract candidates from message text and tool argument dictionaries, merge them without duplication, and optionally filter by domain to keep prefetching and planner context focused.  
2. Tool policy normalization inspects arbitrary payload shapes and returns a canonical dict with allow/deny/also_allow lists or None when absent; this is used for both session- and task-scoped policies.  
3. Layered memory initialization checks configuration and session-manager paths, then attempts to construct a semantic memory object and, conditionally, a Typesense-backed deep memory index, logging and degrading to None on failures.  
4. Auto-capture routines use conservative regular expressions to detect todos, contact declarations, script mentions, and API mentions in user and assistant text; matches lead to session-manager calls to create or update records.  
5. Tool-call-driven auto-capture inspects tool arguments for write/send_mail/web_fetch usages to discover scripts, contact emails, or API endpoints and avoid duplicates by searching existing records and incrementing usage counters when appropriate.  
6. Default tool registration consults configuration to instantiate and register a curated set of tool classes; plugin discovery loads Python files from configured directories and either calls a register_tools(module) hook or instantiates Tool subclasses found in the module.  
7. System prompt construction uses a templating instructions object to render a base prompt and optionally appends skill-provided sections when present.  
8. Tool memory note selection ranks skipped historical tool messages by tokenized term overlap with the query and by recency, truncates long snippets, and emits a debug signature to the UI when selection changes.  
9. Message composition begins with a system message and then assembles candidate messages from session history and generated context notes (memory, semantic, deep, planning, list tasks, scale progress, todo, contacts, scripts, apis).  
10. A token-budgeting loop iterates over candidates in reverse chronological order, measuring token counts via internal token-count helpers and always ensuring inclusion of the latest user turn and critical scale-progress notes while dropping lower-priority items when over budget.  
11. Historical tool messages can be filtered by index; filtered tool responses are collected into a skipped list used for the memory continuity note and their tool_call ids are tracked so corresponding assistant tool_calls can be stripped to avoid orphan references.  
12. Provider compatibility normalization enforces an assistant/tool message pairing model required by some providers: it consolidates tool_calls on assistant messages, keeps tool messages that match pending tool_call ids, converts orphaned tool messages into assistant content prefixed with a tool context tag, and clears incomplete tool chains.  
13. Tool call normalization converts persisted or in-memory ToolCall objects into a consistent JSON-friendly shape expected by providers and for session persistence, serializing argument dicts into JSON strings when needed.  
14. After selection and normalization, candidate messages become Message objects with appropriate role, content, and tool metadata; the mixin records a last_context_window summary including token budgets, included/dropped counts, and whether various context notes were used.  
15. Throughout, the mixin emits structured logs and tool output debug events for memory selection and deep memory usage, and it gracefully handles exceptions from optional subsystems so agent initialization and message building remain resilient.

---

## captain-claw-src/captain_claw/cli.py

Description:
1. This module implements a TerminalUI class that provides a command-line interface framework for the Captain Claw application.  
2. It initializes terminal behavior, readline-based history and completion, and stores UI-related runtime state and buffers.  
3. The class supports a sticky footer with a fixed system/status area and an optional split monitor view showing chat and raw tool output.  
4. Multiple print_* methods handle rendering of user, assistant, system, tool messages, token usage, errors, warnings, and other informational views.  
5. Monitor rendering logic computes layout, wraps text to pane widths, slices scrolled views, and writes directly to the terminal using ANSI cursor controls.  
6. The file contains logic to append and format tool outputs, including special summarization for web fetch results and size-limited buffering.  
7. Input handling includes a prompt method, support for streaming assistant output (begin/end stream), and ESC key capture using termios/asyncio on POSIX.  
8. A comprehensive handle_special_command method parses slash-commands (/session, /cron, /todo, /contacts, etc.) into structured return tokens or triggers printed help/errors.  
9. Footer rendering is rate-limited with FPS constraints and composes contextual status lines showing token usage, timing, session, and model details.  
10. Utility helpers manage scroll offsets, persistence of history to a file, and some provider/tool-specific behaviors through configuration access.

Purpose:
1. The primary role of this file is to provide a terminal-based user interface layer for interacting with the Captain Claw runtime.  
2. It exists to centralize all terminal formatting, input prompting, and user-visible status presentation so higher-level runtime logic can remain UI-agnostic.  
3. By encapsulating monitor and footer rendering, it enables a consistent split-screen experience with live tool trace output alongside conversational text.  
4. The TerminalUI maps many user-facing slash commands into machine-readable action tokens, simplifying how the command dispatcher interprets interactive input.  
5. Readline integration and history persistence improve the interactive experience by enabling tab completion, history recall, and durable session command logs.  
6. Streaming helpers and assistant output state management ensure the UI can render partial LLM outputs while preserving footer/system updates without visual corruption.  
7. Layout and wrapping helpers compute pane sizes from terminal dimensions and handle narrow-terminal fallbacks so the UI degrades gracefully.  
8. The file includes utility logic to truncate, summarize, and bound tool output buffers to prevent runaway memory usage in long-lived monitor mode.  
9. It also provides small user-facing conveniences like confirmation prompts, error/warning/success formatting, and compact session/model/cron printing utilities.  
10. Footer and system panel composition conveys runtime telemetry (tokens, durations, model selection) to users for transparency and debugging.  
11. Integration points (configuration access and occasional imports of agent tool mixins) connect the UI to other runtime components without embedding business logic.  
12. Overall, the module exists to offer a robust, interactive terminal front end that supports both conversational flows and developer-focused monitoring/tracing needs.

Key elements:
- TerminalUI class (primary UI implementation and state container).  
- __init__ (initializes config, buffers, layout flags, and calls _setup_readline).  
- _setup_readline (attempts to configure readline, history file, and completion).  
- _special_commands (list of slash-commands for completion).  
- print_welcome, print_help (welcome and command help rendering).  
- print_message, print_error, print_warning, print_success (role-aware printing helpers).  
- print_tool_call, print_tool_result, append_tool_output (tool output formatting and monitor integration).  
- _format_monitor_tool_body, _summarize_text, _split_web_fetch_payload (web-fetch specific summarization helpers).  
- Monitor rendering: _layout_metrics, _monitor_pane_layout, _wrap_plain_text, _slice_scrolled_lines, _render_monitor_view.  
- Scroll management: scroll_monitor_pane, _monitor_scroll_limits, _clamp_monitor_scroll_offsets, get_monitor_scroll_state.  
- Footer and status: _render_system_panel, _render_footer, print_status_line, set_runtime_status, set_thinking.  
- Streaming and prompt: begin_assistant_stream, end_assistant_stream, complete_stream_line, prompt.  
- History persistence: _history_file path and _save_history (registered via atexit).  
- Input parsing: handle_special_command (parses and validates many slash-commands, returns encoded actions).  
- ESC capture: can_capture_escape and wait_for_escape (termios/tty + asyncio reader).  
- Configuration and logging dependencies: get_config and get_logger usage, plus dynamic import of AgentToolLoopMixin inside append_tool_output.

Key logic:
1. Initialization establishes UI behavior by loading configuration, setting flags for sticky footer/ANSI, and creating buffers and scroll offsets.  
2. _setup_readline tries to import and configure readline, register a completer based on _special_commands, and persist history to a file on exit.  
3. Printing functions branch on monitor mode and sticky footer: when monitor mode is active they append to internal buffers and call _render_monitor_view, otherwise they print directly to stdout.  
4. The monitor renderer computes layout metrics from terminal size, determines left/right pane widths, wraps buffered text to pane widths, extracts the visible slice given scroll offsets, and writes rows with ANSI cursor positioning.  
5. Text wrapping uses textwrap.wrap with controlled options to avoid dropping whitespace and to break long words when necessary; trailing newline behavior is preserved.  
6. append_tool_output formats a header and body for each tool invocation, optionally summarizes web fetch outputs, clips long outputs, appends to the tool buffer, and triggers a thinking indicator for non-silent tools.  
7. The thinking indicator and runtime status are shown in the system panel; set_thinking updates inline text and forces rendering of the system panel immediately to provide real-time feedback.  
8. Footer rendering composes two status lines with left/right pieces, using _compose_footer_line to right-align metadata, and enforces a minimum interval between renders to throttle updates.  
9. handle_special_command parses slash-prefixed strings into normalized commands, validates arguments, constructs JSON payloads when needed, and returns uniform action tokens that the caller can interpret; invalid usage triggers printed errors and returns None.  
10. Scrolling operations compute page steps relative to content rows, clamp offsets within computed maxima, update internal offsets, and re-render the monitor view when running in sticky footer mode.  
11. Assistant streaming mode toggles an internal flag so output can be streamed into the chat pane without immediate footer refreshes; end_assistant_stream flushes and triggers a final footer render.  
12. POSIX ESC capture installs an asyncio reader on stdin in cbreak mode to resolve an ESC key press into a Future result, and restores terminal settings on completion or cancellation.

---

## captain-claw-src/captain_claw/google_oauth_manager.py

Description:
1. This module defines a GoogleOAuthManager class that manages Google OAuth token storage and refresh.  
2. It interacts with a SessionManager to persist tokens and Google user profile data into an app_state SQLite table.  
3. The manager caches tokens in memory and will return the cached copy when it is still valid.  
4. When stored tokens are expired, it attempts to refresh the access token using stored refresh credentials.  
5. The module exposes methods to load, store, and revoke tokens, as well as to store and retrieve user profile information.  
6. It can build an authorized_user credentials dict suitable for Vertex/LiteLLM when client credentials are available in configuration.  
7. Revocation logic tries the refresh token first and falls back to the access token where appropriate.  
8. JSON serialization/deserialization is used for persistent storage of tokens and user info, with defensive error handling on failure.  
9. External helper functions (refresh_access_token, revoke_token, fetch_user_info) are invoked for network operations.  
10. Logging is used to emit warnings and informational messages for refresh, failure, and disconnect events.

Purpose:
This file centralizes the lifecycle management of Google OAuth tokens for the application so other components can obtain valid credentials without duplicating refresh and storage logic. It exists to provide a single asynchronous interface that handles caching, persistence, refresh, and revocation of OAuth tokens while integrating with the application's SessionManager-backed app_state. By persisting tokens and user info to app_state, the manager enables tokens to survive process restarts and be shared across sessions. It also packages tokens into the specific credentials format required by Vertex/LiteLLM, bridging the gap between raw OAuth tokens and provider-specific credential expectations. The class encapsulates error-handling policies, such as returning None on deserialization or refresh failures and logging warnings rather than raising in most cases, which keeps callers simple and robust. The manager avoids unnecessary network calls by using an in-memory cache when possible, reducing latency for credential retrieval. It updates cached user profile data opportunistically after successful refreshes so downstream UI or logic can present fresh account information. Revocation behavior is implemented as best-effort to clear server-side access when disconnecting, while also ensuring local state is cleared. The file enforces dependency on application configuration for client_id and client_secret to produce Vertex credentials, preventing misuse when those values are absent. Being written with async methods, it integrates cleanly into asynchronous application flows. Overall, it provides a focused, reusable component that implements the OAuth token lifecycle concerns needed by the rest of the project.

Key elements:
- GoogleOAuthManager (class; orchestrates token lifecycle and storage)  
- __init__ (constructor; accepts SessionManager and initializes cache)  
- get_tokens (async; loads tokens from session storage, deserializes, refreshes if expired)  
- store_tokens (async; persists tokens JSON to app_state and updates in-memory cache)  
- store_user_info (async; persists Google user profile JSON to app_state)  
- get_vertex_credentials (async; returns authorized_user credentials dict using config client_id/client_secret)  
- get_user_info (async; returns cached user profile by reading app_state)  
- is_connected (async; reports whether valid or refreshable tokens exist)  
- disconnect (async; revokes tokens and clears stored OAuth state)  
- _try_refresh (async; attempts refresh via refresh_access_token, stores fresh tokens, updates user info)  
- External calls/dependencies: get_config (config access), refresh_access_token, revoke_token, fetch_user_info (network helpers), GoogleOAuthTokens (type with from_dict/to_dict/is_expired/to_vertex_credentials_json), SessionManager methods get_app_state/set_app_state/delete_app_state, logging via get_logger

Key logic:
1. Token retrieval first checks an in-memory cached GoogleOAuthTokens instance; if present and not expired it is returned immediately to avoid I/O.  
2. If no valid cache exists, get_tokens reads a JSON blob from session app_state using a predefined STATE_KEY_TOKENS key and attempts to deserialize into GoogleOAuthTokens.  
3. Deserialization failures are caught, logged as warnings, and result in returning None to indicate no usable tokens.  
4. When deserialized tokens report as expired, get_tokens delegates to _try_refresh to obtain fresh access credentials; failures in refresh return None.  
5. _try_refresh requires a refresh_token and application client credentials from config; if either is missing it logs and aborts the refresh attempt.  
6. On successful refresh, _try_refresh persistently stores the fresh tokens via store_tokens and tries to fetch and persist updated user profile info, treating user-info fetch failures as non-critical.  
7. store_tokens serializes the GoogleOAuthTokens to JSON, writes it to app_state with set_app_state, and updates the in-memory cache.  
8. get_vertex_credentials uses the tokens returned by get_tokens and the configured client_id/client_secret to build a Vertex-compatible authorized_user credentials JSON via GoogleOAuthTokens.to_vertex_credentials_json; it returns None when tokens or config are missing.  
9. disconnect performs best-effort token revocation by calling revoke_token on the refresh token if available, otherwise on the access token, then clears the cache and deletes both token and user app_state entries.  
10. is_connected is a lightweight convenience that treats presence of tokens and a refresh_token as an indicator of a connected state.  
11. get_user_info simply reads the stored user JSON from app_state and returns a parsed dict or None on error.  
12. Throughout the flow, the module uses logging to record important events (successful refresh, failed refresh, disconnection) and avoids raising exceptions for recoverable OAuth lifecycle issues, preferring to return None so callers can handle absent credentials.

---

## captain-claw-src/captain_claw/remote_command_handler.py

Description:
1. This module provides unified remote command and message handling for chat platforms like Telegram, Slack, and Discord.  
2. It defines helper functions to format recent session history and active configuration text for remote responses.  
3. A remote_help_text helper composes a platform-specific help listing from command specs on the runtime context.  
4. The core function handle_remote_command parses incoming command text, routes many application-specific commands, and sends text replies via a provided send_text callback.  
5. handle_remote_command supports commands for session management, pipeline mode, skills, scripts, to-dos, contacts, APIs, orchestration, and configuration inspection.  
6. It interacts extensively with the agent and its session_manager to query, create, update, and delete domain objects.  
7. Per-platform dispatch is implemented in handle_platform_message which adapts raw platform messages using PlatformAdapter and mediates monitoring and permission checks.  
8. handle_platform_message strips bot mentions from slash commands, enforces approved user pairing, and distinguishes slash commands from normal chat messages.  
9. Slash commands are executed through handle_remote_command wrapped in adapter.run_with_typing to show typing status and to forward assistant output back to the platform.  
10. The module includes robust error handling that logs errors, reports handler failures to the monitoring system, and sends error messages back to the chat when possible.  

Purpose:
This file centralizes the logic for interpreting and executing remote chat commands so platform-specific adapters do not need to implement command semantics.  
It exists to map textual slash commands and normal chat messages into operations on the agent, its session manager, and other core services.  
By providing format helpers, it standardizes how session history and configuration are presented to remote users.  
It delegates execution of prompts and long-running tasks to prompt_execution utilities while handling immediate command responses itself.  
The handler also enforces platform-level constraints such as guild mention requirements for Discord and pairing/approval for unknown users.  
It integrates monitoring hooks via PlatformAdapter.monitor_event to record incoming messages and handler errors.  
Command parsing is centralized so new commands or command translations can be added in one module.  
The module coordinates skill installation, invocation, and searching by calling agent methods and returning human-readable summaries.  
It manipulates persistent artifacts (sessions, scripts, todos, contacts, APIs) through the agent.session_manager and surfaces results to the user.  
For chat flows it orchestrates typing indicators, assistant text streaming, and optional audio delivery via adapter callbacks.  
Error handling and monitoring in this layer minimize exposure of internal errors to platform clients and ensure operator visibility.  
Overall, it provides a stable translation layer between external chat protocols and the application's agent-centric runtime operations.  

Key elements:
- format_recent_history (formats a compact text summary of recent session messages).  
- format_active_configuration_text (renders active model, workspace, pipeline and guard settings).  
- remote_help_text (builds help text from ctx.telegram_command_specs for a given platform label).  
- handle_remote_command (async function that parses and executes many slash commands; primary command dispatcher).  
- handle_platform_message (async function that adapts platform messages, enforces pairing, and routes slash vs normal chat).  
- PlatformAdapter (external adapter used for sending, monitoring, marking read, pairing, typing, and audio delivery).  
- truncate_chat_text (helper imported from platform_adapter to truncate previews used in monitoring).  
- get_config (configuration accessor used by formatting helpers).  
- log (logging facility used in exception handling).  
- enqueue_agent_task and run_prompt_in_active_session (prompt_execution utilities used to run orchestrations and dialogue tasks).  
- SessionOrchestrator (instantiated for orchestration requests within handle_remote_command).  
- agent and agent.session_manager (used extensively for session, skills, scripts, todos, contacts, and APIs operations).  
- JSON parsing (json.loads used to accept structured payloads for several commands).  
- adapter.run_with_typing, adapter.send, adapter.monitor_event, adapter.mark_read, adapter.pair_unknown_user, adapter.maybe_send_audio_for_turn (adapter methods used to interact with platforms and report status).  

Key logic:
The module first defines small formatters that produce human-readable summaries of session history and active configuration for remote replies.  
handle_remote_command lowercases and trims incoming raw_text, handles built-in short commands like /start and /help, and delegates many structured commands through a ui.handle_special_command hook.  
When ui.handle_special_command returns special tokens, the dispatcher interprets them to perform actions such as toggling pipeline modes, orchestrating tasks, or mapping to internal verbs for skills and resource management.  
For orchestrate requests it builds a SessionOrchestrator and enqueues its orchestration call via enqueue_agent_task, then sends the orchestrator's response back to the user and shuts it down.  
Skill-related flows parse JSON payloads or argument strings, support search/install/invoke flows, and either return immediate text results or transform invocation responses into prompts executed in the active session.  
Session management commands create, select, rename, clear, compact, and inspect sessions by calling agent.session_manager methods and then informing the requesting user of outcomes.  
To-do, contacts, scripts, and APIs are each handled by a group of commands that parse payloads or inline arguments, call the appropriate session_manager CRUD methods, and render summary lines describing the resulting data.  
Input that requires updating records often uses shlex splitting to parse key=value pairs, filters them against valid field names, and passes the resulting kwargs to update_* methods on the session manager.  
When a slash command is unhandled for remote platforms the function explicitly responds that the command requires the local console, preventing accidental exposure of local-only operations.  
handle_platform_message creates a PlatformAdapter for the incoming message, performs platform-specific checks (e.g., Discord guild mention requirement), marks the message as read, and emits monitoring events with a truncated preview.  
It enforces user approval by checking state.approved_users and triggers pairing for unknown users; it also strips @BotName suffixes from slash commands to normalize command tokens.  
Depending on whether the message is a slash command or normal chat, the handler either runs handle_remote_command (wrapped in adapter.run_with_typing) or starts a prompt run via run_prompt_in_active_session, wiring adapter callbacks to stream assistant text and optionally send audio; all of this is guarded by try/except logic that logs errors, reports handler_error events, and attempts to notify the user of failures.

---

## captain-claw-src/captain_claw/agent.py

Description:
1. This module defines the Agent class which orchestrates runtime behavior for Captain Claw.  
2. Agent composes many mixins to provide features like orchestration, file operations, context management, guarding, model interfacing, pipeline control, reasoning, session handling, skills, and tool loops.  
3. The constructor accepts optional LLM provider and several callback hooks and then configures the tool registry, runtime and workspace paths, and a session manager.  
4. The agent initializes usage tracking buckets, monitoring flags, instruction loading, and other runtime bookkeeping such as provider override and model detail caches.  
5. Utility methods create empty usage containers and accumulate token usage from provider responses.  
6. Helper methods forward runtime status and inline "thinking" messages to configured callbacks while protecting against callback exceptions.  
7. A small helper determines monitor-only tool names that should not be added to model context.  
8. Tool output handling can record tool outputs into the active session, emit pipeline trace payloads when configured, and call an external tool output callback.  
9. The agent exposes an asyncio cancellation event intended for external UI layers to cancel long-running orchestrations.  
10. Overall, the file focuses on wiring runtime components, tracking resource usage, and mediating interactions among tools, sessions, and UI callbacks.

Purpose:
This file exists to centralize and encapsulate the top-level orchestration responsibilities of an Agent instance within the Captain Claw project. It provides a single class that wires together many orthogonal capabilities through mixins so that higher-level flows (planning, tool execution, session management) can rely on a consistent runtime surface. The constructor sets up dependencies such as the LLM provider, tool registry, session manager, and resolved workspace paths so other components do not need to duplicate that configuration logic. Usage accounting helpers are included so token consumption can be tracked per-turn and aggregated globally for reporting or limits. Callback forwarders (status, thinking, tool output, approval) let UI or integration layers receive incremental updates without coupling the orchestration logic to specific presentation code. The monitor-only tool name filter prevents certain tools from polluting model context, supporting observable tracing without affecting reasoning. The file registry and instruction loader initialization enable consistent cross-task file handling and instruction resolution for multi-step workflows. Cancellation support via an asyncio.Event gives the UI a mechanism to interrupt loops gracefully. The module also stores runtime flags and caches (e.g., pipeline mode, planning toggle, provider override, model details) that influence orchestration behavior across different runs. By composing behavior through mixins, this Agent class remains extensible and focused on coordination while delegating specialized behaviors to their respective mixins.

Key elements:
- Agent class (main orchestrator composed from multiple mixins).  
- __init__ (constructor) (initializes provider, callbacks, tools, paths, session manager, flags, and caches).  
- _empty_usage (static method) (creates a token usage bucket).  
- _is_monitor_only_tool_name (static method) (normalizes and checks if a tool is monitor-only).  
- _accumulate_usage (static method) (adds prompt/completion/total token counts into a target).  
- _finalize_turn_usage (method) (persists last turn usage and aggregates totals).  
- _set_runtime_status (method) (forwards status strings to status_callback safely).  
- _emit_thinking (method) (forwards inline reasoning/thinking updates to thinking_callback safely).  
- _emit_tool_output (method) (records certain tool outputs into session and calls tool_output_callback; emits pipeline trace messages when enabled).  
- tools (ToolRegistry instance obtained via get_tool_registry).  
- session_manager (Session manager obtained via get_session_manager).  
- cancel_event (asyncio.Event used to cancel orchestrations).  
- instructions (InstructionLoader instance).  
- External dependencies (get_config, FileRegistry, InstructionLoader, LLMProvider, get_session_manager, get_tool_registry, Session, Path, asyncio).

Key logic:
1. During initialization the Agent sets provided callbacks and the LLM provider reference, then acquires the global tool registry and applies the approval callback to it.  
2. The runtime base path is resolved from the current working directory and the workspace path is derived via configuration to determine where file operations should execute.  
3. The tools registry is informed of the runtime workspace so tools that operate on files can resolve paths consistently.  
4. A session manager is fetched and stored; the active session begins as None until session lifecycle methods (in mixins) create or attach one.  
5. The agent sets up token usage tracking with empty buckets for last and total usage and holds a dictionary for context window measurements and other debug signatures.  
6. Monitoring flags and pipeline mode settings are configured from provided configuration values so tracing and pipeline behavior can be toggled at runtime.  
7. _empty_usage returns a zeroed token count map; _accumulate_usage reads numeric prompt/completion values, computes totals, and safely accumulates them into target totals.  
8. _finalize_turn_usage assigns the provided turn usage to last_usage and invokes _accumulate_usage to update the persistent total_usage.  
9. _set_runtime_status and _emit_thinking simply invoke the configured callbacks with try/except around the calls to prevent callback exceptions from bubbling into orchestration logic.  
10. _is_monitor_only_tool_name normalizes a tool name string and checks membership in a fixed set of tool identifiers that are treated as trace/monitor-only.  
11. _emit_tool_output first checks for special tool names (planning, task_contract, task_rephrase, completion_gate) and if present, appends the raw output to the session as a tool message and optionally creates a pipeline_trace payload when pipeline tracing is enabled.  
12. After session recording, _emit_tool_output will call the external tool_output_callback with the tool name, arguments, and output, again guarding the call in a try/except to avoid propagation of errors to the orchestrator.

---

## captain-claw-src/captain_claw/slack_bridge.py

Description:
1. This module implements a minimal Slack Web API bridge focused on direct message polling and message sending.  
2. It defines a SlackMessage dataclass that normalizes incoming Slack payloads with fields for channel id, message timestamp, user id, username, text, and optional thread timestamp.  
3. The SlackBridge class wraps an httpx.AsyncClient and the Slack API base URL and token to perform authenticated asynchronous HTTP requests.  
4. It centralizes low-level request logic in helper methods that build URLs, headers, and perform GET/POST requests while validating Slack's "ok" response field.  
5. The bridge maintains an in-memory user ID → display name cache to reduce repeated users.info calls.  
6. A paginated listing of IM channels is implemented to discover direct-message conversations via conversations.list.  
7. The get_updates method retrieves conversation history per DM, filters out non-user and bot messages, sorts by timestamp, and returns normalized SlackMessage objects plus updated per-channel offsets.  
8. Sending messages is handled by splitting large texts into safe-sized chunks and posting each chunk to chat.postMessage, optionally in a thread.  
9. The module implements best-effort helpers for signaling typing/read state using conversations.mark and a method for uploading audio files to Slack via files.upload.  
10. Error handling propagates API errors for GET/POST helper calls while some higher-level interactions swallow exceptions to provide best-effort behavior.

Purpose:
This file exists to encapsulate all direct interactions with the Slack Web API required by a DM-first bot workflow. It centralizes connection configuration (token and base URL) and the httpx.AsyncClient lifecycle so higher-level components do not need to manage HTTP details. The SlackMessage dataclass provides a simple normalized structure that other parts of the application can consume consistently. Username resolution and caching reduce redundant network calls and present human-friendly names to the rest of the system. The paginated conversation listing and history retrieval implement the polling semantics needed to detect new direct messages across multiple IM channels. get_updates returns both new messages and updated offsets so callers can persist and resume polling state. The send_message chunking logic exists to avoid hitting Slack message size limits and to preserve message structure by preferring splits at newlines. Best-effort methods like send_chat_action and mark_read provide UX-friendly behavior while avoiding hard failures when the Slack API lacks stable endpoints for typing. The send_audio_file method enables sending local MP3 files as Slack uploads and performs basic file validation before attempting to upload. Centralizing Slack API error checking in _api_get and _api_post ensures consistent error semantics across all high-level operations. Overall, the module is designed to be a small, dependable adapter that exposes a simple async interface for polling, sending, and basic channel operations without embedding business logic or state management beyond username caching and per-channel offsets.

Key elements:
- SlackMessage (dataclass) — normalized incoming message payload structure.  
- SlackBridge (class) — main adapter encapsulating Slack interactions.  
- __init__ (SlackBridge) — initializes token, api_base_url, httpx.AsyncClient, and user cache.  
- enabled (property) — boolean indicating presence of a token.  
- close (async method) — closes the underlying httpx client.  
- _url, _headers (helpers) — construct endpoint URL and Authorization header.  
- _api_get, _api_post (async helpers) — perform HTTP GET/POST, validate response JSON and Slack "ok" field.  
- _resolve_username (async method) — resolves user display name via users.info and caches results.  
- _list_dm_channels (async method) — paginates conversations.list to enumerate direct-message channels.  
- _ts_to_float (static) — safe conversion of Slack timestamp strings to float.  
- get_updates (async method) — polls conversations.history, filters and sorts messages, returns SlackMessage list and offsets.  
- send_message (async method) — chunks large text and posts via chat.postMessage, supports thread replies.  
- send_chat_action (async method) — best-effort typing signal implemented via conversations.mark.  
- mark_read (async method) — best-effort mark read via conversations.mark.  
- send_audio_file (async method) — validates Path and uploads file via files.upload.  
- External dependency: httpx.AsyncClient (for async HTTP).  
- Slack endpoints used: conversations.list, conversations.history, users.info, chat.postMessage, conversations.mark, files.upload.

Key logic:
1. Initialization records the token and API base URL, constructs an AsyncClient with a 40-second timeout, and prepares an empty username cache.  
2. The enabled property is a simple truth test on the configured token to allow callers to skip Slack operations when no token is present.  
3. Low-level request methods _api_get and _api_post centralize HTTP calls, call response.raise_for_status(), parse JSON, ensure the payload is a dict, and require payload["ok"] to be True; otherwise they raise RuntimeError.  
4. URL and header construction helpers ensure consistent Authorization headers and normalized endpoint paths for all requests.  
5. Username resolution checks the cache first, then calls users.info; it extracts display_name, real_name, or name in that order and caches empty strings on failure to avoid repeated lookups.  
6. The DM channel enumerator _list_dm_channels loops with a cursor to call conversations.list repeatedly, collects channel dicts, and respects Slack pagination via response_metadata.next_cursor.  
7. get_updates takes an offsets map and an optional per-channel limit, lists DM channels, and for each channel requests conversation history with optional oldest param to limit returned messages.  
8. Messages from history are normalized by ensuring dict shape, filtered to skip empty text, missing user, and subtypes like bot_message, message_changed, and message_deleted, and are converted into SlackMessage objects with resolved usernames.  
9. Timestamps are handled by _ts_to_float to allow sorting and comparison; get_updates computes last_seen_ts per channel and returns next_offsets to let callers persist polling state.  
10. send_message implements a chunking algorithm with a max_len of 3500 characters: it prefers to split at the last newline before the limit but falls back to a hard split if that newline is too early, then posts each chunk and attaches thread_ts only for the first chunk when replying.  
11. send_chat_action and mark_read are implemented as best-effort operations that call conversations.mark and swallow exceptions to avoid failing the caller when Slack lacks stable typing endpoints.  
12. send_audio_file validates the provided file path (exists and is a file), opens it in binary mode, and uploads it as "audio/mpeg" using files.upload with appropriate metadata fields; it raises FileNotFoundError if validation fails.

---

## captain-claw-src/captain_claw/deep_memory.py

Description:
1. This module provides a Typesense-backed deep memory implementation for long-term searchable content.  
2. It defines a DeepMemoryResult dataclass that represents a single search hit with metadata like doc_id, source, path, snippet, scores, and timestamps.  
3. A collection schema template for Typesense is declared to specify fields, facets, token separators, and default sorting.  
4. Helper functions include a deterministic short-hash generator for IDs and a line-based overlapping text chunker used to split documents.  
5. The DeepMemoryIndex class encapsulates configuration, a lazy httpx.Client, and methods to manage a Typesense collection.  
6. Indexing methods include index_document for auto-chunking and embedding text, index_batch for bulk upserts, and an internal _upsert_batch that sends JSONL to Typesense.  
7. An embedding helper _embed invokes a provided embedding_chain when enabled to compute vector representations.  
8. Search supports hybrid BM25 and optional vector queries, converting Typesense hits into DeepMemoryResult objects.  
9. A build_context_note method formats search results into a text block suitable for LLM prompt injection along with a debug block.  
10. Deletion helpers and a close method complete the lifecycle by allowing document removal and HTTP client shutdown.  

Purpose:
1. The file exists to provide a persistent, long-term archive layer for searchable content that complements an in-memory or SQLite-backed semantic memory.  
2. It centralizes Typesense collection management so the rest of the application can index, search, and delete long-term documents without dealing with HTTP details.  
3. By handling chunking and optional embedding, it ensures large documents are split into consistent chunks that align with other memory layers.  
4. The auto-embedding integration lets the index store vector representations when an embedding chain is available, enabling hybrid text + vector search.  
5. Its upsert and batch indexing logic provide efficient ingestion paths for both programmatic calls and manual tool-based indexing.  
6. Search results are normalized to a consistent dataclass so callers receive typed results with combined scoring and metadata.  
7. The build_context_note method exists to produce concise context snippets that can be injected into LLM prompts without callers needing to format the results.  
8. Ensure_collection abstracts collection creation and schema management, including adding an embedding field if dimensions are configured.  
9. Error handling around HTTP calls and embeddings is conservative: failures in embedding or remote requests are logged and often result in empty fallbacks.  
10. Delete helpers let higher-level components purge documents either by a doc_id or arbitrary Typesense filters.  
11. A lazy HTTP client and a close method manage network resources so the index can be long-lived without leaking connections.  
12. Overall, the module exists to offer a reusable, testable interface for long-term searchable memory backed by Typesense for the agent or application.  

Key elements:
- DeepMemoryResult (dataclass for search hit metadata).  
- _COLLECTION_SCHEMA_TEMPLATE (Typesense collection schema template dict).  
- _hash_id(text) (short deterministic SHA1-based ID generator).  
- _chunk_text(text, chunk_chars, chunk_overlap_chars) (line-based overlapping chunker).  
- DeepMemoryIndex (main class encapsulating Typesense interactions and memory logic).  
- DeepMemoryIndex.__init__ (stores config: host, port, api_key, collection_name, embedding dims, chunk sizes, embedding_chain).  
- DeepMemoryIndex._get_client (lazy httpx.Client creator with Typesense headers).  
- DeepMemoryIndex.ensure_collection (checks/creates Typesense collection and schema).  
- DeepMemoryIndex.index_document (auto-chunks text, builds docs, optionally embeds, upserts).  
- DeepMemoryIndex.index_batch (accepts prebuilt documents, optionally embeds missing vectors, upserts).  
- DeepMemoryIndex._upsert_batch (JSONL upsert to Typesense import endpoint and success counting).  
- DeepMemoryIndex._embed (uses provided embedding_chain.embed_batch when enabled; returns vectors or empty on failure).  
- DeepMemoryIndex.search (hybrid BM25 + optional vector search, converts hits to DeepMemoryResult).  
- DeepMemoryIndex.build_context_note (formats top search hits into a note and a debug block for LLM prompts).  
- DeepMemoryIndex.delete_document / delete_by_filter (delete via Typesense documents endpoint using filter_by).  
- DeepMemoryIndex.close (closes the httpx client).  
- Dependencies: httpx (HTTP client), time, hashlib, json, and a pluggable embedding_chain interface.  

Key logic:
1. Initialization captures all configuration parameters (Typesense host/port/protocol, API key, collection name, embedding dimensions, chunk sizing, and an optional embedding_chain) and defers network setup by keeping _client None until needed.  
2. A lazy HTTP client is created by _get_client, which constructs an httpx.Client with a 30s timeout and Typesense API key header to reuse connections across operations.  
3. ensure_collection first probes the collection via a GET and only constructs and POSTs a schema when the collection is not present; the schema conditionally includes a float[] embedding field when embedding_dims is set.  
4. _chunk_text implements a consistent, line-aware chunking algorithm with overlap: it accumulates lines until a character budget is reached, emits a chunk, and computes an overlap region to preserve context between adjacent chunks.  
5. index_document calls _chunk_text to split text, builds per-chunk document dicts with metadata (id, doc_id, source, path, lines, timestamps), and collects texts for embedding when enabled.  
6. The embedding step (_embed) checks auto_embed and the presence and enabled flag on embedding_chain, then calls embed_batch(texts) and returns vectors, swallowing exceptions and logging failures to avoid breaking indexing.  
7. _upsert_batch serializes the list of document dicts into JSONL and posts it to the Typesense import endpoint with action=upsert, then parses each response line to count successes and logs a warning if some documents failed.  
8. index_batch handles preformed documents by embedding only those with text but missing an embedding field, then calls the same _upsert_batch path to persist them.  
9. search builds query parameters for Typesense (q/query_by/per_page and optional filter_by), auto-generates a vector_query by embedding the query text when possible, and issues a GET to the documents/search endpoint.  
10. Search post-processes Typesense hits by extracting document fields and metrics (text_match and vector_distance), computing a combined score that favors text matches but inverts vector distance, and returning DeepMemoryResult instances.  
11. build_context_note invokes search, truncates long snippets to max_snippet_chars, composes a human-readable note listing source, location, and score for each hit, and also produces a debug block with per-hit diagnostics for developer use.  
12. Deletion methods call the Typesense documents delete endpoint with filter expressions to remove documents by doc_id or arbitrary filters, return the number deleted, and close cleans up the HTTP client to release network resources.

---

## captain-claw-src/captain_claw/exceptions.py

Description:
1. This module defines custom exception types used across the Captain Claw project.  
2. It declares a single base exception CaptainClawError that all other custom errors inherit from.  
3. Specialized subclasses cover configuration, LLM interactions, tool execution, sessions, context management, validation, and guard-related failures.  
4. LLMAPIError extends LLMError and stores an optional HTTP-like status_code alongside the error message.  
5. Tool-related exceptions include ToolError and more specific ToolExecutionError, ToolNotFoundError, and ToolBlockedError that attach tool_name and reason metadata.  
6. SessionNotFoundError extends SessionError and records a missing session_id in its instance.  
7. ContextOverflowError captures current and maximum token counts when a context window is exceeded.  
8. GuardBlockedError represents policy or guard rejections and preserves a guard_type to indicate the blocking mechanism.  
9. Several classes use simple __init__ methods to format human-readable messages while storing additional attributes for programmatic inspection.  
10. The module contains no external dependencies and focuses solely on exception definitions and lightweight attribute assignment.  

Purpose:
1. The file exists to centralize and standardize error handling across the codebase by providing a clear hierarchy of exception types.  
2. By grouping errors into semantic categories (configuration, LLM, tools, sessions, context, validation, guard), other modules can catch and respond to classes of failures rather than relying on generic exceptions.  
3. Several exception classes carry structured metadata (for example status_code, tool_name, reason, session_id, token counts, guard_type) to enable richer logging, diagnostics, and programmatic decision making.  
4. Formatting descriptive messages in constructors ensures that raised exceptions produce consistent human-readable output for observability and debugging.  
5. The presence of fine-grained tool exceptions allows tool orchestration layers to differentiate between missing tools, execution failures, and policy-blocked attempts.  
6. LLM-specific exceptions provide a pathway to convey API-level failures such as rate limits or authorization issues by surfacing an optional numeric status code.  
7. Session and context-related exceptions help session management components detect and react to missing state or token budget violations.  
8. GuardBlockedError encapsulates guard decisions so higher-level logic can treat guarded actions distinctly from functional errors.  
9. The exception types facilitate mapping internal failures to external responses or retry policies in integration layers without inspecting message strings.  
10. Because the module is dependency-free and lightweight, it can be imported widely without risking circular imports or heavy coupling.  
11. Overall, the file exists to improve code clarity, error handling robustness, and maintainability by providing a single source of truth for the project's error taxonomy.  
12. The design anticipates common operational needs such as logging, monitoring, and conditional handling based on error attributes rather than raw messages.  

Key elements:
- CaptainClawError (base exception class).  
- ConfigurationError (configuration-related subclass).  
- LLMError (base class for LLM-related errors).  
- LLMAPIError (stores message and optional status_code).  
- ToolError (base class for tool-related errors).  
- ToolExecutionError (formats message and stores tool_name).  
- ToolNotFoundError (indicates missing tool and stores tool_name).  
- ToolBlockedError (indicates blocked tool execution and stores tool_name and reason).  
- SessionError (base class for session-related errors).  
- SessionNotFoundError (stores session_id of missing session).  
- ContextError (base class for context/window errors).  
- ContextOverflowError (stores current_tokens and max_tokens).  
- ValidationError (generic validation failure).  
- GuardBlockedError (stores guard_type and message indicating a guard blocked an action).  

Key logic:
1. The module establishes a simple inheritance hierarchy with CaptainClawError at the root so that catch-all and specific catches are both supported.  
2. Most subclasses are declarative and contain no additional logic beyond inheritance and optional attribute initialization.  
3. LLMAPIError defines an __init__ that calls the base Exception initializer with the provided message and then stores status_code as an instance attribute.  
4. ToolExecutionError formats a message that includes the tool name and failure message and retains the tool_name for programmatic access.  
5. ToolNotFoundError and ToolBlockedError both set human-readable messages and preserve identifying attributes such as tool_name and reason to guide handling.  
6. SessionNotFoundError constructs a message indicating the missing session and stores the session_id for downstream logic to reference.  
7. ContextOverflowError computes and stores current_tokens and max_tokens and formats an informative message reflecting the overflow condition.  
8. GuardBlockedError stores a guard_type along with the provided message so callers can distinguish between different guard mechanisms.  
9. The module relies entirely on attribute assignment and string formatting inside constructors rather than complex control flow or external I/O.  
10. Because exceptions are simple objects, they are intended to be raised and caught in other components where the contained attributes inform response behavior.  
11. There are no helper functions or side effects; the file's runtime behavior is limited to class definitions and their initialization semantics when instances are created.  
12. This minimal, explicit approach ensures exceptions are lightweight, serializable by standard mechanisms if needed, and easy to inspect during error handling and logging.

---

## captain-claw-src/captain_claw/google_oauth.py

Description:
1. This module implements Google OAuth2 helpers targeted at obtaining credentials usable with Vertex AI and LiteLLM.  
2. It defines constants for Google OAuth2 endpoints and a set of default scopes used for authorization.  
3. The GoogleOAuthTokens dataclass encapsulates access, refresh, id token, expiry, and scope information with helper methods.  
4. A PKCE helper generate_pkce_pair produces a code verifier and an S256 code challenge suitable for the Authorization Code flow.  
5. build_authorization_url constructs the authorization endpoint URL including optional state and PKCE code challenge parameters.  
6. exchange_code_for_tokens performs an async POST to the token endpoint to exchange an authorization code for tokens and computes an expires_at timestamp.  
7. refresh_access_token performs an async refresh-token grant and returns a GoogleOAuthTokens instance, preserving the original refresh token.  
8. fetch_user_info performs an authenticated async GET to Google’s userinfo endpoint and returns the parsed JSON profile.  
9. revoke_token tries to revoke an access or refresh token with Google, returning True on HTTP 200 and logging warnings on exceptions.  
10. The module uses httpx.AsyncClient for HTTP requests, standard library crypto utilities for PKCE, and a module-level logger for warnings.

Purpose:
1. The file exists to centralize and encapsulate Google OAuth2 logic required to authenticate against Google APIs and to produce credentials consumable by Vertex AI/LiteLLM.  
2. It provides a small, focused API for the common OAuth flows required by the application: building authorization URLs, exchanging codes, refreshing tokens, fetching user info, and revoking tokens.  
3. By packaging token data in GoogleOAuthTokens it standardizes token handling, expiry checks, serialization, and conversion to the "authorized_user" format expected by downstream libraries.  
4. The PKCE utilities support a secure Authorization Code flow with S256 code challenges to avoid exposing client secrets in insecure contexts.  
5. The authorization URL builder abstracts away parameter encoding details and ensures scopes, access_type, and prompt settings are consistently applied.  
6. Async token exchange and refresh functions centralize HTTP interaction details (timeouts, POST payload shape, response parsing) so callers don’t duplicate that behavior.  
7. fetch_user_info and revoke_token encapsulate specific Google endpoints and headers, keeping higher-level code free of hard-coded URLs and HTTP plumbing.  
8. Constants for app-state keys (STATE_KEY_TOKENS, STATE_KEY_USER) are provided to allow persistent storage managers (e.g., GoogleOAuthManager referenced in comments) to store and retrieve OAuth state consistently.  
9. The module intentionally delegates HTTP error propagation (via resp.raise_for_status) for most operations so calling code can handle failures, while best-effort revocation logs and returns False rather than raising.  
10. Conversion to a Vertex/LiteLLM-friendly credentials dict is provided to bridge this module with authentication consumers that expect the "authorized_user" format.  
11. Use of typed dataclasses, small helpers, and clear function boundaries makes the module suitable for reuse in different parts of the application that require Google authentication.  
12. Overall, the file exists to hide protocol specifics and provide reliable, testable primitives for integrating Google OAuth2 into the project.

Key elements:
- GOOGLE_AUTH_URL, GOOGLE_TOKEN_URL, GOOGLE_USERINFO_URL, GOOGLE_REVOKE_URL (endpoint constants).  
- DEFAULT_SCOPES (default OAuth scopes list).  
- STATE_KEY_TOKENS, STATE_KEY_USER (app-state keys for persistent storage).  
- GoogleOAuthTokens (dataclass holding access_token, refresh_token, token_type, expires_at, scope, id_token).  
- GoogleOAuthTokens.is_expired (checks expiry with buffer_seconds).  
- GoogleOAuthTokens.to_dict and .from_dict (serialization helpers).  
- GoogleOAuthTokens.to_vertex_credentials_json (builds authorized_user dict for LiteLLM/Vertex).  
- generate_pkce_pair (creates code_verifier and S256 code_challenge).  
- build_authorization_url (constructs OAuth2 authorization URL with query params).  
- exchange_code_for_tokens (async; exchanges code for tokens using httpx.AsyncClient).  
- refresh_access_token (async; obtains fresh access token with refresh_token).  
- fetch_user_info (async; GET userinfo with Bearer token).  
- revoke_token (async; POST to revoke endpoint, returns boolean).  
- httpx.AsyncClient (external HTTP dependency used for async requests).  
- get_logger / log (module-level logger for warnings).

Key logic:
1. The module centralizes OAuth endpoint configuration as constants so all request builders and HTTP calls reference the same URLs.  
2. PKCE generation uses secrets.token_urlsafe(64) to create a high-entropy verifier, computes its SHA-256 digest, and produces a URL-safe base64-encoded challenge with padding removed for S256.  
3. build_authorization_url assembles a parameter dictionary including client_id, redirect_uri, response_type, joined scopes, access_type, and prompt, then conditionally includes state and PKCE code_challenge parameters before URL-encoding.  
4. exchange_code_for_tokens composes a token request payload with grant_type "authorization_code" and includes code_verifier when provided, then performs an HTTP POST to GOOGLE_TOKEN_URL using httpx.AsyncClient with a 30s timeout.  
5. After posting the token exchange request, exchange_code_for_tokens calls resp.raise_for_status() to propagate HTTP errors and reads resp.json() to extract access_token, refresh_token, token_type, expires_in, scope, and id_token; it computes expires_at by adding expires_in to the current time.  
6. refresh_access_token builds a payload for the refresh_token grant and POSTs to the token endpoint; it expects the response to contain a new access_token and possibly other fields, but preserves the original refresh_token because Google typically does not return a new refresh token.  
7. Both token-issuing functions return a GoogleOAuthTokens instance populated from the JSON response and computed expiry, providing a single object for callers to inspect and persist.  
8. fetch_user_info issues a GET to GOOGLE_USERINFO_URL with an Authorization: Bearer header, raises for non-2xx responses, and returns the parsed JSON profile to the caller.  
9. revoke_token sends a POST to the revoke endpoint with the token as a URL parameter and a form content-type header, interprets an HTTP 200 as success, and catches exceptions to log a warning and return False as a best-effort behavior.  
10. GoogleOAuthTokens provides helper logic: is_expired compares current time against expires_at minus a buffer to indicate near-term expiry; from_dict filters unknown keys when reconstructing an instance.  
11. to_vertex_credentials_json constructs the "authorized_user" dictionary expected by LiteLLM/VertexBase.load_auth() containing client_id, client_secret, refresh_token, token, and token_uri to enable downstream libraries to create refreshable Google credentials.  
12. The module relies on httpx.AsyncClient context managers to manage connection lifetimes and sets explicit timeouts for each kind of request (30s for token endpoints, 15s for userinfo and revoke) to limit blocking durations.

---

## captain-claw-src/captain_claw/main.py

Description:
1. This module is the main entry point for the Captain Claw application and coordinates startup for interactive and web-based modes.  
2. It provides a CLI argument parser builder for runtime overrides and a helper to decide whether to parse argv implicitly.  
3. The main() function orchestrates initial setup including logging configuration, onboarding, loading and applying configuration, and branching into TUI or web server modes.  
4. A special "orchestrate" subcommand is handled early to support headless workflow execution, including listing and running saved workflows.  
5. The module sets up session and workspace directories and exposes a version() helper to print package version information.  
6. An async run_interactive() function implements the terminal interactive loop, including signal handling, UI integration, agent initialization, and platform lifecycle management.  
7. run_interactive starts a background cron scheduler, races a threaded prompt against a stop event, and dispatches user input to local commands or the agent execution flow.  
8. Cleanup logic ensures platforms are torn down, background tasks are cancelled, terminal state is restored, and the process is force-exited to avoid thread-hang issues.  
9. When executed as a script it registers a small Typer-based CLI with run and ver commands that delegate to main() and version().  
10. The module relies on other project components such as Agent, UI, configuration, logging, onboarding, orchestrator, and web server modules to perform its responsibilities.

Purpose:
1. The file exists to centralize application bootstrap and provide a single, well-defined entrypoint for users and scripts to start Captain Claw.  
2. It encapsulates runtime argument parsing so callers and package entrypoints can flexibly override configuration, model, provider, and UI mode without duplicating logic.  
3. By handling an "orchestrate" subcommand early and separately, it supports headless automation and workflow execution suitable for cron jobs and non-interactive use.  
4. The onboarding integration allows initial configuration to be run interactively before normal startup, ensuring first-time users can be guided into a usable configuration.  
5. The main function unifies configuration loading, CLI overrides, and global configuration registration so the rest of the application can access a consistent Config instance.  
6. It chooses between terminal UI (TUI) and web UI modes based on flags and configuration, providing both interactive and server-based usage models from the same codepath.  
7. run_interactive implements a resilient event-driven REPL-style loop that coexists with asynchronous platform bridges and scheduled cron work.  
8. Signal handling and a cancellable agent cancel_event provide a controlled shutdown and per-turn cancellation behavior that is important for a responsive CLI.  
9. The module ensures workspace and session directories are created proactively to avoid runtime file-system errors when sessions are started or logs are written.  
10. Centralized logging configuration and a mechanism to redirect system log sink to the UI keep runtime status and diagnostics visible to the user.  
11. The forced os._exit() at the end of interactive shutdown is included to avoid deadlocks caused by non-interruptible input threads, trading a normal atexit sequence for guaranteed process termination.  
12. Providing a lightweight Typer CLI wrapper lets the module behave nicely when invoked as a script or installed CLI entrypoint without duplicating CLI definitions elsewhere.

Key elements:
- _build_runtime_arg_parser (function) — constructs argparse.ArgumentParser with runtime options and an "orchestrate" subparser.  
- _should_parse_runtime_cli_from_argv (function) — heuristic to decide whether to parse sys.argv for runtime flags.  
- main (function) — primary synchronous startup routine that handles CLI integration, onboarding, config loading, mode selection, and launching UI or web server.  
- run_interactive (async function) — implements the asynchronous terminal interactive loop, signal handlers, agent initialization, and cleanup.  
- version (function) — prints the package version using captain_claw.__version__.  
- Typer CLI (if __name__ == "__main__") — registers run and ver commands that delegate to main() and version().  
- Agent (imported class) — used to create the agent instance and access cancel_event, session, and usage metrics.  
- get_ui (imported function) — obtains UI instance used for prompt, status, and output callbacks.  
- Config (imported class) and set_config/get_config (functions) — configuration loading, instantiation, and global registration.  
- configure_logging, log, set_system_log_sink (imports) — logging setup and runtime log sinking into the UI.  
- run_onboarding_wizard and should_run_onboarding (imports) — interactive onboarding flow control.  
- orchestrator_cli.run_orchestrator_headless and _list_workflows_cli (imports used in orchestrate mode).  
- run_web_server (imported function) — starts the web server when web UI mode is selected.  
- asyncio, signal, os._exit, asyncio.Event, asyncio.to_thread, and asyncio.create_task (standard concurrency primitives used extensively).

Key logic:
1. On entry, the module may parse runtime CLI arguments sourced from sys.argv only if no explicit parameters were passed to main() and the invoking program name indicates a direct run.  
2. The _build_runtime_arg_parser defines global overrides such as config, model, provider, streaming, verbosity, onboarding, version, and a "tui" flag, plus an "orchestrate" subcommand with its own options.  
3. If parsing detects the "orchestrate" subcommand the module configures logging, imports orchestrator helpers, handles listing saved workflows, validates inputs, and invokes run_orchestrator_headless synchronously via asyncio.run().  
4. After orchestrator handling or normal CLI parsing, main sets up logging, possibly toggling DEBUG via environment variables when verbose is requested.  
5. Onboarding is conditionally run based on configuration and flags; failures or cancellations are caught, logged, and may cause process exit with appropriate messages.  
6. Configuration is loaded from a provided path or via Config.load(); CLI model/provider/no_stream overrides are applied and the resulting Config instance is stored globally via set_config.  
7. Filesystem preparation ensures session and workspace directories exist by expanding paths and creating parent directories as needed.  
8. The choice of TUI vs web mode is made from flags and cfg.web.enabled; TUI mode obtains the UI, sets system log sink, and executes the async run_interactive loop via asyncio.run().  
9. run_interactive sets up signal handlers that map first Ctrl+C to canceling the current agent turn and a second to a full stop, using a shared asyncio.Event and the agent's cancel_event.  
10. The interactive loop initializes the Agent, loads previous session outputs into the UI if present, starts platform bridges, and starts a cron scheduler task as a background worker.  
11. For each iteration it prints a status line, then races a threaded blocking prompt (via asyncio.to_thread) against the stop_event to remain responsive to signals while waiting for user input.  
12. After receiving input, special UI commands are handled first, then local commands are dispatched (which may break or continue the loop), and non-empty user prompts are passed to run_prompt_in_active_session for execution.  
13. Exceptions like KeyboardInterrupt, EOFError, and generic errors are logged and surfaced to the UI as appropriate, with the loop breaking on termination signals.  
14. During shutdown the module awaits teardown of platform bridges, cancels the cron worker and awaits its cancellation, resets terminal scroll regions, moves the cursor to a clean line, flushes stdout, and calls os._exit(0) to avoid hanging on thread joins.  
15. In web mode the module defers to run_web_server(cfg) and implements similar KeyboardInterrupt and exception handling to exit cleanly or log fatal errors.  
16. The included version() helper and Typer CLI provide convenience entrypoints for printing version information and running the main startup flow from the command line.

---

## captain-claw-src/captain_claw/prompt_execution.py

Description:
1. This module provides helpers to execute user prompts and to dispatch those prompts into the project's queuing and followup systems.  
2. It implements utilities for enqueuing tasks into layered command lanes, resolving per-session queue settings, and waiting for session idle states.  
3. The module can update and validate session queue metadata, persisting changes through the agent's session manager.  
4. It exposes a cancellable runner that races an awaitable against an ESC key capture from the UI to allow user-initiated cancellation.  
5. The core prompt execution path handles printing user prompts, streaming or non-streaming assistant responses, and integrating with cron events.  
6. It records timing and completion metadata on the runtime context and writes tool-style messages into session history for cron-triggered runs.  
7. Followup and scheduled prompts are enqueued into a followup queue when sessions are busy, with deduplication and drop-policy handling.  
8. An interrupt mode can clear a session's command lane and followup backlog before scheduling a new followup prompt.  
9. The module carefully switches agent.session when executing prompts in arbitrary sessions and restores the previous session afterward.  
10. Errors during prompt handling are logged, propagated to cron monitoring events, and optionally re-raised depending on context.

Purpose:
1. The file exists to centralize and standardize how prompts are executed in both interactive and scheduled (cron) contexts within the application.  
2. It abstracts queue lane resolution and multilayer enqueuing so callers can request prompt execution without managing low-level queue details.  
3. By resolving session-specific queue settings it ensures session metadata can influence runtime behavior like debounce, cap, mode, and drop policy.  
4. It provides a clean cancellation mechanism tied to the UI so long-running completions or streams can be interrupted by the user.  
5. The module integrates with cron_dispatch to emit structured events for monitoring and to log assistant and system activities related to scheduled runs.  
6. It supports streaming assistant output and non-streaming completion paths, allowing the UI to present partial output during generation.  
7. Followup queuing and dispatch logic decouples scheduled followups from immediate execution and implements deduplication and scheduling semantics.  
8. The interrupt capability exists to allow critical followups to preempt queued work and clear backlogs when required by policy.  
9. Updating session queue metadata via a dedicated function ensures validation and consistent persistence through the session manager.  
10. The file ensures that when a prompt is run in a session other than the current one, the agent's session is temporarily switched and then restored to avoid side effects.  
11. It also collects execution timing and state into the runtime context so higher-level components can report or react to recent execution metrics.  
12. Overall, the module ties together configuration, queueing, UI behavior, session management, and cron instrumentation to make prompt execution robust and observable.

Key elements:
- enqueue_agent_task (nested enqueuing into session, global, and AGENT_RUNTIME lanes).  
- _safe_int (parses and bounds integers with a minimum).  
- resolve_queue_settings_for_session (builds QueueSettings from config and session metadata).  
- wait_until_session_idle (polls command queue size for a session lane).  
- queue_meta (extracts queue metadata from a session-like object).  
- update_active_session_queue_settings (validates and writes queue metadata to the active session).  
- run_cancellable (runs an awaitable and cancels it if UI ESC is detected).  
- run_prompt_in_active_session (prints user message, runs agent stream/complete, handles streaming, calls cron events, and invokes callbacks).  
- run_queued_followup_prompt (adapter to run a FollowupRun from the followup queue).  
- dispatch_prompt_in_session (decides execute vs queue for followups, handles interrupt mode, schedules followup drains).  
- run_prompt_in_session (loads target session, switches agent.session, records tool messages, and enqueues the prompt run).  
- External dependencies: get_config (config access), CommandLane/FollowupRun/QueueSettings and normalize_* helpers from execution_queue, cron_chat_event/cron_monitor_event from cron_dispatch, ctx.command_queue and ctx.followup_queue, and agent.session_manager.

Key logic:
1. enqueue_agent_task composes three nested enqueue_in_lane calls so a task is first enqueued in a session-specific lane, then a resolved global lane, and finally the AGENT_RUNTIME lane to control execution ordering across scopes.  
2. _safe_int attempts integer conversion and enforces a minimum value, returning a provided default on failure.  
3. resolve_queue_settings_for_session fetches global config, loads the session if necessary, merges session-level queue metadata with config defaults, normalizes mode and drop_policy, and returns a QueueSettings object with computed debounce and cap values.  
4. wait_until_session_idle polls the command queue size for the resolved session lane with a short sleep loop until the queue is empty.  
5. queue_meta defensively extracts a "queue" dict from a session-like object's metadata only if present and valid.  
6. update_active_session_queue_settings validates incoming mode and drop_policy values using normalization helpers, updates the session metadata, timestamps the change, persists the session via session_manager, and returns a summary message along with success status.  
7. run_cancellable creates tasks for the work awaitable and optionally an ESC waiter from the UI, waits for the first to complete, cancels the other, and reports whether cancellation occurred while ensuring cleanup of tasks.  
8. run_prompt_in_active_session is the principal path for executing a single prompt in the currently active session: it prints the user prompt, emits cron start events if applicable, sets UI thinking/streaming states, and either streams assistant chunks via agent.stream or collects a single completion via agent.complete.  
9. During streaming, chunks are appended and printed via UI stream methods; non-streaming completions are printed as a single assistant message; both paths use run_cancellable to allow ESC-driven cancellation and handle cron bookkeeping for cancellations.  
10. After assistant output, optional callbacks on_assistant_text and after_turn are invoked with derived outbound text and turn indices; execution timing and last-completed timestamps are stored on the runtime context and the UI status is reset to waiting.  
11. Error handling logs the exception, emits cron failure events and messages into the session history, attempts to notify on_assistant_text of the error, and conditionally re-raises based on raise_on_error.  
12. Followup dispatch logic checks whether the session is busy or has a followup backlog, decides immediate execution or queuing based on resolved QueueSettings, supports an "interrupt" mode that clears lanes and followups, enqueues FollowupRun entries with deduplication, schedules drain callbacks, and emits monitoring/chat events for queued/skipped actions.  
13. run_prompt_in_session loads the target session object, raises if not found, and defines an _execute closure that switches agent.session to the target session, records start/done/fail tool messages into session history with token counts, invokes run_prompt_in_active_session directly (queue=False) under the CRON lane, persists session changes, and restores the previous session afterward.  
14. The module consistently uses ctx.command_queue and ctx.followup_queue for concurrency control and scheduling, and leverages agent.session_manager for durable session operations.

---

## captain-claw-src/captain_claw/telegram_bridge.py

Description:
1. This module implements a minimal asynchronous Telegram Bot API bridge using httpx.AsyncClient.  
2. It defines a dataclass TelegramMessage that normalizes incoming update payloads into a consistent structure.  
3. The TelegramBridge class wraps API URL construction, polling for updates, sending text messages, and other helper endpoints.  
4. get_updates performs long-polling, validates the API response, and extracts only text messages into TelegramMessage instances.  
5. send_message splits long text into manageable chunks and posts each chunk to Telegram using the sendMessage endpoint.  
6. send_chat_action posts transient chat status (for example, typing) to inform users of activity.  
7. send_audio_file uploads an audio file as multipart form data to the sendAudio endpoint after verifying the file exists.  
8. read_business_message posts a read receipt for business API messages when a business_connection_id is present.  
9. The bridge also exposes methods to register bot commands and configure the chat menu button via set_my_commands and set_chat_menu_button_commands.  
10. All network calls raise for HTTP errors through response.raise_for_status and the class manages an underlying AsyncClient lifecycle.

Purpose:
1. The file exists to centralize Telegram API interactions so other parts of the project can poll messages and send responses without duplicating HTTP logic.  
2. It provides a small, focused abstraction over the Telegram Bot API operations the application needs: fetching updates, sending messages and actions, uploading audio, and managing command metadata.  
3. By normalizing incoming updates into TelegramMessage objects, it simplifies downstream code that consumes user messages by guaranteeing a consistent set of fields.  
4. Long-polling logic and timeout handling are encapsulated so the rest of the system can rely on a single async call to receive new messages.  
5. The message chunking behavior ensures very long messages are safely split to respect Telegram payload limits and reduces the need for callers to handle splitting.  
6. File upload support is provided with local file validation to avoid sending invalid requests and to centralize the multipart upload pattern.  
7. Business-message read receipts are handled only when a business_connection_id is present, keeping consumer code free of API details.  
8. Command registration helpers let the application configure slash commands and menu button behavior in one place, improving maintainability when command sets change.  
9. The AsyncClient is owned by the bridge so connection pooling, timeouts, and graceful closure are managed consistently.  
10. Exposing an enabled property makes it trivial for the application to disable Telegram integration by omitting a token.  
11. The module keeps API base URL configurable to support alternate Telegram-compatible endpoints if needed.  
12. Overall, it exists to provide dependable, reusable Telegram integration primitives that other modules can call asynchronously without handling HTTP or payload normalization themselves.

Key elements:
- TelegramMessage (dataclass: normalized fields for update_id, message_id, chat_id, user_id, username, first_name, text, business_connection_id)  
- TelegramBridge.__init__ (constructor: stores token, api_base_url, creates httpx.AsyncClient)  
- TelegramBridge.enabled (property: boolean indicating token presence)  
- TelegramBridge._url (helper: constructs endpoint URL for given method)  
- TelegramBridge.close (async: closes AsyncClient)  
- TelegramBridge.get_updates (async: long-poll getUpdates and normalize messages)  
- TelegramBridge.send_message (async: chunk and post sendMessage)  
- TelegramBridge.send_chat_action (async: post sendChatAction)  
- TelegramBridge.send_audio_file (async: validate file and post sendAudio with multipart files)  
- TelegramBridge.read_business_message (async: post readBusinessMessage for business API)  
- TelegramBridge.set_my_commands (async: sanitize and post setMyCommands payload)  
- TelegramBridge.set_chat_menu_button_commands (async: post setChatMenuButton payload)  
- httpx.AsyncClient (external dependency used for all HTTP calls)  
- pathlib.Path (used for file resolution/validation in send_audio_file)

Key logic:
1. Initialization stores a stripped token and a normalized API base URL, then creates an AsyncClient with a 40-second timeout for reuse across calls.  
2. The enabled property simply returns whether a non-empty token is configured, enabling callers to gate Telegram usage.  
3. _url concatenates the base URL, bot token, and a method name to produce endpoint URLs used by all request methods.  
4. get_updates builds query parameters including an optional offset and a timeout for long-polling, then performs a GET against getUpdates.  
5. The response JSON is validated to be a dict with ok=True and a list result; nonconforming responses result in an empty list.  
6. For each result item, get_updates prefers the "message" key and falls back to "business_message", then skips non-dict or non-text entries.  
7. It extracts user and chat info, coerces numeric fields to int, filters out zero ids, and creates TelegramMessage objects only for valid text messages.  
8. send_message accepts text, trims it, and splits it into chunks with a practical max length (3800 chars), trying to break on newlines but falling back to a hard split when necessary.  
9. Each chunk is posted to sendMessage as JSON, with reply_to_message_id included only for the first chunk if provided, and each call raises on HTTP error.  
10. send_chat_action simply posts a chat_id and action (default typing) to the sendChatAction endpoint and raises on error.  
11. send_audio_file resolves and validates the file path, constructs a payload and multipart files mapping, then posts data/files to sendAudio and raises on failure.  
12. read_business_message composes a payload with business_connection_id, chat_id, and message_id but returns early if the business_connection_id is empty to avoid unnecessary calls.  
13. set_my_commands iterates provided (name, description) tuples, sanitizes and lowercases command names, builds a list of command dicts, skips if empty, and posts to setMyCommands.  
14. set_chat_menu_button_commands posts a fixed payload to set the menu button to open commands.  
15. All methods rely on response.raise_for_status to surface HTTP error conditions rather than returning partial or silent failures.

---

## captain-claw-src/captain_claw/tools/pocket_tts.py

Description:
1. This module implements a local text-to-speech tool that synthesizes MP3 audio from text using the pocket-tts package.  
2. It provides helper functions to normalize and convert model-produced audio samples into signed 16-bit PCM and then encode those bytes to MP3.  
3. The module attempts MP3 encoding first via the Python lameenc package and falls back to invoking system ffmpeg if lameenc is not available.  
4. A PocketTTSTool class is defined that extends the project Tool abstraction and exposes an async execute method to run the synthesis pipeline.  
5. The tool lazily loads and caches a pocket-tts model, capturing a load error message to avoid repeated failed import attempts.  
6. The code supports selecting a voice preset, obtaining a corresponding model "state", and handling multiple generate_audio method signatures for compatibility.  
7. Input text length is validated against a configurable max_chars setting from project configuration before synthesis proceeds.  
8. Generated audio samples are coerced from nested or tensor-like structures into a flat list of floats, then converted into PCM, encoded, and saved to a normalized path under the saved/media area.  
9. The execute method returns a ToolResult summarizing file path, voice, format, bitrate, sample rate, and approximate duration on success or an error on failure.  
10. Robust error handling and logging are used throughout to convert dependency or runtime failures into clear error messages.

Purpose:
1. The file exists to provide a reusable, project-integrated tool for converting textual content into speech that can be stored and referenced by other components.  
2. It centralizes pocket-tts integration so callers need not manage model loading, signature compatibility, sample conversion, or encoding details.  
3. The PocketTTSTool wraps configuration-driven defaults (voice, sample rate, mp3 bitrate, and timeouts) and enforces length limits to keep synthesis predictable.  
4. By encoding to MP3 and writing into the project's saved/media area, the tool matches the repository's file organization and ensures outputs are accessible to downstream features.  
5. The lazy model loading and cached error behavior reduce startup overhead and avoid redundant import failures in long-running processes.  
6. The module provides compatibility handling for different pocket-tts method signatures and for different audio sample containers (lists, tensors, numpy-like objects).  
7. The lameenc/ffmpeg dual-encoding strategy makes the feature usable in environments with either a pure-Python encoder or a system ffmpeg binary.  
8. Helper conversion functions isolate concerns: iterating nested audio values, coercing to floats, PCM conversion, and MP3 encoding are each testable and replaceable.  
9. The tool's execute method exposes a simple, documented parameter set so orchestration layers can request synthesis without duplicating audio processing logic.  
10. Centralized logging and error propagation via ToolResult allow orchestration code to handle failures uniformly.  
11. Path resolution logic ensures untrusted or user-provided paths are normalized under the saved root and that output files always use the .mp3 suffix.  
12. Overall, the file exists to reliably turn text into persisted speech artifacts while hiding low-level audio and dependency complexity from the rest of the project.

Key elements:
- _iter_scalar_samples (function): yields float samples from arbitrarily nested list/tuple or scalar values.  
- _coerce_samples (function): normalizes tensor-like or nested model outputs into a flat list of float samples.  
- _samples_to_pcm16 (function): converts float samples into signed 16-bit PCM bytes with scaling and clipping.  
- _encode_mp3_bytes (function): encodes PCM bytes to MP3 using lameenc or falling back to ffmpeg via subprocess.  
- _write_bytes (function): simple helper to write raw bytes to a pathlib.Path.  
- PocketTTSTool (class): Tool subclass implementing pocket-tts synthesis, configuration, and file output.  
- PocketTTSTool.execute (async method): orchestrates validation, model load, generation, conversion, encoding, and file write.  
- PocketTTSTool._ensure_model (async method): lazily imports pocket_tts, validates TTSModel, and loads it in a background thread.  
- PocketTTSTool._generate_audio (staticmethod): compatibility wrapper trying multiple generate_audio call signatures including state handling.  
- PocketTTSTool._resolve_output_path (method): constructs and normalizes the output path under the project's saved root and enforces .mp3 suffix.  
- get_config (external call): used to read pocket_tts-related configuration values.  
- WriteTool (external dependency): used for saved root and session id normalization utilities.  
- importlib, asyncio.to_thread, subprocess.run, shutil.which, lameenc, ffmpeg (external modules/calls): used for dynamic imports, threading wrappers, and encoding fallbacks.  
- ToolResult (class): used to return structured success/error results from execute.

Key logic:
1. The module first provides small, focused helpers to transform arbitrary model audio outputs into a canonical float sample list by attempting tensor detachment, CPU transfer, reshape, and tolist conversions.  
2. After coercing samples, it converts floats to signed 16-bit integers by scaling values within a typical [-1,1] range to the 16-bit amplitude and clipping to the valid PCM range.  
3. MP3 encoding is attempted using the lameenc Python encoder; if that import or encoding fails, the code locates a system ffmpeg binary and runs it as a subprocess feeding raw s16le mono PCM on stdin and capturing encoded MP3 on stdout.  
4. The ffmpeg call is constructed with explicit sample rate, channel count, format, and bitrate and any subprocess errors are captured and surfaced with stderr content when available.  
5. PocketTTSTool manages a cached _model and a _model_load_error string so repeated attempts to use a missing or incompatible dependency produce a consistent runtime error rather than repeatedly failing import.  
6. _ensure_model performs a dynamic import of pocket_tts and verifies that the package exposes a TTSModel; model loading is delegated to a background thread via asyncio.to_thread.  
7. _generate_audio provides signature compatibility by trying multiple call forms when a voice state is provided and falling back to simple text-only calls when state is None, raising a TypeError for unsupported signatures.  
8. execute validates the provided text and enforces a configurable maximum character length from the project config, returning a failure ToolResult for invalid input.  
9. The output file path is resolved using WriteTool utilities to ensure the path is safely nested under the saved root and to guarantee an .mp3 suffix; directories are created as needed.  
10. Voice selection prioritizes the explicit voice parameter, then a configured default in config, then a model-provided default_voice; if a voice is selected the code requests a voice state from the model in a background thread.  
11. Audio generation, sample coercion, PCM conversion, MP3 encoding, and file writing are each executed in background threads to avoid blocking the event loop, and intermediate emptiness checks (e.g., no samples) produce clear error results.  
12. On success the tool composes a human-readable summary including the actual saved path, voice label, format, bitrate, sample rate, and estimated duration, while exceptions are logged and returned as ToolResult failures.

---

## captain-claw-src/captain_claw/tools/contacts.py

Description:
1. This module defines a ContactsTool class for managing a persistent cross-session address book.  
2. The tool exposes actions to add, list, search, view info, update, and remove contacts.  
3. It integrates with a session manager (obtained via get_session_manager) to perform CRUD operations on stored contact records.  
4. The tool declares a JSON schema for expected parameters including fields like name, contact_id, email, tags, notes, and privacy_tier.  
5. The execute method routes incoming action requests to internal async helper methods based on the action string.  
6. The add helper validates that a name is provided, calls sm.create_contact, and returns a success ToolResult with a brief confirmation.  
7. The list and search helpers format contact summaries into line-oriented strings and return them as ToolResult content.  
8. The info helper assembles a multi-line detailed view of a single contact including metadata such as importance and last seen.  
9. The update helper builds an update dict from provided fields, appends notes instead of replacing, clamps importance into a 1–10 range, and calls sm.update_contact.  
10. The remove helper selects a contact then calls sm.delete_contact and returns success or error results accordingly.  

Purpose:
1. This file exists to provide a reusable tool abstraction that allows other parts of the application to manage contacts in a consistent programmatic way.  
2. By encapsulating contact operations behind the Tool interface, the module makes it straightforward to invoke contact actions from sessions, agents, or external integrations.  
3. The parameter schema documents available fields and expected types so callers can validate and build requests uniformly.  
4. Delegating persistence to the session manager separates storage concerns from the tool logic and enables contacts to persist across sessions.  
5. Helper methods centralize validation, formatting, and transformation logic so responses are standardized and human-readable.  
6. Returning ToolResult objects integrates with the project's tool execution framework and provides consistent success/error reporting.  
7. The module implements small business rules like defaulting importance and privacy tiers to maintain sensible defaults on creation.  
8. Appending notes instead of replacing them preserves context accumulation on contacts, which supports tracking over time.  
9. Formatting choices such as truncated IDs and inline organization/position snippets optimize lists for compact display.  
10. Centralizing contact operations reduces duplication and simplifies future changes to persistence, formatting, or validation.  
11. The top-level execute method also provides a single place to catch and log exceptions and convert them into ToolResult errors for callers.  
12. Overall, the module serves as the bridge between external commands and the session-backed contact datastore while enforcing input constraints and presentation conventions.  

Key elements:
- ContactsTool (class) — Tool subclass implementing contact management.  
- name, description (attributes) — tool metadata used by registry and user-facing help.  
- parameters (attribute) — JSON schema describing allowed action fields and types.  
- execute(action, ...) (method) — dispatcher that routes actions to internal helpers and handles errors.  
- _add(sm, ...) (async helper) — creates a contact via sm.create_contact with defaults and validation.  
- _list(sm) (async helper) — lists contacts via sm.list_contacts and formats summary lines.  
- _search(sm, query) (async helper) — searches via sm.search_contacts and formats results.  
- _info(sm, contact_id) (async helper) — builds detailed multi-line view from a selected contact.  
- _update(sm, contact_id, ...) (async helper) — constructs update kwargs, appends notes, clamps importance, calls sm.update_contact.  
- _remove(sm, contact_id) (async helper) — selects and deletes a contact via sm.delete_contact.  
- get_session_manager (external call) — obtains persistence/session manager used for contact operations.  
- ToolResult (type) — used for returning standardized success/error payloads.  
- get_logger / log (dependency) — used for error logging in execute exception handling.  
- session manager methods referenced: create_contact, list_contacts, search_contacts, select_contact, update_contact, delete_contact.  

Key logic:
1. execute begins by extracting an optional _session_id from kwargs and obtaining the shared session manager to route operations through a consistent persistence layer.  
2. The method then matches the action string against supported actions and forwards parameters to the corresponding private async helper.  
3. Unknown actions immediately return a ToolResult error, while exceptions thrown by helpers are caught, logged, and converted to ToolResult errors.  
4. The add helper enforces that a non-empty name is provided, calls sm.create_contact with defaults for importance and privacy_tier, and returns a brief success message containing the new contact's truncated id and name.  
5. The list helper requests up to 50 contacts from sm.list_contacts and builds compact summary lines including importance, name, optional position and organization, relation, and an 8-character id prefix.  
6. The search helper requires a non-empty query, calls sm.search_contacts with a limit (20), and formats matching entries similarly to the list output.  
7. The info helper requires a contact identifier, resolves it via sm.select_contact, and composes a detailed, multi-line representation including id, position, organization, emails, phones, importance and whether it was pinned, mention counts, last seen timestamp, tags, description, notes, and privacy tier.  
8. The update helper first resolves the contact by id then accumulates only provided fields into a kwargs dict; it clamps importance values to the 1–10 range and sets an importance_pinned flag when importance is provided.  
9. Notes provided in an update are appended to any existing notes with a newline separator rather than replacing them, preserving historical context.  
10. If no updatable fields are present the update helper returns an error; otherwise it calls sm.update_contact and reports success or failure based on the return value.  
11. The remove helper resolves the contact, calls sm.delete_contact, and returns success with a truncated id and name or an error if deletion failed.  
12. Throughout, methods return ToolResult objects with success booleans and textual content or error messages, enabling predictable consumption by the tool registry and callers.

---

## captain-claw-src/captain_claw/tools/write.py

Description:
1. This module implements a WriteTool class that provides functionality to create or overwrite files with supplied content.  
2. The tool defines metadata including a name ("write"), a short description, and a JSON schema for expected parameters such as path, content, and append.  
3. It includes helper static methods to normalize a session identifier, resolve a saved-root directory, and map requested paths into a session-scoped saved area.  
4. The write operation enforces that outputs are placed under a designated saved root and attempts to scope files by session and category names.  
5. The execute method creates parent directories as needed, chooses append or write mode, writes UTF-8 content to the resolved file path, and returns a ToolResult.  
6. The module attempts a best-effort registration of the logical requested path to the physical file path with an optional file registry passed in kwargs.  
7. Path normalization handles absolute and relative inputs, strips unsafe path parts, rejects upward traversal, and applies a fallback when a candidate path would escape the saved root.  
8. Session identifiers are sanitized to filesystem-safe strings with a default of "default" when empty.  
9. Saved-root resolution prefers explicit _saved_base_path, then derives a saved subdirectory from _runtime_base_path, and otherwise falls back to the current working directory's saved folder.  
10. Errors during writing are logged and returned as a failing ToolResult rather than raising.

Purpose:
1. This file exists to centralize and encapsulate the logic for writing tool-managed outputs into a controlled filesystem area so other components can produce files safely.  
2. It enforces consistent scoping of outputs by session and by a set of accepted categories so that multiple sessions or tasks do not collide on file names.  
3. The tool exists to provide a programmatic, schema-driven interface for agents or tasks to request file writes without needing to manipulate the repository filesystem directly.  
4. By resolving a saved root from runtime-provided paths, the tool can operate in different deployment contexts where the base output location may vary.  
5. The normalization helpers ensure session identifiers become filesystem-safe and that requested paths are mapped into the saved hierarchy, preventing accidental writes outside the intended area.  
6. Appending support is provided to allow incremental writes to existing outputs when needed by callers.  
7. The optional file registry integration allows other parts of the system to later discover files by their original requested logical path, improving interoperability.  
8. The implementation takes a defensive stance: it creates directories as needed and performs best-effort registry registration but does not fail the write if the registry call throws.  
9. Logging and ToolResult-based error reporting make the tool suitable for use in broader automated workflows where exceptions should be converted into structured results.  
10. The category-based scoping and fallback behavior exist to keep files organized into predictable directories like downloads, media, and tmp, aiding downstream consumers.  
11. The tool is designed to be lightweight and synchronous in its file I/O while fitting into an async-compatible tool execution flow (execute is async).  
12. Overall, it provides a safe, auditable, and reusable mechanism for controlled file output from programmatic tasks.

Key elements:
- WriteTool (class) (main tool class exposing name, description, parameters, and execute).  
- _normalize_session_id (static method) (creates filesystem-safe session id with alnum and ._- allowed).  
- _resolve_saved_root (static method) (determines saved root from _saved_base_path, _runtime_base_path, or cwd and ensures it exists).  
- _normalize_under_saved (static method) (maps requested path into saved_root, enforces session scoping, categories, and fallback).  
- execute (async method) (performs actual write, directory creation, registry registration, and returns ToolResult).  
- parameters (dict) (JSON schema for path, content, append).  
- ToolResult (external type) (used to encapsulate success, content, or error).  
- get_logger / log (external logging) (used for error logging).  
- Path (pathlib) usage (expanduser, resolve, mkdir, relative_to manipulations).  
- kwargs keys referenced (_saved_base_path, _runtime_base_path, _session_id, _file_registry, _task_id).

Key logic:
1. The execute method starts by resolving the saved root using _resolve_saved_root, which prefers explicit saved base paths, falls back to a runtime base path's saved subfolder, and finally uses the current working directory's saved folder, creating it if necessary.  
2. The session id is normalized by _normalize_session_id to a safe token composed of alphanumeric characters and a limited set of punctuation, defaulting to "default" when empty.  
3. The requested path is normalized into the saved hierarchy by _normalize_under_saved, which first expands the path and distinguishes absolute from relative inputs.  
4. For absolute inputs, the method attempts to compute a path relative to saved_root; if that fails it constructs a relative hint from the absolute path parts to avoid placing files outside saved_root.  
5. The normalization strips empty and traversal parts, treats an empty or invalid path as "output.txt", and allows a leading "saved" token to be omitted so callers can use both "saved/..." and plain names.  
6. A set of known categories triggers creation of a scoped path [category, session_id, ...]; otherwise the file is placed under tmp/session_id/... to maintain session isolation.  
7. The candidate path is resolved and validated to be inside saved_root; if it would escape, a fallback path under saved_root/tmp/session_id is constructed using the final safe part.  
8. Once a concrete file_path is chosen, parent directories are created with mkdir(parents=True, exist_ok=True) to ensure the filesystem is ready for writing.  
9. The file is opened in "a" mode if append is True, otherwise in "w" mode, and content is written as UTF-8.  
10. A redirect note is computed when the requested path differs from the actual physical path to inform callers about the mapping.  
11. If a _file_registry is provided in kwargs, the tool attempts to register the logical-to-physical mapping along with an optional task id, but ignores exceptions from this best-effort registration.  
12. On success, the tool returns a ToolResult with success=True and a content string describing number of characters written and the file location; on exception it logs an error and returns a failing ToolResult with the error string.

---

## captain-claw-src/captain_claw/tools/send_mail.py

Description:
1. This module defines a SendMailTool class that implements an asynchronous tool for sending email messages with optional file attachments.  
2. The tool supports three delivery providers: Mailgun and SendGrid via HTTP APIs, and direct SMTP delivery.  
3. It validates input parameters such as recipients, subject, and at least one of a plain text or HTML body before attempting delivery.  
4. Attachment paths are resolved, validated for existence and file-ness, size-checked against a configurable maximum, and read into memory as bytes.  
5. The module uses an httpx.AsyncClient for HTTP-based providers and constructs provider-specific payloads for Mailgun and SendGrid.  
6. For SMTP delivery it builds an email.message.EmailMessage, sets appropriate headers, handles text/HTML alternatives, and attaches files with proper MIME types.  
7. The SMTP path prefers the aiosmtplib async library and falls back to Python's smtplib executed in a thread when aiosmtplib is not available.  
8. Configuration values (provider selection, credentials, host/port, timeouts, limits) are read via get_config and environment-variable fallbacks for API keys.  
9. The execute method returns a ToolResult indicating success or failure and includes a human-readable detail string on success.  
10. A close method is provided to cleanly close the underlying httpx client when the tool is no longer needed.

Purpose:
This module provides a single, reusable tool implementation to send email from the application, encapsulating provider differences and common validation in one place. It exists to let other parts of the project dispatch email without duplicating delivery logic, offering a consistent interface and result format (ToolResult). The tool centralizes configuration lookup for provider selection, credentials, timeouts, and attachment limits so those settings are managed in config rather than scattered code. Supporting Mailgun, SendGrid, and SMTP allows flexible deployment choices depending on available services or preferences. Attachment handling lives here so callers can supply filesystem paths and rely on consistent size and type checks. By using an asynchronous httpx client and preferring aiosmtplib, the implementation aims to integrate cleanly into async application workflows while still providing a synchronous fallback for environments without aiosmtplib. Error handling and explicit failure ToolResult returns make it straightforward for callers to detect and report delivery failures. The module formats provider-specific payloads and authentication mechanisms, isolating API details from callers. It also normalizes headers and recipient handling (including CC and BCC) to ensure consistent envelope construction across providers. Finally, the provided close method enables proper cleanup of network resources, preventing client leaks in long-running processes.

Key elements:
- SendMailTool (class) (Tool subclass implementing email sending).  
- name, timeout_seconds, description, parameters (class attributes for tool metadata and JSON schema).  
- execute(...) (main async method that validates inputs, reads attachments, selects provider, and returns a ToolResult).  
- _send_mailgun(...) (async helper that posts multipart/form-data to Mailgun using httpx with basic auth).  
- _send_sendgrid(...) (async helper that posts JSON to SendGrid using Bearer token authorization and base64-encoded attachments).  
- _send_smtp(...) (async helper that composes EmailMessage, attaches files, and sends via aiosmtplib or smtplib fallback).  
- close(...) (async method to aclose the module's httpx.AsyncClient).  
- httpx.AsyncClient (used for HTTP API calls).  
- get_config (reads mail-related configuration).  
- EmailMessage (from email.message for SMTP message construction).  
- asyncio.to_thread (used to read files and run smtplib send in a thread).  
- mimetypes.guess_type, base64.b64encode, pathlib.Path (used for attachment MIME detection, encoding, and file handling).  
- ToolResult (return type used to signal success/error to callers).  

Key logic:
The execute method begins by normalizing and validating recipient lists, subject, and the presence of either plain text or HTML content, immediately returning failure if required inputs are missing. It reads mail-related configuration via get_config and chooses the provider string (mailgun, sendgrid, or smtp) along with sender information and numeric timeouts or limits. Attachments are processed in sequence: each given path is expanded, resolved, and verified to exist and be a regular file; file sizes are compared to a configurable max_attachment_bytes and large files cause a failure. Files are read into memory using asyncio.to_thread to avoid blocking the event loop, and mimetypes.guess_type is used to assign a MIME type fallback to application/octet-stream if unknown. After preparing attachment metadata, the method dispatches to a provider-specific helper based on the configured provider. The Mailgun helper builds form data and a files list suitable for multipart/form-data and posts to the Mailgun messages endpoint with basic auth using the API key; it raises errors for missing API key or domain. The SendGrid helper composes a JSON payload with personalizations, from/to objects, content parts for text and/or HTML, and encodes attachments as base64 strings while sending with a Bearer token header; it interprets a 202 response as accepted. The SMTP helper constructs an EmailMessage, sets From/To/Cc/Subject headers, handles text vs HTML variants properly using set_content/add_alternative, and attaches binary content with maintype/subtype parsed from the MIME type. For SMTP delivery the helper attempts to import aiosmtplib and send asynchronously; if that import fails it runs a synchronous smtplib SMTP sequence (starttls, login if provided, sendmail) inside asyncio.to_thread to preserve the async calling contract. Throughout, exceptions during provider calls are caught upstream in execute, logged, and converted into a failing ToolResult with the exception string. On success, execute composes a multi-line summary including provider, from/to/cc/bcc, subject, recipient count, attachment count, and provider detail string returned from the helper, and returns that in a successful ToolResult. The close method simply closes the httpx.AsyncClient to release network resources.

---

## captain-claw-src/captain_claw/tools/registry.py

Description:
1. This module implements a tool registry system and a base Tool abstraction for registering, selecting, and executing tools.  
2. It defines utility functions to parse and analyze shell commands, including tokenization, segment splitting, and extraction of base executable tokens.  
3. A ToolResult Pydantic model encapsulates execution outcomes and normalizes error messages for failed executions.  
4. The abstract Tool base class specifies the interface and basic argument validation used by concrete tool implementations.  
5. ToolPolicy and ToolPolicyChain models provide structured allow/deny/also_allow rules and the logic to apply them in sequence.  
6. ToolRegistry stores registered Tool instances, manages metadata, enforces policies, and exposes methods to list and retrieve tools and their definitions.  
7. The registry contains logic to evaluate shell execution policies, check explicitly blocked shell commands, and optionally require approval callbacks.  
8. Execution of a tool is performed asynchronously with support for timeout handling, abort event bridging, and safe task cancellation.  
9. Global helper functions supply a singleton registry instance and allow replacing it with a custom registry.  
10. The module relies on configuration via get_config, logging via get_logger, and standard libraries for regex, fnmatch, shlex, asyncio, and pathlib.

Purpose:
This module exists to centralize management of tools that the application can use and to provide consistent control over which tools are available and how they are executed. It provides a formal base class and result model so that tools present a uniform interface and validation, simplifying integration with higher-level orchestrators or LLM-driven flows. The policy types and the ToolPolicyChain enable layered policy evaluation (global, session, task) so administrators or sessions can restrict or expand available tools dynamically. Shell-related utilities and policy evaluation focus on safety: they parse commands to determine base executables, support pattern-based deny/allow rules, and detect unparseable or empty commands. The registry's execute method coordinates the full lifecycle of running a tool, including argument validation, policy checks, approval prompts, execution with timeout, and abort propagation, which centralizes complexity and reduces duplication. It also provides path management for saved outputs by resolving a runtime base path and an isolated saved directory, preventing accidental escapes. The module integrates with project configuration and logging to make behavior configurable and observable. By exposing get_definitions and list_tools it supports downstream components like LLM function schemas or UIs that need metadata about available tools. The singleton accessors (get_tool_registry and set_tool_registry) make it easy to obtain or replace the global registry instance for tests or different runtime contexts. Overall, the file exists to provide a safe, configurable, and consistent mechanism to register, filter, and run tools while handling concurrency, timeouts, and cancellation robustly.

Key elements:
- _normalize_tool_name (function) (normalizes names for comparison).  
- _compile_shell_pattern (function) (compiles regex with literal fallback).  
- _tokenize_shell_command, _split_shell_segments, _extract_segment_base_command (functions) (tokenize and segment shell commands and extract base executables).  
- extract_shell_base_commands (function) (public helper to get base commands from a shell string).  
- is_blocked_shell_command (function) (evaluates a command against blocked patterns with parsed matching).  
- ToolResult (Pydantic model) (contains success, content, error and normalizes error on failure).  
- Tool (abstract base class) (defines name, description, parameters, timeout_seconds, execute, get_definition, validate_arguments).  
- ToolPolicy (Pydantic model) (policy fields: allow, deny, also_allow).  
- ToolPolicyChain (class) (applies policy steps and resolves allowed tools).  
- ToolRegistry (class) (register/unregister tools, manage metadata, policies, execute tools with timeout/abort handling).  
- _evaluate_shell_exec_policy and _shell_pattern_matches (methods) (determine allow/deny/ask for shell commands using glob-like patterns and targets).  
- get_tool_registry / set_tool_registry (global singleton accessors).  
- Dependencies: get_config (configuration), get_logger (logging), fnmatch, re, shlex, asyncio, pathlib, pydantic.

Key logic:
1. Shell parsing logic tokenizes commands using shlex with punctuation_chars set to separate common shell control operators and then splits tokens into segments by those separators.  
2. For each shell segment the extractor skips environment-like assignments and common wrapper tokens (sudo, command, builtin, nohup, time) to identify the actual executable token.  
3. extract_shell_base_commands returns the base executable for each segment; that list is used both for policy evaluation and pattern matching.  
4. is_blocked_shell_command first short-circuits empty or unparseable commands, then compiles each blocked pattern (falling back to literal escape on regex errors) and matches either the full segment text or the base commands depending on whether the pattern contains whitespace.  
5. ToolPolicyChain builds a normalized set of tool names and applies each policy step by intersecting with explicit allow lists, removing deny names, and unioning in also_allow limited to known tools.  
6. ToolRegistry maintains internal maps of tool instances and metadata and supports per-instance runtime base paths and a configurable saved directory name to derive safe save paths.  
7. When executing a tool, the registry resolves the effective set of available tools through the policy chain and raises ToolBlockedError if the requested tool is not allowed.  
8. For the special "shell" tool name the registry runs an extra policy evaluation (_evaluate_shell_exec_policy) which checks deny/allow patterns from configuration and returns deny/allow/ask; an approval callback may be invoked for "ask" decisions.  
9. The registry also checks configured blocked shell commands via is_blocked_shell_command and rejects empty or unparseable commands with specific error reasons.  
10. Argument validation is delegated to the tool via validate_arguments; missing required parameters raise ToolExecutionError.  
11. Execution is performed by creating an asyncio task for the tool.execute coroutine and a separate task that waits on a tool-specific abort event; an optional external abort event can be bridged to the tool abort event.  
12. The registry waits for either the execute task to complete, the abort wait task to trigger, or a timeout to elapse; it cancels tasks cleanly using an internal _cancel_task helper that awaits cancelled tasks to suppress warnings.  
13. If the execute task completes, its return value is validated to be a ToolResult; otherwise ToolExecutionError is raised for invalid payloads.  
14. If the abort event occurs the execute task is cancelled and an execution-aborted error is raised; if timeout occurs the execute task is cancelled and a timeout error including the elapsed seconds is raised.  
15. Exceptions during execution are logged and wrapped in ToolExecutionError except for already-raised ToolExecutionError and asyncio.CancelledError which are propagated appropriately.  
16. The registry supports per-call overrides for runtime base path, approval callback, and file registry references, and ensures the computed saved base path remains a descendant of the runtime base path to avoid path traversal.

---

## captain-claw-src/captain_claw/tools/web_fetch.py

Description:
1. This module provides asynchronous tools to fetch web content and return either cleaned readable text or raw HTML.  
2. It constructs a shared-style httpx.AsyncClient configured with a timeout, follow-redirect behavior, and a custom User-Agent.  
3. An HTML-to-text extractor uses BeautifulSoup to remove non-content tags like script, style, noscript, template, svg, and canvas.  
4. Anchor tags are preserved by replacing them with their visible label followed by the absolute URL in parentheses, or just the absolute URL if no label exists.  
5. The extractor collects visible text lines, collapses whitespace, and preserves the document title at the beginning when appropriate.  
6. WebFetchTool implements a tool that always returns plain text extracted from a fetched page and prepends metadata headers.  
7. WebGetTool implements a tool that returns the raw HTML source of a fetched page with similar metadata headers.  
8. Both tools consult configuration for a default maximum character limit, accept an optional max_chars parameter, and truncate output with a clear marker when exceeded.  
9. HTTP errors and general exceptions are logged and returned as failure ToolResult objects with error messages.  
10. Each tool creates and holds its own AsyncClient instance and exposes an async close method to properly aclose the client.

Purpose:
This module exists to provide reusable web fetching capabilities for the project, exposing two specialized tools for different consumption needs. It centralizes HTTP client creation so both tools share consistent timeout, redirect, and header behavior. The readable-text extractor exists to convert HTML into a compact, human-friendly representation suitable for downstream consumption by other components. The raw-HTML fetcher is provided for cases that need the original markup for scraping, parsing, or DOM inspection. Both tools expose parameter schemas so callers or a tool registry can validate invocation arguments. The module integrates with project configuration (get_config) to apply a configurable default maximum character limit, giving operators control over result sizes. Logging via the project's logger is used to surface operational failures and contextual metadata about fetch operations. The design enforces that WebFetchTool always returns text by removing any extract_mode override, reducing ambiguity in usage. The replacement of anchor tags with absolute URLs helps preserve source references for later turns or citations. Exception handling differentiates HTTP-specific errors from other failures to provide clearer error messages. The included close methods ensure that client resources are released when tools are shut down. Overall, the module provides predictable, configurable, and safe ways to retrieve web content for the rest of the application.

Key elements:
- _make_http_client (function; constructs and returns httpx.AsyncClient with timeout, follow_redirects, and User-Agent header).  
- _extract_readable_text (function; uses BeautifulSoup to strip non-content tags, handle anchors, collapse whitespace, and preserve title).  
- WebFetchTool (class; name "web_fetch", parameters schema, always returns text, methods __init__, execute, close).  
- WebGetTool (class; name "web_get", parameters schema, returns raw HTML, methods __init__, execute, close).  
- execute (method on both tools; performs async GET, enforces max_chars, assembles metadata headers, returns ToolResult).  
- close (async method on both tools; closes the httpx client via aclose).  
- get_config (external call; used to read tools.web_fetch.max_chars default).  
- get_logger (external call; module-level logger used for info and error logging).  
- httpx (external dependency; AsyncClient, HTTPError, response handling).  
- BeautifulSoup (external dependency; HTML parsing and DOM manipulation).  
- urljoin from urllib.parse (used to resolve relative hrefs to absolute URLs).  
- re (standard library; used to collapse whitespace in extracted text).  
- Tool and ToolResult (external base classes/models from tools.registry used for tool interface and results).

Key logic:
The module begins by providing a helper to create a configured httpx.AsyncClient with a 30-second timeout, automatic redirect following, and a custom User-Agent header. The HTML extraction function parses raw HTML with BeautifulSoup, removes elements that do not contribute to readable content (script/style/noscript/template/svg/canvas), and then processes anchor tags to preserve a visible label paired with an absolute URL computed via urljoin when a base URL is available. After DOM cleanup, the extractor retrieves the document text, splits it into lines, collapses runs of whitespace on each line using a regular expression, and collects non-empty cleaned lines into a single newline-joined text. If a title element is present and the cleaned text does not already start with it, the extractor prefixes the title followed by a blank line. Both WebFetchTool and WebGetTool construct their own AsyncClient instances at initialization. In execute, each tool logs the fetch attempt and reads the global configuration to determine a configured max_chars default; an explicit max_chars parameter overrides this default, but the effective value is coerced to at least 1. The tools perform an async GET request to the provided URL and call response.raise_for_status() to surface HTTP errors. WebFetchTool passes response.text to the extractor to obtain readable text, while WebGetTool uses response.text directly for raw HTML output. Before returning, each tool truncates the content to the effective maximum length and appends "\n... [truncated]" when truncation occurs. Both tools format an output string that includes metadata headers ([URL:], [Status:], [Mode:], [Size:]) followed by the content, and they wrap the result in a ToolResult with success=True on success. HTTP-specific exceptions (httpx.HTTPError) are caught, logged with context, and returned as ToolResult failures containing an "HTTP error" message; other exceptions are similarly logged and returned with the exception string. The close methods asynchronously close their httpx clients to release network resources. WebFetchTool also explicitly removes any "extract_mode" kwarg passed in execute to guarantee it always returns text.

---

## captain-claw-src/captain_claw/tools/shell.py

Description:
1. This module implements a ShellTool class for executing shell commands asynchronously.  
2. ShellTool is a Tool subclass that exposes metadata like name, description, parameters, and a configurable timeout.  
3. The tool reads configuration via get_config during initialization to set its default timeout and access allowed/blocked command lists.  
4. It validates commands using a private _is_command_safe method that consults is_blocked_shell_command and extract_shell_base_commands.  
5. The execute method runs commands with asyncio.create_subprocess_shell, capturing stdout and stderr.  
6. Execution supports an external abort Event passed via kwargs and enforces a timeout with asyncio.wait.  
7. The implementation decodes outputs as UTF-8 with replacement, combines stderr into the output with a “[stderr]” prefix, and truncates long outputs.  
8. The tool returns results as ToolResult objects indicating success, content, or an error message.  
9. Detailed logging is emitted for command execution, blocked commands, and exceptions via the project logger.  
10. Exceptions during execution are caught, logged, and converted into failed ToolResult responses.

Purpose:
This file exists to provide a controlled, asynchronous interface for running shell commands from the application while enforcing safety and resource limits. It centralizes command execution logic so other parts of the project can request shell operations without dealing with subprocess management, timeouts, or output handling. The module enforces security policies configured in the project's settings, including blocked patterns and an allowed command list, to reduce the risk of executing dangerous commands. It also integrates with the project's Tool and ToolResult abstractions so command execution results are returned in a consistent shape. By supporting an abort Event, it enables cooperative cancellation from higher-level workflows or task orchestrators. The timeout behavior is configurable and safeguarded by a minimum value to avoid accidental infinite waits. Output decoding, stderr merging, and truncation ensure that returned content is predictable in size and format for consumers such as UI components or logs. Logging calls provide observability for both successful runs and failure cases, aiding debugging and auditing. The tool isolates environment setup (like PATH) to provide consistent execution contexts across platforms. Centralizing subprocess creation and cleanup reduces duplication and the likelihood of resource leaks in the broader codebase. Overall, the file exists to offer a safe, observable, and standardized mechanism to run shell commands asynchronously within the project's architecture.

Key elements:
- ShellTool (class) (Tool subclass implementing shell execution).  
- name, description, timeout_seconds, parameters (class attributes describing the tool).  
- __init__ (method) (loads configuration and sets timeout).  
- _is_command_safe(command: str) -> tuple[bool, str] (private method that checks blocked patterns and allowed commands).  
- execute(command: str, timeout: int | None = None, **kwargs) -> ToolResult (async method that runs the command).  
- get_config (external call) (retrieves project configuration).  
- get_logger (external call) (obtains logger instance used for info/warning/error).  
- is_blocked_shell_command, extract_shell_base_commands (external utility calls used for safety checks).  
- asyncio.create_subprocess_shell, asyncio.create_task, asyncio.wait (asyncio APIs used to run and coordinate subprocess and abort handling).  
- ToolResult (external class) (used to return success, content, or error metadata).  
- os.environ and PATH handling (environment setup for subprocess).

Key logic:
The ShellTool initialization reads the project's configuration to set a default timeout and retain references to allowed/blocked command settings. Before running any command, execute calls _is_command_safe which first asks is_blocked_shell_command whether the command matches blocked patterns and returns explicit reasons for empty or unparseable commands. If an allowed_commands list is present in configuration, _is_command_safe extracts base commands with extract_shell_base_commands, normalizes them, and verifies each against the allowed set, returning a failure reason if any base command is not allowed. In execute, the tool logs the impending execution and determines the effective timeout, applying a minimum of one second. It checks for an abort_event passed via kwargs; if the abort Event is already set the method returns immediately with an aborted ToolResult. Environment variables are copied and PATH is ensured to have sensible defaults before spawning the subprocess. The command is executed with asyncio.create_subprocess_shell with stdout/stderr pipes, and a communicate task is created to read outputs. If an abort event is provided, a separate task waiting on abort_event.wait is created and both tasks are awaited concurrently using asyncio.wait with FIRST_COMPLETED. If the communicate task completes first, stdout and stderr bytes are decoded and post-processed. If the abort wait task completes first, the subprocess is killed, communication is cancelled and awaited or ignored if cancelled, and an aborted ToolResult is returned. If neither completes within the configured timeout, the subprocess is killed and the communicate task is cancelled, resulting in a timeout ToolResult. The implementation carefully handles asyncio.CancelledError to ensure subprocess is terminated and tasks are cancelled cleanly. After successful capture of output, stdout and stderr are decoded with UTF-8 replacement, stderr is appended with a “[stderr]” prefix if present, and the combined output is truncated to a 10000-character limit with a truncation marker that indicates total original length. The final ToolResult marks success based on the subprocess returncode and includes either the content or a “[no output]” placeholder. Any unexpected exceptions are logged and converted into a failed ToolResult containing the error string. Cleanup also cancels a pending abort wait task if it exists and suppresses its CancelledError to avoid leaking tasks.

---

## captain-claw-src/captain_claw/tools/__init__.py

Description:
1. This module serves as the package initializer for the captain_claw.tools package.  
2. It imports key classes and functions from submodules within the same tools package.  
3. The imported names include registry-related types and many concrete Tool implementations.  
4. After importing, it defines the package's public API by populating the __all__ list.  
5. The file itself contains no function or class definitions beyond the import and export statements.  
6. Importing this module causes the referenced submodules to be imported and their top-level code to run.  
7. The module aggregates many tool implementations so callers can import them from a single location.  
8. The __all__ list explicitly enumerates the public symbols that should be exported from the package.  
9. The file acts as a convenient façade that centralizes tool names for external consumers.  
10. It is a lightweight module focused on namespace composition rather than implementing logic.

Purpose:
This module exists to present a single, consolidated public interface for the captain_claw.tools package so consumers can import frequently used tools and registry types from one location. By importing specific names from submodules and listing them in __all__, it documents and restricts what is considered the public API of the tools package. It reduces the need for external code to know internal submodule paths, simplifying imports like "from captain_claw.tools import ShellTool" instead of deeper module paths. The file ensures consistent exposure of registry primitives (Tool, ToolPolicy, ToolRegistry, ToolResult, get_tool_registry) alongside concrete Tool implementations. It collects a variety of tool implementations—file readers/writers, web fetchers, document extractors, and integrations—so the package consumer has immediate access to common functionality. The explicit __all__ helps tools like "from ... import *" behave predictably by listing intended exports. Because the initializer performs imports, it centralizes potential import-time side effects of submodules in one place. It also serves as documentation by naming the core building blocks and integrations the package provides. The module's existence supports maintainability by providing a single location to update which tools are public without editing every submodule's consumers. Finally, it keeps the package surface stable and readable, making it clear which components are part of the supported API.

Key elements:
- Tool (class from captain_claw.tools.registry; registry primitive)  
- ToolPolicy (class from captain_claw.tools.registry; policy abstraction)  
- ToolPolicyChain (class from captain_claw.tools.registry; policy composition)  
- ToolRegistry (class from captain_claw.tools.registry; registry management)  
- ToolResult (class from captain_claw.tools.registry; standardized result type)  
- get_tool_registry (function from captain_claw.tools.registry; access helper)  
- ShellTool (class from captain_claw.tools.shell; shell command tool)  
- ReadTool (class from captain_claw.tools.read; file read tool)  
- WriteTool (class from captain_claw.tools.write; file write tool)  
- GlobTool (class from captain_claw.tools.glob; filesystem globbing tool)  
- WebFetchTool (class from captain_claw.tools.web_fetch; HTTP fetcher)  
- WebGetTool (class from captain_claw.tools.web_fetch; HTTP GET helper)  
- WebSearchTool (class from captain_claw.tools.web_search; web search tool)  
- DocxExtractTool (class from captain_claw.tools.document_extract; DOCX extractor)  
- PdfExtractTool (class from captain_claw.tools.document_extract; PDF extractor)  
- PptxExtractTool (class from captain_claw.tools.document_extract; PPTX extractor)  
- XlsxExtractTool (class from captain_claw.tools.document_extract; XLSX extractor)  
- PocketTTSTool (class from captain_claw.tools.pocket_tts; text-to-speech tool)  
- SendMailTool (class from captain_claw.tools.send_mail; email sender)  
- GoogleDriveTool (class from captain_claw.tools.google_drive; Drive integration)  
- TodoTool (class from captain_claw.tools.todo; todo list tool)  
- ContactsTool (class from captain_claw.tools.contacts; contacts integration)  
- ScriptsTool (class from captain_claw.tools.scripts; script runner)  
- ApisTool (class from captain_claw.tools.apis; external API helper)  
- TypesenseTool (class from captain_claw.tools.typesense; Typesense integration)  
- __all__ (list; enumerates the module's public symbols)

Key logic:
1. The module's primary control action is importing selected names from submodules so they become attributes of the package namespace.  
2. Each import statement references a submodule and specific symbols, which triggers Python to load and execute those submodules if they are not already loaded.  
3. By importing registry types first, the file exposes foundational types used by other tool implementations.  
4. The subsequent imports gather concrete Tool implementations that depend on those registry types.  
5. After imports complete, the module constructs the __all__ list containing string names that mirror the imported symbols.  
6. The __all__ list determines which names are exported when clients use "from captain_claw.tools import *".  
7. The module does not perform runtime computation, configuration, or initialization beyond these imports and the __all__ assignment.  
8. Because imports execute submodule code, any top-level initialization in those modules runs as a side effect of importing this package initializer.  
9. The file acts as a namespace aggregator rather than implementing algorithms; its logic centers on composition and exposure of symbols.  
10. Changes to the imported list or __all__ alter the package's public API and affect how external code imports tools.  
11. The order of imports can influence import-time behavior if submodules have dependencies on each other or on registry symbols.  
12. Overall, the module's logic is simple and deterministic: import named symbols and publish them via __all__.

---

## captain-claw-src/captain_claw/tools/glob.py

Description:
1. This module implements a glob-based file discovery tool.  
2. It provides a GlobTool class that inherits from a generic Tool base class.  
3. The module defines metadata on the tool including a name, description, and a parameters JSON schema.  
4. The core feature is an asynchronous execute method that accepts a glob pattern, optional root, and a limit.  
5. The execute method uses pathlib.Path to combine a provided root with the pattern when a root is given.  
6. It delegates the actual filesystem globbing to Python's built-in glob.glob function executed inside an executor to avoid blocking the event loop.  
7. The method applies a configurable result limit and formats the matching file paths into a human-readable string.  
8. If no matches are found the tool returns a successful ToolResult with a message indicating that no files were found.  
9. Any exceptions raised during execution are caught, logged via the module logger, and returned as a failed ToolResult.  
10. The module imports and uses a ToolResult type to standardize success/error responses.

Purpose:
This file exists to expose a reusable, asynchronous file-finding capability within the codebase by wrapping standard globbing functionality in the project's Tool interface. By defining name, description, and parameters metadata it makes the glob operation discoverable and describable to any system components that inspect tool metadata (for example a tool registry or UI). The execute method offers a non-blocking implementation suitable for integration into asynchronous workflows and agents that expect coroutine-based tools. The parameters schema documents accepted inputs such as the glob pattern, optional root directory, and an optional limit on results, which supports validation and tooling around invocation. Returning a ToolResult ensures consistent success/error payload structure compatible with other tools in the same framework. The module centralizes error handling and logging so callers receive clear failure information while internal errors are recorded for debugging. Using run_in_executor to call glob.glob avoids blocking the event loop while reusing the standard library's globbing semantics including recursive patterns. The formatted output (count plus newline-separated paths) makes it straightforward for consumers to display or parse search results. Limiting results by slicing protects consumers from extremely large result sets by default. Overall, the file exists to provide a simple, documented, and async-friendly file search tool that fits into the project's tool registry and execution model.

Key elements:
- GlobTool (class) (subclass of Tool that implements the file-finding tool).  
- name (attribute) (tool identifier, set to "glob").  
- description (attribute) (short description of the tool's purpose).  
- parameters (dict) (JSON schema describing "pattern", optional "root", and "limit").  
- execute (async method) (main entry point that performs the glob search and returns a ToolResult).  
- pathlib.Path (usage) (used to join root and pattern when root is provided).  
- asyncio.get_event_loop and loop.run_in_executor (calls) (used to run glob.glob without blocking the event loop).  
- glob.glob (function) (standard library call used to perform the filesystem matching with recursive=True).  
- ToolResult (type) (used for structured success/error return values).  
- get_logger / log.error (logging) (module logger used to report failures).

Key logic:
The execute method begins by accepting a required pattern and optional root and limit parameters, with a default limit of 100. If a root is provided it constructs a combined pattern by joining the root path and the given pattern using pathlib.Path, ensuring the search starts from the specified directory. To perform the file matching without blocking asynchronous execution, it obtains the current event loop and schedules a synchronous glob.glob call in an executor via loop.run_in_executor. The glob.glob call is invoked with recursive=True so patterns like "**/*.py" will match across subdirectories. Once the executor returns the full list of matches, the method immediately applies slicing to enforce the provided limit and prevent returning more than the allowed number of results. If the matches list is empty after the search, the method returns a ToolResult that indicates success and contains a brief message stating no files were found for the provided pattern. If there are matches, the method composes a multi-line string that begins with "Found N file(s):" followed by each matched path on its own indented line, and returns that string in a successful ToolResult. The entire operation is wrapped in a try/except block; any exception raised during path handling, executor scheduling, or globbing is caught. On exception the code logs an error with the pattern and serialized error string using the module logger. After logging, the method returns a ToolResult marked as a failure with the error message included so callers can react accordingly. The method relies only on standard library globbing semantics and the surrounding Tool/ToolResult types to integrate results into the broader tool execution framework.

---

## captain-claw-src/captain_claw/tools/apis.py

Description:
1. This module provides an ApisTool class for managing a persistent collection of API definitions across sessions.  
2. The tool registers metadata including name, description, and a JSON schema for accepted parameters.  
3. The main entrypoint is an asynchronous execute method that dispatches actions like add, list, search, info, update, and remove.  
4. Each action is implemented as a static asynchronous helper method prefixed with an underscore.  
5. The add action validates required fields and calls the session manager to create a new API record.  
6. The list and search actions fetch multiple API entries and format concise textual summaries.  
7. The info action retrieves a single API and assembles detailed fields into a multi-line description.  
8. The update action builds a dictionary of provided fields and calls the session manager to apply changes.  
9. The remove action verifies existence and delegates deletion to the session manager.  
10. Errors are caught at the top level, logged, and returned as failed ToolResult objects.

Purpose:
This file exists to centralize CRUD-like operations for APIs stored in the application's persistent session manager. It exposes a single tool implementing a consistent interface so other parts of the system can discover and invoke API management actions uniformly. By defining a parameters schema the tool makes its expected inputs explicit for tooling, validation, or UI generation. It delegates all storage and retrieval responsibilities to the session manager to keep persistence details out of the tool. The module formats human-readable results for list, search, and info actions so that callers receive concise textual output suitable for display. Validation checks prevent missing required fields from being sent to the session manager and provide clear error messages to callers. The update implementation supports partial updates by collecting only provided fields and refusing to call the session manager when nothing is supplied. The list and search methods impose default limits when requesting many items, providing predictable output sizes. Centralized logging of unexpected exceptions helps with troubleshooting and auditing of tool usage. The tool returns ToolResult instances uniformly for success and failure, integrating with the project's tooling framework. Overall, this module exists to be the authoritative, safe, and user-friendly interface for registering, discovering, inspecting, modifying, and deleting API definitions used by the application.

Key elements:
- ApisTool (class; subclass of Tool implementing API management actions).  
- name, description, parameters (module/class-level metadata; defines tool identity and JSON schema).  
- execute (async method; dispatches based on action parameter and handles top-level errors).  
- _add (static async; validates inputs and calls sm.create_api).  
- _list (static async; calls sm.list_apis and formats entries).  
- _search (static async; validates query and calls sm.search_apis).  
- _info (static async; calls sm.select_api and composes detailed output).  
- _update (static async; builds kwargs from provided fields and calls sm.update_api).  
- _remove (static async; calls sm.select_api then sm.delete_api).  
- get_session_manager (external call; obtains the session manager instance).  
- ToolResult (imported type; used for standardized success/error responses).  
- get_logger / log (logging setup; used to report errors).

Key logic:
The execute method begins by extracting an optional session identifier from kwargs and acquiring the session manager instance. It uses the provided action string to route the request to the corresponding helper method and wraps the entire dispatch in a try/except to log and return errors as ToolResult failures. The _add helper enforces that name and base_url are present and non-empty, then calls sm.create_api with provided fields and the source session, returning a success message containing a short form of the new API id. The _list helper requests up to 50 APIs from sm.list_apis, handles the empty case with a friendly message, and otherwise builds one-line summaries that include an index, optional auth type, base URL, use count, and shortened id. The _search helper requires a non-empty query, calls sm.search_apis with a 20-item limit, and formats matching results similarly to list. The _info helper requires an api_id, selects the API via sm.select_api, and then conditionally includes available attributes (auth, credentials, endpoints, description, purpose, tags, use count, timestamps) in a multi-line output. The _update helper requires an api_id, resolves the target via sm.select_api, then collects only the provided non-None fields into a kwargs dict and returns an error if no fields were given; it calls sm.update_api and reports success or failure accordingly. The _remove helper verifies the api exists with sm.select_api, calls sm.delete_api, and reports whether deletion succeeded. Throughout these helpers, returned messages are plain text composed for human consumption rather than structured objects. Top-level exception handling logs the action and error string and ensures the tool reports failure rather than raising. The module relies on the session manager for all persistent operations and on ToolResult to normalize function outputs.

---

## captain-claw-src/captain_claw/tools/scripts.py

Description:
1. This module defines a ScriptsTool class that provides persistent cross-session management for script/file metadata.  
2. The tool exposes a parameters JSON schema describing accepted fields and the allowed actions.  
3. The main entrypoint is an asynchronous execute method that dispatches based on the action parameter.  
4. Supported actions are add, list, search, info, update, and remove, each handled by a corresponding static async helper.  
5. The add action validates required inputs and delegates creation to the session manager.  
6. The list and search actions query the session manager for matching script records and format human-readable summaries.  
7. The info action retrieves a single script record and assembles a multi-line detail view containing available fields.  
8. The update action selects a script, builds an update payload from provided fields, and requests the session manager to apply changes.  
9. The remove action validates existence and asks the session manager to delete the script.  
10. Errors during execution are logged and returned as failed ToolResult objects.

Purpose:
This file exists to provide a single, discoverable tool that other parts of the application can invoke to manage script metadata consistently. It centralizes CRUD-like operations for scripts so persistence details are encapsulated behind a uniform interface. By declaring a parameters schema it makes expected inputs explicit for validation, tooling, or UI generation. The tool persists and queries attributes such as name, file_path, description, purpose, language, created_reason, tags, usage counts, and timestamps via the session manager. It therefore acts as the application surface for registering, locating, inspecting, updating, and removing script records that survive across sessions. The implementation focuses on input validation, formatting of textual summaries, and clear success/error ToolResult responses. The class logs errors to aid debugging and returns structured failure messages instead of raising exceptions outward. Static helper methods keep each action's logic isolated and testable. The module avoids directly handling storage and instead relies on the session manager API, keeping concerns separated. Overall, it exists to make script metadata operations predictable, discoverable, and uniform for callers of the tools registry.

Key elements:
- ScriptsTool (class) — inherits from Tool and encapsulates script management functionality.  
- name, description (class attrs) — human-readable tool identity and long description.  
- parameters (class attr) — JSON schema specifying accepted properties and required action.  
- execute (async method) — main dispatcher that routes actions to helper methods and handles exceptions.  
- _add (static async) — validates inputs and calls session manager create_script.  
- _list (static async) — calls session manager list_scripts and formats a numbered summary.  
- _search (static async) — validates query and calls session manager search_scripts to format matches.  
- _info (static async) — calls session manager select_script and builds a detailed multi-line view.  
- _update (static async) — selects a script, assembles update kwargs, and calls session manager update_script.  
- _remove (static async) — selects a script and calls session manager delete_script.  
- get_session_manager (imported function) — used to obtain the session manager instance.  
- get_logger / log (imported) — logging facility used to record errors.  
- ToolResult (imported) — standardized return object for success/error responses.  
- session manager methods (external calls) — create_script, list_scripts, search_scripts, select_script, update_script, delete_script.

Key logic:
The module's control flow centers on the execute method which first extracts an optional session_id from kwargs and obtains the session manager instance. execute then checks the action string and forwards the call to the matching static helper, returning its ToolResult; unknown actions immediately produce a failure ToolResult. A top-level try/except around the dispatch ensures any unexpected exception is logged and returned as an error ToolResult. Each helper method performs focused validation for required parameters and returns explicit error ToolResult objects when validation fails. The _add helper requires a non-empty name and file_path, calls sm.create_script with provided metadata, and returns a success message including the short form of the new item's id. The _list helper requests up to 50 scripts, returns a "no scripts" message when empty, or formats each entry with index, optional language, path, use count, and truncated id. The _search helper requires a non-empty query, calls sm.search_scripts with a limit, and formats results similarly to list. The _info helper requires a script identifier, selects the script via sm.select_script, and conditionally appends available fields (language, description, purpose, tags, usage, timestamps) to a multi-line response. The _update helper selects the target script, accumulates only the provided fields into an update payload, refuses to proceed if no fields are supplied, and calls sm.update_script, returning success or failure accordingly. The _remove helper ensures the script exists via selection, calls sm.delete_script, and reports deletion success or failure. All helpers are asynchronous and static, enabling predictable concurrency behavior and making them easy to call without class state.

---

## captain-claw-src/captain_claw/tools/document_extract.py

Description:
1. This module implements document extraction tools that convert PDF, DOCX, XLSX, and PPTX files into Markdown.  
2. It defines helper routines for normalizing text, escaping Markdown table cells, truncating output, and validating file paths.  
3. DOCX extraction reads the ZIP package, parses word/document.xml with ElementTree, and renders paragraphs and tables as Markdown.  
4. XLSX extraction reads shared strings and workbook relationships from the XLSX ZIP, resolves sheet targets, and emits sheet data as Markdown tables.  
5. PPTX extraction enumerates slide XML files, collects paragraph text from drawingML nodes, and formats slides as Markdown sections.  
6. PDF extraction attempts to import pypdf, reads pages up to a limit, and extracts text to Markdown while returning a dependency error if pypdf is not present.  
7. The module exposes four asynchronous Tool subclasses (PdfExtractTool, DocxExtractTool, XlsxExtractTool, PptxExtractTool) with JSON parameter schemas.  
8. Each Tool validates that the provided path exists and is a file, then runs blocking extraction logic on a thread via asyncio.to_thread.  
9. Extracted content is normalized, assembled into Markdown structures (headings, lists, tables), and truncated to a requested character limit.  
10. The code logs exceptions and returns structured ToolResult objects indicating success or error conditions.

Purpose:
This file exists to centralize file-format-specific extraction logic and present a uniform Markdown output interface for downstream consumers. It provides programmatic tools that other parts of the project can call to convert common document types into searchable, displayable Markdown. By grouping format parsing and normalization here, callers need not manage ZIP/XML parsing, shared strings resolution, or pypdf usage themselves. The tools expose parameter schemas so they can be invoked with validated inputs and consistent options such as maximum characters, pages, rows, or slides. Running heavy extraction on background threads via asyncio.to_thread keeps the asynchronous API non-blocking while reusing synchronous XML and ZIP parsing code. The module also encapsulates common sanitization behaviors, like escaping Markdown table separators and normalizing whitespace, ensuring consistent output across formats. Error handling for malformed archives, missing XML parts, and missing optional dependencies is centralized so callers receive clear messages. Logging of exceptions provides diagnostics while ToolResult objects deliver machine-readable status and content. The design supports safe truncation to avoid returning excessively large payloads. Overall, this module exists to make document-to-Markdown conversion reliable, consistent, and easy to call from the larger application.

Key elements:
- _escape_md_cell (function) — escapes '|' and newlines for Markdown table cells.  
- _normalize_text (function) — collapses internal whitespace while preserving line boundaries.  
- _truncate_markdown (function) — trims Markdown to a max character length with a truncation suffix.  
- _require_existing_file (function) — validates and resolves a filesystem path to an existing file.  
- _local_name (function) — strips XML namespace to obtain the local tag name.  
- _extract_docx_paragraph_text (function) — concatenates text nodes from a DOCX paragraph element.  
- _extract_docx_table_markdown (function) — converts a DOCX table element into Markdown table lines.  
- _extract_docx_markdown (function) — orchestrates DOCX document.xml parsing and Markdown rendering.  
- _xlsx_col_to_index / _xlsx_index_to_col (functions) — convert between Excel column letters and zero-based indices.  
- _extract_xlsx_markdown (function) — parses XLSX archive, shared strings, workbook relationships, and renders sheets as Markdown tables.  
- _extract_pptx_markdown (function) — finds slide XML entries and extracts paragraph text into slide sections.  
- _extract_pdf_markdown (function) — uses pypdf to read PDF pages and extract text; returns content and error.  
- PdfExtractTool, DocxExtractTool, XlsxExtractTool, PptxExtractTool (classes) — Tool subclasses exposing parameter schemas and async execute entrypoints.  
- External dependencies referenced (modules): zipfile, xml.etree.ElementTree (ET), re, asyncio, pathlib.Path, pypdf (optional), captain_claw.logging.get_logger, captain_claw.tools.registry.Tool and ToolResult.

Key logic:
1. The module begins with small utility functions to sanitize and normalize extracted text and to enforce a maximum returned character count.  
2. _require_existing_file centralizes path resolution and existence checks so each Tool execute method can quickly validate input before extraction.  
3. DOCX extraction opens the .docx ZIP, reads word/document.xml, locates the document body, and iterates child elements to classify paragraphs and tables.  
4. Paragraphs are processed by collecting all w:t nodes; paragraph styles and numbering properties are inspected to render headings and list items appropriately.  
5. DOCX tables are traversed row-by-row and cell-by-cell; cell paragraphs are concatenated, empty rows are skipped, the table is normalized to a consistent column width, and Markdown table syntax is generated with header and separator rows.  
6. XLSX extraction first reads sharedStrings (if present) to resolve string cell indices, then parses workbook.xml and its relationship file to map sheets to their XML parts inside the archive.  
7. For each sheet, rows are iterated up to max_rows; each cell's column index is computed from its reference, its type (inlineStr, s, b, or default) is used to determine how to read and normalize the value, and rows without content are skipped.  
8. The XLSX logic computes a header row (using existing header cells or fallback column letters), pads rows to equal width, and produces Markdown table lines with escaped cell content.  
9. PPTX extraction enumerates entries matching the slide filename pattern, sorts them, parses each slide XML, collects drawingML text nodes, and emits slide headings followed by bulleted paragraph text or a marker for empty slides.  
10. PDF extraction attempts to import pypdf, opening the reader and iterating pages up to max_pages, extracting page text via page.extract_text(), normalizing it, and assembling per-page Markdown sections; if pypdf is unavailable a descriptive error is returned.  
11. Each Tool subclass defines a JSON parameters schema, uses _require_existing_file in execute to validate the path, and then calls the corresponding extraction function on a background thread with asyncio.to_thread to avoid blocking the event loop.  
12. Returned content from extractors is truncated with _truncate_markdown according to max_chars before being wrapped in a successful ToolResult; known exceptions like KeyError or zipfile.BadZipFile are caught and translated into user-facing error messages.  
13. The module logs unexpected exceptions with context (path and error) and returns failed ToolResult objects when runtime errors occur.  
14. Overall, control flow emphasizes safe file validation, format-specific parsing strategies based on XML/ZIP structure, normalization and escaping for Markdown safety, and asynchronous wrappers that provide a consistent interface to callers.

---

## captain-claw-src/captain_claw/tools/web_search.py

Description:
1. This module implements a WebSearchTool class that uses the Brave Search API to perform web searches.  
2. It defines the tool's metadata including name, description, and a JSON schema for accepted parameters.  
3. The class constructs an async httpx.AsyncClient with a custom User-Agent for performing requests.  
4. The execute method validates the incoming query, reads configuration, and enforces that the provider is Brave.  
5. API key resolution is attempted from configuration first and then from the BRAVE_API_KEY environment variable.  
6. The tool builds request parameters such as count, offset, country, search language, freshness, and safesearch.  
7. Requests include an X-Subscription-Token header for authentication and expect JSON responses from Brave.  
8. Response parsing extracts web results and formats them into a plain-text list with titles, URLs, and snippets.  
9. A helper _clean_text normalizes whitespace and truncates long fields for safe display in results.  
10. Errors from HTTP status failures and other exceptions are logged and returned as ToolResult error responses.

Purpose:
This file provides an integrated web search capability for the project by wrapping Brave Search into a reusable Tool object. It exists so higher-level components can perform web lookups through a consistent Tool interface and receive normalized, safe text output. The configuration-driven design allows administrators to supply API keys and override base URL, timeout, and default result limits without changing code. It centralizes authentication logic including support for an environment variable fallback (BRAVE_API_KEY). Parameter validation and clamping logic (e.g., min/max count and non-negative offsets) protect downstream consumers from invalid or excessive requests. The tool enforces a single supported provider ("brave") to keep implementation focused and predictable. Formatting of results into a compact, human-readable text block simplifies presentation for agents or logs that consume ToolResult content. Error handling captures HTTP status details and response bodies when available to aid debugging. The async client pattern and an explicit close method enable clean resource management in async runtimes. Overall, the module exists to offer a reliable, configurable, and easy-to-use web search primitive for the larger system.

Key elements:
- WebSearchTool (class) — main Tool implementation for Brave Search.  
- name, description, parameters (class attributes) — metadata and parameter schema.  
- __init__ (method) — constructs httpx.AsyncClient with custom User-Agent.  
- _clean_text (static method) — normalizes whitespace and truncates output.  
- execute (async method) — performs validation, builds request, calls Brave API, and formats results.  
- close (async method) — closes the httpx client.  
- httpx.AsyncClient (dependency) — used for async HTTP requests.  
- get_config (import) — reads runtime configuration for tool settings.  
- get_logger (import) — used for logging errors.  
- Tool, ToolResult (imports) — base types from the tools registry used for interface and results.  
- BRAVE_API_KEY (environment variable) — alternate source for the API key.  
- X-Subscription-Token header (HTTP header) — used for API authentication.

Key logic:
1. On construction, the class creates an httpx.AsyncClient configured to follow redirects and present a specific User-Agent.  
2. The _clean_text helper normalizes whitespace and enforces a maximum character length, appending an explicit truncation marker when needed.  
3. The execute method first trims and validates the required query string and returns a ToolResult error if it is missing.  
4. It loads tool-specific configuration via get_config and ensures the configured provider is "brave", otherwise returning an error.  
5. The method resolves the API key from configuration or the BRAVE_API_KEY environment variable and fails early if no key is found.  
6. It computes effective request parameters: base URL, timeout, default and requested counts (clamped between 1 and 20), offset (non-negative), and a validated safesearch value.  
7. Optional parameters country, search_lang, and freshness are included only when provided and non-empty.  
8. Headers are prepared with Accept: application/json and X-Subscription-Token set to the resolved API key.  
9. An asynchronous GET request is issued to the Brave endpoint with prepared params and headers; response.raise_for_status() is used to surface HTTP errors.  
10. On a successful response the JSON payload is inspected for a "web" block and a "results" list; non-list or malformed data is tolerated by normalizing to an empty list.  
11. Each result dictionary is sanitized using _clean_text for title and description, and results are rendered into a numbered plain-text summary including URL and snippet.  
12. HTTPStatusError handling extracts response body where possible, creates a concise error detail (including truncated body), logs the failure, and returns a ToolResult with the error.  
13. A generic exception handler logs and returns other unexpected errors as ToolResult failures.  
14. The close method asynchronously closes the underlying httpx client to release network resources.

---

## captain-claw-src/captain_claw/tools/google_drive.py

Description:
1. This module implements a GoogleDriveTool class that provides actions to list, search, read, get info, upload, create, and update files on Google Drive.  
2. It communicates with the Google Drive REST API v3 using an httpx.AsyncClient and OAuth2 Bearer tokens obtained from a session-managed GoogleOAuthManager.  
3. The tool exposes a JSON schema for accepted parameters and validates required action names before dispatching.  
4. For reading files it inspects file metadata and either exports Google Workspace documents, downloads and extracts binary formats, lists folder contents, or returns text downloads for plain files.  
5. Exported Google Workspace files are requested in mapped export MIME types (with a fallback for unsupported markdown exports) and truncated if larger than a configured maximum.  
6. Binary files that match known extractable MIME types are downloaded to a temporary file and processed by dynamically loaded extract tools.  
7. Upload and create operations use a multipart/related upload implementation that constructs a boundary-delimited body and posts it to the Drive upload endpoint.  
8. Update operations send a media patch request to replace file content, handling either provided text content or a local file.  
9. The module centralizes error handling by translating HTTP status errors into user-friendly ToolResult messages for common Drive error codes.  
10. Utility helpers include metadata retrieval, size formatting, extraction tool resolution, and a close method to terminate the internal HTTP client.

Purpose:
This file exists to encapsulate all interactions with Google Drive into a single reusable Tool object so higher-level components can perform Drive operations without dealing with raw HTTP or OAuth details. It centralizes token retrieval and scope validation to ensure requests are authorized and the Drive scope is present before any API call. By providing a uniform execute(...) entrypoint and a parameters schema, the tool fits into the project's tool registry and can be invoked programmatically with predictable inputs and outputs. The read path handles multiple content types so the rest of the application receives readable text or descriptive errors regardless of whether a file is a Google Doc, a binary Office file, a PDF, or plain text. Upload, create, and update flows are implemented to support both Google Workspace conversion and standard file uploads, allowing users to create native Google Docs or store plain files. The module performs client-side checks and truncation for large content to protect downstream consumers from excessive payloads. Error mapping converts Drive API errors into concise messages that explain authentication, permission, not-found, and rate-limit issues, improving operator experience. The design avoids external Google SDKs by using direct REST calls, keeping dependencies minimal and the behavior transparent. Dynamic loading of extract tools enables integration with existing file-extraction utilities in the codebase without hard-coding those implementations. Overall, it exists to provide a high-level, robust, and consistent interface for Drive operations within the Captain Claw system while handling common edge cases like large files, conversion fallbacks, and multi-drive support.

Key elements:
- GoogleDriveTool (class) (main tool providing Drive actions and integrating with the tool registry)  
- name, description, parameters (class attributes) (tool metadata and JSON schema)  
- __init__ (constructor) (creates httpx.AsyncClient with custom User-Agent)  
- execute(action, **kwargs) (dispatch method, token retrieval, error handling)  
- _get_access_token (token retrieval via GoogleOAuthManager and session manager)  
- _auth_headers (builds Authorization header)  
- _handle_http_error (maps HTTPStatusError to ToolResult with friendly messages)  
- _action_list, _action_search, _action_read, _action_info, _action_upload, _action_create, _action_update (action handlers)  
- _export_google_file, _download_and_extract, _download_as_text (reading/exporting helpers for different mime types)  
- _multipart_upload (constructs multipart/related upload body and posts to upload API)  
- _get_file_metadata (fetches file metadata from Drive)  
- _get_extract_tool (dynamic importer for extract tools like pdf_extract, docx_extract)  
- _format_size (human-readable byte size formatting)  
- close (closes the internal httpx client)  
- Constants: _DRIVE_API, _UPLOAD_API, _DRIVE_SCOPE, _GOOGLE_EXPORT_MAP, _EXTRACTABLE_MIMES, _MAX_READ_BYTES (configuration and mappings)  
- External deps: httpx.AsyncClient, GoogleOAuthManager, get_session_manager, Tool/ToolResult, tempfile, io, json, pathlib.Path

Key logic:
The module's primary control flow begins in execute(...), which strips injected runtime kwargs, attempts to obtain an OAuth access token via a GoogleOAuthManager-backed session, and then dispatches to a specific action handler based on the provided action string. Token retrieval checks that tokens exist and that the Drive scope is granted, raising user-oriented RuntimeError messages if not. Handlers are looked up in a mapping and called with the resolved token; HTTP and generic exceptions are caught and converted into ToolResult error responses, with HTTPStatusError routed through a dedicated mapper that translates common status codes into helpful messages. Listing constructs a Drive files query for the given parent folder, requests the configured fields, and formats results into a readable list including size (formatted) and modified date. Search builds an escaped query that searches both filename and full text, uses a pageSize limit, and optionally applies ordering; it formats matched files similarly to list. Reading begins by fetching file metadata; behavior then branches by MIME type: Google Workspace types are exported using mapped export MIME types (with a fallback for markdown), extractable binary types are downloaded to a temporary file and passed to an extraction tool, folders invoke the list action for that folder, and other files are downloaded as text with truncation and decoding checks. Binary extraction enforces a maximum download size and writes content to a temp file before invoking a dynamically resolved extract tool; temporary files are cleaned up in a finally block. Upload and create flows build metadata and content bytes, determine content types (including guesses via mimetypes), and call _multipart_upload to send a multipart/related request to the Drive upload endpoint, optionally requesting conversion to Google Workspace types. Update performs a media patch against the upload API to replace file contents and supports either direct text content or uploading from a local path. The multipart upload implementation composes a custom boundary, writes the JSON metadata and raw content into an in-memory bytes buffer following Drive's multipart spec, posts with appropriate headers, and returns the JSON response. Utility helpers provide metadata fetching, extract-tool lookup by name with local imports, human-readable size formatting, and an async close method to terminate the httpx client. The module consistently enforces size limits configured by _MAX_READ_BYTES and other thresholds to avoid excessive memory or processing.

---

## captain-claw-src/captain_claw/tools/todo.py

Description:
1. This module implements a TodoTool class that provides a simple persistent cross-session to-do list manager.  
2. The tool is a subclass of Tool and exposes a JSON schema for parameters that includes actions "add", "list", "update", and "remove".  
3. The module extracts an optional session identifier from provided kwargs and obtains a session manager via get_session_manager().  
4. The execute method dispatches based on the "action" parameter and forwards other parameters to internal helper methods.  
5. Helper methods _add, _list, _update, and _remove are defined as async static methods that interact with the session manager to perform storage operations.  
6. _add validates content, supplies default responsible and priority values, and calls sm.create_todo to persist a new item.  
7. _list queries sm.list_todos with optional filters and formats results into a numbered plain-text listing that includes truncated item ids.  
8. _update and _remove both select a target item via sm.select_todo and then call sm.update_todo or sm.delete_todo, returning success or error ToolResult values.  
9. The module uses a module-level _PRIORITY_ORDER mapping and a logger obtained via get_logger, and it wraps execution in a try/except to log and return errors.  
10. All operations return ToolResult objects indicating success, content messages, or error descriptions suitable for user-facing responses.

Purpose:
1. The file exists to provide a reusable tool that external components can call to manage persistent to-do items across user or bot sessions.  
2. It centralizes to-do manipulation logic so callers need only specify a high-level action and minimal parameters instead of interacting with low-level storage APIs.  
3. By defining a JSON parameters schema the tool documents expected inputs and constrains allowed values for status, priority, and responsible fields.  
4. The tool integrates with the session management subsystem to attribute created items to a source session and to optionally scope listings to a session.  
5. It supports both human and bot assignment semantics through a responsible field and provides default behavior for common add operations.  
6. The list action supports simple filtering by status and responsible party, enabling callers to request focused views without post-filtering.  
7. Update and remove actions encapsulate selection semantics and error reporting when an item cannot be found, abstracting selection logic via the session manager.  
8. Returning ToolResult objects keeps the tool consistent with the broader tool registry and execution framework used by the project.  
9. The module logs unexpected exceptions to aid debugging while converting runtime failures into structured ToolResult errors for downstream handling.  
10. It provides textual, human-readable summaries for operations (e.g., created/updated/removed messages and formatted list lines) to simplify presentation in chat or UI contexts.  
11. The presence of a priority ordering mapping suggests integration with priority-aware sorting or display elsewhere, even though the mapping is not used within the file's methods.  
12. Overall, the module exists to make to-do item lifecycle operations simple, consistent, and accessible to other subsystems without exposing storage implementation details.

Key elements:
- _PRIORITY_ORDER (dict) (module-level priority ranking mapping: urgent→0, high→1, normal→2, low→3).  
- log (logger) (module logger via get_logger for error logging).  
- TodoTool (class) (Tool subclass implementing the to-do management interface).  
- TodoTool.name (str) (tool name "todo").  
- TodoTool.description (str) (human-readable tool description used by registry).  
- TodoTool.parameters (dict) (JSON schema describing accepted parameters and enums).  
- execute (async method) (dispatches "add", "list", "update", "remove" actions and handles exceptions).  
- _add (async static method) (validates content; calls sm.create_todo; returns creation message).  
- _list (async static method) (calls sm.list_todos; formats and returns a numbered list).  
- _update (async static method) (validates todo_id; selects item via sm.select_todo; calls sm.update_todo).  
- _remove (async static method) (validates todo_id; selects item via sm.select_todo; calls sm.delete_todo).  
- get_session_manager (external call) (used to obtain session manager instance).  
- ToolResult (type) (used for all method return values to indicate success/content/error).

Key logic:
1. The execute method begins by extracting a session identifier from kwargs and obtaining the session manager instance for subsequent storage operations.  
2. It uses the provided "action" parameter to choose which internal async helper to run: "add" → _add, "list" → _list, "update" → _update, "remove" → _remove.  
3. Each helper method performs its own input validation: _add requires non-empty content, while _update and _remove require a todo_id.  
4. For creating items, _add supplies defaults for responsible ("bot") and priority ("normal") when not provided, and passes tags and context through to sm.create_todo.  
5. _add returns a ToolResult with a success flag and a short message including the first eight characters of the created item's id.  
6. Listing queries sm.list_todos with limit and optional status/responsible/session filters, then iterates results to build formatted lines that include priority, responsible, content, status, optional tags, and truncated ids.  
7. The update flow selects the target via sm.select_todo(todo_id); if selection fails it returns an error ToolResult; if selection succeeds it calls sm.update_todo with provided fields and reports failure or success accordingly.  
8. The remove flow similarly selects the item and then calls sm.delete_todo, returning a failure ToolResult if deletion did not succeed or a success message when it does.  
9. All helper methods interact exclusively with the session manager interface (create_todo, list_todos, select_todo, update_todo, delete_todo) to keep storage details encapsulated.  
10. The module-level _PRIORITY_ORDER exists as a mapping for priority ranking but is not referenced by the implemented methods, indicating either future use or external reliance on the mapping.  
11. Errors raised during execute are caught, logged with context including the action and error string, and converted into a ToolResult with success=False.  
12. Output from each operation is deliberately textual and concise, optimized for presentation in user-facing contexts (chat/UIs) rather than returning raw data structures.

---

## captain-claw-src/captain_claw/tools/typesense.py

Description:
1. This module defines a TypesenseTool class that exposes index, search, and delete operations against a configured Typesense deep memory collection.  
2. The tool is a subclass of Tool and declares a JSON parameters schema describing allowed actions and their inputs.  
3. It prefers to delegate to an injected DeepMemoryIndex for chunking, embedding, hybrid search, and schema management when available.  
4. When DeepMemoryIndex is not provided the tool performs raw HTTP operations against a Typesense server using httpx.  
5. The tool lazily constructs an httpx.AsyncClient with configured timeouts and an API key header.  
6. Before performing operations it ensures the target collection exists, creating it via the canonical schema template if necessary.  
7. Indexing computes a deterministic doc_id using an SHA-1 hash of the reference and text snippet and either calls deep_memory.index_document or upserts a single document via the import endpoint.  
8. Searching uses deep_memory.search to run a hybrid query and format results or falls back to the /documents/search endpoint and formats hits.  
9. Deletion supports removing by document_id (deleting all chunks) or by a filter expression, delegating to DeepMemoryIndex when present or issuing HTTP delete requests otherwise.  
10. The module centralizes error handling for httpx and JSON errors, returning ToolResult objects indicating success or failure.  

Purpose:
1. The file exists to provide a tightly controlled interface for LLMs or other components to interact with application deep memory stored in Typesense.  
2. It restricts available operations to indexing, searching, and deletion and prevents creation or arbitrary selection of collections by callers.  
3. By routing through DeepMemoryIndex when available the tool leverages consistent chunking, embedding generation, doc_id management, and search ranking logic already implemented elsewhere in the project.  
4. The fallback HTTP paths exist to allow the tool to function even when DeepMemoryIndex is not wired in, using the configured Typesense host, port, protocol, and API key.  
5. Collection bootstrap code ensures the required schema is present and appends an embedding field sized from deep_memory configuration when appropriate.  
6. The tool exposes a parameter schema for validation and for the tools registry so callers know which inputs are accepted and required.  
7. It centralizes HTTP client configuration (timeouts, headers) and cleans up the client on close to avoid resource leaks.  
8. Error handling converts various httpx exceptions and JSON decoding errors into user-friendly ToolResult error messages and logs warnings for operational issues.  
9. Index and search handlers format human-readable results that include source tags, references, scores, and truncated previews to make responses concise and informative.  
10. Delete handlers support both single-document deletion by doc_id (removing all chunks) and bulk deletion by filter expressions to enable flexible memory management operations.  
11. Overall, the module exists to provide a safe, observable, and consistent bridge between the application’s tools subsystem and the Typesense-backed deep memory store.  
12. It is designed to be resilient by preferring application-level index/search implementations while remaining capable of direct Typesense operations for simpler deployments or bootstrapping scenarios.  

Key elements:
- TypesenseTool (class) (Tool subclass implementing index/search/delete backed by Typesense or DeepMemoryIndex).  
- name, description, timeout_seconds, parameters (class attributes describing tool metadata and JSON schema).  
- __init__ (initializes deep_memory reference, base URL, API key, default collection, timeouts, and lazy client state).  
- _get_collection (returns the enforced collection name from DeepMemoryIndex or default configuration).  
- _ensure_collection (creates/validates collection using DeepMemoryIndex.ensure_collection or raw HTTP and the _COLLECTION_SCHEMA_TEMPLATE).  
- _get_client (lazy-initializes httpx.AsyncClient with configured timeouts and API key header).  
- execute (dispatch method that validates config, ensures collection, routes actions, and handles exceptions).  
- _action_index (handles indexing, computes doc_id via hashlib.sha1, delegates to deep_memory.index_document or POSTs to /documents/import).  
- _action_search (handles query validation and per-page limits, delegates to deep_memory.search or GETs /documents/search and formats results).  
- _action_delete (supports deletion by document_id or filter_by, delegates to deep_memory or issues HTTP DELETE calls).  
- close (async cleanup to close the httpx client).  
- External dependencies: httpx (async HTTP), get_config (config access), get_logger (logging), hashlib/json/time, DeepMemoryIndex and _COLLECTION_SCHEMA_TEMPLATE from captain_claw.deep_memory, ToolResult and Tool base from tools.registry.  

Key logic:
1. The execute method first removes injected runtime kwargs, checks that an API key and collection name are configured, and then attempts to ensure the collection exists before dispatching to an action handler.  
2. A simple handlers mapping routes the action string to _action_index, _action_search, or _action_delete; unknown actions return a ToolResult error.  
3. Exception handling around handler invocation converts httpx connection, HTTP status, generic HTTP, JSON decode, and other exceptions into ToolResult responses and logs warnings for unexpected errors.  
4. _ensure_collection returns immediately if the collection was already ensured; if a DeepMemoryIndex is present it delegates to its ensure_collection method synchronously.  
5. In the fallback creation path _ensure_collection checks for collection existence with a GET, constructs a schema from the canonical template, appends an embedding field when embedding dimensions are configured, and attempts to POST the schema, treating 409 as a non-error.  
6. _get_client lazy-initializes an httpx.AsyncClient with configured timeout and connection timeout values and sets the X-TYPESENSE-API-KEY and Content-Type headers.  
7. _action_index validates that text is present, creates a tag list from a comma-separated string, and computes a deterministic doc_id by hashing reference and a text prefix; if deep_memory exists it calls index_document and returns a summary of chunk count and metadata.  
8. When DeepMemoryIndex is absent the index path constructs a single document dictionary with doc_id, doc_id-backed fields, text, chunk_index 0, and updated_at timestamp, serializes it, and posts it to /collections/{coll}/documents/import with action=upsert.  
9. _action_search enforces a non-empty query and a per_page limit, then either calls deep_memory.search and formats each result with snippet truncation, source tag, location, and score, or performs an HTTP GET to /documents/search with q, query_by, per_page, and optional filter_by and formats hits from the JSON response.  
10. _action_delete requires either document_id or filter_by; for document_id it either calls deep_memory.delete_document (which deletes all chunks) or issues a DELETE with a doc_id filter; for filter-based deletion it delegates to deep_memory.delete_by_filter or issues a DELETE with the provided filter.  
11. HTTP responses are raised for status (resp.raise_for_status()) to surface HTTP errors to the centralized exception handlers; JSON responses are parsed to extract found/hits or num_deleted values to include in ToolResult content.  
12. The close method asynchronously closes the httpx client if present and not already closed to release network resources and reset the client state.

---

## captain-claw-src/captain_claw/tools/read.py

Description:
1. This module defines a ReadTool class that provides an asynchronous execute method for reading file contents.  
2. The tool is declared with a name ("read"), a short description, and a JSON parameters schema that accepts path, limit, and offset.  
3. execute accepts a path string and optional numeric limit and offset values and returns a ToolResult describing success or failure.  
4. The implementation resolves the given path using pathlib.Path.expanduser and resolve, and checks whether the target exists.  
5. If the file is not found on the filesystem the tool attempts to resolve the path via an optional _file_registry passed in kwargs.  
6. If registry resolution fails it also inspects an optional _saved_base_path before reporting a not-found error.  
7. The tool rejects non-file paths and enforces a hard file size limit of 100,000 bytes, returning an error if exceeded.  
8. When allowed, the file is read as UTF-8, split into lines, and sliced according to the offset and limit parameters.  
9. The returned content is prefixed with metadata including the resolved path, character count, and an optional line range.  
10. All exceptions are caught, logged via the module logger, and converted into a failing ToolResult with an error message.

Purpose:
1. The file provides a reusable, well-scoped tool for reading file contents within the project tooling framework.  
2. By implementing a Tool subclass it integrates into the project's tool registry and can be invoked by other components that expect Tool/ToolResult semantics.  
3. The JSON parameters schema documents and enforces the expected inputs (path, limit, offset) for callers or for automated validation.  
4. Registry-based path resolution support allows callers to supply abstract or relative references that can be resolved by an external file registry object.  
5. The optional saved-base fallback mechanism provides an additional scope-aware resolution path for session-scoped file lookups.  
6. The explicit file size limit protects callers and the system from attempting to load excessively large files into memory.  
7. Returning a ToolResult with standardized success/error fields makes the tool's outcomes easy to interpret and chain with other tools.  
8. The inclusion of metadata (path, character count, line range) aids callers in quickly assessing what portion of a file was returned without parsing the content.  
9. Centralized exception handling and logging ensure operational issues are recorded and surface as structured errors rather than crashing callers.  
10. The async signature (async def execute) makes the tool compatible with asynchronous orchestrators even though the implementation performs synchronous file I/O.  
11. The module is minimal and focused, exposing a single primary class to keep the file-reading behavior consistent and auditable.  
12. Overall, it exists to provide a safe, discoverable, and integrable mechanism for reading files by other components in the project.

Key elements:
- ReadTool (class) (Tool subclass implementing file-reading behavior).  
- execute(self, path, limit=None, offset=None, **kwargs) (async method that performs resolution, validation, reading, slicing, and returns ToolResult).  
- name / description / parameters (class attributes declaring tool identity and JSON schema).  
- ToolResult (external type from captain_claw.tools.registry used for structured results).  
- get_logger / log (module logger used for error reporting).  
- Path (pathlib.Path usage for expanduser(), resolve(), is_file(), stat(), read_text()).  
- _file_registry resolution (optional kwargs-based call to file_registry.resolve(path)).  
- _saved_base_path (optional kwargs-based fallback scope value).  
- File size limit constant max_size = 100_000 (enforced before reading).  
- UTF-8 read_text call (file reading with explicit encoding).  

Key logic:
1. The execute method begins by converting the provided path string into a pathlib.Path and normalizing it via expanduser and resolve.  
2. It checks for the file's existence; if the resolved path does not exist it attempts to consult an optional _file_registry passed in kwargs.  
3. If a file_registry is present the code calls file_registry.resolve(path) inside a try/except and, if that returns a resolution, re-resolves that candidate path.  
4. If registry resolution yields a candidate that still does not exist the tool returns a failing ToolResult with a descriptive message.  
5. If no registry resolution is available the code optionally looks for a _saved_base_path but, when no fallback is found, it returns a not-found error.  
6. After a candidate path is established the method verifies the path points to a file (is_file()); non-files cause an immediate error result.  
7. Before reading, the method checks the file size via stat().st_size and compares it to a hard maximum (100,000 bytes), returning an error if the file is too large.  
8. If size checks pass the file is read using read_text with UTF-8 encoding, producing a string that is then split into lines for slicing.  
9. The offset parameter is interpreted as a 1-indexed start line with a floor of 1; selected_lines is taken from that start to the end and then truncated by limit if provided.  
10. The tool computes metadata including the resolved path, total returned character count, and if applicable the returned line range, formatting that as a prefix to content.  
11. A successful ToolResult is returned with success=True and content set to the metadata line followed by the sliced content.  
12. Any exception raised anywhere in the above steps is caught, logged via log.error (including path and the error string), and converted into a failing ToolResult with the exception message.

---

## captain-claw-src/captain_claw/llm/__init__.py

Description:
1. This module implements a small LLM provider framework with concrete providers for Ollama and LiteLLM-backed services.  
2. It defines dataclasses for Message, ToolCall, LLMResponse, and ToolDefinition to represent conversation items, tool invocations, and responses.  
3. An abstract LLMProvider base class declares the expected async methods complete, complete_streaming, and the synchronous count_tokens.  
4. Multiple helper functions normalize provider and model names, safely parse JSON, convert message and tool formats for different APIs, and extract usage counts.  
5. OllamaProvider is implemented to call a local or remote Ollama API with synchronous and streaming POST requests using httpx.AsyncClient.  
6. LiteLLMProvider is implemented to call litellm (if available), map providers like openai/anthropic/gemini to LiteLLM usage, and support streaming and token counting via litellm.  
7. Both providers parse tool call information from provider responses and convert tool arguments into dictionaries when possible.  
8. The module contains logic to resolve API keys from explicit arguments or environment variables and to special-case Gemini Vertex credentials.  
9. A create_provider factory constructs the appropriate provider by name and parameters, while get_provider and set_provider manage a global provider instance.  
10. The module maps provider-specific quirks such as OpenAI GPT-5 temperature constraints and provider-prefixed model names for LiteLLM.

Purpose:
1. The file centralizes LLM integration details so the rest of the project can use a uniform provider interface regardless of backend.  
2. It exists to encapsulate provider-specific request and response adaptation, so callers can work with Message and ToolDefinition objects rather than raw HTTP payloads.  
3. By providing OllamaProvider and LiteLLMProvider implementations, the module supports both a local Ollama deployment and litellm-based access to multiple cloud providers.  
4. Helper utilities ensure consistent behavior across providers: normalizing names, adjusting temperature constraints, and constructing the model identifiers LiteLLM expects.  
5. The file also handles authentication concerns by resolving API keys from parameters or environment variables and allowing injection of Google Vertex credentials for Gemini.  
6. Streaming and non-streaming completion are both provided in a standardized way, enabling consumers to choose synchronous or incremental output handling.  
7. Tool call extraction and normalization mean higher-level tooling can receive structured ToolCall objects representing function/tool invocation intents.  
8. The create_provider factory simplifies configuration-based initialization and enforces supported provider names, providing a single entrypoint for provider creation.  
9. Global provider management via get_provider and set_provider supports lazy initialization from the project's configuration and allows tests or runtime code to swap providers.  
10. Error translation wraps HTTP and JSON errors into project-specific exceptions (LLMAPIError and LLMError) so callers can handle failures consistently.  
11. Token counting fallbacks are implemented to provide approximate token estimates when provider-specific counters are unavailable.  
12. Overall, the module reduces duplication and centralizes LLM-specific behavior so other components remain provider-agnostic and focus on higher-level logic.

Key elements:
- OLLAMA_NATIVE_BASE_URL (constant) (default local Ollama URL).  
- Message (dataclass) (holds role, content, and tool call metadata).  
- ToolCall (dataclass) (represents an extracted tool invocation).  
- LLMResponse (dataclass) (encapsulates content, tool_calls, model, usage, finish_reason).  
- ToolDefinition (dataclass) (name, description, parameters JSON schema).  
- LLMProvider (ABC) (abstract methods: complete, complete_streaming, count_tokens).  
- _obj_get (helper) (safe attribute/dict access).  
- _safe_json_loads (helper) (robust JSON parsing returning dict).  
- _normalize_provider_name, _provider_model_name, _base_model_name (helpers) (normalize provider/model naming).  
- _is_openai_gpt5_family, _normalize_temperature_for_model (helpers) (provider-model specific constraints).  
- _resolve_api_key (helper) (resolve API keys from args or environment variables).  
- _convert_messages_for_openai_style, _convert_messages_for_ollama (helpers) (translate internal Message into provider formats).  
- _convert_tools_for_openai_style (helper) (translate ToolDefinition into function-style tool descriptions).  
- _extract_usage (helper) (normalize usage tokens from provider response objects).  
- OllamaProvider (class) (methods: __init__, complete, complete_streaming, count_tokens, close).  
- LiteLLMProvider (class) (methods: __init__, set_vertex_credentials, clear_vertex_credentials, _request_kwargs, complete, complete_streaming, count_tokens).  
- create_provider (factory) (constructs OllamaProvider or LiteLLMProvider based on normalized name).  
- get_provider, set_provider (global provider management) (lazy creation using captain_claw.config).

Key logic:
1. Message and tool conversion functions traverse lists of Message objects or tool definitions and produce the payload shapes required by different backends (OpenAI-style function entries for LiteLLM; role/content pairs plus tool metadata for Ollama).  
2. _obj_get provides a uniform accessor that works with either dicts or objects, avoiding repeated isinstance checks throughout parsing code.  
3. _safe_json_loads attempts to parse string arguments into JSON and falls back to returning the raw string under a key when parsing fails, ensuring tool argument extraction does not throw.  
4. Provider/model normalization functions ensure consistency in naming and prefixing: LiteLLM models are given provider/model prefixes and model base names can be extracted when needed.  
5. Temperature normalization enforces provider-specific constraints such as forcing temperature=1.0 for OpenAI GPT-5 family models.  
6. _resolve_api_key reads API keys from explicit parameters or standard environment variables depending on provider to centralize credential resolution.  
7. OllamaProvider.complete builds a JSON body with model, messages, options, optional tools, and then POSTs to the Ollama API, parsing JSON response content and extracting tool_calls and usage counts.  
8. OllamaProvider.complete_streaming uses httpx's AsyncClient.stream to iterate lines from a streaming endpoint, JSON-decodes each non-empty line, yields content pieces, and stops when a 'done' flag is encountered.  
9. LiteLLMProvider._request_kwargs prepares a dictionary for litellm.acompletion, injecting api_key or vertex credentials and remapping gemini to vertex_ai when Google OAuth credentials are provided.  
10. LiteLLMProvider.complete calls litellm.acompletion (imported at runtime), reads the first choice and its message to obtain content, and extracts tool_calls by parsing returned function call structures, converting argument strings via _safe_json_loads.  
11. LiteLLMProvider.complete_streaming requests a streaming acompletion and iterates chunks; it extracts delta content from choice deltas handling strings, lists of text parts, and other delta types, yielding assembled text increments.  
12. Both provider implementations wrap HTTP, JSON, and other runtime errors into project-specific exceptions (LLMAPIError when status codes are available, otherwise LLMError) to provide predictable error semantics to callers.  
13. Token counting implementations try provider-specific counters (litellm.token_counter) and otherwise fall back to a heuristic length//4 to approximate tokens when counters are not available.  
14. create_provider selects the correct provider class based on normalized provider name and environment/default values; unsupported names raise a ValueError.  
15. get_provider lazily initializes a module-global provider using configuration from captain_claw.config and create_provider, enabling configuration-driven defaults and singletons.  
16. set_provider allows overriding the global provider instance, facilitating tests or runtime swaps without needing to modify callers.

---

## captain-claw-src/captain_claw/web/rest_orchestrator.py

Description:
1. This module defines aiohttp REST handlers that expose orchestrator control, task management, workflow, and session endpoints.  
2. Each handler is an async function that accepts a WebServer-like server and an aiohttp.web.Request and returns a web.Response.  
3. Handlers use server._orchestrator and server.agent to forward requests to orchestrator and agent functionality.  
4. The module imports InstructionLoader to render prompts and get_logger for structured logging.  
5. Several endpoints perform JSON body parsing and validate required fields such as task_id, input, or name.  
6. Error conditions are handled by returning JSON error responses with appropriate HTTP status codes.  
7. The rephrase endpoint uses the configured LLM provider to convert casual user input into a structured orchestrator prompt.  
8. Prepare and workflow endpoints call orchestrator methods like prepare, save_workflow, load_workflow, and delete_workflow.  
9. Task control endpoints delegate actions such as edit, update, restart, pause, resume, and postpone to the orchestrator.  
10. Responses often serialize complex objects using json.dumps with default=str to ensure non-serializable values are handled.

Purpose:
This module exists to provide an HTTP surface for clients (typically the web UI) to inspect and control the orchestrator, manage tasks, and work with saved workflows and sessions. It centralizes request validation, error handling, and logging so higher-level code in the orchestrator and agent can focus on orchestration logic rather than HTTP concerns. By forwarding calls to server._orchestrator and server.agent, it maps REST operations to internal methods such as prepare, edit_task, update_task, restart_task, pause_task, resume_task, and postpone_task. The rephrase endpoint integrates the InstructionLoader and the configured LLM provider to produce a standardized prompt form of user input, which helps produce more predictable orchestration plans. The prepare endpoint supports previewing task decomposition without execution, enabling users to inspect proposed task graphs. Workflow endpoints let clients persist, load, list, and delete workflow templates through the orchestrator backend. Session and model listing endpoints expose agent-managed resources for per-task overrides and selections in the UI. The handlers uniformly parse JSON request bodies, validate required parameters, and return JSON responses with consistent structure for success and error cases. Logging calls record important events, input sizes, and errors to aid debugging and operational visibility. The module thus acts as a thin but essential translation layer between HTTP clients and the internal orchestrator/agent APIs.

Key elements:
- get_orchestrator_status (handler; returns orchestrator.get_status())  
- reset_orchestrator (handler; calls orchestrator.reset())  
- get_orchestrator_skills (handler; uses server.agent.list_user_invocable_skills() and server.agent.tools.list_tools())  
- rephrase_orchestrator_input (handler; uses InstructionLoader.render and provider.complete() with Message)  
- edit_orchestrator_task (handler; calls orchestrator.edit_task(task_id))  
- update_orchestrator_task (handler; calls orchestrator.update_task(task_id, description))  
- restart_orchestrator_task (handler; calls orchestrator.restart_task(task_id))  
- pause_orchestrator_task (handler; calls orchestrator.pause_task(task_id))  
- resume_orchestrator_task (handler; calls orchestrator.resume_task(task_id))  
- postpone_orchestrator_task (handler; calls orchestrator.postpone_task(task_id))  
- prepare_orchestrator (handler; calls orchestrator.prepare(user_input))  
- get_orchestrator_sessions (handler; uses server.agent.session_manager.list_sessions(limit=30))  
- get_orchestrator_models (handler; uses server.agent.get_allowed_models())  
- list_workflows, save_workflow, load_workflow, delete_workflow (handlers; CRUD for orchestrator workflows)  
- Dependencies: aiohttp.web, json, InstructionLoader, get_logger, captain_claw.llm.Message and provider APIs (used in rephrase)

Key logic:
The module follows a consistent handler pattern: check for the presence of server._orchestrator or server.agent as required, parse and validate the JSON body or route parameters, and call the corresponding orchestrator or agent method. When required parameters are missing (for example task_id, input, or name), handlers immediately return a JSON error with status 400. JSON parsing of request bodies is wrapped in try/except blocks to return a clear "Invalid JSON" error when parsing fails. For actions that modify orchestrator state (reset, edit, update, restart, pause, resume, postpone), the handler simply forwards validated arguments to the orchestrator method and returns its result. The prepare endpoint logs input size and preview, then awaits orchestrator.prepare(user_input) and returns its result; failures are logged and converted to a 500-style JSON error. The rephrase endpoint constructs a prompt via InstructionLoader.render and then attempts to call the configured LLM provider.complete with a Message; it uses a 60-second asyncio wait_for and falls back to the original input if the provider call fails or returns empty. Some responses that may include non-serializable objects use json.dumps with default=str passed as the dumps argument to web.json_response to ensure safe serialization. Skill and tool listing queries call agent APIs and guard against exceptions by returning empty lists on error. Session listing calls agent.session_manager.list_sessions with a fixed limit and converts session objects into id/name pairs for the response. The save_workflow handler accepts optional name, task_overrides, and model fields, normalizes model to a stripped string if present, and delegates to orchestrator.save_workflow. Load and delete workflow handlers validate the workflow name and forward to orchestrator.load_workflow and orchestrator.delete_workflow respectively. Throughout, errors are logged via the module logger with contextual information such as input previews and exception types to aid troubleshooting.

---

## captain-claw-src/captain_claw/web/chat_handler.py

Description:
1. This module implements WebSocket-based chat handling for the web UI.  
2. It exposes an async handle_chat function that validates the agent state and schedules background work.  
3. When a chat arrives it checks whether an agent is initialized and whether the server is busy, returning error messages over the WebSocket if not.  
4. If accepted, it sets server._busy, broadcasts a thinking status, and invokes a thinking callback to update UI state.  
5. The user's message is echoed to all connected clients via server._broadcast.  
6. The heavy work is delegated to an asyncio background task created from the internal _run_agent coroutine so the WebSocket read-loop remains responsive.  
7. The background _run_agent coroutine routes messages prefixed with '/orchestrate' to the orchestrator when available.  
8. For non-orchestrate messages it calls server.agent.complete to obtain an assistant response, handling tool calls and guards there.  
9. After producing a response _run_agent broadcasts assistant messages, usage statistics, and session information to clients.  
10. Exceptions during agent processing are logged and broadcast as error messages, and the finally block clears busy state and notifies clients that the server is ready.  

Purpose:
This module exists to bridge incoming WebSocket chat messages from the web UI to the server-side agent and orchestrator logic. It centralizes validation of agent availability and busy state to prevent concurrent processing conflicts. By offloading processing to a background coroutine it keeps the WebSocket reader free to accept control messages such as cancel or stop. It provides user feedback via server._broadcast for status, chat messages, errors, usage, and session details so the UI can stay synchronized. The special '/orchestrate' prefix is handled here so UI users can directly invoke orchestrator workflows through the same chat channel. The module also updates the server's active task reference so long-running operations are tracked and not garbage-collected. It integrates with existing server-side hooks like _thinking_callback to present intermediate UI state while the agent reasons. Error handling and logging are localized to this component to ensure failures are reported back to clients and recorded. The file is lightweight and intentionally delegates the domain-specific work to server.agent and server._orchestrator implementations. This separation keeps the handler focused on message orchestration, lifecycle management, and client communication semantics. Because it manipulates server internals like _busy and _active_task, it enforces single-turn processing semantics and predictable cleanup. Overall, the module exists to provide a resilient, responsive link between UI chat input and backend reasoning/orchestration services.

Key elements:
- handle_chat (async function; validates state, broadcasts status, schedules background work).  
- _run_agent (async coroutine; performs orchestrator routing or agent completion and final broadcast).  
- server._busy (server attribute; used to prevent concurrent processing).  
- server._active_task (server attribute; stores background asyncio.Task reference).  
- server._broadcast (method; used to send messages to all clients).  
- server._send (method; used to send direct WebSocket responses, e.g., errors).  
- server._thinking_callback (callable; used to provide intermediate UI thinking text).  
- server.agent.complete (external call; obtains assistant responses and handles tools/guards).  
- server._orchestrator.orchestrate (external call; invoked for '/orchestrate' commands if available).  
- server._session_info (method; provides session information for broadcasting).  
- asyncio.create_task (used to spawn background execution without awaiting).  
- get_logger / log (module-level logger; used for error logging).  
- aiohttp.web.WebSocketResponse (type hinting; indicates WebSocket interactions).

Key logic:
1. handle_chat first verifies that an agent is present and returns an error message through server._send if not.  
2. It then checks server._busy to reject simultaneous requests with a clear error broadcast.  
3. If the incoming message is allowed, handle_chat sets server._busy to True, broadcasts a 'thinking' status, and calls server._thinking_callback to update UI text.  
4. The handler broadcasts the user's message to all clients to keep the shared chat state consistent.  
5. It spawns _run_agent as an asyncio background task via asyncio.create_task and stores that task on server._active_task so it is not garbage-collected.  
6. _run_agent strips and inspects the message to detect a '/orchestrate ' prefix and, if found and an orchestrator is attached, invokes orchestrator.orchestrate with the remainder.  
7. If an orchestrate invocation lacks a request body, _run_agent broadcasts a usage error message rather than calling the orchestrator.  
8. For regular messages _run_agent delegates to server.agent.complete to obtain an assistant response, relying on the agent implementation to perform any tool calls or guard checks.  
9. After receiving a response, _run_agent broadcasts the assistant reply and then broadcasts usage statistics extracted from server.agent.last_usage and server.agent.total_usage.  
10. It also broadcasts session information by calling server._session_info to keep clients aware of session state changes.  
11. Any exceptions raised during processing are caught, logged via the module logger, and an error message is broadcast to clients to surface the failure.  
12. In the finally block _run_agent resets server._busy to False, clears server._active_task, and broadcasts a 'ready' status so the system can accept new chat turns.

---

## captain-claw-src/captain_claw/web/openai_proxy.py

Description:
1. This module implements OpenAI-compatible API proxy handlers for chat completion and model listing endpoints.  
2. It exposes functions to parse Bearer tokens from the Authorization header and to build OpenAI-style JSON completion responses.  
3. The api_chat_completions handler validates request JSON, extracts the last user message, and supports both immediate JSON and SSE streaming responses.  
4. Streaming responses are produced by write_sse_streaming_response which sends Server-Sent Events that chunk the assistant text into word groups.  
5. Agent instances are obtained from server._api_pool using a session id provided in the Authorization header.  
6. The module calls agent.complete to generate a text response and consults agent.get_runtime_model_details and agent.last_usage for metadata and usage.  
7. It handles a range of error conditions and returns proper OpenAI-style error objects with HTTP status codes for invalid JSON, missing messages, authentication errors, and internal failures.  
8. api_list_models returns a list of available models derived from server.agent.get_allowed_models and ensures a default 'captain-claw' model entry.  
9. Utility functions use standard libraries such as json, time, uuid and depend on aiohttp.web types and server attributes.  
10. Logging via the project's get_logger is used for error reporting during agent initialization and completion failures.  

Purpose:
This module exists to provide an OpenAI-compatible HTTP API surface that front-ends can call instead of talking directly to the internal agent implementation. It translates incoming OpenAI-style requests into operations on internal agent sessions and translates agent outputs back into OpenAI-style JSON and SSE formats. By requiring a Bearer session token this proxy maps HTTP requests to server-managed agent sessions in an API pool. The module centralizes validation of request structure, extraction of the most recent user message, and consistent error responses for malformed calls. It also encapsulates handling of streaming versus non-streaming responses so callers can request incremental SSE output or a single completed JSON object. Error handling and logging are concentrated here to ensure failures in session creation or completion are reported and converted into appropriate HTTP errors. The api_list_models handler provides a simple model discovery endpoint based on the live server.agent allowed models, guaranteeing a baseline 'captain-claw' model when absent. The write_sse_streaming_response function implements a deterministic chunking strategy that splits text into small word groups for SSE delivery. The module relies on server-side objects and lifecycle managed by the enclosing WebServer, keeping network-facing concerns separated from agent internals. It exists so external clients or tools that expect OpenAI semantics can integrate with the Captain Claw agent without knowledge of internal APIs. The file therefore provides a compatibility layer and a place to implement OpenAI-like behaviors such as usage reporting and completion identifiers. Overall, it reduces duplication by providing reusable builders for responses and a consistent approach to agent acquisition, release, and response formatting.

Key elements:
- extract_api_session_id (function: parse "Authorization: Bearer <token>" header)  
- build_chat_completion_response (function: construct OpenAI-style completion JSON)  
- write_sse_streaming_response (async function: prepares aiohttp StreamResponse and emits SSE chunks)  
- api_chat_completions (async handler: POST /v1/chat/completions entrypoint)  
- api_list_models (async handler: GET /v1/models entrypoint)  
- nested _sse (async inner helper in write_sse_streaming_response: writes SSE "data:" lines)  
- server._api_pool (external dependency: used to get_or_create and release agent sessions)  
- server.agent (external dependency: used by api_list_models and to enumerate allowed models)  
- agent.complete (agent method: invoked to produce assistant text)  
- agent.get_runtime_model_details (agent method: used to obtain model name)  
- agent.last_usage (attribute: used for prompt/completion/total token counts)  
- aiohttp.web.StreamResponse / web.json_response (framework integration)  
- json, time, uuid (standard libs used for payloads, timestamps, ids)  
- get_logger / log.error (logging facility used for error reporting)

Key logic:
1. api_chat_completions begins by verifying that server._api_pool exists and returns a 503 error payload if the API proxy is disabled.  
2. It extracts the session id from the Authorization header using extract_api_session_id and returns a 401 JSON error if no valid Bearer token is present.  
3. The handler attempts to parse the request body as JSON and will return a 400 error if parsing fails.  
4. It validates that the "messages" field is a non-empty list and returns a 400 error when that condition is not met.  
5. To locate the user prompt it iterates messages in reverse order finding the most recent dict with role "user"; for message content it supports either a plain string or a list of part objects where parts with type "text" contribute their "text" field.  
6. After extracting the user message it determines whether streaming is requested via the "stream" boolean in the body.  
7. The handler obtains an agent via server._api_pool.get_or_create(session_id) inside a try/except that logs initialization failures and returns a 500 error if creation fails.  
8. It constructs a completion id with uuid, invokes agent.complete(user_message) to produce the response text, and ensures the session id is released back to the pool in a finally block; completion failures are logged and returned as 500 errors.  
9. The code attempts to read model metadata from agent.get_runtime_model_details and falls back to "captain-claw" if unavailable; usage counters are read from agent.last_usage or defaulted to zeros.  
10. If streaming is not requested the handler returns a single JSON response built by build_chat_completion_response containing id, model, choices, and usage.  
11. If streaming is requested it delegates to write_sse_streaming_response which prepares an SSE StreamResponse, emits an initial assistant role chunk, then splits the response text into fixed-size word groups (chunk_size=5) and writes each group as a chat.completion.chunk SSE event, preserving spacing between chunks.  
12. The streaming logic emits a final chunk with finish_reason "stop" including usage, writes the "data: [DONE]" sentinel, calls write_eof, and returns the StreamResponse. api_list_models separately queries server.agent.get_allowed_models when available, assembles model entries with timestamps/ownership, ensures a "captain-claw" entry is present, and returns the aggregated list as JSON.

---

## captain-claw-src/captain_claw/web/rest_loops.py

Description:
1. This module defines REST handlers and execution logic for running workflows in a loop.  
2. It exposes HTTP endpoints to start a loop, check its status, and request a stop.  
3. start_loop validates the agent state, request JSON, workflow name, and iteration definitions before scheduling execution.  
4. The handler prepares per-iteration metadata and stores a short UUID and ISO timestamp in server._loop_runner_state.  
5. A background asyncio task is created to run the work via the run_loop coroutine.  
6. get_loop_status returns the current loop state or an idle response if none exists.  
7. stop_loop sets a stop flag that causes the running loop to cancel remaining iterations.  
8. run_loop iterates sequentially over provided iteration configs and uses a SessionOrchestrator to load and execute workflows.  
9. Each iteration broadcasts events for start, completion, failure, and the overall loop lifecycle using server._broadcast.  
10. The module records durations, previews, statuses, and errors and logs lifecycle events.

Purpose:
This file implements the HTTP-facing control surface and background execution engine for repeating workflow runs. It exists to allow clients to request repeated execution of a named workflow with varying variable sets and to monitor and control that execution asynchronously. By validating input and creating a dedicated loop task, it prevents blocking the request thread and centralizes loop state on the server object. The code coordinates with a SessionOrchestrator to load workflows, resolve variables, and perform the actual workflow execution, keeping orchestration details separate. It provides structured per-iteration metadata (status, duration, preview, error) so UIs or other clients can present progress and results. The module also supports graceful stopping, marking remaining iterations as cancelled and broadcasting a stop event. Logging calls record lifecycle milestones and failures for operational visibility. Broadcasting of events via server._broadcast gives real-time updates to connected clients or dashboards. Error handling around workflow loading and execution ensures failed iterations are captured and reported without crashing the whole loop. The file enforces a single concurrently running loop by checking server._loop_runner_task, preventing overlapping executions. UUID-based loop ids and ISO timestamps provide consistent identifiers and timing information. The module integrates configuration (via get_config) to control orchestrator limits like parallelism and agent counts.

Key elements:
- start_loop (async function; HTTP POST handler that validates input and starts run_loop).  
- get_loop_status (async function; HTTP GET handler returning current loop state or idle).  
- stop_loop (async function; HTTP POST handler that signals a running loop to stop).  
- run_loop (async function; core loop executor that runs iterations sequentially).  
- _make_loop_broadcast (inner closure in run_loop; adapts orchestrator events to loop events).  
- SessionOrchestrator (external class used to load and execute workflows via orchestrator.load_workflow and orchestrator.execute).  
- get_config (imported function used to read orchestrator-related configuration values).  
- server attributes accessed: agent, _loop_runner_task, _loop_runner_state, _loop_runner_stop, _broadcast.  
- log (module logger from captain_claw.logging used for lifecycle and error logging).  
- Standard libraries and aiohttp: asyncio, json, time, uuid, datetime.UTC, aiohttp.web for request/response handling.

Key logic:
1. start_loop first ensures the main agent exists and that no other loop task is currently running; it returns appropriate HTTP error responses for those conditions.  
2. The handler parses JSON from the request, validates presence of a workflow name and an iterations list, and returns 400 errors for malformed input.  
3. A short loop_id is generated from a UUID, and an iterations list of dictionaries is constructed containing index, variable values, and initial status metadata.  
4. The server's loop state fields (_loop_runner_stop, _loop_runner_state) are initialized and a background task is created to run run_loop, allowing immediate HTTP response while execution proceeds asynchronously.  
5. run_loop reads configuration using get_config and then processes iterations sequentially, checking the stop flag before each iteration to support cancellation.  
6. If stop is requested, remaining iterations are marked "cancelled", loop state is set to "stopped", and a loop_stopped event is broadcast with the index at which it stopped.  
7. For each iteration, the code sets status to "running", broadcasts an iteration_started event, and records a start timestamp for duration calculation.  
8. A SessionOrchestrator is instantiated with parameters taken from config and the server agent plus a broadcast callback that converts orchestrator events into loop-scoped events.  
9. The orchestrator attempts to load the named workflow; failure to load raises and is handled by marking the iteration as failed and broadcasting an iteration_failed event.  
10. When a workflow loads, default variables are combined with per-iteration variable overrides to produce effective_vars, then orchestrator.execute is awaited to run the workflow and synthesize results.  
11. On success the iteration is marked "completed", duration and a result preview (first 500 chars) are recorded, and an iteration_completed event is broadcast; errors are captured and logged when exceptions occur.  
12. After each iteration the orchestrator is shut down in a finally block if it was created; when all iterations finish normally the loop state is set to "completed" and a loop_completed event is broadcast.

---

## captain-claw-src/captain_claw/web/slash_commands.py

Description:
1. This module implements handling of slash-style commands received over the web UI WebSocket.  
2. The primary entry point, handle_command, parses a raw command string into the command and arguments and routes to specific handlers.  
3. It supports many top-level commands such as /help, /clear, /config, /stop, /history, /compact, /new, /session, /sessions, /models, /pipeline, /planning, /skills, /monitor, /exit, /approve, /orchestrate, /orchestrate-execute, /todo, /contacts, /scripts, and /apis.  
4. Several commands directly mutate server or agent state (for example creating or switching sessions, toggling planning or pipeline modes, setting cancel flags).  
5. Subcommands for session management are implemented in handle_session_subcommand and include list, switch/load, new, rename, description, model, and protect.  
6. Entity-specific handlers implement CRUD and search flows for todos, contacts, scripts, and APIs via handle_todo_command, handle_contacts_command, handle_scripts_command, and handle_apis_command.  
7. Those handlers use a session manager API to list, create, select, update, delete, and search domain items and format human-readable text responses.  
8. The module uses shlex-based tokenization for parsing field=value update strings and JSON parsing for orchestrator execution overrides.  
9. Results and events are communicated back to the client using server._send for single-reply messages and server._broadcast for session or state updates.  
10. A format_help function builds grouped Markdown help content from a COMMANDS registry for the /help command.

Purpose:
This file exists to provide a concise mapping from text-based slash commands entered in the web UI to programmatic actions on the server and agent components. It centralizes command parsing and routing so the WebSocket layer can remain simple and just forward raw command strings. By grouping related behaviors (session management, todos, contacts, scripts, APIs) into separate handler functions, the module keeps per-entity logic organized and reusable. It also enforces consistent output formatting for command results, including truncation or summarization for history and id-prefixing for items. The module integrates with the agent's session manager API to perform persistent operations and to ensure that created or updated entities are saved and optionally broadcast to other clients. It bridges interactive control (like /stop and /approve) with asynchronous components such as an orchestrator and chat handler by importing and invoking those components when needed. Error handling around the top-level dispatcher ensures that command exceptions produce readable error messages rather than crashing the WebSocket handler. The file provides a help generator that reflects the command registry so the UI can present up-to-date guidance without duplicating command metadata. Parsing utilities (shlex and JSON) are used to accept structured update and execute payloads from users while keeping input handling relatively simple. Overall, this module exists so that end users can manipulate sessions, data entities, model/runtime settings, and orchestration features from a compact command syntax inside the web interface.

Key elements:
- handle_command(server, ws, raw) (main dispatcher for slash commands).  
- handle_session_subcommand(server, args) (handles /session subcommands and session lifecycle operations).  
- handle_todo_command(server, args) (CRUD and listing for to-do items via session_manager).  
- handle_contacts_command(server, args) (CRUD, search, and info display for contacts).  
- handle_scripts_command(server, args) (manage script records including add/info/search/update/remove).  
- handle_apis_command(server, args) (manage API records including add/info/search/update/remove).  
- format_help() (builds grouped Markdown help from captain_claw.web_server.COMMANDS).  
- get_config (configuration helper used for /config output).  
- _shlex (shlex imported as _shlex for parsing field=value tokens).  
- json (used to parse orchestrator override payloads).  
- server._send and server._broadcast (WebSocket send and broadcast mechanisms).  
- server.agent and server.agent.session_manager (primary stateful objects manipulated by commands).  
- server._orchestrator (optional orchestrator used by /orchestrate-execute).  
- handle_chat and handle_approve_command (dynamically imported handlers invoked by specific commands).

Key logic:
The module begins by splitting an incoming raw command into a command token and the rest of the arguments, normalizing the command to lowercase for routing. The handle_command function implements a long chain of conditional branches that map known command strings to their corresponding behavior, preparing a human-readable result string in most cases. Many branches interact with server.agent and its session_manager to list, create, select, update, or delete domain entities; these interactions are synchronous in flow but generally await asynchronous session_manager calls. Commands that change shared state (like creating a session, switching sessions, or updating session metadata) trigger server._broadcast calls to notify other UI components of the change. The /session command delegates to handle_session_subcommand which implements subcommand parsing, selection logic, model setting, description auto-generation, and toggling of memory protection flags. Entity handlers parse a top-level subcommand (list/add/info/search/update/remove) and map those to session_manager methods; list operations format paginated summaries, info operations assemble multi-line detail strings, and update operations use shlex tokenization to accept field=value pairs and validate allowed fields. For /orchestrate-execute the code attempts to parse JSON arguments into task_overrides and variable_values then calls server._orchestrator.execute and broadcasts the result, handling exceptions and broadcasting errors on failure. The module treats unrecognized commands with a default "Unknown command" message and wraps the entire dispatch in a try/except to convert exceptions into an error result sent via server._send. Helper behaviors include truncating long history messages for the /history output, formatting id previews with the first 8 characters, and mapping item attributes (importance, tags, status icons) into concise lines. Some commands, such as /orchestrate, import and hand off processing to a chat handler and return early to avoid duplicate response building. The format_help function inspects a COMMANDS registry, groups commands by category, and constructs Markdown lines for display by the client. Overall, control flow is straightforward imperative dispatch with per-entity helper functions encapsulating repeated CRUD and formatting patterns.

---

## captain-claw-src/captain_claw/web/telegram.py

Description:
1. This module provides a Telegram bridge integration for the web server.  
2. It initializes and manages long-polling, a worker loop, and message handling tasks when Telegram is enabled.  
3. start_telegram sets up a TelegramBridge instance, loads persisted approval and pairing state, and starts background poll and worker tasks.  
4. stop_telegram cancels running tasks and closes the bridge.  
5. _telegram_poll_loop performs repeated get_updates calls and enqueues incoming updates for processing.  
6. _telegram_worker pulls queued updates and spawns concurrent handlers for each message.  
7. _handle_telegram_message routes messages through pairing checks, command execution, and agent forwarding while handling business messages.  
8. execute_telegram_command implements several slash-style commands such as /clear, /config, /history, /compact, /new, /session, /sessions, /models, /pipeline, /planning, /skills, /monitor, /approve and /orchestrate.  
9. _tg_process_with_typing runs agent.complete or orchestrator.orchestrate while sending periodic typing actions and broadcasting status and usage updates.  
10. Helper functions handle sending messages, loading and saving approval/pairing state, cleaning expired pairings, generating tokens, pairing unknown users, and approving pending pairings.  

Purpose:
1. The file's role is to bridge Telegram chats into the web server's chat and agent workflow.  
2. It exists to allow remote users to interact with the Captain Claw agent over Telegram using plain text and a subset of slash commands.  
3. Lifecycle functions (start_telegram / stop_telegram) allow enabling or disabling the integration according to server configuration and presence of a bot token.  
4. The long-polling and worker design separates update retrieval from message processing, improving responsiveness and enabling concurrent handling.  
5. Pairing and approval mechanics ensure only approved Telegram users can send messages to the agent while allowing operators to approve pending tokens.  
6. The module persists approved and pending pairing state through the agent's session_manager app state APIs so that approvals survive restarts.  
7. Command handling maps Telegram slash commands to server and agent operations to mirror functionality present in the Web UI.  
8. Typing indicator management and broadcasting keep Telegram users informed and also update connected web clients about agent status and usage.  
9. The module delegates heavy lifting to the server and agent objects (e.g., session management, model info, compacting, orchestration) rather than reimplementing those concerns.  
10. Token generation and expiration cleanup provide a safety mechanism to avoid stale pairing tokens and enforce TTLs.  
11. Error handling aims to log failures, notify the Telegram user, and broadcast error messages to the web UI when processing fails.  
12. Overall, the file encapsulates the Telegram-specific input/output and security workflows while integrating tightly with server-side persistence, session, and broadcasting APIs.  

Key elements:
- start_telegram (initializes TelegramBridge, loads state, starts poll/worker tasks)  
- stop_telegram (cancels tasks and closes bridge)  
- _telegram_poll_loop (long-polling loop calling TelegramBridge.get_updates and enqueuing updates)  
- _telegram_worker (dequeues updates and spawns message handlers)  
- _handle_telegram_message (per-message processing, pairing checks, command dispatch, broadcasting)  
- execute_telegram_command (parses and executes supported slash commands)  
- _tg_process_with_typing (manages typing heartbeat, busy locking, calls orchestrator or agent, broadcasts responses and usage)  
- _tg_send (sends messages via TelegramBridge.send_message with error logging)  
- _tg_load_state / _tg_save_state (persist/load JSON state via agent.session_manager.get_app_state and set_app_state)  
- _tg_cleanup_expired (removes expired pairing tokens based on ISO timestamp)  
- _tg_generate_pairing_token (generates unique 8-character pairing tokens)  
- _tg_pair_unknown_user (creates pending pairing entries, persists state, and notifies user and web UI)  
- handle_approve_command (validates token, moves pending pairing to approved users, persists state, notifies approved user)  
- Dependencies: TelegramBridge, TelegramMessage, server._broadcast, server.agent, server.agent.session_manager, server._orchestrator  

Key logic:
1. start_telegram checks configuration and bot token presence, creates a TelegramBridge, loads persisted approved and pending pairing maps, runs a cleanup for expired pairings, saves state, and then starts a polling task and worker task.  
2. stop_telegram cancels the poll and worker tasks if running and closes the bridge connection to ensure a graceful shutdown.  
3. The poll loop repeatedly calls get_updates with an offset and timeout, updates the stored offset to avoid reprocessing, and places each update on an asyncio queue for downstream processing.  
4. The worker loop continuously consumes that queue and creates an independent asyncio task to handle each TelegramMessage so processing of one message does not block retrieval of others.  
5. _handle_telegram_message first attempts to mark business messages as read, enforces approval by checking server._approved_telegram_users and initiating pairing for unknown users, and ignores empty messages.  
6. It normalizes bot-mention forms of slash commands, provides built-in handlers for /start and /help, and otherwise tries to run execute_telegram_command for leading slash commands; if a command returns None it falls through to agent processing (notably /orchestrate).  
7. Non-command messages are broadcast into the web UI with a user label and then processed by _tg_process_with_typing which performs the actual agent or orchestrator invocation.  
8. execute_telegram_command tokenizes the raw command, verifies agent availability, and implements command-specific flows such as clearing session messages, compacting sessions via agent.compact_session, creating new sessions via session_manager.create_session, listing sessions, retrieving allowed models, toggling pipeline/planning modes, listing skills, and delegating session subcommands to slash_commands.handle_session_subcommand.  
9. For /approve it delegates to handle_approve_command which validates and approves a pending token by moving data from _pending_telegram_pairings to _approved_telegram_users and persists the change.  
10. _tg_process_with_typing acquires a busy lock to serialize agent access, sets a busy flag, broadcasts a thinking status, and spawns a typing heartbeat that periodically sends chat_action "typing" via the bridge until the work completes.  
11. While typing is active, the function either calls orchestrator.orchestrate for explicit /orchestrate requests or agent.complete for normal messages, sends the resulting text back to the Telegram chat, and broadcasts assistant messages, usage, and session_info to the web UI.  
12. Exceptions during message handling are logged, the user is informed via Telegram when possible, and error events are broadcast to the web UI; the typing heartbeat is stopped and busy state cleared in a finally block.  
13. State persistence uses JSON serialization and the agent.session_manager app-state API to store both approved users and pending pairings; loading validates the parsed JSON is a dict.  
14. Pairing token generation uses a restricted alphabet to create an 8-character token, ensures uniqueness relative to existing pending tokens, and pending entries include creation and ISO-formatted expiration timestamps which are honored and cleaned up by _tg_cleanup_expired.

---

## captain-claw-src/captain_claw/web/rest_workflows.py

Description:
1. This module provides REST handlers used by a workflow browser within the web server.  
2. It exposes functions to list available workflows and to retrieve workflow output files.  
3. workflows_dir determines the workflows directory under the resolved workspace path and ensures it exists.  
4. list_workflow_outputs scans the workflows directory for .json workflow definitions and for markdown output files.  
5. The listing function builds a summary structure for each workflow including name, filename, user_input, task_count, and outputs.  
6. It parses each .json file to extract workflow metadata and falls back to filename-derived defaults on parse failure.  
7. Output markdown files are associated with workflows by matching filename stems using a "-output-" pattern and an inferred-key fallback.  
8. The handler sorts outputs for each workflow by their timestamp and returns the assembled list as a JSON response.  
9. get_workflow_output validates requested filenames to prevent path traversal, reads the markdown file, and returns its content.  
10. Both handlers use aiohttp.web responses and perform error handling for missing files and file-read exceptions.

Purpose:
1. The file exists to provide HTTP endpoints that allow a browser-based workflow UI to discover and inspect persisted workflows and their generated outputs.  
2. It centralizes filesystem access logic related to workflows so the web server can present structured information without embedding path handling elsewhere.  
3. By ensuring the workflows directory is present, workflows_dir prepares the runtime environment for storing workflow metadata and outputs.  
4. list_workflow_outputs aggregates information from two kinds of filesystem artifacts — .json workflow descriptors and output .md files — into a single consumable representation.  
5. The JSON returned by the listing handler is suitable for populating UI lists, showing recent outputs, and providing basic metadata such as task counts and user input.  
6. The handler's robust parsing and fallback behavior means malformed or missing metadata files do not prevent discovery of outputs.  
7. get_workflow_output provides a safe way for the UI to fetch the textual content of a particular workflow output while preventing path traversal attacks.  
8. The module leverages the project's configuration to resolve workspace paths, keeping filesystem layout consistent with other orchestrator components.  
9. Sorting outputs and workflows ensures predictable presentation order for callers and avoids exposing raw filesystem ordering.  
10. Error responses are returned with appropriate HTTP status codes and JSON error messages to simplify client-side handling.  
11. The functions are asynchronous handlers compatible with aiohttp's web framework, fitting into the web server's routing and request lifecycle.  
12. Overall, the module encapsulates the minimal file-IO, parsing, and validation logic required to support a workflow browser UI without implementing UI or orchestration logic itself.

Key elements:
- workflows_dir (function) — resolves and ensures existence of the "workflows" directory under the configured workspace.  
- list_workflow_outputs (async function) — handler for listing workflows and their outputs as JSON.  
- get_workflow_output (async function) — handler for returning the content of a specified output markdown file as JSON.  
- get_config (imported call) — used to obtain configuration and the resolved workspace path.  
- Path.glob and Path.read_text (pathlib) — used for discovering files and reading their contents.  
- json.loads (standard library) — used to parse workflow .json files.  
- aiohttp.web.json_response (imported) — used to return JSON responses with status codes.  
- Filename validation checks (simple string checks for ".." and "/") — used to prevent directory traversal.  
- File stat and st_size access (Path.stat) — used to determine file sizes for outputs.  
- Glob patterns "*.json" and "*-output-*.md" — define which files are treated as workflows and outputs.  
- TYPE_CHECKING and WebServer typing hint — provides a type hint for handler signatures without runtime import.

Key logic:
1. workflows_dir calls get_config() to obtain the resolved workspace path and constructs a "workflows" subdirectory, creating it if necessary.  
2. list_workflow_outputs begins by scanning the workflows directory for files matching "*.json" and builds an initial dictionary keyed by each file's stem.  
3. For each .json file the handler attempts to read and parse JSON to extract workflow_name, user_input, and a task list length; failures fall back to inferred defaults.  
4. Each workflow entry is initialized with name, filename, user_input, task_count, and an empty outputs list to which matching markdown outputs will be appended.  
5. The function then scans for files matching "*-output-*.md" and attempts to match each output file to an existing workflow key by testing whether the file stem starts with "workflowkey-output-".  
6. If a direct prefix match is found the code extracts the timestamp portion from the stem, attempts to get the file size, and appends a metadata object for that output to the corresponding workflow's outputs list.  
7. If no direct match is found the code tries to infer a workflow key by locating the last occurrence of "-output-" and splitting the stem there, creating a new workflow entry if necessary to record the output.  
8. File size retrieval is wrapped in exception handling so that errors obtaining stat information do not abort processing and instead yield a size of zero.  
9. After collecting outputs the handler sorts each workflow's outputs by the timestamp string in descending order to present recent outputs first.  
10. The workflows dictionary is converted to a sorted list by workflow name and returned as a JSON response via aiohttp.web.json_response.  
11. get_workflow_output checks the requested filename for invalid characters or patterns (empty string, "..", or "/") to block path traversal and returns a 400 error for invalid names.  
12. If the requested file exists the function reads its content in UTF-8 with exception handling and returns the filename and content as JSON, otherwise returning 404 for missing files or 500 for read errors.

---

## captain-claw-src/captain_claw/web/__init__.py

Description:
1. This file is the package initializer for the captain_claw.web Python package.  
2. It is present to mark the directory as an importable Python package.  
3. The file contains no executable code, classes, functions, or variables.  
4. Importing this module will perform no side effects because it is empty.  
5. It does not define __all__ or other package export controls.  
6. There are no runtime behaviors, configuration settings, or constants declared here.  
7. The file's existence allows relative imports within the captain_claw.web package.  
8. It serves as a logical namespace holder for web-related submodules in the package.  
9. The file does not document any public API or provide any runtime checks.  
10. As shipped, it functions solely as a package marker without internal logic.  

Purpose:
1. The primary role of this file is to signal to Python that the captain_claw.web directory is an importable package.  
2. By existing, it enables other parts of the project to perform imports like import captain_claw.web or import captain_claw.web.submodule.  
3. It provides a stable package namespace under which web-related modules and handlers can be organized.  
4. Although empty now, it is the appropriate location for package-level initialization if future needs arise.  
5. Potential future uses include defining package exports, performing lazy imports of submodules, or setting package-level constants.  
6. Keeping an __init__.py file avoids implicit namespace package behaviors and clarifies package boundaries for tooling.  
7. Tools like linters, test runners, and import systems rely on the presence of this file to resolve module paths consistently.  
8. It also serves as a predictable place to centralize documentation or convenience imports if the project chooses to expose a smaller API surface.  
9. The file's presence simplifies relative imports within the captain_claw.web package by maintaining a clear module path.  
10. From a packaging and distribution perspective, the file helps ensure the directory is included in source distributions and wheels.  
11. The empty initializer keeps startup fast because no code runs at import time.  
12. Overall, the file exists to provide package structure and a future extension point without adding runtime behavior today.  

Key elements:
- Package marker (serves as the package initializer for captain_claw.web).  
- No functions, classes, or module-level variables defined (explicitly empty).  
- Placeholder/extension point (intended location for potential future package-level initialization or export control).  

Key logic:
1. The module contains no executable statements, so importing captain_claw.web performs no operations.  
2. Python's import machinery will load the module object, bind it to the package name, and then search for submodules on demand.  
3. Because the file is empty, there are no side effects such as I/O, logging, or configuration when the package is imported.  
4. Any relative imports within submodules of captain_claw.web will rely on this package namespace being present.  
5. There is no __all__ or attribute exposure defined here, so attribute access like captain_claw.web.X will only succeed if X is set by other submodules after import.  
6. If future code is added, it would execute at import time in this module, potentially initializing package-level state.  
7. The absence of code also means unit tests or runtime diagnostics cannot rely on package-initialization hooks from this module.  
8. Packaging tools that traverse the project will treat the directory as a regular package due to the file's presence.  
9. Import errors related to captain_claw.web will typically originate from missing submodules rather than from this initializer.  
10. Namespace resolution will continue into subpackages and modules beneath captain_claw.web when those are imported explicitly.  
11. The current control flow is therefore minimal: module load, binding to name, and immediate return to the importer.  
12. Any orchestration of web handlers or REST endpoints must be implemented in the web submodules rather than in this file.

---

## captain-claw-src/captain_claw/web/rest_config.py

Description:
1. This module defines asynchronous REST handlers related to configuration, session listings, and available commands.  
2. It exposes three main aiohttp handler functions that return JSON responses for different API endpoints.  
3. get_config_summary constructs a safe configuration summary that purposely omits secrets and sensitive information.  
4. The config summary uses runtime details from a server.agent when available and falls back to static configuration values otherwise.  
5. list_sessions_api queries the session manager to retrieve up to twenty sessions and returns summarized session metadata.  
6. get_commands_api returns a JSON representation of the COMMANDS object imported from the web server module.  
7. All handlers accept a WebServer instance and an aiohttp.web.Request object as parameters and are declared async.  
8. The module relies on captain_claw.config.get_config to obtain the canonical configuration object.  
9. Responses are created using aiohttp.web.json_response to serialize Python structures to JSON.  
10. The module contains no class definitions and focuses exclusively on lightweight request-to-JSON transformations.

Purpose:
1. The file exists to provide simple REST endpoints that surface runtime and configuration-related information to clients such as UIs or administrative tools.  
2. By presenting a safe config summary it allows front-end components to display model, context, tool, and guard settings without exposing secrets.  
3. Integrating runtime agent details when available enables the handlers to reflect dynamic state changes from an active agent rather than only static config.  
4. The session-listing handler centralizes the logic for summarizing stored sessions for management consoles or session browsers.  
5. Returning a limited number of sessions (limit=20) prevents excessive payload sizes and discourages expensive large-list operations in the handler itself.  
6. The commands endpoint delegates to a central COMMANDS definition so the UI can retrieve the set of available commands from the running web server.  
7. Implementing these as async aiohttp handlers allows them to be integrated into the existing asynchronous web server and handle concurrent requests.  
8. The module keeps the REST surface minimal and focused, avoiding business logic beyond assembling safe summaries and transforming objects into JSON-serializable dicts.  
9. Placing this logic in a dedicated module separates concerns between web routing, session management, configuration access, and runtime agent introspection.  
10. The handlers are small and suitable for reuse and testing, because each function's responsibility is narrow and its inputs and outputs are well defined.  
11. By depending on higher-level interfaces like get_config and get_session_manager, the module remains decoupled from storage or configuration implementation details.  
12. The overall role is to serve as the glue between internal runtime/config state and external consumers requesting that information over HTTP.

Key elements:
- get_config_summary (async function; builds and returns a safe config summary as JSON).  
- list_sessions_api (async function; retrieves sessions via session manager and returns summarized list).  
- get_commands_api (async function; returns COMMANDS from captain_claw.web_server).  
- get_config (call to captain_claw.config.get_config; used to read static configuration).  
- get_session_manager (imported inside list_sessions_api; provides session listing API).  
- COMMANDS (imported from captain_claw.web_server inside get_commands_api; represents available commands).  
- web.json_response (aiohttp utility used to produce JSON responses).  
- server.agent.get_runtime_model_details (optional call when server.agent is present to obtain live model settings).  
- Access to session attributes: id, name, messages, created_at, updated_at, metadata (used to build session summaries).

Key logic:
1. get_config_summary begins by retrieving the canonical configuration object via get_config and initializing an empty details mapping.  
2. If the provided WebServer instance has an agent attribute, the handler attempts to obtain runtime model details by calling agent.get_runtime_model_details, and uses those values to override config-sourced defaults.  
3. The response payload is explicitly constructed with top-level keys "model", "context", "tools", and "guards", each populated from either the runtime details or the static config.  
4. Within the "model" mapping the handler includes provider, model, temperature, and max_tokens fields, preferring runtime-provided values and falling back to cfg.model.* when absent.  
5. The "context" mapping includes max_tokens and compaction_threshold drawn directly from the configuration object.  
6. Tool availability is reported via cfg.tools.enabled and guard settings are reported via cfg.guards.input.enabled, cfg.guards.output.enabled, and cfg.guards.script_tool.enabled.  
7. list_sessions_api dynamically imports get_session_manager and invokes list_sessions with a fixed limit=20 to obtain recent or available sessions.  
8. For each returned session object, list_sessions_api constructs a summary dict containing id, name, a computed message_count via len(s.messages), timestamps, and a description extracted from session metadata if present.  
9. The session description defaults to an empty string when metadata or the description key is absent, ensuring JSON-serializable and consistent output shapes.  
10. get_commands_api performs a local import of COMMANDS from the web_server module and immediately returns it as a JSON response without transformation.  
11. All handlers rely on aiohttp.web.json_response to convert Python dicts and lists into HTTP JSON responses with appropriate content type and serialization.  
12. The module avoids side effects and does not perform mutation of configuration or sessions; it solely reads state and formats it for consumption by clients.

---

## captain-claw-src/captain_claw/web/rest_cron.py

Description:
1. This module implements aiohttp REST handlers for managing cron jobs via an HTTP API.  
2. It defines endpoints to list, create, run, pause, resume, update, delete, and retrieve history for cron jobs.  
3. Each handler first checks that the server.agent is initialized and returns a 503 error if it is missing.  
4. The list_cron_jobs handler queries the session_manager for up to 200 jobs and returns a JSON array of job summaries.  
5. The create_cron_job handler validates JSON input for kind, schedule, payload, and session_id, computes the next run time, and creates a job via the session_manager.  
6. The run_cron_job handler loads a job by id and triggers its execution asynchronously using an execute_cron_job function.  
7. The pause_cron_job and resume_cron_job handlers toggle a job's enabled state and update status or next_run_at via the session_manager.  
8. The update_cron_job_payload handler patches only the payload field of a job after validating the request body.  
9. The delete_cron_job handler removes a job by id and reports a 404 error when the job is not found.  
10. The get_cron_job_history handler returns stored chat and monitor history for a job and serializes the response with json.dumps(default=str) to handle non-serializable objects.  

Purpose:
1. The file exists to expose an HTTP API that allows clients (such as UIs or administrative tools) to perform CRUD and control operations on scheduled cron jobs managed by the agent.  
2. It centralizes input validation and error handling for cron-related operations so that callers receive consistent JSON responses and HTTP status codes.  
3. By delegating persistence and job lifecycle actions to the session_manager, the module keeps HTTP-layer logic separate from storage and scheduling mechanics.  
4. The create handler supplements user-provided schedules with a human-readable "_text" and computes the canonical next_run_at in UTC, ensuring schedules are normalized before storage.  
5. The run handler enables immediate, manual execution of a cron job without altering its persisted schedule and does so asynchronously to avoid blocking the web request.  
6. Pause, resume, update, and delete handlers provide lightweight endpoints that translate client intentions into session_manager updates and appropriate status reporting.  
7. The module performs conservative validation on inputs (e.g., allowed kinds and schedule structure) to prevent malformed jobs from being created.  
8. Returning structured JSON for job listings and history supports front-end rendering and debugging tools by exposing job metadata and execution traces.  
9. The handlers use common patterns (checking server.agent, loading jobs by id, mapping errors to HTTP responses) to make the behavior predictable and easy to integrate with other server routes.  
10. The module also integrates with cron-specific utilities (compute_next_run, schedule_to_text, to_utc_iso) to ensure time calculations and schedule descriptions are consistent with the rest of the codebase.  
11. Error pathways are explicit and informative, mapping parsing errors, validation failures, and missing resources to appropriate HTTP status codes and JSON messages.  
12. Overall, the file functions as the thin web-facing adapter that translates HTTP requests into session_manager operations and scheduling actions used by the agent runtime.  

Key elements:
- list_cron_jobs (async function; lists jobs via session_manager.list_cron_jobs)  
- create_cron_job (async function; validates input, computes next run, and calls session_manager.create_cron_job)  
- run_cron_job (async function; loads job and triggers execute_cron_job via asyncio.create_task)  
- pause_cron_job (async function; calls session_manager.update_cron_job to disable a job)  
- resume_cron_job (async function; computes next run and updates job to enabled)  
- update_cron_job_payload (async function; patches a job's payload via session_manager.update_cron_job)  
- delete_cron_job (async function; removes a job via session_manager.delete_cron_job)  
- get_cron_job_history (async function; returns job.chat_history and job.monitor_history with json.dumps default=str)  
- server.agent.session_manager (external dependency; used for job CRUD and queries)  
- compute_next_run, schedule_to_text, to_utc_iso (imported cron utilities used for scheduling logic)  
- execute_cron_job (imported from captain_claw.cron_dispatch; used to run jobs)  
- aiohttp.web.json_response and request.json() (framework usage for HTTP I/O and responses)  

Key logic:
1. Each handler begins by checking for server.agent and immediately returns a 503 JSON error when the agent is not initialized, preventing further operations.  
2. list_cron_jobs calls session_manager.list_cron_jobs with a limit and active_only flag, iterates returned job objects, and builds a list of dictionaries with selected job fields for the JSON response.  
3. create_cron_job reads and parses the request body as JSON, validates that "kind" is one of the allowed types, ensures schedule is a dict containing "type", and that payload is a dict and session_id is present.  
4. For schedule handling, create_cron_job augments the schedule with a "_text" generated by schedule_to_text and then computes the next run time using compute_next_run followed by to_utc_iso; failures in these steps produce 400 errors with explanatory messages.  
5. Upon successful validation and computation, create_cron_job calls session_manager.create_cron_job with the normalized schedule, kind, payload, session_id, and next_run_at, returning the created job id and next_run_at.  
6. run_cron_job retrieves the job id from request.match_info, loads the job via session_manager.load_cron_job, and returns 404 if missing; it then obtains a web runtime context from server._get_web_runtime_context and schedules execute_cron_job(ctx, job, trigger="manual") via asyncio.create_task to run asynchronously.  
7. pause_cron_job and resume_cron_job both use request.match_info to get the id, then interact with session_manager.update_cron_job to set enabled=False/True and update last_status and next_run_at as appropriate, mapping nonexistence to 404 responses.  
8. resume_cron_job recomputes next_run_at from the existing job.schedule using the same compute_next_run and to_utc_iso utilities before updating the job to pending and enabled.  
9. update_cron_job_payload validates the presence of a "payload" field in the parsed JSON body and then calls session_manager.update_cron_job to replace the payload, returning a 400 error for missing payload and 404 if the job is not found.  
10. delete_cron_job delegates deletion to session_manager.delete_cron_job and returns a simple {"ok": True} on success or a 404 error when deletion fails.  
11. get_cron_job_history loads the job and returns its chat_history and monitor_history in a JSON response, supplying a custom dumps function that uses json.dumps with default=str to serialize non-standard objects safely.  
12. Error handling across handlers is consistent: parse errors return 400, missing resources return 404, uninitialized agent returns 503, and unexpected failures in triggering execution return 500 with the exception string.

---

## captain-claw-src/captain_claw/web/rest_entities.py

Description:
1. This module implements aiohttp REST handlers for CRUD operations on Todos, Contacts, Scripts, and APIs.  
2. Each handler first verifies that server.agent is present and returns a 503 JSON error if it is not.  
3. List and search handlers call the session_manager to retrieve collections with fixed limits and serialize results using a JSON dumper that falls back to str for non-serializable objects.  
4. Create handlers parse and validate JSON request bodies, sanitize and default incoming fields, and call session_manager.create_* methods returning 201 on success.  
5. Get handlers load single entities via session_manager.load_* and return 404 when the entity is not found.  
6. Update handlers read JSON bodies, build kwargs from allowed fields, perform small field-specific adjustments (e.g., clamping importance), and call session_manager.update_* returning 404 if the target is missing.  
7. Delete handlers call session_manager.delete_* and return a 404 when deletion fails or an {"ok": True} on success.  
8. Search endpoints require a non-empty query parameter and return 400 when q is missing.  
9. The module consistently converts incoming values to strings with strip(), casts numeric inputs where needed, and uses explicit limits for list/search operations.  
10. Error handling covers invalid JSON bodies, missing required fields, missing entities, and uninitialized agent state with appropriate JSON responses and HTTP status codes.

Purpose:
1. The file exists to expose a simple HTTP API layer that translates external HTTP requests into calls against the application's session_manager persistence/service layer.  
2. It centralizes request validation, sanitization, and HTTP-level error reporting for several entity types so higher-level business logic can remain focused in the session manager and models.  
3. Grouping handlers by entity type (Todos, Contacts, Scripts, APIs) provides a clear structure that mirrors the backend session_manager capabilities and keeps routes organized.  
4. The module enforces minimal input validation (required fields, non-empty query parameters) to prevent malformed data from reaching storage.  
5. It standardizes JSON serialization across handlers through a shared dumper that safely converts non-standard objects.  
6. By returning conventional HTTP status codes (201 for creation, 400 for bad requests, 404 for missing resources, 503 for uninitialized agent) the file enables predictable client behavior and easier integration with UIs and tools.  
7. The handlers apply simple normalization for incoming fields (str(...).strip(), optional defaults), reducing duplication of that boilerplate across the codebase.  
8. Limited list and search sizes (limits like 50 or 200) provide a basic protection against heavy queries via the API surface.  
9. The file intentionally delegates persistence, domain validation, and complex business rules to the session_manager, acting mainly as a thin translation and validation layer.  
10. Its design allows the web server to be started even if agent is not yet initialized while providing clear 503 responses until the backend is ready.  
11. The module is designed to be minimal and easily extendable with additional entity handlers or fields by following the established patterns.  
12. Overall, it exists to provide a predictable, consistent, and lightweight REST interface that maps HTTP semantics to the internal session management operations.

Key elements:
- _JSON_DUMPS (lambda) (JSON dumper using json.dumps(default=str) for safe serialization).  
- list_todos (handler) (lists todos with optional filters).  
- create_todo (handler) (validates and creates a todo via session_manager.create_todo).  
- update_todo (handler) (patches todo fields and calls session_manager.update_todo/load_todo).  
- delete_todo (handler) (deletes a todo via session_manager.delete_todo).  
- list_contacts (handler) (lists contacts).  
- search_contacts (handler) (requires q and searches contacts).  
- create_contact (handler) (validates and creates a contact with many optional fields).  
- get_contact (handler) (loads a single contact).  
- update_contact (handler) (patches contact, clamps importance, sets importance_pinned).  
- delete_contact (handler) (deletes a contact).  
- list_scripts / search_scripts / create_script / get_script / update_script / delete_script (handlers) (CRUD and search for scripts).  
- list_apis / search_apis / create_api / get_api / update_api / delete_api (handlers) (CRUD and search for API definitions).  
- Dependencies on aiohttp.web (web.Response/json_response), json, and the server.agent.session_manager API methods (list_*, search_*, create_*, load_*, update_*, delete_*).  
- Use of request.json(), request.query, and request.match_info for input.

Key logic:
1. Every handler begins by verifying the presence of server.agent and short-circuits with a 503 JSON error if the agent is not initialized.  
2. List handlers call the corresponding session_manager.list_* method with a hard-coded limit (usually 200) and serialize returned model objects by calling to_dict on each item.  
3. Search handlers extract the q parameter, trim it, and return a 400 error if q is empty; they then call session_manager.search_* with a smaller limit (usually 50).  
4. Create handlers attempt to parse the JSON body, return 400 on parse failure, validate required fields (e.g., name/base_url/file_path/content), and construct creation arguments by trimming string inputs and providing defaults or None for optional fields.  
5. On successful creation handlers return the created item's to_dict serialized JSON with HTTP 201.  
6. Get handlers extract an id from request.match_info, call session_manager.load_*, and return 404 if the item is not found otherwise returning its to_dict.  
7. Update (PATCH) handlers parse JSON, iterate over an allowed list of fields to build kwargs, convert values to trimmed strings or None, and for numeric fields perform conversions and constraints (for example, clamping contact importance between 1 and 10 and setting an importance_pinned flag).  
8. Update handlers call session_manager.update_*, check the boolean response to detect missing targets (returning 404), and then load and return the updated object when available.  
9. Delete handlers call session_manager.delete_*, return 404 if deletion reports failure, and otherwise return a simple {"ok": True} JSON response.  
10. Throughout the module, input normalization is consistently applied via str(...).strip() and int(...) where used, preventing accidental storage of raw structures.  
11. The shared _JSON_DUMPS function is used when serializing lists or objects to ensure that any non-serializable fields are represented as strings instead of breaking responses.  
12. Error responses are explicit and consistent: invalid JSON yields 400, missing parameters yield 400, missing resources yield 404, and uninitialized backend yields 503, enabling straightforward client-side handling.

---

## captain-claw-src/captain_claw/web/ws_handler.py

Description:
1. This module implements a WebSocket protocol handler for the web UI.  
2. It defines an async ws_handler function that prepares and manages WebSocket connections using aiohttp.web.WebSocketResponse.  
3. When a client connects the handler registers the socket in server.clients and sends a welcome payload containing session info, allowed models, and available commands.  
4. If an Agent with an active session exists the handler replays prior session messages to the connecting client, translating stored roles and tools into chat or monitor messages.  
5. Replayed messages distinguish between user, assistant, and tool roles and may convert specific tool messages like task_rephrase into visible chat panels.  
6. The module reads incoming messages in a loop, decodes JSON text frames, and reports invalid JSON back to the client.  
7. Decoded messages are dispatched to handle_ws_message which routes chat messages, slash/command invocations, cancellation signals, and approval responses.  
8. Chat messages beginning with a slash are forwarded to a slash command handler while other chat text is sent to the chat handler.  
9. The ws_handler logs WebSocket errors and ensures the client is removed from server.clients when the connection closes.  
10. The module relies on server methods such as _send and _session_info and on Agent helpers to filter monitor-only tools.  

Purpose:
1. This file exists to provide a centralized gateway between the browser-based UI and the server-side Agent and session state.  
2. It supplies an entry point for incoming WebSocket connections and ensures each connected client receives the current session context and configuration.  
3. By replaying past session messages it brings newly connected clients up to date without requiring additional REST calls.  
4. The handler translates internal session message representations into structured UI events (chat_message, monitor, replay_done) that the front end can render.  
5. It validates and normalizes incoming WebSocket payloads, returning structured error messages for invalid JSON.  
6. Messages are dispatched to specialized modules (slash_commands and chat_handler) so that command parsing and chat processing remain modular and testable.  
7. The ws_handler also surfaces control actions like cancellation to the running Agent by setting a cancel_event, allowing UI-driven interruption of operations.  
8. Implementation choices such as max_msg_size, server.clients tracking, and explicit use of server._send enforce resource limits and centralized delivery semantics.  
9. Use of Agent._is_monitor_only_tool_name allows the handler to suppress monitor messages that should not be shown to users, centralizing visibility policy.  
10. Having a dedicated WebSocket module simplifies lifecycle management including connection preparation, error logging, and cleanup on disconnect.  
11. The module therefore exists to provide reliable, real-time bidirectional communication, integrate server agent state with the UI, and delegate domain logic to other components.  
12. Its responsibilities are narrowly scoped to connection and message dispatch so higher-level behaviors remain in agent and handler modules.  

Key elements:
- ws_handler (async function; prepares WebSocket, registers client, sends welcome, replays session, receives messages).  
- handle_ws_message (async function; dispatches message types: chat, command, cancel, approval_response).  
- aiohttp.web.WebSocketResponse (used to manage WebSocket connection; configured with max_msg_size).  
- server.clients (set; tracks active WebSocket clients).  
- server._send (method called to send structured events to a client).  
- server._session_info (method used to include session metadata in welcome payload).  
- server.agent.get_allowed_models (call to populate allowed models in welcome payload, guarded by server.agent presence).  
- COMMANDS (imported from captain_claw.web_server; included in welcome payload).  
- Agent._is_monitor_only_tool_name (helper used to filter out monitor-only tool messages).  
- Delegated handlers: captain_claw.web.slash_commands.handle_command and captain_claw.web.chat_handler.handle_chat.  
- JSON parsing with json.loads and JSONDecodeError handling.  
- server.agent.cancel_event (used to propagate cancel requests).  
- Logging via captain_claw.logging.get_logger for errors and cancellation notices.  

Key logic:
1. The ws_handler coroutine creates a WebSocketResponse with a configured max message size and awaits its preparation with the incoming request.  
2. It immediately registers the socket in server.clients to track active connections and constructs a welcome payload by calling server._session_info and retrieving allowed models from server.agent if present.  
3. COMMANDS is imported from the web_server module and included in the welcome payload so the client knows available slash commands.  
4. If an agent session exists the handler iterates over session.messages and inspects each message's role, content, and tool metadata to determine how to forward it.  
5. Messages with roles 'user' or 'assistant' are forwarded as chat_message events while certain tool messages are rendered as rephrase chat panels and other tool outputs are sent as monitor events unless filtered by Agent._is_monitor_only_tool_name.  
6. After replaying messages the handler sends a replay_done event to indicate the replay sequence is complete.  
7. The main receive loop uses async for raw_msg in ws to process incoming frames and checks the message type to handle text frames and track errors.  
8. Text frames are parsed as JSON; JSONDecodeError triggers an error response back to the client and the loop continues without dispatch.  
9. Valid messages are handed to handle_ws_message which inspects a top-level type field and routes to appropriate behavior.  
10. For type 'chat' the message content is normalized, empty content is ignored, and content starting with '/' is treated as a slash command while other chat text is passed to the chat handler.  
11. For type 'command' the handler normalizes and forwards the command string to the command handler.  
12. For type 'cancel' the function sets server.agent.cancel_event when available to request cancellation and logs the action.  
13. The type 'approval_response' is recognized but currently a no-op placeholder.  
14. On exit from the receive loop the finally block ensures the socket is removed from server.clients and the WebSocketResponse is returned to complete cleanup.

---

## captain-claw-src/captain_claw/web/google_oauth.py

Description:
1. This module implements HTTP handlers for Google OAuth2 flows used by the web server.  
2. It provides endpoints to start the login flow, handle the OAuth callback, report status, and perform logout.  
3. The login handler validates configuration, generates a PKCE verifier/challenge pair and a random state, records the pending state, and redirects the browser to Google's authorization URL.  
4. The callback handler validates the returned code and state, exchanges the authorization code for tokens, and optionally fetches user profile information.  
5. On successful token exchange it stores tokens and user info via the server's OAuth manager and injects credentials into an LLM provider when applicable.  
6. A status handler returns JSON indicating whether Google OAuth is enabled, connected, and includes stored user info when connected.  
7. The logout handler instructs the OAuth manager to disconnect and clears injected credentials from the active provider.  
8. Utilities in the module purge stale pending PKCE states older than ten minutes to avoid replayed or expired states.  
9. The module uses aiohttp.web types and responses and constructs HTML responses for human-facing error and success pages.  
10. It relies on helper functions from captain_claw.google_oauth for PKCE generation, URL building, token exchange, and user info retrieval.  

Purpose:
1. This file exists to integrate Google OAuth2 authentication into the web component of the application and to centralize the HTTP endpoints related to that integration.  
2. It enables users to authenticate via Google and allows the server to obtain, store, and use OAuth tokens and user profile information.  
3. The handlers enforce basic configuration checks so OAuth is only available when enabled and properly configured.  
4. By generating PKCE pairs and state tokens the module improves security and prevents CSRF/replay attacks during the OAuth flow.  
5. The callback handler converts the OAuth authorization code into usable tokens and handles errors with informative HTML responses to aid debugging or user feedback.  
6. Storing tokens and user info through the server's OAuth manager decouples credential persistence from HTTP handling and centralizes token lifecycle operations.  
7. Injecting credentials into the Gemini (Vertex) provider allows LLM-related functionality to access Google services when required, bridging authentication and model provider configuration.  
8. The status endpoint provides a simple JSON API for frontend components to show connection state and the connected user's identity.  
9. The logout endpoint allows administrators or users to revoke stored credentials and to remove those credentials from any active providers.  
10. Logging is included to record token exchange failures and user info fetch issues so administrators can diagnose problems.  
11. The module is intentionally lightweight and delegates heavy lifting (token exchange, PKCE, user info fetching) to dedicated helper functions and an OAuth manager implementation.  
12. Overall, the file exists to provide a secure, user-facing OAuth flow and to make acquired credentials available to other server components in a controlled way.  

Key elements:
- auth_google_login (async function) — starts OAuth flow, generates state and PKCE, stores pending state, redirects to Google.  
- auth_google_callback (async function) — handles OAuth callback, validates state/code, exchanges code for tokens, fetches user info, stores tokens, and injects credentials.  
- auth_google_status (async function) — returns JSON with connected/enabled flags and user info when connected.  
- auth_google_logout (async function) — revokes/disconnects stored tokens and clears injected credentials.  
- inject_oauth_into_provider (async function) — retrieves vertex credentials from OAuth manager and injects into LiteLLMProvider (Gemini) if active.  
- clear_oauth_from_provider (function) — clears vertex credentials from an active LiteLLMProvider.  
- generate_pkce_pair, build_authorization_url, exchange_code_for_tokens, fetch_user_info (external helpers from captain_claw.google_oauth).  
- server._pending_oauth (dict) — in-memory pending state storage keyed by state with verifier and timestamp.  
- server._oauth_manager (pluggable manager) — used to store tokens, store user info, check connection, get credentials, disconnect.  
- get_config (external call) — reads google_oauth settings such as enabled, client_id, client_secret, scopes, project_id, location, and web port.  
- LiteLLMProvider and its methods set_vertex_credentials / clear_vertex_credentials (used when provider == "gemini").  
- aiohttp.web responses and exceptions (web.Response, web.json_response, web.HTTPFound) — used for HTTP interactions.  
- logging via get_logger — logs token exchange failures and user info fetch warnings.  

Key logic:
1. The login endpoint first reads configuration and returns an error JSON response if Google OAuth is not enabled or missing client_id.  
2. It purges any pending PKCE states older than 600 seconds to limit the validity window and prevent stale state reuse.  
3. A random URL-safe state token is generated and a PKCE verifier/challenge pair is created; the verifier is saved alongside a timestamp under server._pending_oauth[state].  
4. The module constructs a redirect_uri pointing to localhost with the configured web port and builds the Google authorization URL using provided scopes and the PKCE challenge, then issues an HTTP redirect to that URL.  
5. The callback handler inspects the query for an error parameter and returns an HTML error page if present, providing user-facing diagnostics.  
6. It validates presence of both code and state, then attempts to pop the matching pending state; missing or expired state results in an HTML error response.  
7. The handler performs the token exchange by calling exchange_code_for_tokens with the authorization code, client credentials, redirect URI, and the stored PKCE verifier; token exchange failures are logged and returned as HTML error pages.  
8. After obtaining tokens it tries to fetch Google user info with the access token, logs a warning on failure, and proceeds with empty user info if necessary.  
9. If an OAuth manager is configured on the server, the handler stores the tokens and user info through that manager and then calls inject_oauth_into_provider to pass vertex credentials into a Gemini provider if present.  
10. The successful callback returns a small HTML page that indicates the connected account and automatically redirects the browser back to the home page.  
11. The status handler reads configuration and the server's OAuth manager to return a JSON object describing whether OAuth is enabled, whether a connection exists, and the stored user info when connected.  
12. The logout handler asks the OAuth manager to disconnect, then calls clear_oauth_from_provider to remove any injected vertex credentials from the active provider, and returns a JSON confirmation.

---

## captain-claw-src/captain_claw/web/rest_instructions.py

Description:
1. This module provides aiohttp REST handlers for managing markdown instruction files used by the application.  
2. It exposes handlers to list available instruction files, read a specific instruction, save a personal override, and revert a personal override to the system default.  
3. The listing handler merges files from a system directory and a personal overrides directory, marking files that are overridden.  
4. The read handler validates the requested file name, prefers a personal override if present, and returns the file content as JSON.  
5. The save handler validates the name and resolved path, writes content into the personal overrides directory, and reports whether the file was created or updated.  
6. The revert handler deletes a personal override (if present), ensures a system default exists, and returns the reverted system content.  
7. All file reads and writes use UTF-8 encoding and report file sizes from the filesystem.  
8. Name validation prevents path traversal and requires the filename to end with the ".md" suffix.  
9. When changes occur the handlers clear the agent's instruction cache for the named file if an agent is attached to the server.  
10. Responses are returned as JSON objects with status details, file metadata, and content when applicable.

Purpose:
1. This file exists to provide HTTP endpoints that let clients manage instruction markdown files used by the application.  
2. It centralizes the filesystem operations and validation logic for instruction content so that web clients can view, edit, and revert instructions through the web API.  
3. By supporting both a system directory and a personal overrides directory, it enables a default set of instructions to be shipped while allowing user-specific customizations.  
4. The module enforces filename and path safety to prevent directory traversal and accidental writes outside the intended personal directory.  
5. Returning metadata such as file size and overridden status helps clients present a combined view of available and overridden instructions.  
6. Clearing the agent's cached instruction entry when a personal file is saved or reverted ensures consumers of instructions will see updated content.  
7. The handlers return clear error JSONs and HTTP status codes for invalid names, missing files, and invalid revert attempts, supporting robust client behavior.  
8. Using simple JSON responses keeps the API straightforward to consume from JavaScript frontends or other HTTP clients.  
9. The module is lightweight and focused on file management concerns, delegating higher-level instruction parsing or agent behavior to other components.  
10. It exists as part of the web server layer, mapping REST endpoints to safe filesystem operations and coordinating cache invalidation with the agent when present.  
11. The separation of system and personal directories implemented here supports an expected workflow of shipping defaults while preserving user edits.  
12. Overall, it provides a controlled, auditable mechanism for manipulating instruction files via HTTP.

Key elements:
- list_instructions (async handler) — merges system and personal instruction directories and returns a sorted JSON list.  
- get_instruction (async handler) — validates a filename, selects personal or system file, reads content, and returns JSON.  
- put_instruction (async handler) — validates filename and path containment, writes content to personal directory, creates directories as needed, and clears agent cache.  
- revert_instruction (async handler) — validates filename, removes the personal override, verifies system default exists, reads system content, and clears agent cache.  
- server._instructions_dir (filesystem Path) — system instruction directory used as the default source.  
- server._instructions_personal_dir (filesystem Path) — personal override directory where edits are written.  
- server.agent.instructions._cache (dict access) — cache that is popped to invalidate cached instruction content when files change.  
- web.json_response (aiohttp) — used to construct JSON HTTP responses with optional status codes.  
- Path.read_text / write_text / stat / unlink / is_file / is_dir / iterdir (pathlib) — filesystem operations used throughout.  
- path.resolve().relative_to(...) check — used to ensure saved paths remain inside the personal directory.

Key logic:
1. The listing handler builds a dictionary keyed by filename to deduplicate system and personal entries, processing system files first and then overwriting entries with personal overrides so overridden status and size reflect the personal file.  
2. Both directories are iterated in sorted order and only files with a ".md" suffix and that are regular files are collected.  
3. The final list returned by the listing handler is sorted by filename and returned as JSON objects containing name, size, and overridden flag.  
4. Filename validation in the read, put, and revert handlers rejects names containing "..", forward slashes, backslashes (for put/revert), or names not ending with ".md" and returns a 400 error JSON for invalid names.  
5. The read handler constructs personal and system paths, determines whether the personal path exists, chooses the appropriate path, checks existence, reads the file content with UTF-8, and returns name, content, and overridden flag; missing files produce a 404 JSON.  
6. The save (put) handler additionally checks that the resolved target path is actually inside the personal directory using resolve().relative_to(...); a ValueError from that check triggers a 400 invalid path response.  
7. The save handler reads JSON body content from the request, ensures the personal directory exists by creating parents if necessary, writes the content with UTF-8, and determines whether the action created a new file or updated an existing one to set the status field.  
8. After writing or deleting a personal file, handlers check server.agent and, if present, remove the named entry from server.agent.instructions._cache to force downstream refreshes of instruction content.  
9. The revert handler ensures a personal override exists and that a system default also exists before unlinking the personal file; if the system default is missing it returns a 400 error indicating revert cannot proceed.  
10. On successful revert, the handler reads the system file text and returns a JSON response with status "reverted", the content, size, and overridden false.  
11. All handlers rely on aiohttp.web.Request match_info to obtain the requested filename and use aiohttp.web.json_response for uniform structured HTTP responses.  
12. Error conditions are handled with appropriate HTTP status codes (400 for invalid input or bad path, 404 for not found) and explanatory JSON error messages.

---

## captain-claw-src/captain_claw/web/static_pages.py

Description:
1. This module defines asynchronous aiohttp request handlers that serve static pages for the web UI.  
2. It computes a STATIC_DIR path relative to the module file and uses it as the source for static assets.  
3. Several handlers return web.FileResponse objects that point to specific HTML files inside STATIC_DIR.  
4. The serve_favicon handler checks for the presence of a favicon.svg file and returns it if present.  
5. If the favicon file is not present, serve_favicon returns a web.Response with status 204 instead of a file.  
6. Handlers are declared to accept a server object (typed as WebServer under TYPE_CHECKING) and the aiohttp request.  
7. The module imports pathlib.Path for filesystem path manipulation and aiohttp.web for response types.  
8. All HTML filenames used by handlers are hard-coded (e.g., home.html, index.html, orchestrator.html).  
9. The module contains no additional routing logic, error handling beyond the favicon check, or dynamic content generation.  
10. The overall design is a lightweight static-file-serving layer for the application's frontend pages.

Purpose:
1. This file exists to centralize and expose simple aiohttp handlers that deliver the web application's static HTML pages.  
2. By resolving STATIC_DIR relative to the module, it makes the static assets location explicit and portable across deployments.  
3. The handlers provide a clear mapping between logical endpoints (home, chat, orchestrator, etc.) and concrete HTML files.  
4. Implementing these handlers as async functions maintains compatibility with aiohttp's handler model and the rest of the web server.  
5. The serve_favicon handler includes a small optimization/guard to avoid returning a missing-file response when the favicon is absent.  
6. Typing the server parameter via TYPE_CHECKING with WebServer documents the intended server context without requiring runtime imports.  
7. Keeping filenames hard-coded simplifies the routing and reduces configuration complexity for the static UI assets.  
8. The module is intentionally minimal so it can be reused or extended easily if additional static pages are added.  
9. It separates concerns by handling only static page delivery while leaving routing registration and business logic to the web server.  
10. This separation makes tests and maintenance easier because the handlers have deterministic behavior tied to files.  
11. The module relies on aiohttp.web primitives so it integrates directly with middleware, static resource handling, and server lifecycle.  
12. Overall, the purpose is to provide a simple, maintainable bridge between HTTP endpoints and the frontend's static HTML files.

Key elements:
- STATIC_DIR (pathlib.Path) — base directory for static files resolved relative to this module.  
- serve_home(server, request) — async handler that serves "home.html" via web.FileResponse.  
- serve_chat(server, request) — async handler that serves "index.html" via web.FileResponse.  
- serve_favicon(server, request) — async handler that serves "favicon.svg" if it exists, otherwise returns web.Response(status=204).  
- serve_orchestrator(server, request) — async handler that serves "orchestrator.html" via web.FileResponse.  
- serve_instructions(server, request) — async handler that serves "instructions.html" via web.FileResponse.  
- serve_cron(server, request) — async handler that serves "cron.html" via web.FileResponse.  
- serve_workflows(server, request) — async handler that serves "workflows.html" via web.FileResponse.  
- serve_loop_runner(server, request) — async handler that serves "loop-runner.html" via web.FileResponse.  
- serve_memory(server, request) — async handler that serves "memory.html" via web.FileResponse.  
- Imports: pathlib.Path (for path resolution) and aiohttp.web (for FileResponse and Response).  
- TYPE_CHECKING + WebServer typing (used for type hints without runtime import).

Key logic:
1. On import, STATIC_DIR is computed as the "static" subdirectory located next to the module file, using Path(__file__).resolve().parent / "static".  
2. Each handler is an async function that accepts a server parameter and the incoming aiohttp request, matching the expected handler signature.  
3. For most endpoints, the handler constructs a path by joining STATIC_DIR with a hard-coded HTML filename and returns web.FileResponse pointing to that path.  
4. The use of web.FileResponse delegates file serving to aiohttp's response mechanism rather than reading file contents into memory inside the handler.  
5. The serve_favicon handler first resolves the favicon.svg path and checks favicon.is_file() to decide whether to return a FileResponse or a 204 Response.  
6. There is no other file existence checking or explicit error handling in the handlers; they rely on aiohttp's FileResponse behavior for file delivery.  
7. Handlers do not inspect request attributes, query parameters, or headers; they always serve the same static file for a given endpoint.  
8. The presence of TYPE_CHECKING and an import annotation for WebServer means the server parameter is intended to be used by the caller or for future extensions but is not used at runtime here.  
9. Because filenames are fixed, adding new static endpoints requires adding a new handler that returns the corresponding FileResponse for the new file.  
10. The module's control flow is straightforward and synchronous at the application level: compute path, check favicon existence when applicable, return appropriate aiohttp response.  
11. Any filesystem or permission errors when aiohttp attempts to open the files will be handled by aiohttp or surface as exceptions; this module does not catch them.  
12. The design favors simplicity and low overhead, making the handlers easy to register with the web server's routing table and predictable in behavior.

---

## captain-claw-src/captain_claw/session/__init__.py

Description:
1. This module implements session and cross-session persistence using an SQLite database accessed asynchronously via aiosqlite.  
2. It declares multiple dataclasses representing domain entities such as Message, Session, CronJob, TodoItem, ContactEntry, ContactMention, ScriptEntry, and ApiEntry.  
3. The SessionManager class encapsulates database initialization, schema creation, and CRUD operations for sessions, cron jobs, to-dos, contacts, scripts, and APIs.  
4. Database initialization creates tables and indexes and includes a migration step to add missing cron_jobs columns for backward compatibility.  
5. Many fields that are structured (messages, payloads, histories, metadata) are serialized to and from JSON when stored in the SQLite tables.  
6. Selection helpers accept flexible selectors (exact id, named entity, or numeric index using optional "#" prefixes) for sessions, cron jobs, todos, scripts, and APIs.  
7. The module implements utility behaviors such as computing a UTC ISO timestamp, archiving old todos, incrementing usage counters, and appending per-job history with size trimming.  
8. Contact importance can be auto-computed from mention frequency, recency, and the number of distinct sessions, and that computed value is persisted.  
9. A simple global singleton pattern exposes a module-level SessionManager via get_session_manager and set_session_manager functions.  
10. The module depends on standard libraries (json, uuid, datetime, pathlib, dataclasses, typing) and on project-specific get_config and get_logger utilities.

Purpose:
1. The file exists to provide a centralized, persistent store for conversational sessions and various cross-session memories required by the application.  
2. It exists to make session data durable between runs by mapping in-memory dataclasses to SQLite rows and JSON blobs in a consistent schema.  
3. By encapsulating schema creation and migration logic in _ensure_db and _ensure_cron_jobs_migrations, the module ensures forward- and backward-compatible storage across releases.  
4. It supplies a single abstraction (SessionManager) that other parts of the application can call to create, load, list, update, and delete sessions and related domain objects.  
5. The selection helpers and list/search methods provide convenient, user-facing resolution semantics (id/name/index/fuzzy match) so UI or CLI code can resolve items flexibly.  
6. The module centralizes auxiliary app state storage and last-active-session tracking so session lifecycle and user context can be preserved.  
7. Cron job persistence and related helpers are included so scheduled or pseudo-cron tasks can be managed, queried for due work, and have execution history recorded.  
8. To-do items, contacts, scripts, and API memories are stored here to enable cross-session features such as reminders, address-book functionality, script reuse, and API endpoint management.  
9. The auto-importance and archival routines provide simple domain-specific logic (importance scoring, tombstoning old items) that keeps stored data actionable without external tooling.  
10. JSON serialization of structured columns and indices for common access patterns (name, updated_at, use_count, importance) optimize typical queries executed by UI and orchestration layers.  
11. The global singleton accessor is provided to avoid duplicating connection setup and to make manager reuse easy across the codebase.  
12. Methods that increment usage and timestamps support telemetry-style bookkeeping (use_count, last_used_at) for prioritization and ordering in lists and searches.  
13. The module's async API is tailored for an asynchronous application architecture, allowing non-blocking database access from web handlers, schedulers, or background tasks.  
14. Overall, it exists to be the authoritative, durable store for conversational context and related artifacts needed by other project components.

Key elements:
- _utcnow_iso (function): returns current UTC time in ISO format.  
- Message (dataclass): lightweight message record with role, content, tool metadata, tokens, timestamp.  
- Session (dataclass): conversation session with id, name, messages, created_at, updated_at, metadata; methods add_message, to_dict, from_dict.  
- CronJob (dataclass): persisted pseudo-cron job with from_row constructor and fields for schedule, history, status.  
- TodoItem (dataclass): to-do entry with from_row and to_dict.  
- ContactEntry (dataclass): contact/address-book entry with from_row and to_dict.  
- ContactMention (dataclass): mention log with from_row.  
- ScriptEntry (dataclass): stored script/file memory with from_row and to_dict.  
- ApiEntry (dataclass): stored API memory with from_row and to_dict.  
- SessionManager (class): core manager handling DB path config, _ensure_db, schema creation, and extensive CRUD for sessions, cron jobs, todos, contacts, scripts, and apis.  
- SessionManager methods of note: get_or_create_session, load_session, save_session, list_sessions, delete_session; create_cron_job, list_cron_jobs, get_due_cron_jobs, update_cron_job, append_cron_job_history; create_todo, list_todos, update_todo, archive_old_todos; create_contact, search_contacts, update_contact, increment_contact_mention, compute_auto_importance; create_script/search_scripts/update_script/increment_script_usage; create_api/search_apis/update_api/increment_api_usage; close.  
- App state helpers: get_app_state, set_app_state, delete_app_state, get_last_active_session_id, set_last_active_session, load_last_active_session.  
- Global singleton: _manager, get_session_manager, set_session_manager.  
- External dependencies: aiosqlite (async DB), json (serialization), uuid (ids), get_config (config retrieval), get_logger (logging), pathlib.Path, datetime.UTC.

Key logic:
1. On first use, SessionManager._ensure_db opens an aiosqlite connection, creates required tables, and defines multiple indexes to support efficient queries; it then runs migrations for cron_jobs to add missing columns when needed.  
2. Structured fields (lists, dicts) are marshaled to JSON strings for storage and unmarshaled on read; this pattern is used for messages, payloads, schedules, histories, and metadata.  
3. Session creation assigns a UUID, default timestamps, and immediately persists the new session with save_session which updates updated_at and writes a JSON-encoded messages field.  
4. Session selection supports three resolution strategies: direct id lookup, latest session with matching name, and numeric index into the recent sessions list parsed from selectors that may start with "#".  
5. List methods build SQL queries with ORDER BY clauses optimized for their domain (e.g., sessions ordered by updated_at, scripts and apis ordered by use_count then updated_at, contacts ordered by importance and mention_count).  
6. Update methods construct dynamic SQL assignments from provided keyword arguments, prepend an updated_at timestamp, and execute a single UPDATE statement, returning a boolean based on affected rowcount.  
7. Cron job retrieval includes filters for enabled jobs and next_run_at comparisons to implement get_due_cron_jobs; append_cron_job_history reads the job, appends events, trims lists to max_entries, and writes the updated JSON back via update_cron_job.  
8. To-do listing composes WHERE clauses conditionally for status/responsible/session filters and applies a CASE-based priority ordering to surface urgent items first; update_todo sets completed_at when status transitions to done.  
9. archive_old_todos computes age using SQLite julianday differences and marks long-completed items as cancelled in a single UPDATE statement.  
10. Contact management includes fuzzy search using SQL LIKE with COLLATE NOCASE, mention recording that inserts into contact_mentions and atomically increments mention_count and last_seen_at on the contact row.  
11. compute_auto_importance reads mention_count and last_seen_at to compute a recency factor (21-day half-life), queries distinct session mentions for a diversity factor, computes a log2-based score, clamps it between 1 and 10, and persists the computed importance via update_contact.  
12. Script and API memories support create/read/update/delete plus search by LIKE patterns and ordering by use_count to help discover frequently used items; increment_*_usage updates use_count and timestamps.  
13. Selector helpers for scripts, apis, cron jobs, and todos share similar behaviors: try direct id, then numeric index when prefixed with "#", then fallback to search returning the first match.  
14. The module maintains a simple global singleton manager instance lazily instantiated by get_session_manager to centralize connection lifecycle; set_session_manager allows tests or alternative instances to be injected.

---

## captain-claw-src/captain_claw/agent_tool_loop_mixin.py

Description:
1. The AgentToolLoopMixin module provides a comprehensive set of helpers for parsing, executing, and managing tool calls produced by an LLM-driven agent. 
2. It implements robust mechanisms for scale-aware processing, including guards against off-track behavior, duplicate call detection, and context trimming to keep the conversation size bounded. 
3. The mixin supports a micro-turn scale loop that extracts, processes with a single isolated LLM call, and writes results per item to avoid context growth and LLM confusion. 
4. It includes utilities to derive item labels, detect the appropriate extractor for a given item (URL, file path or extension), and build concise item-specific prompts that include optional format references. 
5. The code instruments execution with progress and thinking indicators, precise timing, and token accounting to monitor performance and ETA. 
6. Tool call extraction supports many embedded formats (code blocks, XML-like invocations, JSON blobs, and pseudo-DSL patterns) and normalizes them to ToolCall objects. 
7. Execution of tool calls is mediated by guards (scale guard), duplicate-call limits, and stateful vs stateless tool classification. 
8. After tool execution, the mixin updates internal scale progress, emits outputs into the session, and triggers trimming of large extractor outputs to reclaim context tokens. 
9. It also contains helper methods for friendly rewrite of raw tool output, clipping long outputs for rewrite prompts, and heuristics about whether the runtime model supports tool-result followups. 
10. Overall, the module is focused on reliable, incremental, and scalable execution of tool-driven agent workflows.

Purpose:
1. The primary purpose of AgentToolLoopMixin is to make large-scale, item-by-item processing dependable and efficient when orchestrated by an LLM, by enforcing a strict extract→process→write pattern that prevents the LLM from re-discovering or re-reading items and avoids quadratic context growth. 
2. It provides a scale guard that actively blocks or redirects off-track tool calls (like re-globbing, reading output files, or re-extracting already-processed items) so the agent behaves like a state machine and follows the intended incremental workflow. 
3. The mixin implements a micro-turn loop that isolates each item's processing into a single short LLM conversation, thereby keeping latency and context size constant regardless of list length and allowing thousands of items to be processed without LLM confusion. 
4. It centralizes tool-call parsing from free-form model responses, turning varied embedded syntax into structured ToolCall objects for consistent handling. 
5. The mixin also performs duplicate-call detection with configurable thresholds and special allowances during scale tasks, which reduces wasted executions and prevents repeated expensive operations. 
6. It tracks progress transparently (total, completed, remaining) and injects a compact progress note into LLM calls so the model never needs to re-glob or re-check the output. 
7. When writes occur, the mixin attempts to detect which item was written and marks items as done, updating internal counters and optionally compressing older assistant/tool message pairs to conserve tokens. 
8. The mixin supports multiple output strategies (single shared file, per-item files, or no-file sinks like typesense/email) and routes writes accordingly. 
9. It exposes hooks and emits structured monitoring messages so the hosting agent can surface human-friendly progress and diagnostics. 
10. Finally, the mixin coordinates cancellation, error accumulation, and retry-friendly behaviors (like rolling back duplicate counters on failure) to make large automated runs robust and recoverable.

Key elements:
- Methods (major): _trim_processed_extracts_in_session, _scale_guard_intercept, _build_scale_progress_note, _derive_member_label, _detect_item_extractor, _build_scale_item_prompt, _resolve_per_item_filename, _run_scale_micro_loop, _scale_loop_ready, _get_scale_task_description.
- Methods (utilities): _tool_thinking_summary, _extract_command_from_response, _supports_tool_result_followup, _collect_turn_tool_output, _turn_has_successful_tool, _clip_tool_output_for_rewrite, _friendly_tool_output_response, _extract_tool_calls_from_content, _handle_tool_calls.
- Objects / attributes: self.session (session message list), self._scale_progress (tracking dict), Message, ToolCall, cancel_event, instructions, tools registry, various helper counters (e.g. _turn_tool_call_counts).
- External calls / hooks: _execute_tool_with_guard (executes named tools), _complete_with_guards (LLM completion wrapper), _emit_thinking (status line), _emit_tool_output (UI/log output), _add_session_message (store tool results), _count_tokens (token accounting), get_config(), get_logger().
- Data flows: tool call parsing → guard/dup checks → _execute_tool_with_guard → session append + emit → scale progress updates → optional trimming and monitoring emits.

Key logic:
1. The mixin implements a layered guarding strategy to keep scale tasks on-track: a scale guard intercepts calls that would rediscover items or re-read output files and returns a redirect message instead of executing the tool. 
2. Duplicate-call detection computes a canonical signature per tool invocation (path, url, pattern, or serialized args) and tracks counts per turn; once a threshold is reached the mixin blocks further redundant executions and returns a helpful DUPLICATE CALL BLOCKED message. 
3. Extraction detection maps items to extractor tools by checking for explicit URLs, embedded URLs, known file extensions, or falling back to a file read. 
4. The micro-turn scale loop follows a strict four-step flow for each item: extract content with the detected tool, call the LLM once with a minimal prompt to produce a processed summary, write or sink the result according to the output strategy, and update progress tracking. 
5. For no-file strategies the loop supports sinks like typesense (indexing), send_mail, or in-memory reply accumulation, and handles sink failures separately from extract/LLM errors. 
6. The loop instruments time and token usage for each item to compute ETA and performance metrics, and it captures the last written summary to provide a format reference to later LLM calls so outputs remain consistent. 
7. After each successful write the mixin attempts to match written content or filenames to items and mark them done; it also records resolved absolute output paths and tracks when multiple distinct output files exist (which can prevent micro-loop takeover). 
8. The mixin prunes large extractor tool results and compresses older assistant/tool message pairs to prevent linear context growth, using configurable thresholds and keeping a small window of recent full pairs for continuity. 
9. Tool result handling appends helpful hints when the agent appears to be skipping write steps, and it rolls back duplicate counters on failures to allow retries. 
10. Embedded tool-call extraction supports many syntaxes: annotated blocks, DSL-like maps, JSON blobs, and XML-ish invokes; parsed calls are normalized into ToolCall objects with deduplication of identical signatures. 
11. Friendly rewrite logic clips long raw output into representative blocks and asks the LLM to produce a user-facing summary using stored prompt templates, with fallback to returning the raw output if the rewrite fails. 
12. Throughout, cancellation checks are performed at safe points (between items, after extract, after LLM) so long runs can be stopped promptly and cleanly. 
13. The mixin also provides heuristics for model/runtime compatibility (e.g., whether tool-role messages can be followed up) and exposes hooks for auto-capturing contacts, scripts, and APIs after certain successful tool calls. 
14. Finally, the mixin logs structured diagnostics at key events (start/finish per item, write results, errors) and returns a summarized result dict at loop completion describing processed, failed, cancelled, and error details.