devharness 0.9.8 → 0.9.10

package/build/tools/message-tools.js

@@ -0,0 +1,251 @@
+/**
+ * Message tool - text between two devharness sessions on this machine.
+ *
+ * Transport is `src/session-messages.ts`: one append-only JSONL mailbox per
+ * session under `~/.devharness/messages/`. Discovery reuses the dashboard
+ * hub's session registry, which already holds every live session's short id,
+ * pid and project directory.
+ */
+import { z } from 'zod';
+import { createTool } from '../validation-helpers.js';
+import { createSuccessResponse, createErrorResponse } from '../messages.js';
+import { getProjectDir } from '../helpers/paths.js';
+import { getSessionInfo } from './dashboard-tools.js';
+import { listSessionRecords } from '../session-endpoint.js';
+import { resolveSessionName } from '../session-identity.js';
+import { appendEvent, getEventStreamPath } from '../session-events.js';
+import { isValidMailboxId, getMailboxPath, getMessagesDir, listMailboxIds, readMailbox, readCursor, writeCursor, sendMessage, waitForMailbox, } from '../session-messages.js';
+const messageSchema = z.object({
+    action: z.enum(['sessions', 'send', 'read', 'reply'])
+        .describe('sessions (list reachable sessions and this one\'s mailbox path), send (write to another session), read (take new messages from this session\'s mailbox), reply (answer a message by id)'),
+    to: z.string().optional()
+        .describe('send: recipient mailbox id, as reported by action sessions'),
+    text: z.string().optional()
+        .describe('send/reply: the message body'),
+    replyTo: z.string().optional()
+        .describe('reply: id of the message being answered - the reply goes to its sender'),
+    waitForReplyMs: z.number().int().positive().max(300000).optional()
+        .describe('send/reply: hold the call open until a message arrives in this session\'s mailbox, or this many ms elapse (max 300000). Returns on any arrival, not only a tagged reply.'),
+    pollIntervalMs: z.number().int().min(100).max(5000).optional()
+        .describe('send/reply: interval between mailbox checks while waiting (default 500)'),
+}).strict();
+const DEFAULT_POLL_INTERVAL_MS = 500;
+function buildMeta(action, self, extra) {
+    return {
+        tool: 'message',
+        action,
+        timestamp: Date.now(),
+        message: { action, self, ...extra },
+    };
+}
+/** One line per message, newest last, for the rendered response. */
+function formatMessages(messages) {
+    return messages
+        .map(m => `- [${m.id.slice(0, 8)}] from ${m.from}${m.replyTo ? ` (reply to ${m.replyTo.slice(0, 8)})` : ''} at ${m.at}\n  ${m.text}`)
+        .join('\n');
+}
+export function createMessageTools() {
+    return {
+        message: createTool('Text between two devharness sessions on this machine. Actions: sessions (who is reachable), send (write to another session, optionally holding the call open for a reply), read (take new messages), reply (answer a message by id).', messageSchema, async (args, abortSignal) => {
+            const self = resolveSessionName(getSessionInfo()?.shortId);
+            const pollIntervalMs = args.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+            switch (args.action) {
+                // ---- sessions ------------------------------------------------------
+                case 'sessions': {
+                    // The endpoint records are written by the live child and swept by
+                    // a pid check, so they carry both identity and liveness. The
+                    // dashboard hub holds the same sessions but prunes only on a clean
+                    // socket close, which reports a replaced child as still running.
+                    const records = listSessionRecords();
+                    const mailboxIds = await listMailboxIds();
+                    const rows = [];
+                    const seen = new Set();
+                    for (const record of records) {
+                        const id = record.shortId ?? `pid-${record.pid}`;
+                        if (seen.has(id))
+                            continue;
+                        seen.add(id);
+                        rows.push({ id, pid: record.pid, cwd: record.cwd, live: true, self: id === self });
+                    }
+                    // A mailbox with no session behind it is one that has exited.
+                    // Listing it keeps a reply to a dead session visible, not silent.
+                    for (const id of mailboxIds) {
+                        if (seen.has(id))
+                            continue;
+                        seen.add(id);
+                        rows.push({ id, live: false, self: id === self });
+                    }
+                    if (!seen.has(self)) {
+                        rows.push({ id: self, pid: process.pid, live: true, self: true });
+                    }
+                    const response = createSuccessResponse('MESSAGE_SESSIONS', {
+                        self,
+                        mailboxPath: getMailboxPath(self),
+                        messagesDir: getMessagesDir(),
+                        eventStreamPath: getEventStreamPath(self),
+                        sessionList: rows
+                            .map(r => `- ${r.id}${r.self ? ' (this session)' : ''} - ${r.live ? 'live' : 'no process'}${r.cwd ? ` - ${r.cwd}` : ''}`)
+                            .join('\n'),
+                        count: rows.length,
+                    });
+                    return { ...response, _meta: buildMeta('sessions', self, { sessions: rows }) };
+                }
+                // ---- send / reply --------------------------------------------------
+                case 'send':
+                case 'reply': {
+                    if (!args.text) {
+                        return createErrorResponse('MESSAGE_INVALID_ARGS', {
+                            message: `message({ action: '${args.action}' }) requires text.`,
+                        });
+                    }
+                    let target;
+                    let replyTo;
+                    if (args.action === 'reply') {
+                        if (!args.replyTo) {
+                            return createErrorResponse('MESSAGE_INVALID_ARGS', {
+                                message: "message({ action: 'reply' }) requires replyTo - the id of the message being answered.",
+                            });
+                        }
+                        const own = await readMailbox(self);
+                        const original = own.find(m => m.id === args.replyTo || m.id.startsWith(args.replyTo));
+                        if (!original) {
+                            return createErrorResponse('MESSAGE_TARGET_UNKNOWN', {
+                                target: args.replyTo,
+                                reason: `No message with id "${args.replyTo}" in this session's mailbox`,
+                                self,
+                            });
+                        }
+                        target = original.from;
+                        replyTo = original.id;
+                    }
+                    else {
+                        if (!args.to) {
+                            return createErrorResponse('MESSAGE_INVALID_ARGS', {
+                                message: "message({ action: 'send' }) requires to - a mailbox id from message({ action: 'sessions' }).",
+                            });
+                        }
+                        target = args.to;
+                    }
+                    if (!isValidMailboxId(target)) {
+                        return createErrorResponse('MESSAGE_TARGET_UNKNOWN', {
+                            target,
+                            reason: 'Not a valid mailbox id (letters, digits, dot, dash, underscore; 64 chars max)',
+                            self,
+                        });
+                    }
+                    if (target === self) {
+                        return createErrorResponse('MESSAGE_INVALID_ARGS', {
+                            message: `"${target}" is this session's own mailbox - a message to it would never reach another agent.`,
+                        });
+                    }
+                    // The line count is taken BEFORE the append: a reply that lands
+                    // between the append and the first poll sits past this offset and
+                    // is returned, rather than being counted as already-read.
+                    const fromLine = args.waitForReplyMs ? (await readMailbox(self)).length : 0;
+                    // Where `read` had got to. A mailbox with unread lines sits behind
+                    // fromLine, and advancing the cursor past them would drop them.
+                    const cursorBefore = args.waitForReplyMs ? await readCursor(self) : 0;
+                    const sent = await sendMessage({
+                        from: self,
+                        fromCwd: getProjectDir(),
+                        to: target,
+                        text: args.text,
+                        ...(replyTo ? { replyTo } : {}),
+                    });
+                    // The recipient's Monitor watches its event stream, not its
+                    // mailbox, so the arrival is announced there.
+                    await appendEvent(target, 'message', {
+                        from: self,
+                        id: sent.id,
+                        detail: `Message from ${self}: ${args.text.slice(0, 120)}`,
+                        resolve: "message({ action: 'read' })",
+                    });
+                    // A typo mints a mailbox nothing ever reads, and nothing removes
+                    // one, so the sessions listing grows a fictional peer per slip.
+                    // Refusing would block a genuine first message to a session whose
+                    // server is suspended, which has neither record nor mailbox, so the
+                    // state is reported rather than enforced.
+                    const targetListening = listSessionRecords()
+                        .some(r => (r.shortId ?? `pid-${r.pid}`) === target);
+                    if (!args.waitForReplyMs) {
+                        const response = createSuccessResponse('MESSAGE_SENT', {
+                            to: target,
+                            id: sent.id,
+                            shortId: sent.id.slice(0, 8),
+                            mailboxPath: getMailboxPath(target),
+                            deliveryNote: targetListening
+                                ? ''
+                                : `\n\n**No session is listening as \`${target}\` right now.** It reads this when it next starts, or the id is a typo and nothing ever will - check \`message({ action: 'sessions' })\`.`,
+                        });
+                        return { ...response, _meta: buildMeta(args.action, self, { sent, targetListening }) };
+                    }
+                    const waitStart = Date.now();
+                    const received = await waitForMailbox(self, fromLine, {
+                        timeoutMs: args.waitForReplyMs,
+                        pollIntervalMs,
+                        abortSignal,
+                    });
+                    const waitElapsedMs = Date.now() - waitStart;
+                    if (received.length === 0) {
+                        return {
+                            ...createErrorResponse('MESSAGE_REPLY_TIMEOUT', {
+                                to: target,
+                                timeoutMs: args.waitForReplyMs,
+                                id: sent.id.slice(0, 8),
+                                self,
+                                mailboxPath: getMailboxPath(self),
+                            }),
+                            _meta: buildMeta(args.action, self, { sent, waitTimedOut: true, waitElapsedMs }),
+                        };
+                    }
+                    // The wait consumed these lines, so the cursor moves past them and
+                    // a later `read` does not hand back the same messages - but only
+                    // when `read` had already caught up. With unread lines behind
+                    // fromLine there is no cursor value that means "those unread, these
+                    // read", so the cursor stays put and `read` returns the backlog
+                    // together with what the wait already showed. Repeating a message
+                    // is recoverable; losing one is not.
+                    if (cursorBefore >= fromLine) {
+                        await writeCursor(self, fromLine + received.length);
+                    }
+                    const response = createSuccessResponse('MESSAGE_REPLY_RECEIVED', {
+                        to: target,
+                        count: received.length,
+                        elapsedMs: waitElapsedMs,
+                        messageList: formatMessages(received),
+                        // A cursor cannot express "those unread, these read", so with a
+                        // backlog behind fromLine it stays put and `read` hands these
+                        // back a second time. Acting on them twice is the failure that
+                        // silence here would cause.
+                        repeatNote: cursorBefore < fromLine
+                            ? `\n\n**Unread messages sit behind these**, so the cursor did not move: \`message({ action: 'read' })\` returns the backlog AND repeats the message(s) above once. Treat a repeat as already handled.`
+                            : '',
+                    });
+                    return {
+                        ...response,
+                        _meta: buildMeta(args.action, self, { sent, received, waitTimedOut: false, waitElapsedMs }),
+                    };
+                }
+                // ---- read ----------------------------------------------------------
+                case 'read': {
+                    const all = await readMailbox(self);
+                    const cursor = await readCursor(self);
+                    // A mailbox deleted while a cursor survives would slice past the
+                    // end and return nothing forever; clamp to the current length.
+                    const from = Math.min(cursor, all.length);
+                    const fresh = all.slice(from);
+                    await writeCursor(self, all.length);
+                    const response = createSuccessResponse('MESSAGE_INBOX', {
+                        self,
+                        count: fresh.length,
+                        total: all.length,
+                        mailboxPath: getMailboxPath(self),
+                        messageList: fresh.length ? formatMessages(fresh) : '(nothing new)',
+                    });
+                    return { ...response, _meta: buildMeta('read', self, { received: fresh }) };
+                }
+            }
+        }),
+    };
+}
+//# sourceMappingURL=message-tools.js.map

