@pellux/goodvibes-tui 1.16.1 → 1.18.0

package/src/core/stable-host.ts

@@ -0,0 +1,171 @@
+/**
+ * stable-host.ts — a stable name for printed/QR pairing links.
+ *
+ * The legacy resolution used the first non-internal IPv4 in enumeration order
+ * (see getLocalNetworkIp in management-utils.ts). That address is bound to the
+ * current DHCP lease: when the lease changes, every printed link and every QR
+ * that encoded it stops resolving. This module resolves a name that survives a
+ * lease change where one exists, and only falls back to a routable address when
+ * no stable name is available.
+ *
+ * Resolution ladder (highest preference first):
+ *   1. Tailscale MagicDNS name — preferred when tailscale is up. It resolves on
+ *      and off the LAN and is never bound to a DHCP lease.
+ *   2. mDNS `<hostname>.local` — a LAN name a DHCP change does not break.
+ *   3. Gateway-routed interface address — the IPv4 on the default-route
+ *      interface (not merely the first non-internal one, which can land on a
+ *      bridge/VPN). The last resort; DHCP-bound.
+ *   4. Loopback — nothing routable enumerated.
+ *
+ * The resolver (resolveStableHost) is a pure function of injected inputs so the
+ * ladder is testable under mocked interface / tailscale states; the probes that
+ * gather those inputs are impure and bounded, and degrade to undefined rather
+ * than throw when a tool is missing or slow.
+ */
+import { execFileSync } from 'node:child_process';
+import { hostname as osHostname, networkInterfaces } from 'node:os';
+
+export type StableHostKind = 'tailscale-magicdns' | 'mdns-local' | 'gateway-interface' | 'loopback';
+
+export interface TailscaleState {
+  /** BackendState === 'Running'. */
+  readonly up: boolean;
+  /** Self.DNSName from `tailscale status --json`, trailing dot stripped. */
+  readonly magicDnsName?: string | undefined;
+}
+
+export interface StableHostInputs {
+  /** os.hostname(), possibly an FQDN — the `.local` name derives from its first label. */
+  readonly hostname: string;
+  /** The routable IPv4 on the default-route interface, when known. */
+  readonly gatewayInterfaceIp?: string | undefined;
+  /** First non-internal IPv4 in enumeration order — the legacy fallback address. */
+  readonly firstNonInternalIp?: string | undefined;
+  /** Tailscale state, when the CLI is present and answered in time. */
+  readonly tailscale?: TailscaleState | undefined;
+}
+
+export interface ResolvedStableHost {
+  readonly host: string;
+  readonly kind: StableHostKind;
+  /** True when `host` is a name that survives a DHCP lease change. */
+  readonly stable: boolean;
+}
+
+function stripTrailingDot(name: string): string {
+  return name.replace(/\.+$/, '');
+}
+
+/** `<hostname>.local` from the first label of a hostname, or null when there is no usable label. */
+export function mdnsLocalName(host: string): string | null {
+  const label = (host ?? '').trim().split('.')[0]?.trim();
+  if (!label || label.toLowerCase() === 'localhost') return null;
+  // Already a `.local` name (hostname was set to the mDNS form): keep it as-is.
+  if (host.trim().toLowerCase().endsWith('.local')) return stripTrailingDot(host.trim());
+  return `${label}.local`;
+}
+
+/**
+ * Resolve the stable host from injected inputs. Pure — no I/O — so the ladder is
+ * exercised directly under mocked interface / tailscale states.
+ */
+export function resolveStableHost(inputs: StableHostInputs): ResolvedStableHost {
+  const magic = inputs.tailscale?.up ? inputs.tailscale.magicDnsName?.trim() : undefined;
+  if (magic) return { host: stripTrailingDot(magic), kind: 'tailscale-magicdns', stable: true };
+
+  const local = mdnsLocalName(inputs.hostname);
+  if (local) return { host: local, kind: 'mdns-local', stable: true };
+
+  const routed = inputs.gatewayInterfaceIp?.trim() || inputs.firstNonInternalIp?.trim();
+  if (routed) return { host: routed, kind: 'gateway-interface', stable: false };
+
+  return { host: '127.0.0.1', kind: 'loopback', stable: false };
+}
+
+/** First non-internal IPv4 in enumeration order (the legacy fallback address). */
+export function firstNonInternalIpv4(nets: ReturnType<typeof networkInterfaces>): string | undefined {
+  for (const name of Object.keys(nets)) {
+    for (const netInfo of nets[name] ?? []) {
+      if (netInfo.family === 'IPv4' && !netInfo.internal) return netInfo.address;
+    }
+  }
+  return undefined;
+}
+
+/** Parse the `src <ip>` field out of a Linux `ip route get` line. */
+export function parseIpRouteSrc(output: string): string | undefined {
+  const match = /\bsrc\s+(\d+\.\d+\.\d+\.\d+)/.exec(output);
+  return match?.[1];
+}
+
+/** Parse `Self.DNSName` + running state out of `tailscale status --json` output. */
+export function parseTailscaleStatus(json: string): TailscaleState | undefined {
+  try {
+    const parsed = JSON.parse(json) as { BackendState?: unknown; Self?: { DNSName?: unknown } };
+    const up = parsed.BackendState === 'Running';
+    const dnsName = typeof parsed.Self?.DNSName === 'string' ? stripTrailingDot(parsed.Self.DNSName) : undefined;
+    return { up, ...(dnsName ? { magicDnsName: dnsName } : {}) };
+  } catch {
+    return undefined;
+  }
+}
+
+function probeGatewayInterfaceIp(): string | undefined {
+  try {
+    const out = execFileSync('ip', ['route', 'get', '1.1.1.1'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 1500 });
+    return parseIpRouteSrc(out);
+  } catch {
+    return undefined;
+  }
+}
+
+function probeTailscaleState(): TailscaleState | undefined {
+  try {
+    const out = execFileSync('tailscale', ['status', '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 1500 });
+    return parseTailscaleStatus(out);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Gather the impure inputs the resolver needs, each bounded and failure-tolerant. */
+export function probeStableHostInputs(): StableHostInputs {
+  let nets: ReturnType<typeof networkInterfaces> = {};
+  try {
+    nets = networkInterfaces();
+  } catch {
+    nets = {};
+  }
+  const first = firstNonInternalIpv4(nets);
+  const gateway = probeGatewayInterfaceIp();
+  const tailscale = probeTailscaleState();
+  return {
+    hostname: safeHostname(),
+    ...(gateway ? { gatewayInterfaceIp: gateway } : {}),
+    ...(first ? { firstNonInternalIp: first } : {}),
+    ...(tailscale ? { tailscale } : {}),
+  };
+}
+
+function safeHostname(): string {
+  try {
+    return osHostname();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * The stable host for a printed/QR link given the endpoint's bind host. A
+ * wildcard bind (0.0.0.0 / ::) resolves through the ladder; an explicit bind
+ * host is honored as-is (loopback stays loopback). `probe` is injectable for
+ * tests.
+ */
+export function stableUrlHostForBindHost(
+  host: string,
+  probe: () => StableHostInputs = probeStableHostInputs,
+): ResolvedStableHost {
+  if (host === '0.0.0.0' || host === '::') return resolveStableHost(probe());
+  const bound = host || '127.0.0.1';
+  return { host: bound, kind: bound === '127.0.0.1' ? 'loopback' : 'gateway-interface', stable: false };
+}

package/src/core/stream-event-wiring.ts

@@ -24,6 +24,13 @@ export interface StreamMetrics {
   activeToolStartedAtMs: number | undefined;
   /** Name of the currently executing tool; cleared when execution completes. */
   activeToolName: string | undefined;
+  /**
+   * callId of the currently executing tool call; cleared when execution
+   * completes. This is the real orchestrator callId (from TOOL_EXECUTING),
+   * so a per-tool cancel affordance targets exactly the running call — never
+   * the synthetic 'live' render id.
+   */
+  activeToolCallId: string | undefined;
   /**
    * Epoch ms of the most recent STREAM_START or STREAM_DELTA; undefined when
    * idle (no turn in flight). Read every render frame — not just on the
@@ -49,6 +56,16 @@ export interface StreamMetrics {
   reconnectMaxAttempts: number | undefined;
 }
 
+/** The idle initial StreamMetrics — mutated in place by wireStreamEventMetrics handlers. */
+export function createStreamMetrics(): StreamMetrics {
+  return {
+    startTime: 0, deltaCount: 0, tokenSpeed: 0, ttftMs: undefined, ttftRecorded: false,
+    activeToolStartedAtMs: undefined, activeToolName: undefined, activeToolCallId: undefined,
+    lastDeltaAtMs: undefined, stallEpisode: 0,
+    reconnectAttempt: undefined, reconnectMaxAttempts: undefined,
+  };
+}
+
 /** Minimal orchestrator surface required for stream token-speed calculation. */
 interface StreamOrchestrator {
   readonly streamingOutputTokens: number;
@@ -115,11 +132,11 @@ function isStreamRetryLikePayload(payload: unknown): payload is StreamRetryLikeP
 
 /**
  * Minimal cost lookup surface for attaching cost-delta information to failover notices.
- * Returns USD-per-1M-token pricing for the given model ID.
- * The implementation may consult a catalog; if the model is unknown both fields are 0.
+ * Returns USD-per-1M-token pricing for the given model ID, or null when the
+ * catalog honestly does not know the model (never a fabricated zero).
  */
 export interface FailoverCostLookup {
-  getCostFromCatalog(modelId: string): { readonly input: number; readonly output: number };
+  getCostFromCatalog(modelId: string): { readonly input: number; readonly output: number } | null;
 }
 
 export interface WireStreamEventMetricsOptions {
@@ -219,9 +236,11 @@ function buildCostDeltaSuffix(
   // Registry key format: `provider:modelId` — modelId may itself contain `:`.
   const fromModelId = fromRegistryKey ? fromRegistryKey.split(':').slice(1).join(':') : '';
   const toModelId = toRegistryKey.split(':').slice(1).join(':');
-  const fromCost = fromModelId ? lookup.getCostFromCatalog(fromModelId) : { input: 0, output: 0 };
-  const toCost = lookup.getCostFromCatalog(toModelId);
-  // Report unavailable when either side has zero pricing (unknown model).
+  // A null catalog answer means honestly unknown — treated exactly like the
+  // legacy zero-pricing sentinel below.
+  const fromCost = (fromModelId ? lookup.getCostFromCatalog(fromModelId) : null) ?? { input: 0, output: 0 };
+  const toCost = lookup.getCostFromCatalog(toModelId) ?? { input: 0, output: 0 };
+  // Report unavailable when either side has no pricing (unknown model).
   if (fromCost.input === 0 && fromCost.output === 0 && !fromModelId) {
     return ' [cost data unavailable]';
   }
@@ -441,6 +460,7 @@ export function wireStreamEventMetrics(
   unsubs.push(events.tools.on('TOOL_EXECUTING', (ev) => {
     metrics.activeToolStartedAtMs = ev.startedAt;
     metrics.activeToolName = ev.tool;
+    metrics.activeToolCallId = ev.callId;
     render();
   }));
   // On every tool-completion path, reset lastDeltaAtMs to "now" so the
@@ -454,16 +474,19 @@ export function wireStreamEventMetrics(
   unsubs.push(events.tools.on('TOOL_SUCCEEDED', () => {
     metrics.activeToolStartedAtMs = undefined;
     metrics.activeToolName = undefined;
+    metrics.activeToolCallId = undefined;
     metrics.lastDeltaAtMs = Date.now();
   }));
   unsubs.push(events.tools.on('TOOL_FAILED', () => {
     metrics.activeToolStartedAtMs = undefined;
     metrics.activeToolName = undefined;
+    metrics.activeToolCallId = undefined;
     metrics.lastDeltaAtMs = Date.now();
   }));
   unsubs.push(events.tools.on('TOOL_CANCELLED', () => {
     metrics.activeToolStartedAtMs = undefined;
     metrics.activeToolName = undefined;
+    metrics.activeToolCallId = undefined;
     metrics.lastDeltaAtMs = Date.now();
   }));
 

package/src/core/system-message-noise.ts

@@ -4,7 +4,7 @@
  * source these rules catch is emitted (from the SDK) through
  * SystemMessageRouter, so this one funnel is where first-run plumbing is kept
  * out of the user's stream while the information stays reachable elsewhere
- * (fleet panel, /health, /model, activity log). (UX-B item 1.)
+ * (fleet panel, /health, /model, activity log). (item 1.)
  */
 
 export interface NoiseGateDeps {

package/src/core/system-message-router.ts

@@ -9,7 +9,7 @@
  * that target — plus whether a panel is attached — into a { toPanel,
  * toConversation } decision.
  *
- * W6.1 (the purge): the SystemMessagesPanel this router used to optionally
+ * (the purge): the SystemMessagesPanel this router used to optionally
  * push into was DELETE-disposition (no surviving human surface — a picker
  * over the old panel registry, not something worth a dedicated console) and
  * has been removed entirely, so this router now always resolves with
@@ -61,7 +61,7 @@ export type {
   SystemMessageTarget,
 } from '@/runtime/index.ts';
 
-/** Panel emphasis level. Panel delivery was removed in W6.1 (see file doc); kept as the priority vocabulary for callers and for the SDK's delivery-resolution signature. */
+/** Panel emphasis level. Panel delivery was removed in (see file doc); kept as the priority vocabulary for callers and for the SDK's delivery-resolution signature. */
 export type SystemMessagePriority = 'high' | 'low';
 
 /**
@@ -88,7 +88,7 @@ function mustReachConversation(message: string): boolean {
 
 /**
  * Routes system messages to the conversation based on priority level and
- * configured target. See file doc for the W6.1 panel removal.
+ * configured target. See file doc for the panel removal.
  */
 export class SystemMessageRouter {
   /** Buffered provider "from last session" replay lines, folded on a microtask. */
@@ -123,7 +123,7 @@ export class SystemMessageRouter {
     kind: SystemMessageKind,
   ): void {
     // Noise gate — keep first-run plumbing out of the transcript while the
-    // information stays reachable via other live surfaces. (UX-B item 1.)
+    // information stays reachable via other live surfaces. (item 1.)
     const verdict = classifyNoise(message, this.noiseDeps);
     if (verdict.action === 'drop') return;
     if (verdict.action === 'foldProviderReplay') {
@@ -137,7 +137,7 @@ export class SystemMessageRouter {
   /** Post-noise-gate delivery: resolve target and append to the conversation. */
   private deliver(message: string, kind: SystemMessageKind): void {
     const target = this.getTargetForKind(kind);
-    // hasPanel is always false post-W6.1 — resolveSystemMessageDelivery's own
+    // hasPanel is always false now that panel delivery was removed — resolveSystemMessageDelivery's own
     // contract means every target ('panel' | 'conversation' | 'both')
     // resolves toConversation: true in that case (see file doc).
     const delivery = resolveSystemMessageDelivery(target, false);
@@ -153,7 +153,7 @@ export class SystemMessageRouter {
    * Buffer a provider "from last session" replay line and schedule a microtask
    * flush. The SDK emits the whole persisted-provider burst synchronously, so a
    * single microtask captures the full burst and folds it to one quiet line.
-   * (UX-B item 1b.)
+   * (item 1b.)
    */
   private bufferProviderReplay(message: string): void {
     this.providerReplayBuffer.push(message);

package/src/core/turn-budget-outcome.ts

@@ -0,0 +1,60 @@
+/**
+ * turn-budget-outcome.ts — render a turn-budget exhaustion as an honest budget
+ * line, distinct from an infrastructure failure.
+ *
+ * When a member agent spends its whole turn budget the SDK stamps a typed
+ * outcome — failureKind 'max_turns' with the ceiling that applied and which
+ * input set it — instead of leaving consumers to regex a prose message. This
+ * renders that typed outcome in plain language: a budget was reached (not a
+ * crash), with the number and where the number came from.
+ */
+export type TurnBudgetSource = 'default' | 'spawn-override' | 'policy-bound';
+
+/** Plain-language provenance for a turn ceiling. */
+export function describeTurnBudgetSource(source: TurnBudgetSource | undefined): string {
+  switch (source) {
+    case 'spawn-override':
+      return 'a per-spawn override';
+    case 'policy-bound':
+      return 'the policy cap (agents.maxTurnsCap)';
+    case 'default':
+      return 'the default limit (agents.maxTurns)';
+    default:
+      return 'the configured turn limit';
+  }
+}
+
+export interface TurnBudgetOutcome {
+  readonly limit?: number | undefined;
+  readonly source?: TurnBudgetSource | undefined;
+}
+
+/**
+ * A short budget line: "reached its turn budget — 50 turns (the default limit
+ * (agents.maxTurns))". Honest about the fact that the run stopped because it hit
+ * a ceiling, not because something broke.
+ */
+export function formatTurnBudgetOutcome(outcome: TurnBudgetOutcome): string {
+  const source = describeTurnBudgetSource(outcome.source);
+  return outcome.limit !== undefined
+    ? `reached its turn budget — ${outcome.limit} turn${outcome.limit === 1 ? '' : 's'} (${source})`
+    : `reached its turn budget (${source})`;
+}
+
+/** The machine-readable failure reason the SDK stamps on a turn-budget exhaustion. */
+export const TURN_BUDGET_FAILURE_REASON = 'max_turns';
+
+export function isTurnBudgetReason(reason: string | null | undefined): boolean {
+  return reason === TURN_BUDGET_FAILURE_REASON;
+}
+
+/**
+ * Render a failure-reason string for a surface that only has the reason (not the
+ * typed limit/source event fields), mapping the machine-readable 'max_turns' to
+ * a plain budget phrase distinct from an infrastructure failure. Any other
+ * reason passes through unchanged.
+ */
+export function describeFailureReason(reason: string | null | undefined): string {
+  if (!reason) return '';
+  return isTurnBudgetReason(reason) ? 'reached its turn budget' : reason;
+}

package/src/core/turn-cancellation.ts

@@ -5,7 +5,7 @@ import type { SpokenTurnRuntime } from '../audio/spoken-turn-wiring.ts';
  * Builds the shared "cancel the active turn" action: stops any in-flight
  * spoken output, then aborts the orchestrator's turn if one is actively
  * streaming. Extracted from main.ts so the file can stay under its 800-line
- * cap while still wiring `commandContext.isGenerating` (see W1.6 FIX 1).
+ * cap while still wiring `commandContext.isGenerating` (see FIX 1).
  *
  * Returns whether SPEECH was actively stopped — a Ctrl+C that silenced live
  * TTS is consumed by that job (an earlier replay fix), same as a press that
@@ -23,3 +23,42 @@ export function createCancelGeneration(
     return stoppedSpeech;
   };
 }
+
+/** The narrow orchestrator surface the per-tool cancel needs. */
+export interface ToolCancelOrchestrator {
+  /** Cancel ONE in-flight tool call; false when no such call is running. */
+  cancelToolCall(callId: string): boolean;
+  /** The callIds of tool calls currently in flight. */
+  listRunningToolCalls(): readonly string[];
+}
+
+/**
+ * Builds the "cancel the running tool call" action: stops JUST the currently-
+ * running tool call, leaving the turn to continue. The in-process orchestrator
+ * holds the per-call AbortController — this is the local-session equivalent of
+ * the sessions.toolCalls.cancel wire verb. The cancelled call settles as a
+ * structured "cancelled by user" result (partial output preserved) the model
+ * adapts to in the same turn.
+ *
+ * Target selection is honest: the tracked active callId (the live transcript
+ * row) when known, else the sole in-flight call when exactly one is running,
+ * else nothing (returns false — never guesses which of several to stop).
+ * `onCancelled` fires only on a real cancellation, with the callId stopped.
+ */
+export function createCancelToolCall(
+  orchestrator: ToolCancelOrchestrator,
+  getActiveToolCallId: () => string | undefined,
+  onCancelled: (callId: string) => void,
+): () => boolean {
+  return () => {
+    let target = getActiveToolCallId();
+    if (target === undefined) {
+      const running = orchestrator.listRunningToolCalls();
+      if (running.length === 1) target = running[0];
+    }
+    if (target === undefined) return false;
+    const cancelled = orchestrator.cancelToolCall(target);
+    if (cancelled) onCancelled(target);
+    return cancelled;
+  };
+}

package/src/core/turn-event-wiring.ts

@@ -1,6 +1,7 @@
 import type { UiRuntimeEvents, RuntimeEventBus } from '@/runtime/index.ts';
 import { buildPersistedSessionContext, persistConversation } from '@/runtime/index.ts';
 import { buildCompactionReceiptBlock } from './compaction-receipt.ts';
+import { formatTurnBudgetOutcome } from './turn-budget-outcome.ts';
 import { persistTurnAnchors, recordTurnAnchor, summarizeTurnLabel } from './rewind-turn-anchors.ts';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
@@ -78,12 +79,12 @@ export interface WireTurnEventHandlersOptions {
    */
   readonly webhookNotifier?: WebhookNotifier | null;
   /**
-   * Terminal focus tracker (W2.3). Gates the long-task, budget-breach, and
+   * Terminal focus tracker. Gates the long-task, budget-breach, and
    * agent/chain-failure desktop alerts wired in this module — see
-   * alert-gating.ts. Optional; when absent, none of the new W2.3 alert
-   * behavior is gated by focus (long-task keeps its pre-W2.3 always-fire
-   * behavior, and budget-breach/failure alerts are skipped entirely, since
-   * they are new-in-W2.3 and have no pre-existing unconditional-fire path
+   * alert-gating.ts. Optional; when absent, none of the new alert
+   * behavior is gated by focus (long-task keeps its always-fire
+   * behavior from before focus gating existed, and budget-breach/failure alerts are
+   * skipped entirely, since they have no pre-existing unconditional-fire path
    * to fall back to).
    */
   readonly focusTracker?: Pick<FocusTracker, 'shouldAlertWhenUnfocused'> | null;
@@ -152,7 +153,7 @@ export function wireTurnEventHandlers(
   // Track turn start time for long-task notification threshold.
   let turnStartTime: number | null = null;
 
-  // Budget-breach edge-trigger checker (W2.3) — one instance per session,
+  // Budget-breach edge-trigger checker — one instance per session,
   // piggybacking on the same TURN_COMPLETED handler as the long-task
   // notification below rather than adding a second TURN_COMPLETED subscription.
   const budgetBreachNotifier: BudgetBreachNotifier | null = focusTracker
@@ -193,7 +194,7 @@ export function wireTurnEventHandlers(
       focusTracker,
       configGet,
     });
-    // Budget-breach alert (W2.3): edge-triggered, piggybacks on this same
+    // Budget-breach alert: edge-triggered, piggybacks on this same
     // TURN_COMPLETED handler rather than a second subscription.
     if (budgetBreachNotifier) {
       const sessionModel = providerRegistry.getCurrentModel().id ?? 'unknown';
@@ -264,7 +265,7 @@ export function wireTurnEventHandlers(
     refreshGit();
   }));
 
-  // Agent/chain-failure desktop alerts (W2.3). The SDK's WebhookNotifier and
+  // Agent/chain-failure desktop alerts. The SDK's WebhookNotifier and
   // Notifier already fire webhook/Slack/Discord notifications for these two
   // events unconditionally (attachToRuntimeBus in the SDK's
   // platform/integrations — pre-existing, not focus-gated: an out-of-band
@@ -290,6 +291,11 @@ export function wireTurnEventHandlers(
         // chain/owner/cohort surfaces.
         if (payload.failureKind === 'cancelled') {
           notifyCompletion('GoodVibes — WRFC chain cancelled', `chain ${payload.chainId.slice(0, 12)} cancelled: ${payload.reason}`, FORCE_NOTIFY_DURATION_MS);
+        } else if (payload.failureKind === 'max_turns') {
+          // A turn-budget exhaustion is a spent ceiling, not an infrastructure
+          // failure — narrate the limit and where it came from, from the typed
+          // event fields, never a regex of the prose reason.
+          notifyCompletion('GoodVibes — WRFC chain hit its turn budget', `chain ${payload.chainId.slice(0, 12)} ${formatTurnBudgetOutcome({ limit: payload.turnLimit, source: payload.turnLimitSource })}`, FORCE_NOTIFY_DURATION_MS);
         } else {
           const kindLabel = payload.failureKind === 'transport' ? 'transient transport error' : payload.reason;
           notifyCompletion('GoodVibes — WRFC chain failed', `chain ${payload.chainId.slice(0, 12)} failed: ${kindLabel}`, FORCE_NOTIFY_DURATION_MS);