opencode-superagent 0.0.0-stage → 0.2.0

package/dist/server.js

@@ -0,0 +1,148 @@
+import { Plugin, Rpc } from "@opencode/plugin/effect";
+import { Effect, Schema } from "effect";
+import { registerAbort, runAbort } from "./src/abort.js";
+import { registerAgents } from "./src/agents.js";
+import { registerContext } from "./src/context.js";
+import { hydrateDirs } from "./src/dirs.js";
+import { registerTools } from "./src/dispatch.js";
+import { formatTrigger } from "./src/format.js";
+import { Definition } from "./src/protocol.js";
+import { hydrateReports } from "./src/report.js";
+import { ensureRouter, enqueuePending, flushPending, hydratePending, registerRouterIdle } from "./src/router.js";
+import { hydrateSessionMeta } from "./src/session-meta.js";
+import { registerSleep } from "./src/sleep.js";
+import { hydrate, store, toSessionID } from "./src/state.js";
+import { hydrateTickets, TICKET_STATES } from "./src/ticket.js";
+import { registerTicketTools, renderTicketText, renderTicketsText } from "./src/ticket-tools.js";
+import { registerWatcher } from "./src/watcher.js";
+import { registerWatchdog } from "./src/watchdog.js";
+const runTrigger = Effect.fn("superagent.runTrigger")(function* (ctx, input) {
+    const sources = ctx.options.sources;
+    if (Array.isArray(sources) && !sources.includes(input.source))
+        return { route: "dropped" };
+    if (input.text.trim() === "")
+        return { route: "dropped" };
+    const formatted = formatTrigger(input);
+    // Sticky thread affinity: follow-ups on a known thread go straight back to
+    // its worker instead of spawning a fresh session per message. Running
+    // workers get everything; otherwise the most recent idle/done worker is
+    // resumed (prompting a finished session starts a new execution in it, and
+    // the watcher flips it back to running). Failed workers are skipped so the
+    // next message gets a fresh dispatch through the Router. A genuinely new
+    // thread (no affinity record) starts with the Router.
+    const subscribed = store.threads.get(input.threadID) ?? [];
+    const running = subscribed.filter((sessionID) => store.workers.get(sessionID)?.state === "running");
+    const resumed = [...subscribed].reverse().find((sessionID) => {
+        const state = store.workers.get(sessionID)?.state;
+        return state === "idle" || state === "done";
+    });
+    const targets = running.length > 0 ? running : resumed === undefined ? [] : [resumed];
+    if (targets.length > 0) {
+        const sessions = ctx.session;
+        let delivered = 0;
+        for (const target of targets) {
+            const ok = yield* sessions.prompt({ sessionID: toSessionID(target), text: formatted, delivery: "queue" }).pipe(Effect.as(true), Effect.catch((cause) => Effect.logWarning("superagent direct-to-worker prompt failed", { worker: target, cause }).pipe(Effect.as(false))));
+            if (ok)
+                delivered += 1;
+        }
+        if (delivered > 0)
+            return { route: "worker", sessionID: targets[0] };
+    }
+    yield* enqueuePending(ctx, input);
+    const routerID = yield* ensureRouter(ctx);
+    if (!store.routerBusy)
+        yield* flushPending(ctx);
+    return { route: "router", sessionID: routerID };
+});
+/**
+ * The RPC surface this server registers. `stop` gains its rejection error here
+ * rather than in the shared TUI contract: only the server refuses router-only
+ * calls, and the TUI never calls `stop`.
+ */
+export const ServerDefinition = {
+    ...Definition,
+    methods: {
+        ...Definition.methods,
+        stop: {
+            ...Definition.methods.stop,
+            errors: { "stop.rejected": Schema.toStandardSchemaV1(Schema.Struct({})) },
+        },
+    },
+};
+/**
+ * Router-only RPC methods are rejected unconditionally.
+ *
+ * The RPC transport does not expose a caller identity: `RpcCallContext` only
+ * carries `error`. The old handler therefore passed `store.routerID` as
+ * `runDispatch`'s caller, which let every RPC client act as the router. Input
+ * fields such as `caller` / `routerID` are just as forgeable (and the router
+ * id is public in `status`), so they are never used as proof of identity.
+ * Until the host exposes the calling session on the RPC context, the safe
+ * behavior is to keep router-only effects off the RPC surface. The real
+ * router still works through its tools, whose `context.sessionID` is
+ * authoritative and is checked by `runDispatch` / `runAbort`.
+ */
+export const rejectedRouterRpc = {
+    dispatch: (_input, context) => Effect.fail(context.error("dispatch.rejected", "dispatch is only available to the router session; RPC callers cannot prove that identity — use the router's dispatch tool", {})),
+    stop: (_input, context) => Effect.fail(context.error("stop.rejected", "stop is only available to the router session; RPC callers cannot prove that identity — use abort_session from the router", {})),
+};
+export default Plugin.define({
+    id: "opencode.superagent",
+    effect: Effect.fn(function* (ctx) {
+        // Tickets first: hydrating workers reconciles finished `running` records
+        // and closes their tickets, so the ticket store must already be loaded.
+        yield* hydrateTickets(ctx);
+        yield* hydrate(ctx);
+        // Before any session work: the Router and Worker sessions resolve their agent by id.
+        yield* registerAgents(ctx);
+        yield* hydratePending(ctx);
+        yield* hydrateDirs(ctx);
+        yield* hydrateSessionMeta(ctx);
+        yield* hydrateReports(ctx);
+        yield* registerTools(ctx);
+        yield* registerSleep(ctx);
+        yield* registerTicketTools(ctx);
+        yield* registerAbort(ctx);
+        yield* registerContext(ctx);
+        yield* registerRouterIdle(ctx);
+        yield* registerWatcher(ctx);
+        yield* registerWatchdog(ctx);
+        yield* ctx.rpc
+            .register(ServerDefinition, {
+            router: () => ensureRouter(ctx).pipe(Effect.map((sessionID) => ({ sessionID })), Effect.catch((cause) => Effect.logWarning("superagent router handler failed", { cause }).pipe(Effect.andThen(Effect.die(new Error("superagent router is unavailable")))))),
+            status: () => Effect.sync(() => ({
+                // Omit the key entirely when no router exists: an explicit
+                // `undefined` value fails output validation.
+                ...(store.routerID === undefined ? {} : { router: store.routerID }),
+                pending: store.pending.length,
+                workers: [...store.workers.values()].map((worker) => ({
+                    sessionID: worker.sessionID,
+                    ...(worker.title === undefined ? {} : { title: worker.title }),
+                    threads: [...worker.threads],
+                    state: worker.state,
+                })),
+            })),
+            tickets: (input, context) => {
+                // The protocol literal already rejects unknown states with
+                // `rpc.invalid_input`; keep an explicit RPC error as a second line of
+                // defence so a bypassed/older client can never turn an unknown status
+                // into an unfiltered list.
+                if (input.status !== undefined && !TICKET_STATES.includes(input.status)) {
+                    return Effect.fail(context.error("tickets.invalid_status", `invalid ticket status: ${String(input.status)}`, {
+                        status: String(input.status),
+                    }));
+                }
+                return Effect.sync(() => renderTicketsText({
+                    ...(input.threadID === undefined ? {} : { threadID: input.threadID }),
+                    ...(input.status === undefined ? {} : { status: input.status }),
+                    ...(input.limit === undefined ? {} : { limit: input.limit }),
+                })).pipe(Effect.map((text) => ({ text })));
+            },
+            ticket: (input) => Effect.sync(() => ({ text: renderTicketText(input.ticketID) })),
+            ...rejectedRouterRpc,
+            trigger: (input) => runTrigger(ctx, input).pipe(Effect.catch((cause) => Effect.logWarning("superagent trigger handler failed", { cause }).pipe(Effect.as({ route: "dropped" })))),
+            abort: (input, context) => runAbort(ctx, input).pipe(Effect.map((result) => ({ text: result.output.text })), Effect.catchTag("Tool.Error", (error) => Effect.fail(context.error("abort.rejected", error.message, {})))),
+        })
+            .pipe(Effect.orDie);
+    }),
+});

