opencode-courier 0.13.8 → 0.14.0

package/dist/platform/hub.d.ts

@@ -1,195 +1,82 @@
 import { type Registry, type Storage } from "./storage.js";
-/**
- * The plugin's process-wide state on `globalThis`, shared by every loaded copy; only this module puts
- * it there. `HUB_VERSION`, the fixed claim keys and version skew: docs/maintainers/architecture.md, § Several copies in one process.
- */
 export declare const HUB_VERSION = 2;
-/** The key of the hub; a copy that finds another version there keeps its own under `${HUB_KEY}@<version>`. */
 export declare const HUB_KEY = "opencode-courier.hub";
-/** The ports a member's scheduler keeps the owner key through: what every member's `later` ports have. */
 export interface TickPorts {
     readonly storage: Pick<Storage, "get" | "set" | "remove">;
     readonly now: () => number;
 }
-/**
- * The events handled, and the permission requests a session was told about or that were answered
- * first: claim sets shared by every subscription and copy, so each event is handled once.
- */
 export interface Watched {
     readonly seen: Set<string>;
     readonly waiting: Set<string>;
     readonly answered: Set<string>;
 }
-/** The forms sessions were told about, kept apart from the permission requests. */
 export interface FormsTold {
-    /** Forms still shown whose notice went out, or is going out: the notice's delivery. */
     readonly told: Map<string, Promise<unknown>>;
-    /** Forms settled before anyone was told, so a notice whose roster lookup was overtaken is not sent. */
     readonly settled: Set<string>;
 }
-/**
- * A loaded plugin instance: its location's directory and permission domain, and the ports a job
- * run once for the whole process would run it through.
- */
 export interface Member {
     readonly directory: string;
-    /**
-     * The location OpenCode set the instance up with, the very object the instance's Effect half is
-     * handed too, which finds its member by it (`portsAt`). A member of a copy before it has none.
-     */
     readonly location?: object;
-    /** The location's permission domain, kept in `locations`. */
     readonly permission: unknown;
-    /** The ports the scheduler's tick runs through: the owner key's, and the tick jobs'. */
     readonly later: TickPorts;
-    /** The ports the hub's subscriptions to OpenCode's events run through. */
     readonly watch: unknown;
-    /** The question relay's ports. */
     readonly questions: unknown;
     readonly log: (message: string) => void;
 }
-/**
- * A tick under way: the member it runs through, when it started, by the wall clock every member's
- * `now` reads (the next ticks compare it with another member's), and its end.
- */
 export interface Tick {
     readonly member: Member;
     readonly since: number;
-    /** Settles once the tick has ended, the owner key released if its loop stopped meanwhile; never rejects. */
     readonly done: Promise<void>;
 }
-/**
- * The scheduler's loop, one per hub: it runs while the hub has members, and each tick runs the jobs
- * registered with `open` through the ports of the member that joined first and is still loaded.
- */
 export interface Scheduler {
-    /** The loop's interval, while it runs. */
     timer?: unknown;
-    /**
-     * The tick under way, whichever copy started it: for a minute the key is renewed for it and due
-     * ticks skip; past it, one whose member left holds nothing up. Older copies have only `ticking`.
-     */
     running?: Tick;
-    /**
-     * The member the tick under way runs through, if any, set and cleared with `running`, for a copy
-     * that reads only this: a tick that falls due meanwhile is skipped, unless that member has left.
-     */
     ticking?: Member;
-    /** One tick, by the copy of the plugin that joined last, so a copy loaded after an update runs its own code. */
     tick?: () => Promise<void>;
-    /** Whether a nudge came since the tick under way started, whichever copy's, so it ticks once more when done. */
     nudged?: boolean;
 }
-/** How the hub starts and stops the scheduler's loop, and waits before re-reading the owner key; tests pass their own. */
 export interface Timers {
     readonly every: (run: () => void, ms: number) => unknown;
     readonly stop: (timer: unknown) => void;
     readonly wait: (ms: number) => Promise<void>;
 }
