agent-nuvira 3.3.3 → 3.3.5

package/dist/gateway/registry.js

@@ -26,6 +26,7 @@ import { ConfigManager } from '../config/manager.js';
 import { ChannelDirectory, PLATFORM_ENV_VARS, PLATFORM_LABELS, } from './channel-directory.js';
 import { DeliveryLedger } from './delivery.js';
 import { InboxLedger } from './inbox.js';
+import { inboundAttachmentPolicy } from './inbound-media.js';
 import { InboundDedupLedger } from './dedup.js';
 import { GatewayHeartbeat, HEARTBEAT_INTERVAL_MS } from './heartbeat.js';
 import { logGatewayEvent, previewText } from './gateway-log.js';
@@ -36,6 +37,11 @@ import { createResilientCallLLM, markFailoverAttempts, modelBreadthReport, rende
 // The intent audit: on a REPEATED failure, ask the model what the ask really
 // needs and feed a confirmed correction back into the NLU (see learnings.ts).
 import { confirmRoutedIntent, intentConfirmedNote, intentCorrectedNote, } from '../nlu/intent-confirm.js';
+// The audit's verdict goes into the gateway's own durable record, in the SAME
+// wire shape every other surface reports (WS1, `findings/verdicts.ts`): a
+// messaging surface has no terminal to scroll, so "what we decided, and what it
+// was checked against" has to be in the log or it does not exist.
+import { toWire } from '../findings/verdicts.js';
 // The retry queue behind the "Reply *yes* and I will keep trying" offer. LEAF
 // import: a plain store + matcher, so the gateway does not pull routing in for it.
 import { abandonedLine, acceptedLine, cancelTasksFor, confirmTask, deferTask, dueTasks, expiredTasks, getPendingTask, isRetryAcceptance, isRetryDecline, removeDeferredTask, retryingLine, updateDeferredTask, } from '../learning/deferred-task.js';
@@ -57,6 +63,17 @@ const DELIVERY_DRAIN_INTERVAL_MS = 30_000;
 const RETRY_DRAIN_INTERVAL_MS = 15_000;
 /** Cap the per-target send-failure map (diagnostics only — never grows). */
 const MAX_TRACKED_SEND_ERRORS = 200;
+/**
+ * How often the inbound artifact sandbox is swept (ms). Hourly: the sweep
+ * removes attachments past their TTL / over the size cap, and the 15s liveness
+ * tick that triggers it must not do directory work it does not need to.
+ */
+const INBOUND_PRUNE_INTERVAL_MS = 60 * 60 * 1000;
+/**
+ * Longest answer spoken as a voice note (chars). A voice-note question expects a
+ * spoken reply, not a synthesized essay — past this the answer goes out as text.
+ */
+const VOICE_REPLY_MAX_CHARS = 700;
 // ─── Response cleanup ──────────────────────────────────────────────────────
 /**
  * Strip leaked internal reasoning, planning blocks, and meta-commentary from
@@ -527,6 +544,8 @@ export class GatewayRegistry {
     adapterHealth = new Map();
     /** Earliest epoch-ms at which a not-yet-started adapter may be retried. */
     adapterRetryAt = new Map();
+    /** Epoch ms of the last inbound-sandbox sweep (throttles the hourly prune). */
+    lastInboundPruneAt = 0;
     /** The heartbeat + watchdog tick. */
     livenessTimer = null;
     chatEngine;
@@ -634,6 +653,38 @@ export class GatewayRegistry {
         }
         return this.sendToRef(ref, text, target);
     }
