@agentprojectcontext/apx 1.53.7 → 1.55.0

package/package.json

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

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/core/stores/messages.js

@@ -591,6 +591,75 @@ export function readGlobalMessages({ channel, limit = 100, since } = {}) {
   return all.slice(-limit);
 }
 
+// ---------------------------------------------------------------------------
+// Global channel threads (super-agent chats surfaced in the web Chats sidebar)
+// ---------------------------------------------------------------------------
+// The global ledger is the source of truth for every super-agent turn outside
+// exec (telegram, web quick-chat, desktop, deck …). A "thread" is one
+// channel+day JSONL file — the same granularity the context window reads.
+
+const CHANNEL_NAME_RE = /^[a-z0-9_-]+$/i;
+
+// List every non-empty channel+day thread, newest-last-activity first.
+export function listGlobalThreads({ channels, _globalMessagesDir } = {}) {
+  const base = _globalMessagesDir || GLOBAL_MESSAGES_DIR;
+  if (!fs.existsSync(base)) return [];
+  const chans = (channels && channels.length
+    ? channels
+    : fs.readdirSync(base).filter((f) => {
+        try { return fs.statSync(path.join(base, f)).isDirectory(); } catch { return false; }
+      })
+  ).filter((c) => CHANNEL_NAME_RE.test(c));
+
+  const out = [];
+  for (const ch of chans) {
+    const dir = path.join(base, ch);
+    let files;
+    try { files = fs.readdirSync(dir); } catch { continue; }
+    for (const f of files) {
+      const m = f.match(/^(\d{4}-\d{2}-\d{2})\.jsonl$/);
+      if (!m) continue;
+      const msgs = parseDayJsonl(fs.readFileSync(path.join(dir, f), "utf8")).filter(
+        (r) => r.type === "user" || r.type === "agent"
+      );
+      if (!msgs.length) continue;
+      const firstUser = msgs.find((r) => r.type === "user");
+      const title = String((firstUser || msgs[0]).body || "")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 80);
+      out.push({
+        id: m[1],
+        channel: ch,
+        title: title || `${ch} · ${m[1]}`,
+        messages: msgs.length,
+        started_at: msgs[0].ts,
+        last_ts: msgs[msgs.length - 1].ts,
+      });
+    }
+  }
+  out.sort((a, b) => (b.last_ts || "").localeCompare(a.last_ts || ""));
+  return out;
+}
+
+// Read one channel+day thread shaped for the web chat viewer:
+// { id, channel, messages: [{ role, content, ts }] } — or null when missing.
+export function readGlobalThread({ channel, date, _globalMessagesDir } = {}) {
+  if (!CHANNEL_NAME_RE.test(String(channel || ""))) return null;
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(date || ""))) return null;
+  const base = _globalMessagesDir || GLOBAL_MESSAGES_DIR;
+  const file = path.join(base, channel, `${date}.jsonl`);
+  if (!fs.existsSync(file)) return null;
+  const messages = parseDayJsonl(fs.readFileSync(file, "utf8"))
+    .filter((r) => r.type === "user" || r.type === "agent")
+    .map((r) => ({
+      role: r.type === "user" ? "user" : "assistant",
+      content: r.body || "",
+      ts: r.ts,
+    }));
+  return { id: date, channel, messages };
+}
+
 // Wipe the cache and re-populate from APX project messages. Reads BOTH `.jsonl`
 // (current format) and `.md` (legacy). Called by rebuild.
 export function rebuildMessagesFromFs(db, projectRoot) {

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

@@ -1,11 +1,14 @@
 // Per-agent conversation surface: list, fetch, compact, and a2a /send.
 //   GET  /projects/:pid/agents/:slug/conversations
 //   GET  /projects/:pid/agents/:slug/conversations/:id
+//   GET  /projects/:pid/super-agent/threads                    (channel ledger)
+//   GET  /projects/:pid/super-agent/threads/:channel/:id
 //   POST /projects/:pid/agents/:slug/compact
 //   POST /projects/:pid/agents/:slug/conversations/:id/compact
 //   POST /projects/:pid/send                                   (agent-to-agent)
 import { readAgents } from "#core/apc/parser.js";
 import { listConversations, readConversation } from "#core/stores/conversations.js";
+import { listGlobalThreads, readGlobalThread } from "#core/stores/messages.js";
 import { compactConversation } from "#core/stores/conversations-compactor.js";
 import { replyAsAgent } from "#core/agent/a2a/reply.js";
 import { nowIso } from "./shared.js";
@@ -48,6 +51,28 @@ export function register(app, { project, config }) {
     });
   });
 
