@agentprojectcontext/apx 1.33.1 → 1.35.0

package/src/core/runtime-skills/apx-mcp-builder/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: apx-mcp-builder
+scope: internal
+description: Author a new MCP (Model Context Protocol) server and register it in APX. Covers JSON-RPC stdio protocol, FastMCP (Python) / TypeScript SDK shapes, tool design, secrets, debugging. Load when building a new MCP / exposing a new tool surface. To add an existing MCP, load `apx-mcp` instead.
+---
+
+# apx-mcp-builder
+
+An MCP server is a tiny stdio JSON-RPC process. APX spawns it (via `apx mcp add`), discovers tools (`tools/list`), and lets the super-agent call them by name.
+
+## Minimum surface
+
+| Method | Purpose | Returns |
+|---|---|---|
+| `initialize` | Handshake (protocol version + capabilities). | Server capabilities. |
+| `tools/list` | Enumerate tools. | `{ tools: [{name, description, inputSchema}] }` |
+| `tools/call` | Run one tool with `{ name, arguments }`. | `{ content: [...], isError? }` |
+| `notifications/initialized` | One-way init-done from APX. | — |
+
+JSON-RPC 2.0 over stdio, framed `Content-Length: N\r\n\r\n<JSON>`. The `@modelcontextprotocol/sdk` (TS) and `fastmcp` / `mcp` (Python) packages handle framing.
+
+## Pick a stack
+
+| Stack | When |
+|---|---|
+| **Python + FastMCP** | Fastest path; decorator-based; ideal for pip-wrapping tools. |
+| **Node + @modelcontextprotocol/sdk** | Node-only libs, or zero install (`npx -y`). |
+| Raw JSON-RPC | Only when exposing an existing daemon. Otherwise use the SDK. |
+
+## Python (FastMCP) — minimum viable server
+
+```python
+# my_server.py
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("my-server")
+
+@mcp.tool()
+def search_inventory(query: str, limit: int = 10) -> list[dict]:
+    """Search the inventory by free-text query. Returns matching SKUs."""
+    return [{"sku": "abc", "title": "..."}]
+
+@mcp.tool()
+def get_stock(sku: str) -> dict:
+    """Return the current stock count for a SKU."""
+    return {"sku": sku, "stock": 42}
+
+if __name__ == "__main__":
+    mcp.run()  # stdio transport
+```
+
+```bash
+pip install fastmcp
+# or: uv tool install fastmcp
+
+apx mcp add my-server \
+  --command uv --project iacrmar \
+  -- run python /abs/path/my_server.py
+```
+
+## Node (TypeScript SDK) — minimum viable server
+
+```typescript
+// my-server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const server = new Server(
+  { name: "my-server", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "search_inventory",
+      description: "Search the inventory by free-text query.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string" },
+          limit: { type: "number", default: 10 },
+        },
+        required: ["query"],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  if (req.params.name === "search_inventory") {
+    const { query, limit = 10 } = req.params.arguments as any;
+    return {
+      content: [{ type: "text", text: JSON.stringify([{ sku: "abc" }]) }],
+    };
+  }
+  throw new Error(`unknown tool: ${req.params.name}`);
+});
+
+await server.connect(new StdioServerTransport());
+```
+
+```bash
+apx mcp add my-server \
+  --command npx --project iacrmar \
+  -- -y my-server-package
+```
+
+## Tool design rules
+
+1. **Names are snake_case verbs**: `search_inventory`, not `inventorySearch`.
+2. **inputSchema is JSON Schema draft-07**. `required` matters — vague schemas → bad calls.
+3. **Descriptions read like a man-page**. Tool + param descriptions are surfaced to the model.
+4. **Return structured data**, not prose. Convention: JSON inside a text content block. Images use the `image` type.
+5. **Errors are errors**: `throw new Error(...)` propagates as `isError: true`. Empty result = "found nothing" — different signal.
+
+## Env vars and secrets
+
+```bash
+apx mcp add github \
+  --scope runtime --project iacrmar \
+  --command npx \
+  --env GITHUB_TOKEN=ghp_xxx \
+  --env GITHUB_OWNER=manuel \
+  -- -y @modelcontextprotocol/server-github
+```
+
+`--scope runtime` writes to `~/.apx/projects/<id>/mcps.json` (chmod 0600, never committed). NEVER `--scope shared` for tokens — that file lives in `.apc/` and gets committed.
+
+## Anti-examples
+
+```python
+# DON'T expose every internal function. A server with 40 tools eats context.
+# Pick 5-10 high-value tools per server; split into multiple servers if more.
+
+# DON'T return giant blobs in `content`. The agent re-reads every turn.
+# Paginate (`offset`, `limit`) and let the agent ask for more.
+
+# DON'T mix stdio + HTTP transports in one process. APX spawns stdio;
+# for HTTP use `url:` in mcps.json instead of `command:`.
+
+# DON'T print to stdout outside JSON-RPC frames. Stray print() corrupts
+# the protocol — use stderr for logs. (SDKs handle this; bare `print("debug")`
+# in a tool body breaks everything.)
+```
+
+## Debugging
+
+```bash
+# Smoke test (apx mcp tools is a v0.2 stub — don't rely on it)
+apx mcp run my-server search_inventory '{"query":"shoes"}'
+
+# Spawn errors / stderr
+apx log -f
+
+# Scopes / files / env APX sees
+apx mcp check --project iacrmar
+```
+
+## Don't
+
+- Don't reinvent SDK framing — bypass only with reason.
+- Don't make interactive tools. MCP is one-shot per call; split flows into multiple tools.
+- Don't ship without a README — future-you forgets which env vars matter.
+- Don't expect APX to retry MCP errors. The agent sees the error and decides.

