opencode-superagent 0.0.0-stage → 0.1.0

package/dist/src/recall.d.ts

@@ -0,0 +1,58 @@
+import type { Plugin } from "@opencode/plugin/effect";
+import { Tool } from "@opencode/schema/tool";
+import { Effect, Schema } from "effect";
+export declare const ThreadDetailInput: Schema.Struct<{
+    readonly threadID: Schema.String;
+    readonly limit: Schema.optionalKey<Schema.Number>;
+    readonly offset: Schema.optionalKey<Schema.Number>;
+}>;
+export declare const WorkerDetailInput: Schema.Struct<{
+    readonly sessionID: Schema.String;
+    readonly messages: Schema.optionalKey<Schema.Number>;
+}>;
+export declare const ReportReadInput: Schema.Struct<{
+    readonly sessionID: Schema.String;
+    readonly offset: Schema.optionalKey<Schema.Number>;
+    readonly limit: Schema.optionalKey<Schema.Number>;
+}>;
+interface ThreadDetailInput {
+    readonly threadID: string;
+    readonly limit?: number;
+    readonly offset?: number;
+}
+interface WorkerDetailInput {
+    readonly sessionID: string;
+    readonly messages?: number;
+}
+interface ReportReadInput {
+    readonly sessionID: string;
+    readonly offset?: number;
+    readonly limit?: number;
+}
+export declare const runThreadDetail: (ctx: Plugin.Context, input: ThreadDetailInput, caller: string) => Effect.Effect<{
+    output: {
+        text: string;
+    };
+    content: string;
+}, Tool.Error, never>;
+export declare const runWorkerDetail: (ctx: Plugin.Context, input: WorkerDetailInput, caller: string) => Effect.Effect<{
+    output: {
+        text: string;
+    };
+    content: string;
+}, Tool.Error, never>;
+/** Page through the full report kept at `report:<sessionID>`. */
+export declare const runReportRead: (ctx: Plugin.Context, input: ReportReadInput, caller: string) => Effect.Effect<{
+    output: {
+        text: string;
+    };
+    content: string;
+}, Tool.Error, never>;
+/**
+ * Router-only recall tools plus capture of triggers delivered straight to
+ * workers (they never pass the pending queue, so the prompt hook records
+ * them from the admitted text). Both tools reuse the `status` permission
+ * action, which the router session already allows.
+ */
+export declare const registerRecall: (ctx: Plugin.Context) => Effect.Effect<void, never, import("effect/Scope").Scope>;
+export {};

package/dist/src/recall.js

