@agent-native/core 0.168.12 → 0.169.0

package/dist/client/EnvironmentBadge.js

@@ -16,7 +16,9 @@ export function isAgentNativeDesktopUserAgent(userAgent) {
 }
 export function resolveEnvironmentChannel(config, hostname) {
     const configured = config.deployment?.environment;
-    if (configured === "beta" || configured === "production") {
+    if (configured === "local" ||
+        configured === "beta" ||
+        configured === "production") {
         return configured;
     }
     const targets = resolveEnvironmentTargets(hostname);
@@ -74,6 +76,7 @@ function consumeBetaOptOutQueryParam(sourceHref, now = Date.now()) {
     }
     return active;
 }
+const environmentBadgePlacementClasses = "fixed bottom-3 left-3 z-[100] h-6 min-w-0 rounded-xl px-2 text-[11px] font-semibold uppercase tracking-[0.5px] shadow-sm backdrop-blur-sm";
 function EnvironmentLink({ label, href }) {
     return (_jsx(Button, { asChild: true, className: "w-full justify-center", size: "sm", variant: "outline", children: _jsx("a", { href: href, children: label }) }));
 }
@@ -89,9 +92,12 @@ function EnvironmentBadgeContent({ environment, targets, }) {
     const title = environment === "beta"
         ? "You're on Agent Native Beta"
         : "You're on Agent Native Production";
-    return (_jsxs(Popover, { children: [_jsx(PopoverTrigger, { asChild: true, children: _jsx(Button, { "aria-label": `Open ${title.toLowerCase()} switcher`, className: cn("fixed bottom-3 right-3 z-[100] h-6 min-w-0 rounded-xl px-2 text-[11px] font-semibold uppercase tracking-[0.5px] shadow-sm backdrop-blur-sm", environment === "beta"
+    return (_jsxs(Popover, { children: [_jsx(PopoverTrigger, { asChild: true, children: _jsx(Button, { "aria-label": `Open ${title.toLowerCase()} switcher`, className: cn(environmentBadgePlacementClasses, environment === "beta"
                         ? "border-primary/80"
-                        : "border-border/80 bg-background/95 text-foreground"), size: "sm", variant: environment === "beta" ? "default" : "outline", children: label }) }), _jsxs(PopoverContent, { align: "center", className: "w-[280px] p-5", side: "top", sideOffset: 8, children: [_jsx("div", { className: "mb-1 text-sm font-semibold leading-5", children: title }), _jsx("div", { className: "mb-4 text-sm text-muted-foreground", children: "Choose where you want to continue." }), _jsx("div", { className: "grid gap-2", children: environment === "beta" ? (_jsx(EnvironmentLink, { href: productionHref, label: "Switch to production" })) : (_jsx(EnvironmentLink, { href: betaHref, label: "Go to beta" })) })] })] }));
+                        : "border-border/80 bg-background/95 text-foreground"), size: "sm", variant: environment === "beta" ? "default" : "outline", children: label }) }), _jsxs(PopoverContent, { align: "start", className: "w-[280px] p-5", side: "top", sideOffset: 8, children: [_jsx("div", { className: "mb-1 text-sm font-semibold leading-5", children: title }), _jsx("div", { className: "mb-4 text-sm text-muted-foreground", children: "Choose where you want to continue." }), _jsx("div", { className: "grid gap-2", children: environment === "beta" ? (_jsx(EnvironmentLink, { href: productionHref, label: "Switch to production" })) : (_jsx(EnvironmentLink, { href: betaHref, label: "Go to beta" })) })] })] }));
+}
+function LocalEnvironmentBadge() {
+    return (_jsx("div", { "aria-label": "Local development environment", className: cn(environmentBadgePlacementClasses, "inline-flex items-center justify-center border border-border/80 bg-background/95 text-foreground"), role: "status", children: "dev" }));
 }
 function ProductionEnvironmentBadge({ targets, }) {
     const { session, status } = useSession();
@@ -128,9 +134,10 @@ function ProductionEnvironmentBadge({ targets, }) {
     return _jsx(EnvironmentBadgeContent, { environment: "production", targets: targets });
 }
 /**
- * First-party hosted lane switcher. Beta is intentionally visible before
- * authentication so a visitor can always leave beta from the sign-in page.
- * Production remains an internal auto-redirect lane for authenticated staff.
+ * Environment indicator and first-party hosted lane switcher. Beta is
+ * intentionally visible before authentication so a visitor can always leave
+ * beta from the sign-in page. Production remains an internal auto-redirect
+ * lane for authenticated staff.
  */
 export function EnvironmentBadge({ showProduction = true, } = {}) {
     const config = useMemo(injectedAgentNativeConfig, []);
@@ -139,10 +146,14 @@ export function EnvironmentBadge({ showProduction = true, } = {}) {
     const targets = resolveEnvironmentTargets(hostname);
     if (typeof window === "undefined" ||
         window.parent !== window ||
-        !environment ||
-        !targets) {
+        !environment) {
         return null;
     }
+    if (environment === "local") {
+        return _jsx(LocalEnvironmentBadge, {});
+    }
+    if (!targets)
+        return null;
     if (environment === "beta") {
         return _jsx(EnvironmentBadgeContent, { environment: "beta", targets: targets });
     }

package/dist/client/agent-chat-adapter.d.ts

@@ -15,8 +15,6 @@ export type AgentChatSurfaceKind =
  | "desktop";
 export declare const BACKGROUND_FOLLOW_ATTACH_WATCHDOG_MS = 90000;
 export declare const BACKGROUND_FOLLOW_IDLE_TIMEOUT_MS = 210000;
-export declare const MAX_FOLLOWED_BACKGROUND_RUNS = 24;
-export declare const MAX_BACKGROUND_FOLLOW_WALL_TIME_MS: number;
 /**
  * True when an action was streamed but never returned a result yet — i.e. a
  * `tool_start` with no matching `tool_done`. The server is still executing it,

package/dist/client/agent-chat-adapter.js

@@ -170,29 +170,13 @@ export const BACKGROUND_FOLLOW_IDLE_TIMEOUT_MS = 210_000;
 // 22 minutes, all error:stale_run, user watching a spinner). These bound the
 // whole turn instead, and an identical repeated failure counts as no progress.
 //
-// CLIENT-ABOVE-SERVER INVARIANT (asserted in agent-chat-adapter.spec.ts).
-// These are a backstop for a server that has gone silent in a way the idle
-// timeout misses — NOT the primary limit. They must stay ABOVE the server's
-// own ceilings so the server, which can actually tell progress from looping,
-// always terminates a turn first and writes a truthful terminal reason:
-//   BACKGROUND_SOFT_TIMEOUT_CEILING_MS  (13 min, run-manager.ts)  — one chunk
-//   MAX_TURN_WALL_CLOCK_MS              (90 min, production-agent.ts) — one turn
-//   MAX_BACKGROUND_RUN_CONTINUATIONS    (20,     production-agent.ts)
-//
-// They were originally set to 10 min / 6 runs, which put the whole-turn client
-// budget BELOW the 13-minute ceiling of a single legal chunk. Any turn needing
-// a second full-length chunk was killed by the client while the server was
-// healthy and had 80 minutes left — measured in prod as turns dying at 11-25
-// minutes with `last_progress_at` tracking the abort, i.e. still streaming
-// tokens and completing tools when the client gave up. That is the top
-// non-auth cause of "the chat just stopped" reports.
-//
-// Killing a turn that is NOT progressing is already covered twice over, by
-// mechanisms that read progress rather than a clock: the 210s idle timeout
-// above, and MAX_REPEATED_BACKGROUND_TERMINAL_REASONS below. Do not re-tighten
-// these two to catch a stuck turn — fix the progress signal instead.
-export const MAX_FOLLOWED_BACKGROUND_RUNS = 24;
-export const MAX_BACKGROUND_FOLLOW_WALL_TIME_MS = 95 * 60_000;
+// Defined in `app-config/run-lifecycle-invariants.ts`, not here, because the
+// CLIENT-ABOVE-SERVER relationship they belong to is checked there against the
+// RESOLVED server configuration — the server bounds are runtime-configurable
+// now, so a spec pinning them against module constants stopped enforcing
+// anything. Re-exported under the same names so importers are unchanged; that
+// module has no runtime imports, so the bundle pays nothing for it.
+import { MAX_BACKGROUND_FOLLOW_WALL_TIME_MS, MAX_FOLLOWED_BACKGROUND_RUNS, } from "../app-config/run-lifecycle-invariants.js";
 const MAX_REPEATED_BACKGROUND_TERMINAL_REASONS = 3;
 // A re-observed terminal run whose outcome would be an ERROR (never a
 // genuine "done" success) gets a short extra grace window before the follow

package/dist/client/app-providers.d.ts

@@ -39,7 +39,8 @@
  *   toaster                  — custom Toaster element rendered after children.
  *                              Pass `null` to suppress the built-in Toaster when
  *                              children already include a styled one.
- *                              Defaults to `<Toaster richColors position="bottom-left" />`.
+ *                              Defaults to a rich-color bottom-left toaster raised above
+ *                              the environment badge.
  *   disableThemeTransitions  — passed to next-themes ThemeProvider
  *                              `disableTransitionOnChange`. Defaults to `true`
  *                              (suppresses CSS transitions during theme switches,
@@ -75,7 +76,7 @@ export interface AppProvidersProps {
      * Custom Toaster element rendered after children inside TooltipProvider.
      * Pass `null` to suppress the built-in Toaster when children already
      * include a styled one.
-     * Defaults to `<Toaster richColors position="bottom-left" />`.
+     * Defaults to a rich-color bottom-left toaster raised above the environment badge.
      */
     toaster?: React.ReactNode | null;
     /**

package/dist/client/app-providers.js

@@ -40,7 +40,8 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
  *   toaster                  — custom Toaster element rendered after children.
  *                              Pass `null` to suppress the built-in Toaster when
  *                              children already include a styled one.
- *                              Defaults to `<Toaster richColors position="bottom-left" />`.
+ *                              Defaults to a rich-color bottom-left toaster raised above
+ *                              the environment badge.
  *   disableThemeTransitions  — passed to next-themes ThemeProvider
  *                              `disableTransitionOnChange`. Defaults to `true`
  *                              (suppresses CSS transitions during theme switches,
@@ -65,7 +66,7 @@ import { AgentNativeRouteWarmup } from "./route-warmup.js";
 import { RouteTransitionIndicator } from "./RouteTransitionIndicator.js";
 import { RuntimeConfigNotice } from "./RuntimeConfigNotice.js";
 import { EMBEDDED_THEME_CHANGE_EVENT, applyEmbeddedThemeUpdate, parseEmbeddedThemeUpdate, } from "./theme.js";
-const DEFAULT_TOASTER = _jsx(Toaster, { richColors: true, position: "bottom-left" });
+const DEFAULT_TOASTER = (_jsx(Toaster, { richColors: true, position: "bottom-left", offset: { bottom: 44, left: 32 }, mobileOffset: { bottom: 44, left: 16 } }));
 function RoutedAppEnhancements() {
     const isInRouter = useInRouterContext();
     if (!isInRouter)

package/dist/collab/awareness.d.ts

@@ -62,11 +62,11 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
-    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
+    error?: undefined;
 }>>;
 /**
  * GET /_agent-native/collab/:docId/users
@@ -77,9 +77,9 @@ export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("
     error: string;
     users?: undefined;
 } | {
-    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
+    error?: undefined;
 }>>;

package/dist/collab/routes.d.ts

@@ -26,8 +26,8 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
  * Body: { update: string (base64), requestSource?: string }
  */
 export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/jobs/background-automation-runner.d.ts

@@ -5,7 +5,23 @@ import { type AutomationExecutionIdentity } from "../automations/service.js";
 import { type Resource } from "../resources/store.js";
 import { type RequestContext } from "../server/request-context.js";
 import type { JobFrontmatter } from "./frontmatter.js";
+/**
+ * Default hard abort for one in-process automation run. Read through
+ * `resolveBackgroundRunHardTimeoutMs()` at the use site — this is the host's
+ * real function budget for scheduled work, and it differs by deployment.
+ */
 export declare const BACKGROUND_RUN_HARD_TIMEOUT_MS: number;
+/**
+ * Terminal failure of a background automation, carrying the machine-readable
+ * code the failure taxonomy already computes.
+ *
+ * The code used to be produced and then dropped, so "how often are runs cut
+ * off?" was a `LIKE '%no_progress%'` over an English sentence.
+ */
+export declare class BackgroundAutomationRunError extends Error {
+    readonly errorCode: string;
+    constructor(message: string, errorCode: string);
+}
 export interface BackgroundAutomationContext {
     name: string;
     meta: JobFrontmatter;
@@ -35,6 +51,15 @@ export interface BackgroundAutomationRunOptions {
     actionAutomation?: ActionAutomationContext;
     /** Reuse a history row created by a durable run-now enqueue. */
     historyId?: string;
+    /**
+     * Per-run overrides for the run-manager no-progress backstop. `startRun` has
+     * always accepted these; the automation path had no way to reach them, and
+     * the one indirect route (zeroing `agent.runSoftTimeoutMs`) is global and
+     * would strip foreground chat of its chunk boundary. Additive: unset means
+     * the configured/default behaviour, unchanged.
+     */
+    noProgressTimeoutMs?: number;
+    backgroundNoProgressTimeoutMs?: number;
 }
 export interface BackgroundAutomationRunResult {
     responseText: string;

package/dist/jobs/background-automation-runner.js

@@ -2,7 +2,7 @@ import { collectFinalResponseTextFromAgentEvents } from "../a2a/response-text.js
 import { getStoredModelForEngine, normalizeModelForEngine, resolveEngine, } from "../agent/engine/index.js";
 import { actionsToEngineTools, filterInitialEngineTools, getOwnerActiveApiKey, } from "../agent/production-agent.js";
 import { runAgentLoopDirectWithSoftTimeout } from "../agent/run-loop-with-resume.js";
-import { resolveRunSoftTimeoutMs, startRun, } from "../agent/run-manager.js";
+import { abortRun, resolveBackgroundAutomationSoftTimeoutMs, resolveBackgroundRunHardTimeoutMs, startRun, } from "../agent/run-manager.js";
 import { claimBackgroundRun, insertRun } from "../agent/run-store.js";
 import { buildAssistantMessage, buildUserMessage, extractThreadMeta, foldAssistantTurn, upsertUserMessage, } from "../agent/thread-data-builder.js";
 import { attachToolSearch } from "../agent/tool-search.js";
@@ -13,8 +13,27 @@ import { organizationIdFromResourceOwner, organizationResourceOwner, } from "../
 import { captureError } from "../server/capture-error.js";
 import { runWithRequestContext, } from "../server/request-context.js";
 import { attachAutomationRunThread, finishAutomationRun, startAutomationRun, } from "./run-history.js";
-const BACKGROUND_RUN_STUCK_MS = 10 * 60_000;
+/**
+ * Default hard abort for one in-process automation run. Read through
+ * `resolveBackgroundRunHardTimeoutMs()` at the use site — this is the host's
+ * real function budget for scheduled work, and it differs by deployment.
+ */
 export const BACKGROUND_RUN_HARD_TIMEOUT_MS = 10 * 60_000;
+/**
+ * Terminal failure of a background automation, carrying the machine-readable
+ * code the failure taxonomy already computes.
+ *
+ * The code used to be produced and then dropped, so "how often are runs cut
+ * off?" was a `LIKE '%no_progress%'` over an English sentence.
+ */
+export class BackgroundAutomationRunError extends Error {
+    errorCode;
+    constructor(message, errorCode) {
+        super(message);
+        this.name = "BackgroundAutomationRunError";
+        this.errorCode = errorCode;
+    }
+}
 /**
  * A persisted background run must not outlive its execution identity.
  * Organization runs fail closed when membership state cannot be read. A
@@ -112,8 +131,11 @@ export function isBackgroundAutomationRunActive(meta, now = new Date()) {
     if (!meta.lastRun)
         return false;
     const startedAt = new Date(meta.lastRun).getTime();
+    // Tracks the hard abort: past it no run of this automation is still alive, so
+    // a deployment that raises the abort must not have its live runs treated as
+    // stuck and re-dispatched underneath themselves.
     return (Number.isFinite(startedAt) &&
-        now.getTime() - startedAt < BACKGROUND_RUN_STUCK_MS);
+        now.getTime() - startedAt < resolveBackgroundRunHardTimeoutMs());
 }
 /**
  * A soft-timeout/no-progress checkpoint is a continuation boundary, not a
@@ -186,6 +208,9 @@ export async function runBackgroundAutomation(options, deps) {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        const errorCode = err instanceof BackgroundAutomationRunError
+            ? err.errorCode
+            : "background_automation_failed";
         // Both callers (recurring-jobs scheduler, trigger dispatcher) record this
         // onto the automation's own metadata and console.error it, and neither
         // reports it. A failure visible only in a resource field and stdout is not
@@ -204,7 +229,7 @@ export async function runBackgroundAutomation(options, deps) {
             },
             ...(runIdRef.current ? { aiTraceId: runIdRef.current } : {}),
         });
-        await recordRunOutcome(historyId, "error", `${message}. No delivery was confirmed.`);
+        await recordRunOutcome(historyId, "error", `${message}. No delivery was confirmed.`, errorCode);
         throw err;
     }
     // Outside the try: history is bookkeeping about the run, so a failure to
@@ -229,8 +254,9 @@ async function recordRunThread(historyId, threadId, runId) {
 }
 function backgroundAutomationPersistFailure(input) {
     if (input.hardTimedOut) {
+        const minutes = Math.round((input.hardTimeoutMs ?? BACKGROUND_RUN_HARD_TIMEOUT_MS) / 60_000);
         return {
-            message: `Background automation timed out after ${BACKGROUND_RUN_HARD_TIMEOUT_MS / 60_000} minutes`,
+            message: `Background automation timed out after ${minutes} minutes`,
             errorCode: "background_automation_hard_timeout",
         };
     }
@@ -301,11 +327,11 @@ async function persistBackgroundAutomationTurn(input) {
         await updateThreadData(input.threadId, JSON.stringify(repo), input.threadTitle || row.title, meta.preview || row.preview, Array.isArray(messages) ? messages.length : 0);
     });
 }
-async function recordRunOutcome(historyId, status, error) {
+async function recordRunOutcome(historyId, status, error, errorCode) {
     if (!historyId)
         return;
     try {
-        await finishAutomationRun(historyId, status, error);
+        await finishAutomationRun(historyId, status, error, errorCode);
     }
     catch (err) {
         console.error(`[automations] Could not record run ${historyId} as ${status}:`, err);
@@ -372,12 +398,15 @@ async function executeBackgroundAutomation(options, deps, historyId, runIdRef) {
         // Hardcoded rather than `isInBackgroundFunctionRuntime()` (what
         // webhook-handler.ts uses): a webhook can arrive on either runtime, but
         // a scheduler tick never serves a synchronous request, so the
-        // interactive clamp never applies to it. The wider soft ceiling stays
-        // bounded by this runner's own BACKGROUND_RUN_HARD_TIMEOUT_MS abort.
-        const softTimeoutMs = resolveRunSoftTimeoutMs(undefined, {
-            useHostedDefault: true,
-            backgroundFunction: true,
-        });
+        // interactive clamp never applies to it.
+        //
+        // Derived from this runner's OWN hard abort, not from the durable-chat
+        // background ceiling: that ceiling is 13 minutes and this process is
+        // killed at 10, so taking it left the recoverable soft-timeout boundary
+        // as dead code and the terminal no-progress backstop as the only
+        // boundary an automation could reach.
+        const hardTimeoutMs = resolveBackgroundRunHardTimeoutMs();
+        const softTimeoutMs = resolveBackgroundAutomationSoftTimeoutMs();
         const usageRef = { current: null };
         let responseText = "";
         let hardAbortTimer = null;
@@ -400,8 +429,8 @@ async function executeBackgroundAutomation(options, deps, historyId, runIdRef) {
             throw new Error(`Background automation "${automation.name}" (run "${runId}") could not claim its own freshly-inserted run row`);
         }
         await new Promise((resolve, reject) => {
-            const activeRun = startRun(runId, thread.id, async (send, signal) => {
-                usageRef.current = await runAgentLoopDirectWithSoftTimeout({
+            const activeRun = startRun(runId, thread.id, async (send, signal, control) => {
+                const loopOpts = {
                     engine,
                     model,
                     systemPrompt,
@@ -425,7 +454,45 @@ async function executeBackgroundAutomation(options, deps, historyId, runIdRef) {
                     runId,
                     maxIterations: automation.meta.maxIterations,
                     maxRunInputTokens: automation.meta.maxRunInputTokens,
-                }, softTimeoutMs, { backgroundFunction: true });
+                };
+                // Same adapter A2A uses: bridge this runner's multi-argument shape
+                // to the single-argument `runAgentLoop` `instrumentAgentLoop`
+                // expects. `control` is what lets a chunk boundary be recovered
+                // here instead of ending the turn.
+                const execute = (o = loopOpts) => runAgentLoopDirectWithSoftTimeout(o, softTimeoutMs, { backgroundFunction: true }, control);
+                let instrumented = false;
+                try {
+                    const { getObservabilityConfig, instrumentAgentLoop } = await import("../observability/traces.js");
+                    const config = await getObservabilityConfig();
+                    if (config.enabled) {
+                        instrumented = true;
+                        usageRef.current = await instrumentAgentLoop({
+                            runAgentLoop: (o) => execute(o),
+                            loopOpts,
+                            runId,
+                            threadId: thread.id,
+                            // A scheduled run is NOT anonymous. Passing the owner is what
+                            // makes it visible to per-user observability reads.
+                            userId: ownerEmail,
+                            config,
+                            spanName: "background_automation_run",
+                            metadata: {
+                                automation: automation.name,
+                                trigger: "background_automation",
+                                scope: orgId ? "organization" : "personal",
+                            },
+                        });
+                        return;
+                    }
+                }
+                catch (error) {
+                    // Match A2A and interactive chat: a setup failure falls through
+                    // to an uninstrumented run, but a failure from INSIDE the
+                    // instrumented loop is the real run failure and must rethrow.
+                    if (instrumented)
+                        throw error;
+                }
+                usageRef.current = await execute();
             }, async (run) => {
                 if (hardAbortTimer) {
                     clearTimeout(hardAbortTimer);
@@ -434,6 +501,7 @@ async function executeBackgroundAutomation(options, deps, historyId, runIdRef) {
                 const persistFailure = backgroundAutomationPersistFailure({
                     run,
                     hardTimedOut,
+                    hardTimeoutMs,
                 });
                 try {
                     await persistBackgroundAutomationTurn({
@@ -453,11 +521,11 @@ async function executeBackgroundAutomation(options, deps, historyId, runIdRef) {
                 if (hardTimedOut)
                     return;
                 if (persistFailure) {
-                    reject(new Error(persistFailure.message));
+                    reject(new BackgroundAutomationRunError(persistFailure.message, persistFailure.errorCode));
                     return;
                 }
                 if (run.status !== "completed") {
-                    reject(new Error(`Background automation ended with status: ${run.status}`));
+                    reject(new BackgroundAutomationRunError(`Background automation ended with status: ${run.status}`, `background_automation_${run.status}`));
                     return;
                 }
                 responseText = collectFinalResponseTextFromAgentEvents((run.events ?? []).map((entry) => entry.event));
@@ -465,22 +533,37 @@ async function executeBackgroundAutomation(options, deps, historyId, runIdRef) {
             }, {
                 softTimeoutMs,
                 backgroundFunction: true,
+                // This runner owns continuation in-process: there is no HTTP body
+                // to re-POST and no `chainServerDrivenContinuation` behind it, so a
+                // checkpoint must end the CHUNK and let the loop above recover it.
+                recoverChunkBoundaries: true,
+                // Matches the `dispatch_mode` this runner already writes onto the
+                // run row at insert. Without it the terminal and boundary analytics
+                // events reported every scheduled run as foreground.
+                dispatchMode: "background",
+                noProgressTimeoutMs: options.noProgressTimeoutMs,
+                backgroundNoProgressTimeoutMs: options.backgroundNoProgressTimeoutMs,
                 model,
                 engineName: engine.name,
+                userId: ownerEmail,
             });
             hardAbortTimer = setTimeout(() => {
                 hardAbortTimer = null;
                 if (activeRun.status !== "running")
                     return;
                 hardTimedOut = true;
-                activeRun.abort.abort("background_automation_hard_timeout");
-                const timeoutError = new Error(`Background automation timed out after ${BACKGROUND_RUN_HARD_TIMEOUT_MS / 60_000} minutes`);
+                // `abortRun`, not `activeRun.abort.abort`: the controller alone
+                // carries no reason the run manager can see, so finalization fell
+                // through to `aborted:user` and a hard timeout was recorded as a
+                // person pressing Stop.
+                abortRun(runId, "background_automation_hard_timeout");
+                const timeoutError = new BackgroundAutomationRunError(`Background automation timed out after ${Math.round(hardTimeoutMs / 60_000)} minutes`, "background_automation_hard_timeout");
                 void activeRun.finalized
                     .catch(() => { })
                     .then(() => {
                     reject(timeoutError);
                 });
-            }, BACKGROUND_RUN_HARD_TIMEOUT_MS);
+            }, hardTimeoutMs);
         }).finally(() => {
             if (hardAbortTimer) {
                 clearTimeout(hardAbortTimer);

package/dist/jobs/run-history.d.ts

@@ -20,6 +20,12 @@ export interface AutomationRun {
     startedAt: number;
     finishedAt: number | null;
     error: string | null;
+    /**
+     * Machine-readable failure code, so "how often are runs cut off?" is a
+     * GROUP BY instead of a LIKE over an English sentence. Null on success and
+     * on rows written before the column existed.
+     */
+    errorCode: string | null;
 }
 export interface StartAutomationRunInput {
     owner: string;
@@ -56,7 +62,7 @@ export declare function listUnclaimedAutomationRuns(options?: {
     olderThanMs?: number;
     limit?: number;
 }): Promise<AutomationRun[]>;
-export declare function finishAutomationRun(id: string, status: Exclude<AutomationRunStatus, "running">, error?: string): Promise<void>;
+export declare function finishAutomationRun(id: string, status: Exclude<AutomationRunStatus, "running">, error?: string, errorCode?: string): Promise<void>;
 /**
  * Attach the agent thread once it exists. The thread is created after the run
  * row so the history survives a crash between the two.