package/{skills → src/core/runtime-skills}/apx-project/SKILL.md

@@ -1,30 +1,30 @@
 ---
 name: apx-project
-description: How to register, list, configure, and manage APX projects. Use BEFORE asking the user "which project?" — registered projects are listable; per-project config (model override, etc) is set with dotted-key PATCH.
+description: Register, list, configure, manage APX projects. Load BEFORE asking "which project?" — registered projects are listable; per-project config set via dotted-key PATCH. Triggers: 'register project', 'apx project', 'project config', 'list projects', 'what projects are registered'.
 ---
 
 # apx-project
 
-A project in APX is an APC-compliant folder on disk (`AGENTS.md` + `.apc/project.json`). Once registered, APX keeps runtime state (sessions, messages, routines, tasks, MCPs) under `~/.apx/projects/<apxId>/`.
+A project in APX is an APC-compliant folder (`AGENTS.md` + `.apc/project.json`). Once registered, APX keeps runtime state (sessions, messages, routines, tasks, MCPs) under `~/.apx/projects/<apxId>/`.
 
-## The two kinds of projects
+## Two kinds of projects
 
-- **`default`** (id=0): the super-agent's scratch workspace under `~/.apx/projects/default/`. Used when the user has no project named, has no project registered, or explicitly addresses "apx itself". Don't use it for real work — it's shared.
+- **`default`** (id=0): super-agent's scratch workspace at `~/.apx/projects/default/`. Used when user has no project named, no project registered, or addresses "apx itself". Don't use for real work — shared.
 - **registered** (id=1+): real projects, each rooted at a path the user owns.
 
 ## Concrete CLI calls
 
 ```bash
 # Register
-apx project add /path/to/repo          # registers; reads AGENTS.md + .apc/project.json
+apx project add /path/to/repo          # reads AGENTS.md + .apc/project.json
 apx project add .                       # current dir
 
 # Inspect
 apx project list                        # id, name, agents count, path
 
-# Remove / rebuild (id or exact path only — these do NOT resolve by name)
+# Remove / rebuild (id or exact path only — no name resolution here)
 apx project remove <id|path>
-apx project rebuild <id|path>           # force re-scan of .apc/ on disk
+apx project rebuild <id|path>           # force re-scan of .apc/
 
 # Per-project config — dotted keys, lives in <repo>/.apc/config.json
 apx project config show <project>                                  # effective + project_only
@@ -36,17 +36,11 @@ apx project config unset <project> super_agent.model               # back to glo
 apx project config edit <project>                                  # opens $EDITOR on project_only JSON
 ```
 
-Every write to `project config` triggers `POST /admin/reload` so the daemon picks up the change without restart.
+Every `project config` write triggers `POST /admin/reload` so the daemon picks up changes without restart.
 
-## Resolution of `<project>` argument
+## `<project>` argument resolution
 
-Accepted forms:
-- numeric id: `1`
-- exact name from `.apc/project.json`: `iacrmar`
-- absolute path: `/Volumes/SSDT7Shield/trabajos_proyectos/iacrmar`
-- relative path (from cwd) — resolved before matching.
-
-The CLI calls `resolveProjectId()` which does fuzzy id-or-name-or-path matching. If you got "project not found", `apx project list` first.
+Accepted: numeric id (`1`), exact name from `.apc/project.json` (`iacrmar`), absolute path, relative path (resolved from cwd). The CLI's `resolveProjectId()` does fuzzy id/name/path matching. If "project not found", run `apx project list` first.
 
 ## What lives where
 
