mu-harness 0.32.0 → 0.33.0

package/esm/channels/ws/client.js

@@ -44,6 +44,26 @@ export async function connectHarness(opts) {
     const listWaiters = [];
     const modelWaiters = [];
     const rawWaiters = new Map();
+    const voiceWaiters = new Map();
+    const voiceCheckWaiters = new Map();
+    // Settle every request-keyed voice waiter so transcribe()/unavailableReason()
+    // never hang when the socket drops (or the server tears the connection down,
+    // e.g. an oversized frame). voice:check resolves with a reason string (its
+    // contract is `string | undefined`) so the caller shows an error rather than
+    // throwing; voice:transcribe rejects.
+    const failVoiceWaiters = (message) => {
+        const err = new Error(message);
+        for (const w of voiceWaiters.values())
+            w.reject(err);
+        voiceWaiters.clear();
+        for (const resolve of voiceCheckWaiters.values())
+            resolve(message);
+        voiceCheckWaiters.clear();
+        for (const w of subagentWaiters.values())
+            w.reject(err);
+        subagentWaiters.clear();
+    };
+    client.onClose(() => failVoiceWaiters('connection lost'));
     const agentsReady = deferred();
     const route = (sessionId, event) => sessionsById.get(sessionId)?._emit(event);
     const applyRaw = (sessionId, messages) => {
@@ -164,7 +184,9 @@ export async function connectHarness(opts) {
                     cwd: opts.cwd,
                     createdAt: s.createdAt,
                 }));
-                listWaiters.shift()?.(records);
+                const waiters = listWaiters.splice(0);
+                for (const w of waiters)
+                    w(records);
                 return;
             }
             case 'sessions:raw':
