@agent-native/core 0.168.12 → 0.169.0

package/dist/jobs/run-history.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
+import { resolveBackgroundRunHardTimeoutMs } from "../agent/run-manager.js";
 import { getDbExec, intType, isPostgres } from "../db/client.js";
 import { ensureColumnExists, ensureIndexExists, ensureTableExists, } from "../db/ddl-guard.js";
 import { runMigrations } from "../db/migrations.js";
@@ -17,20 +18,38 @@ registerEvent({
         threadId: z.string().nullable(),
         status: z.enum(["success", "error", "interrupted"]),
         error: z.string().nullable(),
+        errorCode: z.string().nullable(),
+        /** Wall-clock from `started_at` to now. Null when the row predates the
+         *  start timestamp being readable, so "not measured" stays distinct from
+         *  "took no time". */
+        durationMs: z.number().nullable(),
     }),
 });
 const TABLE = "automation_runs";
 const MAX_ERROR_LENGTH = 500;
+const MAX_ERROR_CODE_LENGTH = 100;
 /**
- * Generous multiple of the runner's own 10 minute hard abort
- * (BACKGROUND_RUN_HARD_TIMEOUT_MS). Past this, no run is still alive.
+ * Past this, no run of this automation is still alive.
+ *
+ * DERIVED from the runner's own hard abort rather than pinned, because that
+ * abort became configurable: a fixed 15 minutes against a longer configured
+ * timeout would report a still-executing run as `interrupted` and expire its
+ * claim lease, redispatching it on top of itself. Half again the abort leaves
+ * room for wind-down and the terminal write without ever preceding them.
  */
-const RUN_LIVENESS_CEILING_MS = 15 * 60_000;
+function resolveRunLivenessCeilingMs() {
+    return Math.ceil(resolveBackgroundRunHardTimeoutMs() * 1.5);
+}
 const INTERRUPTED_RUN_MESSAGE = "Worker stopped before a terminal result was recorded. The serverless worker may have timed out or been recycled. No delivery was confirmed.";
-// The background worker has a shorter hard timeout than this lease. A worker
-// that dies after claiming can therefore be redelivered without overlapping a
-// still-live execution under normal runtime limits.
-const CLAIM_LEASE_MS = RUN_LIVENESS_CEILING_MS;
+/**
+ * Derived at read time alongside `INTERRUPTED_RUN_MESSAGE`: a process killed
+ * mid-run cannot write its own code any more than it can write its own message.
+ */
+const INTERRUPTED_RUN_ERROR_CODE = "background_automation_interrupted";
+// The background worker's hard timeout is always shorter than this lease, by
+// construction above. A worker that dies after claiming can therefore be
+// redelivered without overlapping a still-live execution.
+const claimLeaseMs = () => resolveRunLivenessCeilingMs();
 /** Rows kept per automation, so a per-minute schedule cannot grow forever. */
 const RUNS_RETAINED_PER_AUTOMATION = 50;
 /** Authoritative release-time schema for durable automation history. */
@@ -76,6 +95,11 @@ export const AUTOMATION_RUN_MIGRATIONS = [
         name: "automation-runs-app-id",
         sql: `ALTER TABLE ${TABLE} ADD COLUMN IF NOT EXISTS app_id TEXT`,
     },