package/dist/src/abort.d.ts

@@ -0,0 +1,31 @@
+import type { Plugin } from "@opencode/plugin/effect";
+import { Tool } from "@opencode/schema/tool";
+import { Effect, Schema } from "effect";
+/** How long a terminating call waits for an interrupted worker to settle before reporting a timeout. */
+export declare const ABORT_TIMEOUT_MS = 10000;
+export declare const AbortInput: Schema.Struct<{
+    readonly sessionID: Schema.optionalKey<Schema.String>;
+    readonly reason: Schema.optionalKey<Schema.String>;
+    readonly all: Schema.optionalKey<Schema.Boolean>;
+    readonly stale: Schema.optionalKey<Schema.Boolean>;
+}>;
+interface AbortInput {
+    readonly sessionID?: string;
+    readonly reason?: string;
+    readonly all?: boolean;
+    readonly stale?: boolean;
+}
+/**
+ * Terminate tracked workers. `caller` is set by the router tool (which then
+ * enforces router-only access); the TUI RPC passes nothing because the user
+ * drives it directly. Only sessions the plugin created can be touched: the
+ * router, user sessions and unknown ids are always refused.
+ */
+export declare const runAbort: (ctx: Plugin.Context, input: AbortInput, caller?: string | undefined) => Effect.Effect<{
+    output: {
+        text: string;
+    };
+    content: string;
+}, Tool.Error, never>;
+export declare const registerAbort: (ctx: Plugin.Context) => Effect.Effect<void, never, import("effect/Scope").Scope>;
+export {};

