@agent-native/core 0.134.1 → 0.135.1

package/corpus/core/src/client/settings/SchedulingTimezoneField.tsx

@@ -0,0 +1,71 @@
+import {
+  TimezoneSelect,
+  browserTimezone,
+} from "../agent-page/TimezoneSelect.js";
+import { useT } from "../i18n.js";
+import { useActionMutation, useActionQuery } from "../use-action.js";
+
+interface LocalizationPreferenceResult {
+  locale: string;
+  timezone: string;
+}
+
+const SYSTEM = "system";
+
+/**
+ * Timezone used when the agent schedules work for this user.
+ *
+ * This is deliberately a stored preference rather than a per-request read of
+ * the browser zone: automations are created and run by callers that have no
+ * browser at all (cron ticks, chat integrations, A2A), and those callers would
+ * otherwise fall back to the host zone and schedule the user's 8am job in UTC.
+ */
+export function SchedulingTimezoneField() {
+  const t = useT();
+  const detected = browserTimezone();
+  const preference = useActionQuery<LocalizationPreferenceResult>(
+    "get-localization-preference",
+  );
+  const save = useActionMutation<
+    LocalizationPreferenceResult,
+    { timezone: string }
+  >("set-localization-preference");
+
+  // Selecting a zone commits it, matching the language picker beside it.
+  const stored = preference.data?.timezone ?? SYSTEM;
+  const pending = save.isPending ? save.variables?.timezone : undefined;
+  const value = pending ?? stored;
+
+  return (
+    <div className="space-y-2">
+      <label
+        className="text-sm font-medium"
+        htmlFor="agent-native-scheduling-timezone"
+      >
+        {t("settings.timezoneLabel", { defaultValue: "Timezone" })}
+      </label>
+
+      <TimezoneSelect
+        id="agent-native-scheduling-timezone"
+        value={value}
+        disabled={preference.isLoading || save.isPending}
+        suggested={[detected]}
+        systemLabel={t("settings.timezoneSystem", {
+          defaultValue: "Follow this browser ({{zone}})",
+          zone: detected,
+        })}
+        onChange={(timezone) => save.mutate({ timezone })}
+      />
+
+      <p className="min-h-4 text-xs text-muted-foreground">
+        {save.error ? (
+          <span className="text-destructive">{save.error.message}</span>
+        ) : (
+          t("settings.timezoneHint", {
+            defaultValue: "Used for timestamps and scheduled automations.",
+          })
+        )}
+      </p>
+    </div>
+  );
+}

package/corpus/core/src/client/settings/SettingsRow.tsx

