agent-nuvira 3.3.3 → 3.3.4

package/dist/tools/finding-tool.js

@@ -0,0 +1,125 @@
+/**
+ * WS1 (#23) — `finding`: the model states a CLAIM, the gate decides the VERDICT.
+ *
+ * WHY A TOOL, AND WHY IT DOES NOT ACCEPT A VERDICT. `src/findings/verdicts.ts`
+ * is the vocabulary and the gate; it deliberately does not decide who may
+ * produce a finding (`intent-confirm` produces one for a routing decision). This
+ * is the producer for an ORDINARY turn on every surface, and the one design rule
+ * that matters is here: the model may supply the claim, the outcome and the
+ * evidence, and must NOT be able to supply the verdict. A tool argument called
+ * `verdict` would be the exact bypass the gate exists to refuse — the model
+ * typing "CONFIRMED" is the false-success defect with a nicer name — so the
+ * parameter does not exist. `confirmFinding` promotes to CONFIRMED only when at
+ * least one non-blank evidence reference was supplied, and refuses otherwise
+ * with the reason attached.
+ *
+ * WHAT THE MODEL SEES BACK is the rendered finding (`describeFinding`), including
+ * the honest line for a PLAUSIBLE one ("no evidence — reported as PLAUSIBLE, not
+ * verified"). That is the point of returning the render rather than a summary: a
+ * model that states a claim with no evidence is told, in the tool result it must
+ * act on, that the claim was recorded as unverified rather than as fact.
+ *
+ * THE STRUCTURED COPY travels to the surface on the context bus as
+ * `finding:recorded` (the same mechanism `plan_todo` uses for `plan:changed`),
+ * so every surface reports the SAME wire form — which is what
+ * `findings-verdicts@<surface>` is proved against.
+ *
+ * A CALL THAT RECORDED NOTHING IS A FAILURE. A blank claim or a blank outcome
+ * returns `Error:` (the loop's own accounting is `ok: !startsWith('Error:')`),
+ * because a finding with no claim is not a finding — and reporting one as a
+ * successful call would be this repository's recurring defect in miniature.
+ */
+import { z } from 'zod';
+import { confirmFinding, describeFinding, plausibleFinding, toWire, } from '../findings/verdicts.js';
+/** The registry name — one place, so the toolset/core lists and the tests agree. */
+export const FINDING_TOOL_NAME = 'finding';
+/**
+ * The bus event carrying the structured wire finding.
+ *
+ * Named `finding:recorded` (past tense) on purpose: the event is emitted AFTER
+ * the gate has decided, so a listener never sees a claim whose verdict is still
+ * being computed — the same convention `plan:changed` follows.
+ */
+export const FINDING_EVENT = 'finding:recorded';
+/** The evidence kinds the model may cite (the closed set the gate normalises to). */
+const EVIDENCE_KINDS = ['quote', 'command', 'file', 'observation'];
+/** `finding` args. There is deliberately no `verdict` field — see the header. */
+export const findingSchema = z.object({
+    claim: z
+        .string()
+        .describe('What is being asserted, in the words the reader will see — e.g. "the login endpoint rejects an expired token".'),
+    outcome: z
+        .string()
+        .describe('What BECAME of the claim: verified, corrected, dropped, still open. A finding with no outcome is a status report, not a finding.'),
+    evidence: z
+        .array(z.object({
+        kind: z.enum(EVIDENCE_KINDS).describe('The sort of check that was performed.'),
+        ref: z
+            .string()
+            .describe('The evidence ITSELF — a verbatim quote from the input, the exact command line, the path that was read, or a value a probe returned. A restatement of the claim is not evidence, and a blank reference is not a check.'),
+        detail: z.string().optional().describe('Optional context: the command output, the surrounding line, why it matters.'),
+    }))
+        .optional()
+        .describe('The checks actually performed. Supply this and the finding is recorded CONFIRMED; omit it (or leave a reference blank) and it is recorded PLAUSIBLE, unverified — which is an honest, useful result, not an error.'),
+});
+/**
+ * Record one finding: build it PLAUSIBLE, let the gate decide, report it.
+ *
+ * Split out from the `Tool` wrapper so the behaviour is testable without the
+ * registry, and so a caller that already has a context (the child process) can
+ * reuse it.
+ */
+export function recordFinding(args, ctx) {
+    const claim = String(args?.claim ?? '').trim();
+    const outcome = String(args?.outcome ?? '').trim();
+    if (!claim) {
+        return {
+            error: "Error: finding needs a 'claim' — what is being asserted, in the words the user will read. " +
+                'A finding with no claim records nothing.',
+        };
+    }
+    if (!outcome) {
+        return {
+            error: "Error: finding needs an 'outcome' — what became of the claim (verified, corrected, dropped, still open). " +
+                'A finding with no outcome is a status report, not a finding.',
+        };
+    }
+    const evidence = (args.evidence ?? []);
+    // The gate, not the caller, decides. `confirmFinding` returns the finding
+    // STILL PLAUSIBLE (with the reason) when no usable evidence was supplied; that
+    // refusal is a normal outcome, so it is recorded in the outcome line rather
+    // than thrown.
+    const promotion = confirmFinding(plausibleFinding({ claim, outcome, source: 'agent', evidence }), [], { outcome });
+    const finding = promotion.promoted
+        ? promotion.finding
+        : promotion.reason
+            ? { ...promotion.finding, outcome: `${outcome} — ${promotion.reason}` }
+            : promotion.finding;
+    // Best-effort: a listener that is not there (a direct tool call, a test) must
+    // never break the tool, exactly like `plan_todo`'s snapshot emit.
+    try {
+        ctx?.emit?.(FINDING_EVENT, toWire(finding));
+    }
+    catch {
+        /* best-effort */
+    }
+    return { finding, text: describeFinding(finding) };
+}
+/** The `finding` tool as the registry takes it. */
+export function createFindingTool() {
+    return {
+        name: FINDING_TOOL_NAME,
+        description: 'Record one finding — a claim about the world, with a verdict you do NOT set. Supply `claim` + `outcome`, and `evidence` for anything you actually CHECKED (a command and its real output, a path you read, a quote from the request, a value a probe returned): usable evidence records the finding CONFIRMED, and no usable evidence records it PLAUSIBLE (an honest, useful result — never a failure). Use it whenever your answer asserts something a second party could check, so the user can tell what was verified from what is a reasoned guess.',
+        category: 'experience',
+        inputSchema: findingSchema,
+        endsAgentStep: false,
+        run: async (args, ctx) => {
+            const parsed = findingSchema.parse(args);
+            const result = recordFinding(parsed, ctx);
+            if ('error' in result)
+                return result.error;
+            return result.text;
+        },
+    };
+}
+//# sourceMappingURL=finding-tool.js.map