package/dist/src/abort.js

@@ -0,0 +1,171 @@
+import { Tool } from "@opencode/schema/tool";
+import { Effect, Option, Schema } from "effect";
+import { requireRouter } from "./guard.js";
+import { encodeThread, isRunning, saveWorker, store, threadKey, toSessionID } from "./state.js";
+import { closeTicketsForWorker } from "./ticket.js";
+import { specFor, toolPermission } from "./tools.js";
+/** How long a terminating call waits for an interrupted worker to settle before reporting a timeout. */
+export const ABORT_TIMEOUT_MS = 10_000;
+export const AbortInput = Schema.Struct({
+    sessionID: Schema.optionalKey(Schema.String),
+    reason: Schema.optionalKey(Schema.String),
+    all: Schema.optionalKey(Schema.Boolean),
+    stale: Schema.optionalKey(Schema.Boolean),
+});
+const AbortOutput = Schema.Struct({ text: Schema.String });
+function abortNote(reason, detail, previous) {
+    const head = `aborted${reason === undefined ? "" : ` (${reason})`} [${detail}]`;
+    return previous === undefined ? head : `${head} | ${previous}`;
+}
+/**
+ * Drop the session from every thread affinity list it subscribed to, so later
+ * messages on those threads no longer target a terminated worker. An empty
+ * thread falls back to the router on the next message. The worker record keeps
+ * its `threads` for tracing.
+ */
+const detachThreads = Effect.fn("superagent.detachThreads")(function* (ctx, sessionID) {
+    const worker = store.workers.get(sessionID);
+    if (worker === undefined)
+        return [];
+    const detached = [];
+    for (const threadID of worker.threads) {
+        const current = store.threads.get(threadID);
+        if (current === undefined || !current.includes(sessionID))
+            continue;
+        const next = current.filter((id) => id !== sessionID);
+        if (next.length === 0) {
+            store.threads.delete(threadID);
+            yield* ctx.storage.remove(threadKey(threadID)).pipe(Effect.catch(() => Effect.void));
+        }
+        else {
+            store.threads.set(threadID, next);
+            yield* ctx.storage
+                .set(threadKey(threadID), encodeThread({ threadID, workers: next, updatedAt: Date.now() }))
+                .pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to persist thread", { cause })));
+        }
+        detached.push(threadID);
+    }
+    return detached;
+});
+/**
+ * Terminate one tracked worker. The record is marked `aborted` before the
+ * interrupt lands, so the watcher cannot resurrect it to `idle`/`done` when
+ * the interruption settles; the record itself stays in KV for tracing.
+ */
+const abortWorker = Effect.fn("superagent.abortWorker")(function* (ctx, sessionID, reason) {
+    const worker = store.workers.get(sessionID);
+    if (worker === undefined)
+        return undefined;
+    const previous = worker.lastReport;
+    const info = yield* ctx.session.get({ sessionID: toSessionID(sessionID) }).pipe(Effect.option);
+    const running = Option.isSome(info) && isRunning(info.value);
+    worker.state = "aborted";
+    yield* saveWorker(ctx, worker);
+    // Terminating a worker aborts its ticket: the work did not finish, and a
+    // failed ticket is what the Router needs to decide on a re-dispatch.
+    yield* closeTicketsForWorker(ctx, {
+        sessionID,
+        outcome: "failed",
+        summary: `aborted${reason === undefined ? "" : `: ${reason}`}`,
+        note: "aborted",
+    }).pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to abort ticket for worker", { sessionID, cause })));
+    const threads = yield* detachThreads(ctx, sessionID);
+    if (Option.isNone(info)) {
+        worker.lastReport = abortNote(reason, "session missing", previous);
+        yield* saveWorker(ctx, worker);
+        return { sessionID, status: "missing", interrupted: false, timedOut: false, threads };
+    }
+    // Interrupt unconditionally: when the session is not executing this is a
+    // harmless no-op, but it still clears a prompt queued behind the previous
+    // execution so it cannot start after abort returned.
+    const interrupted = yield* ctx.session.interrupt({ sessionID: toSessionID(sessionID) }).pipe(Effect.map((result) => result.interrupted), Effect.catch((cause) => Effect.logWarning("superagent abort interrupt failed", { sessionID, cause }).pipe(Effect.as(false))));
+    if (!running) {
+        worker.lastReport = abortNote(reason, interrupted ? "interrupted queued prompt" : "already ended", previous);
+        yield* saveWorker(ctx, worker);
+        return { sessionID, status: "already-ended", interrupted, timedOut: false, threads };
+    }
+    const settled = yield* ctx.session.wait({ sessionID: toSessionID(sessionID) }).pipe(Effect.timeoutOption(ABORT_TIMEOUT_MS), Effect.catch((cause) => Effect.logWarning("superagent abort wait failed", { sessionID, cause }).pipe(Effect.as(Option.some(undefined)))));
+    const timedOut = Option.isNone(settled);
+    const detail = timedOut ? "interrupted, settle timeout" : interrupted ? "interrupted" : "no active execution";
+    worker.lastReport = abortNote(reason, detail, previous);
+    yield* saveWorker(ctx, worker);
+    return { sessionID, status: "aborted", interrupted, timedOut, threads };
+});
+function render(results) {
+    if (results.length === 0) {
+        const text = "no tracked worker matched; nothing to abort";
+        return { output: { text }, content: text };
+    }
+    const counts = { aborted: 0, "already-ended": 0, missing: 0 };
+    const lines = [];
+    for (const result of results) {
+        counts[result.status] += 1;
+        const title = store.workers.get(result.sessionID)?.title ?? "-";
+        const detail = result.status === "aborted"
+            ? `interrupted=${result.interrupted}${result.timedOut ? " settle-timeout" : ""}`
+            : result.status;
+        const threads = result.threads.length === 0 ? "" : ` detached=${result.threads.join(",")}`;
+        lines.push(`- ${result.sessionID} ${title}: ${detail}${threads}`);
+    }
+    const summary = `aborted ${counts.aborted}, already ended ${counts["already-ended"]}, session missing ${counts.missing} (${results.length} worker(s))`;
+    const text = [summary, ...lines].join("\n");
+    return { output: { text }, content: text };
+}
+/**
+ * Terminate tracked workers. `caller` is set by the router tool (which then
+ * enforces router-only access); the TUI RPC passes nothing because the user
+ * drives it directly. Only sessions the plugin created can be touched: the
+ * router, user sessions and unknown ids are always refused.
+ */
+export const runAbort = Effect.fn("superagent.abort")(function* (ctx, input, caller) {
+    if (caller !== undefined)
+        yield* requireRouter(caller, "abort_session");
+    const batch = input.all === true || input.stale === true;
+    if (batch && input.sessionID !== undefined) {
+        return yield* new Tool.Error({ message: "pass either sessionID or all/stale, not both" });
+    }
+    if (!batch && input.sessionID === undefined) {
+        return yield* new Tool.Error({
+            message: "abort_session needs a sessionID, or all: true / stale: true for batch cleanup",
+        });
+    }
+    if (input.sessionID !== undefined) {
+        if (input.sessionID === caller) {
+            return yield* new Tool.Error({ message: "cannot abort the calling session" });
+        }
+        if (store.routerID !== undefined && input.sessionID === store.routerID) {
+            return yield* new Tool.Error({ message: "cannot abort the router session" });
+        }
+        if (!store.workers.has(input.sessionID)) {
+            return yield* new Tool.Error({
+                message: `${input.sessionID} is not tracked by the superagent router; refusing to abort a session the plugin does not own`,
+            });
+        }
+        const result = yield* abortWorker(ctx, input.sessionID, input.reason);
+        return render(result === undefined ? [] : [result]);
+    }
+    // Batch mode never includes the router: it is not a worker record. `stale`
+    // only cleans records with no live work; `all` also interrupts running ones.
+    const targets = [...store.workers.values()]
+        .filter((worker) => input.all === true || worker.state !== "running")
+        .map((worker) => worker.sessionID);
+    const results = [];
+    for (const sessionID of targets) {
+        const result = yield* abortWorker(ctx, sessionID, input.reason);
+        if (result !== undefined)
+            results.push(result);
+    }
+    return render(results);
+});
+export const registerAbort = Effect.fn("superagent.registerAbort")(function* (ctx) {
+    yield* ctx.tool.transform((editor) => {
+        editor.add({
+            name: "abort_session",
+            description: specFor("abort_session").description,
+            input: AbortInput,
+            output: AbortOutput,
+            options: { permission: toolPermission(specFor("abort_session")) },
+            execute: (input, context) => runAbort(ctx, input, context.sessionID),
+        });
+    });
+});