+    /**
+     * Deliver an ANSWER, using a VOICE NOTE when the sender's own message was a
+     * voice note and a TTS backend is installed.
+     *
+     * Falls back to text whenever anything is missing — no TTS backend, an answer
+     * too long to speak sanely, or a platform that cannot send audio — so a voice
+     * reply is a courtesy and never a way for the answer to get lost. Returns true
+     * when a voice note was delivered, false when text was sent instead.
+     */
+    async replyInKind(ref, text, opts = {}) {
+        if (opts.voice && text.length > 0 && text.length <= VOICE_REPLY_MAX_CHARS) {
+            try {
+                const voice = await import('../tools/modality/voice.js');
+                if (voice.isTtsAvailable()) {
+                    const spoken = await voice.speak(text);
+                    if (spoken.ok && spoken.file) {
+                        const { readFileSync } = await import('node:fs');
+                        const data = new Uint8Array(readFileSync(spoken.file));
+                        const ext = spoken.file.toLowerCase().endsWith('.wav') ? 'wav' : 'mp3';
+                        const ok = await this.sendMediaToRef(ref, { type: 'audio', data, filename: `reply.${ext}` });
+                        if (ok)
+                            return true;
+                    }
+                }
+            }
+            catch {
+                /* fall back to text */
+            }
+        }
+        await this.sendToRef(ref, text);
+        return false;
+    }
     /**
      * P3 — send media to a channel ref. Adapters that implement the optional
      * `sendMedia` (WhatsApp, Telegram, Discord) support it; others return false
@@ -871,6 +922,53 @@ export class GatewayRegistry {
         if (!this.isAllowed(ref)) {
             return refuse('This channel is not authorized to trigger the agent. Add it to BUFF_GATEWAY_ALLOW_IDS (platform:channelId).');
         }
+        // ── INBOUND DOCUMENT HYDRATION ── A document/image arrives as BYTES, not
+        // text. Turn it into text BEFORE routing, because every downstream reader
+        // (the dedup ledger, the chat store, and finally the model) reads
+        // `msg.text`: this runs the SAME `read_extract` the agent uses for a file in
+        // the project folder and prepends the extracted section to the caption.
+        // Without it a document message had empty text and was dropped by the
+        // bridge — the sender's own file vanished with no reply.
+        //
+        // Placed AFTER the authorization gates on purpose: an unapproved sender must
+        // leave no trace, so their bytes are never written to the artifact sandbox
+        // or extracted. `parsed` above already ran on the CAPTION only, so a long
+        // document never pollutes the NLU route; the extracted text joins the turn
+        // for the model.
+        //
+        // Consumed ONCE (media is cleared) so a retry or an audit re-route of the
+        // same message never re-downloads or duplicates the section.
+        let mediaFailureReply = null;
+        // A voice note gets a voice reply when one was sent (see replyInKind).
+        let voiceReplyWanted = false;
+        if (msg.media) {
+            const media = msg.media;
+            msg.media = undefined;
+            const attachmentPolicy = inboundAttachmentPolicy(this.configManager);
+            if (!attachmentPolicy.enabled) {
+                // Policy lets the MESSAGE through but not the attachment. Say so to the
+                // model rather than silently dropping it — or extracting it.
+                const label = media.filename?.trim() || media.type;
+                msg.text = [msg.text, `[Attachment: ${label} — inbound attachment handling is disabled by configuration]`]
+                    .filter(Boolean)
+                    .join('\n\n');
+            }
+            else {
+                voiceReplyWanted = media.type === 'audio';
+                try {
+                    const { hydrateInboundMedia, formatMediaFailureReply } = await import('./inbound-media.js');
+                    const hydration = await hydrateInboundMedia(media, { maxBytes: attachmentPolicy.maxBytes });
+                    if (hydration.section)
+                        msg.text = [msg.text, hydration.section].filter(Boolean).join('\n\n');
+                    if (hydration.failure)
+                        mediaFailureReply = formatMediaFailureReply(hydration.failure);
+                    logger.info(`gateway: hydrated inbound ${media.type} (${media.data.byteLength} bytes) for ${msg.platform}:${msg.channelId}`);
+                }
+                catch {
+                    /* Never break handling on a media failure — the text turn still runs. */
+                }
+            }
+        }
         // ── IDEMPOTENCY ── A messaging transport is at-least-once: the bridge
         // reconnects and replays its offline backfill, a webhook retries, a device
         // re-syncs. Observed live: ONE WhatsApp ask arrived 20+ times and was
@@ -898,6 +996,15 @@ export class GatewayRegistry {
             record('duplicate', undefined, { key: dedupVerdict.key, count: dedupVerdict.count });
             return 'duplicate';
         }
+        // A document that produced NO text cannot be answered by routing it to the
+        // model — the model would only invent an answer about a file it never read.
+        // Answer the sender directly, naming why, and stop. Placed AFTER dedup so a
+        // re-delivered message (bridge backfill / webhook retry) never re-sends it.
+        if (mediaFailureReply) {
+            await replyTo(mediaFailureReply);
+            record('attachment_failed', mediaFailureReply);
+            return mediaFailureReply;
+        }
         // 7-DAY PER-CONTACT CONVERSATION MEMORY — record every AUTHORIZED inbound
         // message the moment it arrives, BEFORE the routing decision (chat,
         // pipeline, help). Placed AFTER the sender/channel gates: an unapproved
