@agent-native/core 0.134.0 → 0.135.0

package/dist/jobs/run-history.js

@@ -0,0 +1,169 @@
+import { randomUUID } from "node:crypto";
+import { getDbExec, intType, isPostgres } from "../db/client.js";
+import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
+const TABLE = "automation_runs";
+const MAX_ERROR_LENGTH = 500;
+/**
+ * Generous multiple of the runner's own 5 minute hard abort
+ * (BACKGROUND_RUN_HARD_TIMEOUT_MS). Past this, no run is still alive.
+ */
+const RUN_LIVENESS_CEILING_MS = 15 * 60_000;
+/** Rows kept per automation, so a per-minute schedule cannot grow forever. */
+const RUNS_RETAINED_PER_AUTOMATION = 50;
+let _initPromise;
+async function ensureTable() {
+    if (!_initPromise) {
+        _initPromise = (async () => {
+            const client = getDbExec();
+            const createSql = `
+        CREATE TABLE IF NOT EXISTS ${TABLE} (
+          id TEXT PRIMARY KEY,
+          owner TEXT NOT NULL,
+          automation TEXT NOT NULL,
+          path TEXT NOT NULL,
+          scope TEXT,
+          org_id TEXT,
+          run_id TEXT,
+          thread_id TEXT,
+          status TEXT NOT NULL DEFAULT 'running',
+          started_at ${intType()} NOT NULL,
+          finished_at ${intType()},
+          error TEXT
+        )
+      `;
+            const indexSql = `CREATE INDEX IF NOT EXISTS idx_${TABLE}_owner_automation ON ${TABLE} (owner, automation, started_at)`;
+            if (isPostgres()) {
+                await ensureTableExists(TABLE, createSql);
+                await ensureIndexExists(`idx_${TABLE}_owner_automation`, indexSql);
+                return;
+            }
+            await client.execute(createSql);
+            await client.execute(indexSql);
+        })().catch((err) => {
+            _initPromise = undefined;
+            throw err;
+        });
+    }
+    return _initPromise;
+}
+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
+        ? "interrupted"
+        : stored;
+    return {
+        id: String(row.id),
+        owner: String(row.owner),
+        automation: String(row.automation),
+        path: String(row.path),
+        scope: row.scope == null ? null : String(row.scope),
+        orgId: row.org_id == null ? null : String(row.org_id),
+        runId: row.run_id == null ? null : String(row.run_id),
+        threadId: row.thread_id == null ? null : String(row.thread_id),
+        status,
+        startedAt,
+        finishedAt: row.finished_at == null ? null : Number(row.finished_at),
+        error: row.error == null ? null : String(row.error),
+    };
+}
+/**
+ * Record that an automation actually began executing. Returns the run id used
+ * to close the record out. Only real executions get a row — a tick that
+ * declined to run the automation must not appear in its history.
+ */
+export async function startAutomationRun(input) {
+    await ensureTable();
+    const id = randomUUID();
+    await getDbExec().execute({
+        sql: `INSERT INTO ${TABLE} (id, owner, automation, path, scope, org_id, run_id, thread_id, status, started_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'running', ?)`,
+        args: [
+            id,
+            input.owner,
+            input.automation,
+            input.path,
+            input.scope ?? null,
+            input.orgId ?? null,
+            input.runId ?? null,
+            input.threadId ?? null,
+            Date.now(),
+        ],
+    });
+    await pruneAutomationRuns(input.owner, input.automation);
+    return id;
+}
+/**
+ * Drop the oldest rows for one automation once it exceeds the retention cap.
+ *
+ * Pruning on insert keeps the table bounded by the number of automations
+ * rather than by how often they run, and avoids a separate sweeper. The
+ * derived table is aliased because Postgres requires it.
+ */
+async function pruneAutomationRuns(owner, automation) {
+    await getDbExec().execute({
+        sql: `DELETE FROM ${TABLE}
+          WHERE owner = ? AND automation = ? AND started_at < (
+            SELECT MIN(started_at) FROM (
+              SELECT started_at FROM ${TABLE}
+              WHERE owner = ? AND automation = ?
+              ORDER BY started_at DESC
+              LIMIT ${RUNS_RETAINED_PER_AUTOMATION}
+            ) recent
+          )`,
+        args: [owner, automation, owner, automation],
+    });
+}
+export async function finishAutomationRun(id, status, error) {
+    await ensureTable();
+    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],
+    });
+}
+/**
+ * Attach the agent thread once it exists. The thread is created after the run
+ * row so the history survives a crash between the two.
+ */
+export async function attachAutomationRunThread(id, threadId, runId) {
+    await ensureTable();
+    await getDbExec().execute({
+        sql: `UPDATE ${TABLE} SET thread_id = ?, run_id = ? WHERE id = ?`,
+        args: [threadId, runId, id],
+    });
+}
+/**
+ * Forget an automation's executions.
+ *
+ * History is keyed by the automation's name, which is reusable: deleting
+ * "digest" and creating a new "digest" would otherwise show the old
+ * definition's runs as the new one's history.
+ */
+export async function deleteAutomationRuns(owner, automation) {
+    await ensureTable();
+    // Bounded to runs that had already started. Names are reusable, so if a new
+    // automation takes this name and starts running before the cleanup lands,
+    // the cutoff keeps that run's history from being swept up with the old
+    // definition's.
+    const cutoff = Date.now();
+    await getDbExec().execute({
+        sql: `DELETE FROM ${TABLE} WHERE owner = ? AND automation = ? AND started_at <= ?`,
+        args: [owner, automation, cutoff],
+    });
+}
+export async function listAutomationRuns(options) {
+    await ensureTable();
+    const owners = options.owners.filter(Boolean);
+    if (!owners.length)
+        return [];
+    const limit = Math.min(Math.max(options.limit ?? 20, 1), 100);
+    const placeholders = owners.map(() => "?").join(", ");
+    const result = await getDbExec().execute({
+        sql: `SELECT * FROM ${TABLE} WHERE owner IN (${placeholders}) AND automation = ?
+          ORDER BY started_at DESC LIMIT ${limit}`,
+        args: [...owners, options.automation],
+    });
+    const now = Date.now();
+    return (result.rows ?? []).map((row) => toRun(row, now));
+}
+//# sourceMappingURL=run-history.js.map

