opencode-courier 0.10.1 → 0.10.3

package/dist/tree/running.js

@@ -0,0 +1,58 @@
+import { millis } from "../platform/json.js";
+import { setBounded } from "../platform/bounded.js";
+import { busy, endedAt, turnEnd } from "./domain.js";
+/** How many sessions' answers each session port remembers. */
+const ANSWERS_MAX = 500;
+/** How long after its stamp an answer of rest is read again: an item enqueued then may be delivered, stamping nothing until its step. */
+const FRESH_MS = 10_000;
+/** How long an answer of rest is kept: an item waiting since a lost wake is delivered on the wake sent again, which stamps nothing. */
+const REST_MS = 30_000;
+const RUNNING = { running: true };
+const rest = (at) => (at === undefined ? { running: false } : { running: false, endedAt: at });
+/** Each session port's last answer per session, which holds until the next stamp, but for those `turnOf` drops or keeps `until`. */
+const answers = new WeakMap();
+/**
+ * Whether a session runs and, at rest, when its last turn ended: by its times when they show rest, else by its transcript
+ * (#324, #326), kept until the next stamp, a rest for `REST_MS` and not within `FRESH_MS` of it; one unread or empty runs.
+ */
+export function turnOf(session, sessionID, time, now = Date.now()) {
+    return resolve(session, sessionID, time, now, () => session.context({ sessionID }), true);
+}
+/** `turnOf` for a caller that reads the transcript itself: it answers from these `messages`, read just now, and keeps the answer. */
+export function turnIn(session, sessionID, time, messages, now = Date.now()) {
+    return resolve(session, sessionID, time, now, () => messages, false);
+}
+function resolve(session, sessionID, time, now, load, cached) {
+    if (!busy(time))
+        return Promise.resolve(rest(millis(time.idle)));
+    const known = answers.get(session) ?? new Map();
+    answers.set(session, known);
+    const stamp = `${millis(time.updated)} ${millis(time.idle)}`;
+    const found = known.get(sessionID);
+    if (cached && found?.stamp === stamp && now < found.until)
+        return found.turn;
+    // Only its own answer: a newer read of the session may have taken its place meanwhile.
+    const forget = () => {
+        if (known.get(sessionID) === answer)
+            known.delete(sessionID);
+    };
+    const turn = load().then((messages) => {
+        const end = turnEnd(messages);
+        if (!messages.length)
+            forget();
+        if (!end)
+            return RUNNING;
+        if (now - millis(time.updated) < FRESH_MS)
+            forget();
+        answer.until = now + REST_MS;
+        return rest(endedAt(end, time));
+    }, () => {
+        forget();
+        return RUNNING;
+    });
+    const answer = { stamp, turn, until: Number.POSITIVE_INFINITY };
+    known.delete(sessionID);
+    setBounded(known, sessionID, answer, ANSWERS_MAX);
+    return turn;
+}
+export const runs = (session, sessionID, time, now) => turnOf(session, sessionID, time, now).then((turn) => turn.running);

package/dist/tree/send.js

@@ -2,6 +2,7 @@ import { envelope, isStatus, STATUSES } from "../kernel/protocol.js";
 import { groupStanding, holdReport, membershipFor, unholdForBlocked } from "./group.js";
 import { childStore, groupStore } from "./store.js";
 import { reportBody } from "./text.js";
