@agentprojectcontext/apx 1.10.3 → 1.10.4

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.10.4",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"

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/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/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"
+```

package/src/core/runtime-skills/openrouter.md

@@ -0,0 +1,54 @@
+---
+name: openrouter
+description: "Activate ONLY when the user explicitly mentions OpenRouter, OPENROUTER_API_KEY, OpenRouter models, installing OpenRouter provider config, or using OpenRouter with APX, OpenCode, LiteLLM, or an OpenAI-compatible client."
+homepage: https://openrouter.ai/docs
+---
+# OpenRouter
+
+Use this skill only for OpenRouter install/config, model listing, or usage through APX/OpenCode or
+OpenAI-compatible clients.
+
+## Verify before acting
+
+OpenRouter is an API/provider, not a local coding runtime by itself. First identify which client
+will use it: APX engine, OpenCode provider, LiteLLM, OpenAI SDK, or another OpenAI-compatible tool.
+
+Do not expose keys. Check only presence:
+
+```bash
+test -n "$OPENROUTER_API_KEY" && echo "OPENROUTER_API_KEY present"
+```
+
+## OpenAI-compatible base URL
+
+Typical API settings:
+
+```bash
+OPENAI_BASE_URL=https://openrouter.ai/api/v1
+OPENROUTER_API_KEY=...
+```
+
+Use the selected client's current docs/help before writing config.
+
+## APX guidance
+
+If configuring APX engine/provider, inspect current config schema first:
+
+```bash
+apx config --help
+apx status
+```
+
+Then update only non-secret project-safe settings. Keep API keys in user config or environment, not
+in `.apc/` or git.
+
+## OpenCode guidance
+
+If using OpenRouter via OpenCode, inspect provider commands first:
+
+```bash
+opencode providers
+opencode models
+```
+
+Then configure OpenRouter through OpenCode's current provider flow.

package/src/core/scaffold.js

@@ -87,7 +87,7 @@ function buildSkillMd(content) {
   const frontmatter = [
     "---",
     "name: apx",
-    "description: APX CLI skill. Activate when: user asks to run or coordinate agents, use MCP tools from .apc/mcps.json, install agents from a team workspace, or explicitly mentions apx commands. Do NOT activate just because .apc/ exists — that is handled by the apc-context skill. Activate on: 'apx run', 'apx exec', 'run an agent', 'coordinate agents', 'MCP not working', 'install agent', 'team agents', 'apx memory', 'daemon'.",
+    "description: \"APX CLI skill. Activate when: user asks to run or coordinate agents, use MCP tools from .apc/mcps.json, install agents from a team workspace, or explicitly mentions apx commands. Do NOT activate just because .apc/ exists — that is handled by the apc-context skill. Activate on: 'apx run', 'apx exec', 'run an agent', 'coordinate agents', 'MCP not working', 'install agent', 'team agents', 'apx memory', 'daemon'.\"",
     "homepage: https://github.com/agentprojectcontext/apx",
     "---",
     "",
@@ -95,6 +95,19 @@ function buildSkillMd(content) {
   return frontmatter + content;
 }
 
+function readRuntimeSkillFiles() {
+  const skillsDir = path.join(__dirname, "runtime-skills");
+  if (!fs.existsSync(skillsDir)) return [];
+
+  return fs.readdirSync(skillsDir)
+    .filter((name) => name.endsWith(".md"))
+    .sort()
+    .map((name) => ({
+      slug: path.basename(name, ".md"),
+      md: fs.readFileSync(path.join(skillsDir, name), "utf8").trim(),
+    }));
+}
+
 // Install APX + APC context skills into IDE rule files. Returns an array of result objects.
 // targetIds: array of target ids to install; null = all project targets.
 export function installIdeSkills(root, targetIds = null) {
@@ -159,6 +172,7 @@ export function installGlobalSkills() {
     skills.push({ slug: "apx", md: buildSkillMd(fs.readFileSync(apxSrc, "utf8").trim()) });
   if (fs.existsSync(apcSrc))
     skills.push({ slug: "apc-context", md: buildApcContextSkillMd(fs.readFileSync(apcSrc, "utf8").trim()) });
+  skills.push(...readRuntimeSkillFiles());
 
   for (const base of GLOBAL_SKILL_DIRS) {
     for (const { slug, md } of skills) {

package/src/daemon/runtimes/codex.js

@@ -1,5 +1,5 @@
 // OpenAI Codex CLI runtime adapter.
-//   codex exec "<prompt>"
+//   codex exec --sandbox workspace-write --skip-git-repo-check "<prompt>"
 // System prompt is prepended to the prompt body since Codex doesn't have a
 // dedicated --system flag in `exec` mode.
 // Reference: https://github.com/openai/codex
@@ -15,7 +15,7 @@ export default {
     const fullPrompt = system ? `${system}\n\n---\n\n${prompt}` : prompt;
     const r = await runProcess({
       command: "codex",
-      args: ["exec", fullPrompt],
+      args: ["exec", "--sandbox", "workspace-write", "--skip-git-repo-check", fullPrompt],
       cwd,
       env,
       timeoutMs,