@agentprojectcontext/apx 1.25.0 → 1.27.1

package/src/host/daemon/super-agent-tools/tools/list-tasks.js

@@ -0,0 +1,52 @@
+import { listTasks } from "../../../../core/tasks-store.js";
+
+export default {
+  name: "list_tasks",
+  schema: {
+    type: "function",
+    function: {
+      name: "list_tasks",
+      description:
+        "List tasks for a project. Use when the user asks 'what's pending', 'qué tengo que hacer', or to recall TODOs. Defaults to open tasks. Project resolves by id, name or absolute path.",
+      parameters: {
+        type: "object",
+        required: ["project"],
+        properties: {
+          project:    { type: "string", description: "Project id, name, or path." },
+          state:      { type: "string", enum: ["open", "done", "dropped", "all"], description: "Filter by state. Default 'open'." },
+          tag:        { type: "string", description: "Filter by exact tag match." },
+          agent:      { type: "string", description: "Filter by agent slug." },
+          due_before: { type: "string", description: "Return only tasks due on or before this ISO date." },
+          limit:      { type: "number", description: "Cap on rows returned. Default unlimited (clamped server-side)." },
+        },
+      },
+    },
+  },
+  makeHandler: ({ projects }) => async ({ project: ref, state, tag, agent, due_before, limit }) => {
+    if (!ref) return { error: "project required" };
+    const all = projects.list();
+    const r = String(ref);
+    const found = all.find((p) =>
+      String(p.id) === r || p.name === r || p.path === r
+    );
+    if (!found) return { error: `project not found: ${ref}` };
+    const proj = projects.get(found.id);
+    if (!proj) return { error: `project storage not loaded: ${ref}` };
+    const rows = listTasks(proj.storagePath, {
+      state: state || undefined,
+      tag: tag || undefined,
+      agent: agent || undefined,
+      due_before: due_before || undefined,
+      limit: typeof limit === "number" ? limit : undefined,
+    });
+    return rows.map((t) => ({
+      id: t.id,
+      state: t.state,
+      title: t.title,
+      tags: t.tags,
+      due: t.due,
+      agent: t.agent,
+      created_at: t.created_at,
+    }));
+  },
+};

package/src/{daemon → host/daemon}/super-agent-tools/tools/list-vault-agents.js