+import { noteSent } from "./wake.js";
 /**
  * Drops a message into another session's inbox; OpenCode wakes that session if it is idle. From a spawned session
  * to the one that started it, it is its report or its progress (`noteReport`); a group member's final report is held (`hold`).
@@ -17,13 +18,17 @@ export async function send(ports, from, input) {
         const held = noted?.member && status && status !== "blocked" ? await hold(ports, noted.member, { at: noted.at, status, message: input.message, ...(input.artifacts ? { artifacts: input.artifacts } : {}) }) : undefined;
         if (held)
             return { status, report: true, held };
+        const text = envelope(from, reportBody(input.message, input.artifacts), status ? { status } : {});
+        const description = `Message from ${from}`;
         const delivered = await ports.session.synthetic({
             sessionID: input.sessionID,
-            text: envelope(from, reportBody(input.message, input.artifacts), status ? { status } : {}),
-            description: `Message from ${from}`,
+            text,
+            description,
             metadata: { source: "courier", from, ...(status ? { status } : {}) },
             delivery: input.queue ? "queue" : "steer",
         });
+        // Watched now, not when OpenCode's enqueued event is handled: a spawn in the same step must count the child it wakes.
+        await noteSent(ports, { sessionID: input.sessionID, inboxID: delivered.id, text, description }).catch(() => undefined);
         // A blocked report, once delivered, is the member's latest word: an earlier report held for it would be stale.
         if (noted?.member && status === "blocked")
             await unholdForBlocked(groupStore(ports.storage), noted.member).catch(() => undefined);

package/dist/tree/status.d.ts

@@ -15,6 +15,7 @@ export declare function status(ports: CourierPorts, input: StatusInput): Promise
     outcome: "failed" | "interrupted" | "succeeded" | undefined;
     updated: number;
     idle: number | undefined;
+    archived: number | undefined;
     lastText: string | undefined;
     pending: readonly import("./ports.js").Pending[] | undefined;
 }>>;
@@ -38,6 +39,7 @@ export declare function listChildren(ports: CourierPorts, parentID: string): Pro
     outcome?: "failed" | "interrupted" | "succeeded" | undefined;
     updated?: number | undefined;
     idle?: number | undefined;
+    archived?: number | undefined;
     lastText?: string | undefined;
     pending?: readonly import("./ports.js").Pending[] | undefined;
 } | {
@@ -51,6 +53,7 @@ export declare function listChildren(ports: CourierPorts, parentID: string): Pro
     outcome?: "failed" | "interrupted" | "succeeded" | undefined;
     updated?: number | undefined;
     idle?: number | undefined;
+    archived?: number | undefined;
     lastText?: string | undefined;
     pending?: readonly import("./ports.js").Pending[] | undefined;
 } | {
@@ -88,6 +91,7 @@ export declare function described(ports: CourierPorts, entry: RosterEntry): Prom
     outcome?: "failed" | "interrupted" | "succeeded" | undefined;
     updated?: number | undefined;
     idle?: number | undefined;
+    archived?: number | undefined;
     lastText?: string | undefined;
     pending?: readonly import("./ports.js").Pending[] | undefined;
 } | {
@@ -101,6 +105,7 @@ export declare function described(ports: CourierPorts, entry: RosterEntry): Prom
     outcome?: "failed" | "interrupted" | "succeeded" | undefined;
     updated?: number | undefined;
     idle?: number | undefined;
+    archived?: number | undefined;
     lastText?: string | undefined;
     pending?: readonly import("./ports.js").Pending[] | undefined;
 } | {

package/dist/tree/status.js

@@ -17,6 +17,7 @@ export async function status(ports, input) {
         outcome: info.outcome,
         updated: info.time.updated,
         idle: info.time.idle,
+        archived: info.time.archived,
         lastText,
         pending: pending.length ? pending : undefined,
     });

package/dist/tree/subtree.d.ts

@@ -20,9 +20,12 @@ export declare function subtree(storage: RosterStorage, rootID: string, retentio
     nodes: Below[];
 }>;
 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. */
+/** A session of a tree as a read looks it up: OpenCode's info of it, if it still knows it, whether it runs, and what it waits on. */
 export interface Looked extends Below {
     readonly info: Info | undefined;
+    readonly running: boolean;
+    /** When its last turn ended, if it does not run and that is known. */
+    readonly endedAt?: number;
     readonly pending: ReadonlyArray<Pending>;
     readonly forms: ReadonlyArray<ShownForm>;
 }
