@agentprojectcontext/apx 1.77.3 → 1.79.0

package/src/core/routines/signals.js

@@ -0,0 +1,270 @@
+// Signals — deterministic detection of things worth noticing.
+//
+// THE SPLIT THIS FILE EXISTS FOR: detection is cheap and mechanical; judgement
+// is expensive and contextual. Mixing them means paying a language model every
+// five minutes to conclude that nothing is happening. Everything here is a
+// pure function over stored state — no model, no network, no clock beyond the
+// `now` you pass in — so a watch routine that finds nothing costs nothing, and
+// every rule below is testable with synthetic state.
+//
+// Thresholds are PARAMETERS, never constants. "Stale after 7 days" is a
+// judgement about how someone works, and judgements belong to the profile.
+//
+// A signal is:
+//   { type, project_id, project_name, severity, subject, detected_at, payload }
+//
+// `subject` is a one-line human phrasing — the detector already knows exactly
+// what it found, and making the model re-derive it from payload fields is how
+// summaries drift from the data they claim to describe.
+import { listTasks } from "#core/stores/tasks.js";
+import { listCommitments } from "#core/stores/commitments.js";
+import { nowIso } from "#core/util/time.js";
+
+/** Every detector, keyed by the type it emits. */
+export const SIGNAL_TYPES = Object.freeze([
+  "overdue_task",
+  "blocked_task",
+  "stale_project",
+  "commitment_due",
+  "overdue_commitment",
+]);
+
+/** Defaults chosen to be quiet. A watcher that cries on day one gets turned off. */
+export const DEFAULT_THRESHOLDS = Object.freeze({
+  blocked_hours: 48,
+  stale_project_days: 7,
+  commitment_lead_hours: 48,
+  /** Detectors to run. Empty = all of them. */
+  types: [],
+});
+
+// ---------------------------------------------------------------------------
+// detectors — each takes (project, opts) and returns Signal[]
+// ---------------------------------------------------------------------------
+
+/** A task whose due date has passed and which nobody closed. */
+function detectOverdueTasks(project, { now }) {
+  const today = now.slice(0, 10);
+  return listTasks(project.storagePath, { state: "open" })
+    .filter((t) => t.due && t.due < today)
+    .map((t) =>
+      signal(project, {
+        type: "overdue_task",
+        // A task one day late and one three weeks late are not the same event.
+        severity: daysBetween(t.due, today) >= 7 ? "high" : "normal",
+        subject: `"${t.title}" was due ${t.due}`,
+        payload: { task_id: t.id, title: t.title, due: t.due, days_late: daysBetween(t.due, today) },
+      }),
+    );
+}
+
+/**
+ * A task sitting in `blocked` long enough that nobody is coming back to it.
+ *
+ * Uses updated_at, not created_at: a task blocked this morning is a normal
+ * working state, and flagging it would train the user to ignore the watcher.
+ */
+function detectBlockedTasks(project, { now, blocked_hours }) {
+  const cutoff = new Date(Date.parse(now) - blocked_hours * 3_600_000).toISOString();
+  return listTasks(project.storagePath, { state: "open", status: "blocked" })
+    .filter((t) => (t.updated_at || t.created_at || "") < cutoff)
+    .map((t) =>
+      signal(project, {
+        type: "blocked_task",
+        severity: "normal",
+        subject: `"${t.title}" has been blocked since ${(t.updated_at || t.created_at || "").slice(0, 10)}`,
+        payload: { task_id: t.id, title: t.title, since: t.updated_at || t.created_at },
+      }),
+    );
+}
+
+/**
+ * A project nobody has touched.
+ *
+ * WHAT "ACTIVITY" MEANS HERE: the newest task or commitment event in the
+ * project's store. APX has no single per-project activity timestamp, and
+ * folding every conversation on a five-minute tick would defeat the point of a
+ * cheap detector. So this measures what it can actually see, and the phrasing
+ * says so — "no task or commitment activity", not "nothing happened". A caller
+ * with a better timestamp can pass `last_activity_at` and it wins.
+ *
+ * Claiming more than the data supports is the failure mode that kills trust in
+ * a watcher: one confident "you have abandoned this" about a project the user
+ * worked on all week, and they stop believing the rest.
+ *
+ * Deliberately ONE signal per project rather than per silent item — the point
+ * is "you have forgotten about this", and saying it once is the whole message.
+ *
+ * A project with nothing recorded at all is skipped: a freshly registered
+ * project is not neglected, and greeting someone with "this is stale" the day
+ * they add it is exactly what gets a watcher muted.
+ */
+function detectStaleProject(project, { now, stale_project_days }) {
+  const last = project.last_activity_at || lastRecordedActivity(project.storagePath);
+  if (!last) return [];
+  const days = daysBetween(last.slice(0, 10), now.slice(0, 10));
+  if (days < stale_project_days) return [];
+  const measured = project.last_activity_at ? "activity" : "task or commitment activity";
+  return [
+    signal(project, {
+      type: "stale_project",
+      severity: days >= stale_project_days * 3 ? "normal" : "low",
+      subject: `no ${measured} on ${project.name || project.path || "this project"} for ${days} days`,
+      payload: { days, last_activity_at: last, measured },
+    }),
+  ];
+}
+
+/** Newest task or commitment timestamp in a project store, or "" when empty. */
+function lastRecordedActivity(storagePath) {
+  let newest = "";
+  const bump = (v) => { if (v && v > newest) newest = v; };
+  try {
+    for (const t of listTasks(storagePath, { state: "all" })) bump(t.updated_at || t.created_at);
+  } catch { /* unreadable → treated as no evidence, not as staleness */ }
+  try {
+    for (const c of listCommitments(storagePath, { state: "all" })) bump(c.updated_at || c.created_at);
+  } catch { /* same */ }
+  return newest;
+}
+
+/** A promise coming due inside the lead window — still time to keep it. */
+function detectCommitmentsDue(project, { now, commitment_lead_hours }) {
+  const horizon = new Date(Date.parse(now) + commitment_lead_hours * 3_600_000).toISOString();
+  return listCommitments(project.storagePath, { state: "open" })
+    .filter((c) => c.due && c.due >= now && c.due <= horizon)
+    .map((c) =>
+      signal(project, {
+        type: "commitment_due",
+        // Higher than an equivalent task on purpose: someone is waiting, and a
+        // warning that arrives in time is worth more than one that arrives after.
+        severity: "high",
+        subject: `you promised ${c.counterparty}: ${c.body} — due ${c.due.slice(0, 10)}`,
+        payload: { commitment_id: c.id, counterparty: c.counterparty, due: c.due, body: c.body },
+      }),
+    );
+}
+
+/** A promise already past its date and still open. The costliest thing here. */
+function detectOverdueCommitments(project, { now }) {
+  return listCommitments(project.storagePath, { state: "open", overdue: true, now })
+    .map((c) =>
+      signal(project, {
+        type: "overdue_commitment",
+        severity: "critical",
+        subject: `you owe ${c.counterparty}: ${c.body} — was due ${c.due.slice(0, 10)}`,
+        payload: {
+          commitment_id: c.id, counterparty: c.counterparty, due: c.due, body: c.body,
+          days_late: daysBetween(c.due.slice(0, 10), now.slice(0, 10)),
+        },
+      }),
+    );
+}
+
+const DETECTORS = {
+  overdue_task: detectOverdueTasks,
+  blocked_task: detectBlockedTasks,
+  stale_project: detectStaleProject,
+  commitment_due: detectCommitmentsDue,
+  overdue_commitment: detectOverdueCommitments,
+};
+
+// ---------------------------------------------------------------------------
+// public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the configured detectors over the given projects.
+ *
+ * @param {{id, name?, path?, storagePath, last_activity_at?}[]} projects
+ * @param {object} opts  thresholds + `types` + `now` (ISO, injectable for tests)
+ * @returns {{ signals: object[], skipped: {id, error}[] }}
+ */
+export function detectSignals(projects, opts = {}) {
+  const cfg = { ...DEFAULT_THRESHOLDS, ...opts, now: opts.now || nowIso() };
+  const wanted = Array.isArray(cfg.types) && cfg.types.length
+    ? cfg.types.filter((t) => t in DETECTORS)
+    : SIGNAL_TYPES;
+
+  const signals = [];
+  const skipped = [];
+
+  for (const project of projects || []) {
+    if (!project?.storagePath) continue;
+    for (const type of wanted) {
+      try {
+        signals.push(...DETECTORS[type](project, cfg));
+      } catch (e) {
+        // One unreadable log must not blank the whole sweep — and must not be
+        // silent either, or the watcher reports "all clear" when it is blind.
+        skipped.push({ id: project.id, type, error: e?.message || String(e) });
+      }
+    }
+  }
+
+  signals.sort(bySeverityThenDate);
+  return { signals, skipped };
+}
+
+const SEVERITY_RANK = { critical: 0, high: 1, normal: 2, low: 3 };
+
+function bySeverityThenDate(a, b) {
+  const s = (SEVERITY_RANK[a.severity] ?? 9) - (SEVERITY_RANK[b.severity] ?? 9);
+  if (s !== 0) return s;
+  return String(a.subject).localeCompare(String(b.subject));
+}
+
+/**
+ * Render signals as the block a routine hands the model.
+ *
+ * Pre-rendered rather than passed as JSON because the model's job here is
+ * judgement — "is any of this worth interrupting for?" — not parsing.
+ */
+export function formatSignals(signals) {
+  if (!signals?.length) return "";
+  const lines = signals.map(
+    (s) => `- [${s.severity}] ${s.project_name ? `${s.project_name}: ` : ""}${s.subject}`,
+  );
+  return lines.join("\n");
+}
+
+/** The highest severity present, for the interruption budget. */
+export function peakSeverity(signals) {
+  let best = "low";
+  for (const s of signals || []) {
+    if ((SEVERITY_RANK[s.severity] ?? 9) < (SEVERITY_RANK[best] ?? 9)) best = s.severity;
+  }
+  return signals?.length ? best : "low";
+}
+
+/** Thresholds from a profile's config, falling back to the defaults. */
+export function thresholdsFromConfig(profileConfig = {}) {
+  const pick = (key, fallback) => {
+    const v = Number.parseInt(profileConfig[key], 10);
+    return Number.isFinite(v) && v > 0 ? v : fallback;
+  };
+  return {
+    blocked_hours: pick("blocked_task_hours", DEFAULT_THRESHOLDS.blocked_hours),
+    stale_project_days: pick("stale_project_days", DEFAULT_THRESHOLDS.stale_project_days),
+    commitment_lead_hours: pick("commitment_lead_hours", DEFAULT_THRESHOLDS.commitment_lead_hours),
+  };
+}
+
+// ---------------------------------------------------------------------------
+
+function signal(project, fields) {
+  return {
+    project_id: project.id ?? null,
+    project_name: project.name || project.path || "",
+    detected_at: nowIso(),
+    ...fields,
+  };
+}
+
+/** Whole days between two YYYY-MM-DD strings. Negative when `to` precedes `from`. */
+function daysBetween(from, to) {
+  const a = Date.parse(`${String(from).slice(0, 10)}T00:00:00Z`);
+  const b = Date.parse(`${String(to).slice(0, 10)}T00:00:00Z`);
+  if (!Number.isFinite(a) || !Number.isFinite(b)) return 0;
+  return Math.round((b - a) / 86_400_000);
+}