package/dist/src/agents.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Programmatic agent definitions for the Router and the Worker.
+ *
+ * Shipping the definitions as code is what makes the plugin installable as a
+ * standalone package: a fresh install no longer needs the user to copy
+ * `.opencode/agent/superagent-*.md` by hand. `agent/*.md` stays in the package
+ * as templates for customization and as the documented fallback for hosts
+ * whose kernel cannot create agents from a plugin transform.
+ *
+ * Precedence is "user files first". External plugins register before the
+ * built-in config agent plugin, so this transform replays *before*
+ * `.opencode/agent/*.md` documents are applied; a file therefore updates the
+ * same entry afterwards and keeps its own description, system, mode and
+ * hidden. The `get` guard below covers hosts that replay config first (and
+ * keeps repeated replays from re-applying the default).
+ */
+import type { Plugin } from "@opencode/plugin/effect";
+import type { AgentEditor } from "@opencode/plugin/effect/agent";
+import { Effect } from "effect";
+export declare const ROUTER_AGENT = "superagent-router";
+export declare const WORKER_AGENT = "superagent-worker";
+export interface AgentDefinition {
+    readonly id: string;
+    readonly description: string;
+    readonly mode: "primary" | "subagent";
+    readonly hidden: boolean;
+    readonly system: string;
+}
+export declare const AGENT_DEFINITIONS: readonly [{
+    readonly id: "superagent-router";
+    readonly description: "Superagent router. Talks to the human, never executes work itself.";
+    readonly mode: "primary";
+    readonly hidden: true;
+    readonly system: "你是 Super Agent Router 的会话身份；行为规则由运行时注入的 Router 提示提供。";
+}, {
+    readonly id: "superagent-worker";
+    readonly description: "Superagent worker. Executes one task in its own session.";
+    readonly mode: "subagent";
+    readonly hidden: false;
+    readonly system: "你是一个独立的 Worker，在自己的会话中完成被分派的单一任务。\n\n- 专注任务本身，不主动联系用户。\n- 结束时用简短结论说明改了什么、验证了什么、还有什么风险；这段文字会作为 report 交给 Router。\n- 不要创建子任务给其他 worker。";
+}];
+/**
+ * Registers the defaults on an agent editor, mutating it in place.
+ *
+ * Returns the ids the kernel refused to create. `Agent.Info.default` materializes
+ * an unknown id, which is what newer kernels do inside `editor.update`; older
+ * kernels silently ignore an unknown id, and there the returned ids are the
+ * signal to fall back to the markdown templates.
+ */
+export declare function applyAgentDefinitions(editor: AgentEditor): string[];
+export declare const registerAgents: (ctx: Pick<Plugin.Context, "agent">) => Effect.Effect<void, never, import("effect/Scope").Scope>;

