@robodev-ai/runtime 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robodev-ai/runtime",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Robodev project runtime — deploy-file classification, esbuild compile, module loading, schema push, route matching, OpenAPI, handler invocation, Robodev Auth, the socket engine, and local file storage. Shared by hosted Starbase and `robodev dev`.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -218,6 +218,7 @@ export {
   ensureJobsSchema,
   type JobsQueryable,
   type LocalCronRow,
+  type LocalJobFinishedEvent,
   type LocalJobRow,
   type LocalJobStatus,
   type LocalJobsEngine,

package/src/local-jobs.test.ts

@@ -10,7 +10,9 @@ import {
   ensureJobsSchema,
   type JobsQueryable,
   type LocalCronRow,
+  type LocalJobFinishedEvent,
   type LocalJobRow,
+  type LocalJobsEngineOptions,
   type LocalJobsGeneration,
 } from "./local-jobs.js";
 
@@ -208,6 +210,7 @@ function engineFor(
   store: ReturnType<typeof memoryJobs>,
   jobs: LocalJobsGeneration["jobs"],
   logs: string[] = [],
+  onJobFinished?: LocalJobsEngineOptions["onJobFinished"],
 ) {
   const generation: LocalJobsGeneration = { db: {} as RobodevDb, jobs };
   return createLocalJobsEngine({
@@ -215,6 +218,7 @@ function engineFor(
     getGeneration: () => generation,
     log: (line) => logs.push(line),
     clients: mockClients,
+    onJobFinished,
   });
 }
 
@@ -465,3 +469,73 @@ test("start resets running rows; stop clears timers", async () => {
   assert.equal(engine.running, false);
   await engine.stop();
 });
+
+test("onJobFinished fires once per finishJob for succeeded, failed-retry, and dead", async () => {
+  const succeeded: LocalJobFinishedEvent[] = [];
+  const okStore = memoryJobs();
+  const ok = engineFor(okStore, [{ name: "digest", def: jobDef(() => undefined) }], [], (event) =>
+    succeeded.push(event),
+  );
+  await ok.enqueue({ name: "digest", payload: { n: 1 } });
+  await ok.tickJobs();
+  await waitUntil(() => succeeded.length === 1);
+  assert.equal(succeeded.length, 1);
+  assert.equal(succeeded[0]?.outcome, "succeeded");
+  assert.equal(succeeded[0]?.engineStatus, "succeeded");
+  assert.equal(succeeded[0]?.error, null);
+  assert.equal(succeeded[0]?.name, "digest");
+  assert.deepEqual(succeeded[0]?.payload, { n: 1 });
+
+  const retried: LocalJobFinishedEvent[] = [];
+  const retryStore = memoryJobs();
+  const retry = engineFor(
+    retryStore,
+    [
+      {
+        name: "digest",
+        def: jobDef(() => {
+          throw new Error("boom");
+        }),
+      },
+    ],
+    [],
+    (event) => retried.push(event),
+  );
+  await retry.enqueue({ name: "digest", payload: { n: 2 } });
+  await retry.tickJobs();
+  await waitUntil(() => retried.length === 1);
+  assert.equal(retried.length, 1);
+  assert.equal(retried[0]?.outcome, "failed");
+  assert.equal(retried[0]?.engineStatus, "queued");
+  assert.equal(retried[0]?.error, "boom");
+  assert.equal(retried[0]?.attempts, 1);
+  assert.deepEqual(retried[0]?.payload, { n: 2 });
+
+  const finished: LocalJobFinishedEvent[] = [];
+  const deadStore = memoryJobs();
+  const dying = engineFor(
+    deadStore,
+    [
+      {
+        name: "digest",
+        def: jobDef(() => {
+          throw new Error("boom");
+        }),
+      },
+    ],
+    [],
+    (event) => finished.push(event),
+  );
+  await dying.enqueue({ name: "digest" });
+  for (let attempt = 1; attempt <= JOB_MAX_ATTEMPTS; attempt++) {
+    deadStore.jobs[0]!.run_at = new Date(0);
+    deadStore.jobs[0]!.status = "queued";
+    await dying.tickJobs();
+    await waitUntil(() => finished.length === attempt);
+  }
+  assert.equal(finished.length, JOB_MAX_ATTEMPTS);
+  assert.equal(finished.at(-1)?.outcome, "failed");
+  assert.equal(finished.at(-1)?.engineStatus, "dead");
+  assert.equal(finished.at(-1)?.attempts, JOB_MAX_ATTEMPTS);
+  assert.equal(finished.at(-1)?.error, "boom");
+});

package/src/local-jobs.ts

@@ -49,11 +49,23 @@ export type LocalJobsGeneration = {
   jobs: readonly { name: string; file?: string; def: JobDefinition }[];
 };
 
+export type LocalJobFinishedEvent = {
+  id: string;
+  name: string;
+  payload: unknown;
+  outcome: "succeeded" | "failed";
+  engineStatus: "succeeded" | "queued" | "dead";
+  attempts: number;
+  error: string | null;
+};
+
 export type LocalJobsEngineOptions = {
   query: JobsQueryable["query"];
   getGeneration: () => LocalJobsGeneration | null;
   log?: (line: string) => void;
   clients: () => RouteClients;
+  /** Invoked after the job row UPDATE. Failed-retry (`queued`) and `dead` both report `failed`. */
+  onJobFinished?: (event: LocalJobFinishedEvent) => void;
 };
 
 export type LocalJobsEngine = {
@@ -221,6 +233,8 @@ export function createLocalJobsEngine(options: LocalJobsEngineOptions): LocalJob
   }
 
   async function finishJob(row: LocalJobRow, error: string | null): Promise<void> {
+    let engineStatus: LocalJobFinishedEvent["engineStatus"];
+    let attempts = row.attempts;
     if (!error) {
       await query(
         `UPDATE robodev_jobs.jobs
@@ -229,21 +243,38 @@ export function createLocalJobsEngine(options: LocalJobsEngineOptions): LocalJob
         [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)}`);
+      engineStatus = "succeeded";
     } else {
-      log(`  ${row.name} failed attempt ${attempts}/${JOB_MAX_ATTEMPTS}: ${shortError(error)}`);
+      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],
+      );
+      engineStatus = next.status;
+      if (next.status === "dead") {
+        log(`  ${row.name} dead: ${shortError(error)}`);
+      } else {
+        log(`  ${row.name} failed attempt ${attempts}/${JOB_MAX_ATTEMPTS}: ${shortError(error)}`);
+      }
+    }
+    let payload: unknown = null;
+    try {
+      payload = JSON.parse(row.payload_json) as unknown;
+    } catch {
+      payload = null;
     }
+    options.onJobFinished?.({
+      id: row.id,
+      name: row.name,
+      payload,
+      outcome: error ? "failed" : "succeeded",
+      engineStatus,
+      attempts,
+      error,
+    });
   }
 
   async function runClaimedJob(