opencode-superagent 0.0.0-stage → 0.1.0

package/dist/src/ticket-view.js

@@ -0,0 +1,135 @@
+/**
+ * Sidebar view model for the ticket list.
+ *
+ * The `tickets` RPC returns `renderTicketList` text rather than structured
+ * rows (the server side is deployed separately and needs a service restart to
+ * change), so the TUI parses that text back into rows and re-lays them out for
+ * the fixed-width sidebar. Everything here is pure and width-aware, which
+ * keeps the OpenTUI component in `tui.tsx` to rendering only.
+ *
+ * `src/ticket.ts` is only imported for types: valuing `TICKET_STATES` here
+ * would pull the Effect/KV store into the TUI bundle. `test/ticket-view.test.ts`
+ * asserts the local copy stays in step with the real state list.
+ */
+import { displayWidth } from "./tools.js";
+export const TICKET_STATES = [
+    "open",
+    "in_progress",
+    "blocked",
+    "done",
+    "failed",
+    "cancelled",
+    "superseded",
+];
+/**
+ * `SESSION_SIDEBAR_WIDTH` is 42 columns: 4 of horizontal padding plus the
+ * scrollbar column the sidebar reserves on the right leave 37 cells. The panel
+ * uses 36 and keeps one cell of slack, so a row can never push the sidebar
+ * into a horizontal scroll.
+ */
+export const TICKET_PANEL_WIDTH = 36;
+/** Titles are capped below the full remainder so a long one never pushes the id off-screen. */
+export const TICKET_TITLE_MAX = 26;
+/** Terminal tickets are collapsed; the panel is a glance, not an archive. */
+export const TICKET_TERMINAL_LIMIT = 3;
+export const TICKET_PANEL_LIMIT = 20;
+export const TICKET_PANEL_REFRESH_MS = 4000;
+const SHORT_ID_LENGTH = 4;
+export const TICKET_STATE_SYMBOL = {
+    open: "○",
+    in_progress: "●",
+    blocked: "◆",
+    done: "✓",
+    failed: "✗",
+    cancelled: "⊘",
+    superseded: "·",
+};
+/** Unfinished states first (running work, then stuck work, then queued), terminal ones last. */
+const STATE_RANK = {
+    in_progress: 0,
+    blocked: 1,
+    open: 2,
+    done: 3,
+    failed: 4,
+    cancelled: 5,
+    superseded: 6,
+};
+const TERMINAL = new Set(["done", "failed", "cancelled", "superseded"]);
+const GROUP_LINE = /^(open|in_progress|blocked|done|failed|cancelled|superseded) \(\d+\)$/;
+const ITEM_LINE = /^· (tk_\S+) (p[012])(?: (.*))?$/;
+/** `renderTicketList` writes `MM-DD HH:MM` (plus an optional worker suffix) under every item. */
+const TRAILER_LINE = /^\s{2}\d{2}-\d{2} \d{2}:\d{2}(?: w=\S+)?$/;
+/**
+ * Parse `renderTicketList` output. Rows arrive grouped by state and already
+ * sorted newest-first inside a group, so the input order is the time order.
+ * Unrecognised lines are ignored: a future format change degrades the panel to
+ * "no tickets" instead of breaking the sidebar.
+ */
+export function parseTicketList(text) {
+    const rows = [];
+    let state;
+    for (const line of text.split("\n")) {
+        const group = GROUP_LINE.exec(line);
+        if (group?.[1] !== undefined) {
+            state = group[1];
+            continue;
+        }
+        const item = ITEM_LINE.exec(line);
+        if (item !== null && state !== undefined) {
+            rows.push({
+                id: item[1],
+                priority: item[2],
+                state,
+                title: (item[3] ?? "").trim(),
+            });
+            continue;
+        }
+        // A wrapped title continues on indented lines; trailers are not titles.
+        if (state !== undefined && rows.length > 0 && line.startsWith("  ") && !TRAILER_LINE.test(line)) {
+            const last = rows[rows.length - 1];
+            const continuation = line.trim();
+            if (continuation !== "")
+                last.title = last.title === "" ? continuation : `${last.title} ${continuation}`;
+        }
+    }
+    return rows;
+}
+/** Truncate to `max` terminal cells (CJK counts as 2) with a trailing ellipsis. */
+export function truncateCells(text, max) {
+    if (max <= 0)
+        return "";
+    if (displayWidth(text) <= max)
+        return text;
+    let result = "";
+    let cells = 0;
+    for (const char of text) {
+        const width = displayWidth(char);
+        if (cells + width > max - 1)
+            break;
+        result += char;
+        cells += width;
+    }
+    return `${result}…`;
+}
+export function shortTicketID(ticketID) {
+    return ticketID.length <= SHORT_ID_LENGTH ? ticketID : ticketID.slice(-SHORT_ID_LENGTH);
+}
+/** Order, truncate and collapse parsed rows into what the sidebar renders. */
+export function ticketPanel(rows, width = TICKET_PANEL_WIDTH, terminalLimit = TICKET_TERMINAL_LIMIT) {
+    const titleMax = Math.min(TICKET_TITLE_MAX, width - (1 + 1 + 1 + SHORT_ID_LENGTH));
+    // `Array.prototype.sort` is stable, so newest-first survives inside a state.
+    const ordered = [...rows].sort((left, right) => STATE_RANK[left.state] - STATE_RANK[right.state]);
+    const active = ordered.filter((row) => !TERMINAL.has(row.state));
+    const terminal = ordered.filter((row) => TERMINAL.has(row.state));
+    return {
+        total: rows.length,
+        active: active.length,
+        hidden: Math.max(0, terminal.length - terminalLimit),
+        items: [...active, ...terminal.slice(0, terminalLimit)].map((row) => ({
+            id: row.id,
+            shortID: shortTicketID(row.id),
+            title: truncateCells(row.title, titleMax),
+            state: row.state,
+        })),
+    };
+}

