@isomorph.ai/app-sdk 1.4.1 → 1.4.3

package/dist/runtime.d.ts

@@ -46,17 +46,18 @@ export declare class Runs {
     }>;
     get(id: string, owner: string): Promise<JobRun | null>;
     cancel(id: string, owner: string): Promise<JobRun | null>;
-    /** Rows whose lease ran out go back to the queue while attempts remain, else fail. */
-    reclaim(now: Date): Promise<void>;
+    /** Rows whose lease ran out go back to the queue while attempts remain, else fail; how many there were. */
+    reclaim(now: Date): Promise<number>;
     /** Claims the oldest queued run by a conditional update; null when the queue is empty or another worker won. */
     claim(now: Date): Promise<JobRun | null>;
     progress(id: string, percent: number, note?: string): Promise<void>;
     cancelRequested(id: string): Promise<boolean>;
+    /** Records the outcome; the status written, `queued` when the failure left a retry for the next pass. */
     finish(run: JobRun, outcome: {
         result?: unknown;
         error?: string;
         cancelled?: boolean;
-    }): Promise<void>;
+    }): Promise<JobRun['status']>;
 }
 /**
  * What the process runs beside the action server:
@@ -71,7 +72,11 @@ export interface RuntimeOptions {
     gatewayUrl: string;
     mode: RuntimeMode;
     tokenFile?: string;
+    /** False when the app has no runs table (ISOMORPH_JOB_RUNS=none): nothing reads or works it. */
+    jobRuns?: boolean;
     log?: (line: string) => void;
+    /** The pause between queue passes while work is found; the tests shorten it. */
+    queuePollMs?: number;
 }
 export declare class Runtime {
     private readonly options;
@@ -79,11 +84,23 @@ export declare class Runtime {
     private readonly running;
     private readonly timers;
     private stopped;
+    private queueLive;
+    private queueWake;
     private readonly runs;
     private readonly log;
     readonly server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
     constructor(options: RuntimeOptions);
     start(): Promise<number>;
+    /** Whether this process works the queue at all: not the gate, a runs table, an app with jobs, a gateway to reach. */
+    private worksQueue;
+    /**
+     * Starts the queue loop unless it is already live. The first pass runs at
+     * once; each further pass follows QUEUE_POLL_MS after one that found work
+     * (or threw: a gateway that is waking answers 5xx, and the row that woke
+     * the loop is still there). A pass that finds nothing ends the loop with no
+     * timer armed, so an idle runtime makes no data calls at all.
+     */
+    wakeQueue(): void;
     /**
      * `--run-job <name>`: one scheduled run of one job, as a CronJob pod runs it.
      * The run is the scheduler's own (`runScheduled`, the current minute as its
@@ -99,8 +116,13 @@ export declare class Runtime {
     private scheduleTick;
     /** One scheduled run; true when the handler returned, false when it threw or the last tick's run is still going. */
     private runScheduled;
-    /** One pass of the queue loop: reclaim expired leases, claim one run, run it. */
-    work(): Promise<void>;
+    /**
+     * One pass of the queue loop: reclaim expired leases, claim one run, run it.
+     * True when the pass found work — a lease reclaimed, a run claimed, or the
+     * run it finished left a retry queued — so the loop should look again; false
+     * when the queue is empty (or another pass is already going).
+     */
+    work(): Promise<boolean>;
     private serve;
     private reserved;
 }

package/dist/runtime.js

@@ -16,6 +16,20 @@
 // when it threw or the app has no such job. No port is opened, no scheduler
 // or queue loop starts.
 //
+// The queue is worked on demand, not on a clock. An idle kit app makes no
+// database calls: the runtime is the process that serves the enqueue action
+// and the one that finishes every run, so it knows when work exists. It runs
+// one pass at start (reclaiming whatever a crashed predecessor left running
+// and draining any backlog), then loops every QUEUE_POLL_MS only while a pass
+// found something — a claimed run, a reclaimed lease, a run that finished with
+// retries queued — and stops with no timer armed once the queue is empty. An
+// enqueue starts the loop again. This holds because kit-runtime is pinned to
+// one replica; a multi-replica runtime would need a slow periodic poll as well,
+// since a row inserted through another replica is invisible to this one until
+// it looks (out of scope here). The V2 idle controller reads pg_stat_database
+// counters to decide a database is quiet, so a poll that issued a transaction
+// every 2 s kept the shared Postgres awake for every app that had a job.
+//
 // Environment:
 //   PORT                          the action server's port (default 8080)
 //   ISOMORPH_GATEWAY_URL          the gateway the SDK calls; HARBOUR_GATEWAY_URL
@@ -30,6 +44,10 @@
 //                                 in-process scheduler. Set by Provision on the
 //                                 hosted kit-runtime; `isomorph dev` leaves it
 //                                 unset and keeps cron in-process
+//   ISOMORPH_JOB_RUNS=none        the app has no runs table (it never calls
+//                                 isomorph.jobs): no queue loop, and --run-job
+//                                 runs without waiting on the data path. Set by
+//                                 Provision; the table exists otherwise
 //   ISOMORPH_APP_ROOT             the app root (default: the working directory)
 import { createServer } from 'node:http';
 import { readFile, readdir, stat } from 'node:fs/promises';
@@ -174,13 +192,14 @@ export class Runs {
         }
         return data;
     }
