opencode-superagent 0.2.0 → 0.2.1

package/dist/src/ticket-state.d.ts

@@ -0,0 +1,97 @@
+import type { WorkerState } from "./worker-state.js";
+/**
+ * Pure ticket domain model: records, the state machine, and the selectors
+ * shared by the ticket store, the dispatcher and the worker lifecycle.
+ *
+ * Nothing here touches the KV store, Effect or the worker registry, so this
+ * module can be imported from any layer without recreating the state ↔ ticket
+ * import cycle. `ticket.ts` keeps the effectful store and re-exports these
+ * names, so its public API is unchanged.
+ */
+export type TicketState = "open" | "in_progress" | "blocked" | "done" | "failed" | "cancelled" | "superseded";
+export type TicketPriority = "p0" | "p1" | "p2";
+export type TicketCloseOutcome = "done" | "failed" | "cancelled";
+export interface TicketRequester {
+    readonly source: string;
+    readonly threadID: string;
+    readonly author?: string;
+}
+/** Which trigger authorized the ticket: the id plus a short quote of what the user said. */
+export interface TicketAuthorization {
+    readonly triggerID: string;
+    readonly quote: string;
+    readonly at: number;
+}
+export interface TicketAttempt {
+    readonly at: number;
+    readonly sessionID?: string;
+    readonly note?: string;
+}
+export interface TicketHistoryEntry {
+    readonly at: number;
+    readonly kind: "created" | "state" | "note" | "dispatch" | "closed";
+    readonly from?: TicketState;
+    readonly to?: TicketState;
+    readonly note?: string;
+}
+export interface Ticket {
+    readonly id: string;
+    state: TicketState;
+    readonly title: string;
+    readonly objective: string;
+    readonly acceptance: ReadonlyArray<string>;
+    readonly requester: TicketRequester;
+    readonly authorization: TicketAuthorization;
+    readonly threadID: string;
+    workerSessionID?: string;
+    readonly attempts: Array<TicketAttempt>;
+    readonly priority: TicketPriority;
+    directory?: string;
+    readonly dedupeKey: string;
+    readonly parentTicketID?: string;
+    readonly tags: Array<string>;
+    readonly createdAt: number;
+    updatedAt: number;
+    closedAt?: number;
+    closeReason?: string;
+    readonly history: Array<TicketHistoryEntry>;
+}
+export declare const PRIORITIES: ReadonlyArray<TicketPriority>;
+export declare const TICKET_STATES: ReadonlyArray<TicketState>;
+/** A ticket can be dispatched while it is one of these. */
+export declare const ACTIVE_STATES: ReadonlyArray<TicketState>;
+export declare function isTerminalState(state: TicketState): boolean;
+export declare function allowedTransitions(state: TicketState): ReadonlyArray<TicketState>;
+/** Same-state moves are no-ops, not transitions. */
+export declare function canTransition(from: TicketState, to: TicketState): boolean;
+/** Human-readable reason a move is illegal, or `undefined` when it is allowed. */
+export declare function transitionError(from: TicketState, to: TicketState): string | undefined;
+/** Minimal shape a worker-bound ticket needs, so the selector stays pure and generic. */
+export interface WorkerBoundTicket {
+    readonly workerSessionID?: string;
+    readonly state: TicketState;
+}
+/**
+ * The `in_progress` ticket attached to a worker session, if any. Shared by the
+ * dispatch link and worker-end closing so both sides agree on "active ticket
+ * for this worker"; insertion order decides ties, as before.
+ */
+export declare function findActiveTicketForWorker<T extends WorkerBoundTicket>(candidates: Iterable<T>, sessionID: string): T | undefined;
+/**
+ * Ticket outcome for a worker that just ended, or `undefined` when the worker
+ * end closes nothing. `idle`/`aborted`/`running` leave the ticket for the abort
+ * path or a deliberate re-dispatch.
+ */
+export declare function closeOutcomeForWorkerState(state: WorkerState): "done" | "failed" | undefined;
+/**
+ * Reason recorded when a worker end closes its ticket: an explicit summary
+ * wins, then the caller's note, then a generated `done (worker <id>)` line.
+ * The store still compacts it to `SUMMARY_MAX` before persisting, exactly as
+ * before this helper existed.
+ */
+export declare function workerCloseSummary(input: {
+    readonly sessionID: string;
+    readonly outcome: "done" | "failed";
+    readonly summary?: string | undefined;
+    readonly note?: string | undefined;
+}): string;

