@agentprojectcontext/apx 1.76.0 → 1.77.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.76.0",
+  "version": "1.77.1",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"
@@ -40,7 +40,8 @@
     "upgrade": "pnpm install && pnpm add -g .",
     "prepare": "node scripts/install-githooks.js",
     "prepack": "node scripts/sync-apc-skill.js && node scripts/build-web.js",
-    "postinstall": "node src/interfaces/cli/postinstall.js"
+    "postinstall": "node src/interfaces/cli/postinstall.js",
+    "smoke:seam": "node --test --test-reporter=spec tests/smoke/*.smoke.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/src/core/net/lan.js

@@ -0,0 +1,114 @@
+// LAN address discovery, for reaching the panel from a phone on the same
+// network.
+//
+// This is deliberately NOT a tunnel. Nothing leaves the local network: the
+// daemon binds a second, specific interface address and that is all. The threat
+// model of a home LAN is not the threat model of a guessable public hostname,
+// which is why this is acceptable where a public tunnel is not — see
+// docs-internal/secretary/04-BACKLOG-agent-inbox.md § C.
+import os from "node:os";
+
+/** Bind addresses that are never chosen automatically. */
+const LOOPBACK = new Set(["127.0.0.1", "::1"]);
+
+/**
+ * Every non-internal IPv4 address on this machine, best candidate first.
+ *
+ * Ordering matters because the first one is what `apx panel share` will pick:
+ * ordinary private ranges (a home or office network) come before link-local
+ * autoconfiguration addresses, which usually mean "no DHCP happened" and are
+ * rarely what someone wants to type into a phone.
+ *
+ * @returns {{ address: string, iface: string, cidr: string|null, private: boolean }[]}
+ */
+export function detectLanAddresses() {
+  const out = [];
+  const ifaces = os.networkInterfaces();
+
+  for (const [iface, addrs] of Object.entries(ifaces || {})) {
+    for (const a of addrs || []) {
+      if (!a || a.internal) continue;
+      // Node <18.4 reported family as the string "IPv4"; newer versions use 4.
+      if (a.family !== "IPv4" && a.family !== 4) continue;
+      if (LOOPBACK.has(a.address)) continue;
+      out.push({
+        address: a.address,
+        iface,
+        cidr: a.cidr || null,
+        private: isPrivateIPv4(a.address),
+      });
+    }
+  }
+
+  return out.sort((x, y) => {
+    // Real private addresses first, link-local last.
+    const rank = (v) => (isLinkLocal(v.address) ? 2 : v.private ? 0 : 1);
+    const d = rank(x) - rank(y);
+    return d !== 0 ? d : x.address.localeCompare(y.address);
+  });
+}
+
+/** RFC1918 plus carrier-grade NAT — "an address someone else's router gave me". */
+export function isPrivateIPv4(address) {
+  const p = String(address || "").split(".").map(Number);
+  if (p.length !== 4 || p.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return false;
+  const [a, b] = p;
+  if (a === 10) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT (e.g. Tailscale)
+  return false;
+}
+
+/** 169.254.0.0/16 — self-assigned when no DHCP answered. */
+export function isLinkLocal(address) {
+  const p = String(address || "").split(".").map(Number);
+  return p[0] === 169 && p[1] === 254;
+}
+
+export function isLoopback(address) {
+  return LOOPBACK.has(String(address || "").trim());
+}
+
+/** Binds every interface, present and future. Never chosen automatically. */
+export function isWildcard(address) {
+  const h = String(address || "").trim();
+  return h === "0.0.0.0" || h === "::" || h === "*";
+}
+
+/**
+ * Validate a host the user asked to bind.
+ *
+ * `0.0.0.0` is refused on purpose. It binds every interface present now AND
+ * every one that appears later — a VPN, a hotspot, a bridged container — which
+ * is a different and much larger promise than "reachable on my home network".
+ * The specific address is always available instead.
+ *
+ * @returns {{ ok: boolean, reason?: string }}
+ */
+export function validateBindHost(host) {
+  const h = String(host || "").trim();
+  if (!h) return { ok: false, reason: "no host given" };
+
+  if (h === "0.0.0.0" || h === "::" || h.toLowerCase() === "any") {
+    return {
+      ok: false,
+      reason:
+        "0.0.0.0 binds every interface, including ones that appear later (a VPN, a hotspot, " +
+        "a bridged container). Bind a specific address instead — `apx panel share` picks one.",
+    };
+  }
+
+  if (isLoopback(h)) return { ok: true };
+
+  const known = detectLanAddresses().map((a) => a.address);
+  if (!known.includes(h)) {
+    return {
+      ok: false,
+      reason:
+        `${h} is not an address of this machine` +
+        (known.length ? ` — available: ${known.join(", ")}` : " (no external interface found)"),
+    };
+  }
+  return { ok: true };
+}

package/src/core/profiles/bundled/secretary/PROFILE.md

@@ -19,10 +19,10 @@ through you is anchored to a project registered in APX.
 
 ## How you work
 
-**Capture by default, ask rarely.** When a task surfaces in conversation, record it
-yourself. Infer the project when you reasonably can and say in one line what you filed and
-where. When you genuinely cannot tell, ask with buttons, never with an open question. The
-system dies the day recording something costs more than not recording it.
+**Capture by default, ask rarely.** When a task surfaces, record it yourself. Infer the
+project when you can and say in one line what you filed and where. When you genuinely
+cannot tell, ask with buttons, never an open question. The system dies the day recording
+something costs more than not recording it.
 
 **Tasks and commitments are different.** A task is work to be done. A commitment was
 promised to a specific person, with a date; breaking it has a relational cost. Commitments
@@ -33,7 +33,8 @@ recorded on X since Y". That is useful. A fabricated summary destroys trust in t
 system and it does not come back. Always prefer the explicit gap over the tidy assumption.
 
 **Write like someone who knows the subject.** Short sentences. No decorative headers, no
-greeting rituals, no six bullets where two sentences do. What matters goes first.
+greeting rituals, no six bullets where two sentences do. What matters goes first. These
+instructions are in English; write to {{owner_name}} in their language.
 
 **Delegate domain work.** You coordinate; you do not do it. Anything involving code goes
 through the development agent. When several specialists report back, you consolidate —

package/src/core/profiles/bundled/secretary/profile.json

@@ -5,16 +5,29 @@
   "description": "Chief of staff for someone running several projects at once. Keeps their state alive, captures what is said, and warns before something breaks.",
   "author": "apx",
   "apx_min_version": "1.74.1",
-  "languages": ["en", "es"],
+  "languages": [
+    "en"
+  ],
   "provides": {
-    "routines": ["day-open", "day-close"],
-    "channels": ["routine"]
+    "routines": [
+      "day-open",
+      "day-close"
+    ],
+    "channels": [
+      "routine"
+    ]
   },
   "requires": {
-    "capabilities": ["routine.memory"],
+    "capabilities": [
+      "routine.memory"
+    ],
     "integrations": [],
-    "optional_integrations": ["calendar"],
-    "channels": ["telegram"]
+    "optional_integrations": [
+      "calendar"
+    ],
+    "channels": [
+      "telegram"
+    ]
   },
   "prompt_budget_tokens": 600
 }