@@ -0,0 +1,113 @@
+import type { ReactNode } from "react";
+
+import { cn } from "../utils.js";
+
+export interface SettingsGroupProps {
+  /** Anchor target so a settings search hit can scroll the whole group. */
+  id?: string;
+  title?: string;
+  description?: string;
+  className?: string;
+  children: ReactNode;
+}
+
+/**
+ * A bordered card holding several one-line settings instead of one card per
+ * control. Copy is passed in already translated — core components do not
+ * resolve an app's i18n keys.
+ */
+export function SettingsGroup({
+  id,
+  title,
+  description,
+  className,
+  children,
+}: SettingsGroupProps) {
+  return (
+    <section
+      id={id}
+      className={cn(
+        "scroll-mt-16 overflow-hidden rounded-lg border border-border bg-card text-card-foreground shadow-sm",
+        className,
+      )}
+    >
+      {(title || description) && (
+        <header className="border-b border-border/60 px-5 py-4 sm:px-6">
+          {title && (
+            <h2 className="text-base font-semibold leading-none tracking-tight">
+              {title}
+            </h2>
+          )}
+          {description && (
+            <p className="mt-1.5 text-sm leading-snug text-muted-foreground">
+              {description}
+            </p>
+          )}
+        </header>
+      )}
+      <div className="divide-y divide-border/60">{children}</div>
+    </section>
+  );
+}
+
+export interface SettingsRowProps {
+  /**
+   * Anchor target. Rows keep the ids their former standalone cards used, so
+   * existing settings-search hashes still resolve after a card collapses into
+   * a row.
+   */
+  id?: string;
+  label: ReactNode;
+  description?: ReactNode;
+  icon?: ReactNode;
+  /** Badge or pill rendered beside the label. */
+  status?: ReactNode;
+  /** The input itself: switch, select, button, link. */
+  control?: ReactNode;
+  /** Extra content below the row, e.g. a disclosure panel. */
+  children?: ReactNode;
+  className?: string;
+}
+
+/** One setting: label and description on the start side, control on the end. */
+export function SettingsRow({
+  id,
+  label,
+  description,
+  icon,
+  status,
+  control,
+  children,
+  className,
+}: SettingsRowProps) {
+  return (
+    <div id={id} className={cn("scroll-mt-16 px-5 py-4 sm:px-6", className)}>
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+        <div className="flex min-w-0 gap-3">
+          {icon && (
+            <span className="mt-0.5 flex size-8 shrink-0 items-center justify-center rounded-md border border-border bg-background text-muted-foreground [&>svg]:size-[18px]">
+              {icon}
+            </span>
+          )}
+          <div className="min-w-0">
+            <div className="flex flex-wrap items-center gap-2">
+              <span className="text-sm font-medium text-foreground">
+                {label}
+              </span>
+              {status}
+            </div>
+            {description && (
+              <p className="mt-1 max-w-xl text-sm leading-6 text-muted-foreground">
+                {description}
+              </p>
+            )}
+          </div>
+        </div>
+        {control && (
+          <div className="shrink-0 sm:ms-4 sm:text-end">{control}</div>
+        )}
+      </div>
+      {children && <div className="mt-4">{children}</div>}
+    </div>
+  );
+}

package/corpus/core/src/client/settings/agent-settings-search.ts