package/dist/src/agents.js

@@ -0,0 +1,83 @@
+/**
+ * Programmatic agent definitions for the Router and the Worker.
+ *
+ * Shipping the definitions as code is what makes the plugin installable as a
+ * standalone package: a fresh install no longer needs the user to copy
+ * `.opencode/agent/superagent-*.md` by hand. `agent/*.md` stays in the package
+ * as templates for customization and as the documented fallback for hosts
+ * whose kernel cannot create agents from a plugin transform.
+ *
+ * Precedence is "user files first". External plugins register before the
+ * built-in config agent plugin, so this transform replays *before*
+ * `.opencode/agent/*.md` documents are applied; a file therefore updates the
+ * same entry afterwards and keeps its own description, system, mode and
+ * hidden. The `get` guard below covers hosts that replay config first (and
+ * keeps repeated replays from re-applying the default).
+ */
+import { Effect } from "effect";
+export const ROUTER_AGENT = "superagent-router";
+export const WORKER_AGENT = "superagent-worker";
+const ROUTER_SYSTEM = "你是 Super Agent Router 的会话身份；行为规则由运行时注入的 Router 提示提供。";
+const WORKER_SYSTEM = `你是一个独立的 Worker，在自己的会话中完成被分派的单一任务。
+
+- 专注任务本身，不主动联系用户。
+- 结束时用简短结论说明改了什么、验证了什么、还有什么风险；这段文字会作为 report 交给 Router。
+- 不要创建子任务给其他 worker。`;
+export const AGENT_DEFINITIONS = [
+    {
+        id: ROUTER_AGENT,
+        description: "Superagent router. Talks to the human, never executes work itself.",
+        mode: "primary",
+        hidden: true,
+        system: ROUTER_SYSTEM,
+    },
+    {
+        id: WORKER_AGENT,
+        description: "Superagent worker. Executes one task in its own session.",
+        mode: "subagent",
+        hidden: false,
+        system: WORKER_SYSTEM,
+    },
+];
+/**
+ * Registers the defaults on an agent editor, mutating it in place.
+ *
+ * Returns the ids the kernel refused to create. `Agent.Info.default` materializes
+ * an unknown id, which is what newer kernels do inside `editor.update`; older
+ * kernels silently ignore an unknown id, and there the returned ids are the
+ * signal to fall back to the markdown templates.
+ */
+export function applyAgentDefinitions(editor) {
+    return AGENT_DEFINITIONS.filter((definition) => !applyDefinition(editor, definition)).map((definition) => definition.id);
+}
+function applyDefinition(editor, definition) {
+    try {
+        if (editor.get(definition.id) !== undefined)
+            return true;
+        editor.update(definition.id, (agent) => {
+            agent.description = definition.description;
+            agent.mode = definition.mode;
+            agent.hidden = definition.hidden;
+            agent.system = definition.system;
+        });
+        return editor.get(definition.id) !== undefined;
+    }
+    catch {
+        // A transform that throws breaks every agent read for the whole process, so a
+        // kernel that rejects the edit degrades to "not registered" instead.
+        return false;
+    }
+}
+export const registerAgents = Effect.fn("superagent.registerAgents")(function* (ctx) {
+    const unregistered = new Set();
+    yield* ctx.agent.transform((editor) => {
+        for (const id of applyAgentDefinitions(editor))
+            unregistered.add(id);
+    });
+    // Force one replay so an unsupported kernel is detected during setup rather than
+    // on the first agent read.
+    yield* ctx.agent.list().pipe(Effect.ignore);
+    if (unregistered.size === 0)
+        return;
+    yield* Effect.logWarning("superagent could not register its agents on this kernel; copy agent/*.md into .opencode/agent instead", { agents: [...unregistered] });
+});

