@sigrun/escalations 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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]
+
+## [0.2.1] - 2026-11-06
+
+### Changed
+
+- The Inbox is one split page: the tab's list in the sidebar (tabs stay
+  in the header), the selected escalation in main, with its actions on
+  a header callout and a `Viewing` badge on the row being read. Params
+  are `{tab?, id}`: an id with no tab lists the item's own tab (notice
+  and tool links), opening a row keeps the current tab, and compact
+  widths use the page selection drill-in (list first, back to the tab).
+  An unknown or invisible id keeps the caller's list and shows "not
+  found" in main (identical for both — no title leak).
+
+## [0.2.0] - 2026-11-05
+
+### Added
+
+- Published hooks `escalation.raise`, `escalation.take` and
+  `escalation.resolve`: the extension-to-extension seam over the same
+  store and lifecycle as the `escalate` tool. `take` claims an ANSWERED
+  item for the calling conversation (idempotent per conversation,
+  caller's bucket only); `resolve` needs the claiming conversation
+  (wrong_claimant propagates). The warden is the first consumer
+  (one-shot job grants).
+
 ## [0.1.1] - 2026-11-03
 ### Fixed
 - `reopenReason` is cleared on forward transitions (`resolve` done,
@@ -28,7 +55,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The factory accepts an optional `{ now }` clock for tests (arity one
   is preserved for the loader).
 
-## [Unreleased]
+## [0.1.0] - 2026-11-02
+
 ### Added
 - The escalation extension factory with `escalate`, `escalation_list`, and
   `escalation_resolve` tools, prompt guidance, a four-tab Inbox, immediate

package/README.md

@@ -44,6 +44,30 @@ Resolves one item claimed by the current conversation:
 
 `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.
 
+## Published hooks
+
+The extension publishes three hooks for other extensions through core's published-hook registry (`host.publishedHooks`). All three require a call context with a `conversationId`; without one the call fails with `escalation hooks need a conversation`.
+
+The namespace is `job:<jobId>` when the payload passes a `jobId`, else the calling conversation's `meta.jobId`, else `"user"`. The bucket comes from the calling conversation's owner, exactly as the agent tools do. All writes go through the store's serialized `update`.
+
+### `escalation.raise`
+
+Input: `{ key, title, body, options, allowInstruction?, onAnswer?, jobId? }` with the same bounds as the `escalate` tool (`key` and `title` ≤ 200 chars, `body` ≤ 20000, 1–8 options with unique ids). Output: `{ id, created, status }`.
+
+Behavior mirrors `escalate`: an unresolved item with the same namespace and key is returned with `created: false` instead of duplicating; a new item notifies its owner. `onAnswer` defaults to `next-run` in a job namespace and `immediate` otherwise; `next-run` without any job context throws. `allowInstruction` defaults to `false`.
+
+### `escalation.take`
+
+Input: `{ key, jobId? }`. Output: `{ status, id?, option? }`.
+
+Finds the unresolved item with the given namespace and key. When none exists, returns `{ status: "none" }`. An **answered** item is claimed for the calling conversation, returning `{ status: "claimed", id, option }` with the answer's option. The take is idempotent for the claiming conversation; another conversation (or an **open** item) gets the item's current status without claiming anything.
+
+### `escalation.resolve`
+
+Input: `{ id, outcome: "done" | "failed", note? }` (`note` defaults to `""`). Output: `{ status }`.
+
+Finds the item by id and resolves it through the claiming conversation. Only the claiming conversation may resolve; a wrong claimant or an unclaimed item fails with the lifecycle transition code (`wrong_claimant` / `not_claimed`) as the error message.
+
 ## 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.

package/dist/hooks.d.ts

@@ -0,0 +1,4 @@
+import type { PublishedHook } from "@sigrun/sigrun/extension";
+import type { DispatchDeps } from "./dispatch.js";
+/** Build the three published escalation hooks over one shared store. */
+export declare function createPublishedHooks(deps: DispatchDeps): readonly PublishedHook[];

package/dist/hooks.js

@@ -0,0 +1,192 @@
+import { Type } from "@earendil-works/pi-ai";
+import { changedInbox } from "./keys.js";
+import { TransitionError, claim, raise, resolve } from "./lifecycle.js";
+import { notifyRaised, notifyReopened } from "./notify.js";
+import { bucketFor } from "./store.js";
+// Bounds mirror the escalate tool's parameters (tools.ts OptionSchema).
+const OptionSchema = Type.Object({
+    id: Type.String({
+        minLength: 1,
+        maxLength: 64,
+        pattern: "^[a-z0-9][a-z0-9_-]{0,63}$",
+    }),
+    label: Type.String({ minLength: 1, maxLength: 200 }),
+    detail: Type.Optional(Type.String({ maxLength: 2000 })),
+});
+const KeySchema = Type.String({ minLength: 1, maxLength: 200 });
+const JobIdSchema = Type.Optional(Type.String({ minLength: 1 }));
+const StatusSchema = Type.String();
+async function context(deps, call, jobId) {
+    if (call.conversationId === undefined) {
+        throw new Error("escalation hooks need a conversation");
+    }
+    const meta = await deps.host.conversations.meta(call.conversationId);
+    const effectiveJobId = jobId ?? meta.jobId;
+    return {
+        namespace: effectiveJobId === undefined ? "user" : `job:${effectiveJobId}`,
+        bucket: await bucketFor(deps.host, meta.owner),
+    };
+}
+/** Build the three published escalation hooks over one shared store. */
+export function createPublishedHooks(deps) {
+    const now = deps.now ?? (() => new Date());
+    const raiseHook = {
+        name: "escalation.raise",
+        description: "Raise an asynchronous decision for the user. Dedups by namespace+key among unresolved items.",
+        input: Type.Object({
+            key: KeySchema,
+            title: Type.String({ minLength: 1, maxLength: 200 }),
+            body: Type.String({ minLength: 1, maxLength: 20_000 }),
+            options: Type.Array(OptionSchema, { minItems: 1, maxItems: 8 }),
+            allowInstruction: Type.Optional(Type.Boolean({ default: false })),
+            onAnswer: Type.Optional(Type.Union([
+                Type.Literal("next-run"),
+                Type.Literal("immediate"),
+            ])),
+            jobId: JobIdSchema,
+        }),
+        output: Type.Object({
+            id: Type.String(),
+            created: Type.Boolean(),
+            status: StatusSchema,
+        }),
+        async run(payload, call) {
+            const args = payload;
+            if (call.conversationId === undefined) {
+                throw new Error("escalation hooks need a conversation");
+            }
+            const meta = await deps.host.conversations.meta(call.conversationId);
+            const effectiveJobId = args.jobId ?? meta.jobId;
+            const namespace = effectiveJobId === undefined ? "user" : `job:${effectiveJobId}`;
+            const bucket = await bucketFor(deps.host, meta.owner);
+            const onAnswer = args.onAnswer ?? (effectiveJobId === undefined ? "immediate" : "next-run");
+            if (onAnswer === "next-run" && effectiveJobId === undefined) {
+                throw new Error("escalation.raise: next-run needs a scheduled job run; use immediate");
+            }
+            const uniqueIds = new Set(args.options.map((option) => option.id));
+            if (uniqueIds.size !== args.options.length) {
+                throw new Error("escalation.raise: option ids must be unique");
+            }
+            const owner = bucket.kind === "user" ? bucket.user : undefined;
+            // The lookup and insertion share the store's one serialized callback.
+            const result = await deps.store.update(bucket, (items) => {
+                const existing = items.find((item) => item.namespace === namespace &&
+                    item.key === args.key &&
+                    item.status !== "resolved");
+                if (existing !== undefined) {
+                    return { items, result: { item: existing, created: false } };
+                }
+                const item = raise({
+                    ...(owner === undefined ? {} : { owner }),
+                    namespace,
+                    key: args.key,
+                    title: args.title,
+                    body: args.body,
+                    options: [...args.options],
+                    allowInstruction: args.allowInstruction ?? false,
+                    onAnswer,
+                    source: {
+                        ...(effectiveJobId === undefined ? {} : { jobId: effectiveJobId }),
+                        conversationId: call.conversationId,
+                    },
+                }, now());
+                return { items: [...items, item], result: { item, created: true } };
+            });
+            if (result.created) {
+                await notifyRaised(deps.host, result.item);
+                changedInbox(deps.host, result.item.id);
+            }
+            return {
+                id: result.item.id,
+                created: result.created,
+                status: result.item.status,
+            };
+        },
+    };
+    const takeHook = {
+        name: "escalation.take",
+        description: "Claim an answered escalation for the calling conversation, or report its current status.",
+        input: Type.Object({ key: KeySchema, jobId: JobIdSchema }),
+        output: Type.Object({
+            status: StatusSchema,
+            id: Type.Optional(Type.String()),
+            option: Type.Optional(Type.String()),
+        }),
+        async run(payload, call) {
+            const args = payload;
+            const { namespace, bucket } = await context(deps, call, args.jobId);
+            const conversationId = call.conversationId;
+            // Take stays in the caller's bucket: another user's item is never
+            // claimable (and its runSettled release sweep must not reach it).
+            const found = await deps.store.update(bucket, (items) => {
+                const item = items.find((entry) => entry.namespace === namespace &&
+                    entry.key === args.key &&
+                    entry.status !== "resolved");
+                if (item === undefined)
+                    return { items, result: undefined };
+                if (item.status === "answered" ||
+                    (item.status === "claimed" && item.claim?.conversationId === conversationId)) {
+                    const claimed = claim(item, conversationId, now());
+                    // Idempotent re-claim returns the item unchanged: keep the
+                    // original array so the store's no-write fast path applies.
+                    const next = claimed === item
+                        ? items
+                        : items.map((entry) => (entry === item ? claimed : entry));
+                    return {
+                        items: next,
+                        result: {
+                            status: "claimed",
+                            id: claimed.id,
+                            ...(claimed.answer?.option === undefined
+                                ? {}
+                                : { option: claimed.answer.option }),
+                        },
+                    };
+                }
+                return {
+                    items,
+                    result: {
+                        status: item.status,
+                        id: item.id,
+                        ...(item.answer?.option === undefined
+                            ? {}
+                            : { option: item.answer.option }),
+                    },
+                };
+            });
+            return found ?? { status: "none" };
+        },
+    };
+    const resolveHook = {
+        name: "escalation.resolve",
+        description: "Resolve an escalation claimed by the calling conversation after carrying out its answer.",
+        input: Type.Object({
+            id: Type.String({ minLength: 1 }),
+            outcome: Type.Union([Type.Literal("done"), Type.Literal("failed")]),
+            note: Type.Optional(Type.String({ maxLength: 4000, default: "" })),
+        }),
+        output: Type.Object({ status: StatusSchema }),
+        async run(payload, call) {
+            const args = payload;
+            const { bucket } = await context(deps, call, undefined);
+            const conversationId = call.conversationId;
+            // A TransitionError (wrong claimant / not claimed) propagates: the
+            // caller sees `failed` with the code as the message.
+            const item = await deps.store.update(bucket, (items) => {
+                const index = items.findIndex((candidate) => candidate.id === args.id);
+                if (index < 0)
+                    throw new TransitionError("not_found");
+                const resolved = resolve(items[index], conversationId, args.outcome, args.note ?? "", now());
+                const next = [...items];
+                next[index] = resolved;
+                return { items: next, result: resolved };
+            });
+            // Mirrors escalation_resolve: a failed claim reopens for the owner.
+            if (args.outcome === "failed")
+                await notifyReopened(deps.host, item);
+            changedInbox(deps.host, item.id);
+            return { status: item.status };
+        },
+    };
+    return [raiseHook, takeHook, resolveHook];
+}

package/dist/inbox.d.ts

@@ -8,12 +8,17 @@
  *   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
+ * - Split layout: the list is the page sidebar (tabs in the header),
+ *   the selected item (params `{tab?, id}`) fills main, and the row
+ *   being viewed carries a `Viewing` badge. An id with no tab lists the
+ *   item's own tab; on compact widths the page's selection drill-in
+ *   shows the list first.
+ * - The detail (main) is a header callout with the item's actions, the
+ *   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.
+ *   (number fields have no `default` prop), Dismiss/Withdraw/Restore and
+ *   conversation links on the header callout, and the history as a log.
  *   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

package/dist/inbox.js

@@ -8,12 +8,17 @@
  *   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
+ * - Split layout: the list is the page sidebar (tabs in the header),
+ *   the selected item (params `{tab?, id}`) fills main, and the row
+ *   being viewed carries a `Viewing` badge. An id with no tab lists the
+ *   item's own tab; on compact widths the page's selection drill-in
+ *   shows the list first.
+ * - The detail (main) is a header callout with the item's actions, the
+ *   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.
+ *   (number fields have no `default` prop), Dismiss/Withdraw/Restore and
+ *   conversation links on the header callout, and the history as a log.
  *   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
@@ -32,6 +37,16 @@ const TABS = [
     { id: "resolved", label: "Resolved" },
 ];
 const ACTIVE_STATUSES = ["answered", "claimed", "snoozed"];
+/** The tab an item of this status lists under. */
+function tabOf(status) {
+    if (status === "open")
+        return "open";
+    if (ACTIVE_STATUSES.includes(status))
+        return "active";
+    if (status === "dismissed")
+        return "dismissed";
+    return "resolved";
+}
 function isObject(payload) {
     return typeof payload === "object" && payload !== null && !Array.isArray(payload);
 }
@@ -182,6 +197,8 @@ export function createInboxView(deps) {
                 // Empty badge text is filtered by the channel, so the waiting
                 // badge shows only on rows that carry it.
                 { text: { $: "./waitingBadge" }, tone: "warn" },
+                // Marks the row whose detail fills main (split layout).
+                { text: { $: "./viewing" }, tone: "accent" },
             ],
             meta: [{ time: { $: "./updatedAt" }, format: "relative" }],
         };
@@ -205,8 +222,9 @@ export function createInboxView(deps) {
             onActivate: { type: "submit", name: "open" },
         };
     }
-    function listTree(tab, error) {
-        const main = error === undefined
+    /** The list column: the tab's collection, or the store-read error. */
+    function sidebarBlocks(tab, error) {
+        return error === undefined
             ? [collectionFor(tab)]
             : [
                 {
@@ -217,41 +235,54 @@ export function createInboxView(deps) {
                     body: error,
                 },
             ];
+    }
+    /** Main with nothing selected. */
+    function placeholderMain() {
+        return [
+            {
+                type: "markdown",
+                id: "inbox-select",
+                text: "Select an escalation from the list to read it and answer.",
+            },
+        ];
+    }
+    /** Main for an unknown id: identical for unknown and for invisible ids. */
+    function notFoundMain() {
+        return [
+            {
+                type: "callout",
+                id: "inbox-not-found-callout",
+                tone: "bad",
+                title: "Escalation not found",
+            },
+        ];
+    }
+    /**
+     * The split page: tabs in the header, the list in the sidebar, the
+     * selection (or a placeholder) in main. On compact widths the
+     * `selection` drill-in shows the list first; back returns to the tab.
+     */
+    function pageTree(tab, sidebar, main, selected) {
         return {
             v: 1,
             root: {
                 type: "page",
                 id: "inbox-root",
                 title: "Inbox",
+                subtitle: TABS.find((entry) => entry.id === tab)?.label ?? "",
                 actions: TABS.map((entry) => ({
                     id: `tab-${entry.id}`,
                     label: entry.label,
                     action: { type: "navigate", params: { tab: entry.id } },
                 })),
+                sidebar,
                 main,
+                selection: { selected, back: { tab } },
             },
         };
     }
-    /** The not-found page: identical for unknown and for invisible ids. */
-    function notFoundTree() {
-        return {
-            v: 1,
-            root: {
-                type: "page",
-                id: "inbox-not-found",
-                title: "Inbox",
-                main: [
-                    {
-                        type: "callout",
-                        id: "inbox-not-found-callout",
-                        tone: "bad",
-                        title: "Escalation not found",
-                    },
-                ],
-            },
-        };
-    }
-    function detailTree(item, jobName) {
+    /** Main for one selected item: header card with its actions, body, forms, history. */
+    function detailMain(item, jobName) {
         const orphaned = item.orphaned === true;
         const actions = [];
         if (item.status === "open" || item.status === "answered") {
@@ -303,7 +334,16 @@ export function createInboxView(deps) {
                 },
             });
         }
-        const main = [];
+        const main = [
+            {
+                type: "callout",
+                id: "inbox-item",
+                tone: "neutral",
+                title: item.title,
+                body: `${sourceLabel(item, jobName)} · ${item.status}`,
+                actions,
+            },
+        ];
         if (orphaned) {
             main.push({
                 type: "callout",
@@ -369,17 +409,7 @@ export function createInboxView(deps) {
             lines: historyLines(item),
             wrap: true,
         });
-        return {
-            v: 1,
-            root: {
-                type: "page",
-                id: "inbox-detail",
-                title: item.title,
-                subtitle: sourceLabel(item, jobName),
-                actions,
-                main,
-            },
-        };
+        return main;
     }
     /** The shared action preamble: resolve the item inside the caller's buckets. */
     async function visibleItem(ctx, payload) {
@@ -475,29 +505,33 @@ export function createInboxView(deps) {
                     access: "none",
                 };
             }
-            const id = typeof ctx.params.id === "string" ? ctx.params.id : undefined;
-            if (id !== undefined) {
-                const found = await findVisible(store, buckets, id);
-                if (found === undefined) {
-                    // Nothing here can be acted on, so the page is not writable.
-                    return { tree: notFoundTree(), data: {}, access: "none" };
-                }
-                const job = await jobOf(found.item);
-                return {
-                    tree: detailTree(found.item, job?.name),
-                    data: { answer: {}, snooze: { days: 7 } },
-                    access: "write",
-                };
-            }
+            const id = typeof ctx.params.id === "string" && ctx.params.id !== ""
+                ? ctx.params.id
+                : undefined;
+            const found = id === undefined ? undefined : await findVisible(store, buckets, id);
             const tabParam = ctx.params.tab;
+            // An id with no tab (a notice or tool link) opens the list the
+            // item lives in.
             const tab = TABS.some((entry) => entry.id === tabParam)
                 ? tabParam
-                : "open";
+                : found !== undefined
+                    ? tabOf(found.item.status)
+                    : "open";
+            let main;
+            if (id === undefined)
+                main = placeholderMain();
+            else if (found === undefined)
+                main = notFoundMain();
+            else
+                main = detailMain(found.item, (await jobOf(found.item))?.name);
+            const selected = id !== undefined;
+            const detailData = found === undefined ? {} : { answer: {}, snooze: { days: 7 } };
             try {
                 const rows = (await Promise.all(buckets.map(rowsFor))).flat();
-                const data = { items: sortForTab(rows, tab) };
+                const items = sortForTab(rows, tab).map((row) => found !== undefined && row.id === found.item.id ? { ...row, viewing: "Viewing" } : row);
+                const data = { items, ...detailData };
                 return {
-                    tree: listTree(tab),
+                    tree: pageTree(tab, sidebarBlocks(tab), main, selected),
                     // SAFETY: rows are a JSON mirror (plain literals), same cast
                     // the curator view uses for its data document.
                     data: data,
@@ -506,20 +540,27 @@ export function createInboxView(deps) {
             }
             catch (error) {
                 return {
-                    tree: listTree(tab, errorText(error)),
-                    data: { error: errorText(error) },
+                    tree: pageTree(tab, sidebarBlocks(tab, errorText(error)), main, selected),
+                    data: { error: errorText(error), ...detailData },
                     access: "write",
                 };
             }
         },
         actions: {
-            open: async (_ctx, payload) => {
+            open: async (ctx, payload) => {
                 const id = itemIdOf(payload);
                 if (id === undefined)
                     return notFound();
+                // Keep the list the row was opened from beside the selection.
+                const tab = TABS.some((entry) => entry.id === ctx.params.tab)
+                    ? ctx.params.tab
+                    : undefined;
                 return {
                     ok: true,
-                    navigate: { type: "navigate", params: { id } },
+                    navigate: {
+                        type: "navigate",
+                        params: tab === undefined ? { id } : { tab, id },
+                    },
                 };
             },
             answer: async (ctx, payload) => await actOn(ctx, payload, async ({ bucket, item }) => {

package/dist/index.js

@@ -1,5 +1,6 @@
 import { defineExtension } from "@earendil-works/pi-durable";
 import { createRunSettled } from "./dispatch.js";
+import { createPublishedHooks } from "./hooks.js";
 import { createInboxView } from "./inbox.js";
 import { escalationsSection } from "./section.js";
 import { EscalationStore } from "./store.js";
@@ -22,6 +23,7 @@ export default function createEscalations(host, options = {}) {
         }),
         jobs: [SWEEP_JOB],
         runSettled: createRunSettled(deps),
+        publishedHooks: createPublishedHooks(deps),
         surfaces: { views: [createInboxView(deps)] },
         userDeleted: async (event) => {
             const source = { kind: "user", user: event.user };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sigrun/escalations",
-	"version": "0.1.1",
+	"version": "0.2.1",
 	"description": "Escalation inbox extension for sigrun: async decisions for jobs and agents",
 	"type": "module",
 	"engines": {