opencode-superagent 0.0.0-stage → 0.2.0

package/dist/src/state.js

@@ -0,0 +1,480 @@
+import { DateTime, Effect } from "effect";
+import { buildReport, lastAssistantText, reportSummary, saveReport } from "./report.js";
+import { closeTicketsForWorker } from "./ticket.js";
+const ROUTES = ["router", "worker"];
+/** Host context for fire-and-forget KV writes from synchronous interception points. Set during hydrate. */
+let persistHost;
+export function triggerIdFor(input) {
+    return input.id ?? `${input.source}:${input.threadID}:${input.createdAt ?? Date.now()}`;
+}
+function normalizeTrigger(input) {
+    return {
+        ...input,
+        id: triggerIdFor(input),
+        createdAt: input.createdAt ?? Date.now(),
+    };
+}
+function schedulePersist(record) {
+    const host = persistHost;
+    if (host === undefined)
+        return;
+    const snapshot = { ...record };
+    Effect.runFork(persistTrigger(host, snapshot).pipe(Effect.catchCause(() => Effect.void)));
+}
+function rememberQueued(input) {
+    const id = input.id ?? triggerIdFor(input);
+    const delivered = store.triggers.get(id);
+    const record = {
+        id,
+        source: input.source,
+        threadID: input.threadID,
+        ...(input.author === undefined ? {} : { author: input.author }),
+        text: input.text,
+        ...(input.title === undefined ? {} : { title: input.title }),
+        createdAt: input.createdAt ?? Date.now(),
+        ...(delivered !== undefined && delivered.route !== undefined ? { route: delivered.route } : {}),
+        ...(delivered !== undefined && delivered.sessionID !== undefined ? { sessionID: delivered.sessionID } : {}),
+    };
+    if (!store.triggers.has(id))
+        store.triggerTotal += 1;
+    store.triggers.set(id, record);
+    schedulePersist(record);
+}
+function markFlushed(removed) {
+    for (const item of removed) {
+        const id = item.trigger.id ?? triggerIdFor(item.trigger);
+        const record = store.triggers.get(id);
+        if (record === undefined)
+            continue;
+        record.route = "router";
+        if (store.routerID !== undefined)
+            record.sessionID = store.routerID;
+        schedulePersist(record);
+    }
+}
+/**
+ * Queue that transparently records trigger history. `server.ts` and
+ * `router.ts` keep using plain `push`/`splice`; interception here writes
+ * the memory map synchronously and persists to KV in the background, so
+ * no caller changes are needed.
+ */
+export class PendingQueue extends Array {
+    push(...items) {
+        const normalized = items.map((item) => ({ trigger: normalizeTrigger(item.trigger), arrivedAt: item.arrivedAt }));
+        for (const item of normalized)
+            rememberQueued(item.trigger);
+        return super.push(...normalized);
+    }
+    splice(start, deleteCount, ...items) {
+        const removed = deleteCount === undefined ? super.splice(start) : super.splice(start, deleteCount, ...items);
+        if (removed.length > 0)
+            markFlushed(removed);
+        return removed;
+    }
+}
+/**
+ * Record a trigger delivered straight to a worker (it never passes the
+ * pending queue). The text comes from the admitted prompt, so it carries
+ * the same truncation as the worker-visible format; queued triggers keep
+ * their full text via `rememberQueued`.
+ */
+export function upsertDirectTrigger(input, sessionID) {
+    const existing = store.triggers.get(input.id);
+    if (existing !== undefined) {
+        if (existing.route === undefined)
+            existing.route = "worker";
+        if (existing.sessionID === undefined)
+            existing.sessionID = sessionID;
+        schedulePersist(existing);
+        return existing;
+    }
+    const record = {
+        id: input.id,
+        source: input.source,
+        threadID: input.threadID,
+        ...(input.author === undefined ? {} : { author: input.author }),
+        text: input.text,
+        createdAt: input.createdAt,
+        route: "worker",
+        sessionID,
+    };
+    store.triggers.set(input.id, record);
+    store.triggerTotal += 1;
+    schedulePersist(record);
+    return record;
+}
+export const store = {
+    routerID: undefined,
+    routerBusy: false,
+    workers: new Map(),
+    threads: new Map(),
+    pending: new PendingQueue(),
+    triggers: new Map(),
+    triggerTotal: 0,
+};
+export const ROUTER_KEY = "router";
+export const WORKER_PREFIX = "worker:";
+export const THREAD_PREFIX = "thread:";
+export const TRIGGER_PREFIX = "trigger:";
+const RECENT_TRIGGER_LIMIT = 200;
+export const workerKey = (sessionID) => `${WORKER_PREFIX}${sessionID}`;
+export const threadKey = (threadID) => `${THREAD_PREFIX}${threadID}`;
+export const triggerKey = (id) => `${TRIGGER_PREFIX}${id}`;
+/** Brands are compile-time only, so a validated session id string converts freely. */
+export const toSessionID = (id) => id;
+/** A Session is running while `time.busy` is newer than the last completed execution's `time.idle`. */
+export function isRunning(info) {
+    const busy = info.time.busy;
+    if (busy === undefined)
+        return false;
+    const idle = info.time.idle;
+    return idle === undefined || DateTime.toEpochMillis(busy) > DateTime.toEpochMillis(idle);
+}
+const STATES = ["running", "idle", "failed", "done", "aborted"];
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function optionalString(record, key) {
+    const value = record[key];
+    return typeof value === "string" ? value : undefined;
+}
+function optionalNumber(record, key) {
+    const value = record[key];
+    return typeof value === "number" ? value : undefined;
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    if (!value.every((item) => typeof item === "string"))
+        return undefined;
+    return [...value];
+}
+export function decodeWorker(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (typeof value["sessionID"] !== "string")
+        return undefined;
+    if (typeof value["state"] !== "string" || !STATES.includes(value["state"]))
+        return undefined;
+    const threads = stringArray(value["threads"]);
+    if (threads === undefined)
+        return undefined;
+    const createdAt = optionalNumber(value, "createdAt") ?? 0;
+    const triggerID = optionalString(value, "triggerID");
+    return {
+        sessionID: value["sessionID"],
+        title: optionalString(value, "title"),
+        // Legacy records have no `threadID`; hydrate backfills it from the thread
+        // record (or `threads[0]`) and persists the result.
+        threadID: optionalString(value, "threadID") ?? "",
+        ...(triggerID === undefined ? {} : { triggerID }),
+        threads,
+        state: value["state"],
+        createdAt,
+        updatedAt: optionalNumber(value, "updatedAt") ?? createdAt,
+        lastReport: optionalString(value, "lastReport"),
+        ...(optionalString(value, "directory") === undefined ? {} : { directory: optionalString(value, "directory") }),
+    };
+}
+export function decodeThread(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (typeof value["threadID"] !== "string")
+        return undefined;
+    const workers = stringArray(value["workers"]);
+    if (workers === undefined)
+        return undefined;
+    return {
+        threadID: value["threadID"],
+        workers,
+        updatedAt: optionalNumber(value, "updatedAt") ?? 0,
+    };
+}
+export function decodeTrigger(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (typeof value["id"] !== "string")
+        return undefined;
+    if (typeof value["source"] !== "string")
+        return undefined;
+    if (typeof value["threadID"] !== "string")
+        return undefined;
+    if (typeof value["text"] !== "string")
+        return undefined;
+    const route = value["route"];
+    if (route !== undefined && (typeof route !== "string" || !ROUTES.includes(route)))
+        return undefined;
+    const sessionID = optionalString(value, "sessionID");
+    const workerIDs = stringArray(value["workerIDs"]);
+    return {
+        id: value["id"],
+        source: value["source"],
+        threadID: value["threadID"],
+        author: optionalString(value, "author"),
+        text: value["text"],
+        title: optionalString(value, "title"),
+        createdAt: optionalNumber(value, "createdAt") ?? 0,
+        ...(route === undefined ? {} : { route: route }),
+        ...(sessionID === undefined ? {} : { sessionID }),
+        ...(workerIDs === undefined || workerIDs.length === 0 ? {} : { workerIDs }),
+    };
+}
+export function encodeWorker(record) {
+    return {
+        sessionID: record.sessionID,
+        ...(record.title === undefined ? {} : { title: record.title }),
+        ...(record.threadID === "" ? {} : { threadID: record.threadID }),
+        ...(record.triggerID === undefined ? {} : { triggerID: record.triggerID }),
+        threads: [...record.threads],
+        state: record.state,
+        createdAt: record.createdAt,
+        ...(record.updatedAt === undefined ? {} : { updatedAt: record.updatedAt }),
+        ...(record.lastReport === undefined ? {} : { lastReport: record.lastReport }),
+        ...(record.directory === undefined ? {} : { directory: record.directory }),
+    };
+}
+export function encodeThread(record) {
+    return {
+        threadID: record.threadID,
+        workers: [...record.workers],
+        updatedAt: record.updatedAt,
+    };
+}
+export function encodeTrigger(record) {
+    return {
+        id: record.id,
+        source: record.source,
+        threadID: record.threadID,
+        ...(record.author === undefined ? {} : { author: record.author }),
+        text: record.text,
+        ...(record.title === undefined ? {} : { title: record.title }),
+        createdAt: record.createdAt,
+        ...(record.route === undefined ? {} : { route: record.route }),
+        ...(record.sessionID === undefined ? {} : { sessionID: record.sessionID }),
+        ...(record.workerIDs === undefined || record.workerIDs.length === 0 ? {} : { workerIDs: [...record.workerIDs] }),
+    };
+}
+const persistWorker = Effect.fn("superagent.persistWorker")(function* (ctx, record) {
+    yield* ctx.storage
+        .set(workerKey(record.sessionID), encodeWorker(record))
+        .pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to persist worker", { cause })));
+});
+const persistTrigger = Effect.fn("superagent.persistTrigger")(function* (ctx, record) {
+    yield* ctx.storage
+        .set(triggerKey(record.id), encodeTrigger(record))
+        .pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to persist trigger", { cause })));
+});
+const removeWorker = Effect.fn("superagent.removeWorker")(function* (ctx, sessionID) {
+    store.workers.delete(sessionID);
+    yield* ctx.storage
+        .remove(workerKey(sessionID))
+        .pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to remove worker", { cause })));
+});
+/**
+ * Reconcile one hydrated `running` record with the live session. A session
+ * that is still executing keeps `running`; one that finished while the plugin
+ * was down is backfilled the same way the watcher would have handled it:
+ * capture the last assistant report, persist the terminal/interrupted state,
+ * and close its ticket for `done`/`failed`.
+ */
+const reconcileRunningWorker = Effect.fn("superagent.reconcileRunningWorker")(function* (ctx, record, info) {
+    if (isRunning(info))
+        return;
+    const state = info.outcome === "succeeded" ? "done" : info.outcome === "failed" ? "failed" : "idle";
+    record.state = state;
+    const sessions = ctx.session;
+    const messages = typeof sessions.context === "function"
+        ? yield* sessions
+            .context({ sessionID: toSessionID(record.sessionID) })
+            .pipe(Effect.catch(() => Effect.succeed([])))
+        : [];
+    const report = lastAssistantText(messages);
+    if (report !== undefined) {
+        const captured = buildReport(record.sessionID, report);
+        yield* saveReport(ctx, captured);
+        record.lastReport = reportSummary(captured);
+    }
+    yield* saveWorker(ctx, record);
+    if (state === "done" || state === "failed") {
+        yield* closeTicketsForWorker(ctx, {
+            sessionID: record.sessionID,
+            outcome: state,
+            summary: record.lastReport ?? report ?? `${state} (worker ${record.sessionID})`,
+        }).pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to close ticket for rehydrated worker", {
+            sessionID: record.sessionID,
+            cause,
+        })));
+    }
+    yield* Effect.logInfo("superagent rehydrated ended worker", { sessionID: record.sessionID, state });
+});
+/**
+ * Load KV state into the in-memory maps. Storage is the unique source of
+ * truth; every loaded session is validated with `session.get` and stale
+ * entries are cleaned from both memory and KV.
+ */
+export const hydrate = Effect.fn("superagent.hydrate")(function* (ctx) {
+    persistHost = ctx;
+    const sessions = ctx.session;
+    const storage = ctx.storage;
+    const storedRouter = yield* storage.get(ROUTER_KEY).pipe(Effect.catch(() => Effect.succeed(undefined)));
+    if (typeof storedRouter === "string") {
+        const info = yield* sessions.get({ sessionID: toSessionID(storedRouter) }).pipe(Effect.map((session) => session), Effect.catch(() => Effect.succeed(undefined)));
+        if (info === undefined) {
+            yield* storage.remove(ROUTER_KEY).pipe(Effect.catch(() => Effect.void));
+        }
+        else {
+            store.routerID = info.id;
+        }
+    }
+    let after;
+    do {
+        const page = yield* storage
+            .scan({ prefix: WORKER_PREFIX, after, limit: 100 })
+            .pipe(Effect.catch(() => Effect.succeed({ entries: [], next: undefined })));
+        for (const entry of page.entries) {
+            const record = decodeWorker(entry.value);
+            if (record === undefined) {
+                yield* storage.remove(entry.key).pipe(Effect.catch(() => Effect.void));
+                continue;
+            }
+            const info = yield* sessions.get({ sessionID: toSessionID(record.sessionID) }).pipe(Effect.map((session) => session), Effect.catch(() => Effect.succeed(undefined)));
+            if (info === undefined) {
+                yield* removeWorker(ctx, record.sessionID);
+                continue;
+            }
+            store.workers.set(record.sessionID, record);
+            if (record.state === "running")
+                yield* reconcileRunningWorker(ctx, record, info);
+        }
+        after = page.next;
+    } while (after !== undefined);
+    let threadAfter;
+    do {
+        const page = yield* storage
+            .scan({ prefix: THREAD_PREFIX, after: threadAfter, limit: 100 })
+            .pipe(Effect.catch(() => Effect.succeed({ entries: [], next: undefined })));
+        for (const entry of page.entries) {
+            const record = decodeThread(entry.value);
+            if (record === undefined) {
+                yield* storage.remove(entry.key).pipe(Effect.catch(() => Effect.void));
+                continue;
+            }
+            const alive = record.workers.filter((sessionID) => store.workers.has(sessionID));
+            if (alive.length === 0) {
+                yield* storage.remove(entry.key).pipe(Effect.catch(() => Effect.void));
+                continue;
+            }
+            store.threads.set(record.threadID, alive);
+        }
+        threadAfter = page.next;
+    } while (threadAfter !== undefined);
+    const collected = [];
+    let triggerAfter;
+    do {
+        const page = yield* storage
+            .scan({ prefix: TRIGGER_PREFIX, after: triggerAfter, limit: 100 })
+            .pipe(Effect.catch(() => Effect.succeed({ entries: [], next: undefined })));
+        for (const entry of page.entries) {
+            const record = decodeTrigger(entry.value);
+            if (record === undefined) {
+                yield* storage.remove(entry.key).pipe(Effect.catch(() => Effect.void));
+                continue;
+            }
+            collected.push(record);
+        }
+        triggerAfter = page.next;
+    } while (triggerAfter !== undefined);
+    collected.sort((left, right) => right.createdAt - left.createdAt);
+    store.triggerTotal = collected.length;
+    for (const record of collected.slice(0, RECENT_TRIGGER_LIMIT)) {
+        if (!store.triggers.has(record.id))
+            store.triggers.set(record.id, record);
+    }
+    // ── reference graph backfill (idempotent) ──────────────────────────────────
+    // New records carry `threadID`/`triggerID`/`workerIDs`; legacy records only
+    // have `threads`. Rebuild a missing edge from what is still authoritative
+    // (the thread affinity list, or the opposite edge) and persist only changed
+    // records, so a second hydrate writes nothing and only a stat line is logged.
+    let backfilledWorkers = 0;
+    let backfilledTriggers = 0;
+    for (const [threadID, workerIDs] of store.threads) {
+        for (const sessionID of workerIDs) {
+            const worker = store.workers.get(sessionID);
+            if (worker === undefined || worker.threadID !== "")
+                continue;
+            worker.threadID = threadID;
+            backfilledWorkers += 1;
+            yield* persistWorker(ctx, worker);
+        }
+    }
+    for (const worker of store.workers.values()) {
+        if (worker.threadID !== "")
+            continue;
+        const primary = worker.threads[0];
+        if (primary === undefined)
+            continue;
+        worker.threadID = primary;
+        backfilledWorkers += 1;
+        yield* persistWorker(ctx, worker);
+    }
+    for (const worker of store.workers.values()) {
+        const triggerID = worker.triggerID;
+        if (triggerID === undefined)
+            continue;
+        const trigger = store.triggers.get(triggerID);
+        if (trigger === undefined)
+            continue;
+        const ids = trigger.workerIDs ?? [];
+        if (ids.includes(worker.sessionID))
+            continue;
+        trigger.workerIDs = [...ids, worker.sessionID];
+        backfilledTriggers += 1;
+        yield* persistTrigger(ctx, trigger);
+    }
+    for (const trigger of store.triggers.values()) {
+        for (const sessionID of trigger.workerIDs ?? []) {
+            const worker = store.workers.get(sessionID);
+            if (worker === undefined || worker.triggerID !== undefined)
+                continue;
+            worker.triggerID = trigger.id;
+            backfilledWorkers += 1;
+            yield* persistWorker(ctx, worker);
+        }
+    }
+    if (backfilledWorkers > 0 || backfilledTriggers > 0) {
+        yield* Effect.logInfo("superagent reference graph backfilled", {
+            workers: backfilledWorkers,
+            triggers: backfilledTriggers,
+        });
+    }
+});
+/** Every worker write refreshes `updatedAt`, so an aborted record keeps a traceable timestamp. */
+export const saveWorker = Effect.fn("superagent.saveWorker")(function* (ctx, record) {
+    record.updatedAt = Date.now();
+    yield* persistWorker(ctx, record);
+});
+export const saveTrigger = persistTrigger;
+/**
+ * Record the worker on the trigger that authorized it (`trigger.workerIDs`),
+ * completing the reverse edge of `WorkerRecord.triggerID`. Memory holds only
+ * the newest triggers, so an older trigger is read from KV once; a missing
+ * trigger is not invented. Repeating the call is a no-op.
+ */
+export const linkTriggerToWorker = Effect.fn("superagent.linkTriggerToWorker")(function* (ctx, triggerID, sessionID) {
+    const existing = store.triggers.get(triggerID);
+    const record = existing ??
+        decodeTrigger(yield* ctx.storage.get(triggerKey(triggerID)).pipe(Effect.catch(() => Effect.succeed(undefined))));
+    if (record === undefined)
+        return false;
+    const workerIDs = record.workerIDs ?? [];
+    if (workerIDs.includes(sessionID))
+        return false;
+    record.workerIDs = [...workerIDs, sessionID];
+    yield* persistTrigger(ctx, record);
+    return true;
+});
+export const saveThread = Effect.fn("superagent.saveThread")(function* (ctx, record) {
+    yield* ctx.storage
+        .set(threadKey(record.threadID), encodeThread(record))
+        .pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to persist thread", { cause })));
+});

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