package/dist/src/context.d.ts

@@ -0,0 +1,27 @@
+import type { Plugin } from "@opencode/plugin/effect";
+import { Effect } from "effect";
+/**
+ * Chain-recall block for the current thread: active tickets plus the newest
+ * workers, each as id + state + one-line summary + report handle. Only IDs and
+ * summaries are injected; `worker_detail`, `report_read`, `thread_detail` and
+ * `ticket_list` fetch the bodies on demand. The whole block is capped so a
+ * long summary cannot crowd out the router prompt.
+ */
+export declare function buildRecallInjection(threadID: string | undefined): string;
+/**
+ * Narrow one request's toolset by session role. The Router keeps only the
+ * catalog tools; a tracked Worker loses every router-only tool (dispatch,
+ * sleep, tickets, recall, abort_session), so those tools are not listed to
+ * the worker model at all. User sessions are left untouched.
+ */
+export declare function filterSessionTools(sessionID: string, tools: Record<string, unknown>): void;
+/**
+ * Context hook: strip each session's toolset to what that role may see
+ * (Router: catalog only; Worker: catalog tools removed), then append the
+ * router prompt plus a short live status line for the Router.
+ *
+ * The status line carries the ticket counters and the current thread's
+ * in-progress ticket ids/titles, so a follow-up can be linked back to an
+ * existing ticket without a tool call.
+ */
+export declare const registerContext: (ctx: Plugin.Context) => Effect.Effect<void, never, import("effect/Scope").Scope>;

