@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/core/agent/tools/handlers/create-agent.js

@@ -0,0 +1,68 @@
+import { createAgent } from "#core/apc/agent-write.js";
+import { readAgents } from "#core/apc/parser.js";
+import { projectMeta, resolveProject } from "../helpers.js";
+
+// Create a project agent — including its system prompt — in one call. This is
+// what the super-agent should reach for instead of shelling out to
+// `apx agent add` (which is awkward for a long, multi-line prompt) and then
+// hand-writing the `.md` when the agent comes out body-less. `system` is
+// required here on purpose: an agent without instructions cannot do anything.
+export default {
+  name: "create_agent",
+  schema: {
+    type: "function",
+    function: {
+      name: "create_agent",
+      description:
+        "Create a project agent (a specialist persona) WITH its system prompt in one step. Use this — not run_shell/apx agent add, and never write_file on the .md — whenever the user asks you to make a new agent. `system` is the agent's full instructions (its reason to exist) and is required. Omit `tools` unless you deliberately want to narrow the agent (an undeclared tools field means the broad default). Project resolves by id/name/path; omit or use 'default' for the super-agent workspace. Call list_agents first if unsure what exists.",
+      parameters: {
+        type: "object",
+        required: ["slug", "system"],
+        properties: {
+          project:     { type: "string", description: "Project id, name or path. Omit or 'default' for ~/.apx/projects/default." },
+          slug:        { type: "string", description: "Lowercase id: starts with a letter, then letters/digits/-/_ (e.g. golf-coach)." },
+          system:      { type: "string", description: "The agent's full system prompt / instructions. REQUIRED — this is what the agent does, how, and what it never does." },
+          name:        { type: "string", description: "Display name (optional; defaults to a title-cased slug)." },
+          role:        { type: "string", description: "One-line role, e.g. 'Golf coach'." },
+          description: { type: "string", description: "One line of metadata shown in listings. NOT a substitute for system." },
+          model:       { type: "string", description: "Optional per-agent model override (else follows the project/global default)." },
+          language:    { type: "string", description: "Default language code, e.g. 'es'." },
+          skills:      { type: "array", items: { type: "string" }, description: "Skill slugs to attach (e.g. ['golf-lvl-2'])." },
+          tools:       { type: "array", items: { type: "string" }, description: "Optional allowlist that NARROWS the agent. Omit for the broad default." },
+          area:        { type: "string", description: "Org area slug/name (optional; call list_agents/org first)." },
+          type:        { type: "string", description: "Agent typology (e.g. specialist, orchestrator)." },
+          emoji:       { type: "string", description: "Optional emoji badge." },
+          icon:        { type: "string", description: "Optional avatar blob key; one is picked if omitted." },
+          is_master:   { type: "boolean", description: "Mark as a master/primary agent of the project." },
+          parent:      { type: "string", description: "Parent agent slug, for hierarchy." },
+          autonomy:    { type: "string", description: "Per-agent autonomy: total | automatico | permiso." },
+        },
+      },
+    },
+  },
+  makeHandler: ({ projects, requirePermission }) => async (args = {}) => {
+    const { project, slug } = args;
+    await requirePermission("create_agent", { dangerous: true, args: { agent: slug, project } });
+    let p;
+    try {
+      p = resolveProject(projects, project || "default");
+    } catch (e) {
+      return { error: e.message };
+    }
+    try {
+      createAgent(p, args, { requireSystem: true });
+      projects.rebuild(p.id);
+      const created = readAgents(p.path).find((a) => a.slug === slug);
+      return {
+        ok: true,
+        agent: created?.slug || slug,
+        project: projectMeta(projects, p),
+        role: created?.fields?.Role || args.role || null,
+        skills: created?.fields?.Skills || args.skills || [],
+        hint: "Agent created with its system prompt. Seed its memory with write_agent_memory if it should track progress across runs.",
+      };
+    } catch (e) {
+      return { error: e.message };
+    }
+  },
+};

package/src/core/agent/tools/handlers/create-task.js