package/src/core/runtime-skills/apx-agency-agents/SKILL.md

@@ -68,7 +68,7 @@ import_agent({ slug: "cody-developer", project: "<name-or-path>" })
 
 ## Web equivalents
 
-Agent defaults tab (`/p/0/agent-defaults`): same CRUD — "New" (POST `/agents/vault`), per-card "Edit" (PATCH `/agents/vault/:slug`, copy-on-write for bundled), "Delete"/"Hide" (DELETE), "Show removed" toggle with "Restore" button.
+Agent defaults tab (`/p/0/agent-defaults`): same CRUD — "New" (POST `/api/agents/vault`), per-card "Edit" (PATCH `/api/agents/vault/:slug`, copy-on-write for bundled), "Delete"/"Hide" (DELETE), "Show removed" toggle with "Restore" button.
 
 ## Which agent to use
 
@@ -107,7 +107,7 @@ is_master: false
 |---|---|
 | `role` | Shown in CLI/web; appears as "Role: …" in prompt. |
 | `model` | Default model for engine routing. |
-| `description` | Shown in `/agents/vault` and AgentDefaultsTab cards. |
+| `description` | Shown in `/api/agents/vault` and AgentDefaultsTab cards. |
 | `language` | Adds "Default language: <code>" to system prompt. |
 | `skills` | Per-agent skill names; bodies loaded by skill resolution. |
 | `tools` | Tool hints; actual callable tools depend on invocation surface. |

