agent.libx.js 0.89.9 → 0.92.1

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-import { a as AgentOptions, H as Hooks, h as RunResult, A as Agent } from './Agent-B0l9qT_j.js';
-export { C as ChatFragment, D as DEFAULT_MUTATING, b as Decision, P as PermissionOptions, c as PermissionPolicy, d as PermissionRule, e as PreToolUseDecision, R as ReasoningEffort, f as RecordingHooks, g as RecordingLifecycle, T as ToolUse, i as ToolUseMeta, j as composeHooks, p as planMode, r as reasoningToChatFragment } from './Agent-B0l9qT_j.js';
+import { a as AgentOptions, H as Hooks, h as RunResult, A as Agent } from './Agent-BzwprwHr.js';
+export { C as ChatFragment, D as DEFAULT_MUTATING, b as Decision, P as PermissionOptions, c as PermissionPolicy, d as PermissionRule, e as PreToolUseDecision, R as ReasoningEffort, f as RecordingHooks, g as RecordingLifecycle, T as ToolUse, i as ToolUseMeta, j as composeHooks, p as planMode, r as reasoningToChatFragment } from './Agent-BzwprwHr.js';
 import { IFilesystem, FileMetadata } from '@livx.cc/wcli/core';
 export { CommandExecutor, FileMetadata, IFilesystem, IndexedDbFilesystem, MemFilesystem, registerHeadlessCommands } from '@livx.cc/wcli/core';
 import { BodDB } from '@bod.ee/db';
-import { A as AgentTool, C as ChatLike, a as ChatOptions, b as ChatResponse, h as ToolCall, H as HostBridge, U as UserQuestion, e as MessageContent } from './tools-Ch-OzOU8.js';
-export { c as ContentPart, d as HostEvent, M as Message, R as Role, S as SandboxJobRegistry, f as StreamChunk, T as TodoItem, g as Tool, i as ToolContext, j as bashTool, k as contentText, l as defaultTools, m as editTool, n as imagePart, o as makeContext, p as makeJobTools, r as readTool, t as toWireTools, q as todoWriteTool, s as toolRegistry, u as toolsByName } from './tools-Ch-OzOU8.js';
-export { M as McpCall, a as McpToolSearchOptions, b as McpToolSpec, m as makeMcpToolSearch, c as mcpToolToAgentTool, d as mcpToolsToAgentTools } from './mcp-Dg3vA1Uj.js';
+import { A as AgentTool, C as ChatLike, a as ChatOptions, b as ChatResponse, h as ToolCall, H as HostBridge, U as UserQuestion, e as MessageContent } from './tools-CeK5AquG.js';
+export { c as ContentPart, d as HostEvent, M as Message, R as Role, S as SandboxJobRegistry, f as StreamChunk, T as TodoItem, g as Tool, i as ToolContext, j as bashTool, k as contentText, l as defaultTools, m as editTool, n as exitSessionTool, o as imagePart, p as makeContext, q as makeJobTools, r as readTool, t as toWireTools, s as todoWriteTool, u as toolRegistry, v as toolsByName } from './tools-CeK5AquG.js';
+export { M as McpCall, a as McpImage, b as McpToolResult, c as McpToolSearchOptions, d as McpToolSpec, m as makeMcpToolSearch, e as mcpToolToAgentTool, f as mcpToolsToAgentTools } from './mcp-Bn5TlRbV.js';
 import * as libx_js_src_modules_log from 'libx.js/src/modules/log';
 export { log } from 'libx.js/src/modules/log';
 