package/src/core/stores/agent-inbox.js

@@ -0,0 +1,153 @@
+// The agent inbox — every agent as a conversation, most recent first.
+//
+// APX is navigated project-first: pick a project, then a tab, then an agent.
+// The inbox inverts that. The unit becomes the CONVERSATION WITH AN AGENT and
+// the project becomes an attribute of it, which is what someone running several
+// projects at once actually wants as a daily entry point.
+//
+// It is a second axis, NOT a replacement. Project-first navigation stays intact
+// — projects as a first-class unit with versioned context is what APX has that
+// a personal assistant does not, and the inbox must not erode it.
+//
+// Same shape as listTasksAcrossProjects in stores/tasks.js, for the same
+// reasons: the caller supplies the project list so core stays free of daemon
+// imports, an unreadable project is skipped and named rather than fatal, and
+// ordering has a deterministic tiebreak because nowIso() only has second
+// resolution.
+import { readAgents } from "../apc/parser.js";
+import { listConversations } from "./conversations.js";
+import { listGlobalThreads, readGlobalThread } from "./messages.js";
+import { SUPERAGENT_ACTOR_ID } from "../constants/actors.js";
+
+/** Most recent first; slug breaks ties so two identical calls agree. */
+function byRecency(a, b) {
+  const t = (b.last_activity_at || "").localeCompare(a.last_activity_at || "");
+  if (t !== 0) return t;
+  return String(a.agent_slug || "").localeCompare(String(b.agent_slug || ""));
+}
+
+/**
+ * One row per agent that has a conversation, plus the super-agent.
+ *
+ * @param {{id:any, name?:string, path?:string, storagePath:string}[]} projects
+ * @param {object} opts
+ *   - limit          cap applied AFTER the merge
+ *   - includeEmpty   also list agents that have never been talked to
+ * @returns {{ rows: object[], skipped: {id:any, error:string}[] }}
+ */
+export function listAgentInbox(projects, opts = {}) {
+  const { limit, includeEmpty = false } = opts || {};
+  const rows = [];
+  const skipped = [];
+
+  for (const entry of projects || []) {
+    if (!entry?.storagePath) continue;
+    const projectMeta = {
+      project_id: entry.id,
+      project_name: entry.name || entry.path || String(entry.id),
+      project_path: entry.path || null,
+    };
+
+    let agents = [];
+    try {
+      agents = entry.path ? readAgents(entry.path) : [];
+    } catch (e) {
+      skipped.push({ id: entry.id, error: e?.message || String(e) });
+      continue;
+    }
+
+    for (const agent of agents) {
+      let conversations = [];
+      try {
+        conversations = listConversations(entry.storagePath, agent.slug);
+      } catch {
+        // One agent's unreadable conversation directory must not drop the
+        // whole project from the inbox.
+        conversations = [];
+      }
+      const latest = conversations[0] || null;
+      if (!latest && !includeEmpty) continue;
+
+      rows.push({
+        ...projectMeta,
+        agent_slug: agent.slug,
+        agent_name: agent.fields?.Name || agent.name || agent.slug,
+        agent_emoji: agent.fields?.Emoji || agent.emoji || null,
+        kind: "agent",
+        pinned: false,
+        conversation_id: latest?.id || null,
+        channel: latest?.channel || null,
+        messages: latest?.messages || 0,
+        // The agent's last REPLY, not the user's last prompt.
+        preview: latest?.preview || null,
+        last_activity_at: latest?.last_turn_at || latest?.started_at || "",
+      });
+    }
+  }
+
+  rows.sort(byRecency);
+
+  // The super-agent is the single voice the owner talks to and the others
+  // report through it. It is pinned first and marked distinct so the hierarchy
+  // is visible, rather than sorted in among its own reports.
+  const superRow = buildSuperAgentRow();
+  const out = superRow ? [superRow, ...rows] : rows;
+
+  return {
+    rows: Number.isFinite(limit) && limit > 0 ? out.slice(0, limit) : out,
+    skipped,
+  };
+}
+
+/**
+ * The pinned super-agent row.
+ *
+ * The super-agent does NOT keep per-agent conversation files the way project
+ * agents do — it talks on channels, and its history is the cross-channel ledger
+ * (~/.apx/messages/<channel>/YYYY-MM-DD.jsonl). So recency and the preview come
+ * from there, not from agents/<slug>/conversations.
+ */
+function buildSuperAgentRow() {
+  let threads = [];
+  try {
+    threads = listGlobalThreads();
+  } catch {
+    threads = [];
+  }
+
+  const messages = threads.reduce((n, t) => n + (t.messages || 0), 0);
+  const latest = threads[0] || null; // listGlobalThreads sorts by last_ts desc
+
+  let preview = null;
+  if (latest) {
+    try {
+      const thread = readGlobalThread({ channel: latest.channel, date: latest.id });
+      const lastReply = [...(thread?.messages || [])]
+        .reverse()
+        .find((m) => m.role === "assistant");
+      preview = (lastReply?.content || "")
+        .replace(/```[\s\S]*?```/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 160) || null;
+    } catch {
+      preview = null;
+    }
+  }
+
+  return {
+    project_id: null,
+    project_name: null,
+    project_path: null,
+    agent_slug: SUPERAGENT_ACTOR_ID,
+    agent_name: null, // resolved by the surface via resolveAgentName()
+    agent_emoji: null,
+    kind: "super_agent",
+    pinned: true,
+    conversation_id: latest?.id || null,
+    channel: latest?.channel || null,
+    messages,
+    preview,
+    last_activity_at: latest?.last_ts || "",
+  };
+}