package/src/core/runtime-skills/apx-profile/SKILL.md

@@ -113,9 +113,9 @@ install. Check the real number with `apx profile show <id>` or
 
 ## HTTP
 
-`GET /profiles` · `GET /profiles/:id` (includes `preview`) · `GET /profiles/doctor` ·
-`POST /profiles/install` · `POST /profiles/use` · `POST /profiles/off` ·
-`PATCH /profiles/config` · `DELETE /profiles/:id`
+`GET /api/profiles` · `GET /api/profiles/:id` (includes `preview`) · `GET /api/profiles/doctor` ·
+`POST /api/profiles/install` · `POST /api/profiles/use` · `POST /api/profiles/off` ·
+`PATCH /api/profiles/config` · `DELETE /api/profiles/:id`
 
 ## Gotchas
 

package/src/core/runtime-skills/apx-project/SKILL.md

@@ -36,7 +36,7 @@ apx project config unset <project> super_agent.model               # back to glo
 apx project config edit <project>                                  # opens $EDITOR on project_only JSON
 ```
 
-Every `project config` write triggers `POST /admin/reload` so the daemon picks up changes without restart.
+Every `project config` write triggers `POST /api/admin/reload` so the daemon picks up changes without restart.
 
 ## `<project>` argument resolution
 

package/src/core/runtime-skills/apx-task/SKILL.md

@@ -79,14 +79,14 @@ apx task drop t_abc            # "no longer needed; archive without completion"
 ## Endpoint surface
 
 ```