@@ -597,6 +597,9 @@ declare class DuplexAgentOptions {
     /** Awaited BEFORE a delegated worker spawns — open a per-task checkpoint frame, audit, etc.
      *  (post-spawn would race the worker's first edits). */
     onTaskStart?: (id: string, label: string) => void | Promise<void>;
+    /** Host overrides for QuickLook lookups (keyed by `what`). The engine's defaults go through the
+     *  (possibly jailed) fs — e.g. `.git/**` is deny-listed, so the CLI supplies 'branch' itself. */
+    quickLook?: Record<string, (path?: string) => string | Promise<string>>;
 }
 declare const VOICE_SYSTEM_PROMPT: string;
 /**
@@ -632,6 +635,10 @@ declare class DuplexAgent {
     private failTask;
     private delegateTool;
     private taskStatusTool;
+    /** Sub-100ms read-only lookups the voice may do itself — everything else stays Delegate-only.
+     *  fs-only (no shell; the engine is VFS-abstracted): time, git branch (.git/HEAD read), ls, file
+     *  head. Output is hard-capped so a lookup can never bloat the skinny voice context. */
+    private quickLookTool;
     private cancelTaskTool;
 }
 
@@ -697,4 +704,191 @@ declare function makeTaskBatchTool(opts: TaskToolOptions): AgentTool;
 /** Component-scoped logger (libx.js). debug/verbose gated via DEBUG env/localStorage. */
 declare const forComponent: (name: string) => libx_js_src_modules_log.ComponentLogger;
 
