@agentprojectcontext/apx 1.10.3 → 1.11.0

package/README.md

@@ -113,10 +113,14 @@ can distinguish Telegram users from APX agents and future subagents.
 | Runtime | Description |
 |---------|-------------|
 | `claude-code` | Spawns Claude Code CLI with the agent's system prompt injected |
-| `codex` | OpenAI Codex CLI |
+| `codex` | OpenAI Codex CLI via non-interactive `codex exec --sandbox workspace-write --skip-git-repo-check` |
 | `opencode` | OpenCode CLI |
 | `aider` | Aider CLI |
 
+Global APX skill installation also writes named helper skills for `codex-cli`, `claude-code`,
+`opencode-cli`, and `openrouter`. They are intentionally narrow and should activate only when those
+tools/providers are explicitly mentioned.
+
 ## Engines (for `apx exec`)
 
 Configured in `~/.apx/config.json`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.10.3",
+  "version": "1.11.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"
@@ -35,6 +35,10 @@
     "express": "^4.21.0",
     "node-fetch": "^3.3.2"
   },
+  "optionalDependencies": {
+    "fast-glob": "^3.3.2",
+    "puppeteer": "^22.0.0"
+  },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",

package/src/cli/commands/search.js

@@ -0,0 +1,62 @@
+// cli/commands/search.js
+// `apx search "query"` — web search from the terminal.
+// Uses the daemon's tools/search.js module directly (no HTTP roundtrip,
+// no need to have `apx daemon start` running).
+
+import { webSearch } from "../../daemon/tools/search.js";
+
+const DIM   = "\x1b[2m";
+const BOLD  = "\x1b[1m";
+const BLUE  = "\x1b[34m";
+const CYAN  = "\x1b[36m";
+const RESET = "\x1b[0m";
+
+export async function cmdSearch(args) {
+  const query = (args._ || []).join(" ").trim();
+  if (!query) {
+    console.error("apx search: missing <query>");
+    console.error("usage: apx search \"<query>\" [--mode auto|ddg|brave|browser] [-n N]");
+    process.exit(1);
+  }
+
+  const mode  = args.flags?.mode || "auto";
+  const limit = parseInt(args.flags?.n || args.flags?.limit || "5", 10) || 5;
+  const json  = !!args.flags?.json;
+
+  process.stderr.write(`${DIM}Searching... (${mode})${RESET}\n`);
+
+  let r;
+  try {
+    r = await webSearch({ query, mode, limit });
+  } catch (e) {
+    console.error(`${DIM}error:${RESET} ${e.message}`);
+    process.exit(1);
+  }
+
+  if (json) {
+    console.log(JSON.stringify(r, null, 2));
+    return;
+  }
+
+  const results = r.results || [];
+  if (results.length === 0) {
+    console.log(`${DIM}(no results from ${r.mode})${RESET}`);
+    if (r.raw_excerpt) console.log(`${DIM}excerpt:${RESET} ${r.raw_excerpt.slice(0, 400)}…`);
+    return;
+  }
+
+  console.log(`${DIM}${results.length} result${results.length === 1 ? "" : "s"} via ${r.mode}${RESET}\n`);
+  results.forEach((item, i) => {
+    const num = `[${i + 1}]`;
+    const title = item.title || "(no title)";
+    console.log(`${BOLD}${num} ${title}${RESET}  ${DIM}— ${hostname(item.url)}${RESET}`);
+    if (item.snippet) console.log(`    ${item.snippet}`);
+    console.log(`    ${BLUE}${item.url}${RESET}`);
+    if (i < results.length - 1) console.log("");
+  });
+}
+
+function hostname(url) {
+  try { return new URL(url).hostname.replace(/^www\./, ""); }
+  catch { return url; }
+}

package/src/cli/commands/sys.js

@@ -32,10 +32,12 @@ export async function cmdSys(args) {
     hasStarted: false,
     sessionTitle: "",
     usage: { input: 0, output: 0, percent: 0 },
+    chatScrollOffset: 0,
     transcript: [],
   };
 
   const previousMessages = [];
