@pellux/goodvibes-sdk 1.0.0 → 1.2.0

package/dist/platform/state/memory-registry.d.ts

@@ -1,6 +1,7 @@
 import type { MemoryAddOptions, MemoryBundle, MemoryDoctorReport, MemoryLink, MemoryRecord, MemoryReviewPatch, MemoryScope, MemorySearchFilter, MemorySemanticSearchResult, MemoryStore } from './memory-store.js';
 import type { MemoryVectorStats } from './memory-vector-store.js';
 import type { MemoryImportResult } from './memory-store.js';
+import { type HonestMemorySearchOptions, type HonestMemorySearchResult } from './memory-recall-contract.js';
 /**
  * MemoryRegistry — thin observable wrapper around the MemoryStore.
  * Panels subscribe via listeners; commands push/retrieve through this.
@@ -15,6 +16,13 @@ export declare class MemoryRegistry {
     add(opts: MemoryAddOptions): Promise<MemoryRecord>;
     search(filter?: MemorySearchFilter): MemoryRecord[];
     searchSemantic(filter?: MemorySearchFilter): MemorySemanticSearchResult[];
+    /**
+     * Search honoring the recall-honesty contract: semantic-or-literal with a stated
+     * fallback reason when the index is unavailable, and (with `options.recall`) the
+     * flagged/confidence-floor exclusion. This is the method a wire client and an
+     * offline surface both route through, so the honesty is identical either way.
+     */
+    honestSearch(filter?: MemorySearchFilter, options?: HonestMemorySearchOptions): HonestMemorySearchResult;
     rebuildVectors(): MemoryVectorStats;
     rebuildVectorsAsync(): Promise<MemoryVectorStats>;
     vectorStats(): MemoryVectorStats;

