niahere 0.3.1 → 0.3.2

package/src/channels/whatsapp.ts

@@ -17,11 +17,11 @@
  * expires after 72h of inactivity; the join code stays valid. Outbound
  * is further gated by Meta's 24-hour customer-service window.
  */
-import { createChatEngine } from "../chat/engine";
 import { getMcpServers } from "../mcp";
-import { Session, Message } from "../db/models";
+import { Message } from "../db/models";
 import { runMigrations } from "../db/migrate";
-import type { Attachment, Channel, ChatState, TwilioConfig, WhatsappConfig, PhoneConfig } from "../types";
+import { chainLock, openChatEngine, rotateRoom } from "./common/chat-session";
+import type { Attachment, Channel, ChatState, Outbound, TwilioConfig, WhatsappConfig, PhoneConfig } from "../types";
 import { getConfig } from "../utils/config";
 import { log } from "../utils/log";
 import { classifyMime, prepareImage, validateAttachment } from "../utils/attachment";
@@ -38,7 +38,7 @@ const RESET_RE = /^\s*\/(reset|new)\s*$/i;
 const VOICE_MIME_PREFIX = "audio/";
 
 class WhatsAppChannel implements Channel {
-  name = "whatsapp";
+  name = "whatsapp" as const;
   private readonly twilio: TwilioConfig;
   private readonly whatsapp: WhatsappConfig;
   private readonly phone: PhoneConfig;
@@ -90,16 +90,16 @@ class WhatsAppChannel implements Channel {
     this.chats.clear();
   }
 
-  /** Outbound text to the owner — used by send_message MCP tool. */
-  async sendMessage(text: string): Promise<void> {
+  /** Outbound to the owner — used by send_message MCP tool. WhatsApp has no threading. */
+  async deliver(out: Outbound): Promise<void> {
     if (!this.twilio.owner_number) throw new Error("whatsapp: owner_number not set");
-    await this.sendTextTo(this.twilio.owner_number, text);
-  }
-
-  /** Outbound media to the owner — used by send_message MCP tool with attachments. */
-  async sendMedia(data: Buffer, mimeType: string, filename?: string): Promise<void> {
-    if (!this.twilio.owner_number) throw new Error("whatsapp: owner_number not set");
-    await this.sendMediaTo(this.twilio.owner_number, data, mimeType, filename);
+    const to = this.twilio.owner_number;
+    if (out.media) {
+      await this.sendMediaTo(to, Buffer.from(out.media.data), out.media.mimeType, out.media.filename);
+    }
+    if (out.text) {
+      await this.sendTextTo(to, out.text);
+    }
   }
 
   // --- Inbound webhook ---
@@ -119,107 +119,98 @@ class WhatsAppChannel implements Channel {
       // Serialize through the same lock so a /reset chasing an in-flight
       // engine.send() waits its turn instead of yanking the engine away.
       const state = await this.getState(from);
-      state.lock = state.lock.then(
-        async () => {
-          const newState = await this.restartChat(from);
-          await this.sendTextTo(
-            from,
-            `New conversation started (room ${this.roomPrefix(from)}-${newState.roomIndex}).`,
-          );
-        },
-        (err) => log.error({ err, from }, "whatsapp: /reset lock chain error"),
-      );
+      chainLock(state, async () => {
+        const newState = await this.restartChat(from);
+        await this.sendTextTo(from, `New conversation started (room ${this.roomPrefix(from)}-${newState.roomIndex}).`);
+      });
       return new Response(EMPTY_TWIML, { status: 200, headers: { "Content-Type": "text/xml" } });
     }
 
     const descriptors = extractMedia(params);
 
     const state = await this.getState(from);
-    state.lock = state.lock.then(
-      async () => {
-        let userText = body;
-        let attachments: Attachment[] | undefined;
-
-        if (descriptors.length > 0) {
-          const downloaded = await downloadInboundMedia(descriptors, {
-            accountSid: this.twilio.sid!,
-            authSid: this.twilio.sid!,
-            authSecret: this.twilio.secret!,
-          });
-
-          const voiceParts: string[] = [];
-          const built: Attachment[] = [];
-
-          for (const item of downloaded) {
-            if (item.mime.startsWith(VOICE_MIME_PREFIX)) {
-              if (!this.phone.openai_api_key) {
-                voiceParts.push("[voice note: transcription unavailable — channels.phone.openai_api_key not set]");
-                continue;
-              }
-              try {
-                const transcript = await transcribeAudio({
-                  apiKey: this.phone.openai_api_key,
-                  data: item.data,
-                  mime: item.mime,
-                });
-                voiceParts.push(transcript || "[empty voice note]");
-              } catch (err) {
-                log.error({ err, from }, "whatsapp: voice transcription failed");
-                voiceParts.push(
-                  `[voice note: transcription failed — ${err instanceof Error ? err.message : String(err)}]`,
-                );
-              }
+    chainLock(state, async () => {
+      let userText = body;
+      let attachments: Attachment[] | undefined;
+
+      if (descriptors.length > 0) {
+        const downloaded = await downloadInboundMedia(descriptors, {
+          accountSid: this.twilio.sid!,
+          authSid: this.twilio.sid!,
+          authSecret: this.twilio.secret!,
+        });
+
+        const voiceParts: string[] = [];
+        const built: Attachment[] = [];
+
+        for (const item of downloaded) {
+          if (item.mime.startsWith(VOICE_MIME_PREFIX)) {
+            if (!this.phone.openai_api_key) {
+              voiceParts.push("[voice note: transcription unavailable — channels.phone.openai_api_key not set]");
               continue;
             }
-
-            const error = validateAttachment(item.data, item.mime);
-            if (error) {
-              log.warn({ from, mime: item.mime, error }, "whatsapp: rejecting attachment");
-              await this.sendTextTo(from, `[error] ${error}`).catch(() => {});
-              continue;
+            try {
+              const transcript = await transcribeAudio({
+                apiKey: this.phone.openai_api_key,
+                data: item.data,
+                mime: item.mime,
+              });
+              voiceParts.push(transcript || "[empty voice note]");
+            } catch (err) {
+              log.error({ err, from }, "whatsapp: voice transcription failed");
+              voiceParts.push(
+                `[voice note: transcription failed — ${err instanceof Error ? err.message : String(err)}]`,
+              );
             }
+            continue;
+          }
 
-            const attType = classifyMime(item.mime) || "file";
-            let data = item.data;
-            let mime = item.mime;
-            if (attType === "image") {
-              const prepared = await prepareImage(data, mime);
-              data = prepared.data;
-              mime = prepared.mimeType;
-            }
-            built.push({ type: attType, data, mimeType: mime });
+          const error = validateAttachment(item.data);
+          if (error) {
+            log.warn({ from, mime: item.mime, error }, "whatsapp: rejecting attachment");
+            await this.sendTextTo(from, `[error] ${error}`).catch(() => {});
+            continue;
           }
 
-          if (voiceParts.length > 0) {
-            const joined = voiceParts.join("\n\n");
-            userText = userText ? `${userText}\n\n${joined}` : joined;
+          const attType = classifyMime(item.mime) || "file";
+          let data = item.data;
+          let mime = item.mime;
+          if (attType === "image") {
+            const prepared = await prepareImage(data, mime);
+            data = prepared.data;
+            mime = prepared.mimeType;
           }
-          if (built.length > 0) attachments = built;
+          built.push({ type: attType, data, mimeType: mime });
         }
 
-        if (!userText && !attachments) {
-          log.debug({ from }, "whatsapp: empty inbound (no body, no usable media)");
-          return;
+        if (voiceParts.length > 0) {
+          const joined = voiceParts.join("\n\n");
+          userText = userText ? `${userText}\n\n${joined}` : joined;
         }
+        if (built.length > 0) attachments = built;
+      }
+
+      if (!userText && !attachments) {
+        log.debug({ from }, "whatsapp: empty inbound (no body, no usable media)");
+        return;
+      }
 
+      try {
+        const { result, messageId } = await state.engine.send(userText || "(media only)", {}, attachments);
+        const reply = result.trim() || "(no response)";
         try {
-          const { result, messageId } = await state.engine.send(userText || "(media only)", {}, attachments);
-          const reply = result.trim() || "(no response)";
-          try {
-            await this.sendTextTo(from, reply);
-            if (messageId) await Message.updateDeliveryStatus(messageId, "sent").catch(() => {});
-          } catch (sendErr) {
-            if (messageId) await Message.updateDeliveryStatus(messageId, "failed").catch(() => {});
-            throw sendErr;
-          }
-        } catch (err) {
-          log.error({ err, from }, "whatsapp: engine error");
-          const errText = err instanceof Error ? err.message : String(err);
-          await this.sendTextTo(from, `[error] ${errText}`).catch(() => {});
+          await this.sendTextTo(from, reply);
+          if (messageId) await Message.updateDeliveryStatus(messageId, "sent").catch(() => {});
+        } catch (sendErr) {
+          if (messageId) await Message.updateDeliveryStatus(messageId, "failed").catch(() => {});
+          throw sendErr;
         }
-      },
-      (err) => log.error({ err, from }, "whatsapp: lock chain error"),
-    );
+      } catch (err) {
+        log.error({ err, from }, "whatsapp: engine error");
+        const errText = err instanceof Error ? err.message : String(err);
+        await this.sendTextTo(from, `[error] ${errText}`).catch(() => {});
+      }
+    });
 
     return new Response(EMPTY_TWIML, { status: 200, headers: { "Content-Type": "text/xml" } });
   }
@@ -321,43 +312,20 @@ class WhatsAppChannel implements Channel {
   private async getState(remoteE164: string): Promise<ChatState> {
     let state = this.chats.get(remoteE164);
     if (state) return state;
-    const prefix = this.roomPrefix(remoteE164);
-    const idx = await Session.getLatestRoomIndex(prefix);
-    const room = `${prefix}-${idx}`;
-    log.info({ remoteE164, room }, "whatsapp: creating chat engine");
-    const engine = await createChatEngine({
-      room,
+    state = await openChatEngine(this.roomPrefix(remoteE164), () => ({
       channel: "whatsapp",
-      resume: true,
       mcpServers: getMcpServers(),
-    });
-    state = { engine, roomIndex: idx, lock: Promise.resolve() };
+    }));
     this.chats.set(remoteE164, state);
     return state;
   }
 
   private async restartChat(remoteE164: string): Promise<ChatState> {
-    const old = this.chats.get(remoteE164);
-    if (old) old.engine.close();
-
-    const prefix = this.roomPrefix(remoteE164);
-    const prevIdx = await Session.getLatestRoomIndex(prefix);
-    const newIdx = prevIdx + 1;
-    const room = `${prefix}-${newIdx}`;
-
-    // Persist a placeholder session so the room index survives daemon
-    // restarts (otherwise getState falls back to the old room).
-    await Session.create(`placeholder-${room}`, room);
-
-    const engine = await createChatEngine({
-      room,
+    const state = await rotateRoom(this.roomPrefix(remoteE164), this.chats.get(remoteE164), () => ({
       channel: "whatsapp",
-      resume: false,
       mcpServers: getMcpServers(),
-    });
-    const state: ChatState = { engine, roomIndex: newIdx, lock: Promise.resolve() };
+    }));
     this.chats.set(remoteE164, state);
-    log.info({ remoteE164, room }, "whatsapp: new conversation started");
     return state;
   }
 }

package/src/chat/identity.ts

@@ -8,8 +8,7 @@ import { getEmployeesSummary } from "../core/employees";
 import { Session } from "../db/models";
 import type { Mode } from "../types";
 
-// Re-export for backwards compat
-export { scanSkills as loadSkills, getSkillNames as loadSkillNames, type SkillInfo } from "../core/skills";
+export { type SkillInfo } from "../core/skills";
 
 function loadFile(dir: string, name: string): string {
   const filePath = join(dir, name);

package/src/cli/phone.ts

@@ -45,7 +45,7 @@ async function phoneCallCommand(): Promise<void> {
   const channel = createPhoneChannel();
   if (!channel) {
     fail(
-      "Phone channel not configured. Set channels.phone.{twilio_sid,twilio_secret,from_number} in ~/.niahere/config.yaml (also channels.phone.{openai_api_key,public_base_url} for the realtime voice loop). Env vars TWILIO_SID / TWILIO_SECRET / PHONE_FROM_NUMBER / OPENAI_API_KEY / PUBLIC_BASE_URL override if you prefer .env.",
+      "Phone channel not configured. Set channels.twilio.{sid,secret} and channels.phone.from_number in ~/.niahere/config.yaml (also channels.phone.openai_api_key and channels.twilio.public_base_url for the realtime voice loop). Env vars TWILIO_SID / TWILIO_SECRET / PHONE_FROM_NUMBER / OPENAI_API_KEY / PUBLIC_BASE_URL override if you prefer .env.",
     );
   }
 
@@ -125,11 +125,14 @@ function helpText(): string {
     "                                phone server, dials, waits, prints transcript.",
     "  status                        Show phone channel configuration.",
     "",
-    "Config lives in ~/.niahere/config.yaml under channels.phone:",
-    "  twilio_sid, twilio_secret, from_number          (required)",
-    "  openai_api_key, public_base_url                 (required for realtime voice loop)",
-    "  twilio_auth_token                               (required if twilio_sid is an API Key SID)",
-    "  port, voice, realtime_model, allowlist          (optional)",
+    "Config lives in ~/.niahere/config.yaml:",
+    "  channels.twilio.{sid, secret}                       (required)",
+    "  channels.phone.from_number                          (required)",
+    "  channels.phone.openai_api_key, channels.twilio.public_base_url",
+    "                                                      (required for realtime voice loop)",
+    "  channels.twilio.auth_token                          (required if sid is an API Key SID)",
+    "  channels.twilio.{owner_number, allowlist, port}     (optional)",
+    "  channels.phone.{voice, realtime_model}              (optional)",
     "",
     "Each field can be overridden by the matching env var (TWILIO_SID, OPENAI_API_KEY, etc.)",
     "if you prefer .env. See the nia-phone skill for full deploy walkthrough.",

package/src/commands/init.ts

@@ -215,14 +215,18 @@ export async function runInit(): Promise<void> {
       }
     }
 
-    // Phone (Twilio Voice + OpenAI Realtime)
+    // Phone (Twilio Voice + OpenAI Realtime). Shared Twilio creds (sid,
+    // secret, auth_token, owner_number, public_base_url) live under
+    // channels.twilio so SMS and WhatsApp can reuse them; voice-specific
+    // fields stay under channels.phone.
+    const exTw = (exCh.twilio || {}) as Record<string, unknown>;
     const exPh = (exCh.phone || {}) as Record<string, unknown>;
-    let phoneTwilioSid = (exPh.twilio_sid as string) || "";
-    let phoneTwilioSecret = (exPh.twilio_secret as string) || "";
-    let phoneTwilioAuthToken = (exPh.twilio_auth_token as string) || "";
+    let phoneTwilioSid = (exTw.sid as string) || "";
+    let phoneTwilioSecret = (exTw.secret as string) || "";
+    let phoneTwilioAuthToken = (exTw.auth_token as string) || "";
     let phoneFromNumber = (exPh.from_number as string) || "";
-    let phoneOwnerNumber = (exPh.owner_number as string) || "";
-    let phonePublicBaseUrl = (exPh.public_base_url as string) || "";
+    let phoneOwnerNumber = (exTw.owner_number as string) || "";
+    let phonePublicBaseUrl = (exTw.public_base_url as string) || "";
     let phoneOpenAiKey = (exPh.openai_api_key as string) || "";
     let phoneVoice = (exPh.voice as string) || "";
 
@@ -485,14 +489,13 @@ export async function runInit(): Promise<void> {
       channels.default = "slack";
     }
     if (phoneTwilioSid && phoneTwilioSecret && phoneFromNumber) {
-      const ph: Record<string, unknown> = {
-        twilio_sid: phoneTwilioSid,
-        twilio_secret: phoneTwilioSecret,
-        from_number: phoneFromNumber,
-      };
-      if (phoneTwilioAuthToken) ph.twilio_auth_token = phoneTwilioAuthToken;
-      if (phoneOwnerNumber) ph.owner_number = phoneOwnerNumber;
-      if (phonePublicBaseUrl) ph.public_base_url = phonePublicBaseUrl.replace(/\/$/, "");
+      const tw: Record<string, unknown> = { sid: phoneTwilioSid, secret: phoneTwilioSecret };
+      if (phoneTwilioAuthToken) tw.auth_token = phoneTwilioAuthToken;
+      if (phoneOwnerNumber) tw.owner_number = phoneOwnerNumber;
+      if (phonePublicBaseUrl) tw.public_base_url = phonePublicBaseUrl.replace(/\/$/, "");
+      channels.twilio = tw;
+
+      const ph: Record<string, unknown> = { from_number: phoneFromNumber };
       if (phoneOpenAiKey) ph.openai_api_key = phoneOpenAiKey;
       if (phoneVoice && phoneVoice !== "marin") ph.voice = phoneVoice;
       channels.phone = ph;

package/src/commands/service.ts

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, writeFileSync, unlinkSync } from "fs";
-import { join } from "path";
+import { join, resolve } from "path";
 import { homedir } from "os";
 import { getPaths } from "../utils/paths";
 import { findDaemonPids } from "../core/daemon";
@@ -29,6 +29,9 @@ function plistPath(): string {
 function buildPlist(): string {
   const paths = getPaths();
   const [execPath, cliPath] = getExecCommand();
+  // Bun auto-loads .env from cwd. Without WorkingDirectory, launchd
+  // spawns the daemon with cwd=/ and any credentials in .env never load.
+  const workingDir = resolve(cliPath, "../../..");
 
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -42,6 +45,8 @@ function buildPlist(): string {
     <string>${cliPath}</string>
     <string>run</string>
   </array>
+  <key>WorkingDirectory</key>
+  <string>${workingDir}</string>
   <key>RunAtLoad</key>
   <true/>
   <key>KeepAlive</key>
@@ -108,6 +113,7 @@ function unitPath(): string {
 function buildUnit(): string {
   const paths = getPaths();
   const [execPath, cliPath] = getExecCommand();
+  const workingDir = resolve(cliPath, "../../..");
 
   return `[Unit]
 Description=nia personal AI assistant
@@ -115,6 +121,7 @@ After=network.target
 
 [Service]
 ExecStart=${execPath} ${cliPath} run
+WorkingDirectory=${workingDir}
 Restart=always
 RestartSec=5
 StandardOutput=append:${paths.daemonLog}
@@ -137,7 +144,10 @@ async function installSystemd(): Promise<void> {
   const reload = Bun.spawn(["systemctl", "--user", "daemon-reload"], { stdout: "pipe", stderr: "pipe" });
   await reload.exited;
 
-  const enable = Bun.spawn(["systemctl", "--user", "enable", "--now", SYSTEMD_UNIT], { stdout: "pipe", stderr: "pipe" });
+  const enable = Bun.spawn(["systemctl", "--user", "enable", "--now", SYSTEMD_UNIT], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
   const exitCode = await enable.exited;
 
   if (exitCode !== 0) {
@@ -150,10 +160,17 @@ async function uninstallSystemd(): Promise<void> {
   const path = unitPath();
   if (!existsSync(path)) return;
 
-  const disable = Bun.spawn(["systemctl", "--user", "disable", "--now", SYSTEMD_UNIT], { stdout: "pipe", stderr: "pipe" });
+  const disable = Bun.spawn(["systemctl", "--user", "disable", "--now", SYSTEMD_UNIT], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
   await disable.exited;
 
-  try { unlinkSync(path); } catch { /* already gone */ }
+  try {
+    unlinkSync(path);
+  } catch {
+    /* already gone */
+  }
 
   const reload = Bun.spawn(["systemctl", "--user", "daemon-reload"], { stdout: "pipe", stderr: "pipe" });
   await reload.exited;
@@ -197,7 +214,7 @@ export async function restartService(opts: { force?: boolean } = {}): Promise<vo
     const path = plistPath();
     // Unload — sends SIGTERM and disables KeepAlive respawn
     const unload = Bun.spawn(["launchctl", "unload", path], { stdout: "pipe", stderr: "pipe" });
-    if (await unload.exited !== 0) {
+    if ((await unload.exited) !== 0) {
       const stderr = await new Response(unload.stderr).text();
       console.error(`  warning: launchctl unload failed: ${stderr.trim()}`);
     }
@@ -206,7 +223,7 @@ export async function restartService(opts: { force?: boolean } = {}): Promise<vo
     if (opts.force) clearForceShutdownRequest();
     // Load — starts a fresh single instance
     const load = Bun.spawn(["launchctl", "load", path], { stdout: "pipe", stderr: "pipe" });
-    if (await load.exited !== 0) {
+    if ((await load.exited) !== 0) {
       const stderr = await new Response(load.stderr).text();
       console.error(`  warning: launchctl load failed: ${stderr.trim()}`);
     }
@@ -227,6 +244,8 @@ async function waitForDaemonExit(timeoutMs: number): Promise<void> {
   }
   // Force kill any stragglers
   for (const pid of findDaemonPids()) {
-    try { process.kill(pid, "SIGKILL"); } catch {}
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {}
   }
 }

package/src/mcp/tools.ts

@@ -1,5 +1,5 @@
-import { readFileSync, writeFileSync, appendFileSync, existsSync } from "fs";
-import type { ScheduleType } from "../types";
+import { readFileSync, appendFileSync, existsSync } from "fs";
+import type { Recipient, ScheduleType } from "../types";
 import { basename, join } from "path";
 import { randomUUID } from "crypto";
 import { Job, Message, Session } from "../db/models";
@@ -8,7 +8,6 @@ import { getConfig, readRawConfig, updateRawConfig, writeRawConfig } from "../ut
 import { getPaths } from "../utils/paths";
 import { getChannel } from "../channels/registry";
 import { log } from "../utils/log";
-import { classifyMime } from "../utils/attachment";
 import { scanAgents } from "../core/agents";
 import { listEmployeesForMcp } from "../core/employees";
 import { resolveJobPrompt } from "../core/job-prompt";
@@ -312,42 +311,27 @@ export async function sendMessage(
   }
 
   try {
-    // Handle media attachment if provided
+    let media: { data: Uint8Array; mimeType: string; filename: string } | undefined;
     if (mediaPath) {
       if (!existsSync(mediaPath)) {
         if (messageId) await Message.updateDeliveryStatus(messageId, "failed").catch(() => {});
         return `Failed to send: file not found: ${mediaPath}`;
       }
-      const data = readFileSync(mediaPath);
-      const mimeType = guessMime(mediaPath);
-      const filename = basename(mediaPath);
-
-      if (useThread && channel?.sendMediaToThread) {
-        await channel.sendMediaToThread(sourceCtx!.slackChannelId!, data, mimeType, filename, sourceCtx!.slackThreadTs);
-      } else if (channel?.sendMedia) {
-        await channel.sendMedia(data, mimeType, filename);
-      } else {
-        await sendMediaDirect(channelTarget, data, mimeType, filename);
-      }
+      const buf = readFileSync(mediaPath);
+      media = { data: new Uint8Array(buf), mimeType: guessMime(mediaPath), filename: basename(mediaPath) };
+    }
 
-      // Also send text if provided (as a separate message)
-      if (text) {
-        if (useThread && channel?.sendToThread) {
-          await channel.sendToThread(sourceCtx!.slackChannelId!, text, sourceCtx!.slackThreadTs);
-        } else if (channel?.sendMessage) {
-          await channel.sendMessage(text);
-        } else {
-          await sendDirect(channelTarget, text);
-        }
-      }
+    const recipient: Recipient = useThread
+      ? { kind: "thread", channelId: sourceCtx!.slackChannelId!, threadTs: sourceCtx!.slackThreadTs }
+      : { kind: "owner" };
+
+    if (channel) {
+      await channel.deliver({ text: text || undefined, media, to: recipient });
     } else {
-      if (useThread && channel?.sendToThread) {
-        await channel.sendToThread(sourceCtx!.slackChannelId!, text, sourceCtx!.slackThreadTs);
-      } else if (channel?.sendMessage) {
-        await channel.sendMessage(text);
-      } else {
-        await sendDirect(channelTarget, text);
-      }
+      // No started channel in this process (e.g. CLI `nia send` outside the daemon).
+      // Fall back to API-direct send — text-only, no thread fan-out.
+      if (media) await sendMediaDirect(channelTarget, Buffer.from(media.data), media.mimeType, media.filename);
+      if (text) await sendDirect(channelTarget, text);
     }
 
     // Mark as sent
@@ -480,7 +464,7 @@ export async function placeCall(args: {
   const { getPhoneChannel } = await import("../channels/phone");
   const phone = getPhoneChannel();
   if (!phone) {
-    return "Phone channel is not configured. Add a channels.phone block to ~/.niahere/config.yaml with twilio_sid, twilio_secret, from_number, public_base_url, openai_api_key (or set the matching env vars in .env), then restart the daemon.";
+    return "Phone channel is not configured. Add channels.twilio.{sid, secret, public_base_url} and channels.phone.{from_number, openai_api_key} to ~/.niahere/config.yaml (or set the matching env vars in .env), then restart the daemon.";
   }
   try {
     const result = await phone.placeCall({

package/src/types/channel.ts

@@ -1,13 +1,42 @@
+/**
+ * Where an outbound payload is delivered.
+ *
+ * - `owner` → the channel's configured default recipient (DM user, owner
+ *   phone number, etc.). Always supported.
+ * - `thread` → reply in a specific Slack thread. Channels that don't
+ *   support threads fall back to `owner`.
+ */
+export type Recipient = { kind: "owner" } | { kind: "thread"; channelId: string; threadTs?: string };
+
+export interface OutboundMedia {
+  data: Uint8Array;
+  mimeType: string;
+  filename?: string;
+}
+
+/**
+ * Structured payload for agent-initiated outbound messages (`send_message`
+ * MCP tool, cross-channel notifications). Replaces the old optional
+ * sendMessage / sendMedia / sendToThread / sendMediaToThread surface.
+ */
+export interface Outbound {
+  text?: string;
+  media?: OutboundMedia;
+  /** Defaults to `{ kind: "owner" }`. */
+  to?: Recipient;
+}
+
 export interface Channel {
+  /** Channel identifier. Built-in channels use the `ChannelName` literals; test fixtures may use other strings. */
   name: string;
   start(): Promise<void>;
   stop(): Promise<void>;
-  sendMessage?(text: string): Promise<void>;
-  sendMedia?(data: Buffer, mimeType: string, filename?: string): Promise<void>;
-  /** Send media to a specific channel/thread when the channel supports it. */
-  sendMediaToThread?(channelId: string, data: Buffer, mimeType: string, filename?: string, threadTs?: string): Promise<void>;
-  /** Send a message to a specific channel/thread (e.g. reply back to a Slack thread). */
-  sendToThread?(channelId: string, text: string, threadTs?: string): Promise<void>;
+  /**
+   * Deliver an outbound payload. Channels are expected to handle either
+   * a text-only, media-only, or text+media payload; format details (chunking,
+   * markdown, attachment shape) are channel-specific.
+   */
+  deliver(out: Outbound): Promise<void>;
 }
 
 export type ChannelFactory = () => Channel | null;

package/src/types/index.ts

@@ -3,7 +3,7 @@ export type { JobStatus, JobStateStatus, JobLifecycle, ScheduleType, Mode, Attac
 export type { JobInput, JobPromptSource, JobResult, ResolvedJobPrompt } from "./job";
 export type { SendResult, StreamCallback, ActivityCallback, SendCallbacks, ChatEngine, EngineOptions } from "./engine";
 export type { AuditEntry, JobState, CronState } from "./audit";
-export type { Channel, ChannelFactory } from "./channel";
+export type { Channel, ChannelFactory, Outbound, OutboundMedia, Recipient } from "./channel";
 export type { ChatState } from "./chat-state";
 export type {
   Config,

package/src/utils/attachment.ts

@@ -1,5 +1,11 @@
 import type { AttachmentType } from "../types";
-import { IMAGE_MIMES, DOCUMENT_MIMES, MAX_ATTACHMENT_SIZE, MAX_IMAGE_DIMENSION, JPEG_QUALITY } from "../constants/attachment";
+import {
+  IMAGE_MIMES,
+  DOCUMENT_MIMES,
+  MAX_ATTACHMENT_SIZE,
+  MAX_IMAGE_DIMENSION,
+  JPEG_QUALITY,
+} from "../constants/attachment";
 
 export function classifyMime(mimeType: string): AttachmentType | null {
   if (IMAGE_MIMES.has(mimeType)) return "image";
@@ -8,7 +14,7 @@ export function classifyMime(mimeType: string): AttachmentType | null {
   return "file";
 }
 
-export function validateAttachment(data: Buffer, mimeType: string): string | null {
+export function validateAttachment(data: Buffer): string | null {
   if (data.length > MAX_ATTACHMENT_SIZE) {
     return `File too large (${(data.length / 1024 / 1024).toFixed(1)}MB, max ${MAX_ATTACHMENT_SIZE / 1024 / 1024}MB)`;
   }