@@ -1000,7 +1107,9 @@ export class GatewayRegistry {
             const attemptMark = markFailoverAttempts();
             const answer = await this.runInboundChat(msg);
             if (answer && answer.content.trim() && !answer.generationFailed) {
-                await replyTo(answer.content);
+                // Reply IN KIND: a spoken question gets a spoken answer when TTS is
+                // available (falls back to text — see replyInKind).
+                await this.replyInKind(ref, answer.content, { voice: voiceReplyWanted });
                 record('chat', answer.content);
                 // A retry that produced a real answer is DONE — the queue entry must go,
                 // or the drain would keep re-running a fulfilled ask.
@@ -1068,7 +1177,10 @@ export class GatewayRegistry {
             const answer = await this.runInboundChat(msg);
             const answered = !!answer && answer.content.trim().length > 0 && !answer.generationFailed;
             const line = answered ? answer.content : this.generationFailureLine();
-            await replyTo(line);
+            if (answered)
+                await this.replyInKind(ref, line, { voice: voiceReplyWanted });
+            else
+                await replyTo(line);
             record('pipeline', line);
             if (answered && opts.retryOf)
                 removeDeferredTask(opts.retryOf);
@@ -1241,6 +1353,10 @@ export class GatewayRegistry {
                 routed,
                 probed: !verdict.failed,
                 reason: verdict.reason,
+                // The verdict for THIS decision, with its evidence. A confirmed reading
+                // now means the model justified it, so the log says which of the two it
+                // was instead of leaving "probed: true" to imply it was checked.
+                finding: toWire(verdict.finding),
             }, 'info');
             // The audit ran and confirmed the reading: say so, because "it failed" and
             // "it failed and I checked that I understood you" are different promises.
@@ -1254,6 +1370,11 @@ export class GatewayRegistry {
             to: verdict.kind,
             reason: verdict.reason,
             learningId: verdict.learning?.id,
+            // Logged even when `learningId` is absent, and that is the case worth
+            // recording: a correction the model could not justify is acted on but NOT
+            // taught, so the log states the verdict (PLAUSIBLE) and its own outcome
+            // rather than looking like a correction that simply failed to save.
+            finding: toWire(verdict.finding),
         }, 'warn');
         const corrected = verdict.kind;
         const line = intentCorrectedNote(corrected, verdict.reason);
@@ -1364,6 +1485,23 @@ export class GatewayRegistry {
             return true;
         }
     }
