Enrich per-call and per-turn context; add burst batching and channel overrides

- Voice: full per-call system instructions (own identity block, caller's
  contact card incl. notes, known/unknown-caller directives, outbound
  purpose/opening guidance, consult-tool capability list, post-call action
  and two-step hangup choreography, third-party privacy rule) plus a
  direction-aware greeting instruction; call parties resolve before the
  mode is chosen; voice frames and post-call prompts carry call_id.
- Reactions: name the target message and frame tapbacks with
  reply-restraint guidance ending in the [SILENT] escape.
- Burst batching: opt-in quiet-window merging of rapid SMS/iMessage
  fragments into one tagged turn (gateway.textBatchWindowMs /
  INKBOX_TEXT_BATCH_WINDOW_MS; caps on count and size; commands bypass).
- Frames: group participants list, RFC Message-ID on email tags for reply
  threading, contact notes on the resolver (voice-only injection).
- Channel overrides: gateway.channelPrompts (per-turn operator directive)
  and gateway.channelAgents (opencode agent override), keyed by contact id
  or channel.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: alex-w-99

src/config.ts

@@ -73,6 +73,15 @@ export interface GatewayOptions {
   agent?: string;
   // Optional model override for gateway sessions, "provider/model".
   model?: string;
+  // Batch rapid-fire SMS/iMessage fragments arriving within this quiet
+  // window (ms) into one merged turn. 0 (default) disables batching.
+  textBatchWindowMs?: number;
+  // Extra per-turn directive text, keyed by contact id or channel name
+  // (contact id wins). Injected under the frame tag on matching turns.
+  channelPrompts?: Record<string, string>;
+  // opencode agent override keyed by contact id or channel name (contact id
+  // wins); falls back to the gateway-wide agent.
+  channelAgents?: Record<string, string>;
   voice?: {
     enabled?: boolean;
     realtime?: {
@@ -104,6 +113,9 @@ export interface ResolvedGatewayConfig {
   mediaDir?: string;
   agent?: string;
   model?: string;
+  textBatchWindowMs: number;
+  channelPrompts: Record<string, string>;
+  channelAgents: Record<string, string>;
   voice: {
     enabled: boolean;
     realtime: {
@@ -157,6 +169,18 @@ function stringArray(value: unknown): string[] {
     .filter((entry): entry is string => Boolean(entry));
 }
 
+// Keep only entries whose key and value are both non-empty strings.
+function stringRecord(value: unknown): Record<string, string> {
+  if (!isRecord(value)) return {};
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(value)) {
+    const key = nonEmptyString(k);
+    const val = nonEmptyString(v);
+    if (key && val) out[key] = val;
+  }
+  return out;
+}
+
 // ~/.inkbox/config — `key = value` lines, the same file the Inkbox SDK and CLI
 // read. Lowest-precedence credential source, after options and env vars.
 function readInkboxConfigFile(): Record<string, string> {
@@ -313,6 +337,10 @@ function resolveGatewayConfig(
     mediaDir: nonEmptyString(opts.mediaDir) ?? nonEmptyString(env.INKBOX_OPENCODE_MEDIA_DIR),
     agent: nonEmptyString(opts.agent),
     model: nonEmptyString(opts.model),
+    textBatchWindowMs:
+      numeric(opts.textBatchWindowMs) ?? numeric(env.INKBOX_TEXT_BATCH_WINDOW_MS) ?? 0,
+    channelPrompts: stringRecord(opts.channelPrompts),
+    channelAgents: stringRecord(opts.channelAgents),
     voice: {
       enabled: voice.enabled ?? boolEnv(env.INKBOX_VOICE_ENABLED) ?? false,
       realtime: {

src/gateway/burst.ts

@@ -0,0 +1,81 @@
+import type { InboundMessage } from "./types.js";
+
+// Humans text in fragments and corrections. Batching fragments that arrive
+// within a quiet window into one merged turn keeps a single thought from
+// becoming several self-interrupting agent turns.
+export const DEFAULT_BURST_MAX_MESSAGES = 8;
+export const DEFAULT_BURST_MAX_CHARS = 4000;
+
+export interface BurstBuffer {
+  // Queue a message for its chat's pending batch (starting one if needed).
+  add(msg: InboundMessage): void;
+  // Flush every pending batch immediately (shutdown).
+  flushAll(): void;
+}
+
+interface Pending {
+  msgs: InboundMessage[];
+  chars: number;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export function createBurstBuffer(opts: {
+  windowMs: number;
+  maxMessages?: number;
+  maxChars?: number;
+  deliver(msg: InboundMessage): void;
+}): BurstBuffer {
+  const maxMessages = opts.maxMessages ?? DEFAULT_BURST_MAX_MESSAGES;
+  const maxChars = opts.maxChars ?? DEFAULT_BURST_MAX_CHARS;
+  const pending = new Map<string, Pending>();
+
+  function flush(chatKey: string): void {
+    const batch = pending.get(chatKey);
+    if (!batch) return;
+    pending.delete(chatKey);
+    clearTimeout(batch.timer);
+    opts.deliver(mergeBurst(batch.msgs));
+  }
+
+  return {
+    add(msg) {
+      const existing = pending.get(msg.chatKey);
+      if (!existing) {
+        const timer = setTimeout(() => flush(msg.chatKey), opts.windowMs);
+        timer.unref?.();
+        pending.set(msg.chatKey, { msgs: [msg], chars: msg.text.length, timer });
+        return;
+      }
+      existing.msgs.push(msg);
+      existing.chars += msg.text.length;
+      // Sliding quiet window: each fragment restarts the countdown.
+      clearTimeout(existing.timer);
+      if (existing.msgs.length >= maxMessages || existing.chars >= maxChars) {
+        flush(msg.chatKey);
+        return;
+      }
+      existing.timer = setTimeout(() => flush(msg.chatKey), opts.windowMs);
+      existing.timer.unref?.();
+    },
+
+    flushAll() {
+      for (const chatKey of [...pending.keys()]) flush(chatKey);
+    },
+  };
+}
+
+// Collapse a batch into one message: newest metadata (ids, threading), all
+// fragment texts in arrival order, and every attachment.
+export function mergeBurst(msgs: InboundMessage[]): InboundMessage {
+  if (msgs.length === 1) return msgs[0];
+  const last = msgs[msgs.length - 1];
+  return {
+    ...last,
+    text: msgs
+      .map((m) => m.text)
+      .filter((t) => t.trim() !== "")
+      .join("\n"),
+    mediaPaths: msgs.flatMap((m) => m.mediaPaths),
+    burst: msgs.length,
+  };
+}

src/gateway/contacts.ts

@@ -10,6 +10,9 @@ export interface ResolvedContact {
   contactCompany?: string;
   contactEmails?: string[];
   contactPhones?: string[];
+  // Free-form notes from the contact record. Injected into voice-call
+  // instructions only — never into per-message frame tags (can be long).
+  contactNotes?: string;
 }
 
 // One-line contact card for [inkbox:...] frame tags: the addresses the agent
@@ -80,12 +83,14 @@ export function createContactResolver(
       const company = contact.companyName?.trim();
       const emails = (contact.emails ?? []).map((e) => e.value).filter(Boolean);
       const phones = (contact.phones ?? []).map((p) => p.value).filter(Boolean);
+      const notes = contact.notes?.trim();
       return {
         contactId: contact.id,
         ...(name ? { contactName: name } : {}),
         ...(company ? { contactCompany: company } : {}),
         ...(emails.length ? { contactEmails: emails } : {}),
         ...(phones.length ? { contactPhones: phones } : {}),
+        ...(notes ? { contactNotes: notes } : {}),
       };
     } catch (error) {
       // Resolution must never drop a message: warn and fall through to the

src/gateway/dispatch.ts

@@ -1,8 +1,10 @@
 import type { InkboxRuntime } from "../client.js";
 import type { ResolvedConfig, ResolvedGatewayConfig } from "../config.js";
+import type { BurstBuffer } from "./burst.js";
 import type { ContactResolver } from "./contacts.js";
 import type { NotifyOnce } from "./dedup.js";
 import { downloadMedia, mediaDir } from "./media.js";
+import { SILENT } from "./prompts.js";
 import type {
   Channel,
   GatewayLogger,
@@ -30,6 +32,9 @@ export interface DispatchDeps {
   sessions: SessionManager;
   notify: NotifyOnce;
   logger: GatewayLogger;
+  // When set, rapid-fire SMS/iMessage fragments are batched per chat into
+  // one merged turn instead of dispatched individually.
+  bursts?: BurstBuffer;
   // Handle a verified non-Inkbox (external) webhook.
   onExternal?(event: VerifiedEvent): Promise<void>;
 }
@@ -227,7 +232,9 @@ async function handleInbound(
     ...resolved,
     text: info.text,
     mediaPaths,
-    ...(participants > 1 ? { group: { participantCount: participants } } : {}),
+    ...(participants > 1
+      ? { group: { participantCount: participants, participants: participantNames(event.body) } }
+      : {}),
   };
 
   // A media-only message still wakes the agent.
@@ -236,6 +243,13 @@ async function handleInbound(
     return true;
   }
 
+  // Batch phone-channel fragments when enabled; slash commands bypass the
+  // window so control replies stay immediate.
+  if (deps.bursts && channel !== "email" && !msg.text.trim().startsWith("/")) {
+    deps.bursts.add(msg);
+    return true;
+  }
+
   // Kick off the turn without blocking the webhook response — a model run can
   // take minutes, and holding the HTTP request open makes the provider retry.
   void deps.sessions
@@ -253,11 +267,28 @@ function countParticipants(body: Record<string, unknown>): number {
   return Math.max(contacts, identities);
 }
 
+// Names of the resolved remote parties on the event, for the group frame tag.
+function participantNames(body: Record<string, unknown>): string[] {
+  const data = record(body.data);
+  const names: string[] = [];
+  for (const c of Array.isArray(data?.contacts) ? data.contacts : []) {
+    const n = str(record(c)?.name);
+    if (n) names.push(n);
+  }
+  for (const a of Array.isArray(data?.agent_identities) ? data.agent_identities : []) {
+    const rec = record(a);
+    const n = str(rec?.display_name) ?? str(rec?.agent_handle);
+    if (n) names.push(n);
+  }
+  return names;
+}
+
 async function handleReaction(deps: DispatchDeps, event: VerifiedEvent): Promise<boolean> {
   const r = resourceOf(event.body, "reaction");
   const from = str(r?.remote_number);
   const conversationId = str(r?.conversation_id);
-  const reaction = str(r?.reaction) ?? "reaction";
+  const reaction = str(r?.custom_emoji) ?? str(r?.reaction) ?? "reaction";
+  const targetMessageId = str(r?.target_message_id);
   if (!from) return true;
   const resolved = await deps.contacts.resolve(from);
   if (!senderAllowed(from, resolved.contactId, deps.config.gateway)) return true;
@@ -267,14 +298,24 @@ async function handleReaction(deps: DispatchDeps, event: VerifiedEvent): Promise
     conversationId,
     from,
   });
+  // Reactions carry reply-restraint guidance: a tapback is a lightweight
+  // signal, and most warrant no visible reply at all.
+  const who = resolved.contactName ?? from;
+  const text = [
+    `[reaction: ${reaction}${targetMessageId ? ` target_message_id=${targetMessageId}` : ""}]`,
+    `${who} reacted with a '${reaction}' tapback to your message.`,
+    "A reaction is a lightweight signal, not always a request for a reply — a 'question' " +
+      "tapback usually wants a follow-up; 'love', 'like', 'laugh', or 'dislike' are usually " +
+      `just acknowledgement. If no reply is warranted, reply with exactly ${SILENT}.`,
+  ].join("\n");
   void deps.sessions
     .handleInbound({
       channel: "imessage",
       chatKey,
       from,
       conversationId,
       ...resolved,
-      text: `[reaction: ${reaction}]`,
+      text,
       mediaPaths: [],
       messageId: str(r?.id),
     })

src/gateway/index.ts

@@ -1,6 +1,7 @@
 import type { OpencodeClient } from "@opencode-ai/sdk";
 import type { InkboxRuntime } from "../client.js";
 import type { ResolvedConfig } from "../config.js";
+import { createBurstBuffer } from "./burst.js";
 import { handleCommand } from "./commands.js";
 import { createContactResolver } from "./contacts.js";
 import { createNotifyOnce, createRequestDedup } from "./dedup.js";
@@ -147,6 +148,19 @@ export async function startGateway(opts: StartGatewayOptions): Promise<GatewayHa
 
   const events = subscribeEvents(opts.opencode, escalation, logger, opts.directory);
 
+  // Fragment batching for phone channels, when a quiet window is configured.
+  const bursts =
+    g.textBatchWindowMs > 0
+      ? createBurstBuffer({
+          windowMs: g.textBatchWindowMs,
+          deliver: (msg) => {
+            void wrapSessions()
+              .handleInbound(msg)
+              .catch((err) => logger.error("turn.dispatch_failed", { error: String(err) }));
+          },
+        })
+      : undefined;
+
   async function onEvent(event: VerifiedEvent): Promise<boolean | undefined> {
     return dispatchEvent(
       {
@@ -156,6 +170,7 @@ export async function startGateway(opts: StartGatewayOptions): Promise<GatewayHa
         sessions: wrapSessions(),
         notify,
         logger,
+        bursts,
         onExternal: g.externalEvents ? handleExternal : undefined,
       },
       event,
@@ -245,6 +260,7 @@ export async function startGateway(opts: StartGatewayOptions): Promise<GatewayHa
     publicUrl: transport.publicUrl,
     async close() {
       events.close();
+      bursts?.flushAll();
       await sessions.close();
       await server.close();
       await transport.close();

src/gateway/prompts.ts

@@ -126,18 +126,30 @@ function groupReminder(participantCount: number): string {
 // Prefix an inbound message with a one-line routing tag — the per-turn
 // context the static system prompt can't carry: which channel this message
 // arrived on and who sent it. Quoted fields may contain spaces.
-export function frameInbound(msg: InboundMessage): string {
-  const fields = [`inkbox:${msg.channel}`, `from=${msg.from}`];
+export function frameInbound(msg: InboundMessage, directive?: string): string {
+  // Merged fragment bursts are tagged as such, with the fragment count.
+  const burst = (msg.burst ?? 1) > 1;
+  const fields = [
+    burst ? `inkbox:${msg.channel}_burst messages=${msg.burst}` : `inkbox:${msg.channel}`,
+    `from=${msg.from}`,
+  ];
   if (msg.channel === "email") {
     if (msg.subject) fields.push(`subject=${JSON.stringify(msg.subject)}`);
+    // RFC 5322 Message-ID, so the agent can thread its own follow-up sends
+    // via inkbox_send_email's inReplyToMessageId.
+    if (msg.rfcMessageId) fields.push(`message_id=${JSON.stringify(msg.rfcMessageId)}`);
   } else if (msg.conversationId) {
     fields.push(`conversation_id=${msg.conversationId}`);
   }
+  if (msg.group?.participants?.length) {
+    fields.push(`participants=${JSON.stringify(msg.group.participants.join(", "))}`);
+  }
   // The contact card carries the addresses the agent may reach this person
   // at, so cross-channel follow-ups never have to guess.
   fields.push("|", contactCard(msg));
 
   const lines = [`[${fields.join(" ")}]`];
+  if (directive) lines.push(`Operator directive for this channel: ${directive}`);
   if (msg.group) lines.push(groupReminder(msg.group.participantCount));
   lines.push(msg.text);
   if (msg.mediaPaths.length > 0) lines.push(`[attached files: ${msg.mediaPaths.join(", ")}]`);

src/gateway/sessions.ts

@@ -16,6 +16,8 @@ interface QueuedTurn {
   kind: TurnKind;
   text: string;
   deliver: boolean;
+  // Per-contact/per-channel opencode agent override for this turn.
+  agent?: string;
   replyTarget?: ReplyTarget;
   // True for a follow-up turn enqueued after a delivery failure, so a second
   // failure doesn't spawn another recovery (bounded to one attempt).
@@ -78,13 +80,18 @@ export function createSessionManager(deps: SessionManagerDeps): SessionManager {
     return id;
   }
 
-  async function runPrompt(sessionID: string, text: string): Promise<string | undefined> {
+  async function runPrompt(
+    sessionID: string,
+    text: string,
+    agentOverride?: string,
+  ): Promise<string | undefined> {
     const g = deps.config.gateway;
+    const agent = agentOverride ?? g.agent;
     const res = await deps.opencode.session.prompt({
       path: { id: sessionID },
       query: { directory: deps.directory },
       body: {
-        ...(g.agent ? { agent: g.agent } : {}),
+        ...(agent ? { agent } : {}),
         ...(g.model?.includes("/")
           ? {
               model: {
@@ -113,7 +120,7 @@ export function createSessionManager(deps: SessionManagerDeps): SessionManager {
         if (turn.kind === "normal") entry.interruptNormal = false;
         try {
           const sessionID = await ensureSession(chatKey);
-          const out = await runPrompt(sessionID, turn.text);
+          const out = await runPrompt(sessionID, turn.text, turn.agent);
           // If a newer message interrupted this normal turn, drop its output.
           if (turn.kind === "normal" && entry.interruptNormal) {
             deps.logger.info("turn.interrupted", { chatKey });
@@ -187,11 +194,16 @@ export function createSessionManager(deps: SessionManagerDeps): SessionManager {
         const sessionID = deps.state.getSession(msg.chatKey);
         if (sessionID) await interruptInFlightNormal(msg.chatKey, sessionID);
       }
+      // Operator overrides, keyed by contact id first, then channel.
+      const g = deps.config.gateway;
+      const overrideFor = (map: Record<string, string>): string | undefined =>
+        (msg.contactId ? map[msg.contactId] : undefined) ?? map[msg.channel];
       await new Promise<string | undefined>((resolve, reject) => {
         entry.queue.push({
           kind: "normal",
-          text: frameInbound(msg),
+          text: frameInbound(msg, overrideFor(g.channelPrompts)),
           deliver: true,
+          agent: overrideFor(g.channelAgents),
           replyTarget,
           resolve,
           reject,