@@ -182,6 +204,18 @@ export async function connectHarness(opts) {
                 subagentWaiters.get(frame.requestId)?.reject(new Error(frame.message));
                 subagentWaiters.delete(frame.requestId);
                 return;
+            case 'voice:availability':
+                voiceCheckWaiters.get(frame.requestId)?.(frame.reason);
+                voiceCheckWaiters.delete(frame.requestId);
+                return;
+            case 'voice:result':
+                voiceWaiters.get(frame.requestId)?.resolve(frame.text);
+                voiceWaiters.delete(frame.requestId);
+                return;
+            case 'voice:error':
+                voiceWaiters.get(frame.requestId)?.reject(new Error(frame.message));
+                voiceWaiters.delete(frame.requestId);
+                return;
             case 'approval_request': {
                 const req = { id: frame.requestId, name: frame.toolName, input: parseArgs(frame.args) };
                 for (const l of [...approvalListeners])
@@ -309,6 +343,30 @@ export async function connectHarness(opts) {
             modelLoadingListeners.add(listener);
             return () => modelLoadingListeners.delete(listener);
         },
+        voice: {
+            unavailableReason: () => new Promise((resolve) => {
+                const requestId = crypto.randomUUID();
+                voiceCheckWaiters.set(requestId, resolve);
+                if (!client.send({ type: 'voice:check', requestId })) {
+                    voiceCheckWaiters.delete(requestId);
+                    resolve('voice unavailable: not connected');
+                }
+            }),
+            transcribe: (data, mime) => new Promise((resolve, reject) => {
+                const requestId = crypto.randomUUID();
+                voiceWaiters.set(requestId, { resolve, reject });
+                const sent = client.send({
+                    type: 'voice:transcribe',
+                    requestId,
+                    mime,
+                    data: Buffer.from(data).toString('base64'),
+                });
+                if (!sent) {
+                    voiceWaiters.delete(requestId);
+                    reject(new Error('not connected'));
+                }
+            }),
+        },
         banner: opts.banner,
         minimal: opts.minimal,
         commands: () => commands.map((c) => ({ name: c.command.replace(/^\//, ''), description: c.description })),

package/esm/channels/ws/protocol.d.ts

@@ -62,6 +62,14 @@ export type WsInbound = {
 } | {
     type: 'sessions:get';
     sessionId: string;
+} | {
+    type: 'voice:check';
+    requestId: string;
+} | {
+    type: 'voice:transcribe';
+    requestId: string;
+    mime: string;
+    data: string;
 };
 export declare function parseInbound(raw: unknown): WsInbound | {
     error: string;
@@ -217,6 +225,18 @@ export type WsOutbound = {
     type: 'subagent:error';
     requestId: string;
     message: string;
+} | {
+    type: 'voice:availability';
+    requestId: string;
+    reason?: string;
+} | {
+    type: 'voice:result';
+    requestId: string;
+    text: string;
+} | {
+    type: 'voice:error';
+    requestId: string;
+    message: string;
 } | {
     type: 'sessions:listed';
     sessions: SessionSummaryWire[];

package/esm/channels/ws/protocol.js

@@ -24,7 +24,12 @@ export function parseInbound(raw) {
             if (typeof o.text !== 'string')
                 return { error: 'chat requires text:string' };
             const attachments = parseAttachments(o.attachments);
-            return { type: 'chat', sessionId: optionalString(o.sessionId), text: o.text, ...(attachments ? { attachments } : {}) };
+            return {
+                type: 'chat',
+                sessionId: optionalString(o.sessionId),
+                text: o.text,
+                ...(attachments ? { attachments } : {}),
+            };
         }
         case 'command': {
             if (typeof o.text !== 'string')
@@ -102,6 +107,22 @@ export function parseInbound(raw) {
                 return { error: 'sessions:get requires sessionId' };
             return { type: 'sessions:get', sessionId: o.sessionId };
         }
+        case 'voice:check': {
+            const requestId = typeof o.requestId === 'string' ? o.requestId : '';
+            if (!requestId)
+                return { error: 'voice:check requires requestId' };
+            return { type: 'voice:check', requestId };
+        }
+        case 'voice:transcribe': {
+            const requestId = typeof o.requestId === 'string' ? o.requestId : '';
+            if (!requestId)
+                return { error: 'voice:transcribe requires requestId' };
+            if (typeof o.mime !== 'string' || !o.mime)
+                return { error: 'voice:transcribe requires mime:string' };
+            if (typeof o.data !== 'string' || !o.data)
+                return { error: 'voice:transcribe requires data:string (base64)' };
+            return { type: 'voice:transcribe', requestId, mime: o.mime, data: o.data };
+        }
         default:
             return { error: `unknown message type: ${type || '<empty>'}` };
     }

package/esm/channels/ws/server.js

@@ -89,7 +89,11 @@ export function webSocketAdapter(opts) {
             const allowed = attachments.filter((a) => (a.kind === 'image' ? caps.vision : caps.audio));
             if (allowed.length < attachments.length) {
                 const kinds = [...new Set(attachments.filter((a) => !allowed.includes(a)).map((a) => a.kind))].join('/');
-                push({ type: 'error', sessionId, message: `the active model has no ${kinds} capability — attachment(s) dropped` });
+                push({
+                    type: 'error',
+                    sessionId,
+                    message: `the active model has no ${kinds} capability — attachment(s) dropped`,
+                });
             }
             if (allowed.length === 0)
                 return body;
@@ -233,6 +237,25 @@ export function webSocketAdapter(opts) {
                     });
                     return;
                 }
+                case 'voice:check': {
+                    const reason = await harness.voice.unavailableReason().catch((err) => err instanceof Error ? err.message : String(err));
+                    send(client.ws, { type: 'voice:availability', requestId: msg.requestId, reason: reason ?? undefined });
+                    return;
+                }
+                case 'voice:transcribe': {
+                    try {
+                        const text = await harness.voice.transcribe(new Uint8Array(Buffer.from(msg.data, 'base64')), msg.mime);
+                        send(client.ws, { type: 'voice:result', requestId: msg.requestId, text });
+                    }
+                    catch (err) {
+                        send(client.ws, {
+                            type: 'voice:error',
+                            requestId: msg.requestId,
+                            message: err instanceof Error ? err.message : String(err),
+                        });
+                    }
+                    return;
+                }
             }
         }
         function handleApprovalResponse(client, requestId, action) {

package/esm/channels/ws/ws-client.d.ts

@@ -6,8 +6,13 @@ export interface WsClientOptions {
 }
 export interface WsClient {
     connect(): Promise<void>;
-    send(frame: WsInbound): void;
+    /** Returns false (frame dropped) when the socket is not OPEN, so callers can
+     * settle a just-registered request waiter instead of hanging forever. */
+    send(frame: WsInbound): boolean;
     on(handler: (frame: WsOutbound) => void): () => void;
+    /** Fires once when the socket closes (after a normal close or an error), so the
+     * caller can reject any in-flight request waiters. */
+    onClose(handler: () => void): () => void;
     close(): Promise<void>;
 }
 export declare function createWsClient(opts: WsClientOptions): WsClient;

package/esm/channels/ws/ws-client.js

@@ -1,7 +1,9 @@
 import { WebSocket } from 'ws';
 export function createWsClient(opts) {
     const handlers = new Set();
+    const closeHandlers = new Set();
     let ws = null;
+    let closeNotified = false;
     const url = () => {
         const u = new URL(opts.url);
         if (opts.token)
@@ -10,14 +12,25 @@ export function createWsClient(opts) {
             u.searchParams.set('sessionId', opts.sessionId);
         return u.toString();
     };
+    const notifyClose = () => {
+        if (closeNotified)
+            return;
+        closeNotified = true;
+        for (const h of [...closeHandlers])
+            h();
+    };
     return {
         connect: () => new Promise((resolve, reject) => {
             const socket = new WebSocket(url());
             ws = socket;
+            closeNotified = false;
             socket.on('open', () => resolve());
             // Pre-open failures reject connect(); post-open the promise is settled and
             // this is a harmless no-op that keeps the error handled.
             socket.on('error', (err) => reject(err));
+            // Fires on both a remote close and after an error tears the socket down;
+            // lets connectHarness reject in-flight request waiters instead of hanging.
+            socket.on('close', () => notifyClose());
             socket.on('message', (data) => {
                 let frame;
                 try {
@@ -31,13 +44,20 @@ export function createWsClient(opts) {
             });
         }),
         send: (frame) => {
-            if (ws && ws.readyState === WebSocket.OPEN)
+            if (ws && ws.readyState === WebSocket.OPEN) {
                 ws.send(JSON.stringify(frame));
+                return true;
+            }
+            return false;
         },
         on: (handler) => {
             handlers.add(handler);
             return () => handlers.delete(handler);
         },
+        onClose: (handler) => {
+            closeHandlers.add(handler);
+            return () => closeHandlers.delete(handler);
+        },
         close: () => new Promise((resolve) => {
             const socket = ws;
             ws = null;

package/esm/harness/create.js

@@ -16,6 +16,7 @@ import { dirsForPath, loadInstructions } from './instructions.js';
 import { createMemoryStore, createRememberTool } from './memory.js';
 import { createCompactionHook } from './compaction.js';
 import { createModelRegistry } from './models.js';
+import { createVoice } from './voice.js';
 const TITLE_AGENT = {
     name: 'title',
     description: 'Generates a concise session title from the first user message.',
@@ -23,7 +24,18 @@ const TITLE_AGENT = {
     tools: [],
 };
 /** Tool-input field names that carry filesystem paths — used to scope nested AGENTS.md. */
-const PATH_KEYS = new Set(['path', 'file', 'filename', 'file_path', 'filepath', 'dir', 'directory', 'cwd', 'paths', 'files']);
+const PATH_KEYS = new Set([
+    'path',
+    'file',
+    'filename',
+    'file_path',
+    'filepath',
+    'dir',
+    'directory',
+    'cwd',
+    'paths',
+    'files',
+]);
 function pathsFromInput(input) {
     if (!input || typeof input !== 'object')
         return [];
@@ -33,10 +45,11 @@ function pathsFromInput(input) {
             continue;
         if (typeof value === 'string')
             out.push(value);
-        else if (Array.isArray(value))
+        else if (Array.isArray(value)) {
             for (const el of value)
                 if (typeof el === 'string')
                     out.push(el);
+        }
     }
     return out;
 }
@@ -45,6 +58,7 @@ export const createHarness = async (options) => {
     const cwd = options.cwd ?? process.cwd();
     const config = createHarnessConfig({ hostName, xdg });
     const models = createModelRegistry({ providers, default: model });
+    const voice = createVoice(models, options.voice);
     const pluginsDir = join(config.configDir, 'plugins');
     const agentsDir = agentDirs?.config ?? join(config.configDir, 'agents');
     const localAgentsDir = agentDirs?.local ?? join(cwd, 'agents');
@@ -155,17 +169,16 @@ export const createHarness = async (options) => {
         ...models.resolve(opts.model ?? agent.model),
         id: newId(),
     });
+    // Hooks every session gets regardless of how it was created (fresh spawn vs revived
+    // from disk). spawn/revive each prepend their own allow-list + approval hook to these.
+    const baseHooks = [envHook, instructionsHook, memoryHook, trackPathsHook, compactionHook];
     const spawn = (agent) => persistTo(store, persona(agent, {
         tools: sessionTools(agent),
         hooks: mergeHooks([
             sessionDefaults.hooks,
             allowList(toolNames(agent)),
             approvalHook(() => agent),
-            envHook,
-            instructionsHook,
-            memoryHook,
-            trackPathsHook,
-            compactionHook,
+            ...baseHooks,
         ]),
     }));
     const scheduler = enableScheduler && tasks
@@ -205,6 +218,12 @@ export const createHarness = async (options) => {
         newId,
         cwd,
         title: title === false ? undefined : ({ id, text }) => {
+            // Internal/hidden sessions (id prefixed with `__`, e.g. a voice STT scratch
+            // session) are machinery, not conversations: don't spend a title-model turn
+            // on them — it both wastes a call and interleaves the main model into an
+            // otherwise single-model flow.
+            if (id.startsWith('__'))
+                return;
             void runTitler({
                 id,
                 text,
@@ -217,11 +236,7 @@ export const createHarness = async (options) => {
             hooks: mergeHooks([
                 sessionDefaults.hooks,
                 approvalHook(() => approvals?.activeAgent()),
-                envHook,
-                instructionsHook,
-                memoryHook,
-                trackPathsHook,
-                compactionHook,
+                ...baseHooks,
             ]),
             tools: sessionTools(undefined, [createSubAgentTool({ registry: agents, spawn, runs, parentId: id })]),
             ...models.resolve(ref),
@@ -259,6 +274,7 @@ export const createHarness = async (options) => {
     return {
         config,
         models,
+        voice,
         plugins,
         sessions,
         agents,

package/esm/harness/index.d.ts

@@ -4,3 +4,4 @@ export { type CompactionOptions, createCompactionHook } from './compaction.js';
 export { createMemoryStore, createRememberTool, type MemoryScope, type MemoryStore } from './memory.js';
 export { loadInstructions } from './instructions.js';
 export { createModelRegistry, type ModelRegistry, type ModelRegistryOptions, type ResolvedModel } from './models.js';
+export { createVoice, VOICE_UNAVAILABLE, type VoiceOptions, type VoiceTranscriber } from './voice.js';

package/esm/harness/index.js

@@ -3,3 +3,4 @@ export { createCompactionHook } from './compaction.js';
 export { createMemoryStore, createRememberTool } from './memory.js';
 export { loadInstructions } from './instructions.js';
 export { createModelRegistry } from './models.js';
+export { createVoice, VOICE_UNAVAILABLE } from './voice.js';

package/esm/harness/types.d.ts

@@ -10,6 +10,7 @@ import type { Skill, SkillRegistry } from '../skills/index.js';
 import type { SubAgentRegistry, SubAgentResult } from '../subAgents/index.js';
 import type { CompactionOptions } from './compaction.js';
 import type { ModelRegistry } from './models.js';
+import type { VoiceTranscriber } from './voice.js';
 export type HarnessOptions = HarnessConfigOptions & Omit<AgentSessionConfig, 'provider' | 'model' | 'id' | 'messages'> & {
     providers: Record<string, Provider>;
     model: string;
@@ -25,6 +26,10 @@ export type HarnessOptions = HarnessConfigOptions & Omit<AgentSessionConfig, 'pr
     cwd?: string;
     sourceUrl?: string;
     scheduler?: boolean;
+    /** Speech-to-text for `/voice`. `model` is sent recorded audio; falls back to the selected model when unset. */
+    voice?: {
+        model?: string;
+    };
     /** Auto-compaction settings, or `false` to disable. Default: enabled at 80% of the window. */
     compaction?: CompactionOptions | false;
     approvals?: {
@@ -39,6 +44,7 @@ export type HarnessOptions = HarnessConfigOptions & Omit<AgentSessionConfig, 'pr
 export interface Harness {
     readonly config: HarnessConfig;
     readonly models: ModelRegistry;
+    readonly voice: VoiceTranscriber;
     readonly plugins: PluginStore;
     readonly sessions: SessionManager;
     readonly agents: AgentRegistry;

package/esm/harness/voice.d.ts

@@ -0,0 +1,10 @@
+import type { ModelRegistry } from './models.js';
+export declare const VOICE_UNAVAILABLE = "voiceModel not configured and the current model doesn't support sound";
+export interface VoiceOptions {
+    model?: string;
+}
+export interface VoiceTranscriber {
+    transcribe(data: Uint8Array, mime: string): Promise<string>;
+    unavailableReason(): Promise<string | undefined>;
+}
+export declare const createVoice: (models: ModelRegistry, options?: VoiceOptions) => VoiceTranscriber;

package/esm/harness/voice.js

@@ -0,0 +1,38 @@
+import { audio } from 'mu-core';
+const TRANSCRIBE_PROMPT = 'Transcribe the speech in this audio verbatim. Output only the transcribed words as plain text, with no preamble, quotes, commentary, or translation. If there is no intelligible speech, output nothing.';
+export const VOICE_UNAVAILABLE = "voiceModel not configured and the current model doesn't support sound";
+export const createVoice = (models, options = {}) => {
+    const ref = () => {
+        if (!options.model)
+            return models.selected;
+        if (options.model.includes('/'))
+            return options.model;
+        const prefix = models.selected.split('/')[0];
+        return `${prefix}/${options.model}`;
+    };
+    const unavailableReason = async () => {
+        if (options.model)
+            return undefined;
+        const caps = await models.capabilities(ref()).catch(() => undefined);
+        return caps?.audio ? undefined : VOICE_UNAVAILABLE;
+    };
+    return {
+        unavailableReason,
+        transcribe: async (data, mime) => {
+            const reason = await unavailableReason();
+            if (reason)
+                throw new Error(reason);
+            const { provider, model } = models.resolve(ref());
+            const messages = [{
+                    role: 'user',
+                    content: [{ type: 'text', text: TRANSCRIBE_PROMPT }, audio(mime, data)],
+                }];
+            let text = '';
+            for await (const event of provider.stream({ model, messages, tools: [] })) {
+                if (event.type === 'text')
+                    text += event.text;
+            }
+            return text.trim();
+        },
+    };
+};

package/esm/permissions/approval-manager.js

@@ -1,4 +1,3 @@
-import { requireApproval } from './approval.js';
 const denied = (name) => [{ type: 'text', text: `Denied: ${name}` }];
 export const createApprovalManager = (options = {}) => {
     const askTools = options.askTools ? new Set(options.askTools) : undefined;
@@ -14,11 +13,6 @@ export const createApprovalManager = (options = {}) => {
             listener(req);
     });
     const defaultNeeds = options.needsApproval ?? (({ name }) => (askTools ? askTools.has(name) : true));
-    const hooks = requireApproval({
-        needsApproval: (call) => defaultNeeds(call) && !alwaysAllow.has(keyOf(undefined, call.name)),
-        newId,
-        prompt: (call) => request(call.id, call.name, call.input, undefined),
-    });
     const hooksFor = ({ decide, agent }) => ({
         beforeToolCall: async (call) => {
             const decision = decide(call);
@@ -33,6 +27,9 @@ export const createApprovalManager = (options = {}) => {
             return allow ? undefined : denied(call.name);
         },
     });
+    // Default hooks (no per-agent policy): ask for every tool that needs approval, allow the
+    // rest. Defined via hooksFor so the beforeToolCall flow lives in exactly one place.
+    const hooks = hooksFor({ decide: (call) => (defaultNeeds(call) ? 'ask' : 'allow') });
     return {
         hooks,
         hooksFor,

package/esm/session/decorate.d.ts

@@ -0,0 +1,9 @@
+import type { ContentPart } from 'mu-core';
+import type { AgentSession } from './types.js';
+/**
+ * Wrap an AgentSession, overriding ONLY `send`. Every other member is forwarded
+ * to the inner session verbatim. The "decorator skeleton" lives here so the
+ * persistence wrapper (persistTo) and the title-on-first-message wrapper share
+ * one passthrough definition instead of each re-listing every AgentSession field.
+ */
+export declare const decorateSession: (session: AgentSession, send: (input: string | ContentPart[]) => Promise<void>) => AgentSession;

package/esm/session/decorate.js

@@ -0,0 +1,25 @@
+/**
+ * Wrap an AgentSession, overriding ONLY `send`. Every other member is forwarded
+ * to the inner session verbatim. The "decorator skeleton" lives here so the
+ * persistence wrapper (persistTo) and the title-on-first-message wrapper share
+ * one passthrough definition instead of each re-listing every AgentSession field.
+ */
+export const decorateSession = (session, send) => ({
+    get id() {
+        return session.id;
+    },
+    get messages() {
+        return session.messages;
+    },
+    get tools() {
+        return session.tools;
+    },
+    model: session.model,
+    assembleRequest: session.assembleRequest?.bind(session),
+    countTokens: session.countTokens?.bind(session),
+    contextWindow: session.contextWindow?.bind(session),
+    compact: session.compact?.bind(session),
+    send,
+    abort: session.abort,
+    subscribe: session.subscribe,
+});

package/esm/session/manager.js

@@ -1,32 +1,15 @@
+import { decorateSession } from './decorate.js';
 import { persistTo } from './persist.js';
 const inputText = (input) => typeof input === 'string' ? input : input.map((part) => (part.type === 'text' ? part.text : '')).join('');
 const onFirstMessage = (session, fire) => {
     let pending = !session.messages.some((message) => message.role === 'user');
-    return {
-        get id() {
-            return session.id;
-        },
-        get messages() {
-            return session.messages;
-        },
-        get tools() {
-            return session.tools;
-        },
-        model: session.model,
-        assembleRequest: session.assembleRequest?.bind(session),
-        countTokens: session.countTokens?.bind(session),
-        contextWindow: session.contextWindow?.bind(session),
-        compact: session.compact?.bind(session),
-        send: async (input) => {
-            if (pending) {
-                pending = false;
-                fire({ id: session.id, text: inputText(input) });
-            }
-            await session.send(input);
-        },
-        abort: session.abort,
-        subscribe: session.subscribe,
-    };
+    return decorateSession(session, async (input) => {
+        if (pending) {
+            pending = false;
+            fire({ id: session.id, text: inputText(input) });
+        }
+        await session.send(input);
+    });
 };
 export const createSessionManager = ({ store, catalog, revive, newId, cwd, title }) => ({
     create: (options) => {

package/esm/session/persist.js

@@ -1,29 +1,18 @@
+import { decorateSession } from './decorate.js';
 export const persistTo = (store, session, persisted = 0) => {
     let count = persisted;
-    return {
-        get id() {
-            return session.id;
-        },
-        get messages() {
-            return session.messages;
-        },
-        get tools() {
-            return session.tools;
-        },
-        model: session.model,
-        assembleRequest: session.assembleRequest?.bind(session),
-        countTokens: session.countTokens?.bind(session),
-        contextWindow: session.contextWindow?.bind(session),
-        compact: session.compact?.bind(session),
-        send: async (input) => {
-            await session.send(input);
-            const all = session.messages;
-            if (all.length > count) {
-                await store.append(session.id, all.slice(count));
-                count = all.length;
-            }
-        },
-        abort: session.abort,
-        subscribe: session.subscribe,
-    };
+    let last = count > 0 ? session.messages[count - 1] : undefined;
+    return decorateSession(session, async (input) => {
+        await session.send(input);
+        const all = session.messages;
+        const intact = count === 0 || all[count - 1] === last;
+        if (!intact) {
+            await store.rewrite(session.id, all);
+        }
+        else if (all.length > count) {
+            await store.append(session.id, all.slice(count));
+        }
+        count = all.length;
+        last = all.length > 0 ? all[all.length - 1] : undefined;
+    });
 };

package/esm/session/store.d.ts

@@ -6,6 +6,7 @@ export interface StoredSession {
 export interface SessionStore {
     load(id: string): Promise<StoredSession>;
     append(id: string, messages: Message[]): Promise<void>;
+    rewrite(id: string, messages: readonly Message[]): Promise<void>;
     delete(id: string): Promise<void>;
 }
 export declare const createSessionStore: ({ dir }: {