-    /** Rows whose lease ran out go back to the queue while attempts remain, else fail. */
+    /** Rows whose lease ran out go back to the queue while attempts remain, else fail; how many there were. */
     async reclaim(now) {
         const { data: expired } = await this.table().select('*').eq('status', 'running').lt('lease_until', now.toISOString()).limit(20);
         for (const run of expired) {
             const exhausted = run.attempt >= run.max_attempts;
             await this.table().update({ status: exhausted ? 'failed' : 'queued', error: exhausted ? 'the worker was interrupted and no attempts remain' : run.error, lease_until: null, updated_at: now.toISOString() }).eq('id', run.id).eq('status', 'running');
         }
+        return expired.length;
     }
     /** Claims the oldest queued run by a conditional update; null when the queue is empty or another worker won. */
     async claim(now) {
@@ -198,10 +217,12 @@ export class Runs {
         const { data } = await this.table().select('cancel_requested').eq('id', id).maybeSingle();
         return Boolean(data?.cancel_requested);
     }
+    /** Records the outcome; the status written, `queued` when the failure left a retry for the next pass. */
     async finish(run, outcome) {
         const retry = outcome.error !== undefined && !outcome.cancelled && run.attempt < run.max_attempts;
         const status = outcome.cancelled ? 'cancelled' : outcome.error === undefined ? 'succeeded' : retry ? 'queued' : 'failed';
         await this.table().update({ status, result: outcome.result ?? null, error: outcome.error ?? null, progress: status === 'succeeded' ? 100 : run.progress, lease_until: null, updated_at: new Date().toISOString() }).eq('id', run.id).eq('status', 'running');
+        return status;
     }
 }
 export class Runtime {
@@ -210,6 +231,10 @@ export class Runtime {
     running = new Set();
     timers = [];
     stopped = false;
+    // The queue loop is live while a pass runs or its next pass is timed; a
+    // wake that arrives mid-pass is remembered so the pass after it looks again.
+    queueLive = false;
+    queueWake = false;
     runs;
     log;
     server = createServer((request, response) => { void this.serve(request, response); });
@@ -232,10 +257,52 @@ export class Runtime {
             this.every(TOKEN_REFRESH_MS, () => this.refreshToken());
         if (this.options.mode === 'full' && this.inventory.jobs.some((job) => job.schedule))
             this.scheduleTick();
-        if (this.options.mode !== 'gate' && this.inventory.jobs.length > 0 && this.options.gatewayUrl)
-            this.every(QUEUE_POLL_MS, () => this.work());
+        this.wakeQueue();
         return port;
     }
+    /** Whether this process works the queue at all: not the gate, a runs table, an app with jobs, a gateway to reach. */
+    worksQueue() {
+        return this.options.mode !== 'gate' && this.options.jobRuns !== false && this.inventory.jobs.length > 0 && Boolean(this.options.gatewayUrl);
+    }
+    /**
+     * Starts the queue loop unless it is already live. The first pass runs at
+     * once; each further pass follows QUEUE_POLL_MS after one that found work
+     * (or threw: a gateway that is waking answers 5xx, and the row that woke
+     * the loop is still there). A pass that finds nothing ends the loop with no
+     * timer armed, so an idle runtime makes no data calls at all.
+     */
+    wakeQueue() {
+        if (this.stopped || !this.worksQueue())
+            return;
+        if (this.queueLive) {
+            this.queueWake = true;
+            return;
+        }
+        this.queueLive = true;
+        const pass = async () => {
+            if (this.stopped) {
+                this.queueLive = false;
+                return;
+            }
+            this.queueWake = false;
+            let again = true;
+            try {
+                again = await this.work();
+            }
+            catch (error) {
+                this.log(`queue pass failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (this.stopped) {
+                this.queueLive = false;
+                return;
+            }
+            if (again || this.queueWake)
+                this.timers.push(setTimeout(() => void pass(), this.options.queuePollMs ?? QUEUE_POLL_MS));
+            else
+                this.queueLive = false;
+        };
+        void pass();
+    }
     /**
      * `--run-job <name>`: one scheduled run of one job, as a CronJob pod runs it.
      * The run is the scheduler's own (`runScheduled`, the current minute as its
@@ -250,7 +317,7 @@ export class Runtime {
             this.log(`this app has no ${JOBS_DIR}/${name}.ts`);
             return false;
         }
-        if (this.options.gatewayUrl && !(await this.awaitDataPath()))
+        if (this.options.gatewayUrl && this.options.jobRuns !== false && !(await this.awaitDataPath()))
             return false;
         return this.runScheduled(name, new Date(Math.floor(now.getTime() / 60_000) * 60_000));
     }
@@ -348,20 +415,25 @@ export class Runtime {
             this.running.delete(key);
         }
     }
-    /** One pass of the queue loop: reclaim expired leases, claim one run, run it. */
+    /**
+     * One pass of the queue loop: reclaim expired leases, claim one run, run it.
+     * True when the pass found work — a lease reclaimed, a run claimed, or the
+     * run it finished left a retry queued — so the loop should look again; false
+     * when the queue is empty (or another pass is already going).
+     */
     async work() {
         if (this.running.has('queue'))
-            return;
+            return false;
         this.running.add('queue');
         try {
             const now = new Date();
-            await this.runs.reclaim(now);
+            const reclaimed = await this.runs.reclaim(now);
             const run = await this.runs.claim(now);
             if (!run)
-                return;
+                return reclaimed > 0;
             if (!this.inventory.jobs.some((job) => job.name === run.job)) {
                 await this.runs.finish({ ...run, attempt: run.max_attempts }, { error: `no jobs/${run.job}.ts in this app` });
-                return;
+                return true;
             }
             try {
                 const handler = await loadHandler(this.options.root, JOBS_DIR, run.job);
@@ -376,6 +448,7 @@ export class Runtime {
             catch (error) {
                 await this.runs.finish(run, { error: error instanceof Error ? error.message : String(error) });
             }
+            return true;
         }
         finally {
             this.running.delete('queue');
@@ -431,7 +504,9 @@ export class Runtime {
                     throw new IsomorphError('VALIDATION_FAILED', `this app has no ${JOBS_DIR}/${job || '<name>'}.ts`, undefined, undefined, 400);
                 if (!owner)
                     throw new IsomorphError('AUTH_REQUIRED', 'a run is started by a signed-in person', undefined, undefined, 401);
-                return this.runs.enqueue(job, body.input, owner);
+                const queued = await this.runs.enqueue(job, body.input, owner);
+                this.wakeQueue();
+                return queued;
             }
             case GET_RUN_ACTION: {
                 const run = typeof body.id === 'string' ? await this.runs.get(body.id, owner) : null;
@@ -458,6 +533,7 @@ export function optionsFromEnvironment(env = process.env) {
         gatewayUrl: (env.ISOMORPH_GATEWAY_URL || env.HARBOUR_GATEWAY_URL || '').replace(/\/$/, ''),
         mode: env.ISOMORPH_RUNTIME_MODE === 'gate' ? 'gate' : env.ISOMORPH_JOBS_SCHEDULER === 'platform' ? 'actions' : 'full',
         tokenFile: env.HARBOUR_WORKLOAD_TOKEN_FILE || undefined,
+        jobRuns: env.ISOMORPH_JOB_RUNS !== 'none',
     };
 }
 /** The job named by `--run-job <name>` or `--run-job=<name>`; undefined when the runtime is a server. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isomorph.ai/app-sdk",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "type": "module",
   "repository": {
     "type": "git",