package/dist/tools/finding-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finding-tool.js","sourceRoot":"","sources":["../../src/tools/finding-tool.ts"],"names":[],"mappings":"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"}

package/dist/tools/messaging-tools.d.ts

@@ -4,11 +4,24 @@
  * Hermes equivalent: send_message_tool.py + react_to_message_tool.py + feishu_doc_tool.py + feishu_drive_tool.py
  *
  * Provides:
- * - Send messages to various platforms
- * - React to messages
+ * - Message history bookkeeping for outbound sends
  * - Feishu document integration
  * - Feishu drive integration
+ *
+ * DOES NOT PROVIDE: delivery to Discord / Slack / Telegram / WhatsApp / Feishu /
+ * webhooks. Every one of those senders used to answer
+ * `{ success: true, messageId: '<platform>_<timestamp>' }` without contacting
+ * anything, and `reactToMessage` answered `{ success: true }` unconditionally —
+ * so an agent could tell the user, honestly from its own point of view, that a
+ * message had been delivered to a third party when nothing left the machine.
+ * The real, authorization-gated sender is `gateway_send`
+ * (`src/tools/gateway-send.ts`); it is the tool whose result the honesty guard in
+ * `tool-loop.ts` trusts. These senders now refuse with `not_configured` and name
+ * it, so the model is steered to the path that can actually deliver.
+ *
+ * See TOOL_TRUTHFULNESS_TRACKER.md (findings #3 and #9).
  */
+import { type ToolRefusalCode } from './tool-refusal.js';
 export interface MessageTarget {
     /** Platform */
     platform: 'discord' | 'slack' | 'telegram' | 'whatsapp' | 'feishu' | 'webhook';
@@ -78,23 +91,40 @@ export interface FeishuDriveFile {
     /** Updated at */
     updatedAt: number;
 }
+/**
+ * The result of an outbound send. `success: false` carries a typed `code` and the
+ * alternatives a caller can take instead — never a synthetic `messageId`.
+ */
+export interface SendResult {
+    success: boolean;
+    /** Present ONLY when a platform adapter actually delivered the message. */
+    messageId?: string;
+    code?: ToolRefusalCode;
+    alternatives?: string[];
+    error?: string;
+}
 export declare class MessagingManager {
     private messageHistory;
+    /**
+     * The one refusal every platform sender returns: this manager has no adapter.
+     * Kept in a single place so a future reader cannot re-introduce a per-platform
+     * fake success without deleting the shared reason that explains why.
+     */
+    private notConfigured;
     /**
      * Send a message to a platform.
+     *
+     * Records the attempt in history ONLY when a platform adapter reported success,
+     * so `getHistory()` can never list a message that was never delivered.
      */
-    sendMessage(target: MessageTarget, options: SendMessageOptions): Promise<{
-        success: boolean;
-        messageId?: string;
-        error?: string;
-    }>;
+    sendMessage(target: MessageTarget, options: SendMessageOptions): Promise<SendResult>;
     /**
      * React to a message.
+     *
+     * No adapter exists for reactions, so this refuses. It used to return
+     * `{ success: true }` and the registry turned that into the string 'Reacted'.
      */
-    reactToMessage(platform: string, channelId: string, messageId: string, emoji: string): Promise<{
-        success: boolean;
-        error?: string;
-    }>;
+    reactToMessage(platform: string, channelId: string, messageId: string, emoji: string): Promise<SendResult>;
     /**
      * Get message history.
      */

package/dist/tools/messaging-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"messaging-tools.d.ts","sourceRoot":"","sources":["../../src/tools/messaging-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,MAAM,WAAW,aAAa;IAC5B,eAAe;IACf,QAAQ,EAAE,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC/E,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;IACtC,kBAAkB;IAClB,WAAW,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClE,gCAAgC;IAChC,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxF;AAED,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,iBAAiB;IACjB,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IAC/D,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc;IACd,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,uBAAuB;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,cAAc,CAMd;IAER;;OAEG;IACG,WAAW,CACf,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IA+BpE;;OAEG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAOhD;;OAEG;IACH,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,KAAK,CAAC;QAC3E,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;YASY,WAAW;YAMX,SAAS;YAKT,YAAY;YAKZ,YAAY;YAKZ,UAAU;YAKV,WAAW;CAI1B;AAID,qBAAa,qBAAqB;IAChC,OAAO,CAAC,SAAS,CAA0C;IAE3D;;OAEG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,WAAW,EAAO,GAAG,cAAc;IAYzE;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAItD;;OAEG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO;IAQlE;;OAEG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IA0BnD;;OAEG;IACH,aAAa,IAAI,cAAc,EAAE;CAGlC;AAID,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,KAAK,CAA2C;IAExD;;OAEG;IACH,SAAS,CAAC,QAAQ,GAAE,MAAe,GAAG,eAAe,EAAE;IAMvD;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAI/C;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,EAAE;IAM7C;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe;IAcrG;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAInC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,OAAO;CAO7D;AAQD,wBAAgB,mBAAmB,IAAI,gBAAgB,CAGtD;AAED,wBAAgB,wBAAwB,IAAI,qBAAqB,CAGhE;AAED,wBAAgB,qBAAqB,IAAI,kBAAkB,CAG1D"}
+{"version":3,"file":"messaging-tools.d.ts","sourceRoot":"","sources":["../../src/tools/messaging-tools.ts"],"names":[],"mappings":"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"}

package/dist/tools/messaging-tools.js

@@ -4,55 +4,107 @@
  * Hermes equivalent: send_message_tool.py + react_to_message_tool.py + feishu_doc_tool.py + feishu_drive_tool.py
  *
  * Provides:
- * - Send messages to various platforms
- * - React to messages
+ * - Message history bookkeeping for outbound sends
  * - Feishu document integration
  * - Feishu drive integration
+ *
+ * DOES NOT PROVIDE: delivery to Discord / Slack / Telegram / WhatsApp / Feishu /
+ * webhooks. Every one of those senders used to answer
+ * `{ success: true, messageId: '<platform>_<timestamp>' }` without contacting
+ * anything, and `reactToMessage` answered `{ success: true }` unconditionally —
+ * so an agent could tell the user, honestly from its own point of view, that a
+ * message had been delivered to a third party when nothing left the machine.
+ * The real, authorization-gated sender is `gateway_send`
+ * (`src/tools/gateway-send.ts`); it is the tool whose result the honesty guard in
+ * `tool-loop.ts` trusts. These senders now refuse with `not_configured` and name
+ * it, so the model is steered to the path that can actually deliver.
+ *
+ * See TOOL_TRUTHFULNESS_TRACKER.md (findings #3 and #9).
  */
 import { logger } from '../utils/logger.js';
+import { refusalFields } from './tool-refusal.js';
 // ─── Messaging Manager ────────────────────────────────────────────────────
 export class MessagingManager {
     messageHistory = [];
+    /**
+     * The one refusal every platform sender returns: this manager has no adapter.
+     * Kept in a single place so a future reader cannot re-introduce a per-platform
+     * fake success without deleting the shared reason that explains why.
+     */
+    notConfigured(platform, channelId) {
+        return {
+            success: false,
+            error: `No messaging adapter is configured for ${platform} (channel ${channelId}), so nothing was sent. ` +
+                'Use gateway_send — it delivers through the configured gateway and returns an explicit sent/refused result.',
+            ...refusalFields('not_configured', [
+                'gateway_send — sends via the configured gateway (WhatsApp / Telegram / Slack / Discord by name or number)',
+                'nuvira gateway send <platform:channel> <message> — the CLI equivalent',
+            ]),
+        };
+    }
     /**
      * Send a message to a platform.
+     *
+     * Records the attempt in history ONLY when a platform adapter reported success,
+     * so `getHistory()` can never list a message that was never delivered.
      */
     async sendMessage(target, options) {
-        const historyEntry = {
-            platform: target.platform,
-            channelId: target.channelId,
-            content: options.content,
-            timestamp: Date.now(),
-        };
-        try {
-            // Route to platform-specific handler
-            switch (target.platform) {
-                case 'discord':
-                    return await this.sendDiscord(target, options);
-                case 'slack':
-                    return await this.sendSlack(target, options);
-                case 'telegram':
-                    return await this.sendTelegram(target, options);
-                case 'whatsapp':
-                    return await this.sendWhatsApp(target, options);
-                case 'feishu':
-                    return await this.sendFeishu(target, options);
-                case 'webhook':
-                    return await this.sendWebhook(target, options);
-                default:
-                    return { success: false, error: `Unsupported platform: ${target.platform}` };
-            }
+        let result;
+        switch (target.platform) {
+            case 'discord':
+                result = await this.sendDiscord(target, options);
+                break;
+            case 'slack':
+                result = await this.sendSlack(target, options);
+                break;
+            case 'telegram':
+                result = await this.sendTelegram(target, options);
+                break;
+            case 'whatsapp':
+                result = await this.sendWhatsApp(target, options);
+                break;
+            case 'feishu':
+                result = await this.sendFeishu(target, options);
+                break;
+            case 'webhook':
+                result = await this.sendWebhook(target, options);
+                break;
+            default:
+                result = {
+                    success: false,
+                    error: `Unsupported platform: ${target.platform}`,
+                    ...refusalFields('unsupported_format'),
+                };
+        }
+        if (result.success) {
+            this.messageHistory.push({
+                platform: target.platform,
+                channelId: target.channelId,
+                content: options.content,
+                timestamp: Date.now(),
+                messageId: result.messageId,
+            });
         }
-        finally {
-            this.messageHistory.push(historyEntry);
+        else {
+            logger.warn(`Messaging: refused ${target.platform} send to ${target.channelId} — ${result.error}`);
         }
+        return result;
     }
     /**
      * React to a message.
+     *
+     * No adapter exists for reactions, so this refuses. It used to return
+     * `{ success: true }` and the registry turned that into the string 'Reacted'.
      */
     async reactToMessage(platform, channelId, messageId, emoji) {
-        logger.info(`Messaging: Reacting with ${emoji} to message ${messageId} on ${platform}`);
-        // In a real implementation, this would call the platform API
-        return { success: true };
+        logger.warn(`Messaging: reaction not sent (no adapter) — ${emoji} on ${messageId} in ${platform}/${channelId}`);
+        return {
+            success: false,
+            error: `No messaging adapter is configured for ${platform}, so the reaction was NOT applied to ${messageId}.`,
+            ...refusalFields('not_configured', [
+                'Report the reaction as not sent, or send the message text instead via gateway_send',
+            ]),
+        };
     }
     /**
      * Get message history.
@@ -66,30 +118,27 @@ export class MessagingManager {
         return history.slice(-limit);
     }
     // ─── Platform Handlers ─────────────────────────────────────────────
-    async sendDiscord(target, options) {
-        logger.info(`Discord: Sending message to channel ${target.channelId}`);
-        // In production, this would call Discord API
-        return { success: true, messageId: `discord_${Date.now()}` };
-    }
-    async sendSlack(target, options) {
-        logger.info(`Slack: Sending message to channel ${target.channelId}`);
-        return { success: true, messageId: `slack_${Date.now()}` };
-    }
-    async sendTelegram(target, options) {
-        logger.info(`Telegram: Sending message to chat ${target.channelId}`);
-        return { success: true, messageId: `telegram_${Date.now()}` };
-    }
-    async sendWhatsApp(target, options) {
-        logger.info(`WhatsApp: Sending message to chat ${target.channelId}`);
-        return { success: true, messageId: `whatsapp_${Date.now()}` };
-    }
-    async sendFeishu(target, options) {
-        logger.info(`Feishu: Sending message to chat ${target.channelId}`);
-        return { success: true, messageId: `feishu_${Date.now()}` };
-    }
-    async sendWebhook(target, options) {
-        logger.info(`Webhook: Sending message to ${target.channelId}`);
-        return { success: true, messageId: `webhook_${Date.now()}` };
+    //
+    // Each returns `notConfigured(...)`. The per-platform shape is kept so a real
+    // adapter can be dropped in per platform without touching the dispatcher; until
+    // one exists, the honest answer is the same for all six.
+    async sendDiscord(target, _options) {
+        return this.notConfigured('discord', target.channelId);
+    }
+    async sendSlack(target, _options) {
+        return this.notConfigured('slack', target.channelId);
+    }
+    async sendTelegram(target, _options) {
+        return this.notConfigured('telegram', target.channelId);
+    }
+    async sendWhatsApp(target, _options) {
+        return this.notConfigured('whatsapp', target.channelId);
+    }
+    async sendFeishu(target, _options) {
+        return this.notConfigured('feishu', target.channelId);
+    }
+    async sendWebhook(target, _options) {
+        return this.notConfigured('webhook', target.channelId);
     }
 }
 // ─── Feishu Document Manager ──────────────────────────────────────────────

package/dist/tools/messaging-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"messaging-tools.js","sourceRoot":"","sources":["../../src/tools/messaging-tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"messaging-tools.js","sourceRoot":"","sources":["../../src/tools/messaging-tools.ts"],"names":[],"mappings":"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"}

package/dist/tools/neutts-synth.d.ts

@@ -1,14 +1,29 @@
 /**
- * NeuTTS Synthesis — High-quality text-to-speech.
+ * NeuTTS Synthesis — text-to-speech.
  *
  * Hermes equivalent: neutts_synth.py (110 lines)
  *
  * Provides:
- * - High-quality TTS synthesis
+ * - API-backed synthesis when NEUTTS_API_KEY (or an injected key) is set
  * - Multiple voice options
- * - SSML support
  * - Audio file output
+ *
+ * WHEN NO BACKEND IS CONFIGURED it does NOT fall back to writing audio: the old
+ * fallback wrote a valid, silent WAV (44-byte header + a zeroed sample buffer) and
+ * returned it as a successful synthesis with duration/voice/text metadata. Anything
+ * downstream — a gateway that sends the file, an agent that reports "the audio is
+ * ready" — then acted on silence that looked like speech. Silence is now an
+ * explicit opt-in (BUFF_NEUTTS_ALLOW_SILENT) and never the default.
+ *
+ * See TOOL_TRUTHFULNESS_TRACKER.md finding #5.
+ */
+import { type ToolRefusal } from './tool-refusal.js';
+/**
+ * Whether a silent placeholder WAV may stand in for speech. Opt-in only
+ * (`BUFF_NEUTTS_ALLOW_SILENT=1`) — the point of the refusal is that silence must
+ * never be mistaken for synthesis. Exported for tests.
  */
+export declare function allowSilentFallback(): boolean;
 export interface NeuTTSConfig {
     /** API key for NeuTTS */
     apiKey?: string;
@@ -23,6 +38,15 @@ export interface SynthesisResult {
     durationMs: number;
     voice: string;
     text: string;
+    ok: boolean;
+    /**
+     * True when the audio is a silent placeholder rather than synthesised speech.
+     * Only ever set behind the BUFF_NEUTTS_ALLOW_SILENT opt-in.
+     */
+    silent?: boolean;
+    code?: ToolRefusal['code'];
+    alternatives?: string[];
+    error?: string;
 }
 export declare class NeuTTSSynthesizer {
     private config;

package/dist/tools/neutts-synth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"neutts-synth.d.ts","sourceRoot":"","sources":["../../src/tools/neutts-synth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH,MAAM,WAAW,YAAY;IAC3B,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uBAAuB;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAID,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,GAAE,YAAiB;IAQrC;;OAEG;IACG,UAAU,CACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAChF,OAAO,CAAC,eAAe,CAAC;IAmB3B;;OAEG;YACW,gBAAgB;IAqC9B;;OAEG;YACW,eAAe;IAsC7B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAqBnF;AAMD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,iBAAiB,CAG7E;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}
+{"version":3,"file":"neutts-synth.d.ts","sourceRoot":"","sources":["../../src/tools/neutts-synth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEpE;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAG7C;AAID,MAAM,WAAW,YAAY;IAC3B,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uBAAuB;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,GAAE,YAAiB;IAQrC;;OAEG;IACG,UAAU,CACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAChF,OAAO,CAAC,eAAe,CAAC;IA2C3B;;OAEG;YACW,gBAAgB;IAsC9B;;OAEG;YACW,eAAe;IAyC7B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAmBnF;AAMD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,iBAAiB,CAG7E;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/tools/neutts-synth.js

@@ -1,19 +1,38 @@
 /**
- * NeuTTS Synthesis — High-quality text-to-speech.
+ * NeuTTS Synthesis — text-to-speech.
  *
  * Hermes equivalent: neutts_synth.py (110 lines)
  *
  * Provides:
- * - High-quality TTS synthesis
+ * - API-backed synthesis when NEUTTS_API_KEY (or an injected key) is set
  * - Multiple voice options
- * - SSML support
  * - Audio file output
+ *
+ * WHEN NO BACKEND IS CONFIGURED it does NOT fall back to writing audio: the old
+ * fallback wrote a valid, silent WAV (44-byte header + a zeroed sample buffer) and
+ * returned it as a successful synthesis with duration/voice/text metadata. Anything
+ * downstream — a gateway that sends the file, an agent that reports "the audio is
+ * ready" — then acted on silence that looked like speech. Silence is now an
+ * explicit opt-in (BUFF_NEUTTS_ALLOW_SILENT) and never the default.
+ *
+ * See TOOL_TRUTHFULNESS_TRACKER.md finding #5.
  */
 import { randomUUID } from 'node:crypto';
 import { writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { logger } from '../utils/logger.js';
+import { envBuff } from '../config/paths.js';
+import { refusalFields } from './tool-refusal.js';
+/**
+ * Whether a silent placeholder WAV may stand in for speech. Opt-in only
+ * (`BUFF_NEUTTS_ALLOW_SILENT=1`) — the point of the refusal is that silence must
+ * never be mistaken for synthesis. Exported for tests.
+ */
+export function allowSilentFallback() {
+    const v = envBuff('NEUTTS_ALLOW_SILENT');
+    return v === '1' || v === 'true' || v === 'yes';
+}
 // ─── NeuTTS Synthesizer ──────────────────────────────────────────────────
 export class NeuTTSSynthesizer {
     config;
@@ -33,17 +52,40 @@ export class NeuTTSSynthesizer {
         const voice = options.voice || this.config.defaultVoice;
         const format = options.format || 'wav';
         const audioPath = join(this.outputDir, `${id}.${format}`);
-        // Try to use external TTS API if configured
+        // 1. The real backend, when one is configured.
+        let failureReason = 'No NeuTTS API key is configured (NEUTTS_API_KEY).';
         if (this.config.apiKey) {
             try {
                 return await this.synthesizeViaAPI(text, voice, audioPath, options);
             }
             catch (err) {
-                logger.warn(`[neutts] API synthesis failed, falling back to local: ${err}`);
+                failureReason = `NeuTTS API synthesis failed: ${err instanceof Error ? err.message : String(err)}`;
+                logger.warn(`[neutts] ${failureReason}`);
             }
         }
-        // Fallback: generate placeholder audio
-        return this.synthesizeLocal(text, voice, audioPath, options);
+        // 2. No real audio. Write a silent placeholder ONLY when the operator asked for
+        //    it — a silent WAV reported as a successful synthesis is a lie the caller
+        //    cannot detect, so it is never the default.
+        if (allowSilentFallback()) {
+            logger.warn(`[neutts] writing SILENT placeholder audio (BUFF_NEUTTS_ALLOW_SILENT is set) — ${failureReason}`);
+            return this.synthesizeLocal(text, voice, audioPath, options);
+        }
+        // 3. Refuse: say what is missing and what to use instead.
+        const reason = `No speech was synthesised. ${failureReason}`;
+        logger.warn(`[neutts] synthesis refused — ${failureReason}`);
+        return {
+            id,
+            audioPath: '',
+            durationMs: 0,
+            voice,
+            text,
+            ok: false,
+            error: reason,
+            ...refusalFields('not_configured', [
+                'Set NEUTTS_API_KEY to enable API-backed synthesis',
+                'Use the `speak` tool — it uses the configured local TTS backend (piper) when available',
+            ]),
+        };
     }
     /**
      * Synthesize via external API.
@@ -74,6 +116,7 @@ export class NeuTTSSynthesizer {
             durationMs: Math.round((buffer.byteLength / (16000 * 2)) * 1000),
             voice,
             text,
+            ok: true,
         };
     }
     /**
@@ -106,6 +149,9 @@ export class NeuTTSSynthesizer {
             durationMs: Math.round(durationSec * 1000),
             voice,
             text,
+            ok: true,
+            // Flagged so a caller (or the user) can see the file is silence, not speech.
+            silent: true,
         };
     }
     /**
@@ -125,12 +171,10 @@ export class NeuTTSSynthesizer {
                 // Ignore
             }
         }
-        // Default voices
-        return [
-            { id: 'default', name: 'Default', language: 'en-US' },
-            { id: 'female-1', name: 'Female 1', language: 'en-US' },
-            { id: 'male-1', name: 'Male 1', language: 'en-US' },
-        ];
+        // No backend → no voices. This used to return three invented voice ids
+        // ('default', 'female-1', 'male-1') that no configured backend could honour, so
+        // a caller could pick one and only discover it was fictitious after synthesis.
+        return [];
     }
 }
 // ─── Singleton ─────────────────────────────────────────────────────────────