# Testing Guide This guide gives concrete commands you can run to verify the current Python implementation feature by feature. All commands below assume you are inside: ```bash cd /path/to/claw-code-agent ``` ## 1. Environment Setup ### 1.1 Start `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 ``` Set the runtime 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 ``` ### 1.2 Run the unit test suite ```bash python3 -m unittest discover -s tests -v ``` ## 2. Installation And Basic Usage ### 2.1 Editable install ```bash pip install -e . ``` ### 2.2 Show CLI help ```bash python3 -m src.main --help python3 -m src.main agent --help python3 -m src.main agent-bg --help python3 -m src.main agent-ps --help python3 -m src.main agent-chat --help python3 -m src.main agent-resume --help ``` ### 2.3 Run the packaged entrypoint ```bash claw-code-agent agent "/help" ``` ## 3. Slash Commands These are handled locally and do not require the model to answer. ```bash python3 -m src.main agent "/help" python3 -m src.main agent "/commands" python3 -m src.main agent "/context" --cwd .. python3 -m src.main agent "/context-raw" --cwd .. python3 -m src.main agent "/search" --cwd .. python3 -m src.main agent "/remote" --cwd .. python3 -m src.main agent "/remotes" --cwd .. python3 -m src.main agent "/plan" --cwd .. python3 -m src.main agent "/prompt" --cwd .. python3 -m src.main agent "/permissions" --cwd .. python3 -m src.main agent "/hooks" --cwd .. python3 -m src.main agent "/policy" --cwd .. python3 -m src.main agent "/trust" --cwd .. python3 -m src.main agent "/task-next" --cwd .. python3 -m src.main agent "/tools" --cwd .. python3 -m src.main agent "/memory" --cwd .. python3 -m src.main agent "/status" --cwd .. python3 -m src.main agent "/clear" --cwd .. ``` ## 4. Context And Prompt Inspection ### 4.1 System prompt rendering ```bash python3 -m src.main agent-prompt --cwd .. ``` ### 4.2 Context usage accounting ```bash python3 -m src.main agent-context --cwd .. ``` ### 4.3 Raw context snapshot ```bash python3 -m src.main agent-context-raw --cwd .. ``` ### 4.4 Additional working directories ```bash python3 -m src.main agent-context --cwd .. --add-dir /path/to/directory ``` ### 4.5 Disable `CLAUDE.md` discovery ```bash python3 -m src.main agent-context --cwd .. --disable-claude-md ``` ### 4.6 Hook/policy context and trust inspection Create a local policy file: ```bash mkdir -p ./test_cases cat > ./test_cases/.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 ``` Inspect the runtime view: ```bash python3 -m src.main agent "/hooks" --cwd ./test_cases python3 -m src.main agent "/trust" --cwd ./test_cases python3 -m src.main agent "/permissions" --cwd ./test_cases python3 -m src.main agent "/tools" --cwd ./test_cases python3 -m src.main agent-context-raw --cwd ./test_cases python3 -m src.main agent-prompt --cwd ./test_cases ``` ### 4.7 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 \ --allow-shell \ --show-transcript ``` ### 4.8 Plan runtime context and prompt inspection ```bash python3 -m src.main agent \ "Use update_plan to store a two-step plan for inspecting and editing the workspace." \ --cwd ./test_cases \ --allow-write \ --show-transcript python3 -m src.main agent "/plan" --cwd ./test_cases python3 -m src.main agent "/tasks" --cwd ./test_cases python3 -m src.main agent-context-raw --cwd ./test_cases python3 -m src.main agent-prompt --cwd ./test_cases ``` ### 4.9 Remote runtime context and prompt inspection Create a local remote manifest: ```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" } ] } EOF ``` Inspect the runtime view: ```bash python3 -m src.main agent "/remote" --cwd ./test_cases python3 -m src.main agent "/remotes" --cwd ./test_cases python3 -m src.main agent-context-raw --cwd ./test_cases python3 -m src.main agent-prompt --cwd ./test_cases ``` ### 4.10 Search runtime context and prompt inspection Create a local search manifest: ```bash cat > ./test_cases/.claw-search.json <<'EOF' { "providers": [ { "name": "local-search", "provider": "searxng", "baseUrl": "http://127.0.0.1:8080" } ] } EOF ``` Inspect the runtime view: ```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-context-raw --cwd ./test_cases python3 -m src.main agent-prompt --cwd ./test_cases ``` ### 4.11 Tokenizer-aware context accounting Inspect which token counter backend the runtime is using: ```bash python3 -m src.main agent "/status" --cwd ./test_cases python3 -m src.main agent-context --cwd ./test_cases ``` Force a local tokenizer path or model override for context accounting: ```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 ``` If no tokenizer backend is available, the runtime will fall back to a heuristic counter and `/status` will show that. ## 5. Core Agent Loop ### 5.1 Read-only run ```bash python3 -m src.main agent \ "Read claw-code-agent/src/agent_runtime.py and summarize how the loop works." \ --cwd .. ``` ### 5.2 Show transcript output ```bash python3 -m src.main agent \ "Read claw-code-agent/src/agent_session.py and summarize the session model." \ --cwd .. \ --show-transcript ``` ### 5.3 Streaming model responses ```bash python3 -m src.main agent \ "Inspect the current repository and summarize the architecture." \ --cwd .. \ --stream \ --show-transcript ``` ### 5.4 Interactive chat loop ```bash python3 -m src.main agent-chat --cwd .. ``` Optional first prompt: ```bash python3 -m src.main agent-chat \ "Inspect the repository and tell me where the runtime loop lives." \ --cwd .. ``` ## 6. Search Runtime And Real Web Search ### 6.1 Configure a provider with a local manifest ```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 ``` ### 6.2 Configure a provider from environment variables Use one of these: ```bash export SEARXNG_BASE_URL=http://127.0.0.1:8080 export BRAVE_SEARCH_API_KEY=your-brave-key export TAVILY_API_KEY=your-tavily-key ``` ### 6.3 Inspect providers from the CLI ```bash python3 -m src.main search-status --cwd ./test_cases python3 -m src.main search-providers --cwd ./test_cases python3 -m src.main search-status --cwd ./test_cases --provider local-search python3 -m src.main search-activate local-search --cwd ./test_cases ``` ### 6.4 Run a real web search from the CLI ```bash python3 -m src.main search \ "python argparse mutually exclusive group" \ --cwd ./test_cases \ --provider local-search \ --max-results 5 ``` Limit results to specific domains: ```bash python3 -m src.main search \ "OpenAI Responses API" \ --cwd ./test_cases \ --domain openai.com \ --domain platform.openai.com ``` ### 6.5 Run a real web search through 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 ``` ### 6.6 Run a real web search through the model tool 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 ``` Inside chat mode: - type normal prompts to continue the same session - use `/exit` or `/quit` to leave ### 5.5 Resume directly into chat mode ```bash python3 -m src.main agent-chat \ --resume-session-id \ --cwd .. ``` ## 6. Tool Execution ### 6.1 Read files ```bash python3 -m src.main agent \ "Read claw-code-agent/src/agent_tools.py and summarize each tool." \ --cwd .. ``` ### 6.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 ``` ### 6.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 ``` ### 6.4 Glob and grep ```bash python3 -m src.main agent \ "Find Python files in the current directory, then search for 'LocalCodingAgent' and summarize the matches." \ --cwd .. ``` ### 6.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 ``` ### 6.6 Unsafe shell mode Use only if you intentionally want destructive-shell permission enabled. ```bash python3 -m src.main agent \ "Explain whether destructive shell commands are currently allowed." \ --cwd .. \ --allow-shell \ --unsafe ``` ### 6.7 Hook/policy tool blocking Update the policy to block `bash`: ```bash cat > ./test_cases/.claw-policy.json <<'EOF' { "trusted": false, "denyTools": ["bash"], "hooks": { "beforePrompt": ["Respect workspace policy before acting."], "afterTurn": ["Persist the policy decision after each turn."] } } EOF ``` Then test the block: ```bash python3 -m src.main agent \ "Try to run bash and then explain what was blocked." \ --cwd ./test_cases \ --allow-shell \ --show-transcript ``` Look for: - `hook_policy_tool_block` - `tool_permission_denial` - `plugin_tool_runtime` messages that now also include hook/policy guidance when present ### 6.8 Plan tools ```bash python3 -m src.main agent \ "Use update_plan to store these steps: inspect the repository, implement the change, run verification. Mark the first step in_progress and sync the plan to tasks." \ --cwd ./test_cases \ --allow-write \ --show-transcript python3 -m src.main agent "/plan" --cwd ./test_cases python3 -m src.main agent "/tasks" --cwd ./test_cases ``` ### 6.9 Remote tools ```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 ``` ## 7. Session Persistence And Resume ### 7.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=... ``` ### 7.2 Resume a saved session ```bash python3 -m src.main agent-resume \ \ "Continue the previous task and improve the file." \ --allow-write \ --show-transcript ``` ### 7.3 Inspect saved sessions ```bash ls -lt .port_sessions/agent ``` ## 8. Background Sessions ### 8.1 Launch a background session Use a local slash-command prompt first so you can verify the background workflow without depending on the model backend: ```bash python3 -m src.main agent-bg "/help" --cwd ./test_cases ``` This prints: - `background_id=...` - `pid=...` - `log_path=...` - `record_path=...` ### 8.2 List background sessions ```bash python3 -m src.main agent-ps ``` ### 8.3 Read background logs ```bash python3 -m src.main agent-logs python3 -m src.main agent-logs --tail 40 ``` ### 8.4 Attach to the current output snapshot ```bash python3 -m src.main agent-attach python3 -m src.main agent-attach --tail 40 ``` ### 8.5 Kill a running background session ```bash python3 -m src.main agent-kill ``` ### 8.6 Daemon-style wrappers ```bash python3 -m src.main daemon start "/help" --cwd ./test_cases python3 -m src.main daemon ps python3 -m src.main daemon logs python3 -m src.main daemon attach python3 -m src.main daemon kill ``` ## 9. Remote Runtime CLI ### 9.1 Remote mode commands ```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 preview --cwd ./test_cases python3 -m src.main direct-connect-mode direct://workspace --cwd ./test_cases python3 -m src.main deep-link-mode preview --cwd ./test_cases ``` ### 9.2 Inspect and clear remote state ```bash python3 -m src.main remote-status --cwd ./test_cases python3 -m src.main remote-profiles --cwd ./test_cases python3 -m src.main remote-disconnect --cwd ./test_cases python3 -m src.main remote-status --cwd ./test_cases ``` ## 10. 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. Budgets And Limits ### 11.1 Total token budget ```bash python3 -m src.main agent \ "Give a very long answer about the current repository." \ --cwd .. \ --max-total-tokens 50 ``` ### 11.2 Input / output token budgets ```bash 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-token budget ```bash python3 -m src.main agent \ "Solve a multi-step task and explain the result." \ --cwd .. \ --max-reasoning-tokens 10 ``` ### 11.4 Tool-call budget ```bash python3 -m src.main agent \ "Read multiple files, search for symbols, and summarize the repo." \ --cwd .. \ --max-tool-calls 1 ``` ### 11.5 Delegated-task budget ```bash python3 -m src.main agent \ "Delegate two subtasks to inspect and summarize the repo." \ --cwd .. \ --max-delegated-tasks 1 ``` ### 11.6 Cost budget ```bash python3 -m src.main agent \ "Inspect the current repository and summarize it." \ --cwd .. \ --input-cost-per-million 0.15 \ --output-cost-per-million 0.60 \ --max-budget-usd 0.000001 ``` ### 11.7 Model-call budget ```bash python3 -m src.main agent \ "Continue inspecting the repository until you are done." \ --cwd .. \ --max-model-calls 1 ``` ### 11.8 Session-turn budget ```bash python3 -m src.main agent \ "Work through the repository across multiple turns and keep going." \ --cwd .. \ --max-session-turns 1 ``` ### 11.9 Budget overrides from local policy ```bash cat > ./test_cases/.claw-policy.json <<'EOF' { "budget": { "max_model_calls": 0 } } EOF python3 -m src.main agent \ "Say hello once." \ --cwd ./test_cases ``` Expected result: the run stops with a model-call budget exceeded message even though you did not pass `--max-model-calls` on the CLI. ## 12. Streaming, Continuation, And Context Reduction ### 12.1 Streaming assistant output ```bash python3 -m src.main agent \ "Produce a long explanation of the current repository architecture." \ --cwd .. \ --stream \ --show-transcript ``` ### 12.2 Automatic continuation after truncation Use a small output budget so the backend is more likely to stop early: ```bash python3 -m src.main agent \ "Write a long, structured explanation of the current repository." \ --cwd .. \ --max-output-tokens 32 \ --show-transcript ``` ### 12.3 Snipping older context ```bash python3 -m src.main agent \ "Read claw-code-agent/src/agent_runtime.py, claw-code-agent/src/agent_session.py, claw-code-agent/src/query_engine.py, and claw-code-agent/src/plugin_runtime.py, then summarize all of them in detail." \ --cwd .. \ --auto-snip-threshold 120 \ --compact-preserve-messages 0 \ --show-transcript ``` ### 12.4 Compaction boundaries ```bash python3 -m src.main agent \ "Read several large files from claw-code-agent/src and keep explaining the repository until the context gets compacted." \ --cwd .. \ --auto-compact-threshold 120 \ --compact-preserve-messages 1 \ --show-transcript ``` ## 13. File History Replay ### 13.1 Create file history ```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 ``` ### 13.2 Resume and inspect replay ```bash 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. ## 14. Nested Delegation ### 14.1 Basic delegated subtask ```bash python3 -m src.main agent \ "Delegate a subtask to inspect claw-code-agent/src/agent_runtime.py and return the summary." \ --cwd .. \ --show-transcript ``` ### 14.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 ``` ### 14.3 Resume a delegated child session 1. Seed a normal saved session: ```bash python3 -m src.main agent \ "Inspect claw-code-agent/src/agent_tools.py and give a short summary." \ --cwd .. ``` 2. Copy that `session_id`, then run: ```bash python3 -m src.main agent \ "Delegate a subtask that resumes session and continues it." \ --cwd .. \ --show-transcript ``` ### 14.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=...` ## 15. Plugin Runtime Create a local plugin manifest: ```bash mkdir -p ./test_cases/plugins/demo cat > ./test_cases/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." }, "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 ``` ### 15.1 Plugin prompt/context discovery ```bash python3 -m src.main agent-prompt --cwd ./test_cases python3 -m src.main agent-context-raw --cwd ./test_cases ``` ### 15.2 Plugin alias tool ```bash echo "hello plugin" > ./test_cases/hello.txt python3 -m src.main agent \ "Use the plugin_read tool to read hello.txt and summarize it." \ --cwd ./test_cases \ --show-transcript ``` ### 15.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 \ --show-transcript ``` ### 15.4 Plugin before/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 \ --show-transcript ``` ### 15.5 Plugin lifecycle with resume/persist 1. Start a session: ```bash python3 -m src.main agent \ "Use the plugin system and create a saved session." \ --cwd ./test_cases ``` 2. Resume it: ```bash python3 -m src.main agent-resume \ \ "Continue and mention any plugin lifecycle guidance you received." \ --show-transcript ``` Look for: - `plugin_before_persist` - `Plugin resume hooks:` - `Plugin runtime state:` ## 16. MCP Runtime Create a local MCP manifest: ```bash mkdir -p ./test_cases_mcp printf 'mcp notes\n' > ./test_cases_mcp/notes.txt 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" } ] } ] } EOF ``` ### 16.1 MCP context and slash commands ```bash python3 -m src.main agent "/mcp" --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 "/mcp (MCP)" --cwd ./test_cases_mcp python3 -m src.main agent-context-raw --cwd ./test_cases_mcp python3 -m src.main agent-prompt --cwd ./test_cases_mcp ``` ### 16.2 MCP tools through the model loop ```bash python3 -m src.main agent \ "List the available MCP resources, then read mcp://workspace/notes and summarize it." \ --cwd ./test_cases_mcp \ --show-transcript ``` ### 16.3 Read inline MCP resources ```bash python3 -m src.main agent \ "Read the MCP resource mcp://workspace/inline and repeat its content." \ --cwd ./test_cases_mcp \ --show-transcript ``` ### 16.4 Real stdio MCP server transport Create a simple stdio MCP server: ```bash 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 ``` Add the stdio server to the MCP manifest: ```bash 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 ``` ### 16.5 MCP transport CLI commands ```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-resource mcp://remote/notes --cwd ./test_cases_mcp python3 -m src.main mcp-tools --cwd ./test_cases_mcp python3 -m src.main mcp-call-tool echo --arguments-json '{"text":"hello"}' --cwd ./test_cases_mcp ``` ### 16.6 MCP transport 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 ``` ### 16.7 MCP transport tools through the model 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 ``` ## 17. Task Runtime Create a clean task workspace: ```bash mkdir -p ./test_cases_tasks rm -rf ./test_cases_tasks/.port_sessions ``` ### 17.1 Task 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-context-raw --cwd ./test_cases_tasks python3 -m src.main agent-prompt --cwd ./test_cases_tasks ``` ### 17.2 Create and update tasks through the model loop ```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 ``` Then inspect the stored task file: ```bash cat ./test_cases_tasks/.port_sessions/task_runtime.json ``` ### 17.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 ``` ### 17.4 Read back task state ```bash python3 -m src.main agent "/tasks" --cwd ./test_cases_tasks python3 -m src.main agent "/task-next" --cwd ./test_cases_tasks python3 -m src.main agent \ "List the current tasks and show me the id of each one." \ --cwd ./test_cases_tasks \ --show-transcript ``` ### 17.5 Plan runtime 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 ``` ### 17.6 Dependency-aware task execution Create a blocked task graph through the model loop: ```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 ``` Then advance the task state: ```bash 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 ``` Inspect the resulting task state: ```bash python3 -m src.main agent "/task-next" --cwd ./test_cases_tasks python3 -m src.main agent "/tasks" --cwd ./test_cases_tasks cat ./test_cases_tasks/.port_sessions/task_runtime.json ``` ### 17.7 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, and task_start for patch." \ --cwd ./test_cases_tasks \ --allow-write \ --show-transcript ``` ## 18. Query Engine And Workspace Commands ### 18.1 Workspace inventory ```bash python3 -m src.main summary python3 -m src.main manifest python3 -m src.main subsystems --limit 20 python3 -m src.main commands --limit 20 python3 -m src.main tools --limit 20 ``` ### 18.2 Query routing and bootstrap reports ```bash 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 ``` ### 18.3 Session flushing for the mirrored workspace ```bash python3 -m src.main flush-transcript "store a temporary transcript" python3 -m src.main load-session ``` ## 19. Parity Tracking Workflow 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` ## 20. Config Runtime Inspect local config state: ```bash python3 -m src.main config-status --cwd ./test_cases python3 -m src.main config-effective --cwd ./test_cases ``` Read a value or a source directly: ```bash python3 -m src.main config-get review.mode --cwd ./test_cases python3 -m src.main config-source project --cwd ./test_cases ``` Write a value into the local settings layer: ```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 ``` Test the 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 get review.mode" --cwd ./test_cases python3 -m src.main agent "/settings source local" --cwd ./test_cases ``` Test the config tools through the real agent 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 ``` ## 21. Account Runtime Inspect local account state: ```bash python3 -m src.main account-status --cwd ./test_cases python3 -m src.main account-profiles --cwd ./test_cases ``` Activate and clear a local account session: ```bash python3 -m src.main account-login local --cwd ./test_cases python3 -m src.main account-logout --cwd ./test_cases ``` Test the 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 "/login local" --cwd ./test_cases python3 -m src.main agent "/logout" --cwd ./test_cases ``` Test the account tools through the real agent 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 ``` ## 22. Extended Tool Slice Test the new tool-surface additions through the real agent loop: ```bash python3 -m src.main agent \ "Use tool_search to find file-related tools and summarize the best ones for reading and editing files." \ --cwd ./test_cases ``` ```bash python3 -m src.main agent \ "Use web_fetch on file://$(pwd)/README.md and summarize the first section." \ --cwd . ``` ```bash python3 -m src.main agent \ "Call the sleep tool for 0.1 seconds, then tell me it completed." \ --cwd ./test_cases ``` Run the direct unit tests for this slice: ```bash python3 -m unittest tests.test_extended_tools -v ```