voicemode-channel 0.2.0 → 0.3.1

package/dist/gateway.js

@@ -268,7 +268,7 @@ export class GatewayClient extends EventEmitter {
             type: 'ready',
             device: {
                 platform: 'channel-server',
-                appVersion: '0.1.4',
+                appVersion: '0.2.1',
                 name: `channel@${hostname()}`,
             },
         };

package/dist/index.js

@@ -20,6 +20,7 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { randomBytes } from 'node:crypto';
 import { GatewayClient, get_project_context } from './gateway.js';
+import { write_message, list_messages, read_message, mark_read, count_unread } from './maildir.js';
 import { login } from './auth.js';
 import { load_credentials, is_expired, CREDENTIALS_FILE, get_valid_token } from './credentials.js';
 // ---------------------------------------------------------------------------
@@ -121,7 +122,16 @@ if (process.env.VOICEMODE_CHANNEL_ENABLED !== 'true') {
 }
 const WS_URL = process.env.VOICEMODE_CONNECT_WS_URL ?? 'wss://voicemode.dev/ws';
 const CHANNEL_NAME = 'voicemode-channel';
-const CHANNEL_VERSION = '0.1.4';
+// Read version from package.json at runtime to avoid hardcoded version drift
+const CHANNEL_VERSION = (() => {
+    try {
+        const pkg_path = new URL('../package.json', import.meta.url);
+        return JSON.parse(readFileSync(pkg_path, 'utf8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
 const INSTRUCTIONS = [
     'Events from VoiceMode appear as <channel source="voicemode-channel" caller="NAME">TRANSCRIPT</channel>.',
     'These are inbound voice messages from a user speaking on their phone or web app.',
@@ -141,6 +151,9 @@ let currentProfile = {
     voice: null,
     presence: 'available',
 };
+// Track the last inbound caller name so outbound replies can reference it.
+// Falls back to 'user' if no inbound message has been received yet.
+let last_caller_name = 'user';
 // ---------------------------------------------------------------------------
 // MCP server with channel capability
 // ---------------------------------------------------------------------------
@@ -167,7 +180,8 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => {
                 name: 'reply',
                 description: 'Send a voice reply to the user through VoiceMode. ' +
                     'Use this to respond to inbound voice channel events. ' +
-                    'The reply is spoken aloud on the user\'s device via TTS.',
+                    'The reply is spoken aloud on the user\'s device via TTS. ' +
+                    'Pass in_reply_to to mark the source message with the R (Replied) flag.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -183,6 +197,10 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => {
                             type: 'boolean',
                             description: 'Whether to listen for user response after speaking (default: false)',
                         },
+                        in_reply_to: {
+                            type: 'string',
+                            description: 'Filename of the inbound message being replied to; receives R flag on successful send',
+                        },
                     },
                     required: ['text'],
                 },
@@ -228,6 +246,89 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => {
                     },
                 },
             },
+            {
+                name: 'list_messages',
+                description: 'List voice messages from the Maildir conversation history. ' +
+                    'By default, only shows messages from the current agent session. ' +
+                    'Use all_sessions to see messages from all sessions. ' +
+                    'Pass include_body: true to fetch bodies in bulk (truncated by body_max_length). ' +
+                    'Pass unread: true to see only unread messages (no S flag).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        all_sessions: {
+                            type: 'boolean',
+                            description: 'If true, show messages from all sessions (default: false, current session only)',
+                        },
+                        direction: {
+                            type: 'string',
+                            description: 'Filter by message direction',
+                            enum: ['inbound', 'outbound'],
+                        },
+                        limit: {
+                            type: 'number',
+                            description: 'Maximum number of messages to return (default: 50)',
+                        },
+                        include_body: {
+                            type: 'boolean',
+                            description: 'If true, include message bodies in the response (default: false)',
+                        },
+                        body_max_length: {
+                            type: 'number',
+                            description: 'Max body length when include_body is true; 0 = unlimited (default: 2000)',
+                        },
+                        unread: {
+                            type: 'boolean',
+                            description: 'If true, only return unread messages; if false, only read; omit for both',
+                        },
+                    },
+                },
+            },
+            {
+                name: 'read_message',
+                description: 'Read the full content of a voice message by filename. ' +
+                    'Use list_messages first to find message filenames. ' +
+                    'By default, marks the message as Seen (moves from new/ to cur/ with S flag). ' +
+                    'Pass mark_read: false to leave the message unread.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        filename: {
+                            type: 'string',
+                            description: 'The message filename (e.g. "vm-abc123def456")',
+                        },
+                        mark_read: {
+                            type: 'boolean',
+                            description: 'Whether to mark the message as Seen on read (default: true)',
+                        },
+                    },
+                    required: ['filename'],
+                },
+            },
+            {
+                name: 'mark_read',
+                description: 'Apply Maildir flags to one or more messages (bulk supported). ' +
+                    'Default flag is "S" (Seen). Files are moved from new/ to cur/ with a ' +
+                    ':2,FLAGS suffix per the Maildir spec. Flags are merged with any existing ' +
+                    'flags on the file (e.g. marking an "R" message as Seen yields ":2,RS"). ' +
+                    'Use this when you want to mark multiple messages read in one call, or to ' +
+                    'apply non-Seen flags (R=Replied, F=Flagged, T=Trashed, D=Draft).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        filenames: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Message filenames to mark (from list_messages)',
+                        },
+                        flags: {
+                            type: 'string',
+                            description: 'Flag letters to apply, e.g. "S", "RS" (default: "S")',
+                        },
+                    },
+                    required: ['filenames'],
+                },
+            },
         ],
     };
 });
