From 74f9870298c73734d1bddea49089495eb7930fc4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=AD=A6=E9=98=B3?= Date: Wed, 6 May 2026 16:24:57 +0800 Subject: [PATCH] Remove obsolete project docs --- PARITY_CHECKLIST.md | 843 ------------------- TESTING_GUIDE.md | 1879 ------------------------------------------- claw-code-agent.md | 845 ------------------- data_agent_v0.md | 391 --------- 4 files changed, 3958 deletions(-) delete mode 100644 PARITY_CHECKLIST.md delete mode 100644 TESTING_GUIDE.md delete mode 100644 claw-code-agent.md delete mode 100644 data_agent_v0.md diff --git a/PARITY_CHECKLIST.md b/PARITY_CHECKLIST.md deleted file mode 100644 index 1277af4..0000000 --- a/PARITY_CHECKLIST.md +++ /dev/null @@ -1,843 +0,0 @@ -# Parity Checklist Against npm `src` - -This document tracks what is already implemented in Python and what is still missing compared with the upstream npm runtime. - -This is a functionality-oriented checklist, not a line-by-line source equivalence claim. Large parts of the mirrored Python workspace still act as inventory or scaffolding, while the working Python runtime currently lives mainly in [`src/agent_runtime.py`](src/agent_runtime.py), [`src/query_engine.py`](src/query_engine.py), [`src/agent_tools.py`](src/agent_tools.py), [`src/agent_prompting.py`](src/agent_prompting.py), [`src/agent_context.py`](src/agent_context.py), [`src/agent_manager.py`](src/agent_manager.py), [`src/plugin_runtime.py`](src/plugin_runtime.py), [`src/agent_slash_commands.py`](src/agent_slash_commands.py), [`src/openai_compat.py`](src/openai_compat.py), [`src/builtin_agents.py`](src/builtin_agents.py), [`src/microcompact.py`](src/microcompact.py), [`src/compact.py`](src/compact.py), [`src/bundled_skills.py`](src/bundled_skills.py), and [`src/session_memory_compact.py`](src/session_memory_compact.py). - ---- - -## 1. Core Agent Runtime - -Done: - -- [x] One-shot agent loop with iterative tool calling -- [x] OpenAI-compatible `chat/completions` client -- [x] Streaming token-by-token assistant output -- [x] Local-model execution against `vLLM` -- [x] Local-model execution through `Ollama` -- [x] Local-model execution through `LiteLLM Proxy` -- [x] Transcript-aware session object for the Python runtime -- [x] Session save and resume support -- [x] Configurable max-turn execution -- [x] Permission-aware tool execution -- [x] Structured output / JSON schema request mode -- [x] Cost tracking and usage budget enforcement -- [x] Scratchpad directory integration -- [x] File history journaling for write/edit/shell tool actions -- [x] Incremental `bash` tool-result streaming events -- [x] Incremental tool-result streaming for read-only text tools -- [x] Incremental tool-result streaming across the current Python text tool surface -- [x] Mutable tool transcript updates during tool execution -- [x] Transcript mutation history for replaced/tombstoned messages -- [x] Assistant streaming and tool-call transcript mutation history -- [x] Session-wide mutation serial tracking across transcript updates -- [x] Structured transcript block export for messages, tool calls, and tool results -- [x] Resume-time file-history replay reminders -- [x] Resume-time file-history snapshot previews for file edits -- [x] File-history snapshot ids and replay summaries for file edits -- [x] File-history result previews for shell and delegated-tool entries -- [x] Truncated-response continuation flow for `finish_reason=length` -- [x] Basic snipping of older tool/tool-call messages for context control -- [x] Basic automatic compact-boundary insertion with preserved recent tail -- [x] Reactive compaction retry after prompt-too-long backend failures -- [x] Reasoning-token budget enforcement -- [x] Tool-call and delegated-task budget enforcement -- [x] Resume-aware cumulative model-call budgets -- [x] Resume-aware cumulative session usage/cost persistence -- [x] Basic nested-agent delegation tool -- [x] Sequential multi-subtask delegation with parent-context carryover -- [x] Dependency-aware delegated subtasks -- [x] Topological dependency-batch delegation planning -- [x] Basic agent-manager lineage tracking for nested agents -- [x] Managed agent-group membership tracking with child indices -- [x] Agent-manager strategy and batch summary tracking for delegated groups -- [x] Delegated child-session resume by saved session id -- [x] Agent-manager tracking for resumed child-session lineage -- [x] Plugin-cache discovery and prompt-context injection -- [x] Manifest-based plugin runtime discovery -- [x] Manifest-defined plugin hooks for before-prompt and after-turn runtime injection -- [x] Manifest-defined plugin lifecycle hooks for resume, persist, and delegate phases -- [x] Manifest-defined plugin tool aliases over base runtime tools -- [x] Manifest-defined executable virtual tools -- [x] Manifest-defined plugin tool blocking -- [x] Manifest-defined plugin `beforeTool` guidance -- [x] Manifest-defined plugin tool-result guidance injected back into the transcript -- [x] Plugin runtime session-state persistence and resume restoration -- [x] Manifest-based hook/policy runtime discovery -- [x] Hook/policy before-prompt runtime injection -- [x] Hook/policy after-turn runtime events -- [x] Hook/policy tool preflight guidance -- [x] Hook/policy tool blocking -- [x] Hook/policy after-tool guidance -- [x] Hook/policy budget override loading -- [x] Hook/policy safe-environment overlay for shell tools -- [x] Local manifest-backed MCP resource discovery -- [x] Local MCP resource listing and reading -- [x] MCP-backed runtime tools for local resource access -- [x] Real stdio MCP client transport for `initialize`, `resources/list`, `resources/read`, `tools/list`, and `tools/call` -- [x] Transport-backed MCP tool listing and execution -- [x] Local manifest-backed remote runtime discovery -- [x] Local remote profile listing and summary reporting -- [x] Local remote connect/disconnect state persistence -- [x] Local manifest/env-backed search runtime discovery -- [x] Local search-provider activation persistence -- [x] Provider-backed web search execution against configured search backends -- [x] Local heuristic LSP runtime for definitions, references, hover, document symbols, workspace symbols, call hierarchy, and diagnostics -- [x] Local persistent task runtime discovery -- [x] Local task create/get/list/update runtime flows -- [x] Local todo-list replacement runtime flow -- [x] Local persistent plan runtime discovery -- [x] Local plan get/update/clear runtime flows -- [x] Local plan-to-task sync flow -- [x] Dependency-aware local task state with blocking and actionable-task selection -- [x] Local task start/complete/block/cancel execution flows -- [x] Compaction metadata with compacted message ids -- [x] Compaction metadata with preserved-tail ids and compaction depth -- [x] Compaction metadata with compacted/preserved lineage ids and revision summaries -- [x] Compaction metadata with source mutation serials and mutation totals -- [x] Snipped-message metadata with source role/kind lineage -- [x] Snipped-message metadata with source lineage id and revision -- [x] Resume-time compaction / snipping replay reminder -- [x] Resume-time compaction replay of source mutation summaries -- [x] Preflight prompt-length validation before each model call -- [x] Hard prompt-length stop before backend calls when the effective input budget is exceeded -- [x] Token-budget calculation with projected prompt size, chat framing overhead, output reserve, and soft/hard input limits -- [x] Preflight auto-compact/context collapse fallback before the next model call -- [x] Query-engine facade that can drive the real Python runtime agent -- [x] Query-engine runtime event counters and transcript-kind summaries -- [x] Query-engine runtime mutation counters -- [x] Query-engine stream-level runtime summary event -- [x] Query-engine transcript-store compaction summaries -- [x] Delegate-group and delegated-subtask runtime events -- [x] Delegate-batch runtime events and summaries -- [x] Query-engine runtime orchestration summaries for group status and child stop reasons -- [x] Query-engine runtime context-reduction summaries -- [x] Query-engine runtime lineage summaries -- [x] Query-engine runtime resumed-child orchestration summaries -- [x] Filesystem-backed custom agent discovery from `~/.claude/agents` and `./.claude/agents` -- [x] Active agent override precedence across built-in, user, and project agent definitions -- [x] Custom agent resolution in the `Agent` tool with model, tool-filter, and initial-prompt support -- [x] Local custom-agent file creation, update, and deletion flows for project/user agent definitions - -Missing: - -- [ ] Full partial tool-result streaming parity across the complete upstream/npm tool surface -- [ ] Full rich transcript mutation behavior like the npm runtime beyond the current lineage, counters, block export, and mutation-serial tracking -- [ ] Full reasoning budgets and task budgets parity beyond the current cumulative model/tool/delegation/session-call enforcement -- [ ] Full multi-agent orchestration parity beyond dependency-aware batched delegation, resumed-child flows, and current agent-manager summaries -- [ ] Full file history snapshots and replay flows beyond the current preview/id-based implementation and delegated-batch replay metadata -- [ ] Full executable plugin lifecycle beyond manifest-driven prompt/tool/session hooks, blocking, aliases, virtual tools, and persisted runtime state -- [ ] Full session compaction / snipping parity beyond lineage-aware summaries, mutation-serial compaction metadata, and replay reminders -- [ ] Full `QueryEngine.ts` parity (session init, message normalization, SDK-compatible message transforms, attachment handling) -- [x] Auto-compact and context collapse features from `query.ts` -- [x] Prompt length validation from `query.ts` -- [x] Token budget calculations from `query/tokenBudget.ts` - -## 2. CLI Entrypoints And Runtime Modes - -Done: - -- [x] Python CLI entrypoint -- [x] `agent` command -- [x] `agent-chat` command -- [x] `agent-resume` command -- [x] `agent-prompt` command -- [x] `agent-context` command -- [x] `agent-context-raw` command -- [x] `token-budget` command -- [x] `agents` command -- [x] `agents-create` command -- [x] `agents-update` command -- [x] `agents-delete` command -- [x] Local background session mode -- [x] Local background session listing (`agent-ps`) -- [x] Local background session logs (`agent-logs`) -- [x] Local background attach snapshot (`agent-attach`) -- [x] Local background kill flow (`agent-kill`) -- [x] Local daemon-style background command family (`daemon start/ps/logs/attach/kill`) -- [x] Local daemon worker command path (`daemon worker`) -- [x] Local remote runtime CLI modes (`remote-mode`, `ssh-mode`, `teleport-mode`, `direct-connect-mode`, `deep-link-mode`) -- [x] Local remote runtime inspection commands (`remote-status`, `remote-profiles`, `remote-disconnect`) -- [x] Local account runtime inspection commands (`account-status`, `account-profiles`, `account-login`, `account-logout`) -- [x] Local search runtime inspection commands (`search-status`, `search-providers`, `search-activate`, `search`) -- [x] Local LSP runtime inspection commands (`lsp-status`, `lsp-symbols`, `lsp-workspace-symbols`, `lsp-definition`, `lsp-references`, `lsp-hover`, `lsp-diagnostics`, `lsp-call-hierarchy`, `lsp-incoming-calls`, `lsp-outgoing-calls`) -- [x] Local MCP runtime inspection commands (`mcp-status`, `mcp-resources`, `mcp-resource`, `mcp-tools`, `mcp-call-tool`) -- [x] Inventory/helper commands such as `summary`, `manifest`, `commands`, and `tools` - -Missing: - -- [ ] Full daemon supervisor parity beyond the current local daemon wrapper and worker flow -- [ ] Remote-control / bridge runtime mode (`src/bridge/` — 30+ files: bridgeMain, bridgeApi, bridgeConfig, bridgeMessaging, bridgePermissionCallbacks, replBridge, sessionRunner, trustedDevice, etc.) -- [ ] Browser/native-host runtime mode -- [ ] Computer-use MCP mode (`src/entrypoints/mcp.ts`) -- [ ] Template job mode -- [ ] Environment runner mode -- [ ] Self-hosted runner mode -- [ ] tmux fast paths -- [ ] Worktree fast paths at the CLI entrypoint level -- [x] Python (Node.js equivalent) version check and platform detection from `setup.ts` -- [ ] Worktree creation/setup from `setup.ts` -- [ ] Terminal backup/restore from `setup.ts` -- [x] Release notes checking from `setup.ts` (local CHANGELOG.md, no network/cache layer) -- [ ] Full `entrypoints/cli.tsx` parity (version flag, feature flags, env setup, dynamic imports) -- [ ] Full `entrypoints/init.ts` parity (settings validation, OAuth, policy limits, telemetry, cleanup handlers) -- [ ] SDK entrypoint (`entrypoints/sdk/` — controlTypes, coreTypes, runtimeTypes, settingsTypes, toolTypes) — partial: HOOK_EVENTS, EXIT_REASONS, ModelUsage, ThinkingConfig, MCP server configs, JsonSchemaOutputFormat ported in `src/sdk_core_types.py` -- [x] Sandbox types/network config schema (`entrypoints/sandboxTypes.ts`) - -## 3. Prompt Assembly - -Done: - -- [x] Structured Python system prompt builder -- [x] Intro/system/task/tool/tone/output sections -- [x] Session-specific prompt guidance -- [x] Environment-aware prompt sections -- [x] User context reminder injection -- [x] Custom system prompt override and append support -- [x] Local hook/policy guidance section in the Python system prompt -- [x] Local MCP guidance section in the Python system prompt -- [x] MCP transport/tool guidance section in the Python system prompt -- [x] Local remote-runtime guidance section in the Python system prompt -- [x] Local search-runtime guidance section in the Python system prompt -- [x] Local account-runtime guidance section in the Python system prompt -- [x] Local planning guidance section in the Python system prompt -- [x] Local task guidance section in the Python system prompt -- [x] Local LSP guidance section in the Python system prompt -- [x] Local agent-configuration guidance section in the Python system prompt - -- [x] Product metadata/branding from `constants/product.ts` — ported to `src/prompt_constants.py` -- [x] API limits constants from `constants/apiLimits.ts` — ported to `src/prompt_constants.py` -- [x] Tool limits constants from `constants/toolLimits.ts` — ported to `src/prompt_constants.py` -- [x] Spinner verbs from `constants/spinnerVerbs.ts` (187 verbs) — ported to `src/prompt_constants.py` -- [x] Turn-completion verbs from `constants/turnCompletionVerbs.ts` (8 verbs) — ported to `src/prompt_constants.py` -- [x] Figures/UI symbols from `constants/figures.ts` — ported to `src/prompt_constants.py` -- [x] XML tag constants from `constants/xml.ts` — ported to `src/prompt_constants.py` -- [x] Message constants from `constants/messages.ts` — ported to `src/prompt_constants.py` -- [x] Date utilities from `constants/common.ts` — ported to `src/prompt_constants.py` -- [x] System prompt section caching from `constants/systemPromptSections.ts` — ported to `src/prompt_constants.py` -- [x] Output-style variants from `constants/outputStyles.ts` — ported to `src/prompt_constants.py` -- [x] Cyber / risk instruction from `constants/cyberRiskInstruction.ts` — ported to `src/prompt_constants.py` -- [x] System prompt prefixes from `constants/system.ts` — ported to `src/prompt_constants.py` -- [x] Knowledge cutoff / model family info from `constants/prompts.ts` — ported to `src/prompt_constants.py` -- [x] Hook instruction section template — ported to `src/prompt_constants.py` -- [x] System reminders section — ported to `src/prompt_constants.py` -- [x] Summarize tool results section — ported to `src/prompt_constants.py` -- [x] Language-control section helper — ported to `src/prompt_constants.py` -- [x] Scratchpad prompt instructions helper — ported to `src/prompt_constants.py` -- [x] Default agent prompt — ported to `src/prompt_constants.py` - -Missing: - -- [ ] Full parity with `constants/prompts.ts` runtime section assembly (many sections already exist in agent_prompting.py) -- [ ] MCP instruction sections (runtime MCP integration) -- [ ] Model-family-specific prompt variations (runtime) -- [ ] More exact autonomous/proactive behavior sections -- [ ] Growthbook / feature-gated prompt sections (N/A for external builds) - -## 4. Context Building And Memory - -Done: - -- [x] Current working directory snapshot -- [x] Shell / platform / date capture -- [x] Git status snapshot -- [x] `CLAUDE.md` discovery -- [x] Extra directory injection through `--add-dir` -- [x] Session context usage report -- [x] Tokenizer-aware context accounting with cached model-specific backends and heuristic fallback -- [x] Raw context inspection command -- [x] Plugin cache snapshot injection -- [x] Manifest-based plugin runtime summary injection -- [x] Manifest-based hook/policy summary injection -- [x] Trust-mode, managed-settings, and safe-env context injection -- [x] Manifest-based MCP runtime summary injection -- [x] Manifest-based MCP transport server summary injection -- [x] Manifest-based remote runtime summary injection -- [x] Manifest/env-based search runtime summary injection -- [x] Manifest-based account runtime summary injection -- [x] Local LSP runtime summary injection -- [x] Manifest-based plan runtime summary injection -- [x] Manifest-based task runtime summary injection - -Missing: - -- [ ] Full tokenizer/chat-message framing parity beyond the current model-aware text token counters -- [ ] Full parity with `utils/queryContext.ts` (context analysis, suggestions, cache shaping) -- [x] Session memory compact (`services/SessionMemory/` partial) → `src/session_memory_compact.py` — remaining: background LLM extraction, full template handling -- [ ] Internal permission-aware memory handling -- [ ] Resume-aware prompt cache shaping used upstream -- [ ] More exact context cache invalidation rules -- [ ] Session context analysis parity (`utils/contextAnalysis.ts`, `utils/contextSuggestions.ts`) -- [ ] Full memory subsystem parity (`utils/memory/`, `services/extractMemories/`) -- [ ] Memory extraction from conversations (`services/extractMemories/extractMemories.ts`) -- [ ] Team memory sync (`services/teamMemorySync/`) -- [ ] Away summary generation (`services/awaySummary.ts`) -- [ ] Token estimation service (`services/tokenEstimation.ts`) -- [ ] Paste content storage and reference parsing (`history.ts`) -- [ ] Image paste handling - -## 5. Slash Commands - -Done (53 slash command names in 37 specs): - -- [x] `/help`, `/commands` -- [x] `/context`, `/usage` -- [x] `/context-raw`, `/env` -- [x] `/token-budget`, `/budget` -- [x] `/mcp` (with subcommands: `tools`, `tool `) -- [x] `/search` (with subcommands: `providers`, `provider`, `use`) -- [x] `/remote` (with `enter`, `exit`) -- [x] `/worktree` (with `enter`, `exit`) -- [x] `/account` (with `profiles`, `profile`) -- [x] `/ask` (with `history`) -- [x] `/login` -- [x] `/logout` -- [x] `/config`, `/settings` (with `effective`, `source`, `get`, `set`) -- [x] `/remotes` -- [x] `/ssh` -- [x] `/teleport` -- [x] `/direct-connect` -- [x] `/deep-link` -- [x] `/disconnect`, `/remote-disconnect` -- [x] `/resources` -- [x] `/resource` -- [x] `/tasks`, `/todo` -- [x] `/workflows`, `/workflow` -- [x] `/triggers`, `/trigger` -- [x] `/teams`, `/team`, `/messages` -- [x] `/task-next`, `/next-task` -- [x] `/plan`, `/planner` -- [x] `/task` -- [x] `/prompt`, `/system-prompt` -- [x] `/permissions` -- [x] `/hooks`, `/policy` -- [x] `/trust` -- [x] `/model` -- [x] `/tools` -- [x] `/memory` -- [x] `/status`, `/session` -- [x] `/clear` - -Missing npm slash commands (from `src/commands/` — 80+ commands total): - -- [x] `/add-dir` — Add a new working directory -- [x] `/agents` — Inspect, create, update, and delete local agent definitions -- [x] `/branch` — Create a branch of the current conversation -- [x] `/bridge` — Connect for remote-control sessions (read-only status in this runtime) -- [x] `/btw` — Quick side question without interrupting main conversation -- [x] `/chrome` — Chrome extension settings -- [x] `/color` — Set the prompt bar color for this session -- [x] `/compact` — Clear history but keep a summary in context -- [x] `/copy` — Copy Claude's last response to clipboard -- [x] `/cost` — Show total cost and duration of session -- [x] `/desktop` — Continue session in Claude Desktop -- [x] `/diff` — View uncommitted changes and per-turn diffs -- [x] `/doctor` — Diagnose and verify installation and settings -- [x] `/effort` — Set effort level for model usage -- [x] `/exit` — Exit the REPL -- [x] `/export` — Export conversation to file or clipboard -- [x] `/extra-usage` — Configure extra usage for rate limits -- [x] `/fast` — Toggle fast mode -- [x] `/feedback` — Submit feedback (alias `/bug`) -- [x] `/files` — List all files currently in context -- [x] `/ide` — Manage IDE integrations and show status -- [x] `/install-github-app` — Set up GitHub Actions -- [x] `/install-slack-app` — Install Slack app -- [x] `/keybindings` — Open keybindings config file -- [x] `/mobile` — Mobile app store links (aliases `/ios`, `/android`) -- [x] `/output-style` — Deprecation pointer to `/config` -- [x] `/passes` — Passes management -- [x] `/plugin` — Plugin management (read-only listing) -- [x] `/pr-comments`, `/pr_comments` — Get comments from a GitHub PR (prompt-type) -- [x] `/privacy-settings` — View/update privacy settings -- [x] `/rate-limit-options` — Show options when rate limited -- [x] `/release-notes` — View release notes -- [x] `/reload-plugins` — Activate pending plugin changes -- [x] `/remote-env` — Configure default remote environment -- [x] `/remote-setup` — Remote setup configuration (gh auth status + Claude.ai/code link) -- [x] `/rename` — Rename current conversation -- [x] `/resume`, `/continue` — Resume a previous conversation -- [x] `/rewind`, `/checkpoint` — Restore code/conversation to a previous point -- [x] `/sandbox-toggle` — Toggle sandbox mode (alias `/sandbox`) -- [x] `/skills` — List available bundled skills (mirrors `commands/skills/SkillsMenu.tsx`; lists `bundled_skills.BUNDLED_SKILLS`, not slash commands) -- [x] `/stats` — Usage statistics and activity -- [x] `/stickers` — Order stickers -- [x] `/tag` — Toggle a searchable tag on the session -- [x] `/theme` — Change the theme -- [x] `/upgrade` — Upgrade to Max -- [x] `/vim` — Toggle Vim/Normal editing modes -- [x] `/voice` — Toggle voice mode -- [ ] Feature-gated: `/buddy`, `/fork`, `/peers`, `/proactive`, `/torch`, `/workflows` (full), etc. -- [ ] Internal: `/backfill-sessions`, `/break-cache`, `/bughunter`, `/commit-push-pr`, `/init-verifiers`, `/mock-limits`, `/version`, `/ultraplan`, `/autofix-pr`, etc. -- [x] `/commit` — Create a git commit (prompt-type with injected git context) -- [ ] Full `/agents` parity for interactive TUI/editor flows, plugin sources, and full multi-source management UX - -## 6. Built-in Tools - -### Tools implemented in Python (65 tools): - -- [x] `list_dir` -- [x] `read_file` -- [x] `write_file` -- [x] `edit_file` -- [x] `notebook_edit` -- [x] `glob_search` -- [x] `grep_search` -- [x] `bash` -- [x] `web_fetch` -- [x] `search_status` -- [x] `search_list_providers` -- [x] `search_activate_provider` -- [x] `web_search` -- [x] `LSP` -- [x] `tool_search` -- [x] `sleep` -- [x] `ask_user_question` -- [x] `account_status` -- [x] `account_list_profiles` -- [x] `account_login` -- [x] `account_logout` -- [x] `config_list` -- [x] `config_get` -- [x] `config_set` -- [x] `mcp_list_resources` -- [x] `mcp_read_resource` -- [x] `mcp_list_tools` -- [x] `mcp_call_tool` -- [x] `remote_status` -- [x] `remote_list_profiles` -- [x] `remote_connect` -- [x] `remote_disconnect` -- [x] `worktree_status` -- [x] `worktree_enter` -- [x] `worktree_exit` -- [x] `workflow_list` -- [x] `workflow_get` -- [x] `workflow_run` -- [x] `remote_trigger` -- [x] `plan_get` -- [x] `update_plan` -- [x] `plan_clear` -- [x] `task_next` -- [x] `task_list` -- [x] `task_get` -- [x] `task_create` -- [x] `task_update` -- [x] `task_start` -- [x] `task_complete` -- [x] `task_block` -- [x] `task_cancel` -- [x] `todo_write` -- [x] `delegate_agent` -- [x] `team_list` -- [x] `team_get` -- [x] `team_create` -- [x] `team_delete` -- [x] `send_message` -- [x] `team_messages` -- [x] `EnterPlanMode` -- [x] `ExitPlanMode` -- [x] `TaskOutput` -- [x] `TaskStop` - -### Tools in npm `tools.ts` not yet ported with full fidelity (40 tool dirs): - -Core tools needing full port: -- [x] `AgentTool` — Sub-agent spawning with built-in agents (explore, general-purpose, verification, plan, claudeCodeGuide, statusline) → `src/builtin_agents.py` — remaining: fork support, agent memory/snapshots, resume agent, color management -- [x] `SkillTool` — Skill execution via slash commands and bundled skills → `src/agent_tools.py`, `src/agent_runtime.py`, `src/bundled_skills.py` — remaining: forked skill execution -- [ ] `BriefTool` — Brief mode with attachments and file upload -- [ ] `LSPTool` — Full upstream LSP fidelity beyond the current local heuristic runtime (server-backed diagnostics, go-to-definition, references, hover, symbol search, formatting) -- [ ] `PowerShellTool` — Full PowerShell execution with security, path validation, CLM types, git safety -- [ ] `REPLTool` — Interactive REPL with primitive tools (ant-only) -- [ ] `MCPTool` — Full MCP tool execution with collapse classification -- [ ] `McpAuthTool` — MCP authentication handling -- [ ] `ConfigTool` — Full config management with supported settings list -- [ ] `SyntheticOutputTool` — Synthetic output injection -- [x] `EnterPlanModeTool` — Enter plan mode → `src/agent_tools.py` -- [x] `ExitPlanModeTool` — Exit plan mode → `src/agent_tools.py` -- [ ] `EnterWorktreeTool` — Full worktree enter with UI -- [ ] `ExitWorktreeTool` — Full worktree exit with UI -- [x] `TaskOutputTool` — Task output display → `src/agent_tools.py` -- [x] `TaskStopTool` — Stop a running task → `src/agent_tools.py` - -Feature-gated tools: -- [ ] `CronCreateTool` / `CronDeleteTool` / `CronListTool` — Cron scheduling (AGENT_TRIGGERS) -- [ ] `RemoteTriggerTool` — Full remote triggers with UI (AGENT_TRIGGERS_REMOTE) -- [ ] `MonitorTool` — MCP server monitoring (MONITOR_TOOL) -- [ ] `SendUserFileTool` — Send file to user (KAIROS) -- [ ] `PushNotificationTool` — Push notifications (KAIROS) -- [ ] `SubscribePRTool` — PR subscription (KAIROS_GITHUB_WEBHOOKS) -- [ ] `SuggestBackgroundPRTool` — Background PR (ant-only) -- [ ] `VerifyPlanExecutionTool` — Plan verification -- [ ] `TungstenTool` — Tungsten tool -- [ ] `WebBrowserTool` — Full web browser -- [ ] `TerminalCaptureTool` — Terminal capture -- [ ] `SnipTool` — Force history snipping -- [ ] `ListPeersTool` — List peers (UDS_INBOX) -- [ ] `EmbeddedSearchTool` — Embedded search -- [ ] `CtxInspectTool` — Context inspection -- [ ] `WorkflowTool` — Workflow scripts (WORKFLOW_SCRIPTS) - -Note: Python has basic tool execution for `bash`, `read_file`, etc., but lacks per-tool UI components, prompt files, constants, and deep security validations (e.g., BashTool has 15 supporting files in npm). - -## 7. Commands And Task Systems - -Done: - -- [x] Basic local command dispatch for the Python runtime -- [x] Inventory view of mirrored command names -- [x] Local persistent task runtime with create/get/list/update flows -- [x] Local todo-list replacement flow -- [x] Local persistent plan runtime with get/update/clear flows -- [x] Local plan-to-task sync flow -- [x] Local dependency-aware task execution flow with next-task selection and blocked/unblocked state -- [x] Local remote profile/runtime flow with persisted connect/disconnect state -- [x] Local background task management for agent worker sessions -- [x] Local ask-user runtime with queued answers, history, and slash/CLI inspection flows -- [x] Local team runtime with persisted teams, messages, and slash/CLI inspection flows -- [x] Local workflow runtime with manifest discovery, run history, and workflow CLI/slash flows -- [x] Local remote trigger runtime with create/update/run flows and trigger CLI/slash flows -- [x] Local managed git worktree runtime with session cwd switching and worktree CLI/slash flows - -Missing: - -- [ ] Real implementation of the larger upstream command tree (80+ commands) -- [ ] Task types: `LocalShellTask`, `LocalAgentTask`, `RemoteAgentTask`, `DreamTask`, `LocalWorkflowTask`, `MonitorMcpTask`, `InProcessTeammateTask` -- [ ] Task stall detection (45s threshold) and prompt detection for interactive input -- [ ] Remote agent task session URL tracking and completion checkers -- [ ] Dream/auto-consolidation task with file tracking and turn history -- [ ] Task orchestration system beyond the current local dependency-aware task runtime -- [ ] Planner / task execution parity beyond the current local plan persistence, sync, and next-task flow -- [ ] Team / collaboration command flows beyond the current local team runtime and message recording flows -- [ ] Command-specific session behaviors -- [ ] Full `src/commands/*` parity (80+ command directories) -- [ ] Full `src/tasks/*` parity (7 task types) - -## 8. Permissions, Hooks, And Policy - -Done: - -- [x] Read-only default mode -- [x] Write-gated mode -- [x] Shell-gated mode -- [x] Unsafe mode for destructive shell actions -- [x] Local hook/policy manifest discovery -- [x] Hook before-prompt and after-turn runtime handling -- [x] Hook/policy tool preflight, deny, and after-tool handling -- [x] Policy budget override loading -- [x] Managed settings loading and reporting -- [x] Safe environment loading for shell tool context -- [x] Trust reporting and hook/policy slash commands -- [x] Permission-denial runtime events for policy/tool blocks - -Missing: - -- [x] Full BashTool security: `bashSecurity.ts`, `sedValidation.ts`, `sedEditParser.ts`, `pathValidation.ts`, `readOnlyValidation.ts`, `modeValidation.ts`, `commandSemantics.ts`, `destructiveCommandWarning.ts`, `shouldUseSandbox.ts` → `src/bash_security.py` (18 validators, destructive warnings, command semantics, read-only detection, 163 tests) -- [ ] Full PowerShellTool security: `powershellSecurity.ts`, `gitSafety.ts`, `clmTypes.ts` -- [ ] Tool-permission workflow parity (`bashPermissions.ts`, `powershellPermissions.ts`) -- [ ] Trust-gated initialization -- [ ] Hook-config management (`schemas/hooks.ts` with Zod schemas) -- [ ] Policy limits service (`services/policyLimits/`) -- [ ] Remote managed settings (`services/remoteManagedSettings/`) -- [ ] Full hooks and policy parity - -## 9. MCP, Plugins, And Skills - -Done: - -- [x] Placeholder mirrored package layout for plugins, skills, services, and remote subsystems -- [x] Local manifest-backed MCP discovery -- [x] Local MCP resource listing and reading -- [x] MCP-backed runtime tools for local resource access -- [x] Real MCP client support over local stdio transport -- [x] MCP server integration for stdio child-process servers -- [x] MCP-backed tool listing and execution over transport - -Missing: - -- [ ] Full MCP service (`services/mcp/` — 25+ files: InProcessTransport, MCPConnectionManager, SdkControlTransport, auth, channelAllowlist, channelPermissions, client, config, elicitationHandler, envExpansion, normalization, oauthPort, officialRegistry, vscodeSdkMcp, xaa, xaaIdpLogin, etc.) -- [ ] MCP server approval dialogs (`services/mcpServerApproval.tsx`) -- [ ] Plugin discovery, loading, and installation (`services/plugins/PluginInstallationManager.ts`, `pluginCliCommands.ts`, `pluginOperations.ts`) -- [ ] Bundled plugin support (`plugins/bundledPlugins.ts`, `plugins/bundled/`) -- [ ] Plugin lifecycle management -- [ ] Plugin update/cache behavior -- [x] Skill discovery and execution → `src/bundled_skills.py` (simplify, verify, debug, update-config) — remaining: loadSkillsDir, mcpSkillBuilders, disk-based SKILL.md loading -- [x] Bundled skill support → `src/bundled_skills.py` — remaining: skillify, batch, loop, schedule, claude-api, chrome, and feature-gated skills -- [ ] Full plugin and skill parity - -## 10. Interactive UI / REPL / TUI - -Done: - -- [x] Non-interactive CLI execution -- [x] Basic interactive REPL-style agent chat loop -- [x] Transcript printing for debugging - -Missing: - -- [ ] Interactive REPL parity (`screens/REPL.tsx`) -- [ ] Ink/TUI framework (`ink/` — 40+ files: custom renderer, reconciler, DOM, layout engine, text wrapping, ANSI handling, focus management, selection) -- [ ] Screen system (`screens/Doctor.tsx`, `screens/ResumeConversation.tsx`) -- [ ] Component library (`components/` — 100+ components in 12+ subdirectories): - - Message rendering: Message, MessageRow, Messages, MessageSelector, MessageResponse - - Dialogs: ApproveApiKey, AutoModeOptIn, Bridge, CostThreshold, IdeAutoConnect, MCPServerApproval - - Settings: ThemePicker, LanguagePicker, ModelPicker, OutputStylePicker - - Search: GlobalSearchDialog, QuickOpenDialog, HistorySearchDialog - - Status: AgentProgressLine, BashModeProgress, MemoryUsageIndicator, TokenWarning - - Design system, agent, team, task, skill, memory, permissions, sandbox, shell components -- [ ] Keyboard interaction parity -- [ ] Interactive status panes -- [ ] Approval UI flows -- [ ] Rich incremental rendering -- [ ] Virtual scrolling -- [ ] Copy-on-select behavior - -## 11. Remote, Background, And Team Features - -Done: - -- [x] Session save/resume on local disk -- [x] Local manifest-backed remote profile/runtime state -- [x] Local remote connect/disconnect session state -- [x] Local background agent processes -- [x] Local background attach/log/kill workflows -- [x] Local daemon-style wrapper over background agent sessions - -Missing: - -- [ ] Real remote session management (`remote/` — 4 files: RemoteSessionManager, SessionsWebSocket, remotePermissionBridge, sdkMessageAdapter) -- [ ] Bridge subsystem (`bridge/` — 30+ files: bridgeMain, bridgeApi, bridgeConfig, bridgeMessaging, bridgePermissionCallbacks, replBridge, replBridgeHandle, replBridgeTransport, sessionRunner, trustedDevice, jwtUtils, capacityWake, inboundAttachments, inboundMessages, etc.) -- [ ] Direct connect subsystem (`server/createDirectConnectSession.ts`, `directConnectManager.ts`) -- [ ] Real team collaboration beyond local recording -- [ ] Shared remote state -- [ ] Upstream proxy (`upstreamproxy/upstreamproxy.ts`, `upstreamproxy/relay.ts`) - -## 12. Editor, Platform, And Native Integrations - -Done: - -- [x] Standard shell-based local workflow - -Missing: - -- [ ] Voice mode (`voice/`, `services/voice.ts`, `services/voiceKeyterms.ts`, `services/voiceStreamSTT.ts`, hooks) -- [ ] VIM mode (`vim/` — 5 files: motions, operators, textObjects, transitions, types) -- [ ] Keybinding system (`keybindings/` — 13 files: defaultBindings, loadUserBindings, match, parser, resolver, schema, template, validate, etc.) -- [ ] Notification hooks (`services/notifier.ts`, `services/preventSleep.ts`) -- [ ] Native TypeScript / platform helpers (`native-ts/`) -- [ ] JetBrains/editor integration (`utils/jetbrains.ts`, `utils/ide.ts`, `utils/idePathConversion.ts`) -- [ ] Browser/native host integrations -- [ ] IDE integration hooks (useIDEIntegration, useIdeAtMentioned, useIdeSelection, useIdeLogging, useDiffInIDE, useLspPluginRecommendation) -- [ ] Platform-specific startup/shutdown logic -- [ ] Chrome extension integration - -## 13. Services And Internal Subsystems - -Done: - -- [x] Minimal internal service layer required by the current Python runtime -- [x] Local account/auth runtime for manifest-backed profile discovery and persisted login state - -Missing: - -- [ ] Analytics service (`services/analytics/` — 10+ files: config, Datadog, Growthbook, first-party event logger, sink, killswitch) -- [ ] API service (`services/api/` — 20+ files: claude client, dumpPrompts, errorUtils, filesApi, firstTokenDate, grove, logging, metricsOptOut, promptCacheBreakDetection, sessionIngress, usage, withRetry, etc.) -- [ ] LSP service (`services/lsp/` — 7 files: LSPClient, LSPDiagnosticRegistry, LSPServerInstance, LSPServerManager, config, manager, passiveFeedback) -- [ ] Tools service (`services/tools/` — 4 files: StreamingToolExecutor, toolExecution, toolHooks, toolOrchestration) -- [ ] Compact service (`services/compact/` — 6 files) — partially ported: compact → `src/compact.py`, microCompact → `src/microcompact.py`, sessionMemoryCompact → `src/session_memory_compact.py`; remaining: autoCompact trigger, apiMicrocompact, compactWarningHook -- [ ] Auto-dream service (`services/autoDream/` — 4 files: autoDream, config, consolidationLock, consolidationPrompt) -- [ ] Agent summary service (`services/AgentSummary/`) -- [ ] Magic docs service (`services/MagicDocs/`) -- [ ] Session memory service (`services/SessionMemory/`) -- [ ] Prompt suggestion service (`services/PromptSuggestion/`) -- [ ] Extract memories service (`services/extractMemories/`) -- [ ] Diagnostic tracking service (`services/diagnosticTracking.ts`) -- [ ] OAuth service (`services/oauth/` — 5 files) -- [ ] Rate limiting (`services/claudeAiLimits.ts`, `services/rateLimitMessages.ts`, etc.) -- [ ] Settings sync (`services/settingsSync/`) -- [ ] Tips service (`services/tips/`) -- [ ] Tool use summary service (`services/toolUseSummary/`) -- [ ] VCR playback (`services/vcr.ts`) -- [ ] Internal/container logging (`services/internalLogging.ts`) -- [ ] Plugin installation management (`services/plugins/`) - -## 14. State Management - -Done: - -- [x] Session state via `AgentSessionState` dataclass -- [x] Basic session persistence - -Missing: - -- [ ] Zustand store (`state/AppStateStore.ts`, `state/store.ts`) -- [ ] Store selectors (`state/selectors.ts`) -- [ ] State change callbacks (`state/onChangeAppState.ts`) -- [ ] React context providers (`state/AppState.tsx`) - -## 15. React Hooks (84+ hooks in `src/hooks/`) - -Not applicable for Python (no React TUI), but these represent features needing alternative implementations: - -- [ ] File suggestions and unified suggestions -- [ ] Remote session / SSH / direct connect hooks -- [ ] Input buffer, text input, vim input, typeahead, search input, paste handling -- [ ] Arrow key history, history search, background task navigation -- [ ] Main loop model selection, assistant history, merged clients/commands/tools -- [ ] Tool permission checking, cancel request, manage plugins -- [ ] Global/command keybindings, exit handling, double-press detection -- [ ] Terminal size, virtual scroll, copy-on-select -- [ ] Voice recording, voice integration -- [ ] IDE integration, @mention, selection, diff-in-IDE -- [ ] Settings management, dynamic config -- [ ] Timeout, elapsed time, scheduled tasks, delayed notifications -- [ ] Prompt suggestion, update notification, feature hints -- [ ] Queue processor, command queue -- [ ] Memory usage, away summary, teleport resume -- [ ] Diff data, turn diffs -- [ ] Task list watcher, tasks v2, PR status -- [ ] Session backgrounding, swarm initialization/permission -- [ ] API key verification, mailbox bridge, inbox poller - -## 16. Utilities (200+ files in `src/utils/`) - -Done: - -- [x] Basic file operations in tool implementations -- [x] Basic git status snapshot -- [x] Basic shell/subprocess handling -- [x] Bundled small portable utilities — `utils/array.ts`, `utils/set.ts`, `utils/objectGroupBy.ts`, `utils/xml.ts`, `utils/uuid.ts` ported in `src/small_utils.py` -- [x] Session-scoped env-var registry (`utils/sessionEnvVars.ts`) ported in `src/session_env_vars.py`, merged into spawned subprocess env via `_build_subprocess_env` (mirrors `utils/shell/bashProvider.ts`), and dropped on `/clear` via `clear_runtime_state` (mirrors `commands/clear/caches.ts`) -- [x] Display formatters from `utils/format.ts` (`formatFileSize`, `formatSecondsShort`, `formatDuration`, `formatNumber`, `formatTokens`) ported in `src/format_utils.py` - -Missing major utility categories: - -- [ ] Shell utilities (`utils/bash/`, `utils/shell/`, `Shell.ts`, `ShellCommand.ts`) -- [ ] Git operations (`utils/git.ts`, `utils/gitDiff.ts`, `utils/gitSettings.ts`, `utils/commitAttribution.ts`) — partial: `findGitRoot`, `normalizeGitRemoteUrl`, `getRepoRemoteHash`, and `shouldIncludeGitInstructions` ported in `src/git_utils.py` -- [ ] File operations (`utils/file.ts`, `utils/fileRead.ts`, `utils/fileHistory.ts`, `utils/fileStateCache.ts`, `utils/fsOperations.ts`, `utils/ripgrep.ts`, `utils/glob.ts`) -- [ ] AI/Model utilities (`utils/modelCost.ts`, `utils/model/`, `utils/context.ts`, `utils/queryContext.ts`) — partial: modelCost ported in `src/model_cost.py` -- [ ] Config/Settings (`utils/config.ts`, `utils/settings/`) -- [ ] Message handling (`utils/messages.ts`, `utils/messages/`, `utils/messageQueueManager.ts`) -- [ ] API/Network (`utils/api.ts`, `utils/http.ts`, `utils/proxy.ts`, `utils/auth.ts`) -- [ ] Session management (`utils/sessionStorage.ts`, `utils/sessionState.ts`, `utils/sessionStart.ts`, `utils/sessionRestore.ts`) -- [ ] Plugin/Skill utilities (`utils/plugins/`, `utils/skills/`) -- [ ] Memory/Context (`utils/memory/`, `utils/claudemd.ts`, `utils/contextAnalysis.ts`) -- [ ] IDE integration (`utils/ide.ts`, `utils/jetbrains.ts`) — partial: `utils/idePathConversion.ts` ported in `src/ide_path_conversion.py` (`WindowsToWSLConverter`, `checkWSLDistroMatch`) -- [ ] Platform/OS (`utils/platform.ts`, `utils/terminal.ts`, `utils/systemDirectories.ts`) — partial: platform detection (`getPlatform`, `getWslVersion`, `getLinuxDistroInfo`, `detectVcs`) and `getSystemDirectories` ported in `src/platform_info.py` -- [ ] Debugging (`utils/debug.ts`, `utils/diagLogs.ts`, `utils/log.ts`, `utils/profilerBase.ts`) -- [ ] Telemetry (`utils/telemetry/`) -- [ ] Deep link utilities (`utils/deepLink/`) - -## 17. Coordinator And Buddy - -Missing: - -- [ ] Coordinator mode (`coordinator/coordinatorMode.ts` — agent tool filtering and async agent allowlist) -- [ ] Buddy/companion system (`buddy/` — 6 files: CompanionSprite, companion procedural generation, personality prompts, sprites, types, notification UI) - -## 18. Migrations - -Missing: - -- [ ] Data/config migration system (`migrations/` — 11 migration scripts): - - Model migrations: migrateFennecToOpus, migrateLegacyOpusToCurrent, migrateOpusToOpus1m, migrateSonnet1mToSonnet45, migrateSonnet45ToSonnet46 - - Feature migrations: migrateAutoUpdatesToSettings, migrateBypassPermissionsAcceptedToSettings, migrateEnableAllProjectMcpServersToSettings, migrateReplBridgeEnabledToRemoteControlAtStartup - - Config resets: resetAutoModeOptInForDefaultOffer, resetProToOpusDefault - -## 19. Type Definitions - -Missing: - -- [ ] Full type system from `types/` (command.ts, hooks.ts, ids.ts, logs.ts, permissions.ts, plugin.ts, textInputTypes.ts, generated/) - -## 20. Mirrored Workspace Versus Working Runtime - -Working Python runtime today (21,193 lines across 51 source files, 10,480 lines across 37 test files): - -- [x] `src/main.py` (1,353 lines) -- [x] `src/agent_runtime.py` (4,318 lines) -- [x] `src/agent_tools.py` (3,183 lines) -- [x] `src/agent_prompting.py` (390 lines) -- [x] `src/agent_context.py` (459 lines) -- [x] `src/agent_context_usage.py` (356 lines) -- [x] `src/agent_session.py` (718 lines) -- [x] `src/agent_slash_commands.py` (633 lines) -- [x] `src/agent_manager.py` (296 lines) -- [x] `src/agent_plugin_cache.py` (154 lines) -- [x] `src/agent_types.py` (193 lines) -- [x] `src/account_runtime.py` (470 lines) -- [x] `src/ask_user_runtime.py` (320 lines) -- [x] `src/background_runtime.py` (371 lines) -- [x] `src/config_runtime.py` (296 lines) -- [x] `src/hook_policy.py` (339 lines) -- [x] `src/mcp_runtime.py` (880 lines) -- [x] `src/openai_compat.py` (413 lines) -- [x] `src/permissions.py` (20 lines) -- [x] `src/plan_runtime.py` (396 lines) -- [x] `src/plugin_runtime.py` (654 lines) -- [x] `src/query_engine.py` (655 lines) -- [x] `src/remote_runtime.py` (571 lines) -- [x] `src/remote_trigger_runtime.py` (371 lines) -- [x] `src/search_runtime.py` (606 lines) -- [x] `src/session_store.py` (295 lines) -- [x] `src/task.py` (130 lines) -- [x] `src/task_runtime.py` (595 lines) -- [x] `src/team_runtime.py` (386 lines) -- [x] `src/tokenizer_runtime.py` (202 lines) -- [x] `src/workflow_runtime.py` (319 lines) -- [x] `src/worktree_runtime.py` (448 lines) -- [x] `src/builtin_agents.py` (426 lines) -- [x] `src/microcompact.py` (236 lines) -- [x] Plus 19 supporting modules - -Mirrored / scaffold areas needing real implementation: - -- [ ] `src/commands.py` — currently minimal dispatch, needs full command tree -- [ ] `src/tools.py` — reference-data based tool loading, needs real per-tool implementations -- [ ] `src/query_engine.py` — facade layer, needs full QueryEngine.ts parity -- [ ] `src/runtime.py` — routing layer, needs full runtime parity -- [ ] Remaining inventory surfaces under `src/reference_data/*` - ---- - -## High-Priority Next Steps - -### Tier 1 — Core Feature Gaps (highest user impact) -- [x] Full BashTool security parity (sed validation, path validation, sandbox, destructive command warnings, command semantics) → `src/bash_security.py` -- [x] LSP tool integration for code intelligence -- [x] Full AgentTool with built-in agent types (explore, general-purpose, verification, plan, statusline-setup, claude-code-guide) → `src/builtin_agents.py`, `src/agent_tools.py`, `src/agent_runtime.py` -- [ ] Auto-compact and context collapse from `query.ts` -- [x] Microcompact service (time-based tool-result clearing) → `src/microcompact.py` -- [x] Compact PTL retry loop and circuit-breaker tracking → `src/compact.py` -- [ ] Full compact service (sessionMemoryCompact, cached microcompact) -- [ ] Interactive REPL improvements - -### Tier 2 — Important Feature Gaps -- [x] SkillTool for slash command execution → `src/agent_tools.py`, `src/agent_runtime.py` -- [ ] Full MCP service parity (auth, permissions, config, registry) -- [ ] Plugin discovery, loading, and installation -- [ ] Real remote session management (WebSocket, bridge) -- [ ] Full command tree implementation (80+ commands) -- [ ] Migration system for config/model upgrades -- [ ] Token budget calculations - -### Tier 3 — Nice-to-Have Features -- [x] Local web GUI (FastAPI + vanilla JS SPA) → `src/gui/__main__.py`, `backend/api/server.py`, `frontend/legacy-static/*`; launch with `python -m src.gui` or `claw-code-gui` -- [ ] TUI/Ink component library -- [ ] Voice mode -- [ ] VIM mode and keybinding system -- [ ] IDE integrations (JetBrains, VS Code) -- [ ] Chrome extension integration -- [ ] Buddy/companion system -- [ ] Analytics/telemetry -- [ ] Coordinator mode -- [ ] Feature flag system (Growthbook) - -### Tier 4 — Platform/Enterprise Features -- [ ] Full bridge subsystem (30+ files) -- [ ] Upstream proxy -- [ ] Direct connect server -- [ ] OAuth service -- [ ] Settings sync -- [ ] Rate limiting and policy limits -- [ ] Dream/auto-consolidation service diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md deleted file mode 100644 index 575f20a..0000000 --- a/TESTING_GUIDE.md +++ /dev/null @@ -1,1879 +0,0 @@ -# Testing Guide - -This guide is the user-facing test checklist for the current Python implementation. - -It is organized by runtime surface, not by source file. Every implemented feature should have at least one concrete command here. - -All commands below assume you are inside the repository root: - -```bash -cd /path/to/claw-code-agent -``` - -## 1. Backend Setup - -### 1.1 `vLLM` with Qwen3-Coder - -```bash -python -m vllm.entrypoints.openai.api_server \ - --model Qwen/Qwen3-Coder-30B-A3B-Instruct \ - --host 127.0.0.1 \ - --port 8000 \ - --enable-auto-tool-choice \ - --tool-call-parser qwen3_xml -``` - -Verify the server: - -```bash -curl http://127.0.0.1:8000/v1/models -``` - -### 1.2 `Ollama` - -```bash -ollama serve -ollama pull qwen3 -``` - -### 1.3 `LiteLLM Proxy` - -```bash -pip install "litellm[proxy]" -litellm --model ollama/qwen3 -``` - -### 1.4 Runtime environment variables - -Use one backend at a time. - -For `vLLM`: - -```bash -export OPENAI_BASE_URL=http://127.0.0.1:8000/v1 -export OPENAI_API_KEY=local-token -export OPENAI_MODEL=Qwen/Qwen3-Coder-30B-A3B-Instruct -``` - -For `Ollama`: - -```bash -export OPENAI_BASE_URL=http://127.0.0.1:11434/v1 -export OPENAI_API_KEY=ollama -export OPENAI_MODEL=qwen3 -``` - -For `LiteLLM Proxy`: - -```bash -export OPENAI_BASE_URL=http://127.0.0.1:4000 -export OPENAI_API_KEY=anything -export OPENAI_MODEL=ollama/qwen3 -``` - -If your cluster wraps `python3`, use an explicit interpreter path such as `/usr/bin/python3.9 -m ...` for the commands below. - -### 1.5 Run the full unit test suite - -```bash -python3 -m unittest discover -s tests -v -``` - -### 1.6 Run focused runtime suites - -```bash -python3 -m unittest tests.test_agent_runtime -v -python3 -m unittest tests.test_query_engine_runtime -v -python3 -m unittest tests.test_mcp_runtime -v -python3 -m unittest tests.test_search_runtime -v -python3 -m unittest tests.test_task_runtime -v -python3 -m unittest tests.test_plan_runtime -v -python3 -m unittest tests.test_background_runtime -v -python3 -m unittest tests.test_remote_runtime -v -python3 -m unittest tests.test_config_runtime -v -python3 -m unittest tests.test_lsp_runtime -v -python3 -m unittest tests.test_account_runtime -v -python3 -m unittest tests.test_ask_user_runtime -v -python3 -m unittest tests.test_team_runtime -v -python3 -m unittest tests.test_tokenizer_runtime -v -python3 -m unittest tests.test_extended_tools -v -python3 -m unittest tests.test_porting_workspace -v -``` - -## 2. Installation And CLI Help - -### 2.1 Editable install - -```bash -pip install -e . -``` - -### 2.2 Main help - -```bash -python3 -m src.main --help -python3 -m src.main agent --help -python3 -m src.main agent-chat --help -python3 -m src.main agent-resume --help -python3 -m src.main agent-bg --help -python3 -m src.main daemon --help -``` - -### 2.3 Packaged entrypoint - -```bash -claw-code-agent agent "/help" -``` - -## 3. Mirrored Workspace And Inventory Commands - -These commands do not depend on the live model backend. - -### 3.1 Summary and audit commands - -```bash -python3 -m src.main summary -python3 -m src.main manifest -python3 -m src.main parity-audit -python3 -m src.main setup-report -python3 -m src.main command-graph -python3 -m src.main tool-pool -python3 -m src.main bootstrap-graph -``` - -### 3.2 Inventory indexes - -```bash -python3 -m src.main subsystems --limit 20 -python3 -m src.main commands --limit 10 --query review -python3 -m src.main commands --limit 10 --no-plugin-commands -python3 -m src.main commands --limit 10 --no-skill-commands -python3 -m src.main tools --limit 10 --query MCP -python3 -m src.main tools --limit 10 --simple-mode -python3 -m src.main tools --limit 10 --no-mcp -python3 -m src.main tools --limit 10 --deny-prefix mcp -python3 -m src.main tools --limit 10 --deny-tool BashTool -``` - -### 3.3 Show exact mirrored entries - -```bash -python3 -m src.main show-command review -python3 -m src.main show-tool MCPTool -``` - -### 3.4 Route and bootstrap reports - -```bash -python3 -m src.main route "review MCP tool" --limit 5 -python3 -m src.main bootstrap "review MCP tool" --limit 5 -python3 -m src.main turn-loop "review MCP tool" --limit 5 --max-turns 2 -python3 -m src.main turn-loop "review MCP tool" --limit 5 --max-turns 2 --structured-output -``` - -### 3.5 Mirrored execution shims - -```bash -python3 -m src.main exec-command review "inspect security review" -python3 -m src.main exec-tool MCPTool "fetch resource list" -``` - -### 3.6 Flush and load mirrored sessions - -```bash -python3 -m src.main flush-transcript "temporary mirrored transcript" -python3 -m src.main load-session -``` - -## 4. Prepare Local Test Workspaces - -Create reusable workspaces: - -```bash -mkdir -p ./test_cases/.claude -mkdir -p ./test_cases_policy -mkdir -p ./test_cases_budget -mkdir -p ./test_cases_plugins/plugins/demo -mkdir -p ./test_cases_mcp -mkdir -p ./test_cases_tasks -mkdir -p ./test_cases_notebooks -``` - -### 4.1 Config fixtures - -```bash -cat > ./test_cases/.claude/settings.json <<'EOF' -{ - "model": { - "name": "project-model", - "temperature": 0.1 - }, - "review": { - "strict": false - } -} -EOF - -cat > ./test_cases/.claude/settings.local.json <<'EOF' -{ - "model": { - "temperature": 0.0 - }, - "review": { - "strict": true - } -} -EOF -``` - -### 4.2 Account fixtures - -```bash -cat > ./test_cases/.claw-account.json <<'EOF' -{ - "profiles": [ - { - "name": "local", - "provider": "openai", - "identity": "dev@example.com", - "authMode": "api_key" - }, - { - "name": "team", - "provider": "anthropic", - "identity": "team@example.com", - "org": "Harness" - } - ] -} -EOF -``` - -### 4.2b Ask-user fixtures - -```bash -cat > ./test_cases/.claw-ask-user.json <<'EOF' -{ - "answers": [ - { - "question": "Approve deploy?", - "answer": "yes" - }, - { - "question": "Choose rollout mode", - "answer": "safe" - } - ] -} -EOF -``` - -### 4.2c Team fixtures - -```bash -cat > ./test_cases/.claw-teams.json <<'EOF' -{ - "teams": [ - { - "name": "reviewers", - "description": "Code review group", - "members": ["alice", "bob"] - }, - { - "name": "release", - "description": "Release coordination group", - "members": ["ops", "qa"] - } - ] -} -EOF -``` - -### 4.2d Notebook fixture - -```bash -cat > ./test_cases_notebooks/demo.ipynb <<'EOF' -{ - "cells": [ - { - "cell_type": "code", - "metadata": {}, - "source": ["print(1)\n"], - "outputs": [], - "execution_count": null - } - ], - "metadata": {}, - "nbformat": 4, - "nbformat_minor": 5 -} -EOF -``` - -### 4.2e LSP fixture - -```bash -cat > ./test_cases/sample.py <<'EOF' -def helper(value): - """Double a numeric value.""" - return value * 2 - - -def orchestrate(item): - return helper(item) - - -class Greeter: - def greet(self, name): - return helper(len(name)) -EOF - -cat > ./test_cases/broken.py <<'EOF' -def broken(: - pass -EOF -``` - -### 4.3 Remote fixtures - -```bash -cat > ./test_cases/.claw-remote.json <<'EOF' -{ - "profiles": [ - { - "name": "staging", - "mode": "ssh", - "target": "dev@staging", - "workspaceCwd": "/srv/app", - "sessionUrl": "wss://remote/session" - }, - { - "name": "preview", - "mode": "deep-link", - "target": "preview://session" - }, - { - "name": "tele", - "mode": "teleport", - "target": "teleport://workspace" - }, - { - "name": "direct", - "mode": "direct-connect", - "target": "direct://workspace" - } - ] -} -EOF -``` - -### 4.4 Search fixtures - -```bash -cat > ./test_cases/.claw-search.json <<'EOF' -{ - "providers": [ - { - "name": "local-search", - "provider": "searxng", - "baseUrl": "http://127.0.0.1:8080" - }, - { - "name": "backup-search", - "provider": "tavily", - "apiKeyEnv": "TAVILY_API_KEY" - } - ] -} -EOF -``` - -### 4.5 Hook and policy fixtures - -```bash -cat > ./test_cases_policy/.claw-policy.json <<'EOF' -{ - "trusted": false, - "managedSettings": { - "reviewMode": "strict" - }, - "safeEnv": ["HOOK_SAFE_TOKEN"], - "hooks": { - "beforePrompt": ["Respect workspace policy before acting."], - "afterTurn": ["Persist the policy decision after each turn."], - "beforeTool": { - "read_file": ["Validate the path before reading."] - } - } -} -EOF - -export HOOK_SAFE_TOKEN=demo-secret -``` - -### 4.6 Plugin fixtures - -```bash -cat > ./test_cases_plugins/plugins/demo/plugin.json <<'EOF' -{ - "name": "demo-plugin", - "hooks": { - "beforePrompt": "Inject plugin prompt guidance.", - "afterTurn": "Attach plugin after-turn guidance.", - "onResume": "Reapply plugin state on resume.", - "beforePersist": "Persist plugin state before saving.", - "beforeDelegate": "Add plugin guidance before delegated children run.", - "afterDelegate": "Add plugin guidance after delegated children finish." - }, - "blockedTools": ["bash"], - "toolAliases": [ - { - "name": "plugin_read", - "baseTool": "read_file", - "description": "Plugin alias for reading files." - } - ], - "virtualTools": [ - { - "name": "demo_virtual", - "description": "Return a rendered plugin response.", - "responseTemplate": "plugin topic: {topic}" - } - ], - "toolHooks": { - "read_file": { - "beforeTool": "Validate the path before reading.", - "afterResult": "Summarize the file before the next action." - } - } -} -EOF - -printf 'hello plugin\n' > ./test_cases_plugins/hello.txt -``` - -### 4.7 MCP fixtures - -```bash -printf 'mcp notes\n' > ./test_cases_mcp/notes.txt - -cat > ./test_cases_mcp/fake_stdio_mcp.py <<'EOF' -import json -import sys - -RESOURCES = [ - { - "uri": "mcp://remote/notes", - "name": "Remote Notes", - "mimeType": "text/plain" - } -] - -TOOLS = [ - { - "name": "echo", - "description": "Echo text", - "inputSchema": { - "type": "object", - "properties": { - "text": {"type": "string"} - } - } - } -] - -for raw in sys.stdin: - raw = raw.strip() - if not raw: - continue - message = json.loads(raw) - method = message.get("method") - if method == "initialize": - print(json.dumps({ - "jsonrpc": "2.0", - "id": message["id"], - "result": { - "protocolVersion": "2025-11-25", - "capabilities": {"resources": {}, "tools": {}}, - "serverInfo": {"name": "fake-remote", "version": "1.0.0"} - } - }), flush=True) - continue - if method == "notifications/initialized": - continue - if method == "resources/list": - print(json.dumps({ - "jsonrpc": "2.0", - "id": message["id"], - "result": {"resources": RESOURCES} - }), flush=True) - continue - if method == "resources/read": - uri = message.get("params", {}).get("uri") - print(json.dumps({ - "jsonrpc": "2.0", - "id": message["id"], - "result": { - "contents": [ - { - "uri": uri, - "mimeType": "text/plain", - "text": "remote notes via stdio" - } - ] - } - }), flush=True) - continue - if method == "tools/list": - print(json.dumps({ - "jsonrpc": "2.0", - "id": message["id"], - "result": {"tools": TOOLS} - }), flush=True) - continue - if method == "tools/call": - text = message.get("params", {}).get("arguments", {}).get("text", "") - print(json.dumps({ - "jsonrpc": "2.0", - "id": message["id"], - "result": { - "content": [{"type": "text", "text": "echo:" + text}], - "isError": False - } - }), flush=True) - continue -EOF - -cat > ./test_cases_mcp/.claw-mcp.json <<'EOF' -{ - "servers": [ - { - "name": "workspace", - "resources": [ - { - "uri": "mcp://workspace/notes", - "name": "Notes", - "path": "notes.txt", - "mimeType": "text/plain" - }, - { - "uri": "mcp://workspace/inline", - "name": "Inline", - "text": "inline body" - } - ] - } - ], - "mcpServers": { - "remote": { - "command": "python3", - "args": ["-u", "./fake_stdio_mcp.py"] - } - } -} -EOF -``` - -### 4.8 Task workspace cleanup - -```bash -mkdir -p ./test_cases_tasks -``` - -### 4.9 Custom agent definitions - -```bash -mkdir -p ./test_cases_agents/.claude/agents - -cat > ./test_cases_agents/.claude/agents/reviewer.md <<'EOF' ---- -name: reviewer -description: "Review implementation changes carefully." -tools: read_file, grep_search -model: Qwen/Qwen3-Coder-30B-A3B-Instruct -initialPrompt: Start by identifying the highest-risk files. ---- - -Inspect code changes and summarize correctness risks, regressions, and missing tests. -EOF -``` - -## 5. Slash Command Matrix - -Slash commands are handled locally before the model loop. - -### 5.1 Core local slash commands - -```bash -python3 -m src.main agent "/help" --cwd ./test_cases -python3 -m src.main agent "/commands" --cwd ./test_cases -python3 -m src.main agent "/context" --cwd ./test_cases -python3 -m src.main agent "/usage summarize current session" --cwd ./test_cases -python3 -m src.main agent "/context-raw" --cwd ./test_cases -python3 -m src.main agent "/env" --cwd ./test_cases -python3 -m src.main agent "/token-budget" --cwd ./test_cases -python3 -m src.main agent "/budget" --cwd ./test_cases -python3 -m src.main agent "/prompt" --cwd ./test_cases -python3 -m src.main agent "/system-prompt" --cwd ./test_cases -python3 -m src.main agent "/permissions" --cwd ./test_cases -python3 -m src.main agent "/model" --cwd ./test_cases -python3 -m src.main agent "/model demo-model" --cwd ./test_cases -python3 -m src.main agent "/tools" --cwd ./test_cases -python3 -m src.main agent "/agents" --cwd ./test_cases_agents -python3 -m src.main agent "/agents show reviewer" --cwd ./test_cases_agents -python3 -m src.main agent "/agents create reviewer-temp :: Review temporary code changes. :: Inspect code and summarize risks." --cwd ./test_cases_agents -python3 -m src.main agent "/agents update reviewer-temp Updated temp reviewer :: Focus on regressions and missing tests." --cwd ./test_cases_agents -python3 -m src.main agent "/agents delete reviewer-temp" --cwd ./test_cases_agents -python3 -m src.main agent "/memory" --cwd ./test_cases -python3 -m src.main agent "/status" --cwd ./test_cases -python3 -m src.main agent "/session" --cwd ./test_cases -python3 -m src.main agent "/clear" --cwd ./test_cases -``` - -### 5.2 Hook, policy, trust, config, and account slash commands - -```bash -python3 -m src.main agent "/hooks" --cwd ./test_cases_policy -python3 -m src.main agent "/policy" --cwd ./test_cases_policy -python3 -m src.main agent "/trust" --cwd ./test_cases_policy -python3 -m src.main agent "/config" --cwd ./test_cases -python3 -m src.main agent "/config effective" --cwd ./test_cases -python3 -m src.main agent "/config source local" --cwd ./test_cases -python3 -m src.main agent "/config get review.strict" --cwd ./test_cases -python3 -m src.main agent "/settings" --cwd ./test_cases -python3 -m src.main agent "/account" --cwd ./test_cases -python3 -m src.main agent "/account profiles" --cwd ./test_cases -python3 -m src.main agent "/account profile local" --cwd ./test_cases -python3 -m src.main agent "/ask" --cwd ./test_cases -python3 -m src.main agent "/ask history" --cwd ./test_cases -python3 -m src.main agent "/login local" --cwd ./test_cases -python3 -m src.main agent "/logout" --cwd ./test_cases -``` - -### 5.3 Remote, search, team, task, and plan slash commands - -```bash -python3 -m src.main agent "/remote" --cwd ./test_cases -python3 -m src.main agent "/remote staging" --cwd ./test_cases -python3 -m src.main agent "/remotes" --cwd ./test_cases -python3 -m src.main agent "/ssh staging" --cwd ./test_cases -python3 -m src.main agent "/teleport tele" --cwd ./test_cases -python3 -m src.main agent "/direct-connect direct" --cwd ./test_cases -python3 -m src.main agent "/deep-link preview" --cwd ./test_cases -python3 -m src.main agent "/disconnect" --cwd ./test_cases -python3 -m src.main agent "/remote-disconnect" --cwd ./test_cases -python3 -m src.main agent "/search" --cwd ./test_cases -python3 -m src.main agent "/search providers" --cwd ./test_cases -python3 -m src.main agent "/search provider local-search" --cwd ./test_cases -python3 -m src.main agent "/search use local-search" --cwd ./test_cases -python3 -m src.main agent "/search python argparse tutorial" --cwd ./test_cases -python3 -m src.main agent "/teams" --cwd ./test_cases -python3 -m src.main agent "/team reviewers" --cwd ./test_cases -python3 -m src.main agent "/messages" --cwd ./test_cases -python3 -m src.main agent "/messages reviewers" --cwd ./test_cases -python3 -m src.main agent "/plan" --cwd ./test_cases_tasks -python3 -m src.main agent "/planner" --cwd ./test_cases_tasks -python3 -m src.main agent "/tasks" --cwd ./test_cases_tasks -python3 -m src.main agent "/todo" --cwd ./test_cases_tasks -python3 -m src.main agent "/task missing-task-id" --cwd ./test_cases_tasks -python3 -m src.main agent "/task-next" --cwd ./test_cases_tasks -python3 -m src.main agent "/next-task" --cwd ./test_cases_tasks -``` - -### 5.4 MCP slash commands - -```bash -python3 -m src.main agent "/mcp" --cwd ./test_cases_mcp -python3 -m src.main agent "/mcp tools" --cwd ./test_cases_mcp -python3 -m src.main agent "/mcp tool echo" --cwd ./test_cases_mcp -python3 -m src.main agent "/resources" --cwd ./test_cases_mcp -python3 -m src.main agent "/resource mcp://workspace/notes" --cwd ./test_cases_mcp -python3 -m src.main agent "/resource mcp://remote/notes" --cwd ./test_cases_mcp -python3 -m src.main agent "/mcp (MCP)" --cwd ./test_cases_mcp -``` - -## 6. Prompt, Context, And Token Accounting - -### 6.1 Prompt and context reports - -```bash -python3 -m src.main agent-prompt --cwd ./test_cases -python3 -m src.main agent-context --cwd ./test_cases -python3 -m src.main agent-context-raw --cwd ./test_cases -python3 -m src.main token-budget --cwd ./test_cases -python3 -m src.main agents --cwd ./test_cases_agents -python3 -m src.main agents reviewer --cwd ./test_cases_agents -python3 -m src.main agents-create reviewer-cli --cwd ./test_cases_agents --description "CLI-created reviewer agent." --prompt "Inspect code changes and summarize risks." -python3 -m src.main agents-update reviewer-cli --cwd ./test_cases_agents --description "Updated CLI reviewer." --prompt "Focus on regressions and missing tests." -python3 -m src.main agents-delete reviewer-cli --cwd ./test_cases_agents --source project -``` - -### 6.2 Extra working directories and `CLAUDE.md` toggle - -```bash -python3 -m src.main agent-context --cwd ./test_cases --add-dir ./src -python3 -m src.main agent-context --cwd ./test_cases --disable-claude-md -``` - -### 6.3 Custom system prompt flags - -```bash -python3 -m src.main agent-prompt \ - --cwd ./test_cases \ - --system-prompt "You are a strict review assistant." - -python3 -m src.main agent-prompt \ - --cwd ./test_cases \ - --append-system-prompt "Always mention the active config source." - -python3 -m src.main agent-prompt \ - --cwd ./test_cases \ - --override-system-prompt "Only output terse bullet points." -``` - -### 6.4 Tokenizer-aware context accounting - -```bash -python3 -m src.main agent "/status" --cwd ./test_cases -python3 -m src.main agent-context --cwd ./test_cases -python3 -m src.main token-budget --cwd ./test_cases -``` - -Override the tokenizer backend: - -```bash -export CLAW_CODE_TOKENIZER_PATH=/path/to/local/tokenizer -# or -export CLAW_CODE_TOKENIZER_MODEL=Qwen/Qwen3-Coder-30B-A3B-Instruct - -python3 -m src.main agent "/status" --cwd ./test_cases -python3 -m src.main agent-context --cwd ./test_cases -python3 -m src.main token-budget --cwd ./test_cases -``` - -If no tokenizer backend is available, the runtime will fall back to the heuristic counter and `/status` will report that. - -## 7. Core Agent Loop And Chat - -### 7.1 Read-only run - -```bash -python3 -m src.main agent \ - "Read src/agent_runtime.py and summarize how the loop works." \ - --cwd . -``` - -### 7.2 Show transcript output - -```bash -python3 -m src.main agent \ - "Read src/agent_session.py and summarize the session model." \ - --cwd . \ - --show-transcript -``` - -### 7.3 Streaming model responses - -```bash -python3 -m src.main agent \ - "Inspect the repository and summarize the architecture." \ - --cwd . \ - --stream \ - --show-transcript -``` - -### 7.4 Interactive chat - -```bash -python3 -m src.main agent-chat --cwd . -``` - -### 7.5 Interactive chat with an initial prompt - -```bash -python3 -m src.main agent-chat \ - "Inspect the repository and tell me where the runtime loop lives." \ - --cwd . -``` - -Inside chat mode: - -- type normal prompts to continue the same session -- use `/exit` or `/quit` to leave - -### 7.6 Resume directly into chat mode - -```bash -python3 -m src.main agent-chat \ - --resume-session-id \ - --cwd . -``` - -## 8. Tool Execution - -### 8.1 Read files - -```bash -python3 -m src.main agent \ - "Read src/agent_tools.py and summarize the implemented tools." \ - --cwd . -``` - -### 8.2 Write files - -```bash -python3 -m src.main agent \ - "Create TEST_WRITE.md in the current directory with one line: write test ok" \ - --cwd ./test_cases \ - --allow-write -``` - -### 8.3 Edit files - -```bash -python3 -m src.main agent \ - "Create demo.txt with 'hello world', then replace 'world' with 'agent'." \ - --cwd ./test_cases \ - --allow-write -``` - -### 8.4 Glob and grep - -```bash -python3 -m src.main agent \ - "Find Python files in the current directory, search for LocalCodingAgent, and summarize the matches." \ - --cwd . -``` - -### 8.5 Shell commands - -```bash -python3 -m src.main agent \ - "Run pwd and ls in the current working directory, then summarize the result." \ - --cwd . \ - --allow-shell \ - --show-transcript -``` - -### 8.6 Unsafe shell mode - -```bash -python3 -m src.main agent \ - "Explain whether destructive shell commands are currently allowed." \ - --cwd . \ - --allow-shell \ - --unsafe -``` - -### 8.7 Tool search - -```bash -python3 -m src.main agent \ - "Use tool_search to find file-related tools and summarize the best options for reading and editing files." \ - --cwd . -``` - -### 8.8 Web fetch - -```bash -python3 -m src.main agent \ - "Use web_fetch on file://$(pwd)/README.md and summarize the first section." \ - --cwd . -``` - -### 8.9 Sleep - -```bash -python3 -m src.main agent \ - "Call the sleep tool for 0.1 seconds, then tell me it completed." \ - --cwd ./test_cases -``` - -### 8.10 Scratchpad root - -```bash -python3 -m src.main agent \ - "Use the scratchpad if needed while inspecting the workspace, then summarize what you did." \ - --cwd ./test_cases \ - --allow-write \ - --scratchpad-root ./test_cases/.scratchpad \ - --show-transcript - -ls -la ./test_cases/.scratchpad -``` - -## 9. Session Persistence, Resume, And File History - -### 9.1 Create a saved session - -```bash -python3 -m src.main agent \ - "Create a short TODO file in the current directory and explain what you wrote." \ - --cwd ./test_cases \ - --allow-write -``` - -At the end of the run, note: - -```text -session_id=... -session_path=... -``` - -### 9.2 Resume a saved session - -```bash -python3 -m src.main agent-resume \ - \ - "Continue the previous task and improve the file." \ - --allow-write \ - --show-transcript -``` - -### 9.3 Inspect saved sessions - -```bash -ls -lt .port_sessions/agent -``` - -### 9.4 File history replay on resume - -```bash -python3 -m src.main agent \ - "Create notes.txt with one line, then update that line to mention file history." \ - --cwd ./test_cases \ - --allow-write - -python3 -m src.main agent-resume \ - \ - "Continue the previous work and tell me what files were changed before this turn." \ - --allow-write \ - --show-transcript -``` - -Look for `file_history_replay` messages in the transcript. - -## 10. Background Sessions And Daemon Mode - -### 10.1 Launch a background session - -```bash -python3 -m src.main agent-bg "/help" --cwd ./test_cases -``` - -This prints: - -- `background_id=...` -- `pid=...` -- `log_path=...` -- `record_path=...` - -### 10.2 List background sessions - -```bash -python3 -m src.main agent-ps -python3 -m src.main agent-ps --tail 20 -``` - -### 10.3 Read background logs - -```bash -python3 -m src.main agent-logs -python3 -m src.main agent-logs --tail 40 -``` - -### 10.4 Attach to the current output snapshot - -```bash -python3 -m src.main agent-attach -python3 -m src.main agent-attach --tail 40 -``` - -### 10.5 Kill a background session - -```bash -python3 -m src.main agent-kill -``` - -### 10.6 Daemon wrappers - -```bash -python3 -m src.main daemon start "/help" --cwd ./test_cases -python3 -m src.main daemon ps -python3 -m src.main daemon ps --tail 20 -python3 -m src.main daemon logs -python3 -m src.main daemon attach -python3 -m src.main daemon kill -``` - -## 11. Structured Output, Budgets, And Context Reduction - -### 11.1 Structured output / JSON schema - -Create a schema file: - -```bash -cat > /tmp/claw_schema.json <<'EOF' -{ - "type": "object", - "properties": { - "status": { "type": "string" }, - "summary": { "type": "string" } - }, - "required": ["status", "summary"], - "additionalProperties": false -} -EOF -``` - -Run the agent with schema mode: - -```bash -python3 -m src.main agent \ - "Inspect the current repository and respond in the requested JSON format." \ - --cwd . \ - --response-schema-file /tmp/claw_schema.json \ - --response-schema-name claw_summary \ - --response-schema-strict -``` - -### 11.2 Token budgets - -```bash -python3 -m src.main agent \ - "Give a very long answer about the current repository." \ - --cwd . \ - --max-total-tokens 50 - -python3 -m src.main agent \ - "Read several files and explain them in detail." \ - --cwd . \ - --max-input-tokens 80 \ - --max-output-tokens 80 -``` - -### 11.3 Reasoning, tool, delegation, model-call, and session-turn budgets - -```bash -python3 -m src.main agent \ - "Solve a multi-step task and explain the result." \ - --cwd . \ - --max-reasoning-tokens 10 - -python3 -m src.main agent \ - "Read multiple files, search for symbols, and summarize the repo." \ - --cwd . \ - --max-tool-calls 1 - -python3 -m src.main agent \ - "Delegate two subtasks to inspect and summarize the repo." \ - --cwd . \ - --max-delegated-tasks 1 - -python3 -m src.main agent \ - "Continue inspecting the repository until you are done." \ - --cwd . \ - --max-model-calls 1 - -python3 -m src.main agent \ - "Work through the repository across multiple turns and keep going." \ - --cwd . \ - --max-session-turns 1 -``` - -### 11.4 Cost budget - -```bash -python3 -m src.main agent \ - "Inspect the repository and summarize it." \ - --cwd . \ - --input-cost-per-million 0.15 \ - --output-cost-per-million 0.60 \ - --max-budget-usd 0.000001 -``` - -### 11.5 Budget override from local policy - -```bash -cat > ./test_cases_budget/.claw-policy.json <<'EOF' -{ - "budget": { - "max_model_calls": 0 - } -} -EOF - -python3 -m src.main agent \ - "Say hello once." \ - --cwd ./test_cases_budget -``` - -Expected result: the run stops with a model-call budget exceeded message even though you did not pass `--max-model-calls`. - -### 11.6 Streaming assistant output - -```bash -python3 -m src.main agent \ - "Produce a long explanation of the current repository architecture." \ - --cwd . \ - --stream \ - --show-transcript -``` - -### 11.7 Automatic continuation after truncation - -```bash -python3 -m src.main agent \ - "Write a long, structured explanation of the current repository." \ - --cwd . \ - --max-output-tokens 32 \ - --show-transcript -``` - -### 11.8 Snipping and compaction - -```bash -python3 -m src.main agent \ - "Read src/agent_runtime.py, src/agent_session.py, src/query_engine.py, and src/plugin_runtime.py, then summarize all of them in detail." \ - --cwd . \ - --auto-snip-threshold 120 \ - --compact-preserve-messages 0 \ - --show-transcript - -python3 -m src.main agent \ - "Read several large files from src and keep explaining the repository until the context gets compacted." \ - --cwd . \ - --auto-compact-threshold 120 \ - --compact-preserve-messages 1 \ - --show-transcript -``` - -## 12. Hook, Policy, And Trust Runtime - -### 12.1 Inspect hook and trust state - -```bash -python3 -m src.main agent "/hooks" --cwd ./test_cases_policy -python3 -m src.main agent "/policy" --cwd ./test_cases_policy -python3 -m src.main agent "/trust" --cwd ./test_cases_policy -python3 -m src.main agent "/permissions" --cwd ./test_cases_policy -python3 -m src.main agent "/tools" --cwd ./test_cases_policy -python3 -m src.main agent-context-raw --cwd ./test_cases_policy -python3 -m src.main agent-prompt --cwd ./test_cases_policy -``` - -### 12.2 Safe environment values in shell tools - -```bash -python3 -m src.main agent \ - "Run bash and print HOOK_SAFE_TOKEN, then explain where it came from." \ - --cwd ./test_cases_policy \ - --allow-shell \ - --show-transcript -``` - -### 12.3 Tool blocking through policy - -```bash -cat > ./test_cases_policy/.claw-policy.json <<'EOF' -{ - "trusted": false, - "denyTools": ["bash"], - "hooks": { - "beforePrompt": ["Respect workspace policy before acting."], - "afterTurn": ["Persist the policy decision after each turn."] - } -} -EOF - -python3 -m src.main agent \ - "Try to run bash and then explain what was blocked." \ - --cwd ./test_cases_policy \ - --allow-shell \ - --show-transcript -``` - -Look for: - -- `hook_policy_tool_block` -- `tool_permission_denial` -- transcript guidance around the blocked tool - -## 13. Config Runtime - -### 13.1 CLI status and inspection - -```bash -python3 -m src.main config-status --cwd ./test_cases -python3 -m src.main config-effective --cwd ./test_cases -python3 -m src.main config-source project --cwd ./test_cases -python3 -m src.main config-source local --cwd ./test_cases -python3 -m src.main config-get review.strict --cwd ./test_cases -python3 -m src.main config-get model.temperature --cwd ./test_cases --source local -``` - -### 13.2 Config writes - -```bash -python3 -m src.main config-set review.mode '"strict"' --cwd ./test_cases -python3 -m src.main config-set review.enabled true --cwd ./test_cases -python3 -m src.main config-effective --cwd ./test_cases -``` - -### 13.3 Slash commands - -```bash -python3 -m src.main agent "/config" --cwd ./test_cases -python3 -m src.main agent "/config effective" --cwd ./test_cases -python3 -m src.main agent "/config source local" --cwd ./test_cases -python3 -m src.main agent "/config get review.mode" --cwd ./test_cases -python3 -m src.main agent "/settings" --cwd ./test_cases -``` - -### 13.4 Real tool loop - -```bash -python3 -m src.main agent \ - "List the current config keys, set review.mode to strict in local config, then read it back." \ - --cwd ./test_cases \ - --allow-write \ - --show-transcript -``` - -## 14. Account Runtime - -### 14.1 CLI status and profile inspection - -```bash -python3 -m src.main account-status --cwd ./test_cases -python3 -m src.main account-profiles --cwd ./test_cases -python3 -m src.main account-profiles --cwd ./test_cases --query local -``` - -### 14.2 Login and logout - -```bash -python3 -m src.main account-login local --cwd ./test_cases -python3 -m src.main account-status --cwd ./test_cases -python3 -m src.main account-logout --cwd ./test_cases -``` - -### 14.3 Ephemeral account identity - -```bash -python3 -m src.main account-login dev@example.com \ - --provider openai \ - --auth-mode api_key \ - --cwd ./test_cases -``` - -### 14.4 Slash commands - -```bash -python3 -m src.main agent "/account" --cwd ./test_cases -python3 -m src.main agent "/account profiles" --cwd ./test_cases -python3 -m src.main agent "/account profile local" --cwd ./test_cases -python3 -m src.main agent "/login local" --cwd ./test_cases -python3 -m src.main agent "/logout" --cwd ./test_cases -``` - -### 14.5 Real tool loop - -```bash -python3 -m src.main agent \ - "List the configured account profiles, activate the local profile, then report the active account session." \ - --cwd ./test_cases \ - --show-transcript -``` - -## 14B. LSP Runtime - -### 14B.1 CLI status and code intelligence reports - -```bash -python3 -m src.main lsp-status --cwd ./test_cases -python3 -m src.main lsp-symbols sample.py --cwd ./test_cases -python3 -m src.main lsp-workspace-symbols helper --cwd ./test_cases -python3 -m src.main lsp-definition sample.py 6 12 --cwd ./test_cases -python3 -m src.main lsp-references sample.py 6 12 --cwd ./test_cases -python3 -m src.main lsp-hover sample.py 1 5 --cwd ./test_cases -python3 -m src.main lsp-diagnostics --cwd ./test_cases -python3 -m src.main lsp-diagnostics --cwd ./test_cases --file-path broken.py -python3 -m src.main lsp-call-hierarchy sample.py 6 12 --cwd ./test_cases -python3 -m src.main lsp-incoming-calls sample.py 1 5 --cwd ./test_cases -python3 -m src.main lsp-outgoing-calls sample.py 6 12 --cwd ./test_cases -``` - -### 14B.2 Slash commands - -```bash -python3 -m src.main agent "/lsp" --cwd ./test_cases -python3 -m src.main agent "/lsp symbols sample.py" --cwd ./test_cases -python3 -m src.main agent "/lsp workspace helper" --cwd ./test_cases -python3 -m src.main agent "/lsp definition sample.py 6 12" --cwd ./test_cases -python3 -m src.main agent "/lsp references sample.py 6 12" --cwd ./test_cases -python3 -m src.main agent "/lsp hover sample.py 1 5" --cwd ./test_cases -python3 -m src.main agent "/lsp diagnostics broken.py" --cwd ./test_cases -python3 -m src.main agent "/lsp hierarchy sample.py 6 12" --cwd ./test_cases -``` - -### 14B.3 Real tool loop - -```bash -python3 -m src.main agent \ - "Use the LSP tool to find the definition of helper in sample.py, then summarize the result." \ - --cwd ./test_cases \ - --show-transcript -``` - -## 14A. Ask-user Runtime - -### 14A.1 CLI status and history - -```bash -python3 -m src.main ask-status --cwd ./test_cases -python3 -m src.main ask-history --cwd ./test_cases -``` - -### 14A.2 Slash commands - -```bash -python3 -m src.main agent "/ask" --cwd ./test_cases -python3 -m src.main agent "/ask history" --cwd ./test_cases -``` - -### 14A.3 Real tool loop - -```bash -python3 -m src.main agent \ - "Use ask_user_question to answer 'Approve deploy?' and then summarize the decision." \ - --cwd ./test_cases \ - --show-transcript -``` - -## 15. Search Runtime And Real Web Search - -### 15.1 Provider status and activation - -```bash -python3 -m src.main search-status --cwd ./test_cases -python3 -m src.main search-providers --cwd ./test_cases -python3 -m src.main search-providers --cwd ./test_cases --query local -python3 -m src.main search-status --cwd ./test_cases --provider local-search -python3 -m src.main search-activate local-search --cwd ./test_cases -``` - -### 15.2 Real search from the CLI - -```bash -python3 -m src.main search \ - "python argparse mutually exclusive group" \ - --cwd ./test_cases \ - --provider local-search \ - --max-results 5 - -python3 -m src.main search \ - "OpenAI Responses API" \ - --cwd ./test_cases \ - --domain openai.com \ - --domain platform.openai.com -``` - -### 15.3 Slash commands - -```bash -python3 -m src.main agent "/search" --cwd ./test_cases -python3 -m src.main agent "/search providers" --cwd ./test_cases -python3 -m src.main agent "/search provider local-search" --cwd ./test_cases -python3 -m src.main agent "/search use local-search" --cwd ./test_cases -python3 -m src.main agent "/search python unittest mock patch examples" --cwd ./test_cases -``` - -### 15.4 Real search through the model loop - -```bash -python3 -m src.main agent \ - "Use web_search to find Python unittest mocking references, then summarize the top results." \ - --cwd ./test_cases \ - --show-transcript -``` - -## 16. Remote Runtime - -### 16.1 CLI runtime modes - -```bash -python3 -m src.main remote-mode staging --cwd ./test_cases -python3 -m src.main ssh-mode staging --cwd ./test_cases -python3 -m src.main teleport-mode tele --cwd ./test_cases -python3 -m src.main direct-connect-mode direct --cwd ./test_cases -python3 -m src.main deep-link-mode preview --cwd ./test_cases -``` - -### 16.2 Status and disconnect - -```bash -python3 -m src.main remote-status --cwd ./test_cases -python3 -m src.main remote-profiles --cwd ./test_cases -python3 -m src.main remote-profiles --cwd ./test_cases --query stag -python3 -m src.main remote-disconnect --cwd ./test_cases -python3 -m src.main remote-status --cwd ./test_cases -``` - -### 16.3 Slash commands - -```bash -python3 -m src.main agent "/remote" --cwd ./test_cases -python3 -m src.main agent "/remote staging" --cwd ./test_cases -python3 -m src.main agent "/remotes" --cwd ./test_cases -python3 -m src.main agent "/ssh staging" --cwd ./test_cases -python3 -m src.main agent "/teleport tele" --cwd ./test_cases -python3 -m src.main agent "/direct-connect direct" --cwd ./test_cases -python3 -m src.main agent "/deep-link preview" --cwd ./test_cases -python3 -m src.main agent "/disconnect" --cwd ./test_cases -``` - -### 16.4 Real tool loop - -```bash -python3 -m src.main agent \ - "List the configured remote profiles, connect to staging, then report the active remote status." \ - --cwd ./test_cases \ - --show-transcript -``` - -## 17. MCP Runtime - -### 17.1 Local resource inspection - -```bash -python3 -m src.main mcp-status --cwd ./test_cases_mcp -python3 -m src.main mcp-resources --cwd ./test_cases_mcp -python3 -m src.main mcp-resources --cwd ./test_cases_mcp --query notes -python3 -m src.main mcp-resource mcp://workspace/notes --cwd ./test_cases_mcp -python3 -m src.main mcp-resource mcp://workspace/inline --cwd ./test_cases_mcp -``` - -### 17.2 Transport-backed MCP tools - -```bash -python3 -m src.main mcp-tools --cwd ./test_cases_mcp -python3 -m src.main mcp-tools --cwd ./test_cases_mcp --query echo -python3 -m src.main mcp-tools --cwd ./test_cases_mcp --server remote -python3 -m src.main mcp-call-tool echo --arguments-json '{"text":"hello"}' --cwd ./test_cases_mcp -python3 -m src.main mcp-call-tool echo --arguments-json '{"text":"hello"}' --server remote --cwd ./test_cases_mcp -``` - -### 17.3 Slash commands - -```bash -python3 -m src.main agent "/mcp" --cwd ./test_cases_mcp -python3 -m src.main agent "/mcp tools" --cwd ./test_cases_mcp -python3 -m src.main agent "/mcp tool echo" --cwd ./test_cases_mcp -python3 -m src.main agent "/resources" --cwd ./test_cases_mcp -python3 -m src.main agent "/resource mcp://remote/notes" --cwd ./test_cases_mcp -``` - -### 17.4 Real tool loop - -```bash -python3 -m src.main agent \ - "List the available MCP tools, call the remote echo tool with text=hello, then summarize the result." \ - --cwd ./test_cases_mcp \ - --show-transcript -``` - -## 18. Task And Plan Runtime - -### 18.1 Slash commands - -```bash -python3 -m src.main agent "/tasks" --cwd ./test_cases_tasks -python3 -m src.main agent "/todo" --cwd ./test_cases_tasks -python3 -m src.main agent "/task missing-task-id" --cwd ./test_cases_tasks -python3 -m src.main agent "/task-next" --cwd ./test_cases_tasks -python3 -m src.main agent "/plan" --cwd ./test_cases_tasks -python3 -m src.main agent "/planner" --cwd ./test_cases_tasks -python3 -m src.main agent-context-raw --cwd ./test_cases_tasks -python3 -m src.main agent-prompt --cwd ./test_cases_tasks -``` - -## 18A. Team Runtime - -### 18A.1 CLI status and inspection - -```bash -python3 -m src.main team-status --cwd ./test_cases -python3 -m src.main team-list --cwd ./test_cases -python3 -m src.main team-get reviewers --cwd ./test_cases -python3 -m src.main team-messages --cwd ./test_cases -``` - -### 18A.2 Create and delete teams - -```bash -python3 -m src.main team-create docs --member alice --member bob --cwd ./test_cases -python3 -m src.main team-list --cwd ./test_cases -python3 -m src.main team-delete docs --cwd ./test_cases -``` - -### 18A.3 Slash commands - -```bash -python3 -m src.main agent "/teams" --cwd ./test_cases -python3 -m src.main agent "/team reviewers" --cwd ./test_cases -python3 -m src.main agent "/messages" --cwd ./test_cases -python3 -m src.main agent "/messages reviewers" --cwd ./test_cases -``` - -### 18A.4 Real tool loop - -```bash -python3 -m src.main agent \ - "Create a local team called docs with members alice and bob, send a message to that team asking for notebook review, then show the team messages." \ - --cwd ./test_cases \ - --allow-write \ - --show-transcript -``` - -## 18B. Notebook Edit Tool - -### 18B.1 Direct notebook edit through the agent loop - -```bash -python3 -m src.main agent \ - "Use notebook_edit to update demo.ipynb cell 0 so it prints 2, then read back the notebook file and summarize the change." \ - --cwd ./test_cases_notebooks \ - --allow-write \ - --show-transcript -``` - -## 18C. Workflow Runtime - -### 18C.1 Prepare a workflow manifest - -```bash -cat > ./test_cases/.claw-workflows.json <<'EOF' -{ - "workflows": [ - { - "name": "review", - "description": "Review the current patch.", - "steps": [ - {"title": "Inspect diff", "detail": "Read {path}"}, - {"title": "Summarize findings"} - ], - "prompt": "Review changes under {path}" - } - ] -} -EOF -``` - -### 18C.2 CLI inspection and run - -```bash -python3 -m src.main workflow-list --cwd ./test_cases -python3 -m src.main workflow-get review --cwd ./test_cases -python3 -m src.main workflow-run review --arguments-json '{"path":"src/"}' --cwd ./test_cases -``` - -### 18C.3 Slash commands - -```bash -python3 -m src.main agent "/workflows" --cwd ./test_cases -python3 -m src.main agent "/workflow review" --cwd ./test_cases -python3 -m src.main agent "/workflow run review" --cwd ./test_cases -``` - -## 18D. Remote Trigger Runtime - -### 18D.1 Prepare a trigger manifest - -```bash -cat > ./test_cases/.claw-triggers.json <<'EOF' -{ - "triggers": [ - { - "trigger_id": "nightly", - "name": "Nightly", - "workflow": "review", - "schedule": "0 0 * * *", - "body": {"depth": "full"} - } - ] -} -EOF -``` - -### 18D.2 CLI inspection, create, update, and run - -```bash -python3 -m src.main trigger-list --cwd ./test_cases -python3 -m src.main trigger-get nightly --cwd ./test_cases -python3 -m src.main trigger-create --body-json '{"trigger_id":"adhoc","name":"Adhoc","workflow":"review"}' --cwd ./test_cases -python3 -m src.main trigger-update adhoc --body-json '{"schedule":"manual"}' --cwd ./test_cases -python3 -m src.main trigger-run nightly --body-json '{"depth":"quick"}' --cwd ./test_cases -``` - -### 18D.3 Slash commands - -```bash -python3 -m src.main agent "/triggers" --cwd ./test_cases -python3 -m src.main agent "/trigger nightly" --cwd ./test_cases -python3 -m src.main agent "/trigger run nightly" --cwd ./test_cases -``` - -## 18E. Worktree Runtime - -### 18E.1 Prepare a git workspace - -```bash -cd ./test_cases -git init -git config user.email test@example.com -git config user.name "Test User" -printf 'hello\n' > README.md -git add README.md -git commit -m "init" -cd .. -``` - -### 18E.2 CLI worktree flow - -```bash -python3 -m src.main worktree-status --cwd ./test_cases -python3 -m src.main worktree-enter preview --cwd ./test_cases -python3 -m src.main worktree-status --cwd ./test_cases -python3 -m src.main worktree-exit --action keep --cwd ./test_cases -``` - -### 18E.3 Slash commands - -```bash -python3 -m src.main agent "/worktree" --cwd ./test_cases -python3 -m src.main agent "/worktree enter preview" --cwd ./test_cases -python3 -m src.main agent "/worktree history" --cwd ./test_cases -python3 -m src.main agent "/worktree exit remove discard" --cwd ./test_cases -``` - -### 18E.4 Real agent cwd switch - -```bash -python3 -m src.main agent \ - "Create a managed worktree called preview, then write note.txt in the current working directory and summarize where the file was created." \ - --cwd ./test_cases \ - --allow-write \ - --show-transcript -``` - -### 18.2 Create and inspect tasks - -```bash -python3 -m src.main agent \ - "Create a task called Review runtime tasks, then list the current tasks." \ - --cwd ./test_cases_tasks \ - --allow-write \ - --show-transcript - -cat ./test_cases_tasks/.port_sessions/task_runtime.json -``` - -### 18.3 Replace the todo list - -```bash -python3 -m src.main agent \ - "Replace the current todo list with three tasks: inspect runtime, verify tests, and update docs. Mark inspect runtime as done and the others as todo." \ - --cwd ./test_cases_tasks \ - --allow-write \ - --show-transcript -``` - -### 18.4 Plan update and task sync - -```bash -python3 -m src.main agent \ - "Use update_plan to create three steps: inspect runtime, verify tests, update docs. Mark inspect runtime completed and sync to tasks." \ - --cwd ./test_cases_tasks \ - --allow-write \ - --show-transcript - -python3 -m src.main agent "/plan" --cwd ./test_cases_tasks -python3 -m src.main agent "/tasks" --cwd ./test_cases_tasks -cat ./test_cases_tasks/.port_sessions/plan_runtime.json -``` - -### 18.5 Dependency-aware task execution - -```bash -python3 -m src.main agent \ - "Use todo_write to create two tasks: scan with status pending, and patch with status blocked and blocked_by scan. Then show the next actionable tasks." \ - --cwd ./test_cases_tasks \ - --allow-write \ - --show-transcript - -python3 -m src.main agent \ - "Mark task scan as completed, then show the next actionable tasks and start task patch with active_form 'Patching files'." \ - --cwd ./test_cases_tasks \ - --allow-write \ - --show-transcript - -python3 -m src.main agent \ - "Block task patch with reason waiting on review, then cancel task patch and summarize the final task state." \ - --cwd ./test_cases_tasks \ - --allow-write \ - --show-transcript -``` - -### 18.6 Task execution tools directly - -```bash -python3 -m src.main agent \ - "Use todo_write to create task scan and task patch where patch is blocked_by scan. Then use task_next, task_complete for scan, task_start for patch, task_block for patch, and task_cancel for patch." \ - --cwd ./test_cases_tasks \ - --allow-write \ - --show-transcript -``` - -## 19. Plugin Runtime - -### 19.1 Plugin prompt and context discovery - -```bash -python3 -m src.main agent-prompt --cwd ./test_cases_plugins -python3 -m src.main agent-context-raw --cwd ./test_cases_plugins -``` - -### 19.2 Plugin alias tool - -```bash -python3 -m src.main agent \ - "Use the plugin_read tool to read hello.txt and summarize it." \ - --cwd ./test_cases_plugins \ - --show-transcript -``` - -### 19.3 Plugin virtual tool - -```bash -python3 -m src.main agent \ - "Use the demo_virtual tool with topic plugins and return the result." \ - --cwd ./test_cases_plugins \ - --show-transcript -``` - -### 19.4 Plugin before and after tool guidance - -```bash -python3 -m src.main agent \ - "Read hello.txt and follow the plugin guidance around the read_file tool." \ - --cwd ./test_cases_plugins \ - --show-transcript -``` - -### 19.5 Plugin block behavior - -```bash -python3 -m src.main agent \ - "Try to run bash and explain what the plugin blocked." \ - --cwd ./test_cases_plugins \ - --allow-shell \ - --show-transcript -``` - -### 19.6 Plugin lifecycle with resume and persist - -```bash -python3 -m src.main agent \ - "Use the plugin system and create a saved session." \ - --cwd ./test_cases_plugins - -python3 -m src.main agent-resume \ - \ - "Continue and mention any plugin lifecycle guidance you received." \ - --cwd ./test_cases_plugins \ - --show-transcript -``` - -Look for: - -- `plugin_before_persist` -- `Plugin resume hooks:` -- `Plugin runtime state:` - -## 20. Delegation, Batching, And Query Engine Runtime - -### 20.1 Basic delegated subtask - -```bash -python3 -m src.main agent \ - "Delegate a subtask to inspect src/agent_runtime.py and return the summary." \ - --cwd . \ - --show-transcript -``` - -### 20.2 Multiple delegated subtasks - -```bash -python3 -m src.main agent \ - "Delegate one subtask to scan the repository and another to summarize it after the scan." \ - --cwd . \ - --show-transcript -``` - -### 20.3 Resume a delegated child session - -```bash -python3 -m src.main agent \ - "Inspect src/agent_tools.py and give a short summary." \ - --cwd . - -python3 -m src.main agent \ - "Delegate a subtask that resumes session and continues it." \ - --cwd . \ - --show-transcript -``` - -### 20.4 Topological dependency batches - -```bash -python3 -m src.main agent \ - "Delegate two subtasks: one named scan, and one named summarize that depends on scan. Use topological batching and then return the final summary." \ - --cwd . \ - --show-transcript -``` - -Look for: - -- `delegate_batch_result` -- `delegate_group_result` -- `batch_index=...` - -### 20.5 Query-engine style helper commands - -```bash -python3 -m src.main summary -python3 -m src.main manifest -python3 -m src.main route "inspect the runtime and tools" --limit 10 -python3 -m src.main bootstrap "inspect the runtime and tools" --limit 10 -python3 -m src.main turn-loop "inspect the runtime and tools" --limit 5 --max-turns 3 -python3 -m src.main turn-loop "inspect the runtime and tools" --limit 5 --max-turns 3 --structured-output -``` - -## 21. Maintenance Rules - -Use this every time a new feature lands: - -```bash -python3 -m unittest discover -s tests -v -``` - -Then update: - -- `PARITY_CHECKLIST.md` -- `TESTING_GUIDE.md` - -Rule for future work: - -- every new implemented feature should add a checked item in `PARITY_CHECKLIST.md` -- every user-testable feature should add at least one concrete command example in `TESTING_GUIDE.md` diff --git a/claw-code-agent.md b/claw-code-agent.md deleted file mode 100644 index 97d0c4f..0000000 --- a/claw-code-agent.md +++ /dev/null @@ -1,845 +0,0 @@ -

