Mert KoseogluandSebastian Breguel
b392c2fe2f
Adds a `concurrency: 1-8` parameter to ctx_batch_execute and
ctx_fetch_and_index, plus a shared `runPool` primitive, observability
extractor, and Parallel I/O guidance across all 14 adapter routing
docs.
What ships
- src/concurrency/runPool.ts (new): generic in-flight-capped worker
pool returning Promise.allSettled-style results. Single primitive
used by both batch tools — no copy-pasted worker logic.
- ctx_batch_execute: serial branch unchanged (shared timeout budget,
cascading skip). Parallel branch routed through runPool. Description
hardened with PARALLELIZE I/O ✅/❌ guidance and NON-NEGOTIABLE
THINK IN CODE clause.
- ctx_fetch_and_index: accepts both legacy `{url, source}` (single,
exact backward-compat wording) and new `{requests: [{url, source}]}`
(batch). Workers fetch in parallel via runPool; FTS5 writes drain
serially through indexFetched to avoid SQLite WAL contention.
Per-URL preview capped at 384 chars in batch mode (~3KB total) so
context-savings hold under 8-URL fan-outs. composeFetchCacheKey
wiring preserved across the refactor — same-label-different-URL
collisions stay fixed (commit 1f1243e regression test enforced).
- effectiveConcurrency = min(N, os.cpus().length) when capByCpuCount
set. Response surfaces capped count in caveman style.
- mcp_tool_call extractor (src/session/extract.ts) persists tool_input
for mcp__* events with UTF-8-aware truncation at 2KB. Unlocks
getMcpToolUsage() analytics — median/max concurrency per batch tool
visible in ctx_stats.
- 14 adapter routing docs updated with the same Parallel I/O
paragraph adapted to each host's tool-call prefix style. GitHub
rate-limit caveat included consistently.
Hardening from 2-round architectural review
- Worker try/catch + Promise.allSettled isolation: one job throw no
longer strands siblings or leaves undefined output slots.
- Timeout sentinel routes through formatCommandOutput: __CM_FS__
markers stripped + bytes counted on partial-stdout-on-timeout.
- trackIndexed moved after FTS5 write succeeds (no over-count on
failed indexes).
- UTF-8-aware truncate (Buffer.byteLength + continuation-byte
walk-back): multi-byte payloads (CJK, 4-byte symbols) honor the
byte budget without landing mid-codepoint.
- cpuCountForCap helper deleted: was CommonJS require in an ESM
file, silently always returning 1. Replaced with top-level
`cpus` import from node:os.
Tests (per CONTRIBUTING.md no-new-test-files rule, all under
existing files)
- 7 runPool unit tests: order, throw isolation, in-flight cap,
job-count clamp, os.cpus cap, onSettled callback ordering.
- 13 ctx_fetch_and_index batch source-level tests: schema accepts
both shapes, serial-write contract holds, backward-compat wording
preserved, batch preview cap enforced, caveman header formatting,
composeFetchCacheKey wiring across the refactor.
- 3 P0 hardening tests: throw-isolation, timeout marker stripping,
5-cmd × 100ms at concurrency=5 < 200ms (CI-checked timing
regression replacing the deleted bench).
- 4 mcp_tool_call extractor tests including UTF-8 multibyte
regression.
- 3 getMcpToolUsage analytics tests.
Verification
- 138/138 server.test.ts pass; 309/309 across server + extract +
analytics on cw/ctx-analytics.
- On next: 318/326 pass. 8 pre-existing unrelated failures
(ctx_index projectRoot resolution from #365, ctx_execute_file env
cascade, getSessionDir pre-detection) untouched.
- Typecheck clean.
Co-Authored-By: Sebastian Breguel <sebastianbreguel@gmail.com>
5.3 KiB
context-mode — MANDATORY routing rules
context-mode MCP tools available. Rules protect context window from flooding. One unrouted command dumps 56 KB into context. Codex CLI has NO hooks — these instructions are ONLY enforcement. Follow strictly.
Think in Code — MANDATORY
Analyze/count/filter/compare/search/parse/transform data: write code via ctx_execute(language, code), console.log() only the answer. Do NOT read raw data into context. PROGRAM the analysis, not COMPUTE it. Pure JavaScript — Node.js built-ins only (fs, path, child_process). try/catch, handle null/undefined. One script replaces ten tool calls.
BLOCKED — do NOT use
curl / wget — FORBIDDEN
Do NOT use curl/wget in shell. Dumps raw HTTP into context.
Use: ctx_fetch_and_index(url, source) or ctx_execute(language: "javascript", code: "const r = await fetch(...)")
Inline HTTP — FORBIDDEN
No node -e "fetch(...", python -c "requests.get(...". Bypasses sandbox.
Use: ctx_execute(language, code) — only stdout enters context
Direct web fetching — FORBIDDEN
Raw HTML can exceed 100 KB.
Use: ctx_fetch_and_index(url, source) then ctx_search(queries)
REDIRECTED — use sandbox
Shell (>20 lines output)
Shell ONLY for: git, mkdir, rm, mv, cd, ls, npm install, pip install.
Otherwise: ctx_batch_execute(commands, queries) or ctx_execute(language: "shell", code: "...")
File reading (for analysis)
Reading to edit → reading correct. Reading to analyze/explore/summarize → ctx_execute_file(path, language, code).
grep / search (large results)
Use ctx_execute(language: "shell", code: "grep ...") in sandbox.
Tool selection
- MEMORY:
ctx_search(sort: "timeline")— after resume, check prior context before asking user. - GATHER:
ctx_batch_execute(commands, queries)— runs all commands, auto-indexes, returns search. ONE call replaces 30+. Each command:{label: "header", command: "..."}. - FOLLOW-UP:
ctx_search(queries: ["q1", "q2", ...])— all questions as array, ONE call (default relevance mode). - PROCESSING:
ctx_execute(language, code)|ctx_execute_file(path, language, code)— sandbox, only stdout enters context. - WEB:
ctx_fetch_and_index(url, source)thenctx_search(queries)— raw HTML never enters context. - INDEX:
ctx_index(content, source)— store in FTS5 for later search.
Parallel I/O batches
For multi-URL fetches or multi-API calls, always include concurrency: N (1-8):
ctx_batch_execute(commands: [3+ network commands], concurrency: 5)— gh, curl, dig, docker inspect, multi-region cloud queriesctx_fetch_and_index(requests: [{url, source}, ...], concurrency: 5)— multi-URL batch fetch
Use concurrency 4-8 for I/O-bound work (network calls, API queries). Keep concurrency 1 for CPU-bound (npm test, build, lint) or commands sharing state (ports, lock files, same-repo writes).
GitHub API rate-limit: cap at 4 for gh calls.
Output
Terse like caveman. Technical substance exact. Only fluff die.
Drop: articles, filler (just/really/basically), pleasantries, hedging. Fragments OK. Short synonyms. Code unchanged.
Pattern: [thing] [action] [reason]. [next step]. Auto-expand for: security warnings, irreversible actions, user confusion.
Write artifacts to FILES — never inline. Return: file path + 1-line description.
Descriptive source labels for ctx_search(source: "label").
Session Continuity
Skills, roles, and decisions persist for the entire session. Do not abandon them as the conversation grows.
Memory
Session history is persistent and searchable. On resume, search BEFORE asking the user:
| Need | Command |
|---|---|
| What were we working on? | ctx_search(queries: ["summary"], source: "compaction", sort: "timeline") |
| What did we decide? | ctx_search(queries: ["decision"], source: "decision", sort: "timeline") |
| What NOT to repeat? | ctx_search(queries: ["rejected"], source: "rejected-approach") |
| What constraints exist? | ctx_search(queries: ["constraint"], source: "constraint") |
Note: user-prompt history not available.
DO NOT ask "what were we working on?" — SEARCH FIRST. If search returns 0 results, proceed as a fresh session.
ctx commands
| Command | Action |
|---|---|
ctx stats |
Call stats MCP tool, display full output verbatim |
ctx doctor |
Call doctor MCP tool, run returned shell command, display as checklist |
ctx upgrade |
Call upgrade MCP tool, run returned shell command, display as checklist |
ctx purge |
Call purge MCP tool with confirm: true. Warns before wiping knowledge base. |
After /clear or /compact: knowledge base and session stats preserved. Use ctx purge to start fresh.
Windows notes
PowerShell cmdlets — Sandbox uses bash. PowerShell cmdlets (Format-List, Get-Culture, etc.) fail with command not found. Wrap with pwsh -NoProfile -Command "...".
Relative paths — Sandbox CWD is temp dir, not project root. Convert to absolute paths. Ask user to confirm if unknown.
Windows drive letters — Sandbox runs Git Bash / MSYS2. X:\path → /x/path (lowercase, no /mnt/). Never emit /mnt/<letter>/.
Quote paths — Spaces in paths cause splits. Always double-quote: rg "symbol" "$REPO_ROOT/some dir/Source".