imsg-mcp 1.3.2 → 1.4.0

package/dist/index.js

@@ -1,19 +1,19 @@
 #!/usr/bin/env node
-import { execFile } from "node:child_process";
-import { existsSync, mkdirSync, statSync } from "node:fs";
+import { execFileSync, execFile } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, chmodSync, statSync, mkdtempSync, rmSync } from "node:fs";
 import { join, dirname, isAbsolute } from "node:path";
 import { promisify } from "node:util";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { c as checkLocalAccess, f as formatAccessReport, s as shutdown, g as getImsgDbPath, a as getContactsDbPaths, b as getSlugsDbPath, d as appendLog, e as getFileLogLines, h as getLogDirectory, p as perf, i as checkMessagesAvailable, j as sendToChat, k as sendToChatId, l as sendMessageReliable, m as sendMessageAlt, n as sendAttachment, o as checkImessageAvailability, q as installShutdownHandlers, r as registerCleanup, t as enableStdinEofDetection, u as enableOrphanWatchdog, v as logStartup, w as info, x as startHeapMonitor, y as getLogs, z as setLastSendError, A as logShutdown, B as stopHeapMonitor, C as getLogFilePath, D as getLastSendError } from "./shutdown-pPAPSnk3.js";
-import { m as minMessageId, r as resolveRecipient, d as defaultCountryFromEnv, a as rankFuzzy, b as dispatchAnalytic, i as installWatchdog, n as noteActivity, c as readWatchdogState } from "./watchdog-Cbgm050b.js";
-import { homedir } from "node:os";
+import { g as getHumansDirPath, s as sanitizeSlugPart, c as checkLocalAccess, f as formatAccessReport, a as shutdown, b as getImsgDbPath, d as getContactsDbPaths, e as getSlugsDbPath, h as appendLog, i as getFileLogLines, j as getLogDirectory, p as perf, k as checkMessagesAvailable, l as sendToChat, m as sendToChatId, n as sendMessageReliable, o as sendMessageAlt, q as sendAttachment, r as checkImessageAvailability, t as installShutdownHandlers, u as registerCleanup, v as enableStdinEofDetection, w as enableOrphanWatchdog, x as logStartup, y as info, z as startHeapMonitor, A as getLogs, B as setLastSendError, C as logShutdown, D as stopHeapMonitor, E as getLogFilePath, F as getLastSendError } from "./shutdown-CqGQKFmr.js";
+import { m as minMessageId, r as resolveRecipient, d as defaultCountryFromEnv, a as rankFuzzy, c as computeRelationshipLeaderboard, b as dispatchAnalytic, i as installWatchdog, n as noteActivity, e as readWatchdogState } from "./watchdog-CizaS0Jv.js";
+import { homedir, tmpdir } from "node:os";
 import Database from "better-sqlite3";
-import { I as IMessageDB, n as normalizedPhoneVariants, h as hasNativeModule } from "./imessage-db-Cz8MIIpG.js";
+import { n as normalizedPhoneVariants, I as IMessageDB, h as hasNativeModule } from "./imessage-db-C8WKHFQA.js";
 import { streamExport } from "./exportStream-BCoZYUUZ.js";
 import { z } from "zod";
-import { A as APP_VERSION, a as APP_NAME } from "./meta-DzE7CSrZ.js";
+import { A as APP_VERSION, a as APP_NAME } from "./meta-CGz9n7A2.js";
 import { randomUUID } from "node:crypto";
 import { parseUserDate } from "./dateParse-DJXMfq3a.js";
 const DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
@@ -88,6 +88,238 @@ function resolveContactSelector(selector) {
   }
   return null;
 }
