opencode-superagent 0.0.0-stage → 0.2.0

package/dist/src/report.d.ts

@@ -0,0 +1,78 @@
+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;
+/**
+ * Last non-empty assistant text in a session-context snapshot. Shared by the
+ * live watcher and startup hydration so a crash-recovered worker gets the
+ * same report extraction as one that ended while the plugin was running.
+ */
+export declare function lastAssistantText(messages: ReadonlyArray<unknown>): string | undefined;
+/** 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,176 @@
+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}）`;
+}
+/**
+ * Last non-empty assistant text in a session-context snapshot. Shared by the
+ * live watcher and startup hydration so a crash-recovered worker gets the
+ * same report extraction as one that ended while the plugin was running.
+ */
+export function lastAssistantText(messages) {
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (typeof message !== "object" || message === null)
+            continue;
+        const typed = message;
+        if (typed.type !== "assistant")
+            continue;
+        if (!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 !== "")
+            return text;
+    }
+    return undefined;
+}
+/** 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,34 @@
+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>;
+/**
+ * Serialised entry point for every flush caller (idle hook, RPC, tests).
+ * Concurrent calls wait on `flushLock`, so one batch is delivered once.
+ */
+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>;

package/dist/src/router.js

@@ -0,0 +1,234 @@
+import { Agent } from "@opencode/plugin/effect";
+import { Effect, Option, Semaphore } from "effect";
+import { ROUTER_AGENT } from "./agents.js";
+import { threadDirHint } from "./dirs.js";
+import { formatTrigger } from "./format.js";
+import { ROUTER_TITLE, superagentMetadata } from "./session-meta.js";
+import { ROUTER_KEY, store, toSessionID } from "./state.js";
+import { noteRouterTrigger } from "./ticket.js";
+import { ROUTER_PERMISSIONS } from "./tools.js";
+const MAX_FLUSH = 20;
+/**
+ * Serialise flushes. A second caller waits for the in-flight flush to finish,
+ * then observes the drained queue and only flushes events enqueued meanwhile,
+ * so the same batch is never injected twice. Effect releases the permit on
+ * success, failure and interruption.
+ */
+const flushLock = Semaphore.makeUnsafe(1);
+/** KV prefix for crash-safe pending triggers. Owned by the router; `state.ts` stays untouched. */
+export const PENDING_PREFIX = "pending:";
+const pendingKey = (id) => `${PENDING_PREFIX}${id}`;
+/** Stable queue identity: explicit id, else source/thread/creation time. */
+function pendingID(trigger, arrivedAt) {
+    return trigger.id ?? `${trigger.source}:${trigger.threadID}:${trigger.createdAt ?? arrivedAt}`;
+}
+function keyOf(item) {
+    return pendingKey(pendingID(item.trigger, item.arrivedAt));
+}
+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 decodePending(value) {
+    if (!isRecord(value))
+        return undefined;
+    const raw = value["trigger"];
+    if (!isRecord(raw))
+        return undefined;
+    if (typeof raw["source"] !== "string" || typeof raw["threadID"] !== "string")
+        return undefined;
+    if (typeof raw["text"] !== "string")
+        return undefined;
+    const arrivedAt = optionalNumber(value, "arrivedAt");
+    if (arrivedAt === undefined)
+        return undefined;
+    return {
+        trigger: {
+            id: optionalString(raw, "id"),
+            source: raw["source"],
+            threadID: raw["threadID"],
+            author: optionalString(raw, "author"),
+            text: raw["text"],
+            title: optionalString(raw, "title"),
+            createdAt: optionalNumber(raw, "createdAt"),
+        },
+        arrivedAt,
+    };
+}
+function encodePending(item) {
+    return {
+        trigger: {
+            ...(item.trigger.id === undefined ? {} : { id: item.trigger.id }),
+            source: item.trigger.source,
+            threadID: item.trigger.threadID,
+            ...(item.trigger.author === undefined ? {} : { author: item.trigger.author }),
+            text: item.trigger.text,
+            ...(item.trigger.title === undefined ? {} : { title: item.trigger.title }),
+            ...(item.trigger.createdAt === undefined ? {} : { createdAt: item.trigger.createdAt }),
+        },
+        arrivedAt: item.arrivedAt,
+    };
+}
+/**
+ * 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 const enqueuePending = Effect.fn("superagent.enqueuePending")(function* (ctx, input) {
+    const arrivedAt = Date.now();
+    const id = pendingID(input, arrivedAt);
+    if (store.pending.some((item) => pendingID(item.trigger, item.arrivedAt) === id))
+        return;
+    const item = {
+        trigger: input.id === undefined ? { ...input, id } : { ...input },
+        arrivedAt,
+    };
+    store.pending.push(item);
+    yield* ctx.storage
+        .set(keyOf(item), encodePending(item))
+        .pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to persist pending trigger", { cause })));
+});
+/**
+ * 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 const hydratePending = Effect.fn("superagent.hydratePending")(function* (ctx) {
+    let after;
+    do {
+        const page = yield* ctx.storage
+            .scan({ prefix: PENDING_PREFIX, after, limit: 100 })
+            .pipe(Effect.catch(() => Effect.succeed({ entries: [], next: undefined })));
+        for (const entry of page.entries) {
+            const item = decodePending(entry.value);
+            if (item === undefined) {
+                yield* ctx.storage.remove(entry.key).pipe(Effect.catch(() => Effect.void));
+                continue;
+            }
+            const id = pendingID(item.trigger, item.arrivedAt);
+            if (store.pending.some((existing) => pendingID(existing.trigger, existing.arrivedAt) === id))
+                continue;
+            store.pending.push(item.trigger.id === undefined ? { trigger: { ...item.trigger, id }, arrivedAt: item.arrivedAt } : item);
+        }
+        after = page.next;
+    } while (after !== undefined);
+});
+/**
+ * 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 const ensureRouter = Effect.fn("superagent.ensureRouter")(function* (ctx) {
+    const sessions = ctx.session;
+    const storage = ctx.storage;
+    if (store.routerID !== undefined) {
+        const cached = yield* sessions.get({ sessionID: toSessionID(store.routerID) }).pipe(Effect.option);
+        if (Option.isSome(cached))
+            return store.routerID;
+        store.routerID = undefined;
+        store.routerBusy = false;
+        yield* storage.remove(ROUTER_KEY).pipe(Effect.catch(() => Effect.void));
+    }
+    const stored = yield* storage.get(ROUTER_KEY).pipe(Effect.catch(() => Effect.succeed(undefined)));
+    if (typeof stored === "string") {
+        const info = yield* sessions.get({ sessionID: toSessionID(stored) }).pipe(Effect.option);
+        if (Option.isSome(info)) {
+            store.routerID = info.value.id;
+            return store.routerID;
+        }
+        yield* storage.remove(ROUTER_KEY).pipe(Effect.catch(() => Effect.void));
+    }
+    const agents = ctx.agent;
+    const routerAgent = yield* agents.get({ agentID: Agent.ID.make(ROUTER_AGENT) }).pipe(Effect.map((result) => result.data.id), Effect.catch((cause) => Effect.logWarning("superagent router agent missing, creating session without it", { cause }).pipe(Effect.as(undefined))));
+    const created = yield* sessions.create({
+        title: ROUTER_TITLE,
+        ...(routerAgent === undefined ? {} : { agent: routerAgent }),
+        metadata: superagentMetadata("router"),
+        // Derived from the tool catalog: a tool whose permission action is not
+        // allowed here is dropped from the Router's toolset by `Tool.snapshot`,
+        // so adding a tool without its action would hide it silently.
+        permissions: ROUTER_PERMISSIONS,
+    });
+    store.routerID = created.id;
+    store.routerBusy = false;
+    yield* storage
+        .set(ROUTER_KEY, created.id)
+        .pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to persist router", { cause })));
+    return created.id;
+});
+/**
+ * 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.
+ */
+const flushPendingUnlocked = Effect.fn("superagent.flushPendingUnlocked")(function* (ctx) {
+    if (store.pending.length === 0)
+        return;
+    const routerID = yield* ensureRouter(ctx);
+    const batch = store.pending.slice(0, MAX_FLUSH);
+    // Identity snapshot of this delivery. Removal below matches these ids
+    // instead of the queue prefix, so events enqueued while the injection is
+    // in flight survive.
+    const batchIDs = new Set(batch.map((item) => pendingID(item.trigger, item.arrivedAt)));
+    const text = [
+        `${batch.length} new event(s) for the router:`,
+        ...batch.map((item) => {
+            const base = formatTrigger(item.trigger);
+            const hint = threadDirHint(item.trigger.threadID);
+            return hint === undefined ? base : `${base}\n${hint}`;
+        }),
+    ].join("\n\n");
+    const delivered = yield* ctx.session
+        .synthetic({ sessionID: toSessionID(routerID), text, description: "superagent triggers", delivery: "queue" })
+        .pipe(Effect.option);
+    if (Option.isNone(delivered)) {
+        yield* Effect.logWarning("superagent failed to flush pending triggers, keeping them queued", {
+            count: batch.length,
+        });
+        return;
+    }
+    // Remove by delivered id, never by position: the queue may have grown at
+    // the tail (or been trimmed elsewhere) while `synthetic` was awaited.
+    for (let index = store.pending.length - 1; index >= 0; index -= 1) {
+        const item = store.pending[index];
+        if (item !== undefined && batchIDs.has(pendingID(item.trigger, item.arrivedAt))) {
+            store.pending.splice(index, 1);
+        }
+    }
+    // Remember what the Router was just told: `ticket_create` copies this
+    // trigger into the ticket's authorization (id + quote).
+    const newest = batch[batch.length - 1];
+    if (newest !== undefined)
+        noteRouterTrigger(newest.trigger);
+    for (const item of batch) {
+        yield* ctx.storage.remove(keyOf(item)).pipe(Effect.catch(() => Effect.void));
+    }
+});
+/**
+ * Serialised entry point for every flush caller (idle hook, RPC, tests).
+ * Concurrent calls wait on `flushLock`, so one batch is delivered once.
+ */
+export const flushPending = Effect.fn("superagent.flushPending")(function* (ctx) {
+    yield* flushLock.withPermit(flushPendingUnlocked(ctx));
+});
+/**
+ * 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 const registerRouterIdle = Effect.fn("superagent.registerRouterIdle")(function* (ctx) {
+    yield* ctx.session.hook("experimental.idle", (event) => Effect.gen(function* () {
+        if (store.routerID === undefined || event.sessionID !== store.routerID)
+            return;
+        if (event.background.length > 0)
+            return;
+        yield* flushPending(ctx);
+    }).pipe(Effect.catch((cause) => Effect.logWarning("superagent router idle flush failed", { cause }))));
+});

package/dist/src/session-meta.d.ts

@@ -0,0 +1,42 @@
+import type { Plugin } from "@opencode/plugin/effect";
+import { Effect, type Schema } from "effect";
+/**
+ * Session identity for the Super-agent prototype.
+ *
+ * A session's role lives in its durable `metadata.superagent` record, not in
+ * its title: the title is user-editable and auto-generated titles are not a
+ * contract. Every session this plugin creates writes the metadata at create
+ * time, and `hydrateSessionMeta` backfills sessions created before that.
+ */
+export type SuperagentRole = "router" | "worker";
+export declare const ROUTER_TITLE = "\uD83E\uDDED router-main";
+/** The role recorded in a session's metadata, when the metadata is a Super-agent one. */
+export declare function superagentRole(metadata: unknown): SuperagentRole | undefined;
+export declare function isSuperagentSession(session: {
+    readonly metadata?: unknown;
+}): boolean;
+export declare function isRouterSession(session: {
+    readonly metadata?: unknown;
+}): boolean;
+export declare function isWorkerSession(session: {
+    readonly metadata?: unknown;
+}): boolean;
+/** The `superagent` metadata entry written at create time. */
+export declare function superagentMetadata(role: SuperagentRole, threads?: ReadonlyArray<string>): Record<string, Schema.Json>;
+/**
+ * Worker session title. It is convenience only: the session stays
+ * identifiable from metadata when a user renames it.
+ */
+export declare function workerTitle(input: {
+    readonly task: string;
+    readonly title?: string;
+    readonly threadID?: string;
+}): string;
+/**
+ * Backfill `metadata.superagent` on sessions this plugin already owns (the
+ * router id plus every recorded worker) so role detection also covers
+ * sessions created before the metadata existed. Idempotent: a session whose
+ * role already matches is left untouched, and existing metadata is merged
+ * rather than replaced.
+ */
+export declare const hydrateSessionMeta: (ctx: Plugin.Context) => Effect.Effect<void, never, never>;

