@robodev-ai/runtime 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robodev-ai/runtime",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Robodev project runtime — deploy-file classification, esbuild compile, module loading, schema push, route matching, OpenAPI, handler invocation, and Robodev Auth. Shared by hosted Starbase and `robodev dev`.",
   "type": "module",
   "license": "MIT",
@@ -32,7 +32,7 @@
     "pg": "^8.16.3",
     "zod": "^3.25.76",
     "zod-to-json-schema": "^3.24.6",
-    "@robodev-ai/sdk": "0.10.0"
+    "@robodev-ai/sdk": "0.11.0"
   },
   "devDependencies": {
     "@types/busboy": "^1.5.4",

package/src/cron.test.ts

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { nextRunAfter, parseCron } from "./cron.js";
+
+test("* * * * * is the next minute", () => {
+  const from = new Date(Date.UTC(2026, 0, 1, 12, 0, 30));
+  assert.deepEqual(nextRunAfter("* * * * *", from), new Date(Date.UTC(2026, 0, 1, 12, 1, 0)));
+});
+
+test("0 0 * * * is the next midnight", () => {
+  const from = new Date(Date.UTC(2026, 0, 1, 12, 30, 0));
+  assert.deepEqual(nextRunAfter("0 0 * * *", from), new Date(Date.UTC(2026, 0, 2, 0, 0, 0)));
+});
+
+test("rejects 6-field and invalid expressions", () => {
+  assert.throws(() => parseCron("* * * * * *"), /exactly 5 fields/);
+  assert.throws(() => parseCron("not-cron"), /exactly 5 fields/);
+  assert.throws(() => parseCron("60 * * * *"), /invalid cron field/);
+});

package/src/cron.ts

@@ -0,0 +1,86 @@
+const FIELD_RANGES = [
+  { min: 0, max: 59 },
+  { min: 0, max: 23 },
+  { min: 1, max: 31 },
+  { min: 1, max: 12 },
+  { min: 0, max: 7 },
+] as const;
+
+export type CronFields = [Set<number>, Set<number>, Set<number>, Set<number>, Set<number>];
+
+function expandField(field: string, min: number, max: number): Set<number> {
+  const values = new Set<number>();
+  for (const part of field.split(",")) {
+    const [rangePart, stepPart] = part.split("/");
+    const step = stepPart ? Number(stepPart) : 1;
+    if (!Number.isInteger(step) || step < 1) {
+      throw new Error("invalid cron field");
+    }
+    let start = min;
+    let end = max;
+    if (rangePart && rangePart !== "*") {
+      if (rangePart.includes("-")) {
+        const [fromRaw, toRaw] = rangePart.split("-");
+        start = Number(fromRaw);
+        end = Number(toRaw);
+      } else {
+        start = Number(rangePart);
+        end = start;
+      }
+    }
+    if (
+      !Number.isInteger(start) ||
+      !Number.isInteger(end) ||
+      start < min ||
+      end > max ||
+      start > end
+    ) {
+      throw new Error("invalid cron field");
+    }
+    for (let value = start; value <= end; value += step) {
+      values.add(value);
+    }
+  }
+  if (max === 7 && values.has(7)) values.add(0);
+  return values;
+}
+
+export function parseCron(expr: string): CronFields {
+  const fields = expr.trim().split(/\s+/);
+  if (fields.length !== 5) {
+    throw new Error("cron must have exactly 5 fields");
+  }
+  return FIELD_RANGES.map((range, index) =>
+    expandField(fields[index] ?? "", range.min, range.max),
+  ) as CronFields;
+}
+
+function matches(date: Date, fields: CronFields): boolean {
+  const [minutes, hours, days, months, weekdays] = fields;
+  const dow = date.getUTCDay();
+  return (
+    minutes.has(date.getUTCMinutes()) &&
+    hours.has(date.getUTCHours()) &&
+    days.has(date.getUTCDate()) &&
+    months.has(date.getUTCMonth() + 1) &&
+    (weekdays.has(dow) || (dow === 0 && weekdays.has(7)))
+  );
+}
+
+export function nextRunAfter(expr: string, from: Date): Date {
+  const fields = parseCron(expr);
+  const cursor = new Date(from.getTime());
+  cursor.setUTCSeconds(0, 0);
+  cursor.setUTCMinutes(cursor.getUTCMinutes() + 1);
+  const limit = cursor.getTime() + 366 * 24 * 60 * 60 * 1000;
+  while (cursor.getTime() <= limit) {
+    if (matches(cursor, fields)) return new Date(cursor);
+    cursor.setUTCMinutes(cursor.getUTCMinutes() + 1);
+  }
+  throw new Error("could not find next cron run");
+}
+
+export function assertFiveFieldCron(expr: string): string {
+  parseCron(expr);
+  return expr.trim();
+}

package/src/index.ts

@@ -1,7 +1,8 @@
 /**
  * `@robodev-ai/runtime` — the project runtime shared by hosted Starbase deploys and the
  * offline `robodev dev` loop: deploy-file classification, the esbuild compile, module
- * loading, schema push, route matching, OpenAPI, handler invocation, and Robodev Auth.
+ * loading, schema push, route matching, OpenAPI, handler invocation, Robodev Auth,
+ * and the offline `robodev dev` jobs engine.
  */
 
 export {
@@ -193,3 +194,31 @@ export {
   type LocalAuthRequest,
   type LocalAuthResult,
 } from "./local-auth.js";
+
+export { assertFiveFieldCron, nextRunAfter, parseCron, type CronFields } from "./cron.js";
+
+export {
+  JOB_CONCURRENCY,
+  JOB_MAX_ATTEMPTS,
+  JOB_PAYLOAD_MAX_BYTES,
+  assertJobCrons,
+  assertKnownJob,
+  jobBackoffMs,
+  nextJobFailureState,
+  serializeJobPayload,
+  type JobCronDefinition,
+} from "./job-queue.js";
+
+export {
+  LOCAL_JOB_CRON_MS,
+  LOCAL_JOB_WORKER_MS,
+  createLocalJobsEngine,
+  ensureJobsSchema,
+  type JobsQueryable,
+  type LocalCronRow,
+  type LocalJobRow,
+  type LocalJobStatus,
+  type LocalJobsEngine,
+  type LocalJobsEngineOptions,
+  type LocalJobsGeneration,
+} from "./local-jobs.js";

package/src/invoke.ts

@@ -56,9 +56,6 @@ export type RunRouteInput = {
   resolveUser: (authorization?: string) => Promise<AuthUser | null>;
   /** Built after auth passes, right before the handler runs. */
   clients: () => Promise<RouteClients> | RouteClients;
-  /** True when the request carries a valid schedule signature. */
-  verifySchedule?: (headers: Record<string, string | string[] | undefined>) => boolean;
-  scheduleId?: string;
   /** Lets the host translate its own error types before the generic 500. */
   mapError?: (error: unknown) => MappedError | null;
 };
@@ -145,22 +142,13 @@ export async function runRoute(input: RunRouteInput): Promise<RouteOutcome> {
     body = parsed.data;
   }
 
-  const scheduleValid = input.verifySchedule ? input.verifySchedule(input.headers) : false;
-  const schedule = scheduleValid
-    ? { id: input.scheduleId ?? "schedule" }
-    : input.scheduleId
-      ? { id: input.scheduleId }
-      : null;
-
   let user: AuthUser | null = null;
   const auth = route.def.auth ?? false;
-  if (auth === "schedule") {
-    if (!scheduleValid) {
-      return invalid(401, {
-        error: "unauthorized",
-        message: "missing or invalid schedule signature",
-      });
-    }
+  if (typeof auth === "string" && auth !== "required" && auth !== "optional") {
+    return invalid(401, {
+      error: "unauthorized",
+      message: "legacy schedule auth is no longer supported",
+    });
   } else if (typeof auth === "function") {
     try {
       user = await auth({ headers: input.headers });
@@ -202,7 +190,6 @@ export async function runRoute(input: RunRouteInput): Promise<RouteOutcome> {
       push: clients.push,
       jobs: clients.jobs,
       sockets: clients.sockets,
-      schedule,
     };
     const result = await withHandlerTimeout(
       () => Promise.resolve(route.def.handler(context)),

package/src/job-queue.test.ts

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  assertJobCrons,
+  assertKnownJob,
+  JOB_MAX_ATTEMPTS,
+  JOB_PAYLOAD_MAX_BYTES,
+  jobBackoffMs,
+  nextJobFailureState,
+  serializeJobPayload,
+} from "./job-queue.js";
+
+function job(name: string, cron?: string, file = `jobs/${name}.ts`) {
+  return { name, file, def: cron === undefined ? {} : { cron } };
+}
+
+test("enqueue row is queued with serialized payload", () => {
+  assertKnownJob("resize", ["resize", "email"]);
+  const payloadJson = serializeJobPayload({ key: "avatar.png" });
+  assert.equal(JSON.parse(payloadJson).key, "avatar.png");
+  const row = {
+    name: "resize",
+    payload_json: payloadJson,
+    status: "queued" as const,
+    attempts: 0,
+  };
+  assert.equal(row.status, "queued");
+  assert.equal(row.attempts, 0);
+});
+
+test("unknown name throws", () => {
+  assert.throws(() => assertKnownJob("missing", ["resize"]), /Unknown job name: missing/);
+});
+
+test("oversize payload throws", () => {
+  const oversized = "x".repeat(JOB_PAYLOAD_MAX_BYTES);
+  assert.throws(() => serializeJobPayload(oversized), /job payload must be at most 256KB/);
+  assert.equal(serializeJobPayload(undefined), "null");
+});
+
+test("backoff then dead after 5 attempts", () => {
+  assert.equal(jobBackoffMs(1), 1000);
+  assert.equal(jobBackoffMs(2), 4000);
+  let state = nextJobFailureState(1);
+  for (let attempts = 2; attempts < JOB_MAX_ATTEMPTS; attempts++) {
+    assert.equal(state.status, "queued");
+    assert.ok(state.runAt);
+    state = nextJobFailureState(attempts);
+  }
+  state = nextJobFailureState(JOB_MAX_ATTEMPTS);
+  assert.equal(state.status, "dead");
+  assert.equal(state.runAt, null);
+});
+
+test("invalid cron fails with hosted error shape", () => {
+  assert.throws(
+    () => assertJobCrons([job("digest", "not-a-cron")]),
+    (error: unknown) => {
+      const err = error as { statusCode?: number; code?: string; path?: string };
+      return (
+        err.statusCode === 400 && err.code === "invalid_job_cron" && err.path === "jobs/digest.ts"
+      );
+    },
+  );
+  assert.throws(() => assertJobCrons([job("digest", "")]));
+  assert.throws(() => assertJobCrons([job("digest", "   ")]));
+  assert.doesNotThrow(() => assertJobCrons([job("digest"), job("hourly", "0 * * * *")]));
+});

package/src/job-queue.ts

@@ -0,0 +1,58 @@
+import { assertFiveFieldCron } from "./cron.js";
+
+export const JOB_MAX_ATTEMPTS = 5;
+export const JOB_PAYLOAD_MAX_BYTES = 256 * 1024;
+export const JOB_CONCURRENCY = 4;
+
+export type JobCronDefinition = {
+  name: string;
+  file?: string;
+  def: { cron?: string };
+};
+
+export function jobBackoffMs(attempt: number): number {
+  return Math.min(1000 * 4 ** Math.max(attempt - 1, 0), 300_000);
+}
+
+export function nextJobFailureState(attempts: number): {
+  status: "queued" | "dead";
+  runAt: Date | null;
+} {
+  if (attempts >= JOB_MAX_ATTEMPTS) {
+    return { status: "dead", runAt: null };
+  }
+  return { status: "queued", runAt: new Date(Date.now() + jobBackoffMs(attempts)) };
+}
+
+export function serializeJobPayload(payload: unknown): string {
+  const json = JSON.stringify(payload ?? null);
+  if (Buffer.byteLength(json, "utf8") > JOB_PAYLOAD_MAX_BYTES) {
+    throw new Error("job payload must be at most 256KB");
+  }
+  return json;
+}
+
+export function assertKnownJob(name: string, known: Iterable<string>): void {
+  const names = new Set(known);
+  if (!names.has(name)) {
+    throw new Error(`Unknown job name: ${name}`);
+  }
+}
+
+export function assertJobCrons(jobs: readonly JobCronDefinition[]): void {
+  for (const job of jobs) {
+    if (job.def.cron === undefined) continue;
+    try {
+      if (typeof job.def.cron !== "string" || job.def.cron.trim() === "") {
+        throw new Error("cron must be a non-empty 5-field expression");
+      }
+      assertFiveFieldCron(job.def.cron);
+    } catch (error) {
+      throw Object.assign(new Error(error instanceof Error ? error.message : "invalid cron"), {
+        statusCode: 400,
+        code: "invalid_job_cron",
+        path: job.file ?? `jobs/${job.name}.ts`,
+      });
+    }
+  }
+}

package/src/local-jobs.test.ts

@@ -0,0 +1,448 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type { JobDefinition, JobHandlerContext, RobodevDb } from "@robodev-ai/sdk";
+import { JOB_KIND } from "@robodev-ai/sdk";
+import { nextRunAfter } from "./cron.js";
+import type { RouteClients } from "./invoke.js";
+import { JOB_MAX_ATTEMPTS, JOB_PAYLOAD_MAX_BYTES } from "./job-queue.js";
+import {
+  createLocalJobsEngine,
+  ensureJobsSchema,
+  type JobsQueryable,
+  type LocalCronRow,
+  type LocalJobRow,
+  type LocalJobsGeneration,
+} from "./local-jobs.js";
+
+function jobDef(
+  handler: (ctx: JobHandlerContext) => Promise<unknown> | unknown,
+  extras: { timeoutMs?: number; cron?: string } = {},
+): JobDefinition {
+  return { _kind: JOB_KIND, handler, ...extras };
+}
+
+function unavailable(feature: string): never {
+  throw new Error(`ctx.${feature} needs hosted Starbase. Run robodev deploy to use it.`);
+}
+
+function mockClients(): RouteClients {
+  return {
+    email: {
+      async send() {
+        return { id: "local_mail", status: "sent" };
+      },
+    },
+    llm: { complete: () => unavailable("llm"), stream: () => unavailable("llm") },
+    agent: {
+      createSession: () => unavailable("agent"),
+      start: () => unavailable("agent"),
+      events: () => unavailable("agent"),
+      subscribe: () => unavailable("agent"),
+      destroy: () => unavailable("agent"),
+    },
+    storage: {
+      upload: () => unavailable("storage"),
+      get: () => unavailable("storage"),
+      getUrl: () => unavailable("storage"),
+      delete: () => unavailable("storage"),
+      list: () => unavailable("storage"),
+    },
+    push: { send: () => unavailable("push") },
+    jobs: { enqueue: async () => ({ id: "nested" }) },
+    sockets: {
+      send: () => unavailable("sockets"),
+      broadcast: () => unavailable("sockets"),
+    },
+    env: {},
+  };
+}
+
+function memoryJobs() {
+  const jobs: LocalJobRow[] = [];
+  const crons: LocalCronRow[] = [];
+  const now = () => new Date();
+
+  const query: JobsQueryable["query"] = async (text, values = []) => {
+    const sql = text.replace(/\s+/g, " ").trim();
+    if (/^(CREATE SCHEMA|CREATE TABLE|CREATE INDEX)/.test(sql)) return { rows: [] };
+
+    if (sql.includes("INSERT INTO robodev_jobs.jobs")) {
+      const created = now();
+      jobs.push({
+        id: String(values[0]),
+        name: String(values[1]),
+        payload_json: String(values[2]),
+        status: "queued",
+        attempts: 0,
+        max_attempts: Number(values[3]),
+        run_at: values[4] as Date,
+        last_error: null,
+        created_at: created,
+        updated_at: created,
+      });
+      return { rows: [] };
+    }
+
+    if (sql.includes("FOR UPDATE SKIP LOCKED")) {
+      const due = jobs
+        .filter((row) => row.status === "queued" && row.run_at.getTime() <= Date.now())
+        .sort((a, b) => a.run_at.getTime() - b.run_at.getTime())[0];
+      if (!due) return { rows: [] };
+      due.status = "running";
+      due.updated_at = now();
+      return { rows: [{ ...due }] };
+    }
+
+    if (sql.includes("SET status = 'succeeded'")) {
+      const row = jobs.find((entry) => entry.id === values[0]);
+      if (row) {
+        row.status = "succeeded";
+        row.last_error = null;
+        row.updated_at = now();
+      }
+      return { rows: [] };
+    }
+
+    if (sql.includes("run_at = COALESCE")) {
+      const row = jobs.find((entry) => entry.id === values[0]);
+      if (row) {
+        row.status = values[1] as LocalJobRow["status"];
+        row.attempts = Number(values[2]);
+        row.last_error = (values[3] as string | null) ?? null;
+        if (values[4]) row.run_at = values[4] as Date;
+        row.updated_at = now();
+      }
+      return { rows: [] };
+    }
+
+    if (sql.includes("WHERE status = 'running'") && sql.includes("SET status = 'queued'")) {
+      for (const row of jobs) {
+        if (row.status === "running") {
+          row.status = "queued";
+          row.updated_at = now();
+        }
+      }
+      return { rows: [] };
+    }
+
+    if (sql.includes("INSERT INTO robodev_jobs.crons")) {
+      crons.push({
+        job_name: String(values[0]),
+        cron: String(values[1]),
+        next_run_at: values[2] as Date,
+      });
+      return { rows: [] };
+    }
+
+    if (sql.includes("FROM robodev_jobs.crons") && sql.includes("WHERE next_run_at <=")) {
+      const at = values[0] as Date;
+      return {
+        rows: crons
+          .filter((row) => row.next_run_at.getTime() <= at.getTime())
+          .sort((a, b) => a.next_run_at.getTime() - b.next_run_at.getTime())
+          .slice(0, 50),
+      };
+    }
+
+    if (sql.includes("FROM robodev_jobs.crons") && sql.includes("SELECT job_name")) {
+      return { rows: [...crons] };
+    }
+
+    if (sql.includes("UPDATE robodev_jobs.crons") && sql.includes("SET cron")) {
+      const row = crons.find((entry) => entry.job_name === values[0]);
+      if (row) {
+        row.cron = String(values[1]);
+        row.next_run_at = values[2] as Date;
+      }
+      return { rows: [] };
+    }
+
+    if (sql.includes("UPDATE robodev_jobs.crons") && sql.includes("SET next_run_at")) {
+      const row = crons.find((entry) => entry.job_name === values[0]);
+      if (row) row.next_run_at = values[1] as Date;
+      return { rows: [] };
+    }
+
+    if (sql.includes("DELETE FROM robodev_jobs.crons")) {
+      const keep = new Set(values[0] as string[]);
+      for (let i = crons.length - 1; i >= 0; i--) {
+        if (!keep.has(crons[i]!.job_name)) crons.splice(i, 1);
+      }
+      return { rows: [] };
+    }
+
+    throw new Error(`unexpected query: ${sql}`);
+  };
+
+  return { jobs, crons, query };
+}
+
+async function waitUntil(pred: () => boolean, ms = 1000): Promise<void> {
+  const start = Date.now();
+  while (!pred()) {
+    if (Date.now() - start > ms) throw new Error("timed out waiting");
+    await new Promise((resolve) => setImmediate(resolve));
+  }
+}
+
+function engineFor(
+  store: ReturnType<typeof memoryJobs>,
+  jobs: LocalJobsGeneration["jobs"],
+  logs: string[] = [],
+) {
+  const generation: LocalJobsGeneration = { db: {} as RobodevDb, jobs };
+  return createLocalJobsEngine({
+    query: store.query,
+    getGeneration: () => generation,
+    log: (line) => logs.push(line),
+    clients: mockClients,
+  });
+}
+
+test("ensureJobsSchema is idempotent SQL", async () => {
+  const store = memoryJobs();
+  await ensureJobsSchema({ query: store.query });
+  await ensureJobsSchema({ query: store.query });
+});
+
+test("enqueue known job; unknown and oversize throw without insert", async () => {
+  const store = memoryJobs();
+  const engine = engineFor(store, [{ name: "digest", def: jobDef(() => undefined) }]);
+  const queued = await engine.enqueue({ name: "digest", payload: { ok: true } });
+  assert.match(queued.id, /^job_/);
+  assert.equal(store.jobs.length, 1);
+  assert.equal(JSON.parse(store.jobs[0]!.payload_json).ok, true);
+
+  await assert.rejects(() => engine.enqueue({ name: "missing" }), /Unknown job name: missing/);
+  await assert.rejects(
+    () => engine.enqueue({ name: "digest", payload: "x".repeat(JOB_PAYLOAD_MAX_BYTES) }),
+    /job payload must be at most 256KB/,
+  );
+  assert.equal(store.jobs.length, 1);
+});
+
+test("successful handler marks succeeded and logs", async () => {
+  const store = memoryJobs();
+  const logs: string[] = [];
+  const seen: unknown[] = [];
+  const engine = engineFor(
+    store,
+    [{ name: "digest", def: jobDef((ctx) => seen.push(ctx.payload)) }],
+    logs,
+  );
+  await engine.enqueue({ name: "digest", payload: { n: 1 } });
+  await engine.tickJobs();
+  await waitUntil(() => store.jobs[0]?.status === "succeeded" && logs.length > 0);
+  assert.deepEqual(seen, [{ n: 1 }]);
+  assert.equal(logs[0], "  digest succeeded");
+});
+
+test("throw backs off then dead at 5", async () => {
+  const store = memoryJobs();
+  const logs: string[] = [];
+  const engine = engineFor(
+    store,
+    [
+      {
+        name: "digest",
+        def: jobDef(() => {
+          throw new Error("boom");
+        }),
+      },
+    ],
+    logs,
+  );
+  await engine.enqueue({ name: "digest" });
+  for (let attempt = 1; attempt <= JOB_MAX_ATTEMPTS; attempt++) {
+    store.jobs[0]!.run_at = new Date(0);
+    store.jobs[0]!.status = "queued";
+    await engine.tickJobs();
+    await waitUntil(() => store.jobs[0]!.status !== "running");
+  }
+  assert.equal(store.jobs[0]?.status, "dead");
+  assert.equal(store.jobs[0]?.attempts, 5);
+  assert.equal(store.jobs[0]?.last_error, "boom");
+  assert.match(logs[0] ?? "", /failed attempt 1\/5: boom/);
+  assert.match(logs.at(-1) ?? "", /digest dead: boom/);
+});
+
+test("timeout is handler_timeout and retries", async () => {
+  const store = memoryJobs();
+  const logs: string[] = [];
+  const engine = engineFor(
+    store,
+    [
+      {
+        name: "slow",
+        def: jobDef(() => new Promise((resolve) => setTimeout(resolve, 50)), { timeoutMs: 10 }),
+      },
+    ],
+    logs,
+  );
+  await engine.enqueue({ name: "slow" });
+  await engine.tickJobs();
+  await waitUntil(() => store.jobs[0]?.last_error === "handler_timeout");
+  assert.equal(store.jobs[0]?.status, "queued");
+  assert.equal(store.jobs[0]?.last_error, "handler_timeout");
+  assert.match(logs[0] ?? "", /failed attempt 1\/5: handler_timeout/);
+});
+
+test("reconcile keeps unchanged next_run, reschedules, and deletes", async () => {
+  const now = new Date("2026-01-01T00:00:00.000Z");
+  const keptNext = new Date("2026-01-01T01:00:00.000Z");
+  const store = memoryJobs();
+  store.crons.push(
+    { job_name: "hourly", cron: "0 * * * *", next_run_at: keptNext },
+    { job_name: "stale", cron: "0 0 * * *", next_run_at: new Date("2026-01-02T00:00:00.000Z") },
+    { job_name: "daily", cron: "0 0 * * *", next_run_at: new Date("2026-01-02T00:00:00.000Z") },
+  );
+  const engine = engineFor(store, []);
+  await engine.reconcile(
+    [
+      { name: "hourly", def: { cron: "0 * * * *" } },
+      { name: "daily", def: { cron: "0 12 * * *" } },
+      { name: "fresh", def: { cron: "*/5 * * * *" } },
+    ],
+    now,
+  );
+  const byName = Object.fromEntries(store.crons.map((row) => [row.job_name, row]));
+  assert.equal(store.crons.length, 3);
+  assert.equal(byName.hourly?.next_run_at, keptNext);
+  assert.equal(byName.daily?.cron, "0 12 * * *");
+  assert.deepEqual(byName.daily?.next_run_at, nextRunAfter("0 12 * * *", now));
+  assert.deepEqual(byName.fresh?.next_run_at, nextRunAfter("*/5 * * * *", now));
+  assert.equal(byName.stale, undefined);
+});
+
+test("removing cron deletes the row", async () => {
+  const store = memoryJobs();
+  store.crons.push({
+    job_name: "hourly",
+    cron: "0 * * * *",
+    next_run_at: new Date("2026-01-01T01:00:00.000Z"),
+  });
+  const engine = engineFor(store, []);
+  await engine.reconcile([{ name: "hourly", def: {} }]);
+  assert.equal(store.crons.length, 0);
+});
+
+test("tick enqueues null payload, advances first, and does not roll back", async () => {
+  const now = new Date("2026-01-01T00:00:00.000Z");
+  const store = memoryJobs();
+  store.crons.push({ job_name: "hourly", cron: "0 * * * *", next_run_at: now });
+  const events: string[] = [];
+  const engine = createLocalJobsEngine({
+    query: async (text, values) => {
+      if (text.includes("UPDATE robodev_jobs.crons") && text.includes("SET next_run_at")) {
+        events.push("advance");
+      }
+      if (text.includes("INSERT INTO robodev_jobs.jobs")) events.push("enqueue");
+      return store.query(text, values);
+    },
+    getGeneration: () => ({
+      db: {} as RobodevDb,
+      jobs: [{ name: "hourly", def: jobDef(() => undefined) }],
+    }),
+    clients: mockClients,
+  });
+  await engine.tickDue(now);
+  assert.deepEqual(events, ["advance", "enqueue"]);
+  assert.equal(JSON.parse(store.jobs[0]!.payload_json), null);
+  assert.deepEqual(store.crons[0]?.next_run_at, nextRunAfter("0 * * * *", now));
+
+  const failStore = memoryJobs();
+  failStore.crons.push({ job_name: "hourly", cron: "0 * * * *", next_run_at: now });
+  const failing = createLocalJobsEngine({
+    query: failStore.query,
+    getGeneration: () => ({ db: {} as RobodevDb, jobs: [] }),
+    clients: mockClients,
+  });
+  await failing.tickDue(now);
+  assert.equal(failStore.jobs.length, 0);
+  assert.deepEqual(failStore.crons[0]?.next_run_at, nextRunAfter("0 * * * *", now));
+});
+
+test("overlap piles up queued rows", async () => {
+  const now = new Date("2026-01-01T00:00:00.000Z");
+  const store = memoryJobs();
+  store.crons.push({ job_name: "hourly", cron: "0 * * * *", next_run_at: now });
+  const engine = engineFor(store, [{ name: "hourly", def: jobDef(() => undefined) }]);
+  await engine.tickDue(now);
+  store.crons[0]!.next_run_at = now;
+  await engine.tickDue(now);
+  assert.equal(store.jobs.length, 2);
+  assert.equal(
+    store.jobs.every((row) => row.status === "queued"),
+    true,
+  );
+});
+
+test("missing handler is route_not_found", async () => {
+  const store = memoryJobs();
+  const logs: string[] = [];
+  const engine = engineFor(store, [], logs);
+  store.jobs.push({
+    id: "job_ghost",
+    name: "gone",
+    payload_json: "null",
+    status: "queued",
+    attempts: 0,
+    max_attempts: 5,
+    run_at: new Date(0),
+    last_error: null,
+    created_at: new Date(),
+    updated_at: new Date(),
+  });
+  await engine.tickJobs();
+  await waitUntil(() => store.jobs[0]?.last_error === "route_not_found");
+});
+
+test("hosted-only clients still throw in job handlers; email is real", async () => {
+  const store = memoryJobs();
+  const seen: string[] = [];
+  const engine = engineFor(store, [
+    {
+      name: "probe",
+      def: jobDef(async (ctx) => {
+        await ctx.email.send({ to: "a@b.c", subject: "hi" });
+        seen.push("email");
+        try {
+          await ctx.llm.complete({ messages: [{ role: "user", content: "x" }] });
+        } catch (error) {
+          seen.push((error as Error).message);
+        }
+      }),
+    },
+  ]);
+  await engine.enqueue({ name: "probe" });
+  await engine.tickJobs();
+  await waitUntil(() => store.jobs[0]?.status === "succeeded");
+  assert.equal(seen[0], "email");
+  assert.match(seen[1] ?? "", /ctx\.llm needs hosted Starbase/);
+});
+
+test("start resets running rows; stop clears timers", async () => {
+  const store = memoryJobs();
+  store.jobs.push({
+    id: "job_stuck",
+    name: "digest",
+    payload_json: "null",
+    status: "running",
+    attempts: 1,
+    max_attempts: 5,
+    run_at: new Date(),
+    last_error: null,
+    created_at: new Date(),
+    updated_at: new Date(),
+  });
+  const engine = engineFor(store, [{ name: "digest", def: jobDef(() => undefined) }]);
+  assert.equal(engine.running, false);
+  await engine.start();
+  assert.equal(store.jobs[0]?.status, "queued");
+  assert.equal(engine.running, true);
+  await engine.start();
+  assert.equal(engine.running, true);
+  await engine.stop();
+  assert.equal(engine.running, false);
+  await engine.stop();
+});

package/src/local-jobs.ts

@@ -0,0 +1,353 @@
+import type { JobDefinition, JobEnqueueInput, RobodevDb } from "@robodev-ai/sdk";
+import { assertFiveFieldCron, nextRunAfter } from "./cron.js";
+import { HandlerTimeoutError, clampTimeoutMs, withHandlerTimeout } from "./handler-timeout.js";
+import { id } from "./ids.js";
+import type { RouteClients } from "./invoke.js";
+import {
+  JOB_CONCURRENCY,
+  JOB_MAX_ATTEMPTS,
+  assertKnownJob,
+  nextJobFailureState,
+  serializeJobPayload,
+  type JobCronDefinition,
+} from "./job-queue.js";
+
+/** Hosted uses metadata `now()`; local worker/ticker intervals match hosted. */
+export const LOCAL_JOB_WORKER_MS = 1000;
+export const LOCAL_JOB_CRON_MS = 60_000;
+
+export type JobsQueryable = {
+  query: <T extends Record<string, unknown> = Record<string, unknown>>(
+    sql: string,
+    values?: unknown[],
+  ) => Promise<{ rows: T[] }>;
+};
+
+export type LocalJobStatus = "queued" | "running" | "succeeded" | "dead";
+
+export type LocalJobRow = {
+  id: string;
+  name: string;
+  payload_json: string;
+  status: LocalJobStatus;
+  attempts: number;
+  max_attempts: number;
+  run_at: Date;
+  last_error: string | null;
+  created_at: Date;
+  updated_at: Date;
+};
+
+export type LocalCronRow = {
+  job_name: string;
+  cron: string;
+  next_run_at: Date;
+};
+
+export type LocalJobsGeneration = {
+  db: RobodevDb;
+  jobs: readonly { name: string; file?: string; def: JobDefinition }[];
+};
+
+export type LocalJobsEngineOptions = {
+  query: JobsQueryable["query"];
+  getGeneration: () => LocalJobsGeneration | null;
+  log?: (line: string) => void;
+  clients: () => RouteClients;
+};
+
+export type LocalJobsEngine = {
+  enqueue: (input: JobEnqueueInput) => Promise<{ id: string }>;
+  reconcile: (jobs: readonly JobCronDefinition[], now?: Date) => Promise<void>;
+  tickDue: (now?: Date) => Promise<void>;
+  tickJobs: () => Promise<void>;
+  start: () => Promise<void>;
+  stop: () => Promise<void>;
+  readonly generation: LocalJobsGeneration | null;
+  readonly running: boolean;
+};
+
+function resolveRunAt(input: JobEnqueueInput): Date {
+  if (input.runAt) return input.runAt;
+  if (typeof input.delayMs === "number" && Number.isFinite(input.delayMs)) {
+    return new Date(Date.now() + Math.max(0, input.delayMs));
+  }
+  return new Date();
+}
+
+function desiredCronJobs(jobs: readonly JobCronDefinition[]): { name: string; cron: string }[] {
+  return jobs
+    .filter((job) => job.def.cron !== undefined)
+    .map((job) => ({ name: job.name, cron: assertFiveFieldCron(job.def.cron!) }));
+}
+
+function shortError(message: string): string {
+  const oneLine = message.split("\n")[0]?.trim() || "handler_failed";
+  return oneLine.length > 160 ? `${oneLine.slice(0, 157)}...` : oneLine;
+}
+
+/** Creates the reserved `robodev_jobs` schema. Idempotent, not drizzle, not public. */
+export async function ensureJobsSchema(db: JobsQueryable): Promise<void> {
+  await db.query(`CREATE SCHEMA IF NOT EXISTS robodev_jobs`);
+  await db.query(`
+    CREATE TABLE IF NOT EXISTS robodev_jobs.jobs (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      payload_json TEXT NOT NULL DEFAULT 'null',
+      status TEXT NOT NULL CHECK (status IN ('queued', 'running', 'succeeded', 'dead')),
+      attempts INTEGER NOT NULL DEFAULT 0,
+      max_attempts INTEGER NOT NULL DEFAULT 5,
+      run_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      last_error TEXT,
+      created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+    )
+  `);
+  await db.query(`
+    CREATE INDEX IF NOT EXISTS robodev_jobs_queued_run_at
+      ON robodev_jobs.jobs (status, run_at)
+      WHERE status = 'queued'
+  `);
+  await db.query(`
+    CREATE TABLE IF NOT EXISTS robodev_jobs.crons (
+      job_name TEXT PRIMARY KEY,
+      cron TEXT NOT NULL,
+      next_run_at TIMESTAMPTZ NOT NULL,
+      updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+    )
+  `);
+  await db.query(`
+    CREATE INDEX IF NOT EXISTS robodev_jobs_crons_next_run_at
+      ON robodev_jobs.crons (next_run_at)
+  `);
+}
+
+export function createLocalJobsEngine(options: LocalJobsEngineOptions): LocalJobsEngine {
+  const query = options.query;
+  const log = options.log ?? (() => undefined);
+  let inFlight = 0;
+  const running = new Set<Promise<void>>();
+  let workerTimer: ReturnType<typeof setInterval> | undefined;
+  let cronTimer: ReturnType<typeof setInterval> | undefined;
+
+  async function enqueue(input: JobEnqueueInput): Promise<{ id: string }> {
+    const generation = options.getGeneration();
+    const known = generation?.jobs.map((job) => job.name) ?? [];
+    assertKnownJob(input.name, known);
+    const payloadJson = serializeJobPayload(input.payload);
+    const jobId = id("job");
+    await query(
+      `INSERT INTO robodev_jobs.jobs
+         (id, name, payload_json, status, attempts, max_attempts, run_at)
+       VALUES ($1, $2, $3, 'queued', 0, $4, $5)`,
+      [jobId, input.name, payloadJson, JOB_MAX_ATTEMPTS, resolveRunAt(input)],
+    );
+    return { id: jobId };
+  }
+
+  async function reconcile(jobs: readonly JobCronDefinition[], now = new Date()): Promise<void> {
+    const desired = desiredCronJobs(jobs);
+    const existing = await query<LocalCronRow>(
+      `SELECT job_name, cron, next_run_at
+       FROM robodev_jobs.crons`,
+    );
+    const byName = new Map(existing.rows.map((row) => [row.job_name, row]));
+
+    for (const job of desired) {
+      const row = byName.get(job.name);
+      if (!row) {
+        await query(
+          `INSERT INTO robodev_jobs.crons (job_name, cron, next_run_at)
+           VALUES ($1, $2, $3)`,
+          [job.name, job.cron, nextRunAfter(job.cron, now)],
+        );
+        continue;
+      }
+      if (row.cron !== job.cron) {
+        await query(
+          `UPDATE robodev_jobs.crons
+           SET cron = $2, next_run_at = $3, updated_at = now()
+           WHERE job_name = $1`,
+          [job.name, job.cron, nextRunAfter(job.cron, now)],
+        );
+      }
+    }
+
+    await query(`DELETE FROM robodev_jobs.crons WHERE NOT (job_name = ANY($1::text[]))`, [
+      desired.map((job) => job.name),
+    ]);
+  }
+
+  async function tickDue(now = new Date()): Promise<void> {
+    const due = await query<LocalCronRow>(
+      `SELECT job_name, cron, next_run_at
+       FROM robodev_jobs.crons
+       WHERE next_run_at <= $1
+       ORDER BY next_run_at ASC
+       LIMIT 50`,
+      [now],
+    );
+    for (const row of due.rows) {
+      const nextRunAt = nextRunAfter(row.cron, now);
+      await query(
+        `UPDATE robodev_jobs.crons
+         SET next_run_at = $2, updated_at = now()
+         WHERE job_name = $1`,
+        [row.job_name, nextRunAt],
+      );
+      try {
+        await enqueue({ name: row.job_name, payload: null });
+      } catch {
+        // Tick is skipped after next_run_at advanced; do not roll back.
+      }
+    }
+  }
+
+  async function claimNextJob(): Promise<LocalJobRow | null> {
+    const result = await query<LocalJobRow>(
+      `UPDATE robodev_jobs.jobs
+       SET status = 'running', updated_at = now()
+       WHERE id = (
+         SELECT id FROM robodev_jobs.jobs
+         WHERE status = 'queued' AND run_at <= now()
+         ORDER BY run_at ASC
+         FOR UPDATE SKIP LOCKED
+         LIMIT 1
+       )
+       RETURNING id, name, payload_json, status, attempts, max_attempts, run_at,
+                 last_error, created_at, updated_at`,
+    );
+    return result.rows[0] ?? null;
+  }
+
+  async function finishJob(row: LocalJobRow, error: string | null): Promise<void> {
+    if (!error) {
+      await query(
+        `UPDATE robodev_jobs.jobs
+         SET status = 'succeeded', last_error = NULL, updated_at = now()
+         WHERE id = $1`,
+        [row.id],
+      );
+      log(`  ${row.name} succeeded`);
+      return;
+    }
+    const attempts = row.attempts + 1;
+    const next = nextJobFailureState(attempts);
+    await query(
+      `UPDATE robodev_jobs.jobs
+       SET status = $2, attempts = $3, last_error = $4, run_at = COALESCE($5, run_at), updated_at = now()
+       WHERE id = $1`,
+      [row.id, next.status, attempts, error, next.runAt],
+    );
+    if (next.status === "dead") {
+      log(`  ${row.name} dead: ${shortError(error)}`);
+    } else {
+      log(`  ${row.name} failed attempt ${attempts}/${JOB_MAX_ATTEMPTS}: ${shortError(error)}`);
+    }
+  }
+
+  async function runClaimedJob(
+    row: LocalJobRow,
+    generation: LocalJobsGeneration | null,
+  ): Promise<void> {
+    const job = generation?.jobs.find((entry) => entry.name === row.name);
+    if (!generation || !job) {
+      await finishJob(row, "route_not_found");
+      return;
+    }
+    let payload: unknown = null;
+    try {
+      payload = JSON.parse(row.payload_json) as unknown;
+    } catch {
+      payload = null;
+    }
+    const clients = options.clients();
+    try {
+      await withHandlerTimeout(async () => {
+        await (job.def as JobDefinition).handler({
+          db: generation.db,
+          email: clients.email,
+          llm: clients.llm,
+          agent: clients.agent,
+          env: clients.env,
+          push: clients.push,
+          jobs: clients.jobs,
+          sockets: clients.sockets,
+          payload,
+        });
+      }, clampTimeoutMs(job.def.timeoutMs));
+      await finishJob(row, null);
+    } catch (error) {
+      const message =
+        error instanceof HandlerTimeoutError
+          ? "handler_timeout"
+          : error instanceof Error
+            ? error.message
+            : "handler_failed";
+      await finishJob(row, message);
+    }
+  }
+
+  async function tickJobs(): Promise<void> {
+    while (inFlight < JOB_CONCURRENCY) {
+      const generation = options.getGeneration();
+      const row = await claimNextJob().catch(() => null);
+      if (!row) return;
+      inFlight += 1;
+      const run = runClaimedJob(row, generation);
+      running.add(run);
+      void run.finally(() => {
+        inFlight -= 1;
+        running.delete(run);
+      });
+    }
+  }
+
+  async function requeueRunning(): Promise<void> {
+    await query(
+      `UPDATE robodev_jobs.jobs
+       SET status = 'queued', updated_at = now()
+       WHERE status = 'running'`,
+    );
+  }
+
+  async function start(): Promise<void> {
+    if (workerTimer || cronTimer) return;
+    await requeueRunning();
+    workerTimer = setInterval(() => {
+      void tickJobs();
+    }, LOCAL_JOB_WORKER_MS);
+    workerTimer.unref?.();
+    cronTimer = setInterval(() => {
+      void tickDue();
+    }, LOCAL_JOB_CRON_MS);
+    cronTimer.unref?.();
+  }
+
+  async function stop(): Promise<void> {
+    if (workerTimer) {
+      clearInterval(workerTimer);
+      workerTimer = undefined;
+    }
+    if (cronTimer) {
+      clearInterval(cronTimer);
+      cronTimer = undefined;
+    }
+    await Promise.all([...running]);
+  }
+
+  return {
+    enqueue,
+    reconcile,
+    tickDue,
+    tickJobs,
+    start,
+    stop,
+    get generation() {
+      return options.getGeneration();
+    },
+    get running() {
+      return Boolean(workerTimer || cronTimer);
+    },
+  };
+}