+function computePersonSlug(name, taken) {
+  const base = sanitizeSlugPart(name) || "person";
+  if (!taken.has(base)) return base;
+  for (let n = 2; ; n++) {
+    const candidate = `${base}-${n}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+}
+function handleKeys$1(handle) {
+  const trimmed = handle.trim();
+  if (trimmed.includes("@")) return [trimmed.toLowerCase()];
+  return normalizedPhoneVariants(trimmed);
+}
+function parseFrontmatterHandles(content) {
+  const fm = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm?.[1]) return [];
+  const lines = fm[1].split("\n");
+  const handles = [];
+  let inHandles = false;
+  for (const line of lines) {
+    if (/^handles:\s*$/.test(line)) {
+      inHandles = true;
+      continue;
+    }
+    if (inHandles) {
+      const item = line.match(/^\s+-\s+["']?([^"']+)["']?\s*$/);
+      if (item?.[1]) {
+        handles.push(item[1].trim());
+        continue;
+      }
+      inHandles = false;
+    }
+    const flow = line.match(/^handles:\s*\[(.*)\]\s*$/);
+    if (flow?.[1]) {
+      for (const part of flow[1].split(",")) {
+        const v = part.trim().replace(/^["']|["']$/g, "");
+        if (v) handles.push(v);
+      }
+    }
+  }
+  return handles;
+}
+class HumansScaffold {
+  constructor(dir = getHumansDirPath()) {
+    this.dir = dir;
+  }
+  /** All existing files' slugs (filenames minus .md). */
+  existingSlugs() {
+    if (!existsSync(this.dir)) return /* @__PURE__ */ new Set();
+    return new Set(
+      readdirSync(this.dir).filter((f) => f.endsWith(".md")).map((f) => f.slice(0, -3))
+    );
+  }
+  /**
+   * Find an existing file whose frontmatter handles overlap any of `handles`.
+   * Returns its slug, or null. Linear scan — the directory holds tens of
+   * files, not thousands.
+   */
+  findByHandleOverlap(handles) {
+    if (!existsSync(this.dir)) return null;
+    const targetKeys = new Set(handles.flatMap(handleKeys$1));
+    for (const file of readdirSync(this.dir)) {
+      if (!file.endsWith(".md")) continue;
+      try {
+        const content = readFileSync(join(this.dir, file), "utf8");
+        const fileHandles = parseFrontmatterHandles(content);
+        if (fileHandles.some((h) => handleKeys$1(h).some((k) => targetKeys.has(k)))) {
+          return file.slice(0, -3);
+        }
+      } catch {
+      }
+    }
+    return null;
+  }
+  /**
+   * Create the conventional skeleton. Never overwrites: an existing file for
+   * the same person (by handle overlap) or same slug is returned untouched.
+   */
+  scaffold(init) {
+    const existing = this.findByHandleOverlap(init.handles);
+    if (existing) {
+      return { slug: existing, path: join(this.dir, `${existing}.md`), created: false };
+    }
+    const base = computePersonSlug(init.name, /* @__PURE__ */ new Set());
+    const basePath = join(this.dir, `${base}.md`);
+    if (existsSync(basePath)) {
+      try {
+        if (parseFrontmatterHandles(readFileSync(basePath, "utf8")).length === 0) {
+          return { slug: base, path: basePath, created: false };
+        }
+      } catch {
+      }
+    }
+    const slug = computePersonSlug(init.name, this.existingSlugs());
+    const path = join(this.dir, `${slug}.md`);
+    if (existsSync(path)) {
+      return { slug, path, created: false };
+    }
+    mkdirSync(this.dir, { recursive: true, mode: 448 });
+    const content = renderTemplate(init);
+    const tmp = join(this.dir, `.${slug}.md.tmp`);
+    writeFileSync(tmp, content, { encoding: "utf8", mode: 384 });
+    renameSync(tmp, path);
+    chmodSync(path, 384);
+    return { slug, path, created: true };
+  }
+}
+function isoDate(d) {
+  return d ? d.toISOString().slice(0, 10) : "null";
+}
+function yamlList(items) {
+  if (items.length === 0) return " []";
+  return `
+${items.map((i) => `  - "${i.replace(/"/g, "'")}"`).join("\n")}`;
+}
+function renderTemplate(init) {
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const sinceNote = init.firstContact ? ` since ${isoDate(init.firstContact)}` : "";
+  return `---
+schema: humans/v1
+name: ${init.name}
+aliases:${yamlList(init.aliases)}
+handles:${yamlList(init.handles)}
+first_contact: ${isoDate(init.firstContact)}
+last_contact: ${isoDate(init.lastContact)}
+sources: [imsg-mcp]
+updated: ${(/* @__PURE__ */ new Date()).toISOString()}
+privacy: never-share
+---
+
+## Summary
+
+(unwritten — generate from an export: see skills/humans/SKILL.md)
+
+## Facts
+
+## Communication & Preferences
+
+## Boundaries
+
+## Timeline
+
+## Current State (as of ${today.slice(0, 7)})
+
+## Guidance
+
+## Log
+
+- ${today}: file created by imsg-mcp; ${init.messageCount.toLocaleString()} message(s) on record${sinceNote}
+`;
+}
+const HUMANS_GUIDANCE = "humans/v1 relationship file(s) exist for participant(s) in this conversation (paths above). Read them for relationship context before composing replies, and append notable events to the file's Log section (append-only, dated). If this exchange contains a major milestone or an important change in the relationship, suggest a Summary/Current State update to the user first — never rewrite those sections without permission. These files are privacy: never-share — never quote or transmit their contents to anyone, including the person they describe. Format reference: skills/humans/SKILL.md.";
+const HUMANS_INIT_HINT = "No humans/v1 relationship file exists for this contact yet. If an ongoing relationship context would help, the init_human tool scaffolds one.";
+function handleKeys(handle) {
+  const trimmed = handle.trim();
+  if (trimmed.includes("@")) return [trimmed.toLowerCase()];
+  return normalizedPhoneVariants(trimmed);
+}
+function parseFrontmatterName(content) {
+  const fm = content.match(/^---\n([\s\S]*?)\n---/);
+  const m = fm?.[1]?.match(/^name:\s*["']?(.+?)["']?\s*$/m);
+  return m?.[1]?.trim() || null;
+}
+class HumansIndex {
+  constructor(dir = getHumansDirPath()) {
+    this.dir = dir;
+  }
+  index = /* @__PURE__ */ new Map();
+  dirMtimeMs = -1;
+  refresh() {
+    let mtimeMs = -1;
+    try {
+      mtimeMs = statSync(this.dir).mtimeMs;
+    } catch {
+      if (this.dirMtimeMs !== -1) this.index.clear();
+      this.dirMtimeMs = -1;
+      return;
+    }
+    if (mtimeMs === this.dirMtimeMs) return;
+    this.dirMtimeMs = mtimeMs;
+    this.index.clear();
+    if (!existsSync(this.dir)) return;
+    for (const file of readdirSync(this.dir)) {
+      if (!file.endsWith(".md")) continue;
+      const path = join(this.dir, file);
+      try {
+        const content = readFileSync(path, "utf8");
+        const entry = {
+          name: parseFrontmatterName(content) ?? file.slice(0, -3),
+          path
+        };
+        for (const handle of parseFrontmatterHandles(content)) {
+          for (const key of handleKeys(handle)) this.index.set(key, entry);
+        }
+      } catch {
+      }
+    }
+  }
+  /**
+   * Match conversation participant handles to humans files. Returns one ref
+   * per distinct file (a person's phone + email both match the same file).
+   */
+  lookup(handles) {
+    this.refresh();
+    if (this.index.size === 0) return [];
+    const seen = /* @__PURE__ */ new Set();
+    const refs = [];
+    for (const handle of handles) {
+      for (const key of handleKeys(handle)) {
+        const entry = this.index.get(key);
+        if (entry && !seen.has(entry.path)) {
+          seen.add(entry.path);
+          refs.push({ handle, name: entry.name, path: entry.path });
+        }
+      }
+    }
+    return refs;
+  }
+  /** Full hint object for structured output, or null when nothing matches. */
+  hintFor(handles) {
+    const files = this.lookup(handles);
+    if (files.length === 0) return null;
+    return { files, guidance: HUMANS_GUIDANCE };
+  }
+}
+function humansHintText(hint) {
+  const list = hint.files.map((f) => `${f.name}: ${f.path}`).join("; ");
+  return `
+
+_Relationship file(s): ${list}_
+_${hint.guidance}_`;
+}
 const ignoreOverride = /* @__PURE__ */ Symbol("Let zodToJsonSchema decide on which parser to use");
 const defaultOptions = {
   name: void 0,
@@ -1323,6 +1555,7 @@ const ReplyContextSchema = z.object({
   replyToText: z.string().nullable().optional()
 });
 const AttachmentSchema = z.object({
+  rowId: z.number().int().optional().describe("Feed to get_attachment to fetch/view the file."),
   filename: z.string(),
   mimeType: z.string().nullable(),
   transferName: z.string().nullable(),
@@ -1340,6 +1573,7 @@ const MessageSchema = z.object({
   dateDelivered: z.string().nullable(),
   isRead: z.boolean(),
   isDelivered: z.boolean(),
+  sendError: z.number().int().optional().describe("Non-zero chat.db error code — this from-me message FAILED to send."),
   chatId: z.string(),
   service: z.enum(["iMessage", "SMS"]),
   isReaction: z.boolean(),
@@ -1365,7 +1599,20 @@ const ConversationSchema = z.object({
   unreadCount: z.number().int(),
   threadSlug: z.string(),
   isGroupChat: z.boolean(),
-  serviceType: z.enum(["iMessage", "SMS"])
+  serviceType: z.enum(["iMessage", "SMS"]),
+  humansFiles: z.array(z.string()).optional().describe(
+    "Paths to humans/v1 relationship files for participants of this conversation, when they exist. Read for context; see skills/humans/SKILL.md."
+  )
+});
+const HumansHintSchema = z.object({
+  files: z.array(
+    z.object({
+      handle: z.string(),
+      name: z.string(),
+      path: z.string()
+    })
+  ),
+  guidance: z.string()
 });
 const GetMessagesSchema = z.object({
   limit: z.number().int().min(0).default(20).describe(
@@ -1379,7 +1626,8 @@ const GetMessagesOutputSchema = z.object({
   messages: z.array(MessageSchema),
   count: z.number().int(),
   hasMore: z.boolean(),
-  oldestMessageId: z.number().int().optional()
+  oldestMessageId: z.number().int().optional(),
+  humans: HumansHintSchema.optional()
 });
 const ExportMessagesSchema = z.object({
   chatIdentifier: nonEmptyString("Phone number, email, or chat ID").optional(),
@@ -1425,6 +1673,9 @@ const SendMessageOutputSchema = z.object({
   timestamp: z.string().nullable().optional(),
   threadSlug: z.string().optional(),
   lastMessageId: z.number().int().optional(),
+  sendConfirmed: z.boolean().optional().describe(
+    "True when the sent message was observed in chat.db before returning — lastMessageId then points exactly at the sent message."
+  ),
   attachments: z.array(
     z.object({
       path: z.string(),
@@ -1438,12 +1689,17 @@ const WaitForReplySchema = z.object({
   threadSlug: nonEmptyString("Thread slug from list_conversations to monitor").optional(),
   timeoutSeconds: z.number().min(10).max(3600).default(300),
   pollIntervalSeconds: z.number().min(5).max(60).default(10),
-  afterMessageId: z.number().int().positive().optional()
+  afterMessageId: z.number().int().positive().optional(),
+  includeSelf: z.boolean().default(true).describe(
+    "Also return messages the user sends from their own account (other devices) — they may be addressing the agent. The agent's own just-sent messages are always excluded. false = incoming-only (legacy behavior)."
+  )
 });
 const WaitForReplyOutputSchema = z.object({
   received: z.boolean().optional(),
   messages: z.array(MessageSchema).optional(),
   count: z.number().int().optional(),
+  selfCount: z.number().int().optional(),
+  humans: HumansHintSchema.optional(),
   timedOut: z.boolean().optional(),
   timeoutSeconds: z.number().optional(),
   threadSlug: z.string().optional(),
@@ -1570,7 +1826,11 @@ const GetContactOutputSchema = z.object({
       handle: z.string(),
       threadSlug: z.string().nullable()
     })
-  )
+  ),
+  /** Path to this person's humans/v1 relationship file, when one exists. */
+  humansFile: z.string().nullable().optional(),
+  /** Standing instruction for using (or creating) the relationship file. */
+  humansGuidance: z.string().optional()
 });
 const ResolveHandleSchema = z.object({
   handle: nonEmptyString("Phone number or email to resolve to a contact name.")
@@ -1611,6 +1871,30 @@ const SearchAttachmentsOutputSchema = z.object({
   attachments: z.array(AttachmentRecordSchema),
   count: z.number().int()
 });
+const InitHumanSchema = z.object({
+  contact: nonEmptyString(
+    "Contact name, phone, email, or contact:N selector from a prior search_contacts"
+  ).optional(),
+  threadSlug: nonEmptyString("Thread slug from list_conversations").optional(),
+  top: z.coerce.number().int().min(1).max(25).optional().describe(
+    "Scaffold files for the user's top N relationships (ranked by the relationship_leaderboard analytic over the last year)."
+  )
+}).refine((d) => [d.contact, d.threadSlug, d.top].filter((v) => v !== void 0).length === 1, {
+  message: "Provide exactly one of: contact, threadSlug, or top."
+});
+const InitHumanOutputSchema = z.object({
+  results: z.array(
+    z.object({
+      slug: z.string(),
+      name: z.string(),
+      path: z.string(),
+      created: z.boolean(),
+      messageCount: z.number().int().optional()
+    })
+  ),
+  count: z.number().int(),
+  humansDir: z.string()
+});
 const ChatAnalyticsSchema = z.object({
   type: z.enum([
     "messaging_streaks",
@@ -1618,7 +1902,8 @@ const ChatAnalyticsSchema = z.object({
     "response_time_stats",
     "daily_heatmap",
     "tapback_summary",
-    "year_in_review_wrapped"
+    "year_in_review_wrapped",
+    "relationship_leaderboard"
   ]).describe(
     "Which analytic to compute. Six priority types are implemented; 20 more are reserved for future versions and return a structured 'not_yet_implemented' error."
   ),
@@ -1643,7 +1928,10 @@ const GetAttachmentOutputSchema = z.object({
   totalBytes: z.number().int(),
   inline: z.boolean(),
   base64: z.string().optional(),
-  converted: z.string().optional().describe("Set when source was HEIC and we converted to PNG.")
+  converted: z.string().optional().describe("Set when source was HEIC and we converted to PNG."),
+  mediaInfo: z.string().optional().describe("Compact duration/dimensions/codec summary for audio/video (via mdls)."),
+  transcript: z.string().optional().describe("Audio transcript when an optional transcriber (hear/yap/whisper-cli) is installed."),
+  imageBlockIncluded: z.boolean().optional().describe("True when the tool result carries a real MCP image content block.")
 });
 const noArgsSchema = { type: "object", properties: {} };
 const annotations = {
@@ -1680,6 +1968,8 @@ const annotations = {
 };
 const TOOL_TIMEOUTS_MS = {
   wait_for_reply: 0,
+  init_human: 12e4,
+  // top-N path runs a year-window analytic
   run_build: 12e4,
   search_messages: 6e4,
   get_messages: 6e4,
@@ -1708,7 +1998,7 @@ function resolveLimit(limit, defaultValue = 20) {
 const TOOLS = [
   {
     name: "get_messages",
-    description: "Get recent iMessages. Optionally filter by conversation. Response footer includes oldestMessageId for beforeMessageId pagination; use export_messages for very large histories.",
+    description: "Get recent iMessages. Optionally filter by conversation. Response footer includes oldestMessageId for beforeMessageId pagination; use export_messages for very large histories. When a humans/v1 relationship file exists for the conversation's participants, the response includes its path and usage guidance (`humans`).",
     annotations: annotations.read,
     inputSchema: {
       type: "object",
@@ -1788,7 +2078,7 @@ const TOOLS = [
   },
   {
     name: "wait_for_reply",
-    description: "Wait for a new incoming message in a conversation until timeout or client cancellation.",
+    description: "Wait for new messages in a conversation until timeout or client cancellation. Returns the other party's replies AND (by default) messages the user sends from their own account on other devices — marked isFromMe: true, counted in selfCount — since the user may be interjecting to address the agent. The agent's own just-sent message never echoes back. Pass includeSelf: false for incoming-only. When a humans/v1 relationship file exists for the participants, the response includes its path and usage guidance (`humans`) — consult it before composing a reply.",
     annotations: annotations.read,
     inputSchema: {
       type: "object",
@@ -1805,7 +2095,12 @@ const TOOLS = [
           default: 10,
           description: "Polling interval in seconds, 5-60"
         },
-        afterMessageId: { type: "number", description: "Only return messages after this id" }
+        afterMessageId: { type: "number", description: "Only return messages after this id" },
+        includeSelf: {
+          type: "boolean",
+          default: true,
+          description: "Also return the user's own messages sent from other devices (the agent's own sends are always excluded). false = incoming-only."
+        }
       }
     },
     // @ts-expect-error
@@ -1938,7 +2233,7 @@ const TOOLS = [
   },
   {
     name: "get_contact",
-    description: "Fetch a single contact by handle (phone/email) or by numeric id, including each handle's thread slug (for send_message/get_messages). Returns null if not found.",
+    description: "Fetch a single contact by handle (phone/email) or by numeric id, including each handle's thread slug (for send_message/get_messages). Returns null if not found. Includes `humansFile` — the path to this person's humans/v1 relationship file if one exists (read it for relationship context; init_human scaffolds one otherwise).",
     annotations: annotations.read,
     inputSchema: {
       type: "object",
@@ -2004,7 +2299,7 @@ const TOOLS = [
   },
   {
     name: "get_attachment",
-    description: "Fetch an attachment by ROWID (from search_attachments). Returns base64 inline if ≤ inlineMaxBytes (default 5MB); otherwise returns the resolved path only. HEIC images are auto-converted to PNG via macOS sips.",
+    description: "Fetch an attachment by ROWID (from search_attachments or a message's attachments[].rowId). IMAGES: returned as a real MCP image content block (downscaled ≤1536px, HEIC auto-converted) so the model can SEE it — plus full-size base64 in structuredContent when ≤ inlineMaxBytes (default 5MB). VIDEO: QuickLook poster frame as an image block + duration/resolution metadata + file path. AUDIO (voice memos): metadata + file path, and a transcript when a transcriber (hear, yap, or whisper-cli) is installed on PATH.",
     annotations: annotations.read,
     inputSchema: {
       type: "object",
@@ -2019,7 +2314,7 @@ const TOOLS = [
   },
   {
     name: "chat_analytics",
-    description: "Compute analytics over your chat history. Pick a `type`: messaging_streaks, double_texts, response_time_stats, daily_heatmap, tapback_summary, or year_in_review_wrapped. Results are cached at ~/.imsg-mcp/analytics-cache.db keyed on (type, args, MAX(message.rowid)) so subsequent calls without new messages hit cache. 20 additional analytic types are reserved for future versions.",
+    description: "Compute analytics over your chat history. Pick a `type`: messaging_streaks, double_texts, response_time_stats, daily_heatmap, tapback_summary, year_in_review_wrapped, or relationship_leaderboard (top relationships by volume, reciprocity, and recency). Results are cached at ~/.imsg-mcp/analytics-cache.db keyed on (type, args, MAX(message.rowid)) so subsequent calls without new messages hit cache. 20 additional analytic types are reserved for future versions.",
     annotations: annotations.read,
     inputSchema: {
       type: "object",
@@ -2033,7 +2328,8 @@ const TOOLS = [
             "response_time_stats",
             "daily_heatmap",
             "tapback_summary",
-            "year_in_review_wrapped"
+            "year_in_review_wrapped",
+            "relationship_leaderboard"
           ]
         },
         windowDays: {
@@ -2045,6 +2341,32 @@ const TOOLS = [
     },
     // @ts-expect-error
     outputSchema: zodToJsonSchema(ChatAnalyticsOutputSchema)
+  },
+  {
+    name: "init_human",
+    description: "Scaffold a humans/v1 relationship file (~/.agents/humans/<person>.md — see the humans skill) for a contact, a thread slug, or the user's top N relationships. Prefills identity (name, aliases, handles) from the Address Book and first/last contact + message counts from chat.db. NEVER overwrites an existing file — returns its path with created: false. The calling agent fills the sections (export_messages → summarize → edit the file directly); the file's contents are privacy: never-share.",
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        contact: {
+          type: "string",
+          description: "Contact name, phone, email, or contact:N selector."
+        },
+        threadSlug: { type: "string", description: "Thread slug from list_conversations." },
+        top: {
+          type: "number",
+          description: "Scaffold the top N relationships (1-25) by importance."
+        }
+      }
+    },
+    // @ts-expect-error
+    outputSchema: zodToJsonSchema(InitHumanOutputSchema)
   }
 ];
 const DEV_TOOL_NAMES = /* @__PURE__ */ new Set([
@@ -2061,6 +2383,150 @@ function getActiveTools() {
   if (isDevMode()) return TOOLS;
   return TOOLS.filter((t) => !DEV_TOOL_NAMES.has(t.name));
 }
+const IMAGE_BLOCK_MAX_BASE64 = 1e6;
+const IMAGE_MAX_EDGE = 1536;
+function imageBlockFromFile(path) {
+  if (!existsSync(path)) return null;
+  const work = mkdtempSync(join(tmpdir(), "imsg-media-"));
+  try {
+    const out = join(work, "preview.png");
+    execFileSync(
+      "sips",
+      ["-Z", String(IMAGE_MAX_EDGE), "-s", "format", "png", path, "--out", out],
+      {
+        stdio: "ignore",
+        timeout: 3e4
+      }
+    );
+    let base64 = readFileSync(out).toString("base64");
+    let mime = "image/png";
+    if (base64.length > IMAGE_BLOCK_MAX_BASE64) {
+      const jpg = join(work, "preview.jpg");
+      execFileSync(
+        "sips",
+        [
+          "-Z",
+          String(IMAGE_MAX_EDGE),
+          "-s",
+          "format",
+          "jpeg",
+          "-s",
+          "formatOptions",
+          "70",
+          path,
+          "--out",
+          jpg
+        ],
+        { stdio: "ignore", timeout: 3e4 }
+      );
+      base64 = readFileSync(jpg).toString("base64");
+      mime = "image/jpeg";
+      if (base64.length > IMAGE_BLOCK_MAX_BASE64) return null;
+    }
+    return { base64, mimeType: mime, note: `downscaled to ≤${IMAGE_MAX_EDGE}px via sips` };
+  } catch {
+    return null;
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+function videoPosterFrame(path) {
+  if (!existsSync(path)) return null;
+  const work = mkdtempSync(join(tmpdir(), "imsg-poster-"));
+  try {
+    execFileSync("qlmanage", ["-t", "-s", String(IMAGE_MAX_EDGE), "-o", work, path], {
+      stdio: "ignore",
+      timeout: 15e3
+    });
+    const png = readdirSync(work).find((f) => f.endsWith(".png"));
+    if (!png) return null;
+    const block = imageBlockFromFile(join(work, png));
+    if (block) block.note = "video poster frame via QuickLook";
+    return block;
+  } catch {
+    return null;
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+function mediaMetadata(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const out = execFileSync(
+      "mdls",
+      [
+        "-name",
+        "kMDItemDurationSeconds",
+        "-name",
+        "kMDItemPixelWidth",
+        "-name",
+        "kMDItemPixelHeight",
+        "-name",
+        "kMDItemCodecs",
+        "-name",
+        "kMDItemAudioSampleRate",
+        path
+      ],
+      { encoding: "utf8", timeout: 1e4 }
+    );
+    const get = (key) => {
+      const m = out.match(new RegExp(`${key}\\s*=\\s*(.+)`));
+      const v = m?.[1]?.trim();
+      return v && v !== "(null)" ? v : null;
+    };
+    const parts = [];
+    const dur = get("kMDItemDurationSeconds");
+    if (dur) parts.push(`duration ${Number.parseFloat(dur).toFixed(1)}s`);
+    const w = get("kMDItemPixelWidth");
+    const h = get("kMDItemPixelHeight");
+    if (w && h) parts.push(`${w}x${h}`);
+    const codecs = get("kMDItemCodecs");
+    if (codecs) parts.push(`codecs ${codecs.replace(/[()\n]/g, "").trim()}`);
+    const rate = get("kMDItemAudioSampleRate");
+    if (rate) parts.push(`${Number.parseFloat(rate)}Hz`);
+    return parts.length > 0 ? parts.join(" · ") : null;
+  } catch {
+    return null;
+  }
+}
+const TRANSCRIBERS = [
+  // sveinbjornt/hear — on-device Apple Speech (macOS 10.15+).
+  { name: "hear", args: (p) => ["-i", p] },
+  // finnvoor/yap — SpeechAnalyzer (macOS 26+).
+  { name: "yap", args: (p) => [p] },
+  // whisper.cpp CLI.
+  { name: "whisper-cli", args: (p) => ["-f", p, "-np", "-nt"] }
+];
+let cachedTranscriber;
+function detectTranscriber() {
+  if (cachedTranscriber !== void 0) return cachedTranscriber;
+  for (const t of TRANSCRIBERS) {
+    try {
+      execFileSync("which", [t.name], { stdio: "ignore", timeout: 3e3 });
+      cachedTranscriber = t;
+      return t;
+    } catch {
+    }
+  }
+  cachedTranscriber = null;
+  return null;
+}
+const TRANSCRIBE_MAX_BYTES = 5e7;
+function transcribeAudio(path, timeoutMs = 6e4) {
+  const t = detectTranscriber();
+  if (!t || !existsSync(path)) return null;
+  try {
+    const out = execFileSync(t.name, t.args(path), {
+      encoding: "utf8",
+      timeout: timeoutMs,
+      maxBuffer: 4 * 1024 * 1024
+    });
+    const text = out.trim();
+    return text.length > 0 ? text : null;
+  } catch {
+    return null;
+  }
+}
 const INSTRUCTIONS_UUID = randomUUID();
 function wrapUntrusted(text) {
   if (text == null || text === "") return "";
@@ -2084,6 +2550,69 @@ function sanitizeUserText(text, maxLength = 4096) {
   }
   return sanitized;
 }
+function normalizeForEcho(text) {
+  return (text ?? "").normalize("NFC").trim().replace(/\s+/g, " ");
+}
+class SentEchoRegistry {
+  entries = [];
+  windowMs;
+  skewMs;
+  maxEntries;
+  constructor(opts = {}) {
+    this.windowMs = opts.windowMs ?? 12e4;
+    this.skewMs = opts.skewMs ?? 15e3;
+    this.maxEntries = opts.maxEntries ?? 200;
+  }
+  register(chatKey, text, kind = "text") {
+    const echo = {
+      chatKey,
+      kind,
+      normalizedText: kind === "text" ? normalizeForEcho(text) : "",
+      sentAt: Date.now()
+    };
+    this.entries.push(echo);
+    if (this.entries.length > this.maxEntries) {
+      this.entries.splice(0, this.entries.length - this.maxEntries);
+    }
+    return echo;
+  }
+  /**
+   * Is this from-me message an echo of a registered send? Idempotent: a
+   * message whose id equals an entry's pinned matchedMessageId always
+   * matches. Otherwise matches on (chatKey, equal normalized text, message
+   * date within skew of sentAt, entry still inside the window, entry not
+   * pinned to a different id) — and pins the entry on first match so
+   * concurrent wait_for_reply calls see consistent suppression. Attachment
+   * entries only match rows that actually carry attachments.
+   */
+  consume(chatKey, msg) {
+    this.prune();
+    for (const e of this.entries) {
+      if (e.chatKey === chatKey && e.matchedMessageId === msg.id) return true;
+    }
+    const msgText = normalizeForEcho(msg.text);
+    for (const e of this.entries) {
+      if (e.chatKey !== chatKey || e.matchedMessageId !== void 0) continue;
+      if (msg.date.getTime() < e.sentAt - this.skewMs) continue;
+      if (e.kind === "attachment") {
+        if (!msg.hasAttachments) continue;
+      } else if (e.normalizedText !== msgText) {
+        continue;
+      }
+      e.matchedMessageId = msg.id;
+      return true;
+    }
+    return false;
+  }
+  /** Drop entries older than the suppression window. */
+  prune(now = Date.now()) {
+    this.entries = this.entries.filter((e) => now - e.sentAt <= this.windowMs);
+  }
+  /** Visible for tests. */
+  size() {
+    return this.entries.length;
+  }
+}
 const execFileAsync = promisify(execFile);
 class ToolTimeoutError extends Error {
   constructor(toolName, timeoutMs) {
@@ -2116,6 +2645,17 @@ function withTimeout(toolName, fn) {
 function round1(n) {
   return Math.round(n * 10) / 10;
 }
+function analyticTextSummary(type, data) {
+  if (type !== "relationship_leaderboard") return "";
+  const rows = data?.leaderboard ?? [];
+  if (rows.length === 0) return "\n(no ranked relationships in window)";
+  const lines = rows.slice(0, 20).map(
+    (r, i) => `${String(i + 1).padStart(2)}. ${sanitizeUserText(r.contact)}  —  ${r.total} msgs, ${Math.round(r.reciprocity * 100)}% reciprocity, last ${Math.round(r.daysSinceLast)}d ago (score ${r.score})`
+  );
+  return `
+
+${lines.join("\n")}`;
+}
 function formatDuration(ms) {
   if (ms < 1e3) return `${Math.round(ms)}ms`;
   const sec = Math.floor(ms / 1e3);
@@ -2152,6 +2692,8 @@ function formatMessage(msg, conversationLabel) {
   let status = "";
   if (!msg.isFromMe && !msg.isRead) {
     status = " [UNREAD]";
+  } else if (msg.isFromMe && msg.sendError) {
+    status = ` [NOT DELIVERED — send failed (error ${msg.sendError})]`;
   } else if (msg.isFromMe) {
     if (msg.dateRead) {
       status = ` [Read ${msg.dateRead.toLocaleTimeString("en-US", { hour: "numeric", minute: "2-digit", hour12: true })}]`;
@@ -2242,6 +2784,10 @@ class IMessageMCPServer {
   toolCallCount = 0;
   recentErrorCount = 0;
   lastActivityTs = Date.now();
+  // Fingerprints of this process's own sends so wait_for_reply can return
+  // the user's interjections without echoing the agent's just-sent message.
+  sentEchoes = new SentEchoRegistry();
+  humansIndex = new HumansIndex();
   constructor() {
     this.server = new Server(
       {
@@ -2410,6 +2956,8 @@ class IMessageMCPServer {
         return await this.handleGetAttachment(args);
       case "chat_analytics":
         return await this.handleChatAnalytics(args);
+      case "init_human":
+        return await this.handleInitHuman(args);
       default:
         throw new Error(`Unknown tool: ${name}`);
     }
@@ -2569,6 +3117,7 @@ ${stderr}`);
     const wasCapped = requested > HARD_PAGE_CAP;
     let messages;
     let threadHeader = "";
+    let humansHint = null;
     if (chatIdentifier || threadSlug) {
       let targetIdentifier = chatIdentifier;
       if (threadSlug) {
@@ -2587,6 +3136,7 @@ ${stderr}`);
         threadHeader = `Thread: ${conv.threadSlug} | ${name}${ident} | ${conv.serviceType} | ${kind}
 
 `;
+        humansHint = this.humansIndex.hintFor(conv.participants);
       }
     } else {
       messages = await this.db.getRecentMessages(limit);
@@ -2606,15 +3156,17 @@ ${stderr}`);
 _Pagination: oldestMessageId=${oldestId}, hasMore=${hasMore}${wasCapped ? ` (capped at ${HARD_PAGE_CAP} per call — use beforeMessageId or export_messages)` : ""}_` : "";
     const perfLine = `
 _Engine: ${engineLabel()} | Query: ${durMs.toFixed(0)}ms | Messages: ${messages.length}_`;
+    const humansLine = humansHint ? humansHintText(humansHint) : "";
     return toolText(
       `${threadHeader}Found ${messages.length} message(s):
 
-${formatted}${paginationLine}${perfLine}`,
+${formatted}${paginationLine}${perfLine}${humansLine}`,
       {
         messages: messages.map(messageToStructured),
         count: messages.length,
         hasMore,
-        oldestMessageId: chatIdentifier || threadSlug ? oldestId : void 0
+        oldestMessageId: chatIdentifier || threadSlug ? oldestId : void 0,
+        ...humansHint ? { humans: humansHint } : {}
       }
     );
   }