@@ -0,0 +1,309 @@
+import { Tool } from "@opencode/schema/tool";
+import { Effect, Schema } from "effect";
+import { threadDirs } from "./dirs.js";
+import { requireRouter } from "./guard.js";
+import { loadReport, REPORT_DEFAULT_LIMIT, REPORT_MAX_LIMIT, REPORT_TEXT_LIMIT, sliceReport } from "./report.js";
+import { decodeTrigger, saveTrigger, store, toSessionID, TRIGGER_PREFIX, upsertDirectTrigger, } from "./state.js";
+import { specFor, toolPermission } from "./tools.js";
+export const ThreadDetailInput = Schema.Struct({
+    threadID: Schema.String,
+    limit: Schema.optionalKey(Schema.Number),
+    offset: Schema.optionalKey(Schema.Number),
+});
+export const WorkerDetailInput = Schema.Struct({
+    sessionID: Schema.String,
+    messages: Schema.optionalKey(Schema.Number),
+});
+export const ReportReadInput = Schema.Struct({
+    sessionID: Schema.String,
+    offset: Schema.optionalKey(Schema.Number),
+    limit: Schema.optionalKey(Schema.Number),
+});
+const DetailOutput = Schema.Struct({ text: Schema.String });
+/** Single response budget: compact text, truncated with a note when over. */
+const MAX_TEXT = 6000;
+const THREAD_ITEM_LIMIT = 300;
+/** Per-message text in `worker_detail`; overridable through plugin options. */
+const MESSAGE_ITEM_LIMIT = 1500;
+const MESSAGE_ITEM_MIN = 200;
+const MESSAGE_ITEM_MAX = 4000;
+const DEFAULT_THREAD_LIMIT = 20;
+const MAX_THREAD_TAKE = 200;
+/** KV fallback is bounded: one page read at a time, so a recall never fans out into per-id reads. */
+const KV_SCAN_PAGE = 100;
+const KV_SCAN_MAX_ENTRIES = 2_000;
+/** At most this many older triggers are pulled from KV for one `thread_detail` call. */
+const KV_BACKFILL_MAX = 20;
+const DEFAULT_MESSAGE_COUNT = 5;
+const MAX_MESSAGE_COUNT = 10;
+function truncate(text, limit, hint) {
+    if (text.length <= limit)
+        return text;
+    const suffix = `(${text.length - limit} chars truncated)${hint === undefined ? "" : ` ${hint}`}`;
+    return `${text.slice(0, limit)}...${suffix}`;
+}
+/** Plugin option `worker_detail_message_limit`, clamped so one message cannot eat the whole budget. */
+function messageItemLimit(ctx) {
+    const raw = ctx.options["worker_detail_message_limit"];
+    const value = typeof raw === "number" ? raw : Number(raw);
+    if (!Number.isFinite(value))
+        return MESSAGE_ITEM_LIMIT;
+    return Math.min(MESSAGE_ITEM_MAX, Math.max(MESSAGE_ITEM_MIN, Math.floor(value)));
+}
+function fitBudget(text) {
+    if (text.length <= MAX_TEXT)
+        return text;
+    return `${text.slice(0, MAX_TEXT)}\n...(truncated to ${MAX_TEXT} chars)`;
+}
+function workerLine(sessionID) {
+    const worker = store.workers.get(sessionID);
+    if (worker === undefined)
+        return `- ${sessionID} untracked`;
+    const threads = worker.threads.length === 0 ? "-" : worker.threads.join(",");
+    const dir = worker.directory ?? "-";
+    return `- ${worker.sessionID} ${worker.title ?? "-"} [${threads}] ${worker.state} dir=${dir} ${worker.lastReport ?? "-"}`;
+}
+export const runThreadDetail = Effect.fn("superagent.threadDetail")(function* (ctx, input, caller) {
+    yield* requireRouter(caller, "thread_detail");
+    const take = Math.min(MAX_THREAD_TAKE, input.limit === undefined ? DEFAULT_THREAD_LIMIT : Math.max(1, Math.floor(input.limit)));
+    const offset = input.offset === undefined ? 0 : Math.max(0, Math.floor(input.offset));
+    const memory = [...store.triggers.values()]
+        .filter((record) => record.threadID === input.threadID)
+        .sort((left, right) => left.createdAt - right.createdAt);
+    // Memory keeps only the newest 200 triggers. When the requested window
+    // starts before that, scan the trigger prefix once (paged, bounded) and keep
+    // the older records. This is a prefix scan, not one KV read per missing id,
+    // so a stale thread cannot fan out into hundreds of round trips.
+    let triggers = memory;
+    let kvFilled = 0;
+    let kvTruncated = false;
+    if (offset + take > memory.length) {
+        const seen = new Set(memory.map((record) => record.id));
+        const found = [];
+        let scanned = 0;
+        let after;
+        // Scan the whole bounded prefix first, then keep the newest missing
+        // records: stopping at the first 20 matches would return key order, not
+        // the most recent triggers of the thread.
+        while (scanned < KV_SCAN_MAX_ENTRIES) {
+            const page = yield* ctx.storage
+                .scan({ prefix: TRIGGER_PREFIX, after, limit: KV_SCAN_PAGE })
+                .pipe(Effect.catch(() => Effect.succeed({ entries: [], next: undefined })));
+            if (page.entries.length === 0)
+                break;
+            scanned += page.entries.length;
+            for (const entry of page.entries) {
+                const record = decodeTrigger(entry.value);
+                if (record === undefined || record.threadID !== input.threadID || seen.has(record.id))
+                    continue;
+                seen.add(record.id);
+                found.push(record);
+            }
+            after = page.next;
+            if (after === undefined)
+                break;
+        }
+        found.sort((left, right) => right.createdAt - left.createdAt);
+        const older = found.slice(0, KV_BACKFILL_MAX);
+        // Still more pages or more matching records than the cap: say so instead of
+        // pretending the list is complete.
+        if (after !== undefined || found.length > KV_BACKFILL_MAX)
+            kvTruncated = true;
+        kvFilled = older.length;
+        if (older.length > 0)
+            triggers = [...memory, ...older].sort((left, right) => left.createdAt - right.createdAt);
+    }
+    const total = triggers.length;
+    const end = Math.max(0, total - offset);
+    const start = Math.max(0, end - take);
+    const shown = triggers.slice(start, end);
+    const workers = [...store.workers.values()].filter((worker) => worker.threadID === input.threadID || worker.threads.includes(input.threadID));
+    const source = kvFilled > 0 ? `memory ${memory.length} + KV ${kvFilled}` : `memory ${memory.length}`;
+    const lines = [
+        `thread ${input.threadID}: ${total} trigger(s) (${source}), ${workers.length} worker(s)`,
+        `directory: ${threadDirs.get(input.threadID) ?? "(no binding, use gateway default and confirm with user)"}`,
+        `triggers (offset=${offset}, showing ${shown.length} of ${total}):`,
+    ];
+    for (const record of shown) {
+        const at = new Date(record.createdAt).toISOString();
+        lines.push(`- [${at}] ${record.author ?? "unknown"} (${record.route ?? "queued"}): ${truncate(record.text, THREAD_ITEM_LIMIT)}`);
+    }
+    if (shown.length === 0)
+        lines.push("(no trigger in this range)");
+    if (offset >= total) {
+        lines.push(`offset ${offset} 超出已知 ${total} 条；thread_detail 每次最多从 KV 回源 ${KV_BACKFILL_MAX} 条。`);
+    }
+    if (kvTruncated) {
+        lines.push(`KV 回源已截断：本次扫描 ${KV_SCAN_MAX_ENTRIES} 条、最多补 ${KV_BACKFILL_MAX} 条，仍有更早的 trigger 未列出。`);
+    }
+    lines.push(`workers (${workers.length}):`);
+    for (const worker of workers)
+        lines.push(workerLine(worker.sessionID).slice(0, THREAD_ITEM_LIMIT));
+    const text = fitBudget(lines.join("\n"));
+    return {
+        output: { text },
+        content: text,
+    };
+});
+function assistantTexts(messages, count) {
+    const collected = [];
+    for (let index = messages.length - 1; index >= 0 && collected.length < count; index--) {
+        const message = messages[index];
+        if (typeof message !== "object" || message === null)
+            continue;
+        const typed = message;
+        if (typed.type !== "assistant" || !Array.isArray(typed.content))
+            continue;
+        const text = typed.content
+            .flatMap((part) => {
+            if (typeof part !== "object" || part === null)
+                return [];
+            const candidate = part;
+            return candidate.type === "text" && typeof candidate.text === "string" ? [candidate.text] : [];
+        })
+            .join("\n")
+            .trim();
+        if (text !== "")
+            collected.push(text);
+    }
+    return collected.reverse();
+}
+export const runWorkerDetail = Effect.fn("superagent.workerDetail")(function* (ctx, input, caller) {
+    yield* requireRouter(caller, "worker_detail");
+    const count = input.messages === undefined
+        ? DEFAULT_MESSAGE_COUNT
+        : Math.min(MAX_MESSAGE_COUNT, Math.max(1, Math.floor(input.messages)));
+    const worker = store.workers.get(input.sessionID);
+    const stored = yield* loadReport(ctx, input.sessionID);
+    const messages = yield* ctx.session
+        .context({ sessionID: toSessionID(input.sessionID) })
+        .pipe(Effect.catch(() => Effect.succeed([])));
+    const texts = assistantTexts(messages, count);
+    const handle = stored === undefined
+        ? "none (无全文记录：Worker 还没结束过，或没有 assistant 文本)"
+        : `${stored.length} chars${stored.truncated ? ` (仅存前 ${stored.text.length})` : ""}，用 report_read 读取全文`;
+    const lines = worker === undefined
+        ? [`worker ${input.sessionID}: not tracked by the router`]
+        : [
+            `worker ${worker.sessionID} ${worker.title ?? "-"} [${worker.threads.join(",") || "-"}] ${worker.state}`,
+            `directory: ${worker.directory ?? "(gateway default)"}`,
+            `report: ${worker.lastReport ?? "none"}`,
+            `report full: ${handle}`,
+        ];
+    const perMessage = messageItemLimit(ctx);
+    const hint = `用 report_read(sessionID: "${input.sessionID}") 读取全文`;
+    lines.push(`recent assistant messages (last ${texts.length} of up to ${count}):`);
+    texts.forEach((text, index) => {
+        lines.push(`${index + 1}. ${truncate(text, perMessage, hint)}`);
+    });
+    if (texts.length === 0)
+        lines.push("(no assistant text found)");
+    const text = fitBudget(lines.join("\n"));
+    return {
+        output: { text },
+        content: text,
+    };
+});
+/** Page through the full report kept at `report:<sessionID>`. */
+export const runReportRead = Effect.fn("superagent.reportRead")(function* (ctx, input, caller) {
+    yield* requireRouter(caller, "report_read");
+    const record = yield* loadReport(ctx, input.sessionID);
+    if (record === undefined) {
+        return yield* new Tool.Error({
+            message: `no stored report for ${input.sessionID}: 该 Worker 没有全文报告（可能还没结束过，或没有 assistant 文本）；先用 worker_detail 看摘要`,
+        });
+    }
+    const rawOffset = input.offset ?? 0;
+    const offset = Number.isFinite(rawOffset) ? Math.max(0, Math.floor(rawOffset)) : 0;
+    if (offset >= record.text.length) {
+        return yield* new Tool.Error({
+            message: `offset ${offset} 超出已存全文长度 ${record.text.length}${record.truncated ? `（原文 ${record.length} 字，已截断存储）` : ""}`,
+        });
+    }
+    const rawLimit = input.limit ?? REPORT_DEFAULT_LIMIT;
+    const limit = Number.isFinite(rawLimit)
+        ? Math.min(REPORT_MAX_LIMIT, Math.max(1, Math.floor(rawLimit)))
+        : REPORT_DEFAULT_LIMIT;
+    const slice = sliceReport(record, offset, limit);
+    const lines = [
+        `report ${record.sessionID}: 全文 ${record.length} 字，已存 ${record.text.length} 字${record.truncated ? `（超出 ${REPORT_TEXT_LIMIT} 字上限，已截断保存）` : ""}`,
+        `captured ${new Date(record.capturedAt).toISOString()} · 本次 [${slice.offset}, ${slice.end}) · limit=${limit}`,
+        "",
+        slice.text,
+    ];
+    if (slice.hasMore) {
+        lines.push("", `还有后续：report_read(sessionID: "${record.sessionID}", offset: ${slice.nextOffset})`);
+    }
+    else {
+        lines.push("", "已到末尾。");
+    }
+    const text = lines.join("\n");
+    return { output: { text }, content: text };
+});
+const TRIGGER_HEADER = /^\[trigger:(.+?)\] source=(\S+) thread=(\S+) author=(\S+) at=(\S+)(?:\n([\s\S]*))?$/;
+/** Parse the worker-visible trigger format back into a record (see `formatTrigger`). */
+function parseTriggerHeader(text) {
+    const match = TRIGGER_HEADER.exec(text);
+    if (match === null)
+        return undefined;
+    const id = match[1];
+    const source = match[2];
+    const threadID = match[3];
+    const author = match[4];
+    const at = match[5];
+    if (id === undefined || source === undefined || threadID === undefined || author === undefined || at === undefined) {
+        return undefined;
+    }
+    const parsed = Date.parse(at);
+    return {
+        id,
+        source,
+        threadID,
+        ...(author === "unknown" ? {} : { author }),
+        text: match[6] ?? "",
+        createdAt: Number.isNaN(parsed) ? Date.now() : parsed,
+    };
+}
+/**
+ * Router-only recall tools plus capture of triggers delivered straight to
+ * workers (they never pass the pending queue, so the prompt hook records
+ * them from the admitted text). Both tools reuse the `status` permission
+ * action, which the router session already allows.
+ */
+export const registerRecall = Effect.fn("superagent.registerRecall")(function* (ctx) {
+    yield* ctx.tool.transform((editor) => {
+        editor.add({
+            name: "thread_detail",
+            description: specFor("thread_detail").description,
+            input: ThreadDetailInput,
+            output: DetailOutput,
+            options: { permission: toolPermission(specFor("thread_detail")) },
+            execute: (input, context) => runThreadDetail(ctx, input, context.sessionID),
+        });
+        editor.add({
+            name: "worker_detail",
+            description: specFor("worker_detail").description,
+            input: WorkerDetailInput,
+            output: DetailOutput,
+            options: { permission: toolPermission(specFor("worker_detail")) },
+            execute: (input, context) => runWorkerDetail(ctx, input, context.sessionID),
+        });
+        editor.add({
+            name: "report_read",
+            description: specFor("report_read").description,
+            input: ReportReadInput,
+            output: DetailOutput,
+            options: { permission: toolPermission(specFor("report_read")) },
+            execute: (input, context) => runReportRead(ctx, input, context.sessionID),
+        });
+    });
+    yield* ctx.session.hook("prompt", (event) => Effect.gen(function* () {
+        if (!store.workers.has(event.sessionID))
+            return;
+        const parsed = parseTriggerHeader(event.prompt.text);
+        if (parsed === undefined)
+            return;
+        const record = upsertDirectTrigger(parsed, event.sessionID);
+        yield* saveTrigger(ctx, record);
+    }).pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to record direct trigger", { cause }))));
+});

package/dist/src/report.d.ts

@@ -0,0 +1,72 @@
+import type { Plugin } from "@opencode/plugin/effect";
+import type { Schema } from "effect";
+import { Effect } from "effect";
+/**
+ * Full worker reports ("spill") kept beside the compact `worker:<id>` record.
+ *
+ * The worker record keeps only a summary (`lastReport`), because it is copied
+ * into every router status line and context. The complete text lives under
+ * `report:<sessionID>` so `report_read` can page through it after the fact.
+ * Reports are intentionally not removed when the worker record disappears: a
+ * supervisor may still need the evidence. Growth is only measured and logged
+ * (see `hydrateReports`); automatic trimming is a later, separate policy.
+ */
+export declare const REPORT_PREFIX = "report:";
+/** Hard cap for one stored report. Longer reports are clipped and marked, never silently lost. */
+export declare const REPORT_TEXT_LIMIT = 200000;
+/** How much of a report the worker record keeps for status lines and router injections. */
+export declare const REPORT_SUMMARY_LIMIT = 2000;
+/** `report_read` paging: default page size, hard cap, and the paging floor. */
+export declare const REPORT_DEFAULT_LIMIT = 4000;
+export declare const REPORT_MAX_LIMIT = 20000;
+export declare const REPORT_MIN_LIMIT = 1;
+export interface ReportRecord {
+    readonly sessionID: string;
+    /** Stored text: the original, or its first `REPORT_TEXT_LIMIT` characters when clipped. */
+    readonly text: string;
+    /** Length of the original text, before any clipping. */
+    readonly length: number;
+    readonly capturedAt: number;
+    readonly truncated: boolean;
+    /** Character offset where the stored text stops, present only when `truncated`. */
+    readonly clippedAt?: number;
+}
+export interface ReportSlice {
+    readonly text: string;
+    readonly offset: number;
+    readonly end: number;
+    /** Length of the original report. */
+    readonly total: number;
+    /** Length of the stored text, which is smaller than `total` for clipped reports. */
+    readonly stored: number;
+    readonly hasMore: boolean;
+    readonly nextOffset?: number;
+}
+export interface ReportStats {
+    readonly entries: number;
+    readonly chars: number;
+    readonly truncated: number;
+}
+export declare const reportKey: (sessionID: string) => string;
+/** Capture-time copy of the text, clipped to the hard cap and tagged with its metadata. */
+export declare function buildReport(sessionID: string, text: string, capturedAt?: number): ReportRecord;
+/** The compact form kept in `worker:<id>.lastReport`. */
+export declare function reportSummary(record: ReportRecord): string;
+/** One router-facing line that names the full-text handle. */
+export declare function reportNotice(record: ReportRecord): string;
+/** Page through a stored report; the caller validates offset against `stored`. */
+export declare function sliceReport(record: ReportRecord, offset: number, limit: number): ReportSlice;
+export declare function encodeReport(record: ReportRecord): Schema.Json;
+export declare function decodeReport(value: Schema.Json | undefined): ReportRecord | undefined;
+export declare const saveReport: (ctx: Plugin.Context, record: ReportRecord) => Effect.Effect<void, never, never>;
+export declare const loadReport: (ctx: Plugin.Context, sessionID: string) => Effect.Effect<ReportRecord | undefined, never, never>;
+export declare const reportStats: () => ReportStats;
+/** Fixed thresholds used to warn about unbounded spill growth at startup. */
+export declare const REPORT_ENTRY_WARN = 500;
+export declare const REPORT_CHARS_WARN = 20000000;
+/**
+ * Measure stored reports once at startup. Nothing is deleted here: dropping a
+ * report is a deliberate retention decision, not a side effect of hydration.
+ * Undecodable values are removed because they can never be read back.
+ */
+export declare const hydrateReports: (ctx: Plugin.Context) => Effect.Effect<void, never, never>;

package/dist/src/report.js

@@ -0,0 +1,147 @@
+import { Effect } from "effect";
+/**
+ * Full worker reports ("spill") kept beside the compact `worker:<id>` record.
+ *
+ * The worker record keeps only a summary (`lastReport`), because it is copied
+ * into every router status line and context. The complete text lives under
+ * `report:<sessionID>` so `report_read` can page through it after the fact.
+ * Reports are intentionally not removed when the worker record disappears: a
+ * supervisor may still need the evidence. Growth is only measured and logged
+ * (see `hydrateReports`); automatic trimming is a later, separate policy.
+ */
+export const REPORT_PREFIX = "report:";
+/** Hard cap for one stored report. Longer reports are clipped and marked, never silently lost. */
+export const REPORT_TEXT_LIMIT = 200_000;
+/** How much of a report the worker record keeps for status lines and router injections. */
+export const REPORT_SUMMARY_LIMIT = 2_000;
+/** `report_read` paging: default page size, hard cap, and the paging floor. */
+export const REPORT_DEFAULT_LIMIT = 4_000;
+export const REPORT_MAX_LIMIT = 20_000;
+export const REPORT_MIN_LIMIT = 1;
+export const reportKey = (sessionID) => `${REPORT_PREFIX}${sessionID}`;
+/** Capture-time copy of the text, clipped to the hard cap and tagged with its metadata. */
+export function buildReport(sessionID, text, capturedAt = Date.now()) {
+    if (text.length <= REPORT_TEXT_LIMIT) {
+        return { sessionID, text, length: text.length, capturedAt, truncated: false };
+    }
+    return {
+        sessionID,
+        text: text.slice(0, REPORT_TEXT_LIMIT),
+        length: text.length,
+        capturedAt,
+        truncated: true,
+        clippedAt: REPORT_TEXT_LIMIT,
+    };
+}
+/** The compact form kept in `worker:<id>.lastReport`. */
+export function reportSummary(record) {
+    if (record.text.length <= REPORT_SUMMARY_LIMIT)
+        return record.text;
+    return `${record.text.slice(0, REPORT_SUMMARY_LIMIT)}…`;
+}
+/** One router-facing line that names the full-text handle. */
+export function reportNotice(record) {
+    const clip = record.truncated ? `，超出 ${REPORT_TEXT_LIMIT} 字上限仅存前 ${record.text.length} 字` : "";
+    return `全文长度 ${record.length}${clip}，可用 report_read 读取（sessionID: ${record.sessionID}）`;
+}
+/** Page through a stored report; the caller validates offset against `stored`. */
+export function sliceReport(record, offset, limit) {
+    const stored = record.text.length;
+    const start = Math.min(Math.max(0, offset), stored);
+    const end = Math.min(stored, start + Math.max(REPORT_MIN_LIMIT, limit));
+    const hasMore = end < stored;
+    return {
+        text: record.text.slice(start, end),
+        offset: start,
+        end,
+        total: record.length,
+        stored,
+        hasMore,
+        ...(hasMore ? { nextOffset: end } : {}),
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function optionalNumber(record, key) {
+    const value = record[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+export function encodeReport(record) {
+    return {
+        sessionID: record.sessionID,
+        text: record.text,
+        length: record.length,
+        capturedAt: record.capturedAt,
+        truncated: record.truncated,
+        ...(record.clippedAt === undefined ? {} : { clippedAt: record.clippedAt }),
+    };
+}
+export function decodeReport(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (typeof value["sessionID"] !== "string")
+        return undefined;
+    if (typeof value["text"] !== "string")
+        return undefined;
+    const length = optionalNumber(value, "length");
+    const capturedAt = optionalNumber(value, "capturedAt");
+    if (length === undefined || capturedAt === undefined)
+        return undefined;
+    const clippedAt = optionalNumber(value, "clippedAt");
+    return {
+        sessionID: value["sessionID"],
+        text: value["text"],
+        length,
+        capturedAt,
+        truncated: value["truncated"] === true,
+        ...(clippedAt === undefined ? {} : { clippedAt }),
+    };
+}
+export const saveReport = Effect.fn("superagent.saveReport")(function* (ctx, record) {
+    yield* ctx.storage
+        .set(reportKey(record.sessionID), encodeReport(record))
+        .pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to persist report", { sessionID: record.sessionID, cause })));
+});
+export const loadReport = Effect.fn("superagent.loadReport")(function* (ctx, sessionID) {
+    const value = yield* ctx.storage.get(reportKey(sessionID)).pipe(Effect.catch(() => Effect.succeed(undefined)));
+    return decodeReport(value);
+});
+let stats = { entries: 0, chars: 0, truncated: 0 };
+export const reportStats = () => stats;
+/** Fixed thresholds used to warn about unbounded spill growth at startup. */
+export const REPORT_ENTRY_WARN = 500;
+export const REPORT_CHARS_WARN = 20_000_000;
+/**
+ * Measure stored reports once at startup. Nothing is deleted here: dropping a
+ * report is a deliberate retention decision, not a side effect of hydration.
+ * Undecodable values are removed because they can never be read back.
+ */
+export const hydrateReports = Effect.fn("superagent.hydrateReports")(function* (ctx) {
+    let entries = 0;
+    let chars = 0;
+    let truncated = 0;
+    let after;
+    do {
+        const page = yield* ctx.storage
+            .scan({ prefix: REPORT_PREFIX, after, limit: 100 })
+            .pipe(Effect.catch(() => Effect.succeed({ entries: [], next: undefined })));
+        for (const entry of page.entries) {
+            const record = decodeReport(entry.value);
+            if (record === undefined) {
+                yield* ctx.storage.remove(entry.key).pipe(Effect.catch(() => Effect.void));
+                continue;
+            }
+            entries += 1;
+            chars += record.length;
+            if (record.truncated)
+                truncated += 1;
+        }
+        after = page.next;
+    } while (after !== undefined);
+    stats = { entries, chars, truncated };
+    yield* Effect.logInfo("superagent report spill measured", stats);
+    if (entries > REPORT_ENTRY_WARN || chars > REPORT_CHARS_WARN) {
+        yield* Effect.logWarning("superagent report spill is growing; a retention policy (per-thread cap or age) is due", stats);
+    }
+});

package/dist/src/router.d.ts

@@ -0,0 +1,35 @@
+import { type Plugin } from "@opencode/plugin/effect";
+import { Effect } from "effect";
+import { type TriggerInput } from "./state.js";
+/** KV prefix for crash-safe pending triggers. Owned by the router; `state.ts` stays untouched. */
+export declare const PENDING_PREFIX = "pending:";
+/**
+ * Enqueue a trigger in memory and in KV. The trigger gets a stable id when
+ * the caller did not supply one, so a crash-restarted process can dedupe and
+ * rehydrate it. Same-id enqueues are ignored.
+ */
+export declare const enqueuePending: (ctx: Plugin.Context, input: TriggerInput) => Effect.Effect<void, never, never>;
+/**
+ * Reload unflushed triggers left in KV by a crashed process back into the
+ * memory queue. Never creates a router session: the queue waits until the
+ * next `router` RPC or trigger asks for a flush.
+ */
+export declare const hydratePending: (ctx: Plugin.Context) => Effect.Effect<void, never, never>;
+/**
+ * Return the live router session, creating it when missing. A router id
+ * whose session no longer exists is forgotten before creating a new one,
+ * so a user-deleted router is recovered automatically.
+ */
+export declare const ensureRouter: (ctx: Plugin.Context) => Effect.Effect<string, unknown, never>;
+/**
+ * Merge queued triggers into one synthetic prompt for the router. Items
+ * leave the queue (memory and KV) only after the injection succeeds; on
+ * failure they stay queued for the next attempt.
+ */
+export declare const flushPending: (ctx: Plugin.Context) => Effect.Effect<void, unknown, never>;
+/**
+ * Router idle hook: when the router goes idle with nothing pending in the
+ * background, flush queued triggers into the same execution. An empty queue
+ * returns without admitting input, so the hook never loops on its own.
+ */
+export declare const registerRouterIdle: (ctx: Plugin.Context) => Effect.Effect<void, never, import("effect/Scope").Scope>;