+  const pendingPrompts = [];
   let restored = false;
   let isRequesting = false;
 
@@ -74,8 +76,6 @@ export async function cmdSys(args) {
   renderScreen();
 
   process.stdin.on("keypress", async (str, key) => {
-    if (isRequesting) return;
-
     if (key.ctrl && key.name === "c") {
       close();
     }
@@ -102,9 +102,16 @@ export async function cmdSys(args) {
       return;
     }
 
+    if (handleScrollKey(key, state, renderScreen)) return;
+
     if (isReturnKey(key)) {
+      if (isRequesting) {
+        queuePrompt(state, pendingPrompts, renderScreen);
+        return;
+      }
+
       isRequesting = true;
-      await submitPrompt(pid, state, previousMessages, renderScreen, close);
+      await submitPromptQueue(pid, state, previousMessages, pendingPrompts, renderScreen, close);
       isRequesting = false;
       return;
     }
@@ -117,6 +124,37 @@ export function isReturnKey(key) {
   return key?.name === "return" || key?.name === "enter";
 }
 
+export function handleScrollKey(key, state, renderScreen) {
+  if (!state.hasStarted || !key) return false;
+  const pageSize = key.name === "pageup" || key.name === "pagedown" ? 8 : 3;
+
+  if (key.name === "pageup" || key.name === "up" || (key.ctrl && key.name === "up")) {
+    state.chatScrollOffset = Math.min(100000, (state.chatScrollOffset || 0) + pageSize);
+    renderScreen();
+    return true;
+  }
+
+  if (key.name === "pagedown" || key.name === "down" || (key.ctrl && key.name === "down")) {
+    state.chatScrollOffset = Math.max(0, (state.chatScrollOffset || 0) - pageSize);
+    renderScreen();
+    return true;
+  }
+
+  if (key.meta && key.name === "up") {
+    state.chatScrollOffset = Math.min(100000, (state.chatScrollOffset || 0) + 20);
+    renderScreen();
+    return true;
+  }
+
+  if (key.meta && key.name === "down") {
+    state.chatScrollOffset = 0;
+    renderScreen();
+    return true;
+  }
+
+  return false;
+}
+
 async function handlePaletteKey(key, cfg, state, renderScreen, close) {
   if (key.name === "up") {
     state.paletteSelection = Math.max(0, state.paletteSelection - 1);
@@ -276,18 +314,46 @@ export function handleEditingKey(str, key, state, renderScreen) {
   return false;
 }
 
-async function submitPrompt(pid, state, previousMessages, renderScreen, close) {
+function queuePrompt(state, pendingPrompts, renderScreen) {
   const text = state.inputText.trim();
   if (!text) return;
-  if (text.toLowerCase() === "exit" || text.toLowerCase() === "quit") {
+
+  state.hasStarted = true;
+  state.inputText = "";
+  state.cursorIndex = 0;
+  state.chatScrollOffset = 0;
+
+  const item = { type: "user", text, meta: "queued" };
+  pendingPrompts.push({ text, item });
+  state.transcript.push(item);
+  renderScreen();
+}
+
+async function submitPromptQueue(pid, state, previousMessages, pendingPrompts, renderScreen, close) {
+  const firstText = state.inputText.trim();
+  if (!firstText) return;
+  if (firstText.toLowerCase() === "exit" || firstText.toLowerCase() === "quit") {
     close();
   }
 
   state.hasStarted = true;
   state.inputText = "";
   state.cursorIndex = 0;
-  state.transcript.push({ type: "user", text });
-  state.transcript.push({ type: "status", text: "Thinking..." });
+  state.chatScrollOffset = 0;
+
+  const firstItem = { type: "user", text: firstText };
+  state.transcript.push(firstItem);
+  await runPrompt(pid, state, previousMessages, renderScreen, firstText, firstItem);
+
+  while (pendingPrompts.length > 0) {
+    const queued = pendingPrompts.shift();
+    delete queued.item.meta;
+    await runPrompt(pid, state, previousMessages, renderScreen, queued.text, queued.item);
+  }
+}
+
+async function runPrompt(pid, state, previousMessages, renderScreen, text, userItem) {
+  appendLiveItem(state, { type: "status", text: "Thinking...", active: true });
   renderScreen();
 
   const startTime = Date.now();
@@ -312,29 +378,42 @@ async function submitPrompt(pid, state, previousMessages, renderScreen, close) {
       result = await http.post(`/projects/${pid}/super-agent/chat`, body);
       removeStatus(state);
       for (const trace of result.trace || []) {
-        state.transcript.push({ type: "tool", trace });
+        appendLiveItem(state, { type: "tool", trace });
       }
     }
 
     completeSuperAgentResult(result, text, startTime, state, previousMessages);
   } catch (e) {
     removeStatus(state);
-    state.transcript.push({ type: "error", text: e.message });
+    appendLiveItem(state, { type: "error", text: e.message });
   }
 
+  if (userItem) delete userItem.meta;
   renderScreen();
 }
 
 function removeStatus(state) {
-  const last = state.transcript[state.transcript.length - 1];
-  if (last?.type === "status") state.transcript.pop();
+  for (let i = state.transcript.length - 1; i >= 0; i--) {
+    if (state.transcript[i]?.type === "status" && state.transcript[i]?.active) {
+      state.transcript.splice(i, 1);
+      return;
+    }
+  }
+}
+
+function appendLiveItem(state, item) {
+  const queuedIndex = state.transcript.findIndex(
+    (entry) => entry?.type === "user" && entry?.meta === "queued"
+  );
+  if (queuedIndex >= 0) state.transcript.splice(queuedIndex, 0, item);
+  else state.transcript.push(item);
 }
 
 function handleProgressEvent(event, state, renderScreen) {
   if (event.type === "model_start") {
-    const last = state.transcript[state.transcript.length - 1];
-    if (last?.type === "status") {
-      last.text = event.iteration > 1 ? `Thinking... step ${event.iteration}` : "Thinking...";
+    const status = [...state.transcript].reverse().find((item) => item?.type === "status" && item?.active);
+    if (status) {
+      status.text = event.iteration > 1 ? `Thinking... step ${event.iteration}` : "Thinking...";
       renderScreen();
     }
     return;
@@ -342,7 +421,7 @@ function handleProgressEvent(event, state, renderScreen) {
 
   if (event.type === "assistant_text" && event.text) {
     removeStatus(state);
-    state.transcript.push({
+    appendLiveItem(state, {
       type: "assistant",
       name: state.activeAgent,
       text: event.text,
@@ -354,7 +433,7 @@ function handleProgressEvent(event, state, renderScreen) {
 
   if (event.type === "tool_start" && event.trace) {
     removeStatus(state);
-    state.transcript.push({ type: "tool", trace: event.trace });
+    appendLiveItem(state, { type: "tool", trace: event.trace });
     renderScreen();
     return;
   }
@@ -365,7 +444,7 @@ function handleProgressEvent(event, state, renderScreen) {
       (item) => item.type === "tool" && item.trace?.id && item.trace.id === event.trace.id
     );
     if (idx >= 0) state.transcript[idx] = { type: "tool", trace: event.trace };
-    else state.transcript.push({ type: "tool", trace: event.trace });
+    else appendLiveItem(state, { type: "tool", trace: event.trace });
     renderScreen();
   }
 }
@@ -383,7 +462,7 @@ function completeSuperAgentResult(result, userText, startTime, state, previousMe
   state.usage.output += result.usage?.output_tokens || 0;
   state.usage.percent = Math.min(99, Math.round((state.usage.input / 200000) * 100));
 
-  state.transcript.push({
+  appendLiveItem(state, {
     type: "assistant",
     name: state.activeAgent,
     text: result.text,

package/src/cli/index.js

@@ -54,6 +54,7 @@ import {
   cmdTelegramSetup,
 } from "./commands/telegram.js";
 import { cmdMessagesTail, cmdMessagesSearch, cmdMessagesChat } from "./commands/messages.js";
+import { cmdSearch } from "./commands/search.js";
 import { cmdExec } from "./commands/exec.js";
 import {
   cmdChat,
@@ -653,6 +654,21 @@ const HELP_TOPICS = new Map(Object.entries({
     options: [["--project <name|id|path>", "Pin command to a specific project."]],
     examples: ["apx messages search \"deploy\""],
   }),
+  search: topic({
+    title: "apx search",
+    summary: "Web search from the terminal (DuckDuckGo / Brave / Puppeteer fallback).",
+    usage: ["apx search \"<query>\" [--mode auto|ddg|brave|browser] [-n N] [--json]"],
+    options: [
+      ["--mode <m>", "auto (default) | ddg | brave | browser. Brave needs BRAVE_API_KEY."],
+      ["-n N",       "Number of results (default 5, max 20)."],
+      ["--json",     "Output raw JSON instead of the formatted list."],
+    ],
+    examples: [
+      "apx search \"agent project context\"",
+      "apx search \"node 22 release notes\" --mode ddg -n 10",
+      "apx search \"weather buenos aires\" --json",
+    ],
+  }),
   "messages chat": topic({
     title: "apx messages chat",
     summary: "Print APX messages as a chat transcript with user, agent, tool, or system type.",
@@ -1129,6 +1145,7 @@ function buildHelp(version) {
     hCmd("apx code",                   36, "APX terminal coding assistant"),
     hCmd("apx exec <agent> \"prompt\"",36, "one-shot agent call  --model <id>  --max-tokens N"),
     hCmd("apx chat <agent>",           36, "interactive agent REPL  --conversation <id>"),
+    hCmd("apx search \"query\"",       36, "web search (ddg | brave | browser)  --mode <m>  -n N"),
     hCmd("apx conversations list",     36, "stored exec/chat conversations for <agent>"),
     hCmd("apx conversations get",      36, "<agent> <id>"),
 
@@ -1433,6 +1450,10 @@ async function dispatch(cmd, rest) {
         await cmdExec(parseArgs(rest));
         break;
 
+      case "search":
+        await cmdSearch(parseArgs(rest));
+        break;
+
       case "chat":
         await cmdChat(parseArgs(rest));
         break;

package/src/cli/terminal-chat/renderer.js

@@ -275,6 +275,9 @@ function transcriptLines(transcript, width) {
       for (const chunk of chunks) {
         addLine(lines, margin + C.primary + "┃" + C.panel + " " + C.text + padAnsi(chunk, inner), C.bg);
       }
+      if (item.meta) {
+        addLine(lines, margin + C.primary + "┃" + C.panel + " " + C.muted + padAnsi(item.meta, inner), C.bg);
+      }
       addLine(lines, margin + C.primary + "┃" + C.panel + " " + " ".repeat(inner), C.bg);
       continue;
     }
@@ -315,14 +318,22 @@ function transcriptLines(transcript, width) {
   return lines;
 }
 
-function renderChat(transcript, chatWidth, height, promptTop) {
+function renderChat(state, chatWidth, height, promptTop) {
   const maxRows = Math.max(1, promptTop - 1);
-  const lines = transcriptLines(transcript, chatWidth - 2);
-  const slice = lines.slice(Math.max(0, lines.length - maxRows));
+  const lines = transcriptLines(state.transcript, chatWidth - 2);
+  const maxOffset = Math.max(0, lines.length - maxRows);
+  const offset = Math.min(Math.max(0, state.chatScrollOffset || 0), maxOffset);
+  state.chatScrollOffset = offset;
+  const start = Math.max(0, lines.length - maxRows - offset);
+  const slice = lines.slice(start, start + maxRows);
 
   for (let i = 0; i < slice.length && i < maxRows; i++) {
     writeAt(i, 0, slice[i].text, chatWidth - 1, slice[i].bg);
   }
+
+  if (offset > 0 && maxRows > 1) {
+    writeAt(0, 0, C.muted + `↑ ${offset} lines above bottom`, chatWidth - 1, C.bg);
+  }
 }
 
 function renderSidebar(state) {
@@ -407,7 +418,7 @@ export function renderTerminalChat(state) {
     renderLogo(chatWidth, Math.max(1, Math.floor(height / 2) - 8));
   } else {
     const prompt = promptGeometry(false, true, chatWidth);
-    renderChat(state.transcript, chatWidth, height, prompt.top);
+    renderChat(state, chatWidth, height, prompt.top);
   }
 
   const cursor = renderPromptBlock(state, chatWidth);

package/src/core/agent-system.js

@@ -1,6 +1,17 @@
 import fs from "node:fs";
 import path from "node:path";
 
+// ---------------------------------------------------------------------------
+// Anti-ghost-response rules injected into every agent system prompt.
+// Prevents agents from saying "Ok, I'll do that" and then doing nothing.
+// ---------------------------------------------------------------------------
+const ACTION_DISCIPLINE_RULES = `## Action Discipline (mandatory)
+- NEVER acknowledge an action without executing it in the same turn. If you are going to do something, call the tool FIRST, then report the result.
+- NEVER use empty acknowledgments like "Ok", "Got it", "Sure", "Understood", "On it", "Give me a moment", "I'll do that now" as standalone responses when a tool call is expected. These are invalid responses.
+- Action first, report after. Produce the tool call in the same response as your acknowledgment.
+- If you cannot execute the action (missing permission, unclear params, tool not available), explain WHY — do not promise and disappear.
+- If the user asks you to do multiple things, do them all in the same turn using sequential tool calls if needed.`;
+
 function listField(value) {
   if (Array.isArray(value)) return value.map(String).map((s) => s.trim()).filter(Boolean);
   return String(value || "").split(",").map((s) => s.trim()).filter(Boolean);
@@ -66,6 +77,10 @@ export function buildAgentSystem(project, agent, {
     if (ep) parts.push(ep);
   }
 
+  // Always append action discipline rules last so they are close to the end
+  // of the system prompt and harder for the model to "forget".
+  parts.push(ACTION_DISCIPLINE_RULES);
+
   return parts.join("\n\n");
 }
 

package/src/core/apx-skill.md

@@ -42,6 +42,22 @@ The output is the agent's full stdout. If it printed `APC_RESULT: <value>`, that
 apx exec <slug> "<prompt>"
 ```
 
+## Command accuracy
+
+Do not invent APX subcommands. Before telling another runtime to call APX, verify the exact CLI
+form with `apx --help` or `apx <command> --help`.
+
+Known Telegram form:
+
+```bash
+apx telegram status
+apx telegram send "message"
+apx telegram send "message" --chat 123456
+```
+
+Do not use guessed aliases such as `apx send-telegram` or `apx telegram "message"` unless current
+`apx --help` shows that exact form.
+
 ## MCP tools
 
 MCPs declared in `.apc/mcps.json` are proxied through the APX daemon. Use `apx mcp` only for MCPs registered there — not for MCPs that are already running locally in your IDE session.

package/src/core/runtime-skills/claude-code.md

@@ -0,0 +1,68 @@
+---
+name: claude-code
+description: "Activate ONLY when the user explicitly mentions Claude Code, Claude CLI, claude command, Anthropic Claude Code, installing Claude Code, using Claude Code, or APX runtime claude-code. Do not activate for generic Claude model discussion."
+homepage: https://docs.anthropic.com/en/docs/claude-code
+---
+# Claude Code CLI
+
+Use this skill only for Claude Code CLI install, auth, usage, or APX runtime dispatch.
+
+## Verify before acting
+
+Check the local CLI first:
+
+```bash
+claude --version
+claude --help
+```
+
+Do not invent flags. If a command is uncertain, inspect help for the exact subcommand before
+running it.
+
+## Install
+
+Common install/update path:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude --version
+```
+
+Claude Code also exposes:
+
+```bash
+claude install
+claude update
+claude auth
+```
+
+Use `claude --help` to confirm current syntax.
+
+## Non-interactive use
+
+Prefer headless print mode:
+
+```bash
+claude -p "task" --output-format json
+claude -p "task" --append-system-prompt "system instructions" --output-format json
+```
+
+For high-trust automation in an already sandboxed environment:
+
+```bash
+claude -p "task" --permission-mode bypassPermissions --output-format json
+```
+
+## APX runtime
+
+Run a project agent through Claude Code:
+
+```bash
+apx run <agent> --runtime claude-code "task"
+```
+
+If the task needs Telegram, tell Claude Code the exact APX command:
+
+```bash
+apx telegram send "message"
+```

package/src/core/runtime-skills/codex-cli.md

@@ -0,0 +1,75 @@
+---
+name: codex-cli
+description: "Activate ONLY when the user explicitly mentions Codex CLI, OpenAI Codex, @openai/codex, codex command, codex exec, installing Codex, using Codex, ~/.codex, or APX runtime codex."
+homepage: https://developers.openai.com/codex
+---
+# Codex CLI
+
+Use this skill only for Codex CLI install, auth, usage, or APX runtime dispatch.
+
+## Verify before acting
+
+Check local CLI and exact flags first:
+
+```bash
+codex --version
+codex --help
+codex exec --help
+```
+
+Do not invent flags. Current Codex CLI may reject older flags such as `--approval-mode` or
+`--full-auto`.
+
+## Install
+
+Common install/update path:
+
+```bash
+npm install -g @openai/codex
+codex --version
+```
+
+Codex also exposes:
+
+```bash
+codex login
+codex update
+```
+
+Auth check:
+
+```bash
+test -f ~/.codex/auth.json && echo "codex auth present"
+```
+
+## Non-interactive use
+
+Use `exec`, not interactive TUI, for automation:
+
+```bash
+codex exec --sandbox workspace-write --skip-git-repo-check "task"
+```
+
+Useful options:
+
+```bash
+codex exec --sandbox workspace-write --skip-git-repo-check --output-last-message /tmp/codex-last.txt "task"
+codex exec --json --sandbox workspace-write --skip-git-repo-check "task"
+```
+
+`--skip-git-repo-check` matters for APX default runtime dirs such as `~/.apx/projects/default`,
+which may not be Git repositories.
+
+## APX runtime
+
+Run a project agent through Codex:
+
+```bash
+apx run <agent> --runtime codex "task"
+```
+
+If the task needs Telegram, tell Codex the exact APX command:
+
+```bash
+apx telegram send "message"
+```

package/src/core/runtime-skills/opencode-cli.md

@@ -0,0 +1,59 @@
+---
+name: opencode-cli
+description: "Activate ONLY when the user explicitly mentions OpenCode, opencode command, installing OpenCode, using OpenCode, OpenCode provider setup, or APX runtime opencode."
+homepage: https://opencode.ai/docs
+---
+# OpenCode CLI
+
+Use this skill only for OpenCode CLI install, auth/provider setup, usage, or APX runtime dispatch.
+
+## Verify before acting
+
+Check local CLI and exact flags first:
+
+```bash
+opencode --version
+opencode --help
+opencode run --help
+```
+
+Do not invent flags. Inspect help for the exact subcommand before running uncertain commands.
+
+## Install
+
+Use the official install method for the target machine, then verify:
+
+```bash
+opencode --version
+```
+
+Provider/auth management:
+
+```bash
+opencode providers
+opencode models
+```
+
+## Non-interactive use
+
+Use headless run:
+
+```bash
+opencode run "task"
+opencode run --model provider/model "task"
+opencode run --dangerously-skip-permissions "task"
+```
+
+## APX runtime
+
+Run a project agent through OpenCode:
+
+```bash
+apx run <agent> --runtime opencode "task"
+```
+
+If the task needs Telegram, tell OpenCode the exact APX command:
+
+```bash
+apx telegram send "message"
+```