niahere 0.2.90 → 0.2.91

package/src/cli/phone.ts

@@ -0,0 +1,127 @@
+/**
+ * `nia phone <subcommand>` — small CLI surface for the phone channel.
+ *
+ * Subcommands:
+ *   call <number> <goal...>    — place an outbound call, wait, print transcript
+ *   status                     — show phone channel config + state
+ *
+ * The call subcommand boots a standalone phone channel server, places the
+ * call, waits for it to complete, then exits. It does NOT start the full
+ * daemon — useful for smoke-testing voice end-to-end without the daemon.
+ */
+import { createPhoneChannel } from "../channels/phone";
+import { getConfig } from "../utils/config";
+import { fail, ICON_PASS, ICON_WARN } from "../utils/cli";
+
+export async function phoneCommand(): Promise<void> {
+  const sub = process.argv[3];
+
+  switch (sub) {
+    case "call":
+      await phoneCallCommand();
+      return;
+    case "status":
+      phoneStatusCommand();
+      return;
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      printHelp();
+      return;
+    default:
+      fail(`Unknown phone subcommand: ${sub}\n\n${helpText()}`);
+  }
+}
+
+async function phoneCallCommand(): Promise<void> {
+  const number = process.argv[4];
+  const goalParts = process.argv.slice(5);
+  if (!number || goalParts.length === 0) {
+    fail('Usage: nia phone call <e164-number> "<goal sentence...>"');
+  }
+  const goal = goalParts.join(" ");
+
+  const channel = createPhoneChannel();
+  if (!channel) {
+    fail(
+      "Phone channel not configured. Need TWILIO_SID, TWILIO_SECRET, PHONE_FROM_NUMBER in .env (plus OPENAI_API_KEY and PUBLIC_BASE_URL for the realtime voice loop).",
+    );
+  }
+
+  await channel!.start();
+  const cfg = getConfig().channels.phone;
+  console.log(`${ICON_PASS} phone server up on :${cfg.port}`);
+  if (!cfg.public_base_url) {
+    console.log(`${ICON_WARN} PUBLIC_BASE_URL not set — Twilio cannot reach this server.`);
+    console.log(`         Start cloudflared (or your tunnel) and set PUBLIC_BASE_URL in .env first.`);
+    await channel!.stop();
+    process.exit(1);
+  }
+  if (!cfg.openai_api_key) {
+    console.log(`${ICON_WARN} OPENAI_API_KEY not set — realtime voice loop will fall back to TwiML <Say>.`);
+  }
+
+  console.log(`  dialing ${number} ...`);
+  console.log(`  goal: ${goal}`);
+
+  const result = await channel!.placeCall({
+    number,
+    goal,
+    maxMinutes: 5,
+  });
+  console.log(`${ICON_PASS} call placed: ${result.callSid} (${result.status})`);
+
+  console.log(`  waiting for call to complete...`);
+  const completion = await channel!.awaitCallCompletion(result.callSid);
+  if (!completion) {
+    console.log(`${ICON_WARN} no completion handle for ${result.callSid}`);
+    await channel!.stop();
+    return;
+  }
+
+  console.log("");
+  console.log(`--- transcript (${completion.transcript.length} turns, ended: ${completion.endedReason}) ---`);
+  for (const turn of completion.transcript) {
+    console.log(`  ${turn.role}: ${turn.text}`);
+  }
+  if (completion.error) console.log(`  error: ${completion.error}`);
+
+  await channel!.stop();
+}
+
+function phoneStatusCommand(): void {
+  const cfg = getConfig().channels.phone;
+  const lines = [
+    `from:           ${cfg.from_number ?? "(not set)"}`,
+    `owner:          ${cfg.owner_number ?? "(not set)"}`,
+    `allowlist:      ${cfg.allowlist.length ? cfg.allowlist.join(", ") : "(empty)"}`,
+    `port:           ${cfg.port}`,
+    `public_base_url:${cfg.public_base_url ?? "(not set)"}`,
+    `realtime_model: ${cfg.realtime_model}`,
+    `voice:          ${cfg.voice}`,
+    `twilio creds:   ${cfg.twilio_sid && cfg.twilio_secret ? "configured" : "MISSING"}`,
+    `openai key:     ${cfg.openai_api_key ? "configured" : "MISSING"}`,
+  ];
+  console.log(lines.join("\n"));
+}
+
+function printHelp(): void {
+  console.log(helpText());
+}
+
+function helpText(): string {
+  return [
+    "Usage: nia phone <subcommand>",
+    "",
+    "Subcommands:",
+    '  call <e164-number> "<goal>"   Place an outbound call. Boots a standalone',
+    "                                phone server, dials, waits, prints transcript.",
+    "  status                        Show phone channel configuration.",
+    "",
+    "Required env:",
+    "  TWILIO_SID, TWILIO_SECRET, PHONE_FROM_NUMBER",
+    "  OPENAI_API_KEY (for realtime voice loop)",
+    "  PUBLIC_BASE_URL (cloudflared/ngrok tunnel pointing at PHONE_PORT)",
+  ].join("\n");
+}

