opencode-superagent 0.0.0-stage → 0.1.0

package/dist/src/abort.js

@@ -0,0 +1,176 @@
+import { Tool } from "@opencode/schema/tool";
+import { DateTime, Effect, Option, Schema } from "effect";
+import { requireRouter } from "./guard.js";
+import { encodeThread, 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 });
+/** A Session is running while `time.busy` is newer than the last completed execution's `time.idle`. */
+function isRunning(info) {
+    const busy = info.time.busy;
+    if (busy === undefined)
+        return false;
+    const idle = info.time.idle;
+    return idle === undefined || DateTime.toEpochMillis(busy) > DateTime.toEpochMillis(idle);
+}
+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 };
+    }
+    if (!running) {
+        worker.lastReport = abortNote(reason, "already ended", previous);
+        yield* saveWorker(ctx, worker);
+        return { sessionID, status: "already-ended", interrupted: false, timedOut: false, threads };
+    }
+    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))));
+    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,20 @@
+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;
+/**
+ * Router-only context hook: strip every tool outside the router set
+ * (derived from the tool catalog in `src/tools.ts`),
+ * then append the router prompt plus a short live status line.
+ *
+ * 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,98 @@
+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);
+}
+/**
+ * Router-only context hook: strip every tool outside the router set
+ * (derived from the tool catalog in `src/tools.ts`),
+ * then append the router prompt plus a short live status line.
+ *
+ * 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(() => {
+        if (store.routerID === undefined || event.sessionID !== store.routerID)
+            return;
+        for (const name of Object.keys(event.tools)) {
+            if (!ROUTER_TOOLS.has(name))
+                delete event.tools[name];
+        }
+        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);
+});

package/dist/src/dirs.d.ts

@@ -0,0 +1,45 @@
+import type { Plugin } from "@opencode/plugin/effect";
+import { Effect } from "effect";
+/**
+ * Router 自管目录记忆：单网关进程服务多目录，Router 从自然语言推断
+ * 项目指向并经 `dispatch({ directory })` 落到目标目录。
+ *
+ * - `dir:thread:<threadID>` -> 绝对路径：该聊天/话题上次使用的目录，命中则复用。
+ * - `dir:alias:<alias小写>` -> 绝对路径：别名（如 `ai-gw`）到目录的映射，basename 自动登记。
+ *
+ * 网关进程本身的目录（`ctx.location.directory`）只是缺省值，不重要。
+ */
+export declare const DIR_THREAD_PREFIX = "dir:thread:";
+export declare const DIR_ALIAS_PREFIX = "dir:alias:";
+export declare const threadDirKey: (threadID: string) => string;
+export declare const aliasDirKey: (alias: string) => string;
+/** threadID -> 绝对路径（内存镜像，hydrate 时从 KV 读回）。 */
+export declare const threadDirs: Map<string, string>;
+/** 小写别名 -> 绝对路径（内存镜像，hydrate 时从 KV 读回）。 */
+export declare const aliasDirs: Map<string, string>;
+export declare function isValidDirectory(dir: string): boolean;
+export declare function normalizeDirectory(dir: string): string | undefined;
+/** 目录 basename 小写即默认别名（`/opt/ai-gw` -> `ai-gw`）。 */
+export declare function basenameAlias(dir: string): string;
+/** 启动时把 KV 中的目录映射读回内存；坏条目直接清理。 */
+export declare const hydrateDirs: (ctx: Plugin.Context) => Effect.Effect<void, never, never>;
+export interface ResolveDirectoryInput {
+    readonly threadID?: string;
+    readonly task?: string;
+    readonly requested?: string;
+}
+/**
+ * 目录解析优先级：显式 directory > thread 绑定 > 任务文本中的已知别名 >
+ * 调用方缺省（网关目录）。返回 `undefined` 时调用方用网关默认目录。
+ */
+export declare function resolveDirectory(input: ResolveDirectoryInput): string | undefined;
+/** 状态行/Spill 用的紧凑摘要（别名全列，thread 只记数量避免刷屏）。 */
+export declare function directorySummary(): string;
+/** 已知 thread 绑定的单行提示，拼到 flush 给 Router 的 trigger 文本后面。 */
+export declare function threadDirHint(threadID: string): string | undefined;
+export declare const rememberDirectory: (ctx: Plugin.Context, input: {
+    readonly threadID?: string;
+    readonly directory: string;
+}) => Effect.Effect<void, never, never>;
+/** `/dir` 手动切 Router 目录时同步记住 basename 别名，不改 thread 绑定。 */
+export declare const rememberAlias: (ctx: Plugin.Context, directory: string) => Effect.Effect<void, never, never>;