package/dist/jobs/run-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-history.js","sourceRoot":"","sources":["../../src/jobs/run-history.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from \"node:crypto\";\n\nimport { getDbExec, intType, isPostgres } from \"../db/client.js\";\nimport { ensureIndexExists, ensureTableExists } from \"../db/ddl-guard.js\";\n\n/**\n * \"interrupted\" is derived at read time, never stored: a process killed\n * mid-run cannot write its own outcome, so a row left running long past the\n * point a run could still be alive is reported as interrupted rather than\n * shown as permanently in-flight.\n */\nexport type AutomationRunStatus =\n  | \"running\"\n  | \"success\"\n  | \"error\"\n  | \"interrupted\";\n\nexport interface AutomationRun {\n  id: string;\n  owner: string;\n  automation: string;\n  path: string;\n  scope: string | null;\n  orgId: string | null;\n  runId: string | null;\n  threadId: string | null;\n  status: AutomationRunStatus;\n  startedAt: number;\n  finishedAt: number | null;\n  error: string | null;\n}\n\nexport interface StartAutomationRunInput {\n  owner: string;\n  automation: string;\n  path: string;\n  scope?: string | null;\n  orgId?: string | null;\n  runId?: string | null;\n  threadId?: string | null;\n}\n\nconst TABLE = \"automation_runs\";\nconst MAX_ERROR_LENGTH = 500;\n\n/**\n * Generous multiple of the runner's own 5 minute hard abort\n * (BACKGROUND_RUN_HARD_TIMEOUT_MS). Past this, no run is still alive.\n */\nconst RUN_LIVENESS_CEILING_MS = 15 * 60_000;\n\n/** Rows kept per automation, so a per-minute schedule cannot grow forever. */\nconst RUNS_RETAINED_PER_AUTOMATION = 50;\n\nlet _initPromise: Promise<void> | undefined;\n\nasync function ensureTable(): Promise<void> {\n  if (!_initPromise) {\n    _initPromise = (async () => {\n      const client = getDbExec();\n      const createSql = `\n        CREATE TABLE IF NOT EXISTS ${TABLE} (\n          id TEXT PRIMARY KEY,\n          owner TEXT NOT NULL,\n          automation TEXT NOT NULL,\n          path TEXT NOT NULL,\n          scope TEXT,\n          org_id TEXT,\n          run_id TEXT,\n          thread_id TEXT,\n          status TEXT NOT NULL DEFAULT 'running',\n          started_at ${intType()} NOT NULL,\n          finished_at ${intType()},\n          error TEXT\n        )\n      `;\n      const indexSql = `CREATE INDEX IF NOT EXISTS idx_${TABLE}_owner_automation ON ${TABLE} (owner, automation, started_at)`;\n\n      if (isPostgres()) {\n        await ensureTableExists(TABLE, createSql);\n        await ensureIndexExists(`idx_${TABLE}_owner_automation`, indexSql);\n        return;\n      }\n\n      await client.execute(createSql);\n      await client.execute(indexSql);\n    })().catch((err) => {\n      _initPromise = undefined;\n      throw err;\n    });\n  }\n  return _initPromise;\n}\n\nfunction toRun(row: Record<string, unknown>, now: number): AutomationRun {\n  const stored = String(row.status) as AutomationRunStatus;\n  const startedAt = Number(row.started_at);\n  const status: AutomationRunStatus =\n    stored === \"running\" && now - startedAt > RUN_LIVENESS_CEILING_MS\n      ? \"interrupted\"\n      : stored;\n  return {\n    id: String(row.id),\n    owner: String(row.owner),\n    automation: String(row.automation),\n    path: String(row.path),\n    scope: row.scope == null ? null : String(row.scope),\n    orgId: row.org_id == null ? null : String(row.org_id),\n    runId: row.run_id == null ? null : String(row.run_id),\n    threadId: row.thread_id == null ? null : String(row.thread_id),\n    status,\n    startedAt,\n    finishedAt: row.finished_at == null ? null : Number(row.finished_at),\n    error: row.error == null ? null : String(row.error),\n  };\n}\n\n/**\n * Record that an automation actually began executing. Returns the run id used\n * to close the record out. Only real executions get a row — a tick that\n * declined to run the automation must not appear in its history.\n */\nexport async function startAutomationRun(\n  input: StartAutomationRunInput,\n): Promise<string> {\n  await ensureTable();\n  const id = randomUUID();\n  await getDbExec().execute({\n    sql: `INSERT INTO ${TABLE} (id, owner, automation, path, scope, org_id, run_id, thread_id, status, started_at)\n          VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'running', ?)`,\n    args: [\n      id,\n      input.owner,\n      input.automation,\n      input.path,\n      input.scope ?? null,\n      input.orgId ?? null,\n      input.runId ?? null,\n      input.threadId ?? null,\n      Date.now(),\n    ],\n  });\n  await pruneAutomationRuns(input.owner, input.automation);\n  return id;\n}\n\n/**\n * Drop the oldest rows for one automation once it exceeds the retention cap.\n *\n * Pruning on insert keeps the table bounded by the number of automations\n * rather than by how often they run, and avoids a separate sweeper. The\n * derived table is aliased because Postgres requires it.\n */\nasync function pruneAutomationRuns(\n  owner: string,\n  automation: string,\n): Promise<void> {\n  await getDbExec().execute({\n    sql: `DELETE FROM ${TABLE}\n          WHERE owner = ? AND automation = ? AND started_at < (\n            SELECT MIN(started_at) FROM (\n              SELECT started_at FROM ${TABLE}\n              WHERE owner = ? AND automation = ?\n              ORDER BY started_at DESC\n              LIMIT ${RUNS_RETAINED_PER_AUTOMATION}\n            ) recent\n          )`,\n    args: [owner, automation, owner, automation],\n  });\n}\n\nexport async function finishAutomationRun(\n  id: string,\n  status: Exclude<AutomationRunStatus, \"running\">,\n  error?: string,\n): Promise<void> {\n  await ensureTable();\n  await getDbExec().execute({\n    sql: `UPDATE ${TABLE} SET status = ?, finished_at = ?, error = ? WHERE id = ?`,\n    args: [status, Date.now(), error?.slice(0, MAX_ERROR_LENGTH) ?? null, id],\n  });\n}\n\n/**\n * Attach the agent thread once it exists. The thread is created after the run\n * row so the history survives a crash between the two.\n */\nexport async function attachAutomationRunThread(\n  id: string,\n  threadId: string,\n  runId: string,\n): Promise<void> {\n  await ensureTable();\n  await getDbExec().execute({\n    sql: `UPDATE ${TABLE} SET thread_id = ?, run_id = ? WHERE id = ?`,\n    args: [threadId, runId, id],\n  });\n}\n\n/**\n * Forget an automation's executions.\n *\n * History is keyed by the automation's name, which is reusable: deleting\n * \"digest\" and creating a new \"digest\" would otherwise show the old\n * definition's runs as the new one's history.\n */\nexport async function deleteAutomationRuns(\n  owner: string,\n  automation: string,\n): Promise<void> {\n  await ensureTable();\n  // Bounded to runs that had already started. Names are reusable, so if a new\n  // automation takes this name and starts running before the cleanup lands,\n  // the cutoff keeps that run's history from being swept up with the old\n  // definition's.\n  const cutoff = Date.now();\n  await getDbExec().execute({\n    sql: `DELETE FROM ${TABLE} WHERE owner = ? AND automation = ? AND started_at <= ?`,\n    args: [owner, automation, cutoff],\n  });\n}\n\nexport async function listAutomationRuns(options: {\n  owners: string[];\n  automation: string;\n  limit?: number;\n}): Promise<AutomationRun[]> {\n  await ensureTable();\n  const owners = options.owners.filter(Boolean);\n  if (!owners.length) return [];\n  const limit = Math.min(Math.max(options.limit ?? 20, 1), 100);\n  const placeholders = owners.map(() => \"?\").join(\", \");\n  const result = await getDbExec().execute({\n    sql: `SELECT * FROM ${TABLE} WHERE owner IN (${placeholders}) AND automation = ?\n          ORDER BY started_at DESC LIMIT ${limit}`,\n    args: [...owners, options.automation],\n  });\n  const now = Date.now();\n  return (result.rows ?? []).map((row) =>\n    toRun(row as Record<string, unknown>, now),\n  );\n}\n"]}

package/dist/jobs/scheduler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/jobs/scheduler.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,yBAAyB,EAIzB,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC9B,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,yBAAyB,GAC/B,MAAM,kBAAkB,CAAC;AAE1B,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG;IACpD,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd,CAGA;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1E;AAID,MAAM,MAAM,mBAAmB,GAAG,2BAA2B,CAAC;AAE9D,MAAM,WAAW,aAAc,SAAQ,wBAAwB;IAC7D;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,mBAAmB,KAAK,MAAM,EAAE,GAAG,SAAS,CAAC;CAC3E;AAgCD;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA0F7E;AAED,eAAO,MAAM,kBAAkB,kCAA4B,CAAC"}
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/jobs/scheduler.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,yBAAyB,EAIzB,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC9B,MAAM,mCAAmC,CAAC;AAO3C,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,yBAAyB,GAC/B,MAAM,kBAAkB,CAAC;AAE1B,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG;IACpD,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd,CAGA;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1E;AAID,MAAM,MAAM,mBAAmB,GAAG,2BAA2B,CAAC;AAE9D,MAAM,WAAW,aAAc,SAAQ,wBAAwB;IAC7D;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,mBAAmB,KAAK,MAAM,EAAE,GAAG,SAAS,CAAC;CAC3E;AAgCD;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA0F7E;AAED,eAAO,MAAM,kBAAkB,kCAA4B,CAAC"}

package/dist/jobs/scheduler.js

@@ -1,6 +1,6 @@
-import { resourceListAllOwners, resourcePut, } from "../resources/store.js";
+import { resourceGetByPath, resourceListAllOwners, resourcePut, } from "../resources/store.js";
 import { backgroundRunCutOffReason, isBackgroundAutomationRunActive, resolveBackgroundAutomationIdentity, runBackgroundAutomation, } from "./background-automation-runner.js";
-import { nextOccurrence, isValidCron, describeCron } from "./cron.js";
+import { nextOccurrence, isValidCron, describeCron, effectiveTimezone, } from "./cron.js";
 import { buildJobResourceContent, parseJobResource, } from "./frontmatter.js";
 // ─── Frontmatter parsing ────────────────────────────────────────────────────
 export { classifyJobFrontmatter, classifyJobResource, normalizeJobMcpTools, parseJobResource, } from "./frontmatter.js";
