@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/interfaces/cli/commands/project.js

@@ -67,6 +67,35 @@ export async function cmdProjectRebuild(args) {
   console.log(`Rebuilt project #${id}: ${result.agents} agents`);
 }
 
+/**
+ * The filesystem root of a project, from the same selectors resolveProjectId
+ * accepts (numeric id, path, exact name, fuzzy name/path).
+ *
+ * WHY THIS EXISTS. Commands that edit files under `.apc/` need the path, not the
+ * id, and they all resolved it by walking up from cwd. So `apx agent set magui
+ * --tools …` run from anywhere but that one checkout failed with "not inside an
+ * APC project (run `apx init` first)" — advice that would have scaffolded a
+ * second project on top of the shell's cwd instead of editing the agent the
+ * user named. `--project` already works everywhere else; now it works here.
+ */
+export async function resolveProjectRoot(target) {
+  if (target === true) {
+    throw new Error("--project needs a value: a project name, id, or path (`apx project list` shows them)");
+  }
+  if (target === undefined || target === null || target === "") {
+    const root = findApfRoot();
+    if (root) return root;
+    throw new Error(
+      "not inside an APC project — cd into one, run `apx init` here, or name the project with --project <name|id|path>"
+    );
+  }
+  const id = await resolveProjectId(target);
+  const projects = await http.get("/api/projects");
+  const found = projects.find((p) => Number(p.id) === Number(id));
+  if (!found) throw new Error(`--project "${target}" is not registered — run \`apx project list\``);
+  return found.path;
+}
+
 // Resolve a project id from one of:
 //   numeric id   ("2")
 //   absolute path ("/abs/path/to/project")

package/src/interfaces/cli/commands/routine.js

@@ -1,6 +1,12 @@
 import { http } from "../http.js";
 import { resolveProjectId } from "./project.js";
 import { listRoutines } from "#core/stores/routines.js";
