opencode-courier 0.5.0 → 0.7.0

package/dist/tree/store.d.ts

@@ -1,5 +1,5 @@
 import { type Storage } from "../platform/storage.js";
-import type { ChildStore, GroupStore } from "./ports.js";
+import type { ChildStore, GroupStore, WakeStore } from "./ports.js";
 /**
  * What the reverse index holds for a child: the sessions above it, its parent first and the top
  * session, which courier_spawn did not start, last; each is the parent of the one before it.
@@ -18,7 +18,10 @@ export declare const memberKey: (parentID: string, group: string, sessionID: str
 /** The key prefix of a parent's groups, and of one group's members. */
 export declare const groupsPrefix: (parentID: string) => string;
 export declare const groupPrefix: (parentID: string, group: string) => string;
+export declare const wakeKey: (sessionID: string, inboxID: string) => string;
 /** The `ChildStore` over the plugin's storage. */
 export declare function childStore(storage: Storage): ChildStore;
 /** The `GroupStore` over the plugin's storage. */
 export declare function groupStore(storage: Storage): GroupStore;
+/** The `WakeStore` over the plugin's storage. */
+export declare function wakeStore(storage: Storage): WakeStore;

package/dist/tree/store.js

@@ -42,6 +42,12 @@ export const memberKey = (parentID, group, sessionID) => `${GROUP_PREFIX}${paren
 /** The key prefix of a parent's groups, and of one group's members. */
 export const groupsPrefix = (parentID) => `${GROUP_PREFIX}${parentID}/`;
 export const groupPrefix = (parentID, group) => `${groupsPrefix(parentID)}${group}/`;
+/**
+ * The courier messages waiting in a session's inbox, each under `wake/<sessionID>/<inboxID>` until it is delivered, for
+ * the scheduler to wake a session whose wake was missed. docs/maintainers/architecture.md, § Storage.
+ */
+const WAKE_PREFIX = "wake/";
+export const wakeKey = (sessionID, inboxID) => `${WAKE_PREFIX}${sessionID}/${inboxID}`;
 function isReverse(value) {
     const ancestors = value?.ancestors;
     return Array.isArray(ancestors) && ancestors.length > 0 && ancestors.every((id) => typeof id === "string");
@@ -262,3 +268,48 @@ export function groupStore(storage) {
         },
     };
 }
+/** A watched message as stored under its key's session and inbox id; one that cannot be read is left out. */
+function readWake(sessionID, inboxID, value) {
+    const given = obj(value);
+    const at = num(given.at);
+    const text = str(given.text);
+    if (at === undefined || text === undefined || typeof given.running !== "boolean")
+        return undefined;
+    const optional = (field) => {
+        const time = num(given[field]);
+        return time === undefined ? {} : { [field]: time };
+    };
+    const description = str(given.description);
+    return {
+        sessionID,
+        inboxID,
+        at,
+        text,
+        ...(description !== undefined ? { description } : {}),
+        running: given.running,
+        ...optional("idleAt"),
+        ...optional("rewoken"),
+        ...optional("stalled"),
+    };
+}
+/** The `WakeStore` over the plugin's storage. */
+export function wakeStore(storage) {
+    const under = async (prefix) => {
+        const entries = await scanEntries(storage, prefix);
+        return entries.flatMap(({ key, value }) => {
+            const parts = `${prefix.slice(WAKE_PREFIX.length)}${key}`.split("/");
+            const wake = parts.length === 2 ? readWake(parts[0], parts[1], value) : undefined;
+            return wake ? [wake] : [];
+        });
+    };
+    return {
+        async put({ sessionID, inboxID, ...wake }) {
+            await storage.set(wakeKey(sessionID, inboxID), { ...wake });
+        },
+        of: (sessionID) => under(`${WAKE_PREFIX}${sessionID}/`),
+        all: () => under(WAKE_PREFIX),
+        async remove(sessionID, inboxID) {
+            await storage.remove(wakeKey(sessionID, inboxID));
+        },
+    };
+}

package/dist/tree/subtree.d.ts

@@ -1,20 +1,50 @@
-import type { CourierPorts, RosterEntry, RosterStorage } from "./ports.js";
+import type { Plugin } from "@opencode/plugin";
+import type { CourierPorts, Pending, RosterEntry, RosterStorage, ShownForm } from "./ports.js";
+import { reportOf } from "./report.js";
+import { type Exists } from "./roster.js";
 /** A session below the one a subtree is read from, with how many levels below it is: a child is at depth 1. */
 export interface Below {
     readonly entry: RosterEntry;
     readonly depth: number;
 }
+/** What a read drops: the entries past retention at `now`, as `courier_children` drops them; `exists` tells a worktree still there. */
+export interface Retention {
+    readonly now: number;
+    readonly exists?: Exists;
+}
 /**
- * The sessions started from a session, directly or through others, read one prefix scan per parent, at most `max`
- * (`truncated` if more), in the order a tree is drawn.
+ * The sessions started from a session, directly or through others, every one of them, read one prefix scan per
+ * parent, in the order a tree is drawn; with `retention`, without the expired entries and what is under them.
  */
-export declare function subtree(storage: RosterStorage, rootID: string, max?: number): Promise<{
+export declare function subtree(storage: RosterStorage, rootID: string, retention?: Retention): Promise<{
     nodes: Below[];
-    truncated: boolean;
+}>;
+type Info = Awaited<ReturnType<Plugin.Context["session"]["get"]>>;
+/** A session of a tree as a read looks it up: OpenCode's info of it, if it still knows it, and what it waits on. */
+export interface Looked extends Below {
+    readonly info: Info | undefined;
+    readonly pending: ReadonlyArray<Pending>;
+    readonly forms: ReadonlyArray<ShownForm>;
+}
+/** A session as a listing looks it up: `Looked` plus its report state, and whether it is live (`isLive`). */
+export interface Listed extends Looked {
+    readonly report: Awaited<ReturnType<typeof reportOf>>;
+    readonly live: boolean;
+}
+export type ReadPorts = Pick<CourierPorts, "storage" | "session" | "pending" | "forms" | "now" | "limits">;
+/** Every session under a session, without those past retention, each looked up, in the order a tree is drawn. */
+export declare function lookUp(ports: ReadPorts, rootID: string): Promise<Looked[]>;
+/**
+ * The listing of at most `max` of the sessions under a session: the live ones first, then the newest, with what is
+ * above them, in the order a tree is drawn (`cut`); `leftOut` counts the rest.
+ */
+export declare function readTree(ports: ReadPorts, rootID: string, max?: number): Promise<{
+    kept: Listed[];
+    leftOut: number;
 }>;
 /**
- * The subtree under a session, at most `maxTotal` sessions: what courier_children shows of each, plus its depth,
- * its parent and its report state.
+ * The subtree under a session as courier_tree lists it (`readTree`): each session as courier_children shows it, plus
+ * its depth, its parent and its report state; `truncated` counts the older sessions left out.
  */
 export declare function tree(ports: CourierPorts, rootID: string): Promise<{
     truncated?: number | undefined;
@@ -41,7 +71,7 @@ export declare function tree(ports: CourierPorts, rootID: string): Promise<{
         updated?: number | undefined;
         idle?: number | undefined;
         lastText?: string | undefined;
-        pending?: readonly import("./ports.js").Pending[] | undefined;
+        pending?: readonly Pending[] | undefined;
     } | {
         report?: {
             status?: "done" | "partial" | "blocked" | "failed" | undefined;
@@ -61,7 +91,7 @@ export declare function tree(ports: CourierPorts, rootID: string): Promise<{
         updated?: number | undefined;
         idle?: number | undefined;
         lastText?: string | undefined;
-        pending?: readonly import("./ports.js").Pending[] | undefined;
+        pending?: readonly Pending[] | undefined;
     } | {
         report?: {
             status?: "done" | "partial" | "blocked" | "failed" | undefined;
@@ -99,3 +129,4 @@ export declare function tree(ports: CourierPorts, rootID: string): Promise<{
         title: string;
     })[];
 }>;
+export {};

package/dist/tree/subtree.js

@@ -1,24 +1,23 @@
+import { busy, cut, isLive } from "./domain.js";
 import { lastStatus, reportOf } from "./report.js";
+import { isExpired } from "./roster.js";
 import { described } from "./status.js";
 import { childStore } from "./store.js";
 /**
- * The sessions started from a session, directly or through others, read one prefix scan per parent, at most `max`
- * (`truncated` if more), in the order a tree is drawn.
+ * The sessions started from a session, directly or through others, every one of them, read one prefix scan per
+ * parent, in the order a tree is drawn; with `retention`, without the expired entries and what is under them.
  */
-export async function subtree(storage, rootID, max = Number.POSITIVE_INFINITY) {
+export async function subtree(storage, rootID, retention) {
     const children = childStore(storage);
     const byParent = new Map();
     const seen = new Set([rootID]);
-    let truncated = false;
     const expand = async (level, depth) => {
-        if (!level.length || truncated)
+        if (!level.length)
             return;
         const found = await Promise.all(level.map((parentID) => children.children(parentID)));
         const next = [];
         for (const [index, entries] of found.entries()) {
-            const fresh = entries.filter((entry) => !seen.has(entry.sessionID));
-            const kept = fresh.slice(0, Math.max(0, max - (seen.size - 1)));
-            truncated ||= kept.length < fresh.length;
+            const kept = entries.filter((entry) => !seen.has(entry.sessionID) && !(retention && isExpired(entry, retention.now, retention.exists)));
             for (const entry of kept)
                 seen.add(entry.sessionID);
             if (kept.length)
@@ -28,25 +27,47 @@ export async function subtree(storage, rootID, max = Number.POSITIVE_INFINITY) {
         return expand(next, depth + 1);
     };
     await expand([rootID], 1);
-    return { nodes: drawn(byParent, rootID), truncated };
+    return { nodes: drawn(byParent, rootID) };
 }
 /** The nodes in the order a tree is drawn: each followed by what it started. */
 function drawn(byParent, parentID) {
     return (byParent.get(parentID) ?? []).flatMap((node) => [node, ...drawn(byParent, node.entry.sessionID)]);
 }
+/** Every session under a session, without those past retention, each looked up, in the order a tree is drawn. */
+export async function lookUp(ports, rootID) {
+    const { nodes } = await subtree(ports.storage, rootID, { now: ports.now() });
+    return Promise.all(nodes.map(async (node) => {
+        const [info, pending, forms] = await Promise.all([
+            ports.session.get({ sessionID: node.entry.sessionID }).catch(() => undefined),
+            ports.pending(node.entry.sessionID).catch(() => []),
+            ports.forms(node.entry.sessionID).catch(() => []),
+        ]);
+        // A form outlives its session's turn only when its withdrawal was missed, as while no instance followed the events.
+        return { ...node, info, pending, forms: info && busy(info.time) ? forms : [] };
+    }));
+}
 /**
- * The subtree under a session, at most `maxTotal` sessions: what courier_children shows of each, plus its depth,
- * its parent and its report state.
+ * The listing of at most `max` of the sessions under a session: the live ones first, then the newest, with what is
+ * above them, in the order a tree is drawn (`cut`); `leftOut` counts the rest.
+ */
+export async function readTree(ports, rootID, max = ports.limits.maxTotal) {
+    const children = childStore(ports.storage);
+    const all = await Promise.all((await lookUp(ports, rootID)).map(async (node) => {
+        const report = await reportOf(children, node.entry.sessionID).catch(() => undefined);
+        return { ...node, report, live: isLive(node.info?.time, node.pending.length + node.forms.length, report) };
+    }));
+    const listing = cut(all.map((node) => ({ sessionID: node.entry.sessionID, parentID: node.entry.parentID, createdAt: node.entry.createdAt, live: node.live, node })), max);
+    return { kept: listing.kept.map(({ node }) => node), leftOut: listing.leftOut };
+}
+/**
+ * The subtree under a session as courier_tree lists it (`readTree`): each session as courier_children shows it, plus
+ * its depth, its parent and its report state; `truncated` counts the older sessions left out.
  */
 export async function tree(ports, rootID) {
-    const { nodes, truncated } = await subtree(ports.storage, rootID, ports.limits.maxTotal);
+    const { kept, leftOut } = await readTree(ports, rootID);
     const children = childStore(ports.storage);
-    const listed = await Promise.all(nodes.map(async ({ entry, depth }) => {
-        const [info, report, last] = await Promise.all([
-            described(ports, entry),
-            reportOf(children, entry.sessionID).catch(() => undefined),
-            lastStatus(children, entry.sessionID).catch(() => undefined),
-        ]);
+    const listed = await Promise.all(kept.map(async ({ entry, depth, report }) => {
+        const [info, last] = await Promise.all([described(ports, entry), lastStatus(children, entry.sessionID).catch(() => undefined)]);
         return {
             ...info,
             parentID: entry.parentID,
@@ -56,5 +77,5 @@ export async function tree(ports, rootID) {
                 : {}),
         };
     }));
-    return { sessionID: rootID, sessions: listed, ...(truncated ? { truncated: ports.limits.maxTotal } : {}) };
+    return { sessionID: rootID, sessions: listed, ...(leftOut ? { truncated: leftOut } : {}) };
 }

package/dist/tree/summary.d.ts

@@ -1,7 +1,7 @@
 import type { CourierPorts } from "./ports.js";
 import type { Summary } from "./rpc.js";
 /**
- * The sessions started under a session, at most `maxTotal` as courier_tree reads them, counted by what they
- * are doing, and its open join groups, those of its own children, with how far each has reported.
+ * Every session started under a session, counted by what it is doing (the session itself too, when it is stalled), and its
+ * open join groups, those of its own children, with how far each has reported.
  */
 export declare function summary(ports: CourierPorts, sessionID: string): Promise<Summary>;

package/dist/tree/summary.js

@@ -1,35 +1,36 @@
 import { busy } from "./domain.js";
 import { groupStandings } from "./group.js";
 import { groupStore } from "./store.js";
-import { subtree } from "./subtree.js";
-/** What a session is doing: waiting on a request it made, running, or idle; undefined when OpenCode no longer knows it. */
-async function activity(ports, sessionID) {
-    const [info, pending] = await Promise.all([
-        ports.session.get({ sessionID }).catch(() => undefined),
-        ports.pending(sessionID).catch(() => []),
-    ]);
+import { lookUp } from "./subtree.js";
+import { stalledAmong } from "./wake.js";
+/**
+ * What a session is doing: waiting on a request it made or a form it shows, stalled, running, or idle; undefined when
+ * OpenCode no longer knows it. A message waiting in its inbox makes a stalled session look busy.
+ */
+function activity({ info, pending, forms, entry }, stalled) {
     if (!info)
         return undefined;
-    if (pending.length)
+    if (pending.length || forms.length)
         return "waiting";
+    if (stalled.has(entry.sessionID))
+        return "stalled";
     return busy(info.time) ? "running" : "idle";
 }
 /**
- * The sessions started under a session, at most `maxTotal` as courier_tree reads them, counted by what they
- * are doing, and its open join groups, those of its own children, with how far each has reported.
+ * Every session started under a session, counted by what it is doing (the session itself too, when it is stalled), and its
+ * open join groups, those of its own children, with how far each has reported.
  */
 export async function summary(ports, sessionID) {
-    const counted = async () => {
-        const { nodes, truncated } = await subtree(ports.storage, sessionID, ports.limits.maxTotal);
-        return { activities: await Promise.all(nodes.map(({ entry }) => activity(ports, entry.sessionID))), truncated };
-    };
-    const [{ activities, truncated }, standings] = await Promise.all([counted(), groupStandings(groupStore(ports.storage), sessionID)]);
+    const [looked, standings] = await Promise.all([lookUp(ports, sessionID), groupStandings(groupStore(ports.storage), sessionID)]);
+    const stalled = await stalledAmong(ports, [sessionID, ...looked.map((one) => one.entry.sessionID)]);
+    const activities = looked.map((one) => activity(one, stalled));
     const count = (kind) => activities.filter((item) => item === kind).length;
+    const stalls = count("stalled") + (stalled.has(sessionID) ? 1 : 0);
     return {
         running: count("running"),
         waiting: count("waiting"),
         idle: count("idle"),
+        ...(stalls ? { stalled: stalls } : {}),
         groups: standings.map(({ name, reported, members }) => ({ name, reported, members })),
-        ...(truncated ? { truncated: ports.limits.maxTotal } : {}),
     };
 }

package/dist/tree/text.js

@@ -160,7 +160,10 @@ export function cleanupText(result) {
 export function treeText(tree) {
     if (!tree.sessions.length)
         return "No sessions started with courier_spawn.";
-    const note = tree.truncated === undefined ? "" : `\nOnly the first ${tree.truncated} sessions are listed (maxTotal); courier_tree on one of them lists what is under it.`;
+    if (tree.truncated === undefined)
+        return JSON.stringify(tree, null, 2);
+    const older = tree.truncated === 1 ? "1 older session is" : `${tree.truncated} older sessions are`;
+    const note = `\n${older} not listed: at most maxTotal are, the live ones first, then the newest; courier_tree on a listed session lists what is under it.`;
     return JSON.stringify(tree, null, 2) + note;
 }
 /** What courier_stop did to each session, and to the messages and worktrees. */

package/dist/tree/tools.js

@@ -128,7 +128,8 @@ export function addTreeTools(tools, ports) {
         options: { codemode: false },
         description: "List the whole tree of sessions under this one (or under sessionID): every session started with courier_spawn " +
             "from it, directly or through others, each with its depth, what courier_children shows, and whether it still " +
-            "owes a report, sent progress, or ended without one. For a one-off look, not for waiting; long trees are cut at maxTotal sessions.",
+            "owes a report, sent progress, or ended without one. For a one-off look, not for waiting. A long tree lists at most " +
+            "maxTotal sessions, the live ones first, then the newest, and says how many older ones are left out.",
         input: TreeInput,
         execute: async (input, context) => {
             const result = await tree(ports.courier, input.sessionID || context.sessionID).catch(rethrow("courier_tree"));

package/dist/tree/tui.d.ts

@@ -1,6 +1,8 @@
 import type { Plugin } from "@opencode/plugin/tui";
-import { type Row, type Stopped, type Summary, type Wait } from "./rpc.js";
+import { type Forgotten, type Row, type Stopped, type Summary, type Wait } from "./rpc.js";
 type Context = Plugin.Context;
+/** The events after which a summary may read differently: a turn started or ended, a request or form, a session made or removed. */
+export declare const CHANGES: Set<string>;
 /** How long after the first of a burst of changes the entry asks the server again. */
 export declare const SETTLE_MS = 250;
 /** The panel's settle: each of its asks reads every row's messages, so a busy tree is asked at most once a second. */
@@ -9,8 +11,11 @@ export declare const PANEL_SETTLE_MS = 1000;
 export declare const PANEL = "courier-tree";
 /** How often the panel redraws its running times and how long ago each last tool call was. */
 export declare const TICK_MS = 1000;
-/** The status entry's text, such as "courier 2 running · 1 waiting on you · group pair 1/2"; empty when there is nothing to show. */
-export declare function summaryLine(summary: Summary): string;
+/**
+ * The status entry's text, such as "courier 1 waiting on you · 2 running · group pair 1/2"; empty when there is nothing to show.
+ * Within `maxWidth` it keeps whole parts, most important first, and counts the groups it drops: "· +2 groups".
+ */
+export declare function summaryLine(summary: Summary, maxWidth?: number): string;
 /** A span of time, coarsest first: "45s", "3m 05s", "2h 07m". */
 export declare function duration(ms: number): string;
 /** How many of a session's children have reported, out of those it started, among the rows read. */
@@ -23,21 +28,27 @@ export declare function bar({ reported, started }: {
     reported: number;
     started: number;
 }, width?: number): string;
-/** What a paused session waits on, such as "asks permission: shell echo hi". */
+/** What a paused session waits on, such as "asks permission: shell echo hi" or "shows a form: Web Search". */
 export declare function waitLine(wait: Wait): string;
 /** What a row's session is doing, its report and its group standing: "idle · reported done · group pair held". */
 export declare function statusLine(row: Row): string;
 /** A leaf's activity: how long it has run, its last tool call and how long ago, and its cost. */
 export declare function activityLine(row: Row, now: number): string;
-/** The lines a row shows under its title: an orchestrator's bar, a paused session's requests, or else a live leaf's activity. */
+/** What a stalled session's row, or the panel of one, says of it: "a message waits in its inbox since 2m 05s, woken again in vain". */
+export declare function stalledLine(since: number, now: number): string;
+/** The lines a row shows under its title: an orchestrator's bar, a paused or stalled session's wait, or else a live leaf's activity. */
 export declare function detailLines(row: Row, rows: ReadonlyArray<Row>, now: number): string[];
+/** How often the footer and the panel ask again with no event: the scheduler flags a stalled session without one. */
+export declare const REREAD_MS = 15000;
 /**
  * Adds the tree's entry to the prompt's footer: what the sessions under the open session do, asked of the RPC after each
- * change; nothing on the home screen. Clicked while some wait on the person, it calls `onWaiting` with the open session.
+ * change and every `REREAD_MS`; nothing on the home screen. Clicked while some wait on the person, it calls `onWaiting`.
  */
 export declare function addTreeStatus(ctx: Context, onWaiting?: (sessionID: string) => void): () => void;
 /** The toast after a stop: how many sessions were interrupted, and how many scheduled messages were cancelled. */
 export declare function stoppedLine({ stopped, cancelled }: Stopped): string;
+/** The toast after a forget, as courier_cleanup reports it: forgotten, its worktree removed or already gone, or kept and why. */
+export declare function forgottenLine(title: string, result: Forgotten): string;
 /** The usage the `/courier` command shows for an input it does not know. */
 export declare const USAGE = "/courier tree opens the session tree; /courier stop [session] stops a session and those under it";
 /**

package/dist/tree/wake.d.ts

@@ -0,0 +1,68 @@
+import type { GroupPorts, Wake, WatchPorts } from "./ports.js";
+/** How long a courier message may wait in an idle session's inbox before its wake counts as missed. */
+export declare const WAKE_MS = 30000;
+/** OpenCode's `session.inbox.enqueued`, with the item's payload, which carries the courier's metadata. */
+export interface Enqueued {
+    readonly created?: number;
+    readonly data: {
+        readonly sessionID: string;
+        readonly inboxID: string;
+        readonly item: {
+            readonly type: string;
+            readonly payload?: {
+                readonly text?: unknown;
+                readonly description?: unknown;
+                readonly metadata?: {
+                    readonly source?: unknown;
+                };
+            };
+        };
+    };
+}
+/** OpenCode's `session.inbox.delivered` and `session.inbox.cancelled`. */
+export interface InboxSettled {
+    readonly data: {
+        readonly sessionID: string;
+        readonly inboxID: string;
+    };
+}
+/** OpenCode's `session.execution.*` events, which frame a session's busy period. */
+export interface Execution {
+    readonly created?: number;
+    readonly data: {
+        readonly sessionID: string;
+    };
+}
+/**
+ * Watches a courier message enqueued for a session until it is delivered, noting whether the session runs: a running
+ * turn takes it at its next step, an idle session is woken for it. Returns whether it is watched.
+ */
+export declare function watchWake(ports: WatchPorts, event: Enqueued): Promise<boolean>;
+/** Stops watching a message once it is delivered or cancelled. */
+export declare function settleWake(ports: Pick<WatchPorts, "storage">, event: InboxSettled): Promise<void>;
+/** A turn started in a session: the messages waiting there are its to take. */
+export declare function wakeStarted(ports: Pick<WatchPorts, "storage">, event: Execution): Promise<void>;
+/**
+ * A session's turn ended: a message it took is no longer watched, as its delivery may have been missed by this
+ * subscription; one still waiting is watched as waiting in an idle session from now.
+ */
+export declare function wakeEnded(ports: WatchPorts, event: Execution & {
+    readonly data: {
+        readonly reason?: string;
+    };
+}): Promise<void>;
+/** Forgets the messages watched in a session's inbox: it was deleted, or stopped, which nothing is to wake again. */
+export declare function forgetWakes(ports: Pick<WatchPorts, "storage">, sessionID: string): Promise<void>;
+/** The ports the scheduler's tick wakes sessions through: what every hub member's `later` ports have. */
+export type WakePorts = GroupPorts & {
+    readonly now: () => number;
+};
+/**
+ * Sends once more, under its inbox id, each courier message an idle session has left waiting for `WAKE_MS`, and flags
+ * stalled one still waiting `WAKE_MS` later; run by the scheduler's owner, `claimed` keeping a tick alongside off it.
+ */
+export declare function wakeMissed(ports: WakePorts, claimed: Set<string>): Promise<void>;
+/** Whether a message has waited in an idle session past `WAKE_MS`, and since a wake again, if one was sent; a stalled one is done. */
+export declare function missed(wake: Wake, now: number): boolean;
+/** The sessions among `sessionIDs` flagged stalled, each with when its oldest stalled message was enqueued. */
+export declare function stalledAmong(ports: Pick<WatchPorts, "storage">, sessionIDs: ReadonlyArray<string>): Promise<Map<string, number>>;

package/dist/tree/wake.js

@@ -0,0 +1,119 @@
+import { wakeStore } from "./store.js";
+/** How long a courier message may wait in an idle session's inbox before its wake counts as missed. */
+export const WAKE_MS = 30_000;
+/** Whether a session's stored messages end with the marker of an ended turn; one with none yet is taken to run. */
+const endsIdle = (messages) => messages.at(-1)?.type === "idle";
+/**
+ * Watches a courier message enqueued for a session until it is delivered, noting whether the session runs: a running
+ * turn takes it at its next step, an idle session is woken for it. Returns whether it is watched.
+ */
+export async function watchWake(ports, event) {
+    const { sessionID, inboxID, item } = event.data;
+    const payload = item.payload;
+    if (item.type !== "synthetic" || payload?.metadata?.source !== "courier" || typeof payload.text !== "string")
+        return false;
+    const at = event.created ?? ports.now();
+    // Read after the enqueue: a turn it started has stored messages since, and an unknown session is taken to run.
+    const idle = await ports.session.context({ sessionID }).then(endsIdle, () => false);
+    await wakeStore(ports.storage).put({
+        sessionID,
+        inboxID,
+        at,
+        text: payload.text,
+        ...(typeof payload.description === "string" ? { description: payload.description } : {}),
+        running: !idle,
+        ...(idle ? { idleAt: at } : {}),
+    });
+    return true;
+}
+/** Stops watching a message once it is delivered or cancelled. */
+export async function settleWake(ports, event) {
+    await wakeStore(ports.storage).remove(event.data.sessionID, event.data.inboxID);
+}
+/** A turn started in a session: the messages waiting there are its to take. */
+export async function wakeStarted(ports, event) {
+    const store = wakeStore(ports.storage);
+    const waiting = await store.of(event.data.sessionID);
+    await Promise.all(waiting.filter((wake) => !wake.running).map(({ idleAt: _, ...wake }) => store.put({ ...wake, running: true })));
+}
+/**
+ * A session's turn ended: a message it took is no longer watched, as its delivery may have been missed by this
+ * subscription; one still waiting is watched as waiting in an idle session from now.
+ */
+export async function wakeEnded(ports, event) {
+    if (event.data.reason === "shutdown")
+        return;
+    const { sessionID } = event.data;
+    const store = wakeStore(ports.storage);
+    const waiting = await store.of(sessionID);
+    if (!waiting.length)
+        return;
+    const at = event.created ?? ports.now();
+    const stored = new Set((await ports.session.context({ sessionID }).catch(() => [])).map((message) => message.id));
+    await Promise.all(waiting.map((wake) => (stored.has(wake.inboxID) ? store.remove(sessionID, wake.inboxID) : store.put({ ...wake, running: false, idleAt: at }))));
+}
+/** Forgets the messages watched in a session's inbox: it was deleted, or stopped, which nothing is to wake again. */
+export async function forgetWakes(ports, sessionID) {
+    const store = wakeStore(ports.storage);
+    await Promise.all((await store.of(sessionID)).map((wake) => store.remove(sessionID, wake.inboxID)));
+}
+/**
+ * Sends once more, under its inbox id, each courier message an idle session has left waiting for `WAKE_MS`, and flags
+ * stalled one still waiting `WAKE_MS` later; run by the scheduler's owner, `claimed` keeping a tick alongside off it.
+ */
+export async function wakeMissed(ports, claimed) {
+    const store = wakeStore(ports.storage);
+    const now = ports.now();
+    const due = (await store.all()).filter((wake) => missed(wake, now) && !claimed.has(claimOf(wake)));
+    for (const wake of due)
+        claimed.add(claimOf(wake));
+    await Promise.all(due.map((wake) => wakeAgain(ports, store, wake, now).finally(() => claimed.delete(claimOf(wake)))));
+}
+const claimOf = (wake) => `wake ${wake.sessionID} ${wake.inboxID}`;
+/** Whether a message has waited in an idle session past `WAKE_MS`, and since a wake again, if one was sent; a stalled one is done. */
+export function missed(wake, now) {
+    if (wake.running || wake.stalled !== undefined)
+        return false;
+    const since = Math.max(wake.idleAt ?? wake.at, wake.rewoken ?? 0);
+    return now - since >= WAKE_MS;
+}
+async function wakeAgain(ports, store, wake, now) {
+    try {
+        // Re-read: the message may have been delivered, or the session woken, since the scan.
+        const current = (await store.of(wake.sessionID)).find((one) => one.inboxID === wake.inboxID);
+        if (!current || !missed(current, now))
+            return;
+        if (current.rewoken !== undefined) {
+            ports.log(`courier wake: ${wake.sessionID} has not taken message ${wake.inboxID} since it was woken again; flagged stalled`);
+            return await store.put({ ...current, stalled: now });
+        }
+        // Noted before the send: the turn it starts may take the message, and drop the watch, before the send returns.
+        await store.put({ ...current, rewoken: now });
+        await ports.session.synthetic({
+            sessionID: wake.sessionID,
+            id: wake.inboxID,
+            text: wake.text,
+            ...(wake.description !== undefined ? { description: wake.description } : {}),
+            metadata: { source: "courier", wake: "again" },
+            delivery: "steer",
+        }).catch(async (error) => {
+            await store.put(current);
+            throw error;
+        });
+        ports.log(`courier wake: ${wake.sessionID} left message ${wake.inboxID} waiting while idle; woken again`);
+    }
+    catch (error) {
+        ports.log(`courier wake: could not wake ${wake.sessionID} again for ${wake.inboxID}: ${String(error)}`);
+    }
+}
+/** The sessions among `sessionIDs` flagged stalled, each with when its oldest stalled message was enqueued. */
+export async function stalledAmong(ports, sessionIDs) {
+    const wanted = new Set(sessionIDs);
+    const stalled = new Map();
+    for (const wake of await wakeStore(ports.storage).all()) {
+        if (wake.stalled === undefined || !wanted.has(wake.sessionID))
+            continue;
+        stalled.set(wake.sessionID, Math.min(stalled.get(wake.sessionID) ?? wake.at, wake.at));
+    }
+    return stalled;
+}