@agentprojectcontext/apx 1.53.6 → 1.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.53.6",
+  "version": "1.54.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"

package/src/core/channels/telegram/ask-callbacks.js

@@ -188,6 +188,7 @@ export async function runResumedTurn(self, ctx) {
       previousMessages,
       target,
       author,
+      authorId,
       relationshipBlock,
       allowedTools,
       onEvent,

package/src/core/channels/telegram/dispatch.js

@@ -56,12 +56,17 @@ export async function handleUpdate(self, u) {
     // in-memory globalConfig in place so later messages in this daemon session
     // see the update. The resulting block is injected into whichever agent
     // answers (super-agent OR a routed project agent).
-    const { sender } = registerSender({
+    const { sender, claimedOwner } = registerSender({
       cfg: self.globalConfig,
       channelName: self.channel.name,
       from: msg.from,
       chatType: msg.chat?.type,
     });
+    if (claimedOwner) {
+      // Trust-on-first-use: this sender just became owner of a previously
+      // ownerless private channel. Log it so an unexpected claim is visible.
+      self.log(`telegram[${self.channel.name}] owner claimed by user_id=${msg.from?.id} (${author}) — verify this is you`);
+    }
     const relationshipBlock = buildRelationshipBlock(sender);
     // Role-based tool gating for the super-agent path (guests → no tools).
     const allowedTools = resolveAllowedTools(self.globalConfig, sender);
@@ -287,6 +292,7 @@ export async function handleUpdate(self, u) {
           previousMessages,
           target,
           author,
+          authorId: msg.from?.id,
           relationshipBlock,
           allowedTools,
           contextNote: slashed.handled ? slashed.contextNote : "",

package/src/core/channels/telegram/reply.js

@@ -99,13 +99,15 @@ export function buildStreamHandler(self, { chat_id, update_id, agentDisplay }) {
  * inherit it. Throws on failure (caller decides abort-vs-error handling).
  */
 export function runTelegramSuperAgent(self, {
-  chat_id, prompt, previousMessages, target, author, relationshipBlock,
+  chat_id, prompt, previousMessages, target, author, authorId, relationshipBlock,
   allowedTools, contextNote, signal, onEvent,
 }) {
   const confirmAdapter = createTelegramConfirmAdapter({
     token: resolveBotToken(self.channel),
     chatId: chat_id,
     pendingStore: getConfirmStore(),
+    // Only the user who triggered this turn may answer its confirmations.
+    guardActorId: authorId ?? null,
   });
   return runSuperAgent({
     globalConfig: self.globalConfig,

package/src/core/config/index.js

@@ -218,6 +218,10 @@ function backupConfigBeforeLoss() {
     const ts = new Date().toISOString().replace(/[:.]/g, "-");
     const backup = `${CONFIG_PATH}.${ts}.bak`;
     fs.copyFileSync(CONFIG_PATH, backup);
+    // config.json holds API keys + bot tokens — the backup must not be more
+    // permissive than the original. copyFileSync inherits the source mode on
+    // some platforms but not reliably, so pin it.
+    try { fs.chmodSync(backup, 0o600); } catch {}
     return backup;
   } catch {
     return null;
@@ -280,8 +284,14 @@ export function writeConfig(cfg) {
   if (cfg?._allowClear) delete cfg._allowClear;
 
   const tmp = `${CONFIG_PATH}.tmp`;
-  fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2) + "\n");
+  // 0o600: config.json stores provider API keys and the Telegram bot token.
+  // Without an explicit mode it lands at 0o644 (world-readable) — any local
+  // user could read the secrets. Match daemon.token / clients.json.
+  fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
   fs.renameSync(tmp, CONFIG_PATH);
+  // writeFileSync's mode only applies when the tmp file is created; if it
+  // pre-existed with looser perms the bits stick. Pin it after the rename.
+  try { fs.chmodSync(CONFIG_PATH, 0o600); } catch {}
 }
 
 // Normalise `model_fallback` to the new format (`models` as an ordered array

package/src/core/confirmation/adapters/telegram.js

@@ -31,12 +31,15 @@ import { sendMessage, answerCallbackQuery as apiAnswerCallbackQuery, editMessage
 const TIMEOUT_MS = 60_000; // 60 s — long enough for a human, short enough to not block forever
 
 /**
- * @param {{ token: string, chatId: string|number, pendingStore: ConfirmationPendingStore }} opts
+ * @param {{ token: string, chatId: string|number, pendingStore: ConfirmationPendingStore, guardActorId?: string|number|null }} opts
  * @returns {{ requestConfirmation, handleCallbackQuery }}
  */
-export function createTelegramConfirmAdapter({ token, chatId, pendingStore }) {
+export function createTelegramConfirmAdapter({ token, chatId, pendingStore, guardActorId = null }) {
   async function requestConfirmation(tool, _args, description) {
-    const { correlationId, promise } = pendingStore.create({ timeoutMs: TIMEOUT_MS });
+    // Bind this confirmation to the user who triggered the turn. In a group
+    // chat the keyboard is visible to everyone, so without this any member
+    // could tap "Yes" and approve the initiator's destructive action.
+    const { correlationId, promise } = pendingStore.create({ timeoutMs: TIMEOUT_MS, guardActorId });
 
     await sendConfirmKeyboard(token, chatId, description, correlationId, TIMEOUT_MS);
 
@@ -52,12 +55,21 @@ export function createTelegramConfirmAdapter({ token, chatId, pendingStore }) {
 
     const [, correlationId, answer] = match;
     const confirmed = answer === "yes";
+    const presserId = callbackQuery.from?.id ?? null;
+
+    // Reject a bystander's press without consuming the pending entry or wiping
+    // the keyboard — the authorized initiator can still answer. We still return
+    // true (the callback matched our namespace and is handled).
+    if (!pendingStore.isActorAllowed(correlationId, presserId)) {
+      await answerCallbackQuery(token, callbackQuery.id, "⛔ Not your confirmation");
+      return true;
+    }
 
     // ACK the callback immediately to clear the loading spinner on the button.
     // Fire-and-forget — a slow ACK is annoying but not fatal.
     await answerCallbackQuery(token, callbackQuery.id, confirmed ? "✅ Confirmed" : "❌ Cancelled");
 
-    const resolved = pendingStore.resolve(correlationId, confirmed);
+    const resolved = pendingStore.resolve(correlationId, confirmed, presserId);
 
     // If not resolved, the entry timed out or the process restarted — show "Expired"
     // so the user knows the button is no longer actionable.

package/src/core/confirmation/pending-store.js

@@ -28,30 +28,56 @@ export class ConfirmationPendingStore {
    *   - correlationId: embed in the reply (button callback_data, SSE event…)
    *   - promise: resolves to true (confirmed) or false (denied / timeout)
    *
+   * `guardActorId` (optional): when set, only resolve() calls that supply a
+   * matching actorId may answer this confirmation. Channels where the reply is
+   * visible to more than the initiator (a Telegram group's inline keyboard)
+   * pass the initiator's id so a bystander can't approve someone else's action.
+   * Channels whose transport is already 1:1/authenticated (web SSE + token,
+   * terminal) leave it null and behave exactly as before.
+   *
    * After timeoutMs with no response the promise auto-resolves to false.
    */
-  create({ timeoutMs = 30_000 } = {}) {
+  create({ timeoutMs = 30_000, guardActorId = null } = {}) {
     const correlationId = generateId();
+    const guard = guardActorId == null ? null : String(guardActorId);
 
     const promise = new Promise((resolve) => {
       const timer = setTimeout(() => {
         this._pending.delete(correlationId);
         resolve(false);
       }, timeoutMs);
-      this._pending.set(correlationId, { resolve, timer });
+      this._pending.set(correlationId, { resolve, timer, guardActorId: guard });
     });
 
     return { correlationId, promise };
   }
 
+  /**
+   * Is `actorId` allowed to answer this confirmation? True when the entry is
+   * unknown (let resolve() report "expired"), unguarded, or the actor matches
+   * the guard. Lets an adapter reject a bystander's press WITHOUT consuming the
+   * pending entry, so the real initiator can still respond.
+   */
+  isActorAllowed(correlationId, actorId) {
+    const entry = this._pending.get(correlationId);
+    if (!entry) return true;
+    if (entry.guardActorId == null) return true;
+    return actorId != null && String(actorId) === entry.guardActorId;
+  }
+
   /**
    * Resolve a pending confirmation.
    * Returns true if found and resolved, false if not found (timed out, already
-   * resolved, or stale button after a process restart).
+   * resolved, stale button after a restart) OR if the entry is guarded and
+   * `actorId` doesn't match — in the mismatch case the entry is preserved so
+   * the authorized initiator can still answer.
    */
-  resolve(correlationId, value) {
+  resolve(correlationId, value, actorId) {
     const entry = this._pending.get(correlationId);
     if (!entry) return false;
+    if (entry.guardActorId != null && (actorId == null || String(actorId) !== entry.guardActorId)) {
+      return false;
+    }
     clearTimeout(entry.timer);
     this._pending.delete(correlationId);
     entry.resolve(value);

package/src/core/http-tools/fetch.js

@@ -15,6 +15,9 @@
 // Fetch resolver
 // ---------------------------------------------------------------------------
 
+import dns from "node:dns/promises";
+import net from "node:net";
+
 let _fetch = null;
 
 async function getFetch() {
@@ -32,18 +35,65 @@ async function getFetch() {
 const DEFAULT_TIMEOUT = 30000;
 const MAX_BODY_BYTES  = 5 * 1024 * 1024; // 5MB
 
-// Block private/link-local ranges and cloud metadata endpoints to prevent SSRF.
-const BLOCKED_HOST_RE = /^(localhost|metadata\.google\.internal\.?)$/i;
-const PRIVATE_IP_RE   = /^(127\.\d+\.\d+\.\d+|0\.0\.0\.0|::1|10\.\d+\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+|192\.168\.\d+\.\d+|169\.254\.\d+\.\d+|fd[0-9a-f]{2}:)/i;
+// Block cloud metadata endpoints by name (they may resolve to public-looking
+// IPs on some providers). IP-range blocking is done on the RESOLVED address
+// below, not on the literal host string.
+const BLOCKED_HOST_RE = /^(metadata\.google\.internal\.?|metadata\.goog\.?)$/i;
+
+// True for an IPv4 string in a loopback / private / link-local / CGNAT range.
+// Malformed input returns true (fail closed) — validateUrl only feeds this
+// addresses from dns.lookup / net.isIP, so a non-parse means "don't trust it".
+function isPrivateIpv4(ip) {
+  const parts = ip.split(".").map((n) => Number(n));
+  if (parts.length !== 4 || parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return true;
+  const [a, b] = parts;
+  if (a === 0 || a === 127) return true;                 // this-host / loopback
+  if (a === 10) return true;                             // private
+  if (a === 172 && b >= 16 && b <= 31) return true;      // private
+  if (a === 192 && b === 168) return true;               // private
+  if (a === 169 && b === 254) return true;               // link-local (incl. cloud metadata 169.254.169.254)
+  if (a === 100 && b >= 64 && b <= 127) return true;     // CGNAT
+  return false;
+}
+
+function isBlockedAddress(addr) {
+  if (!addr) return true;
+  const ip = String(addr).toLowerCase();
+  const mapped = ip.match(/^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/); // IPv4-mapped IPv6
+  if (mapped) return isPrivateIpv4(mapped[1]);
+  const fam = net.isIP(ip);
+  if (fam === 4) return isPrivateIpv4(ip);
+  if (fam === 6) {
+    if (ip === "::1" || ip === "::") return true;                // loopback / unspecified
+    if (ip.startsWith("fc") || ip.startsWith("fd")) return true; // ULA fc00::/7
+    if (/^fe[89ab]/.test(ip)) return true;                       // link-local fe80::/10
+    return false;
+  }
+  return true; // not a recognizable IP → fail closed
+}
 
-function validateUrl(rawUrl) {
+// SSRF guard. Resolving the host to concrete IPs (rather than pattern-matching
+// the literal string) defeats DNS names that point at internal ranges AND
+// numeric encodings like http://2130706433 (= 127.0.0.1) that a regex misses.
+// Residual: a rebind between this lookup and the actual connect is still
+// theoretically possible; pinning the resolved IP would need a custom agent.
+async function validateUrl(rawUrl) {
   let parsed;
   try { parsed = new URL(rawUrl); } catch { throw new Error("Invalid URL"); }
   if (!["http:", "https:"].includes(parsed.protocol)) {
     throw new Error(`Protocol "${parsed.protocol}" is not allowed; use http or https`);
   }
   const host = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "");
-  if (BLOCKED_HOST_RE.test(host) || PRIVATE_IP_RE.test(host)) {
+  if (BLOCKED_HOST_RE.test(host)) {
+    throw new Error(`Requests to private or link-local addresses are blocked`);
+  }
+  let addresses;
+  try {
+    addresses = await dns.lookup(host, { all: true });
+  } catch {
+    throw new Error("Could not resolve host");
+  }
+  if (!addresses.length || addresses.some(({ address }) => isBlockedAddress(address))) {
     throw new Error(`Requests to private or link-local addresses are blocked`);
   }
 }
@@ -72,7 +122,7 @@ async function readBody(response, jsonHint) {
 
 async function doRequest({ url, method = "GET", headers = {}, body = null, timeout_ms = DEFAULT_TIMEOUT, json = false } = {}) {
   if (!url) throw new Error("url required");
-  validateUrl(url);
+  await validateUrl(url);
   const fetch = await getFetch();
 
   const controller = new AbortController();

package/src/core/identity/telegram.js

@@ -55,16 +55,18 @@ export function resolveSender({ cfg, channelName, from, chatType }) {
  *  - owner → "*" (all tools)
  *  - guest → [] (no tools; text only)
  *  - a role defined in telegram.roles → its `tools` ("*" or an array)
- *  - any other named role with no definition → "*" (an admin assigned it
- *    deliberately; default permissive rather than silently muting it)
+ *  - any other named role with no definition → [] (fail closed: a typo'd or
+ *    removed role must NOT silently grant every tool. Define the role in
+ *    telegram.roles to grant access.)
  * Returns "*" or an array of tool names.
  */
 export function resolveAllowedTools(cfg, sender) {
   if (sender?.isOwner) return "*";
   const def = cfg?.telegram?.roles?.[sender?.role];
   if (def && def.tools !== undefined) return def.tools;
-  if (sender?.role === SENDER_ROLES.GUEST) return [];
-  return "*";
+  // Fail closed: guests and any sender whose role isn't explicitly defined get
+  // no tools. Only the owner and configured roles receive capabilities.
+  return [];
 }
 
 /**
@@ -108,7 +110,7 @@ export function registerSender({ cfg, channelName, from, chatType }) {
   else if (!existing) kind = "guest";
   else if (existing.last_seen?.slice(0, 10) !== now.slice(0, 10)) kind = "touch";
 
-  if (!kind) return { sender: base(), mutated: false };
+  if (!kind) return { sender: base(), mutated: false, claimedOwner: false };
 
   if (kind === "claim") {
     upsertTelegramChannel(disk, channelName, { owner_user_id: userId });
@@ -123,5 +125,8 @@ export function registerSender({ cfg, channelName, from, chatType }) {
     upsertContact(disk, userId, { last_seen: now });
   }
 
-  return { sender: base(), mutated: true };
+  // Signal an owner-claim (trust-on-first-use) so the caller can surface it —
+  // whoever messages a fresh private channel first becomes owner, and that
+  // event must be auditable rather than silent.
+  return { sender: base(), mutated: true, claimedOwner: kind === "claim" };
 }

package/src/core/mcp/runner.js

@@ -153,7 +153,9 @@ class McpProcess {
 
   async listTools() {
     await this._ensureInitialized();
-    return this._send("tools/list", {});
+    return collectToolPages((cursor) =>
+      this._send("tools/list", cursor ? { cursor } : {})
+    );
   }
 
   async callTool(name, args) {
@@ -374,7 +376,9 @@ class HttpMcpClient {
 
   async listTools() {
     await this._ensureInitialized();
-    return this._rpc("tools/list", {});
+    return collectToolPages((cursor) =>
+      this._rpc("tools/list", cursor ? { cursor } : {})
+    );
   }
 
   async callTool(name, args) {
@@ -399,6 +403,21 @@ class HttpMcpClient {
   }
 }
 
+// tools/list is paginated (nextCursor). Follow every page and hand back a
+// single merged { tools } result so callers never see partial catalogs.
+const MAX_TOOL_PAGES = 32;
+async function collectToolPages(fetchPage) {
+  const tools = [];
+  let cursor;
+  for (let i = 0; i < MAX_TOOL_PAGES; i++) {
+    const result = await fetchPage(cursor);
+    if (Array.isArray(result?.tools)) tools.push(...result.tools);
+    cursor = result?.nextCursor;
+    if (!cursor) break;
+  }
+  return { tools };
+}
+
 function parseFirstSseJson(raw) {
   for (const block of raw.split(/\r?\n\r?\n/)) {
     const dataLines = [];

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

@@ -21,7 +21,7 @@ If you can spawn a subagent natively in the current IDE (Claude Code, Cursor,
 |-------|-----------|------|
 | Delegate to external coding CLI | **apx-runtime** | `apx run <agent> --runtime claude-code\|codex\|...` |
 | List/read/resume/summarise/continue sessions | **apx-sessions** | `apx session resume`, `apx sessions list`, "import a codex session" |
-| Use a registered MCP tool | **apx-mcp** | `apx mcp run`, "call MCP filesystem", "MCP failing" |
+| Use a registered MCP tool | **apx-mcp** | `apx mcp tools`, `apx mcp run`, "call MCP filesystem", "MCP failing" |
 | Add/configure/use a project agent | **apx-agent** | "add an agent", vault import, per-agent model, agent memory |
 | Register/list/configure a project | **apx-project** | "register this project", `apx project list`, per-project config |
 | Per-project TODO list | **apx-task** | "add a task", "remind me to…", "what's pending" |

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

@@ -47,7 +47,12 @@ apx mcp remove github     --scope runtime --project iacrmar
 apx mcp enable  filesystem --project iacrmar
 apx mcp disable filesystem --project iacrmar
 
-# Call a tool through the daemon (debugging)
+# Discover tools — list catalog, then inspect one tool's schema
+apx mcp tools filesystem                     # table: tool name + description
+apx mcp tools filesystem read_file           # params (types, required) + run example
+apx mcp tools filesystem --json              # raw JSON with full inputSchema
+
+# Call a tool through the daemon
 apx mcp run filesystem read_file '{"path":"README.md"}'
 ```
 
@@ -95,13 +100,15 @@ apx mcp remove github          # errors if github lives in runtime
 
 ```bash
 apx mcp check --project iacrmar      # scopes seen + which files exist
-apx mcp run <name> <tool> '{...}'    # spawn server, call a tool
+apx mcp tools <name>                 # spawn server + list its tools (proves init works)
+apx mcp logs <name>                  # spawn/init event log + stderr tail
+apx mcp run <name> <tool> '{...}'    # call a tool for real
 apx log -f                           # tail unified log for spawn errors
 ```
 
-"Doesn't show tools" = command failed to start (missing env vars, package not found) or crashed during initialize. Unified log holds the stderr buffer.
+"Doesn't show tools" = command failed to start (missing env vars, package not found) or crashed during initialize. `apx mcp logs <name>` shows the stderr tail; the unified log has the rest.
 
-> `apx mcp tools <name>` is a placeholder stub ("coming in v0.2"). Use `apx mcp run` to verify spawn.
+Standard workflow to use any MCP: `apx mcp tools <name>` → `apx mcp tools <name> <tool>` (copy the run example) → `apx mcp run <name> <tool> '<json>'`.
 
 ## Don't
 

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

@@ -151,10 +151,17 @@ apx mcp add github \
 ## Debugging
 
 ```bash
-# Smoke test (apx mcp tools is a v0.2 stub — don't rely on it)
+# Smoke test — spawn the server and list its tool catalog
+apx mcp tools my-server
+
+# Inspect one tool's schema + copy-paste run example
+apx mcp tools my-server search_inventory
+
+# Call it for real
 apx mcp run my-server search_inventory '{"query":"shoes"}'
 
-# Spawn errors / stderr
+# Spawn errors / stderr tail
+apx mcp logs my-server
 apx log -f
 
 # Scopes / files / env APX sees

package/src/host/daemon/api/admin.js

@@ -4,7 +4,7 @@
 //
 // Both are auth-gated (the global middleware applies).
 import { readConfig } from "#core/config/index.js";
-import { exec } from "node:child_process";
+import { execFile } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -57,22 +57,52 @@ export function register(app, { scheduler, plugins, config, registries }) {
   // platform lacks a usable picker — or none is installed — the endpoint
   // returns 501 so the frontend can fall back to the inline directory list.
   app.get("/admin/fs/pick-dir", (req, res) => {
-    const prompt = String(req.query.prompt || "Select a folder").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    // The prompt is attacker-controllable (query string). NEVER interpolate it
+    // into a shell string — use execFile (no shell) with an argv array, and
+    // pass the prompt out-of-band via an env var so it can't break out of any
+    // quoting context in the picker's own scripting language.
+    const prompt = String(req.query.prompt || "Select a folder");
     const platform = process.platform;
-    let cmd;
+    const env = { ...process.env, APX_PICK_PROMPT: prompt };
+    let file;
+    let args;
     if (platform === "darwin") {
       // try/end-try makes cancel exit with code 0 + empty stdout so we can
-      // distinguish "cancelled" from "no picker available".
-      cmd = `osascript -e 'try' -e 'POSIX path of (choose folder with prompt "${prompt}")' -e 'on error' -e 'return ""' -e 'end try'`;
+      // distinguish "cancelled" from "no picker available". `system attribute`
+      // reads the env var, so the prompt never touches the AppleScript source.
+      file = "osascript";
+      args = [
+        "-e", "try",
+        "-e", 'POSIX path of (choose folder with prompt (system attribute "APX_PICK_PROMPT"))',
+        "-e", "on error",
+        "-e", 'return ""',
+        "-e", "end try",
+      ];
     } else if (platform === "linux") {
-      cmd = `command -v zenity >/dev/null && zenity --file-selection --directory --title="${prompt}" 2>/dev/null || true`;
+      // zenity takes the title as a plain argv value — no shell, no escaping.
+      file = "zenity";
+      args = ["--file-selection", "--directory", `--title=${prompt}`];
     } else if (platform === "win32") {
-      cmd = `powershell -NoProfile -Command "$f = (New-Object -ComObject Shell.Application).BrowseForFolder(0, '${prompt.replace(/'/g, "''")}', 0, 0); if ($f) { $f.Self.Path }"`;
+      // Reference the prompt via $env: inside PowerShell rather than splicing it
+      // into the -Command string.
+      file = "powershell";
+      args = [
+        "-NoProfile",
+        "-Command",
+        "$f = (New-Object -ComObject Shell.Application).BrowseForFolder(0, $env:APX_PICK_PROMPT, 0, 0); if ($f) { $f.Self.Path }",
+      ];
     } else {
       return res.status(501).json({ error: "Native folder picker not supported on this platform" });
     }
-    exec(cmd, { timeout: 5 * 60 * 1000 }, (err, stdout) => {
-      if (err) return res.status(500).json({ error: err.message });
+    execFile(file, args, { timeout: 5 * 60 * 1000, env }, (err, stdout) => {
+      if (err) {
+        // Picker binary absent (e.g. no zenity) → let the frontend fall back to
+        // the inline directory list instead of surfacing a hard 500.
+        if (err.code === "ENOENT") {
+          return res.status(501).json({ error: "Native folder picker not available" });
+        }
+        return res.status(500).json({ error: err.message });
+      }
       const picked = (stdout || "").trim().replace(/[\r\n]+$/g, "");
       if (!picked) return res.json({ cancelled: true });
       res.json({ path: picked.replace(/\/+$/, "") });

package/src/host/daemon/api/mcps.js

@@ -5,6 +5,7 @@
 //   POST   /projects/:pid/mcps?scope=shared|runtime|global    (default: shared)
 //   DELETE /projects/:pid/mcps/:name?scope=…                   (default: shared)
 //   GET    /projects/:pid/mcps/check
+//   GET    /projects/:pid/mcps/:name/tools
 //   POST   /projects/:pid/mcps/:name/call
 import fs from "node:fs";
 import path from "node:path";
@@ -190,6 +191,20 @@ export function register(app, { projects, registries, project }) {
     });
   });
 
+  // Full tool catalog — tools/list with input schemas, all pages merged.
+  // This is what `apx mcp tools` renders; /test below stays as the
+  // lightweight smoke check for the web UI card.
+  app.get("/projects/:pid/mcps/:name/tools", async (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    try {
+      const result = await registries.for(p).listTools(req.params.name);
+      res.json({ tools: Array.isArray(result?.tools) ? result.tools : [] });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
   app.post("/projects/:pid/mcps/:name/call", async (req, res) => {
     const p = project(req, res);
     if (!p) return;

package/src/host/daemon/api/shared.js

@@ -10,6 +10,7 @@ import { readAgents } from "#core/apc/parser.js";
 import { agentMemoryPath } from "#core/agent/memory.js";
 import { apcMemoryFile } from "#core/apc/paths.js";
 import { CHANNELS } from "#core/constants/channels.js";
+import { isKnownSpaRoute } from "./web.js";
 
 export const nowIso = () =>
   new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
@@ -51,34 +52,29 @@ export function traceIdMiddleware(req, res, next) {
 // /pair/init and /admin/web-token both enforce localhost-only checks of
 // their own — the auth middleware just gets out of their way.
 const UNAUTHENTICATED_PREFIXES = ["/health", "/pair/", "/admin/web-token"];
-// API prefixes that MUST stay authenticated. Anything not in this list,
-// requested with GET, is treated as a static SPA asset (HTML/CSS/JS/font)
-// or a client-router path and served without auth — the bundle itself
-// fetches /admin/web-token to obtain a bearer for the subsequent API
-// calls. This is safe because all data-bearing routes start with one of
-// the API prefixes below.
-const API_PREFIXES = [
-  "/health", "/admin", "/projects", "/telegram", "/engines", "/runtimes",
-  "/messages", "/sessions", "/tools", "/mcp", "/voice", "/tts", "/desktop", "/overlay",
-  "/transcribe", "/run", "/files", "/memory", "/env", "/pair", "/deck",
-  "/super-agent", "/identity", "/agents", "/tasks",
-];
-function isApiPath(p) {
-  for (const prefix of API_PREFIXES) {
-    if (p === prefix || p.startsWith(prefix + "/")) return true;
-  }
-  return false;
+
+// Does this path look like a static asset (has a file extension)? Vite emits
+// hashed, extension-bearing filenames (index-abc123.js, logo.svg, font.woff2),
+// so an extension is a reliable "this is a bundle asset, not a data route"
+// signal. Data routes (/skills, /projects, /p/0/tasks) have no extension.
+function isStaticAssetPath(p) {
+  return path.extname(p) !== "";
 }
+
 function isUnauthenticatedPath(p, method = "GET") {
   if (p === "/health") return true;
   if (p === "/admin/web-token") return true;
   for (const prefix of UNAUTHENTICATED_PREFIXES) {
     if (p === prefix.replace(/\/$/, "") || p.startsWith(prefix)) return true;
   }
-  // GET requests that don't hit an API prefix are SPA assets / client-router
-  // paths; let them through so the admin bundle can load before it has a
-  // bearer.
-  if (method === "GET" && !isApiPath(p)) return true;
+  // SPA bootstrap: the admin bundle loads before it holds a bearer, so a GET
+  // for a static asset or a known client-router route is served without auth —
+  // the bundle then fetches /admin/web-token. Everything else, including every
+  // data GET (/skills, /plugins, /embeddings, …), REQUIRES a token. This is an
+  // allowlist by construction: a new data route can never silently become
+  // public just because someone forgot to register its prefix (the old
+  // denylist failure mode).
+  if (method === "GET" && (isStaticAssetPath(p) || isKnownSpaRoute(p))) return true;
   return false;
 }
 

package/src/host/daemon/api/top-level.js

@@ -62,8 +62,9 @@ export function register(app, { projects, registries, resolveTopProject }) {
         return res.status(500).json({ error: e.message });
       }
     }
+    const root = path.resolve(p.path);
     const abs = path.resolve(p.path, rel);
-    if (!abs.startsWith(path.resolve(p.path)))
+    if (abs !== root && !abs.startsWith(root + path.sep))
       return res.status(403).json({ error: "path escapes project root" });
     if (!fs.existsSync(abs))
       return res.status(404).json({ error: "not found" });
@@ -96,8 +97,9 @@ export function register(app, { projects, registries, resolveTopProject }) {
     if (!rel) return res.status(400).json({ error: "path required" });
     if (typeof content !== "string")
       return res.status(400).json({ error: "content must be string" });
+    const root = path.resolve(p.path);
     const abs = path.resolve(p.path, rel);
-    if (!abs.startsWith(path.resolve(p.path)))
+    if (abs !== root && !abs.startsWith(root + path.sep))
       return res.status(403).json({ error: "path escapes project root" });
     fs.mkdirSync(path.dirname(abs), { recursive: true });
     fs.writeFileSync(abs, content);

package/src/host/daemon/desktop-ws.js

@@ -16,8 +16,9 @@ export function setDesktopMessageHandler(fn) {
 // routes do: a bearer token (master or paired client) carried on the upgrade
 // request. The legitimate desktop window sends `Authorization: Bearer <token>`
 // (src/interfaces/desktop/main.js); browser clients can pass `?token=`. Without
-// this the daemon (which binds 0.0.0.0 by default) would let any LAN client open
-// the channel and drive the super-agent. See QA BUG-WS-AUTH.
+// this, any client that can reach the daemon (loopback by default, but the LAN
+// when host is set to 0.0.0.0) could open the channel and drive the
+// super-agent. See QA BUG-WS-AUTH.
 
 /** Path-gate: is this upgrade for the desktop (or legacy overlay) WS channel? */
 export function isDesktopUpgradePath(url) {

package/src/interfaces/cli/commands/mcp.js

@@ -159,13 +159,130 @@ export async function cmdMcpRun(args) {
   process.stdout.write(JSON.stringify(result.result, null, 2) + "\n");
 }
 
+// Turn a JSON-Schema type into a short placeholder for the run-example JSON.
+function placeholderFor(schema) {
+  const t = Array.isArray(schema?.type) ? schema.type[0] : schema?.type;
+  if (schema?.enum?.length) return schema.enum[0];
+  if (t === "number" || t === "integer") return 0;
+  if (t === "boolean") return false;
+  if (t === "array") return [];
+  if (t === "object") return {};
+  return `<${t || "string"}>`;
+}
+
+function schemaTypeLabel(schema) {
+  if (schema?.enum?.length) return schema.enum.join("|");
+  const t = Array.isArray(schema?.type) ? schema.type.join("|") : schema?.type;
+  return t || "any";
+}
+
+function firstLine(s) {
+  return String(s || "").split("\n")[0].trim();
+}
+
+function printToolDetail(mcpName, tool) {
+  console.log(`${mcpName} · ${tool.name}`);
+  if (tool.description) console.log(`  ${tool.description.trim().replace(/\n/g, "\n  ")}`);
+
+  const props = tool.inputSchema?.properties || {};
+  const required = new Set(tool.inputSchema?.required || []);
+  const keys = Object.keys(props);
+  console.log("");
+  if (keys.length === 0) {
+    console.log("  Params: (none)");
+  } else {
+    console.log("  Params:");
+    const nameW = Math.max(...keys.map((k) => k.length), 4) + 2;
+    const typeW = Math.max(...keys.map((k) => schemaTypeLabel(props[k]).length), 4) + 2;
+    for (const k of keys) {
+      const req = required.has(k) ? "(required)" : "(optional)";
+      console.log(
+        `    ${k.padEnd(nameW)}${schemaTypeLabel(props[k]).padEnd(typeW)}${req}  ${firstLine(props[k]?.description)}`
+      );
+    }
+  }
+
+  // Example invocation with the required params stubbed in.
+  const example = {};
+  for (const k of keys) {
+    if (required.has(k)) example[k] = placeholderFor(props[k]);
+  }
+  console.log("");
+  console.log("  Run:");
+  console.log(`    apx mcp run ${mcpName} ${tool.name} '${JSON.stringify(example)}'`);
+}
+
 export async function cmdMcpTools(args) {
   const name = args._[0];
-  if (!name) throw new Error("apx mcp tools: missing <name>");
-  // Daemon doesn't have a dedicated tools/list endpoint yet; we'd extend it in v0.2.
-  // For now, print a hint:
-  console.log(`(apx mcp tools — list of tools/list will arrive in v0.2)`);
-  console.log(`To call a tool: apx mcp run ${name} <tool> '<json>'`);
+  if (!name) throw new Error("apx mcp tools: usage: apx mcp tools <name> [<tool>] [--json]");
+  const toolFilter = args._[1];
+  const pid = await resolveProjectId(args?.flags?.project);
+  const data = await http.get(`/projects/${pid}/mcps/${name}/tools`);
+  const tools = data.tools || [];
+
+  if (toolFilter) {
+    const tool = tools.find((t) => t.name === toolFilter);
+    if (!tool) {
+      const hint = tools.length
+        ? `Available: ${tools.map((t) => t.name).join(", ")}`
+        : "(server reported no tools)";
+      throw new Error(`MCP "${name}" has no tool "${toolFilter}". ${hint}`);
+    }
+    if (args?.flags?.json) {
+      process.stdout.write(JSON.stringify(tool, null, 2) + "\n");
+      return;
+    }
+    printToolDetail(name, tool);
+    return;
+  }
+
+  if (args?.flags?.json) {
+    process.stdout.write(JSON.stringify(tools, null, 2) + "\n");
+    return;
+  }
+  if (tools.length === 0) {
+    console.log(`(MCP "${name}" reported no tools)`);
+    return;
+  }
+  const nameW = Math.max(...tools.map((t) => t.name.length), 4) + 2;
+  console.log(`${tools.length} tool${tools.length === 1 ? "" : "s"} — apx mcp tools ${name} <tool> for schema\n`);
+  console.log("TOOL".padEnd(nameW) + " DESCRIPTION");
+  for (const t of tools) {
+    console.log(t.name.padEnd(nameW) + " " + firstLine(t.description).slice(0, 100));
+  }
+}
+
+export async function cmdMcpLogs(args) {
+  const name = args._[0];
+  if (!name) throw new Error("apx mcp logs: missing <name>");
+  const pid = await resolveProjectId(args?.flags?.project);
+  const logs = await http.get(`/projects/${pid}/mcps/${name}/logs`);
+  if (args?.flags?.json) {
+    process.stdout.write(JSON.stringify(logs, null, 2) + "\n");
+    return;
+  }
+  const target = logs.transport === "http"
+    ? logs.url
+    : [logs.command, ...(logs.args || [])].filter(Boolean).join(" ");
+  console.log(`${name} (${logs.transport})${target ? " — " + target : ""}`);
+  if (logs.transport === "stdio") {
+    console.log(`  running: ${logs.running ? "yes" : "no"}  started: ${logs.started_at || "-"}  last exit: ${logs.last_exit_code ?? "-"}`);
+  } else {
+    console.log(`  started: ${logs.started_at || "-"}  last error: ${logs.last_error || "-"}`);
+  }
+  if (logs.note) console.log(`  ${logs.note}`);
+  if (logs.events?.length) {
+    console.log("\nEvents:");
+    for (const e of logs.events) {
+      console.log(`  ${e.ts}  [${e.level}] ${e.msg}`);
+    }
+  }
+  if (logs.stderr_tail?.trim()) {
+    console.log("\nstderr tail:");
+    for (const line of logs.stderr_tail.trim().split("\n")) {
+      console.log(`  ${line}`);
+    }
+  }
 }
 
 export async function cmdMcpCheck(args = {}) {

package/src/interfaces/cli/index.js

@@ -46,6 +46,7 @@ import {
   cmdMcpDisable,
   cmdMcpRun,
   cmdMcpTools,
+  cmdMcpLogs,
   cmdMcpCheck,
 } from "./commands/mcp.js";
 import {
@@ -713,7 +714,8 @@ const HELP_TOPICS = new Map(Object.entries({
       ["enable <name>", "Enable a project-owned MCP server."],
       ["disable <name>", "Disable a project-owned MCP server."],
       ["run <name> <tool>", "Call one MCP tool."],
-      ["tools <name>", "Show tool-list hint."],
+      ["tools <name> [<tool>]", "List a server's tools, or show one tool's schema."],
+      ["logs <name>", "Show spawn/init logs and stderr tail for a server."],
       ["check", "Audit source files, merge order, and conflicts."],
     ],
     options: [["--project <name|id|path>", "Pin command to a specific project."]],
@@ -785,10 +787,27 @@ const HELP_TOPICS = new Map(Object.entries({
   }),
   "mcp tools": topic({
     title: "apx mcp tools",
-    summary: "Show MCP tool-list guidance for a server.",
-    usage: ["apx mcp tools <name> [--project <name|id|path>]"],
-    options: [["--project <name|id|path>", "Pin command to a specific project."]],
-    examples: ["apx mcp tools filesystem"],
+    summary: "List an MCP server's tools, or show one tool's input schema with a ready-to-run example.",
+    usage: ["apx mcp tools <name> [<tool>] [--json] [--project <name|id|path>]"],
+    options: [
+      ["--json", "Raw JSON output (full tool objects with inputSchema)."],
+      ["--project <name|id|path>", "Pin command to a specific project."],
+    ],
+    examples: [
+      "apx mcp tools filesystem",
+      "apx mcp tools filesystem read_file",
+      "apx mcp tools dokploy-mcp --json",
+    ],
+  }),
+  "mcp logs": topic({
+    title: "apx mcp logs",
+    summary: "Show an MCP server's spawn/init event log and stderr tail — first stop when a server doesn't list tools.",
+    usage: ["apx mcp logs <name> [--json] [--project <name|id|path>]"],
+    options: [
+      ["--json", "Raw JSON output."],
+      ["--project <name|id|path>", "Pin command to a specific project."],
+    ],
+    examples: ["apx mcp logs dokploy-mcp"],
   }),
   "mcp check": topic({
     title: "apx mcp check",
@@ -2022,7 +2041,8 @@ function buildHelp(version) {
     hCmd("apx mcp remove <name>",      36, ""),
     hCmd("apx mcp enable/disable",     36, "<name>"),
     hCmd("apx mcp run <name> <tool>",  36, "[<json-args>]  call a tool through the daemon"),
-    hCmd("apx mcp tools <name>",       36, "list available tools"),
+    hCmd("apx mcp tools <name>",       36, "[<tool>]  list tools, or one tool's schema + run example"),
+    hCmd("apx mcp logs <name>",        36, "spawn/init log + stderr tail"),
     hCmd("apx mcp check",              36, "audit multi-source merge"),
 
     hSec("Daemon Service"),
@@ -2372,6 +2392,7 @@ async function dispatch(cmd, rest) {
         else if (sub === "disable") await cmdMcpDisable(a);
         else if (sub === "run") await cmdMcpRun(a);
         else if (sub === "tools") await cmdMcpTools(a);
+        else if (sub === "logs") await cmdMcpLogs(a);
         else if (sub === "check") await cmdMcpCheck(a);
         else die(`unknown mcp subcommand: ${sub || "(none)"}`);
         break;

package/src/interfaces/web/package-lock.json

@@ -1259,9 +1259,9 @@
       }
     },
     "node_modules/@reduxjs/toolkit/node_modules/immer": {
-      "version": "11.1.8",
-      "resolved": "https://registry.npmjs.org/immer/-/immer-11.1.8.tgz",
-      "integrity": "sha512-/tbkHMW7y10Lx6i1crLjD4/OhNkRG+Fo7byZHtah0547nIeXYcpIXaUh0IAQY6gO5459qpGGYapcEOHtFXkIuA==",
+      "version": "11.1.9",
+      "resolved": "https://registry.npmjs.org/immer/-/immer-11.1.9.tgz",
+      "integrity": "sha512-sc/z0Cyti70bZa0ZU4sWfAElfovFb9Ni8tArJZLuklYWxegPiK3pDOql1Rq5H0FIRAW9LSQRG6OX4KqBldbhBA==",
       "license": "MIT",
       "funding": {
         "type": "opencollective",
@@ -2059,9 +2059,9 @@
       "license": "MIT"
     },
     "node_modules/@types/node": {
-      "version": "26.0.1",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.0.1.tgz",
-      "integrity": "sha512-fc3KiUoBt6kie0N9bIW3E47vZsuaMf0PM2AaUpLCLT0s/LvX1nxAim6Fc049cNxODPpGm6qRAuUOB86SkRuPQw==",
+      "version": "26.1.0",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.1.0.tgz",
+      "integrity": "sha512-O0A1G3xPGy4w7AgQdAQYUlQ+BKk2Oovw8eRpofyp5KdBZULnbe+WqaOVNrm705SHphCiG4XHsACrSmPu1f+Kgw==",
       "devOptional": true,
       "license": "MIT",
       "dependencies": {
@@ -2162,9 +2162,9 @@
       }
     },
     "node_modules/baseline-browser-mapping": {
-      "version": "2.10.40",
-      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.40.tgz",
-      "integrity": "sha512-BSSLZ9/Cjjv7Gtj5B68ZzXcXUg8iOf3fme+FCuh8rC/Go+Kmh8cox7M3A8dolou16s64QjLPOSdngh7GxXvkSw==",
+      "version": "2.10.41",
+      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.41.tgz",
+      "integrity": "sha512-WwS7MHhqGHHlaVsqRZnhvCEMS0owDX+SxRlve7JkuH7My1Ara3ZriTmCQupPfYjxMZ8I/tgxtJYr2t7taHaH4A==",
       "dev": true,
       "license": "Apache-2.0",
       "bin": {
@@ -2580,9 +2580,9 @@
       "license": "MIT"
     },
     "node_modules/electron-to-chromium": {
-      "version": "1.5.383",
-      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.383.tgz",
-      "integrity": "sha512-I2484/KkAvl8lm9VyjH2JnbOIV0d/UCqT7gbzs6l+o6Vmn9wgB66uVcKX+Vk6HrXtY6fbWTOEXuv8waDTuFNCw==",
+      "version": "1.5.385",
+      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.385.tgz",
+      "integrity": "sha512-78sa/M08MNAYHQfjoWMvOlKQqZ0ElhSm/L5HNUc96VZ3b+KvDVnngFm8sYQy0XrhTRgAhggHr5abA7yTvRdo4Q==",
       "dev": true,
       "license": "ISC"
     },
@@ -3256,9 +3256,9 @@
       "license": "ISC"
     },
     "node_modules/picomatch": {
-      "version": "4.0.4",
-      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
-      "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
+      "version": "4.0.5",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.5.tgz",
+      "integrity": "sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A==",
       "license": "MIT",
       "engines": {
         "node": ">=12"