@kaleidorg/mind 0.6.4 → 0.8.0

package/src/engine.test.ts

@@ -111,8 +111,8 @@ describe('Engine agentic loop', () => {
     const res = await engine.runAgentic([{ role: 'user', content: 'pay lnbc1' }], { onConfirm });
 
     expect(payTool.handler).not.toHaveBeenCalled();
-    expect(res.toolCalls[0].result).toMatchObject({ declined: true, reason: 'cancelled' });
-    expect(res.text).toBe('Okay, cancelled.');
+    expect(res.toolCalls[0].result).toMatchObject({ status: 'cancelled_by_user', declined_by: 'user', host_reason: 'cancelled' });
+    expect(res.text).toBe('Cancelled — you declined: pay invoice. Nothing was sent or changed.');
   });
 
   it('chains multiple tool calls across turns', async () => {
@@ -138,7 +138,9 @@ describe('Engine agentic loop', () => {
   it('stops at maxTurns if the model never stops calling tools', async () => {
     const engine = new Engine({
       provider: scriptedProvider([
-        { text: 'loop', toolCalls: [{ name: 'get_balance', arguments: {} }] }, // always calls a tool
+        { text: 'loop', toolCalls: [{ name: 'get_balance', arguments: { n: 1 } }] },
+        { text: 'loop', toolCalls: [{ name: 'get_balance', arguments: { n: 2 } }] },
+        { text: 'loop', toolCalls: [{ name: 'get_balance', arguments: { n: 3 } }] },
       ]),
       tools: freshTools(),
       defaultMaxTurns: 3,
@@ -205,6 +207,95 @@ describe('Engine agentic loop', () => {
     expect(res.toolCalls[0].result).toMatchObject({ error: 'kaboom' });
     expect(res.text).toBe('handled the error');
   });
+
+  it('sends firstTurnToolChoice on the first call only', async () => {
+    const seen: Array<string | undefined> = [];
+    const provider: LLMProvider = {
+      name: 'rec',
+      async runTurn(input) {
+        seen.push(input.toolChoice);
+        return seen.length === 1
+          ? { text: '', rawContent: '', toolCalls: [{ name: 'get_balance', arguments: {} }] }
+          : { text: 'done', rawContent: 'done', toolCalls: [] };
+      },
+    };
+    const engine = new Engine({ provider, tools: freshTools() });
+    await engine.runAgentic([{ role: 'user', content: 'send 1000 sats' }], { firstTurnToolChoice: 'required' });
+    expect(seen).toEqual(['required', undefined]);
+  });
+
+  it('feeds an unparseable tool call back to the model once, then gives up cleanly', async () => {
+    const histories: number[] = [];
+    const provider: LLMProvider = {
+      name: 'broken',
+      async runTurn(input) {
+        histories.push(input.messages.length);
+        return {
+          text: '<tool_call>{"ticker":"HCK',
+          rawContent: '<tool_call>{"ticker":"HCK',
+          toolCalls: [],
+          toolErrors: [{ code: 'PARSE_ERROR', message: 'unterminated string' }],
+        };
+      },
+    };
+    const engine = new Engine({ provider, tools: freshTools() });
+    const res = await engine.runAgentic([{ role: 'user', content: 'issue HCK' }]);
+    expect(histories).toEqual([1, 3]);
+    expect(res.text).not.toContain('tool_call');
+    expect(res.text).toMatch(/couldn't put together a valid request/i);
+  });
+
+  it('does not count the retry against maxTurns and explains a cut-off call', async () => {
+    const seen: string[] = [];
+    let n = 0;
+    const provider: LLMProvider = {
+      name: 'cutoff',
+      async runTurn(input) {
+        n += 1;
+        seen.push(input.messages[input.messages.length - 1]!.content);
+        if (n === 1) return { text: '', rawContent: '', toolCalls: [{ name: 'get_balance', arguments: {} }] };
+        if (n === 2) {
+          return {
+            text: '', rawContent: '<tool_call>{"name":"get_balance"', toolCalls: [],
+            toolErrors: [{ code: 'PARSE_ERROR', message: 'eof' }],
+            inference: { durationMs: 1, status: 'truncated' },
+          };
+        }
+        return { text: 'You have 50,000 sats.', rawContent: '', toolCalls: [] };
+      },
+    };
+    const engine = new Engine({ provider, tools: freshTools() });
+    const res = await engine.runAgentic([{ role: 'user', content: 'balance?' }], { maxTurns: 2 });
+    expect(res.text).toBe('You have 50,000 sats.');
+    expect(seen[2]).toMatch(/cut off/);
+  });
+
+  it('never returns an empty answer', async () => {
+    const engine = new Engine({ provider: scriptedProvider([{ text: '' }]), tools: freshTools() });
+    const res = await engine.runAgentic([{ role: 'user', content: 'hi' }]);
+    expect(res.text).toMatch(/had to stop/);
+  });
+
+  it('recovers when the retried call parses', async () => {
+    const engine = new Engine({
+      provider: (() => {
+        let n = 0;
+        return {
+          name: 'retry',
+          async runTurn(): Promise<TurnOutput> {
+            n += 1;
+            if (n === 1) return { text: 'x', rawContent: 'x', toolCalls: [], toolErrors: [{ code: 'PARSE_ERROR', message: 'bad' }] };
+            if (n === 2) return { text: '', rawContent: '', toolCalls: [{ name: 'get_balance', arguments: {} }] };
+            return { text: 'You have 50,000 sats.', rawContent: '', toolCalls: [] };
+          },
+        };
+      })(),
+      tools: freshTools(),
+    });
+    const res = await engine.runAgentic([{ role: 'user', content: 'balance?' }]);
+    expect(balanceTool.handler).toHaveBeenCalledTimes(1);
+    expect(res.text).toBe('You have 50,000 sats.');
+  });
 });
 
 describe('ToolRegistry', () => {

package/src/engine.ts

@@ -16,9 +16,25 @@
 
 import type { ConfirmDecision, Message, ToolResult } from './types.js';
 import type { LLMProvider } from './providers/types.js';
-import type { InferenceMetrics } from './providers/types.js';
+import type { InferenceMetrics, ToolCallError, ToolChoice } from './providers/types.js';
 import type { ToolRegistry } from './tools/registry.js';
 import { compressToolResult, type ToolCrushOptions } from './context/compress.js';
+import {
+  callKey,
+  declinedToolResult,
+  detectWalletAction,
+  hasCapableTool,
+  noToolReply,
+  findUngroundedPaymentData,
+  fixSatsBtcConversions,
+  ungroundedReply,
+  validateToolArgs,
+} from './guards.js';
+import { confirmReadback } from './wallet/confirm.js';
+import { annotateRgbBalances, fixRgbBalanceUnits } from './context/rgb-units.js';
+import type { SkillRegistry } from './skills/registry.js';
+import type { Skill } from './skills/types.js';
+import { selectAvailableSkill } from './skills/select.js';
 
 export interface EngineOptions {
   provider: LLMProvider;
@@ -36,6 +52,31 @@ export interface EngineOptions {
    * The `onToolResult` callback and `toolCalls` still carry the raw result.
    */
   compressToolOutput?: boolean | ToolCrushOptions;
+  /**
+   * Replace a final answer that contains an invoice/address/payment request no
+   * tool returned and the user never typed. Default true.
+   */
+  guardUngroundedPaymentData?: boolean;
+  /**
+   * Keep amounts honest: recompute BTC figures paired with a sats amount, add
+   * `balance_display` to RGB asset balances the model sees, and relabel an
+   * asset balance the answer calls sats. Default true.
+   */
+  fixAmountConversions?: boolean;
+  /**
+   * Answer a wallet action (create an invoice, get an address, pay, send) with
+   * a fixed "no tool" reply, without inference, when no exposed tool can do it.
+   * Default true.
+   */
+  guardMissingTools?: boolean;
+  /** End the run with a fixed "Cancelled" reply when the user declines every call in a turn. Default true. */
+  endTurnOnDecline?: boolean;
+}
+
+export interface ComposedSkill {
+  skill: Skill | null;
+  system: string;
+  allowedTools?: string[];
 }
 
 export interface AgenticOptions {
@@ -52,12 +93,18 @@ export interface AgenticOptions {
    */
   onToolResult?: (event: { name: string; arguments: Record<string, unknown>; result: unknown }, turn: number) => void;
   /** Human-in-the-loop gate for tools flagged requiresConfirmation. */
-  onConfirm?: (call: { name: string; arguments: Record<string, unknown> }) => Promise<ConfirmDecision>;
+  onConfirm?: (call: { name: string; arguments: Record<string, unknown>; summary?: string }) => Promise<ConfirmDecision>;
   /**
    * Restrict the tools exposed to the model this run (progressive disclosure).
    * Typically the active skill's tool list — see SkillRegistry.compose().
    */
   allowedTools?: string[];
+  /**
+   * Tool choice for the FIRST model call only — e.g. `'required'` when the
+   * request is a wallet action, so the model can't answer in prose with
+   * made-up data. Later rounds are left to the model.
+   */
+  firstTurnToolChoice?: ToolChoice;
   signal?: AbortSignal;
 }
 
@@ -74,18 +121,39 @@ export interface AgenticResult {
   inference: InferenceMetrics[];
 }
 
+const STOPPED_MESSAGE = 'I had to stop after several steps — please try a more specific request.';
+
+const TOOL_CALL_FAILED_MESSAGE =
+  "I couldn't put together a valid request for that. Please rephrase it with the exact values (asset, amount, recipient).";
+
+function toolErrorMessage(errors: ToolCallError[], cutOff: boolean): string {
+  if (cutOff) {
+    return 'Your tool call was cut off because the output got too long. Make ONE tool call at a time with only the required arguments, or answer from the results you already have.';
+  }
+  const detail = errors.map((e) => e.message).join('; ');
+  return `Your tool call could not be read (${detail}). Call the tool again with valid JSON arguments that match its schema, or ask the user for the missing values.`;
+}
+
 export class Engine {
   private readonly provider: LLMProvider;
   private readonly registry: ToolRegistry;
   private readonly defaultSystem?: string;
   private readonly defaultMaxTurns: number;
   private readonly compressOpts?: ToolCrushOptions;
+  private readonly guardPaymentData: boolean;
+  private readonly fixAmounts: boolean;
+  private readonly guardMissingTools: boolean;
+  private readonly endTurnOnDecline: boolean;
 
   constructor(opts: EngineOptions) {
     this.provider = opts.provider;
     this.registry = opts.tools;
     this.defaultSystem = opts.defaultSystem;
     this.defaultMaxTurns = opts.defaultMaxTurns ?? 5;
+    this.guardPaymentData = opts.guardUngroundedPaymentData ?? true;
+    this.fixAmounts = opts.fixAmountConversions ?? true;
+    this.guardMissingTools = opts.guardMissingTools ?? true;
+    this.endTurnOnDecline = opts.endTurnOnDecline ?? true;
     this.compressOpts = opts.compressToolOutput
       ? opts.compressToolOutput === true
         ? {}
@@ -93,6 +161,19 @@ export class Engine {
       : undefined;
   }
 
+  /**
+   * Select the skill for `query` among those that can act with this engine's
+   * tools (skills whose `requires-tools` are missing are skipped), then
+   * compose its system prompt. Pass the result to runAgentic:
+   *
+   *   const { system, allowedTools } = await engine.composeSkill(skills, question, base);
+   *   await engine.runAgentic([{ role: 'system', content: system }, { role: 'user', content: question }], { allowedTools });
+   */
+  async composeSkill(skills: SkillRegistry, query: string, base: string): Promise<ComposedSkill> {
+    const skill = selectAvailableSkill(skills, query, await this.registry.listTools());
+    return { skill, ...skills.compose(base, skill) };
+  }
+
   async runAgentic(messages: Message[], opts: AgenticOptions = {}): Promise<AgenticResult> {
     const maxTurns = opts.maxTurns ?? this.defaultMaxTurns;
     const hasSystem = messages.some((m) => m.role === 'system');
@@ -108,10 +189,24 @@ export class Engine {
     const executed: ToolResult[] = [];
     let lastRequestId: string | undefined;
     let finalText = '';
+    // Set when finalText is one of the engine's own fixed replies, which the
+    // answer guards below must not rewrite.
+    let engineReply = false;
     let turns = 0;
     const inference: InferenceMetrics[] = [];
+    const seen = new Map<string, { result: unknown; count: number }>();
+    let toolErrorRetries = 0;
+
+    const lastUser = [...messages].reverse().find((m) => m.role === 'user')?.content ?? '';
+    const action = this.guardMissingTools ? detectWalletAction(lastUser) : null;
+    if (action && !hasCapableTool(action, allTools.map((t) => t.name))) {
+      const text = noToolReply(action);
+      history.push({ role: 'assistant', content: text });
+      return { text, turns: 0, toolCalls: [], messages: history, latencyMs: Date.now() - startedAt, inference };
+    }
 
-    for (let turn = 1; turn <= maxTurns; turn++) {
+    // A retry after an unreadable tool call does not count against maxTurns.
+    for (let turn = 1; turn <= maxTurns + toolErrorRetries; turn++) {
       turns = turn;
       if (opts.signal?.aborted) break;
 
@@ -119,6 +214,9 @@ export class Engine {
         messages: history,
         tools: allTools,
         system,
+        ...(turn === 1 && opts.firstTurnToolChoice && allTools.length
+          ? { toolChoice: opts.firstTurnToolChoice }
+          : {}),
         onToken: opts.onToken ? (t) => opts.onToken!(t, turn) : undefined,
         signal: opts.signal,
       });
@@ -126,40 +224,125 @@ export class Engine {
       lastRequestId = out.requestId;
       if (out.inference) inference.push(out.inference);
       if (out.requestId) opts.onStart?.(out.requestId, turn);
-      finalText = (out.text || '').trim();
+      finalText = out.incomplete ? '' : (out.text || '').trim();
+
+      // The model tried to call a tool but the call didn't parse: tell it what
+      // went wrong and let it try again (once) instead of showing the broken
+      // frame as the answer.
+      if ((!out.toolCalls || out.toolCalls.length === 0) && out.toolErrors?.length) {
+        if (toolErrorRetries < 1) {
+          toolErrorRetries += 1;
+          const cutOff = out.inference?.status === 'truncated';
+          history.push({ role: 'assistant', content: out.rawContent || finalText });
+          history.push({ role: 'tool', content: JSON.stringify({ error: toolErrorMessage(out.toolErrors, cutOff) }) });
+          continue;
+        }
+        finalText = TOOL_CALL_FAILED_MESSAGE;
+        engineReply = true;
+        break;
+      }
 
       // No tool calls ⇒ the model produced its final answer.
-      if (!out.toolCalls || out.toolCalls.length === 0) break;
+      if (!out.toolCalls || out.toolCalls.length === 0) {
+        if (!finalText && executed.length) finalText = await this.recoverAnswer(history, system, executed, inference, opts, turn);
+        else if (!finalText && out.incomplete) finalText = (out.text || '').trim();
+        break;
+      }
 
       // Anchor the next turn with the raw assistant frame.
       history.push({ role: 'assistant', content: out.rawContent || finalText });
 
+      let repeatedAgain = false;
+      const declinedThisTurn: string[] = [];
       for (const call of out.toolCalls) {
         opts.onToolCall?.({ name: call.name, arguments: call.arguments }, turn);
         const def = await this.registry.getDef(call.name);
+        const key = callKey(call.name, call.arguments);
+        const previous = seen.get(key);
 
+        let args = call.arguments;
         let result: unknown;
-        if (def?.requiresConfirmation) {
-          const decision = opts.onConfirm
-            ? await opts.onConfirm({ name: call.name, arguments: call.arguments })
-            : { approved: false, reason: 'no confirmation handler available' };
-          if (decision.approved) {
-            result = await this.safeExecute(call.name, call.arguments);
+        if (previous) {
+          previous.count += 1;
+          if (previous.count > 2) repeatedAgain = true;
+          result = {
+            error:
+              `You already called ${call.name} with these arguments; the result was: ` +
+              `${this.toHistoryContent(previous.result)}. Do not call it again — answer the user now.`,
+          };
+        } else if (!def) {
+          result = { error: `Unknown tool "${call.name}".` };
+        } else {
+          const check = validateToolArgs(def, call.arguments);
+          if (!check.ok) {
+            result = {
+              error: `Invalid arguments for ${call.name}: ${check.errors.join('; ')}. Fix them or ask the user for the missing values.`,
+            };
+          } else if (def.requiresConfirmation) {
+            args = check.args;
+            const summary = confirmReadback({ name: call.name, arguments: args }) ?? undefined;
+            const decision = opts.onConfirm
+              ? await opts.onConfirm({ name: call.name, arguments: args, ...(summary ? { summary } : {}) })
+              : { approved: false, reason: 'no confirmation handler available' };
+            if (decision.approved) {
+              result = await this.safeExecute(call.name, args);
+            } else {
+              result = declinedToolResult(call.name, decision.reason);
+              declinedThisTurn.push(summary ? summary.replace(/\.?\s*Confirm\?$/, '') : call.name.replace(/_/g, ' '));
+            }
           } else {
-            result = { declined: true, reason: decision.reason ?? 'user declined' };
+            args = check.args;
+            result = await this.safeExecute(call.name, args);
           }
-        } else {
-          result = await this.safeExecute(call.name, call.arguments);
         }
 
-        executed.push({ name: call.name, arguments: call.arguments, result });
-        opts.onToolResult?.({ name: call.name, arguments: call.arguments, result }, turn);
-        history.push({ role: 'tool', content: this.toHistoryContent(result) });
+        if (!previous) {
+          // A mutating (confirm-gated) call can change what reads return.
+          if (def?.requiresConfirmation) seen.clear();
+          seen.set(key, { result, count: 1 });
+        }
+        executed.push({ name: call.name, arguments: args, result });
+        opts.onToolResult?.({ name: call.name, arguments: args, result }, turn);
+        history.push({ role: 'tool', content: this.toHistoryContent(this.fixAmounts ? annotateRgbBalances(result) : result) });
       }
 
-      if (turn === maxTurns && !finalText) {
-        finalText = 'I had to stop after several steps — please try a more specific request.';
+      if (this.endTurnOnDecline && declinedThisTurn.length && declinedThisTurn.length === out.toolCalls.length) {
+        finalText = `Cancelled — you declined: ${declinedThisTurn.join('; ')}. Nothing was sent or changed.`;
+        engineReply = true;
+        break;
       }
+
+      if (repeatedAgain) {
+        const forced = await this.provider.runTurn({
+          messages: history,
+          tools: [],
+          system,
+          onToken: opts.onToken ? (t) => opts.onToken!(t, turn) : undefined,
+          signal: opts.signal,
+        });
+        if (forced.inference) inference.push(forced.inference);
+        finalText = (forced.text || '').trim() || 'I could not get a different result from the wallet — please try a more specific request.';
+        break;
+      }
+
+    }
+
+    // Never return an empty answer (e.g. the last turn ran out of tokens).
+    if (!finalText && !opts.signal?.aborted) {
+      finalText = STOPPED_MESSAGE;
+      engineReply = true;
+    }
+
+    if (this.fixAmounts && finalText && !engineReply) {
+      finalText = fixRgbBalanceUnits(fixSatsBtcConversions(finalText), executed.map((e) => e.result));
+    }
+
+    if (this.guardPaymentData && finalText && !engineReply) {
+      const ungrounded = findUngroundedPaymentData(finalText, [
+        ...messages.map((m) => m.content),
+        ...executed.map((e) => e.result),
+      ]);
+      if (ungrounded.length) finalText = ungroundedReply(ungrounded);
     }
 
     // Append the final answer so the returned conversation is complete (the
@@ -177,6 +360,38 @@ export class Engine {
     };
   }
 
+  /**
+   * The model ran tools but produced no visible answer (e.g. reasoning used the
+   * whole output budget). Ask once more without tools; if that is empty too,
+   * show the last tool result instead of an empty reply.
+   */
+  private async recoverAnswer(
+    history: Message[],
+    system: string | undefined,
+    executed: ToolResult[],
+    inference: InferenceMetrics[],
+    opts: AgenticOptions,
+    turn: number,
+  ): Promise<string> {
+    if (opts.signal?.aborted) return '';
+    const retry = await this.provider.runTurn({
+      messages: [
+        ...history,
+        { role: 'user', content: 'Answer my question now from the tool results above, in a few short sentences.' },
+      ],
+      tools: [],
+      system,
+      onToken: opts.onToken ? (t) => opts.onToken!(t, turn) : undefined,
+      signal: opts.signal,
+    });
+    if (retry.inference) inference.push(retry.inference);
+    const text = retry.incomplete ? '' : (retry.text || '').trim();
+    if (text) return text;
+    const last = executed[executed.length - 1]!;
+    const body = compressToolResult(last.result, this.compressOpts ?? {}).content;
+    return `I couldn't phrase an answer in time. Here is what ${last.name.replace(/_/g, ' ')} returned:\n\n${body.length > 2000 ? `${body.slice(0, 2000)}…` : body}`;
+  }
+
   async cancel(requestId: string): Promise<void> {
     await this.provider.cancel?.(requestId);
   }

package/src/funnel.mind.test.ts

@@ -335,11 +335,13 @@ describe('desktop mind — skill scoping (real skills)', () => {
     expect(node.tools?.every((tool) => tool.startsWith('rln_'))).toBe(true);
   });
 
-  it('kaleido-trading drops the phantom kaleidoswap_get_nodeinfo / get_order_history names', () => {
+  it('kaleido-trading drops the phantom kaleidoswap_get_nodeinfo / removed order-flow names', () => {
     const trading = SKILLS.find((s) => s.name === 'kaleido-trading')!;
     expect(trading.tools).not.toContain('kaleidoswap_get_nodeinfo');
     expect(trading.tools).not.toContain('kaleidoswap_get_order_history');
-    expect(trading.tools).toEqual(expect.arrayContaining(['kaleidoswap_get_quote', 'kaleidoswap_place_order']));
+    expect(trading.tools).not.toContain('kaleidoswap_place_order');
+    expect(trading.tools).not.toContain('kaleidoswap_get_order_status');
+    expect(trading.tools).toEqual(expect.arrayContaining(['kaleidoswap_get_quote', 'kaleidoswap_atomic_init']));
     expect(trading.tools).not.toEqual(
       expect.arrayContaining([
         'kaleidoswap_get_spreads',

package/src/funnel.ts

@@ -30,6 +30,8 @@ import { receiveRecipe } from './recipe/receive.js';
 import { assetSendRecipe } from './recipe/asset-send.js';
 import type { Recipe } from './recipe/types.js';
 import { SkillRegistry } from './skills/registry.js';
+import { selectAvailableSkill } from './skills/select.js';
+import { detectWalletAction, hasCapableTool, noToolReply, wantsToolCall } from './guards.js';
 import type { Skill } from './skills/types.js';
 import type { LLMProvider } from './providers/types.js';
 import type { InferenceMetrics } from './providers/types.js';
@@ -320,7 +322,9 @@ export class Funnel {
 
     // ── T1: skill-scoped agentic loop ──
     const skills = this.skillsFor(settings.disabledSkills);
-    const skill = skills.select(text);
+    const liveTools = (await this.registry.listTools()).map((t) => t.name);
+    const present = new Set(liveTools);
+    const skill = selectAvailableSkill(skills, text, present);
     let base = settings.persona ? `${this.system}\n\n## Your persona\n${settings.persona}` : this.system;
 
     // Auto-inject relevant knowledge chunks (best-effort — corpus is grounding
@@ -357,7 +361,6 @@ export class Funnel {
       // leaves the model TOOL-LESS — it then narrates "the tool isn't available"
       // instead of acting. If NONE of the scoped tools resolve against the live
       // registry, widen to the full surface so the agent can still work.
-      const present = new Set((await this.registry.listTools()).map((t) => t.name));
       if (!scoped.some((n) => present.has(n))) {
         this.log(
           `tier=agentic: skill '${skill?.name ?? '?'}' tools resolved to 0 live tools — using full tool surface`,
@@ -367,8 +370,23 @@ export class Funnel {
     } else if (disabledAmbient.length) {
       // No skill matched but a toggle is off: expose everything except the
       // disabled ambient tools (the sources stay mounted — no rebuild).
-      const all = (await this.registry.listTools()).map((t) => t.name);
-      scoped = all.filter((n) => !disabledAmbient.includes(n));
+      scoped = liveTools.filter((n) => !disabledAmbient.includes(n));
+    }
+
+    // A wallet action with no tool able to perform it: answer deterministically
+    // instead of letting the model improvise an invoice/address/payment.
+    const action = detectWalletAction(text);
+    if (action) {
+      const inScope = (scoped ?? liveTools).filter((n) => present.has(n));
+      if (!hasCapableTool(action, inScope)) {
+        if (scoped && hasCapableTool(action, liveTools)) {
+          this.log(`tier=agentic: skill '${skill?.name ?? '?'}' has no tool for ${action.id} — using full tool surface`);
+          scoped = liveTools.filter((n) => !disabledAmbient.includes(n));
+        } else {
+          this.log(`tier=agentic: no tool for ${action.id} — refusing`);
+          return { text: noToolReply(action), tier: 'agentic', route: 'no-tool', toolCalls: [], turns: 0, inference: [] };
+        }
+      }
     }
 
     // Trim history so the prompt (system + skill + tools + history) stays
@@ -396,6 +414,7 @@ export class Funnel {
       },
       onToolResult: cbs.onToolResult,
       onConfirm: cbs.onConfirm,
+      ...(wantsToolCall(text) ? { firstTurnToolChoice: 'required' as const } : {}),
       signal: cbs.signal,
     });
     return {