@@ -93,7 +93,8 @@ const SETTINGS_SECTION_SEARCH_META: Record<
 > = {
   account: {
     label: "Account",
-    keywords: "profile photo avatar identity signed in email name",
+    keywords:
+      "profile photo avatar identity signed in email name timezone time zone schedule scheduling clock",
   },
   llm: {
     label: "LLM",

package/corpus/core/src/client/settings/index.ts

@@ -34,6 +34,12 @@ export {
   type OpenBuilderConnectPopupOptions,
 } from "./useBuilderStatus.js";
 export { SecretsSection, type SecretsSectionProps } from "./SecretsSection.js";
+export {
+  SettingsGroup,
+  SettingsRow,
+  type SettingsGroupProps,
+  type SettingsRowProps,
+} from "./SettingsRow.js";
 export {
   normalizeSettingsSection,
   settingsSectionDomId,

package/corpus/core/src/integrations/identity.ts

@@ -1,4 +1,4 @@
-import { getDbExec } from "../db/client.js";
+import { isOrgMember as isMemberOfOrg } from "../org/membership.js";
 import { upsertVerifiedIntegrationIdentity } from "./identity-links-store.js";
 import {
   getActiveIntegrationInstallationByKey,
@@ -74,16 +74,6 @@ async function resolveSlackInstallation(incoming: IncomingMessage) {
     : null;
 }
 
-async function isMemberOfOrg(email: string, orgId: string): Promise<boolean> {
-  const { rows } = await getDbExec().execute({
-    sql: `SELECT 1 FROM org_members
-        WHERE org_id = ? AND LOWER(email) = ?
-        LIMIT 1`,
-    args: [orgId, email],
-  });
-  return rows.length > 0;
-}
-
 /**
  * Resolve the default integration principal.
  *
@@ -150,7 +140,7 @@ export async function resolveDefaultIntegrationExecutionContext(
     incoming.tenantId
   ) {
     try {
-      isOrgMember = await isMemberOfOrg(email, installation.orgId);
+      isOrgMember = await isMemberOfOrg(installation.orgId, email);
     } catch {
       // A membership-store outage is not evidence that the sender is merely
       // unlinked. Fail closed instead of widening them to org-wide access.

package/corpus/core/src/jobs/actions/list-automation-runs.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { organizationResourceOwner } from "../../resources/store.js";
+import { listAutomationRuns, type AutomationRun } from "../run-history.js";
+
+const scopeSchema = z.enum(["personal", "organization"]);
+
+export default defineAction({
+  description:
+    "List past execution records for one automation or recurring job in the selected scope.",
+  agentTool: false,
+  schema: z.object({
+    name: z.string().min(1),
+    scope: scopeSchema.default("personal"),
+    limit: z.number().int().min(1).max(100).optional(),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  parallelSafe: true,
+  run: async ({ name, scope, limit }, ctx): Promise<AutomationRun[]> => {
+    const userEmail = ctx?.userEmail;
+    if (!userEmail) throw new Error("Not authenticated.");
+    if (scope === "organization" && !ctx?.orgId) return [];
+
+    const owner =
+      scope === "organization"
+        ? organizationResourceOwner(ctx.orgId as string)
+        : userEmail;
+
+    return listAutomationRuns({ owners: [owner], automation: name, limit });
+  },
+});

package/corpus/core/src/jobs/actions/list-recurring-jobs.ts

@@ -6,7 +6,12 @@ import {
   resourceGetByPath,
   resourceList,
 } from "../../resources/store.js";
-import { describeCron, isValidCron, nextOccurrence } from "../cron.js";
+import {
+  describeCron,
+  effectiveTimezone,
+  isValidCron,
+  nextOccurrence,
+} from "../cron.js";
 import { classifyJobResource } from "../frontmatter.js";
 import { parseJobFrontmatter } from "../scheduler.js";
 import { authorizeJobMutation } from "../tools.js";
@@ -17,15 +22,25 @@ function jobName(path: string): string {
   return path.replace(/^jobs\//, "").replace(/\.md$/, "");
 }
 
+/**
+ * A stored `nextRun` in the past means the scheduler kept declining to run the
+ * job, not that it is due two days ago. Report the real next occurrence and
+ * let `lastError` carry the reason it keeps being passed over.
+ */
 function nextRun(
   meta: ReturnType<typeof parseJobFrontmatter>["meta"],
 ): string | null {
   if (!meta.enabled) return null;
-  if (meta.nextRun) return meta.nextRun;
-  if (meta.schedule && isValidCron(meta.schedule)) {
-    return nextOccurrence(meta.schedule).toISOString();
+  const scheduled = Boolean(meta.schedule && isValidCron(meta.schedule));
+  if (meta.nextRun) {
+    const stored = new Date(meta.nextRun).getTime();
+    if (!Number.isFinite(stored) || stored > Date.now() || !scheduled) {
+      return meta.nextRun;
+    }
   }
-  return null;
+  return scheduled
+    ? nextOccurrence(meta.schedule, undefined, meta.timezone).toISOString()
+    : null;
 }
 
 export interface RecurringJobActionItem {
@@ -34,10 +49,12 @@ export interface RecurringJobActionItem {
   path: string;
   scope: "personal" | "organization";
   schedule: string;
+  timezone: string;
   scheduleDescription: string;
   instructions: string;
   enabled: boolean;
   lastRun: string | null;
+  lastCheck: string | null;
   lastStatus: string | null;
   lastError: string | null;
   nextRun: string | null;
@@ -87,10 +104,14 @@ export default defineAction({
         path: full.path,
         scope,
         schedule: meta.schedule,
-        scheduleDescription: meta.schedule ? describeCron(meta.schedule) : "",
+        timezone: effectiveTimezone(meta.timezone),
+        scheduleDescription: meta.schedule
+          ? describeCron(meta.schedule, effectiveTimezone(meta.timezone))
+          : "",
         instructions: body,
         enabled: meta.enabled,
         lastRun: meta.lastRun ?? null,
+        lastCheck: meta.lastCheck ?? null,
         lastStatus: meta.lastStatus ?? null,
         lastError: meta.lastError ?? null,
         nextRun: nextRun(meta),

package/corpus/core/src/jobs/actions/manage-recurring-job.ts

@@ -7,8 +7,9 @@ import {
   resourceGetByPath,
   resourcePut,
 } from "../../resources/store.js";
-import { isValidCron, nextOccurrence } from "../cron.js";
+import { isValidCron, isValidTimezone, nextOccurrence } from "../cron.js";
 import { classifyJobResource } from "../frontmatter.js";
+import { deleteAutomationRuns } from "../run-history.js";
 import { buildJobContent, parseJobFrontmatter } from "../scheduler.js";
 import { authorizeJobMutation } from "../tools.js";
 
@@ -23,8 +24,10 @@ export default defineAction({
     name: z.string().min(1),
     scope: scopeSchema.default("personal"),
     enabled: z.boolean().optional(),
+    schedule: z.string().min(1).optional(),
+    timezone: z.string().min(1).optional(),
   }),
-  run: async ({ operation, name, scope, enabled }, ctx) => {
+  run: async ({ operation, name, scope, enabled, schedule, timezone }, ctx) => {
     const userEmail = ctx?.userEmail;
     if (!userEmail) throw new Error("Not authenticated.");
     if (scope === "organization" && !ctx?.orgId) {
@@ -54,17 +57,46 @@ export default defineAction({
 
     if (operation === "delete") {
       await resourceDelete(resource.id);
+      // Names are reusable; history left behind would surface as the run
+      // history of whatever job is next created under this name.
+      await deleteAutomationRuns(resource.owner, name);
       return { deleted: true, name };
     }
 
-    if (enabled === undefined) {
-      throw Object.assign(new Error("enabled is required for update."), {
-        statusCode: 400,
-      });
+    if (timezone !== undefined) {
+      if (!isValidTimezone(timezone)) {
+        throw Object.assign(new Error(`Unknown timezone "${timezone}".`), {
+          statusCode: 400,
+        });
+      }
+      meta.timezone = timezone;
+    }
+    if (
+      enabled === undefined &&
+      schedule === undefined &&
+      timezone === undefined
+    ) {
+      throw Object.assign(
+        new Error("enabled, schedule, or timezone is required for update."),
+        { statusCode: 400 },
+      );
+    }
+    if (schedule !== undefined) {
+      if (!isValidCron(schedule)) {
+        throw Object.assign(
+          new Error(`Invalid cron expression "${schedule}".`),
+          { statusCode: 400 },
+        );
+      }
+      meta.schedule = schedule;
     }
-    meta.enabled = enabled;
-    if (enabled && meta.schedule && isValidCron(meta.schedule)) {
-      meta.nextRun = nextOccurrence(meta.schedule).toISOString();
+    if (enabled !== undefined) meta.enabled = enabled;
+    if (meta.enabled && meta.schedule && isValidCron(meta.schedule)) {
+      meta.nextRun = nextOccurrence(
+        meta.schedule,
+        undefined,
+        meta.timezone,
+      ).toISOString();
     }
     await resourcePut(
       resource.owner,

package/corpus/core/src/jobs/background-automation-runner.ts

@@ -32,6 +32,11 @@ import {
   type RequestContext,
 } from "../server/request-context.js";
 import type { JobFrontmatter } from "./frontmatter.js";
+import {
+  attachAutomationRunThread,
+  finishAutomationRun,
+  startAutomationRun,
+} from "./run-history.js";
 
 const BACKGROUND_RUN_STUCK_MS = 10 * 60_000;
 const BACKGROUND_RUN_HARD_TIMEOUT_MS = 5 * 60_000;
@@ -248,6 +253,87 @@ function createRunId(prefix: string): string {
 export async function runBackgroundAutomation(
   options: BackgroundAutomationRunOptions,
   deps: BackgroundAutomationDeps,
+): Promise<BackgroundAutomationRunResult> {
+  const { automation } = options;
+  // Bookkeeping, so it must not gate the work it describes: a history table
+  // that cannot be written should cost us the record, not the automation.
+  // Everything downstream tolerates a null id by skipping its own write.
+  let historyId: string | null = null;
+  try {
+    historyId = await startAutomationRun({
+      owner: automation.resource.owner,
+      automation: automation.name,
+      path: automation.resource.path,
+      scope: organizationIdFromResourceOwner(automation.resource.owner)
+        ? "organization"
+        : "personal",
+      orgId: options.orgId ?? null,
+    });
+  } catch (err) {
+    console.error(
+      `[automations] Could not open a history record for "${automation.name}"; running anyway:`,
+      err,
+    );
+  }
+
+  let result: BackgroundAutomationRunResult;
+  try {
+    result = await executeBackgroundAutomation(options, deps, historyId);
+  } catch (err) {
+    await recordRunOutcome(
+      historyId,
+      "error",
+      err instanceof Error ? err.message : String(err),
+    );
+    throw err;
+  }
+  // Outside the try: history is bookkeeping about the run, so a failure to
+  // write it must not turn a completed automation into a reported failure.
+  await recordRunOutcome(historyId, "success");
+  return result;
+}
+
+/**
+ * Link the run to its agent thread. Bookkeeping again: the automation is
+ * already executing by this point, so a failed write costs the cross-reference
+ * in the history view, not the run.
+ */
+async function recordRunThread(
+  historyId: string | null,
+  threadId: string,
+  runId: string,
+): Promise<void> {
+  if (!historyId) return;
+  try {
+    await attachAutomationRunThread(historyId, threadId, runId);
+  } catch (err) {
+    console.error(
+      `[automations] Could not attach thread ${threadId} to run ${historyId}:`,
+      err,
+    );
+  }
+}
+
+async function recordRunOutcome(
+  historyId: string | null,
+  status: "success" | "error",
+  error?: string,
+): Promise<void> {
+  if (!historyId) return;
+  try {
+    await finishAutomationRun(historyId, status, error);
+  } catch (err) {
+    console.error(
+      `[automations] Could not record run ${historyId} as ${status}:`,
+      err,
+    );
+  }
+}
+
+async function executeBackgroundAutomation(
+  options: BackgroundAutomationRunOptions,
+  deps: BackgroundAutomationDeps,
+  historyId: string | null,
 ): Promise<BackgroundAutomationRunResult> {
   const { automation, ownerEmail, orgId, prompt, threadTitle, usageLabel } =
     options;
@@ -291,6 +377,8 @@ export async function runBackgroundAutomation(
       const systemPrompt = await deps.getSystemPrompt(ownerEmail);
       const thread = await createThread(ownerEmail, { title: threadTitle });
       const runId = createRunId(options.runIdPrefix);
+      await recordRunThread(historyId, thread.id, runId);
+
       // Scheduled work is background work: it has no synchronous serverless
       // caller waiting on it, so it must not inherit the interactive clamp
       // (40s soft timeout, a 30s no-progress backstop at 0.75x that, and 6

package/corpus/core/src/jobs/cron.ts

@@ -9,12 +9,50 @@ function normalize(cronExpr: string): string {
   return ALIAS_MAP[cronExpr.trim().toLowerCase()] ?? cronExpr;
 }
 
+/**
+ * IANA zone the host process evaluates wall-clock times in. Jobs stored before
+ * schedules carried a `timezone` are interpreted here, so their meaning does
+ * not silently shift when timezone support is added.
+ */
+export function serverTimezone(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+
+export function isValidTimezone(timezone: string): boolean {
+  if (!timezone.trim()) return false;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: timezone });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the zone a schedule's wall-clock fields are read in. An absent
+ * `timezone` means the schedule predates timezone support, so it keeps its
+ * original host-relative meaning rather than being reinterpreted as UTC.
+ */
+export function effectiveTimezone(timezone?: string | null): string {
+  return timezone && isValidTimezone(timezone) ? timezone : serverTimezone();
+}
+
 /**
  * Compute the next occurrence of a cron expression after the given date.
+ * `timezone` is the IANA zone the expression's wall-clock fields refer to.
  */
-export function nextOccurrence(cronExpr: string, after?: Date): Date {
+export function nextOccurrence(
+  cronExpr: string,
+  after?: Date,
+  timezone?: string | null,
+): Date {
   const expr = CronExpressionParser.parse(normalize(cronExpr), {
     currentDate: after ?? new Date(),
+    tz: effectiveTimezone(timezone),
   });
   const next = expr.next();
   return next.toDate();
@@ -36,13 +74,21 @@ export function isValidCron(cronExpr: string): boolean {
  * Convert a cron expression to a human-readable description.
  * Handles common patterns; falls back to the raw expression for unusual ones.
  */
-export function describeCron(cronExpr: string): string {
+export function describeCron(
+  cronExpr: string,
+  timezone?: string | null,
+): string {
   const normalized = normalize(cronExpr);
   const parts = normalized.trim().split(/\s+/);
   if (parts.length !== 5) return cronExpr;
 
   const [minute, hour, dayOfMonth, month, dayOfWeek] = parts;
 
+  // A bare wall-clock time is ambiguous the moment the host and the reader sit
+  // in different zones, so every description carrying a time names its zone.
+  const zone = (text: string) =>
+    timezone ? text + " (" + timezone + ")" : text;
+
   // Every minute
   if (normalized === "* * * * *") return "Every minute";
 
@@ -98,7 +144,7 @@ export function describeCron(cronExpr: string): string {
 
   // Every day at specific time
   if (dayOfMonth === "*" && month === "*" && dayOfWeek === "*" && time) {
-    return `Every day at ${time}`;
+    return zone(`Every day at ${time}`);
   }
 
   // Weekdays
@@ -108,18 +154,18 @@ export function describeCron(cronExpr: string): string {
     (dayOfWeek === "1-5" || dayOfWeek === "MON-FRI") &&
     time
   ) {
-    return `Every weekday at ${time}`;
+    return zone(`Every weekday at ${time}`);
   }
 
   // Specific day of week
   if (dayOfMonth === "*" && month === "*" && dayOfWeek !== "*" && time) {
     const days = dayOfWeek.split(",").map((d) => dayNames[d] || d);
-    return `Every ${days.join(", ")} at ${time}`;
+    return zone(`Every ${days.join(", ")} at ${time}`);
   }
 
   // Specific day of month
   if (dayOfMonth !== "*" && month === "*" && dayOfWeek === "*" && time) {
-    return `On day ${dayOfMonth} of every month at ${time}`;
+    return zone(`On day ${dayOfMonth} of every month at ${time}`);
   }
 
   return cronExpr;

package/corpus/core/src/jobs/frontmatter.ts

@@ -11,10 +11,22 @@ export type JobExecutionMode = "agentic" | "deterministic";
 export interface JobFrontmatter {
   schedule: string;
   enabled: boolean;
+  /**
+   * IANA zone the cron fields are read in. Absent means the schedule predates
+   * timezone support and keeps its original host-relative meaning.
+   */
+  timezone?: string;
   createdBy?: string;
   orgId?: string;
   runAs?: "creator" | "shared";
+  /** Last time the automation actually started executing. */
   lastRun?: string;
+  /**
+   * Last time a tick evaluated this automation and declined to run it. Kept
+   * distinct from `lastRun` so a blocked automation cannot report a run it
+   * never performed.
+   */
+  lastCheck?: string;
   lastStatus?: JobLastStatus;
   lastError?: string;
   nextRun?: string;
@@ -132,6 +144,9 @@ function parseKnownField(
     case "enabled":
       meta.enabled = value !== "false";
       break;
+    case "timezone":
+      meta.timezone = value || undefined;
+      break;
     case "createdBy":
       meta.createdBy = value;
       break;
@@ -145,6 +160,9 @@ function parseKnownField(
     case "lastRun":
       meta.lastRun = value;
       break;
+    case "lastCheck":
+      meta.lastCheck = value;
+      break;
     case "lastStatus":
       meta.lastStatus = value as JobLastStatus;
       break;
@@ -290,7 +308,9 @@ export function buildJobResourceContent(
   pushString(lines, "createdBy", meta.createdBy, false);
   pushString(lines, "orgId", meta.orgId);
   if (meta.runAs) lines.push(`runAs: ${meta.runAs}`);
+  pushString(lines, "timezone", meta.timezone);
   pushString(lines, "lastRun", meta.lastRun);
+  pushString(lines, "lastCheck", meta.lastCheck);
   if (meta.lastStatus) lines.push(`lastStatus: ${meta.lastStatus}`);
   pushString(lines, "lastError", meta.lastError);
   pushString(lines, "nextRun", meta.nextRun);