opencode-courier 0.7.3 → 0.9.0

package/README.md

@@ -38,49 +38,44 @@ If OpenCode asks to allow a child's command, the parent passes the question to y
 sometimes stall on a request; if nothing moves for a few minutes, send the prompt again. Next:
 [Using it](#using-it).
 
-
 ## OpenCode V2 native
 
 Courier is built on OpenCode V2's plugin API (`@opencode/plugin`), not the V1 one
-(`@opencode-ai/plugin`), and needs OpenCode V2. Each release is pinned to one V2 version and tested
-against it end to end; the current one is tested on **OpenCode 2.0.32**. CI also runs the live
-suite on the newest OpenCode release, on `main` and nightly, so a host release that breaks the
-plugin shows up there first. Older releases and their versions: [every release](docs/reference.md#the-opencode-version).
+(`@opencode-ai/plugin`). Each release is pinned to one V2 version and tested against it end to end;
+the current one is tested on **OpenCode 2.0.32**. CI also runs the live suite on the newest OpenCode
+release, on `main` and nightly. Older releases: [every release](docs/reference.md#the-opencode-version).
 
 ## Courier or the built-in subagent tool?
 
-OpenCode V2 has its own [`subagent` tool](https://opencode.ai/v2/docs/agents): it starts an agent
-with fresh context in a child session, and the parent either waits for its final answer or, with
-`background: true`, carries on and is notified when the child finishes; passing the child's
-`sessionID` back prompts it again. Use it when one result back is all you need: a search, a review,
-a self-contained task that needs nothing from you on the way. Use courier when the work needs more:
+OpenCode V2's own [`subagent` tool](https://opencode.ai/v2/docs/agents) starts an agent with fresh
+context in a child session; the parent waits for its final answer or, with `background: true`, is
+notified when the child finishes. Use it when one result back is all you need. Use courier when the
+work needs more:
 
-- **Messages from the child, mid-run:** a child reports progress, or asks its parent something,
+- **Messages from the child, mid-run:** a child reports progress or asks its parent something
   whenever it likes with `courier_send`, and any session can message any other.
 - **Waking an idle session from anywhere:** a message from a child, a schedule (`courier_later`) or
-  a [webhook](#webhooks) (GitHub reviews, comments and CI runs, or any signed POST) starts a new turn
-  in a session that has ended its own.
-- **Worktree isolation:** `isolate: true` gives a child its own git worktree, so children can edit
-  files in parallel; each commits on `courier/<its session ID>` and reports that branch for its
-  parent to merge ([nested isolation](docs/reference.md#nested-isolation)).
-- **Relaying to you:** a child's permission requests and questions reach you through the parent:
-  a request is approved in OpenCode's own permission prompt in the parent's session, never by its
-  model, and your answers go back; a form only you can answer is pointed out to you.
+  a [webhook](#webhooks) starts a new turn in a session that has ended its own.
+- **Worktree isolation:** `isolate: true` gives a child its own git worktree, so children edit files
+  in parallel; each commits on `courier/<its session ID>` and reports that branch for its parent to
+  merge ([nested isolation](docs/reference.md#nested-isolation)).
+- **Relaying to you:** a child's permission requests and questions reach you through the parent. A
+  request is approved in OpenCode's own permission prompt in the parent's session, never by its
+  model; a form only you can answer is pointed out to you.
 
 ## How it works
 
-A parent session calls `courier_spawn`, gets a session id back immediately and ends its turn. The
-child works on its own and, when it is done or stuck, calls `courier_send` with the parent's id, a
-status and what it produced. That message lands in the parent's inbox and OpenCode starts a new turn
-for the parent if it is idle. There is no polling anywhere: a message is admitted into the target
-session's inbox through OpenCode's own API, the way OpenCode's background subagents report to their
-parent. Delivery is `steer` by default (injected into the target's running turn, or starts one if
-idle); `queue: true` waits until the current turn ends.
+A parent calls `courier_spawn`, gets a session id back at once and ends its turn. The child works
+on its own and, when done or stuck, calls `courier_send` with the parent's id, a status and what it
+produced. The message lands in the parent's inbox through OpenCode's own API, the way OpenCode's
+background subagents report, and starts a new turn if the parent is idle. Delivery is `steer` by
+default (into the target's running turn, or a new one if idle); `queue: true` waits until the current
+turn ends.
 
 ## Demos
 
-The video at the top (1:46, narrated) is the TUI driven in `tmux` on the scripted stand-in model of
-the live test, with `e2e/tui.sh`'s setup, so each scene is real plugin behaviour:
+The video at the top (1:46, narrated) is the TUI driven in `tmux` on the live test's scripted
+stand-in model, so each scene is real plugin behaviour:
 
 - **A join group:** one member reports and its report is held with the group, while the other waits
   on a permission request, so the footer says one is waiting on you. You allow it from the asks inbox
@@ -95,11 +90,10 @@ the live test, with `e2e/tui.sh`'s setup, so each scene is real plugin behaviour
 ## Recursive orchestration
 
 A session can split a goal across child sessions, each child deciding in turn whether to split its
-part again, with the results checked and integrated at every level on the way back up. The plugin
-ships the playbook as an OpenCode skill, `courier-orchestrate`, listed in every session: models are
-told to load it at the start of an implementation task that may have independent parts, and
-`/skills` in the TUI attaches it to your prompt. What it says: [the
-reference](docs/reference.md#the-courier-orchestrate-skill).
+part again, with the results checked and integrated at every level on the way back up. The playbook
+ships as the OpenCode skill `courier-orchestrate`, listed in every session: models load it at the
+start of an implementation task that may have independent parts, and `/skills` in the TUI attaches
+it to your prompt ([what it says](docs/reference.md#the-courier-orchestrate-skill)).
 
 ## Install
 
@@ -107,14 +101,14 @@ reference](docs/reference.md#the-courier-orchestrate-skill).
 
 Requires OpenCode V2: the `opencode` command from `@opencode/cli` (also installed as `opencode2`).
 Each release is built and tested against exactly one OpenCode V2 version; a row lists the releases
-pinned to its version. OpenCode never checks it:
-the plugin installs and loads on any V2 host, and on a version other than the pinned one writes one
-line to the server log naming both ([more](docs/reference.md#the-opencode-version)).
+pinned to its version. OpenCode never checks it: the plugin loads on any V2 host, and on another
+version than the pinned one writes one line to the server log
+([more](docs/reference.md#the-opencode-version)).
 
 <!-- compat-table:start rows=3: generated by script/compat-table.ts from the release tags -->
 | opencode-courier | OpenCode V2 (`opencode` and `@opencode/plugin`) |
 |---|---|
-| 0.7.3 | 2.0.32 |
+| 0.7.3, 0.8.0, 0.9.0 | 2.0.32 |
 | 0.7.2 | 2.0.31 |
 | 0.7.1 | 2.0.30 |
 <!-- compat-table:end -->
@@ -122,7 +116,7 @@ line to the server log naming both ([more](docs/reference.md#the-opencode-versio
 Older releases and their versions: [every release](docs/reference.md#the-opencode-version).
 
 The [terminal part](#in-the-terminal) relies on the host to provide its UI modules and is tested on
-OpenCode 2.0.32 only; the server part works as before on older V2 hosts from 2.0.4 on.
+OpenCode 2.0.32 only; the server part works on older V2 hosts from 2.0.4 on.
 
 Check yours with `opencode --version`, and install the matching CLI with:
 
@@ -139,9 +133,8 @@ opencode plugin add opencode-courier
 This installs the package from npm and adds `"opencode-courier"` to `plugins` in the global
 configuration (`~/.config/opencode/opencode.json`); its options ([session trees](#session-trees),
 [webhooks](#webhooks)) go in the object form of that entry. Install it by name, without a version:
-OpenCode only checks plugins for updates when their entry is not an exact version, so
-`opencode-courier@0.2.1` is never offered a newer release ([moving such an
-entry](docs/reference.md#updating-the-plugin)).
+OpenCode only checks plugins for updates when their entry is not an exact version
+([updating](docs/reference.md#updating-the-plugin)).
 
 From a local clone, `bun install && npm run build`, then list its `dist` **directory** in
 `opencode.json` (V2 uses `plugins`, plural; a path to a file is ignored with a warning):
@@ -155,14 +148,15 @@ From a local clone, `bun install && npm run build`, then list its `dist` **direc
 ## Using it
 
 1. Keep the background server running so sessions can be woken while you are away (`opencode
-   service start`), and run one OpenCode server per data directory where you can: a second one, such
-   as `opencode serve` next to it, cannot pass your answer on to a child the other runs
+   service start`), and run one OpenCode server per data directory where you can: a second one
+   cannot pass your answer on to a child the other runs
    ([why](docs/reference.md#two-servers-on-one-data-directory)).
 2. Give the agents that run children the permissions their work needs: a child that hits an approval
-   prompt waits until you answer OpenCode's prompt for it in the parent's session. Let them use the `question` tool if they
-   should be able to ask you. Choose a web search provider before children search the web (run one
-   web search in your own session, or use OpenCode's "Third-party search" setting), or the first
-   child to search shows that prompt in its own session, which only you can answer there.
+   prompt waits until you answer OpenCode's prompt for it in the parent's session. Let them use the
+   `question` tool if they should be able to ask you. Choose a web search provider before children
+   search the web (run one web search in your own session, or use OpenCode's "Third-party search"
+   setting), or the first child to search shows that prompt in its own session, which only you can
+   answer there.
 3. Your own session's prompts are relayed nowhere, and each one stalls the whole tree until you
    answer it. Before an unattended run, allow the orchestrating session's toolchain up front: one rule
    on `bun run *` or `npm run *` (the skill has checks run through the project's scripts), `git`, and
@@ -191,38 +185,33 @@ From a local clone, `bun install && npm run build`, then list its `dist` **direc
 | `courier_cancel` | Drops a message scheduled with `courier_later`. |
 | `courier_subscribe` | Subscribes a session to webhook deliveries for a topic (`owner/repo`, `owner/repo#12` or a name). |
 | `courier_unsubscribe` | Drops one topic, or all of a session's. |
+| `courier_recall` | One look at what earlier session trees in this project did and the lesson each left; with `sessionID`, one tree's [record](#memory) in full. |
+| `courier_note` | Writes this tree's one lesson on its [record](#memory), for the next orchestrator in the project: one line of at most 300 characters, naming the job and the reason. A longer one is refused, a second call replaces the first. From the top or a sub-orchestrator, never a leaf. |
 
 Each tool's parameters: [the reference](docs/reference.md#the-tools).
 
 ## How children reach you
 
 - **A child reports once, with a status**: `done`, `partial`, `blocked` (it needs a decision from
-  its parent, and says what) or `failed`, with its artifacts (branch, commits, files, checks) listed
-  in the message. A message without a status is progress, not the report.
-  [More](docs/reference.md#a-childs-report).
+  its parent, and says what) or `failed`, with its artifacts in the message. A message without a
+  status is progress, not the report. [More](docs/reference.md#a-childs-report).
 - **A join group wakes you once.** Start a batch of sessions with the same `group` name, and their
-  `done`, `partial` and `failed` reports are held until the last one is in and your turn has ended,
-  then delivered in one message. A `blocked` report, a failure, a question or a permission request
-  still reaches you at once. A member that will not report holds the others back: drop it with
-  `courier_cleanup`, and the group is released without it. [More](docs/reference.md#join-groups).
-- **A child that fails, or ends its turn without reporting, is reported** to its parent by the
-  plugin, with the error or its last reply, waking it if idle; one that waits on a request, its own
-  children, a scheduled message or a webhook is not, nor is one that answers what you typed in its
-  session. [More](docs/reference.md#a-child-that-fails).
-- **A message that fails to wake its session is sent again.** A report, notice or scheduled message
-  (but not a note that a request was answered elsewhere) that waits in an idle session's inbox for 30 seconds without a turn starting for it is sent once
-  more under the same inbox id, which OpenCode takes for the same message, not a second one. If the
-  session still does not take it, the footer and the tree panel show it as `stalled`, for you to
-  prompt it. [More](docs/reference.md#a-missed-wake).
-- **Permission requests and questions reach you.** A child's request or question is passed to the
-  session at the top of its tree, any number of levels down. For a request, that session proposes an
-  answer with `courier_answer`, and OpenCode asks you in its own permission prompt, in that session
-  and under its rules, before anything is passed on: its model cannot approve, only propose. For a
-  question, it asks you and passes your answer back, or links its own question to the child's so your
-  pick goes straight to it. Whichever answer comes first counts, and the other is withdrawn.
-  A request starts a turn in the top session if it is idle; if you answer it somewhere else, the
-  note that it is settled waits for that session's next turn, usually the child's report or its
-  silence, instead of starting one of its own. [More](docs/reference.md#a-child-that-asks-for-permission).
+  `done`, `partial` and `failed` reports are held until the last one is in, then delivered in one
+  message; a `blocked` report, a failure, a question or a permission request still reaches you at
+  once. A member that will not report holds the others back: drop it with `courier_cleanup`.
+  [More](docs/reference.md#join-groups).
+- **A child that fails, or ends its turn without reporting, is reported** to its parent, with the
+  error or its last reply, unless it waits on a request, its own children, a scheduled message or a
+  webhook. [More](docs/reference.md#a-child-that-fails).
+- **A message that fails to wake its session is sent again** after 30 seconds; if the session still
+  does not take it, the footer and the tree panel show it as `stalled`, for you to prompt it.
+  [More](docs/reference.md#a-missed-wake).
+- **Permission requests and questions reach you** through the session at the top of the tree, any
+  number of levels down. For a request, that session proposes an answer with `courier_answer`, and
+  OpenCode asks you in its own permission prompt there before anything is passed on: its model
+  cannot approve, only propose. For a question, it asks you and passes your answer back, or links
+  its own question to the child's so your pick goes straight to it.
+  [More](docs/reference.md#a-child-that-asks-for-permission).
 - **Some forms only you can answer**, such as OpenCode's web search asking for a provider: the top
   session is told, and you answer in the child's session. [More](docs/reference.md#a-child-that-shows-a-form).
 - **You can see and stop a whole subtree** with `courier_tree` and `courier_stop`, or in the
@@ -249,49 +238,52 @@ options in the plugin's `options`, in the global config:
 | `maxChildren` | `5` | How many sessions one session started may have live at once. |
 | `maxTotal` | `20` | How many spawned sessions may be live at once in one tree. |
 
-`courier_spawn` refuses a spawn past a limit, naming it and saying what to do instead: do the work
-itself, or wait for a child to report. A session counts while it is live: its turn runs, it owes
-its parent a report (its task or a message reached it after it last reported, failed or was
-interrupted), or a session below it is live. One that has reported, with nothing live below it,
-does not. Each spawned session's brief says when to split its task and when to do it itself
+`courier_spawn` refuses a spawn past a limit, naming it and saying what to do instead. A session
+counts while it is live: its turn runs, it owes its parent a report, or a session below it is live.
+Each spawned session's brief says when to split its task and when to do it itself
 ([more](docs/reference.md#session-trees-and-their-limits)).
 
+## Memory
+
+The plugin keeps **one record per session tree** in the project, from facts it already has: when the
+tree started and last moved, the top session's title and first `split:` line, with up to 3 later ones
+that read otherwise (when each was stated, and after how many parts), and for each session started
+in the tree its title, depth, isolation, join group, status, duration, cost, context use and spawns
+refused; never a report's body or artifacts. A session deleted since keeps its last status and
+duration, or reads `gone` when it had not settled, so it never holds its tree at `not finished`.
+The one thing a model writes into it is **the tree's
+lesson**, with `courier_note`: one line of at most 300 characters, from the session that verified the
+tree, with the job it comes from and the reason. `courier_recall` reads the records back, each line
+showing the split line as prose (its markdown marks dropped, the asterisks of its globs kept) cut at a
+word, then the latest later one (`then, after 1 part: split: 2 parts: …`), and saying how long the tree ran and how long ago it last moved; the `courier-orchestrate` skill asks for
+one call before the split decision and one `courier_note` before the top replies. Each record counts
+how often other trees' `courier_recall` calls listed it and opened it in full, and when last, so the
+person can tell a lesson still read from one nobody reads; a record the person pins in the terminal
+is listed first and never swept. Each project keeps 30 unpinned records, those with a lesson first,
+and none older than 90 days. `"memory":
+false` in the plugin's `options` turns it off ([more](docs/reference.md#memory)).
+
 ## In the terminal
 
-The package ships a part for OpenCode's terminal UI, which the TUI loads from the server's plugin
-list; the server half behaves the same whether or not a TUI is attached. In a session that started
-sessions, the prompt's footer shows what the tree under it is doing: how many wait on you (a
-permission request, a question or a form they show), are [stalled](docs/reference.md#a-missed-wake),
-run or are idle, and for each [join group](docs/reference.md#join-groups) how many of its members have
-reported:
+The package ships a part for OpenCode's terminal UI, loaded from the server's plugin list; the server
+half behaves the same with or without it. In a session that started sessions, the prompt's footer
+shows what the tree under it is doing: how many wait on you (a permission request, a question or a
+form), are [stalled](docs/reference.md#a-missed-wake), run or are idle, and each
+[join group](docs/reference.md#join-groups)'s members reported:
 
 ```
 courier 1 waiting on you · 2 running · group pair 1/2
 ```
 
-`/courier tree` opens a panel beside the session with the tree under it, a row per session indented
-by depth, with a mark and colour from your theme for its state (`✓` reported, a spinner `⠋` while it runs, `●` waiting on you, `!` stalled,
-`✗` failed or interrupted), what it does, its report and its group's standing; a session waiting on you gets a line per
-request or form (`shows a form: Web Search`), a stalled one since when its message waits, a session that started others gets
-a bar of the parts reported, a leaf how long it ran, its last tool call, how full its context is (`ctx 31%`, in the warning colour past 80%) and its cost. A tree that has
-started more than `maxTotal` sessions over time is listed live ones first, then newest, and the header
-says how many older ones are left out; the footer counts them all. `↑`/`↓` select,
-`enter` or a click opens the session, a row under the pointer is highlighted, `s` stops it and everything under it after you confirm, as `courier_stop`
-would, `x` forgets a `gone` session after you confirm, removing its worktree by `courier_cleanup`'s
-rules, and `q` closes the panel; `/courier stop <session>` stops from the prompt. While open, the panel
-follows you between sessions: into one of its tree it keeps that tree, the session on screen marked
-`(on screen)`; elsewhere it shows that session's tree, or hides while you are in a session without one,
-or on the home screen, and shows again once you are back in one; only `q` closes it for good.
-A row whose report arrives flashes in your theme's success colour and fades back over 1.5 s, and the header's bar
-grows to its new length; nothing in the footer moves. Next to the header's title digs Digby, the courier's mole, drawn
-in your theme's colours, whose state follows the tree's: a breathing mound while all is idle, a trembling one while
-children run, up with a blinking sign while one waits on you, slumped while one is stalled, popping up with a letter
-for a report and raising mounds for a spawn. Where the panel has room the tree does not use, on an empty panel or 10
-rows free below the last row, a larger Digby, 16 by 8, shows the same state there instead, paws, sign, letter and all
-([more](docs/reference.md#in-the-terminal)).
-To keep the panel still (`•` for a running row, no flash, the bar at once, Digby in each state's first frame), give the TUI part `"animations": false` in OpenCode's terminal config, `~/.config/opencode/cli.json`:
-the TUI passes options to its plugins only from there, not from the server's `opencode.json`, and has no animations
-setting a plugin can read ([more](docs/reference.md#in-the-terminal)).
+`/courier tree` opens a panel beside the session with the tree under it, a row per session with a
+mark for its state (`✓` reported, a spinner while it runs, `●` waiting on you, `!` stalled, `✗`
+failed or interrupted), what it does, its report, its group's standing and, for a leaf, how long it
+ran, its last tool call, its context use and its cost. `enter` or a click opens the session, `s`
+stops it and everything under it, `x` forgets a `gone` session, `q` closes the panel;
+`/courier stop <session>` stops from the prompt. Digby, the courier's mole, digs beside the header,
+his state following the tree's. `"animations": false` in the TUI part's options keeps the panel
+still; the TUI reads a plugin's options only from its own config, `~/.config/opencode/cli.json`
+([more](docs/reference.md#in-the-terminal)):
 
 ```jsonc
 {
@@ -299,40 +291,31 @@ setting a plugin can read ([more](docs/reference.md#in-the-terminal)).
 }
 ```
 
-`ctrl+x k` (the leader key, then `k`), `/asks` (or `/ask`), the palette's "Courier: what waits on you" or a click
-on "waiting on you" opens the asks inbox: every permission request, question and form waiting
-anywhere in the tree, however many sessions it has, oldest first, after the top session's own permission
-requests, such as the prompt `courier_answer` has OpenCode show there, with where it comes from, kept current
-while it is open as asks arrive or are settled elsewhere, answered in a dialog with no model in between; the session that started the tree hears once that you settled it. The TUI plays OpenCode's
-sounds for a child's report and a group's release, and OpenCode's own for a new ask, which the courier
-adds a notification to for a native child ([more](docs/reference.md#in-the-terminal)).
-
-While a permission prompt or form is shown in the session, OpenCode hides the footer, so open the
-inbox with `ctrl+x k` (or `/asks` once the prompt is back).
+`ctrl+x k` (the leader key, then `k`), `/asks` (or `/ask`), the palette's "Courier: what waits on
+you" or a click on "waiting on you" opens the asks inbox: every permission request, question and form
+waiting anywhere in the tree, after the top session's own permission requests, with where each comes
+from, kept current while open and answered in a dialog with no model in between.
+The TUI plays OpenCode's sounds for a child's report, a group's release and a new ask. While a
+permission prompt or form is shown in the session, OpenCode hides the footer, so open the inbox with
+`ctrl+x k`.
+
+`/courier memory` (or the palette's "Courier: memory") lists the project's [tree records](#memory),
+pinned first, then newest first grouped by the day each tree last moved, one row each with how often
+other trees read it and its lesson under it. `enter` shows one in full; `p` pins or unpins the record,
+and a pinned one is listed first and never swept; `x` forgets the record under the row, or in a
+record on its lesson's rows only the lesson, after a confirm; `esc` goes back and closes. The search
+takes every letter but `x` and `p` ([more](docs/reference.md#the-memory-view)).
 
 ## Native child sessions
 
 Off by default. With `"nativeChildren": true` in the plugin's `options`, a child started without
 `isolate` is also created with OpenCode's own `parentID`, so OpenCode treats it as the parent's
-subagent: the TUI's view of the top session lists and answers the permission requests and forms of
-every session under it, and the paired web, desktop or mobile app's request dock answers a
-grandchild's ask from the top session, on a phone too. Isolated children are created as before, and
-the courier's own tree, limits and relays work as without the option. What changes
-([more](docs/reference.md#native-child-sessions)):
-
-- **Deleting a session deletes its native children**, as OpenCode does with subagents.
-- **A child does not take its parent's session rules**: courier passes it an empty ruleset, so it
-  may do what it could without the option.
-- **Providers see a subagent**: the child's model requests carry its parent's id for cache routing
-  and two headers naming the parent; **on GitHub Copilot**, which meters such requests differently
-  from a person's, courier was not tested.
-- **A child's asks show in the top session's view**, not in its own, and it leaves the TUI's session
-  lists. Its permission requests and questions are answered once, in OpenCode's own prompt there; the
-  top session's model is only told. `opencode run` and the TUI's auto-accept mode answer them as their
-  own subagents'.
-- **Turn it on only with OpenCode's TUI or the paired app**, which show those prompts; with a bare
-  API client nobody prompts you, and only `courier_answer` is left, which prompts you in the top
-  session before it passes anything on.
+subagent: the TUI's view of the top session, and the paired app's request dock, list and answer the
+permission requests, questions and forms of every session under it, and the top session's model is
+only told. Deleting a session then deletes its native children, the child gets an empty ruleset
+rather than its parent's, and providers see a subagent (not tested on GitHub Copilot). Turn it on
+only with OpenCode's TUI or the paired app, which show those prompts
+([more](docs/reference.md#native-child-sessions)).
 
 ## Webhooks
 
@@ -363,7 +346,7 @@ every default):
    arrives as a short summary marked as outside text, queued behind any running turn and waking the
    session if idle.
 
-The options, which events wake whom, the tunnels, the signing scheme and status codes: [the
+The options, which events wake whom, the signing scheme and status codes: [the
 reference](docs/reference.md#webhooks).
 
 ## Development

package/dist/index.js

@@ -8,6 +8,7 @@ import { hub, openInProcess, permissions as domains, sharedState } from "./platf
 import { builtVersions, versionNotice } from "./platform/version.js";
 import { addSchedulingTools, cancelScheduled, dueJob, isScheduled } from "./scheduling/index.js";
 import { addPersonTools, asksPermission, asksQuestion, formsShown, joinRelay, noticeCutOff, pendingOf, pendingQuestions, personEvents, portsAt, registerPersonRpc, relayQuestions, } from "./person/index.js";
+import { addMemoryTools, memoryEvents, NOTE_TOOL, readMemory, RECALL_TOOL, registerMemoryRpc, sweepRecords } from "./memory/index.js";
 import { addSkill } from "./skill.js";
 import { addTreeTools, deliverReleased, wakeMissed, dirtyOf, headOf, inspectWorktree, pruneExpired, readLimits, readNativeChildren, registerTreeRpc, shapeContext, together, treeEvents, waitsOn, } from "./tree/index.js";
 import { addWebhookTools, joinReceiver, readConfig, receiving, subscribedSince, } from "./webhook/index.js";
@@ -17,6 +18,8 @@ const gate = sharedState("spawning", () => ({ reserved: new Set(), turn: Promise
 const inbox = sharedState("inbox", () => new Map());
 /** The forms shown now, which the person events keep and the footer and tree panel count; outside the hub like the inbox. */
 const shown = sharedState("formsShown", () => new Map());
+/** What the memory shares: the models' windows, the locations with memory off, the tops that recalled and the turn ends recorded. */
+const memoryState = sharedState("memory", () => ({ windows: new Map(), off: new Set(), tops: new Set(), seen: new Set() }));
 /**
  * What each tick of the scheduler does, in order, through the first loaded member, of whichever copy:
  * due `courier_later` messages, released join groups, then missed wakes. Every hub-v2 member's `later` is its LaterPorts.
@@ -40,7 +43,7 @@ const personState = { ...watched, forms: hub.forms, shown };
  */
 const outside = waitsOn(asksPermission, asksQuestion, together(isScheduled, subscribedSince));
 /** What the hub's subscriptions do with each event of OpenCode's, module by module, in this order. */
-const eventModules = [treeEvents(watchState, outside), personEvents(personState)];
+const eventModules = [treeEvents(watchState, outside), personEvents(personState), memoryEvents(memoryState)];
 /**
  * The courier tools and webhook receiver, as a promise plugin joining the hub that runs the scheduler
  * and the watcher; its member carries the location by which the question relay finds its ports.
@@ -70,7 +73,8 @@ export const courier = () => Plugin.define({
         };
         const { limits, problems } = readLimits(ctx.options);
         const { nativeChildren, problems: nativeProblems } = readNativeChildren(ctx.options);
-        for (const problem of [...problems, ...nativeProblems])
+        const { memory, problems: memoryProblems } = readMemory(ctx.options);
+        for (const problem of [...problems, ...nativeProblems, ...memoryProblems])
             log(`courier: ${problem}`);
         const roles = new Map();
         const ports = {
@@ -117,21 +121,32 @@ export const courier = () => Plugin.define({
             later.log(`courier webhook: not started: ${error instanceof Error ? error.message : String(error)}`);
         }
         const stopPorts = { courier: ports, cancelScheduled: (sessionID) => cancelScheduled(later, sessionID), cleanup: cleanupPorts };
-        // The tools in a fixed order: the tree's, then the person's, the scheduled messages' and the webhooks'.
+        const memoryPorts = { storage: ctx.storage, session: ctx.session, now: Date.now, log, projectID: ctx.location.project.id, memory, maxDepth: limits.maxDepth };
+        // The tools in a fixed order: the tree's, then the person's, the scheduled messages', the webhooks' and the memory's.
         await ctx.tool.transform((tools) => {
             addTreeTools(tools, { courier: ports, cleanup: cleanupPorts, stop: stopPorts });
             addPersonTools(tools, { answer: answerPorts, questions: questionPorts, waiting: watched.waiting });
             addSchedulingTools(tools, later);
             addWebhookTools(tools, { hooks, receiving });
+            addMemoryTools(tools, { memory: memoryPorts, state: memoryState });
         });
         await ctx.skill.transform(addSkill);
         // What the TUI part reads and its stop; a host that cannot register it still gets the rest, the tools included.
         await Promise.resolve()
             .then(() => registerTreeRpc(ctx.rpc, stopPorts))
             .then(() => registerPersonRpc(ctx.rpc, { questions: questionPorts, permissions }))
+            .then(() => registerMemoryRpc(ctx.rpc, memoryPorts))
             .catch((error) => log(`courier rpc: not registered, the TUI part shows nothing and cannot stop: ${String(error)}`));
-        await ctx.session.hook("context", (event) => shapeContext({ storage: ctx.storage, limits, roles, log }, event));
+        await ctx.session.hook("context", (event) => shapeContext({ storage: ctx.storage, limits, roles, hiddenFromLeaf: [RECALL_TOOL, NOTE_TOOL], log }, event));
         const pruned = pruneExpired(ctx.storage, Date.now()).catch((error) => log(`courier roster prune: ${String(error)}`));
+        const swept = sweepRecords(ctx.storage, Date.now()).catch((error) => log(`courier memory sweep: ${String(error)}`));
+        // The windows the memory reads each part's context use by; a tree whose top runs in a location with memory off is not recorded.
+        const windowed = ports
+            .windows()
+            .then((windows) => windows.forEach((window) => memoryState.windows.set(`${window.providerID}/${window.id}`, window)))
+            .catch((error) => log(`courier memory: cannot list the models' context windows: ${String(error)}`));
+        if (!memory)
+            memoryState.off.add(ctx.location.directory);
         const leaveRelay = joinRelay(questionPorts);
         const noticed = noticeCutOff(questionPorts).catch((error) => questionPorts.log(`courier question: stored questions: ${String(error)}`));
         const watchPorts = {
@@ -158,11 +173,15 @@ export const courier = () => Plugin.define({
         // The leave waits for them, so they do not run on against a location that is closing.
         track(member, pruned);
         track(member, noticed);
+        track(member, swept);
+        track(member, windowed);
         const leave = webhook ? joinReceiver(webhook, hooks) : undefined;
         return async () => {
             // Waits, for a moment at most, for the work this instance leaves behind, and on the last
             // leave for the scheduler's owner key to be released, so another server takes over at once.
             const leftHub = leaveHub();
+            if (!memory)
+                memoryState.off.delete(ctx.location.directory);
             leaveRelay();
             await leave?.();
             await leftHub;

package/dist/kernel/protocol.d.ts

@@ -14,6 +14,8 @@ export declare const SPLIT_LINE = "split: no, because \u2026; considered: <the p
 export declare const SKILL_ID = "courier-orchestrate";
 export declare function envelope(from: string, message: string, attributes?: Record<string, string>): string;
 export declare function clipText(text: string, max?: number): string;
+/** `clipText` cut at the last space within `max` instead, so no word is cut in two, unless that keeps less than half of `max`. */
+export declare function clipWords(text: string, max: number): string;
 /** Defuses `<courier` and `</courier>` in outside text, so it cannot close the envelope or forge another. */
 export declare function defuse(text: string): string;
 /** A readable message for a failed courier call; OpenCode's own errors can carry an empty message. */

package/dist/kernel/protocol.js

@@ -19,8 +19,16 @@ export function envelope(from, message, attributes = {}) {
 }
 /** Longest piece of free text (a review body, a generic payload) copied into a delivered message. */
 const MAX_TEXT = 1500;
+const clipped = (text, kept) => `${kept}… [${text.length - kept.length} more characters]`;
 export function clipText(text, max = MAX_TEXT) {
-    return text.length > max ? `${text.slice(0, max)}… [${text.length - max} more characters]` : text;
+    return text.length > max ? clipped(text, text.slice(0, max)) : text;
+}
+/** `clipText` cut at the last space within `max` instead, so no word is cut in two, unless that keeps less than half of `max`. */
+export function clipWords(text, max) {
+    if (text.length <= max)
+        return text;
+    const space = text.lastIndexOf(" ", max);
+    return clipped(text, (space >= max / 2 ? text.slice(0, space) : text.slice(0, max)).trimEnd());
 }
 /** Defuses `<courier` and `</courier>` in outside text, so it cannot close the envelope or forge another. */
 export function defuse(text) {