@@ -0,0 +1,45 @@
+import type { Plugin } from "@opencode/plugin/effect";
+import { Effect, Schema } from "effect";
+import { type TicketState } from "./ticket.js";
+/**
+ * Router-only ticket tools. They are a thin adapter: validation, the state
+ * machine, dedupe and KV persistence all live in `src/ticket.ts`, so the same
+ * rules apply to the dispatch and watcher links.
+ */
+export declare const TicketCreateInput: Schema.Struct<{
+    readonly threadID: Schema.String;
+    readonly title: Schema.String;
+    readonly objective: Schema.String;
+    readonly acceptance: Schema.$Array<Schema.String>;
+    readonly directory: Schema.String;
+    readonly priority: Schema.optionalKey<Schema.Literals<readonly ["p0", "p1", "p2"]>>;
+    readonly parentTicketID: Schema.optionalKey<Schema.String>;
+    readonly dedupeKey: Schema.optionalKey<Schema.String>;
+}>;
+export declare const TicketListInput: Schema.Struct<{
+    readonly threadID: Schema.optionalKey<Schema.String>;
+    readonly status: Schema.optionalKey<Schema.Literals<readonly TicketState[]>>;
+    readonly since: Schema.optionalKey<Schema.Number>;
+    readonly limit: Schema.optionalKey<Schema.Number>;
+}>;
+export declare const TicketUpdateInput: Schema.Struct<{
+    readonly ticketID: Schema.String;
+    readonly status: Schema.optionalKey<Schema.Literals<readonly TicketState[]>>;
+    readonly note: Schema.optionalKey<Schema.String>;
+}>;
+export declare const TicketCloseInput: Schema.Struct<{
+    readonly ticketID: Schema.String;
+    readonly outcome: Schema.Literals<readonly ["done", "failed", "cancelled"]>;
+    readonly summary: Schema.String;
+}>;
+interface TicketListInput {
+    readonly threadID?: string;
+    readonly status?: TicketState;
+    readonly since?: number;
+    readonly limit?: number;
+}
+/** RPC helper for the TUI: ready-to-render text, no router check (the user drove it). */
+export declare function renderTicketsText(input?: TicketListInput): string;
+export declare function renderTicketText(ticketID: string): string;
+export declare const registerTicketTools: (ctx: Plugin.Context) => Effect.Effect<void, never, import("effect/Scope").Scope>;
+export {};

