feat(inference): opt-in failureNotices — tell the room when a turn produced nothing

changelog.d/feat-failure-notices.added.md

@@ -0,0 +1,4 @@
+- Opt-in `failureNotices`: when a turn fails outright (provider error,
+  refusal, over-budget), post a short automatic notice to the agent's locus on
+  the first failure of a streak and every 5th after, so people can tell a
+  dead turn from a quiet one.

src/agent.ts

@@ -84,6 +84,8 @@ export class Agent {
   readonly refusalHandling: AgentConfig['refusalHandling'];
   /** Prose delivery mode (see AgentConfig.proseRouting). Default 'locus'. */
   readonly proseRouting: 'locus' | 'explicit' | 'hybrid' | 'disabled';
+  /** Post a room notice when a turn fails (see AgentConfig.failureNotices). */
+  readonly failureNotices: boolean;
   /** Exact whole-response known-tool wrapper containment (default off). */
   readonly toolWrapperProseGuard: boolean;
   /** Prompt-cache TTL forwarded to the provider (see AgentConfig.cacheTtl). */
@@ -144,6 +146,7 @@ export class Agent {
     this.thinking = config.thinking;
     this.refusalHandling = config.refusalHandling;
     this.proseRouting = config.proseRouting ?? 'locus';
+    this.failureNotices = config.failureNotices === true;
     this.toolWrapperProseGuard = config.toolWrapperProseGuard ?? false;
     this.cacheTtl = config.cacheTtl ?? '1h';
     this.promptCaching = config.promptCaching ?? true;

src/framework.ts

@@ -11531,6 +11531,7 @@ export class AgentFramework {
 
     const streak = (this.refusalStreak.get(agentName) ?? 0) + 1;
     this.refusalStreak.set(agentName, streak);
+    this.postFailureNotice(agentName, streak, `the model declined to respond (safety category: ${category})`);
 
     this.logFailure({
       agent: agentName,
@@ -11591,6 +11592,30 @@ export class AgentFramework {
     this.opsAlert(kind, agentName, message, { data });
   }
 
+  /**
+   * AgentConfig.failureNotices: tell the ROOM when a turn produced nothing.
+   * The chronicle marker already tells the resident; without this, people
+   * see only silence and can't tell a dead turn from a quiet one. Posted on
+   * the first failure of a streak and every 5th after, so a stuck loop can't
+   * flood the channel. Best-effort: a notice that can't be delivered is
+   * dropped (the stderr/failures.log records remain).
+   */
+  private postFailureNotice(agentName: string, streak: number, what: string): void {
+    const agent = this.agents.get(agentName);
+    if (!agent?.failureNotices || !this.channelRegistry) return;
+    if (streak !== 1 && streak % 5 !== 0) return;
+    const locus = this.channelRegistry.resolveLocus(agentName) ?? null;
+    if (!locus) return;
+    const oneLine = what.replace(/\s+/g, ' ').trim();
+    const reason = oneLine.length > 160 ? `${oneLine.slice(0, 157)}…` : oneLine;
+    const text =
+      `⚠️ [automatic notice] ${agentName}'s reply failed to generate` +
+      `${streak > 1 ? ` (${streak} in a row)` : ''}: ${reason}. ` +
+      'Nothing was lost from the conversation; it will see this and your messages on its next turn.';
+    void this.channelRegistry.routeSpeech(agentName, text, locus)
+      .catch((err) => console.error(`[inference-failed] failure notice not delivered for ${agentName}:`, err));
+  }
+
   private noteInferenceExhausted(
     agentName: string,
     reason: string,
@@ -11603,6 +11628,7 @@ export class AgentFramework {
 
     // (1) Durable stderr line — works in headless/daemon mode with no client.
     console.error(`[inference-failed] agent=${agentName} consecutive=${streak}: ${reason}`);
+    this.postFailureNotice(agentName, streak, reason);
 
     // (1b) Machine-greppable durable record, independent of journald/unit log
     // redirects: logs/failures.log under the host's working directory. This is

src/types/agent.ts

@@ -185,6 +185,13 @@ export interface AgentConfig {
    */
   proseRouting?: 'locus' | 'explicit' | 'hybrid' | 'disabled';
 
+  /**
+   * Post a short automatic notice to the agent's speaking room when a turn
+   * fails outright (model call error, refusal, over-budget) — first failure
+   * of a streak and every 5th after. Default false.
+   */
+  failureNotices?: boolean;
+
   /**
    * Fail-closed containment for a text response whose entire visible prose is
    * an invocation-shaped wrapper naming a tool registered on that exact turn.

test/inference-failure-observability.test.ts

@@ -83,3 +83,24 @@ test('per-agent isolation: one agent failing does not flag another', () => {
   assert.equal(fw.consecutiveInferenceFailures.get('cairn'), 2);
   assert.equal(fw.consecutiveInferenceFailures.get('lena') ?? 0, 0);
 });
+
+test('failureNotices: room notice on failure 1 and every 5th; off by default', async () => {
+  const { fw, restore } = makeHarness();
+  const posted: Array<{ text: string; locus: string | null }> = [];
+  fw.channelRegistry = {
+    resolveLocus: () => 'discord:g:salon',
+    routeSpeech: async (_agent: string, text: string, locus: string | null) => { posted.push({ text, locus }); return { delivered: true }; },
+  };
+  const addMessage = () => {};
+  fw.agents.set('cairn', { failureNotices: true, getContextManager: () => ({ addMessage }) });
+  fw.agents.set('quiet', { failureNotices: false, getContextManager: () => ({ addMessage }) });
+  try {
+    for (let i = 0; i < 5; i++) fw.noteInferenceExhausted('cairn', '400 image/webp label but PNG bytes');
+    fw.noteInferenceExhausted('quiet', 'boom');
+  } finally { restore(); }
+  await new Promise((r) => setImmediate(r));
+  assert.equal(posted.length, 2, 'failure 1 and failure 5 only');
+  assert.equal(posted[0].locus, 'discord:g:salon');
+  assert.match(posted[0].text, /^⚠️ \[automatic notice\] cairn's reply failed to generate: 400 image\/webp/);
+  assert.match(posted[1].text, /\(5 in a row\)/);
+});