weichen
28ed7005dd
Extend agentctl SQLite with catalog tables, CJK FTS5 recall, hard/soft overlap gates, fail-open embeddings, backfill, and MCP/skills hooks so cross-conversation designs cannot silently conflict.
MCP servers (stdio)
Zero-dependency Node MCP wrappers used by Cursor (see .cursor/mcp.json).
| Server | Script | Purpose |
|---|---|---|
agentctl |
agentctl-mcp.mjs |
Lease / docs apply / validate / queue |
jev |
jev-mcp.mjs |
Typed decide/health against local or remote jev-service |
pi-subagents |
pi-subagents-mcp.mjs |
Local PI subagent roles/run/result (engineering tool; not product Runner) |
# from repo root
node scripts/mcp/agentctl-mcp.mjs
node scripts/mcp/jev-mcp.mjs
node scripts/mcp/pi-subagents-mcp.mjs
pi-subagents
Markdown model config is the sole editable source: .doc/ops/2026-09-24-subagent-model-config.md.
| Tool | Behavior |
|---|---|
pi_subagent_roles |
Read-only catalog; never invokes PI; executor binary from this server's INSTALL_ROOT |
pi_subagent_run |
Non-blocking; request JSON in OS tmp; wraps discovered main worktree scripts/agentctl.py with (governance SSOT lease entry) + INSTALL_ROOT scripts/pi_subagents.py run |
pi_subagent_result |
Read-only receipt; running is not isError; terminal failure/UNKNOWN_REQUEST after a settled supervisor rejection surfaces the child's typed error (ROLE_DISABLED, LEASE_REQUIRED, …) |
Install vs main: When the MCP server lives in a linked task worktree, INSTALL_ROOT may differ from the repo main tip. Cross-repo worktrees (different git-common-dir) are refused. Optional config is worktree-relative registered model config only. request.config_path is rejected (use tool config).
CLI:
python3 -B scripts/pi_subagents.py roles --config .doc/ops/2026-09-24-subagent-model-config.md
python3 -B scripts/agentctl.py with --task <id> \
--resource path:.doc/test-reports/assets/pi-subagents/<id>/<request_id> -- \
python3 -B scripts/pi_subagents.py run --request /path/to/req.json \
--config .doc/ops/2026-09-24-subagent-model-config.md
python3 -B scripts/pi_subagents.py result --task <id> --request-id <request_id>
The executor resolves agentctl helpers from the git main worktree scripts directory (not a stale colocated copy beside itself when running from a feature worktree).
Scoped reads: scripts/pi-subagent-readonly.ts — builtin path only; @/~ denied; directory walks must contain only allowlisted regular files. Approved tests use a separate snapshot; model evidence stays pristine.
Cursor CLI compatibility (pi-subagents)
Real Cursor CLI 2026.09.18 (and 2026.09.23 verified here) does not expand ${workspaceFolder} in MCP args. The pi-subagents entry therefore uses workspace-relative args: ["scripts/mcp/pi-subagents-mcp.mjs"] with type: "stdio" / command: "node". Absolute ${workspaceFolder}/… paths fail with Cannot find module '…/${workspaceFolder}/scripts/mcp/pi-subagents-mcp.mjs'. After agent mcp enable pi-subagents, agent mcp list-tools pi-subagents must report exactly three tools: pi_subagent_roles, pi_subagent_run, pi_subagent_result. Older agentctl / jev entries may still use ${workspaceFolder} until separately corrected.
Limitations (v1)
- No shared environment ops (
SHARED_ENV_UNSUPPORTED). - Process-group governance, not an OS sandbox.
- Unit suite uses fake PI; Cursor UI MCP connectivity requires reload after checkout and host smoke.
- Host owns live paid-model checks.
jev credentials (not in git)
~/.secrets/jev/api.key(chmod 600) or envJEV_API_KEY~/.secrets/jev/base-urlor envJEV_BASE_URL(defaulthttp://127.0.0.1:8767)
Reload MCP after checkout. See skill .cursor/skills/jev-decide/SKILL.md.
lease_run / validate take command as an argv array (no shell). Set AGENTCTL_REPO only when the agentctl script is not under the repo tree.