@jack200714/mafw 4.8.0 → 4.10.2

package/gateway/dist/routes/plugins.js

@@ -51,7 +51,10 @@ async function guarded(res, fn) {
     }
 }
 async function handlePluginsList(_req, res, deps) {
-    await guarded(res, async () => ({ plugins: (0, hub_1.listPlugins)(deps.hub) }));
+    await guarded(res, async () => ({
+        plugins: (0, hub_1.listPlugins)(deps.hub),
+        packages: deps.hub.getPackages?.() ?? [],
+    }));
 }
 async function handlePluginsInstall(req, res, deps) {
     await guarded(res, async () => {

package/gateway/dist/routes/registry.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * P4-A 声明式路由注册表（Shadow Registry 架构）。
+ *
+ * RouteDef 是 gateway HTTP 端点的声明式描述。Phase 2"shadow 登记"模式下 catalog
+ * 只贡献 OpenAPI spec（`toOpenApiPaths()` → emit-openapi 脚本），不参与 dispatch；
+ * Phase 3 逐步给 def 挂 handler 并接线 index.ts 主循环，路由器行为由本文件单测锁定。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RouteRegistry = void 0;
+exports.toOpenApiPath = toOpenApiPath;
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+/** ':param' 形式 → OpenAPI '{param}' 形式。 */
+function toOpenApiPath(path) {
+    return path.replace(/:([A-Za-z0-9_]+)/g, '{$1}');
+}
+class RouteRegistry {
+    defs = [];
+    operationIds = new Set();
+    compiled = null;
+    register(...defs) {
+        for (const def of defs) {
+            if (!def.path.startsWith('/'))
+                throw new Error(`RouteDef.path must start with '/': ${def.path}`);
+            if (!HTTP_METHODS.includes(def.method))
+                throw new Error(`RouteDef.method invalid: ${def.method}`);
+            if (!def.operationId)
+                throw new Error(`RouteDef.operationId required: ${def.method} ${def.path}`);
+            if (this.operationIds.has(def.operationId)) {
+                throw new Error(`Duplicate operationId: ${def.operationId}`);
+            }
+            this.operationIds.add(def.operationId);
+            this.defs.push(def);
+            this.compiled = null;
+        }
+        return this;
+    }
+    list() {
+        return this.defs;
+    }
+    /**
+     * P5 Wave 迁移：给已 shadow 登记的 operationId 挂真实 handler。
+     * 幂等禁止——重复 attach 抛错（防两个迁移波次互相覆盖）。
+     */
+    attachHandler(operationId, handler) {
+        const def = this.defs.find((d) => d.operationId === operationId);
+        if (!def)
+            throw new Error(`attachHandler: unknown operationId '${operationId}'（catalog 未登记？）`);
+        if (def.handler)
+            throw new Error(`attachHandler: '${operationId}' already has a handler`);
+        def.handler = handler;
+        return this;
+    }
+    /** 已挂 handler 的 operationId 集合（迁移覆盖率测试用）。 */
+    attachedOperationIds() {
+        return new Set(this.defs.filter((d) => d.handler).map((d) => d.operationId));
+    }
+    compile() {
+        if (this.compiled)
+            return this.compiled;
+        this.compiled = this.defs.map((def) => {
+            const segments = def.path.split('/').filter((s) => s.length > 0);
+            const staticSegments = segments.filter((s) => !s.startsWith(':')).length;
+            return { def, segments, staticSegments };
+        });
+        return this.compiled;
+    }
+    /**
+     * 匹配：静态段多的优先（/api/automations/draft 先于 /api/automations/:id），
+     * 同特异度按注册序。pathname 只取 url 的 path 部分（剥 query）。
+     */
+    match(method, url) {
+        const pathname = url.split('?')[0].replace(/\/+$/, '') || '/';
+        const pathnameSegments = pathname.split('/').filter((s) => s.length > 0);
+        const routes = this.compile()
+            .map((r, i) => ({ r, i }))
+            .sort((a, b) => b.r.staticSegments - a.r.staticSegments || a.i - b.i);
+        for (const { r } of routes) {
+            if (r.def.method !== method)
+                continue;
+            if (r.segments.length !== pathnameSegments.length)
+                continue;
+            const params = {};
+            let ok = true;
+            for (let i = 0; i < r.segments.length; i++) {
+                const seg = r.segments[i];
+                if (seg.startsWith(':')) {
+                    params[seg.slice(1)] = decodeURIComponent(pathnameSegments[i]);
+                }
+                else if (seg !== pathnameSegments[i]) {
+                    ok = false;
+                    break;
+                }
+            }
+            if (ok)
+                return { def: r.def, params };
+        }
+        return null;
+    }
+    /** 生成 OpenAPI paths 片段（':param' → '{param}'，同 path 多 method 合并）。 */
+    toOpenApiPaths() {
+        const out = {};
+        for (const def of this.defs) {
+            const key = toOpenApiPath(def.path);
+            const entry = (out[key] ??= {});
+            const op = { operationId: def.operationId };
+            if (def.tags?.length)
+                op.tags = def.tags;
+            if (def.summary)
+                op.summary = def.summary;
+            const params = def.path.split('/').filter((s) => s.startsWith(':')).map((s) => ({
+                name: s.slice(1),
+                in: 'path',
+                required: true,
+                schema: { type: 'string' },
+            }));
+            if (params.length)
+                op.parameters = params;
+            op.responses = { 200: { description: 'OK' } };
+            entry[def.method.toLowerCase()] = op;
+        }
+        return out;
+    }
+}
+exports.RouteRegistry = RouteRegistry;

package/gateway/dist/routes/route-catalog.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * P4-B Shadow Route Catalog —— gateway 全量 HTTP 端点的声明式登记（无 handler）。
+ *
+ * 两个来源：
+ *  - SDK_FACING_ROUTES：机械转录自 packages/gateway-sdk/contract/openapi.json
+ *    （path+method+operationId+tags 与 openapi 逐字一致，'{param}' → ':param'），
+ *    漂移由 gateway-sdk/src/contract.test.ts 与 tests/unit/api-contract.test.ts 双向锁定。
+ *  - NON_SDK_ROUTES：非 SDK 暴露面的补充登记（desktop/TUI/worker/dashboard 专用端点），
+ *    operationId 自拟（ns.action 风格），tags 统一 'internal'。
+ *
+ * 刻意不登记：/mcp（传输端点非 REST）、/api/ws（websocket upgrade）、dashboard SPA
+ * fallback 与静态资源（/index.html、/assets/*、/static/*）、dashboard 委托内部子路由
+ * （/api/memory/{tier}/{id} 等，见 dashboard/api.ts）、/api/events?stream=true（与
+ * /api/events 同路径，不单独登记）。P5 Wave 2 反向审计后补齐：devices/mobile 全家、
+ * automations history、goals loops :n、A2A agent-card、runtime reload、permissions
+ * runtime 代理、legacy singular session delete。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRouteCatalog = buildRouteCatalog;
+/** SDK-facing 端点（openapi.json 全量 94 条 operation，权威转录，勿手改——改请先改 openapi.json 再同步）。 */
+const SDK_FACING_ROUTES = [
+    { method: 'POST', path: '/api/session', operationId: 'session.create', tags: ['session'] },
+    { method: 'GET', path: '/api/sessions', operationId: 'session.list', tags: ['session'] },
+    { method: 'GET', path: '/api/sessions/:id', operationId: 'session.get', tags: ['session'] },
+    { method: 'DELETE', path: '/api/sessions/:id', operationId: 'session.delete', tags: ['session'] },
+    { method: 'PATCH', path: '/api/sessions/:id', operationId: 'session.rename', tags: ['session'] },
+    { method: 'GET', path: '/api/sessions/:id/messages', operationId: 'session.messages', tags: ['session'] },
+    { method: 'GET', path: '/api/sessions/:id/todo', operationId: 'session.todo', tags: ['session'] },
+    { method: 'GET', path: '/api/sessions/:id/children', operationId: 'session.children', tags: ['session'] },
+    { method: 'GET', path: '/api/sessions/:id/trajectory', operationId: 'session.trajectory', tags: ['session'] },
+    { method: 'GET', path: '/api/sessions/:id/token-summary', operationId: 'session.tokenSummary', tags: ['session'] },
+    { method: 'POST', path: '/api/sessions/:id/fork', operationId: 'session.fork', tags: ['session'] },
+    { method: 'POST', path: '/api/sessions/:id/revert', operationId: 'session.revert', tags: ['session'] },
+    { method: 'POST', path: '/api/sessions/:id/unrevert', operationId: 'session.unrevert', tags: ['session'] },
+    { method: 'POST', path: '/api/session/:id/abort', operationId: 'session.abort', tags: ['session'] },
+    { method: 'POST', path: '/api/session/:id/summarize', operationId: 'session.summarize', tags: ['session'] },
+    { method: 'POST', path: '/api/session/:id/prompt', operationId: 'session.prompt', tags: ['session'] },
+    { method: 'POST', path: '/api/session/:id/promptAsync', operationId: 'session.promptAsync', tags: ['session'] },
+    { method: 'POST', path: '/api/session/:id/command', operationId: 'session.command', tags: ['session'] },
+    { method: 'GET', path: '/api/usage', operationId: 'session.usage', tags: ['session'] },
+    { method: 'GET', path: '/api/usage/summary', operationId: 'session.usageSummary', tags: ['session'] },
+    { method: 'GET', path: '/api/usage/plugins', operationId: 'session.usagePluginsList', tags: ['session'] },
+    { method: 'POST', path: '/api/usage/plugins/reload', operationId: 'session.usagePluginsReload', tags: ['session'] },
+    { method: 'POST', path: '/api/usage/plugins/create', operationId: 'session.usagePluginsCreate', tags: ['session'] },
+    { method: 'GET', path: '/api/usage/plugins/:name/source', operationId: 'session.usagePluginSourceGet', tags: ['session'] },
+    { method: 'PUT', path: '/api/usage/plugins/:name/source', operationId: 'session.usagePluginSourcePut', tags: ['session'] },
+    { method: 'DELETE', path: '/api/usage/plugins/:name', operationId: 'session.usagePluginsDelete', tags: ['session'] },
+    { method: 'POST', path: '/api/usage/plugins/:name/test', operationId: 'session.usagePluginTest', tags: ['session'] },
+    { method: 'GET', path: '/command', operationId: 'command.list', tags: ['command'] },
+    { method: 'GET', path: '/skill', operationId: 'skill.list', tags: ['skill'] },
+    { method: 'POST', path: '/api/mafw-commands/run', operationId: 'mafwCommands.run', tags: ['mafwCommands'] },
+    { method: 'GET', path: '/api/manager/session', operationId: 'manager.session', tags: ['manager'] },
+    { method: 'POST', path: '/api/manager/session/rotate', operationId: 'manager.rotate', tags: ['manager'] },
+    { method: 'GET', path: '/api/projects', operationId: 'project.list', tags: ['project'] },
+    { method: 'GET', path: '/api/projects/current', operationId: 'project.current', tags: ['project'] },
+    { method: 'POST', path: '/register', operationId: 'project.setCurrent', tags: ['project'] },
+    { method: 'GET', path: '/api/events', operationId: 'event.subscribe', tags: ['event'] },
+    { method: 'POST', path: '/api/events', operationId: 'event.publish', tags: ['event'] },
+    { method: 'GET', path: '/api/runtime', operationId: 'runtime.get', tags: ['runtime'] },
+    { method: 'POST', path: '/api/runtime/switch', operationId: 'runtime.switch', tags: ['runtime'] },
+    { method: 'POST', path: '/api/runtime/restart-agent', operationId: 'runtime.restartAgent', tags: ['runtime'] },
+    // runtime.reload（POST /api/runtime/reload）在下方 NON_SDK 补遗块登记（SDK 不调用 → internal）
+    { method: 'GET', path: '/api/plugins', operationId: 'plugins.list', tags: ['plugins'] },
+    { method: 'POST', path: '/api/plugins/install', operationId: 'plugins.install', tags: ['plugins'] },
+    { method: 'POST', path: '/api/plugins/enable', operationId: 'plugins.enable', tags: ['plugins'] },
+    { method: 'POST', path: '/api/plugins/disable', operationId: 'plugins.disable', tags: ['plugins'] },
+    { method: 'POST', path: '/api/plugins/delete', operationId: 'plugins.delete', tags: ['plugins'] },
+    { method: 'GET', path: '/api/config', operationId: 'config.get', tags: ['config'] },
+    { method: 'PUT', path: '/api/config', operationId: 'config.set', tags: ['config'] },
+    { method: 'GET', path: '/api/opencode-config', operationId: 'opencodeConfig.get', tags: ['opencodeConfig'] },
+    { method: 'PATCH', path: '/api/opencode-config', operationId: 'opencodeConfig.update', tags: ['opencodeConfig'] },
+    { method: 'GET', path: '/api/goals', operationId: 'goals.list', tags: ['goals'] },
+    { method: 'GET', path: '/api/goals/:id', operationId: 'goals.get', tags: ['goals'] },
+    { method: 'GET', path: '/api/goals/:id/sessions', operationId: 'goals.sessions', tags: ['goals'] },
+    { method: 'POST', path: '/api/goals/:goalId/questions/:questionId/respond', operationId: 'goals.respondQuestion', tags: ['goals'] },
+    { method: 'POST', path: '/api/work/:goalId/validate', operationId: 'goals.validate', tags: ['goals'] },
+    { method: 'POST', path: '/api/goals/control', operationId: 'goals.control', tags: ['goals'] },
+    { method: 'GET', path: '/api/memory/search', operationId: 'memory.search', tags: ['memory'] },
+    { method: 'GET', path: '/api/memory/merged-search', operationId: 'memory.mergedSearch', tags: ['memory'] },
+    { method: 'GET', path: '/api/memory/energy-distribution', operationId: 'memory.getEnergyDistribution', tags: ['memory'] },
+    { method: 'GET', path: '/api/l5/axioms', operationId: 'memory.getL5Axioms', tags: ['memory'] },
+    { method: 'DELETE', path: '/api/memory/:id', operationId: 'memory.delete', tags: ['memory'] },
+    { method: 'GET', path: '/api/memory/sticky', operationId: 'memory.listSticky', tags: ['memory'] },
+    { method: 'POST', path: '/api/memory/pin', operationId: 'memory.setSticky', tags: ['memory'] },
+    { method: 'GET', path: '/api/memory/embedding-config', operationId: 'embedding.get', tags: ['embedding'] },
+    { method: 'POST', path: '/api/memory/embedding-config', operationId: 'embedding.update', tags: ['embedding'] },
+    { method: 'GET', path: '/api/approvals', operationId: 'approvals.list', tags: ['approvals'] },
+    { method: 'POST', path: '/api/approvals/:id/respond', operationId: 'approvals.respond', tags: ['approvals'] },
+    { method: 'GET', path: '/api/triage', operationId: 'triage.list', tags: ['triage'] },
+    { method: 'POST', path: '/api/triage/:id/dismiss', operationId: 'triage.dismiss', tags: ['triage'] },
+    { method: 'POST', path: '/api/triage/:id/confirm', operationId: 'triage.confirm', tags: ['triage'] },
+    { method: 'POST', path: '/api/triage/:id/reject', operationId: 'triage.reject', tags: ['triage'] },
+    { method: 'POST', path: '/api/triage/:id/propose', operationId: 'triage.propose', tags: ['triage'] },
+    { method: 'GET', path: '/api/questions', operationId: 'questions.list', tags: ['questions'] },
+    { method: 'POST', path: '/api/questions/:id/reply', operationId: 'questions.reply', tags: ['questions'] },
+    { method: 'POST', path: '/api/questions/:id/reject', operationId: 'questions.reject', tags: ['questions'] },
+    { method: 'GET', path: '/api/permissions', operationId: 'permissions.list', tags: ['permissions'] },
+    { method: 'POST', path: '/api/permissions/:id/reply', operationId: 'permissions.reply', tags: ['permissions'] },
+    { method: 'POST', path: '/api/chat', operationId: 'chat.send', tags: ['chat'] },
+    { method: 'POST', path: '/api/chat/enriched', operationId: 'chat.sendEnriched', tags: ['chat'] },
+    { method: 'GET', path: '/api/media/plugins', operationId: 'media.plugins', tags: ['media'] },
+    { method: 'POST', path: '/api/media/switch', operationId: 'media.switch', tags: ['media'] },
+    { method: 'POST', path: '/api/media/upload', operationId: 'media.upload', tags: ['media'] },
+    { method: 'POST', path: '/api/media/upload-and-create', operationId: 'media.uploadAndCreate', tags: ['media'] },
+    { method: 'POST', path: '/a2a', operationId: 'media.createTask', tags: ['media'] },
+    { method: 'GET', path: '/a2a/artifacts/:id', operationId: 'media.artifact', tags: ['media'] },
+    { method: 'POST', path: '/api/tts', operationId: 'tts.speak', tags: ['tts'] },
+    { method: 'GET', path: '/api/tts/voices', operationId: 'tts.voices', tags: ['tts'] },
+    { method: 'POST', path: '/api/tts/stream', operationId: 'tts.speakStream', tags: ['tts'] },
+    { method: 'GET', path: '/api/provider', operationId: 'providers.list', tags: ['providers'] },
+    { method: 'GET', path: '/api/agents', operationId: 'agents.list', tags: ['agents'] },
+    { method: 'GET', path: '/api/model-config', operationId: 'models.get', tags: ['models'] },
+    { method: 'POST', path: '/api/model-config', operationId: 'models.update', tags: ['models'] },
+    { method: 'GET', path: '/api/automations', operationId: 'automations.list', tags: ['automations'] },
+    { method: 'PUT', path: '/api/automations/:id', operationId: 'automations.toggle', tags: ['automations'] },
+    { method: 'POST', path: '/api/automations/draft', operationId: 'automations.draft', tags: ['automations'] },
+];
+/** 非 SDK 端点补充登记（desktop/TUI/worker/dashboard 专用面），operationId 自拟，tags 'internal'。 */
+const NON_SDK_ROUTES = [
+    // Python 内核（§5.17）
+    { method: 'POST', path: '/api/python/execute', operationId: 'python.execute', tags: ['internal'] },
+    { method: 'POST', path: '/api/python/restart', operationId: 'python.restart', tags: ['internal'] },
+    { method: 'GET', path: '/api/python/status', operationId: 'python.status', tags: ['internal'] },
+    // 观察捕获 / 边界 recall / pinned 披露层（§5.11/§5.13）
+    { method: 'POST', path: '/api/obs/capture', operationId: 'obs.capture', tags: ['internal'] },
+    { method: 'GET', path: '/api/recall/context', operationId: 'recall.context', tags: ['internal'] },
+    { method: 'GET', path: '/api/recall/pinned', operationId: 'recall.pinned', tags: ['internal'] },
+    // 记忆补充（memory.mergedSearch 已在 SDK-facing，不重复）
+    { method: 'POST', path: '/api/memory/add', operationId: 'memory.add', tags: ['internal'] },
+    { method: 'GET', path: '/api/memory/get', operationId: 'memory.get', tags: ['internal'] },
+    { method: 'GET', path: '/api/memory/stats', operationId: 'memory.stats', tags: ['internal'] },
+    { method: 'POST', path: '/api/memory/embeddings/backfill', operationId: 'memory.embeddingsBackfill', tags: ['internal'] },
+    { method: 'GET', path: '/api/l5/heuristics', operationId: 'memory.getL5Heuristics', tags: ['internal'] },
+    // Goal / 编排（§5.20）
+    { method: 'GET', path: '/api/goals/:id/loops', operationId: 'goals.loops', tags: ['internal'] },
+    { method: 'POST', path: '/api/work/:goalId/complete', operationId: 'goals.complete', tags: ['internal'] },
+    { method: 'POST', path: '/control', operationId: 'goals.controlLegacy', summary: 'MCP 兼容别名，与 /api/goals/control 同 handler', tags: ['internal'] },
+    { method: 'GET', path: '/api/orchestration/outcomes', operationId: 'orchestration.outcomes', tags: ['internal'] },
+    // 媒体补充（media.upload / uploadAndCreate / switch / plugins GET / a2a / artifacts GET 已在 SDK-facing）
+    { method: 'POST', path: '/api/media/create-task', operationId: 'media.createTaskApi', tags: ['internal'] },
+    { method: 'GET', path: '/api/media/resolve-task/:id', operationId: 'media.resolveTask', tags: ['internal'] },
+    { method: 'POST', path: '/api/media/analyze-audio', operationId: 'media.analyzeAudio', tags: ['internal'] },
+    { method: 'POST', path: '/api/media/plugins/reload', operationId: 'media.pluginsReload', tags: ['internal'] },
+    // 用量 dashboard / 健康
+    { method: 'GET', path: '/api/stats', operationId: 'dashboard.stats', tags: ['internal'] },
+    { method: 'GET', path: '/api/costs/:window', operationId: 'dashboard.costs', tags: ['internal'] },
+    { method: 'GET', path: '/api/alignment', operationId: 'dashboard.alignment', tags: ['internal'] },
+    { method: 'POST', path: '/api/feedback', operationId: 'feedback.record', tags: ['internal'] },
+    { method: 'GET', path: '/api/user-answers/:id', operationId: 'dashboard.userAnswer', tags: ['internal'] },
+    { method: 'GET', path: '/api/sessions/:id/metrics', operationId: 'session.metrics', tags: ['internal'] },
+    { method: 'GET', path: '/api/health', operationId: 'health.check', tags: ['internal'] },
+    // Gateway 控制（goal PAUSE/ABORT 等控制面）
+    { method: 'POST', path: '/api/gateway/pause', operationId: 'gateway.pause', tags: ['internal'] },
+    { method: 'POST', path: '/api/gateway/resume', operationId: 'gateway.resume', tags: ['internal'] },
+    { method: 'POST', path: '/api/gateway/cancel', operationId: 'gateway.cancel', tags: ['internal'] },
+    { method: 'POST', path: '/api/gateway/checkpoint', operationId: 'gateway.checkpoint', tags: ['internal'] },
+    { method: 'POST', path: '/api/gateway/rollback', operationId: 'gateway.rollback', tags: ['internal'] },
+    // 移动端（P5 Wave 2 反向审计后全量登记）
+    { method: 'POST', path: '/api/mobile/media/tasks/:id/ask', operationId: 'mobile.mediaTaskAsk', tags: ['internal'] },
+    { method: 'POST', path: '/api/mobile/media/tasks', operationId: 'mobile.mediaTaskUpload', tags: ['internal'] },
+    { method: 'GET', path: '/api/mobile/tts/artifacts/:id', operationId: 'mobile.ttsArtifact', tags: ['internal'] },
+    { method: 'GET', path: '/api/mobile/devices', operationId: 'mobile.devicesList', tags: ['internal'] },
+    { method: 'DELETE', path: '/api/mobile/devices/:id', operationId: 'mobile.devicesDelete', tags: ['internal'] },
+    { method: 'POST', path: '/api/mobile/devices/register', operationId: 'mobile.devicesRegister', tags: ['internal'] },
+    { method: 'GET', path: '/api/mobile/pairing-code', operationId: 'mobile.pairingCode', tags: ['internal'] },
+    { method: 'POST', path: '/api/mobile/pairing/verify', operationId: 'mobile.pairingVerify', tags: ['internal'] },
+    // 设备注册（mobile 的 legacy 别名族）
+    { method: 'POST', path: '/api/devices', operationId: 'devices.register', tags: ['internal'] },
+    { method: 'GET', path: '/api/devices', operationId: 'devices.list', tags: ['internal'] },
+    { method: 'DELETE', path: '/api/devices/:id', operationId: 'devices.delete', tags: ['internal'] },
+    // P5 Wave 2 反向审计补遗
+    { method: 'GET', path: '/.well-known/agent-card.json', operationId: 'a2a.agentCard', tags: ['internal'] },
+    { method: 'GET', path: '/api/automations/:id/history', operationId: 'automations.history', tags: ['internal'] },
+    { method: 'GET', path: '/api/goals/:id/loops/:n', operationId: 'goals.loopsAt', tags: ['internal'] },
+    { method: 'POST', path: '/api/runtime/reload', operationId: 'runtime.reload', tags: ['internal'] },
+    { method: 'POST', path: '/api/sessions/:sid/permissions/:rid', operationId: 'permissions.replyRuntime', tags: ['internal'] },
+    { method: 'DELETE', path: '/api/session/:id', operationId: 'session.deleteLegacy', tags: ['internal'] },
+    // Eval / LLM 压缩
+    { method: 'POST', path: '/api/eval/chat/completions', operationId: 'eval.chatCompletions', tags: ['internal'] },
+    { method: 'POST', path: '/api/llm/compress', operationId: 'llm.compress', tags: ['internal'] },
+    // 跨 worktree 记忆融合（§5.3）
+    { method: 'POST', path: '/api/merge-memory', operationId: 'memory.merge', tags: ['internal'] },
+    // 根健康检查（dashboard/桌面探测用）
+    { method: 'GET', path: '/health', operationId: 'health.root', tags: ['internal'] },
+];
+/** gateway 全量 HTTP 端点 shadow 登记（无 handler；Phase 3 逐条挂 handler 前不参与 dispatch）。
+ *  每次调用返回全新 def 对象（浅拷贝）——attachHandler 会原地改写 def.handler，
+ *  共享模块级常量会让第二次 build 的 registry 带上一次的 handler（测试已抓过）。 */
+function buildRouteCatalog() {
+    return [...SDK_FACING_ROUTES, ...NON_SDK_ROUTES].map((d) => ({ ...d }));
+}

package/gateway/dist/routes/triage-dismiss.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleTriageDismiss = handleTriageDismiss;
+function json(res, status, payload) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(payload));
+}
+/**
+ * POST /api/triage/:id/dismiss — 忽略 triage 项（SDK triage.dismiss 的服务端落地）。
+ * 语义 = reject（state REJECTED），仅账本 reason 区分（triage_dismissed），
+ * 供 SDK contract 对齐：此前该路由不存在，调用会落入 dashboard 兜底返回 HTML。
+ * 返回 handled=false 表示路径不匹配，交给后续路由。
+ */
+async function handleTriageDismiss(req, res, url, deps) {
+    const m = url.match(/^\/api\/triage\/([^/]+)\/dismiss(?:\?|$)/);
+    if (!m || req.method !== 'POST')
+        return false;
+    const triageId = decodeURIComponent(m[1]);
+    const ok = deps.rejectTriage(triageId);
+    try {
+        deps.appendLedger?.({
+            timestamp: new Date().toISOString(),
+            event: 'AUTOMATION_TRIGGERED',
+            source: 'user',
+            reason: 'triage_dismissed',
+            details: { triageId },
+        });
+    }
+    catch { /* 账本失败不阻塞 */ }
+    json(res, 200, { status: ok ? 'dismissed' : 'not_found' });
+    return true;
+}

package/gateway/dist/routes/waitwhat-command.js

@@ -0,0 +1,43 @@
+"use strict";
+// /waitwhat command (UI-driven, via /api/mafw-commands/run): the user signals
+// "that last reply didn't land" and the agent re-pitches its own last message
+// in simplified language, using the project's CONTEXT.md glossary when one
+// exists. Inspired by mattpocock/skills wait-what (MIT).
+//
+// The re-pitch is prompted INTO THE SAME session so every connected client
+// (desktop / TUI / opencode) sees the answer inline via the event stream.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildWaitwhatPrompt = buildWaitwhatPrompt;
+exports.runWaitwhat = runWaitwhat;
+function buildWaitwhatPrompt(original) {
+    return [
+        '[/waitwhat] 用户没看懂你上一条回复。请把它重述一遍：',
+        '1. 先用一两句补上"我们在做什么、刚才说到哪"的上下文定位；',
+        '2. 然后用简明语言重述：短句、一次一个概念、避免嵌套行话（STE100 简化技术英语的风格）；',
+        '3. 如果项目根目录有 CONTEXT.md，先读它并用其中的项目术语（ubiquitous language）来表达；',
+        '4. 只是重述，不要新增内容、不引入新话题。',
+        '',
+        '—— 需要重述的上一条回复原文 ——',
+        original,
+    ].join('\n');
+}
+/**
+ * Re-pitch the last assistant message of the session. Returns ok:false with
+ * an error string (without prompting) when there is nothing to re-pitch.
+ */
+async function runWaitwhat(sessionID, deps) {
+    const messages = await deps.listMessages(sessionID);
+    const lastAssistant = [...(Array.isArray(messages) ? messages : [])]
+        .reverse()
+        .find((m) => m?.info?.role === 'assistant');
+    const original = (lastAssistant?.parts || [])
+        .filter((p) => p?.type === 'text' && typeof p?.text === 'string')
+        .map((p) => p.text)
+        .join('\n')
+        .trim();
+    if (!original) {
+        return { ok: false, error: 'no assistant message to re-pitch' };
+    }
+    await deps.promptAsync(sessionID, buildWaitwhatPrompt(original));
+    return { ok: true };
+}

package/gateway/dist/routes/wave1-handlers.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachWave1Handlers = attachWave1Handlers;
+const config_1 = require("../config");
+const goal_sessions_1 = require("./goal-sessions");
+const triage_dismiss_1 = require("./triage-dismiss");
+const manager_rotate_1 = require("./manager-rotate");
+const embedding_config_1 = require("./embedding-config");
+const model_config_1 = require("./model-config");
+const session_branch_1 = require("./session-branch");
+const session_mutations_1 = require("./session-mutations");
+const session_summarize_1 = require("./session-summarize");
+const event_publish_1 = require("./event-publish");
+const media_switch_1 = require("./media-switch");
+const usage_plugins_1 = require("./usage-plugins");
+/** 绑定 Wave 1 的 22 条路由。index.ts 在 createServer 之前调用一次。 */
+function attachWave1Handlers(registry, gw) {
+    const H = (fn) => fn;
+    registry.attachHandler('goals.sessions', H(async (req, res, params) => (0, goal_sessions_1.handleGoalSessions)(req, res, req.url || '', {
+        listGoalSessions: (goalId) => gw.getGatewayDb().listGoalSessions(goalId),
+        getSession: (sessionID) => gw.opencodeClient?.session.get({ sessionID }).catch(() => null),
+    })));
+    registry.attachHandler('triage.dismiss', H(async (req, res, params) => (0, triage_dismiss_1.handleTriageDismiss)(req, res, req.url || '', {
+        rejectTriage: (id) => gw.automationEngine?.rejectTriage(id) ?? false,
+        appendLedger: (entry) => gw.ledger?.append(entry),
+    })));
+    registry.attachHandler('manager.rotate', H(async (req, res) => (0, manager_rotate_1.handleManagerRotate)(req, res, gw.rotateDeps())));
+    registry.attachHandler('embedding.get', H(async (req, res) => (0, embedding_config_1.handleEmbeddingConfigGet)(req, res, gw.embeddingConfigDeps())));
+    registry.attachHandler('embedding.update', H(async (req, res) => (0, embedding_config_1.handleEmbeddingConfigUpdate)(req, res, gw.embeddingConfigDeps())));
+    registry.attachHandler('models.get', H(async (req, res) => (0, model_config_1.handleModelConfigGet)(req, res, gw.modelConfigDeps())));
+    registry.attachHandler('models.update', H(async (req, res) => (0, model_config_1.handleModelConfigUpdate)(req, res, gw.modelConfigDeps())));
+    registry.attachHandler('session.fork', H(async (req, res, params) => (0, session_branch_1.handleSessionBranch)(req, res, req.url || '', { getRuntime: () => gw.opencodeClient })));
+    registry.attachHandler('session.revert', H(async (req, res, params) => (0, session_branch_1.handleSessionBranch)(req, res, req.url || '', { getRuntime: () => gw.opencodeClient })));
+    registry.attachHandler('session.unrevert', H(async (req, res, params) => (0, session_branch_1.handleSessionBranch)(req, res, req.url || '', { getRuntime: () => gw.opencodeClient })));
+    registry.attachHandler('session.delete', H(async (req, res) => (0, session_mutations_1.handleSessionMutations)(req, res, {
+        getCapabilities: () => gw.runtimeCaps,
+        getClient: () => (gw.opencodeClient ?? null),
+    })));
+    registry.attachHandler('session.rename', H(async (req, res) => (0, session_mutations_1.handleSessionMutations)(req, res, {
+        getCapabilities: () => gw.runtimeCaps,
+        getClient: () => (gw.opencodeClient ?? null),
+    })));
+    registry.attachHandler('session.summarize', H(async (req, res) => (0, session_summarize_1.handleSessionSummarize)(req, res, req.url || '', { getRuntime: () => gw.opencodeClient })));
+    registry.attachHandler('event.publish', H(async (req, res) => (0, event_publish_1.handleEventPublish)({ broadcast: (e) => gw.broadcast(e) }, req, res)));
+    registry.attachHandler('media.switch', H(async (req, res) => (0, media_switch_1.handleMediaSwitch)(req, res, {
+        persist: (o) => config_1.config.persistOverrides(o),
+        reloadPlugins: async () => { await gw.mediaPluginLoader?.reload(); },
+        availableEngines: () => (gw.mediaPluginLoader?.getState().map((s) => s.name).filter((n) => !!n) ?? []),
+        currentMedia: () => config_1.config.raw.media,
+    })));
+    const usageDeps = () => gw.usagePluginsDeps();
+    registry.attachHandler('session.usagePluginsList', H(async (req, res) => (0, usage_plugins_1.handleUsagePluginsList)(req, res, usageDeps())));
+    registry.attachHandler('session.usagePluginsReload', H(async (req, res) => {
+        await gw.pluginLoader?.reload();
+        await (0, usage_plugins_1.handleUsagePluginsList)(req, res, usageDeps());
+    }));
+    registry.attachHandler('session.usagePluginsCreate', H(async (req, res) => (0, usage_plugins_1.handleUsagePluginCreate)(req, res, usageDeps())));
+    registry.attachHandler('session.usagePluginSourceGet', H(async (req, res, params) => (0, usage_plugins_1.handleUsagePluginSourceGet)(req, res, usageDeps(), decodeURIComponent(params.name))));
+    registry.attachHandler('session.usagePluginSourcePut', H(async (req, res, params) => (0, usage_plugins_1.handleUsagePluginSourcePut)(req, res, usageDeps(), decodeURIComponent(params.name))));
+    registry.attachHandler('session.usagePluginTest', H(async (req, res, params) => (0, usage_plugins_1.handleUsagePluginTest)(req, res, usageDeps(), decodeURIComponent(params.name))));
+    registry.attachHandler('session.usagePluginsDelete', H(async (req, res, params) => (0, usage_plugins_1.handleUsagePluginDelete)(req, res, usageDeps(), decodeURIComponent(params.name))));
+}

package/gateway/dist/routes/wave2-handlers.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachWave2Handlers = attachWave2Handlers;
+const runtime_switch_1 = require("./runtime-switch");
+const restart_agent_1 = require("./restart-agent");
+const plugins_1 = require("./plugins");
+const hub_1 = require("../plugins/hub");
+const logger_1 = require("../core/utils/logger");
+/** 绑定 Wave 2 的 9 条路由。index.ts 在 createServer 之前调用一次。 */
+function attachWave2Handlers(registry, gw) {
+    const H = (fn) => fn;
+    registry.attachHandler('runtime.get', H(async (req, res) => (0, runtime_switch_1.handleRuntimeGet)(req, res, gw.runtimeDeps())));
+    registry.attachHandler('runtime.switch', H(async (req, res) => {
+        if (gw.runtimeSwitchBlocked()) {
+            res.writeHead(409, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Cannot switch runtime during agent restart' }));
+            return;
+        }
+        gw.beginRuntimeSwitch();
+        try {
+            await (0, runtime_switch_1.handleRuntimeSwitch)(req, res, gw.runtimeDeps());
+        }
+        finally {
+            gw.endRuntimeSwitch();
+        }
+    }));
+    registry.attachHandler('runtime.reload', H(async (req, res) => (0, runtime_switch_1.handleRuntimeReload)(req, res, gw.runtimeDeps())));
+    registry.attachHandler('runtime.restartAgent', H(async (req, res) => (0, restart_agent_1.handleRestartAgent)(req, res, gw.restartAgentDeps())));
+    const withCleanup = async (req, fn) => {
+        try {
+            const cleaned = (0, hub_1.cleanupExamples)(gw.pluginHubDeps().hub);
+            if (cleaned.removed.length)
+                logger_1.log.info(`[PluginsHub] removed stale examples: ${cleaned.removed.length}`);
+            if (cleaned.failed.length)
+                logger_1.log.warn(`[PluginsHub] cleanupExamples failed: ${cleaned.failed.join(', ')}`);
+        }
+        catch (err) {
+            logger_1.log.warn(`[PluginsHub] cleanupExamples error: ${err.message}`);
+        }
+        await fn();
+    };
+    registry.attachHandler('plugins.list', H(async (req, res) => withCleanup(req, () => (0, plugins_1.handlePluginsList)(req, res, gw.pluginHubDeps()))));
+    registry.attachHandler('plugins.install', H(async (req, res) => withCleanup(req, () => (0, plugins_1.handlePluginsInstall)(req, res, gw.pluginHubDeps()))));
+    registry.attachHandler('plugins.enable', H(async (req, res) => withCleanup(req, () => (0, plugins_1.handlePluginsEnable)(req, res, gw.pluginHubDeps()))));
+    registry.attachHandler('plugins.disable', H(async (req, res) => withCleanup(req, () => (0, plugins_1.handlePluginsDisable)(req, res, gw.pluginHubDeps()))));
+    registry.attachHandler('plugins.delete', H(async (req, res) => withCleanup(req, () => (0, plugins_1.handlePluginsDelete)(req, res, gw.pluginHubDeps()))));
+}

package/gateway/dist/runtime/contract.js

@@ -15,7 +15,10 @@ function fullCapabilities() {
         agentProcessApi: true,
         completionApi: true,
         sessionBranchApi: true,
-        turnBudgetApi: true,
+        // opencode 适配器不转发 maxTurns/maxCostUsd（SDK 无对应字段）——预算由
+        // gateway 侧 BudgetGuard 承担；声明 true 会让 attachBudgetGuardForGoal
+        // 跳过挂载，goal 预算在默认 runtime 上完全失效。
+        turnBudgetApi: false,
         questionApi: true,
     };
 }

package/gateway/dist/runtime/event-broadcast.js

@@ -12,6 +12,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.opencodeBroadcast = opencodeBroadcast;
 exports.projectRegisteredEvent = projectRegisteredEvent;
 function opencodeBroadcast(data, internal) {
+    if (typeof data?.type !== 'string' || !data.type) {
+        // 形状守卫（fail-open）：信封照常返回，但给出可定位诊断——畸形事件
+        // 在桌面/TUI 是"静默忽略"，没有这行日志时插件作者无从排查。
+        // eslint-disable-next-line no-console
+        console.error(`[EventBroadcast] malformed opencode_event data: 'type' must be a non-empty string ` +
+            `(got ${JSON.stringify(data?.type)}); payload keys: ${data ? Object.keys(data).join(',') : '(null)'} ` +
+            `— downstream (desktop/TUI) will ignore this event`);
+    }
     return {
         type: 'opencode_event',
         data: {

package/gateway/dist/runtime/loader.js

@@ -54,6 +54,7 @@ class RuntimePluginLoader {
     meta = new Map();
     state = new Map();
     builtins = new Map();
+    packageEntries = new Map();
     constructor(pluginsDir) {
         this.pluginsDir = pluginsDir;
     }
@@ -149,12 +150,24 @@ class RuntimePluginLoader {
             logger_1.log.warn(`[RuntimePluginLoader] ${file} load error: ${err.message}`);
         }
     }
+    /** PluginHost 推送的包贡献。查找顺序：legacy 文件 > 包 > 内置。scan() 不影响。 */
+    setPackageEntries(entries) {
+        this.packageEntries = new Map(entries.map((e) => [e.name, e]));
+    }
     /** 插件不存在或未通过校验时返回 undefined（调用方回退内置 opencode）。文件插件优先于内置。 */
     get(name) {
         const createRuntime = this.factories.get(name);
         const meta = this.meta.get(name);
         if (createRuntime && meta)
             return { createRuntime, ...meta };
+        const pkg = this.packageEntries.get(name);
+        if (pkg) {
+            return {
+                createRuntime: pkg.createRuntime,
+                capabilities: { ...(0, contract_1.minimalCapabilities)(), ...pkg.capabilities },
+                external: pkg.external,
+            };
+        }
         const builtin = this.builtins.get(name);
         if (builtin)
             return { createRuntime: builtin.factory, ...builtin };
@@ -168,16 +181,24 @@ class RuntimePluginLoader {
         for (const [name, b] of this.builtins) {
             this.state.set(`builtin:${name}`, { file: `builtin:${name}`, name, status: 'ok', capabilities: b.capabilities });
         }
+        for (const [name, p] of this.packageEntries) {
+            this.state.set(`package:${name}`, {
+                file: `package:${name}`, name, status: 'ok',
+                capabilities: { ...(0, contract_1.minimalCapabilities)(), ...p.capabilities },
+            });
+        }
         return [...this.state.values()];
     }
 }
 exports.RuntimePluginLoader = RuntimePluginLoader;
-function createRuntimePluginContext(credentials) {
+function createRuntimePluginContext(credentials, extra) {
     return {
         fetch: (url, opts) => fetch(url, { ...opts, signal: opts?.signal ?? AbortSignal.timeout(60000) }),
         log: logger_1.log,
         pluginConfig: (name) => config_1.config.raw?.runtime?.pluginConfig?.[name] ?? {},
         credentials,
+        projectDir: extra?.projectDir,
+        gatewayPort: extra?.gatewayPort,
     };
 }
 const README_CONTENT = `# Runtime Plugins