@iflow-mcp/jkheadley-instar 0.26.2

package/dist/messaging/MessageFormatter.js

@@ -0,0 +1,97 @@
+/**
+ * MessageFormatter — formats messages for tmux delivery.
+ *
+ * Produces formatted text blocks that are injected into Claude sessions
+ * via tmux send-keys. Handles inline delivery, pointer delivery (context-limited),
+ * and delimiter sanitization to prevent injection attacks.
+ */
+import { MAX_SUBJECT_LENGTH } from './types.js';
+const DELIMITER = '━'.repeat(56);
+const DELIMITER_PATTERN = /━{10,}/g;
+const HEADER_PATTERN = /\[AGENT MESSAGE\]/g;
+export class MessageFormatter {
+    /**
+     * Format a message for inline delivery (standard case).
+     * Includes full body, reply/ack instructions, and optional thread context.
+     */
+    formatInline(message, thread) {
+        const sender = `${message.from.agent}/${message.from.session}`;
+        const subject = this.truncateSubject(message.subject);
+        const sanitizedBody = this.sanitize(message.body);
+        const headerParts = [
+            `from: ${sender}`,
+            `priority: ${message.priority}`,
+        ];
+        const metaParts = [
+            `type: ${message.type}`,
+            `id: ${message.id}`,
+        ];
+        if (message.threadId) {
+            const threadInfo = thread ? ` (${thread.messageCount} messages)` : '';
+            metaParts.push(`thread: ${message.threadId}${threadInfo}`);
+        }
+        const lines = [
+            DELIMITER,
+            `[AGENT MESSAGE] ${headerParts.join(' | ')}`,
+            metaParts.join(' | '),
+            DELIMITER,
+        ];
+        // Thread context (if provided)
+        if (thread && thread.messageCount > 1) {
+            lines.push(`Thread context (${thread.messageCount - 1} prior messages):`);
+            lines.push(DELIMITER);
+        }
+        // Subject + body
+        if (subject !== sanitizedBody.slice(0, subject.length)) {
+            lines.push(`Subject: ${subject}`);
+        }
+        lines.push(sanitizedBody);
+        // Footer with reply/ack instructions
+        lines.push(DELIMITER);
+        lines.push(`Reply: Use the threadline_send MCP tool with the sender's agentId and threadId to reply.`);
+        lines.push(`Message ID: ${message.id}`);
+        lines.push(DELIMITER);
+        return lines.join('\n');
+    }
+    /**
+     * Format a message as a pointer (context-limited delivery).
+     * Shows subject and commands but not the full body.
+     */
+    formatPointer(message) {
+        const sender = `${message.from.agent}/${message.from.session}`;
+        const subject = this.truncateSubject(message.subject);
+        const lines = [
+            DELIMITER,
+            `[AGENT MESSAGE] from: ${sender} | priority: ${message.priority}`,
+            `type: ${message.type} | id: ${message.id}`,
+            DELIMITER,
+            'Message available (context-limited delivery):',
+            `  Subject: ${subject}`,
+            `  Read full message: /msg read ${message.id}`,
+            `  Quick ack: /msg ack ${message.id}`,
+            DELIMITER,
+        ];
+        return lines.join('\n');
+    }
+    /**
+     * Sanitize message content to prevent delimiter injection.
+     * Strips patterns that could mimic our message format.
+     */
+    sanitize(content) {
+        let sanitized = content;
+        // Replace long runs of ━ with a safe alternative
+        sanitized = sanitized.replace(DELIMITER_PATTERN, '---');
+        // Replace [AGENT MESSAGE] headers with safe alternative
+        sanitized = sanitized.replace(HEADER_PATTERN, '[agent-message]');
+        return sanitized;
+    }
+    /**
+     * Truncate subject to MAX_SUBJECT_LENGTH.
+     */
+    truncateSubject(subject) {
+        if (subject.length <= MAX_SUBJECT_LENGTH)
+            return subject;
+        return subject.slice(0, MAX_SUBJECT_LENGTH - 3) + '...';
+    }
+}
+//# sourceMappingURL=MessageFormatter.js.map