@@ -242,6 +343,15 @@ mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (name === 'reply') {
         return handle_reply_tool(args);
     }
+    if (name === 'list_messages') {
+        return handle_list_messages_tool(args);
+    }
+    if (name === 'read_message') {
+        return handle_read_message_tool(args);
+    }
+    if (name === 'mark_read') {
+        return handle_mark_read_tool(args);
+    }
     return {
         content: [{ type: 'text', text: `Unknown tool: ${name}` }],
         isError: true,
@@ -280,6 +390,16 @@ function handle_status_tool() {
         lines.push('Auth: not authenticated');
     }
     lines.push('');
+    // Unread message count (supports notification-append pattern)
+    try {
+        const unread = count_unread();
+        lines.push(`Unread: ${unread}`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        lines.push(`Unread: unavailable (${message})`);
+    }
+    lines.push('');
     // Profile
     lines.push(`Profile: set`);
     lines.push(`  Name: ${currentProfile.name}`);
@@ -305,6 +425,9 @@ function handle_reply_tool(args) {
     }
     const voice = typeof args?.voice === 'string' ? args.voice : (currentProfile.voice || undefined);
     const wait_for_response = typeof args?.wait_for_response === 'boolean' ? args.wait_for_response : undefined;
+    const in_reply_to = typeof args?.in_reply_to === 'string' && args.in_reply_to.trim().length > 0
+        ? args.in_reply_to.trim()
+        : undefined;
     // Check gateway connection
     if (!gateway || gateway.state !== 'connected') {
         return {
@@ -332,6 +455,40 @@ function handle_reply_tool(args) {
         };
     }
     log(`Sent reply via gateway: id=${msg_id} text="${truncate(text.trim(), 80)}"`);
+    // Apply R (Replied) flag to the source message when reply-context is provided.
+    // Best-effort -- never break reply flow if the source file is gone.
+    if (in_reply_to) {
+        try {
+            const results = mark_read([in_reply_to], 'R');
+            const r = results[0];
+            if (r?.found) {
+                log(`Marked ${in_reply_to} with R flag -> ${r.new_filename}`, 'DEBUG');
+            }
+            else {
+                log(`R flag: source message not found: ${in_reply_to}`, 'WARN');
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log(`R flag application failed (non-fatal): ${message}`, 'WARN');
+        }
+    }
+    // Persist outbound message to Maildir (best-effort -- never break reply flow)
+    try {
+        write_message({
+            direction: 'outbound',
+            from_name: currentProfile.name,
+            to_name: last_caller_name,
+            text: text.trim(),
+            session_id: gateway.session_id ?? 'unknown',
+            agent_session_id: gateway.agent_session_id ?? 'unknown',
+            agent_name: currentProfile.name,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log(`Maildir write failed (non-fatal): ${message}`, 'WARN');
+    }
     return {
         content: [{
                 type: 'text',
@@ -379,6 +536,118 @@ function handle_profile_tool(args) {
     };
 }
 // ---------------------------------------------------------------------------
+// Tool handler: list_messages
+// ---------------------------------------------------------------------------
+function handle_list_messages_tool(args) {
+    const all_sessions = args?.all_sessions === true;
+    const direction = args?.direction;
+    const limit = typeof args?.limit === 'number' ? Math.max(1, Math.min(args.limit, 500)) : 50;
+    const include_body = args?.include_body === true;
+    const body_max_length = typeof args?.body_max_length === 'number' ? Math.max(0, args.body_max_length) : 2000;
+    const unread = typeof args?.unread === 'boolean' ? args.unread : undefined;
+    // Default to current session unless all_sessions is true
+    const agent_session_id = all_sessions ? undefined : (gateway?.agent_session_id ?? undefined);
+    // Validate direction if provided
+    if (direction !== undefined && direction !== 'inbound' && direction !== 'outbound') {
+        return {
+            content: [{ type: 'text', text: 'Error: direction must be "inbound" or "outbound"' }],
+            isError: true,
+        };
+    }
+    const messages = list_messages({ agent_session_id, direction, limit, include_body, body_max_length, unread });
+    if (messages.length === 0) {
+        const scope = all_sessions ? 'any session' : 'the current session';
+        const state = unread === true ? 'unread ' : unread === false ? 'read ' : '';
+        return {
+            content: [{ type: 'text', text: `No ${state}messages found for ${scope}.` }],
+        };
+    }
+    // When bodies are requested, return structured JSON so the caller can work with them.
+    if (include_body) {
+        return {
+            content: [{ type: 'text', text: JSON.stringify(messages, null, 2) }],
+        };
+    }
+    // Format as a summary list (filename, direction, date, subject preview)
+    const lines = messages.map((msg) => {
+        const dir_arrow = msg.direction === 'inbound' ? '<-' : '->';
+        const preview = msg.subject.length > 60 ? msg.subject.slice(0, 60) + '...' : msg.subject;
+        return `${msg.filename}  ${dir_arrow}  ${msg.date}  ${preview}`;
+    });
+    const header = `Messages (${messages.length}${messages.length >= limit ? '+' : ''}):`;
+    return {
+        content: [{ type: 'text', text: [header, ...lines].join('\n') }],
+    };
+}
+// ---------------------------------------------------------------------------
+// Tool handler: read_message
+// ---------------------------------------------------------------------------
+function handle_read_message_tool(args) {
+    const filename = args?.filename;
+    if (typeof filename !== 'string' || filename.trim().length === 0) {
+        return {
+            content: [{ type: 'text', text: 'Error: filename parameter is required and must be non-empty' }],
+            isError: true,
+        };
+    }
+    // mark_read defaults to true -- callers pass false to opt out
+    const should_mark = typeof args?.mark_read === 'boolean' ? args.mark_read : true;
+    const message = read_message(filename.trim(), { mark_read: should_mark });
+    if (!message) {
+        return {
+            content: [{ type: 'text', text: `Message not found: ${filename}` }],
+            isError: true,
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(message, null, 2) }],
+    };
+}
+// ---------------------------------------------------------------------------
+// Tool handler: mark_read
+// ---------------------------------------------------------------------------
+function handle_mark_read_tool(args) {
+    const filenames_arg = args?.filenames;
+    if (!Array.isArray(filenames_arg) || filenames_arg.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'Error: filenames parameter is required and must be a non-empty array' }],
+            isError: true,
+        };
+    }
+    // Validate each filename is a non-empty string
+    const filenames = [];
+    for (const item of filenames_arg) {
+        if (typeof item !== 'string' || item.trim().length === 0) {
+            return {
+                content: [{ type: 'text', text: 'Error: every filename must be a non-empty string' }],
+                isError: true,
+            };
+        }
+        filenames.push(item.trim());
+    }
+    const flags = typeof args?.flags === 'string' && args.flags.length > 0 ? args.flags : 'S';
+    const results = mark_read(filenames, flags);
+    // Format a human-readable summary alongside the structured result
+    const found_count = results.filter(r => r.found).length;
+    const missing_count = results.length - found_count;
+    const lines = [];
+    lines.push(`mark_read: ${found_count}/${results.length} marked with flags=${flags}`);
+    if (missing_count > 0) {
+        lines.push(`  ${missing_count} not found`);
+    }
+    for (const r of results) {
+        if (r.found) {
+            lines.push(`  [OK]  ${r.filename} -> ${r.new_filename}`);
+        }
+        else {
+            lines.push(`  [??]  ${r.filename} (not found)`);
+        }
+    }
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+    };
+}
+// ---------------------------------------------------------------------------
 // Push a channel notification for an inbound voice event
 // ---------------------------------------------------------------------------
 const EXTERNAL_MESSAGE_PREFIX = '[VoiceMode Connect - External Message]: ';
@@ -472,11 +741,32 @@ function start_gateway() {
         const device_id = typeof user_id === 'string' && user_id.length > 0
             ? user_id
             : undefined;
+        // Remember caller name for outbound reply attribution
+        last_caller_name = caller;
         log(`Received voice event: from="${caller}" text="${truncate(safe_text.trim(), 80)}"`);
         push_voice_event(caller, safe_text.trim(), device_id).catch((err) => {
             const message = err instanceof Error ? err.message : String(err);
             log(`Error pushing voice event to channel: ${message}`);
         });
+        // Persist inbound message to Maildir (best-effort -- never break voice pipeline)
+        try {
+            const filename = write_message({
+                direction: 'inbound',
+                from_name: caller,
+                to_name: currentProfile.name,
+                text: safe_text.trim(),
+                session_id: gateway?.session_id ?? 'unknown',
+                agent_session_id: gateway?.agent_session_id ?? 'unknown',
+                agent_name: currentProfile.name,
+            });
+            if (filename) {
+                log(`Maildir: wrote inbound message ${filename}`, 'DEBUG');
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log(`Maildir write failed (non-fatal): ${message}`, 'WARN');
+        }
     });
     // Start the connection (non-blocking -- reconnects in the background)
     gateway.start().catch((err) => {

package/dist/maildir.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Maildir persistence for VoiceMode voice messages.
+ *
+ * Writes inbound (user speaks) and outbound (agent replies) messages to Maildir
+ * format so they can be indexed by notmuch and accessed via MCP tools.
+ *
+ * Maildir protocol: write to tmp/ first, then rename() to new/ (atomic, no locking).
+ * Dedup: content-hash filename (sha256(from|timestamp|text)[:16]) prevents duplicates.
+ *
+ * Environment variables:
+ *   VOICEMODE_MAILDIR_PATH    Override default ~/.voicemode/maildir/channel
+ *   VOICEMODE_MAILDIR_ENABLED Set to 'false' to disable persistence
+ */
+export interface VoiceMessage {
+    direction: 'inbound' | 'outbound';
+    from_name: string;
+    to_name: string;
+    text: string;
+    session_id: string;
+    agent_session_id: string;
+    agent_name: string;
+    timestamp?: Date;
+}
+export interface MaildirMessage {
+    filename: string;
+    from: string;
+    to: string;
+    date: string;
+    subject: string;
+    direction: string;
+    session_id: string;
+    agent_session_id: string;
+    agent_name: string;
+    body: string;
+}
+export declare function get_maildir_path(): string;
+/**
+ * Write a voice message to Maildir.
+ *
+ * Returns the filename if written (or already exists), null if persistence is disabled.
+ * Uses atomic tmp/ -> new/ rename to guarantee no partial reads.
+ * Silently skips duplicate messages (same from/timestamp/text hash).
+ */
+export declare function write_message(msg: VoiceMessage): string | null;
+/**
+ * Read a single message by filename from the Maildir.
+ *
+ * Security: rejects filenames containing '..' or '/' and verifies the
+ * resolved path is within the Maildir directory. Only returns messages
+ * with X-Transport: voicemode-connect header.
+ *
+ * Base-name lookup: the caller can pass either the bare filename or an
+ * already-flagged `:2,FLAGS` form -- we look up by base name across new/
+ * and cur/, matching the behaviour of mark_read.
+ *
+ * By default, a successful read marks the message as Seen (moves to cur/
+ * with S flag). Pass `{ mark_read: false }` to opt out. The returned
+ * MaildirMessage's `filename` field reflects the on-disk name after any
+ * rename (so callers can use it for subsequent operations).
+ *
+ * Returns null if the file doesn't exist, fails security checks, or
+ * has the wrong X-Transport header.
+ */
+export declare function read_message(filename: string, options?: {
+    mark_read?: boolean;
+}): MaildirMessage | null;
+/** Marker appended to bodies that exceed body_max_length. */
+export declare const TRUNCATION_MARKER = "... [truncated]";
+/**
+ * Truncate a body string to at most `max_length` characters, appending a
+ * clear marker when truncation happens. A `max_length` of 0 means unlimited
+ * (returns the body unchanged). Negative values are treated as 0.
+ */
+export declare function truncate_body(body: string, max_length: number): string;
+/**
+ * List messages from the Maildir, filtered by session, direction, and read state.
+ *
+ * Scans both new/ and cur/ directories. Only includes messages with
+ * X-Transport: voicemode-connect header.
+ *
+ * Options:
+ *   - include_body: when false (default), returned messages have body=''
+ *     to keep responses compact. Set true to return bodies (truncated by
+ *     body_max_length).
+ *   - body_max_length: maximum body length when include_body is true.
+ *     Default 2000. Pass 0 for unlimited. Bodies past the limit get a
+ *     "... [truncated]" marker appended.
+ *   - unread: undefined (default) returns both read and unread. true
+ *     returns only unread messages (in new/, or in cur/ without S flag).
+ *     false returns only read messages (in cur/ with S flag).
+ *
+ * Returns messages sorted by date descending (newest first).
+ */
+export declare function list_messages(options: {
+    agent_session_id?: string;
+    direction?: 'inbound' | 'outbound';
+    limit?: number;
+    include_body?: boolean;
+    body_max_length?: number;
+    unread?: boolean;
+}): MaildirMessage[];
+/**
+ * Parse a Maildir filename into its base and flag components.
+ *
+ * Maildir spec: filenames in cur/ use the form `<base>:2,<flags>` where flags
+ * are ASCII letters sorted alphabetically (e.g. "RS" = Replied + Seen).
+ * Files in new/ typically have no suffix.
+ *
+ * Only the experimental `:2,` variant is recognized -- `:1,` filenames are
+ * treated as having no flags, since that form is not used by notmuch/neomutt.
+ */
+export declare function parse_maildir_filename(filename: string): {
+    base: string;
+    flags: string;
+};
+/**
+ * Merge two flag strings into a single set of unique, alphabetically sorted
+ * uppercase ASCII-letter flags.
+ *
+ * Non-letter characters are dropped. Case is normalized to uppercase.
+ * Duplicates are removed. Output is sorted (standard Maildir flag order).
+ */
+export declare function merge_flags(existing: string, new_flags: string): string;
+/**
+ * Build a full Maildir filename from its base and flag components.
+ * When flags is empty, returns just the base (suitable for new/ files).
+ */
+export declare function build_maildir_filename(base: string, flags: string): string;
+/**
+ * Count unread messages in the Maildir.
+ *
+ * Unread = files in new/ (never touched) + files in cur/ without the S flag.
+ * Filters by filename prefix `vm-` so we don't have to read file contents to
+ * decide whether a file is a voicemode-channel message -- keeps the counter
+ * cheap enough to call on every status check / notification append.
+ */
+export declare function count_unread(): number;
+export interface MarkReadResult {
+    /** The filename as passed in by the caller. */
+    filename: string;
+    /** New filename (with flags applied) if the file was found and renamed. */
+    new_filename: string | null;
+    /** True if the file was located in new/ or cur/. */
+    found: boolean;
+}
+/**
+ * Mark one or more messages with Maildir flags, moving them from new/ to cur/.
+ *
+ * For each filename:
+ *   1. Locate the file by its base name (with or without a :2,FLAGS suffix)
+ *      in either new/ or cur/.
+ *   2. Merge the requested flags with any existing flags (unique, sorted).
+ *   3. Rename the file to `<base>:2,<flags>` in cur/.
+ *
+ * Security: filenames containing '..' or '/' are rejected (returns found=false).
+ *
+ * Idempotent: marking an already-marked file with the same flags is a no-op
+ * rename (the file is already in cur/ with those flags).
+ *
+ * @param filenames Basenames of Maildir files (as returned by list_messages)
+ * @param flags Letters to apply (default "S" = Seen). Case-insensitive.
+ * @returns One result per input filename, in the same order.
+ */
+export declare function mark_read(filenames: string[], flags?: string): MarkReadResult[];