package/dist/src/ticket-state.js

@@ -0,0 +1,70 @@
+export const PRIORITIES = ["p0", "p1", "p2"];
+export const TICKET_STATES = [
+    "open",
+    "in_progress",
+    "blocked",
+    "done",
+    "failed",
+    "cancelled",
+    "superseded",
+];
+/** A ticket can be dispatched while it is one of these. */
+export const ACTIVE_STATES = ["open", "in_progress"];
+const TRANSITIONS = {
+    // A ticket can close from any active state: `done`/`failed` also cover work
+    // finished outside the worker (or a dispatch that never started).
+    open: ["in_progress", "blocked", "done", "failed", "cancelled", "superseded"],
+    in_progress: ["blocked", "done", "failed", "cancelled", "superseded"],
+    blocked: ["in_progress", "done", "failed", "cancelled", "superseded"],
+    done: [],
+    failed: [],
+    cancelled: [],
+    superseded: [],
+};
+export function isTerminalState(state) {
+    return TRANSITIONS[state].length === 0;
+}
+export function allowedTransitions(state) {
+    return TRANSITIONS[state];
+}
+/** Same-state moves are no-ops, not transitions. */
+export function canTransition(from, to) {
+    return from === to || TRANSITIONS[from].includes(to);
+}
+/** Human-readable reason a move is illegal, or `undefined` when it is allowed. */
+export function transitionError(from, to) {
+    if (canTransition(from, to))
+        return undefined;
+    if (isTerminalState(from))
+        return `ticket is already closed (${from}); cannot move to ${to}`;
+    return `illegal transition ${from} -> ${to}; allowed: ${TRANSITIONS[from].join(", ")}`;
+}
+/**
+ * The `in_progress` ticket attached to a worker session, if any. Shared by the
+ * dispatch link and worker-end closing so both sides agree on "active ticket
+ * for this worker"; insertion order decides ties, as before.
+ */
+export function findActiveTicketForWorker(candidates, sessionID) {
+    for (const ticket of candidates) {
+        if (ticket.workerSessionID === sessionID && ticket.state === "in_progress")
+            return ticket;
+    }
+    return undefined;
+}
+/**
+ * Ticket outcome for a worker that just ended, or `undefined` when the worker
+ * end closes nothing. `idle`/`aborted`/`running` leave the ticket for the abort
+ * path or a deliberate re-dispatch.
+ */
+export function closeOutcomeForWorkerState(state) {
+    return state === "done" || state === "failed" ? state : undefined;
+}
+/**
+ * Reason recorded when a worker end closes its ticket: an explicit summary
+ * wins, then the caller's note, then a generated `done (worker <id>)` line.
+ * The store still compacts it to `SUMMARY_MAX` before persisting, exactly as
+ * before this helper existed.
+ */
+export function workerCloseSummary(input) {
+    return input.summary ?? input.note ?? `${input.outcome} (worker ${input.sessionID})`;
+}

package/dist/src/ticket.d.ts

@@ -1,7 +1,24 @@
 import type { Plugin } from "@opencode/plugin/effect";
 import { Tool } from "@opencode/schema/tool";
 import { Effect, type Schema } from "effect";