package/dist/messaging/MessageFormatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageFormatter.js","sourceRoot":"","sources":["../../src/messaging/MessageFormatter.ts"],"names":[],"mappings":"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"}

package/dist/messaging/MessageRouter.d.ts

@@ -0,0 +1,157 @@
+/**
+ * MessageRouter — message sending, routing, acknowledgment, and relay.
+ *
+ * The primary entry point for the messaging subsystem. Handles:
+ * - Creating and sending messages with proper envelope wrapping
+ * - Routing to local, cross-agent (same machine), or cross-machine targets
+ * - Default TTL assignment per message type
+ * - Thread auto-creation for query/request types
+ * - Echo prevention (cannot send to self)
+ * - Relay chain loop detection
+ * - Deduplication on relay receipt
+ * - Delivery state monotonic transitions
+ * - Drop-directory fallback for offline agents
+ * - Cross-machine relay with Ed25519 signatures and Machine-HMAC auth
+ * - Outbound queue for offline cross-machine fallback
+ *
+ * Routing decision tree (from INTER-AGENT-MESSAGING-SPEC v3.1):
+ *   target machine == local?
+ *     → Yes: target agent == local agent?
+ *       → Yes: deliver locally (no relay needed)
+ *       → No: relay via POST /api/messages/relay-agent (Bearer token)
+ *              If agent down → write to drop directory with HMAC
+ *     → No: target machine paired and online?
+ *       → Yes: relay via POST /api/messages/relay-machine (Machine-HMAC + Ed25519)
+ *       → No: queue to outbound directory for git-sync fallback
+ */
+import type { IMessageRouter, AgentMessage, MessageEnvelope, MessageFilter, MessageThread, ThreadStatus, MessageType, MessagePriority, SendMessageOptions, SendResult, MessagingStats } from './types.js';
+import type { MessageStore } from './MessageStore.js';
+import type { MessageDelivery } from './MessageDelivery.js';
+import type { MachineIdentityManager } from '../core/MachineIdentity.js';
+import type { NonceStore } from '../core/NonceStore.js';
+import type { SecurityLog } from '../core/SecurityLog.js';
+export interface MessageRouterConfig {
+    localAgent: string;
+    localMachine: string;
+    serverUrl: string;
+}
+/** Optional cross-machine crypto dependencies. Only needed when multi-machine is enabled. */
+export interface CrossMachineDeps {
+    identityManager: MachineIdentityManager;
+    signingKeyPem: string;
+    nonceStore: NonceStore;
+    securityLog: SecurityLog;
+}
+export declare class MessageRouter implements IMessageRouter {
+    private readonly store;
+    private readonly delivery;
+    private readonly config;
+    private readonly crossMachine;
+    /** Monotonic sequence counter for Machine-HMAC outgoing requests */
+    private machineSequence;
+    /** Optional summary sentinel for intelligent routing */
+    private summarySentinel;
+    constructor(store: MessageStore, delivery: MessageDelivery, config: MessageRouterConfig, crossMachine?: CrossMachineDeps);
+    /** Attach a summary sentinel for intelligent routing (session: "best") */
+    setSummarySentinel(sentinel: import('./SessionSummarySentinel.js').SessionSummarySentinel): void;
+    send(from: AgentMessage['from'], to: AgentMessage['to'], type: MessageType, priority: MessagePriority, subject: string, body: string, options?: SendMessageOptions): Promise<SendResult>;
+    acknowledge(messageId: string, sessionId: string): Promise<void>;
+    relay(envelope: MessageEnvelope, source: 'agent' | 'machine'): Promise<boolean>;
+    getMessage(messageId: string): Promise<MessageEnvelope | null>;
+    getInbox(agentName: string, filter?: MessageFilter): Promise<MessageEnvelope[]>;
+    getOutbox(agentName: string, filter?: MessageFilter): Promise<MessageEnvelope[]>;
+    getDeadLetters(filter?: MessageFilter): Promise<MessageEnvelope[]>;
+    getThread(threadId: string): Promise<{
+        thread: MessageThread;
+        messages: MessageEnvelope[];
+    } | null>;
+    listThreads(status?: ThreadStatus): Promise<MessageThread[]>;
+    resolveThread(threadId: string): Promise<void>;
+    private updateThread;
+    getStats(): Promise<MessagingStats>;
+    /**
+     * Route a message to a different agent on the same machine.
+     *
+     * Resolution order (per spec §Cross-Agent Resolution):
+     * 1. Look up target agent in ~/.instar/registry.json
+     * 2. Verify agent is running (PID alive + server responds to health)
+     * 3. Forward via POST http://localhost:{port}/messages/relay-agent
+     *    with Bearer token from ~/.instar/agent-tokens/{agentName}.token
+     * 4. If agent server is down → write to drop directory with HMAC
+     */
+    private routeCrossAgentLocal;
+    /**
+     * Relay an envelope to another agent's server via HTTP.
+     * Returns true if the target accepted the message.
+     */
+    private relayToAgent;
+    /**
+     * Write a message to the drop directory for offline pickup.
+     * The drop is HMAC-signed with the sender's token for tamper protection.
+     *
+     * Drop path: ~/.instar/messages/drop/{targetAgentName}/{messageId}.json
+     */
+    private dropMessage;
+    /**
+     * Route a message to a different machine.
+     *
+     * Flow (per spec §Cross-Machine):
+     * 1. Verify cross-machine deps are available
+     * 2. Verify target machine is paired and active
+     * 3. Resolve target machine URL
+     * 4. Add self to relay chain (before signing — relayChain is part of SignedPayload)
+     * 5. Sign envelope with Ed25519
+     * 6. Forward via POST relay-machine with Machine-HMAC headers
+     * 7. If relay fails → queue to outbound directory for git-sync fallback
+     */
+    private routeCrossMachine;
+    /**
+     * Sign a message envelope with this machine's Ed25519 key.
+     * Sets transport.signature and transport.signedBy.
+     *
+     * Signature covers the canonical JSON of the SignedPayload:
+     * { message, relayChain, originServer, nonce, timestamp }
+     */
+    private signEnvelope;
+    /**
+     * Public signature verification for git-sync inbound messages.
+     * Skips clock skew check (per spec: git-sync has no timestamp check).
+     */
+    verifyInboundSignature(envelope: MessageEnvelope): {
+        valid: true;
+    } | {
+        valid: false;
+        reason: string;
+    };
+    /**
+     * Verify the Ed25519 signature on an incoming cross-machine envelope.
+     * Checks: signature present, signer is active, clock skew within tolerance, signature valid.
+     */
+    private verifyEnvelopeSignature;
+    /**
+     * Relay an envelope to a remote machine via HTTP.
+     * Uses Machine-HMAC (5-header scheme) for transport auth.
+     * The envelope itself carries Ed25519 signature for message integrity.
+     */
+    private relayToMachine;
+    /**
+     * Queue a message in the outbound directory for offline cross-machine delivery.
+     * These are picked up by git-sync or on next machine connection.
+     *
+     * Outbound path: ~/.instar/messages/outbound/{targetMachineId}/{messageId}.json
+     */
+    private queueOutbound;
+    private isValidTransition;
+}
+/**
+ * Serialize an object to canonical JSON per RFC 8785.
+ *
+ * Rules:
+ * - Object keys sorted lexicographically (Unicode code point order)
+ * - No insignificant whitespace
+ * - Applied recursively to all nested objects
+ * - Arrays preserve element order
+ * - Primitive values use standard JSON serialization
+ */
+export declare function canonicalJSON(value: unknown): string;
+//# sourceMappingURL=MessageRouter.d.ts.map

package/dist/messaging/MessageRouter.d.ts.map

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