package/build/tools/message-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-tools.js","sourceRoot":"","sources":["../../src/tools/message-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAEvE,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,cAAc,EACd,WAAW,EACX,UAAU,EACV,WAAW,EACX,WAAW,EACX,cAAc,GAEf,MAAM,wBAAwB,CAAC;AAEhC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7B,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;SAClD,QAAQ,CAAC,yLAAyL,CAAC;IACtM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;SACtB,QAAQ,CAAC,4DAA4D,CAAC;IACzE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;SACxB,QAAQ,CAAC,8BAA8B,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;SAC3B,QAAQ,CAAC,wEAAwE,CAAC;IACrF,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE;SAC/D,QAAQ,CAAC,0KAA0K,CAAC;IACvL,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;SAC3D,QAAQ,CAAC,yEAAyE,CAAC;CACvF,CAAC,CAAC,MAAM,EAAE,CAAC;AAIZ,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAErC,SAAS,SAAS,CAAC,MAA6B,EAAE,IAAY,EAAE,KAA+B;IAC7F,OAAO;QACL,IAAI,EAAE,SAAS;QACf,MAAM;QACN,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,EAAE;KACpC,CAAC;AACJ,CAAC;AAED,oEAAoE;AACpE,SAAS,cAAc,CAAC,QAA0B;IAChD,OAAO,QAAQ;SACZ,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;SACpI,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,OAAO,EAAE,UAAU,CACjB,sOAAsO,EACtO,aAAa,EACb,KAAK,EAAE,IAAiB,EAAE,WAAyB,EAAE,EAAE;YACrD,MAAM,IAAI,GAAG,kBAAkB,CAAC,cAAc,EAAE,EAAE,OAAO,CAAC,CAAC;YAC3D,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,wBAAwB,CAAC;YAEvE,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;gBACpB,uEAAuE;gBACvE,KAAK,UAAU,CAAC,CAAC,CAAC;oBAChB,kEAAkE;oBAClE,6DAA6D;oBAC7D,mEAAmE;oBACnE,iEAAiE;oBACjE,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;oBACrC,MAAM,UAAU,GAAG,MAAM,cAAc,EAAE,CAAC;oBAE1C,MAAM,IAAI,GAA6C,EAAE,CAAC;oBAC1D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;oBAE/B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;wBAC7B,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,IAAI,OAAO,MAAM,CAAC,GAAG,EAAE,CAAC;wBACjD,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;4BAAE,SAAS;wBAC3B,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;wBACb,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;oBACrF,CAAC;oBAED,8DAA8D;oBAC9D,kEAAkE;oBAClE,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;wBAC5B,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;4BAAE,SAAS;wBAC3B,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;wBACb,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;oBACpD,CAAC;oBAED,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;wBACpB,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;oBACpE,CAAC;oBAED,MAAM,QAAQ,GAAG,qBAAqB,CAAC,kBAAkB,EAAE;wBACzD,IAAI;wBACJ,WAAW,EAAE,cAAc,CAAC,IAAI,CAAC;wBACjC,WAAW,EAAE,cAAc,EAAE;wBAC7B,eAAe,EAAE,kBAAkB,CAAC,IAAI,CAAC;wBACzC,WAAW,EAAE,IAAI;6BACd,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;6BACxH,IAAI,CAAC,IAAI,CAAC;wBACb,KAAK,EAAE,IAAI,CAAC,MAAM;qBACnB,CAAC,CAAC;oBACH,OAAO,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;gBACjF,CAAC;gBAED,uEAAuE;gBACvE,KAAK,MAAM,CAAC;gBACZ,KAAK,OAAO,CAAC,CAAC,CAAC;oBACb,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;wBACf,OAAO,mBAAmB,CAAC,sBAAsB,EAAE;4BACjD,OAAO,EAAE,sBAAsB,IAAI,CAAC,MAAM,qBAAqB;yBAChE,CAAC,CAAC;oBACL,CAAC;oBAED,IAAI,MAAc,CAAC;oBACnB,IAAI,OAA2B,CAAC;oBAEhC,IAAI,IAAI,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;wBAC5B,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;4BAClB,OAAO,mBAAmB,CAAC,sBAAsB,EAAE;gCACjD,OAAO,EAAE,uFAAuF;6BACjG,CAAC,CAAC;wBACL,CAAC;wBACD,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;wBACpC,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,OAAQ,CAAC,CAAC,CAAC;wBACxF,IAAI,CAAC,QAAQ,EAAE,CAAC;4BACd,OAAO,mBAAmB,CAAC,wBAAwB,EAAE;gCACnD,MAAM,EAAE,IAAI,CAAC,OAAO;gCACpB,MAAM,EAAE,uBAAuB,IAAI,CAAC,OAAO,6BAA6B;gCACxE,IAAI;6BACL,CAAC,CAAC;wBACL,CAAC;wBACD,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC;wBACvB,OAAO,GAAG,QAAQ,CAAC,EAAE,CAAC;oBACxB,CAAC;yBAAM,CAAC;wBACN,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;4BACb,OAAO,mBAAmB,CAAC,sBAAsB,EAAE;gCACjD,OAAO,EAAE,8FAA8F;6BACxG,CAAC,CAAC;wBACL,CAAC;wBACD,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;oBACnB,CAAC;oBAED,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;wBAC9B,OAAO,mBAAmB,CAAC,wBAAwB,EAAE;4BACnD,MAAM;4BACN,MAAM,EAAE,+EAA+E;4BACvF,IAAI;yBACL,CAAC,CAAC;oBACL,CAAC;oBACD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;wBACpB,OAAO,mBAAmB,CAAC,sBAAsB,EAAE;4BACjD,OAAO,EAAE,IAAI,MAAM,oFAAoF;yBACxG,CAAC,CAAC;oBACL,CAAC;oBAED,gEAAgE;oBAChE,kEAAkE;oBAClE,0DAA0D;oBAC1D,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;oBAC5E,mEAAmE;oBACnE,gEAAgE;oBAChE,MAAM,YAAY,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;oBAEtE,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC;wBAC7B,IAAI,EAAE,IAAI;wBACV,OAAO,EAAE,aAAa,EAAE;wBACxB,EAAE,EAAE,MAAM;wBACV,IAAI,EAAE,IAAI,CAAC,IAAI;wBACf,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;qBAChC,CAAC,CAAC;oBAEH,4DAA4D;oBAC5D,8CAA8C;oBAC9C,MAAM,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE;wBACnC,IAAI,EAAE,IAAI;wBACV,EAAE,EAAE,IAAI,CAAC,EAAE;wBACX,MAAM,EAAE,gBAAgB,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE;wBAC1D,OAAO,EAAE,6BAA6B;qBACvC,CAAC,CAAC;oBAEH,iEAAiE;oBACjE,gEAAgE;oBAChE,kEAAkE;oBAClE,oEAAoE;oBACpE,0CAA0C;oBAC1C,MAAM,eAAe,GAAG,kBAAkB,EAAE;yBACzC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,CAAC,CAAC;oBAEvD,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;wBACzB,MAAM,QAAQ,GAAG,qBAAqB,CAAC,cAAc,EAAE;4BACrD,EAAE,EAAE,MAAM;4BACV,EAAE,EAAE,IAAI,CAAC,EAAE;4BACX,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;4BAC5B,WAAW,EAAE,cAAc,CAAC,MAAM,CAAC;4BACnC,YAAY,EAAE,eAAe;gCAC3B,CAAC,CAAC,EAAE;gCACJ,CAAC,CAAC,sCAAsC,MAAM,2IAA2I;yBAC5L,CAAC,CAAC;wBACH,OAAO,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC;oBACzF,CAAC;oBAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;oBAC7B,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE;wBACpD,SAAS,EAAE,IAAI,CAAC,cAAc;wBAC9B,cAAc;wBACd,WAAW;qBACZ,CAAC,CAAC;oBACH,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;oBAE7C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;wBAC1B,OAAO;4BACL,GAAG,mBAAmB,CAAC,uBAAuB,EAAE;gCAC9C,EAAE,EAAE,MAAM;gCACV,SAAS,EAAE,IAAI,CAAC,cAAc;gCAC9B,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;gCACvB,IAAI;gCACJ,WAAW,EAAE,cAAc,CAAC,IAAI,CAAC;6BAClC,CAAC;4BACF,KAAK,EAAE,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;yBACjF,CAAC;oBACJ,CAAC;oBAED,mEAAmE;oBACnE,iEAAiE;oBACjE,8DAA8D;oBAC9D,oEAAoE;oBACpE,gEAAgE;oBAChE,kEAAkE;oBAClE,qCAAqC;oBACrC,IAAI,YAAY,IAAI,QAAQ,EAAE,CAAC;wBAC7B,MAAM,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;oBACtD,CAAC;oBAED,MAAM,QAAQ,GAAG,qBAAqB,CAAC,wBAAwB,EAAE;wBAC/D,EAAE,EAAE,MAAM;wBACV,KAAK,EAAE,QAAQ,CAAC,MAAM;wBACtB,SAAS,EAAE,aAAa;wBACxB,WAAW,EAAE,cAAc,CAAC,QAAQ,CAAC;wBACrC,gEAAgE;wBAChE,8DAA8D;wBAC9D,+DAA+D;wBAC/D,4BAA4B;wBAC5B,UAAU,EAAE,YAAY,GAAG,QAAQ;4BACjC,CAAC,CAAC,qMAAqM;4BACvM,CAAC,CAAC,EAAE;qBACP,CAAC,CAAC;oBACH,OAAO;wBACL,GAAG,QAAQ;wBACX,KAAK,EAAE,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC;qBAC5F,CAAC;gBACJ,CAAC;gBAED,uEAAuE;gBACvE,KAAK,MAAM,CAAC,CAAC,CAAC;oBACZ,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;oBACpC,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;oBACtC,iEAAiE;oBACjE,+DAA+D;oBAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;oBAC1C,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;oBAC9B,MAAM,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;oBAEpC,MAAM,QAAQ,GAAG,qBAAqB,CAAC,eAAe,EAAE;wBACtD,IAAI;wBACJ,KAAK,EAAE,KAAK,CAAC,MAAM;wBACnB,KAAK,EAAE,GAAG,CAAC,MAAM;wBACjB,WAAW,EAAE,cAAc,CAAC,IAAI,CAAC;wBACjC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,eAAe;qBACpE,CAAC,CAAC;oBACH,OAAO,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;gBAC9E,CAAC;YACH,CAAC;QACH,CAAC,CACF;KACF,CAAC;AACJ,CAAC"}