-/** How often the hub's scheduler ticks: what a job delivers, a `courier_later` message, can be this late. */
 export declare const TICK_MS = 15000;
-/**
- * The storage key, shared by every server on one data directory, naming the server whose scheduler
- * delivers `courier_later` messages: `{ server, at }`, its id and when it last wrote (epoch ms).
- */
 export declare const OWNER_KEY = "scheduler/owner";
-/** How long the owner key holds without being renewed; the owner renews it every tick, four times as often. */
 export declare const OWNER_EXPIRY_MS: number;
-/**
- * How old the owner's own key may be for it to renew the key and deliver at once. An older one,
- * which it may no longer hold by the time it writes, is taken again like a free one, with the wait.
- */
 export declare const OWNER_RENEW_MS: number;
-/** The wait between writing the owner key and reading it back, at least `OWNER_WAIT_MS` and up to twice that. */
 export declare const OWNER_WAIT_MS = 500;
-/**
- * This server's id in the owner key: the same for every copy of the plugin in the process, and
- * different in every other process, a restart of this one included.
- */
 export declare const SERVER: string;
-/**
- * How long an unloading instance waits for the work it leaves behind: what it started itself, a tick
- * or a notice under way through it, and on the last leave the owner key's release.
- */
 export declare const LEAVE_MS = 2000;
-/** How many subscriptions to OpenCode's events a hub keeps, each through another member: one, and a standby. */
 export declare const WATCHERS = 2;
-/** One of the hub's subscriptions to OpenCode's events: the member whose ports it runs through, and how it ends. */
 export interface Watcher {
     readonly member: Member;
     readonly stop: AbortController;
-    /** Settles once the subscription has ended, after `stop`: after the event it is handling, not the stream's close. */
     readonly done: Promise<void>;
 }
 export interface Hub {
     readonly version: typeof HUB_VERSION;
-    /** The instances loaded now, in the order they joined. */
     readonly members: Set<Member>;
     readonly scheduler: Scheduler;
-    /**
-     * The hub's subscriptions to OpenCode's events, each through another member: two while two members
-     * are loaded, so one is always connected when the other's member leaves.
-     */
     readonly watchers: Watcher[];
-    /**
-     * Starts a subscription through a member, by the copy of the plugin that set it last; until one
-     * has, the hub follows no events.
-     */
     subscribe?: (member: Member) => Watcher;
-    /** The ids of the `courier_later` messages being delivered. */
     readonly claimed: Set<string>;
-    /** The events handled, and the permission requests a session was told about or that were answered first. */
     readonly watched: Watched;
-    /** The forms sessions were told about, and those settled first. */
     readonly forms: FormsTold;
-    /**
-     * The permission domain of every loaded instance, by instance. OpenCode keeps a request where its
-     * session runs, so a request of an isolated child is answered through the instance loaded in its worktree.
-     */
     readonly locations: Map<object, unknown>;
-    /** The webhook receiver's state: the object every copy shares under the key `receiver`. */
     readonly receivers: object;
-    /** The question relay's state: the object every copy shares under the key `questions`. */
     readonly questions: object;
-    /** Whether the hub of another version found under `HUB_KEY` has been logged. */
     skewLogged: boolean;
 }
-/**
- * A job each tick runs, in its turn, through the first loaded member, which may be another copy's:
- * it uses only the ports every hub-v2 member has. `claimed` is the hub's claim set; a throw ends the tick.
- */
 export type TickJob = (owner: Member, claimed: Set<string>) => Promise<void>;
-/** A hub, as `open` finds or makes it, and how instances join it. */
 export interface Opened {
     readonly hub: Hub;
-    /**
-     * Adds a loaded instance to the hub and `locations`; returns its leave. The first join starts the
-     * scheduler and watchers, the last leave stops them; a leave waits `LEAVE_MS` for the member's work.
-     */
     readonly join: (member: Member) => () => Promise<void>;
-    /** Hands the hub work a member started, which its leave waits for; the member's own background work. */
     readonly track: (member: Member, work: Promise<unknown>) => void;
-    /**
-     * Runs a tick now, or once the tick under way has ended, so what has just fallen due (a released
-     * group) is delivered at once rather than at the next tick; nothing while no instance is loaded.
-     */
     readonly nudge: () => void;
 }