package/src/core/stores/conversations.js

@@ -73,7 +73,13 @@ export function parseConversation(text) {
     body = text.slice(fmEnd + 4);
   }
   const turns = [];
-  const re = /^##\s+(user|assistant|system|tool|compact)\s+—\s+(\S+)\s*\n([\s\S]*?)(?=\n##\s+(?:user|assistant|system|tool|compact)\s+—\s|\n*$)/gm;
+  // The terminator is "the next turn header, or the true end of input".
+  //
+  // It used to be `\n*$`, and with the /m flag `$` matches the end of any LINE
+  // — so the lazy body stopped at the first newline and every multi-line turn
+  // was silently truncated to its first line. `(?![\s\S])` is end-of-input and
+  // nothing else. /m is still needed for the `^` on the header.
+  const re = /^##\s+(user|assistant|system|tool|compact)\s+—\s+(\S+)\s*\n([\s\S]*?)(?=\n##\s+(?:user|assistant|system|tool|compact)\s+—\s|\s*(?![\s\S]))/gm;
   let m;
   while ((m = re.exec(body)) !== null) {
     turns.push({
@@ -124,15 +130,29 @@ function summarizeConversation(filePath, agentSlug, filename) {
   const messages = turns.filter((t) => t.role !== "system" && t.role !== "compact").length;
   const firstUser = turns.find((t) => t.role === "user");
   const title = (firstUser?.content || "").split("\n")[0].slice(0, 80).trim() || undefined;
+
+  // What the AGENT last said, not what the user last asked. An inbox row that
+  // echoes your own prompt back tells you nothing; the reply is the thing you
+  // want to see without opening the thread ("report filed, nothing over policy").
+  const lastReply = [...turns].reverse().find((t) => t.role === "assistant");
+  const preview = (lastReply?.content || "")
+    .replace(/```[\s\S]*?```/g, " ")   // code fences read as noise at one line
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 160) || undefined;
+
   return {
     id: filename.replace(/\.md$/, ""),
     filename,
     agent_slug: agentSlug,
     started_at: fm.started || fm.last_turn || "",
+    last_turn_at: fm.last_turn || fm.started || "",
     ended_at: fm.status === "closed" ? (fm.last_turn || undefined) : undefined,
     channel: fm.channel || undefined,
     messages,
     title,
+    preview,
+    preview_at: lastReply?.ts || undefined,
   };
 }
 

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

@@ -0,0 +1,45 @@
+// GET /inbox   every agent as a conversation, most recent first, super-agent pinned
+//              ?limit=N&include_empty=1
+//
+// The conversation-first entry point. Project-first navigation is unaffected —
+// this is a second axis over the same data, not a replacement for it.
+import { listAgentInbox } from "#core/stores/agent-inbox.js";
+import { readConfig } from "#core/config/index.js";
+import { resolveAgentName } from "#core/identity/index.js";
+import { pageEnvelope } from "./shared.js";
+
+export function register(app, { projects }) {
+  app.get("/inbox", (req, res) => {
+    try {
+      const entries = [];
+      for (const entry of projects.list()) {
+        const p = projects.get(entry.id);
+        if (!p?.storagePath) continue;
+        entries.push({
+          id: entry.id,
+          name: entry.name || entry.path,
+          path: entry.path,
+          storagePath: p.storagePath,
+        });
+      }
+
+      const { rows, skipped } = listAgentInbox(entries, {
+        includeEmpty: req.query.include_empty === "1" || req.query.include_empty === "true",
+      });
+
+      // The super-agent's display name lives in identity.json, and core must not
+      // reach for it — resolve it here, at the surface (AGENTS.md rule 4).
+      const cfg = readConfig();
+      const superName = resolveAgentName(cfg);
+      const named = rows.map((r) =>
+        r.kind === "super_agent" ? { ...r, agent_name: r.agent_name || superName } : r
+      );
+
+      const envelope = pageEnvelope(named, req.query);
+      if (skipped.length) envelope.meta = { ...(envelope.meta || {}), skipped };
+      res.json(envelope);
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+}

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

@@ -24,7 +24,8 @@ 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", "/skills", "/profiles",
+  "/super-agent", "/identity", "/skills", "/profiles", "/inbox",
+  "/tasks", "/agents", "/plugins", "/previews", "/embeddings",
 ];
 
 export function isApiPath(p) {
@@ -42,7 +43,7 @@ export function isApiPath(p) {
 const SPA_ROUTES = [
   /^\/$/,
   /^\/settings(\/.*)?$/,
-  /^\/m\/(voice|desktop|deck|code)(\/.*)?$/,
+  /^\/m\/(voice|desktop|deck|code|inbox)(\/.*)?$/,
   /^\/p\/[^/]+(\/.*)?$/,
 ];
 

package/src/host/daemon/api.js

@@ -52,6 +52,7 @@ import { register as registerAdmin } from "./api/admin.js";
 import { register as registerAdminConfig } from "./api/admin-config.js";
 import { register as registerIdentity } from "./api/identity.js";
 import { register as registerProfiles } from "./api/profiles.js";
+import { register as registerInbox } from "./api/inbox.js";
 import { register as registerWeb } from "./api/web.js";
 import { register as registerConfirm } from "./api/confirm.js";
 
@@ -153,6 +154,7 @@ export function buildApi({
   registerAdminConfig(app, ctx);
   registerIdentity(app, ctx);
   registerProfiles(app, ctx);
+  registerInbox(app, ctx);
 
   // ---- Web admin panel (static SPA, must mount before 404) ---------
   // Serves src/interfaces/web/dist when present + the /admin/web-token

package/src/host/daemon/db.js

@@ -126,6 +126,12 @@ export class ProjectManager {
         name,
         kind,
         agents: readAgents(e.path).length,
+        // Where this project's runtime state lives. The CLI needs it to reach
+        // per-routine memory and anything else stored outside the repo — it has
+        // no other way to resolve it, and `apx routine memory` was silently
+        // broken for want of these two fields.
+        apx_id: e.apxId || null,
+        storage_path: e.storagePath || null,
       };
     });
   }

package/src/host/daemon/index.js

@@ -3,9 +3,13 @@
 // Must run before any outbound fetch — see the module header for why.
 import "#core/net/ipv4-first.js";
 import fs from "node:fs";
+import http from "node:http";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomBytes } from "node:crypto";
+
+// Loopback is always bound, no matter what `host` is configured to.
+const LOOPBACK_HOST = "127.0.0.1";
 import {
   readConfig,
   writeConfig,
@@ -233,9 +237,29 @@ async function main() {
   plugins.installRoutes(app);
 
   let callbackReconciler = null;
-  const server = app.listen(port, host, () => {
+
+  // Loopback is ALWAYS bound, whatever `host` says.
+  //
+  // Binding a single specific LAN address (what `apx panel share` configures)
+  // excludes 127.0.0.1 — and the CLI, the desktop app and /admin/web-token all
+  // reach the daemon over loopback. Sharing the panel with the phone must not
+  // take the local toolchain down with it, so a non-loopback host means TWO
+  // listeners on one app, not a move.
+  const extraHosts =
+    host && host !== LOOPBACK_HOST && host !== "0.0.0.0" && host !== "::" ? [host] : [];
+  const secondary = [];
+
+  const server = app.listen(port, extraHosts.length ? LOOPBACK_HOST : host, () => {
     writePid();
-    log(`apx-daemon ${PKG.version} listening on http://${host}:${port}`);
+    for (const h of extraHosts) {
+      // A secondary bind failing must never take the daemon down — the local
+      // one is already up and is the one everything depends on.
+      const s2 = http.createServer(app);
+      s2.on("error", (e) => log(`bind ${h}:${port} failed (${e.code || e.message}) — local access unaffected`));
+      s2.listen(port, h, () => log(`apx-daemon also listening on http://${h}:${port}`));
+      secondary.push(s2);
+    }
+    log(`apx-daemon ${PKG.version} listening on http://${extraHosts.length ? LOOPBACK_HOST : host}:${port}`);
     log(`projects: ${projects.list().length} | plugins: ${Object.keys(plugins.status()).join(", ") || "(none)"}`);
     plugins.startAll();
     scheduler.start();
@@ -317,6 +341,11 @@ async function main() {
     import("./whisper-server.js").then(({ shutdownWhisperServer }) => {
       shutdownWhisperServer().catch(() => {});
     }).catch(() => {});
+    // Close the LAN listener(s) too, or the port stays held after SIGTERM and
+    // the next `apx restart` fails with "already running".
+    for (const s2 of secondary) {
+      try { s2.close(); } catch { /* already down */ }
+    }
     server.close(() => {
       clearPid();
       process.exit(0);