@agentprojectcontext/apx 1.33.1 → 1.35.0

package/skills/apx-mcp-builder/SKILL.md

@@ -1,183 +0,0 @@
----
-name: apx-mcp-builder
-scope: internal
-description: How to build a Model Context Protocol (MCP) server from scratch and register it in APX. Load when authoring a new MCP / exposing a new tool surface to agents. Covers the JSON-RPC stdio protocol, FastMCP (Python) / TypeScript SDK shapes, and APX registration.
----
-
-# apx-mcp-builder
-
-A **Model Context Protocol** server is a tiny process the agent talks to over stdio JSON-RPC. APX spawns it (via `apx mcp add`), discovers its tools (`tools/list`), and lets the super-agent call them by name. This skill is for **authoring a new MCP server**. To **add an existing one** to APX, load `apx-mcp` instead.
-
-## The minimum surface
-
-An MCP server must implement four RPC methods:
-
-| Method | Purpose | Returns |
-|---|---|---|
-| `initialize` | Handshake. APX sends protocol version + capabilities. | Server's capabilities. |
-| `tools/list` | Enumerate available tools. | `{ tools: [{name, description, inputSchema}] }` |
-| `tools/call` | Run one tool. APX sends `{ name, arguments }`. | `{ content: [...], isError? }` |
-| `notifications/initialized` | One-way; APX signals it's done initializing. | — |
-
-JSON-RPC 2.0 framing over stdio. Each message: `Content-Length: N\r\n\r\n<JSON>`. The `@modelcontextprotocol/sdk` (TS) and `fastmcp` / `mcp` (Python) packages handle framing for you.
-
-## Pick a stack
-
-| Stack | When |
-|---|---|
-| **Python + FastMCP** | Fastest path. Decorator-based. Great if your tools wrap pip libs. |
-| **Node + @modelcontextprotocol/sdk** | When the tool calls Node-only libs, or you want zero install (`npx -y`). |
-| Raw JSON-RPC | Only if you have an existing daemon you want to expose. Otherwise 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."""
-    # ... your logic ...
-    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 by default
-```
-
-Install:
-```bash
-pip install fastmcp
-# or via uv (recommended):
-uv tool install fastmcp
-```
-
-Register in APX:
-```bash
-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;
-    // ... your logic ...
-    return {
-      content: [{ type: "text", text: JSON.stringify([{ sku: "abc" }]) }],
-    };
-  }
-  throw new Error(`unknown tool: ${req.params.name}`);
-});
-
-await server.connect(new StdioServerTransport());
-```
-
-Register:
-```bash
-apx mcp add my-server \
-  --command npx --project iacrmar \
-  -- -y my-server-package
-```
-
-## Tool design rules
-
-1. **Names are snake_case**, verbs preferred: `search_inventory`, not `inventorySearch`.
-2. **inputSchema is JSON Schema draft-07**. Be strict: `required` matters. The agent reads the schema; vague schemas → bad calls.
-3. **Descriptions read like a CLI man-page**. Each tool's description and each param's description gets surfaced to the model. Make them count.
-4. **Return structured data**, not prose. MCP `content` can be text but the convention is to put JSON inside a text block so the agent can parse it back. For images, use the `image` content type.
-5. **Errors are errors, not silent empty**. `throw new Error(...)` propagates as `isError: true` and the agent will see it. Empty results = "found nothing"; that's a different signal.
-
-## Env vars and secrets
-
-Pass them at registration time via `--env`:
-
-```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 use `--scope shared` for tokens — that file lives in `.apc/` and gets committed.
-
-## Anti-examples
-
-```python
-# DON'T expose every internal function as a tool.
-# A server with 40 tools is a context budget killer. Pick 5-10 high-value
-# tools per server; split into multiple servers if you have more.
-
-# DON'T return giant blobs in `content`. The agent has to read all of it
-# every turn. Paginate (`offset`, `limit`) and let the agent ask for more.
-
-# DON'T mix stdio + HTTP transports in the same process. Pick one. APX
-# spawns stdio servers; if you want HTTP, use `url:` in mcps.json instead
-# of `command:`.
-
-# DON'T print to stdout other than JSON-RPC frames. Any stray print()
-# corrupts the protocol — use stderr for logs. (FastMCP / the SDK handle
-# this for you, but `print("debug")` in a tool body breaks everything.)
-```
-
-## Common debugging path
-
-```bash
-# 1. Does the server start + does a tool work? (apx mcp tools is a v0.2 stub — don't rely on it)
-apx mcp run my-server search_inventory '{"query":"shoes"}'
-
-# 2. Are there spawn errors?
-apx log -f                              # tail the daemon log — stderr lands here
-
-# 3. What scopes/files + env does APX see?
-apx mcp check --project iacrmar
-```
-
-## Don't
-
-- Don't reinvent the SDK framing. FastMCP / @modelcontextprotocol/sdk handle the stdio JSON-RPC dance — bypass only if you really need to.
-- Don't make tools that require interactive input. MCP is one-shot per call. If you need a flow, design separate tools for each step.
-- Don't ship a server without a README in the repo. Future-you will not remember which env vars matter.
-- Don't expect APX to retry MCP errors automatically. The agent sees the error and decides.

package/skills/apx-routine/SKILL.md

@@ -1,140 +0,0 @@
----
-name: apx-routine
-description: How to create, edit, run, and debug APX routines. Use BEFORE writing any `apx routine add` command — schedule grammar, kind selection, pre/post commands, and the gotchas that produce double-replies.
----
-
-# apx-routine
-
-A routine is a scheduled APX task. APX runs the scheduler tick every 5s and fires routines that are due. Each routine has a `kind`, a `schedule`, an optional `spec`, and optional `pre_commands` / `post_commands` shell hooks.
-
-## When to use which `kind`
-
-| Kind | Tools? | Description |
-|---|---|---|
-| `heartbeat` | no | Logs a marker message. Useful as a "still alive" ping. No LLM call. |
-| `shell` | no | Pure shell command. No LLM. Stdout captured. |
-| `exec_agent` | **no tools** | Loads a project agent's system prompt, sends `spec.prompt` to the engine, returns plain text. Single LLM call. |
-| `super_agent` | **all tools** | Runs the APX default agent (super-agent mode) with the full tool registry. Multi-iteration tool loop. |
-| `telegram` | n/a | Sends a hardcoded text via the Telegram plugin. |
-
-**Picking rule of thumb**:
-- Just need text from a model? → `exec_agent`.
-- Need orchestration (call MCPs, write files, call other agents, send messages with logic)? → `super_agent`.
-- Pure shell (curl + jq + write somewhere)? → `shell`.
-- Periodic Telegram poke with fixed text? → `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 at that instant, then disabled.
-- Cron — `*/5 * * * *`, `0 8 * * *`. Standard 5-field. Use only if you really need cron expressions.
-
-## Anatomy of a routine
-
-```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"
-}
-```
-
-**The pipeline**:
-1. `pre_commands` run sequentially. Their combined stdout becomes `{{pre_output}}` substitutable in `spec.prompt`, and `$APX_PRE_OUTPUT` env var available to `post_commands`. Also written to `$APX_PRE_OUTPUT_FILE` for big payloads.
-2. The handler for `kind` runs. Its text result is exposed to post hooks as `$APX_LLM_OUTPUT`.
-3. `post_commands` run sequentially with that env.
-
-## Anti-example: the 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\""]
-}
-```
-
-This sends **two** Telegram messages: one from the super-agent's `send_telegram` tool call, one from `post_commands`. The runner now auto-suppresses `send_telegram` when `post_commands` contains `apx telegram send` (see spec/done/01), but the cleaner fix is to use `exec_agent`:
-
-```json
-{
-  "kind": "exec_agent",
-  "spec": { "agent": "default", "prompt": "The weather is {{pre_output}}. One friendly sentence, no greeting." },
-  "post_commands": ["apx telegram send \"$APX_LLM_OUTPUT\""]
-}
-```
-
-One message, the model writes prose, the shell pipes it to Telegram.
-
-## Concrete CLI calls
-
-```bash
-# List routines per project (always pin --project; never use default for real ones)
-apx routine list --project iacrmar
-
-# Inspect one
-apx routine get weather-bariloche --project iacrmar
-
-# Create — text-only 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`, the default project (id=0, the super-agent's scratch workspace) gets the routine — that is **not** a user project. Always pass `--project <name|id|path>`.
-
-## `skip_prompt_on`
-
-Controls whether the LLM call is skipped based on the `pre_commands` result (`shouldSkipPrompt` in `host/daemon/routines.js`):
-
-| Value | Skips the LLM when… |
-|---|---|
-| `signal` (default) | a pre_command prints the literal marker `APX_SKIP` to stdout. A non-zero exit alone does **not** skip. |
-| `pre_failure` | any pre_command exits non-zero. |
-| `pre_success` | the pre_commands exit 0 (i.e. run the LLM only on pre failure). |
-| `always` | unconditionally — pure pre→post pipeline, no LLM. |
-| `never` | never — the LLM always runs, even if pre crashes. |
-
-Post-commands run regardless of the skip decision. The skip only gates the `kind` handler (the LLM call).
-
-## Debugging a routine
-
-```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
-```
-
-A routine that "sends nothing" most often means: (a) `enabled: false`, (b) `next_run_at` is in the future, (c) the LLM returned empty text — visible in `apx messages` or in the `result.text` of `apx routine run`.
-
-## Don't
-
-- Don't use `super_agent` when `exec_agent` would do. The super-agent loops, calls tools, costs more.
-- Don't write `apx telegram send` inside a `super_agent` routine prompt — the agent will call `send_telegram` AND `post_commands` will fire. Pick one.
-- Don't hardcode model names in `spec` unless you have a reason — the routine inherits `super_agent.model` (with router fallback) by default.
-- Don't put credentials in routine `spec`. Put them in `~/.apx/config.json` engines and reference them by provider.

package/skills/apx-runtime/SKILL.md

@@ -1,117 +0,0 @@
----
-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, and captures the result. Load when delegating work to another AI tool.
----
-
-# apx-runtime
-
-A "runtime" in APX is an external AI coding CLI that APX can invoke headlessly. APX builds the agent's system prompt, spawns the CLI with the right flags, captures the stdout (and the external tool's session id when available), and stores the run metadata as a session file under `~/.apx/projects/<apxId>/agents/<slug>/sessions/` (runtime state — never committed). Some flows also link to the external 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`     | passes system prompt separately |
-
-`apx env detect` reports which are installed and reachable.
-
-## Concrete CLI calls
-
-```bash
-# What's available on this machine
-apx env detect          # which runtimes are installed and reachable
-apx env list            # alias of `apx env detect`
-
-# Run an agent through an external CLI
-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 the run (seconds)
-apx run scratch  --runtime codex -      # read the prompt from stdin (large prompts)
-```
-
-Behavior:
-1. APX picks the project from `--project` or cwd.
-2. Reads the agent's `AGENT.md` + memory + skills, builds the system prompt with `buildAgentSystem({ invocation: "runtime", runtime: "<id>" })`.
-3. Spawns the CLI with the right flags. cwd = project path.
-4. Captures stdout. If the runtime printed `APC_RESULT: <value>`, that's the structured result; else the 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 tool's own session file (when available).
-
-## Resuming an external session
-
-After a `apx run`, the resulting APC 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
----
-```
-
-All session resume / get / continue / summarise operations live in the
-**`apx-sessions`** skill. From here, the most common quick paths:
-
-```bash
-# Discover the id (or use the one printed by `apx run`)
-apx sessions list --engine claude --project iacrmar
-
-# Resume — apx auto-detects which engine owns the id
-apx session resume <id>
-apx session resume <id> --continue              # spawn the native CLI to keep going
-apx session resume <id> --summary               # super-agent summary of the transcript
-apx session resume <id> --into apx:<slug>       # seed a new APX session with the summary
-
-# Just read the transcript
-apx session get <id> --any --full               # or --engine claude --tail 16k
-```
-
-See the `apx-sessions` skill for the full flag reference, collision handling,
-and daemon-vs-no-daemon matrix.
-
-## APC_RESULT contract
-
-When you want APX to capture a structured value from the external runtime, instruct the runtime via the prompt to print on its last line:
-
-```
-APC_RESULT: <one-line value>
-```
-
-APX `extractApfResult()` parses that and stores it as the session's `result` field. Useful for return values from automation.
-
-## Anti-examples
-
-```bash
-# DON'T expect `apx run` to be interactive. It's headless.
-# For interactive, just invoke the CLI directly (e.g. `claude` for Claude Code).
-
-# DON'T pass huge prompts via the command line (shell args have limits).
-# For prompts > ~10KB, use a stdin-friendly route or write a temp file and reference it.
-
-# DON'T forget that each runtime has its own model selection.
-# APX passes the system prompt and the user prompt; it does NOT impose a model on
-# the external CLI. The user's external CLI config (e.g. Claude Code's CLAUDE.md
-# defaults) wins.
-```
-
-## When to use which
-
-| You want | Pick |
-|---|---|
-| Pair-program with file edits and shell | `claude-code` if the user has Claude Code, else `codex` |
-| Lightweight LLM run with no tools | `apx exec <agent> "<prompt>"` (no runtime needed) |
-| The super-agent to call other agents | `call_agent` tool (in-process, no spawn) |
-| Run something that needs persisted state across days | `apx run` with `claude-code` or `codex` (their sessions persist) |
-
-## Don't
-
-- Don't run untrusted prompts in `--runtime` of a CLI with broad tool permissions on the user's machine. The CLI may take file write or shell actions.
-- Don't expect APX to track tool calls inside the external CLI's transcript. APX captures stdout and the external session path — that's it. Inspect the external transcript directly for tool-level audit.
-- Don't pick a runtime the user doesn't have installed; `apx env detect` first if unsure.