@sigrun/sigrun 0.0.0-stage → 0.1.0

package/dist/jobs/docs.js

@@ -0,0 +1,257 @@
+/**
+ * Jobs Task 2 (spec §8.1): the three job record families.
+ *
+ * Every job — from any source — is one `sigrun.job` session-scoped
+ * document-family record keyed by jobId, holding the current definition +
+ * status. History lives in two more families: `sigrun.job.revision`
+ * (one immutable snapshot per version, key `<jobId>:<version>`) and
+ * `sigrun.job.run` (one record per fire, key `<jobId>:<fireKey>` — the
+ * fire's idempotency record). All three are document families precisely
+ * because they commit ATOMICALLY with task creation and run-conversation
+ * creation (spec ruling 13; a separate database could not).
+ *
+ * Writes:
+ * - `writeJobChange` is the ONE job-record change path: it bumps
+ *   `version`, stamps `updatedAt`, and writes the matching revision in
+ *   the SAME commit (callers pass the ambient tx).
+ * - `patchJob` is the small status-edit path (state/reason/nextRun/
+ *   lastRun) — no version bump, no revision.
+ * - Retention (`pruneHistory`, ruling 14): keep the newest `limits.runs`
+ *   runs and the newest `limits.revisions` revisions plus any revision a
+ *   retained run references; the rest RETIRE (pi-durable keeps retired
+ *   incarnations — listing is bounded, the database is not; §12 owns
+ *   compaction).
+ *
+ * Enumeration is `storage.scanDocuments` over the session scope — the
+ * Harness exposes no family listing — filtered by key prefix for one
+ * job's runs/revisions. Task records are never enumerated for listing.
+ */
+import { defineDocFamily, } from "@earendil-works/pi-durable";
+// ---------------------------------------------------------------------------
+// The three families
+// ---------------------------------------------------------------------------
+/** `sigrun.job`, key = jobId. The definition + status row. */
+export const JobDoc = defineDocFamily({
+    kind: "sigrun.job",
+    version: 1,
+    scope: "session",
+    family: true,
+    initial: (seed) => seed,
+});
+/** `sigrun.job.revision`, key = `<jobId>:<version>` — immutable snapshots. */
+export const JobRevisionDoc = defineDocFamily({
+    kind: "sigrun.job.revision",
+    version: 1,
+    scope: "session",
+    family: true,
+    initial: (seed) => seed,
+});
+/** `sigrun.job.run`, key = `<jobId>:<fireKey>` — the idempotency record. */
+export const JobRunDoc = defineDocFamily({
+    kind: "sigrun.job.run",
+    version: 1,
+    scope: "session",
+    family: true,
+    initial: (seed) => seed,
+});
+// ---------------------------------------------------------------------------
+// Reads (storage scans — the harness exposes no family listing)
+// ---------------------------------------------------------------------------
+const SCAN_PAGE = 500;
+/** All live job records, keyed by id (enumeration = records, never tasks). */
+export async function scanJobs(storage, ctx) {
+    const out = [];
+    let cursor;
+    for (;;) {
+        const page = await storage.scanDocuments({
+            scope: { kind: "session" },
+            at: "current",
+            kind: JobDoc.definition.kind,
+        }, SCAN_PAGE, cursor, ctx);
+        for (const item of page.items) {
+            if (item.key === undefined)
+                continue;
+            const stored = await storage.document(item.id, "current", ctx);
+            if (stored === undefined)
+                continue;
+            out.push({ id: item.key, record: stored.value });
+        }
+        if (page.next === undefined)
+            return out;
+        cursor = page.next;
+    }
+}
+/** One job record by id (undefined when absent or retired). */
+export async function readJob(harness, id, ctx) {
+    return await harness.snapshot(JobDoc, id, ctx);
+}
+/**
+ * One job's run records, newest first (by `startedAt`), capped at `limit`.
+ * The scan walks every live `sigrun.job.run` record and filters by the
+ * `<jobId>:` key prefix — O(total retained runs), fine at household scale
+ * (spec §8.1: indexed per-job queries are §12).
+ */
+export async function listRuns(storage, jobId, limit, ctx) {
+    const prefix = `${jobId}:`;
+    const runs = [];
+    let cursor;
+    for (;;) {
+        const page = await storage.scanDocuments({
+            scope: { kind: "session" },
+            at: "current",
+            kind: JobRunDoc.definition.kind,
+        }, SCAN_PAGE, cursor, ctx);
+        for (const item of page.items) {
+            if (item.key === undefined || !item.key.startsWith(prefix))
+                continue;
+            const stored = await storage.document(item.id, "current", ctx);
+            if (stored === undefined)
+                continue;
+            runs.push(stored.value);
+        }
+        if (page.next === undefined)
+            break;
+        cursor = page.next;
+    }
+    runs.sort((a, b) => Date.parse(b.startedAt) - Date.parse(a.startedAt));
+    return runs.slice(0, Math.max(0, limit));
+}
+/** One job's revisions, newest first (by version). */
+export async function listRevisions(storage, jobId, ctx) {
+    const prefix = `${jobId}:`;
+    const revisions = [];
+    let cursor;
+    for (;;) {
+        const page = await storage.scanDocuments({
+            scope: { kind: "session" },
+            at: "current",
+            kind: JobRevisionDoc.definition.kind,
+        }, SCAN_PAGE, cursor, ctx);
+        for (const item of page.items) {
+            if (item.key === undefined || !item.key.startsWith(prefix))
+                continue;
+            const stored = await storage.document(item.id, "current", ctx);
+            if (stored === undefined)
+                continue;
+            revisions.push(stored.value);
+        }
+        if (page.next === undefined)
+            break;
+        cursor = page.next;
+    }
+    revisions.sort((a, b) => b.version - a.version);
+    return revisions;
+}
+// ---------------------------------------------------------------------------
+// Writes
+// ---------------------------------------------------------------------------
+/**
+ * The ONE job-record change path: bump `version`, stamp `updatedAt`, and
+ * write the matching immutable revision — all in the caller's commit.
+ * `next` omits `version`/`updatedAt` (this function derives them); every
+ * definition-relevant field (`spec`/`owner`/`sharing`/`enabled`) moves
+ * only through here, so history is complete by construction.
+ */
+export async function writeJobChange(tx, id, next, changedBy, nowIso) {
+    // The seed only applies when the record is absent (first creation);
+    // for a change the draft starts at the CURRENT value. Carry the
+    // caller's `next` over it field by field (status fields the caller
+    // omitted — state/reason/nextRun/lastRun — are preserved, per the
+    // reconciliation rule: "lastRun is preserved").
+    const seed = {
+        ...next,
+        version: 0,
+        updatedAt: nowIso,
+    };
+    const draft = await tx.doc(JobDoc, id, seed);
+    const priorVersion = draft.version;
+    const version = priorVersion + 1;
+    // Apply `next` onto the draft (object-optional keys ride through).
+    const target = draft;
+    for (const [key, value] of Object.entries(next)) {
+        if (value === undefined)
+            delete target[key];
+        else
+            target[key] = value;
+    }
+    target.version = version;
+    target.updatedAt = nowIso;
+    const applied = target;
+    const revision = {
+        jobId: id,
+        version,
+        source: applied.source,
+        spec: JSON.parse(JSON.stringify(applied.spec)),
+        ...(applied.owner === undefined ? {} : { owner: applied.owner }),
+        ...(applied.sharing === undefined ? {} : { sharing: applied.sharing }),
+        enabled: applied.enabled,
+        changedAt: nowIso,
+        changedBy,
+    };
+    await tx.doc(JobRevisionDoc, `${id}:${version}`, revision);
+}
+/**
+ * A small status edit on the job record (state/reason/nextRun/lastRun) —
+ * NO version bump, NO revision. The change runs in one `harness.commit`,
+ * so concurrent status writes cannot lose each other's fields.
+ */
+export async function patchJob(harness, id, change, ctx) {
+    // Existence + the seed are read OUTSIDE the commit (Tx has no
+    // `snapshot`, and Session reads queue on the line the commit holds).
+    // The seed is ignored when the record exists — tx.doc returns the live
+    // draft — so the pre-read never shadows a concurrent change.
+    const prior = await harness.snapshot(JobDoc, id, ctx);
+    if (prior === undefined)
+        return;
+    await harness.commit(async (tx) => {
+        const draft = await tx.doc(JobDoc, id, { ...prior });
+        change(draft);
+    }, ctx);
+}
+/**
+ * Retention (ruling 14), applied when a run settles and when a revision
+ * is written: retire the oldest runs beyond `limits.runs` and the oldest
+ * revisions beyond `limits.revisions`, EXCEPT a revision any retained run
+ * references (a run's outcome must always map to its exact definition).
+ *
+ * The storage handle is a PARAMETER (the Task-3 carry-forward): callers
+ * thread `OpenedHarness.storage` — the private-field reach this function
+ * used to make is deleted.
+ */
+export async function pruneHistory(storage, harness, jobId, limits, ctx) {
+    const runs = await listRuns(storage, jobId, Number.MAX_SAFE_INTEGER, ctx);
+    const revisions = await listRevisions(storage, jobId, ctx);
+    const keptRuns = runs.slice(0, Math.max(0, limits.runs));
+    const dropRuns = runs.slice(Math.max(0, limits.runs));
+    const referencedVersions = new Set(keptRuns.map((run) => run.version));
+    const keptRevisions = [];
+    const dropRevisions = [];
+    for (const revision of revisions) {
+        if (keptRevisions.length < Math.max(0, limits.revisions) ||
+            referencedVersions.has(revision.version)) {
+            keptRevisions.push(revision);
+        }
+        else {
+            dropRevisions.push(revision);
+        }
+    }
+    await harness.commit(async (tx) => {
+        for (const run of dropRuns) {
+            await tx.retireDoc(JobRunDoc, runKeyOf(run));
+        }
+        for (const revision of dropRevisions) {
+            await tx.retireDoc(JobRevisionDoc, `${jobId}:${revision.version}`);
+        }
+    }, ctx);
+}
+/**
+ * The fire key a stored run was written under, re-derived for retiring:
+ * scheduled runs key on `<jobId>:<fireAt epoch ms>`; manual runs on
+ * `<jobId>:manual:<startedAt epoch ms>` (the manual fire stamps it).
+ */
+function runKeyOf(run) {
+    if (run.manual) {
+        return `${run.jobId}:manual:${Date.parse(run.startedAt)}`;
+    }
+    return `${run.jobId}:${Date.parse(run.fireAt)}`;
+}