-GET    /projects/:pid/tasks                  ?state=open|done|dropped|all&tag=X&agent=Y&due_before=ISO&limit=N
-POST   /projects/:pid/tasks                  { title, body?, tags?, due?, agent?, source?, meta? }
-GET    /projects/:pid/tasks/:id
-PATCH  /projects/:pid/tasks/:id              { patch: {...} }
-POST   /projects/:pid/tasks/:id/done         { by? }
-POST   /projects/:pid/tasks/:id/drop         { by? }
-POST   /projects/:pid/tasks/:id/reopen
-GET    /projects/:pid/tasks-summary          → { open, done, dropped, overdue, total }
+GET    /api/projects/:pid/tasks                  ?state=open|done|dropped|all&tag=X&agent=Y&due_before=ISO&limit=N
+POST   /api/projects/:pid/tasks                  { title, body?, tags?, due?, agent?, source?, meta? }
+GET    /api/projects/:pid/tasks/:id
+PATCH  /api/projects/:pid/tasks/:id              { patch: {...} }
+POST   /api/projects/:pid/tasks/:id/done         { by? }
+POST   /api/projects/:pid/tasks/:id/drop         { by? }
+POST   /api/projects/:pid/tasks/:id/reopen
+GET    /api/projects/:pid/tasks-summary          → { open, done, dropped, overdue, total }
 ```
 
 ## Don't

package/src/core/runtime-skills/apx-telegram/SKILL.md

@@ -71,17 +71,17 @@ apx telegram send "text" --chat 123456789
 apx telegram send "text" --interrupt            # bypass pending-agent queue (also: --force)
 
 # Media (daemon HTTP API — no dedicated CLI subcommand yet)
-curl -X POST http://127.0.0.1:7430/telegram/send_photo \
+curl -X POST http://127.0.0.1:7430/api/telegram/send_photo \
   -H "Authorization: Bearer $(cat ~/.apx/daemon.token)" \
   -H "Content-Type: application/json" \
   -d '{"photo":"/abs/path.png","caption":"...","channel":"clientes"}'
-curl -X POST http://127.0.0.1:7430/telegram/send_voice \
+curl -X POST http://127.0.0.1:7430/api/telegram/send_voice \
   -H "Authorization: Bearer $(cat ~/.apx/daemon.token)" \
   -H "Content-Type: application/json" \
   -d '{"audio":"/abs/path.ogg","duration":5,"channel":"default"}'
 ```
 