package/dist/src/dirs.js

@@ -0,0 +1,129 @@
+import { Effect } from "effect";
+/**
+ * Router 自管目录记忆：单网关进程服务多目录，Router 从自然语言推断
+ * 项目指向并经 `dispatch({ directory })` 落到目标目录。
+ *
+ * - `dir:thread:<threadID>` -> 绝对路径：该聊天/话题上次使用的目录，命中则复用。
+ * - `dir:alias:<alias小写>` -> 绝对路径：别名（如 `ai-gw`）到目录的映射，basename 自动登记。
+ *
+ * 网关进程本身的目录（`ctx.location.directory`）只是缺省值，不重要。
+ */
+export const DIR_THREAD_PREFIX = "dir:thread:";
+export const DIR_ALIAS_PREFIX = "dir:alias:";
+export const threadDirKey = (threadID) => `${DIR_THREAD_PREFIX}${threadID}`;
+export const aliasDirKey = (alias) => `${DIR_ALIAS_PREFIX}${alias.toLowerCase()}`;
+/** threadID -> 绝对路径（内存镜像，hydrate 时从 KV 读回）。 */
+export const threadDirs = new Map();
+/** 小写别名 -> 绝对路径（内存镜像，hydrate 时从 KV 读回）。 */
+export const aliasDirs = new Map();
+export function isValidDirectory(dir) {
+    return dir.startsWith("/") && dir.length >= 1 && dir.length <= 500;
+}
+export function normalizeDirectory(dir) {
+    const trimmed = dir.trim();
+    if (!isValidDirectory(trimmed))
+        return undefined;
+    if (trimmed.length > 1 && trimmed.endsWith("/"))
+        return trimmed.slice(0, -1);
+    return trimmed;
+}
+/** 目录 basename 小写即默认别名（`/opt/ai-gw` -> `ai-gw`）。 */
+export function basenameAlias(dir) {
+    const clean = dir.length > 1 && dir.endsWith("/") ? dir.slice(0, -1) : dir;
+    const parts = clean.split("/").filter((part) => part !== "");
+    return (parts[parts.length - 1] ?? "").toLowerCase();
+}
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+/** 启动时把 KV 中的目录映射读回内存；坏条目直接清理。 */
+export const hydrateDirs = Effect.fn("superagent.hydrateDirs")(function* (ctx) {
+    for (const prefix of [DIR_THREAD_PREFIX, DIR_ALIAS_PREFIX]) {
+        let after;
+        do {
+            const page = yield* ctx.storage
+                .scan({ prefix, after, limit: 100 })
+                .pipe(Effect.catch(() => Effect.succeed({ entries: [], next: undefined })));
+            for (const entry of page.entries) {
+                const dir = asString(entry.value);
+                if (dir === undefined || !isValidDirectory(dir)) {
+                    yield* ctx.storage.remove(entry.key).pipe(Effect.catch(() => Effect.void));
+                    continue;
+                }
+                if (prefix === DIR_THREAD_PREFIX)
+                    threadDirs.set(entry.key.slice(prefix.length), dir);
+                else
+                    aliasDirs.set(entry.key.slice(prefix.length).toLowerCase(), dir);
+            }
+            after = page.next;
+        } while (after !== undefined);
+    }
+});
+/**
+ * 目录解析优先级：显式 directory > thread 绑定 > 任务文本中的已知别名 >
+ * 调用方缺省（网关目录）。返回 `undefined` 时调用方用网关默认目录。
+ */
+export function resolveDirectory(input) {
+    if (input.requested !== undefined) {
+        const normalized = normalizeDirectory(input.requested);
+        if (normalized !== undefined)
+            return normalized;
+    }
+    if (input.threadID !== undefined) {
+        const bound = threadDirs.get(input.threadID);
+        if (bound !== undefined)
+            return bound;
+    }
+    const task = input.task?.toLowerCase() ?? "";
+    if (task !== "") {
+        const aliases = [...aliasDirs.entries()].sort((left, right) => right[0].length - left[0].length);
+        for (const [alias, dir] of aliases) {
+            if (alias.length >= 2 && task.includes(alias))
+                return dir;
+        }
+    }
+    return undefined;
+}
+/** 状态行/Spill 用的紧凑摘要（别名全列，thread 只记数量避免刷屏）。 */
+export function directorySummary() {
+    const aliases = [...aliasDirs.entries()].map(([alias, dir]) => `${alias}=${dir}`).join(",");
+    return `dirs: threads=${threadDirs.size} aliases=${aliases === "" ? "-" : aliases}`;
+}
+/** 已知 thread 绑定的单行提示，拼到 flush 给 Router 的 trigger 文本后面。 */
+export function threadDirHint(threadID) {
+    const bound = threadDirs.get(threadID);
+    if (bound === undefined)
+        return undefined;
+    return `已知目录：${bound}（该 thread 上次使用，命中则复用 dispatch directory=${bound}；换目录需用户确认）`;
+}
+export const rememberDirectory = Effect.fn("superagent.rememberDirectory")(function* (ctx, input) {
+    const normalized = normalizeDirectory(input.directory);
+    if (normalized === undefined)
+        return;
+    if (input.threadID !== undefined) {
+        threadDirs.set(input.threadID, normalized);
+        yield* ctx.storage
+            .set(threadDirKey(input.threadID), normalized)
+            .pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to persist thread directory", { cause })));
+    }
+    const alias = basenameAlias(normalized);
+    if (alias !== "") {
+        aliasDirs.set(alias, normalized);
+        yield* ctx.storage
+            .set(aliasDirKey(alias), normalized)
+            .pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to persist alias directory", { cause })));
+    }
+});
+/** `/dir` 手动切 Router 目录时同步记住 basename 别名，不改 thread 绑定。 */
+export const rememberAlias = Effect.fn("superagent.rememberAlias")(function* (ctx, directory) {
+    const normalized = normalizeDirectory(directory);
+    if (normalized === undefined)
+        return;
+    const alias = basenameAlias(normalized);
+    if (alias === "")
+        return;
+    aliasDirs.set(alias, normalized);
+    yield* ctx.storage
+        .set(aliasDirKey(alias), normalized)
+        .pipe(Effect.catch((cause) => Effect.logWarning("superagent failed to persist alias directory", { cause })));
+});