-export { Agent, type AgentDef, AgentOptions, AgentTool, type Attempt, BodDbFilesystem, ChatLike, ChatOptions, ChatResponse, type CommandInfo, ConsoleHostBridge, DEFAULT_DENY, DuplexAgent, DuplexAgentOptions, type DuplexTaskStatus, FakeAIClient, Hooks, HostBridge, JailOptions, JailedFilesystem, type LessonOptions, LessonOptionsDefaults, MessageContent, type Mount, MountFilesystem, NodeDiskFilesystem, OverlayFilesystem, type ReflectOptions, RunResult, ScriptedHostBridge, type SkillInfo, type TaskRecord, type TaskToolOptions, ToolCall, type ToolSpec, UserQuestion, VOICE_SYSTEM_PROMPT, type WebFetchOptions, type WebSearchOptions, applyEditsTool, askUserQuestionTool, checkpointTool, checkpointTools, compileSynthesizedTool, diskAgentOptions, expandCommand, expandTemplate, forComponent, fullAgentOptions, globTool, grepTool, htmlToText, idfWeights, lessonCapture, loadAgents, loadCommands, loadInstructions, loadMemory, loadSkills, makeTaskBatchTool, makeTaskTool, makeWebFetchTool, makeWebSearchTool, mkdirp, multiEditTool, raceAttempts, reflectOnRun, relevanceScore, repoIndex, repoMapTool, rollbackTool, sandboxAgentOptions, slugify, tokenize, toolCall, topByRelevance, validateToolCode, webFetchTool, webSearchTool, writeFact, writeTool };
+/**
+ * Portable voice I/O contracts — zero platform imports. The engine, STT and TTS clients in this
+ * directory run anywhere with a `WebSocket` global (Bun, Node, browser); platform backends
+ * (mic capture, audio playback) plug in through these seams.
+ */
+type VoiceState = 'idle' | 'listening' | 'thinking' | 'speaking';
+/** STT input sample format — sources MUST deliver this (downsample/convert in the adapter). */
+declare const STT_SAMPLE_RATE = 16000;
+/** Playback format the TTS requests and sinks must play. */
+declare const TTS_SAMPLE_RATE = 44100;
+/** A microphone (or any PCM) source. Emits s16le mono 16kHz chunks.
+ *  Node: mic-aec/ffmpeg child process. Web: getUserMedia({ echoCancellation: true }) + worklet. */
+interface AudioSource {
+    /** `aec` = the source is echo-cancelled (assistant's own TTS never reaches the chunks) —
+     *  selects the engine's trivial barge-in path vs the heuristic echo tier. */
+    readonly aec: boolean;
+    start(onChunk: (pcm: Uint8Array) => void): void | Promise<void>;
+    stop(): void;
+}
+/** An audio playback sink for s16le mono 44.1kHz PCM.
+ *  Node: per-turn ffplay. Web: AudioContext/worklet ring buffer. */
+interface AudioSink {
+    /** start a new spoken turn (may recycle or recreate the underlying player) */
+    markTurn(): void;
+    write(pcm: Uint8Array): void;
+    /** estimated ms until queued audio finishes playing */
+    drainMs(): number;
+    /** ms of audio actually played this turn */
+    playedMs(): number;
+    /** stop playback NOW (barge-in primitive) */
+    kill(): void;
+}
+/** Static key (server/CLI) or an async getter (browser: fetch a short-lived token from YOUR
+ *  backend). Getters are invoked on EVERY (re)connect — temp tokens expire, so a reconnect
+ *  must re-mint, never reuse the boot-time token. */
+type AuthProvider = string | (() => string | Promise<string>);
+declare function resolveAuth(auth: AuthProvider): Promise<string>;
+
+/** Structural contracts (satisfied by SonioxSTT/CartesiaTTS or test fakes). */
+interface SttLike {
+    usingAec: boolean;
+    onPartial: (text: string) => void;
+    onUtterance: (text: string, endpointAt: number) => void;
+    onLevel: (rms: number) => void;
+    start(): Promise<void> | void;
+    reset(): void;
+    stop(): void;
+}
+interface TtsLike {
+    onAudio: (chunk: Uint8Array) => void;
+    onDone: () => void;
+    connect(): Promise<void> | void;
+    newContext(): string;
+    speak(text: string, cont: boolean): void;
+    end(): void;
+    cancel(): void;
+    close(): void;
+}
+declare class VoiceEngineOptions {
+    stt: SttLike;
+    tts: TtsLike;
+    player: AudioSink;
+    /** a final utterance arrived (endpoint) — host dispatches it as a turn */
+    onUtterance: (text: string) => void;
+    /** live partial transcript while listening (host renders the 🎤 line) */
+    onPartial: (text: string) => void;
+    onState: (s: VoiceState) => void;
+    /** user spoke/acted over playback — host aborts the in-flight turn (called AFTER audio is killed).
+     *  phase: 'speaking' = cut mid-speech (real interruption); 'drain' = in the final audio tail
+     *  (normal turn-taking — hosts shouldn't alarm). */
+    onBargeIn: (phase: 'speaking' | 'drain') => void;
+    /** spoken micro-ack on utterance endpoint (masks LLM TTFT); '' disables */
+    ackPhrase: string;
+    /** Endpoint merge window (ms): hold an endpointed utterance briefly — if speech resumes (spelled
+     *  letters, mid-thought pauses), the next utterance MERGES instead of dispatching a truncated one
+     *  ("E-L-Y." / "A."). Costs this much latency per turn; 0 disables. */
+    utteranceMergeMs: number;
+    /** heuristic (non-AEC) energy barge-in tuning */
+    bargeRmsMult: number;
+    bargeRmsFloor: number;
+}
+declare class VoiceEngine {
+    options: VoiceEngineOptions;
+    state: VoiceState;
+    protected stt: SttLike;
+    protected tts: TtsLike;
+    protected player: AudioSink;
+    private speaking;
+    private ctxOpen;
+    private interrupted;
+    private spokeDeltas;
+    private drainTimer;
+    private echoWords;
+    private prevReply;
+    private reply;
+    private echoUntil;
+    private baseline;
+    private hot;
+    private suspectUntil;
+    private ackAt;
+    private pendingUtt;
+    private pendingTimer;
+    private lastInterrupted;
+    constructor(options?: Partial<VoiceEngineOptions>);
+    start(): Promise<void>;
+    get usingAec(): boolean;
+    private idleWaiters;
+    private setState;
+    /** Resolve when the engine is no longer speaking (immediate if already idle). */
+    awaitIdle(): Promise<void>;
+    /** open a spoken turn (idempotent — safe from both onUtterance and first-delta paths).
+     *  `ack` speaks the configured micro-ack as the context opener (utterance path only —
+     *  masks LLM TTFT; re-voice turns begun by their first delta skip it). */
+    beginSpeech(ack?: boolean): void;
+    speakDelta(text: string): void;
+    /** close the spoken turn (idempotent); stays audible until ALL audio arrived AND playback drains */
+    endSpeech(): void;
+    /** text of the reply cut by the last barge-in — consumed by the host to tell the model what
+     *  the user did NOT hear. Cleared on read. */
+    takeInterruptedReply(): {
+        full: string;
+        heard: string;
+    } | null;
+    /** barge-in: stop audio NOW, cancel generation, reset for the user's utterance */
+    interrupt(): void;
+    stop(): void;
+    private words;
+    private novelWords;
+    private echoActive;
+    private handlePartial;
+    private handleUtterance;
+    private flushUtterance;
+    /** energy two-stage barge-in (heuristic tier only): spike over echo baseline → pause + confirm via STT */
+    private handleLevel;
+}
+
+declare class SonioxSTTOptions {
+    auth: AuthProvider;
+    source: AudioSource;
+    model: string;
+    languageHints: string[];
+}
+declare class SonioxSTT {
+    options: SonioxSTTOptions;
+    private ws;
+    private stopped;
+    private sourceStarted;
+    onPartial: (text: string) => void;
+    onUtterance: (text: string, endpointAt: number) => void;
+    /** mic energy (RMS) per chunk — drives the energy-based heuristic barge-in tier */
+    onLevel: (rms: number) => void;
+    private finalText;
+    private partialText;
+    constructor(options?: Partial<SonioxSTTOptions>);
+    get usingAec(): boolean;
+    private connectWs;
+    start(): Promise<void>;
+    private handle;
+    reset(): void;
+    stop(): void;
+}
+
+declare class CartesiaTTSOptions {
+    auth: AuthProvider;
+    voiceId: string;
+    model: string;
+    /** 'apiKey' (server/CLI) → `api_key=` URL param; 'token' (browser, BE-minted) → `access_token=`. */
+    authMode: 'apiKey' | 'token';
+}
+declare class CartesiaTTS {
+    options: CartesiaTTSOptions;
+    private ws;
+    private ctxSeq;
+    ctxId: string;
+    onAudio: (chunk: Uint8Array) => void;
+    onDone: () => void;
+    firstAudioAt: number;
+    constructor(options?: Partial<CartesiaTTSOptions>);
+    connect(): Promise<void>;
+    newContext(): string;
+    private frame;
+    speak(text: string, cont: boolean): void;
+    end(): void;
+    cancel(): void;
+    close(): void;
+}
+
+export { Agent, type AgentDef, AgentOptions, AgentTool, type Attempt, type AudioSink, type AudioSource, type AuthProvider, BodDbFilesystem, CartesiaTTS, CartesiaTTSOptions, ChatLike, ChatOptions, ChatResponse, type CommandInfo, ConsoleHostBridge, DEFAULT_DENY, DuplexAgent, DuplexAgentOptions, type DuplexTaskStatus, FakeAIClient, Hooks, HostBridge, JailOptions, JailedFilesystem, type LessonOptions, LessonOptionsDefaults, MessageContent, type Mount, MountFilesystem, NodeDiskFilesystem, OverlayFilesystem, type ReflectOptions, RunResult, STT_SAMPLE_RATE, ScriptedHostBridge, type SkillInfo, SonioxSTT, SonioxSTTOptions, type SttLike, TTS_SAMPLE_RATE, type TaskRecord, type TaskToolOptions, ToolCall, type ToolSpec, type TtsLike, UserQuestion, VOICE_SYSTEM_PROMPT, VoiceEngine, VoiceEngineOptions, type VoiceState, type WebFetchOptions, type WebSearchOptions, applyEditsTool, askUserQuestionTool, checkpointTool, checkpointTools, compileSynthesizedTool, diskAgentOptions, expandCommand, expandTemplate, forComponent, fullAgentOptions, globTool, grepTool, htmlToText, idfWeights, lessonCapture, loadAgents, loadCommands, loadInstructions, loadMemory, loadSkills, makeTaskBatchTool, makeTaskTool, makeWebFetchTool, makeWebSearchTool, mkdirp, multiEditTool, raceAttempts, reflectOnRun, relevanceScore, repoIndex, repoMapTool, resolveAuth, rollbackTool, sandboxAgentOptions, slugify, tokenize, toolCall, topByRelevance, validateToolCode, webFetchTool, webSearchTool, writeFact, writeTool };