@twinsearth/dsh-master 0.0.0-stage → 3.2.8

package/dist-host/plugins/superagent-router.js

@@ -0,0 +1,499 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+/**
+ * 子插件：SuperAgent Router（v3.2.3）—— 常驻原身（essence）。
+ *
+ * v3.2.3 增量：
+ *   * 派发桥：本地 fangForker 或母体 `/dsh-master/api/bridge/spawn`（Bearer bridgeToken）；
+ *   * 真实 streaming：Worker → Router `/dsh-master/api/superagent/worker-events`（per-ticket token），
+ *     Router 落库 Ticket 状态并在 done 时触发回写（webhook/GitHub comment）；
+ *   * 状态接口暴露事件计数/回写模式，不暴露任何 token。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { FANG_SERVICE, ROW, SERVICE, bearerOf, detectRole, enabledOf, jsonResponse, readJsonBody, roleAllowed, safeGet, } from "../kernel.js";
+import { createTicketStore } from "../superagent/ticket-store.js";
+import { createFangDispatcher } from "../superagent/dispatch.js";
+import { createSuperagentRouter } from "../superagent/router.js";
+import { createStreamTokenManager } from "../superagent/stream-tokens.js";
+import { createNodeStreamTransport, createStreamBroadcaster, resolveHostStreamAdapter, } from "../superagent/stream-adapter.js";
+import { createWriteback } from "../superagent/writeback.js";
+import { createPrDelivery } from "../superagent/pr-delivery.js";
+export const name = 'dsh-master-superagent-router';
+export const inject = ['dshMaster'];
+export const ROW_ID = ROW.superagentRouter;
+const EVENTS_PATH = '/dsh-master/api/superagent/worker-events';
+const STREAM_PATH = '/dsh-master/api/superagent/stream';
+const STREAM_TOKEN_PATH = '/dsh-master/api/superagent/stream-token';
+const STATUS_PATH = '/dsh-master/api/superagent/status';
+const SESSION_PATH = '/dsh-master/api/superagent/session';
+const PR_PATH = '/dsh-master/api/superagent/pr';
+const GITHUB_PATH = '/dsh-master/api/superagent/github';
+const FEISHU_PATH = '/dsh-master/api/superagent/feishu';
+const MAX_BODY_BYTES = 1024 * 1024;
+const MAX_EVENTS_PER_TICKET = 500;
+async function readRawBody(req, limit = MAX_BODY_BYTES) {
+    try {
+        const chunks = [];
+        let total = 0;
+        if (req && typeof req[Symbol.asyncIterator] === 'function') {
+            for await (const chunk of req) {
+                const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+                total += buffer.length;
+                if (total > limit)
+                    return null;
+                chunks.push(buffer);
+            }
+        }
+        else if (req && typeof req.on === 'function') {
+            await new Promise((resolve, reject) => {
+                req.on('data', (chunk) => {
+                    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+                    total += buffer.length;
+                    if (total > limit)
+                        reject(new Error('body-too-large'));
+                    else
+                        chunks.push(buffer);
+                });
+                req.on('end', resolve);
+                req.on('error', reject);
+            });
+        }
+        return Buffer.concat(chunks).toString('utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @param {object} ctx
+ * @param {object} [config]
+ */
+export function apply(ctx, config = {}) {
+    if (!enabledOf(config))
+        return { skipped: true, reason: 'disabled-by-config' };
+    const role = detectRole();
+    if (!roleAllowed(ROW_ID, role)) {
+        try {
+            ctx?.logger?.info?.(`[dsh-master] superagent-router skipped: role=${role} not in essence`);
+        }
+        catch { /* ignore */ }
+        return { skipped: true, reason: `role-not-allowed:${role}` };
+    }
+    const master = safeGet(ctx, SERVICE.master);
+    if (!master || typeof master.registerSubplugin !== 'function') {
+        return { skipped: true, reason: 'master-core-unavailable' };
+    }
+    const store = createTicketStore({ dataDir: config.dataDir, logger: ctx.logger });
+    const writeback = createWriteback(config.writeback, { logger: ctx.logger });
+    const prDelivery = createPrDelivery({
+        token: config.writeback?.githubToken,
+        repo: config.writeback?.githubRepo ?? config.prRepo,
+        apiBase: config.writeback?.githubApiBase,
+        baseBranch: config.writeback?.baseBranch,
+    });
+    /** Ticket → 3_Sessions 会话映射：threadId 优先，缺省用 ticket id。 */
+    const sessionMap = new Map();
+    const tokenAuditFile = config.dataDir ? path.join(String(config.dataDir), 'token-audit.jsonl') : '';
+    const tokenManager = createStreamTokenManager({
+        workerTtlMs: config.streamTokenTtlMs,
+        uiTtlMs: config.uiTokenTtlMs,
+        auditSink: tokenAuditFile ? (record) => {
+            try {
+                fs.mkdirSync(path.dirname(tokenAuditFile), { recursive: true });
+                fs.appendFileSync(tokenAuditFile, JSON.stringify(record) + '\n', { mode: 0o600 });
+            }
+            catch { /* 审计落盘失败不影响鉴权 */ }
+        } : null,
+    });
+    // 定时清理过期 token（避免 TTL 之后仍占内存）
+    const sweepTimer = setInterval(() => { try {
+        tokenManager.sweep();
+    }
+    catch { /* ignore */ } }, 60_000);
+    sweepTimer.unref?.();
+    const quotaCfg = {
+        enabled: !(config.workerQuota && config.workerQuota.enabled === false),
+        maxConcurrent: Math.max(1, Math.floor(Number(config.workerQuota?.maxConcurrent ?? 2))),
+        maxPerSource: Math.max(0, Math.floor(Number(config.workerQuota?.maxPerSource ?? 0))),
+    };
+    const broadcaster = createStreamBroadcaster({ ringSize: 300 });
+    const hostAdapter = resolveHostStreamAdapter(ctx);
+    if (hostAdapter)
+        broadcaster.useHostAdapter(hostAdapter);
+    let origin = '';
+    const workerEvents = new Map();
+    const dispatcher = createFangDispatcher(ctx, config, { getOrigin: () => origin });
+    const wrappedDispatcher = {
+        available: () => dispatcher.available(),
+        describe: () => ({ ...dispatcher.describe(), streaming: Boolean(origin), writeback: writeback.describe().enabled }),
+        async dispatch(ticket) {
+            // Ticket → 会话仓映射：threadId 是 GitHub/飞书里的会话键，缺失时退回 ticket id。
+            const sessionKey = String(ticket?.threadId ?? ticket?.id ?? '');
+            sessionMap.set(String(ticket.id), {
+                ticketId: String(ticket.id),
+                sessionKey,
+                sourceId: String(ticket.sourceId ?? ''),
+                status: 'dispatched',
+                dispatchedAt: Date.now(),
+            });
+            let extraEnv = {};
+            let issued = null;
+            if (origin) {
+                issued = tokenManager.issue({ kind: 'worker', ticketId: ticket.id });
+                extraEnv = {
+                    DSH_MASTER_STREAM_URL: `${origin}${EVENTS_PATH}`,
+                    DSH_MASTER_STREAM_TOKEN: issued.token,
+                };
+            }
+            try {
+                const out = await dispatcher.dispatch(ticket, extraEnv);
+                if (out && out.ok !== true && issued)
+                    tokenManager.revoke(issued.token, 'dispatch-failed');
+                if (out && out.ok !== true) {
+                    const mapped = sessionMap.get(String(ticket.id));
+                    if (mapped)
+                        sessionMap.set(String(ticket.id), { ...mapped, status: 'failed', finishedAt: Date.now(), reason: String(out.code ?? 'dispatch-failed') });
+                }
+                return out;
+            }
+            catch (error) {
+                if (issued)
+                    tokenManager.revoke(issued.token, 'dispatch-threw');
+                const mapped = sessionMap.get(String(ticket.id));
+                if (mapped)
+                    sessionMap.set(String(ticket.id), { ...mapped, status: 'failed', finishedAt: Date.now(), reason: 'dispatch-threw' });
+                throw error;
+            }
+        },
+    };
+    const dispatchTimeoutMs = Math.max(60_000, Number(config.dispatchTimeoutMs ?? 15 * 60_000) || 15 * 60_000);
+    const WATCHDOG_INTERVAL_MS = 60_000;
+    let watchdogSwept = 0;
+    const activeTickets = () => store.list({ limit: 5000 }).filter((record) => ['pending', 'dispatched', 'running'].includes(record.status));
+    /** 派发超时看护：Worker 长时间无终态 → 判 failed(worker-timeout) 并释放配额。 */
+    const watchdogSweep = () => {
+        const now = Date.now();
+        for (const record of activeTickets()) {
+            const status = String(record.status);
+            const startedAt = Math.max(Number(record.updatedAt ?? 0), Number(record.ticket?.createdAt ?? 0), Number(workerEvents.get(record.ticket.id)?.at(-1)?.at ?? 0)) || now;
+            const age = now - startedAt;
+            if (age < dispatchTimeoutMs)
+                continue;
+            store.setStatus(record.ticket.id, 'failed', { code: 'worker-timeout', ageMs: age });
+            const mapped = sessionMap.get(record.ticket.id);
+            if (mapped)
+                sessionMap.set(record.ticket.id, { ...mapped, status: 'failed', finishedAt: now, reason: 'worker-timeout' });
+            watchdogSwept += 1;
+            broadcast({ type: 'timeout', ticketId: record.ticket.id, at: now, payload: { code: 'worker-timeout', ageMs: age } });
+        }
+    };
+    const watchdogTimer = setInterval(() => { try {
+        watchdogSweep();
+    }
+    catch { /* 看护失败不致命 */ } }, WATCHDOG_INTERVAL_MS);
+    watchdogTimer.unref?.();
+    const quotaStatus = () => {
+        const active = activeTickets();
+        const bySource = {};
+        for (const record of active)
+            bySource[record.ticket.sourceId] = (bySource[record.ticket.sourceId] ?? 0) + 1;
+        return { ...quotaCfg, active: active.length, bySource, remaining: Math.max(0, quotaCfg.maxConcurrent - active.length) };
+    };
+    const beforeDispatch = async (ticket) => {
+        if (!quotaCfg.enabled)
+            return { ok: true };
+        const active = activeTickets();
+        if (active.length >= quotaCfg.maxConcurrent) {
+            return { ok: false, reason: 'worker-quota-exceeded', quota: { ...quotaStatus(), limit: quotaCfg.maxConcurrent } };
+        }
+        if (quotaCfg.maxPerSource > 0) {
+            const sameSource = active.filter((record) => record.ticket.sourceId === ticket.sourceId).length;
+            if (sameSource >= quotaCfg.maxPerSource) {
+                return { ok: false, reason: 'worker-quota-per-source-exceeded', quota: { ...quotaStatus(), perSourceLimit: quotaCfg.maxPerSource } };
+            }
+        }
+        return { ok: true, quota: quotaStatus() };
+    };
+    const broadcast = (event) => broadcaster.publish(event);
+    const router = createSuperagentRouter({ config, store, dispatcher: wrappedDispatcher, logger: ctx.logger, beforeDispatch });
+    const hasForker = () => Boolean(safeGet(ctx, FANG_SERVICE.forker));
+    const appendEvents = (ticketId, events) => {
+        const list = workerEvents.get(ticketId) ?? [];
+        for (const event of events) {
+            const enriched = { ...event, ticketId, at: event?.at ?? Date.now() };
+            list.push(enriched);
+            broadcast(enriched);
+        }
+        if (list.length > MAX_EVENTS_PER_TICKET)
+            list.splice(0, list.length - MAX_EVENTS_PER_TICKET);
+        workerEvents.set(ticketId, list);
+        return list;
+    };
+    const handleWorkerEvents = async (ticketId, events, token = '') => {
+        appendEvents(ticketId, events);
+        const done = [...events].reverse().find((event) => event && event.type === 'done');
+        if (!done)
+            return;
+        const result = done.payload?.result ?? null;
+        store.setStatus(ticketId, result?.ok === true ? 'done' : 'failed', { result });
+        const record = store.get(ticketId);
+        if (record) {
+            try {
+                await writeback.send({ ticket: record.ticket, result });
+            }
+            catch { /* 回写失败不影响状态 */ }
+        }
+        // 会话映射进入终态（3_Sessions 侧据此归档/回放）。
+        const mapped = sessionMap.get(ticketId) ?? { ticketId };
+        sessionMap.set(ticketId, { ...mapped, status: result?.ok === true ? 'done' : 'failed', finishedAt: Date.now() });
+        // PR 交付：分支由宿主/分身推好后，Router 用宿主 token 开 PR（Worker 永不持凭据）。
+        const pr = result?.pr ?? null;
+        if (pr && prDelivery.enabled && pr.branch) {
+            const files = Array.isArray(pr.files) ? pr.files : [];
+            const created = files.length > 0
+                ? await prDelivery.deliver({
+                    ticketId,
+                    source: record?.ticket?.sourceId ?? '',
+                    branch: String(pr.branch),
+                    title: String(pr.title ?? `SuperAgent: ${ticketId}`),
+                    body: String(pr.body ?? ''),
+                    base: pr.base,
+                    draft: pr.draft === true,
+                    files,
+                })
+                : await prDelivery.create({
+                    branch: String(pr.branch),
+                    title: String(pr.title ?? `SuperAgent: ${ticketId}`),
+                    body: String(pr.body ?? ''),
+                    base: pr.base,
+                    draft: pr.draft === true,
+                });
+            broadcast({ type: 'pr', ticketId, at: Date.now(), payload: created });
+        }
+        if (token)
+            tokenManager.revoke(token, 'ticket-done');
+    };
+    const service = {
+        id: 'superagent-router',
+        version: '3.2.5',
+        role,
+        status: () => ({
+            ...router.status(),
+            forkerService: hasForker(),
+            streaming: { configured: Boolean(origin), ...broadcaster.describe(), tokens: tokenManager.counts() },
+            workerEvents: Object.fromEntries([...workerEvents.entries()].map(([k, v]) => [k, v.length])),
+            writeback: writeback.describe(),
+            quota: quotaStatus(),
+            sessions: { count: sessionMap.size, last: [...sessionMap.values()].slice(-3) },
+            watchdog: { intervalMs: WATCHDOG_INTERVAL_MS, timeoutMs: dispatchTimeoutMs, swept: watchdogSwept },
+            pr: prDelivery.describe(),
+            tokenAudit: tokenManager.audit(10),
+        }),
+        ingest: (event) => router.ingest(event),
+        ingestGithubWebhook: (input) => router.ingestGithubWebhook(input),
+        ingestFeishuWebhook: (input) => router.ingestFeishuWebhook(input),
+        tickets: (limit) => router.tickets(limit),
+        recent: (limit) => router.recent(limit),
+        policy: () => router.policy(),
+        setTrustMode: (mode) => router.setTrustMode(mode),
+        workerEvents(ticketId) {
+            return { ok: true, ticketId: String(ticketId ?? ''), events: workerEvents.get(String(ticketId ?? '')) ?? [] };
+        },
+        tokenAudit(limit) { return tokenManager.audit(limit); },
+        rotateStreamToken(oldToken = '') { return tokenManager.rotate(oldToken, { kind: 'ui' }); },
+        quota: () => quotaStatus(),
+        close() {
+            try {
+                clearInterval(sweepTimer);
+            }
+            catch { /* ignore */ }
+            try {
+                clearInterval(watchdogTimer);
+            }
+            catch { /* ignore */ }
+            broadcaster.closeAll();
+        },
+    };
+    try {
+        ctx.effect(() => ctx.provide(SERVICE.superagentRouter, service));
+    }
+    catch { /* fake ctx */ }
+    try {
+        ctx.effect(() => () => service.close());
+    }
+    catch { /* fake ctx */ }
+    master.registerSubplugin({
+        id: 'superagent-router',
+        name: 'dsh-master-superagent-router',
+        capabilities: ['webhook-ingest', 'trust-eval', 'ticket-mandate', 'worker-dispatch', 'worker-stream', 'writeback'],
+        description: 'SuperAgent Router（仅原身；只派发不执行）',
+    });
+    // HTTP：Webhook 入口 + Worker 实时事件 + 只读状态。
+    try {
+        if (typeof ctx.inject === 'function') {
+            ctx.inject(['webServer'], (child) => {
+                const webServer = child?.get?.('webServer') ?? child?.webServer;
+                if (!webServer || typeof webServer.register !== 'function')
+                    return;
+                try {
+                    origin = typeof webServer.getOrigin === 'function' ? String(webServer.getOrigin() ?? '').replace(/\/+$/, '') : '';
+                }
+                catch {
+                    origin = '';
+                }
+                const register = (spec) => { try {
+                    webServer.register(spec);
+                }
+                catch { /* duplicate route */ } };
+                register({ kind: 'exact', path: STATUS_PATH, method: 'GET', handler: async (req, res) => jsonResponse(res, 200, service.status()) });
+                // DSH webServer 的路由键是 (kind,path)，不包含 HTTP method；同一路径注册两次
+                // 会抛 duplicate，旧实现把第二次注册吞掉，导致 GET 实际落进 POST handler。
+                // 因此 EVENTS_PATH 只注册一次，在 handler 内显式分流。
+                register({
+                    kind: 'exact', path: EVENTS_PATH, method: 'ANY',
+                    handler: async (req, res) => {
+                        const method = String(req?.method ?? 'POST').toUpperCase();
+                        if (method === 'POST') {
+                            const token = bearerOf(req?.headers ?? {});
+                            const parsed = await readJsonBody(req);
+                            if (!parsed.ok)
+                                return jsonResponse(res, parsed.code === 'body-too-large' ? 413 : 400, { ok: false, code: parsed.code });
+                            const ticketId = String(parsed.body?.ticketId ?? '');
+                            const verified = tokenManager.verify(token, { kind: 'worker' });
+                            if (!verified.ok)
+                                return jsonResponse(res, 401, { ok: false, code: 'worker-token-invalid', reason: verified.reason });
+                            if (!ticketId || ticketId !== verified.entry.ticketId)
+                                return jsonResponse(res, 403, { ok: false, code: 'ticket-token-mismatch' });
+                            const events = Array.isArray(parsed.body?.events) ? parsed.body.events.slice(0, 100) : [];
+                            await handleWorkerEvents(ticketId, events, token);
+                            return jsonResponse(res, 200, { ok: true, accepted: events.length });
+                        }
+                        if (method === 'GET') {
+                            const query = new URL(String(req?.url ?? '/'), 'http://x').searchParams;
+                            const ticketId = String(query.get('ticketId') ?? '');
+                            const supplied = String(query.get('token') ?? '') || bearerOf(req?.headers ?? {});
+                            const verified = tokenManager.verify(supplied);
+                            if (!verified.ok)
+                                return jsonResponse(res, 401, { ok: false, code: 'events-token-invalid', reason: verified.reason });
+                            if (verified.entry.kind === 'worker' && verified.entry.ticketId !== ticketId)
+                                return jsonResponse(res, 403, { ok: false, code: 'ticket-token-mismatch' });
+                            return jsonResponse(res, 200, service.workerEvents(ticketId));
+                        }
+                        return jsonResponse(res, 405, { ok: false, code: 'method-not-allowed' });
+                    },
+                });
+                // v3.2.5：浏览器 SSE 订阅 token（短 TTL、可轮换）；不暴露 worker token。
+                register({
+                    kind: 'exact', path: STREAM_TOKEN_PATH, method: 'POST',
+                    handler: async (req, res) => {
+                        const parsed = await readJsonBody(req);
+                        const oldToken = parsed.ok ? String(parsed.body?.token ?? '') : '';
+                        if (oldToken) {
+                            const issued = tokenManager.rotate(oldToken, { kind: 'ui' });
+                            if (!issued.ok || !issued.token)
+                                return jsonResponse(res, 401, { ok: false, code: 'stream-token-rotate-failed', reason: issued.error ?? 'invalid-token' });
+                            return jsonResponse(res, 200, { ok: true, token: issued.token, expiresAt: issued.expiresAt });
+                        }
+                        // 首次签发只允许本机回环或受信浏览器同源；显式 bootstrap token 可用于受控远程部署。
+                        const remote = String(req?.socket?.remoteAddress ?? req?.connection?.remoteAddress ?? '');
+                        const loopback = !remote || /^(127\.|::1$|::ffff:127\.)/.test(remote);
+                        const bootstrap = String(config.streamBootstrapToken ?? '');
+                        const supplied = bearerOf(req?.headers ?? {});
+                        if (bootstrap) {
+                            if (supplied !== bootstrap)
+                                return jsonResponse(res, 401, { ok: false, code: 'stream-bootstrap-required' });
+                        }
+                        else if (!loopback) {
+                            return jsonResponse(res, 403, { ok: false, code: 'stream-local-only' });
+                        }
+                        const issued = tokenManager.issue({ kind: 'ui' });
+                        return jsonResponse(res, 200, { ok: true, token: issued.token, expiresAt: issued.expiresAt });
+                    },
+                });
+                // v3.2.5：实时事件流（SSE）。默认要求 UI token；config.streamTokenRequired=false 可关闭。
+                register({
+                    kind: 'exact', path: STREAM_PATH, method: 'GET',
+                    handler: async (req, res) => {
+                        const query = new URL(String(req?.url ?? '/'), 'http://x').searchParams;
+                        if (config.streamTokenRequired !== false) {
+                            const verified = tokenManager.verify(String(query.get('token') ?? ''), { kind: 'ui' });
+                            if (!verified.ok)
+                                return jsonResponse(res, 401, { ok: false, code: 'stream-token-invalid', reason: verified.reason });
+                        }
+                        try {
+                            res.writeHead?.(200, {
+                                'content-type': 'text/event-stream; charset=utf-8',
+                                'cache-control': 'no-store',
+                                connection: 'keep-alive',
+                                'x-accel-buffering': 'no',
+                            });
+                        }
+                        catch {
+                            return jsonResponse(res, 500, { ok: false, code: 'sse-failed' });
+                        }
+                        // 传输细节交给 adapter：内置 Node SSE；宿主可注入 WS/自有 SSE。
+                        const transport = createNodeStreamTransport(res);
+                        broadcaster.attach(transport, { replay: true });
+                        const heartbeat = setInterval(() => broadcaster.heartbeat(': ping\n\n'), 15_000);
+                        const cleanup = () => { clearInterval(heartbeat); transport.end(); broadcaster.detach(transport); };
+                        transport.onClose(cleanup);
+                        try {
+                            req.on?.('close', cleanup);
+                        }
+                        catch { /* ignore */ }
+                        return undefined;
+                    },
+                });
+                register({
+                    kind: 'exact', path: SESSION_PATH, method: 'GET',
+                    handler: async (req, res) => {
+                        const query = new URL(String(req?.url ?? '/'), 'http://x').searchParams;
+                        const ticketId = String(query.get('ticketId') ?? '');
+                        if (!ticketId)
+                            return jsonResponse(res, 400, { ok: false, code: 'ticket-id-required' });
+                        const mapped = sessionMap.get(ticketId);
+                        if (!mapped)
+                            return jsonResponse(res, 404, { ok: false, code: 'session-not-found', ticketId });
+                        return jsonResponse(res, 200, { ok: true, session: mapped });
+                    },
+                });
+                register({
+                    kind: 'exact', path: GITHUB_PATH, method: 'POST',
+                    handler: async (req, res) => {
+                        const raw = await readRawBody(req);
+                        if (raw === null)
+                            return jsonResponse(res, 413, { ok: false, code: 'body-too-large' });
+                        const out = await service.ingestGithubWebhook({
+                            rawBody: raw, headers: req?.headers ?? {}, secret: config.githubSecret, mentionHandles: config.mentionHandles,
+                        });
+                        return jsonResponse(res, out.status, out.body);
+                    },
+                });
+                register({
+                    kind: 'exact', path: FEISHU_PATH, method: 'POST',
+                    handler: async (req, res) => {
+                        const raw = await readRawBody(req);
+                        if (raw === null)
+                            return jsonResponse(res, 413, { ok: false, code: 'body-too-large' });
+                        let payload = null;
+                        try {
+                            payload = JSON.parse(raw);
+                        }
+                        catch {
+                            return jsonResponse(res, 400, { ok: false, code: 'invalid-json' });
+                        }
+                        const out = await service.ingestFeishuWebhook({
+                            payload, verificationToken: config.feishuVerificationToken, mentionHandles: config.mentionHandles, encryptKey: config.feishuEncryptKey,
+                        });
+                        return jsonResponse(res, out.status, out.body);
+                    },
+                });
+            });
+        }
+    }
+    catch { /* 无 webServer 时仍可通过服务调用 ingest */ }
+    return service;
+}
+export { EVENTS_PATH, STREAM_PATH, STREAM_TOKEN_PATH, STATUS_PATH, SESSION_PATH, readRawBody };