package/dist/src/dispatch.d.ts

@@ -0,0 +1,38 @@
+import { type Plugin } from "@opencode/plugin/effect";
+import { Tool } from "@opencode/schema/tool";
+import { Effect, Schema } from "effect";
+export declare const DispatchInput: Schema.Struct<{
+    readonly task: Schema.String;
+    readonly title: Schema.optionalKey<Schema.String>;
+    readonly threadID: Schema.optionalKey<Schema.String>;
+    readonly agent: Schema.optionalKey<Schema.String>;
+    readonly directory: Schema.optionalKey<Schema.String>;
+    readonly ticketID: Schema.String;
+}>;
+interface DispatchInput {
+    readonly task: string;
+    readonly title?: string;
+    readonly threadID?: string;
+    readonly agent?: string;
+    readonly directory?: string;
+    readonly ticketID: string;
+}
+/**
+ * The one dispatch implementation, shared by the `dispatch` tool and the
+ * `dispatch` RPC. Both paths pass the same ticket gate: `ticketID` is required
+ * by the schema and re-checked here, so a direct RPC call cannot skip the
+ * work order either.
+ *
+ * There is deliberately no `internal` bypass: no watchdog/resume path calls
+ * dispatch today (the watchdog reports to the Router and resume prompts an
+ * existing worker session), so every caller of this function is a real task
+ * dispatch and must be backed by a ticket.
+ */
+export declare const runDispatch: (ctx: Plugin.Context, input: DispatchInput, caller: string) => Effect.Effect<{
+    output: {
+        sessionID: string & import("effect/Brand").Brand<"SessionID">;
+    };
+    content: string;
+}, Tool.Error, never>;
+export declare const registerTools: (ctx: Plugin.Context) => Effect.Effect<void, never, import("effect/Scope").Scope>;
+export {};