@vellumai/assistant 0.10.3-staging.2 → 0.10.4-staging.1

package/src/memory/worker-control.ts

@@ -7,25 +7,48 @@
  * so the PID-file bookkeeping lives here in one place.
  */
 
-import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
 
-import { getMemoryWorkerPidPath } from "../util/platform.js";
+import { getCurrentLogFilePath } from "../util/logger.js";
+import {
+  getMemorySyncRunnerMarkerPath,
+  getMemoryWorkerPidPath,
+} from "../util/platform.js";
 
 export interface MemoryWorkerStatus {
   status: "running" | "not_running";
   pid?: number;
 }
 
+/** True when `err` is a Node ESRCH error ("no such process"). */
+function isEsrchError(err: unknown): boolean {
+  return (
+    !!err &&
+    typeof err === "object" &&
+    "code" in err &&
+    (err as { code?: unknown }).code === "ESRCH"
+  );
+}
+
 /**
- * Inspect the PID file to determine whether the worker process is alive.
- * A stale PID file (pointing at a dead process) is cleaned up and reported
- * as not_running.
+ * Read a PID file and report liveness. A missing or malformed file reports
+ * not_running; a file pointing at a dead process is cleaned up and reported as
+ * not_running. Shared by the worker-process PID file and the sync-runner
+ * marker so both probe identically.
  */
