@agentprojectcontext/apx 1.61.0 → 1.63.0

package/src/core/stores/runtime-callbacks.js

@@ -0,0 +1,107 @@
+// Durable pending-callback store for background runtime runs.
+//
+// When call_runtime launches a runtime detached (background mode), the result
+// must reach the originating chat when the runtime finishes — even if the
+// daemon that spawned it dies in the meantime (a crash, a pull, or, as we hit
+// in testing, a task whose very job is to restart the daemon). An in-memory
+// promise can't survive that. So we drop a small durable "IOU" here at launch;
+// a reconciler (host/daemon/callback-reconciler.js) delivers it once the
+// runtime's session record shows the run finished — regardless of WHICH daemon
+// is alive, and regardless of who closed the session (the daemon's own await,
+// or the runtime proactively via `apx session close`).
+//
+// One JSON file per pending callback: <APX_HOME>/pending-callbacks/<id>.json.
+// The in-process fast path deletes the file the moment it takes ownership of
+// delivery; whatever files remain are runs whose spawning daemon never got to
+// deliver — exactly the set the reconciler must handle.
+import fs from "node:fs";
+import path from "node:path";
+import { APX_HOME } from "#core/config/paths.js";
+import { nowIso } from "#core/util/time.js";
+
+export const PENDING_CALLBACKS_DIR = path.join(APX_HOME, "pending-callbacks");
+
+const SAFE_ID = /^[A-Za-z0-9._-]+$/;
+
+function fileFor(sessionId) {
+  return path.join(PENDING_CALLBACKS_DIR, `${sessionId}.json`);
+}
+
+/**
+ * Record that a background runtime run owes a callback to a channel. `entry`:
+ * { session_id, session_path, channel, chat_id, tg_channel, runtime, agent, who }.
+ * Best-effort — a failure to persist must never break the launch.
+ */
+export function writePendingCallback(entry) {
+  try {
+    if (!entry?.session_id || !SAFE_ID.test(String(entry.session_id))) return;
+    fs.mkdirSync(PENDING_CALLBACKS_DIR, { recursive: true });
+    fs.writeFileSync(fileFor(entry.session_id), JSON.stringify({ ...entry, created: nowIso() }, null, 2));
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Drop the IOU — called the instant an in-process delivery takes ownership. */
+export function deletePendingCallback(sessionId) {
+  try {
+    if (!sessionId || !SAFE_ID.test(String(sessionId))) return;
+    fs.rmSync(fileFor(sessionId), { force: true });
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** All outstanding IOUs (parsed). Silently skips unreadable/corrupt files. */
+export function listPendingCallbacks() {
+  let files;
+  try {
+    files = fs.readdirSync(PENDING_CALLBACKS_DIR).filter((f) => f.endsWith(".json"));
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const f of files) {
+    try {
+      const entry = JSON.parse(fs.readFileSync(path.join(PENDING_CALLBACKS_DIR, f), "utf8"));
+      if (entry?.session_id) out.push(entry);
+    } catch {
+      /* skip corrupt */
+    }
+  }
+  return out;
+}
+
+/**
+ * Read the finished-state of a runtime session .md by parsing its frontmatter.
+ * Returns { exists, done, status, result, completed } — `done` is true once the
+ * run has a completed timestamp (set by the daemon's closeRuntimeSession OR by
+ * the runtime's proactive `apx session close`).
+ */
+export function readSessionState(sessionPath) {
+  let text;
+  try {
+    text = fs.readFileSync(sessionPath, "utf8");
+  } catch {
+    return { exists: false, done: false };
+  }
+  const fm = {};
+  if (text.startsWith("---\n")) {
+    const end = text.indexOf("\n---", 4);
+    if (end !== -1) {
+      for (const line of text.slice(4, end).split("\n")) {
+        const i = line.indexOf(":");
+        if (i > 0) fm[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+      }
+    }
+  }
+  const completed = fm.completed || "";
+  const status = fm.status || "";
+  return {
+    exists: true,
+    done: !!completed && !/in progress/i.test(status),
+    status,
+    result: fm.result || "",
+    completed,
+  };
+}

package/src/host/daemon/callback-reconciler.js

@@ -0,0 +1,87 @@
+// Durable delivery of background-runtime callbacks.
+//
+// Pairs with core/stores/runtime-callbacks.js: call_runtime drops a pending
+// "IOU" when it launches a runtime detached, and deletes it the moment the
+// in-process fast path delivers. Whatever IOUs survive belong to runs whose
+// spawning daemon died before delivering (crash, pull, or a task that restarted
+// the daemon). This reconciler — run once at boot and on an interval — delivers
+// those late, keying on the runtime SESSION being finished rather than on any
+// in-memory promise. That's what makes the callback survive a restart, and also
+// absorbs the "proactive" close: it doesn't care whether the daemon's own await
+// or the runtime's `apx session close` marked the session done.
+//
+// Recovery delivery is a plain channel send of the session's recorded result
+// (after a restart the full stdout is gone — only the one-line result the
+// session close captured remains). The rich A2A relay (Roby re-voicing the
+// result) stays the job of the live in-process path.
+import { listPendingCallbacks, deletePendingCallback, readSessionState } from "#core/stores/runtime-callbacks.js";
+
+const GRACE_MS = 30_000;               // let the live in-process path win a fresh completion
+const STALE_MS = 24 * 60 * 60 * 1000;  // drop IOUs for runs that never finished in a day
+
+function deliverText(entry, state) {
+  const who = entry.who || entry.runtime || "runtime";
+  const result = String(state.result || "").trim();
+  const isError = /error|⚠️/i.test(state.status) || /^(failed|error)/i.test(result);
+  const head = isError
+    ? `⚠️ La sesión de ${who} (\`${entry.session_id}\`) terminó con error${result ? `: ${result}` : ""}.`
+    : `✅ Terminó la sesión de ${who} (\`${entry.session_id}\`).`;
+  const text = !isError && result ? `${head}\n\n${result}` : head;
+  return text.slice(0, 3800);
+}
+
+/** One reconciliation pass. Best-effort per entry; a failure keeps the IOU for
+ *  the next tick rather than dropping the callback. */
+export async function reconcilePendingCallbacks({ plugins, log }) {
+  const pending = listPendingCallbacks();
+  if (!pending.length) return;
+  const telegram = plugins?.get?.("telegram");
+  const now = Date.now();
+
+  for (const entry of pending) {
+    try {
+      if (entry.channel !== "telegram") continue; // only telegram delivery for now
+      const state = readSessionState(entry.session_path);
+
+      if (!state.exists) {
+        deletePendingCallback(entry.session_id); // session file gone → orphan IOU
+        continue;
+      }
+      if (!state.done) {
+        const age = now - Date.parse(entry.created || "");
+        if (Number.isFinite(age) && age > STALE_MS) {
+          log?.(`callback-reconciler: dropping stale pending ${entry.session_id} (never completed)`);
+          deletePendingCallback(entry.session_id);
+        }
+        continue; // still running — check again next tick
+      }
+
+      // Finished. Give the live in-process path a grace window to win the
+      // normal (no-restart) case, so we don't double-deliver.
+      const compAge = now - Date.parse(state.completed || "");
+      if (Number.isFinite(compAge) && compAge < GRACE_MS) continue;
+
+      if (!telegram) continue; // telegram plugin not up this boot — retry next tick
+      await telegram.send({
+        channel: entry.tg_channel || undefined,
+        chat_id: entry.chat_id,
+        text: deliverText(entry, state),
+      });
+      deletePendingCallback(entry.session_id);
+      log?.(`callback-reconciler: delivered late callback for ${entry.session_id} → chat ${entry.chat_id}`);
+    } catch (e) {
+      log?.(`callback-reconciler: delivery failed for ${entry.session_id}: ${e.message}`);
+      // keep the IOU; next tick retries
+    }
+  }
+}
+
+/** Start the reconciler: one pass at boot (recovers anything a prior daemon
+ *  left behind), then every `intervalMs`. Returns { stop }. */
+export function startCallbackReconciler({ plugins, log, intervalMs = 30_000 }) {
+  const tick = () => reconcilePendingCallbacks({ plugins, log }).catch(() => {});
+  tick();
+  const timer = setInterval(tick, intervalMs);
+  timer.unref?.();
+  return { stop: () => clearInterval(timer) };
+}

package/src/host/daemon/index.js

@@ -19,6 +19,7 @@ import { ProjectManager } from "./db.js";
 import { McpRegistry } from "#core/mcp/runner.js";
 import { PluginManager } from "./plugins/index.js";
 import { RoutineScheduler } from "./routines-scheduler.js";
+import { startCallbackReconciler } from "./callback-reconciler.js";
 import { buildApi } from "./api.js";
 import { createTokenStore } from "./token-store.js";
 import { triggerWakeup } from "./wakeup.js";
@@ -208,12 +209,17 @@ async function main() {
 
   plugins.installRoutes(app);
 
+  let callbackReconciler = null;
   const server = app.listen(port, host, () => {
     writePid();
     log(`apx-daemon ${PKG.version} listening on http://${host}:${port}`);
     log(`projects: ${projects.list().length} | plugins: ${Object.keys(plugins.status()).join(", ") || "(none)"}`);
     plugins.startAll();
     scheduler.start();
+    // Durable background-runtime callbacks: deliver any results whose spawning
+    // daemon died before it could (crash, pull, or a task that restarted the
+    // daemon). Runs once now to recover prior IOUs, then on an interval.
+    callbackReconciler = startCallbackReconciler({ plugins, log });
     // Cross-channel memory: ensure ~/.apx/memory.md exists, open the vector
     // store, and start the incremental RAG indexer. Best-effort — never blocks
     // boot and never throws into the daemon.
@@ -280,6 +286,7 @@ async function main() {
   function shutdown(signal) {
     log(`received ${signal}, shutting down...`);
     scheduler.stop();
+    callbackReconciler?.stop();
     plugins.stopAll();
     stopMemory();
     registries.shutdown();

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

@@ -31,6 +31,33 @@ export function resolveExecRequest(args) {
   };
 }
 
+// Valid channel strings the daemon knows how to route.
+const KNOWN_CHANNELS = new Set(Object.values(CHANNELS));
+
+/**
+ * Resolve which channel `apx exec` should tag the turn with.
+ * Default: CHANNELS.CLI (unchanged behaviour).
+ *   --code / -c        → CHANNELS.CODE (coding system prompt + code tools)
+ *   --channel <name>   → explicit channel (must be a known channel string)
+ */
+export function resolveExecChannel(args) {
+  const flags = args?.flags || {};
+  if (flags.code) return CHANNELS.CODE;
+
+  const raw = flags.channel;
+  if (raw && raw !== true) {
+    const channel = String(raw).toLowerCase();
+    if (!KNOWN_CHANNELS.has(channel)) {
+      throw new Error(
+        `apx exec: unknown channel "${raw}". Known channels: ${[...KNOWN_CHANNELS].join(", ")}`
+      );
+    }
+    return channel;
+  }
+
+  return CHANNELS.CLI;
+}
+
 async function readPromptFromStdin() {
   const fs = await import("node:fs");
   if (process.stdin.isTTY) return "";
@@ -57,14 +84,14 @@ export async function cmdExec(args) {
   }
   if (!prompt) {
     throw new Error(
-      'apx exec: prompt is empty. Usage: apx exec "prompt" | apx exec -a <agent> "prompt" | apx exec -- "prompt"'
+      'apx exec: prompt is empty. Usage: apx exec "prompt" | apx exec --code "prompt" | apx exec -a <agent> "prompt" | apx exec -- "prompt"'
     );
   }
 
   const pid = await resolveProjectId(args?.flags?.project);
   const body = {
     prompt,
-    channel: CHANNELS.CLI,
+    channel: resolveExecChannel(args),
     channelMeta: { cwd: process.cwd() },
   };
   if (args.flags.model && args.flags.model !== true) body.model = args.flags.model;

package/src/interfaces/cli/index.js

@@ -1100,12 +1100,15 @@ const HELP_TOPICS = new Map(Object.entries({
     summary: "One-shot LLM call. Default target is the APX super-agent (daemon); use -a for an APC agent slug.",
     usage: [
       "apx exec \"<prompt>\" [--model <id>] [--project <name|id|path>]",
+      "apx exec --code \"<prompt>\"   (coding channel: code system prompt + git tools)",
       "apx exec -- \"<prompt>\"",
       "apx exec -a <agent> \"<prompt>\" [--model <id>]",
       "apx exec <agent> \"<prompt>\"  (legacy positional agent)",
     ],
     options: [
       ["-a, --agent <slug>", "APC agent slug (omit for super-agent default)."],
+      ["-c, --code", "Run on the 'code' channel (coding system prompt + code tools)."],
+      ["--channel <name>", "Explicit channel (cli, code, api, …). Default cli."],
       ["--model <id>", "Override configured model."],
       ["--max-tokens N", "Output token limit."],
       ["--temperature T", "Sampling temperature."],
@@ -1113,6 +1116,7 @@ const HELP_TOPICS = new Map(Object.entries({
     ],
     examples: [
       "apx exec \"What time is it in UTC?\"",
+      "apx exec --code \"refactor the auth middleware\"",
       "apx exec -- \"decime qué hora es\"",
       "apx exec -a reviewer \"Summarize your role\"",
       "apx exec reviewer \"Summarize your role\" --model gpt-5.2",
@@ -2090,7 +2094,7 @@ function buildHelp(version) {
 
     hSec("LLM / Code"),
     hCmd("apx code",                   36, "APX terminal coding assistant"),
-    hCmd("apx exec \"prompt\"",         36, "super-agent (default)  --model <id>  -a <agent> for APC slug"),
+    hCmd("apx exec \"prompt\"",         36, "super-agent (default)  --code coding channel  -a <agent> for APC slug"),
     hCmd("apx chat <agent>",           36, "interactive agent REPL  --conversation <id>"),
     hCmd("apx search \"query\"",       36, "web search (ddg | brave | browser)  --mode <m>  -n N"),
     hCmd("apx conversations list",     36, "stored exec/chat conversations for <agent>"),
@@ -2241,6 +2245,11 @@ function findHelpTopic(argv) {
   return { global: true };
 }
 
+// Flags that never take a value. Without this the parser would greedily
+// swallow the following positional (e.g. `apx exec --code "hi"` would set
+// flags.code = "hi" and drop the prompt). Boolean flags always resolve to true.
+const BOOLEAN_FLAGS = new Set(["code", "verbose"]);
+
 function parseArgs(argv) {
   const args = { _: [], flags: {} };
   for (let i = 0; i < argv.length; i++) {
@@ -2253,7 +2262,9 @@ function parseArgs(argv) {
     if (a.startsWith("--")) {
       const key = a.slice(2);
       const next = argv[i + 1];
-      if (next === undefined || next.startsWith("--")) {
+      if (BOOLEAN_FLAGS.has(key)) {
+        args.flags[key] = true;
+      } else if (next === undefined || next.startsWith("--")) {
         args.flags[key] = true;
       } else {
         // support repeated flags (e.g. --env A=1 --env B=2)
@@ -2269,6 +2280,8 @@ function parseArgs(argv) {
       args.flags.n = argv[++i];
     } else if (a === "-a") {
       args.flags.agent = argv[++i];
+    } else if (a === "-c") {
+      args.flags.code = true;
     } else {
       args._.push(a);
     }