@@ -14,16 +14,46 @@ export default {
         properties: {
           project: { type: "string", description: "Project id, name, or path." },
           title:   { type: "string", description: "Short imperative title for the task." },
-          body:    { type: "string", description: "Optional longer description." },
+          parent: {
+            type: "string",
+            description:
+              "Optional id of a parent task, making this one a SUBTASK of it. Use it to split a task " +
+              "that is really several: create the parent (or reuse the existing one) and add a subtask " +
+              "per real unit of work, so each can be assigned, moved and closed on its own.",
+          },
+          description: {
+            type: "string",
+            description:
+              "What the OWNER has to do, in their words. Write this for a person reading a to-do list, " +
+              "not for a model: no prompt scaffolding, no 'you are an agent that…'. Fill it for anything " +
+              "the owner will do themselves — which is most tasks.",
+          },
+          body: {
+            type: "string",
+            description:
+              "The prompt an AGENT receives if it runs this task. Only fill it when the task is meant to " +
+              "be executed by an agent. Leave it empty for a normal to-do — a prompt in place of a " +
+              "description is what makes a task list unreadable to its owner.",
+          },
           tags:    { type: "array", items: { type: "string" }, description: "Optional tags." },
           due:     { type: "string", description: "Optional ISO date (YYYY-MM-DD) the task is due by." },
-          agent:   { type: "string", description: "Optional agent slug responsible for the task." },
+          agent:   { type: "string", description: "Responsible actor: an agent slug, or owner/human for the human owner." },
+          priority: {
+            type: "string",
+            enum: ["low", "normal", "high", "urgent"],
+            description: "Task priority. Defaults to normal.",
+          },
+          reminder_frequency: {
+            type: "string",
+            enum: ["none", "once", "daily", "weekly"],
+            description: "How often the owner wants a reminder recorded for this task. Defaults to none.",
+          },
           source:  { type: "string", description: "Where the task came from (telegram, desktop, …). Defaults to the calling channel." },
         },
       },
     },
   },