- Claw Code Agent logo -

- -

Claw Code Agent

- -

- A Python reimplementation of the Claude Code agent architecture — local models, full control, zero dependencies. -

- -

- Python 3.10+ - GitHub - vLLM - Qwen3-Coder - Zero Dependencies - Alpha - License -

- ---- - -## 📢 What's New - -> **April 2026 — Major Update** - -| | Feature | Details | -|---|---------|---------| -| 🆕 | **Interactive Chat Mode** | New `agent-chat` command — multi-turn REPL with `/exit` to quit | -| 🆕 | **Streaming Output** | Token-by-token streaming with `--stream` flag | -| 🆕 | **Plugin Runtime** | Full manifest-based plugin system — hooks, tool aliases, virtual tools, tool blocking | -| 🆕 | **Nested Agent Delegation** | Delegate subtasks to child agents with dependency-aware topological batching | -| 🆕 | **Agent Manager** | Lineage tracking, group membership, batch summaries for nested agents | -| 🆕 | **Custom Agent Profiles** | Discover local markdown-defined agents from `~/.claude/agents` and `./.claude/agents` and use them through the `Agent` tool | -| 🆕 | **Cost Tracking & Budgets** | Token budgets, cost budgets, tool-call limits, model-call limits, session-turn limits | -| 🆕 | **Structured Output** | JSON schema response mode with `--response-schema-file` | -| 🆕 | **Context Compaction** | Auto-snip, auto-compact, and reactive compaction on prompt-too-long errors | -| 🆕 | **File History Replay** | Journaling of file edits with snapshot IDs, replay summaries on session resume | -| 🆕 | **Truncation Continuation** | Automatic continuation when model response is cut off (`finish_reason=length`) | -| 🆕 | **Ollama Support** | Works out of the box with Ollama's OpenAI-compatible API | -| 🆕 | **LiteLLM Proxy Support** | Route through LiteLLM Proxy to any provider | -| 🆕 | **OpenRouter Support** | Cloud API gateway — access OpenAI, Anthropic, Google models via one endpoint | -| 🆕 | **Query Engine** | Runtime event counters, transcript summaries, orchestration reports | -| 🆕 | **Remote Runtime** | Manifest-backed local remote profiles, connect/disconnect state, and remote CLI/slash flows | -| 🆕 | **Hook & Policy Runtime** | Local `.claw-policy.json` / hook manifests with trust reporting, safe env, tool blocking, and budget overrides | -| 🆕 | **Task & Plan Runtime** | Persistent local tasks and plans with plan-to-task sync and dependency-aware task execution | -| 🆕 | **MCP Transport** | Real stdio MCP transport for `initialize`, resource listing/reading, and tool listing/calling | -| 🆕 | **Search Runtime** | Provider-backed `web_search` with local manifests, activation state, and `/search` flows | -| 🆕 | **Config & Account Runtime** | Local config/settings mutation plus manifest-backed account profiles and login/logout state | -| 🆕 | **Ask-User Runtime** | Queued or interactive local ask-user flow with history, slash commands, and agent tool support | -| 🆕 | **Team Runtime** | Persisted local teams and message history with team/message tools and slash/CLI inspection | -| 🆕 | **Notebook Edit Tool** | Native `.ipynb` cell editing through the real agent tool registry | -| 🆕 | **Workflow Runtime** | Manifest-backed local workflows with workflow tools, slash commands, and run history | -| 🆕 | **Remote Trigger Runtime** | Local remote triggers with create/update/run flows similar to the npm remote trigger surface | -| 🆕 | **Worktree Runtime** | Managed git worktrees with mid-session cwd switching, slash commands, and CLI flows | -| 🆕 | **Tokenizer-Aware Context** | Cached tokenizer backends with heuristic fallback for `/context`, `/status`, and compaction | -| 🆕 | **Prompt Budget Preflight** | Preflight prompt-length validation, token-budget reporting, and auto-compact/context collapse before backend failures | -| 🆕 | **LSP Runtime** | Local LSP-style code intelligence for definitions, references, hover, symbols, call hierarchy, and diagnostics | -| 🆕 | **Local Web GUI** | Browser-based chat UI via `python -m src.gui` — modern dark theme, slash command palette, session browser, settings panel | -| 🆕 | **Daemon Commands** | Local `daemon start/ps/logs/attach/kill` wrapper over background agent sessions | -| 🆕 | **Background Sessions** | Local `agent-bg`, `agent-ps`, `agent-logs`, `agent-attach`, and `agent-kill` flows | -| 🆕 | **Testing Guide** | Comprehensive [TESTING_GUIDE.md](TESTING_GUIDE.md) with commands for every feature | -| 🆕 | **Parity Checklist** | Full [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md) tracking implementation status vs npm source | - ---- - -## 📖 About - -This repository reimplements the [Claude Code](https://docs.anthropic.com/en/docs/claude-code) npm agent architecture **entirely in Python**, designed to run with **local open-source models** via an OpenAI-compatible API server. - -Built on the public porting workspace from [instructkr/claw-code](https://github.com/instructkr/claw-code), the active development lives at [HarnessLab/claw-code-agent](https://github.com/HarnessLab/claw-code-agent). - -> **Goal:** Not to ship the original npm source, but to reimplement the full agent flow in Python — prompt assembly, context building, slash commands, tool calling, session persistence, and local model execution. -> -> **Zero external dependencies** — just Python's standard library. - -