package/dist/src/ticket-tools.js

@@ -0,0 +1,148 @@
+import { Effect, Schema } from "effect";
+import { requireRouter } from "./guard.js";
+import { closeTicket, createTicket, currentTrigger, getTicket, listTickets, renderTicketDetail, renderTicketList, TICKET_STATES, updateTicket, } from "./ticket.js";
+import { specFor, toolPermission } from "./tools.js";
+/**
+ * Router-only ticket tools. They are a thin adapter: validation, the state
+ * machine, dedupe and KV persistence all live in `src/ticket.ts`, so the same
+ * rules apply to the dispatch and watcher links.
+ */
+export const TicketCreateInput = Schema.Struct({
+    threadID: Schema.String,
+    title: Schema.String,
+    objective: Schema.String,
+    acceptance: Schema.Array(Schema.String),
+    directory: Schema.String,
+    priority: Schema.optionalKey(Schema.Literals(["p0", "p1", "p2"])),
+    parentTicketID: Schema.optionalKey(Schema.String),
+    dedupeKey: Schema.optionalKey(Schema.String),
+});
+export const TicketListInput = Schema.Struct({
+    threadID: Schema.optionalKey(Schema.String),
+    status: Schema.optionalKey(Schema.Literals(TICKET_STATES)),
+    since: Schema.optionalKey(Schema.Number),
+    limit: Schema.optionalKey(Schema.Number),
+});
+export const TicketUpdateInput = Schema.Struct({
+    ticketID: Schema.String,
+    status: Schema.optionalKey(Schema.Literals(TICKET_STATES)),
+    note: Schema.optionalKey(Schema.String),
+});
+export const TicketCloseInput = Schema.Struct({
+    ticketID: Schema.String,
+    outcome: Schema.Literals(["done", "failed", "cancelled"]),
+    summary: Schema.String,
+});
+const TicketRefOutput = Schema.Struct({
+    ticketID: Schema.String,
+    state: Schema.String,
+    reused: Schema.Boolean,
+});
+const TicketTextOutput = Schema.Struct({ text: Schema.String });
+const runTicketCreate = Effect.fn("superagent.ticketCreate")(function* (ctx, input, caller) {
+    yield* requireRouter(caller, "ticket_create");
+    const trigger = currentTrigger();
+    const threadID = input.threadID.trim();
+    const requester = trigger?.threadID === threadID ? trigger : undefined;
+    const result = yield* createTicket(ctx, {
+        threadID,
+        title: input.title,
+        objective: input.objective,
+        acceptance: input.acceptance,
+        directory: input.directory,
+        source: requester?.source ?? "router",
+        ...(requester?.author === undefined ? {} : { author: requester.author }),
+        ...(input.priority === undefined ? {} : { priority: input.priority }),
+        ...(input.parentTicketID === undefined ? {} : { parentTicketID: input.parentTicketID }),
+        ...(input.dedupeKey === undefined ? {} : { dedupeKey: input.dedupeKey }),
+    });
+    const ticket = result.ticket;
+    const content = result.reused
+        ? `工单 ${ticket.id} 已存在（reused，state=${ticket.state}，priority=${ticket.priority}）：${ticket.title}。dispatch 时带上 ticketID=${ticket.id}。`
+        : `工单 ${ticket.id} 已建立（state=${ticket.state}，priority=${ticket.priority}）：${ticket.title}。下一步 dispatch 时带上 ticketID=${ticket.id}。`;
+    return {
+        output: { ticketID: ticket.id, state: ticket.state, reused: result.reused },
+        content,
+    };
+});
+const runTicketList = Effect.fn("superagent.ticketList")(function* (input, caller) {
+    yield* requireRouter(caller, "ticket_list");
+    const text = renderTicketList(listTickets({
+        ...(input.threadID === undefined ? {} : { threadID: input.threadID }),
+        ...(input.status === undefined ? {} : { status: input.status }),
+        ...(input.since === undefined ? {} : { since: input.since }),
+        ...(input.limit === undefined ? {} : { limit: input.limit }),
+    }));
+    return { output: { text }, content: text };
+});
+const runTicketUpdate = Effect.fn("superagent.ticketUpdate")(function* (ctx, input, caller) {
+    yield* requireRouter(caller, "ticket_update");
+    const ticket = yield* updateTicket(ctx, {
+        ticketID: input.ticketID,
+        ...(input.status === undefined ? {} : { state: input.status }),
+        ...(input.note === undefined ? {} : { note: input.note }),
+    });
+    const content = `工单 ${ticket.id} → ${ticket.state}：${ticket.title}`;
+    return { output: { ticketID: ticket.id, state: ticket.state, reused: false }, content };
+});
+const runTicketClose = Effect.fn("superagent.ticketClose")(function* (ctx, input, caller) {
+    yield* requireRouter(caller, "ticket_close");
+    const ticket = yield* closeTicket(ctx, {
+        ticketID: input.ticketID,
+        outcome: input.outcome,
+        summary: input.summary,
+    });
+    const content = `工单 ${ticket.id} 已结单（${ticket.state}）：${ticket.closeReason ?? input.summary}`;
+    return { output: { ticketID: ticket.id, state: ticket.state, reused: false }, content };
+});
+/** RPC helper for the TUI: ready-to-render text, no router check (the user drove it). */
+export function renderTicketsText(input = {}) {
+    return renderTicketList(listTickets({
+        ...(input.threadID === undefined ? {} : { threadID: input.threadID }),
+        ...(input.status === undefined ? {} : { status: input.status }),
+        ...(input.since === undefined ? {} : { since: input.since }),
+        ...(input.limit === undefined ? {} : { limit: input.limit }),
+    }));
+}
+export function renderTicketText(ticketID) {
+    const ticket = getTicket(ticketID.trim());
+    if (ticket === undefined)
+        return `没有找到工单 ${ticketID}`;
+    return renderTicketDetail(ticket);
+}
+export const registerTicketTools = Effect.fn("superagent.registerTicketTools")(function* (ctx) {
+    yield* ctx.tool.transform((editor) => {
+        editor.add({
+            name: "ticket_create",
+            description: specFor("ticket_create").description,
+            input: TicketCreateInput,
+            output: TicketRefOutput,
+            options: { permission: toolPermission(specFor("ticket_create")) },
+            execute: (input, context) => runTicketCreate(ctx, input, context.sessionID),
+        });
+        editor.add({
+            name: "ticket_list",
+            description: specFor("ticket_list").description,
+            input: TicketListInput,
+            output: TicketTextOutput,
+            options: { permission: toolPermission(specFor("ticket_list")) },
+            execute: (input, context) => runTicketList(input, context.sessionID),
+        });
+        editor.add({
+            name: "ticket_update",
+            description: specFor("ticket_update").description,
+            input: TicketUpdateInput,
+            output: TicketRefOutput,
+            options: { permission: toolPermission(specFor("ticket_update")) },
+            execute: (input, context) => runTicketUpdate(ctx, input, context.sessionID),
+        });
+        editor.add({
+            name: "ticket_close",
+            description: specFor("ticket_close").description,
+            input: TicketCloseInput,
+            output: TicketRefOutput,
+            options: { permission: toolPermission(specFor("ticket_close")) },
+            execute: (input, context) => runTicketClose(ctx, input, context.sessionID),
+        });
+    });
+});