+    {
+        version: 5,
+        name: "automation-runs-error-code",
+        sql: `ALTER TABLE ${TABLE} ADD COLUMN IF NOT EXISTS error_code TEXT`,
+    },
 ];
 export async function runAutomationRunMigrations(nitroApp) {
     await runMigrations(AUTOMATION_RUN_MIGRATIONS, {
@@ -102,6 +126,7 @@ export async function ensureTable() {
           started_at ${intType()} NOT NULL,
           finished_at ${intType()},
           error TEXT,
+          error_code TEXT,
           claimed_at ${intType()},
           dispatch_pending ${intType()} NOT NULL DEFAULT 0
         )
@@ -111,6 +136,7 @@ export async function ensureTable() {
                 await ensureTableExists(TABLE, createSql);
                 await ensureColumnExists(TABLE, "claimed_at", `ALTER TABLE ${TABLE} ADD COLUMN IF NOT EXISTS claimed_at ${intType()}`);
                 await ensureColumnExists(TABLE, "dispatch_pending", `ALTER TABLE ${TABLE} ADD COLUMN IF NOT EXISTS dispatch_pending ${intType()} NOT NULL DEFAULT 0`);
+                await ensureColumnExists(TABLE, "error_code", `ALTER TABLE ${TABLE} ADD COLUMN IF NOT EXISTS error_code TEXT`);
                 await ensureIndexExists(`idx_${TABLE}_owner_automation`, indexSql);
                 return;
             }
@@ -121,6 +147,7 @@ export async function ensureTable() {
                 ["claimed_at", `${intType()}`],
                 ["dispatch_pending", `${intType()} NOT NULL DEFAULT 0`],
                 ["app_id", "TEXT"],
+                ["error_code", "TEXT"],
             ]) {
                 if (columns.has(name))
                     continue;
@@ -146,7 +173,7 @@ export async function ensureTable() {
 function toRun(row, now) {
     const stored = String(row.status);
     const startedAt = Number(row.started_at);
-    const status = stored === "running" && now - startedAt > RUN_LIVENESS_CEILING_MS
+    const status = stored === "running" && now - startedAt > resolveRunLivenessCeilingMs()
         ? "interrupted"
         : stored;
     return {
@@ -167,6 +194,11 @@ function toRun(row, now) {
             : row.error == null
                 ? null
                 : String(row.error),
+        errorCode: row.error_code == null && status === "interrupted"
+            ? INTERRUPTED_RUN_ERROR_CODE
+            : row.error_code == null
+                ? null
+                : String(row.error_code),
     };
 }
 /**
@@ -212,7 +244,7 @@ export async function claimAutomationRun(id) {
     const now = Date.now();
     const result = await getDbExec().execute({
         sql: `UPDATE ${TABLE} SET claimed_at = ? WHERE id = ? AND dispatch_pending = 1 AND (claimed_at IS NULL OR claimed_at <= ?) AND status = 'running'`,
-        args: [now, id, now - CLAIM_LEASE_MS],
+        args: [now, id, now - claimLeaseMs()],
     });
     return Number(result.rowsAffected ?? 0) > 0;
 }
@@ -234,7 +266,7 @@ export async function listUnclaimedAutomationRuns(options) {
             AND started_at <= ?
           ORDER BY started_at ASC LIMIT ${limit}`,
         args: [
-            Date.now() - CLAIM_LEASE_MS,
+            Date.now() - claimLeaseMs(),
             ...(appId ? [appId] : []),
             Date.now() - olderThanMs,
         ],
@@ -263,19 +295,28 @@ async function pruneAutomationRuns(owner, automation) {
         args: [owner, automation, owner, automation],
     });
 }
-export async function finishAutomationRun(id, status, error) {
+export async function finishAutomationRun(id, status, error, errorCode) {
     await ensureTable();
     const existing = await getDbExec().execute({
-        sql: `SELECT owner, automation, path, org_id, run_id, thread_id FROM ${TABLE} WHERE id = ? LIMIT 1`,
+        sql: `SELECT owner, automation, path, org_id, run_id, thread_id, started_at FROM ${TABLE} WHERE id = ? LIMIT 1`,
         args: [id],
     });
     const row = existing.rows?.[0];
+    const finishedAt = Date.now();
     await getDbExec().execute({
-        sql: `UPDATE ${TABLE} SET status = ?, finished_at = ?, error = ? WHERE id = ?`,
-        args: [status, Date.now(), error?.slice(0, MAX_ERROR_LENGTH) ?? null, id],
+        sql: `UPDATE ${TABLE} SET status = ?, finished_at = ?, error = ?, error_code = ? WHERE id = ?`,
+        args: [
+            status,
+            finishedAt,
+            error?.slice(0, MAX_ERROR_LENGTH) ?? null,
+            errorCode?.slice(0, MAX_ERROR_CODE_LENGTH) ?? null,
+            id,
+        ],
     });
     if (!row)
         return;
+    const rawStartedAt = Number(row.started_at);
+    const startedAt = Number.isFinite(rawStartedAt) ? rawStartedAt : null;
     try {
         emitBusEvent("automation.run.finished", {
             automationRunId: id,
@@ -287,6 +328,8 @@ export async function finishAutomationRun(id, status, error) {
             threadId: row.thread_id == null ? null : String(row.thread_id),
             status,
             error: error?.slice(0, MAX_ERROR_LENGTH) ?? null,
+            errorCode: errorCode?.slice(0, MAX_ERROR_CODE_LENGTH) ?? null,
+            durationMs: startedAt === null ? null : Math.max(0, finishedAt - startedAt),
         }, { owner: String(row.owner) });
     }
     catch (eventError) {

package/dist/notifications/routes.d.ts

@@ -11,14 +11,14 @@
  *   DELETE /_agent-native/notifications/:id         — delete
  */
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
-    error?: undefined;
     count: number;
     updated?: undefined;
+    error?: undefined;
     ok?: undefined;
 } | {
-    error?: undefined;
     count?: undefined;
     updated: number;
+    error?: undefined;
     ok?: undefined;
 } | {
     count?: undefined;
@@ -26,8 +26,8 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     count?: undefined;
     updated?: undefined;
+    error?: undefined;
     ok: boolean;
 }>>;

package/dist/observability/traces.d.ts

@@ -44,6 +44,19 @@ export declare function instrumentAgentLoop(opts: {
      *  reads. */
     userId: string | null;
     config: ObservabilityConfig;
+    /**
+     * Name for this run's root span, in the local trace store and in PostHog LLM
+     * analytics. Defaults to `"agent_run"`. Without it every path emits the same
+     * name and a scheduled automation is indistinguishable from a chat turn in
+     * the one view where telling them apart is the whole question.
+     */
+    spanName?: string;
+    /**
+     * Free-form run context. Persisted onto the local store's parent span AND
+     * forwarded to PostHog as trace properties — a channel that reached only the
+     * SQL store was a channel that could not answer "which automation was this?"
+     * in LLM analytics.
+     */
     metadata?: Record<string, unknown> | null;
     experimentAssignments?: Array<{
         experimentId: string;