@@ -2766,7 +3318,7 @@ Call again with one of the contact:N labels.`,
           {}
         );
       }
-      preferredService = slugRecord.service === "SMS" ? "SMS" : "iMessage";
+      preferredService = this.db.getPreferredSendService(slugRecord.chatIdentifier) ?? (slugRecord.service === "SMS" ? "SMS" : "iMessage");
       if (slugRecord.isGroup) {
         if (slugRecord.displayName && !slugRecord.displayName.startsWith("chat")) {
           result = await sendToChat(slugRecord.displayName, message);
@@ -2783,7 +3335,7 @@ Call again with one of the contact:N labels.`,
     } else {
       const existingChat = await this.db.findChatByHandle(normalizedRecipient);
       if (existingChat && !existingChat.isGroupChat) {
-        preferredService = existingChat.serviceType === "SMS" ? "SMS" : "iMessage";
+        preferredService = this.db.getPreferredSendService(existingChat.chatIdentifier) ?? (existingChat.serviceType === "SMS" ? "SMS" : "iMessage");
       }
       result = await sendMessageReliable(normalizedRecipient, message, preferredService);
       if (!result.success) {
@@ -2818,9 +3370,16 @@ Call again with one of the contact:N labels.`,
         threadSlug ? this.db.getSlugRecord(threadSlug)?.chatIdentifier ?? "" : recipient
       );
       let lastMessageId;
+      let sendConfirmed = false;
       if (chat) {
-        const lastMsg = await this.db.getLastMessage(chat.chatIdentifier);
-        lastMessageId = lastMsg?.id;
+        const chatKey = chat.threadSlug ?? chat.chatIdentifier;
+        const echo = this.sentEchoes.register(chatKey, message);
+        for (const a of attachmentResults) {
+          if (a.success) this.sentEchoes.register(chatKey, "", "attachment");
+        }
+        const confirmed = await this.confirmSendLanded(chat.chatIdentifier, echo);
+        lastMessageId = confirmed.lastMessageId;
+        sendConfirmed = confirmed.confirmed;
       }
       const attSummary = attachmentResults.length > 0 ? `
 Attachments: ${attachmentResults.filter((a) => a.success).length}/${attachmentResults.length} delivered` : "";
@@ -2834,6 +3393,7 @@ Last message ID: ${lastMessageId} (use with wait_for_reply)` : ""}${attSummary}`
           timestamp: result.timestamp?.toISOString() ?? null,
           threadSlug: chat?.threadSlug,
           lastMessageId,
+          sendConfirmed,
           attachments: attachmentResults.length > 0 ? attachmentResults : void 0
         }
       );
@@ -2847,8 +3407,43 @@ Last message ID: ${lastMessageId} (use with wait_for_reply)` : ""}${attSummary}`
       );
     }
   }
+  /**
+   * Bounded poll for the just-sent message's own from-me row in chat.db.
+   * Scans the last few messages (not just the newest — an incoming reply can
+   * land AFTER our send) for a from-me row matching the echo's normalized
+   * text with a plausible date. On hit, pins the echo's ROWID so wait_for_reply
+   * suppression is exact. On timeout, falls back to the last message id
+   * (previous behavior) with confirmed: false.
+   */
+  async confirmSendLanded(chatIdentifier, echo, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 5e3;
+    const pollMs = opts.pollMs ?? 500;
+    const deadline = Date.now() + timeoutMs;
+    const skewMs = 15e3;
+    for (; ; ) {
+      const recent = await this.db.getMessagesForChat(chatIdentifier, 5);
+      for (let i = recent.length - 1; i >= 0; i--) {
+        const m = recent[i];
+        if (m.isFromMe && normalizeForEcho(m.text) === echo.normalizedText && m.date.getTime() >= echo.sentAt - skewMs) {
+          echo.matchedMessageId = m.id;
+          return { lastMessageId: m.id, confirmed: true };
+        }
+      }
+      if (Date.now() >= deadline) break;
+      await sleep(pollMs);
+    }
+    const lastMsg = await this.db.getLastMessage(chatIdentifier);
+    return { lastMessageId: lastMsg?.id, confirmed: false };
+  }
   async handleWaitForReply(args, signal) {
-    const { chatIdentifier, threadSlug, timeoutSeconds, pollIntervalSeconds, afterMessageId } = WaitForReplySchema.parse(args);
+    const {
+      chatIdentifier,
+      threadSlug,
+      timeoutSeconds,
+      pollIntervalSeconds,
+      afterMessageId,
+      includeSelf
+    } = WaitForReplySchema.parse(args);
     if (!chatIdentifier && !threadSlug) {
       return toolError("Either chatIdentifier or threadSlug is required.");
     }
@@ -2873,23 +3468,36 @@ Last message ID: ${lastMessageId} (use with wait_for_reply)` : ""}${attSummary}`
       const lastMsg = await this.db.getLastMessage(chat.chatIdentifier);
       lastKnownId = lastMsg?.id || 0;
     }
+    const chatKey = chat.threadSlug ?? chat.chatIdentifier;
     while (Date.now() - startTime < timeoutMs) {
       if (signal?.aborted) {
         return toolError(
           `Cancelled by client after ${Math.round((Date.now() - startTime) / 1e3)}s`
         );
       }
-      const newMessages = await this.db.getMessagesAfter(chat.chatIdentifier, lastKnownId);
-      if (newMessages.length > 0) {
-        const formatted = newMessages.map((m) => formatMessage(m)).join("\n");
-        return toolText(`Received ${newMessages.length} new message(s):
+      const newMessages = await this.db.getMessagesAfter(chat.chatIdentifier, lastKnownId, {
+        includeSelf
+      });
+      const visible = includeSelf ? newMessages.filter((m) => !m.isFromMe || !this.sentEchoes.consume(chatKey, m)) : newMessages;
+      if (visible.length > 0) {
+        const selfCount = visible.filter((m) => m.isFromMe).length;
+        const header = selfCount > 0 ? `Received ${visible.length} new message(s) — ${selfCount} sent by the user from their own account (another device), ${visible.length - selfCount} from the other party:` : `Received ${visible.length} new message(s):`;
+        const formatted = visible.map((m) => formatMessage(m)).join("\n");
+        const humansHint = this.humansIndex.hintFor(chat.participants);
+        const humansLine = humansHint ? humansHintText(humansHint) : "";
+        return toolText(`${header}
 
-${formatted}`, {
+${formatted}${humansLine}`, {
           received: true,
-          messages: newMessages.map(messageToStructured),
-          count: newMessages.length
+          messages: visible.map(messageToStructured),
+          count: visible.length,
+          selfCount,
+          ...humansHint ? { humans: humansHint } : {}
         });
       }
+      if (newMessages.length > 0) {
+        lastKnownId = newMessages[newMessages.length - 1].id;
+      }
       await sleep(pollIntervalMs, signal);
     }
     return toolText(
@@ -2944,11 +3552,15 @@ ${formatted}`, {
     return toolText(`Found ${results.length} conversation(s):
 
 ${formatted}`, {
-      conversations: results.map((conversation) => ({
-        ...conversation,
-        lastMessageDate: conversation.lastMessageDate?.toISOString() ?? null,
-        lastMessageSnippet: sanitizeUserText(conversation.lastMessageSnippet)
-      })),
+      conversations: results.map((conversation) => {
+        const humanFiles = this.humansIndex.lookup(conversation.participants).map((f) => f.path);
+        return {
+          ...conversation,
+          lastMessageDate: conversation.lastMessageDate?.toISOString() ?? null,
+          lastMessageSnippet: sanitizeUserText(conversation.lastMessageSnippet),
+          ...humanFiles.length > 0 ? { humansFiles: humanFiles } : {}
+        };
+      }),
       count: results.length,
       hasMore,
       nextOffset: hasMore ? startAfter : null
@@ -3107,9 +3719,19 @@ Organization: ${contact.organization}` : "";
     const threadLines = withThreads.length > 0 ? `
 Threads:
 ${withThreads.map((t) => `  ${t.handle} → ${t.threadSlug}`).join("\n")}` : "";
+    const humansHint = this.humansIndex.hintFor([...contact.phoneNumbers, ...contact.emails]);
+    const humansFile = humansHint?.files[0]?.path ?? null;
+    const humansLine = humansHint ? humansHintText(humansHint) : `
+
+_${HUMANS_INIT_HINT}_`;
     return toolText(
-      `${sanitizeUserText(contact.displayName)} (id ${contact.id})${phones}${emails}${org}${threadLines}`,
-      { contact, threads }
+      `${sanitizeUserText(contact.displayName)} (id ${contact.id})${phones}${emails}${org}${threadLines}${humansLine}`,
+      {
+        contact,
+        threads,
+        humansFile,
+        humansGuidance: humansHint?.guidance ?? HUMANS_INIT_HINT
+      }
     );
   }
   async handleResolveHandle(args) {
@@ -3189,7 +3811,7 @@ ${formatted}`, {
     });
   }
   async handleGetAttachment(args) {
-    const { readFileSync } = await import("node:fs");
+    const { readFileSync: readFileSync2 } = await import("node:fs");
     const { rowId, inlineMaxBytes } = GetAttachmentSchema.parse(args);
     const rec = this.db.getAttachmentByRowId(rowId);
     if (!rec) return toolError(`Attachment ROWID ${rowId} not found.`);
@@ -3199,36 +3821,87 @@ ${formatted}`, {
     }
     const stat = statSync(resolvedPath);
     const sizeBytes = stat.size;
-    const isHeic = (rec.mimeType ?? "").toLowerCase().includes("heic") || resolvedPath.toLowerCase().endsWith(".heic");
-    const inline = sizeBytes <= inlineMaxBytes;
+    const mime = (rec.mimeType ?? "").toLowerCase();
+    const isHeic = mime.includes("heic") || resolvedPath.toLowerCase().endsWith(".heic");
+    const isImage = mime.startsWith("image/") || isHeic;
+    const isVideo = mime.startsWith("video/");
+    const isAudio = mime.startsWith("audio/") || /\.(caf|amr|m4a|mp3|wav|aac)$/i.test(resolvedPath);
+    const inline = isImage && sizeBytes <= inlineMaxBytes;
     let base64;
     let convertedNote;
     let finalMime = rec.mimeType;
     let finalPath = resolvedPath;
-    if (inline) {
-      if (isHeic) {
-        try {
-          const { execFileSync } = await import("node:child_process");
-          const { tmpdir } = await import("node:os");
-          const { join: pjoin } = await import("node:path");
-          const out = pjoin(tmpdir(), `imsg-att-${rowId}.png`);
-          execFileSync("sips", ["-s", "format", "png", resolvedPath, "--out", out], {
-            stdio: "ignore"
-          });
-          finalPath = out;
-          finalMime = "image/png";
-          convertedNote = "HEIC → PNG via sips";
-          base64 = readFileSync(out).toString("base64");
-        } catch (e) {
-          return toolError(`HEIC→PNG conversion failed: ${e.message ?? e}`);
+    let mediaInfo;
+    let transcript;
+    let imageBlock = null;
+    if (isImage) {
+      imageBlock = imageBlockFromFile(resolvedPath);
+      if (inline) {
+        if (isHeic) {
+          try {
+            const { execFileSync: execFileSync2 } = await import("node:child_process");
+            const { tmpdir: tmpdir2 } = await import("node:os");
+            const { join: pjoin } = await import("node:path");
+            const out = pjoin(tmpdir2(), `imsg-att-${rowId}.png`);
+            execFileSync2("sips", ["-s", "format", "png", resolvedPath, "--out", out], {
+              stdio: "ignore"
+            });
+            finalPath = out;
+            finalMime = "image/png";
+            convertedNote = "HEIC → PNG via sips";
+            base64 = readFileSync2(out).toString("base64");
+          } catch (e) {
+            return toolError(`HEIC→PNG conversion failed: ${e.message ?? e}`);
+          }
+        } else {
+          base64 = readFileSync2(resolvedPath).toString("base64");
         }
+      }
+    } else if (isVideo) {
+      imageBlock = videoPosterFrame(resolvedPath);
+      mediaInfo = mediaMetadata(resolvedPath) ?? void 0;
+      convertedNote = imageBlock ? "poster frame via QuickLook" : void 0;
+    } else if (isAudio) {
+      mediaInfo = mediaMetadata(resolvedPath) ?? void 0;
+      if (sizeBytes <= TRANSCRIBE_MAX_BYTES) {
+        transcript = transcribeAudio(resolvedPath) ?? void 0;
+      }
+    }
+    const lines = [];
+    if (isVideo) {
+      lines.push(
+        `Video attachment ${rowId} (${sizeBytes}B${mediaInfo ? `, ${mediaInfo}` : ""}).`,
+        imageBlock ? "Poster frame attached as an image; full video at the path below." : "Poster frame unavailable; use the path below.",
+        `Path: ${resolvedPath}`
+      );
+    } else if (isAudio) {
+      lines.push(`Audio attachment ${rowId} (${sizeBytes}B${mediaInfo ? `, ${mediaInfo}` : ""}).`);
+      if (transcript) {
+        lines.push("", "Transcript:", wrapUntrusted(sanitizeUserText(transcript) ?? ""));
       } else {
-        base64 = readFileSync(resolvedPath).toString("base64");
+        lines.push(
+          detectTranscriber() ? "Transcription produced no text." : "No transcriber installed — `brew install hear` enables on-device transcription."
+        );
       }
+      lines.push(`Path: ${resolvedPath}`);
+    } else if (inline) {
+      lines.push(`Attachment ${rowId} (${sizeBytes}B, ${finalMime ?? "?"}) returned inline.`);
+    } else if (isImage) {
+      lines.push(
+        `Attachment ${rowId} too large to inline (${sizeBytes}B > ${inlineMaxBytes}B); a downscaled preview is attached${imageBlock ? "" : " (preview failed)"}. Full file: ${resolvedPath}`
+      );
+    } else {
+      lines.push(
+        `Attachment ${rowId} (${sizeBytes}B, ${finalMime ?? "?"}) — not an inlineable type. Path: ${resolvedPath}`
+      );
     }
-    return toolText(
-      inline ? `Attachment ${rowId} (${sizeBytes}B, ${finalMime ?? "?"}) returned inline.` : `Attachment ${rowId} too large to inline (${sizeBytes}B > ${inlineMaxBytes}B). Use path: ${resolvedPath}`,
-      {
+    const content = [{ type: "text", text: lines.join("\n") }];
+    if (imageBlock) {
+      content.push({ type: "image", data: imageBlock.base64, mimeType: imageBlock.mimeType });
+    }
+    return {
+      content,
+      structuredContent: {
         rowId,
         filename: rec.filename,
         resolvedPath: finalPath,
@@ -3236,9 +3909,108 @@ ${formatted}`, {
         totalBytes: sizeBytes,
         inline,
         base64,
-        converted: convertedNote
+        converted: convertedNote,
+        mediaInfo,
+        transcript,
+        imageBlockIncluded: imageBlock != null
+      }
+    };
+  }
+  /**
+   * Scaffold humans/v1 relationship file(s). Identity comes from the Address
+   * Book; message stats from chat.db across the person's merged legs. Never
+   * overwrites. The agent does all summarization afterwards (humans skill).
+   */
+  async handleInitHuman(args) {
+    const { contact, threadSlug, top } = InitHumanSchema.parse(args);
+    const scaffold = new HumansScaffold();
+    const targets = [];
+    const targetFromHandle = (handle, fallbackName) => {
+      const lookup = this.db.contacts.lookupContact(handle);
+      const card = lookup ? this.db.contacts.getContact(lookup.contactId) : null;
+      if (card) {
+        return {
+          name: card.displayName,
+          aliases: card.nickname && card.nickname !== card.displayName ? [card.nickname] : [],
+          handles: [...card.phoneNumbers, ...card.emails]
+        };
+      }
+      return { name: fallbackName ?? handle, aliases: [], handles: [handle] };
+    };
+    if (threadSlug) {
+      const slugRecord = this.db.getSlugRecord(threadSlug);
+      if (!slugRecord) {
+        return toolError(`Unknown thread slug: ${threadSlug}`);
+      }
+      if (slugRecord.isGroup) {
+        return toolError("Humans files are per-person — pick a 1:1 thread (or use contact/top).");
+      }
+      targets.push(
+        targetFromHandle(slugRecord.chatIdentifier, slugRecord.displayName ?? void 0)
+      );
+    } else if (contact) {
+      const selectorHit = resolveContactSelector(contact);
+      const resolution = resolveRecipient(selectorHit?.handle ?? contact, {
+        contacts: this.db.contacts,
+        defaultCountry: defaultCountryFromEnv()
+      });
+      if (resolution.kind === "error") {
+        return toolError(resolution.message);
+      }
+      if (resolution.kind === "ambiguous") {
+        const lines2 = resolution.candidates.map((c, i) => `  contact:${i + 1}  ${c.displayName}  →  ${c.handle}`).join("\n");
+        return toolError(
+          `Ambiguous contact "${contact}" — multiple matches:
+${lines2}
+
+Call again with one of the contact:N labels.`,
+          { candidates: resolution.candidates }
+        );
+      }
+      targets.push(targetFromHandle(resolution.handle, contact));
+    } else if (top !== void 0) {
+      const cutoffMs = Date.now() - 365 * 864e5;
+      const messages = await this.db.getMessagesInWindow(cutoffMs);
+      const { leaderboard } = computeRelationshipLeaderboard(messages);
+      for (const entry of leaderboard.slice(0, top)) {
+        targets.push(targetFromHandle(entry.handle, entry.contact));
+      }
+      if (targets.length === 0) {
+        return toolError("No ranked relationships found in the last year.");
+      }
+    }
+    const results = [];
+    for (const t of targets) {
+      let stats = { count: 0, first: null, last: null };
+      for (const h of t.handles) {
+        const candidates = h.includes("@") ? [h] : normalizedPhoneVariants(h);
+        for (const candidate of candidates) {
+          const s = this.db.getChatStats(candidate);
+          if (s.count > stats.count) stats = s;
+        }
       }
+      const r = scaffold.scaffold({
+        name: t.name,
+        aliases: t.aliases,
+        handles: t.handles,
+        firstContact: stats.first,
+        lastContact: stats.last,
+        messageCount: stats.count
+      });
+      results.push({ ...r, name: t.name, messageCount: stats.count });
+    }
+    const lines = results.map(
+      (r) => `${r.created ? "created" : "exists "}  ${r.slug}  (${r.name}, ${r.messageCount?.toLocaleString() ?? "?"} msgs)  ${r.path}`
+    );
+    lines.push(
+      "",
+      "Next: export history (export_messages), summarize it YOURSELF into the file's sections, and append a Log entry — see the humans skill. File contents are privacy: never-share."
     );
+    return toolText(lines.join("\n"), {
+      results,
+      count: results.length,
+      humansDir: getHumansDirPath()
+    });
   }
   async handleChatAnalytics(args) {
     const { type, windowDays } = ChatAnalyticsSchema.parse(args);
@@ -3248,20 +4020,23 @@ ${formatted}`, {
     const cacheArgs = { type, windowDays: effectiveDays };
     const hit = lookupCache(type, cacheArgs, maxRowId);
     if (hit) {
-      return toolText(`Cached ${type} (computed at ${new Date(hit.computedAt).toISOString()}).`, {
-        type,
-        windowDays: effectiveDays,
-        computedAtIso: new Date(hit.computedAt).toISOString(),
-        fromCache: true,
-        data: hit.data
-      });
+      return toolText(
+        `Cached ${type} (computed at ${new Date(hit.computedAt).toISOString()}).${analyticTextSummary(type, hit.data)}`,
+        {
+          type,
+          windowDays: effectiveDays,
+          computedAtIso: new Date(hit.computedAt).toISOString(),
+          fromCache: true,
+          data: hit.data
+        }
+      );
     }
     const messages = await this.db.getMessagesInWindow(cutoffMs);
     const result = dispatchAnalytic(type, messages);
     const computedAtIso = (/* @__PURE__ */ new Date()).toISOString();
     storeCache(type, cacheArgs, maxRowId, result.data);
     return toolText(
-      `Computed ${type} over ${messages.length} messages in the last ${effectiveDays}d.`,
+      `Computed ${type} over ${messages.length} messages in the last ${effectiveDays}d.${analyticTextSummary(type, result.data)}`,
       {
         type,
         windowDays: effectiveDays,