@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/gateway/turns/service.js

@@ -0,0 +1,820 @@
+/**
+ * Turn service: runs agent-core turns, bridges loop events to
+ * `@boombot/protocol` stream events, persists session messages,
+ * and tracks in-flight turns for cancellation.
+ *
+ * Lifecycle: `submit()` resolves (or creates) the session, persists the
+ * user message, then runs the turn in the background and returns
+ * `{ turnId, sessionId }` immediately — the client follows progress over
+ * SSE (`GET /v1/turns/:turnId/events`). Terminal stream events
+ * (`agent.turn.done` / `agent.turn.error`) are published only after the
+ * turn's new messages have been persisted.
+ *
+ * HITL approvals: the service implements agent-core's `ApprovalPort`
+ * itself and injects it into the turn's runtime deps, so a policy `'ask'`
+ * pauses the turn here instead of being denied. The pause is announced
+ * over SSE as `turn.approval_required`; the client answers with the
+ * `turn.approve` command (`approveTurn`), or the request times out and
+ * the turn ends with an `approval_timeout` error. Each request is
+ * persisted in `@boombot/security`'s `ApprovalStore`
+ * (`pending` → `approved` | `denied` | `expired`) — the single source of
+ * truth for the request lifecycle — so a restart re-announces survivors
+ * instead of failing them silently (P1-2).
+ */
+import { randomUUID } from 'node:crypto';
+import { ApprovalTimeoutError, ContextCompactor } from '@boombot/core';
+import { createPolicy } from '@boombot/security';
+import { hashSystemPrompt } from '../session-snapshot.js';
+import { simpleLocalReply } from './local-reply.js';
+import { createTurnMiddlewares } from './middleware.js';
+import { IntentClassifier, executePlannedTurn } from './routing/index.js';
+import { attachHarnessGuard, getToolDefinitions } from './runtime-deps.js';
+import { DEFAULT_APPROVAL_TIMEOUT_MS, } from './service-types.js';
+import { buildSystemPrompt } from './system-prompt.js';
+import { deriveTitle, lastAssistantText, parseApprovalArgs, selectNamedSkill, settleWithin, unrefTimer, } from './turn-utils.js';
+// Re-exported from ./service-types.js for backward compatibility.
+// Existing importers (`./index.ts`, `session-adapter.ts`, `session-tool.ts`,
+// `../types.ts`, `../handlers/turn.ts`) keep importing from './service.js'.
+export { DEFAULT_APPROVAL_TIMEOUT_MS, } from './service-types.js';
+export function createTurnService(deps) {
+    return new GatewayTurnService(deps);
+}
+class GatewayTurnService {
+    deps;
+    activeTurns = new Map();
+    activeTasks = new Map();
+    /**
+     * Recently settled terminal events, keyed by turnId, so a late SSE
+     * subscriber can replay a terminal event published before it connected.
+     * Bounded: a turn id is unique per process, old entries are evicted.
+     */
+    terminalEvents = new Map();
+    progressEvents = new Map();
+    static MAX_TERMINAL_EVENTS = 200;
+    /** In-flight HITL approvals, keyed by runId. */
+    pendingApprovals = new Map();
+    /** runId → owning turn, so the ApprovalPort can publish SSE with the turnId. */
+    runToTurn = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    getTerminalEvent(turnId) {
+        return this.terminalEvents.get(turnId);
+    }
+    getProgressEvents(turnId) {
+        return this.progressEvents.get(turnId) ?? [];
+    }
+    async submit(input) {
+        const text = input.input.trim();
+        if (text === '') {
+            throw new Error('turn input must be a non-empty string');
+        }
+        // 1. Resolve (or create) the session.
+        let sessionId = input.sessionId;
+        let history;
+        if (sessionId !== undefined) {
+            let session = await this.deps.sessions.getSession(sessionId);
+            if (session === null) {
+                if (input.channel === 'scheduler') {
+                    const title = `[Lịch chạy] ${input.replyTo ? text.slice(0, 30) + '…' : 'Tự động'}`;
+                    const created = await this.deps.sessions.createSession({ id: sessionId, title });
+                    session = created;
+                }
+                else {
+                    throw new Error(`session not found: ${sessionId}`);
+                }
+            }
+            // For scheduler turns: do not carry massive prior tool outputs/history from previous days/hours
+            history = input.channel === 'scheduler' ? [] : session.messages;
+        }
+        else {
+            const created = await this.deps.sessions.createSession({ title: deriveTitle(text) });
+            sessionId = created.id;
+            history = created.messages;
+        }
+        // 2. Persist the user message immediately so history survives turn failures.
+        const userMessage = {
+            role: 'user',
+            content: text,
+            ...(input.images?.length ? { images: input.images } : {}),
+        };
+        // Fresh runtime deps per turn, so provider/memory/plugin changes are picked up live.
+        const runtimeDeps = await this.deps.getDeps({ sessionId, channel: input.channel, replyTo: input.replyTo });
+        const tools = await getToolDefinitions(runtimeDeps);
+        const toolInfos = tools.map((t) => ({ name: t.name, description: t.description }));
+        const providerSnapshot = await this.deps.describeProvider?.().catch(() => undefined);
+        const localReply = simpleLocalReply(text, {
+            tools: toolInfos,
+            activeProvider: providerSnapshot?.model,
+            contextLimit: 257_000,
+            port: 8788,
+        });
+        let skillCatalog;
+        let loadedSkill;
+        if (localReply === undefined && this.deps.getSkillCatalog !== undefined) {
+            try {
+                skillCatalog = await this.deps.getSkillCatalog();
+                const namedSkill = selectNamedSkill(text, skillCatalog);
+                const semanticMatch = namedSkill === undefined
+                    ? await this.deps.matchSkill?.(text, skillCatalog)
+                    : undefined;
+                const selectedSkill = namedSkill ?? semanticMatch?.name;
+                if (selectedSkill !== undefined && this.deps.readSkill !== undefined) {
+                    const skill = await this.deps.readSkill(selectedSkill);
+                    loadedSkill = {
+                        name: selectedSkill,
+                        content: skill.content,
+                        reason: namedSkill === undefined
+                            ? `semantic match ${semanticMatch?.score.toFixed(3) ?? ''}`.trim()
+                            : 'the user named it',
+                    };
+                }
+            }
+            catch {
+                // Skill discovery is advisory; a broken user skill directory must not block chat.
+            }
+        }
+        // E3 wire-up: prepend the guard-tagging context notice (when a previous
+        // turn of this session left untrusted tool outputs) so the model treats
+        // them as data, never as instructions. The notice is derived fresh per
+        // turn and never persisted: persistNewMessages filters it out because it
+        // is part of baseMessages (same reference).
+        const tagNotice = this.deps.guardContext?.buildContextNotice(sessionId);
+        const memoryPrompt = this.deps.persistentMemory?.formatForSystemPrompt();
+        const baseMessages = [
+            {
+                role: 'system',
+                content: buildSystemPrompt(skillCatalog, loadedSkill, this.deps.assistantInstructions, memoryPrompt, toolInfos),
+            },
+            ...(tagNotice === undefined ? [] : [{ role: 'system', content: tagNotice }]),
+            ...history, userMessage,
+        ];
+        await this.deps.sessions.appendMessages(sessionId, [userMessage]);
+        const runId = randomUUID();
+        // Moved up: the middleware chain needs the turn id at registration.
+        const turnId = `turn_${randomUUID()}`;
+        this.progressList(turnId);
+        const turnContext = {
+            sessionId,
+            messages: baseMessages,
+            // Policy-filtered: a tool this turn's policy would deny is never
+            // offered, so the model cannot choose its way into a stopped turn.
+            tools,
+            runId,
+            budget: {
+                maxRounds: input.channel === 'scheduler' ? 4 : 20,
+                maxToolCalls: input.channel === 'scheduler' ? 8 : 64,
+            },
+            // PR #12 + PR #14 wire-up: run every turn through the middleware
+            // onion (adaptive routing + reasoning-guard verification). Built per
+            // turn so the verification-snapshot holder never leaks across turns;
+            // an empty chain would keep the pipeline's zero-cost old path.
+            middlewares: createTurnMiddlewares({
+                routingEnabled: this.deps.routing?.enabled ?? true,
+                verificationConfig: this.deps.reasoningGuard ?? { mode: 'warn' },
+                turnId,
+                runId,
+                publish: (event) => this.safePublish(event),
+            }),
+        };
+        // 3c. Config snapshot (P1-7): record once per session the exact model,
+        // provider, tool count and system prompt serving its turns. The adapter
+        // keeps the first capture, so later config drift cannot rewrite history.
+        // Best-effort by design: a snapshot failure must never break a turn.
+        try {
+            const describeProvider = this.deps.describeProvider;
+            const providerPart = describeProvider === undefined
+                ? undefined
+                : await describeProvider().catch(() => undefined);
+            const systemPrompt = baseMessages[0]?.content ?? '';
+            await this.deps.sessions.captureConfigSnapshot?.(sessionId, {
+                ...(providerPart ?? {}),
+                toolsEnabled: turnContext.tools.length,
+                systemPromptHash: hashSystemPrompt(systemPrompt),
+            });
+        }
+        catch {
+            // Observability only — the turn proceeds without a snapshot.
+        }
+        // 4. Track the turn and run it in the background; submit returns now.
+        const controller = new AbortController();
+        this.activeTurns.set(turnId, controller);
+        this.runToTurn.set(runId, { turnId, sessionId });
+        const state = { memoryHits: 0, toolStartedAt: new Map() };
+        // 3b. Harness guard: deterministic pre-execution gate for every tool
+        // call. Denials never reach the tool handler and are announced on the
+        // wire as `guard.blocked` so the client knows why the call was refused.
+        attachHarnessGuard(runtimeDeps, createPolicy({
+            mode: this.deps.harnessGuard?.mode ?? 'warn',
+            writeZones: this.deps.harnessGuard?.writeZones ?? [],
+        }), (info) => this.safePublish({
+            type: 'guard.blocked',
+            payload: {
+                turnId,
+                runId,
+                toolName: info.toolName,
+                layer: info.layer,
+                reason: info.reason,
+            },
+        }));
+        const task = this.runInBackground(turnId, runId, controller, sessionId, baseMessages, state, runtimeDeps, turnContext, localReply);
+        this.activeTasks.set(turnId, task);
+        void task.finally(() => this.activeTasks.delete(turnId));
+        return { turnId, sessionId };
+    }
+    async cancel(turnId) {
+        const controller = this.activeTurns.get(turnId);
+        if (controller === undefined) {
+            return false;
+        }
+        this.activeTurns.delete(turnId);
+        controller.abort();
+        return true;
+    }
+    async shutdown() {
+        // Fail pending HITL approvals first: the human can no longer answer,
+        // so each waiting turn ends with an `approval_timeout` error instead of
+        // hanging on a promise whose resolvers are about to be dropped.
+        const pendings = [...this.pendingApprovals.entries()];
+        const pendingTasks = pendings.flatMap(([runId]) => {
+            const turnId = this.runToTurn.get(runId)?.turnId;
+            const task = turnId === undefined ? undefined : this.activeTasks.get(turnId);
+            return task === undefined ? [] : [task];
+        });
+        this.pendingApprovals.clear();
+        const store = this.deps.approvalStore;
+        for (const [runId, pending] of pendings) {
+            // The waiter is about to be dropped: expire the persisted request so
+            // a later boot scan does not resurrect it. Best-effort — the turn
+            // still fails even if the store is broken.
+            try {
+                store?.expireApproval(runId);
+            }
+            catch {
+                // fall through: the rejection below still ends the turn
+            }
+            const err = new ApprovalTimeoutError(runId, 0);
+            err.message = `gateway shutting down: ${err.message}`;
+            pending.reject(err);
+        }
+        await settleWithin(pendingTasks, 2_000);
+        this.runToTurn.clear();
+        const controllers = [...this.activeTurns.values()];
+        this.activeTurns.clear();
+        for (const controller of controllers) {
+            controller.abort();
+        }
+    }
+    // -- ApprovalPort (HITL) -------------------------------------------------
+    async requestApproval(req, signal) {
+        const owner = this.runToTurn.get(req.runId);
+        if (owner === undefined) {
+            throw new Error(`no active turn for approval run ${req.runId}`);
+        }
+        const timeoutMs = this.deps.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS;
+        const { turnId, sessionId } = owner;
+        // Announce the pause on the wire so the client can prompt a human.
+        this.safePublish({
+            type: 'turn.approval_required',
+            payload: {
+                turnId,
+                runId: req.runId,
+                toolName: req.toolName,
+                args: { ...req.args },
+                reason: req.reason,
+            },
+        });
+        // Persist first: the state machine is the single source of truth for
+        // the request lifecycle; the in-memory waiter below is ephemeral. A
+        // broken store degrades to in-memory-only — it never breaks the turn.
+        const store = this.deps.approvalStore;
+        if (store !== undefined) {
+            try {
+                store.requestApproval({
+                    id: req.runId,
+                    turnId,
+                    sessionId,
+                    toolName: req.toolName,
+                    argsJson: JSON.stringify(req.args),
+                    reason: req.reason,
+                    expiresAtMs: Date.now() + timeoutMs,
+                });
+            }
+            catch {
+                // degraded: the waiter below still works; the boot scan just won't see it
+            }
+        }
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+            };
+            const onAbort = () => {
+                this.pendingApprovals.delete(req.runId);
+                cleanup();
+                const err = new Error('turn cancelled while awaiting approval');
+                err.name = 'AbortError';
+                reject(err);
+            };
+            const timer = setTimeout(() => {
+                this.pendingApprovals.delete(req.runId);
+                // Enforce the deadline on the persisted row too, so the boot scan
+                // never resurrects a request this process already killed.
+                try {
+                    store?.sweepExpired();
+                }
+                catch {
+                    // degraded: the turn still fails below
+                }
+                reject(new ApprovalTimeoutError(req.runId, timeoutMs));
+            }, timeoutMs);
+            // The approval timer must not pin the process (or a test worker) open.
+            unrefTimer(timer);
+            this.pendingApprovals.set(req.runId, {
+                resolve: (verdict) => {
+                    cleanup();
+                    resolve(verdict);
+                },
+                reject: (err) => {
+                    cleanup();
+                    reject(err);
+                },
+                turnId,
+                toolName: req.toolName,
+            });
+            if (signal?.aborted === true) {
+                onAbort();
+                return;
+            }
+            signal?.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+    async approveTurn(runId, approved, editedArgs) {
+        const pending = this.pendingApprovals.get(runId);
+        if (pending !== undefined) {
+            this.pendingApprovals.delete(runId);
+            try {
+                this.deps.approvalStore?.resolveApproval(runId, approved ? 'approved' : 'denied');
+            }
+            catch {
+                // The verdict was already delivered; persistence is best-effort.
+            }
+            pending.resolve({ approved, editedArgs });
+            return { found: true, resumed: true };
+        }
+        // Restart path: no live waiter, but the request may still be `pending`
+        // in the store. Record the human's decision; the turn itself cannot
+        // resume (its loop state died with the previous process).
+        try {
+            const resolved = this.deps.approvalStore?.resolveApproval(runId, approved ? 'approved' : 'denied');
+            if (resolved !== undefined) {
+                return { found: true, resumed: false };
+            }
+        }
+        catch {
+            // fall through to not-found
+        }
+        return { found: false, resumed: false };
+    }
+    /**
+     * Re-announce approvals still `pending` from the previous process
+     * (P1-2 approval resume). Called once at gateway boot, before the HTTP
+     * server starts listening: every survivor is re-published as
+     * `turn.approval_required` (payload flag `resumed: true`) and retained in
+     * the per-turn progress replay, so a client opening
+     * `GET /v1/turns/:turnId/events` after boot still sees the pending
+     * approval instead of a silent timeout. Past-deadline requests are marked
+     * `expired` by the store and are NOT re-announced. Returns the number
+     * re-announced.
+     *
+     * Honest limit: the turn that requested the approval is gone (its loop
+     * state died with the old process). Answering via `turn.approve` records
+     * the human's decision; `approveTurn` reports `{ found: true, resumed:
+     * false }` for these.
+     */
+    reannouncePendingApprovals() {
+        const store = this.deps.approvalStore;
+        if (store === undefined)
+            return 0;
+        let resumed;
+        try {
+            resumed = store.resumePendingOnBoot().resumed;
+        }
+        catch {
+            return 0;
+        }
+        for (const req of resumed) {
+            // Retain for late SSE subscribers: the turn never ran in this
+            // process, so no progress list exists for it yet.
+            this.progressList(req.turnId);
+            this.safePublish({
+                type: 'turn.approval_required',
+                payload: {
+                    turnId: req.turnId,
+                    runId: req.id,
+                    toolName: req.toolName,
+                    args: parseApprovalArgs(req.argsJson),
+                    reason: req.reason,
+                    resumed: true,
+                },
+            });
+        }
+        return resumed.length;
+    }
+    /**
+     * Get-or-create the per-turn progress replay list, evicting the oldest
+     * turn when the bound is hit. Used for live turns and for approvals
+     * re-announced after a restart (their turns never ran in this process).
+     */
+    progressList(turnId) {
+        let list = this.progressEvents.get(turnId);
+        if (list === undefined) {
+            if (this.progressEvents.size >= GatewayTurnService.MAX_TERMINAL_EVENTS) {
+                const oldest = this.progressEvents.keys().next();
+                if (!oldest.done)
+                    this.progressEvents.delete(oldest.value);
+            }
+            list = [];
+            this.progressEvents.set(turnId, list);
+        }
+        return list;
+    }
+    async runInBackground(turnId, runId, controller, sessionId, baseMessages, state, runtimeDeps, turnContext, localReply) {
+        try {
+            if (localReply !== undefined) {
+                this.bridgeEvent(turnId, state, { type: 'turn.start', sessionId, runId });
+                const result = {
+                    status: 'completed',
+                    messages: [...baseMessages, { role: 'assistant', content: localReply }],
+                    rounds: 0,
+                    toolCallsExecuted: 0,
+                    toolCallsDenied: 0,
+                };
+                await this.persistNewMessages(turnId, sessionId, baseMessages, 0, result.messages);
+                this.publishTerminal(turnId, result);
+                return;
+            }
+            // Apply Context Auto-Compaction with dynamic provider context limits
+            const limits = this.deps.resolveContextLimits
+                ? await this.deps.resolveContextLimits()
+                : { maxContextTokens: 128_000, maxContextChars: 512_000, triggerThreshold: 0.75, hotZoneRounds: 4 };
+            const compactor = new ContextCompactor({
+                maxContextTokens: limits.maxContextTokens,
+                triggerThreshold: limits.triggerThreshold ?? 0.75,
+                hotZoneRounds: limits.hotZoneRounds ?? 4,
+            });
+            const compactionRes = await compactor.compact(turnContext.messages);
+            const effectiveContext = compactionRes.compacted
+                ? { ...turnContext, messages: compactionRes.messages }
+                : turnContext;
+            if (compactionRes.compacted) {
+                this.safePublish({
+                    type: 'turn.compacted',
+                    payload: {
+                        turnId,
+                        prunedTurns: compactionRes.prunedTurnsCount,
+                        originalTokens: compactionRes.originalTokens,
+                        compactedTokens: compactionRes.compactedTokens,
+                    },
+                });
+            }
+            // The service is its own ApprovalPort: a policy 'ask' pauses the turn
+            // here until `approveTurn` (or the timeout) resolves the verdict.
+            const depsWithApproval = { ...runtimeDeps, approval: this };
+            // Dynamic Macro Routing: Evaluate intent to decide between Planner vs ReAct
+            const latestUserContent = [...effectiveContext.messages].reverse().find((m) => m.role === 'user')?.content ?? '';
+            const decision = IntentClassifier.classify(latestUserContent);
+            let result;
+            if (decision.mode === 'planner') {
+                this.safePublish({
+                    type: 'turn.routed',
+                    payload: {
+                        turnId,
+                        runId,
+                        route: 'deep',
+                        reason: `planner:${decision.reason}`,
+                    },
+                });
+                result = await executePlannedTurn({
+                    goal: decision.goal,
+                    turnId,
+                    runId,
+                    baseContext: effectiveContext,
+                    runtimeDeps: depsWithApproval,
+                    runTurn: this.deps.runTurn,
+                    onEvent: (event) => this.bridgeEvent(turnId, state, event),
+                    signal: controller.signal,
+                    onPhaseProgress: (phase, total, title) => {
+                        this.safePublish({
+                            type: 'task.progress',
+                            payload: {
+                                taskId: turnId,
+                                stepIndex: phase - 1,
+                                totalSteps: total,
+                                detail: title,
+                            },
+                        });
+                    },
+                });
+            }
+            else {
+                result = await this.deps.runTurn(depsWithApproval, effectiveContext, (event) => this.bridgeEvent(turnId, state, event), controller.signal);
+            }
+            // E3 wire-up: tag this turn's tool outputs (trusted/untrusted) into
+            // the gateway guard context so the next turn of the same session can
+            // see them, and announce each created tag on the wire (`guard.tagged`).
+            // Tagging never breaks turn settlement.
+            try {
+                const records = this.deps.guardContext?.tagTurnOutputs({
+                    sessionId,
+                    turnId,
+                    runId,
+                    messages: result.messages,
+                });
+                for (const record of records ?? []) {
+                    try {
+                        this.safePublish({
+                            type: 'guard.tagged',
+                            payload: {
+                                turnId,
+                                runId,
+                                toolName: record.toolName,
+                                trust: record.tag.trust,
+                                callId: record.callId || undefined,
+                                patterns: record.patterns.length > 0 ? [...record.patterns] : undefined,
+                            },
+                        });
+                    }
+                    catch {
+                        // Intentionally swallowed: one broken stream event must not
+                        // hide the remaining tags or break turn settlement.
+                    }
+                }
+            }
+            catch {
+                // Intentionally swallowed: persistence and terminal events continue.
+            }
+            await this.persistNewMessages(turnId, sessionId, baseMessages, state.memoryHits, result.messages, compactionRes.compacted, effectiveContext.messages.length);
+            this.publishTerminal(turnId, result);
+        }
+        catch (err) {
+            // runTurn is not supposed to reject (cancellation and errors become
+            // TurnResult), but a background turn must never die silently.
+            this.safePublish({
+                type: 'agent.turn.error',
+                payload: {
+                    turnId,
+                    error: err instanceof Error ? err.message : 'turn failed unexpectedly',
+                    retryable: true,
+                },
+            });
+        }
+        finally {
+            if (this.activeTurns.get(turnId) === controller) {
+                this.activeTurns.delete(turnId);
+            }
+            this.runToTurn.delete(runId);
+        }
+    }
+    /**
+     * Map loop events to wire stream events. The terminal `turn.end` is NOT
+     * published here — it goes out via `publishTerminal` after persistence.
+     *
+     * Additive mapping: the typed `turn.*` events (turn.start, turn.tool_start,
+     * turn.tool_end, turn.approval_required) are published alongside the
+     * legacy `agent.turn.*` events, which keep their exact shapes.
+     */
+    bridgeEvent(turnId, state, event) {
+        switch (event.type) {
+            case 'turn.start': {
+                state.runId = event.runId;
+                this.safePublish({
+                    type: 'turn.start',
+                    payload: { turnId, runId: event.runId },
+                });
+                break;
+            }
+            case 'turn.routed': {
+                this.safePublish({
+                    type: 'turn.routed',
+                    payload: {
+                        turnId,
+                        runId: event.runId,
+                        route: event.mode,
+                        reason: event.reason,
+                    },
+                });
+                break;
+            }
+            case 'turn.escalated': {
+                // The routing middleware only ever escalates fast → deep, at most
+                // once per turn (routing.ts: the `finalize` hook checks
+                // `state.mode === 'fast'` and flips it to `'deep'` with reason
+                // `guard:unsupported-claims`) — so the wire fields are fixed here
+                // rather than carried on the internal event.
+                this.safePublish({
+                    type: 'turn.escalated',
+                    payload: {
+                        turnId,
+                        runId: event.runId,
+                        from: 'fast',
+                        to: 'deep',
+                        trigger: event.reason,
+                    },
+                });
+                break;
+            }
+            case 'text.delta': {
+                this.safePublish({
+                    type: 'agent.turn.token',
+                    payload: { turnId, delta: event.text },
+                });
+                break;
+            }
+            case 'reasoning.delta': {
+                // Reasoning fragments are a separate stream from the final answer:
+                // they must not flow through `agent.turn.token` (which clients render
+                // as the answer) so web UI can render them in a collapsible block.
+                this.safePublish({
+                    type: 'turn.reasoning_delta',
+                    payload: {
+                        turnId,
+                        ...(state.runId !== undefined ? { runId: state.runId } : {}),
+                        delta: event.text,
+                    },
+                });
+                break;
+            }
+            case 'tool.call': {
+                this.safePublish({
+                    type: 'agent.turn.tool_call',
+                    payload: {
+                        turnId,
+                        toolCall: {
+                            id: event.call.id,
+                            name: event.call.name,
+                            arguments: { ...event.call.arguments },
+                            startedAt: new Date().toISOString(),
+                        },
+                    },
+                });
+                if (state.runId !== undefined) {
+                    state.toolStartedAt.set(event.call.id, Date.now());
+                    this.safePublish({
+                        type: 'turn.tool_start',
+                        payload: {
+                            turnId,
+                            runId: state.runId,
+                            toolCallId: event.call.id,
+                            toolName: event.call.name,
+                        },
+                    });
+                }
+                break;
+            }
+            case 'tool.result': {
+                if (state.runId !== undefined) {
+                    const startedAt = state.toolStartedAt.get(event.result.callId);
+                    state.toolStartedAt.delete(event.result.callId);
+                    this.safePublish({
+                        type: 'turn.tool_end',
+                        payload: {
+                            turnId,
+                            runId: state.runId,
+                            toolCallId: event.result.callId,
+                            toolName: event.result.name,
+                            durationMs: startedAt === undefined ? 0 : Math.max(0, Date.now() - startedAt),
+                            status: event.result.error ? 'error' : 'ok',
+                        },
+                    });
+                }
+                break;
+            }
+            case 'policy.deny': {
+                // Hard policy denials surface as warnings. Approval-required calls
+                // use the separate `approval.pending` path and never enter this case.
+                this.safePublish({
+                    type: 'agent.turn.error',
+                    payload: {
+                        turnId,
+                        error: `policy: ${event.reason} — tool '${event.call.name}' was blocked (accident-prevention)`,
+                        retryable: false,
+                    },
+                });
+                break;
+            }
+            case 'memory.hits': {
+                state.memoryHits = event.count;
+                break;
+            }
+            case 'turn.end':
+            default: {
+                break;
+            }
+        }
+    }
+    publishTerminal(turnId, result) {
+        if (result.status === 'error') {
+            this.safePublish({
+                type: 'agent.turn.error',
+                payload: {
+                    turnId,
+                    error: result.error ?? 'turn failed',
+                    retryable: true,
+                },
+            });
+            return;
+        }
+        const payload = { turnId, status: result.status };
+        const output = lastAssistantText(result.messages);
+        if (output !== '') {
+            payload.output = output;
+        }
+        if (result.usage !== undefined)
+            payload.usage = result.usage;
+        this.safePublish({ type: 'agent.turn.done', payload });
+    }
+    /**
+     * Persist the messages the turn produced. `buildPrompt` unshifts exactly
+     * one derived system message when memory hits exist — skip it so derived
+     * memory context is not duplicated into history on every turn.
+     */
+    async persistNewMessages(turnId, sessionId, baseMessages, memoryHits, resultMessages, wasCompacted = false, effectiveContextLength = 0) {
+        const withoutInjected = memoryHits > 0 ? resultMessages.slice(1) : resultMessages;
+        let added;
+        if (wasCompacted && effectiveContextLength > 0) {
+            added = withoutInjected.slice(effectiveContextLength);
+            // Fallback: đảm bảo không bao giờ bị rơi mất câu trả lời của assistant
+            if (added.length === 0 && withoutInjected.length > 0) {
+                const last = withoutInjected[withoutInjected.length - 1];
+                if (last && last.role === 'assistant')
+                    added = [last];
+            }
+        }
+        else {
+            added = withoutInjected.slice(baseMessages.length);
+        }
+        if (added.length === 0) {
+            return;
+        }
+        try {
+            await this.deps.sessions.appendMessages(sessionId, added);
+        }
+        catch (err) {
+            this.safePublish({
+                type: 'agent.turn.error',
+                payload: {
+                    turnId,
+                    error: `failed to persist turn messages: ${err instanceof Error ? err.message : 'unknown error'}`,
+                    retryable: false,
+                },
+            });
+        }
+    }
+    /** The event bus must never break a turn; terminal state still settles. */
+    safePublish(event) {
+        if (event.type === 'turn.start' ||
+            event.type === 'turn.tool_start' ||
+            event.type === 'turn.tool_end' ||
+            // P1-2: a late subscriber to the turn stream must see the pending
+            // approval (live pause or boot re-announcement), not wait forever.
+            event.type === 'turn.approval_required') {
+            const { turnId } = event.payload;
+            const history = this.progressEvents.get(turnId);
+            history?.push(event);
+            // ponytail: latest 257 lifecycle events for 200 turns; durable replay needs a store.
+            if (history && history.length > 257)
+                history.shift();
+        }
+        try {
+            this.deps.publish(event);
+        }
+        catch {
+            // Intentionally swallowed: persistence and turn settlement continue.
+        }
+        this.rememberTerminal(event);
+    }
+    /**
+     * Retain terminal events for late SSE subscribers. Runs after the publish
+     * attempt so a broken bus still leaves the replay available.
+     */
+    rememberTerminal(event) {
+        if (event.type !== 'agent.turn.done' && event.type !== 'agent.turn.error') {
+            return;
+        }
+        const turnId = event.payload.turnId;
+        if (typeof turnId !== 'string' || turnId.length === 0)
+            return;
+        if (this.terminalEvents.size >= GatewayTurnService.MAX_TERMINAL_EVENTS) {
+            const oldest = this.terminalEvents.keys().next();
+            if (!oldest.done)
+                this.terminalEvents.delete(oldest.value);
+        }
+        this.terminalEvents.set(turnId, event);
+    }
+}
+/**
+ * Parse persisted approval args for the re-announced SSE payload.
+ * Corrupt JSON degrades to `{}` — the approver still sees the tool name
+ * and reason, and the row keeps the original bytes.
+ */