opencode-courier 0.7.2 → 0.8.0

package/dist/memory/tools.js

@@ -0,0 +1,78 @@
+import { Schema } from "effect";
+import { describeFailure } from "../kernel/protocol.js";
+import { rethrow } from "../kernel/tool.js";
+import { LESSON_MAX } from "./domain.js";
+import { note } from "./note.js";
+import { recall } from "./recall.js";
+import { NOTE_EMPTY, NOTE_OFF, NOTE_TOOL, noteLeafRefusal, noteLongRefusal, noteText, noteUnrecordedRefusal, RECALL_OFF, RECALL_TOOL, recallListText, recallMissingText, recallRecordText } from "./text.js";
+export const RecallInput = Schema.Struct({
+    sessionID: Schema.optional(Schema.String.annotate({ description: "The top session of a listed record, for that record in full; without it, one line per record of this project." })),
+});
+export const NoteInput = Schema.Struct({
+    text: Schema.String.annotate({
+        description: `The lesson, one line of at most ${LESSON_MAX} characters (longer is refused, not clipped): what the next orchestrator in this ` +
+            "project should know about running a tree like this one, how it was split, verified or briefed, or what the person decided, " +
+            "with the job it comes from and the reason.",
+    }),
+});
+/** Adds `courier_recall` and `courier_note`, direct tools rather than code-mode ones. */
+export function addMemoryTools(tools, ports) {
+    tools.add({
+        name: RECALL_TOOL,
+        options: { codemode: false },
+        description: "Look once at what earlier session trees in this project did, before you decide whether and how to split a task: " +
+            "one line per tree, newest first, with how its top split the task, how each part went (its status, how long it ran, " +
+            "what it cost, how full its context got) and whether a spawn was refused; with sessionID, one tree's record in full. " +
+            "Records hold no report bodies or files. Call it once at the start, not in a loop, and not to check on sessions you " +
+            "started: their reports wake you.",
+        input: RecallInput,
+        execute: async (input, context) => {
+            const result = await recall(ports.memory, ports.state, context.sessionID, input).catch(rethrow(RECALL_TOOL));
+            switch (result.kind) {
+                case "off":
+                    return { content: RECALL_OFF, metadata: { memory: false } };
+                case "list":
+                    return { content: recallListText(result.records, result.top), metadata: { projectID: result.projectID, top: result.top, records: result.records } };
+                case "record":
+                    return { content: recallRecordText(result.record), metadata: { projectID: result.projectID, record: result.record } };
+                case "missing":
+                    return { content: recallMissingText(result.sessionID), metadata: { projectID: result.projectID, sessionID: result.sessionID, found: false } };
+            }
+        },
+    });
+    tools.add({
+        name: NOTE_TOOL,
+        options: { codemode: false },
+        description: "Write the one lesson of your session tree for the next orchestrator in this project, once you have verified and " +
+            "integrated the work: what it should know about running a tree like this one that the record's facts do not say. How " +
+            "it was split (which parts collided, what was too small to hand off), how it was verified (what a part got wrong and " +
+            "what caught it), how the parts were briefed, or what the person decided. Name the job it comes from and the reason, " +
+            "so that a lesson for one kind of job can be told from one that holds everywhere. One line, at most " +
+            `${LESSON_MAX} characters; a longer one is refused, not clipped, so write it again shorter. Kept on your own tree's ` +
+            "record and listed by courier_recall after its facts, dated; a second call replaces the first. From the top session " +
+            "or one that started sessions, never a leaf. No code, no secrets, and not a rule that holds every time: that belongs " +
+            "in AGENTS.md or the skill, for the person to put there, so tell them instead.",
+        input: NoteInput,
+        execute: async (input, context) => {
+            const result = await note(ports.memory, context.sessionID, input).catch(rethrow(NOTE_TOOL));
+            // A refusal is the tool's failure, as courier_spawn's are, so the step ends on it and the model reads why.
+            const refuse = (text) => describeFailure(NOTE_TOOL, new Error(text));
+            switch (result.kind) {
+                case "noted": {
+                    const { projectID, top, lesson, replaced } = result;
+                    return { content: noteText(top, lesson, replaced), metadata: { projectID, top, lesson, ...(replaced ? { replaced } : {}) } };
+                }
+                case "off":
+                    throw refuse(NOTE_OFF);
+                case "leaf":
+                    throw refuse(noteLeafRefusal(result.depth, result.maxDepth));
+                case "empty":
+                    throw refuse(NOTE_EMPTY);
+                case "long":
+                    throw refuse(noteLongRefusal(result.length));
+                case "unrecorded":
+                    throw refuse(noteUnrecordedRefusal(result.top));
+            }
+        },
+    });
+}

package/dist/memory/tui.d.ts

