@sigrun/escalations 0.0.0-stage → 0.1.0

package/dist/json-file.js

@@ -0,0 +1,78 @@
+/**
+ * JsonFile<T> — one serialized, atomically replaced JSON state file.
+ *
+ * Updates run read → mutate → write in one queue position. Writes use a
+ * same-directory temp file and rename, and are always mode 0600. Malformed
+ * JSON throws naming the path rather than being silently reset.
+ *
+ * The queue is PER INSTANCE: users sharing a path must share the JsonFile.
+ */
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import { dirname } from "node:path";
+export class JsonFile {
+    path;
+    initial;
+    queue = Promise.resolve();
+    constructor(path, initial) {
+        this.path = path;
+        this.initial = initial;
+    }
+    read() {
+        return this.enqueue(() => this.readNow());
+    }
+    /**
+     * Return the next state from the current one. Returning the same reference
+     * is a no-op: the read is serialized, but no replacement is written.
+     */
+    update(mutate) {
+        return this.enqueue(async () => {
+            const current = await this.readNow();
+            const next = await mutate(current);
+            if (next !== current)
+                await this.writeNow(next);
+            return next;
+        });
+    }
+    enqueue(work) {
+        const next = this.queue.then(work, work);
+        // A rejected operation does not poison later reads or updates.
+        this.queue = next.catch(() => { });
+        return next;
+    }
+    async readNow() {
+        let text;
+        try {
+            text = await readFile(this.path, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return this.initial();
+            }
+            throw error;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch (error) {
+            throw new Error(`escalations: malformed JSON in ${this.path}: ${String(error)}`, { cause: error });
+        }
+    }
+    async writeNow(value) {
+        await mkdir(dirname(this.path), { recursive: true });
+        const temp = `${this.path}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temp, `${JSON.stringify(value, null, "\t")}\n`, {
+                mode: 0o600,
+            });
+            await chmod(temp, 0o600);
+            await rename(temp, this.path);
+        }
+        catch (error) {
+            await rm(temp, { force: true }).catch(() => {
+                // Keep the original write failure if cleanup also fails.
+            });
+            throw error;
+        }
+    }
+}

package/dist/keys.d.ts

@@ -0,0 +1,6 @@
+import type { SigrunHost } from "@sigrun/sigrun/extension";
+export declare const INBOX_TABS: readonly ["open", "active", "dismissed", "resolved"];
+/** Every inbox instance whose contents can change for this record. */
+export declare function inboxKeys(id?: string): string[];
+/** Notify the surface host; this is deliberately fire-and-forget per its contract. */
+export declare function changedInbox(host: SigrunHost, id?: string): void;

package/dist/keys.js

@@ -0,0 +1,14 @@
+export const INBOX_TABS = ["open", "active", "dismissed", "resolved"];
+/** Every inbox instance whose contents can change for this record. */
+export function inboxKeys(id) {
+    return [
+        "{}",
+        ...INBOX_TABS.map((tab) => `{"tab":"${tab}"}`),
+        ...(id === undefined ? [] : [`{"id":${JSON.stringify(id)}}`]),
+    ];
+}
+/** Notify the surface host; this is deliberately fire-and-forget per its contract. */
+export function changedInbox(host, id) {
+    for (const key of inboxKeys(id))
+        host.surfaces.changed("inbox", key);
+}

package/dist/lifecycle.d.ts

@@ -0,0 +1,24 @@
+import { type Escalation, type RaiseInput } from "./types.js";
+/** A disallowed lifecycle transition, identified by a stable machine code. */
+export declare class TransitionError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare function raise(input: RaiseInput, now: Date): Escalation;
+export declare function answer(e: Escalation, a: {
+    option?: string;
+    instruction?: string;
+    by?: string;
+}, now: Date): Escalation;
+export declare function withdraw(e: Escalation, now: Date): Escalation;
+export declare function claim(e: Escalation, conversationId: number, now: Date): Escalation;
+export declare function resolve(e: Escalation, conversationId: number, outcome: "done" | "failed", note: string, now: Date): Escalation;
+/** Reopen an unclaimed answer when its immediate action could not start. */
+export declare function reopen(e: Escalation, note: string, now: Date): Escalation;
+export declare function release(e: Escalation, conversationId: number, note: string, now: Date): Escalation;
+export declare function dismiss(e: Escalation, now: Date): Escalation;
+export declare function restore(e: Escalation, now: Date): Escalation;
+export declare function snooze(e: Escalation, days: number, now: Date): Escalation;
+export declare function endSnooze(e: Escalation, now: Date): Escalation;
+export declare function orphan(e: Escalation, now: Date): Escalation;
+export declare function isSkip(e: Escalation): boolean;

package/dist/lifecycle.js

@@ -0,0 +1,159 @@
+import { randomUUID } from "node:crypto";
+import { SKIP_STATUSES, } from "./types.js";
+/** A disallowed lifecycle transition, identified by a stable machine code. */
+export class TransitionError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.name = "TransitionError";
+        this.code = code;
+    }
+}
+function changed(e, now, entry, updates) {
+    return {
+        ...e,
+        ...updates,
+        updatedAt: now.toISOString(),
+        history: [...e.history, { at: now.toISOString(), ...entry }],
+    };
+}
+export function raise(input, now) {
+    const at = now.toISOString();
+    return {
+        ...input,
+        id: randomUUID(),
+        status: "open",
+        createdAt: at,
+        updatedAt: at,
+        history: [{ at, event: "raised" }],
+    };
+}
+export function answer(e, a, now) {
+    if (e.status !== "open")
+        throw new TransitionError("not_open");
+    if (e.orphaned)
+        throw new TransitionError("orphaned");
+    if (a.option === undefined && a.instruction === undefined) {
+        throw new TransitionError("empty_answer");
+    }
+    if (a.option !== undefined && !e.options.some((option) => option.id === a.option)) {
+        throw new TransitionError("unknown_option");
+    }
+    if (a.instruction !== undefined && !e.allowInstruction) {
+        throw new TransitionError("instruction_not_allowed");
+    }
+    const nextAnswer = {
+        ...(a.option === undefined ? {} : { option: a.option }),
+        ...(a.instruction === undefined ? {} : { instruction: a.instruction }),
+        ...(a.by === undefined ? {} : { by: a.by }),
+        at: now.toISOString(),
+    };
+    return changed(e, now, { event: "answered", answer: nextAnswer }, { status: "answered", answer: nextAnswer });
+}
+export function withdraw(e, now) {
+    if (e.status !== "answered")
+        throw new TransitionError("not_answered");
+    return changed(e, now, { event: "withdrawn", ...(e.answer === undefined ? {} : { answer: e.answer }) }, { status: "open", answer: undefined });
+}
+export function claim(e, conversationId, now) {
+    if (e.status === "claimed" && e.claim?.conversationId === conversationId) {
+        return e;
+    }
+    if (e.status !== "answered")
+        throw new TransitionError("not_claimable");
+    return changed(e, now, { event: "claimed" }, { status: "claimed", claim: { conversationId, at: now.toISOString() } });
+}
+export function resolve(e, conversationId, outcome, note, now) {
+    if (e.status !== "claimed" || e.claim === undefined) {
+        throw new TransitionError("not_claimed");
+    }
+    if (e.claim.conversationId !== conversationId) {
+        throw new TransitionError("wrong_claimant");
+    }
+    if (outcome === "done") {
+        return changed(e, now, { event: "resolved", note }, { status: "resolved", resolvedAt: now.toISOString() });
+    }
+    return changed(e, now, {
+        event: "failed",
+        note,
+        ...(e.answer === undefined ? {} : { answer: e.answer }),
+    }, {
+        status: "open",
+        answer: undefined,
+        claim: undefined,
+        reopenReason: "failed",
+    });
+}
+/** Reopen an unclaimed answer when its immediate action could not start. */
+export function reopen(e, note, now) {
+    if (e.status !== "answered")
+        throw new TransitionError("not_reopenable");
+    return changed(e, now, {
+        event: "interrupted",
+        note,
+        ...(e.answer === undefined ? {} : { answer: e.answer }),
+    }, { status: "open", answer: undefined, reopenReason: "interrupted" });
+}
+export function release(e, conversationId, note, now) {
+    if (e.status !== "claimed" || e.claim?.conversationId !== conversationId) {
+        throw new TransitionError("not_claimed");
+    }
+    return changed(e, now, {
+        event: "interrupted",
+        note,
+        ...(e.answer === undefined ? {} : { answer: e.answer }),
+    }, {
+        status: "open",
+        answer: undefined,
+        claim: undefined,
+        reopenReason: "interrupted",
+    });
+}
+export function dismiss(e, now) {
+    if (e.status !== "open" && e.status !== "answered") {
+        throw new TransitionError("not_dismissable");
+    }
+    return changed(e, now, { event: "dismissed" }, { status: "dismissed", answer: undefined });
+}
+export function restore(e, now) {
+    if (e.status !== "dismissed")
+        throw new TransitionError("not_dismissed");
+    return changed(e, now, { event: "restored" }, { status: "open" });
+}
+export function snooze(e, days, now) {
+    if (!Number.isInteger(days) || days < 1 || days > 365) {
+        throw new TransitionError("bad_days");
+    }
+    if (e.status !== "open" && e.status !== "answered") {
+        throw new TransitionError("not_snoozable");
+    }
+    if (e.orphaned)
+        throw new TransitionError("orphaned");
+    return changed(e, now, { event: "snoozed" }, {
+        status: "snoozed",
+        answer: undefined,
+        snoozedUntil: new Date(now.getTime() + days * 86_400_000).toISOString(),
+    });
+}
+export function endSnooze(e, now) {
+    if (e.status !== "snoozed" ||
+        e.snoozedUntil === undefined ||
+        e.snoozedUntil > now.toISOString()) {
+        return e;
+    }
+    return changed(e, now, { event: "snooze-ended" }, { status: "open", snoozedUntil: undefined, reopenReason: "snooze-ended" });
+}
+export function orphan(e, now) {
+    if (e.status === "resolved" || e.status === "dismissed" || e.orphaned) {
+        return e;
+    }
+    return changed(e, now, { event: "job-deleted", note: "job deleted" }, {
+        status: e.status === "answered" ? "open" : e.status,
+        answer: e.status === "answered" ? undefined : e.answer,
+        orphaned: true,
+        reopenReason: "job-deleted",
+    });
+}
+export function isSkip(e) {
+    return SKIP_STATUSES.includes(e.status);
+}

package/dist/notify.d.ts

@@ -0,0 +1,5 @@
+import type { SigrunHost } from "@sigrun/sigrun/extension";
+import type { Escalation } from "./types.js";
+export declare function notifyRaised(host: SigrunHost, e: Escalation): Promise<void>;
+export declare function notifyReopened(host: SigrunHost, e: Escalation): Promise<void>;
+export declare function notifyOrphaned(host: SigrunHost, e: Escalation): Promise<void>;

package/dist/notify.js

@@ -0,0 +1,24 @@
+async function notify(host, e, kind, title) {
+    const input = {
+        user: e.owner,
+        kind,
+        title,
+        body: e.body.slice(0, 200),
+        target: { view: "inbox", params: { id: e.id } },
+    };
+    try {
+        await host.notify(input);
+    }
+    catch (error) {
+        console.warn(`escalations: ${kind} notification failed for ${e.id}`, error);
+    }
+}
+export async function notifyRaised(host, e) {
+    await notify(host, e, "escalation.raised", `Needs your decision: ${e.title}`);
+}
+export async function notifyReopened(host, e) {
+    await notify(host, e, "escalation.reopened", `Back in your inbox: ${e.title}`);
+}
+export async function notifyOrphaned(host, e) {
+    await notify(host, e, "escalation.orphaned", `Job deleted: ${e.title}`);
+}

package/dist/section.d.ts

@@ -0,0 +1,2 @@
+export declare const ESCALATIONS_SECTION_TEXT = "Escalations: when something needs the user's decision and has no prescribed way forward, call `escalate` instead of guessing. Make the body self-contained: the evidence, the exact action you propose, and the alternatives \u2014 whoever acts on the answer may not have this conversation. Offer the possible actions as options; never add \"do nothing\" or \"later\" options \u2014 the user has Dismiss and Snooze for those. In a scheduled job run, call `escalation_list` first: skip every key under `skip`, carry out each item under `act`, and call `escalation_resolve` for each before you finish.";
+export declare const escalationsSection: import("@earendil-works/pi-durable").PromptSection<import("@earendil-works/pi-durable").ToolRegistration>;

package/dist/section.js

@@ -0,0 +1,5 @@
+import { section } from "@earendil-works/pi-durable";
+export const ESCALATIONS_SECTION_TEXT = "Escalations: when something needs the user's decision and has no prescribed way forward, call `escalate` instead of guessing. Make the body self-contained: the evidence, the exact action you propose, and the alternatives — whoever acts on the answer may not have this conversation. Offer the possible actions as options; never add \"do nothing\" or \"later\" options — the user has Dismiss and Snooze for those. In a scheduled job run, call `escalation_list` first: skip every key under `skip`, carry out each item under `act`, and call `escalation_resolve` for each before you finish.";
+export const escalationsSection = section("escalations", (input) => input.agent.tools.some((tool) => tool.name === "escalate")
+    ? ESCALATIONS_SECTION_TEXT
+    : undefined);

package/dist/store.d.ts

@@ -0,0 +1,22 @@
+import type { Principal, SigrunHost } from "@sigrun/sigrun/extension";
+import type { Bucket, Escalation } from "./types.js";
+/** Durable per-bucket escalation storage. */
+export declare class EscalationStore {
+    private readonly host;
+    private readonly files;
+    constructor(host: SigrunHost);
+    fileOf(bucket: Bucket): string;
+    list(bucket: Bucket): Promise<Escalation[]>;
+    update<T>(bucket: Bucket, fn: (items: Escalation[]) => {
+        items: Escalation[];
+        result: T;
+    }): Promise<T>;
+    private fileFor;
+}
+export declare function bucketFor(host: SigrunHost, owner: string | undefined): Promise<Bucket>;
+export declare function bucketsVisibleTo(host: SigrunHost, principal: Principal): Promise<Bucket[]>;
+export declare function allBuckets(host: SigrunHost): Promise<Bucket[]>;
+export declare function findVisible(store: EscalationStore, buckets: readonly Bucket[], id: string): Promise<{
+    bucket: Bucket;
+    item: Escalation;
+} | undefined>;

package/dist/store.js

@@ -0,0 +1,71 @@
+import { join } from "node:path";
+import { JsonFile } from "./json-file.js";
+/** Durable per-bucket escalation storage. */
+export class EscalationStore {
+    host;
+    // One JsonFile per path is essential: its serialization queue is per
+    // instance, so constructing one per update would permit lost updates.
+    files = new Map();
+    constructor(host) {
+        this.host = host;
+    }
+    fileOf(bucket) {
+        return join(bucket.kind === "user"
+            ? this.host.stores.user(bucket.user).paths.data
+            : this.host.stores.paths.data, "escalations.json");
+    }
+    list(bucket) {
+        return this.fileFor(bucket).read();
+    }
+    async update(bucket, fn) {
+        let result;
+        await this.fileFor(bucket).update((items) => {
+            const next = fn(items);
+            result = next.result;
+            // JsonFile treats an unchanged array reference as the no-write fast path.
+            return next.items;
+        });
+        return result;
+    }
+    fileFor(bucket) {
+        const path = this.fileOf(bucket);
+        let file = this.files.get(path);
+        if (file === undefined) {
+            file = new JsonFile(path, () => []);
+            this.files.set(path, file);
+        }
+        return file;
+    }
+}
+export async function bucketFor(host, owner) {
+    if (owner !== undefined && (await host.users.get(owner)) !== undefined) {
+        return { kind: "user", user: owner };
+    }
+    const primaryAdmin = (await host.users.list()).find((user) => user.admin);
+    return primaryAdmin === undefined
+        ? { kind: "shared" }
+        : { kind: "user", user: primaryAdmin.user };
+}
+export async function bucketsVisibleTo(host, principal) {
+    // Core's naive-loopback superuser and service token carry no user
+    // (src/server/auth/principal.ts:27-30), so they see the shared bucket.
+    if (principal.user === undefined)
+        return [{ kind: "shared" }];
+    return (await host.users.get(principal.user)) === undefined
+        ? []
+        : [{ kind: "user", user: principal.user }];
+}
+export async function allBuckets(host) {
+    return [
+        ...(await host.users.list()).map((user) => ({ kind: "user", user: user.user })),
+        { kind: "shared" },
+    ];
+}
+export async function findVisible(store, buckets, id) {
+    for (const bucket of buckets) {
+        const item = (await store.list(bucket)).find((candidate) => candidate.id === id);
+        if (item !== undefined)
+            return { bucket, item };
+    }
+    return undefined;
+}

package/dist/sweep.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The escalation sweep task (`escalations.sweep`), fired by the `sweep`
+ * cron job every 15 minutes. Pure host calls + store updates: no model,
+ * no transcript content.
+ *
+ * Job transfers first copy their items to the current owner's bucket,
+ * then remove them from the source. Each remaining source bucket gets ONE
+ * lifecycle update: end due snoozes, orphan items whose job was deleted,
+ * release claims older than 24h, and prune resolved items older than 90
+ * days. Job lookups are PREFETCHED before entering updates so no bucket
+ * queue is held across harness reads.
+ * Notifications and inbox-change signals fire AFTER the update, for
+ * reopened/orphaned items only. A failing bucket lands in `errors` and
+ * the sweep continues to the next bucket.
+ */
+import type { SigrunHost } from "@sigrun/sigrun/extension";
+import { EscalationStore } from "./store.js";
+/** The registered task kind; the cron job's action names it. */
+export declare const SWEEP_TASK_NAME = "escalations.sweep";
+/** The 15-minute cron job the factory declares. */
+export declare const SWEEP_JOB: {
+    readonly name: "sweep";
+    readonly schedule: {
+        readonly every: "15m";
+    };
+    readonly action: {
+        readonly kind: "task";
+        readonly task: "escalations.sweep";
+    };
+};
+export interface SweepReport {
+    snoozesEnded: number;
+    orphaned: number;
+    claimsExpired: number;
+    pruned: number;
+    errors: string[];
+}
+export interface SweepDeps {
+    readonly host: SigrunHost;
+    readonly store: EscalationStore;
+    readonly now?: () => Date;
+}
+/** The sweep body, shared by the task phase and directly unit-testable. */
+export declare function runSweep(deps: SweepDeps): Promise<SweepReport>;
+/** The task object the extension registers. */
+export declare function createSweepTask(deps: SweepDeps): import("@earendil-works/pi-durable").Task<unknown, {
+    phase: "sweep";
+}, unknown, object>;

package/dist/sweep.js

@@ -0,0 +1,173 @@
+/**
+ * The escalation sweep task (`escalations.sweep`), fired by the `sweep`
+ * cron job every 15 minutes. Pure host calls + store updates: no model,
+ * no transcript content.
+ *
+ * Job transfers first copy their items to the current owner's bucket,
+ * then remove them from the source. Each remaining source bucket gets ONE
+ * lifecycle update: end due snoozes, orphan items whose job was deleted,
+ * release claims older than 24h, and prune resolved items older than 90
+ * days. Job lookups are PREFETCHED before entering updates so no bucket
+ * queue is held across harness reads.
+ * Notifications and inbox-change signals fire AFTER the update, for
+ * reopened/orphaned items only. A failing bucket lands in `errors` and
+ * the sweep continues to the next bucket.
+ */
+import { defineTask } from "@earendil-works/pi-durable";
+import { changedInbox } from "./keys.js";
+import { endSnooze, orphan, release } from "./lifecycle.js";
+import { notifyOrphaned, notifyReopened } from "./notify.js";
+import { allBuckets, bucketFor } from "./store.js";
+import { transferItems } from "./transfer.js";
+/** The registered task kind; the cron job's action names it. */
+export const SWEEP_TASK_NAME = "escalations.sweep";
+/** The 15-minute cron job the factory declares. */
+export const SWEEP_JOB = {
+    name: "sweep",
+    schedule: { every: "15m" },
+    action: { kind: "task", task: SWEEP_TASK_NAME },
+};
+const DAY_MS = 86_400_000;
+const CLAIM_TIMEOUT_MS = 24 * 60 * 60 * 1000;
+const RESOLVED_RETENTION_MS = 90 * DAY_MS;
+const CLAIM_TIMED_OUT = "claim timed out";
+function jobIdOf(e) {
+    return e.namespace.startsWith("job:")
+        ? e.namespace.slice("job:".length)
+        : undefined;
+}
+/** Read-only planning pass: which jobs exist. Never holds the bucket queue. */
+async function planSweep(deps, bucket) {
+    const items = await deps.store.list(bucket);
+    const jobs = new Map();
+    for (const item of items) {
+        const jobId = jobIdOf(item);
+        if (jobId === undefined || jobs.has(jobId))
+            continue;
+        jobs.set(jobId, await deps.host.jobs.get(jobId));
+    }
+    return { items, jobs };
+}
+/** Reconcile job-owned items into the buckets of their jobs' current owners. */
+async function migrateTransferredJobs(deps, bucket, plan, now) {
+    const owner = bucket.kind === "user" ? bucket.user : undefined;
+    for (const [jobId, job] of plan.jobs) {
+        if (job === undefined || job.owner === owner)
+            continue;
+        const ids = new Set(plan.items.filter((item) => jobIdOf(item) === jobId).map((item) => item.id));
+        await transferItems(deps.store, bucket, await bucketFor(deps.host, job.owner), ids, now);
+    }
+}
+/** One atomic lifecycle update per source bucket: the four phases in order. */
+async function sweepBucket(deps, bucket, plan, now) {
+    const reopened = [];
+    const orphaned = [];
+    return deps.store.update(bucket, (items) => {
+        const next = [];
+        const report = { snoozesEnded: 0, orphaned: 0, claimsExpired: 0, pruned: 0 };
+        for (const item of items) {
+            // 4. Retention: drop resolved items older than 90 days.
+            if (item.status === "resolved" &&
+                item.resolvedAt !== undefined &&
+                item.resolvedAt <= new Date(now.getTime() - RESOLVED_RETENTION_MS).toISOString()) {
+                report.pruned += 1;
+                continue;
+            }
+            let current = item;
+            // 1. Snoozes due at or before now.
+            const unsnoozed = endSnooze(current, now);
+            if (unsnoozed !== current) {
+                current = unsnoozed;
+                reopened.push(current);
+                report.snoozesEnded += 1;
+            }
+            // 2. Orphan items whose job no longer exists.
+            const jobId = jobIdOf(current);
+            if (jobId !== undefined && plan.jobs.get(jobId) === undefined) {
+                const nextOrphan = orphan(current, now);
+                if (nextOrphan !== current) {
+                    current = nextOrphan;
+                    orphaned.push(current);
+                    report.orphaned += 1;
+                }
+            }
+            // 3. Release claims older than 24h (orphaned claimed items stay
+            // claimed until this timeout — see E1 reviewer note).
+            if (current.status === "claimed" &&
+                current.claim !== undefined &&
+                current.claim.at <= new Date(now.getTime() - CLAIM_TIMEOUT_MS).toISOString()) {
+                current = release(current, current.claim.conversationId, CLAIM_TIMED_OUT, now);
+                report.claimsExpired += 1;
+            }
+            next.push(current);
+        }
+        return { items: next, result: { report, reopened, orphaned } };
+    });
+}
+/** The sweep body, shared by the task phase and directly unit-testable. */
+export async function runSweep(deps) {
+    const now = deps.now?.() ?? new Date();
+    const report = {
+        snoozesEnded: 0,
+        orphaned: 0,
+        claimsExpired: 0,
+        pruned: 0,
+        errors: [],
+    };
+    for (const bucket of await allBuckets(deps.host)) {
+        try {
+            const plan = await planSweep(deps, bucket);
+            await migrateTransferredJobs(deps, bucket, plan, now);
+            const outcome = await sweepBucket(deps, bucket, plan, now);
+            report.snoozesEnded += outcome.report.snoozesEnded;
+            report.orphaned += outcome.report.orphaned;
+            report.claimsExpired += outcome.report.claimsExpired;
+            report.pruned += outcome.report.pruned;
+            // Notifications AFTER the update, only for reopened/orphaned items.
+            for (const item of outcome.reopened) {
+                await notifyReopened(deps.host, item);
+                changedInbox(deps.host, item.id);
+            }
+            for (const item of outcome.orphaned) {
+                await notifyOrphaned(deps.host, item);
+                changedInbox(deps.host, item.id);
+            }
+        }
+        catch (error) {
+            const path = deps.store.fileOf(bucket);
+            const message = error instanceof Error ? error.message : String(error);
+            report.errors.push(`${path}: ${message}`);
+            console.warn(`escalations: sweep failed for ${path}`, error);
+        }
+    }
+    return report;
+}
+/** The task object the extension registers. */
+export function createSweepTask(deps) {
+    return defineTask({
+        name: SWEEP_TASK_NAME,
+        version: 1,
+        initial: () => ({ phase: "sweep" }),
+        phases: {
+            sweep: async (_task, runtime, context) => {
+                await runSweep(deps);
+                // REQUIRED: a phase returning without durable progress faults the
+                // task. The sweep's bookkeeping lives in the store files; the
+                // task's own terminal outcome is the durable progress.
+                await runtime.commit(() => ({
+                    status: "terminal",
+                    outcome: { status: "completed", result: undefined },
+                }), context);
+            },
+        },
+        abort: async (_task, runtime, context) => {
+            await runtime.commit(() => ({
+                status: "terminal",
+                outcome: {
+                    status: "failed",
+                    error: { message: "aborted" },
+                },
+            }), context);
+        },
+    });
+}

package/dist/tools.d.ts

@@ -0,0 +1,10 @@
+import { type ToolRegistration } from "@earendil-works/pi-durable";
+import type { SigrunHost } from "@sigrun/sigrun/extension";
+import { EscalationStore } from "./store.js";
+export interface ToolDeps {
+    readonly host: SigrunHost;
+    readonly store: EscalationStore;
+    readonly now?: () => Date;
+}
+/** Build the three host-identity-derived escalation tools over one store. */
+export declare function createTools(deps: ToolDeps): ToolRegistration[];