@@ -59,7 +53,7 @@ The CLI calls `resolveProjectId()` which does fuzzy id-or-name-or-path matching.
     ├── skills/<slug>.md or <slug>/SKILL.md
     ├── mcps.json                               ← shared MCPs (committed)
     ├── commands/                               ← custom slash-commands
-    └── config.json                             ← project-only overrides (this is what `project config` edits)
+    └── config.json                             ← project-only overrides (edited by `project config`)
 
 ~/.apx/projects/<apxId>/                        ← runtime state (never committed)
 ├── messages/YYYY-MM-DD.jsonl
@@ -70,29 +64,26 @@ The CLI calls `resolveProjectId()` which does fuzzy id-or-name-or-path matching.
 └── mcps.json                                   ← per-project runtime MCPs (local, may hold tokens)
 ```
 
-## Anti-example
+## Anti-examples
 
 ```bash
 # DON'T hand-write AGENTS.md + .apc/project.json with shell tools.
 echo "Hello" > /path/repo/AGENTS.md
-mkdir -p /path/repo/.apc
-echo "{...}" > /path/repo/.apc/project.json
-```
+mkdir -p /path/repo/.apc && echo "{...}" > /path/repo/.apc/project.json
+# ↑ No scaffold validation; project appears registered but breaks on `apx project rebuild`.
+# Use `apx init <path>` then `apx project add <path>`.
 
-There's no scaffold validation, the project will appear registered but break on the first `apx project rebuild`. Use `apx init <path>` (project scaffold) and then `apx project add <path>`.
-
-```bash
-# DON'T set super_agent.model to a model that's not in the engine you have keys for.
+# DON'T set super_agent.model to a model lacking an engine key.
 apx project config set iacrmar super_agent.model gemini:gemini-1.5-pro