package/build/tools/message-tools.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tests for the `message` tool and its mailbox transport.
+ *
+ * Every case runs against a temporary DEVHARNESS_DIR, so the mailboxes are the
+ * real files the tool writes in production rather than a mock of them - the
+ * cursor and the blocking wait are both defined by what is on disk.
+ */
+export {};
+//# sourceMappingURL=message-tools.test.d.ts.map

package/build/tools/message-tools.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-tools.test.d.ts","sourceRoot":"","sources":["../../src/tools/message-tools.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/build/tools/message-tools.test.js

@@ -0,0 +1,332 @@
+/**
+ * Tests for the `message` tool and its mailbox transport.
+ *
+ * Every case runs against a temporary DEVHARNESS_DIR, so the mailboxes are the
+ * real files the tool writes in production rather than a mock of them - the
+ * cursor and the blocking wait are both defined by what is on disk.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, readFileSync, existsSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { initializePaths } from '../helpers/paths.js';
+import { setSessionInfo } from './dashboard-tools.js';
+import { createMessageTools } from './message-tools.js';
+import { isValidMailboxId, getMailboxPath, readMailbox, readCursor, sendMessage, waitForMailbox, } from '../session-messages.js';
+let dir;
+let previousDir;
+let previousSessionId;
+function asSession(shortId) {
+    setSessionInfo({
+        sessionId: `${shortId}-full-uuid`,
+        shortId,
+        sessionFile: `/tmp/${shortId}.jsonl`,
+        detectedAt: Date.now(),
+    });
+}
+const { message } = createMessageTools();
+beforeEach(() => {
+    previousDir = process.env.DEVHARNESS_DIR;
+    previousSessionId = process.env.CLAUDE_CODE_SESSION_ID;
+    dir = mkdtempSync(join(tmpdir(), 'devharness-messages-'));
+    process.env.DEVHARNESS_DIR = dir;
+    // The real value on the machine running the suite would otherwise decide
+    // every mailbox id below.
+    process.env.CLAUDE_CODE_SESSION_ID = 'aaaaaaaa-1111-2222-3333-444444444444';
+    initializePaths();
+    asSession('aaaaaaaa');
+});
+afterEach(() => {
+    setSessionInfo(null);
+    if (previousDir === undefined)
+        delete process.env.DEVHARNESS_DIR;
+    else
+        process.env.DEVHARNESS_DIR = previousDir;
+    if (previousSessionId === undefined)
+        delete process.env.CLAUDE_CODE_SESSION_ID;
+    else
+        process.env.CLAUDE_CODE_SESSION_ID = previousSessionId;
+    initializePaths();
+    rmSync(dir, { recursive: true, force: true });
+});
+// ---------------------------------------------------------------------------
+// mailbox ids
+// ---------------------------------------------------------------------------
+describe('isValidMailboxId', () => {
+    it('accepts the short-id and pid forms the tool produces', () => {
+        expect(isValidMailboxId('aaaaaaaa')).toBe(true);
+        expect(isValidMailboxId('pid-12345')).toBe(true);
+    });
+    it('rejects ids that would write outside the messages directory', () => {
+        expect(isValidMailboxId('../escape')).toBe(false);
+        expect(isValidMailboxId('a/b')).toBe(false);
+        expect(isValidMailboxId('..')).toBe(false);
+        expect(isValidMailboxId('')).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// transport
+// ---------------------------------------------------------------------------
+describe('mailbox transport', () => {
+    it('appends one JSON line per message to the recipient', async () => {
+        await sendMessage({ from: 'aaaaaaaa', to: 'bbbbbbbb', text: 'first' });
+        await sendMessage({ from: 'aaaaaaaa', to: 'bbbbbbbb', text: 'second' });
+        const raw = readFileSync(getMailboxPath('bbbbbbbb'), 'utf-8');
+        expect(raw.trimEnd().split('\n')).toHaveLength(2);
+        const messages = await readMailbox('bbbbbbbb');
+        expect(messages.map(m => m.text)).toEqual(['first', 'second']);
+        expect(messages[0].from).toBe('aaaaaaaa');
+        expect(messages[0].to).toBe('bbbbbbbb');
+    });
+    it('skips a torn line instead of losing every message after it', async () => {
+        await sendMessage({ from: 'aaaaaaaa', to: 'bbbbbbbb', text: 'good' });
+        const { appendFileSync } = await import('fs');
+        appendFileSync(getMailboxPath('bbbbbbbb'), '{not json\n');
+        await sendMessage({ from: 'aaaaaaaa', to: 'bbbbbbbb', text: 'after' });
+        const messages = await readMailbox('bbbbbbbb');
+        expect(messages.map(m => m.text)).toEqual(['good', 'after']);
+    });
+    it('reads an absent mailbox as empty', async () => {
+        expect(await readMailbox('nobody')).toEqual([]);
+        expect(existsSync(getMailboxPath('nobody'))).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// waitForMailbox
+// ---------------------------------------------------------------------------
+describe('waitForMailbox', () => {
+    it('returns the messages past the offset once one lands', async () => {
+        const pending = waitForMailbox('aaaaaaaa', 0, { timeoutMs: 5000, pollIntervalMs: 25 });
+        setTimeout(() => { void sendMessage({ from: 'bbbbbbbb', to: 'aaaaaaaa', text: 'here' }); }, 50);
+        const received = await pending;
+        expect(received.map(m => m.text)).toEqual(['here']);
+    });
+    it('returns empty when the timeout elapses with nothing new', async () => {
+        const received = await waitForMailbox('aaaaaaaa', 0, { timeoutMs: 150, pollIntervalMs: 25 });
+        expect(received).toEqual([]);
+    });
+    it('ignores messages at or before the offset', async () => {
+        await sendMessage({ from: 'bbbbbbbb', to: 'aaaaaaaa', text: 'old' });
+        const received = await waitForMailbox('aaaaaaaa', 1, { timeoutMs: 150, pollIntervalMs: 25 });
+        expect(received).toEqual([]);
+    });
+    it('throws an abort-shaped error when the signal aborts mid-wait', async () => {
+        const controller = new AbortController();
+        const pending = waitForMailbox('aaaaaaaa', 0, {
+            timeoutMs: 5000,
+            pollIntervalMs: 25,
+            abortSignal: controller.signal,
+        });
+        setTimeout(() => controller.abort(), 40);
+        await expect(pending).rejects.toMatchObject({ name: 'AbortError' });
+    });
+});
+// ---------------------------------------------------------------------------
+// the tool
+// ---------------------------------------------------------------------------
+describe('message send', () => {
+    it('writes to the target mailbox and reports the id', async () => {
+        const res = await message.handler({ action: 'send', to: 'bbbbbbbb', text: 'hello' });
+        expect(res.isError).toBeFalsy();
+        expect(res._meta.message.sent.to).toBe('bbbbbbbb');
+        expect(res._meta.message.sent.from).toBe('aaaaaaaa');
+        expect(res._meta.message.self).toBe('aaaaaaaa');
+        const delivered = await readMailbox('bbbbbbbb');
+        expect(delivered.map(m => m.text)).toEqual(['hello']);
+    });
+    it('refuses a message addressed to this session', async () => {
+        const res = await message.handler({ action: 'send', to: 'aaaaaaaa', text: 'hello' });
+        expect(res.isError).toBe(true);
+        expect(res._errorId).toBe('MESSAGE_INVALID_ARGS');
+    });
+    it('refuses an id that would escape the messages directory', async () => {
+        const res = await message.handler({ action: 'send', to: '../escape', text: 'hello' });
+        expect(res.isError).toBe(true);
+        expect(res._errorId).toBe('MESSAGE_TARGET_UNKNOWN');
+    });
+    it('requires text', async () => {
+        const res = await message.handler({ action: 'send', to: 'bbbbbbbb' });
+        expect(res.isError).toBe(true);
+        expect(res._errorId).toBe('MESSAGE_INVALID_ARGS');
+    });
+});
+describe('message send with waitForReplyMs', () => {
+    it('returns once anything lands in this session\'s mailbox', async () => {
+        const pending = message.handler({
+            action: 'send', to: 'bbbbbbbb', text: 'ping', waitForReplyMs: 5000, pollIntervalMs: 25,
+        });
+        setTimeout(() => { void sendMessage({ from: 'bbbbbbbb', to: 'aaaaaaaa', text: 'pong' }); }, 50);
+        const res = await pending;
+        expect(res.isError).toBeFalsy();
+        expect(res._meta.message.waitTimedOut).toBe(false);
+        expect(res._meta.message.received.map((m) => m.text)).toEqual(['pong']);
+    });
+    it('fails with MESSAGE_REPLY_TIMEOUT when nothing answers', async () => {
+        const res = await message.handler({
+            action: 'send', to: 'bbbbbbbb', text: 'ping', waitForReplyMs: 150, pollIntervalMs: 25,
+        });
+        expect(res.isError).toBe(true);
+        expect(res._errorId).toBe('MESSAGE_REPLY_TIMEOUT');
+        expect(res._meta.message.waitTimedOut).toBe(true);
+    });
+    it('leaves a message that arrived before the send unconsumed by the wait', async () => {
+        await sendMessage({ from: 'bbbbbbbb', to: 'aaaaaaaa', text: 'earlier' });
+        const res = await message.handler({
+            action: 'send', to: 'bbbbbbbb', text: 'ping', waitForReplyMs: 150, pollIntervalMs: 25,
+        });
+        expect(res._errorId).toBe('MESSAGE_REPLY_TIMEOUT');
+        const inbox = await message.handler({ action: 'read' });
+        expect(inbox._meta.message.received.map((m) => m.text)).toEqual(['earlier']);
+    });
+    it('keeps an unread backlog readable when the wait succeeds', async () => {
+        await sendMessage({ from: 'bbbbbbbb', to: 'aaaaaaaa', text: 'earlier-unread' });
+        const pending = message.handler({
+            action: 'send', to: 'bbbbbbbb', text: 'ping', waitForReplyMs: 5000, pollIntervalMs: 25,
+        });
+        setTimeout(() => { void sendMessage({ from: 'bbbbbbbb', to: 'aaaaaaaa', text: 'pong' }); }, 50);
+        expect((await pending).isError).toBeFalsy();
+        // The backlog is what must survive; the waited message repeating is the
+        // price of a cursor that cannot express a hole.
+        const inbox = await message.handler({ action: 'read' });
+        expect(inbox._meta.message.received.map((m) => m.text)).toEqual(['earlier-unread', 'pong']);
+        // Exactly once - a second read is empty, not another repeat.
+        const again = await message.handler({ action: 'read' });
+        expect(again._meta.message.received).toEqual([]);
+    });
+    it('says in the response that the waited message will come back once', async () => {
+        await sendMessage({ from: 'bbbbbbbb', to: 'aaaaaaaa', text: 'earlier-unread' });
+        const pending = message.handler({
+            action: 'send', to: 'bbbbbbbb', text: 'ping', waitForReplyMs: 5000, pollIntervalMs: 25,
+        });
+        setTimeout(() => { void sendMessage({ from: 'bbbbbbbb', to: 'aaaaaaaa', text: 'pong' }); }, 50);
+        const res = await pending;
+        expect(res.content[0].text).toContain('repeats the message');
+    });
+    it('says nothing about repeats when the mailbox was already caught up', async () => {
+        const pending = message.handler({
+            action: 'send', to: 'bbbbbbbb', text: 'ping', waitForReplyMs: 5000, pollIntervalMs: 25,
+        });
+        setTimeout(() => { void sendMessage({ from: 'bbbbbbbb', to: 'aaaaaaaa', text: 'pong' }); }, 50);
+        const res = await pending;
+        expect(res.content[0].text).not.toContain('repeats the message');
+    });
+    it('advances the cursor past what the wait returned', async () => {
+        const pending = message.handler({
+            action: 'send', to: 'bbbbbbbb', text: 'ping', waitForReplyMs: 5000, pollIntervalMs: 25,
+        });
+        setTimeout(() => { void sendMessage({ from: 'bbbbbbbb', to: 'aaaaaaaa', text: 'pong' }); }, 50);
+        await pending;
+        expect(await readCursor('aaaaaaaa')).toBe(1);
+        const inbox = await message.handler({ action: 'read' });
+        expect(inbox._meta.message.received).toEqual([]);
+    });
+});
+describe('waitForReplyMs shorter than one poll interval', () => {
+    it('still polls, rather than timing out before the first check', async () => {
+        const pending = message.handler({
+            action: 'send', to: 'bbbbbbbb', text: 'ping', waitForReplyMs: 400, pollIntervalMs: 500,
+        });
+        setTimeout(() => { void sendMessage({ from: 'bbbbbbbb', to: 'aaaaaaaa', text: 'pong' }); }, 100);
+        const res = await pending;
+        expect(res.isError).toBeFalsy();
+        expect(res._meta.message.received.map((m) => m.text)).toEqual(['pong']);
+    });
+});
+describe('message read', () => {
+    it('returns each message once', async () => {
+        await sendMessage({ from: 'bbbbbbbb', to: 'aaaaaaaa', text: 'one' });
+        await sendMessage({ from: 'bbbbbbbb', to: 'aaaaaaaa', text: 'two' });
+        const first = await message.handler({ action: 'read' });
+        expect(first._meta.message.received.map((m) => m.text)).toEqual(['one', 'two']);
+        const second = await message.handler({ action: 'read' });
+        expect(second._meta.message.received).toEqual([]);
+        await sendMessage({ from: 'bbbbbbbb', to: 'aaaaaaaa', text: 'three' });
+        const third = await message.handler({ action: 'read' });
+        expect(third._meta.message.received.map((m) => m.text)).toEqual(['three']);
+    });
+    it('returns nothing for a session that has received nothing', async () => {
+        const res = await message.handler({ action: 'read' });
+        expect(res.isError).toBeFalsy();
+        expect(res._meta.message.received).toEqual([]);
+    });
+});
+describe('message reply', () => {
+    it('routes back to the sender of the message being answered', async () => {
+        const incoming = await sendMessage({ from: 'bbbbbbbb', to: 'aaaaaaaa', text: 'question' });
+        await message.handler({ action: 'read' });
+        const res = await message.handler({ action: 'reply', replyTo: incoming.id, text: 'answer' });
+        expect(res.isError).toBeFalsy();
+        const theirs = await readMailbox('bbbbbbbb');
+        expect(theirs.map(m => m.text)).toEqual(['answer']);
+        expect(theirs[0].replyTo).toBe(incoming.id);
+        expect(theirs[0].from).toBe('aaaaaaaa');
+    });
+    it('accepts the abbreviated id the response prints', async () => {
+        const incoming = await sendMessage({ from: 'bbbbbbbb', to: 'aaaaaaaa', text: 'question' });
+        const res = await message.handler({
+            action: 'reply', replyTo: incoming.id.slice(0, 8), text: 'answer',
+        });
+        expect(res.isError).toBeFalsy();
+        expect((await readMailbox('bbbbbbbb'))[0].replyTo).toBe(incoming.id);
+    });
+    it('fails when no message in this mailbox carries that id', async () => {
+        const res = await message.handler({ action: 'reply', replyTo: 'deadbeef', text: 'answer' });
+        expect(res.isError).toBe(true);
+        expect(res._errorId).toBe('MESSAGE_TARGET_UNKNOWN');
+    });
+    it('requires replyTo', async () => {
+        const res = await message.handler({ action: 'reply', text: 'answer' });
+        expect(res.isError).toBe(true);
+        expect(res._errorId).toBe('MESSAGE_INVALID_ARGS');
+    });
+});
+describe('message sessions', () => {
+    it('lists this session and every mailbox on disk when the hub is down', async () => {
+        await sendMessage({ from: 'aaaaaaaa', to: 'bbbbbbbb', text: 'hello' });
+        const res = await message.handler({ action: 'sessions' });
+        expect(res.isError).toBeFalsy();
+        const ids = res._meta.message.sessions.map((s) => s.id).sort();
+        expect(ids).toEqual(['aaaaaaaa', 'bbbbbbbb']);
+        const self = res._meta.message.sessions.find((s) => s.self);
+        expect(self.id).toBe('aaaaaaaa');
+        expect(res._meta.message.sessions.find((s) => s.id === 'bbbbbbbb').live).toBe(false);
+    });
+});
+describe('mailbox identity', () => {
+    it('uses the session id from the environment, with no detection needed', async () => {
+        setSessionInfo(null);
+        const res = await message.handler({ action: 'read' });
+        expect(res._meta.message.self).toBe('aaaaaaaa');
+    });
+    it('keeps the same id when the child pid changes, which a rebuild does', async () => {
+        const before = (await message.handler({ action: 'read' }))._meta.message.self;
+        setSessionInfo(null); // the detector's result is lost with the old child
+        const after = (await message.handler({ action: 'read' }))._meta.message.self;
+        expect(after).toBe(before);
+        expect(after).not.toContain(String(process.pid));
+    });
+    it('prefers the environment over a detector result that disagrees', async () => {
+        asSession('zzzzzzzz');
+        const res = await message.handler({ action: 'read' });
+        expect(res._meta.message.self).toBe('aaaaaaaa');
+    });
+    it('falls back to the detector when the environment carries no session id', async () => {
+        delete process.env.CLAUDE_CODE_SESSION_ID;
+        asSession('zzzzzzzz');
+        const res = await message.handler({ action: 'read' });
+        expect(res._meta.message.self).toBe('zzzzzzzz');
+    });
+    it('falls back to the pid form when neither source has an id', async () => {
+        delete process.env.CLAUDE_CODE_SESSION_ID;
+        setSessionInfo(null);
+        const res = await message.handler({ action: 'read' });
+        expect(res._meta.message.self).toBe(`pid-${process.pid}`);
+    });
+    it('ignores an environment value that could escape the messages directory', async () => {
+        process.env.CLAUDE_CODE_SESSION_ID = '../../escape';
+        setSessionInfo(null);
+        const res = await message.handler({ action: 'read' });
+        expect(res._meta.message.self).toBe(`pid-${process.pid}`);
+    });
+});
+//# sourceMappingURL=message-tools.test.js.map