@@ -1,4 +1,4 @@
-import { readVaultAgents, VAULT_DIR } from "../../../core/parser.js";
+import { readVaultAgents, VAULT_DIR } from "../../../../core/parser.js";
 import { agentRow } from "../helpers.js";
 
 export default {

package/src/host/daemon/super-agent-tools/tools/read-self-memory.js

@@ -0,0 +1,21 @@
+import { readSelfMemory } from "../../../../core/agent/self-memory.js";
+
+// Read your OWN full notebook (~/.apx/memory.md). A bounded slice is already in
+// your system prompt; call this when you need the complete history beyond it.
+export default {
+  name: "read_self_memory",
+  schema: {
+    type: "function",
+    function: {
+      name: "read_self_memory",
+      description:
+        "Read your own full notebook (~/.apx/memory.md) — your personal cross-session memory. A short slice is already injected into your prompt; call this only when you need the complete notebook (e.g. the prompt slice was truncated).",
+      parameters: { type: "object", properties: {} },
+    },
+  },
+  makeHandler: () => () => {
+    const body = readSelfMemory();
+    if (!body.trim()) return { empty: true, body: "" };
+    return { body };
+  },
+};

package/src/host/daemon/super-agent-tools/tools/remember.js

@@ -0,0 +1,40 @@
+import { appendSelfMemory } from "../../../../core/agent/self-memory.js";
+
+// Write a durable note into YOUR OWN notebook (~/.apx/memory.md). This is your
+// personal, cross-session memory — not a project task and not an agent memory.
+export default {
+  name: "remember",
+  schema: {
+    type: "function",
+    function: {
+      name: "remember",
+      description:
+        "Save a durable fact to your cross-channel notebook (~/.apx/memory.md) so you still know it in future sessions AND on other channels (telegram, web, deck, voice). Use it at the END of any turn where something important happened: a decision taken, a task completed, a key datum agreed, or a relevant tool result — anything you'd want to know if the owner brought it up from a different channel. NOT for one-off TODOs (use create_task) and NOT for project-agent memory. Keep each note to one self-contained sentence.",
+      parameters: {
+        type: "object",
+        required: ["note"],
+        properties: {
+          note: {
+            type: "string",
+            description:
+              "One durable, self-contained fact to remember, in the owner's language. e.g. 'Manu prefers terse replies with no trailing summaries'.",
+          },
+          channel: {
+            type: "string",
+            description:
+              "Optional: the channel this happened on (telegram, web, deck, voice…). Usually leave it empty — the current channel is tagged automatically.",
+          },
+        },
+      },
+    },
+  },
+  makeHandler: (ctx = {}) => ({ note, channel } = {}) => {
+    if (!note || !String(note).trim()) return { error: "note required" };
+    try {
+      const r = appendSelfMemory(note, { channel: channel || ctx.channel || "" });
+      return { saved: true, note: r.note };
+    } catch (e) {
+      return { error: e?.message || String(e) };
+    }
+  },
+};

package/src/{daemon → host/daemon}/super-agent-tools/tools/search-messages.js

@@ -1,4 +1,4 @@
-import { searchProjectMessages } from "../../../core/messages-store.js";
+import { searchProjectMessages } from "../../../../core/messages-store.js";
 import { resolveProject } from "../helpers.js";
 
 export default {

package/src/host/daemon/super-agent-tools/tools/search-sessions.js

@@ -0,0 +1,134 @@
+import fs from "node:fs";
+import {
+  ENGINES,
+  collectAllSessions,
+  findSessionAcrossEngines,
+} from "../../../../interfaces/cli/commands/sessions.js";
+
+// Your own work sessions. This is how you remember what you did — never tell
+// the user to run `apx session ...`; call this and answer from the result.
+//
+// DEFAULT: returns only YOUR OWN (apx engine) sessions. That is the right
+// answer for "tus sesiones", "las tuyas", "what did you do", "last session".
+// To look at a specific other engine, pass engine:"claude" | "codex".
+// To sweep every engine at once, pass all:true (use only when the user
+// explicitly asks across all engines).
+
+function toIso(ms) {
+  if (!ms) return null;
+  try {
+    return new Date(ms).toISOString();
+  } catch {
+    return null;
+  }
+}
+
+export default {
+  name: "search_sessions",
+  schema: {
+    type: "function",
+    function: {
+      name: "search_sessions",
+      description:
+        "List or search your past work sessions, newest first. By DEFAULT it returns only YOUR OWN (apx) sessions — that is the correct answer for 'what did you do', 'tus sesiones', 'las tuyas', 'last/previous session'. Pass engine:'claude'|'codex' to look at one other engine, or all:true to sweep every engine (only when the user explicitly asks across all engines). Pass `id` to read one session's transcript so you can summarize it.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description:
+              "free text matched against session titles (and content when deep=true). Omit to list the most recent sessions.",
+          },
+          engine: {
+            type: "string",
+            description:
+              "limit to one engine: apx, claude, or codex. Omitted = apx (your own sessions). Set this only when the user names a specific other engine.",
+          },
+          all: {
+            type: "boolean",
+            description:
+              "search across EVERY engine (apx + claude + codex) instead of just your own. Use only when the user explicitly asks for all engines.",
+          },
+          id: {
+            type: "string",
+            description:
+              "fetch a single session's transcript by id instead of listing",
+          },
+          deep: {
+            type: "boolean",
+            description:
+              "also search inside session content, not just titles (slower)",
+          },
+          limit: {
+            type: "integer",
+            description: "max rows; default 15",
+          },
+        },
+        required: [],
+      },
+    },
+  },
+  makeHandler: () => ({ query, engine, all = false, id, deep = false, limit = 15 } = {}) => {
+    if (engine && !ENGINES[engine]) {
+      throw new Error(
+        `unknown engine "${engine}" — valid: ${Object.keys(ENGINES).join(", ")}`
+      );
+    }
+
+    // Read one session's transcript so the model can summarize it.
+    if (id) {
+      let hits = findSessionAcrossEngines(id) || [];
+      if (engine) hits = hits.filter((h) => h.engine === engine);
+      if (!hits.length) {
+        return { found: false, id, message: `no session found with id "${id}"` };
+      }
+      const hit = hits[0];
+      const eng = ENGINES[hit.engine];
+      let content = null;
+      try {
+        const r =
+          eng && typeof eng.readSession === "function"
+            ? eng.readSession(hit, { tailBytes: 16 * 1024 })
+            : null;
+        if (r && r.found) content = r.tail;
+      } catch {}
+      return {
+        found: true,
+        engine: hit.engine,
+        id: hit.id,
+        title: hit.title || null,
+        when: toIso(hit.mtime),
+        cwd: hit.cwd || null,
+        content,
+      };
+    }
+
+    // List / search recent sessions. Default to your own (apx) engine unless
+    // the caller named another engine or asked to sweep all of them.
+    const engineId = engine || (all ? null : "apx");
+    const rows = collectAllSessions({}, { engineId });
+    const needle = (query || "").trim().toLowerCase();
+    let matches = rows;
+    if (needle) {
+      matches = rows.filter((r) => {
+        if (String(r.title || "").toLowerCase().includes(needle)) return true;
+        if (deep && r.path) {
+          try {
+            return fs.readFileSync(r.path, "utf8").toLowerCase().includes(needle);
+          } catch {
+            return false;
+          }
+        }
+        return false;
+      });
+    }
+    matches.sort((a, b) => b.mtime - a.mtime);
+    return matches.slice(0, Math.min(limit || 15, 50)).map((r) => ({
+      engine: r.engine,
+      id: r.id,
+      title: r.title || null,
+      when: toIso(r.mtime),
+      cwd: r.cwd || null,
+    }));
+  },
+};