-/**
- * The value under `opencode-courier.<name>` every copy in the process shares, made by `create` the first
- * time; another version, or a copy before the hub, may have made it, so its shape is kept for good.
- */
 export declare function sharedState<T>(name: string, create: () => T, registry?: Registry): T;
-/**
- * This copy's hub in `registry`, and how its instances join it. Its ticks run `jobs` in order, kept in
- * this copy's tick, which the hub runs once this copy has joined last, never in the hub itself.
- */
 export declare function open(registry: Registry, jobs: readonly TickJob[], timers?: Timers, server?: string): Opened;
-/** This copy's hub, in the process. */
 export declare const hub: Hub;
-/** Opens this copy's hub in the process, with its tick jobs; see `open`. */
 export declare const openInProcess: (jobs: readonly TickJob[]) => Opened;
-/** The member of this copy's hub set up with `location` that joined last, while it is loaded. */
 export declare function memberAt(location: object): Member | undefined;
-/** The permission domains of the loaded instances. */
 export declare const permissions: () => MapIterator<unknown>;

package/dist/platform/hub.js

@@ -2,38 +2,18 @@ import { randomInt } from "node:crypto";
 import { hostname } from "node:os";
 import { num, obj, str } from "./json.js";
 import { processWide } from "./storage.js";
-/**
- * The plugin's process-wide state on `globalThis`, shared by every loaded copy; only this module puts
- * it there. `HUB_VERSION`, the fixed claim keys and version skew: docs/maintainers/architecture.md, § Several copies in one process.
- */
 export const HUB_VERSION = 2;
-/** The key of the hub; a copy that finds another version there keeps its own under `${HUB_KEY}@<version>`. */
 export const HUB_KEY = "opencode-courier.hub";
 const realTimers = {
     every: (run, ms) => setInterval(run, ms),
     stop: (timer) => clearInterval(timer),
     wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
 };
-/** How often the hub's scheduler ticks: what a job delivers, a `courier_later` message, can be this late. */
 export const TICK_MS = 15_000;
-/**
- * The storage key, shared by every server on one data directory, naming the server whose scheduler
- * delivers `courier_later` messages: `{ server, at }`, its id and when it last wrote (epoch ms).
- */
 export const OWNER_KEY = "scheduler/owner";
-/** How long the owner key holds without being renewed; the owner renews it every tick, four times as often. */
 export const OWNER_EXPIRY_MS = 4 * TICK_MS;
-/**
- * How old the owner's own key may be for it to renew the key and deliver at once. An older one,
- * which it may no longer hold by the time it writes, is taken again like a free one, with the wait.
- */
 export const OWNER_RENEW_MS = OWNER_EXPIRY_MS / 2;
-/** The wait between writing the owner key and reading it back, at least `OWNER_WAIT_MS` and up to twice that. */
 export const OWNER_WAIT_MS = 500;