+import {
+  deliveryChannelIds,
+  normalizeDeliverTo,
+  PROFILE_DELIVERY,
+  NO_DELIVERY,
+} from "#core/routines/index.js";
 import { projectStorageRoot } from "#core/config/index.js";
 import {
   routineMemoryPath,
@@ -9,6 +15,13 @@ import {
   ensureRoutineMemory,
 } from "#core/stores/routine-memory.js";
 
+// Flags that belong to the routine record itself, not to its `spec`.
+const ROUTINE_FLAGS = [
+  "name", "kind", "schedule", "spec", "verbose", "project",
+  "permission-mode", "allowed-tools",
+  "pre-commands", "post-commands", "skip-prompt-on", "deliver-to",
+];
+
 function parseSpec(args) {
   // Build spec from --spec '<json>' or from --K=V pairs
   if (args.flags.spec && args.flags.spec !== true) {
@@ -20,7 +33,11 @@ function parseSpec(args) {
   }
   const spec = {};
   for (const [k, v] of Object.entries(args.flags)) {
-    if (["name", "kind", "schedule", "spec", "verbose", "permission-mode", "allowed-tools"].includes(k)) continue;
+    // Every flag `cmdRoutineAdd` reads for itself. A name missing from this
+    // list does not just get ignored — it lands in `spec` as a stray key the
+    // handler never reads, which is how `--post-commands` used to end up
+    // stored twice, once parsed and once as raw text.
+    if (ROUTINE_FLAGS.includes(k)) continue;
     if (v === true) continue;
     // try to JSON-parse the value (numbers, bools), else keep as string
     let val = v;
@@ -86,12 +103,26 @@ export async function cmdRoutineAdd(args) {
   const skip_prompt_on = args.flags["skip-prompt-on"] && args.flags["skip-prompt-on"] !== true
     ? args.flags["skip-prompt-on"]
     : undefined;
+  // Where the output goes: `--deliver-to telegram,web`, `--deliver-to profile`
+  // to take it from the active agent profile, `--deliver-to none` to say out
+  // loud that this one delivers nowhere. Omitted leaves the field unset, which
+  // is not the same as empty — see deliver_to in core/stores/routines.js.
+  const deliver_to = args.flags["deliver-to"] && args.flags["deliver-to"] !== true
+    ? normalizeDeliverTo(String(args.flags["deliver-to"]))
+    : undefined;
+  if (deliver_to) {
+    const known = [...deliveryChannelIds(), PROFILE_DELIVERY, NO_DELIVERY];
+    const bad = deliver_to.filter((c) => !known.includes(c));
+    if (bad.length)
+      throw new Error(`apx routine add: unknown --deliver-to channel: ${bad.join(", ")} (known: ${known.join(", ")})`);
+  }
   const pid = await resolveProjectId(args?.flags?.project);
-  const r = await http.post(`/api/projects/${pid}/routines`, { name, kind, schedule, spec, permission_mode, allowed_tools, pre_commands, post_commands, skip_prompt_on });
+  const r = await http.post(`/api/projects/${pid}/routines`, { name, kind, schedule, spec, permission_mode, allowed_tools, pre_commands, post_commands, skip_prompt_on, deliver_to });
   console.log(`added routine "${r.name}" (${r.kind}, ${r.schedule}) → next ${r.next_run_at}`);
   if (r.pre_commands?.length)  console.log(`  pre:  ${r.pre_commands.join(", ")}`);
   if (r.post_commands?.length) console.log(`  post: ${r.post_commands.join(", ")}`);
   if (r.skip_prompt_on && r.skip_prompt_on !== "signal") console.log(`  skip_prompt_on: ${r.skip_prompt_on}`);
+  if (r.deliver_to) console.log(`  deliver_to: ${r.deliver_to.length ? r.deliver_to.join(", ") : "(nowhere)"}`);
 }
 
 export async function cmdRoutineRemove(args) {
@@ -182,16 +213,20 @@ export async function cmdRoutineHistory(args) {
   if (!name) throw new Error("apx routine history: missing <name>");
   const pid = await resolveProjectId(args?.flags?.project);
   const limit = args.flags.n || args.flags.last || "50";
-  const rows = await http.get(`/api/projects/${pid}/messages?channel=routine&limit=${encodeURIComponent(limit)}`);
-  const filtered = rows
-    .filter((r) => r.meta?.routine === name)
-    .reverse();
-  if (filtered.length === 0) {
+  // The daemon decides what counts as a run (core/routines/run-log.js). This
+  // used to read the raw routine channel and keep every row carrying
+  // `meta.routine`, which is one row per TOOL CALL plus the "routine created /
+  // updated" rows — so `history` printed a run's internals interleaved with
+  // edits and called all of it history. Same bug the panel had; same fix.
+  const runs = await http.get(
+    `/api/projects/${pid}/routines/${encodeURIComponent(name)}/runs?limit=${encodeURIComponent(limit)}`
+  );
+  if (runs.length === 0) {
     console.log("(no routine history)");
     return;
   }
-  for (const r of filtered) {
-    const status = r.meta?.status ? ` ${r.meta.status}` : "";
-    console.log(`${r.ts}${status} ${r.author || ""}: ${r.body}`);
+  for (const r of [...runs].reverse()) {
+    const chat = r.conversation_id ? ` [chat ${r.agent_slug}/${r.conversation_id}]` : "";
+    console.log(`${r.ts} ${r.status} ${r.body}${chat}`);
   }
 }

package/src/interfaces/cli/commands/runtime.js

@@ -1,13 +1,36 @@
 import { http } from "../http.js";
 import { resolveProjectId } from "./project.js";
 
+const SLUG_RE = /^[a-z][a-z0-9_-]*$/;
+
+// Resolve the OPTIONAL agent and the prompt positionals for `apx run`. The APX
+// agent only shapes the system prompt handed to the external CLI — the CLI has
+// its own agency — so no agent means a pass-through:
+//   apx run --runtime claude-code "<prompt>"              → { slug: null }  (pass-through)
+//   apx run -a reviewer --runtime claude-code "<prompt>"  → { slug: "reviewer" }
+//   apx run reviewer --runtime claude-code "<prompt>"     → legacy positional (still works)
+// A SINGLE positional is always the prompt, so a quoted pass-through prompt is
+// never mistaken for an agent.
+export function resolveRunAgent(flags = {}, positionals = []) {
+  const flagVal =
+    (flags.agent && flags.agent !== true) ? String(flags.agent) :
+    (flags.a && flags.a !== true) ? String(flags.a) : null;
+  let slug = flagVal;
+  let rest = positionals.slice();
+  if (!slug && rest.length >= 2 && SLUG_RE.test(rest[0])) {
+    slug = rest[0];
+    rest = rest.slice(1);
+  }
+  return { slug: slug || null, positionals: rest };
+}
+
 export async function cmdRun(args) {
-  const slug = args._[0];
-  if (!slug) throw new Error("apx run: usage: apx run <agent> --runtime <id> \"<prompt>\"");
   const runtime = args.flags.runtime === true ? null : args.flags.runtime;
   if (!runtime) throw new Error("apx run: --runtime required (claude-code | codex | opencode | aider | cursor-agent | gemini-cli | qwen-code | antigravity)");
 
-  let prompt = args._.slice(1).join(" ").trim();
+  const { slug, positionals } = resolveRunAgent(args.flags, args._);
+
+  let prompt = positionals.join(" ").trim();
   if (!prompt || prompt === "-") {
     const fs = await import("node:fs");
     if (!process.stdin.isTTY) {
@@ -30,10 +53,10 @@ export async function cmdRun(args) {
     ? parseInt(args.flags.timeout, 10) * 1000
     : undefined;
 
-  const result = await http.post(
-    `/api/projects/${pid}/agents/${slug}/runtime`,
-    { runtime, prompt, timeoutMs }
-  );
+  const endpoint = slug
+    ? `/api/projects/${pid}/agents/${slug}/runtime`
+    : `/api/projects/${pid}/runtime`;
+  const result = await http.post(endpoint, { runtime, prompt, timeoutMs });
 
   if (result.output) process.stdout.write(result.output + "\n");
   if (process.stderr.isTTY || args.flags.verbose) {

package/src/interfaces/cli/commands/session.js

@@ -6,6 +6,7 @@ import { getOrCreateApxId } from "#core/apc/scaffold.js";
 import { generateSessionId } from "#core/stores/sessions.js";
 import { projectStorageRoot } from "#core/config/index.js";
 import { http } from "../http.js";
+import { readStdinSync } from "../stdin.js";
 import { resolveProjectId } from "./project.js";
 import {
   ENGINES,
@@ -30,20 +31,6 @@ function requireStorageRoot(root) {
 
 const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 
-function readStdinSync() {
-  const chunks = [];
-  const buf = Buffer.alloc(65536);
-  try {
-    while (true) {
-      const bytes = fs.readSync(0, buf, 0, buf.length);
-      if (!bytes) break;
-      chunks.push(buf.slice(0, bytes).toString("utf8"));
-    }
-  } catch {}
-  return chunks.join("");
-}
-
-
 
 function listAllSessions(root) {
   const agentsDir = path.join(requireStorageRoot(root), "agents");
@@ -173,8 +160,8 @@ export function cmdSessionList(args) {
 /**
  * `apx session get <id>` — single-record fetch.
  *
- *   - Default: search the current APC project's local sessions (legacy
- *     behaviour, fast, no daemon, no engine scan).
+ *   - Default: search the current APC project's local sessions (fast, no
+ *     daemon, no engine scan).
  *   - --engine <id>  : look only inside that engine's storage (apx, claude,
  *                      codex). Useful when you want the raw transcript of a
  *                      Claude/Codex session by id.
@@ -214,7 +201,7 @@ export function cmdSessionGet(args) {
     return printEngineSession(hits[0], args);
   }
 
-  // Legacy / default — local APC project session lookup.
+  // Default — local APC project session lookup.
   const root = requireRoot();
   const s = findSessionById(root, id);
   if (!s) {
@@ -489,30 +476,76 @@ export async function cmdSessionResume(args) {
     }
   }
 
-  // ── 4. Optional spawn of native CLI to continue ──────────────────────────
-  if (args.flags.continue) {
-    const spec = spawnContinueSpec(meta);
-    if (!spec) {
-      console.log("");
-      console.log(`(--continue not supported for engine "${meta.engine}")`);
+  // ── 4. Continue the session ──────────────────────────────────────────────
+  // Two shapes share one flag family:
+  //   --continue                 → interactive: hand the terminal to the native
+  //                                CLI (claude --resume / codex resume) so a
+  //                                HUMAN keeps typing. (stdio inherited)
+  //   --continue --msg "<text>"  → headless: inject one message into the
+  //                                existing transcript (full context) and
+  //                                capture the reply. This is how an APX agent
+  //                                answers a coding session it doesn't share a
+  //                                live process with — the return leg of a
+  //                                CLI ⇄ agent hand-off. `--msg` implies continue.
+  const relayMsgFlag = args.flags.msg ?? args.flags.text ?? args.flags.m;
+  const wantsRelay = relayMsgFlag !== undefined && relayMsgFlag !== false;
+  if (args.flags.continue || wantsRelay) {
+    if (wantsRelay) {
+      const message = relayMsgFlag === true || relayMsgFlag === "-" ? readStdinSync().trim() : String(relayMsgFlag);
+      if (!message) throw new Error('apx session resume --msg: message is empty (pass "<text>" or pipe it on stdin)');
+      const spec = spawnHeadlessMsgSpec(meta, message);
+      if (!spec) {
+        console.log("");
+        console.log(`(--msg headless delivery not supported for engine "${meta.engine}" yet — claude only; use --continue without --msg for interactive)`);
+        process.exitCode = 2;
+      } else {
+        console.error(`→ delivering to ${meta.engine}:${meta.id}${spec.cwd ? `  (cwd: ${spec.cwd})` : ""}`);
+        const child = spawn(spec.bin, spec.args, {
+          cwd: spec.cwd || process.cwd(),
+          stdio: ["ignore", "pipe", "pipe"],
+        });
+        let out = "";
+        let err = "";
+        child.stdout.on("data", (d) => (out += d));
+        child.stderr.on("data", (d) => (err += d));
+        const code = await new Promise((resolve) => {
+          child.on("exit", (c) => resolve(c));
+          child.on("error", (e) => {
+            err += `\n(failed to launch ${spec.bin}: ${e.message})`;
+            resolve(-1);
+          });
+        });
+        const text = out.trim();
+        if (text) console.log(text);
+        if (code !== 0) {
+          if (err.trim()) console.error(err.trim().slice(0, 800));
+          process.exitCode = code === -1 ? 1 : code;
+        }
+      }
     } else {
-      console.log("");
-      console.log(`→ launching: ${spec.bin} ${spec.args.join(" ")}`);
-      if (spec.cwd) console.log(`   cwd: ${spec.cwd}`);
-      const child = spawn(spec.bin, spec.args, {
-        cwd: spec.cwd || process.cwd(),
-        stdio: "inherit",
-      });
-      await new Promise((resolve) => {
-        child.on("exit", (code) => {
-          if (code !== 0) console.log(`(native CLI exited with code ${code})`);
-          resolve();
+      const spec = spawnContinueSpec(meta);
+      if (!spec) {
+        console.log("");
+        console.log(`(--continue not supported for engine "${meta.engine}")`);
+      } else {
+        console.log("");
+        console.log(`→ launching: ${spec.bin} ${spec.args.join(" ")}`);
+        if (spec.cwd) console.log(`   cwd: ${spec.cwd}`);
+        const child = spawn(spec.bin, spec.args, {
+          cwd: spec.cwd || process.cwd(),
+          stdio: "inherit",
         });
-        child.on("error", (e) => {
-          console.log(`(failed to launch ${spec.bin}: ${e.message})`);
-          resolve();
+        await new Promise((resolve) => {
+          child.on("exit", (code) => {
+            if (code !== 0) console.log(`(native CLI exited with code ${code})`);
+            resolve();
+          });
+          child.on("error", (e) => {
+            console.log(`(failed to launch ${spec.bin}: ${e.message})`);
+            resolve();
+          });
         });
-      });
+      }
     }
   }
 
@@ -752,6 +785,25 @@ function spawnContinueSpec(meta) {
   return null;
 }
 
+// Map (engine, id, cwd, message) → how to spawn the native CLI HEADLESS with a
+// new message injected into the existing transcript. This is the async-relay
+// counterpart to spawnContinueSpec: `--continue` opens the session for a human
+// to keep typing (stdio inherited); `--continue --msg` hands one message into an
+// idle session non-interactively and captures what it does, so any APX agent can
+// relay a user's reply back into a coding-CLI session it doesn't share a live
+// process with. Claude only for now (`claude -p "<msg>" --resume <id>`); other
+// engines fall through to an explicit "not supported yet".
+function spawnHeadlessMsgSpec(meta, message) {
+  if (meta.engine === "claude") {
+    return {
+      bin: "claude",
+      args: ["-p", message, "--resume", meta.id, "--output-format", "text"],
+      cwd: meta.cwd && fs.existsSync(meta.cwd) ? meta.cwd : null,
+    };
+  }
+  return null;
+}
+
 // Create a new APX session whose body is the summary of an existing session.
 // Used by `apx session resume <id> --into apx[:slug]`. Picks a sensible
 // default agent slug when none is given.

package/src/interfaces/cli/commands/sessions.js

@@ -116,6 +116,31 @@ function printSessions(engine, dir, result, limit) {
   }
 }
 
+// OpenCode keeps no project tree — it answers with every session at once, so
+// there is nothing to group by. Same table as printSessions, minus the
+// directory it doesn't have.
+function printAllSessions(engine, rows, limit) {
+  if (!rows.length) {
+    console.log("  (sin nada)");
+    return;
+  }
+  const sessions = limit && limit > 0 ? rows.slice(0, limit) : rows;
+  console.log(`${engine.label} sessions:`);
+  console.log("");
+  console.log(`${"DATE".padEnd(12)} ${"SESSION ID".padEnd(38)} TITLE`);
+  console.log(`${"─".repeat(12)} ${"─".repeat(38)} ${"─".repeat(40)}`);
+  for (const s of sessions) {
+    console.log(
+      `${fmtDate(s.mtime).padEnd(12)} ${String(s.id).padEnd(38)} ${String(s.title).slice(0, 70)}`
+    );
+  }
+  if (engine.resumeHint && sessions[0]) {
+    console.log("");
+    console.log("Resume:");
+    console.log(`  specific: ${engine.resumeHint(sessions[0].id)}`);
+  }
+}
+
 function printProjects(engine, projects) {
   if (projects.length === 0) {
     console.log(`(no ${engine.label} projects found)`);
@@ -158,8 +183,10 @@ function listSingleEngine(engine, args, opts, { headerPrefix = "" } = {}) {
 
   if (dir) {
     printSessions(engine, dir, engine.listSessions(dir, opts), limit);
-  } else {
+  } else if (typeof engine.listProjects === "function") {
     printProjects(engine, engine.listProjects(opts));
+  } else {
+    printAllSessions(engine, engine.listAllSessions(opts), limit);
   }
   return true;
 }
@@ -211,13 +238,19 @@ export function cmdSessionsList(args, opts = {}) {
       } else {
         printSessions(engine, dir, result, limit);
       }
-    } else {
+    } else if (typeof engine.listProjects === "function") {
       const list = engine.listProjects(opts);
       if (list.length === 0) {
         console.log("  (sin nada)");
       } else {
         printProjects(engine, list);
       }
+    } else {
+      // Engines that list flat (OpenCode). `implemented` is true for them —
+      // they list fine, just not by project — so the check above lets them
+      // through and this is where they land. Calling listProjects here is what
+      // made `apx sessions list` exit 1 for everyone with OpenCode installed.
+      printAllSessions(engine, engine.listAllSessions(opts), limit);
     }
   }
   if (!anyDetected) {

package/src/interfaces/cli/commands/skills.js

@@ -12,7 +12,7 @@ import {
   installGlobalSkills,
   listBundledSkills,
   listEngineSkills,
-  listLegacyPruneSlugs,
+  listRetiredSkillSlugs,
 } from "#core/apc/scaffold.js";
 import {
   ensureIndex,
@@ -174,7 +174,7 @@ export async function cmdSkillsSync(args) {
     for (const k of ["created", "updated", "unchanged", "pruned"]) {
       if (counts[k]) parts.push(`${counts[k]} ${k}`);
     }
-    const tag = entries[0]?.scope === "legacy" ? " [legacy]" : "";
+    const tag = entries[0]?.scope === "retired" ? " [retired]" : "";
     console.log(`  ${slug.padEnd(sw)}${tag.padEnd(10)}  ${parts.join(", ")}`);
   }
   console.log("");
@@ -214,11 +214,17 @@ export async function cmdSkillsList(args = {}) {
       console.log("(no skills available)");
       return;
     }
-    console.log(`SLUG`.padEnd(28) + "SOURCE".padEnd(10) + "STATE".padEnd(10) + "DESCRIPTION");
+    console.log(`SLUG`.padEnd(28) + "SOURCE".padEnd(10) + "ORIGIN".padEnd(10) + "STATE".padEnd(10) + "DESCRIPTION");
     for (const s of out.skills) {
       const desc = (s.description || "").slice(0, 70);
       const state = s.private ? "private" : s.enabled === false ? "off" : "on";
-      console.log(s.slug.padEnd(28) + (s.source || "?").padEnd(10) + state.padEnd(10) + desc);
+      console.log(
+        s.slug.padEnd(28)
+        + (s.source || "?").padEnd(10)
+        + (s.origin || "—").padEnd(10)
+        + state.padEnd(10)
+        + desc,
+      );
     }
     return;
   }
@@ -245,7 +251,7 @@ export async function cmdSkillsStatus() {
 
   const engineSet = listEngineSkills();        // what we publish to engines
   const bundled = listBundledSkills();          // what stays in-repo for the super-agent
-  const legacy = listLegacyPruneSlugs();        // slugs APX shipped historically — pruned on sync
+  const retired = listRetiredSkillSlugs();      // slugs APX shipped historically — pruned on sync
 
   console.log(
     `Engine skill set (replicated to global dirs): ${engineSet.length} ` +
@@ -260,7 +266,7 @@ export async function cmdSkillsStatus() {
     { label: "Codex",                       dir: path.join(os.homedir(), ".codex",  "skills") },
     { label: "Antigravity / others",        dir: path.join(os.homedir(), ".agents", "skills") },
   ];
-  const allSlugs = [...engineSet.map((s) => s.slug), ...legacy];
+  const allSlugs = [...engineSet.map((s) => s.slug), ...retired];
   const sw = Math.max(...allSlugs.map((s) => s.length), 8);
   for (const { label, dir } of GLOBAL_DIRS) {
     console.log(`\n  ${label} — ${dir.replace(os.homedir(), "~")}`);
@@ -270,12 +276,12 @@ export async function cmdSkillsStatus() {
       const state = present ? "✓ installed" : "✗ MISSING (run `apx skills sync`)";
       console.log(`    ${slug.padEnd(sw)}             ${state}`);
     }
-    const stale = legacy.filter((slug) =>
+    const stale = retired.filter((slug) =>
       fs.existsSync(path.join(dir, slug, "SKILL.md"))
     );
     if (stale.length) {
       for (const slug of stale) {
-        console.log(`    ${slug.padEnd(sw)} [legacy]    ⚠ stale (run \`apx skills sync\` to prune)`);
+        console.log(`    ${slug.padEnd(sw)} [retired]   ⚠ stale (run \`apx skills sync\` to prune)`);
       }
     }
   }
@@ -475,7 +481,7 @@ export async function cmdSkillsInspector(args) {
   if (sub === "disable" || sub === "off") {
     ensureInspectorBlock(cfg).skills.inspector.enabled = false;
     writeConfig(cfg);
-    console.log("Skill Inspector disabled. Falling back to the legacy slug hint + passive RAG nudge.");
+    console.log("Skill Inspector disabled. Falling back to the static slug hint + passive RAG nudge.");
     return;
   }
   if (sub === "set") {

package/src/interfaces/cli/commands/status.js

@@ -88,8 +88,7 @@ export async function cmdStatus() {
 
   // ── Telegram ───────────────────────────────────────────────────────────────
   // Prefer the daemon's live view (real polling state). Fall back to the
-  // config file only when the daemon is unreachable. The config check must
-  // honour BOTH the legacy top-level bot_token AND per-channel tokens.
+  // config file only when the daemon is unreachable.
   console.log(sec("Telegram"));
   const tg = cfg.telegram || {};
   let tgLive = null;
@@ -117,7 +116,7 @@ export async function cmdStatus() {
     }
   } else {
     // Daemon down — best-effort from config. Token may be top-level or per-channel.
-    const hasToken = !!tg.bot_token || (tg.channels || []).some((c) => c.bot_token);
+    const hasToken = (tg.channels || []).some((c) => c.bot_token);
     if (tg.enabled && hasToken) {
       console.log(`  ${off("configured")}   ${DI}daemon down — start it to see live status${R}`);
       console.log(`${key("channels")}${val((tg.channels?.length || 1) + " configured")}`);

package/src/interfaces/cli/commands/task.js

@@ -1,13 +1,20 @@
 // apx task — per-project TODO list. Backed by /projects/:pid/tasks.
 //
-//   apx task add "<title>" [--project X] [--body Y] [--tag t] [--due 2026-05-30] [--agent A]
+//   apx task add "<title>" [--project X] [--description D] [--body Y] [--tag t]
+//                          [--due 2026-05-30] [--agent A]
+//                          [--category trip] [--place "Farmacia X"] [--at "-41.13,-71.31"] [--radius 1500]
 //   apx task list          [--all | --project X] [--state ...] [--status ...] [--tag X] [--agent Y]
 //                          [--due-before ISO] [--due-after ISO] [--updated-since ISO] [--limit N]
 //   apx task show <id>     [--project X]
 //   apx task done <id>     [--project X] [--by name]
 //   apx task drop <id>     [--project X] [--by name]
 //   apx task reopen <id>   [--project X]
-//   apx task patch <id>    [--project X] [--title T] [--body B] [--due D] [--agent A] [--tag t]
+//   apx task patch <id>    [--project X] [--title T] [--description D] [--body B] [--due D]
+//                          [--agent A] [--tag t]
+//
+// --description is what YOU have to do; --body is the prompt an agent receives
+// when it runs the task. Keeping them apart is what makes `apx task list`
+// readable as a to-do rather than as a dispatch queue.
 //
 // Each subcommand exports a usage string + a usageX() helper. The top-level
 // help (apx task --help / apx task <sub> --help) is wired through HELP_TOPICS
@@ -18,13 +25,13 @@ import { resolveProjectId } from "./project.js";
 
 // ── Usage strings (also used by index.js help topics) ────────────────────────
 export const TASK_USAGE = {
-  add:    'apx task add "<title>" [--project X] [--body Y] [--tag t]... [--due 2026-05-30] [--agent A]',
+  add:    'apx task add "<title>" [--project X] [--description D] [--body Y] [--tag t]... [--due 2026-05-30] [--agent A] [--category trip] [--place "Farmacia X"] [--at "lat,lon"] [--radius 1500]',
   list:   "apx task list [--all | --project X] [--state open|done|dropped|all] [--status pending|running|in_review|blocked] [--tag X] [--agent Y] [--due-before ISO] [--due-after ISO] [--updated-since ISO] [--limit N]",
   show:   "apx task show <id> [--project X]",
   done:   "apx task done <id> [--project X] [--by name]",
   drop:   "apx task drop <id> [--project X] [--by name]",
   reopen: "apx task reopen <id> [--project X]",
-  patch:  "apx task patch <id> [--project X] [--title T] [--body B] [--due D] [--agent A] [--tag t]",
+  patch:  "apx task patch <id> [--project X] [--title T] [--description D] [--body B] [--due D] [--agent A] [--tag t]",
 };
 
 // Print "<msg>\nUsage: <usage>" to stderr and exit 1. Each cmd has a tiny
@@ -83,8 +90,13 @@ function renderDetail(t) {
     id: t.id,
     state: t.state,
     title: t.title,
+    description: t.description || undefined,
     body: t.body,
     tags: t.tags,
+    // Only when it says something: a "general" category on every row is noise,
+    // and an absent location should read as absent rather than as null.
+    category: t.category && t.category !== "general" ? t.category : undefined,
+    location: t.location || undefined,
     due: t.due,
     agent: t.agent,
     source: t.source,
@@ -95,6 +107,36 @@ function renderDetail(t) {
   }, null, 2));
 }
 
+/**
+ * Build the `location` field from the place flags, or return {} when none were
+ * given so a patch that touches nothing else stays a no-op.
+ *
+ * `--at` takes "lat,lon" as one argument because that is how coordinates are
+ * copied out of Maps — asking for two separate flags guarantees one of them is
+ * eventually forgotten, and half a coordinate is worse than none.
+ */
+function locationFrom(flags = {}) {
+  const place = flags.place;
+  const address = flags.address;
+  const at = flags.at;
+  const radius = flags.radius;
+  if (place === undefined && address === undefined && at === undefined && radius === undefined) return {};
+  // An explicitly empty --place clears the location.
+  if (place === "" && at === undefined && address === undefined) return { location: null };
+  const location = {};
+  if (place) location.place = place;
+  if (address) location.address = address;
+  if (at) {
+    const [lat, lon] = String(at).split(",").map((part) => Number(part.trim()));
+    if (Number.isFinite(lat) && Number.isFinite(lon)) {
+      location.latitude = lat;
+      location.longitude = lon;
+    }
+  }
+  if (radius) location.radius_m = Number(radius);
+  return { location };
+}
+
 // ── add ───────────────────────────────────────────────────────────────────────
 export async function cmdTaskAdd(args) {
   const title = (args._ || []).join(" ").trim();
@@ -102,11 +144,14 @@ export async function cmdTaskAdd(args) {
   const pid = await resolveProjectId(args?.flags?.project);
   const body = {
     title,
+    description: args.flags?.description || null,
     body: args.flags?.body || null,
     due: args.flags?.due || null,
     agent: args.flags?.agent || null,
     source: args.flags?.source || "cli",
     tags: asArray(args.flags?.tag).filter(Boolean),
+    ...(args.flags?.category ? { category: args.flags.category } : {}),
+    ...locationFrom(args.flags),
   };
   const task = await http.post(`/api/projects/${pid}/tasks`, body);
   console.log(`added task ${task.id}: ${task.title}`);
@@ -198,12 +243,16 @@ export async function cmdTaskPatch(args) {
   const pid = await resolveProjectId(args?.flags?.project);
   const patch = {};
   if (args.flags?.title !== undefined) patch.title = args.flags.title;
+  if (args.flags?.description !== undefined) patch.description = args.flags.description || null;
   if (args.flags?.body  !== undefined) patch.body  = args.flags.body;
   if (args.flags?.due   !== undefined) patch.due   = args.flags.due || null;
   if (args.flags?.agent !== undefined) patch.agent = args.flags.agent || null;
   if (args.flags?.tag   !== undefined) patch.tags  = asArray(args.flags.tag).filter(Boolean);
+  if (args.flags?.category !== undefined) patch.category = args.flags.category;
+  const located = locationFrom(args.flags);
+  if ("location" in located) patch.location = located.location;
   if (Object.keys(patch).length === 0) {
-    return fail("patch", "at least one --title|--body|--due|--agent|--tag required");
+    return fail("patch", "at least one --title|--description|--body|--due|--agent|--tag|--category|--place|--at required");
   }
   const t = await http.patch(`/api/projects/${pid}/tasks/${encodeURIComponent(id)}`, { patch });
   renderDetail(t);