@loopingai/core 0.8.0 → 0.8.1

package/dist/job/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@loopingai/core/job` — a long job a Durable Object owns through its alarm.
+ *
+ * **The sibling of `@loopingai/core/alarm`, and the pairing is the point.**
+ * `WakeMap` owns *when* an object wakes; this owns *what a job owes on waking*.
+ * Neither depends on the other's reason for existing, and both are useful to a
+ * plain `DurableObject` rather than only to a `LoopingAgent` — which is why they
+ * are subpaths and not part of the agent machinery.
+ *
+ * **Mechanism only.** Nothing here knows what a job *does*: no command, no
+ * container, no filesystem, no vendor library. A consumer supplies the handle
+ * and the meaning; this supplies the four rules that are wrong in the same way
+ * every time — arming before the work starts, one job at a time, a drain that
+ * can outlive its job, and a job nobody is draining. See {@link JobLifecycle}.
+ *
+ * Deliberately **not** called `task`. Core already has a `Task` — the A2A one,
+ * with its own lifecycle, its own guarded writes and its own table — and two
+ * unrelated meanings in one namespace is a cost paid forever by every reader.
+ */
+export { isRearmable, isRunning, type DoneJob, type FailedJob, type IdleJob, type JobState, type RunningJob, type SkippedJob } from "./state.js";
+export { JobLifecycle, type JobContext, type JobHandle, type JobLifecycleOptions, type JobResult } from "./lifecycle.js";

package/dist/job/index.js

@@ -0,0 +1,21 @@
+/**
+ * `@loopingai/core/job` — a long job a Durable Object owns through its alarm.
+ *
+ * **The sibling of `@loopingai/core/alarm`, and the pairing is the point.**
+ * `WakeMap` owns *when* an object wakes; this owns *what a job owes on waking*.
+ * Neither depends on the other's reason for existing, and both are useful to a
+ * plain `DurableObject` rather than only to a `LoopingAgent` — which is why they
+ * are subpaths and not part of the agent machinery.
+ *
+ * **Mechanism only.** Nothing here knows what a job *does*: no command, no
+ * container, no filesystem, no vendor library. A consumer supplies the handle
+ * and the meaning; this supplies the four rules that are wrong in the same way
+ * every time — arming before the work starts, one job at a time, a drain that
+ * can outlive its job, and a job nobody is draining. See {@link JobLifecycle}.
+ *
+ * Deliberately **not** called `task`. Core already has a `Task` — the A2A one,
+ * with its own lifecycle, its own guarded writes and its own table — and two
+ * unrelated meanings in one namespace is a cost paid forever by every reader.
+ */
+export { isRearmable, isRunning } from "./state.js";
+export { JobLifecycle } from "./lifecycle.js";

package/dist/job/lifecycle.d.ts

@@ -0,0 +1,176 @@
+import type { WakeMap } from "../alarm/index.js";
+import { type JobState, type RunningJob } from "./state.js";
+/**
+ * The choreography around a long job a Durable Object owns through its alarm.
+ *
+ * The job itself — what command, where, and what its output means — belongs to
+ * the owner. What lives here is the part that is the same every time and is
+ * wrong in the same four ways every time:
+ *
+ * 1. **Arming writes `running` before anything runs.** The alarm has not fired
+ *    yet, and a `done` record in that window lets a gated caller through against
+ *    a workspace that is not ready. Writing `running` first also makes arming
+ *    self-limiting: the next call sees it and stops.
+ * 2. **One job at a time**, guarded by a read that goes *through* the staleness
+ *    bound — so a `running` record left by a dead isolate resolves rather than
+ *    blocking every retry forever.
+ * 3. **A drain can outlive the job it watched.** `ctx.waitUntil` keeps running
+ *    after the RPC returns, and a late drain writing its verdict over a record
+ *    describing a *live* job is silent corruption. {@link generation} is the
+ *    marker that makes it harmless.
+ * 4. **Nobody may be draining at all.** A watch intent re-attaches to a job
+ *    whose isolate went away mid-flight.
+ *
+ * What is deliberately *not* here is the drain loop. Two real consumers want
+ * different ones — an install runs to completion under `waitUntil` and writes a
+ * single verdict; a coding-agent run is drained in bounded windows and reports
+ * partial progress between them. They share the four rules above and nothing
+ * below them, so the loop stays with the owner.
+ *
+ * ## Storage keys
+ *
+ * Derived from {@link JobLifecycleOptions.id} so one object can own several
+ * jobs. For `id: "install"` they come out as `install`, `install:armed`,
+ * `install:last-armed`, `install:context`, and the wake intents `install-run`
+ * and `install-watch` — the exact keys the predecessor wrote by hand, which is
+ * why adopting this needs no storage migration.
+ */
+/** What a job's result looks like to the lifecycle. Deliberately minimal. */
+export interface JobResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/** A running command, reduced to what the lifecycle needs of it. */
+export interface JobHandle {
+    result(): Promise<JobResult>;
+    [Symbol.dispose](): void;
+}
+/**
+ * The per-job record naming what is running and *which* run it is.
+ *
+ * `startedAt` is the generation marker, so it is the one required field: a drain
+ * compares the stamp it captured against the stamp on disk, and a mismatch means
+ * it has been superseded and has nothing useful left to say.
+ */
+export interface JobContext {
+    startedAt: number;
+}
+export interface JobLifecycleOptions {
+    /** Namespaces every key and intent. Also the state record's own key. */
+    id: string;
+    storage: DurableObjectStorage;
+    wake: WakeMap;
+    /**
+     * How long a `running` record may stand before it is presumed dead.
+     *
+     * Measured from `startedAt` and compared against the job's own timeout plus
+     * this, never against this alone — the point is to outlast a job that is
+     * merely slow, and only then to declare one that is gone.
+     */
+    staleMs?: number;
+    /** How often the watch intent re-checks a job nobody is draining. */
+    watchMs?: number;
+    /**
+     * The floor between two arming attempts.
+     *
+     * Without it a job that cannot start re-arms on every call into the object.
+     */
+    armCooldownMs?: number;
+}
+export declare class JobLifecycle<TExtra extends object = Record<never, never>, TContext extends JobContext = JobContext> {
+    #private;
+    /** `install` — the state record. */
+    readonly stateKey: string;
+    /** `install:armed` — the stamp the arming path wrote, for the alarm to match. */
+    readonly armedKey: string;
+    /** `install:last-armed` — the cooldown floor. */
+    readonly lastArmedKey: string;
+    /** `install:context` — where the generation marker lives. */
+    readonly contextKey: string;
+    /** `install-run` — the intent that *runs* a job. */
+    readonly runIntent: string;
+    /** `install-watch` — the intent that re-attaches to one nobody is draining. */
+    readonly watchIntent: string;
+    constructor(options: JobLifecycleOptions);
+    /** The raw record, with no staleness repair. `idle` when nothing is written. */
+    read(): Promise<JobState<TExtra>>;
+    write(state: JobState<TExtra>): Promise<void>;
+    context(): Promise<TContext | undefined>;
+    /**
+     * Record which run this is, **before** spawning.
+     *
+     * The order is the whole point: a drain captures `startedAt` after the spawn,
+     * so a context written afterwards would let two runs share a generation.
+     */
+    putContext(context: TContext): Promise<void>;
+    /**
+     * Hand a cold job to the alarm, if one is not already pending.
+     *
+     * Returns the stamp it armed with, or `undefined` when it declined — the
+     * caller needs the stamp because it is what the alarm must present to
+     * {@link claim} to get past the single-flight guard.
+     *
+     * An arming caller must **not** own the run. The predecessor handed one to
+     * `ctx.waitUntil` from a gate poll that returned in milliseconds, and the
+     * drain was disposed underneath it mid-command. An alarm invocation belongs to
+     * the object rather than to any request, so nothing it awaits can be cut short.
+     */
+    arm(placeholder: Omit<RunningJob<TExtra>, "state" | "startedAt">): Promise<number | undefined>;
+    /** The stamp {@link arm} wrote, so the alarm can recognise its own placeholder. */
+    armedAt(): Promise<number | undefined>;
+    clearArmed(): Promise<void>;
+    /**
+     * Decide whether a new run may start.
+     *
+     * `takeOverArmedAt` is the one exemption and it is narrow on purpose. The
+     * alarm's placeholder *is* a `running` record for a job that has not started,
+     * so the alarm has to pass its own guard — and only its own. Matching the
+     * exact stamp it wrote is what stops this becoming "take over any running
+     * job", which is the displacement bug the guard exists to prevent: three
+     * callers spawning under one exec id in fifty seconds, each displacing the
+     * last, every displaced drain still attached and still writing verdicts.
+     *
+     * Applies the staleness bound **itself**, rather than trusting the caller to
+     * have repaired the record first. An earlier draft took an
+     * "already-repaired" state and said so in prose, which enforced nothing: the
+     * repaired and raw types are identical, so a caller passing a raw read got a
+     * `running` record that could never be claimed and a job wedged forever.
+     * `timeoutMs` is the job's own budget; see {@link isStale}.
+     */
+    claim(state: JobState<TExtra>, timeoutMs: number, takeOverArmedAt?: number): {
+        ok: true;
+    } | {
+        ok: false;
+        current: RunningJob<TExtra>;
+    };
+    /**
+     * Whether a `running` record has stood long enough to be presumed dead.
+     *
+     * `timeoutMs` is the job's own budget; the bound is that plus `staleMs`, so a
+     * job that is merely slow is never declared gone.
+     */
+    isStale(state: RunningJob<TExtra>, timeoutMs: number, now?: number): boolean;
+    /** Arm the watchdog that re-attaches to a job nobody is draining. */
+    armWatch(now?: number): Promise<void>;
+    /**
+     * Disarm the watchdog.
+     *
+     * Never call this from a superseded drain: the watchdog belongs to whichever
+     * run owns the record *now*, and clearing it there disarms the one recovery
+     * path the live run has.
+     */
+    clearWatch(): Promise<void>;
+    /**
+     * A predicate a drain calls before every write, to ask whether it still owns
+     * the record.
+     *
+     * Captures the stamp once, at drain start, and compares it against disk each
+     * time. The closure also latches, so a drain can ask afterwards whether it was
+     * superseded — which is what decides if it may touch the watchdog.
+     */
+    generation(startedAt: number): {
+        stillMine: () => Promise<boolean>;
+        superseded: () => boolean;
+    };
+}

package/dist/job/lifecycle.js

@@ -0,0 +1,230 @@
+import { isRearmable } from "./state.js";
+/**
+ * `WakeMap`'s own storage row, spelled here rather than imported.
+ *
+ * Importing `WAKE_KEY` would be a *value* import from `../alarm`, and this
+ * module is careful to reach that package only for types — a runtime edge would
+ * pull the whole alarm module into any bundle that imports `/job`. So the string
+ * is duplicated, and `lifecycle.spec.ts` asserts it still equals `WAKE_KEY`;
+ * specs never ship, so the check costs nothing at runtime and fails loudly if
+ * the two ever drift.
+ */
+const WAKE_MAP_KEY = "wake";
+const DEFAULT_STALE_MS = 5 * 60_000;
+const DEFAULT_WATCH_MS = 60_000;
+const DEFAULT_ARM_COOLDOWN_MS = 5 * 60_000;
+export class JobLifecycle {
+    #o;
+    /** `install` — the state record. */
+    stateKey;
+    /** `install:armed` — the stamp the arming path wrote, for the alarm to match. */
+    armedKey;
+    /** `install:last-armed` — the cooldown floor. */
+    lastArmedKey;
+    /** `install:context` — where the generation marker lives. */
+    contextKey;
+    /** `install-run` — the intent that *runs* a job. */
+    runIntent;
+    /** `install-watch` — the intent that re-attaches to one nobody is draining. */
+    watchIntent;
+    constructor(options) {
+        /**
+         * An id is a storage key, so a bad one is not a bad name — it is a write
+         * landing on somebody else's row.
+         *
+         * `"wake"` is the one that matters and the reason this guard exists: it is
+         * `WakeMap`'s single row, so a job with that id would overwrite the whole
+         * intent map on its first state write, and the `wake.set()` immediately
+         * after would then read job fields as intents. Every pending wake-up on the
+         * object — not just this job's — silently stops happening.
+         *
+         * Empty is rejected for the same reason one level down: it yields the
+         * intents `-run` and `-watch`, which two differently-broken callers would
+         * share.
+         */
+        if (!options.id)
+            throw new Error("a job id must be a non-empty string");
+        if (options.id === WAKE_MAP_KEY) {
+            throw new Error(`"${WAKE_MAP_KEY}" is reserved: it is WakeMap's storage row, and a job ` +
+                `with that id would overwrite every pending intent on this object`);
+        }
+        this.#o = {
+            ...options,
+            staleMs: options.staleMs ?? DEFAULT_STALE_MS,
+            watchMs: options.watchMs ?? DEFAULT_WATCH_MS,
+            armCooldownMs: options.armCooldownMs ?? DEFAULT_ARM_COOLDOWN_MS
+        };
+        this.stateKey = options.id;
+        this.armedKey = `${options.id}:armed`;
+        this.lastArmedKey = `${options.id}:last-armed`;
+        this.contextKey = `${options.id}:context`;
+        this.runIntent = `${options.id}-run`;
+        this.watchIntent = `${options.id}-watch`;
+    }
+    // --- the record ------------------------------------------------------------
+    /** The raw record, with no staleness repair. `idle` when nothing is written. */
+    async read() {
+        return ((await this.#o.storage.get(this.stateKey)) ??
+            { state: "idle" });
+    }
+    async write(state) {
+        await this.#o.storage.put(this.stateKey, state);
+    }
+    async context() {
+        return await this.#o.storage.get(this.contextKey);
+    }
+    /**
+     * Record which run this is, **before** spawning.
+     *
+     * The order is the whole point: a drain captures `startedAt` after the spawn,
+     * so a context written afterwards would let two runs share a generation.
+     */
+    async putContext(context) {
+        await this.#o.storage.put(this.contextKey, context);
+    }
+    // --- arming ----------------------------------------------------------------
+    /**
+     * Hand a cold job to the alarm, if one is not already pending.
+     *
+     * Returns the stamp it armed with, or `undefined` when it declined — the
+     * caller needs the stamp because it is what the alarm must present to
+     * {@link claim} to get past the single-flight guard.
+     *
+     * An arming caller must **not** own the run. The predecessor handed one to
+     * `ctx.waitUntil` from a gate poll that returned in milliseconds, and the
+     * drain was disposed underneath it mid-command. An alarm invocation belongs to
+     * the object rather than to any request, so nothing it awaits can be cut short.
+     */
+    async arm(placeholder) {
+        const state = await this.read();
+        if (!isRearmable(state))
+            return undefined;
+        const lastArmed = await this.#o.storage.get(this.lastArmedKey);
+        if (lastArmed !== undefined &&
+            Date.now() - lastArmed < this.#o.armCooldownMs)
+            return undefined;
+        const armedAt = Date.now();
+        await this.write({
+            ...placeholder,
+            state: "running",
+            startedAt: armedAt
+        });
+        await this.#o.storage.put(this.armedKey, armedAt);
+        // Kept even if the scheduling below fails, deliberately: a floor that only
+        // applied to *successful* arming would let a persistently failing schedule
+        // re-arm on every call into the object, which is what it exists to prevent.
+        await this.#o.storage.put(this.lastArmedKey, armedAt);
+        /**
+         * The placeholder and the alarm that owns it are two writes, and between
+         * them is the one window where this can strand a job: a `running` record no
+         * run intent points at, which every later {@link arm} then declines to
+         * replace *because* it is running.
+         *
+         * The staleness bound in {@link claim} would eventually free it, but only
+         * after a full timeout — so unwind instead, and leave the record exactly as
+         * re-armable as it was found.
+         */
+        try {
+            await this.#o.wake.set({ key: this.runIntent, notBefore: armedAt });
+        }
+        catch (err) {
+            await this.write(state);
+            await this.#o.storage.delete(this.armedKey).catch(() => { });
+            throw err;
+        }
+        return armedAt;
+    }
+    /** The stamp {@link arm} wrote, so the alarm can recognise its own placeholder. */
+    async armedAt() {
+        return await this.#o.storage.get(this.armedKey);
+    }
+    async clearArmed() {
+        await this.#o.storage.delete(this.armedKey);
+    }
+    // --- the single-flight guard ------------------------------------------------
+    /**
+     * Decide whether a new run may start.
+     *
+     * `takeOverArmedAt` is the one exemption and it is narrow on purpose. The
+     * alarm's placeholder *is* a `running` record for a job that has not started,
+     * so the alarm has to pass its own guard — and only its own. Matching the
+     * exact stamp it wrote is what stops this becoming "take over any running
+     * job", which is the displacement bug the guard exists to prevent: three
+     * callers spawning under one exec id in fifty seconds, each displacing the
+     * last, every displaced drain still attached and still writing verdicts.
+     *
+     * Applies the staleness bound **itself**, rather than trusting the caller to
+     * have repaired the record first. An earlier draft took an
+     * "already-repaired" state and said so in prose, which enforced nothing: the
+     * repaired and raw types are identical, so a caller passing a raw read got a
+     * `running` record that could never be claimed and a job wedged forever.
+     * `timeoutMs` is the job's own budget; see {@link isStale}.
+     */
+    claim(state, timeoutMs, takeOverArmedAt) {
+        if (state.state !== "running")
+            return { ok: true };
+        // The alarm presenting its own placeholder — the one narrow exemption.
+        if (state.startedAt === takeOverArmedAt)
+            return { ok: true };
+        // A record whose isolate is gone must not block every later run.
+        if (this.isStale(state, timeoutMs))
+            return { ok: true };
+        return { ok: false, current: state };
+    }
+    // --- staleness and re-attach -------------------------------------------------
+    /**
+     * Whether a `running` record has stood long enough to be presumed dead.
+     *
+     * `timeoutMs` is the job's own budget; the bound is that plus `staleMs`, so a
+     * job that is merely slow is never declared gone.
+     */
+    isStale(state, timeoutMs, now = Date.now()) {
+        return now - state.startedAt > timeoutMs + this.#o.staleMs;
+    }
+    /** Arm the watchdog that re-attaches to a job nobody is draining. */
+    async armWatch(now = Date.now()) {
+        await this.#o.wake.set({
+            key: this.watchIntent,
+            notBefore: now + this.#o.watchMs
+        });
+    }
+    /**
+     * Disarm the watchdog.
+     *
+     * Never call this from a superseded drain: the watchdog belongs to whichever
+     * run owns the record *now*, and clearing it there disarms the one recovery
+     * path the live run has.
+     */
+    async clearWatch() {
+        await this.#o.wake.clear(this.watchIntent).catch(() => { });
+    }
+    // --- generation --------------------------------------------------------------
+    /**
+     * A predicate a drain calls before every write, to ask whether it still owns
+     * the record.
+     *
+     * Captures the stamp once, at drain start, and compares it against disk each
+     * time. The closure also latches, so a drain can ask afterwards whether it was
+     * superseded — which is what decides if it may touch the watchdog.
+     */
+    generation(startedAt) {
+        let superseded = false;
+        return {
+            stillMine: async () => {
+                // The latch is checked *before* the read, not after. Ownership is not
+                // recoverable: once another run has owned this record, a stamp that
+                // happens to match again does not hand it back, and a drain that
+                // regained write access here would be the corruption the marker exists
+                // to prevent.
+                if (superseded)
+                    return false;
+                const now = await this.context();
+                if (now?.startedAt === startedAt)
+                    return true;
+                superseded = true;
+                return false;
+            },
+            superseded: () => superseded
+        };
+    }
+}

