@agentprojectcontext/apx 1.77.2 → 1.78.0

package/src/core/agent/tools/handlers/set-permission-mode.js

@@ -1,6 +1,13 @@
+// Changes the super-agent's own autonomy level. This is the gate that decides
+// whether destructive tools run unattended, so the mode vocabulary must come
+// from one place: it used to be spelled out three times in this file (a Set,
+// the schema enum, and the error message), which meant adding or renaming a
+// mode silently left two of them stale.
 import { readConfig, writeConfig } from "#core/config/index.js";
+import { PERMISSION_MODES } from "#core/constants/permissions.js";
 
-const MODES = new Set(["total", "automatico", "permiso"]);
+const MODES = Object.values(PERMISSION_MODES);
+const MODE_LIST = MODES.join(", ");
 
 export default {
   name: "set_permission_mode",
@@ -8,11 +15,11 @@ export default {
     type: "function",
     function: {
       name: "set_permission_mode",
-      description: "Set APX tool permission mode in ~/.apx/config.json. Modes: total, automatico, permiso.",
+      description: `Set APX tool permission mode in ~/.apx/config.json. Modes: ${MODE_LIST}.`,
       parameters: {
         type: "object",
         properties: {
-          mode: { type: "string", enum: ["total", "automatico", "permiso"] },
+          mode: { type: "string", enum: MODES },
         },
         required: ["mode"],
       },
@@ -20,7 +27,7 @@ export default {
   },
   makeHandler: ({ requirePermission }) => async ({ mode, confirmed = false }) => {
     await requirePermission("set_permission_mode", { dangerous: true, confirmed, args: { mode } });
-    if (!MODES.has(mode)) throw new Error("mode must be total, automatico, or permiso");
+    if (!MODES.includes(mode)) throw new Error(`mode must be one of: ${MODE_LIST}`);
     const cfg = readConfig();
     cfg.super_agent = cfg.super_agent || {};
     cfg.super_agent.permission_mode = mode;

package/src/core/agent/tools/names.js

@@ -44,6 +44,10 @@ export const TOOLS = Object.freeze({
 
   // Interaction
   ASK_QUESTIONS:       "ask_questions",
+  // Synthesised by run-agent.js rather than living in handlers/ — it is how the
+  // model declares the turn is over. It was missing from this catalog, so
+  // security.js referenced it as a bare "finish" literal.
+  FINISH:              "finish",
 
   // Delegation / external
   CALL_AGENT:          "call_agent",
@@ -195,3 +199,57 @@ export const CODE_PLAN_TOOLS = Object.freeze([
  * "*" as "expose every tool the channel is otherwise allowed to see".
  */
 export const CODE_BUILD_TOOLS = "*";
+
+// ---------------------------------------------------------------------------
+// Behavioural tool sets
+//
+// These drive real user-facing protections, so they belong next to the names
+// they reference rather than as string literals scattered across the loop. The
+// side-effect set in particular was an inline `new Set([...])` inside
+// runAgent(): rename a tool there and the de-duplication below silently stops
+// working, with the only symptom being a user receiving the same Telegram
+// message three times. tests/tool-name-sets.test.js fails if any member here
+// stops being a real tool.
+// ---------------------------------------------------------------------------
+
+/**
+ * Tools that mutate the world. Weak models (Gemini especially) re-emit the
+ * same call across iterations; for these we remember the (name + args)
+ * signature and answer duplicates with a synthetic "already done" instead of
+ * running them again. Read-only tools are exempt — they are idempotent and are
+ * legitimately repeated (list_tasks before and after a change).
+ */
+export const SIDE_EFFECT_TOOLS = new Set([
+  TOOLS.SEND_TELEGRAM,
+  TOOLS.CREATE_TASK,
+  TOOLS.WRITE_FILE,
+  TOOLS.EDIT_FILE,
+  TOOLS.RUN_SHELL,
+  TOOLS.CALL_RUNTIME,
+  TOOLS.ADD_PROJECT,
+  TOOLS.SET_IDENTITY,
+]);
+
+/**
+ * Tools that only acknowledge — the turn has produced no new information for
+ * the user, so a run of them is capped (MAX_CONSECUTIVE_ACKS).
+ */
+export const ACK_ONLY_TOOLS = new Set([TOOLS.SEND_TELEGRAM]);
+
+/**
+ * Tools whose semantics REQUIRE handing control back to a human. The loop
+ * breaks after these even under a completion contract, because the task
+ * cannot advance without a reply. Without it, models under forced toolChoice
+ * ask the same question every iteration.
+ */
+export const TURN_ENDING_TOOLS = new Set([TOOLS.ASK_QUESTIONS]);
+
+/**
+ * Tools exempt from the injected `security_risk` parameter: they cannot touch
+ * anything, so grading them is noise the model has to pay for on every call.
+ */
+export const RISK_EXEMPT_TOOLS = new Set([
+  TOOLS.FINISH,
+  TOOLS.ASK_QUESTIONS,
+  TOOLS.DISCOVER_TOOLS,
+]);

package/src/core/apc/context-copy.js

@@ -1,5 +1,5 @@
 // Snapshot a project's read-aloud context — AGENTS.md + .apc/memory.md —
-// into a single labelled markdown string. Used by /deck/context/copy and
+// into a single labelled markdown string. Used by /api/deck/context/copy and
 // (potentially) any other "give me the context" surface.
 import fs from "node:fs/promises";
 import { AGENTS_MD, apcMemoryFile } from "./paths.js";

package/src/core/apc/frontmatter.js

@@ -0,0 +1,85 @@
+// YAML-ish frontmatter — one parser.
+//
+// Four copies existed, and they did not agree on which keys are legal:
+//
+//   apc/parser.js        /^([a-zA-Z_-]+):/          dashes, no digits
+//   agent/skills/loader  /^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:/  digits and dashes, strips quotes
+//   core/sessions        /^([a-zA-Z_]+):/           neither
+//   cli/commands/session /^([a-zA-Z_]+):/           neither
+//
+// That is not cosmetic duplication: a key like `route_to_agent2` or
+// `agent-slug` parsed in some code paths and vanished in others, so the same
+// file read by the CLI and by the daemon yielded different data — with no
+// error anywhere, because a non-matching line is simply skipped.
+//
+// This takes the most permissive correct behaviour (identifiers may contain
+// digits and dashes, quoted values are unquoted) and returns everything the
+// callers between them needed: the fields, the body, and where the body starts.
+//
+// Deliberately not a YAML library: the frontmatter APX writes is flat
+// `key: value` and staying strict about that keeps the format predictable for
+// the models that also read these files.
+
+const KEY_VALUE = /^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$/;
+
+function unquote(value) {
+  const v = value.trim();
+  if (v.length >= 2 && ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))) {
+    return v.slice(1, -1);
+  }
+  return v;
+}
+
+/**
+ * Parse leading `---` frontmatter.
+ *
+ * @param {string} text
+ * @returns {{ fm: Record<string,string>, body: string, bodyStart: number }}
+ *   `fm` is `{}` when there is no frontmatter; `body` is then the whole text
+ *   and `bodyStart` is 0.
+ */
+export function parseFrontmatter(text) {
+  const raw = String(text ?? "");
+  // Accept both "---\n" and a bare leading "---" (the skills loader allowed
+  // the latter; session files always write the former).
+  if (!raw.startsWith("---")) return { fm: {}, body: raw, bodyStart: 0 };
+
+  const openLen = raw.startsWith("---\n") ? 4 : 3;
+  const end = raw.indexOf("\n---", openLen - 1);
+  if (end === -1) return { fm: {}, body: raw, bodyStart: 0 };
+
+  const fm = {};
+  for (const line of raw.slice(openLen, end).split("\n")) {
+    const m = line.match(KEY_VALUE);
+    if (m) fm[m[1]] = unquote(m[2]);
+  }
+
+  // The closing fence is followed by a newline, and authors conventionally
+  // leave a blank line after it — consume both so `body` starts at content.
+  const bodyStart = end + 4;
+  return { fm, body: raw.slice(bodyStart).replace(/^\n+/, ""), bodyStart };
+}
+
+/** Just the fields, for callers that don't need the body. */
+export function parseFrontmatterFields(text) {
+  return parseFrontmatter(text).fm;
+}
+
+/**
+ * Set or replace one field in place, preserving the rest of the file byte for
+ * byte. Returns the text unchanged when there is no frontmatter to edit.
+ */
+export function setFrontmatterField(text, field, value) {
+  const raw = String(text ?? "");
+  if (!raw.startsWith("---\n")) return raw;
+  const end = raw.indexOf("\n---", 4);
+  if (end === -1) return raw;
+
+  const lines = raw.slice(4, end).split("\n");
+  const idx = lines.findIndex((l) => l.match(KEY_VALUE)?.[1] === field);
+  const entry = `${field}: ${value}`;
+  if (idx >= 0) lines[idx] = entry;
+  else lines.push(entry);
+
+  return `---\n${lines.join("\n")}${raw.slice(end)}`;
+}

package/src/core/apc/parser.js

@@ -1,6 +1,7 @@
 // Core parsers for APC — pure ESM, no deps.
 import fs from "node:fs";
 import path from "node:path";
+import { AGENT_VAULT_DIR } from "../config/paths.js";
 import {
   apcAgentsDir,
   apcAgentFile,
@@ -124,12 +125,13 @@ export function readAgentsFromDir(root) {
 // if it's a bundled slug, deletes the user file otherwise.
 // ---------------------------------------------------------------------------
 
-import os from "node:os";
 import { fileURLToPath } from "node:url";
+import { parseFrontmatterFields } from "./frontmatter.js";
+import { readJson } from "#core/util/json-file.js";
 
 const __parserDir = path.dirname(fileURLToPath(import.meta.url));
 
-export const VAULT_DIR = path.join(os.homedir(), ".apx", "agents");
+export const VAULT_DIR = AGENT_VAULT_DIR;
 export const BUNDLED_VAULT_DIR = path.resolve(__parserDir, "../../../assets/agent-vault-defaults");
 export const VAULT_TOMBSTONE_PATH = path.join(VAULT_DIR, ".removed.json");
 
@@ -144,10 +146,8 @@ function readVaultDirRaw(dir) {
 
 export function readVaultTombstones() {
   if (!fs.existsSync(VAULT_TOMBSTONE_PATH)) return new Set();
-  try {
-    const raw = JSON.parse(fs.readFileSync(VAULT_TOMBSTONE_PATH, "utf8"));
-    return new Set(Array.isArray(raw.slugs) ? raw.slugs : []);
-  } catch { return new Set(); }
+  const raw = readJson(VAULT_TOMBSTONE_PATH, {});
+  return new Set(Array.isArray(raw?.slugs) ? raw.slugs : []);
 }
 
 export function writeVaultTombstones(slugs) {
@@ -212,10 +212,7 @@ export { readVaultAgent };
 export function importedVaultSlugs(root) {
   const p = apcProjectFile(root);
   if (!fs.existsSync(p)) return [];
-  try {
-    const cfg = JSON.parse(fs.readFileSync(p, "utf8"));
-    return cfg.agents?.imported ?? [];
-  } catch { return []; }
+  return readJson(p, {})?.agents?.imported ?? [];
 }
 
 // Primary entry point.
@@ -273,14 +270,5 @@ export function findApfRoot(start = process.cwd()) {
 // Session / conversation frontmatter
 // ---------------------------------------------------------------------------
 
-export function parseSessionFrontmatter(text) {
-  if (!text.startsWith("---\n")) return {};
-  const end = text.indexOf("\n---", 4);
-  if (end === -1) return {};
-  const out = {};
-  for (const line of text.slice(4, end).split("\n")) {
-    const m = line.match(/^([a-zA-Z_-]+):\s*(.*)$/);
-    if (m) out[m[1]] = m[2].trim();
-  }
-  return out;
-}
+// Kept as the public name; the implementation is the shared parser.
+export const parseSessionFrontmatter = parseFrontmatterFields;

package/src/core/apc/paths.js

@@ -9,16 +9,16 @@ import fs from "node:fs";
 import path from "node:path";
 
 // Raw names — exported for the rare caller that needs to glob/match by name.
-export const APC_DIR = ".apc";
-export const APC_PROJECT_FILE = "project.json";
-export const APC_PROJECT_CONFIG_FILE = "config.json";
-export const APC_PROJECT_MEMORY_FILE = "memory.md";
-export const APC_AGENTS_DIR = "agents";
-export const APC_SKILLS_DIR = "skills";
+const APC_DIR = ".apc";
+const APC_PROJECT_FILE = "project.json";
+const APC_PROJECT_CONFIG_FILE = "config.json";
+const APC_PROJECT_MEMORY_FILE = "memory.md";
+const APC_AGENTS_DIR = "agents";
+const APC_SKILLS_DIR = "skills";
 export const APC_COMMANDS_DIR = "commands";
 export const APC_NOTES_DIR = "notes";
-export const APC_MCPS_FILE = "mcps.json";
-export const APC_ORGANIZATION_FILE = "organization.json";
+const APC_MCPS_FILE = "mcps.json";
+const APC_ORGANIZATION_FILE = "organization.json";
 export const APC_REMOVED_FILE = ".removed.json";
 export const AGENTS_MD = "AGENTS.md";
 

package/src/core/apc/scaffold.js

@@ -18,6 +18,7 @@ import {
   apcAgentFile,
   agentsMdFile,
 } from "./paths.js";
+import { readJson } from "#core/util/json-file.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Now under src/core/apc/ — one more "../" to escape than before.
@@ -431,8 +432,8 @@ function writeMigrateMd(apfDir, found) {
 export function getOrCreateApxId(root) {
   const p = apcProjectFile(root);
   if (!fs.existsSync(p)) return null;
-  let cfg;
-  try { cfg = JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
+  const cfg = readJson(p, null);
+  if (!cfg) return null;
   if (cfg.apx_id) return cfg.apx_id;
   const apxId = crypto.randomUUID().replace(/-/g, "").slice(0, 12);
   console.log(`[apx] Generating new stable ID ${apxId} for project at ${root}`);
@@ -490,7 +491,7 @@ export function initApf(directory, { name } = {}) {
   return { root, agentsMd, projectJson, pendingMigration: scattered };
 }
 
-export function ensureAgentDir(root, slug) {
+export function ensureAgentDir(root, _slug) {
   fs.mkdirSync(apcAgentsDir(root), { recursive: true });
   return apcAgentsDir(root);
 }
@@ -587,7 +588,7 @@ export function restoreVaultAgent(slug) {
 export function addImportedAgent(root, slug) {
   const p = apcProjectFile(root);
   let cfg = {};
-  try { cfg = JSON.parse(fs.readFileSync(p, "utf8")); } catch {}
+  cfg = readJson(p, {});
   if (!cfg.agents) cfg.agents = {};
   if (!cfg.agents.imported) cfg.agents.imported = [];
   if (!cfg.agents.imported.includes(slug)) cfg.agents.imported.push(slug);

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

@@ -0,0 +1,201 @@
+// Telegram identity: channels, contacts and roles.
+//
+// This is channel domain, not configuration plumbing — it happened to live in
+// core/config/index.js because the data is stored in the global config file.
+// That made the config module 711 lines, half of them Telegram, and forced
+// host/daemon/api/telegram.js to import 13 symbols from "the config module".
+//
+// The shapes:
+//   cfg.telegram.channels[] — { name, bot_token, chat_id, route_to_agent,
+//     project, respond_with_engine, poll_interval_ms, owner_user_id }
+//   cfg.telegram.contacts[] — the global roster, keyed by Telegram user_id.
+//     Identity is per-person and the same across every chat; a channel's
+//     owner_user_id only marks who owns *that* channel.
+//   cfg.telegram.roles    — role -> capabilities. "owner" is implicit (full),
+//     "guest" is the default for unknown senders (no tools).
+//
+// Re-exported from core/config/index.js so existing import sites keep working.
+import { writeConfig } from "../../config/index.js";
+
+// ── Telegram channels (multi-channel mode) ──────────────────────────────────
+// Each entry in cfg.telegram.channels[] is { name, bot_token, chat_id,
+// route_to_agent, project, respond_with_engine, poll_interval_ms }.
+// These helpers keep the array shape stable for the CLI and the daemon API.
+
+const CHANNEL_FIELDS = [
+  "name",
+  "bot_token",
+  "chat_id",
+  "route_to_agent",
+  "project",
+  "respond_with_engine",
+  "poll_interval_ms",
+  "owner_user_id",
+];
+
+function ensureChannelsArray(cfg) {
+  cfg.telegram = cfg.telegram || {};
+  if (!Array.isArray(cfg.telegram.channels)) cfg.telegram.channels = [];
+  return cfg.telegram.channels;
+}
+
+export function listTelegramChannels(cfg) {
+  return ensureChannelsArray(cfg).slice();
+}
+
+export function findTelegramChannel(cfg, name) {
+  return ensureChannelsArray(cfg).find((c) => c.name === name) || null;
+}
+
+// Create-or-patch a channel by name. `patch` is a partial channel object;
+// unknown keys are dropped. Returns { created, channel }.
+export function upsertTelegramChannel(cfg, name, patch = {}) {
+  if (!name || typeof name !== "string")
+    throw new Error("upsertTelegramChannel: name required");
+  const channels = ensureChannelsArray(cfg);
+  let entry = channels.find((c) => c.name === name);
+  const created = !entry;
+  if (!entry) {
+    entry = { name };
+    channels.push(entry);
+  }
+  for (const k of CHANNEL_FIELDS) {
+    if (k === "name") continue;
+    if (patch[k] !== undefined) entry[k] = patch[k];
+  }
+  // Default respond_with_engine to true on create.
+  if (created && entry.respond_with_engine === undefined) {
+    entry.respond_with_engine = true;
+  }
+  writeConfig(cfg);
+  return { created, channel: entry };
+}
+
+export function removeTelegramChannel(cfg, name) {
+  const channels = ensureChannelsArray(cfg);
+  const before = channels.length;
+  cfg.telegram.channels = channels.filter((c) => c.name !== name);
+  const removed = before - cfg.telegram.channels.length;
+  if (removed > 0) {
+    // Explicit user-initiated removal — bypass the credential-loss guard
+    // so the write goes through even when this empties the array.
+    cfg._allowClear = true;
+    writeConfig(cfg);
+  }
+  return { removed };
+}
+
+// Clear specific optional fields on a channel (project, route_to_agent, …).
+// Returns { channel } or null when no such channel.
+export function unsetTelegramChannelFields(cfg, name, fields = []) {
+  const ch = findTelegramChannel(cfg, name);
+  if (!ch) return null;
+  let mutated = false;
+  for (const f of fields) {
+    if (!CHANNEL_FIELDS.includes(f) || f === "name") continue;
+    if (f in ch) {
+      delete ch[f];
+      mutated = true;
+    }
+  }
+  if (mutated) writeConfig(cfg);
+  return { channel: ch };
+}
+
+// ── Telegram contacts (global roster, keyed by user_id) ─────────────────────
+// Identity of a person is global; the per-channel owner_user_id only marks who
+// owns a given channel. Role lives on the contact (global), per the chosen
+// design — owner_user_id overrides it to "owner" for that channel only.
+
+const CONTACT_FIELDS = [
+  "user_id",
+  "name",
+  "username",
+  "role",
+  "note",
+  "first_seen",
+  "last_seen",
+];
+
+function ensureContactsArray(cfg) {
+  cfg.telegram = cfg.telegram || {};
+  if (!Array.isArray(cfg.telegram.contacts)) cfg.telegram.contacts = [];
+  return cfg.telegram.contacts;
+}
+
+export function listContacts(cfg) {
+  return ensureContactsArray(cfg).slice();
+}
+
+export function findContact(cfg, userId) {
+  if (userId == null) return null;
+  return (
+    ensureContactsArray(cfg).find((c) => String(c.user_id) === String(userId)) ||
+    null
+  );
+}
+
+// Create-or-patch a contact by user_id. Unknown keys are dropped.
+export function upsertContact(cfg, userId, patch = {}, { persist = true } = {}) {
+  if (userId == null) throw new Error("upsertContact: user_id required");
+  const contacts = ensureContactsArray(cfg);
+  let entry = contacts.find((c) => String(c.user_id) === String(userId));
+  const created = !entry;
+  if (!entry) {
+    entry = { user_id: userId };
+    contacts.push(entry);
+  }
+  for (const k of CONTACT_FIELDS) {
+    if (k === "user_id") continue;
+    if (patch[k] !== undefined) entry[k] = patch[k];
+  }
+  if (persist) writeConfig(cfg);
+  return { created, contact: entry };
+}
+
+export function setContactRole(cfg, userId, role) {
+  const { contact } = upsertContact(cfg, userId, { role });
+  return contact;
+}
+
+export function removeContact(cfg, userId) {
+  const contacts = ensureContactsArray(cfg);
+  const before = contacts.length;
+  cfg.telegram.contacts = contacts.filter(
+    (c) => String(c.user_id) !== String(userId)
+  );
+  const removed = before - cfg.telegram.contacts.length;
+  if (removed > 0) writeConfig(cfg);
+  return { removed };
+}
+
+export function setChannelOwner(cfg, channelName, userId) {
+  return upsertTelegramChannel(cfg, channelName, { owner_user_id: userId });
+}
+
+// ── Telegram roles (role → capability map) ──────────────────────────────────
+
+export function listRoles(cfg) {
+  cfg.telegram = cfg.telegram || {};
+  return { ...(cfg.telegram.roles || {}) };
+}
+
+export function setRole(cfg, name, def) {
+  if (!name || typeof name !== "string") throw new Error("setRole: name required");
+  cfg.telegram = cfg.telegram || {};
+  cfg.telegram.roles = cfg.telegram.roles || {};
+  cfg.telegram.roles[name] = def;
+  writeConfig(cfg);
+  return cfg.telegram.roles[name];
+}
+
+export function removeRole(cfg, name) {
+  cfg.telegram = cfg.telegram || {};
+  if (!cfg.telegram.roles || !(name in cfg.telegram.roles)) return { removed: 0 };
+  if (name === "owner" || name === "guest") {
+    throw new Error(`role "${name}" is built-in and cannot be removed`);
+  }
+  delete cfg.telegram.roles[name];
+  writeConfig(cfg);
+  return { removed: 1 };
+}