package/dist/src/session-meta.js

@@ -0,0 +1,91 @@
+import { Effect, Option } from "effect";
+import { store, toSessionID } from "./state.js";
+const WORKER_TITLE_PREFIX = "🔧 worker-";
+export const ROUTER_TITLE = "🧭 router-main";
+const TITLE_SLUG_MAX = 40;
+const THREAD_LABEL_MAX = 12;
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/** The role recorded in a session's metadata, when the metadata is a Super-agent one. */
+export function superagentRole(metadata) {
+    if (!isRecord(metadata))
+        return undefined;
+    const superagent = metadata["superagent"];
+    if (!isRecord(superagent))
+        return undefined;
+    const role = superagent["role"];
+    return role === "router" || role === "worker" ? role : undefined;
+}
+export function isSuperagentSession(session) {
+    return superagentRole(session.metadata) !== undefined;
+}
+export function isRouterSession(session) {
+    return superagentRole(session.metadata) === "router";
+}
+export function isWorkerSession(session) {
+    return superagentRole(session.metadata) === "worker";
+}
+/** The `superagent` metadata entry written at create time. */
+export function superagentMetadata(role, threads) {
+    return {
+        superagent: role === "worker" ? { role, threads: threads === undefined ? [] : [...threads] } : { role },
+    };
+}
+/**
+ * Short label for a thread id: the last `:`-separated segment, so
+ * `telegram:123456789` becomes `123456789` and long ids keep their tail.
+ */
+function threadLabel(threadID) {
+    const segment = (threadID.split(":").pop() ?? threadID).trim();
+    if (segment === "")
+        return "thread";
+    return segment.length > THREAD_LABEL_MAX ? segment.slice(-THREAD_LABEL_MAX) : segment;
+}
+function titleSlug(text) {
+    const clean = text.replace(/\s+/g, " ").trim();
+    if (clean === "")
+        return "task";
+    return clean.length > TITLE_SLUG_MAX ? `${clean.slice(0, TITLE_SLUG_MAX - 1).trimEnd()}…` : clean;
+}
+/**
+ * Worker session title. It is convenience only: the session stays
+ * identifiable from metadata when a user renames it.
+ */
+export function workerTitle(input) {
+    const subject = titleSlug(input.title ?? input.task.split("\n")[0] ?? "");
+    const label = input.threadID === undefined ? subject : `${threadLabel(input.threadID)}-${subject}`;
+    return `${WORKER_TITLE_PREFIX}${label}`;
+}
+/**
+ * Backfill `metadata.superagent` on sessions this plugin already owns (the
+ * router id plus every recorded worker) so role detection also covers
+ * sessions created before the metadata existed. Idempotent: a session whose
+ * role already matches is left untouched, and existing metadata is merged
+ * rather than replaced.
+ */
+export const hydrateSessionMeta = Effect.fn("superagent.hydrateSessionMeta")(function* (ctx) {
+    const targets = [];
+    if (store.routerID !== undefined)
+        targets.push({ sessionID: store.routerID, role: "router" });
+    for (const worker of store.workers.values())
+        targets.push({ sessionID: worker.sessionID, role: "worker" });
+    for (const target of targets) {
+        const current = yield* ctx.session.get({ sessionID: toSessionID(target.sessionID) }).pipe(Effect.option);
+        if (Option.isNone(current))
+            continue;
+        const metadata = current.value.metadata;
+        if (superagentRole(metadata) === target.role)
+            continue;
+        const threads = target.role === "worker" ? store.workers.get(target.sessionID)?.threads : undefined;
+        yield* ctx.session
+            .update({
+            sessionID: toSessionID(target.sessionID),
+            metadata: { ...(metadata ?? {}), ...superagentMetadata(target.role, threads) },
+        })
+            .pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to backfill session metadata", {
+            sessionID: target.sessionID,
+            cause,
+        })));
+    }
+});