@sigrun/escalations 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+### Added
+- The escalation extension factory with `escalate`, `escalation_list`, and
+  `escalation_resolve` tools, prompt guidance, a four-tab Inbox, immediate
+  and next-run dispatch, and a 15-minute maintenance sweep.
+- Durable per-user escalation records with answer, claim, snooze, dismiss,
+  restore, failure recovery, and resolved-item retention lifecycles.
+- At-least-once escalation transfer when a directory user is deleted.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael MacLeod
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# @sigrun/escalations
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An asynchronous decision inbox for [sigrun](https://github.com/sigrun-ai/sigrun). Jobs and agents can ask a person to choose a course of action without pausing the work that raised the question. Escalations are durable records with a complete history; they live in their own **Inbox** pane rather than blocking a conversation.
+
+Unlike a mid-conversation question, an escalation does not suspend its source. A scheduled run can finish and deal with the decision on a later run, and an agent can hand the answered decision to a fresh run. Both surfaces use the same choice-and-instruction vocabulary, but only a person answers, dismisses, or snoozes an escalation.
+
+## Requirements and installation
+
+This extension requires **sigrun core with job hooks (unreleased at the time of writing)** — the first release carrying `host.notify`, `host.jobs` and `conversations.create({job})`.
+
+Add `@sigrun/escalations` to the `extensions` list in sigrun's settings. The extension contributes the three agent tools, the Inbox view, and a maintenance job that runs every 15 minutes.
+
+## Agent tools
+
+### `escalate`
+
+Raises a decision for the conversation owner. Parameters:
+
+- `key` (string, required): a stable identifier for the underlying issue, such as a resource key.
+- `title` (string, required): a short summary.
+- `body` (string, required): self-contained evidence, context, and the proposed action.
+- `options` (array, required): one to eight choices. Each has a stable `id`, a `label`, and an optional `detail`. Do not offer “do nothing” or “later” choices; the person already has Dismiss and Snooze.
+- `allowInstruction` (boolean, optional): whether the answer may include a free-text instruction. Defaults to `true`.
+- `onAnswer` (`"next-run"` or `"immediate"`, optional): how to act after the answer. See below.
+
+An unresolved item with the same key in the same job or user namespace is returned instead of duplicated. Raising a new item notifies its owner.
+
+### `escalation_list`
+
+Takes no parameters and returns two groups:
+
+- **`skip`**: keys the current job must not act on because a matching escalation is open, answered, claimed, dismissed, or snoozed and is not held by this conversation. A dismissed or snoozed issue therefore stays out of the job's way until the person restores it or the snooze ends.
+- **`act`**: answered `next-run` items whose work this conversation should carry out, including the chosen option and any instruction.
+
+A scheduled (`cron`) run atomically claims its actionable items when it lists them. Other callers only see claims they already hold. After carrying out each claimed item, the run must resolve it.
+
+### `escalation_resolve`
+
+Resolves one item claimed by the current conversation:
+
+- `id` (string, required): the escalation id.
+- `outcome` (`"done"` or `"failed"`, required): whether the requested action succeeded.
+- `note` (string, required): a short outcome record for the history.
+
+`done` moves the item to **Resolved**. `failed` returns it to **Open**, clears its answer and claim, and records that the action failed. Only the claiming conversation may resolve the item.
+
+## Next-run versus immediate dispatch
+
+For a job conversation, the default is **`next-run`**: the answer waits until a later scheduled run, when `escalation_list` claims it for action. `next-run` is valid only for an item raised by a scheduled job.
+
+For an ordinary agent conversation, the default is **`immediate`**: answering starts a fresh run in a **new conversation**, seeded with the escalation and the answer. It does not resume or modify the source conversation. An immediate item from a job also starts a fresh run. If the new run cannot be created or seeded, the item returns to open; if it settles without resolving its claim, the item is released back to open.
+
+## The Inbox
+
+The Inbox has four tabs:
+
+- **Open**: unanswered decisions, including items returned by failed or interrupted actions.
+- **In progress**: answered, claimed, and snoozed items.
+- **Dismissed**: items the person has set aside. Restore moves one back to open.
+- **Resolved**: completed items, retained for 90 days after resolution.
+
+An open item can be answered by selecting an offered option and, when allowed, adding an instruction. **Dismiss** and **Snooze** are user-only actions, never agent options. A snooze lasts from 1 to 365 days; when it ends, the maintenance job returns the item to open. Nothing automatically answers an escalation or acts merely because a snooze expired.
+
+The maintenance sweep also releases claims older than 24 hours, marks items whose source job was deleted, and prunes old resolved records. An orphaned item offers only Dismiss; nothing acts on it automatically.

package/dist/dispatch.d.ts

@@ -0,0 +1,14 @@
+import type { ExtensionRunSettledHandler, SigrunHost } from "@sigrun/sigrun/extension";
+import { EscalationStore } from "./store.js";
+import type { Bucket, Escalation } from "./types.js";
+export interface DispatchDeps {
+    readonly host: SigrunHost;
+    readonly store: EscalationStore;
+    readonly now?: () => Date;
+}
+/** Seed the fresh immediate-run conversation with the complete decision. */
+export declare function seedText(e: Escalation, jobName?: string): string;
+/** Create, claim, and seed one immediate run for an answered item. */
+export declare function startImmediateRun(deps: DispatchDeps, bucket: Bucket, id: string): Promise<number | undefined>;
+/** Release claims left unresolved by a settled run, isolating every failure. */
+export declare function createRunSettled(deps: DispatchDeps): ExtensionRunSettledHandler;

package/dist/dispatch.js

@@ -0,0 +1,165 @@
+import { changedInbox } from "./keys.js";
+import { TransitionError, claim, release, reopen } from "./lifecycle.js";
+import { notifyReopened } from "./notify.js";
+import { bucketFor } from "./store.js";
+import { transferItems } from "./transfer.js";
+const RUN_ENDED = "run ended without resolving the escalation";
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function sourceText(e, jobName) {
+    if (e.source.jobId !== undefined)
+        return `job "${jobName ?? e.source.jobId}" (${e.source.jobId})`;
+    if (e.source.conversationId !== undefined)
+        return `conversation #${e.source.conversationId}`;
+    return "none";
+}
+/** Seed the fresh immediate-run conversation with the complete decision. */
+export function seedText(e, jobName) {
+    const option = e.options.find((candidate) => candidate.id === e.answer?.option);
+    const chosen = option === undefined
+        ? "none chosen"
+        : `${option.label} (${option.id})`;
+    return `You are acting on an answered escalation (id ${e.id}).\n\n` +
+        `Title: ${e.title}\n` +
+        `Source: ${sourceText(e, jobName)}\n\n` +
+        `## Escalation\n${e.body}\n\n` +
+        `## The user's answer\n` +
+        `Chosen action: ${chosen}\n` +
+        `Instruction: ${e.answer?.instruction ?? "none"}\n\n` +
+        `Carry out the chosen action, following the instruction if one is given. When you are finished, call escalation_resolve with id "${e.id}", outcome "done" or "failed", and a short note. Do not raise a new escalation for this same issue.`;
+}
+async function reopenAnswer(deps, bucket, id, note) {
+    return await deps.store.update(bucket, (items) => {
+        let reopened;
+        const next = items.map((item) => {
+            if (item.id !== id || item.status !== "answered")
+                return item;
+            reopened = reopen(item, note, deps.now?.() ?? new Date());
+            return reopened;
+        });
+        return { items: reopened === undefined ? items : next, result: reopened };
+    });
+}
+async function releaseClaim(deps, bucket, id, conversationId, note) {
+    const now = deps.now?.() ?? new Date();
+    return await deps.store.update(bucket, (items) => {
+        let released;
+        const next = items.map((item) => {
+            if (item.id !== id || item.status !== "claimed" || item.claim?.conversationId !== conversationId) {
+                return item;
+            }
+            released = release(item, conversationId, note, now);
+            return released;
+        });
+        return { items: released === undefined ? items : next, result: released };
+    });
+}
+/** Create, claim, and seed one immediate run for an answered item. */
+export async function startImmediateRun(deps, bucket, id) {
+    const { host, store } = deps;
+    let activeBucket = bucket;
+    let existing = (await store.list(activeBucket)).find((item) => item.id === id);
+    if (existing === undefined)
+        return undefined;
+    const job = existing.source.jobId === undefined
+        ? undefined
+        : await host.jobs.get(existing.source.jobId);
+    if (job !== undefined && job.owner !== existing.owner) {
+        const target = await bucketFor(host, job.owner);
+        await transferItems(store, activeBucket, target, new Set([id]), deps.now?.() ?? new Date());
+        activeBucket = target;
+        existing = (await store.list(activeBucket)).find((item) => item.id === id);
+        if (existing === undefined)
+            return undefined;
+    }
+    let conversationId;
+    try {
+        conversationId = await host.conversations.create({
+            owner: job === undefined ? existing.owner : job.owner,
+            name: `Escalation: ${existing.title}`.slice(0, 120),
+            source: "escalations",
+            ...(job === undefined ? {} : { job: job.id }),
+        });
+    }
+    catch (error) {
+        const reopened = await reopenAnswer(deps, activeBucket, id, `dispatch failed: ${errorMessage(error)}`);
+        if (reopened !== undefined) {
+            await notifyReopened(host, reopened);
+            changedInbox(host, reopened.id);
+        }
+        return undefined;
+    }
+    const claimed = await store.update(activeBucket, (items) => {
+        let nextClaim;
+        const next = items.map((item) => {
+            if (item.id !== id)
+                return item;
+            try {
+                nextClaim = claim(item, conversationId, deps.now?.() ?? new Date());
+                return nextClaim;
+            }
+            catch (error) {
+                if (error instanceof TransitionError)
+                    return item;
+                throw error;
+            }
+        });
+        return { items: nextClaim === undefined ? items : next, result: nextClaim };
+    });
+    if (claimed === undefined)
+        return undefined;
+    try {
+        await host.conversations.submit(conversationId, [
+            { type: "text", text: seedText(existing, job?.name) },
+        ]);
+        return conversationId;
+    }
+    catch (error) {
+        const released = await releaseClaim(deps, activeBucket, id, conversationId, `dispatch failed: ${errorMessage(error)}`);
+        if (released !== undefined) {
+            await notifyReopened(host, released);
+            changedInbox(host, released.id);
+        }
+        return undefined;
+    }
+}
+/** Release claims left unresolved by a settled run, isolating every failure. */
+export function createRunSettled(deps) {
+    return async (event) => {
+        try {
+            const bucket = await bucketFor(deps.host, event.owner);
+            const items = await deps.store.list(bucket);
+            if (!items.some((item) => item.status === "claimed" && item.claim?.conversationId === event.conversationId))
+                return;
+            const released = await deps.store.update(bucket, (current) => {
+                const nextReleased = [];
+                const next = current.map((item) => {
+                    if (item.status !== "claimed" || item.claim?.conversationId !== event.conversationId)
+                        return item;
+                    const reopened = release(item, event.conversationId, RUN_ENDED, deps.now?.() ?? new Date());
+                    nextReleased.push(reopened);
+                    return reopened;
+                });
+                return { items: nextReleased.length === 0 ? current : next, result: nextReleased };
+            });
+            for (const item of released) {
+                try {
+                    await notifyReopened(deps.host, item);
+                }
+                catch (error) {
+                    console.warn(`escalations: reopen notification failed for ${item.id}`, error);
+                }
+                try {
+                    changedInbox(deps.host, item.id);
+                }
+                catch (error) {
+                    console.warn(`escalations: inbox change notification failed for ${item.id}`, error);
+                }
+            }
+        }
+        catch (error) {
+            console.warn(`escalations: runSettled failed for conversation ${event.conversationId}`, error);
+        }
+    };
+}

package/dist/inbox.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The Inbox view (Task E6): the four-tab list (Open / In progress /
+ * Dismissed / Resolved) and the per-item detail page, over the visible
+ * buckets of the CALLING principal.
+ *
+ * - List rows carry a `source` label field and the collection groups on
+ *   it, so the list groups by job / conversation / agent (spec §4.5).
+ *   The open tab sorts reopened items first, then newest; resolved is
+ *   newest first. An answered `next-run` item whose job is disabled
+ *   shows the badge `Waiting: job disabled`.
+ * - Detail mode is a page titled with the escalation title: markdown
+ *   body, answer form (options in the agent's order, NONE marked
+ *   recommended — the webui preselects recommended options and the
+ *   proposed action may be destructive), snooze form seeded at 7 days
+ *   (number fields have no `default` prop), Dismiss/Withdraw/Restore as
+ *   page actions, conversation links, and the history as a log block.
+ *   Orphaned items show only the pinned warn callout and Dismiss.
+ * - Every action resolves the item through `findVisible` over the
+ *   caller's buckets, so another user's id behaves exactly like an
+ *   unknown id (no title leak). Successful actions call `changedInbox`.
+ * - A store read failure renders a `bad` callout with the error message
+ *   instead of the collection (the render never throws on corrupt data).
+ */
+import type { SigrunHost, SurfaceDef } from "@sigrun/sigrun/extension";
+import { EscalationStore } from "./store.js";
+export interface InboxDeps {
+    readonly host: SigrunHost;
+    readonly store: EscalationStore;
+    readonly now?: () => Date;
+}
+export declare function createInboxView(deps: InboxDeps): SurfaceDef<"view">;