opencode-courier 0.13.8 → 0.15.0

package/dist/tree/panel.js

@@ -4,7 +4,6 @@ import { standingIn } from "./status.js";
 import { childStore } from "./store.js";
 import { readTop, readTree } from "./subtree.js";
 import { stalledAmong } from "./wake.js";
-/** The last tool call in a session's messages, and when it was made. */
 export function lastTool(messages) {
     for (const message of messages.toReversed()) {
         if (message.type !== "assistant")
@@ -15,7 +14,7 @@ export function lastTool(messages) {
     }
     return undefined;
 }
-/** How full a session's context is, as OpenCode's session view reads it (packages/tui/src/util/session.ts, v2.1.0): the last usage since the last compaction over its model's window. */
+// as OpenCode's session view reads it (packages/tui/src/util/session.ts)
 export function contextOf(messages, windows) {
     const compacted = messages.findLastIndex((message) => message.type === "compaction" && message.status === "completed");
     const last = messages.findLast((message, index) => index > compacted && message.type === "assistant" && message.tokens !== undefined);
@@ -26,13 +25,10 @@ export function contextOf(messages, windows) {
     const window = windows.find((model) => model.providerID === last.model.providerID && model.id === last.model.id)?.context;
     return used > 0 && window ? used / window : undefined;
 }
-/** A request as the panel says what a paused session waits on: a permission request, or its first question. */
 export const waitOf = (pending) => pending.type === "permission"
     ? { type: "permission", action: pending.action, resources: [...pending.resources] }
     : { type: "question", question: pending.questions[0]?.question ?? "" };
-/** A form a session shows, as the panel says what it waits on. */
 export const formWait = (form) => ({ type: "form", title: form.title });
-/** A session's report since its last prompt, as the panel shows it; none for one spawned before this was kept. */
 function reportRow(report, status) {
     if (!report)
         return {};
@@ -42,10 +38,6 @@ function reportRow(report, status) {
         return { report: { state: "ended", progressed: report.progressed } };
     return { report: { state: "reported", progressed: report.progressed, ...(status ? { status } : {}) } };
 }
-/**
- * What a session does: waiting on a request to the person or a form it shows them, stalled, running, idle, or gone when
- * OpenCode no longer knows it. A message waiting in its inbox is no turn (`runs`); a stalled one reads stalled.
- */
 function stateOf(info, waits, stalled, running) {
     if (!info)
         return "gone";
@@ -55,8 +47,7 @@ function stateOf(info, waits, stalled, running) {
         return "stalled";
     return running ? "running" : "idle";
 }
-/** One session of the panel: what it is doing, its report and group standing, its last tool call, context use and cost. */
-async function row(ports, windows, { entry, depth, info, running, endedAt, pending, forms, report }, stalled) {
+async function row(ports, windows, { entry, depth, subagent, info, running, endedAt, pending, forms, report }, stalled) {
     const { sessionID } = entry;
     const [messages, status, standing, stopped] = await Promise.all([
         ports.session.context({ sessionID }).catch(() => []),
@@ -67,7 +58,6 @@ async function row(ports, windows, { entry, depth, info, running, endedAt, pendi
     const tool = lastTool(messages);
     const context = contextOf(messages, windows);
     const state = stateOf(info, pending.length + forms.length, stalled !== undefined, running);
-    // A prompt since the failure drops it from the report, so `resumesAt` here is that of the last turn alone.
     const resumes = state === "idle" && !stopped && report?.resumesAt !== undefined && report.resumesAt > ports.now() ? report.resumesAt : undefined;
     return {
         sessionID,
@@ -82,6 +72,7 @@ async function row(ports, windows, { entry, depth, info, running, endedAt, pendi
         ...reportRow(report, status),
         ...(entry.group && standing ? { group: { name: entry.group, standing } } : {}),
         ...startedAs(entry),
+        ...(subagent ? { subagent } : {}),
         created: info?.time.created ?? entry.createdAt,
         ...(info && !running && endedAt !== undefined ? { idle: endedAt } : {}),
         ...(info ? { cost: info.cost } : {}),
@@ -90,10 +81,6 @@ async function row(ports, windows, { entry, depth, info, running, endedAt, pendi
         waits: [...pending.map(waitOf), ...forms.map(formWait)],
     };
 }
-/**
- * The tree panel's rows: the sessions under a session as courier_tree lists them, at most `maxTotal`, live ones first,
- * then the newest, each as `row` reads it; `top` the session itself, `truncated` the ones left out, `stalled` its stall.
- */
 export async function panel(ports, rootID) {
     const [{ kept, leftOut }, root] = await Promise.all([readTree(ports, rootID), readTop(ports, rootID)]);
     const stalled = await stalledAmong(ports, [rootID, ...kept.map((node) => node.entry.sessionID)]);

package/dist/tree/ports.d.ts

@@ -1,7 +1,3 @@
-/**
- * The tree's ports, what it needs of the plugin context and of other modules, and the data types they and
- * its texts take; those its pure rules take are declared in `domain.ts` and re-exported here.
- */
 import type { Plugin } from "@opencode/plugin";
 import type { Status } from "../kernel/protocol.js";
 import type { Storage } from "../platform/storage.js";
@@ -9,236 +5,143 @@ import type { Limits, Member, ModelRef, RosterEntry } from "./domain.js";
 export type { Artifacts, HeldReport, LeftMember, Limits, Member, ModelRef, RosterEntry, Standing } from "./domain.js";
 type Context = Plugin.Context;
 export type RosterStorage = Storage;
-/** How a session's wait for a report ended: it reported to its parent, or its turn failed or was interrupted. */
 export type Settled = "report" | "failed" | "interrupted";
-/** The notes kept of a spawned session's report state; docs/maintainers/architecture.md has each. */
 export type ReportField = "prompt" | "settled" | "progress" | "told" | "stopped" | "nudged";
-/** A report note as read: when it was made, and for `settled` how the wait ended, the report's status or a failure's `resumesAt`, as stored. */
 export interface ReportNote {
     readonly at: number | undefined;
     readonly by: unknown;
     readonly status: unknown;
     readonly resumesAt: unknown;
 }
-/** A stored value, as `Storage` gives and takes it. */
 export type Stored = Parameters<Storage["set"]>[1];
-/** The report keys found, by the session they are about. */
 export type ReportKeys = ReadonlyMap<string, ReadonlyArray<string>>;
-/**
- * A spawned session as kept: its roster entry under its parent, the reverse index that finds it, and its report
- * state, which go together. The reverse index is only an index: a session it does not name is looked for in the roster.
- */
 export interface ChildStore {
-    /** Records a child under its parent, then indexes it; a failed index write is left to a scan and the next load. */
     record(entry: RosterEntry): Promise<void>;
-    /** Removes a child's entry and, at once and best effort, its reverse key and report state; only the entry's removal can fail it. */
     remove(parentID: string, sessionID: string): Promise<void>;
-    /** A session's roster entry under a parent, if it is there. */
     entry(parentID: string, sessionID: string): Promise<RosterEntry | undefined>;
-    /** A parent's children, oldest first. */
     children(parentID: string): Promise<RosterEntry[]>;
-    /** Every parent's children. */
     all(): Promise<RosterEntry[]>;
-    /** A session's roster entries: one for the parent that started it, none if courier_spawn did not. */
     entriesOf(sessionID: string): Promise<RosterEntry[]>;
-    /** The session that started a session, by the reverse index alone, without scanning the roster. */
     indexedParent(sessionID: string): Promise<string | undefined>;
-    /** The sessions above a session, its parent first, by the reverse index alone: empty when it does not name the session. */
     indexedAncestors(sessionID: string): Promise<ReadonlyArray<string>>;
-    /** A session's roster entry, by the reverse index alone, without scanning the roster. */
     indexedEntry(sessionID: string): Promise<RosterEntry | undefined>;
-    /**
-     * The roster entries from a session up to the top, its own first, ending with the entry whose parent
-     * courier_spawn did not start; empty when courier_spawn did not start the session.
-     */
     lineage(sessionID: string): Promise<RosterEntry[]>;
-    /** `lineage` by the reverse index alone: empty, without scanning the roster, when it does not name the session. */
     indexedLineage(sessionID: string): Promise<RosterEntry[]>;
-    /** Writes the reverse keys missing or stale for the given entries, the whole roster, and drops those whose entry is gone. */
     backfill(entries: ReadonlyArray<RosterEntry>): Promise<void>;
-    /** The given notes of a session's report state, read at once. */
     notes<F extends ReportField>(sessionID: string, fields: ReadonlyArray<F>): Promise<{
         readonly [K in F]: ReportNote;
     }>;
-    /** Notes that a prompt or message reached a spawned session at `at`, unless a later one is noted. */
     prompted(sessionID: string, at: number): Promise<void>;
-    /**
-     * Notes how a spawned session's wait for a report ended at `at`, with its report's status or, for a failed turn, when the
-     * provider's limit lifts (`resumesAt`), unless a later end is noted.
-     */
     settled(sessionID: string, by: Settled, at: number, status?: Status, resumesAt?: number): Promise<void>;
-    /** Notes that a spawned session messaged its parent without a status at `at`, unless a later one is noted. */
     progressed(sessionID: string, at: number): Promise<void>;
-    /** Notes that a spawned session's parent was told at `at` that a turn ended without a report, unless a later telling is noted. */
     told(sessionID: string, at: number): Promise<void>;
-    /** Takes back the note `told` made at `at`; a later one stays, and one that cannot be read goes. */
     untold(sessionID: string, at: number): Promise<void>;
-    /** Notes that courier_stop stopped a spawned session at `at`. */
     stopped(sessionID: string, at: number): Promise<void>;
-    /** Notes that a spawned session was reminded at `at` to report, with the reminder's inbox id once it is admitted. */
     nudged(sessionID: string, at: number, inboxID?: string): Promise<void>;
-    /** When a spawned session was last reminded to report, and the reminder's inbox id. */
     nudgeOf(sessionID: string): Promise<{
         readonly at: number | undefined;
         readonly inboxID?: string;
     }>;
-    /** A `settled` or `progress` note as stored, for `restore` to put back. */
     peek(sessionID: string, field: "settled" | "progress"): Promise<Stored | undefined>;
-    /** Puts back a note `peek` read; one that was not there is removed. */
     restore(sessionID: string, field: "settled" | "progress", value: Stored | undefined): Promise<void>;
-    /** Drops a session's report state. */
     forgetReport(sessionID: string): Promise<void>;
-    /** Every report key, by the session it is about. */
     reported(): Promise<ReportKeys>;
-    /** Removes report keys `reported` found, each best effort. */
     dropReported(keys: ReadonlyArray<string>): Promise<void>;
 }
-/**
- * A courier message waiting in a session's inbox, watched until it is delivered: `running` while the session runs a
- * turn, which takes it at its next step; `idleAt` since the session was last seen idle with it waiting.
- */
 export interface Wake {
     readonly sessionID: string;
     readonly inboxID: string;
-    /** When OpenCode enqueued it. */
     readonly at: number;
-    /** Its text and description, which waking the session again sends under the same inbox id. */
     readonly text: string;
     readonly description?: string;
     readonly running: boolean;
     readonly idleAt?: number;
-    /** When the scheduler woke the session again, the message still waiting. */
     readonly rewoken?: number;
-    /** When the session was found still not woken after that: it is stalled. */
     readonly stalled?: number;
 }
 export interface WakeStore {
-    /** Writes a watched message, replacing what was kept of it. */
     put(wake: Wake): Promise<void>;
-    /** The messages watched in a session's inbox. */
     of(sessionID: string): Promise<Wake[]>;
-    /** Every message watched. */
     all(): Promise<Wake[]>;
-    /** Stops watching a message: delivered, cancelled, or its session gone. */
     remove(sessionID: string, inboxID: string): Promise<void>;
 }
-/** A member of a join group with where it is kept. */
 export interface Membership extends Member {
     readonly parentID: string;
     readonly group: string;
     readonly sessionID: string;
 }
-/** The members of parents' join groups, each with its held report or how it left; a value that is not a member reads as none. */
 export interface GroupStore {
-    /** A session's member in a parent's group, if it is one. */
     member(parentID: string, group: string, sessionID: string): Promise<Member | undefined>;
-    /** The members of every group. */
     all(): Promise<Membership[]>;
-    /** The members of a parent's groups. */
     ofParent(parentID: string): Promise<Membership[]>;
-    /** The members of one group. */
     ofGroup(parentID: string, group: string): Promise<Membership[]>;
-    /** Writes a member in place of what was kept for it. */
     put(parentID: string, group: string, sessionID: string, member: Member): Promise<void>;
-    /** Removes a member whatever it holds. */
     remove(parentID: string, group: string, sessionID: string): Promise<void>;
 }
-/** A report held with its group: which group, and how many of its members have reported so far, when that could be read. */
 export interface Held {
     readonly group: string;
     readonly reported?: number;
     readonly members?: number;
 }
-/**
- * What courier_send did; `report` says whether the message was noted as the sender's report to the session
- * that started it, and `held` that it was held with the sender's group rather than delivered, with no `messageID`.
- */
 export interface Sent {
     readonly messageID?: string;
     readonly status?: Status;
     readonly report?: boolean;
     readonly held?: Held;
-    /** The status it was sent with to a session below the sender, where a status means nothing. */
     readonly dropped?: Status;
 }
-/**
- * What the `context` hook remembers of a session: its depth, null for one nobody spawned that has started none, and
- * whether it carries the role entry (`ROLE_KEY`), which then names its role in place of the hook's system part.
- */
 export interface Role {
     readonly depth: number | null;
     readonly entry: boolean;
+    readonly subagent?: true;
 }
-/** The keyed session entries, missing on a host before 2.2.0 (every copy's ports carry the host's `session`): an entry is then skipped. */
 export type Instructions = Partial<Pick<Context["session"], "instructions">>;
-/** A keyed session instruction entry: its key, `^[a-z0-9][a-z0-9._-]*$`, and its text. */
+export type Lister = Partial<Pick<Context["session"], "list">>;
 export interface Entry {
     readonly key: string;
     readonly value: string;
 }
-/**
- * Supplies the entries other modules write to a spawned session below `maxDepth` before its prompt, and to a root at its
- * first spawn beside its role; `src/index.ts` composes it from the modules' suppliers, as it does the `Waits` port.
- */
 export type Entries = () => Promise<ReadonlyArray<Entry>>;
-/** What writing a parent's `standing` entry needs: the tools', the watcher's and the scheduler's ports all have these. */
 export interface StandingPorts {
     readonly storage: RosterStorage;
     readonly now: () => number;
     readonly session?: Instructions;
     readonly log?: (message: string) => void;
 }
-/** The slice of the plugin context the courier tools use; tests pass a fake. */
 export interface CourierPorts {
-    /** `instructions`, the keyed session entries, is missing on a host before 2.2.0: the role then goes in a system part. */
-    readonly session: Pick<Context["session"], "create" | "prompt" | "synthetic" | "get" | "context" | "interrupt"> & Instructions;
-    /** The entries of other modules a spawned session gets before its prompt, the memory's lessons; none when not given. */
+    readonly session: Pick<Context["session"], "create" | "prompt" | "synthetic" | "get" | "context" | "interrupt"> & Instructions & Lister;
     readonly entries?: Entries;
     readonly agent: Pick<Context["agent"], "get">;
     readonly worktree: Pick<Context["worktree"], "create" | "remove">;
-    /** The project of the plugin's location; an isolated child's worktree is made in it, and removed from it. */
     readonly projectID: string;
-    /** The commit a directory's checkout is on, or undefined; recorded as an isolated child's base. */
     readonly head: (directory: string) => Promise<string | undefined>;
-    /** Whether a directory's checkout has uncommitted changes, or undefined when git cannot tell. */
     readonly dirty: (directory: string) => Promise<boolean | undefined>;
     readonly storage: RosterStorage;
     readonly directory: string;
     readonly now: () => number;
-    /** The permission requests and questions a session waits on, wherever they are pending. */
     readonly pending: (sessionID: string) => Promise<ReadonlyArray<Pending>>;
-    /** The forms a session shows, which only the person can answer: web search's, a plugin's; not the question tool's. */
     readonly forms: (sessionID: string) => Promise<ReadonlyArray<ShownForm>>;
-    /** The models available, each with its context window and variants, as courier_spawn checks a choice and the panel reads a session's context use. */
     readonly models: () => Promise<ReadonlyArray<KnownModel>>;
-    /** OpenCode's default model here, which a session with no model of its own runs on; undefined when there is none. */
     readonly defaultModel: () => Promise<ModelRef | undefined>;
     readonly limits: Limits;
-    /** The `nativeChildren` option: a child started without isolate and without `native` is created with OpenCode's own `parentID`. */
     readonly nativeChildren?: boolean;
     readonly gate: SpawnGate;
-    /** The roles the `context` hook remembers; a parent's is dropped when it starts a child, a root's kept once its entry is written. */
     readonly roles: Map<string, Role>;
-    /** Has the scheduler deliver what is due now rather than at its next tick: a group a report has just completed. */
     readonly nudge: () => void;
     readonly log: (message: string) => void;
 }
-/** A model's context window in tokens, as the panel and the memory read a session's context use by. */
 export interface ModelWindow {
     readonly providerID: string;
     readonly id: string;
     readonly context: number;
 }
-/** A model OpenCode lists, as `CourierPorts.models` gives it: its window, and the ids of its variants. */
 export interface KnownModel extends ModelWindow {
     readonly variants: ReadonlyArray<string>;
 }
-/** A form a session shows, as `CourierPorts.forms` lists it; `person/` keeps them. */
 export interface ShownForm {
     readonly id: string;
     readonly title: string;
 }
-/** One question a session waits on, as `Pending` shows it; `person/`'s `Prompt` has these fields. */
 export interface PendingPrompt {
     readonly question: string;
     readonly header: string;
@@ -248,7 +151,6 @@ export interface PendingPrompt {
     }>;
     readonly multiple?: boolean;
 }
-/** A request a session waits on until someone answers it: a permission request, or a question it asked. */
 export type Pending = {
     readonly type: "permission";
     readonly requestID: string;
@@ -259,19 +161,13 @@ export type Pending = {
     readonly type: "question";
     readonly requestID: string;
     readonly questions: ReadonlyArray<PendingPrompt>;
-    /** Its question call was cut off; the answer reaches it as a message. */
     readonly stopped?: true;
 };
-/** A spawn past its limit check: its parent, the top of its tree, and its child once created. */
 export interface Reservation {
     readonly parentID: string;
     readonly top: string;
     sessionID?: string;
 }
-/**
- * The spawns under way in the process, under a fixed process-wide key outside the hub, so spawns in
- * other locations and copies count them; `turn` runs the limit checks one at a time.
- */
 export interface SpawnGate {
     readonly reserved: Set<Reservation>;
     turn: Promise<unknown>;
@@ -282,7 +178,6 @@ export interface LimitPorts {
     readonly limits: Limits;
     readonly gate: SpawnGate;
 }
-/** What courier_cleanup did: removed the worktree, found it gone, kept it and why, or forgot a child with none; `group`, one it dropped the child from. */
 export type CleanupResult = {
     readonly sessionID: string;
     readonly directory: string;
@@ -296,86 +191,57 @@ export type CleanupResult = {
     readonly changes: readonly string[];
     readonly commits: readonly string[];
 };
-/** What would be lost by removing a worktree. */
 export interface WorktreeState {
-    /** Paths with uncommitted changes, untracked files included, as `git status --porcelain` lists them. */
     readonly changes: readonly string[];
-    /**
-     * Commits reachable from the worktree's HEAD but from no branch, tag or remote-tracking ref, nor
-     * from the commit the worktree was made from, newest first.
-     */
     readonly commits: readonly string[];
 }
 export interface CleanupPorts {
     readonly storage: RosterStorage;
     readonly worktree: Pick<Context["worktree"], "remove">;
-    /** The project of the plugin's location, for roster entries recorded before they carried their project. */
     readonly projectID: string;
-    /** The worktree's state, or undefined when its directory no longer exists; `base` is the commit it was made from. */
     readonly inspect: (directory: string, base?: string) => Promise<WorktreeState | undefined>;
-    /** When a member still out is dropped from its group. */
     readonly now: () => number;
-    /** Has the scheduler deliver what is due now: a group the forgotten child may have been the last member out of. */
     readonly nudge: () => void;
-    /** For the parent's `standing` entry once the child is forgotten; without them it is left as it was. */
     readonly session?: Instructions;
     readonly log?: (message: string) => void;
 }
 export interface StopPorts {
     readonly courier: CourierPorts;
-    /** Cancels the messages scheduled for a session; the ids of those cancelled. */
     readonly cancelScheduled: (sessionID: string) => Promise<ReadonlyArray<string>>;
     readonly cleanup: CleanupPorts;
 }
 export interface GroupPorts {
     readonly storage: Storage;
-    readonly session: Pick<Context["session"], "synthetic" | "get"> & Instructions;
+    readonly session: Pick<Context["session"], "synthetic" | "get" | "context"> & Instructions;
     readonly now: () => number;
     readonly log: (message: string) => void;
 }
-/** The error of OpenCode's `session.execution.failed` event. */
 export interface ExecutionError {
     readonly type: string;
     readonly message: string;
     readonly status?: number;
-    /** How long the provider asked to wait before trying again, counted from the event's `created`; set by rate and quota limits and some provider errors. */
     readonly retryAfterMs?: number;
 }
 export interface WatchPorts {
     readonly storage: RosterStorage;
-    /** `context` reads the last reply of a session that ended its turn without reporting; `get` is what every member joins with too. */
     readonly session: Pick<Context["session"], "synthetic" | "context" | "get"> & Instructions;
     readonly event: Pick<Context["event"], "subscribe">;
-    /** The permission domains of every loaded location, which the `Waits` suppliers ask; an isolated child's are in its worktree's. */
     readonly permissions: () => Iterable<Pick<Context["permission"], "list">>;
-    /** The clock, in epoch milliseconds, for an event that carries no `created`. */
     readonly now: () => number;
     readonly log: (message: string) => void;
-    /** Has the scheduler deliver what is due now rather than at its next tick: a group completed, or its parent's turn ended. */
     readonly nudge: () => void;
 }
-/**
- * What every plugin instance in the process shares. Several subscriptions and copies see the same
- * events, so each is claimed synchronously and handled once.
- */
 export interface WatchState {
     readonly seen: Set<string>;
-    /** The type of each item enqueued for a spawned session, by inbox id, for its delivery to look up. */
     readonly inbox: Map<string, string>;
 }
-/**
- * Whether a session waits, since `since`, on what the tree does not keep: asked by the silent-turn
- * rule after the tree's own checks, through the watcher's ports; `src/index.ts` composes it.
- */
 export type Waits = (ports: Pick<WatchPorts, "storage" | "permissions">, sessionID: string, since: number) => Promise<boolean>;
 export interface ContextPorts {
     readonly storage: RosterStorage;
     readonly limits: Limits;
-    /** Each session's role once looked up; a session nobody spawned reads as depth null until it starts one. */
     readonly roles: Map<string, Role>;
-    /** The keyed session entries, listed when a session's role is looked up; missing on a host before 2.2.0, which gets the system part. */
+    readonly session: Pick<Context["session"], "get">;
     readonly instructions?: Context["session"]["instructions"];
-    /** Tools of other modules hidden from a leaf alongside courier_spawn; `src/index.ts` names courier_recall and courier_note. */
     readonly hiddenFromLeaf?: ReadonlyArray<string>;
     readonly log: (message: string) => void;
 }

package/dist/tree/report.d.ts

@@ -1,14 +1,9 @@
 import { type Status } from "../kernel/protocol.js";
 import type { ChildStore } from "./ports.js";
 type Notes = Pick<ChildStore, "notes">;
-/** Whether courier_stop stopped a session after its last prompt, or with none noted, at all. */
 export declare function stoppedSincePrompt(children: Notes, sessionID: string): Promise<boolean>;
-/** The status of a spawned session's last report to its parent, if it has reported with one. */
+export declare function reportedSincePrompt(children: Notes, sessionID: string): Promise<boolean>;
 export declare function lastStatus(children: Notes, sessionID: string): Promise<Status | undefined>;
-/**
- * What is known of a spawned session's report: when a prompt last reached it, and whether since then it owes one, has
- * messaged its parent without a status, or failed (`resumesAt`: until when) or was interrupted. Undefined before this was kept.
- */
 export declare function reportOf(children: Notes, sessionID: string): Promise<{
     resumesAt?: number | undefined;
     prompt: number;
@@ -16,9 +11,5 @@ export declare function reportOf(children: Notes, sessionID: string): Promise<{
     progressed: boolean;
     ended: boolean;
 } | undefined>;
-/**
- * Whether its parent still waits on a spawned session's report: it owes one, and the parent has not
- * been told since its last prompt that it ended a turn without one.
- */
 export declare function awaited(children: Notes, sessionID: string): Promise<boolean>;
 export {};

package/dist/tree/report.js

@@ -1,20 +1,17 @@
 import { isStatus } from "../kernel/protocol.js";
-/** Whether `at` is known and no earlier than the prompt at `prompt`. */
 const since = (at, prompt) => at !== undefined && at >= prompt;
-/** Whether courier_stop stopped a session after its last prompt, or with none noted, at all. */
 export async function stoppedSincePrompt(children, sessionID) {
     const { stopped, prompt } = await children.notes(sessionID, ["stopped", "prompt"]);
     return stopped.at !== undefined && (prompt.at === undefined || stopped.at >= prompt.at);
 }
-/** The status of a spawned session's last report to its parent, if it has reported with one. */
+export async function reportedSincePrompt(children, sessionID) {
+    const { prompt, settled } = await children.notes(sessionID, ["prompt", "settled"]);
+    return prompt.at !== undefined && settled.by === "report" && settled.status !== "blocked" && since(settled.at, prompt.at);
+}
 export async function lastStatus(children, sessionID) {
     const { status } = (await children.notes(sessionID, ["settled"])).settled;
     return isStatus(status) ? status : undefined;
 }
-/**
- * What is known of a spawned session's report: when a prompt last reached it, and whether since then it owes one, has
- * messaged its parent without a status, or failed (`resumesAt`: until when) or was interrupted. Undefined before this was kept.
- */
 export async function reportOf(children, sessionID) {
     const { prompt, settled, progress } = await children.notes(sessionID, ["prompt", "settled", "progress"]);
     const promptAt = prompt.at;
@@ -30,10 +27,6 @@ export async function reportOf(children, sessionID) {
         ...(resumesAt === undefined ? {} : { resumesAt }),
     };
 }
-/**
- * Whether its parent still waits on a spawned session's report: it owes one, and the parent has not
- * been told since its last prompt that it ended a turn without one.
- */
 export async function awaited(children, sessionID) {
     const { prompt, settled, told } = await children.notes(sessionID, ["prompt", "settled", "told"]);
     return prompt.at !== undefined && !since(settled.at, prompt.at) && !since(told.at, prompt.at);

package/dist/tree/roster.d.ts

@@ -2,21 +2,10 @@ import { type Status } from "../kernel/protocol.js";
 import { type Exists } from "./domain.js";
 import type { RosterEntry, RosterStorage } from "./ports.js";
 export { RETENTION_MS, type Exists } from "./domain.js";
-/** Every parent's children. */
 export declare function allEntries(storage: RosterStorage): Promise<RosterEntry[]>;
-/**
- * The roster entries from a session up to the top, its own first, ending with the entry whose parent
- * courier_spawn did not start; empty when courier_spawn did not start the session.
- */
 export declare function lineage(storage: RosterStorage, sessionID: string): Promise<RosterEntry[]>;
-/** `lineage` by the reverse index alone: empty, without scanning the roster, when it does not name the session. */
 export declare function indexedLineage(storage: RosterStorage, sessionID: string): Promise<RosterEntry[]>;
-/** The sessions a session started, oldest first, expired entries included. */
 export declare function childrenOf(storage: RosterStorage, parentID: string): Promise<RosterEntry[]>;
-/**
- * What another module reads of a spawned session's report: `known` once a prompt was noted, whether it `owes` one, how
- * its wait `ended` when not by a report, the `status` of its last report, and whether courier_stop `stopped` it since its last prompt.
- */
 export interface ReportState {
     readonly known: boolean;
     readonly owes: boolean;
@@ -25,17 +14,7 @@ export interface ReportState {
     readonly stopped: boolean;
 }
 export declare function reportState(storage: RosterStorage, sessionID: string): Promise<ReportState>;
-/**
- * The top of a spawned session's lineage, where its permission requests and questions go, since the
- * person is there. Throws unless the session was spawned and `callerID` is that top; `what` names it.
- */
 export declare function answeringTop(storage: RosterStorage, sessionID: string, callerID: string, what: string): Promise<string>;
-/** `domain.ts`'s `isExpired`, asking the file system whether an isolated child's worktree is still there unless a test passes a fake. */
 export declare const isExpired: (entry: RosterEntry, now: number, exists?: Exists) => boolean;
-/** A parent's children, oldest first, after dropping the expired ones. */
 export declare function current(storage: RosterStorage, parentID: string, now: number, exists?: Exists): Promise<RosterEntry[]>;
-/**
- * On loading: drops expired entries of every parent, then brings the reverse index in line with
- * what is left (`backfill`) and drops report state with no entry (`dropOrphanedReports`).
- */
 export declare function pruneExpired(storage: RosterStorage, now: number, exists?: Exists): Promise<void>;

package/dist/tree/roster.js

@@ -5,22 +5,15 @@ import { forgetChild, forgetReports } from "./forget.js";
 import { stoppedSincePrompt } from "./report.js";
 import { childStore } from "./store.js";
 export { RETENTION_MS } from "./domain.js";
-/** Every parent's children. */
 export async function allEntries(storage) {
     return childStore(storage).all();
 }
-/**
- * The roster entries from a session up to the top, its own first, ending with the entry whose parent
- * courier_spawn did not start; empty when courier_spawn did not start the session.
- */
 export async function lineage(storage, sessionID) {
     return childStore(storage).lineage(sessionID);
 }
-/** `lineage` by the reverse index alone: empty, without scanning the roster, when it does not name the session. */
 export async function indexedLineage(storage, sessionID) {
     return childStore(storage).indexedLineage(sessionID);
 }
-/** The sessions a session started, oldest first, expired entries included. */
 export async function childrenOf(storage, parentID) {
     return childStore(storage).children(parentID);
 }
@@ -38,10 +31,6 @@ export async function reportState(storage, sessionID) {
         stopped,
     };
 }
-/**
- * The top of a spawned session's lineage, where its permission requests and questions go, since the
- * person is there. Throws unless the session was spawned and `callerID` is that top; `what` names it.
- */
 export async function answeringTop(storage, sessionID, callerID, what) {
     const chain = await lineage(storage, sessionID);
     if (!chain.length)
@@ -51,31 +40,21 @@ export async function answeringTop(storage, sessionID, callerID, what) {
         throw new Error(`${sessionID}'s ${what} go to ${top}, the session at the top of the sessions started from it with courier_spawn; ${callerID} cannot answer them.`);
     return top;
 }
-/** `domain.ts`'s `isExpired`, asking the file system whether an isolated child's worktree is still there unless a test passes a fake. */
 export const isExpired = (entry, now, exists = existsSync) => expiredBy(entry, now, exists);
-/** Forgets the given entries that are expired at `now`, and returns the rest. */
 async function dropExpired(storage, entries, now, exists) {
     const expired = new Set(entries.filter((entry) => isExpired(entry, now, exists)));
     await Promise.all([...expired].map((entry) => forgetChild(storage, entry.parentID, entry.sessionID, entry.group)));
     return entries.filter((entry) => !expired.has(entry));
 }
-/** A parent's children, oldest first, after dropping the expired ones. */
 export async function current(storage, parentID, now, exists = existsSync) {
     return dropExpired(storage, await childStore(storage).children(parentID), now, exists);
 }
-/**
- * On loading: drops expired entries of every parent, then brings the reverse index in line with
- * what is left (`backfill`) and drops report state with no entry (`dropOrphanedReports`).
- */
 export async function pruneExpired(storage, now, exists = existsSync) {
     const children = childStore(storage);
-    // Report keys are read before the roster: courier_spawn writes a child's entry before its first
-    // report key, so a session seen here that spawns during the sweep has its entry in the read below.
     const reported = await children.reported().catch(() => new Map());
     const entries = await dropExpired(storage, await children.all(), now, exists);
     await Promise.all([children.backfill(entries), dropOrphanedReports(storage, reported, entries)]);
 }
-/** Removes the report keys read of sessions that have no roster entry. */
 async function dropOrphanedReports(storage, reported, entries) {
     const sessions = new Set(entries.map((entry) => entry.sessionID));
     await forgetReports(storage, reported, [...reported.keys()].filter((sessionID) => !sessions.has(sessionID)));