-/**
- * This server's id in the owner key: the same for every copy of the plugin in the process, and
- * different in every other process, a restart of this one included.
- */
 export const SERVER = `${hostname()}:${process.pid}:${performance.timeOrigin}`;
 async function readOwner(ports) {
     const value = obj(await ports.storage.get(OWNER_KEY));
@@ -41,26 +21,13 @@ async function readOwner(ports) {
     const at = num(value.at);
     return server !== undefined && at !== undefined ? { server, at } : undefined;
 }
-/**
- * How long an unloading instance waits for the work it leaves behind: what it started itself, a tick
- * or a notice under way through it, and on the last leave the owner key's release.
- */
+// OpenCode waits up to 2 s for an unloading instance (architecture)
 export const LEAVE_MS = 2_000;
-/** Whether a key written at `at` still holds at `now`; one from the future, after the clock went back, holds as long. */
 const holds = (at, now, ms) => Math.abs(now - at) < ms;
-/** How many subscriptions to OpenCode's events a hub keeps, each through another member: one, and a standby. */
 export const WATCHERS = 2;
-/**
- * The value under `opencode-courier.<name>` every copy in the process shares, made by `create` the first
- * time; another version, or a copy before the hub, may have made it, so its shape is kept for good.
- */
 export function sharedState(name, create, registry = globalThis) {
     return processWide(`opencode-courier.${name}`, create, registry);
 }
-/**
- * Finds or makes this copy's hub in `registry`: the one under `HUB_KEY`, or its own under a versioned
- * key when another version holds that; its claim sets are the pre-hub keys', made when missing.
- */
 function find(registry) {
     const shared = (name, create) => sharedState(name, create, registry);
     const create = () => ({
@@ -73,25 +40,15 @@ function find(registry) {
         forms: shared("forms", () => ({ told: new Map(), settled: new Set() })),
         locations: shared("locations", () => new Map()),
         receivers: shared("receiver", () => ({})),
-        // Filled in by `person/question/`, field by field, since a copy before the hub may have made it without them.
         questions: shared("questions", () => ({})),
         skewLogged: false,
     });
     const found = registry[Symbol.for(HUB_KEY)];
-    // The version of the hub of another copy found under `HUB_KEY`, if one is there.
     const skew = found != null && found.version !== HUB_VERSION ? { version: found.version } : undefined;
     return { hub: processWide(skew ? `${HUB_KEY}@${HUB_VERSION}` : HUB_KEY, create, registry), skew };
 }
-/**
- * This copy's hub in `registry`, and how its instances join it. Its ticks run `jobs` in order, kept in
- * this copy's tick, which the hub runs once this copy has joined last, never in the hub itself.
- */
 export function open(registry, jobs, timers = realTimers, server = SERVER) {
     const { hub, skew } = find(registry);
-    /**
-     * Whether this server holds the owner key, taking or renewing it through `ports`. A free, expired
-     * or stalled key is written and read back after a random wait: the last of two writers holds it.
-     */
     const own = async (ports) => {
         const held = await readOwner(ports);
         const now = ports.now();
@@ -103,34 +60,23 @@ export function open(registry, jobs, timers = realTimers, server = SERVER) {
         await timers.wait(randomInt(OWNER_WAIT_MS, 2 * OWNER_WAIT_MS));
         return (await readOwner(ports))?.server === server;
     };
-    /** Whether `held` is this server's key, recent enough to renew without reading it back. */
     const fresh = (held, now) => held?.server === server && holds(held.at, now, OWNER_RENEW_MS);
-    /** Renews the owner key if this server holds it fresh: what a tick does, for a tick still delivering. */
     const renew = async (ports) => {
         const now = ports.now();
         if (fresh(await readOwner(ports), now))
             await ports.storage.set(OWNER_KEY, { server, at: now });
     };
-    /** Whether a hub of another version in the process has instances, so its loop, under the same server id, still holds the key. */
     const othersRunning = () => Object.getOwnPropertySymbols(registry).some((key) => {
         const other = registry[key];
         const name = key.description ?? "";
         return other !== hub && (name === HUB_KEY || name.startsWith(`${HUB_KEY}@`)) && Number(other?.members?.size) > 0;
     });
-    /**
-     * Removes the owner key if this server holds it, so another takes over at its next tick: once the
-     * loop has stopped, no tick is under way and no other hub version here runs a loop under this id.
-     */
     const release = async (ports) => {
         const scheduler = hub.scheduler;
         const idle = () => scheduler.timer === undefined && !scheduler.running && !scheduler.ticking && !othersRunning();
         if (idle() && (await readOwner(ports))?.server === server && idle())
             await ports.storage.remove(OWNER_KEY);
     };
-    /**
-     * Whether the tick under way still holds the next up: within a minute of its start it does; past
-     * that it is taken to hang, holding up only while its member is loaded. `recent` says which.
-     */
     const busy = () => {
         const { running, ticking } = hub.scheduler;
         if (!running)
@@ -140,7 +86,6 @@ export function open(registry, jobs, timers = realTimers, server = SERVER) {
             return { busy: true, recent: true };
         return { busy: hub.members.has(running.member), recent: false };
     };
-    /** `busy`, renewing the key for a recent tick under way, as each tick falling due meanwhile does. */
     const underWay = () => {
         const state = busy();
         const first = hub.members.values().next().value;
@@ -148,8 +93,6 @@ export function open(registry, jobs, timers = realTimers, server = SERVER) {
             void renew(first.later).catch((error) => first.log(`courier_later scheduler: ${String(error)}`));
         return state.busy;
     };
-    // One tick, through the first loaded member, by the server holding the owner key. The claim on each
-    // delivery stays, as a second line of defence against a pre-hub copy running its own interval.
     const tick = async () => {
         const scheduler = hub.scheduler;
         if (underWay())
@@ -170,8 +113,6 @@ export function open(registry, jobs, timers = realTimers, server = SERVER) {
         const run = { member: owner, since, done: new Promise((resolve) => (end = resolve)) };
         scheduler.running = run;
         scheduler.ticking = owner;
-        // `done` settles however the tick ends, and the key is given back, a log that throws included:
-        // leaves wait for it. A log that throws is not logged again; there is nowhere left to tell.
         const tell = (message) => {
             try {
                 owner.log(message);
@@ -188,21 +129,17 @@ export function open(registry, jobs, timers = realTimers, server = SERVER) {
             tell(`courier_later scheduler: ${String(error)}`);
         }
         finally {
-            // A tick past its minute may have been followed by another, whose record stays.
             if (scheduler.running === run) {
                 scheduler.running = undefined;
                 scheduler.ticking = undefined;
             }
         }
-        // A loop stopped meanwhile, its members gone, gives back the key this tick may have written.
         if (scheduler.timer === undefined)
             await release(owner.later).catch((error) => tell(`courier_later scheduler: owner key not released: ${String(error)}`));
         end();
         if (scheduler.nudged && scheduler.timer !== undefined)
             void scheduler.tick?.();
     };
-    // Through the hub's tick, the copy loaded last's, like the loop's; this copy's only before one joined. A
-    // tick under way runs once more when it ends, so nothing is started here meanwhile.
     const nudge = () => {
         const scheduler = hub.scheduler;
         if (scheduler.timer === undefined)
@@ -211,8 +148,6 @@ export function open(registry, jobs, timers = realTimers, server = SERVER) {
         if (!busy().busy)
             void (scheduler.tick ?? tick)();
     };
-    // Subscriptions through the earliest members without one, the longest loaded, until there are
-    // `WATCHERS`; never through `leaving`.
     const watch = (leaving) => {
         const watching = new Set(hub.watchers.map((watcher) => watcher.member));
         for (const member of hub.members) {
@@ -222,7 +157,6 @@ export function open(registry, jobs, timers = realTimers, server = SERVER) {
                 hub.watchers.push(hub.subscribe(member));
         }
     };
-    // The work each member of this copy started and handed over, until it settles.
     const work = new WeakMap();
     const track = (member, started) => {
         const set = work.get(member) ?? new Set();
@@ -248,13 +182,9 @@ export function open(registry, jobs, timers = realTimers, server = SERVER) {
         return () => {
             hub.members.delete(member);
             hub.locations.delete(member);
-            // What this member leaves behind: the work it handed over, and a tick under way through it,
-            // which keeps using its storage and session until it ends.
             const behind = [...(work.get(member) ?? [])];
             if (scheduler.running?.member === member)
                 behind.push(scheduler.running.done);
-            // The other subscription, already connected, follows the events meanwhile; this one is replaced
-            // before it ends, after its current event, so the relay's watcher count never drops to none.
             const index = hub.watchers.findIndex((watcher) => watcher.member === member);
             if (index >= 0) {
                 const [leaving] = hub.watchers.splice(index, 1);
@@ -265,7 +195,6 @@ export function open(registry, jobs, timers = realTimers, server = SERVER) {
             if (hub.members.size === 0 && scheduler.timer !== undefined) {
                 timers.stop(scheduler.timer);
                 scheduler.timer = undefined;
-                // After the tick under way, whichever copy started it, which may be writing the key.
                 behind.push((async () => {
                     await scheduler.running?.done;
                     await release(member.later);
@@ -283,11 +212,8 @@ export function open(registry, jobs, timers = realTimers, server = SERVER) {
         nudge,
     };
 }
-/** This copy's hub, in the process. */
 export const hub = find(globalThis).hub;
-/** Opens this copy's hub in the process, with its tick jobs; see `open`. */
 export const openInProcess = (jobs) => open(globalThis, jobs);
-/** The member of this copy's hub set up with `location` that joined last, while it is loaded. */
 export function memberAt(location) {
     let found;
     for (const member of hub.members)
@@ -295,5 +221,4 @@ export function memberAt(location) {
             found = member;
     return found;
 }
-/** The permission domains of the loaded instances. */
 export const permissions = () => hub.locations.values();

package/dist/platform/json.d.ts

@@ -1,9 +1,6 @@
-/** 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;
-/** Whether an error of OpenCode's says that what it names, such as a session, does not exist (`Session.NotFoundError`). */
 export declare const isNotFound: (error: unknown) => boolean;

package/dist/platform/json.js

@@ -1,9 +1,8 @@
-/** 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. */
+// OpenCode's session times are DateTimes; tests pass numbers
 export function millis(value) {
     if (typeof value === "number")
         return value;
@@ -12,5 +11,4 @@ export function millis(value) {
     const epoch = obj(value).epochMilliseconds;
     return typeof epoch === "number" ? epoch : Number.NaN;
 }
-/** Whether an error of OpenCode's says that what it names, such as a session, does not exist (`Session.NotFoundError`). */
 export const isNotFound = (error) => str(obj(error)._tag)?.includes("NotFound") ?? false;

package/dist/platform/storage.d.ts

@@ -1,18 +1,11 @@
 import type { Plugin } from "@opencode/plugin";
 type Context = Plugin.Context;
 export type Storage = Pick<Context["storage"], "get" | "set" | "remove" | "scan">;
-/** Every value stored under `prefix`, following the scan's pages. */
 export declare function scanAll<T>(storage: Pick<Storage, "scan">, prefix: string): Promise<T[]>;
-/** Every key under `prefix`, without the prefix, with its value, following the scan's pages. */
 export declare function scanEntries<T>(storage: Pick<Storage, "scan">, prefix: string): Promise<{
     key: string;
     value: T;
 }[]>;
-/** Where process-wide values are kept: `globalThis`, or a stand-in for it in tests. */
 export type Registry = Record<symbol, unknown>;
-/**
- * The one value the whole process keeps under `Symbol.for(key)`, made by `create` the first time,
- * so every instance of the plugin, and every copy of it loaded later, gets the same one.
- */
 export declare function processWide<T>(key: string, create: () => T, registry?: Registry): T;
 export {};

package/dist/platform/storage.js

@@ -1,8 +1,6 @@
-/** Every value stored under `prefix`, following the scan's pages. */
 export async function scanAll(storage, prefix) {
     return (await scanEntries(storage, prefix)).map((entry) => entry.value);
 }
-/** Every key under `prefix`, without the prefix, with its value, following the scan's pages. */
 export async function scanEntries(storage, prefix) {
     const entries = [];
     let after;
@@ -14,10 +12,6 @@ export async function scanEntries(storage, prefix) {
     } while (after);
     return entries;
 }
-/**
- * The one value the whole process keeps under `Symbol.for(key)`, made by `create` the first time,
- * so every instance of the plugin, and every copy of it loaded later, gets the same one.
- */
 export function processWide(key, create, registry = globalThis) {
     const symbol = Symbol.for(key);
     registry[symbol] ??= create();

package/dist/platform/version.d.ts

@@ -1,16 +1,7 @@
 import type { App } from "@opencode/plugin/app";
-/** The versions a build of the plugin carries: its own, and the OpenCode it was built and tested against. */
 export interface BuiltVersions {
     readonly plugin: string;
     readonly opencode: string;
 }
-/**
- * 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.
- */
 export declare function builtVersions(): BuiltVersions;
-/**
- * The server-log line for an OpenCode other than the plugin was built against, undefined when it is;
- * logged once per load, never in a tool result. A context without a version is still told the pin.
- */
 export declare function versionNotice(built: BuiltVersions, app: Partial<Pick<App, "version" | "channel">> | undefined): string | undefined;

package/dist/platform/version.js

@@ -1,9 +1,5 @@
 import { readFileSync } from "node:fs";
 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.
- */
 export function builtVersions() {
     const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
     const plugin = pkg.version;
@@ -14,10 +10,6 @@ export function builtVersions() {
         throw new Error("package.json pins no @opencode/plugin under devDependencies");
     return { plugin, opencode };
 }
-/**
- * The server-log line for an OpenCode other than the plugin was built against, undefined when it is;
- * logged once per load, never in a tool result. A context without a version is still told the pin.
- */
 export function versionNotice(built, app) {
     const version = typeof app?.version === "string" ? app.version : undefined;
     if (version === built.opencode)

package/dist/rpc.js

@@ -1,4 +1,3 @@
-// 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/scheduling/index.d.ts

@@ -2,5 +2,4 @@ import type { TickJob } from "../platform/hub.js";
 export { cancel, cancelScheduled, deliverDue, isScheduled, schedule, scheduledFor } from "./later.js";
 export type { LaterEntry, LaterInput, LaterPorts } from "./later.js";
 export { addSchedulingTools } from "./tools.js";
-/** The scheduler's tick job: due messages, through the first loaded member, whose `later` is every hub-v2 member's LaterPorts. */
 export declare const dueJob: TickJob;

package/dist/scheduling/index.js

@@ -1,5 +1,4 @@
 import { deliverDue } from "./later.js";
 export { cancel, cancelScheduled, deliverDue, isScheduled, schedule, scheduledFor } from "./later.js";
 export { addSchedulingTools } from "./tools.js";
-/** The scheduler's tick job: due messages, through the first loaded member, whose `later` is every hub-v2 member's LaterPorts. */
 export const dueJob = (owner, claimed) => deliverDue(owner.later, claimed);

package/dist/scheduling/later.d.ts

@@ -11,7 +11,6 @@ export interface LaterEntry {
 }
 export interface LaterPorts {
     readonly storage: Storage;
-    /** `get` for the release of a join group, which waits for its parent's turn to end; `get` and `context` for a missed wake (`ctx.session`). */
     readonly session: Pick<Context["session"], "synthetic" | "get" | "context">;
     readonly now: () => number;
     readonly newID: () => string;
@@ -19,26 +18,16 @@ export interface LaterPorts {
 }
 export interface LaterInput {
     readonly message: string;
-    /** A number, or a string holding one, which some models send instead. */
     readonly delayMinutes?: number | string;
     readonly at?: string;
     readonly sessionID?: string;
 }
-/** Stores a message for later delivery; the scheduler in `deliverDue` sends it once it is due. */
 export declare function schedule(ports: LaterPorts, from: string, input: LaterInput): Promise<LaterEntry>;
-/** Drops a pending message; false when there was none, e.g. it was already delivered. */
 export declare function cancel(ports: LaterPorts, id: string): Promise<boolean>;
-/** The messages scheduled for a session that have not been delivered yet. */
 export declare function scheduledFor(storage: Pick<Storage, "scan">, sessionID: string): Promise<LaterEntry[]>;
-/** Cancels every message scheduled for a session; the ids of those cancelled. */
 export declare function cancelScheduled(ports: LaterPorts, sessionID: string): Promise<string[]>;
-/** Whether a session waits on a scheduled message of its own. */
 export declare function isScheduled(ports: {
     readonly storage: Pick<Storage, "scan">;
 }, sessionID: string): Promise<boolean>;
-/**
- * Delivers every due message once: an id is claimed synchronously in the shared `claimed`, re-read,
- * delivered and only then removed; a crash in between delivers it again after a restart, not never.
- */
 export declare function deliverDue(ports: LaterPorts, claimed: Set<string>): Promise<void>;
 export {};

package/dist/scheduling/later.js

@@ -1,12 +1,7 @@
 import { envelope } from "../kernel/protocol.js";
 import { scanAll } from "../platform/storage.js";
 const PREFIX = "later/";
-/** The latest time a Date can hold; a message due after it could never be shown or delivered. */
 const LATEST = 8.64e15;
-/**
- * A plain decimal number of minutes, the only string form of delayMinutes taken ("0x10" is not),
- * once trimmed of the whitespace `\s` matches.
- */
 const DECIMAL = /^(?:\d+(?:\.\d*)?|\.\d+)$/;
 function minutesOf(given) {
     if (typeof given !== "string")
@@ -34,7 +29,6 @@ function fireTime(now, input) {
         throw new Error(`at is in the past: ${input.at}`);
     return at;
 }
-/** Stores a message for later delivery; the scheduler in `deliverDue` sends it once it is due. */
 export async function schedule(ports, from, input) {
     const now = ports.now();
     const entry = {
@@ -48,7 +42,6 @@ export async function schedule(ports, from, input) {
     await ports.storage.set(PREFIX + entry.id, { ...entry });
     return entry;
 }
-/** Drops a pending message; false when there was none, e.g. it was already delivered. */
 export async function cancel(ports, id) {
     if ((await ports.storage.get(PREFIX + id)) === undefined)
         return false;
@@ -58,24 +51,17 @@ export async function cancel(ports, id) {
 function pending(ports) {
     return scanAll(ports.storage, PREFIX);
 }
-/** The messages scheduled for a session that have not been delivered yet. */
 export async function scheduledFor(storage, sessionID) {
     return (await pending({ storage: storage })).filter((entry) => entry.sessionID === sessionID);
 }
-/** Cancels every message scheduled for a session; the ids of those cancelled. */
 export async function cancelScheduled(ports, sessionID) {
     const scheduled = await scheduledFor(ports.storage, sessionID);
     const dropped = await Promise.all(scheduled.map(async (later) => ((await cancel(ports, later.id)) ? later.id : undefined)));
     return dropped.filter((id) => id !== undefined);
 }
-/** Whether a session waits on a scheduled message of its own. */
 export async function isScheduled(ports, sessionID) {
     return (await scheduledFor(ports.storage, sessionID)).length > 0;
 }
-/**
- * Delivers every due message once: an id is claimed synchronously in the shared `claimed`, re-read,
- * delivered and only then removed; a crash in between delivers it again after a restart, not never.
- */
 export async function deliverDue(ports, claimed) {
     const now = ports.now();
     for (const due of (await pending(ports)).filter((entry) => entry.fireAt <= now)) {

package/dist/scheduling/text.d.ts

@@ -1,4 +1,3 @@
-/** `own` when the message goes to the session that scheduled it. */
 export declare function laterText(entry: {
     readonly id: string;
     readonly sessionID: string;

package/dist/scheduling/text.js

@@ -1,4 +1,3 @@
-/** `own` when the message goes to the session that scheduled it. */
 export function laterText(entry, fireAt, own) {
     const next = own
         ? "It arrives when due, after your current turn if one is running, so do not wait for it: once nothing " +