-  makeHandler: ({ projects }) => async ({ project: ref, title, body, tags, due, agent, source }) => {
+  makeHandler: ({ projects }) => async ({ project: ref, title, description, body, tags, due, agent, priority, reminder_frequency, source, parent }) => {
     if (!ref) return { error: "project required" };
     if (!title) return { error: "title required" };
     const all = projects.list();
@@ -36,10 +66,14 @@ export default {
     if (!proj) return { error: `project storage not loaded: ${ref}` };
     const task = createTask(proj.storagePath, {
       title,
+      parent: parent || null,
+      description: description || null,
       body: body || null,
       tags: Array.isArray(tags) ? tags : [],
       due: due || null,
       agent: agent || null,
+      priority,
+      reminder_frequency,
       source: source || "super-agent",
     });
     return {
@@ -47,6 +81,10 @@ export default {
       project: { id: proj.id, name: proj.name },
       title: task.title,
       state: task.state,
+      ...(task.parent ? { parent: task.parent } : {}),
+      agent: task.agent,
+      priority: task.priority,
+      reminder_frequency: task.reminder_frequency,
     };
   },
 };

package/src/core/agent/tools/handlers/import-agent.js

@@ -1,6 +1,4 @@
-import fs from "node:fs";
-import path from "node:path";
-import { readVaultAgents, VAULT_DIR } from "#core/apc/parser.js";
+import { readVaultAgents, vaultAgentFile } from "#core/apc/parser.js";
 import { addImportedAgent, ensureAgentDir } from "#core/apc/scaffold.js";
 import { ensureAgentRuntimeDir } from "#core/agent/memory.js";
 import { projectMeta, resolveProject } from "../helpers.js";
@@ -26,8 +24,10 @@ export default {
     await requirePermission("import_agent", { dangerous: true, confirmed, args: { agent: slug } });
     if (!slug) throw new Error("import_agent: agent required");
 
-    const vaultPath = path.join(VAULT_DIR, `${slug}.md`);
-    if (!fs.existsSync(vaultPath)) {
+    // Layered lookup (user file → bundled default). A raw path into the user
+    // vault would reject every bundled agent this same error message lists.
+    const vaultPath = vaultAgentFile(slug);
+    if (!vaultPath) {
       const available = readVaultAgents().map((a) => a.slug).join(", ") || "(none)";
       throw new Error(`agent "${slug}" not found in vault. Available: ${available}`);
     }

package/src/core/agent/tools/handlers/list-mcp-tools.js

@@ -0,0 +1,83 @@
+import { resolveProject } from "../helpers.js";
+
+// The catalog of ONE MCP server. `list_mcps` names the servers; without this
+// the model knew a server called "postbean" existed and had no way to learn
+// what it could ask it for. In practice it guessed tool names, got
+// `Tool [tools] not found`, and then went reading the server's own source to
+// reverse-engineer the contract — a dozen shell calls to recover something the
+// protocol hands over in one request.
+//
+// Schemas are returned trimmed by default: names + one-line descriptions +
+// required args are enough to pick a tool, and full JSON Schemas for a large
+// server would swamp a chat turn. Ask for `detail: "full"` once the tool is
+// chosen and the exact argument shape matters.
+function oneLine(desc = "", cap = 200) {
+  const flat = String(desc).replace(/\s+/g, " ").trim();
+  return flat.length <= cap ? flat : flat.slice(0, cap - 1) + "…";
+}
+
+function briefTool(t) {
+  const schema = t.inputSchema || t.input_schema || {};
+  const props = schema.properties && typeof schema.properties === "object" ? schema.properties : {};
+  return {
+    name: t.name,
+    description: oneLine(t.description),
+    args: Object.keys(props),
+    required: Array.isArray(schema.required) ? schema.required : [],
+  };
+}
+
+export default {
+  name: "list_mcp_tools",
+  schema: {
+    type: "function",
+    function: {
+      name: "list_mcp_tools",
+      description:
+        "List the tools an MCP server exposes, with their arguments. Call this " +
+        "BEFORE call_mcp on a server you have not used this turn — it is how you " +
+        "learn the tool names and argument shapes. Never guess an MCP tool name " +
+        "and never read the server's source to find out; ask the server.",
+      parameters: {
+        type: "object",
+        properties: {
+          mcp: { type: "string", description: "MCP server name (from list_mcps)." },
+          project: { type: "string", description: "Project id/name/path the MCP is registered in. Omit for default." },
+          detail: {
+            type: "string",
+            enum: ["brief", "full"],
+            description: "brief (default) = names, descriptions, arg names. full = complete JSON Schemas.",
+          },
+        },
+        required: ["mcp"],
+      },
+    },
+  },
+  makeHandler: ({ projects, registries }) => async ({ mcp, project, detail } = {}) => {
+    if (!mcp) return { error: "list_mcp_tools: mcp is required" };
+    if (!registries) return { error: "MCP registry unavailable" };
+    const p = resolveProject(projects, project);
+    const registry = registries.for ? registries.for(p) : registries.ensure(p);
+
+    const known = registry.list?.() || [];
+    if (known.length && !known.some((m) => m.name === mcp)) {
+      return {
+        error: `MCP "${mcp}" is not registered here`,
+        available: known.map((m) => m.name),
+      };
+    }
+
+    let result;
+    try {
+      result = await registry.listTools(mcp);
+    } catch (e) {
+      return { error: `MCP "${mcp}" tools/list failed: ${e.message}` };
+    }
+    const tools = Array.isArray(result?.tools) ? result.tools : [];
+    return {
+      mcp,
+      count: tools.length,
+      tools: detail === "full" ? tools : tools.map(briefTool),
+    };
+  },
+};

package/src/core/agent/tools/handlers/list-routines.js

@@ -0,0 +1,46 @@
+import { listRoutines } from "#core/stores/routines.js";
+import { resolveProject } from "../helpers.js";
+
+// The routines a project has, and how their last run went. Pairs with
+// run_routine: this answers "what can I run / did the 08:00 one fire", which
+// otherwise took a shell round-trip through the CLI.
+export default {
+  name: "list_routines",
+  schema: {
+    type: "function",
+    function: {
+      name: "list_routines",
+      description:
+        "List a project's routines: name, kind, schedule, whether they are enabled, " +
+        "and how the last run went. Use before run_routine, or to answer 'did the " +
+        "cron run', 'qué rutinas tiene', 'por qué no corrió'.",
+      parameters: {
+        type: "object",
+        properties: {
+          project: { type: "string", description: "Project id, name or path. Omit for the default project." },
+        },
+      },
+    },
+  },
+  makeHandler: ({ projects }) => async ({ project } = {}) => {
+    const p = resolveProject(projects, project);
+    if (!p) return { error: `project not found: ${project}` };
+    return {
+      project: p.name || p.path,
+      routines: listRoutines(p.storagePath).map((r) => ({
+        name: r.name,
+        kind: r.kind,
+        schedule: r.schedule,
+        enabled: !!r.enabled,
+        agent: r.spec?.agent || undefined,
+        // An empty list means "no override — the agent's own tools"; say so
+        // rather than printing [] and inviting the old misreading.
+        tools: r.allowed_tools?.length ? r.allowed_tools.length : "agent default",
+        last_run_at: r.last_run_at,
+        last_status: r.last_status,
+        ...(r.last_error ? { last_error: String(r.last_error).slice(0, 300) } : {}),
+        next_run_at: r.next_run_at,
+      })),
+    };
+  },
+};

package/src/core/agent/tools/handlers/list-tasks.js

@@ -33,14 +33,16 @@ export default {
           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." },
+          parent:     { type: "string", description: "Return only the SUBTASKS of this task id. Pass an empty string for top-level tasks only." },
           limit:      { type: "number", description: "Cap on rows returned. Default 100." },
         },
       },
     },
   },
   makeHandler: ({ projects }) => async (args = {}) => {
-    const { project: ref, state, status, tag, agent, due_before, limit } = args;
+    const { project: ref, state, status, tag, agent, due_before, limit, parent } = args;
     const opts = {
+      ...(parent !== undefined ? { parent } : {}),
       state: state || undefined,
       status: status || undefined,
       tag: tag || undefined,
@@ -86,6 +88,11 @@ function compact(t) {
     due: t.due,
     agent: t.agent,
     created_at: t.created_at,
+    // Only when they say something — a "0 subtasks, 0 comments" pair on every
+    // row is prompt tokens spent to communicate nothing.
+    ...(t.subtask_count ? { subtasks: `${t.subtask_done}/${t.subtask_count}` } : {}),
+    ...(t.comment_count ? { comments: t.comment_count } : {}),
+    ...(t.parent ? { parent: t.parent } : {}),
     ...(t.project_name ? { project: t.project_name } : {}),
   };
 }

package/src/core/agent/tools/handlers/mark-commitment.js

@@ -0,0 +1,57 @@
+import {
+  keepCommitment, missCommitment, dropCommitment, renegotiateCommitment,
+} from "#core/stores/commitments.js";
+import { missingArg, projectMeta, resolveProject } from "../helpers.js";
+
+// Close out a commitment. The sibling of record_commitment: a promise you can
+// record but never resolve is a promise that silently rots. kept/missed carry
+// the relationship; drop retracts a mis-filed one; renegotiate needs a new date.
+export default {
+  name: "mark_commitment",
+  schema: {
+    type: "function",
+    function: {
+      name: "mark_commitment",
+      description:
+        "Resolve a commitment recorded with record_commitment: kept (you delivered), missed (the date passed and it didn't happen), drop (it was filed by mistake — not the same as missed), or renegotiate (a new date agreed with them, which requires `due`). Use after list_commitments.",
+      parameters: {
+        type: "object",
+        required: ["commitment", "action"],
+        properties: {
+          project:    { type: "string", description: "Project id, name or path. Omit or 'default' for ~/.apx/projects/default." },
+          commitment: { type: "string", description: "Commitment id or a ≥3-char unique prefix (from list_commitments)." },
+          action:     { type: "string", enum: ["kept", "missed", "drop", "renegotiate"], description: "kept | missed | drop | renegotiate." },
+          due:        { type: "string", description: "New due date (ISO). REQUIRED when action is 'renegotiate'." },
+          note:       { type: "string", description: "Optional note recorded with the change." },
+        },
+      },
+    },
+  },
+  makeHandler: ({ projects, requirePermission }) => async (args = {}) => {
+    const { project, commitment, action, due, note } = args;
+    await requirePermission("mark_commitment", { dangerous: true, args: { commitment, action } });
+    // Same trap as complete_task: list_commitments returns `id`, this takes
+    // `commitment`. Say which, rather than only that one is missing.
+    if (!commitment) return missingArg("mark_commitment", "commitment", { required: ["commitment", "action"], optional: ["project", "due", "note"] }, args);
+    let p;
+    try {
+      p = resolveProject(projects, project || "default");
+    } catch (e) {
+      return { error: e.message };
+    }
+    try {
+      let result;
+      if (action === "kept") result = keepCommitment(p.storagePath, commitment, note || null);
+      else if (action === "missed") result = missCommitment(p.storagePath, commitment, note || null);
+      else if (action === "drop") result = dropCommitment(p.storagePath, commitment, note || null);
+      else if (action === "renegotiate") {
+        if (!due) return { error: "due required when action is 'renegotiate'" };
+        result = renegotiateCommitment(p.storagePath, commitment, due, note || null);
+      } else return { error: `unknown action "${action}" (use kept|missed|drop|renegotiate)` };
+      if (!result) return { error: `commitment not found: ${commitment}` };
+      return { ok: true, action, project: projectMeta(projects, p), commitment: result };
+    } catch (e) {
+      return { error: e.message };
+    }
+  },
+};

package/src/core/agent/tools/handlers/read-skill.js

@@ -0,0 +1,64 @@
+// read_skill — pull ONE section of a skill on demand, instead of carrying the
+// whole skill in the prompt. The system prompt shows a lazy skill's outline
+// (its section titles); this fetches the body of the section the agent names.
+// Called with no section, it returns the outline + image manifest so the agent
+// can see what it can ask for.
+import { loadSkill } from "#core/agent/skills/loader.js";
+import { splitSkillSections, skillOutline, pickSkillSection } from "#core/agent/skills/sections.js";
+import { readSkillMedia } from "#core/agent/skills/media.js";
+
+export default {
+  name: "read_skill",
+  schema: {
+    type: "function",
+    function: {
+      name: "read_skill",
+      description:
+        "Read one section of a skill loaded on demand (progressive disclosure). Pass the skill slug and a section title or number to get that section's text; omit the section to get the list of sections and images. Use this for a skill the system prompt showed as '(loaded on demand)'.",
+      parameters: {
+        type: "object",
+        properties: {
+          skill: { type: "string", description: "skill slug, e.g. \"golf-lvl-2\"" },
+          section: {
+            type: "string",
+            description: "section title (fuzzy) or number, e.g. \"2\" or \"Técnica del Swing\". Omit to list sections.",
+          },
+          project_path: { type: "string", description: "optional project root for project-scoped skills" },
+        },
+        required: ["skill"],
+      },
+    },
+  },
+  makeHandler: (ctx = {}) => ({ skill, section, project_path } = {}) => {
+    if (!skill) throw new Error("read_skill: skill required");
+    const projectPath = project_path || ctx?.channelMeta?.projectPath || undefined;
+    let loaded;
+    try {
+      loaded = loadSkill(skill, { projectPath });
+    } catch (e) {
+      return { error: e?.message || `skill "${skill}" not found` };
+    }
+    const body = String(loaded.body || "").trim();
+    const media = readSkillMedia(loaded).filter((m) => m.exists);
+
+    if (!section || !String(section).trim()) {
+      return {
+        skill: loaded.slug,
+        description: loaded.description || "",
+        sections: skillOutline(body),
+        all_headings: splitSkillSections(body).filter((s) => s.title).map((s) => s.title),
+        images: media.map((m) => ({ id: m.id, caption: m.caption })),
+        hint: "Call read_skill again with { section: \"<title or number>\" } to read one.",
+      };
+    }
+
+    const found = pickSkillSection(body, section);
+    if (!found) {
+      return {
+        error: `no section matching "${section}" in ${loaded.slug}`,
+        sections: skillOutline(body),
+      };
+    }
+    return { skill: loaded.slug, section: found.title, body: found.text };
+  },
+};

package/src/core/agent/tools/handlers/remember-routine.js

@@ -1,4 +1,4 @@
-import { appendRoutineMemory } from "#core/stores/routine-memory.js";
+import { appendRoutineMemory, resolveRoutineStorage } from "#core/stores/routine-memory.js";
 
 /**
  * A routine writing to its OWN memory.
@@ -60,13 +60,7 @@ export default {
     }
 
     // The routine's project storage, never a model-supplied path.
-    const projectPath = channelMeta?.projectPath || "";
-    let storagePath = "";
-    for (const entry of projects?.list?.() || []) {
-      if (projectPath && entry.path !== projectPath) continue;
-      storagePath = projects.get(entry.id)?.storagePath || "";
-      if (storagePath) break;
-    }
+    const storagePath = resolveRoutineStorage(projects, channelMeta?.projectPath || "");
     if (!storagePath) return { error: "could not resolve this routine's storage" };
 
     try {

package/src/core/agent/tools/handlers/remember.js

@@ -1,7 +1,34 @@
 import { appendSelfMemory } from "#core/agent/self-memory.js";
+import { appendProjectLocalMemory } from "#core/stores/project-memory.js";
+import { appendRoutineMemory, resolveRoutineStorage } from "#core/stores/routine-memory.js";
+import { looksDurable } from "#core/memory/consolidate.js";
+import { resolveProject, projectMeta } from "../helpers.js";
+import { CHANNELS } from "#core/constants/channels.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.
+// Write a durable note into YOUR OWN notebook (~/.apx/memory.md) — or, with
+// `project`, into that project's LOCAL memory (~/.apx/projects/<apxId>/memory.md).
+// This is durable memory, not a project task and not an agent memory.
+//
+// The `project` scope exists because a fact about ONE repo does not belong in a
+// notebook that ships in every prompt on every channel, and because without it
+// the model had no way at all to write project memory: asked to record what a
+// dozen projects were, it invented a `MEMORY.md` at each repo root, which the
+// Memories screen does not read and the RAG indexer does not see.
+//
+// It writes the LOCAL file, never the repo's `.apc/memory.md`. An automatic
+// writer pointed at a committed file is how a token pasted into a chat ends up
+// in a public git history — APC keeps private runtime memory out of `.apc/` for
+// exactly that reason, and reserves `.apc/memory.md` for facts a person read and
+// judged team-safe. Promotion from local to committed is the owner's move, made
+// in the Memories screen, which shows both files side by side.
+//
+// Routine runs get one extra judgement: the notebook ships in every prompt on
+// every channel forever, and a scheduled routine calling `remember` each run
+// ("today's weather is -8°C", "the routine ran and sent a message") turned it
+// into a daily log — sixty days of weather is zero facts. So inside a routine,
+// a note that does not read as a durable owner-level fact (looksDurable, the
+// same judgement consolidation applies) is diverted to that routine's own
+// memory instead of the global notebook. Durable facts still land globally.
 export default {
   name: "remember",
   schema: {
@@ -9,7 +36,7 @@ export default {
     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.",
+        "Save a durable fact. Without `project` it goes to your cross-channel notebook (~/.apx/memory.md) so you still know it in future sessions AND on other channels (telegram, web, deck, voice); with `project` it goes to THAT project's local memory, which its Memories screen shows. Never create a memory file yourself — this tool is the only correct way to write one, and it deliberately writes the project's LOCAL file, not the repo's committed .apc/memory.md (the owner promotes a fact there once they have read it). 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. NOT for one-off TODOs (use create_task), NOT for project-agent memory, and NOT for ephemeral data that ages out within a day (today's weather, a routine's run summary) — inside a routine those belong in `remember_routine`, and non-durable notes are diverted there automatically. Keep each note to one self-contained sentence.",
       parameters: {
         type: "object",
         required: ["note"],
@@ -17,21 +44,70 @@ export default {
           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'.",
+              "One durable, self-contained fact to remember, in the owner's language. e.g. 'the owner 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.",
           },
+          project: {
+            type: "string",
+            description:
+              "Optional: project id, name or path. Give it when the fact is about ONE project (what it is, its stack, who owns it, a decision taken in it) — the note lands in that project's local memory instead of your notebook. Leave it empty for facts that matter on every channel.",
+          },
         },
       },
     },
   },
-  makeHandler: (ctx = {}) => ({ note, channel } = {}) => {
+  makeHandler: (ctx = {}) => ({ note, channel, project } = {}) => {
     if (!note || !String(note).trim()) return { error: "note required" };
+    const text = String(note).trim();
     try {
-      const r = appendSelfMemory(note, { channel: channel || ctx.channel || "" });
+      // An explicit project wins over the routine divert below: the model has
+      // said where this belongs, and a project fact is durable by definition.
+      if (project !== undefined && project !== null && String(project).trim()) {
+        let p;
+        try {
+          p = resolveProject(ctx.projects, String(project).trim());
+        } catch (e) {
+          return { error: e.message };
+        }
+        const meta = projectMeta(ctx.projects, p);
+        const r = appendProjectLocalMemory(p, text, {
+          channel: channel || ctx.channel || "",
+          projectName: meta.name,
+        });
+        return {
+          saved: true,
+          scope: "project",
+          project: meta.name,
+          note: text,
+          path: r.path,
+          hint:
+            "saved to this project's LOCAL memory (not committed). If the owner wants it in the repo, they promote it to .apc/memory.md from the Memories screen.",
+        };
+      }
+
+      const routineId = ctx.channelMeta?.routineId;
+      if (ctx.channel === CHANNELS.ROUTINE && routineId && !looksDurable(text)) {
+        // Divert, don't drop — and if storage can't be resolved, fall through
+        // to the global save: a misplaced note beats a lost one.
+        const storagePath = resolveRoutineStorage(ctx.projects, ctx.channelMeta?.projectPath || "");
+        if (storagePath) {
+          const routineName = ctx.channelMeta?.routineName || "";
+          appendRoutineMemory(storagePath, routineId, text, { routineName });
+          return {
+            saved: true,
+            scope: "routine",
+            routine: routineName || routineId,
+            note: text,
+            hint:
+              "not a durable owner-level fact — saved to this routine's own memory, not the global notebook. Use `remember` only for facts worth knowing on every channel.",
+          };
+        }
+      }
+      const r = appendSelfMemory(text, { channel: channel || ctx.channel || "" });
       return { saved: true, note: r.note };
     } catch (e) {
       return { error: e?.message || String(e) };

package/src/core/agent/tools/handlers/remove-agent.js

@@ -0,0 +1,42 @@
+import { removeAgent } from "#core/apc/agent-write.js";
+import { projectMeta, resolveProject } from "../helpers.js";
+
+// Delete a project agent — its definition and its runtime dir (memory,
+// conversations, sessions). Completes the agent CRUD next to create_agent /
+// set_agent_prompt / configure_agent so the super-agent never shells out.
+export default {
+  name: "remove_agent",
+  schema: {
+    type: "function",
+    function: {
+      name: "remove_agent",
+      description:
+        "Delete a project agent: removes its .apc/agents/<slug>.md definition AND its runtime data (memory, conversations, sessions). Irreversible. Confirm with the user first unless they clearly asked to delete it.",
+      parameters: {
+        type: "object",
+        required: ["agent"],
+        properties: {
+          project: { type: "string", description: "Project id, name or path. Omit or 'default' for ~/.apx/projects/default." },
+          agent:   { type: "string", description: "Slug of the agent to delete (from list_agents)." },
+        },
+      },
+    },
+  },
+  makeHandler: ({ projects, requirePermission }) => async ({ project, agent } = {}) => {
+    await requirePermission("remove_agent", { dangerous: true, args: { agent, project } });
+    if (!agent) return { error: "agent required" };
+    let p;
+    try {
+      p = resolveProject(projects, project || "default");
+    } catch (e) {
+      return { error: e.message };
+    }
+    try {
+      removeAgent(p, agent);
+      projects.rebuild(p.id);
+      return { ok: true, removed: agent, project: projectMeta(projects, p) };
+    } catch (e) {
+      return { error: e.message };
+    }
+  },
+};