+  // ---- Super-agent channel threads ----
+  // The super-agent's chats (telegram, web quick-chat, desktop, deck …) live
+  // in the global per-channel ledger, not in per-agent conversation files.
+  // These endpoints surface that ledger as day-threads so the web Chats
+  // sidebar can list and reopen them.
+  app.get("/projects/:pid/super-agent/threads", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    res.json(listGlobalThreads());
+  });
+
+  app.get("/projects/:pid/super-agent/threads/:channel/:id", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const thread = readGlobalThread({
+      channel: req.params.channel,
+      date: req.params.id,
+    });
+    if (!thread) return res.status(404).json({ error: "thread not found" });
+    res.json(thread);
+  });
+
   async function handleCompact(req, res, filename) {
     const p = project(req, res);
     if (!p) return;

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/interfaces/cli/commands/code.js

@@ -0,0 +1,56 @@
+// `apx code` — launch the APX terminal coding assistant (Solid.js TUI).
+// The TUI runs its TypeScript source directly under bun; there is no
+// legacy readline fallback anymore (removed with the old sys.js chat).
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { resolveProjectId } from "./project.js";
+import { readConfig } from "#core/config/index.js";
+import { readIdentity } from "#core/identity/index.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TUI_SRC = resolve(__dirname, "../../tui/run.ts");
+
+export async function cmdCode(args) {
+  const pid = await resolveProjectId(args?.flags?.project);
+  const cfg = readConfig();
+  const id = readIdentity();
+
+  // Optional --agent <slug>: route chat to a project agent instead of the APX
+  // default. Empty / missing flag means default ("super-agent" mode).
+  const agentFlag = typeof args?.flags?.agent === "string" ? args.flags.agent.trim() : "";
+  const routedAgentSlug = agentFlag || null;
+  const defaultAgentLabel = id?.agent_name || cfg.super_agent?.name || "APX";
+
+  if (!existsSync(TUI_SRC)) {
+    throw new Error(
+      "apx code: TUI source not found at src/interfaces/tui/run.ts — reinstall with `npm i -g @agentprojectcontext/apx`."
+    );
+  }
+
+  // bun must resolve node_modules/tsconfig from the apx package root, so the
+  // spawn cwd stays there — but we pass the user's actual working directory
+  // (where they ran `apx code`) via --cwd so the TUI shows the real project
+  // path + git branch instead of apx/src.
+  const bunBin = process.env.BUN_PATH || "bun";
+  const userCwd = process.cwd();
+  const result = spawnSync(bunBin, [
+    "--preload", "@opentui/solid/preload",
+    TUI_SRC,
+    "--pid", pid,
+    "--agent", routedAgentSlug || defaultAgentLabel,
+    "--model", cfg.super_agent?.model || "claude-3-5-sonnet",
+    "--cwd", userCwd,
+  ], { stdio: "inherit", cwd: resolve(__dirname, "../../..") });
+
+  if (result.error?.code === "ENOENT") {
+    throw new Error(
+      "apx code: bun is required to run the TUI but was not found. Install it (https://bun.sh) or set BUN_PATH to the binary."
+    );
+  }
+  if (result.error) throw result.error;
+  if (typeof result.status === "number" && result.status !== 0) {
+    process.exitCode = result.status;
+  }
+}

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 {
@@ -89,7 +90,7 @@ import {
   cmdConversationsList,
   cmdConversationsGet,
 } from "./commands/chat.js";
-import { cmdSys as cmdCode } from "./commands/sys.js";
+import { cmdCode } from "./commands/code.js";
 import { cmdRun, cmdEnvDetect } from "./commands/runtime.js";
 import { cmdSend, cmdConnections } from "./commands/a2a.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;