@@ -79,7 +79,7 @@ export async function processRecurringJobs(deps) {
                 // Stuck — reset so the next check can re-run it
                 meta.lastStatus = "error";
                 meta.lastError = "Job timed out or server crashed mid-run";
-                const next = nextOccurrence(meta.schedule, now);
+                const next = nextOccurrence(meta.schedule, now, meta.timezone);
                 meta.nextRun = next.toISOString();
                 await updateResource(resource, meta, body);
                 continue;
@@ -95,7 +95,7 @@ export async function processRecurringJobs(deps) {
                 // real next occurrence. Computing from new Date(0) (the epoch) always
                 // returns a 1970 date, which is < now, so the job would fire
                 // immediately on first sight regardless of its schedule.
-                const next = nextOccurrence(meta.schedule, now);
+                const next = nextOccurrence(meta.schedule, now, meta.timezone);
                 meta.nextRun = next.toISOString();
                 await updateResource(resource, meta, body);
                 continue;
@@ -146,10 +146,16 @@ async function executeJob(resource, meta, body, deps, now) {
         console.warn(`[recurring-jobs] Skipping job "${jobName}": ${identity.reason}. ` +
             `User/membership no longer valid — leaving cron entry for admin review.`);
         // Mark as skipped without resetting nextRun so an admin can find it.
-        meta.lastRun = now.toISOString();
+        // `lastRun` is deliberately untouched: the job did not run, and stamping
+        // it here made a permanently blocked job look like it ran every minute.
+        // Re-writing an unchanged resource on every tick also churns the poll
+        // stream, so only persist when the failure state actually changed.
+        const alreadyRecorded = meta.lastStatus === "skipped" && meta.lastError === identity.reason;
+        meta.lastCheck = now.toISOString();
         meta.lastStatus = "skipped";
         meta.lastError = identity.reason;
-        await updateResource(resource, meta, body);
+        if (!alreadyRecorded)
+            await updateResource(resource, meta, body);
         return;
     }
     const jobUserEmail = identity.identity.userEmail;
@@ -188,29 +194,56 @@ async function executeJob(resource, meta, body, deps, now) {
             automation: jobContext,
             ownerEmail: jobUserEmail,
             orgId: jobOrgId,
-            prompt: `[Recurring Job: ${jobName}]\nSchedule: ${describeCron(meta.schedule)}\n\nExecute the following job instructions:\n\n${body}`,
+            prompt: `[Recurring Job: ${jobName}]\nSchedule: ${describeCron(meta.schedule, effectiveTimezone(meta.timezone))}\n\nExecute the following job instructions:\n\n${body}`,
             threadTitle: `Job: ${jobName} — ${now.toLocaleDateString()}`,
             runIdPrefix: `job-${jobName}`,
             usageLabel: `recurring-job:${jobName}`,
             requestContext,
         }, deps);
-        // Compute from completion time so long runs cannot immediately re-fire.
-        meta.lastStatus = "success";
-        meta.nextRun = nextOccurrence(meta.schedule, new Date()).toISOString();
-        await updateResource(resource, meta, body);
-        console.log(`[recurring-jobs] Job "${jobName}" completed. Next run: ${meta.nextRun}`);
+        await recordExecutionOutcome(resource, {
+            lastRun: meta.lastRun,
+            lastStatus: "success",
+            lastError: undefined,
+        });
+        console.log(`[recurring-jobs] Job "${jobName}" completed.`);
     }
     catch (err) {
-        meta.lastStatus = "error";
-        meta.lastError =
-            err instanceof Error ? err.message.slice(0, 200) : "Unknown error";
-        meta.nextRun = nextOccurrence(meta.schedule, new Date()).toISOString();
-        await updateResource(resource, meta, body);
-        console.error(`[recurring-jobs] Job "${jobName}" failed:`, meta.lastError);
+        const lastError = err instanceof Error ? err.message.slice(0, 200) : "Unknown error";
+        await recordExecutionOutcome(resource, {
+            lastRun: meta.lastRun,
+            lastStatus: "error",
+            lastError,
+        });
+        console.error(`[recurring-jobs] Job "${jobName}" failed:`, lastError);
     }
 }
 async function updateResource(resource, meta, body) {
     const content = buildJobContent(meta, body);
     await resourcePut(resource.owner, resource.path, content);
 }
+/**
+ * Persist the result of a run without clobbering a concurrent edit.
+ *
+ * A run holds its `meta` for as long as the job takes, so writing that whole
+ * snapshot back on completion would silently revert a schedule, timezone or
+ * instruction change made while it was running. Only the execution fields are
+ * ours to write, and `nextRun` is recomputed from whatever schedule is stored
+ * now, so an edit mid-run takes effect on the next tick.
+ */
+async function recordExecutionOutcome(resource, outcome) {
+    const latest = await resourceGetByPath(resource.owner, resource.path);
+    if (!latest) {
+        // Deleted while it was running. Writing the pre-run snapshot back would
+        // resurrect the automation and schedule it again.
+        console.log(`[recurring-jobs] "${resource.path}" was deleted mid-run; dropping its outcome.`);
+        return;
+    }
+    const current = parseJobResource(latest.content);
+    const meta = { ...current.meta, ...outcome };
+    if (meta.schedule && isValidCron(meta.schedule)) {
+        // Measured from completion so a long run cannot immediately re-fire.
+        meta.nextRun = nextOccurrence(meta.schedule, new Date(), meta.timezone).toISOString();
+    }
+    await updateResource(resource, meta, current.body);
+}
 //# sourceMappingURL=scheduler.js.map

package/dist/jobs/scheduler.js.map