package/src/mcp/server.ts

@@ -158,7 +158,9 @@ export function createNiaMcpServer(sourceCtx?: McpSourceContext) {
           target: z
             .enum(["auto", "dm", "thread"])
             .default("auto")
-            .describe("Where to send: 'auto' (current context — thread if in one, else DM), 'dm' (always DM the owner), 'thread' (reply in current thread)"),
+            .describe(
+              "Where to send: 'auto' (current context — thread if in one, else DM), 'dm' (always DM the owner), 'thread' (reply in current thread)",
+            ),
         },
         async (args) => ({
           content: [
@@ -349,6 +351,27 @@ export function createNiaMcpServer(sourceCtx?: McpSourceContext) {
           content: [{ type: "text" as const, text: handlers.listEmployees() }],
         }),
       ),
+      tool(
+        "place_call",
+        "Place an outbound phone call. Nia dials the number, introduces herself, and pursues the stated goal. Use for appointments, vendor follow-ups, scheduled standup calls to the owner, or anything that's faster by voice than by message.",
+        {
+          number: z.string().describe("E.164 phone number to dial (e.g. +13025551234)."),
+          goal: z
+            .string()
+            .describe(
+              "What this call should accomplish, in plain English. Seeded into the voice agent's instructions.",
+            ),
+          context: z
+            .string()
+            .optional()
+            .describe("Extra background to seed the call (calendar dump, prior notes, etc.)."),
+          max_minutes: z.number().optional().describe("Hard cap on call duration in minutes (default 10, max 30)."),
+          voice: z.string().optional().describe("Override the default realtime voice for this call."),
+        },
+        async (args) => ({
+          content: [{ type: "text" as const, text: await handlers.placeCall(args) }],
+        }),
+      ),
     ],
   });
 }

package/src/mcp/tools.ts

@@ -12,6 +12,7 @@ import { classifyMime } from "../utils/attachment";
 import { scanAgents } from "../core/agents";
 import { listEmployeesForMcp } from "../core/employees";
 import { resolveJobPrompt } from "../core/job-prompt";
