@pellux/goodvibes-agent 1.5.7 → 1.5.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-agent",
-  "version": "1.5.7",
+  "version": "1.5.9",
   "private": false,
   "description": "GoodVibes personal operator assistant TUI with a proactive Agent product brain, isolated Agent Knowledge, local profiles, routines, skills, personas, and explicit build delegation.",
   "type": "module",

package/src/agent/memory-prompt.ts

@@ -1,5 +1,5 @@
 import type { MemoryRecord, MemoryRegistry, MemoryVectorStats } from '@pellux/goodvibes-sdk/platform/state';
-// W6-C2 (E6): the recall-honesty floor + eligibility receipt now live in the SDK as
+// The recall-honesty floor + eligibility receipt now live in the SDK as
 // the ONE cross-surface contract (memory-recall-contract.ts) instead of being defined
 // per surface. This file re-exports them unchanged so every existing agent consumer
 // keeps importing from './memory-prompt.ts', while the SDK is the single source of the
@@ -32,9 +32,9 @@ function formatMemoryLine(record: MemoryRecord): string {
 }
 
 /**
- * Per-turn semantic ranking of an already-eligible memory set (Wave-4 W4-A1B).
+ * Per-turn semantic ranking of an already-eligible memory set.
  *
- * W4-A1 shipped eligibility (confidence + reviewState + provenance) as the hard trust
+ * Eligibility (confidence + reviewState + provenance) shipped as the hard trust
  * gate but had no per-turn query to rank WITHIN that eligible set — records were only
  * ever ordered by stored confidence/recency, regardless of whether they had anything to
  * do with what the user actually just asked. `rankMemoryForTurn` never touches the gate

package/src/agent/operator-actions.ts

@@ -103,7 +103,7 @@ export const OPERATOR_ACTIONS: Record<OperatorActionId, OperatorActionDescriptor
     pathTemplate: '/api/automation/jobs/{jobId}/run',
     targetField: 'jobId',
   },
-  // W6-C3: automation.jobs.pause/resume were retired (redundant with
+  // automation.jobs.pause/resume were retired (redundant with
   // disable/enable — same {id,enabled} output, same semantics). The
   // user-facing "pause"/"resume" verb is unchanged; only the wire action +
   // path moved to the canonical disable/enable methods.

package/src/agent/prompt-context-receipts.ts

@@ -140,7 +140,7 @@ function receiptSegment(input: Omit<PromptContextReceiptSegment, 'approxTokens'>
 
 function buildRuntimePromptReceiptSegments(input: RuntimePromptCompositionInput): readonly PromptContextReceiptSegment[] {
   const vibe = discoverVibeFiles(input.shellPaths);
-  // W6-C2 (E6): the VIBE prompt is a PROJECTION of persona/constraint records, not a
+  // The VIBE prompt is a PROJECTION of persona/constraint records, not a
   // re-read of the files (discoverVibeFiles above stays for the file-discovery receipt).
   const vibePrompt = buildVibeProjectionPrompt(input.memoryRegistry) ?? '';
   const projectContext = discoverProjectContextFiles(input.shellPaths);
@@ -234,7 +234,7 @@ function buildRuntimePromptReceiptSegments(input: RuntimePromptCompositionInput)
       suppressedCount: suppressedMemory.length,
       promptChars: memoryPrompt.length,
       promptText: memoryPrompt,
-      // Honest degrade note (Wave-4 W4-A1B): when per-turn relevance scoring did not
+      // Honest degrade note: when per-turn relevance scoring did not
       // run — no active-turn text, semantic index unavailable, or no vector match —
       // say so instead of silently presenting the fallback confidence/recency order as
       // if it were a relevance ranking.
@@ -245,7 +245,7 @@ function buildRuntimePromptReceiptSegments(input: RuntimePromptCompositionInput)
         class: record.cls,
         confidence: record.confidence,
         reason: describeMemoryPromptEligibility(record).reason,
-        // Per-turn relevance (W4-A1B): honest wording, only present when actually scored.
+        // Per-turn relevance: honest wording, only present when actually scored.
         // F7a: the raw percent is paired with a qualitative band (see relevanceBand)
         // so a genuinely-lower-but-real score like "28%" doesn't read as noise.
         ...(memoryRanking.scored ? { relevance: `relevance to this turn: ${memoryRanking.relevanceById.get(record.id) ?? 0}% (${relevanceBand(memoryRanking.relevanceById.get(record.id) ?? 0)})` } : {}),

package/src/agent/session-registration.ts

@@ -86,7 +86,7 @@ export interface SessionRecordSummary {
 }
 
 /**
- * Honest outcome discriminator. 'still_closed' is the Wave-1 heartbeat-resurrection
+ * Honest outcome discriminator. 'still_closed' is the heartbeat-resurrection
  * guard: a 200 that carries conflict:{status:'closed'} with reopened:false MUST NOT
  * be read as 'registered' or 'reopened'.
  */