-import { type TriggerInput, type WorkerState } from "./state.js";
+import { type Ticket, type TicketAuthorization, type TicketCloseOutcome, type TicketPriority, type TicketState } from "./ticket-state.js";
+export type { Ticket, TicketAttempt, TicketAuthorization, TicketCloseOutcome, TicketHistoryEntry, TicketPriority, TicketRequester, TicketState, } from "./ticket-state.js";
+export { ACTIVE_STATES, allowedTransitions, canTransition, isTerminalState, TICKET_STATES, transitionError, } from "./ticket-state.js";
+export { isWorkerTerminal, TERMINAL_WORKER_STATES } from "./worker-state.js";
+/**
+ * Structural copy of the queued trigger input. The ticket layer must not import
+ * `state.ts` (that is the cycle this module just broke), and the shape is all
+ * `noteRouterTrigger` needs.
+ */
+export interface TicketTriggerNoteInput {
+    readonly id?: string;
+    readonly source: string;
+    readonly threadID: string;
+    readonly author?: string;
+    readonly text: string;
+    readonly title?: string;
+    readonly createdAt?: number;
+}
 /**
  * Ticket (work order) store for the Super-agent P0.
  *
@@ -23,54 +40,6 @@ import { type TriggerInput, type WorkerState } from "./state.js";
  *
  * `done`, `failed`, `cancelled` and `superseded` are terminal.
  */
-export type TicketState = "open" | "in_progress" | "blocked" | "done" | "failed" | "cancelled" | "superseded";
-export type TicketPriority = "p0" | "p1" | "p2";
-export type TicketCloseOutcome = "done" | "failed" | "cancelled";
-export interface TicketRequester {
-    readonly source: string;
-    readonly threadID: string;
-    readonly author?: string;
-}
-/** Which trigger authorized the ticket: the id plus a short quote of what the user said. */
-export interface TicketAuthorization {
-    readonly triggerID: string;
-    readonly quote: string;
-    readonly at: number;
-}
-export interface TicketAttempt {
-    readonly at: number;
-    readonly sessionID?: string;
-    readonly note?: string;
-}
-export interface TicketHistoryEntry {
-    readonly at: number;
-    readonly kind: "created" | "state" | "note" | "dispatch" | "closed";
-    readonly from?: TicketState;
-    readonly to?: TicketState;
-    readonly note?: string;
-}
-export interface Ticket {
-    readonly id: string;
-    state: TicketState;
-    readonly title: string;
-    readonly objective: string;
-    readonly acceptance: ReadonlyArray<string>;
-    readonly requester: TicketRequester;
-    readonly authorization: TicketAuthorization;
-    readonly threadID: string;
-    workerSessionID?: string;
-    readonly attempts: Array<TicketAttempt>;
-    readonly priority: TicketPriority;
-    directory?: string;
-    readonly dedupeKey: string;
-    readonly parentTicketID?: string;
-    readonly tags: Array<string>;
-    readonly createdAt: number;
-    updatedAt: number;
-    closedAt?: number;
-    closeReason?: string;
-    readonly history: Array<TicketHistoryEntry>;
-}
 export declare const TICKET_PREFIX = "ticket:";
 export declare const TICKET_STATUS_PREFIX = "ticketidx:status:";
 export declare const TICKET_THREAD_PREFIX = "ticketidx:thread:";
@@ -87,15 +56,6 @@ export declare const INDEX_LIMIT = 200;
 export declare const MEMORY_LIMIT = 500;
 export declare const LIST_DEFAULT = 20;
 export declare const LIST_MAX = 100;