@@ -0,0 +1,73 @@
+import type { Plugin } from "@opencode/plugin/tui";
+import { type Forgotten, type MemoryLesson, type MemoryPart, type MemoryRecord } from "./rpc.js";
+type Context = Plugin.Context;
+/** The command that opens the memory view: `/courier memory`, or the palette. */
+export declare const MEMORY_COMMAND = "courier.memory";
+/** The memory view's line of the `/courier` command's usage. */
+export declare const MEMORY_USAGE = "/courier memory lists this project's tree records, to read or forget";
+/** What the view says, in a toast, with the memory option off in the project asked. */
+export declare const MEMORY_OFF = "Memory is off in this project: the plugin's memory option is false, so no record of a session tree is kept or listed here.";
+/** What the view says, in a toast, when the project has no record: when none was written yet, or the last was forgotten. */
+export declare const NO_RECORDS = "No record of a session tree in this project: one is written as each turn in a tree ends, and kept 90 days.";
+/** The most characters of a lesson a list row's line under it shows; the record in full has it whole. */
+export declare const LESSON_LINE_MAX = 160;
+/** The most characters of a title a list row shows, so that "(this session)" after it fits the host's 61. */
+export declare const ROW_TITLE_MAX = 46;
+/** The group of the records moved on the current local day, over the others' local dates, as the host's Sessions dialog has it. */
+export declare const TODAY = "Today";
+/** The widest a row of the lesson in a record in full is; a longer lesson wraps over rows. */
+export declare const LESSON_ROW = 90;
+/** A record's name, as its rows and confirms show it: its title on one line, else its top session. */
+export declare const nameOf: (record: MemoryRecord) => string;
+/** A record's parts counted by status, in the order of `PART_STATUSES`: "3 parts: 2 done, 1 partial"; "no parts" with none. */
+export declare function partsCounted(parts: ReadonlyArray<MemoryPart>): string;
+/** The parts' costs summed, when any is known. */
+export declare function costOf(record: MemoryRecord): number | undefined;
+/** A list row's title: the tree's title, its top session's id without one; the open session's own tree says so. */
+export declare function recordTitle(record: MemoryRecord, open?: string): string;
+/** A list row's group: `Today` for a tree last moved on the local day of `now`, else that local date; the RPC's order, by the last move, keeps the groups newest first. */
+export declare function recordCategory(record: MemoryRecord, now?: number): string;
+/** A lesson as the view shows it: dated on the local day, from which depth when a session below the top wrote it, and its text. */
+export declare function lessonHeading(lesson: MemoryLesson): string;
+/** A list row's description: its parts by status, how long the tree ran, what its parts cost, and that it is not finished when it is not. */
+export declare function recordDescription(record: MemoryRecord): string;
+/** The lines under a list row: the lesson, dated and from which depth, clipped; none without a lesson. */
+export declare function recordDetails(record: MemoryRecord): string[];
+/** One part as the record in full describes it: its status, depth, isolation, group, duration, cost, context use and spawns refused. */
+export declare function partLine(part: MemoryPart): string;
+/** `text` in rows of at most `width` characters, broken at spaces where it can be. */
+export declare function wrap(text: string, width: number): string[];
+/** A row of a record in full: a fact of the tree, one of its parts, or a row of its lesson (0 its heading), which `x` forgets alone. */
+export type Line = {
+    readonly kind: "fact";
+    readonly key: string;
+} | {
+    readonly kind: "part";
+    readonly sessionID: string;
+} | {
+    readonly kind: "lesson";
+    readonly row: number;
+};
+/** Where the cursor goes in a record in full after its lesson is forgotten: the lesson's first row, or the row that replaced it. */
+export declare const lessonLine: (record: MemoryRecord) => Line;
+/** The records the list's cursor tries, in order, after one is forgotten, kept or left: it, unless forgotten, then those after it, then those before it, nearest first. */
+export declare function nearby(sessionIDs: ReadonlyArray<string>, sessionID: string, forgotten: boolean): string[];
+/** The rows of a record in full, in three categories: the tree's facts, its parts and its lesson. */
+export declare function detailOptions(record: MemoryRecord): Array<{
+    title: string;
+    value: Line;
+    category: string;
+    description?: string;
+}>;
+/** What the confirm asks before a forget: the record named, with the local day it last moved, and what goes and what stays. */
+export declare function forgetMessage(record: MemoryRecord, lesson: boolean): string;
+/** The toast after a forget, as the server reports it. */
+export declare function forgottenLine(record: MemoryRecord, outcome: Forgotten["outcome"]): string;
+/**
+ * Adds the memory view: the project's records (the open session's location, else the TUI's, else the server's default) under
+ * `Today` and the local days they last moved; `enter` shows one in full, `x` forgets one or its lesson after a confirm, `esc` goes back and closes.
+ */
+export declare function addMemoryView(ctx: Context): {
+    open: () => Promise<void>;
+};
+export {};

package/dist/person/rpc.d.ts