@@ -1 +1 @@
-{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../../src/jobs/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,WAAW,GAEZ,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,yBAAyB,EACzB,+BAA+B,EAC/B,mCAAmC,EACnC,uBAAuB,GAGxB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EACL,uBAAuB,EACvB,gBAAgB,GAEjB,MAAM,kBAAkB,CAAC;AAE1B,+EAA+E;AAE/E,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,GAGjB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,UAAU,mBAAmB,CAAC,OAAe;IAIjD,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACjD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAoB,EAAE,IAAY;IAChE,OAAO,uBAAuB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC7C,CAAC;AAqBD,IAAI,UAAU,GAAG,KAAK,CAAC;AAEvB,0EAA0E;AAC1E,4EAA4E;AAC5E,qEAAqE;AACrE,IAAI,aAAkC,CAAC;AACvC,IAAI,cAAc,GAAG,CAAC,CAAC;AACvB,MAAM,sBAAsB,GAAG,CAAC,GAAG,MAAM,CAAC;AAC1C,IAAI,kBAAkB,GAAG,KAAK,CAAC;AAE/B,SAAS,6BAA6B;IACpC,IAAI,kBAAkB;QAAE,OAAO;IAC/B,kBAAkB,GAAG,IAAI,CAAC;IAC1B,oDAAoD;IACpD,MAAM,CAAC,yBAAyB,CAAC;SAC9B,IAAI,CAAC,CAAC,EAAE,mBAAmB,EAAE,EAAE,EAAE;QAChC,mBAAmB,EAAE,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,KAAU,EAAE,EAAE;YACnD,IAAI,OAAO,KAAK,EAAE,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;gBACtE,aAAa,GAAG,SAAS,CAAC;YAC5B,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;SACD,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACb,OAAO,CAAC,IAAI,CACV,4CAA4C,EAC5C,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CACzC,CAAC;IACJ,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,IAAmB;IAC5D,0BAA0B;IAC1B,IAAI,UAAU;QAAE,OAAO;IAEvB,6BAA6B,EAAE,CAAC;IAEhC,mEAAmE;IACnE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,IACE,aAAa,KAAK,KAAK;QACvB,KAAK,GAAG,cAAc,GAAG,sBAAsB,EAC/C,CAAC;QACD,OAAO;IACT,CAAC;IAED,UAAU,GAAG,IAAI,CAAC;IAElB,IAAI,CAAC;QACH,MAAM,YAAY,GAAG,MAAM,qBAAqB,CAAC,OAAO,CAAC,CAAC;QAC1D,aAAa,GAAG,YAAY,CAAC,IAAI,CAC/B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAC3D,CAAC;QACF,cAAc,GAAG,KAAK,CAAC;QACvB,IAAI,CAAC,aAAa;YAAE,OAAO;QAC3B,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QAEvB,KAAK,MAAM,QAAQ,IAAI,YAAY,EAAE,CAAC;YACpC,mCAAmC;YACnC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAAE,SAAS;YAC7C,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAAE,SAAS;YAE9C,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,mBAAmB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAE7D,oCAAoC;YACpC,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ;gBAAE,SAAS;YAC9C,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC;gBAAE,SAAS;YAE1C,+EAA+E;YAC/E,8EAA8E;YAC9E,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;gBAClC,IAAI,+BAA+B,CAAC,IAAI,EAAE,GAAG,CAAC;oBAAE,SAAS;gBACzD,gDAAgD;gBAChD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC;gBAC1B,IAAI,CAAC,SAAS,GAAG,yCAAyC,CAAC;gBAC3D,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;gBAChD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;gBAClC,MAAM,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;gBAC3C,SAAS;YACX,CAAC;YAED,eAAe;YACf,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC3C,IAAI,WAAW,GAAG,GAAG;oBAAE,SAAS;YAClC,CAAC;iBAAM,CAAC;gBACN,wEAAwE;gBACxE,sEAAsE;gBACtE,6DAA6D;gBAC7D,yDAAyD;gBACzD,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;gBAChD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;gBAClC,MAAM,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;gBAC3C,SAAS;YACX,CAAC;YAED,wBAAwB;YACxB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;gBAAE,SAAS;YAE3B,kBAAkB;YAClB,MAAM,UAAU,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,yEAAyE;QACzE,yEAAyE;QACzE,wCAAwC;QACxC,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;QAC9D,IAAI,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,aAAa,GAAG,SAAS,CAAC,CAAC,yCAAyC;YACpE,cAAc,GAAG,CAAC,CAAC;YACnB,OAAO;QACT,CAAC;QACD,gGAAgG;QAChG,MAAM,MAAM,GACV,GAAG,YAAY,KAAK;YAClB,CAAC,CAAC,GAAG;YACL,CAAC,CAAC,CAAE,GAAW,EAAE,KAAK,IAAK,GAAW,EAAE,OAAO,IAAI,GAAG,CAAC,CAAC;QAC5D,OAAO,CAAC,KAAK,CAAC,yCAAyC,EAAE,MAAM,CAAC,CAAC;IACnE,CAAC;YAAS,CAAC;QACT,UAAU,GAAG,KAAK,CAAC;IACrB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAG,yBAAyB,CAAC;AAE5D,KAAK,UAAU,UAAU,CACvB,QAAkB,EAClB,IAAoB,EACpB,IAAY,EACZ,IAAmB,EACnB,GAAS;IAET,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAE1E,MAAM,UAAU,GAAwB;QACtC,IAAI,EAAE,OAAO;QACb,IAAI;QACJ,IAAI;QACJ,QAAQ;KACT,CAAC;IACF,MAAM,QAAQ,GAAG,MAAM,mCAAmC,CAAC,UAAU,CAAC,CAAC;IAEvE,qEAAqE;IACrE,wEAAwE;IACxE,gEAAgE;IAChE,kEAAkE;IAClE,iBAAiB;IACjB,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,OAAO,CAAC,IAAI,CACV,kCAAkC,OAAO,MAAM,QAAQ,CAAC,MAAM,IAAI;YAChE,wEAAwE,CAC3E,CAAC;QACF,qEAAqE;QACrE,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;QACjC,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC;QACjC,MAAM,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QAC3C,OAAO;IACT,CAAC;IACD,MAAM,YAAY,GAAG,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC;IACjD,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC;IAEzC,kBAAkB;IAClB,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IACjC,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC5B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC3B,MAAM,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAE3C,MAAM,cAAc,GAClB,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,gBAAgB,IAAI,IAAI,CAAC,mBAAmB;QACrE,CAAC,CAAC;YACE,mBAAmB,EAAE,IAAa;YAClC,WAAW,EAAE;gBACX,MAAM,EAAE,OAAO,OAAO,IAAI,GAAG,CAAC,OAAO,EAAE,EAAE;gBACzC,OAAO,EAAE,IAAI,CAAC,aAAa;gBAC3B,aAAa,EAAE,SAAkB;gBACjC,QAAQ,EAAE;oBACR,QAAQ,EAAE,IAAI,CAAC,gBAAgB;oBAC/B,gBAAgB,EAAE,GAAG,IAAI,CAAC,gBAAgB,IAAI,SAAS,IAAI,IAAI,CAAC,mBAAmB,IAAI,IAAI,CAAC,iBAAiB,IAAI,MAAM,EAAE;oBACzH,IAAI,EAAE,EAAE;oBACR,QAAQ,EAAE,IAAI,CAAC,gBAAgB;oBAC/B,kBAAkB,EAAE,IAAI,CAAC,aAAa;oBACtC,eAAe,EAAE;wBACf,SAAS,EAAE,IAAI,CAAC,mBAAmB;wBACnC,QAAQ,EAAE,IAAI,CAAC,iBAAiB;wBAChC,MAAM,EAAE,IAAI,CAAC,gBAAgB;qBAC9B;oBACD,SAAS,EAAE,IAAI,CAAC,iBAAiB;oBACjC,SAAS,EAAE,GAAG,CAAC,OAAO,EAAE;iBACzB;aACF;SACF;QACH,CAAC,CAAC,SAAS,CAAC;IAEhB,IAAI,CAAC;QACH,MAAM,uBAAuB,CAC3B;YACE,UAAU,EAAE,UAAU;YACtB,UAAU,EAAE,YAAY;YACxB,KAAK,EAAE,QAAQ;YACf,MAAM,EAAE,mBAAmB,OAAO,gBAAgB,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,kDAAkD,IAAI,EAAE;YACrI,WAAW,EAAE,QAAQ,OAAO,MAAM,GAAG,CAAC,kBAAkB,EAAE,EAAE;YAC5D,WAAW,EAAE,OAAO,OAAO,EAAE;YAC7B,UAAU,EAAE,iBAAiB,OAAO,EAAE;YACtC,cAAc;SACf,EACD,IAAI,CACL,CAAC;QAEF,wEAAwE;QACxE,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QACvE,MAAM,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QAC3C,OAAO,CAAC,GAAG,CACT,yBAAyB,OAAO,0BAA0B,IAAI,CAAC,OAAO,EAAE,CACzE,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC;QAC1B,IAAI,CAAC,SAAS;YACZ,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC;QACrE,IAAI,CAAC,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QACvE,MAAM,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QAC3C,OAAO,CAAC,KAAK,CAAC,yBAAyB,OAAO,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAC7E,CAAC;AACH,CAAC;AAED,KAAK,UAAU,cAAc,CAC3B,QAAkB,EAClB,IAAoB,EACpB,IAAY;IAEZ,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5C,MAAM,WAAW,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC5D,CAAC","sourcesContent":["import {\n  resourceListAllOwners,\n  resourcePut,\n  type Resource,\n} from \"../resources/store.js\";\nimport {\n  backgroundRunCutOffReason,\n  isBackgroundAutomationRunActive,\n  resolveBackgroundAutomationIdentity,\n  runBackgroundAutomation,\n  type BackgroundAutomationContext,\n  type BackgroundAutomationDeps,\n} from \"./background-automation-runner.js\";\nimport { nextOccurrence, isValidCron, describeCron } from \"./cron.js\";\nimport {\n  buildJobResourceContent,\n  parseJobResource,\n  type JobFrontmatter,\n} from \"./frontmatter.js\";\n\n// ─── Frontmatter parsing ────────────────────────────────────────────────────\n\nexport {\n  classifyJobFrontmatter,\n  classifyJobResource,\n  normalizeJobMcpTools,\n  parseJobResource,\n  type JobFrontmatter,\n  type JobResourceClassification,\n} from \"./frontmatter.js\";\n\nexport function parseJobFrontmatter(content: string): {\n  meta: JobFrontmatter;\n  body: string;\n} {\n  const { meta, body } = parseJobResource(content);\n  return { meta, body };\n}\n\nexport function buildJobContent(meta: JobFrontmatter, body: string): string {\n  return buildJobResourceContent(meta, body);\n}\n\n// ─── Job execution ──────────────────────────────────────────────────────────\n\nexport type RecurringJobContext = BackgroundAutomationContext;\n\nexport interface SchedulerDeps extends BackgroundAutomationDeps {\n  /**\n   * Tool names to expose on the FIRST engine request for a job run. When\n   * provided, every other action returned by `getActions()` is deferred\n   * behind an attached `tool-search` entry instead of being serialized on\n   * every scheduled tick — `runAgentLoop`'s mid-run tool expansion\n   * (`expandActiveTools`) still lets the model discover and call them after\n   * a search. Omit to keep the full `getActions()` set visible up front\n   * (current behavior). The caller (not this module) knows which of the\n   * merged actions are the app's own vs. framework additions, so this must\n   * be supplied explicitly rather than inferred here.\n   */\n  getInitialToolNames?: (job?: RecurringJobContext) => string[] | undefined;\n}\n\nlet _isRunning = false;\n\n// Skip the DB query on every tick if we recently confirmed no jobs exist.\n// `_hasJobsCache` is invalidated whenever a `jobs/*` resource is written or\n// deleted (subscribed below), and refreshed at most every 5 minutes.\nlet _hasJobsCache: boolean | undefined;\nlet _lastJobsCheck = 0;\nconst JOBS_CHECK_INTERVAL_MS = 5 * 60_000;\nlet _emitterSubscribed = false;\n\nfunction subscribeToJobsResourceEvents(): void {\n  if (_emitterSubscribed) return;\n  _emitterSubscribed = true;\n  // Lazy import to avoid circular deps at module load\n  import(\"../resources/emitter.js\")\n    .then(({ getResourcesEmitter }) => {\n      getResourcesEmitter().on(\"resources\", (event: any) => {\n        if (typeof event?.path === \"string\" && event.path.startsWith(\"jobs/\")) {\n          _hasJobsCache = undefined;\n        }\n      });\n    })\n    .catch((err) => {\n      console.warn(\n        \"[jobs] resource-event subscription failed:\",\n        err instanceof Error ? err.message : err,\n      );\n    });\n}\n\n/**\n * Process all due recurring jobs. Called every 60 seconds.\n * Sequential execution with 5-minute timeout per job.\n */\nexport async function processRecurringJobs(deps: SchedulerDeps): Promise<void> {\n  // Prevent concurrent runs\n  if (_isRunning) return;\n\n  subscribeToJobsResourceEvents();\n\n  // Skip if we recently confirmed there are no job resources to run.\n  const nowMs = Date.now();\n  if (\n    _hasJobsCache === false &&\n    nowMs - _lastJobsCheck < JOBS_CHECK_INTERVAL_MS\n  ) {\n    return;\n  }\n\n  _isRunning = true;\n\n  try {\n    const jobResources = await resourceListAllOwners(\"jobs/\");\n    _hasJobsCache = jobResources.some(\n      (r) => r.path.endsWith(\".md\") && !r.path.endsWith(\".keep\"),\n    );\n    _lastJobsCheck = nowMs;\n    if (!_hasJobsCache) return;\n    const now = new Date();\n\n    for (const resource of jobResources) {\n      // Skip non-markdown or .keep files\n      if (!resource.path.endsWith(\".md\")) continue;\n      if (resource.path.endsWith(\".keep\")) continue;\n\n      const { meta, body } = parseJobFrontmatter(resource.content);\n\n      // Skip disabled or missing schedule\n      if (!meta.enabled || !meta.schedule) continue;\n      if (!isValidCron(meta.schedule)) continue;\n\n      // Skip if currently running, unless it has been stuck for more than 10 minutes\n      // (server crash mid-job leaves lastStatus=running forever without this guard)\n      if (meta.lastStatus === \"running\") {\n        if (isBackgroundAutomationRunActive(meta, now)) continue;\n        // Stuck — reset so the next check can re-run it\n        meta.lastStatus = \"error\";\n        meta.lastError = \"Job timed out or server crashed mid-run\";\n        const next = nextOccurrence(meta.schedule, now);\n        meta.nextRun = next.toISOString();\n        await updateResource(resource, meta, body);\n        continue;\n      }\n\n      // Check if due\n      if (meta.nextRun) {\n        const nextRunDate = new Date(meta.nextRun);\n        if (nextRunDate > now) continue;\n      } else {\n        // No nextRun computed yet — seed it from `now` so the job waits for its\n        // real next occurrence. Computing from new Date(0) (the epoch) always\n        // returns a 1970 date, which is < now, so the job would fire\n        // immediately on first sight regardless of its schedule.\n        const next = nextOccurrence(meta.schedule, now);\n        meta.nextRun = next.toISOString();\n        await updateResource(resource, meta, body);\n        continue;\n      }\n\n      // Skip if body is empty\n      if (!body.trim()) continue;\n\n      // Execute the job\n      await executeJob(resource, meta, body, deps, now);\n    }\n  } catch (err) {\n    // Transient WS / connection drops (Neon serverless): silently retry next\n    // tick instead of spamming stderr — `retryOnConnectionError` already did\n    // its retry budget at the driver level.\n    const { isConnectionError } = await import(\"../db/client.js\");\n    if (isConnectionError(err)) {\n      _hasJobsCache = undefined; // force re-check on next successful tick\n      _lastJobsCheck = 0;\n      return;\n    }\n    // Unwrap ErrorEvent (Neon WS driver emits these on network failure) so logs show the real cause\n    const detail =\n      err instanceof Error\n        ? err\n        : ((err as any)?.error ?? (err as any)?.message ?? err);\n    console.error(\"[recurring-jobs] Error processing jobs:\", detail);\n  } finally {\n    _isRunning = false;\n  }\n}\n\nexport const jobRunCutOffReason = backgroundRunCutOffReason;\n\nasync function executeJob(\n  resource: Resource,\n  meta: JobFrontmatter,\n  body: string,\n  deps: SchedulerDeps,\n  now: Date,\n): Promise<void> {\n  const jobName = resource.path.replace(/^jobs\\//, \"\").replace(/\\.md$/, \"\");\n\n  const jobContext: RecurringJobContext = {\n    name: jobName,\n    meta,\n    body,\n    resource,\n  };\n  const identity = await resolveBackgroundAutomationIdentity(jobContext);\n\n  // SECURITY (audit 12 #10): re-validate the run-as user/membership on\n  // every tick. Sharing revocation, user deletion, and org-member removal\n  // must take effect for already-scheduled jobs. Skip the tick on\n  // failure; leave the cron entry alone so an admin can purge after\n  // investigation.\n  if (!identity.ok) {\n    console.warn(\n      `[recurring-jobs] Skipping job \"${jobName}\": ${identity.reason}. ` +\n        `User/membership no longer valid — leaving cron entry for admin review.`,\n    );\n    // Mark as skipped without resetting nextRun so an admin can find it.\n    meta.lastRun = now.toISOString();\n    meta.lastStatus = \"skipped\";\n    meta.lastError = identity.reason;\n    await updateResource(resource, meta, body);\n    return;\n  }\n  const jobUserEmail = identity.identity.userEmail;\n  const jobOrgId = identity.identity.orgId;\n\n  // Mark as running\n  meta.lastRun = now.toISOString();\n  meta.lastStatus = \"running\";\n  meta.lastError = undefined;\n  await updateResource(resource, meta, body);\n\n  const requestContext =\n    meta.originScopeId && meta.deliveryPlatform && meta.deliveryDestination\n      ? {\n          isIntegrationCaller: true as const,\n          integration: {\n            taskId: `job:${jobName}:${now.getTime()}`,\n            scopeId: meta.originScopeId,\n            principalType: \"service\" as const,\n            incoming: {\n              platform: meta.deliveryPlatform,\n              externalThreadId: `${meta.deliveryTenantId || \"unknown\"}:${meta.deliveryDestination}:${meta.deliveryThreadRef || \"root\"}`,\n              text: \"\",\n              tenantId: meta.deliveryTenantId,\n              integrationScopeId: meta.originScopeId,\n              platformContext: {\n                channelId: meta.deliveryDestination,\n                threadTs: meta.deliveryThreadRef,\n                teamId: meta.deliveryTenantId,\n              },\n              threadRef: meta.deliveryThreadRef,\n              timestamp: now.getTime(),\n            },\n          },\n        }\n      : undefined;\n\n  try {\n    await runBackgroundAutomation(\n      {\n        automation: jobContext,\n        ownerEmail: jobUserEmail,\n        orgId: jobOrgId,\n        prompt: `[Recurring Job: ${jobName}]\\nSchedule: ${describeCron(meta.schedule)}\\n\\nExecute the following job instructions:\\n\\n${body}`,\n        threadTitle: `Job: ${jobName} — ${now.toLocaleDateString()}`,\n        runIdPrefix: `job-${jobName}`,\n        usageLabel: `recurring-job:${jobName}`,\n        requestContext,\n      },\n      deps,\n    );\n\n    // Compute from completion time so long runs cannot immediately re-fire.\n    meta.lastStatus = \"success\";\n    meta.nextRun = nextOccurrence(meta.schedule, new Date()).toISOString();\n    await updateResource(resource, meta, body);\n    console.log(\n      `[recurring-jobs] Job \"${jobName}\" completed. Next run: ${meta.nextRun}`,\n    );\n  } catch (err) {\n    meta.lastStatus = \"error\";\n    meta.lastError =\n      err instanceof Error ? err.message.slice(0, 200) : \"Unknown error\";\n    meta.nextRun = nextOccurrence(meta.schedule, new Date()).toISOString();\n    await updateResource(resource, meta, body);\n    console.error(`[recurring-jobs] Job \"${jobName}\" failed:`, meta.lastError);\n  }\n}\n\nasync function updateResource(\n  resource: Resource,\n  meta: JobFrontmatter,\n  body: string,\n): Promise<void> {\n  const content = buildJobContent(meta, body);\n  await resourcePut(resource.owner, resource.path, content);\n}\n"]}
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../../src/jobs/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,WAAW,GAEZ,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,yBAAyB,EACzB,+BAA+B,EAC/B,mCAAmC,EACnC,uBAAuB,GAGxB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,cAAc,EACd,WAAW,EACX,YAAY,EACZ,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,uBAAuB,EACvB,gBAAgB,GAEjB,MAAM,kBAAkB,CAAC;AAE1B,+EAA+E;AAE/E,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,GAGjB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,UAAU,mBAAmB,CAAC,OAAe;IAIjD,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACjD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAoB,EAAE,IAAY;IAChE,OAAO,uBAAuB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC7C,CAAC;AAqBD,IAAI,UAAU,GAAG,KAAK,CAAC;AAEvB,0EAA0E;AAC1E,4EAA4E;AAC5E,qEAAqE;AACrE,IAAI,aAAkC,CAAC;AACvC,IAAI,cAAc,GAAG,CAAC,CAAC;AACvB,MAAM,sBAAsB,GAAG,CAAC,GAAG,MAAM,CAAC;AAC1C,IAAI,kBAAkB,GAAG,KAAK,CAAC;AAE/B,SAAS,6BAA6B;IACpC,IAAI,kBAAkB;QAAE,OAAO;IAC/B,kBAAkB,GAAG,IAAI,CAAC;IAC1B,oDAAoD;IACpD,MAAM,CAAC,yBAAyB,CAAC;SAC9B,IAAI,CAAC,CAAC,EAAE,mBAAmB,EAAE,EAAE,EAAE;QAChC,mBAAmB,EAAE,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,KAAU,EAAE,EAAE;YACnD,IAAI,OAAO,KAAK,EAAE,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;gBACtE,aAAa,GAAG,SAAS,CAAC;YAC5B,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;SACD,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACb,OAAO,CAAC,IAAI,CACV,4CAA4C,EAC5C,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CACzC,CAAC;IACJ,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,IAAmB;IAC5D,0BAA0B;IAC1B,IAAI,UAAU;QAAE,OAAO;IAEvB,6BAA6B,EAAE,CAAC;IAEhC,mEAAmE;IACnE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,IACE,aAAa,KAAK,KAAK;QACvB,KAAK,GAAG,cAAc,GAAG,sBAAsB,EAC/C,CAAC;QACD,OAAO;IACT,CAAC;IAED,UAAU,GAAG,IAAI,CAAC;IAElB,IAAI,CAAC;QACH,MAAM,YAAY,GAAG,MAAM,qBAAqB,CAAC,OAAO,CAAC,CAAC;QAC1D,aAAa,GAAG,YAAY,CAAC,IAAI,CAC/B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAC3D,CAAC;QACF,cAAc,GAAG,KAAK,CAAC;QACvB,IAAI,CAAC,aAAa;YAAE,OAAO;QAC3B,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QAEvB,KAAK,MAAM,QAAQ,IAAI,YAAY,EAAE,CAAC;YACpC,mCAAmC;YACnC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAAE,SAAS;YAC7C,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAAE,SAAS;YAE9C,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,mBAAmB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAE7D,oCAAoC;YACpC,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ;gBAAE,SAAS;YAC9C,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC;gBAAE,SAAS;YAE1C,+EAA+E;YAC/E,8EAA8E;YAC9E,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;gBAClC,IAAI,+BAA+B,CAAC,IAAI,EAAE,GAAG,CAAC;oBAAE,SAAS;gBACzD,gDAAgD;gBAChD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC;gBAC1B,IAAI,CAAC,SAAS,GAAG,yCAAyC,CAAC;gBAC3D,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;gBAC/D,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;gBAClC,MAAM,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;gBAC3C,SAAS;YACX,CAAC;YAED,eAAe;YACf,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC3C,IAAI,WAAW,GAAG,GAAG;oBAAE,SAAS;YAClC,CAAC;iBAAM,CAAC;gBACN,wEAAwE;gBACxE,sEAAsE;gBACtE,6DAA6D;gBAC7D,yDAAyD;gBACzD,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;gBAC/D,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;gBAClC,MAAM,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;gBAC3C,SAAS;YACX,CAAC;YAED,wBAAwB;YACxB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;gBAAE,SAAS;YAE3B,kBAAkB;YAClB,MAAM,UAAU,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,yEAAyE;QACzE,yEAAyE;QACzE,wCAAwC;QACxC,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;QAC9D,IAAI,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,aAAa,GAAG,SAAS,CAAC,CAAC,yCAAyC;YACpE,cAAc,GAAG,CAAC,CAAC;YACnB,OAAO;QACT,CAAC;QACD,gGAAgG;QAChG,MAAM,MAAM,GACV,GAAG,YAAY,KAAK;YAClB,CAAC,CAAC,GAAG;YACL,CAAC,CAAC,CAAE,GAAW,EAAE,KAAK,IAAK,GAAW,EAAE,OAAO,IAAI,GAAG,CAAC,CAAC;QAC5D,OAAO,CAAC,KAAK,CAAC,yCAAyC,EAAE,MAAM,CAAC,CAAC;IACnE,CAAC;YAAS,CAAC;QACT,UAAU,GAAG,KAAK,CAAC;IACrB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAG,yBAAyB,CAAC;AAE5D,KAAK,UAAU,UAAU,CACvB,QAAkB,EAClB,IAAoB,EACpB,IAAY,EACZ,IAAmB,EACnB,GAAS;IAET,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAE1E,MAAM,UAAU,GAAwB;QACtC,IAAI,EAAE,OAAO;QACb,IAAI;QACJ,IAAI;QACJ,QAAQ;KACT,CAAC;IACF,MAAM,QAAQ,GAAG,MAAM,mCAAmC,CAAC,UAAU,CAAC,CAAC;IAEvE,qEAAqE;IACrE,wEAAwE;IACxE,gEAAgE;IAChE,kEAAkE;IAClE,iBAAiB;IACjB,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,OAAO,CAAC,IAAI,CACV,kCAAkC,OAAO,MAAM,QAAQ,CAAC,MAAM,IAAI;YAChE,wEAAwE,CAC3E,CAAC;QACF,qEAAqE;QACrE,yEAAyE;QACzE,wEAAwE;QACxE,sEAAsE;QACtE,mEAAmE;QACnE,MAAM,eAAe,GACnB,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,IAAI,CAAC,SAAS,KAAK,QAAQ,CAAC,MAAM,CAAC;QACtE,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC;QACjC,IAAI,CAAC,eAAe;YAAE,MAAM,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACjE,OAAO;IACT,CAAC;IACD,MAAM,YAAY,GAAG,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC;IACjD,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC;IAEzC,kBAAkB;IAClB,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IACjC,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC5B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC3B,MAAM,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAE3C,MAAM,cAAc,GAClB,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,gBAAgB,IAAI,IAAI,CAAC,mBAAmB;QACrE,CAAC,CAAC;YACE,mBAAmB,EAAE,IAAa;YAClC,WAAW,EAAE;gBACX,MAAM,EAAE,OAAO,OAAO,IAAI,GAAG,CAAC,OAAO,EAAE,EAAE;gBACzC,OAAO,EAAE,IAAI,CAAC,aAAa;gBAC3B,aAAa,EAAE,SAAkB;gBACjC,QAAQ,EAAE;oBACR,QAAQ,EAAE,IAAI,CAAC,gBAAgB;oBAC/B,gBAAgB,EAAE,GAAG,IAAI,CAAC,gBAAgB,IAAI,SAAS,IAAI,IAAI,CAAC,mBAAmB,IAAI,IAAI,CAAC,iBAAiB,IAAI,MAAM,EAAE;oBACzH,IAAI,EAAE,EAAE;oBACR,QAAQ,EAAE,IAAI,CAAC,gBAAgB;oBAC/B,kBAAkB,EAAE,IAAI,CAAC,aAAa;oBACtC,eAAe,EAAE;wBACf,SAAS,EAAE,IAAI,CAAC,mBAAmB;wBACnC,QAAQ,EAAE,IAAI,CAAC,iBAAiB;wBAChC,MAAM,EAAE,IAAI,CAAC,gBAAgB;qBAC9B;oBACD,SAAS,EAAE,IAAI,CAAC,iBAAiB;oBACjC,SAAS,EAAE,GAAG,CAAC,OAAO,EAAE;iBACzB;aACF;SACF;QACH,CAAC,CAAC,SAAS,CAAC;IAEhB,IAAI,CAAC;QACH,MAAM,uBAAuB,CAC3B;YACE,UAAU,EAAE,UAAU;YACtB,UAAU,EAAE,YAAY;YACxB,KAAK,EAAE,QAAQ;YACf,MAAM,EAAE,mBAAmB,OAAO,gBAAgB,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,kDAAkD,IAAI,EAAE;YACvK,WAAW,EAAE,QAAQ,OAAO,MAAM,GAAG,CAAC,kBAAkB,EAAE,EAAE;YAC5D,WAAW,EAAE,OAAO,OAAO,EAAE;YAC7B,UAAU,EAAE,iBAAiB,OAAO,EAAE;YACtC,cAAc;SACf,EACD,IAAI,CACL,CAAC;QAEF,MAAM,sBAAsB,CAAC,QAAQ,EAAE;YACrC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,SAAS;YACrB,SAAS,EAAE,SAAS;SACrB,CAAC,CAAC;QACH,OAAO,CAAC,GAAG,CAAC,yBAAyB,OAAO,cAAc,CAAC,CAAC;IAC9D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,SAAS,GACb,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC;QACrE,MAAM,sBAAsB,CAAC,QAAQ,EAAE;YACrC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,OAAO;YACnB,SAAS;SACV,CAAC,CAAC;QACH,OAAO,CAAC,KAAK,CAAC,yBAAyB,OAAO,WAAW,EAAE,SAAS,CAAC,CAAC;IACxE,CAAC;AACH,CAAC;AAED,KAAK,UAAU,cAAc,CAC3B,QAAkB,EAClB,IAAoB,EACpB,IAAY;IAEZ,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5C,MAAM,WAAW,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC5D,CAAC;AAQD;;;;;;;;GAQG;AACH,KAAK,UAAU,sBAAsB,CACnC,QAAkB,EAClB,OAAyB;IAEzB,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IACtE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,wEAAwE;QACxE,kDAAkD;QAClD,OAAO,CAAC,GAAG,CACT,qBAAqB,QAAQ,CAAC,IAAI,8CAA8C,CACjF,CAAC;QACF,OAAO;IACT,CAAC;IACD,MAAM,OAAO,GAAG,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAEjD,MAAM,IAAI,GAAmB,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;IAC7D,IAAI,IAAI,CAAC,QAAQ,IAAI,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChD,qEAAqE;QACrE,IAAI,CAAC,OAAO,GAAG,cAAc,CAC3B,IAAI,CAAC,QAAQ,EACb,IAAI,IAAI,EAAE,EACV,IAAI,CAAC,QAAQ,CACd,CAAC,WAAW,EAAE,CAAC;IAClB,CAAC;IACD,MAAM,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;AACrD,CAAC","sourcesContent":["import {\n  resourceGetByPath,\n  resourceListAllOwners,\n  resourcePut,\n  type Resource,\n} from \"../resources/store.js\";\nimport {\n  backgroundRunCutOffReason,\n  isBackgroundAutomationRunActive,\n  resolveBackgroundAutomationIdentity,\n  runBackgroundAutomation,\n  type BackgroundAutomationContext,\n  type BackgroundAutomationDeps,\n} from \"./background-automation-runner.js\";\nimport {\n  nextOccurrence,\n  isValidCron,\n  describeCron,\n  effectiveTimezone,\n} from \"./cron.js\";\nimport {\n  buildJobResourceContent,\n  parseJobResource,\n  type JobFrontmatter,\n} from \"./frontmatter.js\";\n\n// ─── Frontmatter parsing ────────────────────────────────────────────────────\n\nexport {\n  classifyJobFrontmatter,\n  classifyJobResource,\n  normalizeJobMcpTools,\n  parseJobResource,\n  type JobFrontmatter,\n  type JobResourceClassification,\n} from \"./frontmatter.js\";\n\nexport function parseJobFrontmatter(content: string): {\n  meta: JobFrontmatter;\n  body: string;\n} {\n  const { meta, body } = parseJobResource(content);\n  return { meta, body };\n}\n\nexport function buildJobContent(meta: JobFrontmatter, body: string): string {\n  return buildJobResourceContent(meta, body);\n}\n\n// ─── Job execution ──────────────────────────────────────────────────────────\n\nexport type RecurringJobContext = BackgroundAutomationContext;\n\nexport interface SchedulerDeps extends BackgroundAutomationDeps {\n  /**\n   * Tool names to expose on the FIRST engine request for a job run. When\n   * provided, every other action returned by `getActions()` is deferred\n   * behind an attached `tool-search` entry instead of being serialized on\n   * every scheduled tick — `runAgentLoop`'s mid-run tool expansion\n   * (`expandActiveTools`) still lets the model discover and call them after\n   * a search. Omit to keep the full `getActions()` set visible up front\n   * (current behavior). The caller (not this module) knows which of the\n   * merged actions are the app's own vs. framework additions, so this must\n   * be supplied explicitly rather than inferred here.\n   */\n  getInitialToolNames?: (job?: RecurringJobContext) => string[] | undefined;\n}\n\nlet _isRunning = false;\n\n// Skip the DB query on every tick if we recently confirmed no jobs exist.\n// `_hasJobsCache` is invalidated whenever a `jobs/*` resource is written or\n// deleted (subscribed below), and refreshed at most every 5 minutes.\nlet _hasJobsCache: boolean | undefined;\nlet _lastJobsCheck = 0;\nconst JOBS_CHECK_INTERVAL_MS = 5 * 60_000;\nlet _emitterSubscribed = false;\n\nfunction subscribeToJobsResourceEvents(): void {\n  if (_emitterSubscribed) return;\n  _emitterSubscribed = true;\n  // Lazy import to avoid circular deps at module load\n  import(\"../resources/emitter.js\")\n    .then(({ getResourcesEmitter }) => {\n      getResourcesEmitter().on(\"resources\", (event: any) => {\n        if (typeof event?.path === \"string\" && event.path.startsWith(\"jobs/\")) {\n          _hasJobsCache = undefined;\n        }\n      });\n    })\n    .catch((err) => {\n      console.warn(\n        \"[jobs] resource-event subscription failed:\",\n        err instanceof Error ? err.message : err,\n      );\n    });\n}\n\n/**\n * Process all due recurring jobs. Called every 60 seconds.\n * Sequential execution with 5-minute timeout per job.\n */\nexport async function processRecurringJobs(deps: SchedulerDeps): Promise<void> {\n  // Prevent concurrent runs\n  if (_isRunning) return;\n\n  subscribeToJobsResourceEvents();\n\n  // Skip if we recently confirmed there are no job resources to run.\n  const nowMs = Date.now();\n  if (\n    _hasJobsCache === false &&\n    nowMs - _lastJobsCheck < JOBS_CHECK_INTERVAL_MS\n  ) {\n    return;\n  }\n\n  _isRunning = true;\n\n  try {\n    const jobResources = await resourceListAllOwners(\"jobs/\");\n    _hasJobsCache = jobResources.some(\n      (r) => r.path.endsWith(\".md\") && !r.path.endsWith(\".keep\"),\n    );\n    _lastJobsCheck = nowMs;\n    if (!_hasJobsCache) return;\n    const now = new Date();\n\n    for (const resource of jobResources) {\n      // Skip non-markdown or .keep files\n      if (!resource.path.endsWith(\".md\")) continue;\n      if (resource.path.endsWith(\".keep\")) continue;\n\n      const { meta, body } = parseJobFrontmatter(resource.content);\n\n      // Skip disabled or missing schedule\n      if (!meta.enabled || !meta.schedule) continue;\n      if (!isValidCron(meta.schedule)) continue;\n\n      // Skip if currently running, unless it has been stuck for more than 10 minutes\n      // (server crash mid-job leaves lastStatus=running forever without this guard)\n      if (meta.lastStatus === \"running\") {\n        if (isBackgroundAutomationRunActive(meta, now)) continue;\n        // Stuck — reset so the next check can re-run it\n        meta.lastStatus = \"error\";\n        meta.lastError = \"Job timed out or server crashed mid-run\";\n        const next = nextOccurrence(meta.schedule, now, meta.timezone);\n        meta.nextRun = next.toISOString();\n        await updateResource(resource, meta, body);\n        continue;\n      }\n\n      // Check if due\n      if (meta.nextRun) {\n        const nextRunDate = new Date(meta.nextRun);\n        if (nextRunDate > now) continue;\n      } else {\n        // No nextRun computed yet — seed it from `now` so the job waits for its\n        // real next occurrence. Computing from new Date(0) (the epoch) always\n        // returns a 1970 date, which is < now, so the job would fire\n        // immediately on first sight regardless of its schedule.\n        const next = nextOccurrence(meta.schedule, now, meta.timezone);\n        meta.nextRun = next.toISOString();\n        await updateResource(resource, meta, body);\n        continue;\n      }\n\n      // Skip if body is empty\n      if (!body.trim()) continue;\n\n      // Execute the job\n      await executeJob(resource, meta, body, deps, now);\n    }\n  } catch (err) {\n    // Transient WS / connection drops (Neon serverless): silently retry next\n    // tick instead of spamming stderr — `retryOnConnectionError` already did\n    // its retry budget at the driver level.\n    const { isConnectionError } = await import(\"../db/client.js\");\n    if (isConnectionError(err)) {\n      _hasJobsCache = undefined; // force re-check on next successful tick\n      _lastJobsCheck = 0;\n      return;\n    }\n    // Unwrap ErrorEvent (Neon WS driver emits these on network failure) so logs show the real cause\n    const detail =\n      err instanceof Error\n        ? err\n        : ((err as any)?.error ?? (err as any)?.message ?? err);\n    console.error(\"[recurring-jobs] Error processing jobs:\", detail);\n  } finally {\n    _isRunning = false;\n  }\n}\n\nexport const jobRunCutOffReason = backgroundRunCutOffReason;\n\nasync function executeJob(\n  resource: Resource,\n  meta: JobFrontmatter,\n  body: string,\n  deps: SchedulerDeps,\n  now: Date,\n): Promise<void> {\n  const jobName = resource.path.replace(/^jobs\\//, \"\").replace(/\\.md$/, \"\");\n\n  const jobContext: RecurringJobContext = {\n    name: jobName,\n    meta,\n    body,\n    resource,\n  };\n  const identity = await resolveBackgroundAutomationIdentity(jobContext);\n\n  // SECURITY (audit 12 #10): re-validate the run-as user/membership on\n  // every tick. Sharing revocation, user deletion, and org-member removal\n  // must take effect for already-scheduled jobs. Skip the tick on\n  // failure; leave the cron entry alone so an admin can purge after\n  // investigation.\n  if (!identity.ok) {\n    console.warn(\n      `[recurring-jobs] Skipping job \"${jobName}\": ${identity.reason}. ` +\n        `User/membership no longer valid — leaving cron entry for admin review.`,\n    );\n    // Mark as skipped without resetting nextRun so an admin can find it.\n    // `lastRun` is deliberately untouched: the job did not run, and stamping\n    // it here made a permanently blocked job look like it ran every minute.\n    // Re-writing an unchanged resource on every tick also churns the poll\n    // stream, so only persist when the failure state actually changed.\n    const alreadyRecorded =\n      meta.lastStatus === \"skipped\" && meta.lastError === identity.reason;\n    meta.lastCheck = now.toISOString();\n    meta.lastStatus = \"skipped\";\n    meta.lastError = identity.reason;\n    if (!alreadyRecorded) await updateResource(resource, meta, body);\n    return;\n  }\n  const jobUserEmail = identity.identity.userEmail;\n  const jobOrgId = identity.identity.orgId;\n\n  // Mark as running\n  meta.lastRun = now.toISOString();\n  meta.lastStatus = \"running\";\n  meta.lastError = undefined;\n  await updateResource(resource, meta, body);\n\n  const requestContext =\n    meta.originScopeId && meta.deliveryPlatform && meta.deliveryDestination\n      ? {\n          isIntegrationCaller: true as const,\n          integration: {\n            taskId: `job:${jobName}:${now.getTime()}`,\n            scopeId: meta.originScopeId,\n            principalType: \"service\" as const,\n            incoming: {\n              platform: meta.deliveryPlatform,\n              externalThreadId: `${meta.deliveryTenantId || \"unknown\"}:${meta.deliveryDestination}:${meta.deliveryThreadRef || \"root\"}`,\n              text: \"\",\n              tenantId: meta.deliveryTenantId,\n              integrationScopeId: meta.originScopeId,\n              platformContext: {\n                channelId: meta.deliveryDestination,\n                threadTs: meta.deliveryThreadRef,\n                teamId: meta.deliveryTenantId,\n              },\n              threadRef: meta.deliveryThreadRef,\n              timestamp: now.getTime(),\n            },\n          },\n        }\n      : undefined;\n\n  try {\n    await runBackgroundAutomation(\n      {\n        automation: jobContext,\n        ownerEmail: jobUserEmail,\n        orgId: jobOrgId,\n        prompt: `[Recurring Job: ${jobName}]\\nSchedule: ${describeCron(meta.schedule, effectiveTimezone(meta.timezone))}\\n\\nExecute the following job instructions:\\n\\n${body}`,\n        threadTitle: `Job: ${jobName} — ${now.toLocaleDateString()}`,\n        runIdPrefix: `job-${jobName}`,\n        usageLabel: `recurring-job:${jobName}`,\n        requestContext,\n      },\n      deps,\n    );\n\n    await recordExecutionOutcome(resource, {\n      lastRun: meta.lastRun,\n      lastStatus: \"success\",\n      lastError: undefined,\n    });\n    console.log(`[recurring-jobs] Job \"${jobName}\" completed.`);\n  } catch (err) {\n    const lastError =\n      err instanceof Error ? err.message.slice(0, 200) : \"Unknown error\";\n    await recordExecutionOutcome(resource, {\n      lastRun: meta.lastRun,\n      lastStatus: \"error\",\n      lastError,\n    });\n    console.error(`[recurring-jobs] Job \"${jobName}\" failed:`, lastError);\n  }\n}\n\nasync function updateResource(\n  resource: Resource,\n  meta: JobFrontmatter,\n  body: string,\n): Promise<void> {\n  const content = buildJobContent(meta, body);\n  await resourcePut(resource.owner, resource.path, content);\n}\n\n/** Execution bookkeeping the scheduler owns; the rest belongs to the editor. */\ntype ExecutionOutcome = Pick<\n  JobFrontmatter,\n  \"lastRun\" | \"lastCheck\" | \"lastStatus\" | \"lastError\"\n>;\n\n/**\n * Persist the result of a run without clobbering a concurrent edit.\n *\n * A run holds its `meta` for as long as the job takes, so writing that whole\n * snapshot back on completion would silently revert a schedule, timezone or\n * instruction change made while it was running. Only the execution fields are\n * ours to write, and `nextRun` is recomputed from whatever schedule is stored\n * now, so an edit mid-run takes effect on the next tick.\n */\nasync function recordExecutionOutcome(\n  resource: Resource,\n  outcome: ExecutionOutcome,\n): Promise<void> {\n  const latest = await resourceGetByPath(resource.owner, resource.path);\n  if (!latest) {\n    // Deleted while it was running. Writing the pre-run snapshot back would\n    // resurrect the automation and schedule it again.\n    console.log(\n      `[recurring-jobs] \"${resource.path}\" was deleted mid-run; dropping its outcome.`,\n    );\n    return;\n  }\n  const current = parseJobResource(latest.content);\n\n  const meta: JobFrontmatter = { ...current.meta, ...outcome };\n  if (meta.schedule && isValidCron(meta.schedule)) {\n    // Measured from completion so a long run cannot immediately re-fire.\n    meta.nextRun = nextOccurrence(\n      meta.schedule,\n      new Date(),\n      meta.timezone,\n    ).toISOString();\n  }\n  await updateResource(resource, meta, current.body);\n}\n"]}