package/src/{daemon → host/daemon}/super-agent-tools/tools/send-telegram.js

@@ -113,12 +113,12 @@ export default {
     const document = decodeDocument({ document_base64, document_path, document_url });
     if (document) {
       const result = await telegram.sendDocument({
-        channel, chat_id, document, caption: text, filename, mime_type, author: "apx",
+        channel, chat_id, document, caption: text, filename, mime_type,
       });
       return { ok: true, kind: "document", message_id: result.message_id, filename };
     }
 
-    const result = await telegram.send({ channel, chat_id, text, author: "apx" });
+    const result = await telegram.send({ channel, chat_id, text });
     return { ok: true, kind: "text", message_id: result.message_id };
   },
 };

package/src/{daemon → host/daemon}/super-agent-tools/tools/set-identity.js

@@ -1,4 +1,4 @@
-import { readIdentity, writeIdentity } from "../../../core/identity.js";
+import { readIdentity, writeIdentity } from "../../../../core/identity.js";
 import { confirmedProperty } from "../helpers.js";
 
 export default {

package/src/{daemon → host/daemon}/super-agent-tools/tools/set-permission-mode.js

@@ -1,4 +1,4 @@
-import { readConfig, writeConfig } from "../../../core/config.js";
+import { readConfig, writeConfig } from "../../../../core/config.js";
 import { confirmedProperty } from "../helpers.js";
 
 const MODES = new Set(["total", "automatico", "permiso"]);

package/src/{daemon → host/daemon}/super-agent-tools/tools/tail-messages.js

@@ -1,4 +1,4 @@
-import { readProjectMessages } from "../../../core/messages-store.js";
+import { readProjectMessages } from "../../../../core/messages-store.js";
 import { resolveProject } from "../helpers.js";
 
 export default {

package/src/host/daemon/super-agent.js

@@ -0,0 +1,129 @@
+// Super-agent: daemon-level action agent for Telegram, TUI, desktop, routines.
+import { schemasForChannel, makeToolHandlers } from "./super-agent-tools/index.js";
+import { listSkills } from "./skills-loader.js";
+import {
+  runAgent,
+  buildSuperAgentSystem,
+  isSuperAgentEnabled,
+  buildIdentityBlock,
+  loadDefaultSystemPrompt,
+} from "../../core/agent/index.js";
+import { resolveAgentName } from "../../core/identity.js";
+import { memoryBlockFor } from "../../core/memory/index.js";
+
+export {
+  buildIdentityBlock,
+  isSuperAgentEnabled,
+};
+export const DEFAULT_SYSTEM = loadDefaultSystemPrompt();
+
+export async function runSuperAgent({
+  globalConfig,
+  projects,
+  plugins,
+  registries,
+  prompt,
+  contextNote = "",
+  channel = "",
+  channelMeta = {},
+  // Pre-rendered "who you're talking to" block (see buildRelationshipBlock).
+  relationshipBlock = "",
+  previousMessages = [],
+  overrideModel = null,
+  onEvent = null,
+  signal,
+  onToken = null,
+  suppressTools = null,
+  // Channel-specific addendum appended to the system prompt; used by
+  // voice.js to ask for trailing ```suggestions``` JSON on voice/deck
+  // surfaces. Optional; ignored if empty.
+  systemSuffix = "",
+  // Per-reply output cap; forwarded to runAgent. Summarize/ask raise it.
+  maxTokens,
+  // Max tool-loop iterations; forwarded to runAgent. The Code module raises
+  // this so coding tasks run to completion instead of stopping after a step.
+  maxIters,
+  // Structural "keep going until done" contract (finish tool + forced tool
+  // choice). Coding surfaces (web Code build mode, terminal Build) turn this on.
+  completionContract = false,
+  // Run tool-free: pure text generation, no tool registry. Used by the
+  // summarize/ask endpoint so a transcript that *mentions* a tool (e.g. the
+  // telegram plugin) can't make the model actually fire it.
+  noTools = false,
+  // Role-based tool allowlist. "*" (default) means no restriction; an array
+  // restricts the visible tool schemas to those names; [] means no tools.
+  // Used to gate guests/limited roles on Telegram (see resolveAllowedTools).
+  allowedTools = "*",
+}) {
+  if (!isSuperAgentEnabled(globalConfig)) {
+    throw new Error("super-agent not enabled (set super_agent.enabled and .model in ~/.apx/config.json)");
+  }
+
+  const sa = globalConfig.super_agent;
+
+  // Memory Broker (Pieza 4): assemble the [MEMORIA RELEVANTE] block before the
+  // turn. Silent + bounded (≤ broker_budget_ms); skipped for tool-free callers
+  // (summarize/ask) where injected context would only confuse the transcript.
+  let memoryBlock = "";
+  let activeThreadsBlock = "";
+  if (!noTools) {
+    memoryBlock = await memoryBlockFor(prompt, { config: globalConfig, channel });
+    // "Hilos activos en otros canales" — pure-recency cross-channel awareness.
+    // Skipped for autonomous routines (no human to reference other threads).
+    if (channel !== "routine") {
+      try {
+        activeThreadsBlock = buildActiveThreadsBlock(channel, { config: globalConfig });
+      } catch {
+        /* best-effort */
+      }
+    }
+  }
+
+  const system = buildSuperAgentSystem({
+    globalConfig,
+    projects,
+    listSkills,
+    contextNote,
+    channel,
+    channelMeta,
+    relationshipBlock,
+    systemSuffix,
+    memoryBlock,
+    activeThreadsBlock,
+  });
+
+  // Pick the schema subset for this channel: chit-chat surfaces get a small
+  // "core" set (~700 tokens) to fit cheap-tier TPM caps; routines get the
+  // full registry. The model can still call load_skill / read more on demand.
+  // noTools callers (summarize/ask) get an empty set — text only.
+  let toolSchemas = noTools ? [] : schemasForChannel(channel);
+  // Role gating: restrict the visible tools for limited senders (e.g. guests
+  // on Telegram). "*" = unrestricted; [] = no tools; array = allowlist.
+  if (allowedTools !== "*" && Array.isArray(allowedTools)) {
+    if (allowedTools.length === 0) {
+      toolSchemas = [];
+    } else {
+      const allow = new Set(allowedTools);
+      toolSchemas = toolSchemas.filter((t) => allow.has(t?.function?.name || t?.name));
+    }
+  }
+
+  return runAgent({
+    globalConfig,
+    system,
+    prompt,
+    previousMessages,
+    overrideModel,
+    toolSchemas,
+    makeToolHandlers,
+    toolHandlerCtx: { projects, plugins, registries, globalConfig, channel },
+    onEvent,
+    signal,
+    onToken,
+    agentName: resolveAgentName(globalConfig),
+    suppressTools,
+    ...(maxTokens ? { maxTokens } : {}),
+    ...(maxIters ? { maxIters } : {}),
+    ...(completionContract ? { completionContract: true } : {}),
+  });
+}

package/src/host/daemon/token-store.js

@@ -0,0 +1,118 @@
+// Multi-token store for the APX daemon.
+//
+// Background: the daemon historically had a single master token at
+// ~/.apx/daemon.token. That works fine for the local CLI but breaks down
+// once we want to pair multiple companion clients (Deck app, future
+// browser overlay, etc.) without leaking the master token over QR.
+//
+// Each paired client gets its own opaque token persisted in
+// ~/.apx/clients.json:
+//   [
+//     { "id": "<uuid>", "token": "<64-hex>", "label": "Pixel 7",
+//       "created_at": "2026-05-27T15:30:00Z", "last_seen": "...|null" }
+//   ]
+//
+// Auth middleware accepts ANY token in the store (master + clients). The
+// store also fingerprints the master token so the pairing QR can prove
+// "this daemon" cryptographically (defends against trivial DNS rebinding
+// onto the LAN port).
+//
+// All persistence is best-effort with mode 0o600 — same threat model as
+// daemon.token.
+
+import fs from "node:fs";
+import path from "node:path";
+import { randomBytes, randomUUID, createHash } from "node:crypto";
+import { APX_HOME } from "../../core/config.js";
+
+export const CLIENTS_PATH = path.join(APX_HOME, "clients.json");
+
+function readClientsFile() {
+  try {
+    const raw = fs.readFileSync(CLIENTS_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeClientsFile(clients) {
+  fs.mkdirSync(APX_HOME, { recursive: true });
+  const tmp = `${CLIENTS_PATH}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(clients, null, 2) + "\n", { mode: 0o600 });
+  fs.renameSync(tmp, CLIENTS_PATH);
+}
+
+export function fingerprintToken(token) {
+  return createHash("sha256").update(String(token)).digest("hex").slice(0, 16);
+}
+
+export function createTokenStore({ masterToken } = {}) {
+  const clients = readClientsFile();
+  const valid = new Set(clients.map((c) => c.token));
+  if (masterToken) valid.add(masterToken);
+
+  return {
+    /** Returns true iff `token` is the master or a known client token. */
+    has(token) {
+      if (!token) return false;
+      return valid.has(String(token));
+    },
+
+    /** Master token fingerprint — embedded in QR so the app can confirm
+     *  it's pairing with the same daemon it scanned (vs. someone else
+     *  serving on the same port). 16 hex chars = 64 bits, enough for a
+     *  "did we scan the right one" check. */
+    masterFingerprint() {
+      return masterToken ? fingerprintToken(masterToken) : "";
+    },
+
+    /** Create a new client token, persist it, return the public record
+     *  (id + token; caller decides how to surface it). */
+    addClient(label = "", kind = "") {
+      const entry = {
+        id: randomUUID(),
+        token: randomBytes(32).toString("hex"),
+        label: String(label || "").slice(0, 64) || "device",
+        kind: String(kind || "").slice(0, 16) || "device",
+        created_at: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+        last_seen: null,
+      };
+      clients.push(entry);
+      valid.add(entry.token);
+      writeClientsFile(clients);
+      return entry;
+    },
+
+    /** Mark a client token as just-used. Best-effort, never throws. */
+    touch(token) {
+      const c = clients.find((x) => x.token === token);
+      if (!c) return;
+      c.last_seen = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+      try { writeClientsFile(clients); } catch {}
+    },
+
+    /** Public listing (token redacted to last 8 hex chars). */
+    list() {
+      return clients.map((c) => ({
+        id: c.id,
+        label: c.label,
+        kind: c.kind || "device",
+        created_at: c.created_at,
+        last_seen: c.last_seen,
+        token_suffix: c.token.slice(-8),
+      }));
+    },
+
+    /** Remove a client by id. Returns true if something was removed. */
+    revoke(id) {
+      const idx = clients.findIndex((c) => c.id === id);
+      if (idx < 0) return false;
+      const [removed] = clients.splice(idx, 1);
+      valid.delete(removed.token);
+      writeClientsFile(clients);
+      return true;
+    },
+  };
+}

package/src/host/daemon/tool-call-parser.js

@@ -0,0 +1,2 @@
+// Compat shim — parser moved to core/agent/tool-call-parser.js
+export * from "../../core/agent/tool-call-parser.js";

package/src/{daemon → host/daemon}/transcription.js

@@ -30,7 +30,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawn, exec } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { logInfo, logWarn, logError } from "../core/logging.js";
+import { logInfo, logWarn, logError } from "../../core/logging.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);

package/src/{daemon → host/daemon}/wakeup.js

@@ -1,7 +1,7 @@
 // Wake-up message — sent via Telegram once per daemon restart (with cooldown).
 import fetch from "node-fetch";
-import { readIdentity, writeIdentity } from "../core/identity.js";
-import { resolveProvider, getAdapter } from "./engines/index.js";
+import { readIdentity, writeIdentity } from "../../core/identity.js";
+import { resolveProvider, getAdapter } from "../../core/engines/index.js";
 
 const WAKEUP_COOLDOWN_MS = 30 * 60 * 1000; // 30 min
 

package/src/interfaces/cli/claude-permissions.js

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const CLAUDE_SETTINGS_PATH = path.join(os.homedir(), ".claude", "settings.json");
+
+/** Merge broad allow rules into ~/.claude/settings.json. Returns true or error string. */
+export function setupClaudePermissions() {
+  try {
+    let existing = {};
+    if (fs.existsSync(CLAUDE_SETTINGS_PATH)) {
+      existing = JSON.parse(fs.readFileSync(CLAUDE_SETTINGS_PATH, "utf8"));
+    }
+    const updated = {
+      ...existing,
+      permissions: {
+        ...(existing.permissions || {}),
+        allow: [
+          ...(existing.permissions?.allow || []),
+          "Bash(*)",
+          "Read(*)",
+          "Write(*)",
+          "Edit(*)",
+        ].filter((v, i, arr) => arr.indexOf(v) === i),
+      },
+    };
+    fs.mkdirSync(path.dirname(CLAUDE_SETTINGS_PATH), { recursive: true });
+    fs.writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(updated, null, 2) + "\n");
+    return true;
+  } catch (e) {
+    return e.message;
+  }
+}