+    /**
+     * One inbound chat turn, and the backend it was served by.
+     *
+     * The result carries `provider`/`model`/`transport` because this method is the
+     * surface's boundary: the shared engine resolves all three, and keeping only
+     * `content` + `generationFailed` is what made `run-attribution@gateway-chat`
+     * the one capability cell the gateway could not prove. A messaging run is
+     * also the hardest to inspect after the fact — there is no terminal to scroll
+     * — so the same triple goes to the gateway log.
+     *
+     * It also carries the turn's per-call tool lifecycles (`toolCalls`), read from
+     * the engine's `onToolCall` seam. Those are recorded, never sent to the
+     * sender: a chat turn's `started`/`called` events are internal, exactly like
+     * `onProgress`, but the OUTCOME of each call is a fact the surface should be
+     * able to report — otherwise a gateway turn's tool work is unattributable
+     * (`tool-call-lifecycle@gateway-chat`).
+     */
     async runInboundChat(msg) {
         try {
             // Broadcast typing indicator start.
@@ -1437,10 +1575,44 @@ export class GatewayRegistry {
             const routingDefault = this.configManager.getAll().defaultProvider;
             const useAuto = !routingDefault || routingDefault === 'auto';
             const { type: providerType, config: providerConfig } = this.configManager.getProviderConfig();
+            // The turn's tool-call lifecycle. Collected from the SHARED engine seam
+            // (the same `called` phase the CLI and dashboard read) so the gateway
+            // reports what the turn DID, not what the answer text claims. Outcome is
+            // optional: a call whose outcome never arrived is recorded as absent, the
+            // same honest reading the other surfaces use, never up-graded to success.
+            const toolCalls = [];
+            /**
+             * WS1 — the findings this turn recorded, in call order.
+             *
+             * Read from the shared engine seam like `toolCalls` above, and written to
+             * the `inbound.chat` log record for the same reason: a messaging surface
+             * has no terminal to scroll, so the log is where a turn's verdicts have to
+             * live (and it is what the parity driver reads).
+             */
+            const findings = [];
             const answer = await engine.answerOnce(prompt, {
                 provider: useAuto ? 'auto' : providerType,
                 model: useAuto ? 'auto' : providerConfig.model,
                 history,
+                // WS5 (#27) — isolation and resume are asked through the environment
+                // (`NUVIRA_ISOLATE` / `NUVIRA_RESUME`), which is how a messaging gateway
+                // is configured: an inbound WhatsApp message has no flags to carry, and
+                // the operator decides once for the deployment. This is the code's own
+                // record of that decision, on the log line that reports the turn.
+                onToolCall: (phase, info) => {
+                    if (phase !== 'called')
+                        return;
+                    toolCalls.push({ tool: info.tool, ...(typeof info.ok === 'boolean' ? { ok: info.ok } : {}) });
+                },
+                // WS1 — every finding the turn recorded, with the gate's verdict. Kept
+                // internal exactly like onToolCall: it belongs in the log and this
+                // method's return, never in the channel sender's message.
+                onFinding: (finding) => {
+                    findings.push(finding);
+                },
+                // WS2 (#24) — a messaging turn is the GATEWAY's; the session debug log's
+                // header must name it that way rather than the shared engine's default.
+                debugSurface: 'gateway-chat',
                 // Session 3 — the channel rules go in the STABLE layer, not the ask.
                 systemPolicy: CHANNEL_POLICY,
                 // P5 — a replied followup carries the continuation marker into the
@@ -1493,7 +1665,9 @@ export class GatewayRegistry {
                 // P3 note: the engine's onProgress is intentionally NOT wired here —
                 // internal progress lines (routed-to, raw tool calls) must never leak
                 // to the channel. Progress stays in the audit logs; the single
-                // "working" line + final answer is the whole conversation.
+                // "working" line + final answer is the whole conversation. The
+                // structured onToolCall lifecycle above is wired, but only for the log
+                // and this method's return — it is never rendered to the sender.
             });
             // Only the FINAL answer reaches the sender, in natural language — plus
             // the model's suggested followups rendered as a readable numbered list
@@ -1584,7 +1758,36 @@ export class GatewayRegistry {
             this.chatStore.append(historyKey, null, content);
             this.onTypingCallback?.({ platform: msg.platform, channelId: msg.channelId, typing: false });
             this.writeTypingFile({ platform: msg.platform, channelId: msg.channelId, typing: false });
-            return { content, generationFailed: answer.generationFailed };
+            // The run's own record, with the backend that served it. Best-effort by
+            // the logger's own contract — an unwritable log must never lose a reply.
+            logGatewayEvent('inbound.chat', {
+                platform: msg.platform,
+                channelId: msg.channelId,
+                ...(answer.provider ? { provider: answer.provider } : {}),
+                ...(answer.model ? { model: answer.model } : {}),
+                ...(answer.transport ? { transport: answer.transport } : {}),
+                ...(toolCalls.length > 0 ? { toolCalls } : {}),
+                ...(findings.length > 0 ? { findings } : {}),
+                // WS5 (#27) — the isolation this turn had, and what it changed against
+                // its base commit. Durable, for the same reason the tool lifecycle and
+                // the findings are: a messaging surface has no terminal, so the log IS
+                // where an operator can see that an isolated turn ran and what it
+                // touched.
+                ...(answer.worktree ? { worktree: answer.worktree } : {}),
+                ...(answer.resume ? { resume: answer.resume } : {}),
+                generationFailed: answer.generationFailed === true,
+            });
+            return {
+                content,
+                generationFailed: answer.generationFailed,
+                ...(answer.provider ? { provider: answer.provider } : {}),
+                ...(answer.model ? { model: answer.model } : {}),
+                ...(answer.transport ? { transport: answer.transport } : {}),
+                ...(toolCalls.length > 0 ? { toolCalls } : {}),
+                ...(findings.length > 0 ? { findings } : {}),
+                ...(answer.worktree ? { worktree: answer.worktree } : {}),
+                ...(answer.resume ? { resume: answer.resume } : {}),
+            };
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -1774,6 +1977,23 @@ export class GatewayRegistry {
                 supervisorPid: process.ppid || undefined,
                 adapters: [...this.adapterHealth.values()],
             });
+            // Scheduled sandbox cleanup: extracted inbound attachments are kept for
+            // their TTL, then swept — throttled to hourly so the 15s liveness tick
+            // never walks the directory unnecessarily.
+            const now = Date.now();
+            if (now - this.lastInboundPruneAt >= INBOUND_PRUNE_INTERVAL_MS) {
+                this.lastInboundPruneAt = now;
+                try {
+                    const { pruneInboundMedia } = await import('./inbound-media.js');
+                    const pruned = pruneInboundMedia({ now });
+                    if (pruned.removed > 0) {
+                        logger.info(`gateway: pruned ${pruned.removed} inbound attachment(s) — ${Math.round(pruned.bytesFreed / 1024)} KB freed`);
+                    }
+                }
+                catch {
+                    /* best-effort sweep — never take the gateway down over cleanup */
+                }
+            }
         };
         // First beat immediately, so `gateway status` is honest within a second of
         // startup instead of reporting the previous run's stale beat.