package/dist/jobs/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/jobs/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAkBhE,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AAsCxB;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAkBxB;AAoOD,wBAAgB,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CA8F5D"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/jobs/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAyBhE,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AAsCxB;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAkBxB;AAwQD,wBAAgB,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAmG5D"}

package/dist/jobs/tools.js

@@ -1,7 +1,8 @@
 import { getDbExec } from "../db/client.js";
+import { resolveUserSchedulingTimezone } from "../localization/user-timezone.js";
 import { resourcePut, resourceGetByPath, resourceList, resourceDelete, organizationIdFromResourceOwner, sharedResourceOwner, SHARED_OWNER, } from "../resources/store.js";
 import { getRequestUserEmail, getRequestOrgId, getIntegrationRequestContext, } from "../server/request-context.js";
-import { isValidCron, nextOccurrence, describeCron } from "./cron.js";
+import { isValidCron, nextOccurrence, describeCron, effectiveTimezone, isValidTimezone, } from "./cron.js";
 import { classifyJobResource } from "./frontmatter.js";
 import { parseJobFrontmatter, buildJobContent, normalizeJobMcpTools, } from "./scheduler.js";
 function getOwner() {
@@ -70,6 +71,7 @@ export async function authorizeJobMutation(resourceOwner, meta) {
 }
 async function runCreate(args) {
     const { name, schedule, instructions, scope, runAs, model } = args;
+    const requestedTimezone = args.timezone;
     if (!name || !schedule || !instructions) {
         return JSON.stringify({
             error: "name, schedule, and instructions are required",
@@ -90,12 +92,22 @@ async function runCreate(args) {
     const owner = scope === "personal" ? getOwner() : getSharedOwner();
     const path = `jobs/${name}.md`;
     const now = new Date();
-    const next = nextOccurrence(schedule, now);
+    // A cron time with no zone silently means the host's zone, which is how an
+    // "8am" job ends up firing at 4am for the person who asked for it.
+    if (requestedTimezone && !isValidTimezone(requestedTimezone)) {
+        return JSON.stringify({
+            error: `Unknown timezone: "${requestedTimezone}". Use an IANA zone such as America/New_York.`,
+        });
+    }
+    const timezone = requestedTimezone ||
+        (await resolveUserSchedulingTimezone(getRequestUserEmail()));
+    const next = nextOccurrence(schedule, now, timezone);
     const integration = getIntegrationRequestContext();
     const channelId = integration?.incoming.platformContext.channelId;
     const threadRef = integration?.incoming.threadRef;
     const meta = {
         schedule,
+        timezone,
         enabled: true,
         createdBy: getOwner(),
         orgId: getRequestOrgId() || undefined,
@@ -124,7 +136,8 @@ async function runCreate(args) {
         name,
         path,
         schedule,
-        scheduleDescription: describeCron(schedule),
+        timezone,
+        scheduleDescription: describeCron(schedule, timezone),
         nextRun: next.toISOString(),
         scope: scope || "shared",
         ...(mcpTools?.length ? { mcpTools } : {}),
@@ -156,7 +169,10 @@ async function runList(args) {
             path: r.path,
             scope: r.owner === sharedOwner ? "shared" : "personal",
             schedule: meta.schedule,
-            scheduleDescription: meta.schedule ? describeCron(meta.schedule) : "",
+            timezone: effectiveTimezone(meta.timezone),
+            scheduleDescription: meta.schedule
+                ? describeCron(meta.schedule, effectiveTimezone(meta.timezone))
+                : "",
             enabled: meta.enabled,
             lastRun: meta.lastRun || null,
             lastStatus: meta.lastStatus || null,
@@ -208,7 +224,17 @@ async function runUpdate(args) {
             });
         }
         meta.schedule = schedule;
-        meta.nextRun = nextOccurrence(schedule).toISOString();
+    }
+    if (args.timezone !== undefined) {
+        if (!isValidTimezone(args.timezone)) {
+            return JSON.stringify({
+                error: `Unknown timezone: "${args.timezone}".`,
+            });
+        }
+        meta.timezone = args.timezone;
+    }
+    if (schedule || args.timezone !== undefined) {
+        meta.nextRun = nextOccurrence(meta.schedule, undefined, meta.timezone).toISOString();
     }
     if (enabled !== undefined) {
         // Accept both the schema's string enum ("true"/"false") and a real boolean
@@ -240,7 +266,8 @@ async function runUpdate(args) {
         updated: true,
         name,
         schedule: meta.schedule,
-        scheduleDescription: describeCron(meta.schedule),
+        timezone: effectiveTimezone(meta.timezone),
+        scheduleDescription: describeCron(meta.schedule, effectiveTimezone(meta.timezone)),
         enabled: meta.enabled,
         nextRun: meta.nextRun,
         mcpTools: meta.mcpTools || [],
@@ -299,6 +326,10 @@ For jobs that use a connected MCP, pass the exact tool names in mcpTools. This b
                             type: "string",
                             description: "Job name (hyphen-case, e.g. 'daily-scorecard-check'). Required for create and update.",
                         },
+                        timezone: {
+                            type: "string",
+                            description: "IANA timezone the schedule's clock time is read in, e.g. 'America/New_York'. Optional; defaults to the user's saved scheduling timezone, then the caller's browser zone. Always pass this when the user names a time of day, so '8am' means 8am where they are rather than on the server.",
+                        },
                         schedule: {
                             type: "string",
                             description: "Cron expression (5 fields: minute hour day-of-month month day-of-week). Required for create, optional for update.",