-# ↑ Will fail at first call unless engines.gemini.api_key is set.
+# ↑ Fails at first call unless engines.gemini.api_key is set.
 ```
 
 ## When asked "what projects are there?"
 
-Don't ask. Call `list_projects` (tool) or `apx project list`. Same for "which agents does X have?" → `list_agents` / `apx agent list --project X`.
+Don't ask — call `list_projects` tool or `apx project list`. Same for "which agents does X have?" → `list_agents` / `apx agent list --project X`.
 
 ## Don't
 
-- Don't operate on the default project (id=0) as if it were the user's main work. It's a scratch space for super-agent state.
+- Don't operate on the default project (id=0) as if it were the user's main work. Scratch space for super-agent state.
 - Don't put secrets in `.apc/config.json` — it's committed. Put them in `~/.apx/config.json` (machine-local) under `engines.*` or `voice.tts.*`.
-- Don't move a project's `.apc/` folder without re-running `apx project rebuild` afterwards. The `apxId` will be stale.
+- Don't move a project's `.apc/` folder without re-running `apx project rebuild` — `apxId` will be stale.

package/src/core/runtime-skills/apx-routine/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: apx-routine
+description: Create, edit, run, debug APX routines (scheduled tasks). Load BEFORE `apx routine add` — schedule grammar, kind selection, pre/post hooks, double-reply gotcha.
+---
+
+# apx-routine
+
+A scheduled APX task. Scheduler ticks every 5s. Each routine has a `kind`, `schedule`, optional `spec`, and optional `pre_commands` / `post_commands` shell hooks.
+
+## Picking `kind`
+
+| Kind | Tools? | Description |
+|---|---|---|
+| `heartbeat` | no | "Still alive" marker. No LLM. |
+| `shell` | no | Pure shell. Stdout captured. |
+| `exec_agent` | **no** | Loads agent prompt, sends `spec.prompt`, returns text. Single LLM call. |
+| `super_agent` | **all** | Default agent with full tool registry. Multi-iteration loop. |
+| `telegram` | n/a | Sends hardcoded text via Telegram plugin. |
+
+Rule: text from model → `exec_agent`; orchestration (MCPs, files, multi-agent) → `super_agent`; pure shell → `shell`; fixed Telegram poke → `telegram`.
+
+## Schedule grammar
+
+- `every:<N><unit>` — `every:30s`, `every:5m`, `every:24h`, `every:7d`. **Most common.**
+- `once:<iso-8601>` — `once:2026-12-01T08:00:00Z`. Fires once, then disabled.
+- Cron — `*/5 * * * *`, `0 8 * * *`. Standard 5-field.
+
+## Anatomy
+
+```json
+{
+  "name": "weather-bariloche",
+  "kind": "exec_agent",
+  "schedule": "every:24h",
+  "spec": { "agent": "default", "prompt": "Write a short greeting..." },
+  "pre_commands":  ["curl -s 'https://wttr.in/Bariloche?format=...'"],
+  "post_commands": ["apx telegram send \"$APX_LLM_OUTPUT\""],
+  "enabled": true,
+  "skip_prompt_on": "signal"
+}
+```
+
+Pipeline: `pre_commands` run sequentially → combined stdout becomes `{{pre_output}}` in `spec.prompt` and `$APX_PRE_OUTPUT` (plus `$APX_PRE_OUTPUT_FILE` for big payloads) → handler runs, result becomes `$APX_LLM_OUTPUT` → `post_commands` run.
+
+## Anti-example: double-reply
+
+```json
+{
+  "kind": "super_agent",   ← DON'T
+  "spec": { "prompt": "The weather is {{pre_output}}. Send it via Telegram." },
+  "post_commands": ["apx telegram send \"$APX_LLM_OUTPUT\""]
+}
+```
+
+Sends **two** messages: one from agent's `send_telegram` tool, one from `post_commands`. The runner auto-suppresses `send_telegram` when post contains `apx telegram send`, but the clean fix is `exec_agent`:
+
+```json
+{
+  "kind": "exec_agent",
+  "spec": { "agent": "default", "prompt": "The weather is {{pre_output}}. One friendly sentence." },
+  "post_commands": ["apx telegram send \"$APX_LLM_OUTPUT\""]
+}
+```
+
+## Concrete CLI calls
+
+```bash
+# Always pin --project; never use default for real ones
+apx routine list --project iacrmar
+apx routine get  weather-bariloche --project iacrmar
+
+# Create — exec_agent + shell delivery
+apx routine add weather-bariloche \
+  --project iacrmar \
+  --kind exec_agent \
+  --schedule "every:24h" \
+  --spec '{"agent":"default","prompt":"The weather is {{pre_output}}. One friendly sentence."}' \
+  --pre-commands "curl -s 'https://wttr.in/Bariloche?format=%t+%C+viento+%w'" \
+  --post-commands 'apx telegram send "$APX_LLM_OUTPUT"'
+
+# Create — super-agent with tools
+apx routine add daily-status \
+  --project iacrmar \
+  --kind super_agent \
+  --schedule "0 9 * * *" \
+  --spec '{"prompt":"List projects with pending tasks and send me a short summary via Telegram."}' \
+  --permission-mode automatico
+
+# Toggle / run / remove
+apx routine enable  weather-bariloche --project iacrmar
+apx routine disable weather-bariloche --project iacrmar
+apx routine run     weather-bariloche --project iacrmar     # force-trigger now
+apx routine remove  weather-bariloche --project iacrmar
+```
+
+## `--project` is non-negotiable
+
+Routines live in `~/.apx/projects/<apxId>/routines.json`. Without `--project`, they go to default (id=0, super-agent scratch) — **not** a user project. Always pass `--project <name|id|path>`.
+
+## `skip_prompt_on`
+
+Gates the LLM call based on `pre_commands` (`shouldSkipPrompt` in `host/daemon/routines.js`). Post-commands always run.
+
+| Value | Skips LLM when… |
+|---|---|
+| `signal` (default) | pre_command prints literal `APX_SKIP`. Non-zero exit alone does NOT skip. |
+| `pre_failure` | any pre_command exits non-zero. |
+| `pre_success` | pre_commands exit 0 (LLM only on pre failure). |
+| `always` | unconditionally — pure pre→post, no LLM. |
+| `never` | LLM always runs, even if pre crashes. |
+
+## Debugging
+
+```bash
+apx routine history weather-bariloche --project iacrmar    # last runs
+apx log -f                                                  # tail unified log
+apx messages tail --channel routine -n 20                   # routine-channel messages
+```
+
+"Sends nothing" usually means: `enabled: false`, `next_run_at` in the future, or empty LLM text (check `apx messages` or `result.text`).
+
+## Don't
+
+- Use `super_agent` when `exec_agent` would do — it loops, calls tools, costs more.
+- Write `apx telegram send` inside a `super_agent` prompt — agent calls `send_telegram` AND post_commands fire. Pick one.
+- Hardcode model names in `spec` without reason — routines inherit `super_agent.model` (with router fallback).
+- Put credentials in `spec`. Use `~/.apx/config.json` engines and reference by provider.

package/src/core/runtime-skills/apx-runtime/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: apx-runtime
+description: Delegate a task to an external coding CLI (claude-code, codex, opencode, aider, cursor-agent, gemini-cli, qwen-code) via `apx run`. APX builds the system prompt, spawns the CLI, captures the result. Load when delegating to another AI tool.
+---
+
+# apx-runtime
+
+A "runtime" is an external AI coding CLI that APX invokes headlessly. APX builds the agent's system prompt, spawns the CLI with the right flags, captures stdout (and the external session id when available), and stores run metadata as a session file under `~/.apx/projects/<apxId>/agents/<slug>/sessions/` (never committed). Some flows link to the engine's own transcript path.
+
+## Supported runtimes
+
+| id | binary | Headless flag |
+|---|---|---|
+| `claude-code`   | `claude`        | `-p "<prompt>" --append-system-prompt "<sys>" --output-format json` |
+| `codex`         | `codex`         | `exec "<prompt>"` (works outside git repos) |
+| `opencode`      | `opencode`      | non-interactive mode |
+| `aider`         | `aider`         | `--message "<prompt>" --no-stream` |
+| `cursor-agent`  | `cursor-agent`  | headless print mode |
+| `gemini-cli`    | `gemini`        | headless prompt mode |
+| `qwen-code`     | `qwen-code`     | system prompt passed separately |
+
+`apx env detect` reports which are installed and reachable.
+
+## Concrete CLI calls
+
+```bash
+apx env detect          # which runtimes are installed
+apx env list            # alias
+
+apx run reviewer --runtime claude-code "Review the diff in src/host/daemon/api/ for memory leaks"
+apx run scratch  --runtime codex       "Refactor parseAgentsMd to use a state machine"
+apx run scratch  --runtime opencode    "<prompt>"
+apx run scratch  --runtime codex --timeout 300 "<prompt>"   # cap (seconds)
+apx run scratch  --runtime codex -      # prompt from stdin (large prompts)
+```
+
+Behavior:
+1. APX picks project from `--project` or cwd.
+2. Reads agent's `AGENT.md` + memory + skills; builds system prompt with `buildAgentSystem({ invocation: "runtime", runtime: "<id>" })`.
+3. Spawns CLI with the right flags; cwd = project path.
+4. Captures stdout. If runtime printed `APC_RESULT: <value>`, that's the structured result; else first 200 chars of stdout.
+5. Writes `~/.apx/projects/<apxId>/agents/<slug>/sessions/<YYYY-MM-DD>-<id>.md` with frontmatter linking back to the external transcript when available.
+
+## Resuming an external session
+
+The session file references the external transcript:
+
+```yaml
+# ~/.apx/projects/<apxId>/agents/reviewer/sessions/2026-05-27-claude-code-abc123.md
+---
+external_session_path: /Users/.../.claude/projects/<...>/abc123.jsonl
+runtime: claude-code
+session_id: abc123
+---
+```
+
+Full resume/get/continue/summarise lives in the **`apx-sessions`** skill. Quick paths:
+
+```bash
+apx sessions list --engine claude --project iacrmar
+apx session resume <id>                          # auto-detects engine
+apx session resume <id> --continue               # spawn native CLI to keep going
+apx session resume <id> --summary                # super-agent summary
+apx session resume <id> --into apx:<slug>        # seed new APX session
+apx session get <id> --any --full                # or --engine claude --tail 16k
+```
+
+See `apx-sessions` for full flag reference, collision handling, and daemon-vs-no-daemon matrix.
+
+## APC_RESULT contract
+
+To capture a structured value from the external runtime, instruct it via the prompt to print on its last line:
+
+```
+APC_RESULT: <one-line value>
+```
+
+`extractApfResult()` parses that into the session's `result` field. Useful for automation return values.
+
+## Anti-examples
+
+- DON'T expect `apx run` to be interactive — it's headless. For interactive, invoke the CLI directly (e.g. `claude`).
+- DON'T pass huge prompts via command line (shell arg limits). For >~10KB, use stdin (`-`) or a temp file.
+- DON'T expect APX to impose a model on the external CLI. APX passes system + user prompt only; the external CLI's own config wins.
+
+## When to use which
+
+| You want | Pick |
+|---|---|
+| Pair-program with file edits + shell | `claude-code` if installed, else `codex` |
+| Lightweight LLM run, no tools | `apx exec <agent> "<prompt>"` (no runtime needed) |
+| Super-agent to call other agents | `call_agent` tool (in-process, no spawn) |
+| Persisted state across days | `apx run` with `claude-code` or `codex` (their sessions persist) |
+
+## Don't
+
+- Run untrusted prompts in a `--runtime` CLI with broad tool permissions — the CLI may take file/shell actions.
+- Expect APX to track tool calls inside the external transcript. APX captures stdout + external session path only; inspect the external transcript for tool-level audit.
+- Pick a runtime the user doesn't have installed; `apx env detect` first.