- Claw Code Agent demo -

- ---- - -## ✨ Key Features - -| Feature | Description | -|---------|-------------| -| 🤖 **Agent Loop** | Full agentic coding loop with tool calling and iterative reasoning | -| 💬 **Interactive Chat** | Multi-turn REPL via `agent-chat` with session continuity | -| 🖥️ **Local Web GUI** | Browser-based chat UI launched with `python -m src.gui` — sessions browser, slash command palette, live settings | -| 🧰 **Core Tools** | File read / write / edit, glob search, grep search, shell execution | -| 🔌 **Plugin Runtime** | Manifest-based plugins with hooks, aliases, virtual tools, and tool blocking | -| 🪆 **Nested Delegation** | Delegate subtasks to child agents with dependency-aware topological batching | -| 🧩 **Custom Agents** | Load local agent profiles from `~/.claude/agents` and `./.claude/agents`, inspect them via `/agents`, and delegate with `subagent_type` | -| 📡 **Streaming** | Token-by-token streaming output with `--stream` | -| 💬 **Slash Commands** | Local commands for context, config, account, search, MCP, remote, tasks, plan, hooks, and model control | -| 🌐 **Remote Runtime** | Manifest-backed remote profiles with local `remote-mode`, `ssh-mode`, `teleport-mode`, and connect/disconnect state | -| 🧭 **Task & Plan Runtime** | Persistent tasks and plans with sync, next-task selection, and blocked/unblocked state | -| 🛰️ **MCP Runtime** | Local MCP manifests plus real stdio MCP transport for resources and tools | -| 🔎 **Search Runtime** | Provider-backed `web_search` plus provider activation and status reporting | -| ⚙️ **Config & Account Runtime** | Local config mutation, settings inspection, account profiles, and login/logout state | -| 🙋 **Ask-User Runtime** | Queued answer or interactive user-question flow with history tracking | -| 👥 **Team Runtime** | Persisted local teams plus message history, handoff notes, and collaboration metadata | -| 📓 **Notebook Editing** | Native Jupyter notebook cell editing through `notebook_edit` | -| 🪵 **Worktree Runtime** | Managed git worktrees with `worktree_enter`, `worktree_exit`, and live cwd switching | -| 🧭 **Workflow Runtime** | Manifest-backed workflows with slash commands, CLI inspection, and recorded runs | -| ⏰ **Remote Triggers** | Local remote triggers with create/update/run flows and npm-style trigger actions | -| 🪝 **Hook & Policy Runtime** | Trust reporting, safe env, managed settings, tool blocking, and budget overrides | -| 🧠 **LSP Code Intelligence** | Local LSP-style definitions, references, hover, symbols, diagnostics, and call hierarchy | -| 🧠 **Context Engine** | Automatic context building with CLAUDE.md discovery, compaction, and snipping | -| 🔢 **Tokenizer-Aware Accounting** | Model-aware token counting with cached tokenizer backends and fallback heuristics | -| 📏 **Prompt Budgeting** | Soft/hard prompt-window checks, token-budget reports, and preflight context collapse | -| 🔄 **Session Persistence** | Save and resume agent sessions with file-history replay | -| 🗂️ **Background Sessions** | `agent-bg` and local daemon wrappers for background runs, logs, attach, and kill | -| 💰 **Cost & Budget Control** | Token budgets, cost limits, tool-call caps, model-call caps | -| 📋 **Structured Output** | JSON schema response mode for programmatic use | -| 🔐 **Permission System** | Granular control: `--allow-write`, `--allow-shell`, `--unsafe` | -| 🏗️ **OpenAI-Compatible** | Works with vLLM, Ollama, LiteLLM Proxy, OpenRouter — any OpenAI-compatible API | -| 🐉 **Qwen3-Coder** | First-class support for `Qwen3-Coder-30B-A3B-Instruct` via vLLM | -| 📦 **Zero Dependencies** | Pure Python standard library — nothing to install | - ---- - -## 📋 Roadmap - -### 📚 Documentation - -| Document | Description | -|----------|-------------| -| [TESTING_GUIDE.md](TESTING_GUIDE.md) | Step-by-step commands to verify every feature | -| [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md) | Full implementation status vs the npm source | - -### ✅ Done - -- [x] Python CLI agent loop -- [x] Interactive chat mode (`agent-chat`) with multi-turn REPL -- [x] OpenAI-compatible local model backend -- [x] Qwen3-Coder support through vLLM with `qwen3_xml` tool parser -- [x] Ollama, LiteLLM Proxy, and OpenRouter backends -- [x] Core tools: `list_dir`, `read_file`, `write_file`, `edit_file`, `glob_search`, `grep_search`, `bash` -- [x] Context building and `/context`-style usage reporting -- [x] Slash commands: `/help`, `/context`, `/context-raw`, `/token-budget`, `/prompt`, `/permissions`, `/model`, `/tools`, `/agents`, `/memory`, `/status`, `/clear` -- [x] Session persistence and `agent-resume` flow -- [x] Permission system (read-only, write, shell, unsafe tiers) -- [x] Streaming token-by-token assistant output -- [x] Truncated-response continuation flow -- [x] Auto-snip and auto-compact context reduction -- [x] Reactive compaction retry on prompt-too-long errors -- [x] Preflight prompt-length validation and token-budget reporting -- [x] Preflight auto-compact/context collapse before backend prompt-too-long failures -- [x] Cost tracking and usage budget enforcement -- [x] Token, tool-call, model-call, and session-turn budgets -- [x] Structured output / JSON schema response mode -- [x] File history journaling with snapshot IDs and replay summaries -- [x] Nested agent delegation with dependency-aware topological batching -- [x] Agent manager with lineage tracking and group membership -- [x] Filesystem-backed custom agent profiles with built-in/user/project precedence -- [x] Local custom-agent create/update/delete flows via CLI and `/agents` -- [x] Local daemon-style background command family -- [x] Local background session workflows: `agent-bg`, `agent-ps`, `agent-logs`, `agent-attach`, `agent-kill` -- [x] Local remote runtime: manifest discovery, profile listing, connect/disconnect persistence, and CLI/slash flows -- [x] Local hook and policy runtime with trust reporting, safe env, tool blocking, and budget overrides -- [x] Local config runtime: config discovery, effective settings, source inspection, and config mutation -- [x] Local LSP runtime: definitions, references, hover, symbols, diagnostics, and call hierarchy -- [x] Local account runtime: profile discovery, login/logout state, and account CLI/slash flows -- [x] Local ask-user runtime: queued answers, history, and ask-user CLI/slash flows -- [x] Local team runtime: persisted teams, team messages, and team CLI/slash flows -- [x] Local search runtime with provider discovery, activation, and provider-backed `web_search` -- [x] Local MCP runtime: manifest resources, stdio transport, MCP resources, and MCP tool calls -- [x] Local task and plan runtimes with plan sync and dependency-aware task execution -- [x] Notebook edit tool in the real Python tool registry -- [x] Local workflow runtime with workflow list/get/run tools and CLI/slash flows -- [x] Local remote trigger runtime with create/update/run flows and CLI/slash inspection -- [x] Local managed git worktree runtime with live cwd switching and worktree CLI/slash flows -- [x] Local web GUI (FastAPI + vanilla JS SPA) with chat, sessions browser, slash command palette, and live settings (`python -m src.gui`) -- [x] Tokenizer-aware context accounting with cached tokenizer backends and heuristic fallback -- [x] Plugin runtime: manifest discovery, hooks, aliases, virtual tools, tool blocking -- [x] Plugin lifecycle hooks: resume, persist, delegate phases -- [x] Plugin session-state persistence and resume restoration -- [x] Query engine facade driving the real Python runtime -- [x] Compaction metadata with lineage IDs and revision summaries -- [x] Extended runtime tools: `web_fetch`, `web_search`, `tool_search`, `sleep` -- [x] Unit tests for the Python runtime -- [x] `pyproject.toml` packaging with `setuptools` - -### 🔲 In Progress - -- [ ] Full MCP parity beyond the current stdio transport and local manifest/resource/tool support -- [ ] Full slash-command parity with npm runtime -- [ ] Full interactive REPL / TUI behavior -- [ ] Full tokenizer/chat-message framing parity beyond the current tokenizer-aware accounting -- [ ] Hooks system parity -- [ ] Real remote transport/runtime parity beyond the current local remote-profile runtime -- [ ] Voice and VIM modes -- [ ] Editor and platform integrations -- [ ] Background and team features - ---- - -## 🏗️ Architecture - -```text -claw-code/ -├── README.md -├── TESTING_GUIDE.md # How to test every feature -├── PARITY_CHECKLIST.md # Implementation status vs npm source -├── pyproject.toml -├── .gitignore -├── images/ -│ └── logo.png -├── src/ # Python implementation -│ ├── main.py # CLI entry point & argument parsing -│ ├── agent_runtime.py # Core agent loop (LocalCodingAgent) -│ ├── agent_tools.py # Tool definitions & execution engine -│ ├── agent_prompting.py # System prompt assembly -│ ├── agent_registry.py # Built-in + filesystem-backed custom agent discovery -│ ├── agent_context.py # Context building & CLAUDE.md discovery -│ ├── agent_context_usage.py # Context usage estimation & reporting -│ ├── agent_session.py # Session state management -│ ├── agent_slash_commands.py # Local slash command processing -│ ├── agent_manager.py # Nested agent lineage & group tracking -│ ├── agent_types.py # Shared dataclasses & type definitions -│ ├── openai_compat.py # OpenAI-compatible API client (streaming) -│ ├── plugin_runtime.py # Plugin manifest, hooks, aliases, virtual tools -│ ├── agent_plugin_cache.py # Plugin discovery & prompt injection cache -│ ├── session_store.py # Session serialization & persistence -│ ├── transcript.py # Transcript block export & mutation tracking -│ ├── query_engine.py # Query engine facade & runtime orchestration -│ ├── mcp_runtime.py # Local MCP discovery and stdio MCP transport -│ ├── search_runtime.py # Search providers and provider-backed web_search -│ ├── remote_runtime.py # Local remote profiles, connect/disconnect state, remote CLI support -│ ├── background_runtime.py # Local background sessions and daemon support -│ ├── account_runtime.py # Local account profiles, login/logout state, account CLI support -│ ├── ask_user_runtime.py # Local ask-user queued answers and interaction history -│ ├── config_runtime.py # Local workspace config/settings discovery and mutation -│ ├── lsp_runtime.py # Local LSP-style code intelligence and diagnostics -│ ├── token_budget.py # Prompt-window budgeting and preflight prompt-length validation -│ ├── plan_runtime.py # Persistent plan runtime and plan sync -│ ├── task_runtime.py # Persistent task runtime and task execution -│ ├── task.py # Task state model and task dataclasses -│ ├── team_runtime.py # Local teams, messages, and collaboration metadata -│ ├── workflow_runtime.py # Local workflow manifests and recorded workflow runs -│ ├── remote_trigger_runtime.py # Local remote trigger manifests and trigger run history -│ ├── worktree_runtime.py # Managed git worktree sessions and cwd switching -│ ├── hook_policy.py # Hook/policy manifests, trust, and safe env handling -│ ├── tokenizer_runtime.py # Tokenizer-aware context accounting backends -│ ├── permissions.py # Tool permission filtering -│ ├── cost_tracker.py # Cost & budget enforcement -│ ├── commands.py # Mirrored command inventory -│ ├── tools.py # Mirrored tool inventory -│ ├── runtime.py # Mirrored runtime facade -│ ├── reference_data/ # Mirrored inventory snapshots -│ └── gui/ # Local web GUI (FastAPI + vanilla JS SPA) -│ ├── __main__.py # `python -m src.gui` entry point -│ ├── server.py # FastAPI app and JSON endpoints -│ └── static/ # index.html, app.css, app.js -└── tests/ # Unit tests - ├── test_agent_runtime.py - ├── test_agent_context.py - ├── test_agent_context_usage.py - ├── test_agent_prompting.py - ├── test_agent_slash_commands.py - ├── test_main.py - ├── test_query_engine_runtime.py - └── test_porting_workspace.py -``` - ---- - -## 📦 Requirements - -| Requirement | Details | -|-------------|---------| -| 🐍 Python | `3.10` or higher | -| 📚 Dependencies | **None** — pure Python standard library | -| 🖥️ Model Server | `vLLM`, `Ollama`, `LiteLLM Proxy`, or `OpenRouter`, with tool calling support | -| 🧠 Model | [`Qwen/Qwen3-Coder-30B-A3B-Instruct`](https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct) (recommended) | - ---- - -## 🚀 Quick Start - -### 1. Start vLLM with Qwen3-Coder - -vLLM must be started with automatic tool choice enabled. Use the `qwen3_xml` parser for Qwen3-Coder tool calling: - -```bash -python -m vllm.entrypoints.openai.api_server \ - --model Qwen/Qwen3-Coder-30B-A3B-Instruct \ - --host 127.0.0.1 \ - --port 8000 \ - --enable-auto-tool-choice \ - --tool-call-parser qwen3_xml -``` - -Verify the server is running: - -```bash -curl http://127.0.0.1:8000/v1/models -``` - -> 📚 **References:** [vLLM Tool Calling Docs](https://docs.vllm.ai/en/v0.13.0/features/tool_calling/) · [OpenAI-Compatible Server](https://docs.vllm.ai/en/v0.13.0/serving/openai_compatible_server.html) - -### Optional: Use Ollama Instead of vLLM - -`claw-code-agent` can also work with Ollama because the runtime targets an OpenAI-compatible API. Use a model that supports tool calling well. - -Example: - -```bash -ollama serve -ollama pull qwen3 -``` - -Then configure: - -```bash -export OPENAI_BASE_URL=http://127.0.0.1:11434/v1 -export OPENAI_API_KEY=ollama -export OPENAI_MODEL=qwen3 -``` - -Notes: - -- prefer tool-capable models such as `qwen3` -- plain chat-only models are not enough for full agent behavior -- Ollama does not use the `vLLM` parser flags shown above - -> 📚 **References:** [Ollama OpenAI Compatibility](https://docs.ollama.com/api/openai-compatibility) · [Ollama Tool Calling](https://docs.ollama.com/capabilities/tool-calling) - -### Optional: Use LiteLLM Proxy - -`claw-code-agent` can also work through LiteLLM Proxy because the runtime targets an OpenAI-compatible chat completions API. The routed model still needs to support tool calling for full agent behavior. - -Quick start example: - -```bash -pip install 'litellm[proxy]' -litellm --model ollama/qwen3 -``` - -LiteLLM Proxy runs on port `4000` by default. Then configure: - -```bash -export OPENAI_BASE_URL=http://127.0.0.1:4000 -export OPENAI_API_KEY=anything -export OPENAI_MODEL=ollama/qwen3 -``` - -Notes: - -- LiteLLM Proxy gives you an OpenAI-style gateway in front of many providers -- tool use still depends on the underlying routed model and provider behavior -- if you configure a LiteLLM master key, use that instead of `anything` - -> 📚 **References:** [LiteLLM Docs](https://docs.litellm.ai/) · [LiteLLM Proxy Quick Start](https://docs.litellm.ai/) - -### Optional: Use OpenRouter - -`claw-code-agent` can also work with [OpenRouter](https://openrouter.ai/), a cloud API gateway that provides access to models from OpenAI, Anthropic, Google, Meta, and others through a single OpenAI-compatible endpoint. No local model server required. - -Configure: - -```bash -export OPENAI_BASE_URL=https://openrouter.ai/api/v1 -export OPENAI_API_KEY=sk-or-v1-your-key-here -export OPENAI_MODEL=openai/gpt-4o-mini -``` - -Notes: - -- sign up at [openrouter.ai](https://openrouter.ai/) and create an API key under [Keys](https://openrouter.ai/keys) -- model names use the `provider/model` format (e.g. `anthropic/claude-sonnet-4`, `openai/gpt-4o`, `google/gemini-2.5-pro`) -- tool calling support varies by model — check the [model list](https://openrouter.ai/models) for capabilities -- this sends your conversation (including file contents and shell output) to OpenRouter and the upstream provider — do not use with repos containing secrets or sensitive data - -> 📚 **References:** [OpenRouter Docs](https://openrouter.ai/docs) · [Supported Models](https://openrouter.ai/models) · [API Keys](https://openrouter.ai/keys) - -### 2. Configure Environment - -```bash -export OPENAI_BASE_URL=http://127.0.0.1:8000/v1 -export OPENAI_API_KEY=local-token -export OPENAI_MODEL=Qwen/Qwen3-Coder-30B-A3B-Instruct -``` - -### Use Another Model With vLLM - -If you want to try another model, keep the same `vLLM` server setup and change the `--model` value when you launch `vLLM`. - -Example: - -```bash -python -m vllm.entrypoints.openai.api_server \ - --model your-model-name \ - --host 127.0.0.1 \ - --port 8000 \ - --enable-auto-tool-choice \ - --tool-call-parser your_parser -``` - -Then update: - -```bash -export OPENAI_MODEL=your-model-name -``` - -Notes: - -- the documented path in this repository is `vLLM` -- the model must support tool calling well enough for agent use -- some model families require a different `--tool-call-parser` -- slash commands such as `/help`, `/context`, and `/tools` are local and do not require the model server - -### 3. Run the Agent - -```bash -# Read-only question -python3 -m src.main agent \ - "Read src/agent_runtime.py and summarize how the loop works." \ - --cwd . - -# Write-enabled task -python3 -m src.main agent \ - "Create TEST_QWEN_AGENT.md with one line: test ok" \ - --cwd . --allow-write - -# Shell-enabled task -python3 -m src.main agent \ - "Run pwd and ls src, then summarize the result." \ - --cwd . --allow-shell - -# Interactive chat mode -python3 -m src.main agent-chat --cwd . - -# Streaming output -python3 -m src.main agent \ - "Explain the current architecture." \ - --cwd . --stream -``` - ---- - -## 🛠️ Usage - -### Agent Commands - -| Command | Description | -|---------|-------------| -| `agent ` | Run the agent with a prompt | -| `agent-chat [prompt]` | Start interactive multi-turn chat mode | -| `agent-bg ` | Run the agent in a local background session | -| `agent-ps` | List local background sessions | -| `agent-logs ` | Show background session logs | -| `agent-attach ` | Show the current background output snapshot | -| `agent-kill ` | Stop a background session | -| `daemon ` | Daemon-style wrapper over local background sessions | -| `agent-prompt` | Show the assembled system prompt | -| `agent-context` | Show estimated context usage | -| `agent-context-raw` | Show the raw context snapshot | -| `token-budget` | Show prompt-window budget, reserves, and soft/hard input limits | -| `agents [agent_type]` | List active local agent definitions or show one agent profile | -| `agents-create ` | Create a project or user agent definition markdown file | -| `agents-update ` | Update an existing project or user agent definition | -| `agents-delete ` | Delete an existing project or user agent definition | -| `agent-resume ` | Resume a saved session | - -### Runtime Utility Commands - -| Command | Description | -|---------|-------------| -| `search-status` / `search-providers` / `search-activate` / `search` | Inspect and use the local search runtime | -| `mcp-status` / `mcp-resources` / `mcp-resource` / `mcp-tools` / `mcp-call-tool` | Inspect and use the local MCP runtime | -| `remote-status` / `remote-profiles` / `remote-disconnect` | Inspect local remote runtime state | -| `remote-mode` / `ssh-mode` / `teleport-mode` / `direct-connect-mode` / `deep-link-mode` | Activate local remote runtime modes | -| `config-status` / `config-effective` / `config-source` / `config-get` / `config-set` | Inspect and mutate local config/settings | -| `account-status` / `account-profiles` / `account-login` / `account-logout` | Inspect and mutate local account state | - -### CLI Flags - -| Flag | Description | -|------|-------------| -| `--cwd ` | Set the workspace directory | -| `--model ` | Override the model name | -| `--base-url ` | Override the API base URL | -| `--allow-write` | Allow the agent to modify files | -| `--allow-shell` | Allow the agent to execute shell commands | -| `--unsafe` | Allow destructive shell operations | -| `--stream` | Enable token-by-token streaming output | -| `--show-transcript` | Print the full message transcript | -| `--scratchpad-root ` | Override the scratchpad directory | -| `--system-prompt ` | Set a custom system prompt | -| `--append-system-prompt ` | Append to the system prompt | -| `--override-system-prompt ` | Replace the generated system prompt | -| `--add-dir ` | Add extra directories to context | - -### Budget & Limit Flags - -| Flag | Description | -|------|-------------| -| `--max-total-tokens ` | Total token budget | -| `--max-input-tokens ` | Input token budget | -| `--max-output-tokens ` | Output token budget | -| `--max-reasoning-tokens ` | Reasoning token budget | -| `--max-budget-usd ` | Maximum cost in USD | -| `--max-tool-calls ` | Maximum tool calls per run | -| `--max-delegated-tasks ` | Maximum delegated subtasks | -| `--max-model-calls ` | Maximum model API calls | -| `--max-session-turns ` | Maximum session turns | -| `--input-cost-per-million ` | Input token pricing | -| `--output-cost-per-million ` | Output token pricing | - -### Context Control Flags - -| Flag | Description | -|------|-------------| -| `--auto-snip-threshold ` | Auto-snip older messages at this token count | -| `--auto-compact-threshold ` | Auto-compact at this token count | -| `--compact-preserve-messages ` | Messages to preserve during compaction | -| `--disable-claude-md` | Disable CLAUDE.md discovery | - -### Structured Output Flags - -| Flag | Description | -|------|-------------| -| `--response-schema-file ` | JSON schema file for structured output | -| `--response-schema-name ` | Schema name identifier | -| `--response-schema-strict` | Enforce strict schema validation | - -### Slash Commands - -These are handled **locally** before the model loop: - -| Command | Aliases | Description | -|---------|---------|-------------| -| `/help` | `/commands` | Show built-in slash commands | -| `/context` | `/usage` | Show estimated session context usage | -| `/context-raw` | `/env` | Show raw environment & context snapshot | -| `/token-budget` | `/budget` | Show prompt-window budget, reserves, and soft/hard input limits | -| `/mcp` | — | Show MCP runtime status, tools, or a single MCP tool | -| `/resources` | — | List MCP resources | -| `/resource` | — | Read an MCP resource by URI | -| `/search` | — | Show search status, providers, activate a provider, or run a search | -| `/remote` | — | Show local remote status or activate a target | -| `/remotes` | — | List local remote profiles | -| `/ssh` | — | Activate an SSH-style remote profile | -| `/teleport` | — | Activate a teleport-style remote profile | -| `/direct-connect` | — | Activate a direct-connect remote profile | -| `/deep-link` | — | Activate a deep-link remote profile | -| `/disconnect` | `/remote-disconnect` | Disconnect the active remote runtime target | -| `/account` | — | Show account runtime status or profiles | -| `/login` | — | Activate a local account profile or identity | -| `/logout` | — | Clear the active account session | -| `/config` | `/settings` | Inspect effective config, sources, or a single config value | -| `/plan` | `/planner` | Show the local plan runtime state | -| `/tasks` | `/todo` | Show the local task list | -| `/task` | — | Show a task by id | -| `/task-next` | `/next-task` | Show the next actionable tasks | -| `/prompt` | `/system-prompt` | Render the effective system prompt | -| `/hooks` | `/policy` | Show local hook/policy manifests | -| `/trust` | — | Show trust mode, managed settings, and safe env values | -| `/permissions` | — | Show active tool permission mode | -| `/model` | — | Show or update the active model | -| `/tools` | — | List registered tools with permission status | -| `/agents` | — | List, show, create, update, or delete local agent definitions | -| `/memory` | — | Show loaded CLAUDE.md memory bundle | -| `/status` | `/session` | Show runtime/session status summary | -| `/clear` | — | Clear ephemeral runtime state | - -```bash -python3 -m src.main agent "/help" -python3 -m src.main agent "/context" --cwd . -python3 -m src.main agent "/token-budget" --cwd . -python3 -m src.main agent "/tools" --cwd . -python3 -m src.main agent "/agents" --cwd . -python3 -m src.main agent "/status" --cwd . -``` - -### Custom Agent Definitions - -Custom agent profiles can live in either of these directories: - -- `./.claude/agents/*.md` -- `~/.claude/agents/*.md` - -Project agents override user agents, and user agents override built-ins when the `agent_type` matches. - -Example agent file: - -```md ---- -name: reviewer -description: "Review implementation changes carefully." -tools: read_file, grep_search -model: Qwen/Qwen3-Coder-30B-A3B-Instruct -initialPrompt: Start by identifying the highest-risk files. ---- - -Inspect code changes and summarize correctness risks, regressions, and missing tests. -``` - -Inspect the loaded profiles: - -```bash -python3 -m src.main agents --cwd . -python3 -m src.main agents reviewer --cwd . -python3 -m src.main agent "/agents" --cwd . -python3 -m src.main agent "/agents show reviewer" --cwd . -``` - -Create, update, or delete agent files from the CLI: - -```bash -python3 -m src.main agents-create reviewer \ - --cwd . \ - --description "Review implementation changes carefully." \ - --prompt "Inspect code changes and summarize risks." \ - --tools read_file,grep_search \ - --model Qwen/Qwen3-Coder-30B-A3B-Instruct - -python3 -m src.main agents-update reviewer \ - --cwd . \ - --description "Review implementation changes and tests carefully." \ - --prompt "Focus on regressions, missing tests, and risky diffs." - -python3 -m src.main agents-delete reviewer --cwd . --source project -``` - -Or use the local slash command management forms: - -```bash -python3 -m src.main agent "/agents create reviewer :: Review implementation changes carefully. :: Inspect code changes and summarize risks." --cwd . -python3 -m src.main agent "/agents update reviewer Updated review description :: Focus on regressions and missing tests." --cwd . -python3 -m src.main agent "/agents delete reviewer" --cwd . -``` - -### Utility Commands - -```bash -python3 -m src.main summary # Workspace summary -python3 -m src.main manifest # Workspace manifest -python3 -m src.main commands --limit 10 # Command inventory -python3 -m src.main tools --limit 10 # Tool inventory -``` - ---- - -## 🔧 Built-in Tools - -The runtime currently includes core and extended tools: - -| Tool | Description | Permission | -|------|-------------|------------| -| `list_dir` | List files and directories | 🟢 Always | -| `read_file` | Read file contents (with line ranges) | 🟢 Always | -| `write_file` | Write or create files | 🟡 `--allow-write` | -| `edit_file` | Edit files via exact string matching | 🟡 `--allow-write` | -| `glob_search` | Find files by glob pattern | 🟢 Always | -| `grep_search` | Search file contents by regex | 🟢 Always | -| `bash` | Execute shell commands | 🔴 `--allow-shell` | -| `web_fetch` | Fetch local or remote text content by URL | 🟢 Always | -| `search_status` / `search_list_providers` / `search_activate_provider` / `web_search` | Search runtime status and provider-backed web search | 🟢 Always | -| `tool_search` | Search the current Python tool registry | 🟢 Always | -| `sleep` | Bounded local wait tool | 🟢 Always | -| `config_list` / `config_get` / `config_set` | Inspect and mutate local workspace config | `config_set` is 🟡 `--allow-write` | -| `account_status` / `account_list_profiles` / `account_login` / `account_logout` | Inspect and mutate local account state | 🟢 Always | -| `remote_status` / `remote_list_profiles` / `remote_connect` / `remote_disconnect` | Inspect and mutate local remote runtime state | 🟢 Always | -| `mcp_list_resources` / `mcp_read_resource` / `mcp_list_tools` / `mcp_call_tool` | Use local MCP resources and transport-backed MCP tools | 🟢 Always | -| `plan_get` / `update_plan` / `plan_clear` | Inspect and mutate the local plan runtime | `update_plan` is 🟡 `--allow-write` | -| `task_next` / `task_list` / `task_get` / `task_create` / `task_update` / `task_start` / `task_complete` / `task_block` / `task_cancel` / `todo_write` | Persistent local task and todo management | write-like task mutations are 🟡 `--allow-write` | -| `delegate_agent` | Delegate work to nested child agents | 🟢 Always | - ---- - -## 🔌 Plugin System - -Claw Code Agent supports a **manifest-based plugin runtime**. Drop a `plugin.json` in a `plugins/` subdirectory: - -```json -{ - "name": "my-plugin", - "hooks": { - "beforePrompt": "Inject guidance into the system prompt.", - "afterTurn": "Run after each agent turn.", - "onResume": "Reapply state on session resume.", - "beforePersist": "Save state before session is saved.", - "beforeDelegate": "Inject guidance before child agents.", - "afterDelegate": "Process child agent results." - }, - "toolAliases": [ - { "name": "my_read", "baseTool": "read_file", "description": "Custom read alias." } - ], - "virtualTools": [ - { "name": "my_tool", "description": "A virtual tool.", "responseTemplate": "result: {input}" } - ] -} -``` - -> See [TESTING_GUIDE.md](TESTING_GUIDE.md) **Section 19** for full plugin testing commands. - ---- - -## 🪆 Nested Agent Delegation - -The agent can delegate subtasks to child agents with full context carryover: - -```bash -python3 -m src.main agent \ - "Delegate a subtask to inspect src/agent_runtime.py and return a summary." \ - --cwd . --show-transcript -``` - -Features: -- Sequential and parallel subtask execution -- Dependency-aware topological batching -- Child-session save and resume -- Agent manager lineage tracking - -> See [TESTING_GUIDE.md](TESTING_GUIDE.md) **Section 20** for delegation testing commands. - ---- - -## 🖥️ Local Web GUI - -If the terminal isn't your thing, launch the bundled browser GUI: - -```bash -python3 -m src.gui --cwd . --allow-write --allow-shell -``` - -Your default browser opens to `http://127.0.0.1:8765` with a modern dark-themed chat UI. - -| Flag | Description | -|------|-------------| -| `--host ` | Bind address (default `127.0.0.1`) | -| `--port ` | Port to listen on (default `8765`) | -| `--cwd ` | Workspace directory the agent operates in | -| `--model ` | Override the model name | -| `--base-url ` | Override the OpenAI-compatible API base URL | -| `--api-key ` | API key for the model server | -| `--session-dir ` | Where saved sessions live | -| `--allow-write` | Allow file write/edit tools | -| `--allow-shell` | Allow shell execution | -| `--no-browser` | Don't auto-open a browser tab | - -The GUI surfaces: - -- multi-turn chat with tool-call cards (collapsible JSON args + results) -- saved sessions sidebar with one-click resume -- slash command and skill pickers (`/` and `★` buttons, or `Cmd/Ctrl+K`) -- live settings panel (model, base URL, working dir, permissions) -- usage / cost meta in the composer footer - -> **Note:** The GUI uses [FastAPI](https://fastapi.tiangolo.com/) and [Uvicorn](https://www.uvicorn.org/) under the hood. These get installed automatically if you install the package via `pip install -e .`. The core Python agent runtime itself remains dependency-free. - ---- - -## 🔄 Session Persistence - -Each `agent` run automatically saves a resumable session: - -```text -session_id=4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67 -session_path=.port_sessions/agent/4f2c8c6f... -``` - -Resume a previous session: - -```bash -python3 -m src.main agent-resume \ - 4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67 \ - "Continue the previous task and finish the missing parts." -``` - -Resume directly into interactive chat: - -```bash -python3 -m src.main agent-chat \ - --resume-session-id \ - --cwd . -``` - -Inspect saved sessions: - -```bash -ls -lt .port_sessions/agent -``` - -> **Note:** Run `agent-resume` from the same `claw-code/` directory where the session was created. A resumed session continues from the saved transcript, not from scratch. - ---- - -## 🧪 Testing - -Run the full test suite: - -```bash -python3 -m unittest discover -s tests -v -``` - -Smoke tests: - -```bash -python3 -m src.main agent "/help" -python3 -m src.main agent-context --cwd . -python3 -m src.main agent \ - "Read src/agent_session.py and summarize the message flow." \ - --cwd . -``` - -> 📚 **Full testing guide:** See [TESTING_GUIDE.md](TESTING_GUIDE.md) for step-by-step commands covering the full implemented runtime surface. - ---- - -## 🔐 Permission Model - -Claw Code Agent uses a **tiered permission system** to keep the agent safe by default: - -| Tier | Capability | Flag Required | -|------|-----------|---------------| -| **Read-only** | List, read, glob, grep | None (default) | -| **Write** | + file creation and editing | `--allow-write` | -| **Shell** | + shell command execution | `--allow-shell` | -| **Unsafe** | + destructive shell operations | `--unsafe` | - ---- - -## 🔎 Parity Status - -The full implementation checklist tracking parity against the npm `src` lives in [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md). - -It covers: core runtime, CLI modes, prompt assembly, context/memory, slash commands, tools, permissions, plugins, MCP, REPL/TUI, remote features, editor integrations, and internal subsystems. - ---- - -## ⚠️ Disclaimer - -- This repository is a **Python reimplementation** inspired by the Claude Code npm architecture. -- It does **not** ship the original npm source. -- It is **not** affiliated with or endorsed by Anthropic. - ---- - -