@@ -70,6 +73,7 @@ export declare function tree(ports: CourierPorts, rootID: string): Promise<{
         outcome?: "failed" | "interrupted" | "succeeded" | undefined;
         updated?: number | undefined;
         idle?: number | undefined;
+        archived?: number | undefined;
         lastText?: string | undefined;
         pending?: readonly Pending[] | undefined;
     } | {
@@ -90,6 +94,7 @@ export declare function tree(ports: CourierPorts, rootID: string): Promise<{
         outcome?: "failed" | "interrupted" | "succeeded" | undefined;
         updated?: number | undefined;
         idle?: number | undefined;
+        archived?: number | undefined;
         lastText?: string | undefined;
         pending?: readonly Pending[] | undefined;
     } | {

package/dist/tree/subtree.js

@@ -1,6 +1,7 @@
-import { busy, cut, isLive } from "./domain.js";
+import { cut, isLive } from "./domain.js";
 import { lastStatus, reportOf } from "./report.js";
 import { isExpired } from "./roster.js";
+import { turnOf } from "./running.js";
 import { described } from "./status.js";
 import { childStore } from "./store.js";
 /**
@@ -42,8 +43,10 @@ export async function lookUp(ports, rootID) {
             ports.pending(node.entry.sessionID).catch(() => []),
             ports.forms(node.entry.sessionID).catch(() => []),
         ]);
+        const turn = info === undefined ? undefined : await turnOf(ports.session, node.entry.sessionID, info.time);
+        const running = turn?.running ?? false;
         // 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 : [] };
+        return { ...node, info, running, ...(turn?.endedAt !== undefined ? { endedAt: turn.endedAt } : {}), pending, forms: running ? forms : [] };
     }));
 }
 /**
@@ -54,7 +57,7 @@ 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) };
+        return { ...node, report, live: isLive(node.info ? node.running : undefined, 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 };

package/dist/tree/summary.js

@@ -1,20 +1,19 @@
-import { busy } from "./domain.js";
 import { groupStandings } from "./group.js";
 import { groupStore } from "./store.js";
 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.
+ * OpenCode no longer knows it. A message waiting in its inbox is no turn (`runs`); a stalled one reads stalled.
  */
-function activity({ info, pending, forms, entry }, stalled) {
+function activity({ info, running, pending, forms, entry }, stalled) {
     if (!info)
         return undefined;
     if (pending.length || forms.length)
         return "waiting";
     if (stalled.has(entry.sessionID))
         return "stalled";
-    return busy(info.time) ? "running" : "idle";
+    return running ? "running" : "idle";
 }
 /**
  * Every session started under a session, counted by what it is doing (the session itself too, when it is stalled), and its

package/dist/tree/tui.d.ts

@@ -4,7 +4,10 @@ import { type Accessor } from "solid-js";
 import { type MascotState, type Token } from "./mascot.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. */
+/**
+ * The events after which a summary may read differently: a turn started or ended, a request or form, a session made, removed,
+ * archived or unarchived.
+ */
 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;

package/dist/tree/wake.d.ts

@@ -39,6 +39,16 @@ export interface Execution {
  * Returns whether it is watched, which one sent with `resume: false` is not.
  */
 export declare function watchWake(ports: WatchPorts, event: Enqueued): Promise<boolean>;
+/**
+ * Watches a message `courier_send` has just had enqueued, without waiting for its enqueued event, so the limits see a reported child woken
+ * for it at once; the event leaves this row be. Dropped again if the message is already stored, delivered before it was written.
+ */
+export declare function noteSent(ports: Pick<WatchPorts, "storage" | "session" | "now">, sent: {
+    readonly sessionID: string;
+    readonly inboxID: string;
+    readonly text: string;
+    readonly description?: string;
+}): Promise<void>;
 /** 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. */
@@ -54,16 +64,24 @@ export declare function wakeEnded(ports: WatchPorts, event: Execution & {
 }): 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. */
+/** The ports the scheduler's tick wakes sessions through: what every hub-v2 member's `later` ports have, whose session is its `ctx.session`. */
 export type WakePorts = GroupPorts & {
+    readonly session: Pick<WatchPorts["session"], "get" | "context">;
     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.
+ * Sends once more, under its inbox id, each courier message an idle session has left waiting for `WAKE_MS`, flags stalled one still
+ * waiting `WAKE_MS` later, and marks running one a turn it shows will take; 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;
+/**
+ * Whether a courier message sent with a wake waits undelivered in the session's inbox while it is idle, waiting or, unless
+ * `stalled` is false, stalled; one a running turn is to take is not counted, as `runs` says that turn runs.
+ */
+export declare function waitsInInbox(ports: Pick<WatchPorts, "storage">, sessionID: string, { stalled }?: {
+    stalled?: boolean | undefined;
+}): Promise<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

@@ -1,8 +1,7 @@
+import { busy, endsIdle } from "./domain.js";
 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.
  * Returns whether it is watched, which one sent with `resume: false` is not.
@@ -16,19 +15,30 @@ export async function watchWake(ports, event) {
     if (payload.metadata.resume === false)
         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 } : {}),
-    });
+    // A row `noteSent` wrote already is kept: it may have moved on since, and is no later than this one.
+    if ((await wakeStore(ports.storage).of(sessionID)).some((wake) => wake.inboxID === inboxID))
+        return true;
+    await watch(ports, { sessionID, inboxID, at, text: payload.text, ...(typeof payload.description === "string" ? { description: payload.description } : {}) });
     return true;
 }
+/**
+ * Watches a message `courier_send` has just had enqueued, without waiting for its enqueued event, so the limits see a reported child woken
+ * for it at once; the event leaves this row be. Dropped again if the message is already stored, delivered before it was written.
+ */
+export async function noteSent(ports, sent) {
+    const store = wakeStore(ports.storage);
+    if ((await store.of(sent.sessionID)).some((wake) => wake.inboxID === sent.inboxID))
+        return;
+    await watch(ports, { ...sent, at: ports.now() });
+    const stored = await ports.session.context({ sessionID: sent.sessionID }).then((messages) => messages.some((message) => message.id === sent.inboxID), () => false);
+    if (stored)
+        await store.remove(sent.sessionID, sent.inboxID);
+}
+async function watch(ports, wake) {
+    // 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: wake.sessionID }).then(endsIdle, () => false);
+    await wakeStore(ports.storage).put({ ...wake, running: !idle, ...(idle ? { idleAt: wake.at } : {}) });
+}
 /** 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);
@@ -44,15 +54,18 @@ export async function wakeStarted(ports, event) {
  * 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));
+    const messages = await ports.session.context({ sessionID }).catch(() => []);
+    // A plain decline reports a shutdown after the aborted step that ends its turn; a real one between steps ends none. One during a
+    // step reads as ended too, until the turn the next boot resumes is seen to start or `wakeAgain` finds it running.
+    if (event.data.reason === "shutdown" && !endsIdle(messages))
+        return;
+    const stored = new Set(messages.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. */
@@ -61,8 +74,8 @@ export async function forgetWakes(ports, sessionID) {
     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.
+ * Sends once more, under its inbox id, each courier message an idle session has left waiting for `WAKE_MS`, flags stalled one still
+ * waiting `WAKE_MS` later, and marks running one a turn it shows will take; run by the scheduler's owner, `claimed` keeping a tick alongside off it.
  */
 export async function wakeMissed(ports, claimed) {
     const store = wakeStore(ports.storage);
@@ -86,6 +99,11 @@ async function wakeAgain(ports, store, wake, now) {
         const current = (await store.of(wake.sessionID)).find((one) => one.inboxID === wake.inboxID);
         if (!current || !missed(current, now))
             return;
+        // A shutdown during a step reads as an end, and the turn the next boot resumes may start unseen: that turn takes the message.
+        if (await runsNow(ports, wake.sessionID)) {
+            const { idleAt: _, ...running } = current;
+            return await store.put({ ...running, running: true });
+        }
         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 });
@@ -109,6 +127,21 @@ async function wakeAgain(ports, store, wake, now) {
         ports.log(`courier wake: could not wake ${wake.sessionID} again for ${wake.inboxID}: ${String(error)}`);
     }
 }
+/** Whether a session shows a turn running, by its times and its transcript read now; one that cannot be read does not, and is woken again. */
+async function runsNow(ports, sessionID) {
+    const info = await ports.session.get({ sessionID }).catch(() => undefined);
+    if (!info || !busy(info.time))
+        return false;
+    const messages = await ports.session.context({ sessionID }).catch(() => []);
+    return messages.length > 0 && !endsIdle(messages);
+}
+/**
+ * Whether a courier message sent with a wake waits undelivered in the session's inbox while it is idle, waiting or, unless
+ * `stalled` is false, stalled; one a running turn is to take is not counted, as `runs` says that turn runs.
+ */
+export async function waitsInInbox(ports, sessionID, { stalled = true } = {}) {
+    return (await wakeStore(ports.storage).of(sessionID)).some((wake) => !wake.running && (stalled || wake.stalled === undefined));
+}
 /** 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);