instar 0.26.4 → 0.26.5

package/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">instar</h1>
 
 <p align="center">
-  <strong>Persistent Claude Code agents with scheduling, sessions, memory, and Telegram.</strong>
+  <strong>Persistent Claude Code agents with scheduling, sessions, memory, and messaging.</strong>
 </p>
 
 <p align="center">
@@ -31,11 +31,11 @@
 npx instar
 ```
 
-One command. Guided setup. Talking to your agent from Telegram within minutes.
+One command. Guided setup. Talking to your agent from your phone within minutes.
 
 ---
 
-Instar turns Claude Code from a powerful CLI tool into a **coherent, autonomous partner**. Persistent identity, memory that survives every restart, job scheduling, two-way Telegram messaging, and the infrastructure to evolve.
+Instar turns Claude Code from a powerful CLI tool into a **coherent, autonomous partner**. Persistent identity, memory that survives every restart, job scheduling, two-way messaging (Telegram, WhatsApp, iMessage), and the infrastructure to evolve.
 
 ## Quick Start
 
@@ -48,10 +48,10 @@ npx instar
 # 2. Start your agent
 instar server start
 
-# 3. Message it on Telegram — it responds, runs jobs, and remembers everything
+# 3. Message it from your phone — it responds, runs jobs, and remembers everything
 ```
 