package/dist/platform/state/memory-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-registry.d.ts","sourceRoot":"","sources":["../../../src/platform/state/memory-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACnN,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,SAAS,CAAyB;gBAE9B,KAAK,EAAE,WAAW;IAI9B,QAAQ,IAAI,WAAW;IAIvB,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAOrC,OAAO,CAAC,MAAM;IAIR,GAAG,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;IAMxD,MAAM,CAAC,MAAM,GAAE,kBAAuB,GAAG,YAAY,EAAE;IAIvD,cAAc,CAAC,MAAM,GAAE,kBAAuB,GAAG,0BAA0B,EAAE;IAI7E,cAAc,IAAI,iBAAiB;IAI7B,mBAAmB,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAIvD,WAAW,IAAI,iBAAiB;IAI1B,MAAM,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAI3C,WAAW,CAAC,KAAK,SAAK,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,YAAY,EAAE;IAI5D,YAAY,CAAC,MAAM,GAAE,kBAAuB,GAAG,YAAY;IAIrD,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAMrE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAI9B,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAMtF,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,EAAE;IAIlC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,KAAK,CAAC,EAAE,WAAW,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,YAAY,GAAG,IAAI;IAM3H,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,YAAY,GAAG,IAAI;IAMjE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAM3B,MAAM,IAAI,YAAY,EAAE;CAGzB"}
+{"version":3,"file":"memory-registry.d.ts","sourceRoot":"","sources":["../../../src/platform/state/memory-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACnN,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAyB,KAAK,yBAAyB,EAAE,KAAK,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAEnI;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,SAAS,CAAyB;gBAE9B,KAAK,EAAE,WAAW;IAI9B,QAAQ,IAAI,WAAW;IAIvB,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAOrC,OAAO,CAAC,MAAM;IAIR,GAAG,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;IAMxD,MAAM,CAAC,MAAM,GAAE,kBAAuB,GAAG,YAAY,EAAE;IAIvD,cAAc,CAAC,MAAM,GAAE,kBAAuB,GAAG,0BAA0B,EAAE;IAI7E;;;;;OAKG;IACH,YAAY,CAAC,MAAM,GAAE,kBAAuB,EAAE,OAAO,GAAE,yBAA8B,GAAG,wBAAwB;IAIhH,cAAc,IAAI,iBAAiB;IAI7B,mBAAmB,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAIvD,WAAW,IAAI,iBAAiB;IAI1B,MAAM,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAI3C,WAAW,CAAC,KAAK,SAAK,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,YAAY,EAAE;IAI5D,YAAY,CAAC,MAAM,GAAE,kBAAuB,GAAG,YAAY;IAIrD,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAMrE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAI9B,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAMtF,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,EAAE;IAIlC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,KAAK,CAAC,EAAE,WAAW,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,YAAY,GAAG,IAAI;IAM3H,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,YAAY,GAAG,IAAI;IAMjE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAM3B,MAAM,IAAI,YAAY,EAAE;CAGzB"}

package/dist/platform/state/memory-registry.js

@@ -1,3 +1,4 @@
+import { runHonestMemorySearch } from './memory-recall-contract.js';
 /**
  * MemoryRegistry — thin observable wrapper around the MemoryStore.
  * Panels subscribe via listeners; commands push/retrieve through this.
@@ -32,6 +33,15 @@ export class MemoryRegistry {
     searchSemantic(filter = {}) {
         return this.store.searchSemantic(filter);
     }
+    /**
+     * Search honoring the recall-honesty contract: semantic-or-literal with a stated
+     * fallback reason when the index is unavailable, and (with `options.recall`) the
+     * flagged/confidence-floor exclusion. This is the method a wire client and an
+     * offline surface both route through, so the honesty is identical either way.
+     */
+    honestSearch(filter = {}, options = {}) {
+        return runHonestMemorySearch(this.store, filter, options);
+    }
     rebuildVectors() {
         return this.store.rebuildVectorIndex();
     }

package/dist/platform/state/memory-vector-store.js

@@ -6,7 +6,7 @@ import { MemoryEmbeddingProviderRegistry, embedMemoryText, normalizeMemoryEmbedd
 import { loadSqliteVecExtension } from './sqlite-vec-loader.js';
 import { logger } from '../utils/logger.js';
 import { summarizeError } from '../utils/error-display.js';
-// Lifted to sqlite-vec-loader.ts (Wave-5 W5.3) so code-index-store.ts can load
+// Lifted to sqlite-vec-loader.ts (see CHANGELOG 0.38.0) so code-index-store.ts can load
 // the exact same native extension the exact same way. Re-exported here so
 // existing callers that import resolveSqliteVecPath from this module keep working.
 export { resolveSqliteVecPath } from './sqlite-vec-loader.js';

package/dist/platform/state/sqlite-vec-loader.d.ts

@@ -13,7 +13,7 @@ import type { Database } from 'bun:sqlite';
  * via the re-exported `load()` function.
  *
  * Shared by memory-vector-store.ts (MemoryStore's vector index) and
- * code-index-store.ts (the repo source-tree code index, Wave-5 W5.3) so both
+ * code-index-store.ts (the repo source-tree code index; see CHANGELOG 0.38.0) so both
  * indexes load the exact same native extension the exact same way.
  */
 export declare function resolveSqliteVecPath(): string;

package/dist/platform/state/sqlite-vec-loader.js

@@ -14,7 +14,7 @@ import { load as loadSqliteVec } from 'sqlite-vec';
  * via the re-exported `load()` function.
  *
  * Shared by memory-vector-store.ts (MemoryStore's vector index) and
- * code-index-store.ts (the repo source-tree code index, Wave-5 W5.3) so both
+ * code-index-store.ts (the repo source-tree code index; see CHANGELOG 0.38.0) so both
  * indexes load the exact same native extension the exact same way.
  */
 export function resolveSqliteVecPath() {

package/dist/platform/state/vibe-projection.d.ts

@@ -1,8 +1,8 @@
 /**
- * vibe-projection.ts — VIBE.md as a PROJECTION of memory records (Wave-6 E6).
+ * vibe-projection.ts — VIBE.md as a PROJECTION of memory records (see CHANGELOG 1.0.0).
  *
- * BEFORE E6, VIBE.md was a persona file read off disk and injected into the prompt
- * — a projection of ITSELF, a source of truth disjoint from the memory store. E6
+ * BEFORE memory unification, VIBE.md was a persona file read off disk and injected into the prompt
+ * — a projection of ITSELF, a source of truth disjoint from the memory store. Memory unification
  * demotes the file to an import/export FORMAT and makes the prompt block a
  * projection of first-class memory records:
  *

package/dist/platform/state/vibe-projection.js

@@ -1,8 +1,8 @@
 /**
- * vibe-projection.ts — VIBE.md as a PROJECTION of memory records (Wave-6 E6).
+ * vibe-projection.ts — VIBE.md as a PROJECTION of memory records (see CHANGELOG 1.0.0).
  *
- * BEFORE E6, VIBE.md was a persona file read off disk and injected into the prompt
- * — a projection of ITSELF, a source of truth disjoint from the memory store. E6
+ * BEFORE memory unification, VIBE.md was a persona file read off disk and injected into the prompt
+ * — a projection of ITSELF, a source of truth disjoint from the memory store. Memory unification
  * demotes the file to an import/export FORMAT and makes the prompt block a
  * projection of first-class memory records:
  *

package/dist/platform/tools/agent/manager.d.ts

@@ -25,7 +25,7 @@ export interface AgentManagerDependencies {
     readonly conversationSnapshotRetention?: number | undefined;
 }
 /**
- * Wave-3 tab attach point (Part C6): default bound on how many recently
+ * Conversation-snapshot tab attach point (Part C6): default bound on how many recently
  * finished agents' final conversation snapshot AgentManager keeps around
  * after their live source is released. Without a bound, a long-lived process
  * that spawns many short-lived agents would retain every finished agent's
@@ -56,7 +56,7 @@ export interface AgentRecord {
     /**
      * Set by cancel(id, kind) when status transitions to 'cancelled'. Distinguishes
      * a graceful interrupt request from a hard kill for display purposes
-     * (Wave-3 verb formalization) without overloading `status`, which is
+     * (verb formalization) without overloading `status`, which is
      * consumed widely (ledger parse, orchestrator finalize, exportState/
      * importState). Absent on records cancelled before this field existed, and
      * on any record cancelled via the single-arg cancel(id) call — both default
@@ -90,7 +90,7 @@ export interface AgentRecord {
     fanoutCollapse?: AgentInput['fanoutCollapse'] | undefined;
     dangerously_disable_wrfc?: boolean | undefined;
     /**
-     * Wave-4 orchestration engine tag (wo701): set by phase-runner.ts when it
+     * Orchestration engine tag: set by phase-runner.ts when it
      * spawns an agent to run one WorkItem through one Phase. Mirrors
      * wrfcId/wrfcSubtaskId — the fleet's agent adapter uses it to parent this
      * agent node under its work-item ProcessNode (adapters/agent.ts
@@ -132,7 +132,7 @@ export interface AgentRecord {
         reviewState: 'fresh' | 'reviewed' | 'stale' | 'contradicted';
     }>;
     /**
-     * Wave-5 (wo801, W5.1) bounded ring of per-turn passive-injection honesty
+     * Bounded ring of per-turn passive-injection honesty
      * records — one entry per turn that actually ran retrieval (turns that
      * reused the prior turn's cached block, or that ran with the feature
      * flag/budget off, append nothing). See turn-knowledge-injection.ts for
@@ -153,14 +153,14 @@ export declare class AgentManager {
     private executor;
     private readonly configManager;
     /**
-     * Live snapshot accessors for RUNNING agents (Wave-3 Part C6 bridge).
+     * Live snapshot accessors for RUNNING agents (conversation-snapshot bridge, Part C6).
      * Registered by the executor (orchestrator-runner.ts) right after it
      * creates the agent's ConversationManager; the manager never stores
      * messages itself while an agent is running — it just holds a callback.
      */
     private readonly conversationSources;
     /**
-     * Wave-4 cooperative cancellation bridge (wo701): per-agent AbortSignal
+     * Cooperative cancellation bridge: per-agent AbortSignal
      * registered by an orchestration-engine work item for the duration of one
      * phase run. AgentOrchestrator reads this via
      * setCancellationSource/getCancellationSignal and threads it into
@@ -187,14 +187,14 @@ export declare class AgentManager {
     cancel(id: string, kind?: 'interrupt' | 'kill'): boolean;
     /**
      * Register the live conversation-snapshot source for a running agent
-     * (Wave-3 Part C6 bridge). Called by the executor (orchestrator-runner.ts)
+     * (conversation-snapshot bridge, Part C6). Called by the executor (orchestrator-runner.ts)
      * once its ConversationManager exists — `source` is invoked on demand by
      * getConversationSnapshot(); the manager never copies or stores the
      * messages itself while the agent is running.
      */
     registerConversationSource(agentId: string, source: () => ConversationMessageSnapshot[]): void;
     /**
-     * Wave-4 cooperative cancellation bridge (wo701): register the AbortSignal
+     * Cooperative cancellation bridge: register the AbortSignal
      * an orchestration engine's cancellation registry created for a work
      * item's current agent. Called by the engine right after
      * AgentManager.spawn() so the signal is in place before the agent's first
@@ -212,7 +212,7 @@ export declare class AgentManager {
      * open at the moment of completion keeps showing content instead of going
      * blank. Once evicted (oldest-first, beyond the retention bound),
      * getConversationSnapshot falls back to an empty array — callers past that
-     * point are expected to degrade to the on-disk event ledger (Wave-3 TUI
+     * point are expected to degrade to the on-disk event ledger (TUI
      * Part C6's documented fallback for completed/detached agents).
      *
      * Safe to call even when no source was ever registered for this agentId
@@ -220,7 +220,7 @@ export declare class AgentManager {
      */
     releaseConversationSource(agentId: string): void;
     /**
-     * The Wave-3 tab attach point: a full-fidelity conversation history for a
+     * The conversation-snapshot tab attach point: a full-fidelity conversation history for a
      * fleet agent (ConversationMessageSnapshot[] — the same shape the main
      * session surface renders via MessageLineCache/conversation.ts).
      *

package/dist/platform/tools/agent/manager.js

@@ -9,7 +9,7 @@ import { summarizeError } from '../../utils/error-display.js';
 import { splitModelRegistryKey } from '../../providers/registry-helpers.js';
 import { isRootReviewRoleTask, resolveAuthoritativeWrfcScope, resolveImplementationToolContract, resolveNarrowedRootSpawnScope, } from './wrfc-batch-policy.js';
 /**
- * Wave-3 tab attach point (Part C6): default bound on how many recently
+ * Conversation-snapshot tab attach point (Part C6): default bound on how many recently
  * finished agents' final conversation snapshot AgentManager keeps around
  * after their live source is released. Without a bound, a long-lived process
  * that spawns many short-lived agents would retain every finished agent's
@@ -82,14 +82,14 @@ export class AgentManager {
     executor;
     configManager;
     /**
-     * Live snapshot accessors for RUNNING agents (Wave-3 Part C6 bridge).
+     * Live snapshot accessors for RUNNING agents (conversation-snapshot bridge, Part C6).
      * Registered by the executor (orchestrator-runner.ts) right after it
      * creates the agent's ConversationManager; the manager never stores
      * messages itself while an agent is running — it just holds a callback.
      */
     conversationSources = new Map();
     /**
-     * Wave-4 cooperative cancellation bridge (wo701): per-agent AbortSignal
+     * Cooperative cancellation bridge: per-agent AbortSignal
      * registered by an orchestration-engine work item for the duration of one
      * phase run. AgentOrchestrator reads this via
      * setCancellationSource/getCancellationSignal and threads it into
@@ -529,7 +529,7 @@ export class AgentManager {
     }
     /**
      * Register the live conversation-snapshot source for a running agent
-     * (Wave-3 Part C6 bridge). Called by the executor (orchestrator-runner.ts)
+     * (conversation-snapshot bridge, Part C6). Called by the executor (orchestrator-runner.ts)
      * once its ConversationManager exists — `source` is invoked on demand by
      * getConversationSnapshot(); the manager never copies or stores the
      * messages itself while the agent is running.
@@ -538,7 +538,7 @@ export class AgentManager {
         this.conversationSources.set(agentId, source);
     }
     /**
-     * Wave-4 cooperative cancellation bridge (wo701): register the AbortSignal
+     * Cooperative cancellation bridge: register the AbortSignal
      * an orchestration engine's cancellation registry created for a work
      * item's current agent. Called by the engine right after
      * AgentManager.spawn() so the signal is in place before the agent's first
@@ -562,7 +562,7 @@ export class AgentManager {
      * open at the moment of completion keeps showing content instead of going
      * blank. Once evicted (oldest-first, beyond the retention bound),
      * getConversationSnapshot falls back to an empty array — callers past that
-     * point are expected to degrade to the on-disk event ledger (Wave-3 TUI
+     * point are expected to degrade to the on-disk event ledger (TUI
      * Part C6's documented fallback for completed/detached agents).
      *
      * Safe to call even when no source was ever registered for this agentId
@@ -593,7 +593,7 @@ export class AgentManager {
         }
     }
     /**
-     * The Wave-3 tab attach point: a full-fidelity conversation history for a
+     * The conversation-snapshot tab attach point: a full-fidelity conversation history for a
      * fleet agent (ConversationMessageSnapshot[] — the same shape the main
      * session surface renders via MessageLineCache/conversation.ts).
      *

package/dist/platform/tools/exec/runtime.js

@@ -124,7 +124,7 @@ function applyExpectations(result, expect, exitCode) {
 function buildTimedOutResult(cmdStr, cwd, durationMs, progressFile) {
     return { cmd: cmdStr, exit_code: null, stdout: '', stderr: '', success: false, timed_out: true, duration_ms: durationMs, cwd, ...(progressFile ? { progress_file: progressFile } : {}) };
 }
-/** Wave-4 cooperative cancellation (wo701): mirrors buildTimedOutResult's shape for the AbortSignal path. */
+/** Cooperative cancellation: mirrors buildTimedOutResult's shape for the AbortSignal path. */
 function buildCancelledResult(cmdStr, cwd, durationMs) {
     return { cmd: cmdStr, exit_code: null, stdout: '', stderr: '', success: false, cancelled: true, duration_ms: durationMs, cwd };
 }
@@ -136,7 +136,7 @@ function buildCancelledResult(cmdStr, cwd, durationMs) {
  */
 const POST_STOP_DRAIN_GRACE_MS = 500;
 /**
- * Wave-4 cooperative cancellation (wo701): after a timeout/abort kill the
+ * Cooperative cancellation: after a timeout/abort kill the
  * child has already been SIGKILL'd, but a grandchild that inherited the
  * stdout/stderr pipe can hold it open, so reading those streams to EOF may
  * never settle. Awaiting the full IO promise unbounded here could therefore
@@ -214,11 +214,11 @@ async function runCommand(processManager, overflowHandler, featureFlags, cmdStr,
     const timeoutMs = cmdInput.timeout_ms ?? globalTimeout;
     const mergedEnv = { ...buildCleanEnv(), ...cmdInput.env };
     const startTime = Date.now();
-    // Wave-4 cooperative cancellation (wo701) is wired for the foreground and
+    // Cooperative cancellation is wired for the foreground and
     // progress-streamed paths (the common cases — progress auto-engages once
     // timeout_ms exceeds PROGRESS_AUTO_THRESHOLD_MS, which the 120s default
     // timeout always does). `until`-pattern commands are explicitly deferred
-    // (see the WO report) — the timeout kill-timer they already have still
+    // — the timeout kill-timer they already have still
     // applies, just not an external AbortSignal.
     if (cmdInput.until) {
         return runUntil(processManager, overflowHandler, cmdStr, cmdInput, cwd, mergedEnv, timeoutMs, startTime);
@@ -543,7 +543,7 @@ export function isRetryableExecResult(result, allowed) {
     // Timed-out commands are never auto-retried — callers must decide
     if (result.timed_out)
         return false;
-    // Cancelled commands (Wave 4, wo701) must never be retried — retrying
+    // Cancelled commands must never be retried — retrying
     // after an operator/engine kill would defeat the cancellation entirely.
     if (result.cancelled)
         return false;

package/dist/platform/tools/exec/schema.d.ts

@@ -269,7 +269,7 @@ export interface ExecCommandResult {
     expectation_error?: string | undefined;
     /** Set when command exceeded timeout. */
     timed_out?: boolean | undefined;
-    /** Set when an external AbortSignal cancelled the command (Wave 4, wo701 — orchestration engine cancellation). Never combined with timed_out. */
+    /** Set when an external AbortSignal cancelled the command (orchestration engine cancellation). Never combined with timed_out. */
     cancelled?: boolean | undefined;
     /** Set when command ran in background. */
     process_id?: string | undefined;

package/dist/platform/tools/exec/schema.d.ts.map

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

package/dist/platform/tools/fetch/runtime.d.ts

@@ -7,7 +7,7 @@ export interface FetchRuntimeDeps {
     readonly serviceRegistry?: Pick<ServiceRegistry, 'resolveAuth'> | null | undefined;
     readonly featureFlags?: Pick<FeatureFlagManager, 'isEnabled'> | null | undefined;
     /**
-     * Wave-4 cooperative cancellation (wo701): an externally-supplied signal,
+     * Cooperative cancellation: an externally-supplied signal,
      * combined with each request's own per-URL timeout signal via
      * `AbortSignal.any`. Optional and additive — omitted, behavior is
      * unchanged from before this field existed.

package/dist/platform/tools/registry.d.ts

@@ -44,7 +44,7 @@ export declare class ToolRegistry {
     /**
      * Execute a named tool with the given arguments. Wraps errors in ToolResult.
      *
-     * `opts.signal` (Wave 4, wo701) is an additive pass-through to
+     * `opts.signal` is an additive pass-through to
      * `tool.execute` — only tools that opt in (exec, fetch) read it. Callers
      * that don't have a cancellation signal (the common case) omit `opts`.
      */

package/dist/platform/tools/registry.js

@@ -73,7 +73,7 @@ export class ToolRegistry {
     /**
      * Execute a named tool with the given arguments. Wraps errors in ToolResult.
      *
-     * `opts.signal` (Wave 4, wo701) is an additive pass-through to
+     * `opts.signal` is an additive pass-through to
      * `tool.execute` — only tools that opt in (exec, fetch) read it. Callers
      * that don't have a cancellation signal (the common case) omit `opts`.
      */

package/dist/platform/types/tools.d.ts

@@ -33,7 +33,7 @@ export interface ToolResult {
 /**
  * Optional per-call execution options.
  *
- * `signal` (Wave 4, wo701) is ADDITIVE: it was not present before, and every
+ * `signal` is ADDITIVE: it was not present before, and every
  * existing tool implementation that declares `execute(args)` with a single
  * parameter remains a valid implementation of this interface (structural
  * typing — an unused trailing optional parameter is simply never read). Only

package/dist/platform/utils/request-body.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request-body.d.ts","sourceRoot":"","sources":["../../../src/platform/utils/request-body.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,8BAA8B,UAAY,CAAC;AAMxD,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,OAAO,EACZ,QAAQ,SAAiC,GACxC,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC,CA4B5B;AAED,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,OAAO,EACZ,QAAQ,SAAiC,GACxC,OAAO,CAAC,OAAO,GAAG,QAAQ,CAAC,CAQ7B"}
+{"version":3,"file":"request-body.d.ts","sourceRoot":"","sources":["../../../src/platform/utils/request-body.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,8BAA8B,UAAY,CAAC;AA8CxD,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,OAAO,EACZ,QAAQ,SAAiC,GACxC,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC,CA+B5B;AAED,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,OAAO,EACZ,QAAQ,SAAiC,GACxC,OAAO,CAAC,OAAO,GAAG,QAAQ,CAAC,CAQ7B"}

package/dist/platform/utils/request-body.js

@@ -1,11 +1,54 @@
 export const DEFAULT_MAX_REQUEST_BODY_BYTES = 1_000_000;
-function ignoreCancelError() {
-    // Stream cancellation failure is intentionally non-blocking.
+/**
+ * Reads and discards the remainder of a request body reader.
+ *
+ * Bun (and Node) keep-alive connection reuse depends on the previous
+ * request's body having been fully read off the wire — `stream.cancel()`
+ * signals "stop delivering chunks to me" but does not, in practice, drain the
+ * underlying connection buffer, which leaves the NEXT request on a reused
+ * connection stalled for several seconds waiting for the runtime to notice
+ * the connection is actually free (observed directly against a bare
+ * `Bun.serve()` with no SDK code involved). Actively reading-and-discarding
+ * the rest of the body is the correct fix: it costs a little time
+ * proportional to the bytes the caller already sent, but leaves the
+ * connection immediately reusable. Best-effort — a drain failure must not
+ * mask the caller's own response/error.
+ */
+async function drainReader(reader) {
+    try {
+        for (;;) {
+            const { done } = await reader.read();
+            if (done)
+                break;
+        }
+    }
+    catch {
+        // Best-effort.
+    }
+}
+async function drainBody(body) {
+    if (!body)
+        return;
+    const reader = body.getReader();
+    try {
+        await drainReader(reader);
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function payloadTooLargeResponse(maxBytes) {
+    // Honest refusal: state the actual limit rather than a bare "too large" —
+    // a caller (browser composer, webhook sender, etc.) needs the number to
+    // decide whether to retry with a different transport (e.g. the artifact
+    // multipart/raw-body upload path) or shrink the payload.
+    return Response.json({ error: `Payload exceeds the ${maxBytes}-byte limit.` }, { status: 413 });
 }
 export async function readTextBodyWithinLimit(req, maxBytes = DEFAULT_MAX_REQUEST_BODY_BYTES) {
     const contentLength = Number.parseInt(req.headers.get('content-length') ?? '0', 10);
     if (Number.isFinite(contentLength) && contentLength > maxBytes) {
-        return Response.json({ error: 'Payload too large' }, { status: 413 });
+        await drainBody(req.body);
+        return payloadTooLargeResponse(maxBytes);
     }
     if (!req.body)
         return '';
@@ -20,8 +63,10 @@ export async function readTextBodyWithinLimit(req, maxBytes = DEFAULT_MAX_REQUES
                 break;
             total += value.byteLength;
             if (total > maxBytes) {
-                await reader.cancel('Payload too large').catch(ignoreCancelError);
-                return Response.json({ error: 'Payload too large' }, { status: 413 });
+                // Keep reading (and discarding) the rest of this oversized body
+                // rather than cancelling — see drainReader's doc comment.
+                await drainReader(reader);
+                return payloadTooLargeResponse(maxBytes);
             }
             body += decoder.decode(value, { stream: true });
         }

package/dist/platform/version.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-let version = '1.0.0';
+let version = '1.2.0';
 try {
     const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', '..', 'package.json'), 'utf-8'));
     version = pkg.version ?? version;

package/dist/platform/voice/index.d.ts

@@ -4,4 +4,6 @@ export type { VoiceProviderDescriptor } from './provider-registry.js';
 export { VoiceService } from './service.js';
 export type { VoiceServiceStatus } from './service.js';
 export { ensureBuiltinVoiceProviders } from './builtin-providers.js';
+export { SpokenTurnController, TtsTextChunker, normalizeSpeechText } from './spoken-turn/index.js';
+export type { SpokenTurnControllerOptions, TtsTextChunkerOptions, AudioSink, AudioSinkPlaybackOptions, } from './spoken-turn/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/platform/voice/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/platform/voice/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,2BAA2B,EAC3B,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/platform/voice/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,2BAA2B,EAC3B,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAIrE,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AACnG,YAAY,EACV,2BAA2B,EAC3B,qBAAqB,EACrB,SAAS,EACT,wBAAwB,GACzB,MAAM,wBAAwB,CAAC"}

package/dist/platform/voice/index.js

@@ -1,3 +1,6 @@
 export { VoiceProviderRegistry } from './provider-registry.js';
 export { VoiceService } from './service.js';
 export { ensureBuiltinVoiceProviders } from './builtin-providers.js';
+// Spoken-turn (live TTS) policy engine — shared behavioral contract; consumers
+// inject an AudioSink for I/O. See ./spoken-turn.
+export { SpokenTurnController, TtsTextChunker, normalizeSpeechText } from './spoken-turn/index.js';

package/dist/platform/voice/spoken-turn/audio-sink.d.ts

@@ -0,0 +1,111 @@
+import type { VoiceAudioChunk } from '../types.js';
+/**
+ * AudioSink — the injectable I/O boundary the spoken-turn policy engine plays
+ * through. The SDK owns POLICY (chunking, the bounded synthesis window, merge
+ * coalescing, retry/backoff, the turn state machine); a sink owns I/O (turning
+ * an ordered stream of audio bytes into sound and reporting when it has stopped
+ * making sound). The controller never spawns a process, opens a device, or
+ * touches Web Audio — it only talks to this interface, so the same policy runs
+ * unchanged behind a terminal subprocess player, a browser Web Audio sink, or a
+ * test fake.
+ *
+ * ## Behavioral contract
+ *
+ * The controller depends on these guarantees, not on any implementation detail:
+ *
+ * 1. **Readiness / head survival.** `play()` must not drop the leading bytes of
+ *    the stream while the underlying output is still coming up. A subprocess
+ *    sink holds the first byte until the player has actually exec'd (its spawn
+ *    event); a browser sink holds until the MediaSource `sourceopen` /
+ *    SourceBuffer is ready. The controller writes the whole stream and trusts
+ *    the sink to have played the head — it does not re-send or pre-buffer.
+ *    `available` is the coarse, synchronous readiness signal (is any output
+ *    device usable at all); per-call readiness is internal to `play()`.
+ *
+ * 2. **Natural drain plays everything.** When the input stream ends without an
+ *    abort, `play()` resolves only after the last buffered sample has been
+ *    heard — never at end-of-input. Truncating the tail of a response is the
+ *    bug this contract exists to prevent.
+ *
+ * 3. **Abort cuts immediately.** When `options.signal` aborts (a deliberate
+ *    interrupt — new turn, Ctrl+C, /tts stop, turn cancel), `play()` stops
+ *    emitting sound and resolves promptly; it must NOT wait on a graceful
+ *    drain. `stop()` is the same instant cut driven imperatively rather than by
+ *    a signal.
+ *
+ * 4. **Bounded exit drain.** `waitForDrain(timeoutMs)` resolves when the sound
+ *    currently playing finishes naturally OR after `timeoutMs`, whichever comes
+ *    first, and resolves immediately when nothing is playing. The exit path
+ *    uses this to let the final audio of a finished response play out inside a
+ *    short window instead of being cut mid-word.
+ *
+ * ## Web Audio / browser sink mapping (proof the interface fits a browser)
+ *
+ * A browser sink for the webui voice build implements this same interface over
+ * streaming MP3 into MediaSource; no interface change is required:
+ *
+ * - `available` -> `('MediaSource' in window) && MediaSource.isTypeSupported('audio/mpeg')`
+ *   (fall back to Web Audio `decodeAudioData` where MSE is absent).
+ * - `play(chunks, { format, signal })` ->
+ *     - create a `MediaSource`, attach it to an `HTMLAudioElement` via
+ *       `URL.createObjectURL`, and `await` its `sourceopen` event — this is the
+ *       readiness gate (contract 1);
+ *     - `addSourceBuffer(mimeFor(format))` where `mimeFor('mp3') === 'audio/mpeg'`
+ *       (the same `format` string the controller forwards from the synthesis
+ *       result), then `await audioEl.play()`;
+ *     - `for await (const chunk of chunks)` -> `sourceBuffer.appendBuffer(chunk.data)`,
+ *       awaiting each `updateend`, honoring `signal.aborted` between chunks;
+ *     - on input end without abort: `mediaSource.endOfStream()` and resolve on
+ *       the audio element's `ended` event -> natural drain (contract 2);
+ *     - on `signal` abort: `audioEl.pause()`, `sourceBuffer.abort()`,
+ *       `mediaSource.endOfStream()`, revoke the object URL, resolve now
+ *       (contract 3).
+ * - `stop()` -> the same teardown as the abort branch, driven imperatively.
+ * - `waitForDrain(timeoutMs)` -> resolve on the audio element's `ended` event or
+ *   a `setTimeout(timeoutMs)`, whichever fires first (contract 4).
+ *
+ * `VoiceAudioChunk.data` is a `Uint8Array`, which `appendBuffer` accepts
+ * directly, and the `format` string maps 1:1 to a MediaSource MIME type, so the
+ * byte-and-format shape the controller emits is exactly what a browser sink
+ * consumes. (The subprocess sink — mpv/ffplay over stdin — stays consumer-side
+ * and is not part of the SDK.)
+ */
+export interface AudioSink {
+    /** Human-readable sink name for status lines (e.g. 'mpv', 'web-audio'). */
+    readonly label: string;
+    /**
+     * Coarse, synchronous readiness: is any output device usable at all. When
+     * false the controller arms nothing and reports the graceful-degradation
+     * notice instead of attempting playback.
+     */
+    readonly available: boolean;
+    /**
+     * Play an ordered stream of audio chunks to completion. Resolves after the
+     * final sample is heard on a natural end, or promptly on abort. See the
+     * interface contract above for readiness, drain, and abort obligations.
+     */
+    play(chunks: AsyncIterable<VoiceAudioChunk>, options: AudioSinkPlaybackOptions): Promise<void>;
+    /** Instant cut: stop emitting sound now and release the output. Idempotent; a no-op when idle. */
+    stop(): void;
+    /**
+     * Resolves once the currently playing sound has finished naturally or after
+     * `timeoutMs`, whichever comes first; resolves immediately when nothing is
+     * playing. The bounded exit drain — see contract 4.
+     */
+    waitForDrain(timeoutMs: number): Promise<void>;
+}
+export interface AudioSinkPlaybackOptions {
+    /**
+     * Container/codec hint for the byte stream (e.g. 'mp3'), forwarded verbatim
+     * from the synthesis result's `format`. A subprocess sink maps it to a
+     * demuxer flag; a browser sink maps it to a MediaSource MIME type. Omitted or
+     * a value containing '/' (already a MIME type) leaves the sink on its default.
+     */
+    readonly format?: string | undefined;
+    /**
+     * Deliberate-interrupt signal. When it aborts, playback cuts immediately (no
+     * graceful drain) and `play()` resolves. Absence means "play to natural end".
+     */
+    readonly signal?: AbortSignal | undefined;
+}
+//# sourceMappingURL=audio-sink.d.ts.map

package/dist/platform/voice/spoken-turn/audio-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-sink.d.ts","sourceRoot":"","sources":["../../../../src/platform/voice/spoken-turn/audio-sink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,MAAM,WAAW,SAAS;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,EAAE,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/F,kGAAkG;IAClG,IAAI,IAAI,IAAI,CAAC;IACb;;;;OAIG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C"}

package/dist/platform/voice/spoken-turn/audio-sink.js

@@ -0,0 +1 @@
+export {};