opencode-superagent 0.0.0-stage → 0.1.0

package/dist/src/router.js

@@ -0,0 +1,209 @@
+import { Agent } from "@opencode/plugin/effect";
+import { Effect, Option } 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;
+/** 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.
+ */
+export const flushPending = Effect.fn("superagent.flushPending")(function* (ctx) {
+    if (store.pending.length === 0)
+        return;
+    const routerID = yield* ensureRouter(ctx);
+    const batch = store.pending.slice(0, MAX_FLUSH);
+    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;
+    }
+    store.pending.splice(0, batch.length);
+    // 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));
+    }
+});
+/**
+ * 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,
+        })));
+    }
+});

package/dist/src/state.d.ts

@@ -0,0 +1,124 @@
+import type { Plugin } from "@opencode/plugin/effect";
+import type { Session } from "@opencode/schema/session";
+import { Effect, type Schema } from "effect";
+export type WorkerState = "running" | "idle" | "failed" | "done" | "aborted";
+export interface WorkerRecord {
+    readonly sessionID: string;
+    readonly title?: string;
+    /**
+     * Primary thread this worker was dispatched for. Legacy records decode to
+     * `""` and `hydrate` backfills it from `thread.workers`, so every live record
+     * carries a forward link to its thread without losing the multi-thread
+     * `threads` list.
+     */
+    threadID: string;
+    /** Trigger that authorized the dispatch, when the record knows it. */
+    triggerID?: string;
+    readonly threads: Array<string>;
+    state: WorkerState;
+    readonly createdAt: number;
+    /** Last persisted write. Refreshed by `saveWorker`, so an aborted record keeps a traceable timestamp. */
+    updatedAt?: number;
+    lastReport?: string;
+    directory?: string;
+}
+export interface ThreadRecord {
+    readonly threadID: string;
+    readonly workers: Array<string>;
+    readonly updatedAt: number;
+}
+export interface TriggerInput {
+    readonly id?: string;
+    readonly source: string;
+    readonly threadID: string;
+    readonly author?: string;
+    readonly text: string;
+    readonly title?: string;
+    readonly createdAt?: number;
+}
+export interface PendingTrigger {
+    readonly trigger: TriggerInput;
+    readonly arrivedAt: number;
+}
+export type TriggerRoute = "router" | "worker";
+export interface TriggerRecord {
+    readonly id: string;
+    readonly source: string;
+    readonly threadID: string;
+    readonly author?: string;
+    readonly text: string;
+    readonly title?: string;
+    readonly createdAt: number;
+    route?: TriggerRoute;
+    sessionID?: string;
+    /** Workers dispatched from this trigger (reverse of `WorkerRecord.triggerID`). */
+    workerIDs?: Array<string>;
+}
+export interface DirectTriggerInput {
+    readonly id: string;
+    readonly source: string;
+    readonly threadID: string;
+    readonly author?: string;
+    readonly text: string;
+    readonly createdAt: number;
+}
+export declare function triggerIdFor(input: TriggerInput): string;
+/**
+ * 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 declare class PendingQueue extends Array<PendingTrigger> {
+    push(...items: Array<PendingTrigger>): number;
+    splice(start: number, deleteCount?: number, ...items: Array<PendingTrigger>): Array<PendingTrigger>;
+}
+/**
+ * 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 declare function upsertDirectTrigger(input: DirectTriggerInput, sessionID: string): TriggerRecord;
+export interface Store {
+    routerID: string | undefined;
+    routerBusy: boolean;
+    readonly workers: Map<string, WorkerRecord>;
+    readonly threads: Map<string, Array<string>>;
+    readonly pending: Array<PendingTrigger>;
+    readonly triggers: Map<string, TriggerRecord>;
+    triggerTotal: number;
+}
+export declare const store: Store;
+export declare const ROUTER_KEY = "router";
+export declare const WORKER_PREFIX = "worker:";
+export declare const THREAD_PREFIX = "thread:";
+export declare const TRIGGER_PREFIX = "trigger:";
+export declare const workerKey: (sessionID: string) => string;
+export declare const threadKey: (threadID: string) => string;
+export declare const triggerKey: (id: string) => string;
+/** Brands are compile-time only, so a validated session id string converts freely. */
+export declare const toSessionID: (id: string) => Session.ID;
+export declare function decodeWorker(value: Schema.Json | undefined): WorkerRecord | undefined;
+export declare function decodeThread(value: Schema.Json | undefined): ThreadRecord | undefined;
+export declare function decodeTrigger(value: Schema.Json | undefined): TriggerRecord | undefined;
+export declare function encodeWorker(record: WorkerRecord): Schema.Json;
+export declare function encodeThread(record: ThreadRecord): Schema.Json;
+export declare function encodeTrigger(record: TriggerRecord): Schema.Json;
+/**
+ * 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 declare const hydrate: (ctx: Plugin.Context) => Effect.Effect<void, never, never>;
+/** Every worker write refreshes `updatedAt`, so an aborted record keeps a traceable timestamp. */
+export declare const saveWorker: (ctx: Plugin.Context, record: WorkerRecord) => Effect.Effect<void, never, never>;
+export declare const saveTrigger: (ctx: Plugin.Context, record: TriggerRecord) => Effect.Effect<void, never, never>;
+/**
+ * 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 declare const linkTriggerToWorker: (ctx: Plugin.Context, triggerID: string, sessionID: string) => Effect.Effect<boolean, never, never>;
+export declare const saveThread: (ctx: Plugin.Context, record: ThreadRecord) => Effect.Effect<void, never, never>;