package/dist-host/plugins/superagent-worker.js

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+/**
+ * 子插件：SuperAgent Worker（v3.2.1）—— 只允许在 fork（分身 VM）。
+ *
+ * 物理隔离由瓮城负责；本插件只恢复 Router 注入的 Ticket、校验 Mandate 边界、
+ * 暴露 Worker 提示词与长任务后台化契约。它不执行命令、不访问网络、不持有母体凭据。
+ */
+import { ROW, SERVICE, detectRole, enabledOf, roleAllowed, safeGet, } from "../kernel.js";
+import { publicTicket } from "../superagent/types.js";
+import { createWorkerGuard, planShellCommand, ticketFromEnv, workerPrompt, } from "../superagent/worker.js";
+export const name = 'dsh-master-superagent-worker';
+export const inject = ['dshMaster'];
+export const ROW_ID = ROW.superagentWorker;
+/**
+ * @param {object} ctx
+ * @param {{enabled?:boolean}} [config]
+ */
+export function apply(ctx, config = {}) {
+    if (!enabledOf(config))
+        return { skipped: true, reason: 'disabled-by-config' };
+    const role = detectRole();
+    if (!roleAllowed(ROW_ID, role)) {
+        try {
+            ctx?.logger?.info?.(`[dsh-master] superagent-worker skipped: role=${role} not in fork`);
+        }
+        catch { /* ignore */ }
+        return { skipped: true, reason: `role-not-allowed:${role}` };
+    }
+    const master = safeGet(ctx, SERVICE.master);
+    if (!master || typeof master.registerSubplugin !== 'function') {
+        return { skipped: true, reason: 'master-core-unavailable' };
+    }
+    const restored = ticketFromEnv();
+    const guard = restored.ok ? createWorkerGuard(restored.ticket) : null;
+    const service = {
+        id: 'superagent-worker',
+        version: '3.2.5',
+        role,
+        ready: restored.ok,
+        reason: restored.ok ? null : restored.reason,
+        ticket: restored.ok ? publicTicket(restored.ticket) : null,
+        prompt: () => (restored.ok ? workerPrompt(restored.ticket) : ''),
+        assertScope: (scope) => (guard ? guard.assertScope(scope) : { ok: false, code: 'worker-no-ticket' }),
+        /** 长任务后台化契约：>5s 的 Shell 命令必须走异步 job。 */
+        planShellCommand: (input) => planShellCommand(input),
+        status() {
+            return {
+                ok: true,
+                id: 'superagent-worker',
+                version: '3.2.5',
+                role,
+                ready: restored.ok,
+                reason: restored.ok ? null : restored.reason,
+                ticket: restored.ok ? publicTicket(restored.ticket) : null,
+                mandateScope: restored.ok ? restored.ticket.mandate.scope : null,
+                longTaskThresholdMs: 5000,
+            };
+        },
+    };
+    try {
+        ctx.effect(() => ctx.provide(SERVICE.superagentWorker, service));
+    }
+    catch { /* fake ctx */ }
+    master.registerSubplugin({
+        id: 'superagent-worker',
+        name: 'dsh-master-superagent-worker',
+        capabilities: ['ticket-context', 'mandate-scope-guard', 'worker-prompt', 'long-task-plan'],
+        description: restored.ok ? 'SuperAgent Worker 已恢复工单（仅 fork）' : 'SuperAgent Worker 待工单（仅 fork）',
+    });
+    return service;
+}