- Built with 🐍 Python · Powered by 🐉 HarnessLab Team. -

diff --git a/data_agent_v0.md b/data_agent_v0.md deleted file mode 100644 index 22b0896..0000000 --- a/data_agent_v0.md +++ /dev/null @@ -1,391 +0,0 @@ -中控数据Agent构建-汇报 - Badcase 反馈渠道接入与自动收集分析:数据挖掘Agent设计方案 -1. 背景与目标 -- 数据开发是中控核心工作之一，但当前流程仍以人工驱动为主。 -- 需求 / badcase 驱动的评测集构建、样本补充和线上挖掘链路分散，人工介入重、复用性差。 -- 结合近期 AI native 工作方式转变，我们希望基于 Agent 底座先打通最小数据开发闭环。 -当前方式的瓶颈与挑战： -- 人工驱动重：从需求、badcase 到评测集构建，多个关键环节依赖人工推进。 -- 流程割裂重：人工构造、线上挖掘、LLM 生成彼此分散，数据格式转换和整理成本高。 -- 经验复用弱：边界判断和处理经验难以沉淀，导致新问题进入后仍需重复劳动。 -数据开发范式转变： -[图片] -2. AI Native数据Agent -不是做一个固定流程平台，而是做一个 Agent-native 的数据开发工作台。 -让 Agent 能够围绕一个需求 / badcase，自主理解问题、探索数据、发现边界冲突、提出人工裁决问题、生成评测集候选、沉淀长期经验，从而显著提升路由评测 / 训练数据构建效率。 - ---- -2.1 设计目标与边界 -- 核心目标：基于一个精简、可定制的 Agent 底座，建设一个面向中控数据开发场景的智能体执行底座。 -- 方案形态：不是“流程自动化 + LLM 节点”，而是一个以 Agent 为核心、能够围绕任务自主检索、生成、筛选和整理的数据开发执行底座。 -- 实现方式：基于 code-agent / claw-code-agent 实现，复用 Agent loop、文件读写、工具调用、代码执行、过程记录等通用能力。 -[图片] - ---- -2.2 核心架构 -- 中控数据Agent应该由 6 个核心要素组成： - - Workspace：任务工作区 - - Skills：领域经验包 - - Tools：可执行工具 - - Memory：Agent 外部认知状态 - - Policy：权限与人工裁决边界 -[图片] - ---- -2.2.1 Workspace：任务工作区 -每个需求 / badcase 启动后，系统创建一个独立 workspace。 -示例结构： -[图片] -Workspace 的作用： -- 承载任务上下文 -- 记录 Agent 中间理解 -- 保存探索过程 -- 支持人机协作 -- 沉淀可复用经验 -- 保证过程可追溯 -Agent 不是在一个固定流程里跑，而是在 workspace 按照我们之前的工作流程去工作 - ---- -2.2.2 MD First：以 Markdown 作为 Agent 工作语言 -[图片] -Agent 工作过程优先使用 Markdown -- MD 是 Agent 的工作语言； -- JSONL / CSV / DB 是数据资产的交换格式。 -内容 -推荐格式 -需求理解 -MD -边界分析 -MD -人工裁决 -MD -经验沉淀 -MD -候选样本池 -CSV / JSONL -评测集 -JSONL -训练集 -JSONL -回放结果 -表格 + MD 报告 -工具调用参数 -schema / JSON - ---- -2.2.3 Skills：固化成熟工作流程 -[图片] -Skill 是 Agent 可发现、可按需加载、可组合的领域经验包。 -示例： -/skills/ - router-label-boundary/ - SKILL.md - examples.md - known-confusions.md - decision-principles.md - - online-session-mining/ - SKILL.md - query-patterns.md - sampling-strategies.md - badcase-mining.md - - eval-set-construction/ - SKILL.md - golden-set-rules.md - boundary-set-rules.md - anti-patterns.md - - active-learning-router/ - SKILL.md - disagreement-mining.md - hard-negative-mining.md - recall-gap-analysis.md -Agent 在运行中根据问题自主选择是否读取某个 skill。 -例如： -发现 FAST_DIRECT 和 SLOW_FILTER_RANK 边界不清 -→ 读取 router-label-boundary skill - -需要从线上 session 挖相关样本 -→ 读取 online-session-mining skill - -发现模型离线准确率高但线上效果差 -→ 读取 active-learning-router skill -Skill ：之前工作经验的沉淀 - ---- -2.2.4 Tools：可执行能力 -Tools 是 Agent 可以调用的实际能力。 -示例： -search_online_sessions() -sample_top_queries() -find_similar_cases() -mine_by_pattern() -mine_by_embedding() -mine_by_model_disagreement() -cluster_and_dedup() -run_router_eval() -run_online_replay() -create_annotation_queue() -read_human_review_result() -train_router_model() -compare_model_versions() -Agent 不应该直接写复杂 SQL 或手工操作数据表。 -系统应该提供稳定、可控、可审计的工具接口。 -Agent 自己决定： -什么时候查线上 session -什么时候找历史裁决 -什么时候跑模型分歧 -什么时候构造混淆样本 -什么时候创建标注任务 -什么时候请求人工裁决 - ---- -2.2.5 Memory：Agent 外部认知状态 -Memory 不是简单存几个结构化字段。 -错误理解： -{ - "status": "running", - "target_label": "SLOW_FILTER_RANK" -} -正确理解： -Memory 是 Agent 为了完成长期任务而主动维护的外部认知状态。 -建议形式： -memory/current_understanding.md -memory/open_questions.md -memory/human_decisions.md -memory/failed_attempts.md -memory/reusable_lessons.md -其中： -current_understanding.md -记录 Agent 当前对任务的理解。 -open_questions.md -记录尚未解决的边界问题。 -human_decisions.md -记录人工裁决及其理由。 -failed_attempts.md -记录无效挖掘策略，避免重复踩坑。 -reusable_lessons.md -记录可复用经验，供后续任务调用。 -长期看，系统要沉淀： -哪些标签容易混淆 -哪些边界已有裁决 -哪些挖掘策略有效 -哪些关键词误伤高 -哪些样本适合评测集 -哪些样本只适合训练集 -哪些模型错误模式反复出现 - ---- -2.2.6 Policy：权限与人工裁决边界 -[图片] -Agent 可以自主推进任务，但不能无限自由。 -需要明确哪些事情 Agent 可以自动做，哪些必须人类确认。 -动作 -权限 -读取需求文档 -自动 -读取历史标签定义 -自动 -查询脱敏线上 session -自动 -挖候选样本 -自动 -聚类去重 -自动 -预打标 -自动 -生成边界分析 -自动 -生成标签定义修订建议 -自动 -修改标签边界 -人工确认 -样本入库抽检 -人工确认 -修改历史数据资产 -人工确认 - ---- -2.3 典型运行方式 -[图片] - -用户输入： -一批 badcase + 需求说明 + 当前标签定义 -Agent 启动任务 workspace。 -然后 Agent 自主推进： -1. 读取需求和 badcase -2. 写 goal.md -3. 写 current_understanding.md -4. 检索相关标签定义 -5. 检索历史类似裁决 -6. 判断当前问题涉及哪些边界 -7. 自主选择数据挖掘策略 -8. 查询线上 session / topquery / 模型误判样本 -9. 聚类、去重、找代表样本 -10. 发现标签冲突或定义不清 -11. 生成 open_questions.md -12. 向人提出高价值裁决问题 -13. 根据裁决继续挖掘和修正 -14. 生成候选评测集 -15. 生成回放报告 -16. 沉淀 reusable_lessons.md - ---- -3. 第一阶段目标 -- 基于现有 Agent 底座完成最小运行环境搭建，并优先打通三条主要的数据开发链路： - - 需求 / badcase 反馈 → 生成式构建专项评测集 → 数据持久化 - - 需求 / badcase 反馈 → 挖掘线上问题 → 构建专项评测集 → 数据持久化 - - badcase 自动收集与分析链路打通 -3.1 第一阶段落地方案 -第一阶段基于现有 claw-code-agent 作为执行底座，在保留其通用 Agent 能力的基础上，补齐面向中控数据开发场景的输入、检索、生成、落盘和 review 能力。 -让 claw-code-agent 从一个通用 code-agent，变成一个能够进入中控数据开发环境并执行真实任务的数据 Agent 底座。 -前两周的目标： -在一个受控工作区内完成： -- 读取需求 / badcase -- 检索线上样本 -- 生成或筛选评测集候选 -- 记录过程和中间判断 -- 输出可落盘、可 review 的结果 -在这一底座之上，第一阶段优先验证三条真实链路： -- 需求 / badcase 反馈 → 生成式构建专项评测集 → 数据持久化 -- 需求 / badcase 反馈 → 挖掘线上问题 → 构建专项评测集 → 数据持久化 -- badcase 自动收集与分析链路打通 -落地原则： -底层复用 -claw-code-agent 现有的 loop、tool calling、session persistence、transcript、compaction、markdown memory 注入、policy hook 等能力已经足够成熟，适合作为底层执行引擎直接复用。 - 因此，第一阶段不重写主循环，不重写工具调用链，不重写 session 基础设施。 -上层收口 -当前 claw-code-agent 的默认形态是 coding-first：prompt 偏代码助手，工具面偏泛代码操作，workspace 也更接近 code workspace。 - 第一阶段要做的不是扩展更多能力，而是把这些默认形态收口成 data-first：让 Agent 更聚焦于数据检索、样本筛选、评测集构建和结果沉淀。 -具体任务拆解： -直接复用底层执行内核 -这一部分不作为改造重点，只作为底座能力直接承接： -- Agent loop -- session / transcript / file_history -- tool schema + tool execution -- markdown memory 注入基础能力 -- hook / policy 基础机制 -- compaction / replay 基础设施 -这些能力已经能支撑“模型驱动循环 + 工具调用 + 过程追踪”，第一阶段不需要投入主要精力。 -需要改造的四个点： -1）把 code workspace 改成 task workspace @王云浩 -这是最关键的一步。 - 当前底座支持 markdown memory，但还没有真正 task-native 的工作区。第一阶段要把任务固定到 /tasks/{task_id}/ 目录下，让输入、记忆、产物和日志都围绕任务目录组织。 -2）把 coding-first prompt 改成 data-first prompt @王云浩 -当前 system prompt 更强调读代码、改代码、bash、git、验证代码修改。 - 第一阶段需要改成围绕： -- 需求理解 -- 边界分析 -- open questions -- 样本挖掘 -- 标注 / 裁决 -- eval/train set 构造 -- 经验沉淀 -这些数据任务来组织默认口径。 -3）把默认工具集改成最小数据工具集 @武阳 -当前工具面过宽，对数据 Agent 初版来说不是增强，而是噪音。 - 第一阶段要做的是裁出一套 default_data_tool_registry()，只保留必要文件工具和少量数据专用工具，让 Agent 的动作空间收敛。 -4）把 coding policy 扩展成数据治理 policy @武阳 -当前权限语义更像： -- allow write -- allow shell -- deny tool -- ask user -但数据场景需要更细的治理边界，比如： -- 是否允许查线上样本 -- 是否允许导出敏感字段 -- 是否允许生成标注任务 -- 哪些问题必须人工裁决 -- 哪些标签修订必须人工确认 -这一部分必须在第一阶段明确下来。 -需要重点建设的两层能力： -1）之前挖掘经验通过SKILL的方式进行注入(需要进行实验和验证) -第一阶段 skill 不应再只是 prompt 片段，而应沉淀成目录化 markdown 经验包，至少覆盖： -- 边界判断 -- 线上挖掘 -- 评测集构建 -并采用“元信息先注入，正文按需展开”的方式，避免一次性把全部经验塞进上下文。 -2）artifacts 统一沉淀 -第一阶段所有关键结果都应统一沉淀到 task workspace 下，而不是只停留在 session json 或临时输出里。 -这一步是后续 review、复盘、数据资产化的前提。 -目标的形态 -/tasks/{task_id}/ - goal.md - context/ - requirement.md - badcase.md - memory/ - open_questions.md - working_notes.md - decisions.md - artifacts/ - eval_candidates.jsonl - mining_strategy.md - report.md - logs/ - agent_trace.md -在这个形态下，Agent 能够围绕一个任务完成： -- 输入读取 -- 数据检索 -- 样本筛选或生成 -- 结果沉淀 -- 人工 review 触发 -代码改造清单 -类型 -项目 -第一阶段动作 -说明 -直接复用 -Agent loop -保留 -不重写主循环 -直接复用 -session / transcript / compaction -保留 -直接复用过程追踪能力 -直接复用 -tool schema / execution -保留 -不改调用链 -核心改造 -workspace -改造 -从 code workspace 收口为 task workspace -核心改造 -system prompt -改造 -从 coding-first 改为 data-first -核心改造 -默认工具集 -改造 -裁出最小数据工具集 -核心改造 -policy / human gate -改造 -从 coding 权限扩展为数据治理边界 -必须新增 -skill 机制 -新增 -目录化 markdown 经验包，按需加载 -必须新增 -artifacts 沉淀规则 -新增 -所有关键结果统一沉淀到 task 目录 -业务验证 -生成式评测集构建 -打通 -作为第一条真实链路 -业务验证 -线上问题挖掘 -打通 -作为第二条真实链路 -业务验证 -badcase 自动收集分析 -打通 -作为第三条真实链路 -[图片] - - - -