package/dist/job/state.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The record an alarm-owned job writes about itself, and the shape a gate reads.
+ *
+ * This is the contract between two halves that do not own each other: the
+ * Durable Object *runs* the job, and something else — a shell tool, a subagent
+ * executor — refuses to proceed while one is in flight. A shape they agreed on
+ * informally would drift, and the drift shows up as a command running halfway
+ * through the job it was supposed to wait for.
+ *
+ * ## Why `TExtra` intersects rather than nests
+ *
+ * The obvious generic is `{ state: "running"; meta: TExtra }`. It is wrong here,
+ * and expensively so: every existing reader spells the job's own field at the
+ * top level (`status.command`), so nesting would rewrite every read site and
+ * every spec assertion in both consumers to buy nothing. Intersecting keeps
+ * `JobState<{ command: string }>` *byte-identical* to the hand-written union it
+ * replaces, which is what makes adopting this a type change and not a refactor.
+ *
+ * The cost of the choice is that `TExtra` must not collide with the field names
+ * below. That is a real constraint, and it is why they are named for the
+ * mechanism (`startedAt`, `finishedAt`, `exitCode`) rather than for any job.
+ */
+/**
+ * A job's durable state.
+ *
+ * Five variants, and the two that look redundant are not:
+ *
+ * - `idle` — nothing has ever run. There is no context recording *where* or
+ *   *what*, so a caller cannot re-drive it; that is the owner's job.
+ * - `skipped` — something looked and decided there was nothing to do. Terminal
+ *   and *correct*, which is why it is not `done`: a gate must not treat a
+ *   deliberate no-op as a failure to retry, and an arming path must not re-drive
+ *   it forever.
+ * - `running` — in flight, or believed to be. Never trusted without the
+ *   staleness bound in {@link JobLifecycle.claim}, because the isolate that
+ *   wrote it may be long gone.
+ * - `done` / `failed` — terminal, carrying enough to explain the outcome without
+ *   the caller reaching for the transcript.
+ */
+/** Nothing has ever run; no context exists naming what would. */
+export type IdleJob = {
+    state: "idle";
+};
+/** Something looked and decided there was nothing to do. Terminal and correct. */
+export type SkippedJob = {
+    state: "skipped";
+    reason: string;
+};
+/** In flight, or believed to be. Never trusted without the staleness bound. */
+export type RunningJob<TExtra = Record<never, never>> = {
+    state: "running";
+    startedAt: number;
+    tail?: string;
+} & TExtra;
+export type DoneJob<TExtra = Record<never, never>> = {
+    state: "done";
+    exitCode: number;
+    finishedAt: number;
+    ms: number;
+    tail?: string;
+} & TExtra;
+export type FailedJob<TExtra = Record<never, never>> = {
+    state: "failed";
+    finishedAt: number;
+    error: string;
+    exitCode?: number;
+    tail?: string;
+} & TExtra;
+/**
+ * A job's durable state.
+ *
+ * The variants are named types rather than inlined into the union because
+ * `Extract<JobState<TExtra>, { state: "running" }>` cannot narrow while `TExtra`
+ * is generic — the compiler has no way to prove `DoneJob & TExtra` does not also
+ * carry `state: "running"`. Naming them is what lets a caller say
+ * `RunningJob<TExtra>` and get its fields.
+ */
+export type JobState<TExtra = Record<never, never>> = IdleJob | SkippedJob | RunningJob<TExtra> | DoneJob<TExtra> | FailedJob<TExtra>;
+/**
+ * Whether a state is one a new run may start from.
+ *
+ * `done` and `failed` both qualify, and the second was a gap worth closing in
+ * the predecessor: arming used to require `done`, so one bad run left a record
+ * that declined to re-arm forever — one failure poisoning every task after it.
+ *
+ * `skipped` and `idle` are excluded for different reasons. `skipped` means the
+ * answer is already correct and permanent. `idle` means no context exists naming
+ * what to run, so there is nothing to re-drive.
+ */
+export declare function isRearmable<TExtra extends object>(state: JobState<TExtra>): boolean;
+/** Whether a state claims a job is in flight. Never conclusive on its own. */
+export declare function isRunning<TExtra extends object>(state: JobState<TExtra>): state is RunningJob<TExtra>;