@@ -106,8 +106,8 @@ export declare const personRpc: {
                 readonly sessions: readonly {
                     readonly sessionID: string;
                     readonly title: string;
-                    readonly parentID: string;
                     readonly depth: number;
+                    readonly parentID: string;
                     readonly group?: string | undefined;
                 }[];
                 readonly permissions: readonly {
@@ -140,8 +140,8 @@ export declare const personRpc: {
                 readonly sessions: readonly {
                     readonly sessionID: string;
                     readonly title: string;
-                    readonly parentID: string;
                     readonly depth: number;
+                    readonly parentID: string;
                     readonly group?: string | undefined;
                 }[];
                 readonly permissions: readonly {
@@ -227,11 +227,11 @@ export declare const personRpc: {
             }>;
             readonly output: import("effect/StandardSchema").StandardSchemaV1<{
                 readonly answered: boolean;
-                readonly by?: "result" | "message" | undefined;
+                readonly by?: "message" | "result" | undefined;
                 readonly problem?: string | undefined;
             }, {
                 readonly answered: boolean;
-                readonly by?: "result" | "message" | undefined;
+                readonly by?: "message" | "result" | undefined;
                 readonly problem?: string | undefined;
             }> & Schema.Struct<{
                 readonly answered: Schema.Boolean;

package/dist/platform/json.d.ts

@@ -1,6 +1,7 @@
 /** Readers for untyped JSON, such as a webhook payload or a plugin option: the value when it has the type, else nothing. */
 export declare const str: (value: unknown) => string | undefined;
 export declare const num: (value: unknown) => number | undefined;
+export declare const finite: (value: unknown) => number | undefined;
 export declare const obj: (value: unknown) => Record<string, any>;
 /** Epoch milliseconds from a session time, a `DateTime` in OpenCode's API and a number in tests; NaN for none. */
 export declare function millis(value: unknown): number;

package/dist/platform/json.js

@@ -1,6 +1,7 @@
 /** Readers for untyped JSON, such as a webhook payload or a plugin option: the value when it has the type, else nothing. */
 export const str = (value) => (typeof value === "string" ? value : undefined);
 export const num = (value) => (typeof value === "number" && Number.isInteger(value) ? value : undefined);
+export const finite = (value) => (typeof value === "number" && Number.isFinite(value) ? value : undefined);
 export const obj = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
 /** Epoch milliseconds from a session time, a `DateTime` in OpenCode's API and a number in tests; NaN for none. */
 export function millis(value) {

package/dist/platform/version.js

@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-const README_TABLE = "https://github.com/ivopogace/opencode-courier#supported-opencode-version";
+const VERSION_TABLE = "https://github.com/ivopogace/opencode-courier/blob/main/docs/reference.md#the-opencode-version";
 /**
  * Reads from the package's own package.json, next to `dist/` as to `src/`: `version` and the exact
  * `@opencode/plugin` devDependency version, which the peer repeats. Throws if either is missing.
@@ -25,5 +25,5 @@ export function versionNotice(built, app) {
     const running = version === undefined ? "this server reports no version" : `this server is ${version}`;
     const channel = typeof app?.channel === "string" ? ` (channel ${app.channel})` : "";
     return (`opencode-courier ${built.plugin} was built and tested against OpenCode ${built.opencode}; ${running}${channel}. ` +
-        `Its tools may fail: see the Supported OpenCode version table in the README, ${README_TABLE}`);
+        `Its tools may fail: see every release and the OpenCode it is pinned to, ${VERSION_TABLE}`);
 }

package/dist/rpc.d.ts

@@ -1,2 +1,3 @@
 export { treeRpc, type Row, type Stopped, type Summary, type Tree, type TreeRpc, type Wait } from "./tree/rpc.js";
 export { personRpc, type Answered, type Asks, type PersonRpc } from "./person/rpc.js";
+export { memoryRpc, type Forgotten as MemoryForgotten, type MemoryLesson, type MemoryPart, type MemoryRecord, type MemoryRpc, type Records } from "./memory/rpc.js";

package/dist/rpc.js

@@ -1,3 +1,4 @@
 // The package's `rpc` entrypoint: the courier's RPC contracts, for a client that calls them.
 export { treeRpc } from "./tree/rpc.js";
 export { personRpc } from "./person/rpc.js";
+export { memoryRpc } from "./memory/rpc.js";

package/dist/skill.js

@@ -10,8 +10,9 @@ export const SKILL_CONTENT = [
     "How to split a task across OpenCode sessions with opencode-courier, and bring the results back up. Your brief, or the " +
         "opencode-courier role line in your system prompt, names your depth in the session tree and its limits.",
     "",
-    "1. Decide: split or do. Split when the task has 2 or more independent, substantial parts touching separate files or " +
-        "areas; do it yourself when it is small, sequential or tightly coupled. Never start exactly one session for the whole " +
+    "1. Decide: split or do. First call courier_recall once: it lists how earlier trees in this project were split and how " +
+        "each part went, so weigh that; one call, before you decide, never in a loop. Split when the task has 2 or more " +
+        "independent, substantial parts touching separate files or areas; do it yourself when it is small, sequential or tightly coupled. Never start exactly one session for the whole " +
         "task: it only adds a hop. What you read and write yourself stays in your context for every later turn, so keep the " +
         "deciding, checking and integrating, and hand off the long reading and writing. An implementation task with one tightly " +
         "coupled core usually still has independent parts: finding out what the change needs (a session with isolate: false " +
@@ -44,7 +45,13 @@ export const SKILL_CONTENT = [
     "7. Integrate: merge each reported branch into your own checkout (git merge courier/<session>), resolve conflicts " +
         "yourself, run the checks once more, then courier_cleanup the isolated sessions you are done with.",
     "8. Report upward if a session started you: one courier_send to it, with one status for the whole (done only when every " +
-        "part is verified and integrated; partial, blocked or failed otherwise) and the artifacts. At the top, reply to the person.",
+        "part is verified and integrated; partial, blocked or failed otherwise) and the artifacts. At the top, before you reply " +
+        "to the person: if there is something the next tree in this project should know about running a tree like this one (how " +
+        "it was split, what a part got wrong and what caught it, what a brief should have said, what the person decided), one " +
+        "courier_note with that one line; none when there is nothing. Name the job it comes from and the reason, so that a " +
+        "lesson for one kind of job is not taken for every job; the tool refuses a line over its limit rather than clipping " +
+        "it, so write it again shorter. A rule that holds every time goes to AGENTS.md or the skill, through the person, not " +
+        "into a note. Then reply to the person.",
     "",
     "When a part goes wrong:",
     "- A failed turn (failed=\"...\") or a silent end (ended=\"without-report\", quoting the session's last reply): message " +

package/dist/tree/context.d.ts

@@ -9,7 +9,7 @@ export interface Shaped {
     }>;
 }
 /**
- * The `context` hook: names a session's role in its tree in a system part, and hides courier_spawn
- * from one at `maxDepth`. A session nobody spawned that has started none is pointed to the skill, if it could spawn.
+ * The `context` hook: names a session's role in its tree in a system part, and hides courier_spawn, and the tools
+ * named `hiddenFromLeaf`, from one at `maxDepth`. A session nobody spawned that has started none is pointed to the skill, if it could spawn.
  */
 export declare function shapeContext(ports: ContextPorts, event: Shaped): Promise<void>;

package/dist/tree/context.js

@@ -4,8 +4,8 @@ import { ROLE_PREFIX, rolePart } from "./text.js";
 /** How many sessions' depths an instance remembers. */
 const ROLES_MAX = 1000;
 /**
- * The `context` hook: names a session's role in its tree in a system part, and hides courier_spawn
- * from one at `maxDepth`. A session nobody spawned that has started none is pointed to the skill, if it could spawn.
+ * The `context` hook: names a session's role in its tree in a system part, and hides courier_spawn, and the tools
+ * named `hiddenFromLeaf`, from one at `maxDepth`. A session nobody spawned that has started none is pointed to the skill, if it could spawn.
  */
 export async function shapeContext(ports, event) {
     try {
@@ -13,7 +13,8 @@ export async function shapeContext(ports, event) {
         if (depth === null && !event.tools.courier_spawn)
             return;
         if (depth !== null && depth >= ports.limits.maxDepth)
-            delete event.tools.courier_spawn;
+            for (const tool of ["courier_spawn", ...(ports.hiddenFromLeaf ?? [])])
+                delete event.tools[tool];
         if (!event.system.some((part) => part.text.startsWith(ROLE_PREFIX)))
             event.system.push({ type: "text", text: rolePart(depth, ports.limits) });
     }

package/dist/tree/index.d.ts

@@ -1,11 +1,12 @@
 export { dirtyOf, headOf, inspectWorktree } from "./cleanup.js";
 export { shapeContext } from "./context.js";
-export { lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
+export { busy, lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
 export { together, treeEvents, waitsOn } from "./events.js";
 export { deliverReleased } from "./group.js";
-export type { CleanupPorts, CourierPorts, Pending, PendingPrompt, RosterEntry, RosterStorage, ShownForm, SpawnGate, Waits, WatchPorts, WatchState, } from "./ports.js";
-export { allEntries, answeringTop, lineage, pruneExpired, RETENTION_MS } from "./roster.js";
-export { subtree } from "./subtree.js";
+export { contextOf } from "./panel.js";
+export type { CleanupPorts, CourierPorts, ModelWindow, Pending, PendingPrompt, RosterEntry, RosterStorage, ShownForm, SpawnGate, Waits, WatchPorts, WatchState, } from "./ports.js";
+export { allEntries, answeringTop, childrenOf, indexedLineage, lineage, pruneExpired, reportState, RETENTION_MS, type ReportState } from "./roster.js";
+export { subtree, type Below } from "./subtree.js";
 export { registerTreeRpc } from "./rpc-handlers.js";
 export { addTreeTools } from "./tools.js";
-export { wakeMissed } from "./wake.js";
+export { stalledAmong, wakeMissed } from "./wake.js";

package/dist/tree/index.js

@@ -1,12 +1,13 @@
 // What the rest of the plugin uses of the session tree: its tools, RPC, event module, context hook and tick jobs
-// for `src/index.ts`, and the lineage and subtree queries and types `person/` reads.
+// for `src/index.ts`, the lineage and subtree queries and types `person/` reads, and what `memory/` reads of each session.
 export { dirtyOf, headOf, inspectWorktree } from "./cleanup.js";
 export { shapeContext } from "./context.js";
-export { lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
+export { busy, lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
 export { together, treeEvents, waitsOn } from "./events.js";
 export { deliverReleased } from "./group.js";
-export { allEntries, answeringTop, lineage, pruneExpired, RETENTION_MS } from "./roster.js";
+export { contextOf } from "./panel.js";
+export { allEntries, answeringTop, childrenOf, indexedLineage, lineage, pruneExpired, reportState, RETENTION_MS } from "./roster.js";
 export { subtree } from "./subtree.js";
 export { registerTreeRpc } from "./rpc-handlers.js";
 export { addTreeTools } from "./tools.js";
-export { wakeMissed } from "./wake.js";
+export { stalledAmong, wakeMissed } from "./wake.js";

package/dist/tree/mascot.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A pixel of Digby, the tree panel's mole, as the theme colour it takes: `b` body, `k` background (eyes), `g` mound,
+ * `m` muted (paws, dirt, post, arm), `a` accent (snout, letter), `w`, `e` and `s` warning, error and success (sign, dots, spark).
+ */
+export type Token = "b" | "k" | "g" | "m" | "a" | "w" | "e" | "s";
+/** What Digby shows: the tree's state, or for a while after one arrives, a spawn or a report. */
+export type MascotState = "idle" | "spawn" | "running" | "waiting" | "stalled" | "report" | "gone";
+/** One cell of a drawing: `▀` the top pixel's colour over the bottom's, `▄` only a bottom pixel, `█` both alike, or a character. */
+export type Cell = {
+    readonly char: string;
+    readonly fg?: Token;
+    readonly bg?: Token;
+};
+/** Digby's frames take one panel frame in this many, about every 450 ms. */
+export declare const MASCOT_EVERY = 5;
+/** He blinks on every this-many-th of his frames where his eyes are open. */
+export declare const BLINK_EVERY = 11;
+/**
+ * The 8×4 glyph's frames by state, pixel rows top to bottom; a state with several cycles through them, one per mascot frame.
+ * No muted pixel touches the mound, here or in the 16×16, as `text.muted` is close to `background.raised.max`.
+ */
+export declare const GLYPH: Readonly<Record<MascotState, ReadonlyArray<ReadonlyArray<string>>>>;
+/** The 8×4 glyph's pixels for `state` at mascot frame `frame`, its first frame with none: animations off. */
+export declare function glyph(state: MascotState, frame?: number): ReadonlyArray<string>;
+/** Pixel rows, two to a line of cells, by the half-block rule; an odd last row has nothing under it. */
+export declare function cells(pixels: ReadonlyArray<string>): ReadonlyArray<ReadonlyArray<Cell>>;
+/** How his eyes are drawn: one pixel each, `wide` two tall, `shut` two wide, or `none` (blinking). */
+export type Eyes = "open" | "wide" | "shut" | "none";
+/**
+ * The 16×16 Digby, his head raised by `rise` (0 in the hole, 1 fully up; below 0 out of sight) over a body in the hole,
+ * then the mound (its top row `top` wide, `shift` columns over) and the ground, both `mound`, drawn over it but for the hole.
+ */
+export declare function digby(rise: number, { top, eyes, slump, shift, mound }?: {
+    top?: number;
+    eyes?: Eyes;
+    slump?: boolean;
+    shift?: number;
+    mound?: "g" | "m";
+}): ReadonlyArray<string>;
+/** A spot of `pixels` with its first at row `row`, column `column`; `.` leaves what is under it. */
+type Spot = readonly [row: number, column: number, pixels: string];
+/** `pixels` with `spots` drawn over them. */
+export declare function paint(pixels: ReadonlyArray<string>, spots: ReadonlyArray<Spot>): ReadonlyArray<string>;
+/** The 16×16's frames by state but idle, each its pixels with the eyes open or, for a blink, not; the first reads alone. */
+export declare const ART: Readonly<Record<Exclude<MascotState, "idle">, ReadonlyArray<(open: boolean) => ReadonlyArray<string>>>>;
+/** The 16×16 idle Digby at mascot frame `frame`, its first with none: the mound breathing, a `z` drifting up beside it. */
+export declare function idleArt(frame?: number): ReadonlyArray<ReadonlyArray<Cell>>;
+/** The 16×16 Digby for `state` at mascot frame `frame`, its first frame with none: animations off. */
+export declare function art(state: MascotState, frame?: number): ReadonlyArray<ReadonlyArray<Cell>>;
+export {};

package/dist/tree/mascot.js

@@ -0,0 +1,171 @@
+/** Digby's frames take one panel frame in this many, about every 450 ms. */
+export const MASCOT_EVERY = 5;
+/** He blinks on every this-many-th of his frames where his eyes are open. */
+export const BLINK_EVERY = 11;
+/**
+ * The 8×4 glyph's frames by state, pixel rows top to bottom; a state with several cycles through them, one per mascot frame.
+ * No muted pixel touches the mound, here or in the 16×16, as `text.muted` is close to `background.raised.max`.
+ */
+export const GLYPH = {
+    idle: [["........", "........", "..gggg..", "gggggggg"]],
+    spawn: [
+        ["........", "...bb...", "g.bbbb.g", "gggggggg"],
+        [".g....g.", "...bb...", "ggbbbbgg", "gggggggg"],
+    ],
+    running: [
+        ["..g..g..", "...bb...", ".gbbbbg.", "gggggggg"],
+        [".g....g.", "........", ".gbbbbg.", "gggggggg"],
+    ],
+    waiting: [
+        [".bbbbbbw", ".bkbbkbw", ".bbaabbm", "ggggggg."],
+        [".bbbbbbb", ".bkbbkbb", ".bbaabbm", "ggggggg."],
+    ],
+    stalled: [
+        ["..e.....", ".bbbbbb.", ".bkbbkb.", "gbbaabbg"],
+        ["..e.e...", ".bbbbbb.", ".bkbbkb.", "gbbaabbg"],
+        ["..e.e.e.", ".bbbbbb.", ".bkbbkb.", "gbbaabbg"],
+    ],
+    report: [
+        ["......aa", "bbbbbbaa", "bkbbkbm.", "bbaabbm."],
+        ["s.....aa", "bbbbbbaa", "bkbbkbm.", "bbaabbm."],
+    ],
+    gone: [["........", ".mmmmmm.", ".mkmmkm.", "mmmmmmmm"]],
+};
+/** The states in which his eyes are open, so he blinks. */
+const OPEN_EYES = new Set(["waiting", "report"]);
+/** The 8×4 glyph's pixels for `state` at mascot frame `frame`, its first frame with none: animations off. */
+export function glyph(state, frame) {
+    const frames = GLYPH[state];
+    const pixels = frames[(frame ?? 0) % frames.length];
+    if (frame === undefined)
+        return pixels;
+    if (state === "idle" && breathesOut(frame))
+        return [...pixels.slice(0, 2), ".gggggg.", ...pixels.slice(3)];
+    return OPEN_EYES.has(state) && blinks(frame) ? pixels.map((row) => row.replaceAll("k", "b")) : pixels;
+}
+/** The mound's top row widens for two frames in four. */
+const breathesOut = (frame) => Math.floor(frame / 2) % 2 === 1;
+const blinks = (frame) => frame % BLINK_EVERY === BLINK_EVERY - 1;
+/** Pixel rows, two to a line of cells, by the half-block rule; an odd last row has nothing under it. */
+export function cells(pixels) {
+    const lines = [];
+    for (let row = 0; row < pixels.length; row += 2) {
+        const top = pixels[row];
+        const bottom = pixels[row + 1] ?? "";
+        lines.push([...top].map((pixel, column) => cell(token(pixel), token(bottom[column]))));
+    }
+    return lines;
+}
+const token = (pixel) => (pixel && pixel !== "." ? pixel : undefined);
+function cell(top, bottom) {
+    if (!top && !bottom)
+        return { char: " " };
+    if (!top)
+        return { char: "▄", fg: bottom };
+    if (top === bottom)
+        return { char: "█", fg: top };
+    return bottom ? { char: "▀", fg: top, bg: bottom } : { char: "▀", fg: top };
+}
+/** The 16×16's size, in pixels. */
+const SIZE = 16;
+/** How far each of the head's rows leans right when he slumps. */
+const SLUMP = [2, 2, 2, 1, 1, 0, 0];
+/**
+ * The 16×16 Digby, his head raised by `rise` (0 in the hole, 1 fully up; below 0 out of sight) over a body in the hole,
+ * then the mound (its top row `top` wide, `shift` columns over) and the ground, both `mound`, drawn over it but for the hole.
+ */
+export function digby(rise, { top = 6, eyes = "open", slump = false, shift = 0, mound = "g" } = {}) {
+    const grid = Array.from({ length: SIZE }, () => new Array(SIZE).fill("."));
+    const span = (row, width, pixel, skip = (_column) => false, by = 0) => {
+        if (row < 0 || row >= SIZE)
+            return;
+        for (let column = (SIZE - width) / 2; column < (SIZE + width) / 2; column++)
+            if (!skip(column))
+                grid[row][column + by] = pixel;
+    };
+    const head = Math.round(10 - 8 * rise);
+    const lean = (at) => (slump ? SLUMP[at] : 0);
+    [4, 6, 8, 8, 8, 6, 4].forEach((width, at) => span(head + at, width, "b", undefined, lean(at)));
+    for (let row = head + 7; row <= 11; row++)
+        span(row, 4, "b");
+    const eyeColumns = eyes === "shut" ? [5, 6, 9, 10] : [6, 9];
+    if (eyes !== "none")
+        span(head + 3, 8, "k", (column) => !eyeColumns.includes(column), lean(3));
+    if (eyes === "wide")
+        span(head + 2, 8, "k", (column) => !eyeColumns.includes(column), lean(2));
+    span(head + 4, 2, "a", undefined, lean(4));
+    span(10, SIZE, ".", (column) => column >= 6 && column <= 9);
+    span(10, top, mound, (column) => column >= 6 && column <= 9, shift);
+    span(11, 10, mound, undefined, shift);
+    span(12, 12, mound, undefined, shift);
+    for (const row of [13, 14, 15])
+        span(row, SIZE, mound);
+    return grid.map((row) => row.join(""));
+}
+/** `pixels` with `spots` drawn over them. */
+export function paint(pixels, spots) {
+    const grid = pixels.map((row) => [...row]);
+    for (const [row, column, drawn] of spots)
+        [...drawn].forEach((pixel, at) => {
+            if (pixel !== "." && grid[row]?.[column + at] !== undefined)
+                grid[row][column + at] = pixel;
+        });
+    return grid.map((row) => row.join(""));
+}
+/** A column of `length` pixels of `pixel` from row `row`. */
+const post = (row, column, length, pixel) => Array.from({ length }, (_, at) => [row + at, column, pixel]);
+/** The head's top row at `rise`, where running's snout pokes up. */
+const headTop = (rise) => Math.round(10 - 8 * rise);
+const running = (rise, shift, dirt) => paint(digby(rise, { shift }), [[headTop(rise), 7, "aa"], ...dirt]);
+/** A child's head peeking out of a side mound at columns `column`–`column + 2`, `up` or half sunk. */
+const peek = (column, up) => [
+    ...(up ? [[8, column, ".b."], [9, column, "bkb"]] : [[9, column, ".b."]]),
+    [10, column, "gbg"],
+    [11, column, "ggg"],
+];
+const spawn = (up, dirt) => paint(digby(0.1), [...peek(0, up), ...peek(13, up), [12, 0, "gg"], [12, 14, "gg"], ...dirt]);
+/** The sign on its post, which stops a pixel above the ground so the muted post does not sit on it. */
+const sign = (shown) => [...(shown ? [[2, 13, "www"], [3, 13, "wkw"], [4, 13, "www"]] : []), ...post(5, 14, 7, "m")];
+/** His paws, held a pixel above the mound's rim so the muted pixels do not touch it. */
+const waiting = (shown) => (open) => paint(digby(1, { eyes: open ? "wide" : "none" }), [[8, 4, "mm"], [8, 10, "mm"], ...sign(shown)]);
+const stalled = (dots) => () => paint(digby(0.7, { eyes: "shut", slump: true }), [[5, 0, dots]]);
+/** The letter held up on his arm, which stops a pixel above the mound so it does not touch it, and the spark beside him. */
+const report = (rise, spark) => (open) => paint(digby(rise, { eyes: open ? "open" : "none" }), [
+    [0, 12, "aaaa"],
+    [1, 12, "akka"],
+    [2, 12, "aaaa"],
+    ...post(3, 13, 8, "m"),
+    ...spark.map((row, at) => [1 + at, 0, row]),
+]);
+/** The 16×16's frames by state but idle, each its pixels with the eyes open or, for a blink, not; the first reads alone. */
+export const ART = {
+    spawn: [
+        () => spawn(true, [[3, 1, "m"], [5, 3, "m"], [2, 14, "m"], [5, 12, "m"]]),
+        () => spawn(false, [[1, 0, "m"], [4, 2, "m"], [3, 15, "m"], [6, 13, "m"]]),
+    ],
+    running: [
+        () => running(0.22, 0, [[5, 2, "m"], [7, 1, "m"], [4, 13, "m"], [6, 14, "m"]]),
+        () => running(0.12, 1, [[3, 1, "m"], [6, 3, "m"], [5, 12, "m"], [3, 15, "m"]]),
+    ],
+    waiting: [waiting(true), waiting(false)],
+    stalled: [stalled("e.e.e"), stalled("e"), stalled("e.e")],
+    report: [report(1, [".s.", "sss", ".s."]), report(1.25, ["s.s", ".s.", "s.s"]), report(1.1, [".s.", "sss", ".s."])],
+    gone: [() => digby(-0.3, { mound: "m" })],
+};
+/** Where idle's `z` drifts up, by cell line, one step per mascot frame, then gone a frame. */
+const Z_LINES = [3, 2, 1, undefined];
+/** The 16×16 idle Digby at mascot frame `frame`, its first with none: the mound breathing, a `z` drifting up beside it. */
+export function idleArt(frame) {
+    const lines = cells(digby(-0.3, { top: frame !== undefined && breathesOut(frame) ? 8 : 6 }));
+    const line = Z_LINES[(frame ?? 0) % Z_LINES.length];
+    if (line === undefined)
+        return lines;
+    return lines.map((cellsOf, at) => (at === line ? cellsOf.map((one, column) => (column === 13 ? { char: "z", fg: "m" } : one)) : cellsOf));
+}
+/** The 16×16 Digby for `state` at mascot frame `frame`, its first frame with none: animations off. */
+export function art(state, frame) {
+    if (state === "idle")
+        return idleArt(frame);
+    const frames = ART[state];
+    return cells(frames[(frame ?? 0) % frames.length](!(frame !== undefined && OPEN_EYES.has(state) && blinks(frame))));
+}

package/dist/tree/panel.d.ts

@@ -1,4 +1,4 @@
-import type { CourierPorts, Pending, ShownForm } from "./ports.js";
+import type { CourierPorts, ModelWindow, Pending, ShownForm } from "./ports.js";
 import type { Tree, Wait } from "./rpc.js";
 type Messages = Awaited<ReturnType<CourierPorts["session"]["context"]>>;
 /** The last tool call in a session's messages, and when it was made. */
@@ -6,6 +6,8 @@ export declare function lastTool(messages: Messages): {
     name: string;
     at: number;
 } | undefined;
+/** How full a session's context is, as OpenCode's session view reads it (packages/tui/src/util/session.ts, v2.0.32): the last usage since the last compaction over its model's window. */
+export declare function contextOf(messages: Messages, windows: ReadonlyArray<ModelWindow>): number | undefined;
 /** A request as the panel says what a paused session waits on: a permission request, or its first question. */
 export declare const waitOf: (pending: Pending) => Wait;
 /** A form a session shows, as the panel says what it waits on. */

package/dist/tree/panel.js

@@ -15,6 +15,17 @@ 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.0.32): the last usage since the last compaction over its model's window. */
+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);
+    if (last?.type !== "assistant" || !last.tokens)
+        return undefined;
+    const { input, output, reasoning, cache } = last.tokens;
+    const used = input + output + reasoning + cache.read + cache.write;
+    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] }
@@ -44,8 +55,8 @@ 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 and its cost. */
-async function row(ports, { entry, depth, info, pending, forms, report }, stalled) {
+/** 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, pending, forms, report }, stalled) {
     const { sessionID } = entry;
     const [messages, status, standing, stopped] = await Promise.all([
         ports.session.context({ sessionID }).catch(() => []),
@@ -55,6 +66,7 @@ async function row(ports, { entry, depth, info, pending, forms, report }, stalle
     ]);
     const running = info !== undefined && busy(info.time);
     const tool = lastTool(messages);
+    const context = contextOf(messages, windows);
     return {
         sessionID,
         parentID: entry.parentID,
@@ -70,6 +82,7 @@ async function row(ports, { entry, depth, info, pending, forms, report }, stalle
         created: info?.time.created ?? entry.createdAt,
         ...(info && !running && info.time.idle !== undefined ? { idle: info.time.idle } : {}),
         ...(info ? { cost: info.cost } : {}),
+        ...(context !== undefined ? { context } : {}),
         ...(tool ? { tool } : {}),
         waits: [...pending.map(waitOf), ...forms.map(formWait)],
     };
@@ -81,7 +94,8 @@ async function row(ports, { entry, depth, info, pending, forms, report }, stalle
 export async function panel(ports, rootID) {
     const { kept, leftOut } = await readTree(ports, rootID);
     const stalled = await stalledAmong(ports, [rootID, ...kept.map((node) => node.entry.sessionID)]);
-    const rows = await Promise.all(kept.map((node) => row(ports, node, stalled.get(node.entry.sessionID))));
+    const windows = await ports.windows().catch(() => []);
+    const rows = await Promise.all(kept.map((node) => row(ports, windows, node, stalled.get(node.entry.sessionID))));
     const own = stalled.get(rootID);
     return { rows, ...(leftOut ? { truncated: leftOut } : {}), ...(own !== undefined ? { stalled: own } : {}) };
 }