-export declare const TICKET_STATES: ReadonlyArray<TicketState>;
-/** A ticket can be dispatched while it is one of these. */
-export declare const ACTIVE_STATES: ReadonlyArray<TicketState>;
-export declare function isTerminalState(state: TicketState): boolean;
-export declare function allowedTransitions(state: TicketState): ReadonlyArray<TicketState>;
-/** Same-state moves are no-ops, not transitions. */
-export declare function canTransition(from: TicketState, to: TicketState): boolean;
-/** Human-readable reason a move is illegal, or `undefined` when it is allowed. */
-export declare function transitionError(from: TicketState, to: TicketState): string | undefined;
 /** Lowercased, whitespace-collapsed objective, so wording drift does not defeat dedupe. */
 export declare function normalizeObjective(text: string): string;
 export declare function dedupeKeyFor(input: {
@@ -122,7 +82,7 @@ export interface RouterTriggerNote {
     readonly text: string;
     readonly at: number;
 }
-export declare function noteRouterTrigger(trigger: TriggerInput): void;
+export declare function noteRouterTrigger(trigger: TicketTriggerNoteInput): void;
 export declare function currentTrigger(): RouterTriggerNote | undefined;
 /** Reset memory (hydrate and tests): the map and its thread index are rebuilt together. */
 export declare function resetTickets(): void;
@@ -142,13 +102,6 @@ export declare function ticketStats(): TicketStats;
 export declare function activeTicketSummary(threadID: string | undefined, limit?: number): string;
 /** Active ticket for a worker session, used when a worker ends. */
 export declare function activeTicketForWorker(sessionID: string): Ticket | undefined;
-/**
- * Worker states after which the ticket may be dispatched again. `idle` is not
- * here on purpose: an idle session can still be resumed, so a re-dispatch
- * would race a live worker.
- */
-export declare const TERMINAL_WORKER_STATES: ReadonlyArray<WorkerState>;
-export declare function isWorkerTerminal(state: WorkerState): boolean;
 export declare function validateCreateInput(input: {
     readonly threadID?: string;
     readonly title?: string;

package/dist/src/ticket.js

@@ -2,8 +2,32 @@ import { Tool } from "@opencode/schema/tool";
 import { Effect } from "effect";
 import { createHash } from "node:crypto";
 import { normalizeDirectory } from "./dirs.js";
-import { store } from "./state.js";
+import { ACTIVE_STATES, findActiveTicketForWorker, isTerminalState, PRIORITIES, TICKET_STATES, transitionError, workerCloseSummary, } from "./ticket-state.js";
+import { isWorkerTerminal, workers } from "./worker-state.js";
 import { displayWidth, wrapText } from "./tools.js";
+export { ACTIVE_STATES, allowedTransitions, canTransition, isTerminalState, TICKET_STATES, transitionError, } from "./ticket-state.js";
+export { isWorkerTerminal, TERMINAL_WORKER_STATES } from "./worker-state.js";
+/**
+ * Ticket (work order) store for the Super-agent P0.
+ *
+ * A ticket is the durable statement of "what the user asked for and how we
+ * will know it is done". The Router creates one before dispatching work; the
+ * dispatch records the worker session on it and the worker's terminal state
+ * closes it. Records live in KV under `ticket:<id>`; the `ticketidx:*` keys
+ * are derived accelerators, so hydration always rebuilds them from the
+ * record prefix (a lost index never loses a ticket).
+ *
+ * State machine:
+ *
+ *   open ─┬─▶ in_progress ─┬─▶ done
+ *         │                ├─▶ failed
+ *         │                ├─▶ blocked ──▶ in_progress
+ *         ├─▶ blocked      └─▶ cancelled
+ *         ├─▶ cancelled
+ *         └─▶ superseded
+ *
+ * `done`, `failed`, `cancelled` and `superseded` are terminal.
+ */
 export const TICKET_PREFIX = "ticket:";
 export const TICKET_STATUS_PREFIX = "ticketidx:status:";
 export const TICKET_THREAD_PREFIX = "ticketidx:thread:";
@@ -20,47 +44,6 @@ export const INDEX_LIMIT = 200;
 export const MEMORY_LIMIT = 500;
 export const LIST_DEFAULT = 20;
 export const LIST_MAX = 100;
-const PRIORITIES = ["p0", "p1", "p2"];
-export const TICKET_STATES = [
-    "open",
-    "in_progress",
-    "blocked",
-    "done",
-    "failed",
-    "cancelled",
-    "superseded",
-];
-/** A ticket can be dispatched while it is one of these. */
-export const ACTIVE_STATES = ["open", "in_progress"];
-const TRANSITIONS = {
-    // A ticket can close from any active state: `done`/`failed` also cover work
-    // finished outside the worker (or a dispatch that never started).
-    open: ["in_progress", "blocked", "done", "failed", "cancelled", "superseded"],
-    in_progress: ["blocked", "done", "failed", "cancelled", "superseded"],
-    blocked: ["in_progress", "done", "failed", "cancelled", "superseded"],
-    done: [],
-    failed: [],
-    cancelled: [],
-    superseded: [],
-};
-export function isTerminalState(state) {
-    return TRANSITIONS[state].length === 0;
-}
-export function allowedTransitions(state) {
-    return TRANSITIONS[state];
-}
-/** Same-state moves are no-ops, not transitions. */
-export function canTransition(from, to) {
-    return from === to || TRANSITIONS[from].includes(to);
-}
-/** Human-readable reason a move is illegal, or `undefined` when it is allowed. */
-export function transitionError(from, to) {
-    if (canTransition(from, to))
-        return undefined;
-    if (isTerminalState(from))
-        return `ticket is already closed (${from}); cannot move to ${to}`;
-    return `illegal transition ${from} -> ${to}; allowed: ${TRANSITIONS[from].join(", ")}`;
-}
 /** Lowercased, whitespace-collapsed objective, so wording drift does not defeat dedupe. */
 export function normalizeObjective(text) {
     return text.toLowerCase().replace(/\s+/g, " ").trim();
@@ -162,16 +145,7 @@ export function activeTicketSummary(threadID, limit = 3) {
 }
 /** Active ticket for a worker session, used when a worker ends. */
 export function activeTicketForWorker(sessionID) {
-    return [...tickets.values()].find((ticket) => ticket.workerSessionID === sessionID && ticket.state === "in_progress");
-}
-/**
- * Worker states after which the ticket may be dispatched again. `idle` is not
- * here on purpose: an idle session can still be resumed, so a re-dispatch
- * would race a live worker.
- */
-export const TERMINAL_WORKER_STATES = ["done", "failed", "aborted"];
-export function isWorkerTerminal(state) {
-    return TERMINAL_WORKER_STATES.includes(state);
+    return findActiveTicketForWorker(tickets.values(), sessionID);
 }
 // ── validation ────────────────────────────────────────────────────────────────
 export function validateCreateInput(input) {
@@ -568,7 +542,7 @@ export const requireDispatchTicket = Effect.fn("superagent.requireDispatchTicket
     // a re-dispatch exactly like `running`. A worker record that is gone blocks
     // nothing: there is no live worker left to wait for.
     const workerID = ticket.workerSessionID;
-    const worker = workerID === undefined ? undefined : store.workers.get(workerID);
+    const worker = workerID === undefined ? undefined : workers.get(workerID);
     if (workerID !== undefined && worker !== undefined && !isWorkerTerminal(worker.state)) {
         const article = worker.state === "idle" ? "an" : "a";
         return yield* new Tool.Error({
@@ -619,7 +593,7 @@ export const closeTicketsForWorker = Effect.fn("superagent.closeTicketsForWorker
     return yield* closeTicket(ctx, {
         ticketID: ticket.id,
         outcome: input.outcome,
-        summary: input.summary ?? input.note ?? `${input.outcome} (worker ${input.sessionID})`,
+        summary: workerCloseSummary(input),
         ...(input.now === undefined ? {} : { now: input.now }),
     });
 });

package/dist/src/tools.js

@@ -150,11 +150,14 @@ export const ROUTER_TOOL_SPECS = [
         name: "status",
         group: "query",
         description: "Show a compact summary of the router, pending triggers and worker sessions.",
-        summary: "查看 Router、pending 触发器数量与全部 Worker 的 thread/状态/最近报告。",
+        summary: "查看插件版本、Router、pending 触发器数量与全部 Worker 的 thread/状态/最近报告。",
         params: [],
         risk: "read",
         confirmation: "只读，自动执行（permission: status）。",
-        usage: ["system 状态行只给计数，细节用 status / thread_detail。"],
+        usage: [
+            "首行是插件版本与「升级后需重启网关」提示，用来判断网关是否还在跑旧代码。",
+            "system 状态行只给计数，细节用 status / thread_detail。",
+        ],
     },
     {
         name: "thread_detail",

package/dist/src/version.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Plugin version, read from the package's own `package.json`.
+ *
+ * The version is the only thing this module exposes: it is deliberately not a
+ * diagnostics dump, so logging it can never leak config, tokens, absolute
+ * paths or session ids.
+ */
+/** Shown when no candidate `package.json` can be read or parsed. */
+export declare const UNKNOWN_VERSION = "0.0.0-unknown";
+/** Extract `version` from raw `package.json` text; `undefined` when unusable. */
+export declare function versionFromPackageJson(raw: string): string | undefined;
+export type ReadFile = (file: string) => string | undefined;
+/**
+ * Read the first usable candidate, falling back to {@link UNKNOWN_VERSION}.
+ *
+ * `read` is injectable so the fallback path is testable without touching the
+ * filesystem: pass `() => undefined` for a missing package, or a stub that
+ * returns unparsable JSON.
+ */
+export declare function loadVersion(read?: ReadFile): string;
+/** Cached plugin version; the process never changes version at runtime. */
+export declare function pluginVersion(): string;
+/**
+ * One-line startup notice. Says what is loaded and that upgrading an already
+ * running gateway is not enough — the plugin has no hot reload, so a service
+ * restart is required before the new code is active.
+ */
+export declare function versionNotice(): string;

package/dist/src/version.js

@@ -0,0 +1,76 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+/**
+ * Plugin version, read from the package's own `package.json`.
+ *
+ * The version is the only thing this module exposes: it is deliberately not a
+ * diagnostics dump, so logging it can never leak config, tokens, absolute
+ * paths or session ids.
+ */
+/** Shown when no candidate `package.json` can be read or parsed. */
+export const UNKNOWN_VERSION = "0.0.0-unknown";
+/**
+ * `package.json` locations relative to this module, most specific first:
+ * - source (dev / tests): `src/version.ts` → `../package.json`
+ * - build output: `dist/src/version.js` → `../../package.json`
+ *
+ * Both are tried so the same code works in the repo and in a packed tarball.
+ */
+const CANDIDATES = ["../package.json", "../../package.json"];
+/** Extract `version` from raw `package.json` text; `undefined` when unusable. */
+export function versionFromPackageJson(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return undefined;
+    const value = parsed.version;
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+function readRelative(file) {
+    try {
+        return readFileSync(path.resolve(import.meta.dir, file), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read the first usable candidate, falling back to {@link UNKNOWN_VERSION}.
+ *
+ * `read` is injectable so the fallback path is testable without touching the
+ * filesystem: pass `() => undefined` for a missing package, or a stub that
+ * returns unparsable JSON.
+ */
+export function loadVersion(read = readRelative) {
+    for (const candidate of CANDIDATES) {
+        const raw = read(candidate);
+        if (raw === undefined)
+            continue;
+        const version = versionFromPackageJson(raw);
+        if (version !== undefined)
+            return version;
+    }
+    return UNKNOWN_VERSION;
+}
+let cached;
+/** Cached plugin version; the process never changes version at runtime. */
+export function pluginVersion() {
+    cached ??= loadVersion();
+    return cached;
+}
+/**
+ * One-line startup notice. Says what is loaded and that upgrading an already
+ * running gateway is not enough — the plugin has no hot reload, so a service
+ * restart is required before the new code is active.
+ */
+export function versionNotice() {
+    return `superagent ${pluginVersion()} loaded; restart the OpenCode gateway after upgrading (no hot reload)`;
+}

package/dist/src/watcher.js

@@ -3,6 +3,7 @@ import { buildReport, lastAssistantText, reportNotice, reportSummary, saveReport
 import { ensureRouter } from "./router.js";
 import { saveWorker, store, toSessionID } from "./state.js";
 import { closeTicketsForWorker } from "./ticket.js";
+import { closeOutcomeForWorkerState } from "./ticket-state.js";
 /**
  * Capture one finished report: the complete text goes to `report:<sessionID>`
  * first, then the worker record keeps a short summary for status lines and the
@@ -75,11 +76,12 @@ const handleEnded = Effect.fn("superagent.workerEnded")(function* (ctx, sessionI
     // A worker that reached a terminal state closes its in-progress ticket.
     // Interruptions (`idle`) leave it open: the abort tool closes it explicitly
     // and a plain interrupt may still be resumed with a follow-up.
-    if (state === "done" || state === "failed") {
+    const closeOutcome = closeOutcomeForWorkerState(state);
+    if (closeOutcome !== undefined) {
         yield* closeTicketsForWorker(ctx, {
             sessionID,
-            outcome: state,
-            summary: worker.lastReport ?? report ?? detail ?? `${state} (worker ${sessionID})`,
+            outcome: closeOutcome,
+            summary: worker.lastReport ?? report ?? detail ?? `${closeOutcome} (worker ${sessionID})`,
         }).pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to close ticket for ended worker", { sessionID, cause })));
     }
     // Keep the thread subscriptions after the worker ends: follow-ups on the

package/dist/src/worker-state.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Worker records and the in-memory worker registry they live in.
+ *
+ * This module is intentionally dependency-free: `state.ts` owns KV persistence
+ * and the rest of the store, while the ticket layer only needs to look up a
+ * worker's state when it gates a dispatch. Keeping the record type and the
+ * registry map here lets `ticket.ts` avoid importing `state.ts`, which is what
+ * breaks the state ↔ ticket import cycle. `store.workers` in `state.ts` is the
+ * same map instance, so both layers always see one registry.
+ */
+export type WorkerState = "running" | "idle" | "failed" | "done" | "aborted";
+export declare const WORKER_STATES: ReadonlyArray<WorkerState>;
+export interface WorkerRecord {
+    readonly sessionID: string;
+    readonly title?: string;
+    /**
+     * Primary thread this worker was dispatched for. Legacy records decode to
+     * `""` and `hydrate` backfills it from `thread.workers`, so every live record
+     * carries a forward link to its thread without losing the multi-thread
+     * `threads` list.
+     */
+    threadID: string;
+    /** Trigger that authorized the dispatch, when the record knows it. */
+    triggerID?: string;
+    readonly threads: Array<string>;
+    state: WorkerState;
+    readonly createdAt: number;
+    /** Last persisted write. Refreshed by `saveWorker`, so an aborted record keeps a traceable timestamp. */
+    updatedAt?: number;
+    lastReport?: string;
+    directory?: string;
+}
+/** Canonical in-memory worker registry; `store.workers` points at this map. */
+export declare const workers: Map<string, WorkerRecord>;
+/**
+ * Worker states after which the ticket may be dispatched again. `idle` is not
+ * here on purpose: an idle session can still be resumed, so a re-dispatch
+ * would race a live worker.
+ */
+export declare const TERMINAL_WORKER_STATES: ReadonlyArray<WorkerState>;
+export declare function isWorkerTerminal(state: WorkerState): boolean;

package/dist/src/worker-state.js

@@ -0,0 +1,22 @@
+/**
+ * Worker records and the in-memory worker registry they live in.
+ *
+ * This module is intentionally dependency-free: `state.ts` owns KV persistence
+ * and the rest of the store, while the ticket layer only needs to look up a
+ * worker's state when it gates a dispatch. Keeping the record type and the
+ * registry map here lets `ticket.ts` avoid importing `state.ts`, which is what
+ * breaks the state ↔ ticket import cycle. `store.workers` in `state.ts` is the
+ * same map instance, so both layers always see one registry.
+ */
+export const WORKER_STATES = ["running", "idle", "failed", "done", "aborted"];
+/** Canonical in-memory worker registry; `store.workers` points at this map. */
+export const workers = new Map();
+/**
+ * Worker states after which the ticket may be dispatched again. `idle` is not
+ * here on purpose: an idle session can still be resumed, so a re-dispatch
+ * would race a live worker.
+ */
+export const TERMINAL_WORKER_STATES = ["done", "failed", "aborted"];
+export function isWorkerTerminal(state) {
+    return TERMINAL_WORKER_STATES.includes(state);
+}

package/dist/tui.js

@@ -151,11 +151,14 @@ var ROUTER_TOOL_SPECS = [
     name: "status",
     group: "query",
     description: "Show a compact summary of the router, pending triggers and worker sessions.",
-    summary: "\u67E5\u770B Router\u3001pending \u89E6\u53D1\u5668\u6570\u91CF\u4E0E\u5168\u90E8 Worker \u7684 thread/\u72B6\u6001/\u6700\u8FD1\u62A5\u544A\u3002",
+    summary: "\u67E5\u770B\u63D2\u4EF6\u7248\u672C\u3001Router\u3001pending \u89E6\u53D1\u5668\u6570\u91CF\u4E0E\u5168\u90E8 Worker \u7684 thread/\u72B6\u6001/\u6700\u8FD1\u62A5\u544A\u3002",
     params: [],
     risk: "read",
     confirmation: "\u53EA\u8BFB\uFF0C\u81EA\u52A8\u6267\u884C\uFF08permission: status\uFF09\u3002",
-    usage: ["system \u72B6\u6001\u884C\u53EA\u7ED9\u8BA1\u6570\uFF0C\u7EC6\u8282\u7528 status / thread_detail\u3002"]
+    usage: [
+      "\u9996\u884C\u662F\u63D2\u4EF6\u7248\u672C\u4E0E\u300C\u5347\u7EA7\u540E\u9700\u91CD\u542F\u7F51\u5173\u300D\u63D0\u793A\uFF0C\u7528\u6765\u5224\u65AD\u7F51\u5173\u662F\u5426\u8FD8\u5728\u8DD1\u65E7\u4EE3\u7801\u3002",
+      "system \u72B6\u6001\u884C\u53EA\u7ED9\u8BA1\u6570\uFF0C\u7EC6\u8282\u7528 status / thread_detail\u3002"
+    ]
   },
   {
     name: "thread_detail",
@@ -476,6 +479,7 @@ var Definition = Rpc.define({
     status: {
       input: Schema.toStandardSchemaV1(Schema.Struct({})),
       output: Schema.toStandardSchemaV1(Schema.Struct({
+        version: Schema.optionalKey(Schema.String),
         router: Schema.optionalKey(Schema.String),
         pending: Schema.Number,
         workers: Schema.Array(Schema.Struct({
@@ -530,7 +534,8 @@ var Definition = Rpc.define({
     },
     stop: {
       input: Schema.toStandardSchemaV1(Schema.Struct({ sessionID: Schema.String })),
-      output: Schema.toStandardSchemaV1(Schema.Struct({ interrupted: Schema.Boolean }))
+      output: Schema.toStandardSchemaV1(Schema.Struct({ interrupted: Schema.Boolean })),
+      errors: { "stop.rejected": Schema.toStandardSchemaV1(Schema.Struct({})) }
     },
     abort: {
       input: Schema.toStandardSchemaV1(Schema.Struct({

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-superagent",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Superagent: a resident router agent that dispatches background worker agents in OpenCode",
   "type": "module",
   "license": "MIT",
@@ -43,6 +43,7 @@
     "prepare": "bun run build",
     "prepack": "bun run build",
     "test": "bun test",
+    "test:e2e": "bun run e2e/plugin-load.e2e.ts",
     "typecheck": "bun check --no-script",
     "typecheck:tsc": "tsc --noEmit"
   },