package/dist/src/context.js

@@ -0,0 +1,114 @@
+import { Effect } from "effect";
+import { directorySummary } from "./dirs.js";
+import { ROUTER_PROMPT } from "./prompts.js";
+import { registerRecall } from "./recall.js";
+import { store } from "./state.js";
+import { activeTicketSummary, currentTrigger, ticketStats } from "./ticket.js";
+import { displayWidth, ROUTER_TOOLS } from "./tools.js";
+/** How many recent workers the recall block names; their full text stays behind tools. */
+const RECALL_WORKER_LIMIT = 3;
+/** A recall line must stay readable in a narrow terminal. */
+const RECALL_LINE_MAX = 100;
+/** Whole recall block budget: ids and one-line summaries only, never report text. */
+const RECALL_BUDGET = 800;
+function flatten(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function clip(text, max) {
+    if (max <= 0)
+        return "";
+    return text.length <= max ? text : `${text.slice(0, Math.max(1, max - 1))}…`;
+}
+/** One worker line inside 100 cells; the session id stays whole so it can be copied. */
+function workerLine(worker) {
+    const head = `- ${worker.sessionID} ${worker.state}`;
+    const tail = " | report_read";
+    const room = RECALL_LINE_MAX - displayWidth(head) - displayWidth(tail) - 3;
+    const summary = flatten(worker.lastReport ?? worker.title ?? "");
+    return `${head} | ${clip(summary, Math.max(8, room))}${tail}`;
+}
+/**
+ * Chain-recall block for the current thread: active tickets plus the newest
+ * workers, each as id + state + one-line summary + report handle. Only IDs and
+ * summaries are injected; `worker_detail`, `report_read`, `thread_detail` and
+ * `ticket_list` fetch the bodies on demand. The whole block is capped so a
+ * long summary cannot crowd out the router prompt.
+ */
+export function buildRecallInjection(threadID) {
+    if (threadID === undefined)
+        return "";
+    const active = activeTicketSummary(threadID, 3);
+    const lines = ["## 链式召回（只给 ID 与摘要，正文按需取）"];
+    if (active === "") {
+        lines.push("进行中工单（当前 thread）：无");
+    }
+    else {
+        lines.push("进行中工单（当前 thread）：");
+        for (const entry of active.split("; "))
+            lines.push(clip(`- ${entry}`, RECALL_LINE_MAX));
+    }
+    const workers = [...store.workers.values()]
+        .filter((worker) => worker.threadID === threadID || worker.threads.includes(threadID))
+        .sort((left, right) => right.createdAt - left.createdAt)
+        .slice(0, RECALL_WORKER_LIMIT);
+    lines.push(`最近 Worker（当前 thread，最多 ${RECALL_WORKER_LIMIT}）：`);
+    if (workers.length === 0)
+        lines.push("无");
+    for (const worker of workers)
+        lines.push(workerLine(worker));
+    lines.push("取正文：worker_detail / report_read / thread_detail / ticket_list");
+    const text = lines.join("\n");
+    if (text.length <= RECALL_BUDGET)
+        return text;
+    // Pathological titles/summaries: shrink every line instead of dropping whole
+    // lines, so each worker/ticket ID stays visible while the block fits budget.
+    const perLine = Math.max(24, Math.floor(RECALL_BUDGET / lines.length) - 1);
+    return clip(lines.map((line) => clip(line, perLine)).join("\n"), RECALL_BUDGET);
+}
+/**
+ * Narrow one request's toolset by session role. The Router keeps only the
+ * catalog tools; a tracked Worker loses every router-only tool (dispatch,
+ * sleep, tickets, recall, abort_session), so those tools are not listed to
+ * the worker model at all. User sessions are left untouched.
+ */
+export function filterSessionTools(sessionID, tools) {
+    const router = store.routerID !== undefined && sessionID === store.routerID;
+    const worker = store.workers.has(sessionID);
+    if (!router && !worker)
+        return;
+    for (const name of Object.keys(tools)) {
+        if (router ? !ROUTER_TOOLS.has(name) : ROUTER_TOOLS.has(name))
+            delete tools[name];
+    }
+}
+/**
+ * Context hook: strip each session's toolset to what that role may see
+ * (Router: catalog only; Worker: catalog tools removed), then append the
+ * router prompt plus a short live status line for the Router.
+ *
+ * The status line carries the ticket counters and the current thread's
+ * in-progress ticket ids/titles, so a follow-up can be linked back to an
+ * existing ticket without a tool call.
+ */
+export const registerContext = Effect.fn("superagent.registerContext")(function* (ctx) {
+    yield* ctx.session.hook("context", (event) => Effect.sync(() => {
+        const router = store.routerID !== undefined && event.sessionID === store.routerID;
+        if (!router && !store.workers.has(event.sessionID))
+            return;
+        filterSessionTools(event.sessionID, event.tools);
+        if (!router)
+            return;
+        const stats = ticketStats();
+        const threadID = currentTrigger()?.threadID;
+        const active = activeTicketSummary(threadID);
+        const tickets = `tickets=open${stats.open}/in_progress${stats.inProgress}/blocked${stats.blocked}/closed${stats.closed}`;
+        const focus = active === "" ? "" : `\n进行中工单（当前 thread）：${active}`;
+        const recall = buildRecallInjection(threadID);
+        const chain = recall === "" ? "" : `\n\n${recall}`;
+        event.system.push({
+            type: "text",
+            text: `${ROUTER_PROMPT}\n\nStatus: workers=${store.workers.size} pending=${store.pending.length} triggers=${store.triggerTotal} ${tickets}. ${directorySummary()}.${focus}${chain}`,
+        });
+    }));
+    yield* registerRecall(ctx);
+});