package/src/agent/vibe-file.ts

@@ -5,7 +5,7 @@ import type { ShellPathService } from '@/runtime/index.ts';
 import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
 import { assertNoSecretLikeText } from './persona-registry.ts';
 import { parseMarkdownFrontmatter, stripMarkdownFrontmatter } from './markdown-frontmatter.ts';
-// W6-C2 (E6): VIBE.md is now a PROJECTION of persona/constraint records in the
+// VIBE.md is now a PROJECTION of persona/constraint records in the
 // canonical memory store, not a separate source of truth. renderVibeProjection emits
 // the same '## VIBE.md' block from those records (caveat preserved); the file is
 // demoted to an import/export FORMAT folded in via vibeBodyToConstraintOptions.
@@ -213,7 +213,7 @@ export function buildVibePrompt(shellPaths: AgentVibePaths): string | null {
 }
 
 /**
- * W6-C2 (E6): the VIBE.md prompt block as a PROJECTION of persona/constraint records.
+ * The VIBE.md prompt block as a PROJECTION of persona/constraint records.
  *
  * This is the store-sourced replacement for buildVibePrompt (which reads the file
  * directly). It renders the same '## GoodVibes Agent VIBE.md' block — including the
@@ -226,7 +226,7 @@ export function buildVibeProjectionPrompt(memoryRecords: { getAll(): readonly Me
 }
 
 /**
- * W6-C2 (E6): fold discovered VIBE.md files into the store as persona/constraint
+ * Fold discovered VIBE.md files into the store as persona/constraint
  * records — the file demoted to an IMPORT FORMAT. Each bullet becomes one record so a
  * later single-record edit changes exactly one projected line. Secret-like content is
  * already rejected by discoverVibeFiles (readVibeCandidate → assertNoSecretLikeText),
@@ -257,7 +257,7 @@ export async function importVibeFilesIntoMemory(
 }
 
 /**
- * W6-C2 (E6): the persisted marker that makes the VIBE.md → memory import a strictly
+ * The persisted marker that makes the VIBE.md → memory import a strictly
  * ONE-TIME migration. Keyed by absolute file path → content hash, so importing the same
  * VIBE.md twice is a no-op (re-import would create near-duplicate persona records), while
  * a NEW project's VIBE.md still migrates exactly once. Mirrors the sessions.spine-folded
@@ -300,7 +300,7 @@ function hashVibeBody(body: string): string {
 }
 
 /**
- * W6-C2 (E6): fold discovered VIBE.md files into persona/constraint records ONCE.
+ * Fold discovered VIBE.md files into persona/constraint records ONCE.
  * Guarded by a persisted path→hash marker so it never re-imports the same file (which
  * would create near-duplicate persona records). Called at boot AFTER memoryStore.init().
  * Returns the number of records created this run (0 when everything is already migrated).

package/src/audio/player.ts

@@ -15,6 +15,14 @@ export interface StreamingAudioPlayer {
   readonly available: boolean;
   play(chunks: AsyncIterable<VoiceAudioChunk>, options: StreamingAudioPlaybackOptions): Promise<void>;
   stop(): void;
+  /**
+   * Resolves once the currently playing sink has finished naturally (its
+   * process closed) or after `timeoutMs`, whichever comes first; resolves
+   * immediately when nothing is playing. The exit path uses this to let the
+   * audio the user is already hearing finish inside a short bounded window
+   * instead of killing it mid-drain. stop() remains the instant cut.
+   */
+  waitForDrain(timeoutMs: number): Promise<void>;
 }
 
 export interface StreamingAudioPlaybackOptions {
@@ -25,6 +33,8 @@ export interface StreamingAudioPlaybackOptions {
 interface SpawnProcess {
   readonly stdin: Writable;
   once(event: 'close', listener: () => void): this;
+  once(event: 'spawn', listener: () => void): this;
+  once(event: 'error', listener: (error: unknown) => void): this;
   kill(signal?: NodeJS.Signals | number): boolean;
 }
 type SpawnProcessFactory = (command: string, args: readonly string[]) => SpawnProcess;
@@ -32,6 +42,13 @@ type SpawnProcessFactory = (command: string, args: readonly string[]) => SpawnPr
 export interface LocalStreamingAudioPlayerOptions {
   readonly env?: NodeJS.ProcessEnv;
   readonly spawnProcess?: SpawnProcessFactory;
+  /**
+   * Injected player command — the test seam companion to `spawnProcess`.
+   * When set, the constructor uses it verbatim instead of scanning PATH, so
+   * deterministic fake-sink tests never depend on mpv/ffplay being installed
+   * on the machine running them. Pass null to model "no player found".
+   */
+  readonly command?: StreamingAudioPlayerCommand | null;
 }
 
 export class LocalStreamingAudioPlayer implements StreamingAudioPlayer {
@@ -40,7 +57,9 @@ export class LocalStreamingAudioPlayer implements StreamingAudioPlayer {
   private readonly spawnProcess: SpawnProcessFactory;
 
   constructor(options: LocalStreamingAudioPlayerOptions = {}) {
-    this.command = resolveStreamingAudioPlayerCommand(options.env ?? process.env);
+    this.command = options.command !== undefined
+      ? options.command
+      : resolveStreamingAudioPlayerCommand(options.env ?? process.env);
     this.spawnProcess = options.spawnProcess ?? defaultSpawnProcess;
   }
 
@@ -67,12 +86,27 @@ export class LocalStreamingAudioPlayer implements StreamingAudioPlayer {
     options.signal?.addEventListener('abort', abort, { once: true });
 
     try {
+      // Head survival: hold the first audio byte until the sink has actually
+      // started (its 'spawn' event) instead of writing into a process that has
+      // not exec'd yet. Writing before the player is up is the spawn race that
+      // clipped the beginning of playback. A spawn failure rejects here so the
+      // caller can report it honestly rather than swallowing a dead player.
+      await awaitReady(proc, options.signal);
+      if (options.signal?.aborted) return;
+
       for await (const chunk of chunks) {
         if (options.signal?.aborted) break;
         if (chunk.data.byteLength === 0) continue;
         await writeStdin(proc, chunk.data);
       }
-      proc.stdin.end();
+
+      // An intentional interrupt (turn cancel / quit chord / /tts stop) has
+      // already torn the process down via `abort` and must cut immediately —
+      // do not wait on a graceful drain. A natural end-of-speech, by contrast,
+      // closes stdin and waits for the sink to play out every buffered sample
+      // so the tail of the response is never truncated.
+      if (options.signal?.aborted) return;
+      try { proc.stdin.end(); } catch { /* ignore */ }
       await waitForExit(proc);
     } finally {
       options.signal?.removeEventListener('abort', abort);
@@ -87,14 +121,33 @@ export class LocalStreamingAudioPlayer implements StreamingAudioPlayer {
     try { proc.stdin.destroy(); } catch { /* ignore */ }
     try { proc.kill('SIGTERM'); } catch { /* ignore */ }
   }
+
+  waitForDrain(timeoutMs: number): Promise<void> {
+    const proc = this.activeProcess;
+    if (!proc) return Promise.resolve();
+    return new Promise((resolve) => {
+      let settled = false;
+      const settle = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve();
+      };
+      const timer = setTimeout(settle, timeoutMs);
+      proc.once('close', settle);
+    });
+  }
 }
 
 export function resolveStreamingAudioPlayerCommand(env: NodeJS.ProcessEnv = process.env): StreamingAudioPlayerCommand | null {
   const mpv = findExecutable('mpv', env);
   if (mpv) {
+    // No --cache=no: mpv's read-ahead cache buffers the incoming pipe so the
+    // opening audio survives device-open latency and network jitter instead of
+    // underrunning while the output device is still spinning up.
     return {
       command: mpv,
-      args: ['--no-terminal', '--really-quiet', '--force-window=no', '--cache=no', '-'],
+      args: ['--no-terminal', '--really-quiet', '--force-window=no', '-'],
       label: 'mpv',
     };
   }
@@ -102,18 +155,51 @@ export function resolveStreamingAudioPlayerCommand(env: NodeJS.ProcessEnv = proc
   if (ffplay) {
     return {
       command: ffplay,
-      args: ['-nodisp', '-autoexit', '-loglevel', 'error', '-i', 'pipe:0'],
+      args: FFPLAY_BASE_ARGS,
       label: 'ffplay',
     };
   }
   return null;
 }
 
+// ffplay -autoexit quits as soon as its input ends, before the audio output
+// buffer has drained — that clips the tail of the response. `apad` appends a
+// short run of silence so the real audio is fully played out and only the
+// trailing silence gets trimmed.
+const FFPLAY_APAD = ['-af', 'apad=pad_dur=0.3'] as const;
+const FFPLAY_BASE_ARGS = ['-nodisp', '-autoexit', '-loglevel', 'error', ...FFPLAY_APAD, '-i', 'pipe:0'] as const;
+
 function buildPlayerArgs(command: StreamingAudioPlayerCommand, format?: string): readonly string[] {
   if (command.label !== 'ffplay' || !format) return command.args;
   const normalized = format.trim().toLowerCase();
   if (!normalized || normalized.includes('/')) return command.args;
-  return ['-nodisp', '-autoexit', '-loglevel', 'error', '-f', normalized, '-i', 'pipe:0'];
+  return ['-nodisp', '-autoexit', '-loglevel', 'error', ...FFPLAY_APAD, '-f', normalized, '-i', 'pipe:0'];
+}
+
+/**
+ * awaitReady — resolves once the spawned player has actually started (its
+ * 'spawn' event), rejects if it fails to start ('error'), and resolves early
+ * if the caller aborts during startup so an intentional interrupt is never
+ * blocked. This is the readiness gate that keeps the first audio byte from
+ * being written into a not-yet-running sink.
+ */
+function awaitReady(proc: SpawnProcess, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) return Promise.resolve();
+  return new Promise<void>((resolve, reject) => {
+    let settled = false;
+    const settle = (action: () => void) => {
+      if (settled) return;
+      settled = true;
+      signal?.removeEventListener('abort', onAbort);
+      action();
+    };
+    const onSpawn = () => settle(resolve);
+    const onError = (error: unknown) => settle(() => reject(error instanceof Error ? error : new Error(String(error))));
+    const onAbort = () => settle(resolve);
+    proc.once('spawn', onSpawn);
+    proc.once('error', onError);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
 }
 
 function findExecutable(name: string, env: NodeJS.ProcessEnv): string | null {