@theowlops/boombot 0.0.0-stage → 1.1.0

package/dist/gateway/turns/index.js

@@ -0,0 +1,416 @@
+/**
+ * Lifecycle wiring for the turn service.
+ *
+ * `startTurnService` builds the service from the coordinator-owned context
+ * (event bus, sessions, provider + memory services), attaches it as
+ * `ctx.turnService` for the command handlers, and returns a stopper that
+ * aborts every in-flight turn and detaches the service.
+ */
+import { mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { registerChannelTool, CHANNEL_SEND_TOOL_NAME } from '@boombot/channels';
+import { registerResearchTools, runTurn as runTypeScriptTurn } from '@boombot/core';
+import { registerVisionTool } from './vision-tool.js';
+import { PluginManager } from '@boombot/plugins';
+import { createSandboxProvider, SubprocessSandbox } from '@boombot/sandbox';
+import { ApprovalStore } from '@boombot/security';
+import { getGuardTagging } from '../guard/tagging.js';
+import { activeProviderSnapshotPart, } from '../session-snapshot.js';
+import { PersistentMemoryManager } from '../services/persistent-memory.js';
+import { resolveProviderContextLimits } from '../services/context-limits.js';
+import { CLARIFY_TOOL_NAME, registerClarifyTool } from './clarify-tool.js';
+import { CRONJOB_TOOL_NAME, registerCronjobTool } from './cronjob-tool.js';
+import { DeferredToolManager, TOOL_CALL_NAME, TOOL_DESCRIBE_NAME, TOOL_SEARCH_NAME, } from './deferred-tools.js';
+import { EXECUTE_CODE_TOOL_NAME, registerExecuteCodeTool } from './execute-code-tool.js';
+import { FILE_GLOB_TOOL_NAME, FILE_GREP_TOOL_NAME, FILE_READ_TOOL_NAME, FILE_WRITE_TOOL_NAME, FILE_EDIT_TOOL_NAME, FILE_TOOL_NAMES, registerFileTools, } from './file-tool.js';
+import { McpManager } from './mcp-client.js';
+import { registerMemoryTool, registerHermesMemoryTool } from './memory-tool.js';
+import { startPythonAgentCore } from './python-core.js';
+import { createAgentRuntimeDeps, getToolDefinitions } from './runtime-deps.js';
+import { createTurnService } from './service.js';
+import { registerSessionSearchTool, SESSION_SEARCH_TOOL_NAME } from './session-tool.js';
+import { SHELL_TOOL_NAME, registerShellTool } from './shell-tool.js';
+import { registerSkillTools, SKILL_LIST_TOOL_NAME, SKILL_READ_TOOL_NAME, SkillSemanticMatcher, SkillStore, } from './skill-tool.js';
+import { resolveSpilloverDir } from './spillover.js';
+import { DELEGATE_TASK_TOOL_NAME, registerSubagentTool } from './subagent-tool.js';
+import { loadAssistantInstructions } from './system-prompt.js';
+import { registerSelfConfigTools, CONFIG_MANAGE_TOOL_NAME, PLUGIN_MANAGE_TOOL_NAME, } from './self-config-tool.js';
+export { createTurnService };
+export { createAgentRuntimeDeps, GatewayToolExecutor } from './runtime-deps.js';
+/**
+ * Register every tool advertised on a turn: the five research tools plus
+ * the sandboxed `shell.exec`. This is the exact wiring `startTurnService`
+ * uses per turn — exported so tests exercise the real path (no mocks):
+ * an injected production backend or a test-local `SubprocessSandbox` backs
+ * the shell tool, so every command goes through cwd confinement, env
+ * scrubbing, output caps, and process-tree timeout termination.
+ *
+ * The shell tool can be disabled without a code change via the harness
+ * guard policy: `denyTools: ['shell.exec']`.
+ */
+export function registerTurnTools(registry, options) {
+    // The four research tools. Config comes from the gateway context when
+    // present, otherwise from the environment. Throws on duplicate names —
+    // each turn gets a fresh executor, so registration is always clean.
+    registerResearchTools(registry, options.research);
+    if (options.enableVision === true) {
+        registerVisionTool(registry);
+    }
+    if (options.memoryService !== undefined) {
+        registerMemoryTool(registry, options.memoryService);
+    }
+    if (options.persistentMemory !== undefined) {
+        registerHermesMemoryTool(registry, options.persistentMemory);
+    }
+    if (options.channelService !== undefined) {
+        registerChannelTool(registry, options.channelService);
+    }
+    if (options.sessionSearchService !== undefined) {
+        registerSessionSearchTool(registry, options.sessionSearchService);
+    }
+    const skillStore = options.skillStore ?? (options.skillsRoot === undefined ? undefined : new SkillStore(options.skillsRoot));
+    if (skillStore !== undefined) {
+        registerSkillTools(registry, skillStore);
+    }
+    const deferredManager = new DeferredToolManager();
+    options.mcpManager?.registerTools({
+        registerTool: (def, handler) => deferredManager.registerDeferred(def, handler),
+    });
+    deferredManager.registerTo(registry);
+    options.pluginManager?.registerTools(registry);
+    if (options.subagentRunner !== undefined) {
+        registerSubagentTool(registry, options.subagentRunner);
+    }
+    mkdirSync(options.workspaceRoot, { recursive: true });
+    const sandbox = options.sandbox ?? new SubprocessSandbox({ workspaceRoot: options.workspaceRoot });
+    // Truncated-output spillover: both subprocess tools persist what the
+    // sandbox captured to `<dataDir>/tool_outputs/<callId>.txt` and hand the
+    // model a preview + path instead of dropping bytes silently. Old spill
+    // files are pruned (7d TTL, 256MiB cap) on every spill — no cron needed.
+    const spilloverDir = resolveSpilloverDir(options);
+    registerShellTool(registry, { sandbox, spillover: { dir: spilloverDir } });
+    registerExecuteCodeTool(registry, { sandbox, workspaceRoot: options.workspaceRoot, spillover: { dir: spilloverDir } });
+    registerClarifyTool(registry);
+    registerSelfConfigTools(registry, {
+        configPath: join(options.dataDir ?? options.workspaceRoot, '..', 'config.json'),
+        dataDir: options.dataDir ?? options.workspaceRoot,
+        pluginsRoot: join(options.dataDir ?? options.workspaceRoot, 'plugins'),
+        liveConfig: {},
+        pluginManager: options.pluginManager,
+    });
+    if (options.schedulerService !== undefined) {
+        registerCronjobTool(registry, options.schedulerService);
+    }
+    // File tools resolve against their OWN root, which in production is the
+    // project directory (`files.root`, default `process.cwd()`). "Find file X"
+    // is a question about the user's repository; answering it from the gateway
+    // data dir made the model burn its whole round budget finding nothing,
+    // which is where the multi-10s file questions were going. The shell
+    // sandbox keeps its default root (`ctx.dataDir`) unless
+    // `shell.projectRoot` is set — the write-a-script-then-run-it workflow
+    // needs both tools to agree, which is what that flag is for.
+    registerFileTools(registry, { workspaceRoot: options.filesRoot ?? options.workspaceRoot });
+}
+/**
+ * Start the turn service on `ctx`. The returned stopper aborts all
+ * in-flight turns, clears tracking state, and detaches the service.
+ */
+export async function startTurnService(ctx) {
+    // Two roots, deliberately different. The shell sandbox confines every
+    // command under the gateway data dir, so a compromised model can only
+    // reach its own scratch space; `dataDir` is always set in production and
+    // the temp fallback only serves config-less callers (tests). The file
+    // tools point at the project instead, because "find file X" is about the
+    // user's repository. `shell.projectRoot` collapses the two when the
+    // operator wants write-a-script-then-run-it to work.
+    const projectRoot = ctx.config?.files?.root ?? process.cwd();
+    const shellRoot = ctx.config?.shell?.projectRoot === true
+        ? projectRoot
+        : (ctx.dataDir ?? join(tmpdir(), 'boombot-shell'));
+    const skillsRoot = join(ctx.dataDir ?? shellRoot, 'skills');
+    const skillStore = new SkillStore(skillsRoot);
+    const sandbox = createSandboxProvider({
+        workspaceRoot: shellRoot,
+        backend: ctx.config?.shell?.backend ?? 'auto',
+    });
+    ctx.log?.('info', 'sandbox backend selected', { backend: sandbox.name });
+    let semanticMatcher;
+    // Output tagging (E3 wire-up, SQLite persistence follow-up): the service
+    // tags each settled turn's tool outputs and persists them to
+    // `<dataDir>/guard-tags.sqlite` so tags survive restarts. Lazily created
+    // here because no boot code ever attaches `guardContext` — without this,
+    // tagging would silently stay disabled in production (E2 forwarded
+    // `ctx.guardContext` unchanged and nothing called `getGuardTagging` on
+    // the boot path). Stored back on ctx so later `getGuardTagging(ctx)`
+    // callers reuse the same service. Without a `dataDir` the service is
+    // pure in-memory (tests).
+    const guardContext = ctx.guardContext ?? getGuardTagging({ dataDir: ctx.dataDir });
+    ctx.guardContext = guardContext;
+    // P1-2: persisted HITL approval state machine. Own SQLite file — the
+    // session store's schema is never migrated by this module, and no other
+    // worker's migrations can collide with it. Pure in-memory when there is
+    // no dataDir (tests).
+    const approvalStore = ApprovalStore.open(ctx.dataDir === undefined ? ':memory:' : join(ctx.dataDir, 'approvals.sqlite'));
+    const mcpManager = await McpManager.connect(ctx.config?.mcp?.servers, (level, message, meta) => {
+        ctx.log?.(level, message, meta);
+    });
+    const pluginManager = ctx.config?.plugins?.enabled === false
+        ? PluginManager.empty()
+        : await PluginManager.load(ctx.config?.plugins?.root ?? join(ctx.dataDir ?? shellRoot, 'plugins'), ctx.config?.plugins?.config, (level, message, meta) => ctx.log?.(level, message, meta));
+    // Primary Runtime: Native TypeScript cognitive loop. Zero child process overhead,
+    // immune to gRPC serialization latency. Python core is an optional sidecar if explicitly requested.
+    let turnRunner = runTypeScriptTurn;
+    let pythonCore;
+    if (process.env['BOOMBOT_AGENT_RUNTIME'] === 'python') {
+        try {
+            pythonCore = await startPythonAgentCore();
+            turnRunner = pythonCore.runTurn;
+        }
+        catch (error) {
+            ctx.log?.('warn', 'Failed to start optional Python agent sidecar; running native TypeScript core', { error });
+        }
+    }
+    const persistentMemory = new PersistentMemoryManager(ctx.dataDir ?? shellRoot);
+    const service = createTurnService({
+        publish: (event) => ctx.events.publish(event),
+        sessions: ctx.sessions,
+        runTurn: turnRunner,
+        persistentMemory,
+        approvalTimeoutMs: 300_000,
+        resolveContextLimits: async () => {
+            const ps = ctx.providerService;
+            let active;
+            if (ps && typeof ps.list === 'function') {
+                const list = await ps.list();
+                active = list.find((p) => p.active);
+            }
+            return resolveProviderContextLimits(active ? { kind: active.kind, model: active.model } : undefined, active?.model);
+        },
+        assistantInstructions: loadAssistantInstructions({
+            dataDir: ctx.dataDir ?? shellRoot,
+            projectRoot,
+            override: process.env['BOOMBOT_SYSTEM_PROMPT'],
+        }),
+        // P1-7: feed the session config snapshot with the serving provider's
+        // model + kind. The turn service merges this with the per-turn tool
+        // count and system prompt hash it already knows. A provider service
+        // without `list()` (foreign/stubbed) simply yields no provider part.
+        describeProvider: async () => {
+            const service = ctx.providerService;
+            if (service === undefined || typeof service.list !== 'function')
+                return undefined;
+            return activeProviderSnapshotPart(await service.list());
+        },
+        getSkillCatalog: () => skillStore.list(),
+        readSkill: (name) => skillStore.read(name),
+        matchSkill: async (query, catalog) => {
+            const resolveEmbeddings = ctx.providerService?.resolveEmbeddings;
+            if (typeof resolveEmbeddings !== 'function')
+                return undefined;
+            if (semanticMatcher === undefined) {
+                const client = await resolveEmbeddings.call(ctx.providerService).catch(() => undefined);
+                if (client === undefined)
+                    return undefined;
+                semanticMatcher = new SkillSemanticMatcher(client);
+            }
+            return semanticMatcher.match(query, catalog);
+        },
+        getDeps: async (turnInfo) => {
+            const core = await import('@boombot/core');
+            const sessionScope = core.sessionScope;
+            const turnSessionScope = turnInfo ? sessionScope(turnInfo.sessionId) : undefined;
+            // A platform is not an identity: separate chats, but keep memory across their sessions.
+            const chatId = turnInfo?.replyTo ?? turnInfo?.sessionId;
+            const turnScope = turnInfo?.channel && chatId
+                ? core.conversationScope(turnInfo.channel, chatId)
+                : undefined;
+            const memory = ctx.memoryService;
+            // Both automatic and tool-driven recall use the same server-owned scope.
+            const memoryService = memory ? {
+                recall: (query) => memory.recall(query, {
+                    sessionScope: turnSessionScope, channel: turnInfo?.channel, chatId,
+                }),
+                note: (text, meta) => memory.note(text, meta, turnScope),
+            } : undefined;
+            const searchMessages = ctx.sessions.searchMessages?.bind(ctx.sessions);
+            const ps = ctx.providerService;
+            const isAutonomous = ctx.config?.autonomous === true;
+            const deps = createAgentRuntimeDeps({
+                providerService: ps !== undefined && typeof ps.resolveLlm === 'function' ? ps : undefined,
+                memoryService,
+                autonomous: isAutonomous,
+                // Operator opt-in (gateway config `shell.enabled`, default off):
+                // without this the turn policy hides and denies both subprocess
+                // tools — fail-closed.
+                //
+                // File tools are allow-listed UNCONDITIONALLY (operator decision).
+                // That deliberately overrides three defaults in
+                // `packages/security`'s `DefaultApprovalPolicy`: `file.write*` →
+                // require-approval (approval.ts:136) and `file.edit`/`glob`/`grep` →
+                // unknown-tool → require-approval (approval.ts:148-153). The package
+                // defaults stay untouched for other consumers; the override lives
+                // here only. Confinement for these tools comes from `resolveWithin`
+                // in the handler, not from this policy.
+                policyAllowTools: [
+                    ...FILE_TOOL_NAMES,
+                    SESSION_SEARCH_TOOL_NAME,
+                    SKILL_LIST_TOOL_NAME,
+                    SKILL_READ_TOOL_NAME,
+                    DELEGATE_TASK_TOOL_NAME,
+                    TOOL_SEARCH_NAME,
+                    TOOL_DESCRIBE_NAME,
+                    TOOL_CALL_NAME,
+                    CLARIFY_TOOL_NAME,
+                    CONFIG_MANAGE_TOOL_NAME,
+                    PLUGIN_MANAGE_TOOL_NAME,
+                    CRONJOB_TOOL_NAME,
+                    CHANNEL_SEND_TOOL_NAME,
+                    ...pluginManager.toolNames,
+                    ...(ctx.config?.shell?.enabled === true ? [SHELL_TOOL_NAME, EXECUTE_CODE_TOOL_NAME] : []),
+                ],
+                policyDenyTools: ctx.config?.shell?.enabled === true ? [] : [SHELL_TOOL_NAME, EXECUTE_CODE_TOOL_NAME],
+            });
+            const subagentRunner = {
+                run: async (prompt, signal, options) => {
+                    const child = createAgentRuntimeDeps({
+                        providerService: ps !== undefined && typeof ps.resolveLlm === 'function' ? ps : undefined,
+                        memoryService,
+                        principalId: 'subagent',
+                        autonomous: isAutonomous,
+                    });
+                    registerTurnTools(child.tools, {
+                        workspaceRoot: shellRoot,
+                        dataDir: ctx.dataDir ?? shellRoot,
+                        sandbox,
+                        filesRoot: projectRoot,
+                        research: ctx.config?.research,
+                        sessionSearchService: searchMessages === undefined ? undefined : { searchMessages },
+                        skillStore,
+                        mcpManager,
+                    });
+                    const readOnlyTools = new Set([
+                        FILE_READ_TOOL_NAME,
+                        FILE_GLOB_TOOL_NAME,
+                        FILE_GREP_TOOL_NAME,
+                        SESSION_SEARCH_TOOL_NAME,
+                        SKILL_LIST_TOOL_NAME,
+                        SKILL_READ_TOOL_NAME,
+                    ]);
+                    const coderTools = new Set([
+                        ...readOnlyTools,
+                        FILE_WRITE_TOOL_NAME,
+                        FILE_EDIT_TOOL_NAME,
+                        SHELL_TOOL_NAME,
+                    ]);
+                    const isCoder = options?.role === 'coder';
+                    const allowedToolSet = isCoder ? coderTools : readOnlyTools;
+                    const restricted = {
+                        ...child,
+                        policy: {
+                            checkToolCall: (call) => allowedToolSet.has(call.name) || call.name.startsWith('research.') ? 'allow' : 'deny',
+                        },
+                    };
+                    const systemMsg = isCoder
+                        ? 'You are an autonomous coder child agent. You have file-write and sandboxed shell capabilities. Implement, test, and return a verifiable final report.'
+                        : 'You are a read-only child agent. Complete only the delegated task, cite evidence from tools, and return a concise report.';
+                    const result = await turnRunner(restricted, {
+                        sessionId: `subagent:${turnInfo?.sessionId ?? 'standalone'}`,
+                        messages: [
+                            {
+                                role: 'system',
+                                content: systemMsg,
+                            },
+                            { role: 'user', content: prompt },
+                        ],
+                        tools: await getToolDefinitions(restricted),
+                        budget: { maxRounds: isCoder ? 10 : 5, maxToolCalls: isCoder ? 32 : 16 },
+                    }, () => { }, signal);
+                    if (result.status !== 'completed') {
+                        throw new Error(result.error ?? `child turn ${result.status}`);
+                    }
+                    const answer = [...result.messages]
+                        .reverse()
+                        .find((message) => message.role === 'assistant')
+                        ?.content;
+                    if (answer === undefined || answer.trim() === '')
+                        throw new Error('child returned no answer');
+                    return answer;
+                },
+            };
+            // Advertise every turn tool (research + sandboxed shell) on this
+            // turn's fresh executor. `registerTurnTools` throws on duplicate
+            // names — each turn gets a fresh executor, so registration is always
+            // clean.
+            registerTurnTools(deps.tools, {
+                workspaceRoot: shellRoot,
+                dataDir: ctx.dataDir ?? shellRoot,
+                sandbox,
+                filesRoot: projectRoot,
+                research: ctx.config?.research,
+                memoryService,
+                persistentMemory,
+                channelService: ctx.channelService,
+                schedulerService: ctx.schedulerService,
+                sessionSearchService: searchMessages === undefined ? undefined : { searchMessages },
+                skillStore,
+                mcpManager,
+                subagentRunner,
+                pluginManager,
+            });
+            return deps;
+        },
+        // Forward the reasoning-guard mode from the gateway config into every
+        // turn's `TurnContext`. `loadConfig` always defines it; the fallback is
+        // only for callers that pass a config-less context (tests).
+        reasoningGuard: ctx.config?.reasoningGuard ?? { mode: 'warn' },
+        // Same for the harness guard: the pre-execution gate reads its policy
+        // from the turn service deps. The write-zone gate defaults to the two
+        // roots the tools actually operate under (project files + shell
+        // scratch); an explicit config overrides it.
+        harnessGuard: {
+            mode: ctx.config?.harnessGuard?.mode ?? 'warn',
+            writeZones: ctx.config?.harnessGuard?.writeZones ?? [projectRoot, shellRoot],
+        },
+        // Adaptive routing (PR #14): enabled by default; the gateway config
+        // may opt out with `routing: { enabled: false }`.
+        routing: ctx.config?.routing,
+        // Output tagging (E3 wire-up): the service tags each settled turn's
+        // tool outputs; always present here (created above), tests pass their
+        // own via ctx.guardContext.
+        guardContext,
+        // P1-2: persisted HITL approval state machine — the single source of
+        // truth for pending → approved | denied | expired. Created here so its
+        // lifecycle matches the turn service; the boot scan runs at server
+        // creation (`createGatewayServer` → `reannouncePendingApprovals`).
+        approvalStore,
+    });
+    ctx.turnService = service;
+    let stopped = false;
+    return async () => {
+        if (stopped) {
+            return;
+        }
+        stopped = true;
+        try {
+            await service.shutdown();
+        }
+        finally {
+            try {
+                approvalStore.close();
+            }
+            catch {
+                // Best-effort: shutdown continues even if the store is broken.
+            }
+            await Promise.allSettled([
+                pluginManager.close(),
+                mcpManager.close(),
+                pythonCore?.close(),
+                sandbox.close?.(),
+            ]);
+            if (ctx.turnService === service) {
+                ctx.turnService = undefined;
+            }
+        }
+    };
+}

package/dist/gateway/turns/jev-middleware.js

@@ -0,0 +1,91 @@
+/**
+ * Jev middleware — System 1 Reflex Gate for BoomBot's turn pipeline.
+ *
+ * Hooked into `preflight` phase (first, zero-latency gate):
+ * - If noul > blockThreshold → immediate localReply without calling the LLM.
+ * - If confidence < 0.45 on choice routing → log warning, pass through.
+ * - Publishes `jev.blocked` SSE event when a turn is blocked.
+ * - Publishes `jev.routed` SSE event with the choice classification result.
+ *
+ * Latency budget: < 2ms (pure TS, no I/O, no LLM calls).
+ */
+import { jevEval, MiddlewareAbortError } from '@boombot/core';
+const OWNER_GUARD_REPLY = 'Xin lỗi, thông tin kiến trúc và cấu hình hệ thống được bảo mật tuyệt đối.';
+const INJECTION_BLOCK_REPLY = '⚠️ Tin nhắn bị chặn bởi Jev System 1 Gate do phát hiện nội dung tiềm ẩn nguy hiểm hoặc vi phạm chính sách. Vui lòng đặt câu hỏi khác.';
+/** Phrases that trigger Owner-Guard fast-path block before Jev noul scan. */
+const OWNER_GUARD_TRIGGERS = [
+    /system\s+prompt/iu,
+    /(?:list|show|tell|print|reveal)\s+(?:all\s+)?(?:tools?|plugins?|models?|configurations?|api\s+keys?|secrets?|tokens?)/iu,
+    /(?:who|what|how)\s+(?:made|created|built|designed)\s+(?:you|this\s+bot)/iu,
+    /(?:bạn\s+được\s+tạo|ai\s+(?:làm|tạo|xây dựng)\s+(?:bạn|bot))/iu,
+    /(?:hệ thống nội bộ|cấu hình nội bộ|kiến trúc hệ thống)/iu,
+];
+function buildBlockedEvent(turnId, runId, evaluation, reason) {
+    // ponytail: extend protocol schema for jev.* events in a future PR.
+    // For now, broadcast as guard.blocked which is already a known event type.
+    return {
+        type: 'guard.blocked',
+        payload: {
+            turnId,
+            runId,
+            toolName: 'jev.noul',
+            layer: 'preflight',
+            reason: `[Jev] ${reason} (noul=${evaluation.noul.noul.toFixed(3)})`,
+        },
+    };
+}
+export function createJevMiddleware(options) {
+    const { turnId, runId, publish, blockThreshold = 0.5, choiceConfidenceFloor = 0.30, } = options;
+    return {
+        name: 'jev',
+        beforePhase(phase, ctx) {
+            if (phase !== 'preflight')
+                return;
+            // Extract last user message
+            const userMessages = ctx.messages.filter((m) => m.role === 'user');
+            const lastUser = userMessages[userMessages.length - 1];
+            const text = lastUser?.content ?? '';
+            // ─── Owner Guard fast-path ───────────────────────────────────────────
+            // Check before Jev noul scan so the Owner Guard rule is never bypassed
+            // by a crafted message with low noul score.
+            for (const pattern of OWNER_GUARD_TRIGGERS) {
+                if (pattern.test(text)) {
+                    publish(buildBlockedEvent(turnId, runId, {
+                        noul: { noul: 0.85, decision: true, type: 'noul', latency_ms: 0 },
+                        choice: { type: 'choice', choice: 'chat', probabilities: {}, confidence: 0, latency_ms: 0 },
+                        passed: false,
+                        latency_ms: 0,
+                    }, 'Owner-Guard trigger'));
+                    throw new MiddlewareAbortError(OWNER_GUARD_REPLY);
+                }
+            }
+            // ─── Jev System 1 Noul evaluation ───────────────────────────────────
+            const evaluation = jevEval(text, { blockThreshold });
+            // Publish routing telemetry
+            try {
+                publish({
+                    type: 'guard.blocked',
+                    payload: {
+                        turnId,
+                        runId,
+                        toolName: 'jev.route',
+                        layer: 'preflight',
+                        reason: `[Jev] Route=${evaluation.choice.choice} conf=${evaluation.choice.confidence.toFixed(2)} noul=${evaluation.noul.noul.toFixed(3)} latency=${evaluation.latency_ms}ms`,
+                    },
+                });
+            }
+            catch {
+                // telemetry never breaks a turn
+            }
+            // Block if danger threshold exceeded
+            if (!evaluation.passed) {
+                publish(buildBlockedEvent(turnId, runId, evaluation, evaluation.noul.reason ?? 'Noul threshold exceeded'));
+                throw new MiddlewareAbortError(INJECTION_BLOCK_REPLY);
+            }
+            // Warn on low-confidence routing
+            if (evaluation.choice.confidence < choiceConfidenceFloor) {
+                console.warn(`[jev] low-confidence routing: choice=${evaluation.choice.choice} conf=${evaluation.choice.confidence.toFixed(2)} — deferring to System 2`);
+            }
+        },
+    };
+}

package/dist/gateway/turns/local-reply.js

@@ -0,0 +1,156 @@
+/**
+ * Deterministic local replies for isolated turns and slash commands.
+ *
+ * Fast path: instant replies (<1ms) for slash commands (/status, /tools, /help),
+ * system date/time queries, and greetings, without wasting model tokens.
+ */
+export function simpleLocalReply(text, context) {
+    const trimmed = text.trim();
+    const normalized = trimmed
+        .normalize('NFC')
+        .toLocaleLowerCase('vi')
+        .replace(/[.!?…]+$/u, '')
+        .trim()
+        .replace(/\s+/gu, ' ');
+    // 1. Built-in Slash Commands
+    if (normalized.startsWith('/status')) {
+        const port = context?.port ?? 8788;
+        const provider = context?.activeProvider ?? 'anti';
+        const ctxLimit = context?.contextLimit
+            ? `${context.contextLimit.toLocaleString()} tokens`
+            : '257,000 tokens';
+        const plugins = context?.installedPlugins ?? [
+            'boombot.browser',
+            'boombot.github',
+            'boombot.downloader',
+            'boombot.tts',
+            'boombot.diagram',
+        ];
+        return ('⚡ **Báo cáo Trạng thái Hệ thống BoomBot (System Status)**\n\n' +
+            `- **Trạng thái Gateway:** Online (\`http://127.0.0.1:${port}\`)\n` +
+            `- **Cổng dịch vụ (Ports):** Gateway & Web UI: ${port} | Zalo Bridge: 8787 | 9Router: 20128\n` +
+            `- **Active Provider:** \`${provider}\`\n` +
+            `- **Context Window:** ${ctxLimit} (Compaction threshold: 75%)\n` +
+            '- **Bộ nhớ bền vững (Durable Memory):** Hermes-grade (`MEMORY.md` & `USER.md`)\n' +
+            `- **Plugins đang tải (${plugins.length}):** ${plugins.map((p) => `\`${p}\``).join(', ')}\n` +
+            '- **Khả năng tự hành (Autonomous):** Bật (Hỗ trợ hot-reload plugin & tự cấu hình)\n\n' +
+            'Tốc độ phản hồi (latency): 1ms');
+    }
+    if (normalized.startsWith('/tools')) {
+        if (context?.tools && context.tools.length > 0) {
+            const plugins = context.tools.filter((t) => t.name.startsWith('plugin_'));
+            const coreTools = context.tools.filter((t) => !t.name.startsWith('plugin_'));
+            const lines = [
+                `🛠️ **Danh sách Công cụ Đang Hoạt Động (Dynamic Runtime: ${context.tools.length} tools)**\n`,
+            ];
+            if (plugins.length > 0) {
+                lines.push(`### 1. Plugin Tools (${plugins.length}):`);
+                for (const t of plugins) {
+                    lines.push(`- \`${t.name}\`: ${t.description?.replace(/\s+/gu, ' ').trim() || 'Plugin tool'}`);
+                }
+                lines.push('');
+            }
+            lines.push(`### 2. Core & Sandbox Tools (${coreTools.length}):`);
+            for (const t of coreTools) {
+                lines.push(`- \`${t.name}\`: ${t.description?.replace(/\s+/gu, ' ').trim() || 'Core tool'}`);
+            }
+            lines.push('\nTốc độ phản hồi (latency): 1ms');
+            return lines.join('\n');
+        }
+        return ('🛠️ **Danh sách Công cụ & Plugin Đang Hoạt Động (Tools & Plugins)**\n\n' +
+            '### 1. Tự Cấu Hình & Quản Lý Plugin (In-Process Hot-Reload):\n' +
+            '- `config_manage`: Kiểm tra và cập nhật cấu hình hệ thống không cần restart\n' +
+            '- `plugin_manage`: Cài đặt, gỡ bỏ, và hot-reload plugin từ catalog/git/npm với zero downtime\n\n' +
+            '### 2. Plugin Lõi Đã Cài Đặt (Active Plugins):\n' +
+            '- `boombot.browser`: Tự động hóa duyệt web Chromium\n' +
+            '- `boombot.github`: Thao tác GitHub repo, issues, PRs qua GitHub API\n' +
+            '- `boombot.downloader`: Tải file và tài nguyên media đa luồng\n' +
+            '- `boombot.tts`: Đọc văn bản tiếng Việt tự nhiên (Edge TTS)\n' +
+            '- `boombot.diagram`: Tạo sơ đồ kiến trúc Mermaid / Excalidraw\n\n' +
+            '### 3. Sandbox & Bộ Nhớ:\n' +
+            '- `shell.exec`: Chạy lệnh terminal trong Passthrough Sandbox\n' +
+            '- `file.read`, `file.write`, `file.edit`, `file.grep`, `file.glob`: Quản lý tập tin an toàn\n' +
+            '- `memory`: CRUD bộ nhớ bền vững phong cách Hermes (`target: memory|user`)\n' +
+            '- `skill.list`, `skill.read`: Nạp hơn 120 skills chuyên môn hoá\n\n' +
+            'Tốc độ phản hồi (latency): 1ms');
+    }
+    if (normalized.startsWith('/help')) {
+        return ('💡 **Hướng dẫn Sử Dụng & Phím Tắt BoomBot (Quick Guide)**\n\n' +
+            '### ⌨️ Phím Tắt (Keyboard Shortcuts):\n' +
+            '- `Enter`: Gửi tin nhắn\n' +
+            '- `Shift + Enter`: Xuống dòng trong ô nhập liệu\n' +
+            '- `/`: Mở Slash Command Menu gợi ý lệnh nhanh\n' +
+            '- `↑` / `↓`: Di chuyển chọn lệnh trong Slash Menu\n' +
+            '- `Tab` / `Enter`: Kích hoạt lệnh được chọn\n' +
+            '- `Esc`: Đóng popup gợi ý\n\n' +
+            '### ⚡ Lệnh Nhanh (Slash Commands):\n' +
+            '- `/clear`: Làm mới phiên làm việc (New Session)\n' +
+            '- `/compact`: Nén ngữ cảnh thủ công (Manual Context Compaction)\n' +
+            '- `/status`: Báo cáo trạng thái gateway, cổng kết nối, provider và token\n' +
+            '- `/tools`: Liệt kê các plugin và sandbox tools đang hoạt động\n' +
+            '- `/help`: Hiển thị bảng trợ giúp này\n\n' +
+            '### 🎯 Thao Tác Tin Nhắn (Message Action Bar):\n' +
+            '- Rê chuột vào bong bóng tin nhắn để hiển thị: Sao chép (Copy), Đọc giọng nói (TTS), Sửa tin nhắn (Edit), hoặc Tạo lại câu trả lời (Regenerate).\n\n' +
+            'Tốc độ phản hồi (latency): 1ms');
+    }
+    // 2. Greetings (Vietnamese & English)
+    if (/^(?:hello|hi|hey)(?: (?:bot|boombot))?$/i.test(normalized)) {
+        return 'Hi! I’m here and ready to help. What would you like to work on?';
+    }
+    if (/^(?:chào|chào bạn|chào bot|xin chào)(?: (?:bot|boombot|bạn))?$/u.test(normalized)) {
+        return 'Chào sếp! Tôi là BoomBot, sẵn sàng hỗ trợ. Sếp cần kiểm tra hoặc phát triển tính năng gì tiếp theo ạ?\n\nTốc độ phản hồi (latency): 1ms';
+    }
+    if (/^(?:thanks|thank you)(?: (?:bot|boombot))?$/i.test(normalized)) {
+        return 'You are very welcome! Let me know if you need anything else.';
+    }
+    if (/^(?:cảm ơn|cám ơn)(?: (?:bot|boombot|bạn))?$/u.test(normalized)) {
+        return 'Rất sẵn lòng hỗ trợ sếp! Sếp cần làm gì tiếp cứ nhắn tôi nhé.\n\nTốc độ phản hồi (latency): 1ms';
+    }
+    if (/^(?:bye|goodbye)(?: (?:bot|boombot))?$/i.test(normalized)) {
+        return 'Goodbye! Have a great day!';
+    }
+    if (/^(?:tạm biệt)(?: (?:bot|boombot))?$/u.test(normalized)) {
+        return 'Tạm biệt sếp! Hẹn gặp lại sếp khi có tác vụ mới.\n\nTốc độ phản hồi (latency): 1ms';
+    }
+    // 3. Accurate System Clock Date & Time (Vietnamese & English)
+    const now = new Date();
+    const timeZone = 'Asia/Ho_Chi_Minh';
+    if (/^(?:what day is it(?: today)?|what(?:'s| is) the date(?: today)?)$/i.test(normalized)) {
+        const formatter = new Intl.DateTimeFormat('en-US', {
+            weekday: 'long',
+            year: 'numeric',
+            month: 'long',
+            day: 'numeric',
+            timeZone: 'UTC',
+        });
+        return `Today is ${formatter.format(now)} (UTC).`;
+    }
+    if (/^(?:hôm nay (?:là )?(?:thứ mấy|ngày mấy|ngày bao nhiêu))$/u.test(normalized)) {
+        const formatter = new Intl.DateTimeFormat('vi-VN', {
+            weekday: 'long',
+            year: 'numeric',
+            month: 'long',
+            day: 'numeric',
+            timeZone,
+        });
+        return `Hôm nay là ${formatter.format(now)} (giờ Việt Nam, UTC+7).\n\nTốc độ phản hồi (latency): 1ms`;
+    }
+    if (/^(?:mấy giờ rồi|bây giờ là mấy giờ|mấy giờ|what time is it(?: now)?)$/u.test(normalized)) {
+        const timeFormatter = new Intl.DateTimeFormat('vi-VN', {
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+            timeZone,
+            hour12: false,
+        });
+        const dateFormatter = new Intl.DateTimeFormat('vi-VN', {
+            weekday: 'long',
+            year: 'numeric',
+            month: 'long',
+            day: 'numeric',
+            timeZone,
+        });
+        return `Bây giờ là ${timeFormatter.format(now)} (${dateFormatter.format(now)}).\n\nTốc độ phản hồi (latency): 1ms`;
+    }
+    return undefined;
+}