-The wizard discovers your environment, configures messaging (Telegram and/or WhatsApp), sets up identity files, and gets your agent running. **Within minutes, you're talking to your partner from your phone.**
+The wizard discovers your environment, configures messaging (Telegram, WhatsApp, and/or iMessage), sets up identity files, and gets your agent running. **Within minutes, you're talking to your partner from your phone.**
 
 **Requirements:** Node.js 20+ · [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) · [API key](https://console.anthropic.com/) or Claude subscription
 
@@ -60,7 +60,7 @@ The wizard discovers your environment, configures messaging (Telegram and/or Wha
 ## How It Works
 
 ```
-You (Telegram / WhatsApp / Terminal)
+You (Telegram / WhatsApp / iMessage / Terminal)
          │
     conversation
          │
@@ -103,6 +103,7 @@ Instar solves the six dimensions of agent coherence:
 | **Job Scheduler** | Cron-based tasks with priority levels, model tiering, and quota awareness | [→](https://instar.sh/features/scheduler/) |
 | **Telegram** | Two-way messaging via forum topics. Each topic maps to a Claude session | [→](https://instar.sh/features/telegram/) |
 | **WhatsApp** | Full messaging via local Baileys library. No cloud dependency | [→](https://instar.sh/features/whatsapp/) |
+| **iMessage** | Native macOS messaging via Messages.app database polling + `imsg` CLI. [Setup guide](#imessage-setup-macos) | |
 | **Lifeline** | Persistent supervisor. Detects crashes, auto-recovers, queues messages | [→](https://instar.sh/features/lifeline/) |
 | **Conversational Memory** | Per-topic SQLite with FTS5, rolling summaries, context re-injection | [→](https://instar.sh/features/memory/) |
 | **Evolution System** | Proposals, learnings, gap tracking, commitment follow-through | [→](https://instar.sh/features/evolution/) |
@@ -158,7 +159,7 @@ Different tools solve different problems. Here's where Instar fits:
 | **Persistence** | Multi-layered memory across sessions | Session-bound context | Plugin-based memory | Framework-dependent |
 | **Identity** | Hooks enforce identity at every boundary | Manual CLAUDE.md | Not addressed | Not addressed |
 | **Scheduling** | Native cron with priority & quotas | None | None | External required |
-| **Messaging** | Telegram + WhatsApp (two-way) | None | 22+ channels, voice, device apps | External required |
+| **Messaging** | Telegram + WhatsApp + iMessage (two-way) | None | 22+ channels, voice, device apps | External required |
 | **Safety** | LLM-supervised gates, decision journaling | Permission prompts | Behavioral hooks | Guardrails libraries |
 | **Process model** | One process per session, isolated | Single process | All agents in one Gateway | Single orchestrator |
 | **State storage** | 100% file-based (JSON/JSONL/SQLite) | Session only | Database-backed | Framework-dependent |
@@ -197,6 +198,59 @@ The AI systems we build today set precedents for how AI is treated tomorrow. **T
 
 </details>
 
+## iMessage Setup (macOS)
+
+iMessage support lets your agent send and receive iMessages on macOS. Messages are read directly from the native Messages database and sent via the [`imsg`](https://github.com/steipete/imsg) CLI.
+
+### Prerequisites
+
+1. **macOS** with Messages.app signed into an Apple ID
+2. **Full Disk Access** for your terminal app (System Settings → Privacy & Security → Full Disk Access → add Terminal.app or iTerm)
+3. **imsg CLI** installed:
+   ```bash
+   brew install steipete/tap/imsg
+   ```
+4. **Automation permission** for Messages.app — macOS will prompt on first send
+
+### Configuration
+
+Add to your `.instar/config.json`:
+
+```json
+{
+  "messaging": [
+    {
+      "type": "imessage",
+      "enabled": true,
+      "config": {
+        "authorizedSenders": ["+14081234567"],
+        "cliPath": "/opt/homebrew/bin/imsg"
+      }
+    }
+  ]
+}
+```
+
+`authorizedSenders` is required (fail-closed). Only messages from these phone numbers or email addresses will be processed.
+
+### How it works
+
+- **Receiving**: The server polls `~/Library/Messages/chat.db` every 2 seconds for new messages. Uses the `query_only` SQLite pragma to read the WAL (write-ahead log) where Messages.app writes new data.
+- **Sending**: Claude Code sessions run `imessage-reply.sh` which calls `imsg send` and notifies the server for logging. Sending requires Automation permission for Messages.app, which only works from user-context processes (tmux sessions), not the LaunchAgent server.
+- **Session lifecycle**: Follows the same pattern as Telegram — each sender maps to a Claude Code session that receives conversation context on spawn and respawns with full history when needed.
+
+### Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /imessage/status` | Connection state |
+| `POST /imessage/validate-send/:recipient` | Validate recipient + issue single-use send token (outbound safety layer) |
+| `POST /imessage/reply/:recipient` | Confirm delivery with send token (called by imessage-reply.sh after `imsg send`) |
+| `GET /imessage/chats` | List recent conversations |
+| `GET /imessage/chats/:chatId/history` | Message history for a chat |
+| `GET /imessage/search?q=query` | Search messages |
+| `GET /imessage/log-stats` | Outbound audit log statistics |
+
 ## Origin
 
 Instar was extracted from the [Dawn/Portal project](https://dawn.bot-me.ai) -- a production AI system where a human and an AI have been building together for months. The infrastructure patterns were **earned through real experience**, refined through real failures and growth in a real human-AI relationship.

package/dist/commands/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/commands/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA0PH,UAAU,YAAY;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;2DACuD;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA6pCD,wBAAsB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAwoHtE;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsDzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuD5E"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/commands/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA0PH,UAAU,YAAY;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;2DACuD;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAgzCD,wBAAsB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA6qHtE;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsDzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuD5E"}

package/dist/commands/server.js

@@ -1017,6 +1017,115 @@ function wireWhatsAppRouting(whatsapp, sessionManager) {
         }
     });
 }