-export function probeMemoryWorker(): MemoryWorkerStatus {
-  const pidPath = getMemoryWorkerPidPath();
-  if (!existsSync(pidPath)) return { status: "not_running" };
+function probePidFile(path: string): MemoryWorkerStatus {
+  if (!existsSync(path)) return { status: "not_running" };
 
-  const raw = readFileSync(pidPath, "utf-8").trim();
+  const raw = readFileSync(path, "utf-8").trim();
   const pid = parseInt(raw, 10);
   if (!Number.isFinite(pid) || pid <= 0) return { status: "not_running" };
 
@@ -33,15 +56,10 @@ export function probeMemoryWorker(): MemoryWorkerStatus {
     process.kill(pid, 0);
     return { status: "running", pid };
   } catch (err: unknown) {
-    if (
-      err &&
-      typeof err === "object" &&
-      "code" in err &&
-      err.code === "ESRCH"
-    ) {
-      // Stale PID file — clean it up.
+    if (isEsrchError(err)) {
+      // Stale file — clean it up.
       try {
-        unlinkSync(pidPath);
+        unlinkSync(path);
       } catch {
         // best-effort
       }
@@ -51,6 +69,53 @@ export function probeMemoryWorker(): MemoryWorkerStatus {
   }
 }
 
+/**
+ * Inspect the PID file to determine whether the worker process is alive.
+ * A stale PID file (pointing at a dead process) is cleaned up and reported
+ * as not_running.
+ */
+export function probeMemoryWorker(): MemoryWorkerStatus {
+  return probePidFile(getMemoryWorkerPidPath());
+}
+
+/**
+ * Inspect the sync-runner marker to determine whether the daemon's in-process
+ * synchronous runner is currently draining the memory-job queue. The daemon's
+ * worker supervisor writes the marker (with its own PID) only while it owns
+ * processing, so a live marker means the synchronous runner is going. A stale
+ * marker (daemon gone) is cleaned up and reported as not_running.
+ */
+export function probeSyncRunner(): MemoryWorkerStatus {
+  return probePidFile(getMemorySyncRunnerMarkerPath());
+}
+
+/**
+ * Publish the sync-runner marker recording `pid` (the daemon process). Called
+ * by the worker supervisor when its in-process synchronous runner takes over
+ * processing. Best-effort: a write failure only affects status reporting, not
+ * job processing.
+ */
+export function writeSyncRunnerMarker(pid: number): void {
+  try {
+    writeFileSync(getMemorySyncRunnerMarkerPath(), String(pid), { flag: "w" });
+  } catch {
+    // best-effort — the marker is a status hint, not a correctness invariant
+  }
+}
+
+/**
+ * Remove the sync-runner marker. Called by the worker supervisor when it stands
+ * down for an out-of-process worker, and on daemon shutdown. Best-effort.
+ */
+export function removeSyncRunnerMarker(): void {
+  try {
+    const path = getMemorySyncRunnerMarkerPath();
+    if (existsSync(path)) unlinkSync(path);
+  } catch {
+    // best-effort
+  }
+}
+
 export class MemoryWorkerSpawnError extends Error {}
 
 /**
@@ -72,13 +137,34 @@ export async function spawnMemoryWorkerProcess(): Promise<{
   const pidPath = getMemoryWorkerPidPath();
   const entry = new URL("./worker-process.ts", import.meta.url);
 
+  // Pipe the worker's stderr into the same daily log file the daemon
+  // writes to. The worker's pino logger already writes there directly,
+  // but stderr captures crash traces (uncaught exceptions that bypass
+  // the catch handler) and pino's fallback output if the file logger
+  // fails to initialize. Without this, any such output is lost to
+  // /dev/null and the worker dies silently.
+  let stderrFd: number | "inherit" = "inherit";
+  try {
+    const logPath = getCurrentLogFilePath();
+    mkdirSync(dirname(logPath), { recursive: true });
+    stderrFd = openSync(logPath, "a", 0o600);
+  } catch {
+    // If the log file can't be opened, inherit the parent's stderr so
+    // crash output is at least visible to the spawning process.
+  }
+
   // Spawn detached so the worker survives the spawning process exiting.
   const child = Bun.spawn({
     cmd: ["bun", "run", entry.pathname],
-    stdio: ["ignore", "ignore", "ignore"],
+    stdio: ["ignore", "ignore", stderrFd],
     detached: true,
   });
 
+  // Close our copy of the log fd — the child has its own.
+  if (typeof stderrFd === "number") {
+    closeSync(stderrFd);
+  }
+
   // Unreference so the spawning process doesn't wait for the child.
   child.unref();
 

package/src/memory/worker-process.ts

@@ -58,6 +58,23 @@ async function main(): Promise<void> {
   process.on("SIGTERM", () => shutdown("SIGTERM"));
   process.on("SIGINT", () => shutdown("SIGINT"));
 
+  // Catch stray exceptions that escape the worker loop so they produce a
+  // clean pino-formatted log entry (and PID-file cleanup) instead of a raw
+  // stack trace on stderr. The stderr fd is already piped to the log file
+  // by the spawner, so even without these handlers the trace would be
+  // captured — but this gives us structured logging and graceful shutdown.
+  process.on("uncaughtException", (err) => {
+    log.error({ err }, "Uncaught exception in memory worker process");
+    cleanupPidFile();
+    process.exit(1);
+  });
+
+  process.on("unhandledRejection", (reason) => {
+    log.error({ reason }, "Unhandled rejection in memory worker process");
+    cleanupPidFile();
+    process.exit(1);
+  });
+
   // Clean up if the process exits unexpectedly through any other path.
   process.on("exit", () => {
     worker.stop();

package/src/messaging/channel-binding-metadata.ts

@@ -0,0 +1,31 @@
+import type { ExternalConversationBinding } from "../memory/external-conversation-store.js";
+import type { ChannelBindingMetadata } from "./channel-binding-schema.js";
+import { buildSlackBindingMetadata } from "./providers/slack/binding-metadata.js";
+
+type BindingMetadataBuilder = (
+  binding: ExternalConversationBinding,
+) => ChannelBindingMetadata | undefined;
+
+/**
+ * Per-channel binding-metadata builders, keyed by source-channel id. A channel
+ * that can enrich a serialized conversation binding (e.g. with deep links back
+ * to the source message) registers its builder here; channels without an entry
+ * contribute nothing.
+ *
+ * Wired statically on purpose: conversation serialization runs in contexts that
+ * never boot the daemon (unit tests, CLI tooling), so this must not depend on
+ * the lifecycle-registered messaging-provider registry.
+ */
+const BINDING_METADATA_BUILDERS: Record<string, BindingMetadataBuilder> = {
+  slack: buildSlackBindingMetadata,
+};
+
+/**
+ * Channel-specific fields to merge onto a serialized channel binding, or
+ * `undefined` when the source channel contributes none.
+ */
+export function buildChannelBindingMetadata(
+  binding: ExternalConversationBinding,
+): ChannelBindingMetadata | undefined {
+  return BINDING_METADATA_BUILDERS[binding.sourceChannel]?.(binding);
+}

package/src/messaging/channel-binding-schema.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+
+const slackThreadSchema = z.object({
+  channelId: z.string(),
+  threadTs: z.string(),
+  link: z
+    .object({
+      appUrl: z.string().optional(),
+      webUrl: z.string().optional(),
+    })
+    .optional(),
+});
+
+const slackChannelSchema = z.object({
+  channelId: z.string(),
+  name: z.string().optional(),
+  link: z.object({ webUrl: z.string() }).optional(),
+});
+
+/**
+ * Wire shape of a serialized conversation channel binding — the single source
+ * of truth for this contract.
+ *
+ * Consumed as a route `responseBody` (which drives `openapi.yaml` generation
+ * and, in turn, the web client's generated daemon types), and the server-side
+ * builders derive their TypeScript types from it via `z.infer`. The shape is
+ * therefore declared exactly once.
+ */
+export const channelBindingSchema = z.object({
+  sourceChannel: z.string(),
+  externalChatId: z.string(),
+  externalChatName: z.string().optional(),
+  externalThreadId: z.string().optional(),
+  externalUserId: z.string().nullable(),
+  displayName: z.string().nullable(),
+  username: z.string().nullable(),
+  slackThread: slackThreadSchema.optional(),
+  slackChannel: slackChannelSchema.optional(),
+});
+
+type ChannelBinding = z.infer<typeof channelBindingSchema>;
+
+/**
+ * The channel-specific fields a per-channel builder contributes to a binding
+ * (everything beyond the channel-neutral base). Picked from the schema above
+ * so a builder's output can never drift from the wire contract.
+ */
+export type ChannelBindingMetadata = Pick<
+  ChannelBinding,
+  "externalChatName" | "slackThread" | "slackChannel"
+>;

package/src/messaging/providers/__tests__/callback-routing.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+
+import { channelForCallback } from "../callback-routing.js";
+
+describe("channelForCallback", () => {
+  test("resolves each direct-delivery channel from its callback URL", () => {
+    expect(channelForCallback("http://gw/deliver/slack?threadTs=1")).toBe(
+      "slack",
+    );
+    expect(channelForCallback("http://gw/deliver/telegram")).toBe("telegram");
+    expect(channelForCallback("http://gw/deliver/whatsapp")).toBe("whatsapp");
+    expect(channelForCallback("http://gw/deliver/a2a?taskId=t1")).toBe("a2a");
+  });
+
+  test("returns undefined for channels not delivered directly", () => {
+    expect(channelForCallback("http://gw/deliver/discord")).toBeUndefined();
+    expect(channelForCallback("http://gw/deliver/phone")).toBeUndefined();
+  });
+
+  test("returns undefined for non-delivery paths", () => {
+    expect(channelForCallback("http://gw/v1/messages")).toBeUndefined();
+    expect(
+      channelForCallback(
+        "http://gw/v1/internal/managed-gateway/outbound-send/?route_id=r1",
+      ),
+    ).toBeUndefined();
+  });
+
+  test("returns undefined for unparseable input", () => {
+    expect(channelForCallback("not-a-url")).toBeUndefined();
+  });
+
+  test("resolves base-less callback paths", () => {
+    expect(channelForCallback("/deliver/slack?threadTs=1")).toBe("slack");
+  });
+
+  test("resolves relative guardian-style /deliver/<channel> callbacks", () => {
+    // resolveDeliverCallbackUrlForChannel() emits these relative URLs for
+    // off-channel guardian approvals/denials and timer-driven expiry notices;
+    // they must route as direct delivery, not fall through to the HTTP proxy.
+    expect(channelForCallback("/deliver/slack")).toBe("slack");
+    expect(channelForCallback("/deliver/telegram")).toBe("telegram");
+    expect(channelForCallback("/deliver/whatsapp")).toBe("whatsapp");
+  });
+});

package/src/messaging/providers/__tests__/transport-dispatch.test.ts

@@ -0,0 +1,195 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { ChannelReplyPayload } from "@vellumai/gateway-client";
+
+// Replace each channel's provider-API send layer with spies so the dispatcher's
+// routing and sub-operation selection can be asserted without network calls.
+const slack = {
+  sendSlackReply: mock((..._args: unknown[]) =>
+    Promise.resolve({ ts: "slack-ts" }),
+  ),
+  sendSlackReaction: mock((..._args: unknown[]) => Promise.resolve()),
+  sendSlackTypingIndicator: mock((..._args: unknown[]) =>
+    Promise.resolve("typing-ts"),
+  ),
+  sendSlackAssistantThreadStatus: mock((..._args: unknown[]) =>
+    Promise.resolve(),
+  ),
+  sendSlackAttachments: mock((..._args: unknown[]) =>
+    Promise.resolve({ allFailed: false, failureCount: 0 }),
+  ),
+};
+const telegram = {
+  sendTelegramReply: mock((..._args: unknown[]) => Promise.resolve()),
+  sendTelegramTypingIndicator: mock((..._args: unknown[]) => Promise.resolve()),
+  sendTelegramAttachments: mock((..._args: unknown[]) =>
+    Promise.resolve({ allFailed: false, failureCount: 0 }),
+  ),
+};
+const whatsapp = {
+  sendWhatsAppReply: mock((..._args: unknown[]) => Promise.resolve()),
+  sendWhatsAppAttachments: mock((..._args: unknown[]) =>
+    Promise.resolve({ allFailed: false, failureCount: 0 }),
+  ),
+};
+const a2a = {
+  deliverA2AReply: mock((..._args: unknown[]) => Promise.resolve({ ok: true })),
+};
+
+mock.module("../slack/send.js", () => slack);
+mock.module("../telegram-bot/send.js", () => telegram);
+mock.module("../whatsapp/send.js", () => whatsapp);
+mock.module("../a2a/deliver.js", () => a2a);
+mock.module("../../../util/logger.js", () => ({
+  getLogger: () => ({ debug() {}, info() {}, warn() {}, error() {} }),
+}));
+
+const { deliverDirect, isDirectDelivery, getTransportForCallback } =
+  await import("../index.js");
+
+const BASE = "https://gateway.internal";
+
+function payload(
+  overrides: Partial<ChannelReplyPayload> = {},
+): ChannelReplyPayload {
+  return { chatId: "C1", ...overrides };
+}
+
+beforeEach(() => {
+  for (const group of [slack, telegram, whatsapp, a2a]) {
+    for (const spy of Object.values(group)) spy.mockClear();
+  }
+});
+
+describe("routing", () => {
+  test("resolves each channel's callback path to its transport", () => {
+    expect(
+      getTransportForCallback(`${BASE}/deliver/slack?threadTs=1`)?.channel,
+    ).toBe("slack");
+    expect(getTransportForCallback(`${BASE}/deliver/telegram`)?.channel).toBe(
+      "telegram",
+    );
+    expect(getTransportForCallback(`${BASE}/deliver/whatsapp`)?.channel).toBe(
+      "whatsapp",
+    );
+    expect(
+      getTransportForCallback(`${BASE}/deliver/a2a?taskId=t1`)?.channel,
+    ).toBe("a2a");
+  });
+
+  test("isDirectDelivery is true for owned paths, false otherwise", () => {
+    expect(isDirectDelivery(`${BASE}/deliver/slack`)).toBe(true);
+    expect(isDirectDelivery(`${BASE}/deliver/a2a?taskId=t1`)).toBe(true);
+    expect(isDirectDelivery(`${BASE}/deliver/discord`)).toBe(false);
+    expect(isDirectDelivery(`${BASE}/v1/messages`)).toBe(false);
+    expect(
+      isDirectDelivery(
+        `${BASE}/v1/internal/managed-gateway/outbound-send/?route_id=r1`,
+      ),
+    ).toBe(false);
+    expect(getTransportForCallback(`${BASE}/deliver/discord`)).toBeUndefined();
+  });
+});
+
+describe("Slack sub-operation selection", () => {
+  test("text routes to sendSlackReply, threading the callback URL's threadTs", async () => {
+    await deliverDirect(
+      `${BASE}/deliver/slack?threadTs=1700.5`,
+      payload({ text: "hi" }),
+    );
+    expect(slack.sendSlackReply).toHaveBeenCalledTimes(1);
+    const opts = slack.sendSlackReply.mock.calls[0][2] as { threadTs?: string };
+    expect(opts.threadTs).toBe("1700.5");
+    expect(slack.sendSlackReaction).not.toHaveBeenCalled();
+  });
+
+  test("threads a base-less callback URL's threadTs", async () => {
+    await deliverDirect(
+      `/deliver/slack?threadTs=1700.9`,
+      payload({ text: "hi" }),
+    );
+    expect(slack.sendSlackReply).toHaveBeenCalledTimes(1);
+    const opts = slack.sendSlackReply.mock.calls[0][2] as { threadTs?: string };
+    expect(opts.threadTs).toBe("1700.9");
+  });
+
+  test("reaction routes to sendSlackReaction, not the text path", async () => {
+    await deliverDirect(
+      `${BASE}/deliver/slack`,
+      payload({
+        reaction: {
+          action: "add",
+          name: "white_check_mark",
+          messageTs: "1700.5",
+        },
+      }),
+    );
+    expect(slack.sendSlackReaction).toHaveBeenCalledTimes(1);
+    expect(slack.sendSlackReply).not.toHaveBeenCalled();
+  });
+
+  test("assistantThreadStatus routes to sendSlackAssistantThreadStatus", async () => {
+    await deliverDirect(
+      `${BASE}/deliver/slack`,
+      payload({
+        assistantThreadStatus: {
+          channel: "C1",
+          threadTs: "1700.5",
+          status: "is thinking",
+        },
+      }),
+    );
+    expect(slack.sendSlackAssistantThreadStatus).toHaveBeenCalledTimes(1);
+    expect(slack.sendSlackReply).not.toHaveBeenCalled();
+  });
+
+  test("typing routes to sendSlackTypingIndicator", async () => {
+    await deliverDirect(
+      `${BASE}/deliver/slack`,
+      payload({ chatAction: "typing" }),
+    );
+    expect(slack.sendSlackTypingIndicator).toHaveBeenCalledTimes(1);
+    expect(slack.sendSlackReply).not.toHaveBeenCalled();
+  });
+});
+
+describe("capability gating across channels", () => {
+  test("a reaction payload to Telegram falls through to deliver (no sendReaction)", async () => {
+    await deliverDirect(
+      `${BASE}/deliver/telegram`,
+      payload({
+        text: "hi",
+        reaction: { action: "add", name: "x", messageTs: "1" },
+      }),
+    );
+    expect(telegram.sendTelegramReply).toHaveBeenCalledTimes(1);
+  });
+
+  test("typing to Telegram routes to its typing indicator", async () => {
+    await deliverDirect(
+      `${BASE}/deliver/telegram`,
+      payload({ chatAction: "typing" }),
+    );
+    expect(telegram.sendTelegramTypingIndicator).toHaveBeenCalledTimes(1);
+  });
+
+  test("WhatsApp text routes to sendWhatsAppReply", async () => {
+    await deliverDirect(`${BASE}/deliver/whatsapp`, payload({ text: "hi" }));
+    expect(whatsapp.sendWhatsAppReply).toHaveBeenCalledTimes(1);
+  });
+
+  test("A2A routes to deliverA2AReply with the callback URL", async () => {
+    const url = `${BASE}/deliver/a2a?taskId=t1`;
+    await deliverDirect(url, payload({ text: "hi" }));
+    expect(a2a.deliverA2AReply).toHaveBeenCalledTimes(1);
+    expect(a2a.deliverA2AReply.mock.calls[0][0]).toBe(url);
+  });
+});
+
+describe("unsupported callback", () => {
+  test("throws when no transport owns the callback", async () => {
+    await expect(
+      deliverDirect(`${BASE}/deliver/discord`, payload({ text: "hi" })),
+    ).rejects.toThrow(/unsupported callback/);
+  });
+});

package/src/messaging/providers/a2a/__tests__/deliver.test.ts

@@ -167,6 +167,17 @@ describe("deliverA2AReply", () => {
     expect(completeWithArtifactsCalls).toHaveLength(0);
   });
 
+  test("completes task for a base-less (relative) callback URL", async () => {
+    const result = await deliverA2AReply("/deliver/a2a?taskId=task-123", {
+      chatId: "chat-1",
+      text: "Hello",
+    });
+
+    expect(result.ok).toBe(true);
+    expect(completeWithArtifactsCalls).toHaveLength(1);
+    expect(completeWithArtifactsCalls[0].taskId).toBe("task-123");
+  });
+
   test("returns ok: true when payload has no content", async () => {
     const result = await deliverA2AReply(baseCallbackUrl, {
       chatId: "chat-1",

package/src/messaging/providers/a2a/deliver.ts

@@ -36,7 +36,11 @@ const PUSH_TIMEOUT_MS = 15_000;
 /** Extract the `taskId` query parameter from a callback URL. */
 function parseTaskId(callbackUrl: string): string | null {
   try {
-    return new URL(callbackUrl).searchParams.get("taskId");
+    // Dummy base so base-less callbacks (e.g. `/deliver/a2a?taskId=…`) parse the
+    // same as absolute ones — consistent with `callbackContext` in the dispatcher.
+    return new URL(callbackUrl, "http://callback.invalid").searchParams.get(
+      "taskId",
+    );
   } catch {
     return null;
   }

package/src/messaging/providers/a2a/transport.ts

@@ -0,0 +1,10 @@
+import type { ChannelTransport } from "../channel-transport.js";
+import { deliverA2AReply } from "./deliver.js";
+
+export const a2aTransport: ChannelTransport = {
+  channel: "a2a",
+
+  async deliver(ctx, payload) {
+    return deliverA2AReply(ctx.callbackUrl, payload);
+  },
+};

package/src/messaging/providers/callback-routing.ts

@@ -0,0 +1,48 @@
+import type { ChannelId } from "../../channels/types.js";
+
+/**
+ * Channels whose outbound replies the assistant delivers directly to the
+ * provider API, bypassing the gateway HTTP proxy. Each is reached at the gateway
+ * callback path `/deliver/<channel>`.
+ *
+ * This is the single source of truth for that set and that mapping — shared by
+ * the delivery transports (`messaging/providers`) and any caller that needs to
+ * resolve a callback URL back to its channel WITHOUT loading the transport
+ * implementations (and their provider-API send code). Keep it dependency-light.
+ */
+const DIRECT_DELIVERY_CHANNELS = [
+  "slack",
+  "telegram",
+  "whatsapp",
+  "a2a",
+] as const satisfies readonly ChannelId[];
+
+export type DirectDeliveryChannel = (typeof DIRECT_DELIVERY_CHANNELS)[number];
+
+const CALLBACK_PREFIX = "/deliver/";
+
+/**
+ * Resolve a gateway callback URL to the direct-delivery channel that owns it, or
+ * `undefined` when no channel delivers it directly.
+ *
+ * Handles both absolute callbacks (gateway webhook replies) and base-less
+ * relative ones like `/deliver/slack`, which off-channel guardian flows emit
+ * (`resolveDeliverCallbackUrlForChannel`, the guardian expiry sweep). The
+ * query-stripped fallback is required, not defensive: without it those relative
+ * notices fall through to the HTTP proxy, which cannot `fetch()` a base-less URL.
+ */
+export function channelForCallback(
+  callbackUrl: string,
+): DirectDeliveryChannel | undefined {
+  let pathname: string;
+  try {
+    pathname = new URL(callbackUrl).pathname;
+  } catch {
+    pathname = callbackUrl.split("?", 1)[0];
+  }
+  if (!pathname.startsWith(CALLBACK_PREFIX)) return undefined;
+  const channel = pathname.slice(CALLBACK_PREFIX.length);
+  return (DIRECT_DELIVERY_CHANNELS as readonly string[]).includes(channel)
+    ? (channel as DirectDeliveryChannel)
+    : undefined;
+}

package/src/messaging/providers/channel-transport.ts

@@ -0,0 +1,55 @@
+import type {
+  ChannelDeliveryResult,
+  ChannelReplyPayload,
+} from "@vellumai/gateway-client";
+
+import type { ChannelId } from "../../channels/types.js";
+
+/**
+ * Per-channel state carried on the gateway callback URL (e.g. Slack `threadTs`,
+ * A2A `taskId`). The dispatcher parses the URL once; each transport reads only
+ * the params it needs.
+ */
+export interface CallbackContext {
+  readonly callbackUrl: string;
+  readonly params: Readonly<Record<string, string>>;
+}
+
+/**
+ * Direct outbound delivery for one channel, wrapping the channel's provider-API
+ * send functions behind a uniform surface. Transports are registered statically
+ * (delivery runs in non-daemon contexts) and dispatched by channel, resolved
+ * from the gateway callback URL via `callback-routing.ts`.
+ *
+ * The dispatcher routes a payload to the optional sub-operation methods when the
+ * matching payload field is set and the method exists; otherwise it calls
+ * `deliver`. A transport only implements the sub-operations it supports.
+ */
+export interface ChannelTransport {
+  /** Canonical source channel id, e.g. `"slack"`. */
+  readonly channel: ChannelId;
+
+  /** Deliver a rendered reply (text / approval / attachments). */
+  deliver(
+    ctx: CallbackContext,
+    payload: ChannelReplyPayload,
+  ): Promise<ChannelDeliveryResult>;
+
+  /** Send a typing indicator. Routed when `payload.chatAction === "typing"`. */
+  sendTyping?(
+    ctx: CallbackContext,
+    payload: ChannelReplyPayload,
+  ): Promise<ChannelDeliveryResult>;
+
+  /** Add an emoji reaction. Routed when `payload.reaction` is set. */
+  sendReaction?(
+    ctx: CallbackContext,
+    payload: ChannelReplyPayload,
+  ): Promise<ChannelDeliveryResult>;
+
+  /** Update an assistant-thread status surface. Routed when `payload.assistantThreadStatus` is set. */
+  setThreadStatus?(
+    ctx: CallbackContext,
+    payload: ChannelReplyPayload,
+  ): Promise<ChannelDeliveryResult>;
+}