+import { readMemory as readMemoryUtil, addMemory as addMemoryUtil } from "../utils/memory";
 import type { McpSourceContext } from "./index";
 
 export async function listJobs(): Promise<string> {
@@ -240,7 +241,13 @@ async function sendMediaDirect(target: string, data: Buffer, mimeType: string, f
   throw new Error(`Channel "${target}" not configured`);
 }
 
-export async function sendMessage(text: string, channelName?: string, mediaPath?: string, sourceCtx?: McpSourceContext, target: "auto" | "dm" | "thread" = "auto"): Promise<string> {
+export async function sendMessage(
+  text: string,
+  channelName?: string,
+  mediaPath?: string,
+  sourceCtx?: McpSourceContext,
+  target: "auto" | "dm" | "thread" = "auto",
+): Promise<string> {
   const config = getConfig();
   const channelTarget = channelName || config.channels.default;
 
@@ -440,43 +447,8 @@ export function disableWatchChannel(name: string): string {
   return `Watch channel "${name}" disabled. Takes effect on next message.`;
 }
 
-export function readMemory(): string {
-  const { selfDir } = getPaths();
-  const memoryPath = join(selfDir, "memory.md");
-  if (!existsSync(memoryPath)) return "No memories saved yet.";
-  const content = readFileSync(memoryPath, "utf8").trim();
-  // Extract just the entries, skip the header/instructions
-  const lines = content.split("\n").filter((l) => l.startsWith("- ") || l.startsWith("## "));
-  if (lines.length === 0) return "No memories saved yet.";
-  return lines.join("\n");
-}
-
-export function addMemory(entry: string): string {
-  // Guard: reject raw logs, transcripts, and overly long entries
-  const trimmed = entry.trim();
-  if (!trimmed) return "Rejected: empty entry.";
-  if (trimmed.length > 300) return "Rejected: too long (max 300 chars). Distill to a single concise insight.";
-  if (trimmed.includes("[Thread context]") || trimmed.includes("[Current messag"))
-    return "Rejected: no raw conversation transcripts.";
-  if (trimmed.split("\n").length > 5) return "Rejected: too many lines. One concise insight per memory.";
-
-  const { selfDir } = getPaths();
-  const memoryPath = join(selfDir, "memory.md");
-  const existing = existsSync(memoryPath) ? readFileSync(memoryPath, "utf8") : "";
-
-  // TODO: add semantic dedup later (embeddings or similar)
-
-  const date = new Date().toISOString().slice(0, 10);
-  const header = `\n## ${date}`;
-
-  if (existing.includes(header)) {
-    const updated = existing.replace(header, `${header}\n- ${trimmed}`);
-    writeFileSync(memoryPath, updated, "utf8");
-  } else {
-    appendFileSync(memoryPath, `${header}\n- ${trimmed}\n`, "utf8");
-  }
-  return `Memory saved.`;
-}
+export const readMemory = readMemoryUtil;
+export const addMemory = addMemoryUtil;
 
 export function listAgents(): string {
   const agents = scanAgents();
@@ -496,3 +468,30 @@ export function listAgents(): string {
 export function listEmployees(): string {
   return listEmployeesForMcp();
 }
+
+export async function placeCall(args: {
+  number: string;
+  goal: string;
+  context?: string;
+  max_minutes?: number;
+  voice?: string;
+}): Promise<string> {
+  // Dynamic import avoids a static cycle with channels/phone -> mcp/tools.
+  const { getPhoneChannel } = await import("../channels/phone");
+  const phone = getPhoneChannel();
+  if (!phone) {
+    return "Phone channel is not configured. Set TWILIO_SID, TWILIO_SECRET, PHONE_FROM_NUMBER, PUBLIC_BASE_URL, OPENAI_API_KEY in .env and restart the daemon.";
+  }
+  try {
+    const result = await phone.placeCall({
+      number: args.number,
+      goal: args.goal,
+      context: args.context,
+      maxMinutes: args.max_minutes,
+      voice: args.voice,
+    });
+    return `Call placed. callSid=${result.callSid} status=${result.status}. Transcript will land in messages once the call completes.`;
+  } catch (err) {
+    return `place_call failed: ${err instanceof Error ? err.message : String(err)}`;
+  }
+}

package/src/types/config.ts

@@ -28,11 +28,37 @@ export interface SlackConfig {
   watch: Record<string, SlackWatchChannel> | null;
 }
 
+export interface PhoneConfig {
+  twilio_sid: string | null;
+  twilio_secret: string | null;
+  /** Account-level Auth Token used to verify X-Twilio-Signature on inbound webhooks.
+   *  Falls back to twilio_secret if not set (works when twilio_sid is the Account SID
+   *  and twilio_secret is the Auth Token). */
+  twilio_auth_token: string | null;
+  /** Twilio number Nia dials from (E.164, e.g. +13025480697) */
+  from_number: string | null;
+  /** Owner's phone number (E.164). Highest-trust caller. */
+  owner_number: string | null;
+  /** Extra allowlisted E.164 numbers (family, close contacts). */
+  allowlist: string[];
+  /** Public base URL Twilio hits (e.g. https://nia.example.com). No trailing slash. */
+  public_base_url: string | null;
+  /** Local HTTP port for the Twilio webhook server. */
+  port: number;
+  /** OpenAI API key for the Realtime voice loop. */
+  openai_api_key: string | null;
+  /** OpenAI Realtime model id. */
+  realtime_model: string;
+  /** Realtime voice name (marin, alloy, echo, etc.). */
+  voice: string;
+}
+
 export interface ChannelsConfig {
   enabled: boolean;
   default: string;
   telegram: TelegramConfig;
   slack: SlackConfig;
+  phone: PhoneConfig;
 }
 
 export interface SessionFinalizationConfig {

package/src/types/index.ts

@@ -5,7 +5,7 @@ export type { SendResult, StreamCallback, ActivityCallback, SendCallbacks, ChatE
 export type { AuditEntry, JobState, CronState } from "./audit";
 export type { Channel, ChannelFactory } from "./channel";
 export type { ChatState } from "./chat-state";
-export type { Config, ChannelsConfig, TelegramConfig, SlackConfig } from "./config";
+export type { Config, ChannelsConfig, TelegramConfig, SlackConfig, PhoneConfig } from "./config";
 export type { Paths } from "./paths";
 export type { SaveMessageParams, RoomStats, RecentMessage, SearchResult, SessionMessage } from "./message";
 export type { AgentInfo } from "./agent";

package/src/utils/config.ts

@@ -36,6 +36,19 @@ const DEFAULTS: Config = {
       workspace_url: null,
       watch: null,
     },
+    phone: {
+      twilio_sid: null,
+      twilio_secret: null,
+      twilio_auth_token: null,
+      from_number: null,
+      owner_number: null,
+      allowlist: [],
+      public_base_url: null,
+      port: 7079,
+      openai_api_key: null,
+      realtime_model: "gpt-realtime",
+      voice: "marin",
+    },
   },
 };
 
@@ -117,6 +130,7 @@ export function loadConfig(): Config {
   const ch = (raw.channels || {}) as Record<string, unknown>;
   const chTg = (ch.telegram || {}) as Record<string, unknown>;
   const chSl = (ch.slack || {}) as Record<string, unknown>;
+  const chPh = (ch.phone || {}) as Record<string, unknown>;
 
   const channelsEnabled = ch.enabled !== false;
 
@@ -137,11 +151,10 @@ export function loadConfig(): Config {
   const slAppToken = process.env.SLACK_APP_TOKEN || (typeof chSl.app_token === "string" ? chSl.app_token : null);
 
   // Legacy: channel_id was removed in favor of dm_user_id. Fall back to channel_id if dm_user_id is not set.
-  const legacyChannelId = process.env.SLACK_CHANNEL_ID || (typeof chSl.channel_id === "string" ? chSl.channel_id : null);
+  const legacyChannelId =
+    process.env.SLACK_CHANNEL_ID || (typeof chSl.channel_id === "string" ? chSl.channel_id : null);
   const slDmUserId =
-    process.env.SLACK_DM_USER_ID ||
-    (typeof chSl.dm_user_id === "string" ? chSl.dm_user_id : null) ||
-    legacyChannelId;
+    process.env.SLACK_DM_USER_ID || (typeof chSl.dm_user_id === "string" ? chSl.dm_user_id : null) || legacyChannelId;
 
   const slBotUserId = typeof chSl.bot_user_id === "string" ? chSl.bot_user_id : null;
   const slBotName = typeof chSl.bot_name === "string" ? chSl.bot_name : null;
@@ -149,6 +162,47 @@ export function loadConfig(): Config {
   const slWorkspaceId = typeof chSl.workspace_id === "string" ? chSl.workspace_id : null;
   const slWorkspaceUrl = typeof chSl.workspace_url === "string" ? chSl.workspace_url : null;
 
+  // Phone — env vars override config; secrets are env-only by convention
+  const phTwilioSid = process.env.TWILIO_SID || (typeof chPh.twilio_sid === "string" ? chPh.twilio_sid : null);
+  const phTwilioSecret =
+    process.env.TWILIO_SECRET || (typeof chPh.twilio_secret === "string" ? chPh.twilio_secret : null);
+  const phTwilioAuthToken =
+    process.env.TWILIO_AUTH_TOKEN || (typeof chPh.twilio_auth_token === "string" ? chPh.twilio_auth_token : null);
+  const phFromNumber =
+    process.env.PHONE_FROM_NUMBER || (typeof chPh.from_number === "string" ? chPh.from_number : null);
+  const phOwnerNumber =
+    process.env.PRIMARY_PHONE_USER || (typeof chPh.owner_number === "string" ? chPh.owner_number : null);
+  const phPublicBaseUrl =
+    (
+      process.env.PUBLIC_BASE_URL ||
+      (typeof chPh.public_base_url === "string" ? chPh.public_base_url : null) ||
+      ""
+    ).replace(/\/$/, "") || null;
+  const phPortRaw = process.env.PHONE_PORT ? Number(process.env.PHONE_PORT) : null;
+  const phPort =
+    phPortRaw && Number.isFinite(phPortRaw)
+      ? phPortRaw
+      : typeof chPh.port === "number"
+        ? chPh.port
+        : DEFAULTS.channels.phone.port;
+  const phOpenAiKey =
+    process.env.OPENAI_API_KEY || (typeof chPh.openai_api_key === "string" ? chPh.openai_api_key : null);
+  const phRealtimeModel =
+    process.env.PHONE_REALTIME_MODEL ||
+    (typeof chPh.realtime_model === "string" ? chPh.realtime_model : DEFAULTS.channels.phone.realtime_model);
+  const phVoice =
+    process.env.PHONE_VOICE || (typeof chPh.voice === "string" ? chPh.voice : DEFAULTS.channels.phone.voice);
+
+  const phAllowlistRaw =
+    process.env.PHONE_ALLOWLIST ||
+    (Array.isArray(chPh.allowlist)
+      ? (chPh.allowlist as unknown[]).filter((x): x is string => typeof x === "string").join(",")
+      : "");
+  const phAllowlist = phAllowlistRaw
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+
   // Slack watch channels — behavior is optional (defaults to key name lookup)
   const rawWatch = chSl.watch as Record<string, unknown> | undefined;
   let slWatch: Record<string, { behavior?: string; enabled: boolean }> | null = null;
@@ -188,6 +242,19 @@ export function loadConfig(): Config {
         workspace_url: slWorkspaceUrl,
         watch: slWatch,
       },
+      phone: {
+        twilio_sid: phTwilioSid,
+        twilio_secret: phTwilioSecret,
+        twilio_auth_token: phTwilioAuthToken,
+        from_number: phFromNumber,
+        owner_number: phOwnerNumber,
+        allowlist: phAllowlist,
+        public_base_url: phPublicBaseUrl,
+        port: phPort,
+        openai_api_key: phOpenAiKey,
+        realtime_model: phRealtimeModel,
+        voice: phVoice,
+      },
     },
   };
 }

package/src/utils/memory.ts

@@ -0,0 +1,49 @@
+/**
+ * Read/write helpers for the persona memory file (~/.niahere/self/memory.md).
+ *
+ * Lives in utils/ so both the MCP tools (chat surface) and channel modules
+ * (e.g. phone) can share the same validation + write semantics without
+ * creating an import cycle.
+ */
+import { existsSync, readFileSync, appendFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { getPaths } from "./paths";
+
+export function readMemory(): string {
+  const { selfDir } = getPaths();
+  const memoryPath = join(selfDir, "memory.md");
+  if (!existsSync(memoryPath)) return "No memories saved yet.";
+  const content = readFileSync(memoryPath, "utf8").trim();
+  const lines = content.split("\n").filter((l) => l.startsWith("- ") || l.startsWith("## "));
+  if (lines.length === 0) return "No memories saved yet.";
+  return lines.join("\n");
+}
+
+/**
+ * Append a single concise insight under today's date heading. Returns a
+ * human-readable result string for the caller (MCP tool / phone tool) to
+ * relay back to the model.
+ */
+export function addMemory(entry: string): string {
+  const trimmed = entry.trim();
+  if (!trimmed) return "Rejected: empty entry.";
+  if (trimmed.length > 300) return "Rejected: too long (max 300 chars). Distill to a single concise insight.";
+  if (trimmed.includes("[Thread context]") || trimmed.includes("[Current messag"))
+    return "Rejected: no raw conversation transcripts.";
+  if (trimmed.split("\n").length > 5) return "Rejected: too many lines. One concise insight per memory.";
+
+  const { selfDir } = getPaths();
+  const memoryPath = join(selfDir, "memory.md");
+  const existing = existsSync(memoryPath) ? readFileSync(memoryPath, "utf8") : "";
+
+  const date = new Date().toISOString().slice(0, 10);
+  const header = `\n## ${date}`;
+
+  if (existing.includes(header)) {
+    const updated = existing.replace(header, `${header}\n- ${trimmed}`);
+    writeFileSync(memoryPath, updated, "utf8");
+  } else {
+    appendFileSync(memoryPath, `${header}\n- ${trimmed}\n`, "utf8");
+  }
+  return `Memory saved.`;
+}