+/**
+ * Wire iMessage message routing — mirrors Telegram's session patterns exactly.
+ *
+ * Routes incoming iMessages to Claude Code sessions using the same flow as Telegram:
+ * 1. Existing alive session → injectIMessageMessage (with pendingInjections tracking)
+ * 2. Existing dead session → respawn via spawnInteractiveSession(bootstrapMessage)
+ * 3. No session → auto-spawn via spawnInteractiveSession(bootstrapMessage)
+ *
+ * Key design: the bootstrap message (with inline context) is passed as the
+ * initialMessage to spawnInteractiveSession, which handles wait-for-ready and
+ * injection internally — the same code path that Telegram uses successfully.
+ */
+function wireIMessageRouting(imessage, sessionManager) {
+    const spawningSenders = new Set();
+    // Wire session alive check for stall detection
+    imessage.setIsSessionAlive((sessionName) => sessionManager.isSessionAlive(sessionName));
+    const replyScript = '.claude/scripts/imessage-reply.sh';
+    /**
+     * Build a bootstrap message for spawning an iMessage session.
+     * Follows Telegram's spawnSessionForTopic pattern: context is INLINE in the
+     * bootstrap message, not a file reference. For long messages, writes to a temp
+     * file with a strong read instruction (matching Telegram's BOOTSTRAP_FILE_THRESHOLD).
+     */
+    function buildBootstrapMessage(sender, text, senderName) {
+        // Get conversation history from chat.db (includes both user AND agent messages)
+        const conversationContext = imessage.getConversationContext(sender, 30);
+        const parts = [];
+        if (conversationContext) {
+            parts.push(`CONTINUATION — You are resuming an EXISTING conversation via iMessage.`, `Read the context below before responding.`, ``, conversationContext, ``, `IMPORTANT: Your response MUST acknowledge and continue the conversation above. Do NOT introduce yourself or ask "how can I help" — the user has been talking to you. Pick up where the conversation left off.`, ``);
+        }
+        // Sanitize sender name to prevent injection via chat.db display_name
+        const safeSenderName = senderName ? senderName.replace(/[\[\]`$\\]/g, '') : undefined;
+        // iMessage relay instructions
+        parts.push(`--- iMessage SESSION (${sender}) ---`, `This is a PERSISTENT conversational session via iMessage.`, `MANDATORY: After EVERY response, relay your message back to the user:`, `  cat <<'EOF' | ${replyScript} "${sender}"`, `  Your response text here`, `  EOF`, ``, `CRITICAL: After replying, STAY AT THE PROMPT and wait for follow-up messages.`, `Do NOT exit. More messages will be injected as [imessage:${sender}] prefixed text.`, `Strip the [imessage:...] prefix before interpreting messages.`, `Only relay conversational text — not tool output or internal reasoning.`, `--- END iMessage SESSION ---`, ``, `The user's latest message:`, `[imessage:${sender}${safeSenderName ? ` from ${safeSenderName}` : ''}] ${text}`);
+        let bootstrapMessage = parts.join('\n');
+        // Large bootstrap messages: write to temp file with strong read instruction
+        // (matches Telegram's BOOTSTRAP_FILE_THRESHOLD pattern)
+        const BOOTSTRAP_FILE_THRESHOLD = 500;
+        if (bootstrapMessage.length > BOOTSTRAP_FILE_THRESHOLD) {
+            const tmpDir = '/tmp/instar-imessage';
+            fs.mkdirSync(tmpDir, { recursive: true, mode: 0o700 });
+            // Clean up old temp files (>1 hour) to prevent unbounded accumulation
+            try {
+                const cutoff = Date.now() - 3_600_000;
+                for (const f of fs.readdirSync(tmpDir)) {
+                    const fp = path.join(tmpDir, f);
+                    try {
+                        if (fs.statSync(fp).mtimeMs < cutoff)
+                            fs.unlinkSync(fp);
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+            catch { /* non-critical */ }
+            const senderSlug = sender.replace(/[^a-zA-Z0-9]/g, '').slice(-8);
+            const filepath = path.join(tmpDir, `bootstrap-${senderSlug}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.txt`);
+            fs.writeFileSync(filepath, bootstrapMessage, { mode: 0o600 });
+            console.log(`[imessage→session] Bootstrap too large (${bootstrapMessage.length} chars), wrote to ${filepath}`);
+            bootstrapMessage = `[IMPORTANT: Read ${filepath} — it contains your full session context, conversation history, and the user's latest message. You MUST read this file before responding.]`;
+        }
+        return bootstrapMessage;
+    }
+    imessage.onMessage(async (msg) => {
+        const sender = msg.channel?.identifier;
+        if (!sender)
+            return;
+        const text = msg.content;
+        const senderName = msg.metadata?.senderName ?? undefined;
+        const senderNorm = sender.toLowerCase();
+        // Skip empty messages (reactions, read receipts, lookback artifacts)
+        if (!text || !text.trim())
+            return;
+        // Check for existing session
+        const targetSession = imessage.getSessionForSender(sender);
+        // Guard: skip if spawn already in progress for this sender
+        if (spawningSenders.has(senderNorm)) {
+            console.log(`[imessage→session] Spawn already in progress for ${senderNorm} — skipping`);
+            return;
+        }
+        if (targetSession && sessionManager.isSessionAlive(targetSession)) {
+            // Session alive — inject directly (same as Telegram's injectTelegramMessage path)
+            console.log(`[imessage→session] Injecting into ${targetSession}: "${text.slice(0, 80)}"`);
+            sessionManager.injectIMessageMessage(targetSession, sender, text, senderName);
+            imessage.trackMessageInjection(sender, targetSession, text);
+        }
+        else {
+            // Session dead or missing — spawn with full context (same as Telegram's spawnSessionForTopic)
+            spawningSenders.add(senderNorm);
+            // Use a hash of the full sender to avoid collisions (slice(-6) collides easily)
+            const crypto = await import('node:crypto');
+            const senderHash = crypto.createHash('sha1').update(sender.toLowerCase()).digest('hex').slice(0, 8);
+            const sessionName = `im-${senderHash}`;
+            const bootstrapMessage = buildBootstrapMessage(sender, text, senderName);
+            // Pass bootstrap as initialMessage — spawnInteractiveSession handles
+            // wait-for-ready and injection internally (same code path as Telegram)
+            sessionManager.spawnInteractiveSession(bootstrapMessage, sessionName)
+                .then((newSession) => {
+                imessage.registerSession(sender, newSession);
+                console.log(`[imessage→session] Spawned "${newSession}" for ${imessage.constructor.maskIdentifier?.(sender) || sender}`);
+            })
+                .catch((err) => {
+                console.error(`[imessage→session] Spawn failed:`, err);
+            })
+                .finally(() => {
+                spawningSenders.delete(senderNorm);
+            });
+        }
+    });
+}
 /**
  * Ensure the Agent Attention topic exists — the agent's direct line to the user.
  * Created once on first server start, persisted in state.
@@ -2617,6 +2726,39 @@ export async function startServer(options) {
                 });
             }
         }
+        // ── iMessage adapter initialization ────────────────────────────────
+        let imessageAdapter;
+        const imessageConfig = config.messaging?.find(m => m.type === 'imessage' && m.enabled);
+        if (imessageConfig) {
+            try {
+                const { IMessageAdapter } = await import('../messaging/imessage/index.js');
+                imessageAdapter = new IMessageAdapter(imessageConfig.config, config.stateDir);
+                // Wire session routing (following Telegram/WhatsApp pattern)
+                wireIMessageRouting(imessageAdapter, sessionManager);
+                // Set agent name for mention-based triggering
+                const imAgentName = imessageConfig.config?.agentName || config.projectName;
+                if (imAgentName)
+                    imessageAdapter.setAgentName(imAgentName);
+                await imessageAdapter.start();
+                const triggerInfo = imessageAdapter.getTriggerMode() === 'mention'
+                    ? `trigger: @${imAgentName}`
+                    : 'trigger: all messages';
+                console.log(pc.green(`  iMessage adapter: connected (${triggerInfo})`));
+                console.log(pc.green('  iMessage message routing: wired'));
+            }
+            catch (err) {
+                const reason = err instanceof Error ? err.message : String(err);
+                console.error(pc.red(`  iMessage init failed: ${reason}`));
+                imessageAdapter = undefined;
+                degradationReporter.report({
+                    feature: 'iMessage',
+                    primary: 'iMessage messaging adapter',
+                    fallback: 'Other messaging channels',
+                    reason: `iMessage init failed: ${reason}`,
+                    impact: 'iMessage messaging unavailable.',
+                });
+            }
+        }
         // Initialize SemanticMemory — the knowledge graph that unifies all memory systems.
         // Uses the same better-sqlite3 as TopicMemory; shares the rebuild path.
         let semanticMemory;
@@ -4451,7 +4593,7 @@ export async function startServer(options) {
                 return { content: lines.join('\n'), truncated: false, elapsedMs: Date.now() - start };
             }, { description: 'Feature discovery state and behavioral contract summary' });
         }
-        const server = new AgentServer({ config, sessionManager, state, scheduler, telegram, relationships, feedback, feedbackAnomalyDetector, dispatches, updateChecker, autoUpdater, autoDispatcher, quotaTracker, quotaManager, publisher, viewer, tunnel, evolution, watchdog, topicMemory, triageNurse, projectMapper, coherenceGate: scopeVerifier, contextHierarchy, canonicalState, operationGate, sentinel, adaptiveTrust, memoryMonitor, orphanReaper, coherenceMonitor, commitmentTracker, semanticMemory, activitySentinel, messageRouter, summarySentinel, spawnManager, systemReviewer, capabilityMapper, selfKnowledgeTree, coverageAuditor, topicResumeMap: _topicResumeMap ?? undefined, autonomyManager, trustElevationTracker, autonomousEvolution, coordinator: coordinator.enabled ? coordinator : undefined, localSigningKeyPem, whatsapp: whatsappAdapter, slack: slackAdapter, whatsappBusinessBackend, messageBridge, hookEventReceiver, worktreeMonitor, subagentTracker, instructionsVerifier, handshakeManager: threadlineHandshake, threadlineRouter, threadlineRelayClient, listenerManager: listenerManager ?? undefined, responseReviewGate, telemetryHeartbeat, pasteManager, featureRegistry, discoveryEvaluator, liveConfig });
+        const server = new AgentServer({ config, sessionManager, state, scheduler, telegram, relationships, feedback, feedbackAnomalyDetector, dispatches, updateChecker, autoUpdater, autoDispatcher, quotaTracker, quotaManager, publisher, viewer, tunnel, evolution, watchdog, topicMemory, triageNurse, projectMapper, coherenceGate: scopeVerifier, contextHierarchy, canonicalState, operationGate, sentinel, adaptiveTrust, memoryMonitor, orphanReaper, coherenceMonitor, commitmentTracker, semanticMemory, activitySentinel, messageRouter, summarySentinel, spawnManager, systemReviewer, capabilityMapper, selfKnowledgeTree, coverageAuditor, topicResumeMap: _topicResumeMap ?? undefined, autonomyManager, trustElevationTracker, autonomousEvolution, coordinator: coordinator.enabled ? coordinator : undefined, localSigningKeyPem, whatsapp: whatsappAdapter, slack: slackAdapter, imessage: imessageAdapter, whatsappBusinessBackend, messageBridge, hookEventReceiver, worktreeMonitor, subagentTracker, instructionsVerifier, handshakeManager: threadlineHandshake, threadlineRouter, threadlineRelayClient, listenerManager: listenerManager ?? undefined, responseReviewGate, telemetryHeartbeat, pasteManager, featureRegistry, discoveryEvaluator, liveConfig });
         await server.start();
         // Connect DegradationReporter downstream systems now that everything is initialized.
         // Any degradation events queued during startup will drain to feedback + telegram.