package/dist/job/state.js

@@ -0,0 +1,40 @@
+/**
+ * The record an alarm-owned job writes about itself, and the shape a gate reads.
+ *
+ * This is the contract between two halves that do not own each other: the
+ * Durable Object *runs* the job, and something else — a shell tool, a subagent
+ * executor — refuses to proceed while one is in flight. A shape they agreed on
+ * informally would drift, and the drift shows up as a command running halfway
+ * through the job it was supposed to wait for.
+ *
+ * ## Why `TExtra` intersects rather than nests
+ *
+ * The obvious generic is `{ state: "running"; meta: TExtra }`. It is wrong here,
+ * and expensively so: every existing reader spells the job's own field at the
+ * top level (`status.command`), so nesting would rewrite every read site and
+ * every spec assertion in both consumers to buy nothing. Intersecting keeps
+ * `JobState<{ command: string }>` *byte-identical* to the hand-written union it
+ * replaces, which is what makes adopting this a type change and not a refactor.
+ *
+ * The cost of the choice is that `TExtra` must not collide with the field names
+ * below. That is a real constraint, and it is why they are named for the
+ * mechanism (`startedAt`, `finishedAt`, `exitCode`) rather than for any job.
+ */
+/**
+ * Whether a state is one a new run may start from.
+ *
+ * `done` and `failed` both qualify, and the second was a gap worth closing in
+ * the predecessor: arming used to require `done`, so one bad run left a record
+ * that declined to re-arm forever — one failure poisoning every task after it.
+ *
+ * `skipped` and `idle` are excluded for different reasons. `skipped` means the
+ * answer is already correct and permanent. `idle` means no context exists naming
+ * what to run, so there is nothing to re-drive.
+ */
+export function isRearmable(state) {
+    return state.state === "done" || state.state === "failed";
+}
+/** Whether a state claims a job is in flight. Never conclusive on its own. */
+export function isRunning(state) {
+    return state.state === "running";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loopingai/core",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Shared, mandatory foundation for Looping agents on Cloudflare Workers: zero-trust A2A, durable task lifecycle, delegation and subagent runtime, test harness.",
   "keywords": [
     "a2a",
@@ -61,6 +61,10 @@
       "types": "./dist/alarm/index.d.ts",
       "import": "./dist/alarm/index.js"
     },
+    "./job": {
+      "types": "./dist/job/index.d.ts",
+      "import": "./dist/job/index.js"
+    },
     "./round": {
       "types": "./dist/round/index.d.ts",
       "import": "./dist/round/index.js"
@@ -108,7 +112,8 @@
     "test:watch": "vitest",
     "verify:exports": "node scripts/verify-exports.mjs",
     "prepack": "npm run build && npm run verify:exports",
-    "prepublishOnly": "npm run check && npm test && npm run verify:exports"
+    "prepublishOnly": "npm run check && npm test && npm run verify:exports",
+    "prepare": "husky"
   },
   "dependencies": {
     "@a2a-js/sdk": "^1.0.0",
@@ -144,6 +149,7 @@
     "ai": "^7.0.52",
     "drizzle-kit": "^0.31.10",
     "eslint": "^10.8.0",
+    "husky": "^9.1.7",
     "prettier": "^3.9.6",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.66.0",