@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/core/routines/header.js

@@ -0,0 +1,88 @@
+// The automation header prepended to every routine's LLM prompt at run time.
+//
+// It is the native replacement for the old `echo "…date…"` pre_command +
+// `{{pre_output}}` trick: the runner (core/routines/runner.js) builds this block
+// once per run and puts it at the very top of the LLM prompt (spec.prompt), so
+// the model always opens on its id + memory path and what "now" is — without any
+// per-routine shell plumbing. It is NOT prepended to a telegram routine's
+// spec.text: that string is the message body sent verbatim to the chat, so a
+// header there would leak into the delivered message. The routine's human name
+// is not repeated here — the filed record already opens on `[routine: <name>]`.
+//
+// The clock is reported two ways on purpose, each on its own labelled line:
+// machine-friendly (ISO + epoch ms, UTC) so a routine can diff runs
+// deterministically, and human-friendly in the owner's configured timezone
+// (config.user.timezone / .locale) so a reply reads in local wall-clock time.
+// The "(UTC)" / "(owner local time)" labels keep the two frames unambiguous.
+import { isoToMs } from "#core/util/time.js";
+import { routineMemoryPath } from "#core/stores/routine-memory.js";
+
+/** "2026-08-20T13:00:35.123Z (1787230835123)" — ISO with millis + epoch ms. */
+function machineStamp(ms) {
+  return `${new Date(ms).toISOString()} (${ms})`;
+}
+
+/**
+ * Wall-clock stamp in the owner's zone, e.g.
+ * "miércoles, 20 de agosto de 2026, 10:00:35 (America/Argentina/Buenos_Aires)".
+ * Returns "" when no timezone is configured or the zone is unusable, so the
+ * caller simply omits the local line rather than printing a broken one.
+ */
+function localStamp(ms, timezone, locale) {
+  if (!timezone) return "";
+  try {
+    const s = new Intl.DateTimeFormat(locale || "en", {
+      timeZone: timezone,
+      dateStyle: "full",
+      timeStyle: "medium",
+    }).format(new Date(ms));
+    return `${s} (${timezone})`;
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Build the automation header block for one routine run.
+ *
+ * @param {object} routine  The routine record (name, id, last_run_at).
+ * @param {object} opts
+ *   - storagePath: project storage root, to resolve the memory.md path
+ *   - config:      resolved config (reads config.user.timezone / .locale)
+ *   - nowMs:       run-start epoch ms (injected so a run stamps one instant)
+ * @returns {string} The header text (no trailing newline).
+ */
+export function buildRoutineHeader(routine, { storagePath, config, nowMs } = {}) {
+  const user = config?.user || {};
+  const now = Number.isFinite(nowMs) ? nowMs : Date.now();
+  const lastMs = isoToMs(routine?.last_run_at);
+  const memPath = routine?.id && storagePath
+    ? routineMemoryPath(storagePath, routine.id)
+    : "";
+  const local = localStamp(now, user.timezone, user.locale || user.language);
+
+  // The routine name is intentionally NOT repeated here: the filed record already
+  // opens on `[routine: <name>]` (runner.recordRoutineTurn), so a second
+  // `Automation: <name>` line duplicated the slug in the delivered message. The
+  // ID + memory path identify the automation without that echo.
+  const lines = [
+    `Automation ID: ${routine?.id || "—"}`,
+  ];
+  if (memPath) lines.push(`Automation memory: ${memPath}`);
+  lines.push(`Last run: ${lastMs ? machineStamp(lastMs) : "never"}`);
+  // The clock is labelled so the UTC machine stamp (…Z) reads as distinct from
+  // the owner's local wall-clock: same instant, two frames of reference.
+  lines.push(
+    `This run (UTC): ${machineStamp(now)}${local ? `\nThis run (owner local time): ${local}` : ""}`,
+  );
+  return lines.join("\n");
+}
+
+/**
+ * Prepend the header to a prompt body, separated by a blank line. A non-string
+ * body (a spec that has no prompt/text) passes through untouched.
+ */
+export function prependRoutineHeader(prompt, header) {
+  if (typeof prompt !== "string" || !header) return prompt;
+  return `${header}\n\n${prompt}`;
+}

package/src/core/routines/index.js

@@ -14,3 +14,29 @@ export {
 } from "#core/stores/routines.js";
 
 export { runRoutineNow } from "./runner.js";
+
+// Runtime state of a run (in flight) and its history (already made). Both are
+// "what happened to this routine", asked from every surface, so they belong in
+// the same entry point as the CRUD and the runner.
+export {
+  startRoutineRun,
+  getRoutineRun,
+  listRoutineRuns,
+  RUN_PHASES,
+} from "./active-runs.js";
+
+export {
+  listRoutineRunLog,
+  isRoutineRunRow,
+  runRowStatus,
+  RUN_STATUS,
+} from "./run-log.js";
+
+export {
+  deliveryChannelIds,
+  normalizeDeliverTo,
+  resolveDeliveryChannels,
+  PROFILE_DELIVERY,
+  NO_DELIVERY,
+} from "./delivery.js";
+

package/src/core/routines/run-log.js

@@ -0,0 +1,78 @@
+// The runs a routine has ALREADY made, read back out of the ledger.
+//
+// There is no runs table: a run leaves exactly one summary row — the runner's
+// end-of-run system message (runner.js) carrying meta.status, meta.result and
+// meta.flow. The ledger is the record, and this module is the one place that
+// knows how to read it back.
+//
+// The catch, and the bug this fixes: `meta.routine` is NOT the mark of a run.
+// The CRUD route stamps it on "routine X created / updated" rows too
+// (host/daemon/api/routines.js), and those are `system` rows from the same
+// actor. The panel filtered on actor + meta.routine, so EDITING a routine
+// appended a row to its execution history — and since an edit carries no
+// meta.status, the list drew it as a successful run. A routine whose header
+// said "last run: 3 h ago" showed a run that had supposedly finished minutes
+// ago, which is worse than showing nothing.
+//
+// What actually marks a run is `meta.status`. Only the runner writes it.
+import { readProjectMessages } from "#core/stores/messages.js";
+import { CHANNELS } from "#core/constants/channels.js";
+
+/** The statuses a finished run can carry, as the surfaces name them. */
+export const RUN_STATUS = { OK: "ok", ERROR: "error", SKIPPED: "skipped" };
+
+/** Is this ledger row the summary of a RUN (as opposed to a CRUD event)? */
+export function isRoutineRunRow(row, name) {
+  const meta = row?.meta || {};
+  if (name && meta.routine !== name) return false;
+  if (!meta.routine) return false;
+  // A CRUD row names its event and carries no status; a run carries a status
+  // and no event. Checking both ways means a future event type cannot sneak in.
+  if (meta.event) return false;
+  return typeof meta.status === "string" && meta.status.length > 0;
+}
+
+/** ok / error / skipped — what the row's status and skip flag amount to. */
+export function runRowStatus(row) {
+  const meta = row?.meta || {};
+  if (meta.skipped) return RUN_STATUS.SKIPPED;
+  return meta.status === RUN_STATUS.ERROR ? RUN_STATUS.ERROR : RUN_STATUS.OK;
+}
+
+/**
+ * One run, in the shape a surface renders — so no caller has to know that a run
+ * is a message with a particular meta on it. `conversation_id` + `agent_slug`
+ * are lifted out of the result because they are what "open this run's chat"
+ * needs, and digging for them was why the link only ever existed in one place.
+ */
+export function shapeRoutineRun(row) {
+  const meta = row?.meta || {};
+  const result = meta.result || {};
+  return {
+    ts: row.ts,
+    routine: meta.routine,
+    status: runRowStatus(row),
+    skipped: !!meta.skipped,
+    body: row.body || "",
+    result,
+    flow: meta.flow || null,
+    conversation_id: typeof result.conversation_id === "string" ? result.conversation_id : null,
+    agent_slug: typeof result.agent_slug === "string" ? result.agent_slug : null,
+  };
+}
+
+/**
+ * A routine's run history, newest first.
+ *
+ * Reads more rows than it returns on purpose: one run writes a row per tool
+ * call plus its summary, so the summaries of 50 runs are scattered through
+ * hundreds of rows, and every routine in the project shares this channel. The
+ * scan window is the ceiling on how far back "the last N runs" can see, not on
+ * how many come back. 1000 is also readProjectMessages' own hard cap.
+ */
+export function listRoutineRunLog(projectRoot, name, { limit = 50, scan = 1000 } = {}) {
+  // Newest first already — readProjectMessages sorts descending and then slices,
+  // so the scan window is the most recent `scan` rows of the routine channel.
+  const rows = readProjectMessages(projectRoot, { channel: CHANNELS.ROUTINE, limit: scan });
+  return rows.filter((r) => isRoutineRunRow(r, name)).map(shapeRoutineRun).slice(0, limit);
+}