package/dist/jobs/fire.js

@@ -0,0 +1,342 @@
+/**
+ * Jobs Task 2 (spec §8.1 "The executor" + crash safety): `fireJob`.
+ *
+ * ONE fire path for the schedule task, run-now, and (Task 3+) external
+ * triggers. The run record IS the fire's idempotency record: keyed
+ * `<jobId>:<fireAt>` (scheduled) or `<jobId>:<manual ms>` (run-now), it
+ * is written ATOMICALLY with the run's creation:
+ *
+ * - `conversation: "new"` prompt: inside the SAME commit that creates
+ *   the run conversation (`harness.createConversation({…, init})` — the
+ *   `init` callback runs in the creating commit). The conversation and
+ *   its run record are atomic; a crash either lands both or neither.
+ * - fixed-conversation prompt: the run record commits FIRST (its own
+ *   `harness.commit`), then the task submits with
+ *   `requestId = "job:" + fireKey`. On re-entry a present run record
+ *   means "submitted or about to be", so the task submits again and the
+ *   conversation-scoped requestId dedups.
+ * - `task` action: the run record and `tx.createTask(…, {ownership:
+ *   {kind:"task", taskId: <schedule task>}})` share ONE
+ *   `runtime.commit`. The schedule task's `runtime` is threaded in for
+ *   this branch only.
+ *
+ * Overlap: with the default `overlap: "skip"` and the job's `lastRun`
+ * still `running`, the fire writes an immediately-settled `skipped` run
+ * (plus the `lastRun` refresh) and returns — the skipped fire is visible
+ * history, never a silent drop. `overlap: "queue"` admits anyway (the
+ * conversation's inbox queues the input).
+ *
+ * Blocked: absent/disabled record, or a `task` action naming an
+ * unregistered task (reason pinned by the plan) — `state: "blocked"` is
+ * patched onto the record and no run is written.
+ *
+ * The run's TERMINAL outcome is settled elsewhere (the event-bus
+ * `runSettled` observer for prompts, Task 3's task-settle observation for
+ * task runs); `fireJob` returns once the fire is admitted.
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { parseModelSpec } from "../config.js";
+import { expandInput } from "../commands/expand.js";
+import { SessionMetaDoc } from "../server/session-meta.js";
+import { JobRunDoc, patchJob, readJob } from "./docs.js";
+/**
+ * Fire one job under `fireKey`. `fireAt` is the epoch ms the key pins
+ * (the scheduled slot, or `deps.now()` for run-now). `runtime` is
+ * present only when the schedule task drives the fire (the `task`
+ * branch needs its commit line).
+ */
+export async function fireJob(deps, id, fireKey, fireAt, context, runtime) {
+    const record = await readJob(deps.harness, id, context);
+    if (record === undefined || !record.enabled) {
+        return { outcome: "blocked" };
+    }
+    const action = record.spec.action;
+    const manual = fireKey.slice(id.length + 1).startsWith("manual:");
+    const startedAt = new Date(deps.now()).toISOString();
+    const baseRun = {
+        jobId: id,
+        version: record.version,
+        fireAt: new Date(fireAt).toISOString(),
+        manual,
+        outcome: "running",
+        startedAt,
+    };
+    // Idempotency: a present run record means this fire already ran (or
+    // is running) — reuse its conversation/task and never double-create.
+    const prior = await deps.harness.snapshot(JobRunDoc, fireKey, context);
+    if (prior !== undefined) {
+        if (prior.outcome === "skipped")
+            return { outcome: "skipped" };
+        if (prior.outcome !== "running") {
+            // Already settled (succeeded/failed): the Task-3 re-entry fix —
+            // a re-entered fire whose run record already settled reports
+            // the SETTLED outcome, never "running" (a crash-recovered fire
+            // re-entering after the observer settled must not re-admit).
+            return {
+                outcome: "blocked",
+                ...(prior.conversationId === undefined
+                    ? {}
+                    : { conversationId: prior.conversationId }),
+            };
+        }
+        // Still running: re-submit (the requestId dedups) or nothing (task
+        // runs re-admit by re-creating with the same record — see below).
+    }
+    // Overlap: the previous run is still live.
+    const last = record.lastRun;
+    if (prior === undefined &&
+        (record.spec.overlap ?? "skip") === "skip" &&
+        last !== undefined &&
+        last.outcome === "running") {
+        const skipped = {
+            ...baseRun,
+            outcome: "skipped",
+            settledAt: startedAt,
+        };
+        await deps.harness.commit(async (tx) => {
+            await tx.doc(JobRunDoc, fireKey, skipped);
+        }, context);
+        await patchJob(deps.harness, id, (draft) => {
+            draft.lastRun = skipped;
+        }, context);
+        return { outcome: "skipped" };
+    }
+    if (action.kind === "prompt") {
+        return await firePrompt(deps, id, record, fireKey, baseRun, prior, context);
+    }
+    return await fireTaskAction(deps, id, record, fireKey, baseRun, prior, context, runtime);
+}
+/**
+ * Expand a job prompt through the wired roots (Task 2c): a prompt
+ * starting with `/` that names a skill or template becomes the expanded
+ * text the model sees; anything else is returned verbatim. Expansion
+ * errors (an unterminated quote) are LOUD — the fire fails rather than
+ * admitting a half-parsed prompt.
+ */
+async function jobPromptText(deps, conversationId, prompt, context) {
+    if (deps.commandExpansion === undefined || !prompt.startsWith("/")) {
+        return prompt;
+    }
+    const conversation = await deps.harness.conversation(conversationId, context);
+    if (conversation === undefined)
+        return prompt;
+    const env = await conversationEnv(deps, conversation);
+    const expansion = await expandInput([{ type: "text", text: prompt }], deps.commandExpansion, env, context);
+    const part = expansion.parts[0];
+    return part !== undefined && part.type === "text" ? part.text : prompt;
+}
+/**
+ * The conversation workspace env for a job's conversation — the same
+ * `envBuilder` seam the harness and the submit op use (the expansion's
+ * workspace template root reads through it).
+ */
+async function conversationEnv(deps, conversation) {
+    const builder = deps.envBuilder;
+    if (builder === undefined) {
+        throw new Error("fireJob: no env builder wired (commandExpansion requires envBuilder)");
+    }
+    const agent = await conversation.agent(BACKGROUND_CONTEXT);
+    const built = await builder({
+        conversationId: conversation.id,
+        ...(agent.cwd === undefined ? {} : { cwd: agent.cwd }),
+        read: deps.harness,
+    }, BACKGROUND_CONTEXT);
+    if (built === undefined) {
+        throw new Error("envBuilder returned no ExecutionEnv");
+    }
+    return built;
+}
+// ---------------------------------------------------------------------------
+// The prompt action
+// ---------------------------------------------------------------------------
+async function firePrompt(deps, id, record, fireKey, baseRun, prior, context) {
+    const action = record.spec.action;
+    if (action.kind !== "prompt")
+        throw new Error("unreachable");
+    // Fixed conversation: the run record commits first, then the submit
+    // (re-entry re-submits; the requestId dedups).
+    if (action.conversation !== "new") {
+        const conversationId = action.conversation;
+        const conversation = await deps.harness.conversation(conversationId, context);
+        if (conversation === undefined) {
+            return { outcome: "blocked" };
+        }
+        const run = {
+            ...baseRun,
+            conversationId,
+        };
+        if (prior === undefined) {
+            await deps.harness.commit(async (tx) => {
+                await tx.doc(JobRunDoc, fireKey, run);
+            }, context);
+            await patchJob(deps.harness, id, (draft) => {
+                draft.lastRun = run;
+            }, context);
+        }
+        await conversation.submit({
+            type: "input",
+            content: [
+                {
+                    type: "text",
+                    text: await jobPromptText(deps, conversationId, action.prompt, context),
+                },
+            ],
+            requestId: `job:${fireKey}`,
+        }, context);
+        return { outcome: "running", conversationId };
+    }
+    // conversation: "new" — the run record + conversation in ONE commit.
+    let conversationId = prior?.conversationId;
+    if (conversationId === undefined) {
+        const model = action.model !== undefined
+            ? parseModelSpec(action.model, "job action model")
+            : deps.defaultModel;
+        const conversation = await deps.harness.createConversation({
+            ownership: { kind: "ownerless" },
+            agent: {
+                model,
+                ...(action.thinking === undefined
+                    ? {}
+                    : { thinkingLevel: action.thinking }),
+            },
+            init: async (tx, newId) => {
+                const run = {
+                    ...baseRun,
+                    conversationId: newId,
+                };
+                await tx.doc(JobRunDoc, fireKey, run);
+                const meta = await tx.doc(SessionMetaDoc, newId);
+                meta.source = "cron";
+                meta.jobId = id;
+                if (record.owner !== undefined)
+                    meta.owner = record.owner;
+                if (action.runSharing !== undefined)
+                    meta.sharing = action.runSharing;
+                meta.name = runName(record.spec.name, deps.now(), record, deps);
+            },
+        }, context);
+        conversationId = conversation.id;
+        const run = { ...baseRun, conversationId };
+        await patchJob(deps.harness, id, (draft) => {
+            draft.lastRun = run;
+        }, context);
+    }
+    const conversation = await deps.harness.conversation(conversationId, context);
+    if (conversation === undefined) {
+        // The run record exists but its conversation vanished: a blocked
+        // fire (never silently succeed).
+        return { outcome: "blocked" };
+    }
+    await conversation.submit({
+        type: "input",
+        content: [
+            {
+                type: "text",
+                text: await jobPromptText(deps, conversationId, action.prompt, context),
+            },
+        ],
+        requestId: `job:${fireKey}`,
+    }, context);
+    return { outcome: "running", conversationId };
+}
+/** `<job name> · <YYYY-MM-DD HH:mm in the job's timezone>` (the plan's name). */
+function runName(name, at, record, deps) {
+    const schedule = record.spec.schedule;
+    const tz = ("cron" in schedule ? schedule.timezone : undefined) ?? deps.defaultTz;
+    const parts = new Intl.DateTimeFormat("en-CA", {
+        timeZone: tz,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        hour12: false,
+    }).formatToParts(new Date(at));
+    const field = (type) => parts.find((part) => part.type === type)?.value ?? "";
+    return `${name} · ${field("year")}-${field("month")}-${field("day")} ${field("hour")}:${field("minute")}`;
+}
+// ---------------------------------------------------------------------------
+// The task action
+// ---------------------------------------------------------------------------
+async function fireTaskAction(deps, id, record, fireKey, baseRun, prior, context, runtime) {
+    const action = record.spec.action;
+    if (action.kind !== "task")
+        throw new Error("unreachable");
+    // The target task must be registered by an installed extension.
+    const snapshot = depsRegistry(deps, runtime);
+    const target = snapshot.task(action.task);
+    if (target === undefined) {
+        const reason = `task ${action.task} is not registered`;
+        await patchJob(deps.harness, id, (draft) => {
+            draft.state = "blocked";
+            draft.reason = reason;
+        }, context);
+        return { outcome: "blocked" };
+    }
+    if (prior !== undefined) {
+        // Re-entry: the record (and its task) exist. The task's terminal
+        // outcome settles the run (Task 3's observer); nothing to re-do.
+        return {
+            outcome: "running",
+            ...(prior.conversationId === undefined
+                ? {}
+                : { conversationId: prior.conversationId }),
+        };
+    }
+    // The run record + the created task share ONE commit. With the
+    // schedule task driving, that's the task's own commit line (the child
+    // task is owned by it, so deleting the job cascades). Run-now without
+    // a runtime creates the child conversation-owned on root — the
+    // cascade is Task 3's delete path's concern (abortTask by scan).
+    const run = { ...baseRun };
+    if (runtime !== undefined) {
+        let taskId;
+        await runtime.commit(async (tx) => {
+            taskId = await tx.createTask(target, (action.input ?? {}), { ownership: { kind: "task", taskId: runtime.taskId } });
+            await tx.doc(JobRunDoc, fireKey, {
+                ...run,
+                taskId: taskId,
+            });
+            return undefined;
+        }, context);
+        run.taskId = taskId;
+    }
+    else {
+        // Run-now (no schedule-task runtime): the child task is
+        // conversation-owned on the ROOT conversation — Task 3's spec for
+        // the run-now path (Task 2's shape omitted the conversationId and
+        // threw on a Session commit, which requires it for a
+        // conversation-owned task).
+        const rootConversation = await deps.harness.root(context);
+        await deps.harness.commit(async (tx) => {
+            const taskId = await tx.createTask(target, (action.input ?? {}), {
+                ownership: { kind: "conversation" },
+                conversationId: rootConversation.id,
+            });
+            await tx.doc(JobRunDoc, fireKey, {
+                ...run,
+                taskId: taskId,
+            });
+        }, context);
+    }
+    await patchJob(deps.harness, id, (draft) => {
+        draft.lastRun = run;
+    }, context);
+    return { outcome: "running" };
+}
+/**
+ * The registry snapshot the task-action lookup reads: the driving
+ * runtime's when inside the schedule task (the phase's snapshot), else
+ * the `registry` threaded through `JobRuntimeDeps` (sigrun's boot-owned
+ * `OpenedHarness.registry` — the BINDING Task-3 carry-forward, replacing
+ * the harness private-field reach).
+ */
+function depsRegistry(deps, runtime) {
+    if (runtime !== undefined)
+        return runtime.registry;
+    const registry = deps.registry;
+    if (registry === undefined) {
+        throw new Error("fireJob: no registry available outside a task");
+    }
+    return registry.snapshot();
+}