package/dist/src/ticket.d.ts

@@ -0,0 +1,246 @@
+import type { Plugin } from "@opencode/plugin/effect";
+import { Tool } from "@opencode/schema/tool";
+import { Effect, type Schema } from "effect";
+import { type TriggerInput } from "./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 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:";
+export declare const TICKET_ALL_KEY = "ticketidx:all";
+export declare const TITLE_MAX = 80;
+export declare const OBJECTIVE_MAX = 2000;
+export declare const ACCEPTANCE_MAX = 10;
+export declare const ACCEPTANCE_ITEM_MAX = 300;
+export declare const QUOTE_MAX = 300;
+export declare const SUMMARY_MAX = 500;
+/** Index buckets are capped so a long-lived gateway never writes an unbounded list. */
+export declare const INDEX_LIMIT = 200;
+/** Newest-N tickets kept in memory; older records stay in KV and reappear after hydrate. */
+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: {
+    readonly source: string;
+    readonly threadID: string;
+    readonly objective: string;
+}): string;
+export declare const ticketKey: (id: string) => string;
+export declare const ticketStatusKey: (state: TicketState) => string;
+export declare const ticketThreadKey: (threadID: string) => string;
+/** In-memory mirror of every hydrated ticket, rebuilt from KV at startup. */
+export declare const tickets: Map<string, Ticket>;
+/**
+ * The trigger most recently delivered to the Router. `ticket_create` copies
+ * it into `authorization`, so a ticket always points at what the user said.
+ * It is a heuristic: the newest flushed trigger wins, which matches how the
+ * Router batches queued events before answering.
+ */
+export interface RouterTriggerNote {
+    readonly id: string;
+    readonly source: string;
+    readonly threadID: string;
+    readonly author?: string;
+    readonly text: string;
+    readonly at: number;
+}
+export declare function noteRouterTrigger(trigger: TriggerInput): 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;
+export declare function getTicket(ticketID: string): Ticket | undefined;
+/** Same-thread, same-dedupe-key ticket still open or in progress, if any. */
+export declare function findDuplicate(threadID: string, dedupeKey: string): Ticket | undefined;
+export declare function isActive(ticket: Ticket): boolean;
+export interface TicketStats {
+    readonly total: number;
+    readonly open: number;
+    readonly inProgress: number;
+    readonly blocked: number;
+    readonly closed: number;
+}
+export declare function ticketStats(): TicketStats;
+/** Compact "tk_x title; tk_y title" line for the system status, empty when there is nothing active. */
+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;
+export declare function validateCreateInput(input: {
+    readonly threadID?: string;
+    readonly title?: string;
+    readonly objective?: string;
+    readonly acceptance?: ReadonlyArray<string>;
+    readonly directory?: string;
+}): string | undefined;
+export declare function decodeTicket(value: Schema.Json | undefined): Ticket | undefined;
+export declare function encodeTicket(ticket: Ticket): Schema.Json;
+export interface CreateTicketInput {
+    readonly threadID: string;
+    readonly title: string;
+    readonly objective: string;
+    readonly acceptance: ReadonlyArray<string>;
+    readonly directory: string;
+    readonly source: string;
+    readonly author?: string;
+    readonly priority?: TicketPriority;
+    readonly parentTicketID?: string;
+    readonly dedupeKey?: string;
+    readonly tags?: ReadonlyArray<string>;
+    /** Defaults to the trigger most recently delivered to the Router. */
+    readonly authorization?: TicketAuthorization;
+    readonly now?: number;
+}
+export interface CreateTicketResult {
+    readonly ticket: Ticket;
+    readonly reused: boolean;
+}
+/**
+ * Create a ticket, or return the still-open same-key ticket in the same
+ * thread (`reused: true`). Objective, acceptance and directory are required;
+ * an empty acceptance is rejected so no placeholder ticket can exist.
+ */
+export declare const createTicket: (ctx: Plugin.Context, input: CreateTicketInput) => Effect.Effect<{
+    ticket: Ticket;
+    reused: boolean;
+}, Tool.Error, never>;
+export interface UpdateTicketInput {
+    readonly ticketID: string;
+    readonly state?: TicketState;
+    readonly note?: string;
+    readonly workerSessionID?: string;
+    readonly now?: number;
+}
+/** Move a ticket through the state machine. Illegal moves fail with a `Tool.Error`. */
+export declare const updateTicket: (ctx: Plugin.Context, input: UpdateTicketInput) => Effect.Effect<Ticket, Tool.Error, never>;
+export interface CloseTicketInput {
+    readonly ticketID: string;
+    readonly outcome: TicketCloseOutcome;
+    readonly summary: string;
+    readonly now?: number;
+}
+/** Close a ticket with an outcome, recording summary/closedAt in the record and history. */
+export declare const closeTicket: (ctx: Plugin.Context, input: CloseTicketInput) => Effect.Effect<Ticket, Tool.Error, never>;
+export interface ListTicketsInput {
+    readonly threadID?: string;
+    readonly status?: TicketState;
+    readonly since?: number;
+    readonly limit?: number;
+}
+/** Newest-updated first; filters are combined with AND. */
+export declare function listTickets(input?: ListTicketsInput): Array<Ticket>;
+/**
+ * Gate every dispatch must pass: a dispatch always names a ticket, and that
+ * ticket must be workable right now. The rules are enforced here (not in the
+ * prompt) so a Router cannot dispatch without a ticket, onto a closed ticket,
+ * across threads, or onto a ticket that already has a running worker.
+ */
+export declare const requireDispatchTicket: (ticketID: string | undefined, threadID: string | undefined) => Effect.Effect<Ticket, Tool.Error, never>;
+export interface LinkTicketInput {
+    readonly ticketID: string;
+    readonly sessionID: string;
+    readonly note?: string;
+    readonly now?: number;
+}
+/**
+ * Attach a dispatched worker to its ticket and move `open` to `in_progress`.
+ * Only `open`/`in_progress` tickets accept a worker.
+ */
+export declare const linkTicketToWorker: (ctx: Plugin.Context, input: LinkTicketInput) => Effect.Effect<Ticket, Tool.Error, never>;
+export interface CloseForWorkerInput {
+    readonly sessionID: string;
+    readonly outcome: "done" | "failed";
+    readonly summary?: string;
+    readonly note?: string;
+    readonly now?: number;
+}
+/**
+ * Close the in-progress ticket attached to a worker that just ended. Tickets
+ * in any other state are left alone: a closed ticket never reopens and an
+ * aborted worker is handled by its own path.
+ */
+export declare const closeTicketsForWorker: (ctx: Plugin.Context, input: CloseForWorkerInput) => Effect.Effect<Ticket | undefined, Tool.Error, never>;
+/**
+ * Load every `ticket:<id>` record and rebuild the indexes. Older workers are
+ * never backfilled: a worker with no ticket stays without one, silently.
+ */
+export declare const hydrateTickets: (ctx: Plugin.Context) => Effect.Effect<void, never, never>;
+export declare const DETAIL_WIDTH = 52;
+export declare function renderTicketList(items: ReadonlyArray<Ticket>, width?: number): string;
+export declare function renderTicketDetail(ticket: Ticket, width?: number): string;