-Every `channel` CRUD write triggers `POST /admin/reload` so polling picks up the new wiring without restart.
+Every `channel` CRUD write triggers `POST /api/admin/reload` so polling picks up the new wiring without restart.
 
 ## What "pin to project" does
 
@@ -92,7 +92,7 @@ On a message to a channel with `project: "iacrmar"`:
 
 ## What "master agent" does
 
-With `route_to_agent: "reviewer"`, messages go through `/projects/:pid/agents/reviewer/chat` instead of `/super-agent/chat`. The agent's `AGENT.md` + memory is used. No tools (project agents are `exec_agent`-shaped — text in, text out). Single LLM call. Use this for persona channels (reviewer, sales, support) instead of the general assistant. Empty = super-agent (default).
+With `route_to_agent: "reviewer"`, messages go through `/api/projects/:pid/agents/reviewer/chat` instead of `/api/super-agent/chat`. The agent's `AGENT.md` + memory is used. No tools (project agents are `exec_agent`-shaped — text in, text out). Single LLM call. Use this for persona channels (reviewer, sales, support) instead of the general assistant. Empty = super-agent (default).
 
 ## Anti-examples
 

package/src/core/runtime-skills/apx-voice/SKILL.md

@@ -117,16 +117,16 @@ apx voice say "Hello from APX" --provider gemini
 
 ## Unified voice channel
 
-`POST /voice/turn` is one round-trip: send audio (or text), get back `{ user_text, reply_text, reply_audio_path }`. STT in, agent loop, TTS out. For overlay and future "voice room" clients.
+`POST /api/voice/turn` is one round-trip: send audio (or text), get back `{ user_text, reply_text, reply_audio_path }`. STT in, agent loop, TTS out. For overlay and future "voice room" clients.
 
 ```bash
-curl -X POST http://127.0.0.1:7430/voice/turn \
+curl -X POST http://127.0.0.1:7430/api/voice/turn \
   -H "Authorization: Bearer $(cat ~/.apx/daemon.token)" \
   -H "Content-Type: application/json" \
   -d '{"text":"Hello APX","channel":"voice"}'
 ```
 
-Telegram voice messages and overlay mascot still have their own STT pipelines — they don't go through `/voice/turn` yet.
+Telegram voice messages and overlay mascot still have their own STT pipelines — they don't go through `/api/voice/turn` yet.
 
 ## Anti-examples
 
@@ -146,4 +146,4 @@ Telegram voice messages and overlay mascot still have their own STT pipelines
 
 - Paste base64 audio into chat. Use file paths or `send_voice` / `send_audio`.
 - Switch providers mid-routine without testing — quality varies a lot across Piper voices and cloud engines.
-- Expect TTS streaming yet — `apx voice say` returns a complete file. `/tts/stream` is open work.
+- Expect TTS streaming yet — `apx voice say` returns a complete file. `/api/tts/stream` is open work.

package/src/core/runtimes/detect.js

@@ -1,8 +1,8 @@
 // Best-effort detection of installed agent CLIs and LLM runners.
 // We just probe the binary with `--version` (or equivalent) and don't fail if
 // it isn't there — caller decides what to do with absence.
-import { runProcess } from "#host/daemon/runtimes/_spawn.js";
-import { resolveAntigravityCli } from "#host/daemon/runtimes/antigravity.js";
+import { runProcess } from "./_spawn.js";
+import { resolveAntigravityCli } from "./antigravity.js";
 
 const PROBES = [
   // Coding-agent CLIs (runtimes/)