opencode-courier 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivo Pogace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,303 @@
-# Temporary Holding Version
+# opencode-courier
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/ivopogace/opencode-courier/actions/workflows/ci.yml/badge.svg)](https://github.com/ivopogace/opencode-courier/actions/workflows/ci.yml)
+
+An [OpenCode](https://github.com/anomalyco/opencode) V2 plugin that lets one session start other
+sessions, message them, and be woken by them, without polling.
+
+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.
+That message lands in the parent's inbox and OpenCode starts a new turn for the parent if it is
+idle.
+
+> **Status: early.** Passes an end-to-end test inside a live OpenCode V2 server
+> (`opencode2 v0.0.0-beta-19271`) driven by a scripted stand-in model (`e2e/run.sh`); not yet
+> tried with a real model.
+
+## How the wake works
+
+There is no polling anywhere. `courier_send` calls the plugin API's `session.synthetic`, which
+admits a message into the target session's inbox and, unless `resume: false` is passed, calls
+`execution.wake` on it (`packages/core/src/session/session.ts` on OpenCode's `beta` branch).
+OpenCode's own background subagents report to their parent the same way
+(`packages/core/src/session/subagent-completion.ts`).
+
+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.
+
+## Tools
+
+| Tool | Does |
+|---|---|
+| `courier_spawn` | Creates a session (optionally in its own git worktree with `isolate: true`), sends it the task plus a brief naming the parent and how to report back, and returns at once. |
+| `courier_send` | Delivers a message to a session, signed with the sender's id, waking it if idle. |
+| `courier_status` | One look at a session: outcome, idle time and last reply. For check-ins, not for waiting. |
+| `courier_children` | Lists the sessions this one (or a given `sessionID`) started with `courier_spawn`, each with what `courier_status` reports plus its directory, whether it is isolated and when it was started. |
+| `courier_cleanup` | Removes the git worktree of a child started with `isolate: true` and drops the child from `courier_children`. Keeps a worktree with uncommitted changes or commits on no branch, tag or remote and lists them, unless `force: true` is passed. |
+| `courier_later` | Schedules a message for a session (this one by default) in `delayMinutes` or `at` an ISO time, and returns an id. When due it is delivered like `courier_send`, queued behind any running turn and waking the session if idle. |
+| `courier_cancel` | Drops a message scheduled with `courier_later`, e.g. because the child it was waiting for reported first. |
+| `courier_subscribe` | Subscribes a session (this one by default) to webhook deliveries for a `topic`: `owner/repo`, `owner/repo#12` (one pull request or issue) or a generic name. Each matching delivery arrives as a message, queued behind any running turn and waking the session if idle. Needs the [webhook receiver](#webhooks). |
+| `courier_unsubscribe` | Drops one topic, or all of a session's, e.g. once its pull request is merged. |
+
+### Roster
+
+`courier_spawn` records each child under its parent in the plugin's storage, so a parent that has
+lost track after a compaction or a server restart can call `courier_children` to find them again.
+A child that can no longer be looked up is still listed, with the error instead of its state.
+Entries are dropped 14 days after the child was started, when that parent's roster is read or
+the plugin is next loaded, except isolated children whose worktree is still there (see
+[Worktree cleanup](#worktree-cleanup)). If the roster cannot be written, the child still gets its task and
+`courier_spawn` says it is not on the list.
+
+### Worktree cleanup
+
+An isolated child works in a git worktree under OpenCode's data directory
+(`…/opencode/worktree/<project>/<name>`, on a detached HEAD), and nothing removes it on its own.
+When the parent has what it needs from the child, it calls `courier_cleanup { sessionID }`, which
+removes the worktree through the plugin API's `worktree.remove` and drops the child from
+`courier_children`.
+
+The worktree is kept, and the result says why, when it holds work that would otherwise be lost:
+
+- uncommitted changes, untracked files included (ignored files, such as `node_modules`, are not
+  work and go with the worktree);
+- commits that are on no branch, tag or remote-tracking ref, which is where a child's commits on
+  its detached HEAD end up. A commit on a branch survives the removal, so it does not count, and
+  neither do commits the worktree was made from (`courier_spawn` records that commit), such as a
+  parent's own unbranched work when an isolated child spawns isolated children of its own.
+
+The result lists up to 50 changed paths (an untracked directory counts once) and 50 commits. Commit
+or branch what you want to keep (`git -C <worktree> branch <name>` keeps its commits), or call
+`courier_cleanup` again with `force: true` to discard it; `force` also removes a worktree git can
+no longer read. A worktree whose directory is already gone is just dropped from the list; git
+forgets its registration on its next `git worktree prune` or `git gc`.
+
+Cleanup is explicit only. A child reporting back does not mean the parent has merged, reviewed or
+even read its work, and the parent may still send it more to do in the same worktree, so the
+plugin never removes one on its own. Isolated children whose worktree still exists are kept on
+`courier_children` past the 14 days, so they can still be found and cleaned up.
+
+`courier_cleanup` cannot tell whether the child is still running, so call it after the child has
+reported. It works on the calling session's own children.
+
+### Scheduled messages
+
+Pending `courier_later` messages are kept in the plugin's storage, and every loaded copy of the
+plugin checks for due ones every 15 seconds, so a message can arrive up to about 15 seconds late.
+OpenCode loads the plugin once per project location; the copies share one claim set, so each
+message is delivered once.
+
+They survive a server restart. After a start, OpenCode loads plugins for a project the first time
+that project is used, so messages that fell due while it was down are delivered then, not at the
+moment the server comes back. A crash between delivering a message and forgetting it can deliver
+it twice after the restart; a lost check-in would be worse.
+
+### Webhooks
+
+With the `webhook` option set (see [Receiving webhooks](#receiving-webhooks)), the plugin listens
+for HTTP deliveries and turns them into messages for subscribed sessions:
+
+- `POST /github` takes GitHub webhook deliveries. A pull request review, a review comment, a
+  comment, a pull request or issue being opened, reopened, closed (or merged) or marked ready for
+  review, or a completed check run, check suite or workflow run on a pull request goes to the
+  sessions subscribed to `owner/repo#N` and to `owner/repo`; anything else with a repository (a
+  push, a release) goes to `owner/repo` only. Pings, CI runs that have not completed, and other
+  pull request and issue actions (pushes to the branch, edits, labels, assignments, review
+  requests) wake nobody.
+- `POST /hook/<name>` takes anything else, for sessions subscribed to `<name>`. A JSON body's
+  `text`, `summary` or `message` field is delivered, otherwise the body itself.
+
+Every delivery must carry an `X-Hub-Signature-256` header: `sha256=` followed by exactly 64 hex
+digits, the HMAC-SHA256 under the shared secret. For GitHub that is of the raw body, as GitHub sends it. For
+`/hook/<name>` it is of the name, a newline and the body, so a captured delivery cannot be sent to
+another topic:
+
+```bash
+sig=$(printf '%s\n%s' deploys "$body" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)
+curl -X POST -H "x-hub-signature-256: sha256=$sig" --data-binary "$body" http://127.0.0.1:4097/hook/deploys
+```
+
+A missing or wrong signature gets `401`, and the body is not parsed. The check is constant-time.
+Bodies over 1 MiB (`maxBytes`) get `413`. A delivered event gets `202`, with the number of
+sessions it reached, which can be 0. The digests of the last 1000 accepted deliveries are remembered in
+memory (as lowercase hex, so re-casing the header does not get around it), and a delivery already
+accepted gets `200 already delivered`. One that reached nobody because every delivery to a session
+failed is forgotten again, so it can be retried. That stops replays of
+a captured delivery, and it also means a GitHub Redeliver of a delivery that already arrived is
+ignored. Redelivering one that failed works. Generic senders that post the same text twice should
+add something unique, such as a timestamp, to the body.
+
+A session that OpenCode no longer knows loses its subscriptions the next time a delivery for it
+fails, and `courier_subscribe` refuses a session id that does not exist.
+
+A session sees a short summary (event, repository and number, who, state or conclusion, link, and
+at most 1500 characters of a review or comment body), wrapped in `<courier from="github"
+event="...">` and followed by a note that it is outside text, to be treated as data. Review and
+comment bodies are written by whoever can comment on the repository, so subscribe sessions only to
+repositories whose commenters you trust with your agent's attention. The server log gets one line
+per delivery (event, delivery id, number of sessions), never the payload or the secret.
+
+GitHub does not report check suites on pull requests from forks (`pull_requests` is empty), so CI
+results for those reach `owner/repo` subscribers only. There is no GitHub event for a merge
+conflict.
+
+## Install
+
+Requires OpenCode V2 (`npm install -g @opencode-ai/cli@beta`, command `opencode2`).
+
+```bash
+git clone <this repo> && cd opencode-courier
+bun install && npm run build
+```
+
+Then list it in `opencode.json` (V2 uses `plugins`, plural). A local plugin path must be a
+**directory**; OpenCode loads its `index.js`, and ignores a path to a file with a warning:
+
+```jsonc
+{
+  "plugins": ["/absolute/path/to/opencode-courier/dist"]
+}
+```
+
+To receive webhooks, give the plugin a `webhook` option instead (see below).
+
+Once published to npm, `opencode2 plugin add opencode-courier` installs it and adds it to the
+global configuration.
+
+## Receiving webhooks
+
+The receiver is off unless the plugin has a `webhook` option. Put it in the **global** config
+(`~/.config/opencode/opencode.json`), since there is one receiver per OpenCode server:
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "/absolute/path/to/opencode-courier/dist",
+      "options": { "webhook": { "port": 4097, "secretFile": "~/.config/opencode/courier-webhook-secret" } }
+    }
+  ]
+}
+```
+
+`"webhook": true` takes every default. If the option is given more than once, for example in a
+project's config as well, the first location to load wins, and the others log that their settings
+are ignored.
+
+| Option | Default | |
+|---|---|---|
+| `port` | `4097` | Port to listen on. |
+| `host` | `127.0.0.1` | Address to bind. Only this machine can reach the default. |
+| `secretFile` | | File holding the shared secret (`~` is expanded). |
+| `secretEnv` | `COURIER_WEBHOOK_SECRET` | Environment variable holding it, when there is no `secretFile`. |
+| `maxBytes` | `1048576` | Largest body accepted. |
+
+The secret is never read from `opencode.json` itself (a `secret` key is refused), so the config
+can be committed. Make one with `openssl rand -hex 32 > ~/.config/opencode/courier-webhook-secret`
+and `chmod 600` it. A file is the safer choice with `opencode2 service start`, whose environment
+may not be your shell's. Without a usable secret the receiver does not start, and the server log
+says why.
+
+On GitHub, add a webhook to the repository (Settings → Webhooks) with content type
+`application/json`, the same secret, and the events you want (pull request reviews, review
+comments, issue comments, pull requests, check suites or workflow runs). GitHub must reach the
+receiver, and by default it only listens on `127.0.0.1`: forward a public URL to it with a tunnel
+you trust (`cloudflared tunnel --url http://127.0.0.1:4097`, `ngrok http 4097`, or
+`smee --url https://smee.io/<channel> --target http://127.0.0.1:4097/github`, which needs no
+inbound port at all) and use `<public URL>/github` as the payload URL. Whatever you expose, only
+signed deliveries are acted on.
+
+The receiver starts when OpenCode loads the plugin, which after a server start happens the first
+time a project is used. Until then deliveries fail; GitHub does not retry them on its own, but
+lists them under Recent Deliveries with a Redeliver button.
+
+## Using it
+
+1. Keep the background server running so sessions can be woken while you are away
+   (`opencode2 service start`; `opencode2 service status` to check).
+2. Give the agents that run children permissions that don't need a human; a child waiting on an
+   approval prompt never reports back.
+3. Use `isolate: true` whenever children edit files in parallel. The child's worktree is made
+   from the last commit, so an uncommitted `opencode.json` is not there and the child falls back
+   to your global config: keep providers and models in the global config, or commit the file.
+   When you are done with an isolated child, `courier_cleanup` it so its worktree does not linger.
+4. A child that crashes before calling `courier_send` never wakes the parent. When you spawn a
+   long-running child, also `courier_later` a check-in for yourself, and `courier_cancel` it when
+   the child reports.
+
+## Roadmap
+
+Tracked as [issues](https://github.com/ivopogace/opencode-courier/issues):
+
+- [#5](https://github.com/ivopogace/opencode-courier/issues/5) **Smoke test with a real model.**
+- [#6](https://github.com/ivopogace/opencode-courier/issues/6) **Publish to npm.**
+
+## Development
+
+```bash
+bun install
+bun test           # unit tests, with a fake plugin context
+npm run typecheck
+npm run build      # emits dist/
+OPENCODE_BIN=$(which opencode2) npm run test:e2e   # live test, see below
+```
+
+`e2e/run.sh` starts a real OpenCode V2 server in a throwaway project and home directory, with this
+plugin loaded and `e2e/mock-model.mjs` as the model: an OpenAI-compatible server that replies from
+a fixed script, so no API key is needed. It checks that a parent's spawn completes, that the parent
+gets a new turn after its own has ended once the child reports (shared and `isolate: true`), that
+`courier_status` reports and fails readably, that a `courier_later` message wakes an idle parent,
+that a cancelled one never arrives, that a pending one is delivered after a server restart, that
+`courier_children` lists the two children a parent spawned, before and after that restart, that
+a recorded GitHub review delivery (`e2e/fixtures/pull_request_review.json`), signed, wakes an idle
+session subscribed with `courier_subscribe`, once, while unsigned and wrongly signed ones are
+refused, and that `courier_cleanup` removes an isolated child's clean worktree but keeps one with an
+uncommitted file until asked with `force`. It takes about two minutes and needs node, bun, git,
+curl, jq and openssl.
+
+CI (`.github/workflows/ci.yml`) runs both on every push to `main` and every pull request, with the
+OpenCode CLI at the same version as the pinned plugin API.
+
+### Releasing
+
+`.github/workflows/release.yml` publishes to npm on a `v*` tag. It runs the CI workflow first,
+checks that the tag matches the `version` in `package.json`, builds, publishes from the `npm`
+environment with provenance, and then creates a GitHub release with generated notes. A
+prerelease version (`1.2.0-beta.1`) goes to the `next` dist-tag and is marked as a prerelease.
+
+```bash
+npm version patch   # bumps package.json, commits, tags vX.Y.Z
+git push --follow-tags
+```
+
+It authenticates with npm trusted publishing (OIDC), which needs no stored token: on npmjs.com,
+the package's trusted publisher is this repository, workflow `release.yml`, environment `npm`.
+Until that is set up, npm falls back to an access token in the repository secret `NPM_TOKEN`.
+
+CI also checks the package as published: `publint` for `package.json` and `exports`, and
+`@arethetypeswrong/cli` for the type declarations.
+
+The plugin API is still beta and pinned to an exact version in `package.json`; bump it
+deliberately and re-run both test suites.
+
+### Notes on the V2 plugin API
+
+Found while testing against `0.0.0-beta-19271`:
+
+- A plugin tool is only reachable through code mode's `execute` tool unless it is registered with
+  `options: { codemode: false }`. The courier tools are direct tools.
+- A tool whose result `metadata` holds an `undefined` value never completes: the call stays
+  `running` and no error is reported. Results here drop `undefined` keys.
+- A plugin cannot add an HTTP route to OpenCode's own server. The nearest thing, `rpc.register`,
+  is reached through the authenticated `/api/rpc` endpoint with a JSON envelope, so neither
+  GitHub's headers nor the raw body its signature covers would get through. The webhook receiver
+  is therefore its own small listener inside the OpenCode process, shared by the plugin's
+  per-location instances. It waits for the previous listener to finish closing before it binds,
+  as after a plugin reload, and if binding fails, the next instance to load tries again. A plugin's options come from a `{ "package", "options" }` entry in
+  `plugins`, which takes a local directory as `package` too.
+- OpenCode errors such as `Session.NotFoundError` can arrive with an empty message, so the tools
+  rethrow them with the tag and session id.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/dist/cleanup.d.ts

@@ -0,0 +1,59 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import { type RosterStorage } from "./roster.js";
+type Context = Plugin.Context;
+/** 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 plugin's own location, for roster entries recorded before they carried their source. */
+    readonly directory: 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>;
+}
+export interface CleanupInput {
+    readonly sessionID: string;
+    readonly force?: boolean;
+}
+export type CleanupResult = {
+    readonly sessionID: string;
+    readonly directory: string;
+    readonly outcome: "removed";
+} | {
+    readonly sessionID: string;
+    readonly directory: string;
+    readonly outcome: "gone";
+} | {
+    readonly sessionID: string;
+    readonly directory: string;
+    readonly outcome: "kept";
+    readonly reason: string;
+    readonly changes: readonly string[];
+    readonly commits: readonly string[];
+};
+/** Why a worktree in this state must be kept, or undefined when removing it loses nothing. */
+export declare function keepReason(state: WorktreeState): string | undefined;
+/** At most this many changes and commits are returned; the reason still counts them all. */
+export declare const MAX_LISTED = 50;
+/**
+ * Removes the worktree of an isolated child the parent started, and forgets the child. A worktree
+ * with uncommitted changes or commits that exist nowhere else is kept unless `force` is set, and the
+ * result says what is in it.
+ */
+export declare function cleanup(ports: CleanupPorts, parentID: string, input: CleanupInput): Promise<CleanupResult>;
+/** The commit a worktree is on, or undefined when git cannot tell. */
+export declare function headOf(directory: string): Promise<string | undefined>;
+/**
+ * Reads a worktree's state with git; undefined when the directory is gone. Commits reachable from
+ * `base`, the commit the worktree was made from, are not its own work and are not listed.
+ */
+export declare function inspectWorktree(directory: string, base?: string): Promise<WorktreeState | undefined>;
+export {};

package/dist/cleanup.js

@@ -0,0 +1,98 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { rosterKey } from "./roster.js";
+/** Why a worktree in this state must be kept, or undefined when removing it loses nothing. */
+export function keepReason(state) {
+    const reasons = [
+        state.changes.length ? `${count(state.changes.length, "uncommitted change")} (${preview(state.changes)})` : "",
+        state.commits.length
+            ? `${count(state.commits.length, "commit")} on no branch, tag or remote (${preview(state.commits)})`
+            : "",
+    ].filter(Boolean);
+    return reasons.length ? reasons.join(" and ") : undefined;
+}
+function count(n, noun) {
+    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+/** At most this many changes and commits are returned; the reason still counts them all. */
+export const MAX_LISTED = 50;
+function preview(items) {
+    return items.length > 5 ? `${items.slice(0, 5).join(", ")}, ...` : items.join(", ");
+}
+/**
+ * Removes the worktree of an isolated child the parent started, and forgets the child. A worktree
+ * with uncommitted changes or commits that exist nowhere else is kept unless `force` is set, and the
+ * result says what is in it.
+ */
+export async function cleanup(ports, parentID, input) {
+    const entry = (await ports.storage.get(rosterKey(parentID, input.sessionID)));
+    if (!entry)
+        throw new Error(`${input.sessionID} is not on the courier_children list of ${parentID}.`);
+    if (!entry.isolated)
+        throw new Error(`${input.sessionID} ran in ${entry.directory}, not in a worktree of its own; there is nothing to remove.`);
+    const { directory } = entry;
+    const forget = () => ports.storage.remove(rosterKey(parentID, input.sessionID));
+    // With force the state only decides whether there is anything left to remove, so a worktree git
+    // can no longer read is still removed.
+    const state = await ports
+        .inspect(directory, entry.base)
+        .catch((error) => (input.force ? { changes: [], commits: [] } : Promise.reject(error)));
+    if (!state) {
+        await forget();
+        return { sessionID: input.sessionID, directory, outcome: "gone" };
+    }
+    const reason = keepReason(state);
+    if (reason && !input.force)
+        return {
+            sessionID: input.sessionID,
+            directory,
+            outcome: "kept",
+            reason,
+            changes: state.changes.slice(0, MAX_LISTED),
+            commits: state.commits.slice(0, MAX_LISTED),
+        };
+    await ports.worktree.remove({
+        location: { directory: entry.source ?? ports.directory },
+        directory,
+        force: input.force === true,
+    });
+    await forget();
+    return { sessionID: input.sessionID, directory, outcome: "removed" };
+}
+function git(directory, args) {
+    return new Promise((resolve, reject) => execFile("git", ["-C", directory, ...args], { maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => error ? reject(new Error(`git ${args[0]} in ${directory}: ${stderr.trim() || error.message}`)) : resolve(stdout)));
+}
+/** The commit a worktree is on, or undefined when git cannot tell. */
+export function headOf(directory) {
+    return git(directory, ["rev-parse", "HEAD"]).then((out) => out.trim() || undefined, () => undefined);
+}
+/**
+ * Reads a worktree's state with git; undefined when the directory is gone. Commits reachable from
+ * `base`, the commit the worktree was made from, are not its own work and are not listed.
+ */
+export async function inspectWorktree(directory, base) {
+    if (!existsSync(directory))
+        return undefined;
+    // An untracked directory is one entry, not every file in it.
+    const status = await git(directory, ["status", "--porcelain=v1", "-z", "--untracked-files=normal"]);
+    const changes = [];
+    const records = status.split("\0").filter(Boolean);
+    for (let i = 0; i < records.length; i++) {
+        const record = records[i];
+        changes.push(record.slice(3));
+        // A rename or copy is followed by its source path in a record of its own.
+        if ("RC".includes(record[0]) || "RC".includes(record[1]))
+            i++;
+    }
+    const log = await git(directory, [
+        "log",
+        "--format=%h %s",
+        "HEAD",
+        "--not",
+        "--branches",
+        "--tags",
+        "--remotes",
+        ...(base ? [base] : []),
+    ]);
+    return { changes, commits: log.split("\n").filter(Boolean) };
+}

package/dist/courier.d.ts

@@ -0,0 +1,75 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import { type RosterStorage } from "./roster.js";
+type Context = Plugin.Context;
+/** The slice of the plugin context the courier tools use; tests pass a fake. */
+export interface CourierPorts {
+    readonly session: Pick<Context["session"], "create" | "prompt" | "synthetic" | "get" | "context">;
+    readonly worktree: Pick<Context["worktree"], "create" | "remove">;
+    /** The commit a directory's checkout is on, or undefined; recorded as an isolated child's base. */
+    readonly head: (directory: string) => Promise<string | undefined>;
+    readonly storage: RosterStorage;
+    readonly directory: string;
+    readonly now: () => number;
+}
+export interface SpawnInput {
+    readonly task: string;
+    readonly title?: string;
+    readonly agent?: string;
+    readonly isolate?: boolean;
+}
+export interface SendInput {
+    readonly sessionID: string;
+    readonly message: string;
+    readonly queue?: boolean;
+}
+export interface StatusInput {
+    readonly sessionID: string;
+}
+export interface ChildrenInput {
+    readonly sessionID?: string;
+}
+export declare function childBrief(parentID: string, task: string): string;
+export declare function envelope(from: string, message: string, attributes?: Record<string, string>): string;
+/** Creates a child session, hands it the task and returns at once; the child reports back with courier_send. */
+export declare function spawn(ports: CourierPorts, parentID: string, input: SpawnInput): Promise<{
+    rosterError?: string | undefined;
+    sessionID: string;
+    directory: string;
+}>;
+/** Drops a message into another session's inbox; OpenCode wakes that session if it is idle. */
+export declare function send(ports: CourierPorts, from: string, input: SendInput): Promise<{
+    messageID: string;
+}>;
+/** A one-off look at a session, for check-ins; not meant to be called in a loop. */
+export declare function status(ports: CourierPorts, input: StatusInput): Promise<Partial<{
+    sessionID: string;
+    title: string | undefined;
+    parentID: string | undefined;
+    outcome: "succeeded" | "failed" | "interrupted" | undefined;
+    updated: number;
+    idle: number | undefined;
+    lastText: string | undefined;
+}>>;
+/** The sessions a parent started, each with what courier_status reports, or the error it gave. */
+export declare function listChildren(ports: CourierPorts, parentID: string): Promise<({
+    directory: string;
+    isolated: boolean;
+    created: number;
+    sessionID?: string | undefined;
+    title?: string | undefined;
+    parentID?: string | undefined;
+    outcome?: "succeeded" | "failed" | "interrupted" | undefined;
+    updated?: number | undefined;
+    idle?: number | undefined;
+    lastText?: string | undefined;
+} | {
+    error: string;
+    directory: string;
+    isolated: boolean;
+    created: number;
+    sessionID: string;
+    title: string;
+})[]>;
+/** A readable message for a failed courier call; OpenCode's own errors can carry an empty message. */
+export declare function describeFailure(tool: string, error: unknown): Error;
+export {};