@voicelayer/sdk 0.1.11 → 0.3.0

package/dist/brain/index.js

@@ -0,0 +1,3550 @@
+import { randomUUID } from 'crypto';
+import { promises } from 'dns';
+import { isIP } from 'net';
+import { z } from 'zod';
+import IORedis from 'ioredis';
+
+// src/brain/serialize.ts
+function normalizeRole(role) {
+  switch (role) {
+    case "system":
+    case "developer":
+      return "system";
+    case "user":
+      return "user";
+    case "assistant":
+      return "assistant";
+    default:
+      return null;
+  }
+}
+function extractText(m) {
+  if (typeof m.textContent === "string") return m.textContent;
+  if (typeof m.content === "string") return m.content;
+  if (Array.isArray(m.content)) {
+    const parts = m.content.filter((c) => typeof c === "string");
+    if (parts.length > 0) return parts.join("\n");
+  }
+  return null;
+}
+function chatContextToMessages(chatCtx) {
+  const items = chatCtx?.items;
+  if (!Array.isArray(items)) return [];
+  const out = [];
+  for (const item of items) {
+    const m = item;
+    if (m == null || typeof m !== "object") continue;
+    if (m.type !== void 0 && m.type !== "message") continue;
+    const role = normalizeRole(m.role);
+    if (role === null) continue;
+    const content = extractText(m);
+    if (content === null) continue;
+    out.push({ role, content });
+  }
+  return out;
+}
+function lastUserText(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m && m.role === "user") return m.content;
+  }
+  return "";
+}
+
+// src/brain/transport-callback.ts
+function callbackTransport(onQuery) {
+  async function* stream(req, signal) {
+    const text = lastUserText(req.messages);
+    const result = await onQuery(text, { messages: req.messages, signal });
+    if (typeof result === "string") {
+      if (result.length > 0) yield { content: result };
+      return;
+    }
+    for await (const piece of result) {
+      if (signal.aborted) return;
+      if (piece.length > 0) yield { content: piece };
+    }
+  }
+  async function complete(req, signal) {
+    let acc = "";
+    for await (const chunk of stream(req, signal)) {
+      acc += chunk.content ?? "";
+    }
+    return acc;
+  }
+  return { kind: "callback", stream, complete };
+}
+
+// src/brain/connector-llm.ts
+function buildMetadata(options) {
+  return {
+    channel: "voice",
+    ...options.callId ? { callId: options.callId } : {},
+    ...options.projectId ? { projectId: options.projectId } : {}
+  };
+}
+async function* chatChunkStream(transport, messages, options, signal) {
+  let index = 0;
+  let yielded = false;
+  try {
+    const upstream = transport.stream(
+      {
+        messages,
+        ...options.model ? { model: options.model } : {},
+        ...options.temperature !== void 0 ? { temperature: options.temperature } : {},
+        metadata: buildMetadata(options)
+      },
+      signal
+    );
+    for await (const chunk of upstream) {
+      if (signal.aborted) return;
+      const content = chunk.content;
+      if (content) {
+        yielded = true;
+        yield { id: `vlc_${index++}`, delta: { role: "assistant", content } };
+      }
+    }
+  } catch (err) {
+    if (!yielded && options.fallbackText) {
+      yield { id: `vlc_${index++}`, delta: { role: "assistant", content: options.fallbackText } };
+      return;
+    }
+    if (!yielded) throw err;
+  }
+}
+async function createConnectorLLM(transport, options = {}) {
+  const lk = await import('@livekit/agents');
+  const Base = lk.llm?.LLM;
+  if (!Base) {
+    throw new Error(
+      "@livekit/agents does not export llm.LLM; cannot build ConnectorLLM. Check your @livekit/agents version."
+    );
+  }
+  class ConnectorLLM extends Base {
+    label() {
+      return "voicelayer.ConnectorLLM";
+    }
+    // LK calls chat({chatCtx,...}) and iterates the result, calling close() on
+    // barge-in. We return a plain async-iterable + close(), matching NoOpLLM.
+    chat(args = {}) {
+      const messages = chatContextToMessages(args.chatCtx);
+      const ac = new AbortController();
+      return {
+        [Symbol.asyncIterator]() {
+          return chatChunkStream(transport, messages, options, ac.signal);
+        },
+        async close() {
+          ac.abort();
+        }
+      };
+    }
+  }
+  return new ConnectorLLM();
+}
+
+// src/brain/connector-chat-model.ts
+var ConnectorChatModel = class {
+  constructor(transport, options = {}) {
+    this.transport = transport;
+    this.options = options;
+  }
+  transport;
+  options;
+  /** `signal` cancels the brain request (the tunnel sends `brain.cancel`); a deadline is the caller's to set. */
+  async complete(input, signal) {
+    const ac = new AbortController();
+    if (signal) {
+      if (signal.aborted) ac.abort(signal.reason);
+      else signal.addEventListener("abort", () => ac.abort(signal.reason), { once: true });
+    }
+    const messages = input.messages.map((m) => ({
+      role: m.role,
+      content: m.content
+    }));
+    const model = input.model ?? this.options.model;
+    return this.transport.complete(
+      {
+        messages,
+        ...model ? { model } : {},
+        ...input.temperature !== void 0 ? { temperature: input.temperature } : {},
+        metadata: { channel: "text" }
+      },
+      ac.signal
+    );
+  }
+};
+
+// src/brain/openai-sse.ts
+async function* toAsyncIterable(source) {
+  if (Symbol.asyncIterator in Object(source)) {
+    yield* source;
+    return;
+  }
+  const reader = source.getReader();
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) yield value;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+async function* parseChatCompletionSse(source) {
+  const decoder = new TextDecoder();
+  let buf = "";
+  for await (const chunk of toAsyncIterable(source)) {
+    buf += decoder.decode(chunk, { stream: true });
+    let sep;
+    while ((sep = buf.indexOf("\n\n")) >= 0) {
+      const event = buf.slice(0, sep);
+      buf = buf.slice(sep + 2);
+      for (const line of event.split("\n")) {
+        const trimmed = line.replace(/\r$/, "").trimStart();
+        if (!trimmed.startsWith("data:")) continue;
+        const data = trimmed.slice(5).trim();
+        if (data === "[DONE]") return;
+        if (data.length === 0) continue;
+        let json;
+        try {
+          json = JSON.parse(data);
+        } catch {
+          continue;
+        }
+        const choice = json.choices?.[0];
+        if (!choice) continue;
+        const rawContent = choice.delta?.content;
+        const content = typeof rawContent === "string" ? rawContent : void 0;
+        const finishReason = typeof choice.finish_reason === "string" ? choice.finish_reason : void 0;
+        if (content !== void 0 || finishReason !== void 0) {
+          yield {
+            ...content !== void 0 ? { content } : {},
+            ...finishReason !== void 0 ? { finishReason } : {}
+          };
+        }
+      }
+    }
+  }
+}
+
+// src/brain/daemon-core.ts
+function errMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+async function* runBrainRequest(req, cfg, signal) {
+  const doFetch = cfg.fetchImpl ?? fetch;
+  const url = `${cfg.brainUrl.replace(/\/+$/, "")}/chat/completions`;
+  const body = JSON.stringify({
+    model: req.model ?? cfg.defaultModel ?? "gpt-4o-mini",
+    messages: req.messages.map((m) => ({ role: m.role, content: m.content })),
+    stream: true,
+    ...req.temperature !== void 0 ? { temperature: req.temperature } : {}
+  });
+  let res;
+  try {
+    res = await doFetch(url, {
+      method: "POST",
+      signal,
+      ...cfg.refuseRedirects ? { redirect: "error" } : {},
+      headers: {
+        "content-type": "application/json",
+        ...cfg.apiKey ? { authorization: `Bearer ${cfg.apiKey}` } : {}
+      },
+      body
+    });
+  } catch (err) {
+    yield { kind: "brain.error", streamId: req.streamId, code: "unreachable", message: errMessage(err) };
+    return;
+  }
+  if (!res.ok) {
+    yield {
+      kind: "brain.error",
+      streamId: req.streamId,
+      code: "upstream_error",
+      message: `HTTP ${res.status}`
+    };
+    return;
+  }
+  if (!res.body) {
+    yield { kind: "brain.error", streamId: req.streamId, code: "bad_response", message: "empty body" };
+    return;
+  }
+  try {
+    for await (const delta of parseChatCompletionSse(res.body)) {
+      if (signal.aborted) return;
+      if (delta.content) {
+        yield { kind: "brain.delta", streamId: req.streamId, content: delta.content };
+      }
+    }
+    yield { kind: "brain.done", streamId: req.streamId, finishReason: "stop" };
+  } catch (err) {
+    if (signal.aborted) return;
+    yield { kind: "brain.error", streamId: req.streamId, code: "bad_response", message: errMessage(err) };
+  }
+}
+var BrainConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BrainConfigError";
+  }
+};
+function ipv4Parts(ip) {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(ip);
+  if (!m) return null;
+  const parts = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+  if (parts.some((n) => n > 255)) return null;
+  return parts;
+}
+function isDisallowedV4(ip) {
+  const p = ipv4Parts(ip);
+  if (!p) return false;
+  const [a, b] = p;
+  if (a === 0) return true;
+  if (a === 10) return true;
+  if (a === 127) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  return false;
+}
+function isDisallowedIp(ip) {
+  const raw = ip.startsWith("[") && ip.endsWith("]") ? ip.slice(1, -1) : ip;
+  const kind = isIP(raw);
+  if (kind === 4) return isDisallowedV4(raw);
+  if (kind === 6) {
+    const lower = raw.toLowerCase();
+    if (lower === "::1" || lower === "::") return true;
+    if (lower.startsWith("fe80")) return true;
+    if (lower.startsWith("fc") || lower.startsWith("fd")) return true;
+    const embedded = /^::(?:ffff:)?(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(lower);
+    if (embedded?.[1]) return isDisallowedV4(embedded[1]);
+    const hex = /^::(?:ffff:)?([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(lower);
+    if (hex?.[1] && hex[2]) {
+      const hi = parseInt(hex[1], 16);
+      const lo = parseInt(hex[2], 16);
+      return isDisallowedV4(`${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`);
+    }
+    return false;
+  }
+  return false;
+}
+async function assertPublicHttpsUrl(raw, opts = {}) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new BrainConfigError(`brain URL is not a valid URL: ${raw}`);
+  }
+  if (url.protocol !== "https:") {
+    throw new BrainConfigError(`brain URL must use https:// (got "${url.protocol}//")`);
+  }
+  const host = url.hostname;
+  const bare = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+  if (opts.allowHosts?.includes(host) || opts.allowHosts?.includes(bare)) {
+    return url;
+  }
+  if (isIP(bare)) {
+    if (isDisallowedIp(bare)) {
+      throw new BrainConfigError(`brain URL host is a disallowed address: ${bare}`);
+    }
+    return url;
+  }
+  const lowerHost = bare.toLowerCase();
+  if (lowerHost === "localhost" || lowerHost.endsWith(".localhost")) {
+    throw new BrainConfigError(`brain URL host "${bare}" is not allowed`);
+  }
+  const lookup = opts.lookup ?? (async (h) => (await promises.lookup(h, { all: true })).map((a) => a.address));
+  let addresses;
+  try {
+    addresses = await lookup(bare);
+  } catch {
+    throw new BrainConfigError(`brain URL host could not be resolved: ${bare}`);
+  }
+  if (addresses.length === 0) {
+    throw new BrainConfigError(`brain URL host did not resolve to any address: ${bare}`);
+  }
+  for (const addr of addresses) {
+    if (isDisallowedIp(addr)) {
+      throw new BrainConfigError(
+        `brain URL host "${bare}" resolves to a disallowed address: ${addr}`
+      );
+    }
+  }
+  return url;
+}
+
+// src/brain/errors.ts
+var BrainRequestError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "BrainRequestError";
+  }
+  code;
+};
+
+// src/brain/transport-http.ts
+function httpBrainTransport(opts) {
+  const stream = async function* (req, signal) {
+    await assertPublicHttpsUrl(opts.baseUrl, {
+      ...opts.allowHosts ? { allowHosts: opts.allowHosts } : {},
+      ...opts.lookup ? { lookup: opts.lookup } : {}
+    });
+    const frames = runBrainRequest(
+      {
+        streamId: randomUUID(),
+        messages: req.messages,
+        ...req.model ? { model: req.model } : {},
+        ...req.temperature !== void 0 ? { temperature: req.temperature } : {}
+      },
+      {
+        brainUrl: opts.baseUrl,
+        refuseRedirects: true,
+        ...opts.apiKey ? { apiKey: opts.apiKey } : {},
+        ...opts.defaultModel ? { defaultModel: opts.defaultModel } : {},
+        ...opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}
+      },
+      signal
+    );
+    for await (const frame of frames) {
+      if (frame.kind === "brain.delta") yield { content: frame.content };
+      else if (frame.kind === "brain.error") throw new BrainRequestError(frame.code, frame.message);
+    }
+  };
+  return {
+    kind: "http",
+    stream,
+    async complete(req, signal) {
+      let text = "";
+      for await (const chunk of stream(req, signal)) text += chunk.content ?? "";
+      return text;
+    }
+  };
+}
+var FlowKind = z.enum(["conversation"]);
+var FlowStatus = z.enum(["draft", "published", "archived"]);
+z.enum(["shared", "dedicated"]);
+var FlowNodeType = z.enum([
+  // Explicit entry marker — the interpreter starts here (falls back to the
+  // first indegree-0 node for older graphs without one).
+  "start",
+  "say",
+  "ask",
+  "confirm",
+  "tool",
+  "decision",
+  "handoff",
+  "end",
+  "trigger",
+  "gate",
+  "playbook",
+  "menu",
+  "code",
+  "set",
+  // Reusable component: runs another published flow inline.
+  "subflow",
+  // AI nodes (PRD P5).
+  "llm",
+  "rag",
+  "memory",
+  // Call-wide voice/turn-taking capability (barge-in + endpointing tuning);
+  // managed in the Capabilities panel like `memory`, never a graph step.
+  "speech",
+  "classify",
+  // Agentic router: per-turn, selects 1-of-N skills by their plain-language
+  // descriptions and takes that port (the resident routing surface / hub).
+  "router",
+  // Canvas-only annotation (sticky note); excluded from compilation/runtime.
+  "note"
+]);
+var FlowNodePosition = z.object({
+  x: z.number(),
+  y: z.number()
+});
+var FlowNode = z.object({
+  id: z.string().min(1).max(128),
+  type: FlowNodeType,
+  position: FlowNodePosition,
+  // Node-specific config. Generic on purpose — the per-type shape is validated
+  // by the runtime compiler that targets each plane, not by storage.
+  data: z.record(z.unknown()).default({})
+});
+var FlowEdge = z.object({
+  id: z.string().min(1).max(128),
+  // Source / target node ids (must reference FlowNode.id values).
+  source: z.string().min(1).max(128),
+  target: z.string().min(1).max(128),
+  // React Flow handle ids for multi-port nodes (e.g. a decision's branches).
+  sourceHandle: z.string().max(128).optional(),
+  targetHandle: z.string().max(128).optional(),
+  // Optional label / branch condition — e.g. a normalized tool `result.kind`.
+  label: z.string().max(128).optional(),
+  condition: z.string().max(512).optional()
+});
+var FlowGraph = z.object({
+  nodes: z.array(FlowNode).max(1e3).default([]),
+  edges: z.array(FlowEdge).max(2e3).default([])
+});
+z.object({
+  id: z.string().uuid(),
+  projectId: z.string().min(1),
+  name: z.string().min(1).max(200),
+  kind: FlowKind,
+  status: FlowStatus,
+  // The working/draft graph. Published versions snapshot this.
+  graph: FlowGraph,
+  // Latest published version number; null until first publish.
+  publishedVersion: z.number().int().min(1).nullable(),
+  createdAt: z.string().datetime(),
+  // Optimistic-lock token (mirrors AgentConfig.updatedAt).
+  updatedAt: z.string().datetime()
+});
+z.object({
+  id: z.string().uuid(),
+  flowId: z.string().uuid(),
+  projectId: z.string().min(1),
+  version: z.number().int().min(1),
+  kind: FlowKind,
+  // Frozen graph at publish time.
+  graph: FlowGraph,
+  // Optional human note describing the publish.
+  note: z.string().max(1e3).nullable(),
+  publishedByUserId: z.string().nullable(),
+  publishedAt: z.string().datetime()
+});
+z.object({
+  name: z.string().trim().min(1).max(200),
+  kind: FlowKind,
+  // Optional initial graph; defaults to empty.
+  graph: FlowGraph.optional()
+});
+z.object({
+  name: z.string().trim().min(1).max(200).optional(),
+  graph: FlowGraph.optional(),
+  // Framework is a reversible default-structure switch (Voiceflow parity):
+  // changing kind re-frames the palette/deployability but never touches the graph.
+  kind: FlowKind.optional()
+}).refine((b) => b.name !== void 0 || b.graph !== void 0 || b.kind !== void 0, {
+  message: "provide at least one of `name`, `graph`, or `kind`"
+});
+z.object({
+  note: z.string().max(1e3).optional()
+});
+
+// ../contracts/src/flow-program.ts
+var FlowProgramEdge = z.object({
+  to: z.string().min(1).max(128),
+  // Branch condition (e.g. `slot:Intent==billing`, `tool.lookup.ok`). Empty =
+  // default/fallthrough edge. Evaluated by the runtime's condition matcher.
+  condition: z.string().max(512).optional(),
+  // React Flow handle id for multi-branch nodes (decision/menu ports).
+  sourceHandle: z.string().max(128).optional(),
+  label: z.string().max(128).optional()
+});
+var FlowProgramNode = z.object({
+  id: z.string().min(1).max(128),
+  type: FlowNodeType,
+  // Cleaned, per-type config (text / slot / ask / url / requiredFields / ...).
+  // Produced by compileFlowToProgram; read defensively by the executors.
+  config: z.record(z.unknown()),
+  // Outgoing edges in declaration order.
+  out: z.array(FlowProgramEdge).max(64)
+});
+var FlowProgramDiagnostics = z.object({
+  // False if the graph contains a cycle (runtime still runs it, guarded by a
+  // per-call step/visit budget).
+  acyclic: z.boolean(),
+  // Edge ids whose source/target node was missing (skipped at compile).
+  droppedEdges: z.array(z.string().max(128)).max(256),
+  // Node ids needing external plumbing not wired yet (rag/classify/code) — the
+  // interpreter passes through them.
+  unsupportedNodes: z.array(z.string().max(128)).max(256),
+  // Port-less edges out of a conversational node (llm/ask/playbook) that carry
+  // a display `label` but no `condition` — compiled as the UNCONDITIONAL
+  // default (the label never routes). Mirrors validateFlowGraph's
+  // `edge_label_not_condition` warning. Optional: programs stored before this
+  // field existed must still pass the read-side parse.
+  labelOnlyEdges: z.array(z.string().max(128)).max(256).optional()
+});
+var FlowProgram = z.object({
+  v: z.literal(1),
+  id: z.string().min(1).max(64),
+  // Entry node id(s) — nodes with no inbound edge (interpreter starts here).
+  entry: z.array(z.string().min(1).max(128)).max(64),
+  nodes: z.record(FlowProgramNode),
+  // Mirrors the flat completion gate so the same gate computation is reused.
+  completionGate: z.object({ requiredFields: z.array(z.string()).max(64) }),
+  diagnostics: FlowProgramDiagnostics.optional()
+});
+
+// ../contracts/src/agents.ts
+var AgentEnvironment = z.enum(["dev", "stg", "prd"]);
+var AgentStatus = z.enum(["online", "offline", "degraded"]);
+var AgentName = z.string().min(1).max(128).regex(/^[a-z0-9][a-z0-9-_]*$/, 'lowercase letters, digits, "-" or "_" only');
+var AgentVersion = z.string().min(1).max(64);
+var AgentMetadata = z.record(z.unknown());
+var AgentCapability = z.string().min(1).max(64).regex(/^[a-z0-9][a-z0-9-_:.]*$/, 'lowercase letters, digits, "-_:." only');
+var ReadinessReport = z.object({
+  probe: z.string().min(1).max(128),
+  ok: z.boolean(),
+  detail: z.string().max(512).optional()
+});
+var ProcessFieldDTO = z.object({
+  name: z.string().min(1).max(64),
+  required: z.boolean(),
+  type: z.enum(["string", "string[]", "number", "boolean", "datetime", "email", "phone"]),
+  pattern: z.string().max(1024).optional(),
+  min: z.number().optional(),
+  max: z.number().optional(),
+  enum: z.array(z.string()).max(64).optional(),
+  ask: z.string().max(512).optional()
+});
+var ProcessTriggerDTO = z.object({
+  name: z.string().min(1).max(64),
+  on: z.string().min(1).max(512),
+  then: z.string().min(1).max(1024),
+  onlyWhile: z.string().max(64).optional()
+});
+var ProcessToolDTO = z.object({
+  name: z.string().min(1).max(64).regex(/^[a-z][a-z0-9_]*$/, "snake_case"),
+  description: z.string().min(1).max(2e3),
+  // Shorthand input shape: field name → primitive type. The LLM fills these.
+  // Required (the compiler always provides it, possibly {}) to keep the schema's
+  // input/output types symmetric — a `.default()` here diverges them.
+  input: z.record(z.enum(["string", "number", "boolean"])),
+  url: z.string().url(),
+  method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+  headers: z.record(z.string().max(1024)).optional(),
+  auth: z.enum(["none", "connection"]),
+  connectionRef: z.string().max(128).optional()
+});
+var ProcessSchemaDTO = z.object({
+  id: z.string().min(1).max(64),
+  // System-prompt fragments compiled from say/confirm nodes. The SDK bridge
+  // composes these into the agent's prompt.
+  prompts: z.array(z.object({ id: z.string().min(1).max(128), text: z.string().max(2e3) })).max(64).optional(),
+  fields: z.array(ProcessFieldDTO).max(64),
+  completionGate: z.object({
+    requiredFields: z.array(z.string()).max(64),
+    backendAck: z.object({
+      url: z.string().url(),
+      timeoutMs: z.number().int().positive()
+    }).optional()
+  }),
+  // Deterministic rails compiled from trigger/handoff/end nodes.
+  triggers: z.array(ProcessTriggerDTO).max(64).optional(),
+  // Default human destination for `then:'handoff'` rails.
+  handoff: z.object({
+    fallback: z.string().max(128).optional(),
+    routes: z.record(z.string().max(128)).optional()
+  }).optional(),
+  // Memory config compiled from a memory node (maps to AgentConfig.memory).
+  memory: z.object({
+    scope: z.enum(["call", "caller", "participant", "account", "platform"]).optional(),
+    retentionDays: z.number().int().positive().optional(),
+    piiFields: z.array(z.string().max(64)).max(64).optional()
+  }).optional(),
+  // Tool capabilities compiled from tool nodes (maps to AgentConfig.tools).
+  tools: z.array(ProcessToolDTO).max(32).optional(),
+  // Voice turn-taking compiled from the flow's speech capability node (maps to
+  // AgentConfig.speech → applySpeechTurnHandling). Absent = platform defaults.
+  speech: z.object({
+    interruption: z.object({
+      enabled: z.boolean().optional(),
+      minWords: z.number().int().min(0).max(10).optional(),
+      minDuration: z.number().int().min(0).max(5e3).optional()
+    }).optional(),
+    endpointing: z.object({
+      minDelay: z.number().int().min(0).max(5e3).optional(),
+      maxDelay: z.number().int().min(0).max(15e3).optional()
+    }).optional()
+  }).optional(),
+  // Graph-preserving compiled program. When present and the flow-runtime graph
+  // mode is enabled, the worker executes this node-graph deterministically
+  // (the interpreter) instead of the flat goals+rails form above. Embedded here
+  // (not a new column) so the existing fetch path delivers it with no migration.
+  program: FlowProgram.optional()
+});
+z.object({
+  name: AgentName,
+  version: AgentVersion,
+  environment: AgentEnvironment,
+  // Initial status. Defaults to 'online'; SDK sends 'degraded' when any
+  // readiness probe failed but registration wasn't required-ready.
+  status: z.enum(["online", "degraded"]).optional(),
+  statusDetail: z.string().max(512).optional(),
+  capabilities: z.array(AgentCapability).max(64).optional(),
+  readiness: z.array(ReadinessReport).max(64).optional(),
+  metadata: AgentMetadata.optional(),
+  processSchema: ProcessSchemaDTO.nullable().optional(),
+  // A code-first agent's base prompt (its instructions live in code, not the DB).
+  // Synced here so a generic worker can run it over text (P2). Omit for flow agents.
+  // Cap matches AgentConfig.systemPrompt (64k) so a large-but-valid prompt doesn't
+  // fail registration outright (which agent.ts swallows → agent runs but never
+  // registers/heartbeats).
+  prompt: z.string().max(64e3).nullable().optional(),
+  // The text-turn protocol this worker speaks (burn-down G-4): it registers `<name>::text` and runs text turns as the
+  // agent. Absent = it can't (an older SDK, a puppet, a flow pool) — stored as null, so a downgrade stops text turns.
+  // Any version is accepted (a newer SDK never fails registration); the API decides which versions it dispatches to.
+  textTurns: z.number().int().min(1).max(1e3).optional(),
+  // Opt into MCP exposure. When true the API upserts a matching agent_config
+  // row keyed by (project_id, name, environment) so MCP / dashboard / REST
+  // can list and inspect this agent's identity. When false / omitted, the
+  // agent stays invisible to MCP; identity is purely in worker code.
+  mcpExposed: z.boolean().optional()
+});
+var AgentDTO = z.object({
+  id: z.string().uuid(),
+  projectId: z.string(),
+  name: AgentName,
+  version: AgentVersion,
+  environment: AgentEnvironment,
+  status: AgentStatus,
+  statusDetail: z.string().nullable(),
+  capabilities: z.array(AgentCapability),
+  readiness: z.array(ReadinessReport),
+  lastSeenAt: z.string().datetime().nullable(),
+  metadata: AgentMetadata,
+  processSchema: ProcessSchemaDTO.nullable().optional(),
+  // Whether this agent can run through the engine over text: a flow agent (its
+  // compiled graph rides in processSchema.program), a brain-connector agent, OR a
+  // code-first agent whose worker takes text turns (G-4). Drives the dashboard's chat gate so it
+  // no longer hard-codes "flow only". Computed server-side; not stored. OPTIONAL
+  // on the wire so a new worker validating a response from an OLD api pod during
+  // a rolling deploy doesn't fail register/heartbeat on a missing field.
+  textRunnable: z.boolean().optional(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime()
+});
+z.object({
+  processSchema: ProcessSchemaDTO.nullable()
+});
+z.object({
+  processSchema: ProcessSchemaDTO.nullable()
+});
+z.object({
+  prompt: z.string().nullable()
+});
+z.object({
+  agent: AgentDTO,
+  // Server-controlled cadence so we can tune without an SDK release.
+  heartbeatIntervalMs: z.number().int().positive()
+});
+z.object({
+  status: z.enum(["online", "degraded"]).optional(),
+  statusDetail: z.string().max(512).optional(),
+  metadata: AgentMetadata.optional()
+});
+z.object({
+  agent: AgentDTO,
+  heartbeatIntervalMs: z.number().int().positive()
+});
+z.object({
+  environment: AgentEnvironment.optional()
+});
+z.object({
+  agents: z.array(AgentDTO)
+});
+z.object({
+  ok: z.literal(true)
+});
+var ProcessLifecycleEvent = z.object({
+  id: z.string().min(1),
+  at: z.string().datetime(),
+  kind: z.string().min(1).max(80),
+  source: z.enum(["agent", "caller", "form", "platform"]),
+  data: z.record(z.string(), z.unknown())
+});
+var ProcessSnapshotPayload = z.object({
+  schemaId: z.string(),
+  currentNode: z.string(),
+  fieldsCaptured: z.record(z.string(), z.unknown()),
+  backendAckReceived: z.boolean(),
+  backendAckReceivedAt: z.string().datetime().optional(),
+  // Optional for back-compat with publishers built before this field
+  // existed. The cold-path → SSE pipe is otherwise pass-through.
+  lifecycle: z.array(ProcessLifecycleEvent).optional()
+});
+z.object({
+  callId: z.string().min(1),
+  agentId: z.string().min(1).nullable(),
+  projectId: z.string().min(1),
+  ts: z.string().datetime(),
+  snapshot: ProcessSnapshotPayload
+});
+z.enum([
+  "consultation.requested",
+  "consultation.resolved"
+]);
+z.object({
+  consultationId: z.string().uuid(),
+  // Free-form question. Generic on purpose — no vertical-specific fields.
+  question: z.string().min(1).max(2e3),
+  // Transcript context the agent felt was relevant when asking.
+  transcriptSnippet: z.string().max(4e3).optional(),
+  // Hint to the orchestrator about how aggressively to interrupt the human.
+  urgency: z.enum(["low", "normal", "high"]).default("normal"),
+  // Server-clamped to ConsultationPolicy.maxTimeoutMs and ProjectLimits.
+  timeoutMs: z.number().int().min(1e3).max(3e5)
+});
+z.object({
+  consultationId: z.string().uuid(),
+  // 'timeout' = per-consult cap. 'cumulative_cap' = call-wide ceiling.
+  // 'cancelled' = agent decided it no longer needed an answer.
+  resolution: z.enum(["guidance", "timeout", "cumulative_cap", "cancelled"]),
+  guidance: z.string().max(4e3).optional(),
+  // Wall-clock from requested-emit → resolved-emit. SLA tracking.
+  latencyMs: z.number().int().min(0)
+});
+var GuidanceCommand = z.object({
+  kind: z.literal("guidance"),
+  consultationId: z.string().uuid(),
+  guidance: z.string().min(1).max(4e3),
+  // Optional bridge phrase the agent may speak before delivering guidance.
+  resumePhrase: z.string().max(500).optional(),
+  // G-5: the API's id for this command; the agent confirms it (CallControlAck). Optional so a command from an older
+  // API is still acted on (just not confirmed).
+  commandId: z.string().uuid().optional()
+});
+var ConsultationPolicy = z.object({
+  enabled: z.boolean().default(true),
+  // Per-consult default. ProjectLimits.perCallMaxTimeoutMs clamps this.
+  defaultTimeoutMs: z.number().int().min(1e3).default(3e4),
+  maxTimeoutMs: z.number().int().min(1e3).default(3e4),
+  // Cumulative cap across the call. ProjectLimits clamps.
+  maxCumulativeHoldMs: z.number().int().min(1e3).default(12e4),
+  // Spoken when the agent emits consultation.requested.
+  holdPhrase: z.string().min(1).max(500).default("Let me check on that."),
+  // Spoken when a single consultation times out — the call continues.
+  fallbackPhrase: z.string().min(1).max(500).default("Sorry, I don't have that information right now."),
+  // Spoken when the cumulative cap fires — the call ends after this.
+  callEndFallback: z.string().min(1).max(500).default("I'm going to need someone to call you back. Thank you."),
+  // Optional per-urgency timeout override. Lets ops shorten 'high' urgency
+  // holds without lowering the default.
+  urgencyOverrides: z.object({
+    low: z.number().int().min(1e3).optional(),
+    normal: z.number().int().min(1e3).optional(),
+    high: z.number().int().min(1e3).optional()
+  }).optional()
+});
+
+// ../contracts/src/call-events.ts
+var CallEventKind = z.enum([
+  "status.dialing",
+  "status.dispatched",
+  "status.ringing",
+  "status.answered",
+  "status.ended",
+  "transcript.partial",
+  "transcript.final",
+  "tts.spoken",
+  "cost.update",
+  // Consultation lifecycle — see packages/contracts/src/consultation.ts.
+  // Emitted by the agent's built-in `ask_host` tool. The dashboard and MCP
+  // host SSE clients filter on these to surface the "let me check" UX.
+  "consultation.requested",
+  "consultation.resolved",
+  // DTMF keypad events. `dtmf.received` fires when a remote participant
+  // presses a key on their leg; `dtmf.sent` fires when our agent (or a
+  // programmatic caller via /v1/calls/:id/dtmf) emits one outbound.
+  "dtmf.received",
+  "dtmf.sent"
+]);
+var OP_CALL_EVENT_KIND = /^(tool|handoff|lookup|record|notify|engine)\.[a-z0-9_]{1,48}(\.[a-z0-9_]{1,48})?$/;
+var OpCallEventKind = z.string().regex(OP_CALL_EVENT_KIND);
+z.object({
+  reason: z.string().optional(),
+  durationMs: z.number().int().min(0).optional(),
+  endedAt: z.string().datetime().optional()
+});
+z.object({
+  speaker: z.enum(["caller", "agent"]),
+  text: z.string(),
+  startMs: z.number().int().min(0),
+  endMs: z.number().int().min(0)
+});
+z.object({
+  text: z.string(),
+  // The MCP client sets this so it can correlate the spoken event to the
+  // call_say invocation that triggered it (used for "did my say actually go
+  // through" confirmation in the host chat).
+  correlationId: z.string().optional()
+});
+z.object({
+  digit: z.string().regex(/^[0-9*#A-D]$/),
+  code: z.number().int().min(0).max(15),
+  participantId: z.string().optional()
+});
+z.object({
+  totalUsd: z.string(),
+  breakdown: z.object({
+    llmUsd: z.string().optional(),
+    ttsUsd: z.string().optional(),
+    sttUsd: z.string().optional(),
+    telephonyUsd: z.string().optional()
+  }).optional()
+});
+z.object({
+  // Global bigserial assigned at insert. SSE clients use this as Last-Event-ID.
+  seq: z.number().int().min(0),
+  callId: z.string().uuid(),
+  projectId: z.string().min(1),
+  // Closed lifecycle kinds OR the namespaced operational vocabulary.
+  kind: z.union([CallEventKind, OpCallEventKind]),
+  payload: z.unknown(),
+  ts: z.string().datetime()
+});
+z.enum(["say", "hangup", "dtmf", "instruct", "guidance"]);
+var commandId = z.string().uuid().optional();
+var SayCommand = z.object({
+  kind: z.literal("say"),
+  commandId,
+  text: z.string().min(1),
+  // 'interrupt' replaces any in-flight TTS; 'queue' waits for current to end.
+  mode: z.enum(["interrupt", "queue"]).default("interrupt"),
+  correlationId: z.string().optional()
+});
+var HangupCommand = z.object({
+  kind: z.literal("hangup"),
+  commandId,
+  reason: z.string().optional()
+});
+var DtmfCommand = z.object({
+  kind: z.literal("dtmf"),
+  commandId,
+  digits: z.string().regex(/^[0-9*#]+$/)
+});
+var InstructCommand = z.object({
+  kind: z.literal("instruct"),
+  commandId,
+  text: z.string().min(1)
+});
+z.discriminatedUnion("kind", [
+  SayCommand,
+  HangupCommand,
+  DtmfCommand,
+  InstructCommand,
+  GuidanceCommand
+]);
+z.object({
+  commandId: z.string().uuid(),
+  outcome: z.enum(["applied", "refused", "failed"]),
+  // machine code: output_blocked · not_supported · unknown_consultation · no_consultation · invalid_command ·
+  // say_unavailable · dtmf_unavailable
+  code: z.string().max(64).optional(),
+  detail: z.string().max(500).optional()
+});
+z.object({
+  mode: z.literal("text"),
+  turnId: z.string().uuid(),
+  projectId: z.string().min(1),
+  agentId: z.string().uuid()
+});
+var TextTurnHistoryEntry = z.object({
+  role: z.enum(["user", "assistant"]),
+  content: z.string().max(16e3)
+});
+z.object({
+  turnId: z.string().uuid(),
+  agentId: z.string().uuid(),
+  /** The Line the message came in on (`sms`, `discord`, `web`, `playground`, …). */
+  channel: z.string().min(1).max(40),
+  /** The sender on that Line (phone number, Discord user, widget visitor) — the agent's caller-scoped memory key. */
+  from: z.string().min(1).max(200),
+  /** The conversation this turn belongs to (stable across turns) — the tool context's call id. */
+  conversationKey: z.string().min(1).max(300),
+  history: z.array(TextTurnHistoryEntry).max(80),
+  text: z.string().min(1).max(8e3),
+  /** When the API stops waiting; the worker stops the run before it. */
+  deadlineAt: z.string().datetime()
+});
+var TextTurnUsage = z.object({
+  provider: z.string().min(1).max(60),
+  model: z.string().min(1).max(200),
+  inputTokens: z.number().int().nonnegative(),
+  outputTokens: z.number().int().nonnegative(),
+  /** Only a first-party worker's label is used; a customer's worker runs on its own key (the API decides). */
+  byok: z.boolean()
+});
+var TextTurnErrorCode = z.enum(["agent_unavailable", "agent_timeout"]);
+z.union([
+  z.object({
+    agentId: z.string().uuid(),
+    replies: z.array(z.string().max(16e3)).max(20),
+    usage: z.array(TextTurnUsage).max(50).default([])
+  }),
+  z.object({
+    agentId: z.string().uuid(),
+    error: z.object({ code: TextTurnErrorCode, detail: z.string().max(500).optional() })
+  })
+]);
+var VoiceConfig = z.object({
+  // Finite, vetted list — platform-level enum.
+  provider: z.enum(["deepgram", "elevenlabs", "openai", "cartesia"]),
+  voiceId: z.string().min(1).max(128),
+  // TTS synthesis model (provider-specific, e.g. 'eleven_turbo_v2_5',
+  // 'sonic-2'). Optional — providers like Deepgram fold the voice into the
+  // model id (aura-2-harmonia-en) and ignore this.
+  model: z.string().min(1).max(128).optional(),
+  // Speed knob narrow to what every provider supports — keeps it portable.
+  rate: z.number().min(0.5).max(2).optional()
+});
+var ModelConfig = z.object({
+  provider: z.enum(["openai", "anthropic", "gemini"]),
+  model: z.string().min(1).max(128),
+  temperature: z.number().min(0).max(2).optional(),
+  // Per-call ceiling. Distinct from project-level quota in ProjectLimits.
+  maxOutputTokens: z.number().int().min(1).max(32768).optional(),
+  // Advanced nucleus-sampling knob. Optional — most builders leave it unset
+  // and rely on temperature alone.
+  topP: z.number().min(0).max(1).optional()
+});
+var SttConfig = z.object({
+  provider: z.enum(["deepgram", "cartesia", "assemblyai"]),
+  model: z.string().min(1).max(128).optional(),
+  // BCP-47; falls back to AgentConfig.language when unset.
+  language: z.string().min(2).max(16).optional(),
+  // End-of-turn confidence (higher = wait for more certainty before the agent
+  // takes its turn). The single biggest perceived-latency lever in voice.
+  endOfTurnConfidence: z.number().min(0).max(1).optional(),
+  // Hard cap (ms) on how long to wait for end-of-turn before responding.
+  endOfTurnTimeoutMs: z.number().int().min(100).max(5e3).optional(),
+  // Keyword boost list — bias transcription toward these terms.
+  keywords: z.array(z.string().min(1).max(64)).max(100).optional()
+});
+var RealtimeConfig = z.object({
+  provider: z.enum(["openai", "google"]),
+  model: z.string().min(1).max(128),
+  // Provider-native voice id ('alloy', 'echo' for OpenAI; 'Aoede', 'Puck' for
+  // Gemini Live). Optional — provider default applies when unset.
+  voice: z.string().min(1).max(128).optional(),
+  temperature: z.number().min(0).max(2).optional()
+});
+var PipelineMode = z.enum(["cascade", "realtime"]);
+var ToolBinding = z.object({
+  toolName: z.string().min(1).max(128),
+  // Per-agent override of the tool's default args (e.g. an API base URL).
+  // Generic Record on purpose — no vertical-specific shape.
+  defaultArgs: z.record(z.unknown()).optional()
+});
+var ProcessFieldType = z.enum([
+  "string",
+  "string[]",
+  "number",
+  "boolean",
+  "datetime",
+  "email",
+  "phone"
+]);
+var ProcessFieldSpec = z.object({
+  type: ProcessFieldType,
+  required: z.boolean().optional(),
+  // Regex source string (not a RegExp object — JSON-safe). Applied to
+  // `string` and `string[]` items by the SDK at validation time.
+  pattern: z.string().max(500).optional(),
+  min: z.number().optional(),
+  max: z.number().optional(),
+  enum: z.array(z.string().min(1).max(200)).max(50).optional(),
+  // Override the auto-generated capture prompt.
+  ask: z.string().max(500).optional(),
+  // Override the field-extraction hint shown to the LLM.
+  extract: z.string().max(500).optional()
+});
+var ProcessCompleteWhen = z.enum([
+  "all-required-captured",
+  "all-captured"
+]);
+var ProcessBackendAckSpec = z.object({
+  url: z.string().url(),
+  timeoutMs: z.number().int().min(100).max(6e4).optional(),
+  headers: z.record(z.string(), z.string()).optional()
+});
+var ProcessSpec = z.object({
+  // Defaults to {} so LLM-authored plans can emit `process: { completeWhen }`
+  // without naming any structured fields. Downstream agent runtime handles
+  // empty maps as "no callee-side capture, only the completeWhen criterion."
+  collect: z.record(z.string().min(1).max(128), ProcessFieldSpec).default({}),
+  completeWhen: ProcessCompleteWhen.default("all-required-captured"),
+  backendAck: ProcessBackendAckSpec.optional()
+});
+var TriggerConditionSpec = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("regex"),
+    pattern: z.string().min(1).max(500),
+    flags: z.string().max(8).optional()
+  }),
+  z.object({
+    kind: z.literal("signal"),
+    name: z.string().min(1).max(128)
+  })
+]);
+var TriggerActionSpec = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("handoff") }),
+  z.object({ kind: z.literal("endCall") }),
+  z.object({ kind: z.literal("say"), text: z.string().min(1).max(2e3) })
+]);
+var TriggerSpec = z.object({
+  on: TriggerConditionSpec,
+  then: TriggerActionSpec,
+  // If set, the trigger only fires while the named process field is uncaptured.
+  onlyWhile: z.string().min(1).max(128).optional()
+});
+var RequiredInfoField = z.object({
+  name: z.string().min(1).max(64),
+  type: z.enum(["string", "string[]", "number", "boolean", "datetime", "email", "phone"]),
+  required: z.boolean(),
+  // The field's `ask` prompt — what the value represents / how to source it.
+  description: z.string().max(512).optional(),
+  // Constrained value set, when the field is an enum.
+  enum: z.array(z.string()).max(64).optional()
+});
+var AgentConfig = z.object({
+  id: z.string().uuid(),
+  projectId: z.string().min(1),
+  // Human-readable label. No `agentType` enum on purpose.
+  name: z.string().min(1).max(128),
+  // Soft override of the worker's baked-in prompt. Absent → call_start
+  // uses the SDK worker's predefined prompt (the source of truth for
+  // pre-defined agents like FNOL). Present → it overrides the worker's
+  // prompt at call_start as a snapshot decision; mid-call edits are not
+  // honoured. Per-call override at call_start time is also allowed.
+  systemPrompt: z.string().max(64e3).optional(),
+  // Routing/decision layer (Voiceflow "Instructions"): plain-language guidance the
+  // agent reads to decide WHEN to do things (vs systemPrompt = WHO it is). Injected
+  // into the system prompt below the persona. Interpolated with {{ }} at runtime.
+  routingInstructions: z.string().max(32e3).optional(),
+  voice: VoiceConfig,
+  model: ModelConfig,
+  // STT for the cascade pipeline. Absent → SDK default (Deepgram nova-3).
+  stt: SttConfig.optional(),
+  // Pipeline mode. Defaults to 'cascade' so pre-existing rows (which have no
+  // mode column) behave exactly as before.
+  mode: PipelineMode.default("cascade"),
+  // Realtime / speech-to-speech model. Used when mode === 'realtime'; ignored
+  // otherwise. Optional in the schema so cascade-only agents omit it.
+  realtime: RealtimeConfig.optional(),
+  // BCP-47 string. Free-form so customers add locales without a release.
+  language: z.string().min(2).max(16).default("en-US"),
+  tools: z.array(ToolBinding).max(64).default([]),
+  consultation: ConsultationPolicy,
+  // Structured outcome — the data the agent collects on the call.
+  // Optional; absent means the call has no structured outcome.
+  process: ProcessSpec.optional(),
+  // Deterministic routes that fire BEFORE the LLM. Keyed by stable string
+  // ids (e.g. 'cancellation_fee', 'asked_for_card') so call_plan revisions
+  // can address a specific trigger.
+  triggers: z.record(z.string().min(1).max(128), TriggerSpec).optional(),
+  // Free-form labels — no semantic enums.
+  tags: z.array(z.string().max(64)).max(32).optional(),
+  // Bound brain connector (bring-your-own LLM). When set, the worker drives the
+  // LLM slot through the connector instead of a first-party model. Null/absent →
+  // first-party pipeline (unchanged default). See docs/specs/voice-brain-connector.
+  brainConnectorId: z.string().uuid().nullable().optional(),
+  // Provenance: 'sdk' (hand-coded defineAgent worker), 'flow' (canvas deploy),
+  // 'playbook' (agent-mode deploy), or 'connector' (brain-connector agent).
+  // DERIVED from the linked agents row's deploy tags (flowId / playbookId /
+  // connectorId in metadata) — not stored on agent_config, never PATCHed.
+  source: z.enum(["sdk", "flow", "playbook", "connector"]).optional(),
+  // True when the pipeline MODE is locked to code (genuine SDK agents only):
+  // the dashboard renders mode read-only and PATCH rejects a mode change.
+  // Derived; read-only. Flow/playbook/connector agents → false.
+  modeLocked: z.boolean().optional(),
+  // Inputs this agent needs to run a call, projected from its process schema.
+  // An MCP host reads these (via list_agents) to pre-fill known values as
+  // call_start metadata so the agent never re-asks. Empty when the agent
+  // collects nothing structured. DERIVED from the agents row; read-only.
+  requiredInfo: z.array(RequiredInfoField).max(64).default([]),
+  createdAt: z.string().datetime(),
+  // Optimistic-lock token. PATCH must echo this in If-Match.
+  updatedAt: z.string().datetime()
+});
+
+// ../contracts/src/call-plan.ts
+var PlanStatus = z.enum([
+  "drafting",
+  "clarifying",
+  "ready",
+  "committed",
+  "abandoned"
+]);
+var PlanCallee = z.object({
+  e164: z.string().min(2).optional(),
+  // may be unknown at intent time
+  displayName: z.string().max(200).optional(),
+  // What the host knows about who they're calling. e.g. "their dentist's
+  // billing office", "a hiring manager named Priya". Seeds tone/register
+  // and likely-triggers; not used to gate behaviour.
+  description: z.string().max(2e3).optional()
+});
+var PlanQuestion = z.object({
+  id: z.string().min(1).max(128),
+  // stable across rounds; e.g. 'policy_number'
+  prompt: z.string().min(1).max(1e3),
+  // 'fact'     — the planner needs a piece of data (e.g. account #).
+  // 'decision' — the planner needs the host to pick an option/policy.
+  // 'auth'     — the planner is checking the host has authority to act.
+  kind: z.enum(["fact", "decision", "auth"]),
+  // For 'decision' questions only.
+  options: z.array(z.string().min(1).max(200)).max(20).optional(),
+  // True if the agent could ask the callee for this mid-call instead of
+  // demanding it from the host now. When true and the host can't answer,
+  // the planner promotes this to a draftConfig.process.collect field
+  // rather than blocking the call.
+  deferrableToCallee: z.boolean().default(false)
+});
+var PlanEscalation = z.object({
+  // 'consult_host'    — ask the MCP host (default for plan-first calls).
+  // 'ask_callee'      — stay on the line and ask the caller.
+  // 'fallback_phrase' — read the agent's configured fallback line.
+  onUncertainty: z.enum(["consult_host", "ask_callee", "fallback_phrase"]).default("consult_host"),
+  // Hard cap on host consultations for this call. Independent of
+  // ConsultationPolicy time caps which still apply.
+  maxHostConsults: z.number().int().min(0).max(20).optional(),
+  // If host doesn't reply within this window, fall through to `secondary`.
+  // Server-clamps to ConsultationPolicy.maxTimeoutMs.
+  hostTimeoutMs: z.number().int().min(1e3).max(3e5).optional(),
+  secondary: z.enum(["ask_callee", "fallback_phrase"]).default("fallback_phrase")
+});
+var DraftAgentConfig = AgentConfig.omit({
+  id: true,
+  projectId: true,
+  createdAt: true,
+  updatedAt: true
+}).partial();
+var CallPlan = z.object({
+  planId: z.string().uuid(),
+  projectId: z.string().min(1),
+  status: PlanStatus,
+  // Why we're calling. One sentence, free-form. Kept verbatim from the
+  // host's original IntentRequest so we can replay planning. The refined
+  // version lives in draftConfig.systemPrompt.
+  objective: z.string().min(1).max(2e3),
+  callee: PlanCallee,
+  // The AgentConfig the planner is building. Grows across clarify rounds.
+  // At status='ready' this is a complete (modulo defaulted fields)
+  // AgentConfig override; at status='committed' it's the snapshot the
+  // call booted with.
+  draftConfig: DraftAgentConfig.default({}),
+  // Pre-call host-facing clarifications. When non-empty AND
+  // status='clarifying', the host must answer via call_clarify. When
+  // non-empty AND status='ready', the remaining questions were either
+  // deferred to callee (see unresolvedQuestions) or dropped after
+  // exhausting clarificationRounds — see changeSummary on each
+  // PlanResponse for what happened.
+  openQuestions: z.array(PlanQuestion).max(20).default([]),
+  // Snapshot of deferrableToCallee questions that the planner couldn't
+  // resolve and instead promoted to draftConfig.process.collect at
+  // commit time. Kept for audit + so the host can see what the agent
+  // will ask the callee.
+  unresolvedQuestions: z.array(PlanQuestion).max(20).default([]),
+  escalation: PlanEscalation,
+  // Round counter. Server enforces PlanLimits.maxClarificationRounds.
+  clarificationRounds: z.number().int().min(0).default(0),
+  // Set once `call_commit` succeeds. Links the plan to the call it
+  // created. Useful for the dashboard plan inspector.
+  committedCallId: z.string().uuid().optional(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime()
+});
+z.object({
+  objective: z.string().min(1).max(2e3),
+  callee: PlanCallee.optional(),
+  // Initial facts the host already has. Folded into draftConfig at the
+  // planner's discretion — typically inlined into systemPrompt or stored
+  // as process.collect default values.
+  knowns: z.record(z.string().min(1).max(128), z.string().max(4e3)).optional(),
+  // Hard constraints the planner must respect. e.g.
+  // ["never disclose the card CVV", "if asked for SSN, refuse politely"].
+  // Generate matching triggers + appear in systemPrompt as do-not-disclose
+  // rules.
+  constraints: z.array(z.string().min(1).max(500)).max(20).optional(),
+  // Per-call escalation overrides — merged with project defaults.
+  escalation: PlanEscalation.partial().optional(),
+  // Override the agent's default voice/model/language for this call. Most
+  // hosts won't set this; here for power users.
+  configOverrides: DraftAgentConfig.pick({
+    voice: true,
+    model: true,
+    language: true
+  }).optional()
+});
+z.object({
+  // Map question.id → answer text. For 'decision' questions the value
+  // should be one of `options`, but the server doesn't enforce strictly —
+  // the planner will re-ask if the answer is unrecognized.
+  answers: z.record(z.string().min(1).max(128), z.string().max(4e3)),
+  // The host can also push new facts that weren't asked for.
+  additionalKnowns: z.record(z.string().min(1).max(128), z.string().max(4e3)).optional()
+});
+z.object({
+  to: z.string().min(2),
+  // E.164
+  phoneNumberId: z.string().uuid(),
+  metadata: z.record(z.string().min(1).max(128), z.string().max(4e3)).optional(),
+  force: z.boolean().default(false)
+});
+z.object({
+  plan: CallPlan,
+  // Convenience: questions to answer next. Same as plan.openQuestions
+  // when status='clarifying'; empty otherwise.
+  questions: z.array(PlanQuestion),
+  // Human-readable summary of what changed in this round. Useful for the
+  // host's chat surface ("I added 3 facts and resolved 2 questions").
+  changeSummary: z.string().max(2e3).optional()
+});
+z.object({
+  callId: z.string().uuid(),
+  plan: CallPlan
+  // status will be 'committed'
+});
+z.object({
+  // After this many round-trips, the planner forces status='ready' and
+  // any remaining questions are marked deferrableToCallee or dropped.
+  maxClarificationRounds: z.number().int().min(1).default(3),
+  // How long an uncommitted plan lives before it's auto-abandoned. Lets
+  // the host build a plan in one session and commit it in another.
+  planTtlMs: z.number().int().min(6e4).default(36e5)
+  // 1h
+});
+var MemoryScope = z.enum(["call", "caller", "account", "platform"]);
+var MemoryRecord = z.record(z.unknown());
+var RelevantContext = z.object({
+  call: MemoryRecord,
+  caller: MemoryRecord,
+  account: MemoryRecord,
+  platform: MemoryRecord
+});
+z.object({
+  callerId: z.string().min(1),
+  scopes: z.array(MemoryScope).optional()
+});
+z.object({
+  context: RelevantContext
+});
+z.object({
+  scope: MemoryScope,
+  callerId: z.string().min(1),
+  delta: MemoryRecord,
+  callId: z.string().optional()
+});
+z.object({
+  accepted: z.literal(true)
+});
+z.object({
+  callId: z.string().uuid(),
+  stage: z.string().min(1).max(64),
+  snapshot: MemoryRecord
+});
+z.object({
+  id: z.string().uuid()
+});
+z.object({
+  externalKey: z.string().min(1).max(256),
+  displayName: z.string().max(256).optional(),
+  identifiers: z.array(
+    z.object({
+      type: z.string().min(1).max(64),
+      value: z.string().min(1).max(256)
+    })
+  ).optional()
+});
+var CallerDTO = z.object({
+  id: z.string().uuid(),
+  projectId: z.string(),
+  externalKey: z.string(),
+  displayName: z.string().nullable(),
+  metadata: MemoryRecord,
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime()
+});
+z.object({
+  caller: CallerDTO
+});
+z.object({
+  ok: z.literal(true),
+  scopesPurged: z.array(MemoryScope)
+});
+z.object({
+  systemPrompt: z.string().max(64e3),
+  routingInstructions: z.string().max(32e3).nullable(),
+  voice: VoiceConfig,
+  model: ModelConfig,
+  stt: SttConfig.nullable(),
+  mode: PipelineMode,
+  realtime: RealtimeConfig.nullable(),
+  language: z.string().min(2).max(16),
+  tools: z.array(ToolBinding).max(64),
+  consultation: ConsultationPolicy,
+  tags: z.array(z.string().max(64)).max(32).nullable(),
+  brainConnectorId: z.string().uuid().nullable(),
+  flowVersion: z.number().int().nullable(),
+  processSchema: ProcessSchemaDTO.nullable()
+});
+z.enum(["published", "draft"]);
+var AgentConfigVersionDTO = z.object({
+  id: z.string().uuid(),
+  version: z.number().int().min(1),
+  createdAt: z.string().datetime(),
+  // 'user:<clerkId>' · 'api_key:<id>' · 'system:backfill' · 'system:deploy' · 'system:register'
+  createdBy: z.string().nullable(),
+  note: z.string().nullable(),
+  flowVersion: z.number().int().nullable(),
+  isPublished: z.boolean()
+});
+z.object({
+  versions: z.array(AgentConfigVersionDTO),
+  publishedVersion: z.number().int().min(1)
+});
+z.object({
+  note: z.string().trim().max(500).optional()
+});
+z.object({
+  version: AgentConfigVersionDTO
+});
+var AgentConfigDiffField = z.enum([
+  "systemPrompt",
+  "routingInstructions",
+  "mode",
+  "model",
+  "voice",
+  "stt",
+  "realtime",
+  "language",
+  "tools",
+  "brainConnectorId",
+  "consultation",
+  "tags",
+  "flowVersion",
+  "processSchema"
+]);
+var AgentConfigChange = z.object({
+  field: AgentConfigDiffField,
+  label: z.string(),
+  /** The published value in plain words. */
+  from: z.string(),
+  /** The draft value in plain words. */
+  to: z.string(),
+  /** True for long text (prompts) — the sheet renders it in a scrollable block. */
+  longText: z.boolean()
+});
+z.object({
+  published: z.object({
+    version: z.number().int().min(1),
+    createdAt: z.string().datetime(),
+    note: z.string().nullable()
+  }),
+  hasChanges: z.boolean(),
+  changes: z.array(AgentConfigChange)
+});
+
+// ../contracts/src/providers.ts
+var PROVIDERS = {
+  openai: { id: "openai", label: "OpenAI", capabilities: ["llm", "tts", "realtime"], byok: true, supportsBaseUrl: true, keyPlaceholder: "sk-..." },
+  anthropic: { id: "anthropic", label: "Anthropic", capabilities: ["llm"], byok: true, supportsBaseUrl: true, keyPlaceholder: "sk-ant-..." },
+  deepgram: { id: "deepgram", label: "Deepgram", capabilities: ["stt", "tts"], byok: true, supportsBaseUrl: false, keyPlaceholder: "Deepgram API key" },
+  elevenlabs: { id: "elevenlabs", label: "ElevenLabs", capabilities: ["tts"], byok: true, supportsBaseUrl: false, keyPlaceholder: "ElevenLabs API key" },
+  cartesia: { id: "cartesia", label: "Cartesia", capabilities: ["stt", "tts"], byok: true, supportsBaseUrl: false, keyPlaceholder: "Cartesia API key" },
+  assemblyai: { id: "assemblyai", label: "AssemblyAI", capabilities: ["stt"], byok: true, supportsBaseUrl: false, keyPlaceholder: "AssemblyAI API key" },
+  google: { id: "google", label: "Google (Gemini)", capabilities: ["llm", "realtime"], byok: true, supportsBaseUrl: false, keyPlaceholder: "AIza..." },
+  groq: { id: "groq", label: "Groq", capabilities: ["llm"], byok: true, supportsBaseUrl: true, keyPlaceholder: "gsk_..." },
+  // Runtime-only providers (no external key): local VAD.
+  silero: { id: "silero", label: "Silero", capabilities: ["vad"], byok: false, supportsBaseUrl: false }
+};
+function byokProviders() {
+  return Object.values(PROVIDERS).filter((p) => p.byok);
+}
+var ProviderKind = z.enum(["llm", "stt", "tts", "realtime"]);
+var CatalogVoice = z.object({
+  id: z.string().min(1).max(128),
+  label: z.string().min(1).max(128),
+  // Optional sample for an in-picker preview button.
+  previewUrl: z.string().url().optional(),
+  // e.g. 'female', 'narration', 'en-US'.
+  tags: z.array(z.string().max(40)).max(12).optional()
+});
+var CatalogModel = z.object({
+  id: z.string().min(1).max(128),
+  label: z.string().min(1).max(128),
+  // Pricing hints (USD) shown next to the option. Only the fields relevant to
+  // the provider kind are populated.
+  inputPerMillion: z.number().nonnegative().optional(),
+  // llm / realtime tokens
+  outputPerMillion: z.number().nonnegative().optional(),
+  perMillionChars: z.number().nonnegative().optional(),
+  // tts
+  perMinute: z.number().nonnegative().optional(),
+  // stt / realtime session
+  // Capability hints.
+  contextWindow: z.number().int().positive().optional(),
+  notes: z.string().max(200).optional()
+});
+var CatalogProvider = z.object({
+  id: z.string().min(1).max(64),
+  // 'openai' | 'anthropic' | 'deepgram' | ...
+  label: z.string().min(1).max(64),
+  kind: ProviderKind,
+  models: z.array(CatalogModel).default([]),
+  // Populated for tts / realtime providers.
+  voices: z.array(CatalogVoice).optional(),
+  // Pre-selected when the provider is chosen.
+  defaultModel: z.string().max(128).optional()
+});
+z.object({
+  llm: z.array(CatalogProvider).default([]),
+  stt: z.array(CatalogProvider).default([]),
+  tts: z.array(CatalogProvider).default([]),
+  realtime: z.array(CatalogProvider).default([])
+});
+var CostEstimateAssumptions = z.object({
+  callDurationSeconds: z.number().positive().max(7200).optional(),
+  llmInputTokensPerMin: z.number().nonnegative().max(1e6).optional(),
+  llmOutputTokensPerMin: z.number().nonnegative().max(1e6).optional(),
+  ttsCharsPerMin: z.number().nonnegative().max(1e6).optional(),
+  direction: z.enum(["inbound", "outbound"]).optional(),
+  includeTelephony: z.boolean().optional()
+});
+z.object({
+  mode: PipelineMode.default("cascade"),
+  model: ModelConfig.optional(),
+  // LLM (cascade)
+  voice: VoiceConfig.optional(),
+  // TTS (cascade)
+  stt: SttConfig.optional(),
+  // STT (cascade)
+  realtime: RealtimeConfig.optional(),
+  // realtime
+  assumptions: CostEstimateAssumptions.optional()
+});
+var CostEstimatePerMinute = z.object({
+  llm: z.number().nonnegative(),
+  stt: z.number().nonnegative(),
+  tts: z.number().nonnegative(),
+  realtime: z.number().nonnegative(),
+  telephony: z.number().nonnegative(),
+  total: z.number().nonnegative()
+});
+var CostEstimateBilledPerMinute = z.object({
+  platformFee: z.number().nonnegative(),
+  providerPassthrough: z.number().nonnegative(),
+  telephony: z.number().nonnegative(),
+  allIn: z.number().nonnegative()
+});
+z.object({
+  currency: z.literal("USD"),
+  perMinute: CostEstimatePerMinute,
+  // Present when the server could resolve the project's rate card.
+  billedPerMinute: CostEstimateBilledPerMinute.optional(),
+  // Rough voice-to-voice latency estimate for the chosen pipeline.
+  latencyMs: z.object({
+    estimate: z.number().nonnegative(),
+    realtime: z.boolean()
+  }),
+  // The assumptions actually used (after defaults) — drives the UI footnote.
+  assumptions: CostEstimateAssumptions.required()
+});
+var EvaluationMetric = z.enum(["rating", "binary", "options", "text"]);
+var EvaluationStatus = z.enum(["pending", "scored", "failed"]);
+var EvaluationOption = z.object({
+  value: z.string().min(1).max(64),
+  label: z.string().min(1).max(120),
+  description: z.string().max(400).optional()
+});
+z.object({
+  id: z.string().uuid(),
+  projectId: z.string(),
+  name: z.string().min(1).max(120),
+  criteria: z.string().max(4e3),
+  metric: EvaluationMetric,
+  model: z.string().min(1).max(128),
+  minValue: z.number().int().nullable(),
+  minLabel: z.string().nullable(),
+  maxValue: z.number().int().nullable(),
+  maxLabel: z.string().nullable(),
+  options: z.array(EvaluationOption),
+  enabled: z.boolean(),
+  isDefault: z.boolean(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime()
+});
+var EvaluationInput = z.object({
+  name: z.string().min(1).max(120),
+  criteria: z.string().max(4e3).default(""),
+  metric: EvaluationMetric.default("rating"),
+  model: z.string().min(1).max(128).default("gpt-4o-mini"),
+  minValue: z.number().int().nullable().optional(),
+  minLabel: z.string().max(200).nullable().optional(),
+  maxValue: z.number().int().nullable().optional(),
+  maxLabel: z.string().max(200).nullable().optional(),
+  options: z.array(EvaluationOption).max(12).default([]),
+  enabled: z.boolean().default(true)
+});
+EvaluationInput.partial();
+z.object({
+  id: z.string().uuid(),
+  callId: z.string().uuid(),
+  projectId: z.string(),
+  evaluationId: z.string().uuid(),
+  name: z.string(),
+  metric: EvaluationMetric,
+  status: EvaluationStatus,
+  valueNumber: z.number().nullable(),
+  valueBool: z.boolean().nullable(),
+  valueText: z.string().nullable(),
+  reasoning: z.string().nullable(),
+  model: z.string().nullable(),
+  costUsd: z.number().nullable(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime()
+});
+z.object({
+  status: EvaluationStatus,
+  valueNumber: z.number().nullable(),
+  valueBool: z.boolean().nullable(),
+  valueText: z.string().nullable(),
+  reasoning: z.string().nullable(),
+  costUsd: z.number().nullable(),
+  error: z.string().nullable()
+});
+z.object({
+  evaluationId: z.string().uuid(),
+  name: z.string(),
+  metric: EvaluationMetric,
+  scored: z.number(),
+  average: z.number().nullable(),
+  // rating
+  positiveRate: z.number().nullable(),
+  // binary (fraction true)
+  distribution: z.array(z.object({ value: z.string(), count: z.number() })),
+  // options/text
+  avgCostUsd: z.number().nullable()
+});
+var TestCheckType = z.enum(["response-judge", "routing", "tool-call"]);
+var TestRunStatus = z.enum(["pending", "scored", "failed"]);
+var TestCheckStatus = z.enum(["pass", "fail", "skipped"]);
+z.object({
+  id: z.string().uuid(),
+  projectId: z.string(),
+  name: z.string().min(1).max(120),
+  description: z.string().max(4e3),
+  criteria: z.string().max(4e3),
+  enabled: z.boolean(),
+  isDefault: z.boolean(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime()
+});
+var TestSuiteInput = z.object({
+  name: z.string().min(1).max(120),
+  description: z.string().max(4e3).default(""),
+  criteria: z.string().max(4e3).default(""),
+  enabled: z.boolean().default(true)
+});
+TestSuiteInput.partial();
+var TestRun = z.object({
+  id: z.string().uuid(),
+  projectId: z.string(),
+  testSuiteId: z.string().uuid(),
+  callId: z.string().uuid(),
+  name: z.string(),
+  status: TestRunStatus,
+  reasoning: z.string().nullable(),
+  model: z.string().nullable(),
+  costUsd: z.number().nullable(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime()
+});
+var TestCheck = z.object({
+  id: z.string().uuid(),
+  projectId: z.string(),
+  testRunId: z.string().uuid(),
+  checkType: TestCheckType,
+  turnIndex: z.number().int(),
+  status: TestCheckStatus,
+  input: z.unknown().nullable(),
+  output: z.unknown().nullable(),
+  reasoning: z.string().nullable(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime()
+});
+TestRun.extend({
+  checks: z.array(TestCheck)
+});
+z.object({
+  status: TestRunStatus,
+  reasoning: z.string().nullable(),
+  costUsd: z.number().nullable(),
+  checks: z.array(
+    z.object({
+      checkType: TestCheckType,
+      turnIndex: z.number().int(),
+      status: TestCheckStatus,
+      reasoning: z.string().nullable()
+    })
+  ),
+  error: z.string().nullable()
+});
+z.object({
+  testSuiteId: z.string().uuid(),
+  name: z.string(),
+  runs: z.number(),
+  passed: z.number(),
+  failed: z.number(),
+  passRate: z.number().nullable(),
+  avgCostUsd: z.number().nullable()
+});
+var CallThumb = z.enum(["up", "down"]);
+z.object({
+  callId: z.string().uuid(),
+  projectId: z.string(),
+  thumb: CallThumb.nullable(),
+  note: z.string().nullable(),
+  reviewed: z.boolean(),
+  reviewedBy: z.string().nullable(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime()
+});
+z.object({
+  thumb: CallThumb.nullable().optional(),
+  note: z.string().max(2e3).nullable().optional(),
+  reviewed: z.boolean().optional()
+});
+var ToolExposure = z.enum(["agent", "mcp"]);
+z.object({
+  name: z.string().min(1).max(64).regex(/^[a-z][a-z0-9_]*$/, "snake_case"),
+  // The string that routes the LLM/orchestrator to invoke this tool.
+  description: z.string().min(1).max(2e3),
+  // Zod serialized to JSON Schema at registration time. Persisted as
+  // JSON Schema; SDK and dashboard rehydrate to Zod when needed.
+  inputSchema: z.record(z.unknown()),
+  // When present, the runtime validates the handler's return value.
+  outputSchema: z.record(z.unknown()).optional(),
+  exposedVia: z.array(ToolExposure).min(1),
+  // ── Tool/Plugin SDK (PRD P0.2). All optional for back-compat. ──
+  // Latency class (PRD §4.6.3). Runtime defaults to 'in_call' when omitted.
+  mode: z.enum(["in_call", "async_only"]).optional(),
+  // Hard timeout for an in-call tool (ms).
+  timeoutMs: z.number().int().min(50).max(6e4).optional(),
+  // 'connection' resolves a credential from the vault by `connectionRef`.
+  auth: z.enum(["none", "connection"]).optional(),
+  connectionRef: z.string().max(128).optional(),
+  // Retry policy for safe/async verbs.
+  retry: z.object({
+    maxAttempts: z.number().int().min(1).max(5),
+    backoffMs: z.number().int().min(0).max(6e4)
+  }).optional(),
+  // Normalized result kinds the flow/decision layer branches on (result.kind).
+  resultKinds: z.array(z.string().min(1).max(64)).max(24).optional(),
+  // Free-form dashboard metadata (icon, group, etc.). No `category` enum.
+  metadata: z.record(z.unknown()).optional()
+});
+var TranscriptTurn = z.object({
+  speaker: z.enum(["caller", "agent"]),
+  text: z.string(),
+  startMs: z.number().int().min(0),
+  endMs: z.number().int().min(0)
+});
+var ConsultationAudit = z.object({
+  consultationId: z.string().uuid(),
+  question: z.string(),
+  resolution: z.enum(["guidance", "timeout", "cumulative_cap", "cancelled"]),
+  guidance: z.string().optional(),
+  requestedAt: z.string().datetime(),
+  resolvedAt: z.string().datetime(),
+  latencyMs: z.number().int().min(0)
+});
+var ToolCallAudit = z.object({
+  toolName: z.string(),
+  // Verbatim args the LLM produced. May contain PII — see open question O2
+  // in docs/architecture/contracts-design.md §5.
+  args: z.record(z.unknown()),
+  result: z.unknown(),
+  startedAt: z.string().datetime(),
+  durationMs: z.number().int().min(0),
+  ok: z.boolean(),
+  errorMessage: z.string().optional()
+});
+var McpInteractionAudit = z.object({
+  // One of the four runtime tools — closed set, no growth allowed.
+  tool: z.enum(["call_say", "call_send_guidance", "call_inject_context", "call_instruct"]),
+  // Args verbatim — see open question O2.
+  args: z.record(z.unknown()),
+  ts: z.string().datetime(),
+  // Attribution. The API key that drove the orchestrator session.
+  apiKeyId: z.string()
+});
+z.object({
+  callId: z.string().uuid(),
+  status: z.enum(["completed", "failed"]),
+  startedAt: z.string().datetime(),
+  endedAt: z.string().datetime(),
+  durationMs: z.number().int().min(0),
+  transcript: z.array(TranscriptTurn),
+  // Whatever the agent's process-schema captured. No prescribed shape.
+  structuredOutputs: z.record(z.unknown()).optional(),
+  recordingUrl: z.string().url().optional(),
+  cost: z.object({
+    totalUsd: z.string(),
+    breakdown: z.record(z.string()).optional()
+  }),
+  consultations: z.array(ConsultationAudit),
+  toolCalls: z.array(ToolCallAudit),
+  mcpInteractions: z.array(McpInteractionAudit)
+});
+var PhoneNumberStatus = z.enum([
+  "pending",
+  "active",
+  "releasing",
+  "released",
+  "failed"
+]);
+var PhoneNumberProvider = z.enum(["twilio", "telnyx", "plivo"]);
+var PhoneNumberCapabilities = z.object({
+  voice: z.boolean().optional(),
+  sms: z.boolean().optional(),
+  mms: z.boolean().optional(),
+  fax: z.boolean().optional()
+});
+var PhoneNumberRecord = z.object({
+  id: z.string().uuid(),
+  projectId: z.string(),
+  e164: z.string().regex(/^\+[1-9]\d{1,14}$/),
+  provider: PhoneNumberProvider,
+  // Carrier-side identifiers — sensitive, stripped from PublicPhoneNumber.
+  providerSid: z.string(),
+  providerTrunkSid: z.string().nullable(),
+  voiceRouteId: z.string().nullable(),
+  voiceRouteTrunkId: z.string().nullable(),
+  agentId: z.string().uuid().nullable(),
+  // Environments pin (draft/live). null = no pin → live (today's behaviour).
+  agentConfigEnv: z.enum(["draft", "live"]).nullable(),
+  // "Agent answers texts": the bound agent replies to inbound SMS (burn-down G-1). Off by default.
+  smsAgentReplies: z.boolean(),
+  status: PhoneNumberStatus,
+  friendlyName: z.string().nullable(),
+  region: z.string().nullable(),
+  capabilities: PhoneNumberCapabilities,
+  providerMetadata: z.record(z.unknown()),
+  purchaseIdempotencyKey: z.string().nullable().optional(),
+  purchasedAt: z.string().datetime().nullable(),
+  releasedAt: z.string().datetime().nullable(),
+  createdByUserId: z.string().nullable(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime()
+});
+PhoneNumberRecord.omit({
+  providerSid: true,
+  providerTrunkSid: true,
+  providerMetadata: true,
+  purchaseIdempotencyKey: true
+});
+z.object({
+  phoneNumberId: z.string().uuid(),
+  // null detaches.
+  agentId: z.string().uuid().nullable()
+});
+z.object({ enabled: z.boolean() });
+z.object({
+  consultation: z.object({
+    // Ceiling for ConsultationPolicy.maxTimeoutMs. Project default 90_000.
+    perCallMaxTimeoutMs: z.number().int().min(1e3).default(9e4),
+    // Ceiling for ConsultationPolicy.maxCumulativeHoldMs. Default 300_000.
+    perCallMaxCumulativeMs: z.number().int().min(1e3).default(3e5)
+  })
+});
+var FlowIssueSeverity = z.enum(["error", "warning"]);
+var FlowIssue = z.object({
+  code: z.string().max(64),
+  severity: FlowIssueSeverity,
+  message: z.string().max(500),
+  nodeId: z.string().max(128).optional(),
+  edgeId: z.string().max(128).optional()
+});
+z.object({
+  valid: z.boolean(),
+  issues: z.array(FlowIssue).max(256)
+});
+var ComplianceRule = z.enum(["dnc", "consent", "quiet_hours", "frequency_cap"]);
+var ComplianceDecision = z.enum(["allowed", "blocked"]);
+var ComplianceConfig = z.object({
+  // Local calling window for the CALLED party — TCPA default 8am–9pm.
+  quietHoursStartHour: z.number().int().min(0).max(23).default(8),
+  quietHoursEndHour: z.number().int().min(1).max(24).default(21),
+  enforceDnc: z.boolean().default(true),
+  enforceQuietHours: z.boolean().default(true),
+  // Max dial attempts to one number per rolling 24h. 0 = unlimited.
+  maxAttemptsPerDay: z.number().int().min(0).default(0),
+  // Require a recorded consent flag before dialing.
+  requireConsent: z.boolean().default(false),
+  // Fallback IANA tz when the number's region can't be resolved.
+  fallbackTimeZone: z.string().min(1).default("America/New_York")
+});
+z.object({
+  phoneE164: z.string().regex(/^\+[1-9]\d{1,14}$/, "must be E.164"),
+  // ISO instant the check is evaluated at (defaults to now server-side).
+  now: z.string().datetime().optional(),
+  // Override the resolved timezone (else derived from the number's area code).
+  timeZone: z.string().optional(),
+  // Recent attempt count in the last 24h (for the frequency cap), if known.
+  recentAttempts: z.number().int().min(0).optional(),
+  // Whether consent is on file (for requireConsent).
+  hasConsent: z.boolean().optional()
+});
+z.object({
+  decision: ComplianceDecision,
+  // The first rule that blocked, if any.
+  rule: ComplianceRule.nullable(),
+  reason: z.string().nullable()
+});
+z.object({
+  id: z.string().uuid(),
+  projectId: z.string().min(1),
+  phoneE164: z.string(),
+  reason: z.string().nullable(),
+  source: z.string().nullable(),
+  createdAt: z.string().datetime()
+});
+z.object({
+  id: z.string().uuid(),
+  projectId: z.string().min(1),
+  phoneE164: z.string(),
+  decision: ComplianceDecision,
+  rule: ComplianceRule.nullable(),
+  reason: z.string().nullable(),
+  checkedAt: z.string().datetime()
+});
+z.object({
+  phoneE164: z.string().regex(/^\+[1-9]\d{1,14}$/, "must be E.164"),
+  reason: z.string().max(500).optional(),
+  source: z.string().max(120).optional()
+});
+ComplianceConfig.partial();
+z.object({
+  // When false, the call-event sink skips egress entirely — no recording is made.
+  recordingEnabled: z.boolean().default(true),
+  // Optional consent preamble the agent speaks first on every call. null/empty =
+  // no announcement. Capped so it stays a short notice, not a monologue.
+  consentAnnouncement: z.string().max(1e3).nullable().default(null)
+});
+z.object({
+  recordingEnabled: z.boolean().optional(),
+  consentAnnouncement: z.string().max(1e3).nullable().optional()
+});
+var OutboundAmdMode = z.enum(["off", "detect", "detectMessageEnd"]);
+z.object({
+  // Callee in E.164 (e.g. +14155551234). call-router re-validates strictly.
+  to: z.string().regex(/^\+[1-9]\d{6,14}$/, "must be E.164, e.g. +14155551234"),
+  // Caller-id phone number (must belong to the calling project).
+  phoneNumberId: z.string().min(1),
+  // Optional agent override; falls back to the number's bound agent.
+  agentId: z.string().min(1).optional(),
+  // Template/context variables forwarded to the agent as dispatch metadata.
+  variables: z.record(z.string(), z.string()).optional(),
+  // Per-call AMD override; takes precedence over the agent's stored outbound.amd.
+  amd: OutboundAmdMode.optional()
+});
+var ConnectionAuthType = z.enum(["oauth2", "api_key", "bearer", "basic", "none"]);
+var ConnectionStatus = z.enum(["active", "revoked", "error"]);
+z.object({
+  v: z.number().int(),
+  // Key id (short fingerprint) of the key that encrypted this envelope — lets the
+  // cipher pick the right key from its ring so CREDENTIAL_ENCRYPTION_KEY can rotate
+  // in-band (Tier-1 item 4). Optional/absent on legacy v1 envelopes, which decrypt
+  // with the designated legacy key.
+  kid: z.string().optional(),
+  iv: z.string(),
+  ct: z.string(),
+  tag: z.string()
+});
+z.object({
+  id: z.string().uuid(),
+  projectId: z.string().min(1),
+  name: z.string().min(1).max(128),
+  // Open string — customers name providers freely (e.g. 'google_calendar',
+  // 'salesforce', 'n8n', 'http').
+  provider: z.string().min(1).max(120),
+  authType: ConnectionAuthType,
+  status: ConnectionStatus,
+  // Non-secret metadata (scopes, account label, base URL, …).
+  metadata: z.record(z.unknown()),
+  expiresAt: z.string().datetime().nullable(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime()
+});
+z.object({
+  name: z.string().trim().min(1).max(128),
+  provider: z.string().trim().min(1).max(120),
+  authType: ConnectionAuthType,
+  // The secret material to encrypt at rest. Never stored or returned in plaintext.
+  secret: z.string().min(1).max(8192),
+  metadata: z.record(z.unknown()).optional(),
+  expiresAt: z.string().datetime().optional()
+});
+z.object({
+  name: z.string().trim().min(1).max(128).optional(),
+  // New secret material — re-encrypted at rest; the old envelope is replaced.
+  secret: z.string().min(1).max(8192).optional(),
+  // Merged over the existing metadata (top-level keys win).
+  metadata: z.record(z.unknown()).optional()
+}).refine((v) => v.name !== void 0 || v.secret !== void 0 || v.metadata !== void 0, {
+  message: "nothing to update"
+});
+byokProviders().map((p) => ({
+  id: p.id,
+  label: p.label,
+  keyPlaceholder: p.keyPlaceholder ?? "",
+  supportsBaseUrl: p.supportsBaseUrl
+}));
+var E164 = z.string().regex(/^\+[1-9]\d{6,14}$/, "must be E.164 (+15551234567)");
+var RoomPrefix = z.string().regex(/^[a-z0-9][a-z0-9-]{0,30}[a-z0-9-]?$/, "lowercase letters, digits, dashes; max 32");
+var RecordingPrefix = z.string().min(1).max(128).refine((v) => !v.startsWith("/") && !v.includes(".."), "relative key prefix only");
+var Cidr = z.string().regex(/^\d{1,3}(\.\d{1,3}){3}\/\d{1,2}$/, "must be IPv4 CIDR (a.b.c.d/nn)");
+var TelephonySettings = z.object({
+  outboundTrunkId: z.string().min(1).max(128).nullable().default(null),
+  defaultFromE164: E164.nullable().default(null),
+  roomPrefix: RoomPrefix.nullable().default(null),
+  sipAllowedCidrs: z.array(Cidr).max(32).nullable().default(null),
+  recordingPrefix: RecordingPrefix.nullable().default(null),
+  strictByok: z.boolean().default(false)
+});
+z.object({
+  outboundTrunkId: z.string().min(1).max(128).nullable().optional(),
+  defaultFromE164: E164.nullable().optional(),
+  roomPrefix: RoomPrefix.nullable().optional(),
+  sipAllowedCidrs: z.array(Cidr).max(32).nullable().optional(),
+  recordingPrefix: RecordingPrefix.nullable().optional(),
+  strictByok: z.boolean().optional()
+}).refine((v) => Object.keys(v).length > 0, { message: "nothing to update" });
+var ProfileSource = z.enum(["org", "platform", "none"]);
+var EffectiveCallProfile = z.object({
+  projectId: z.string(),
+  outboundTrunkId: z.string().nullable(),
+  defaultFromE164: z.string().nullable(),
+  roomPrefix: z.string(),
+  sipAllowedCidrs: z.array(z.string()),
+  recordingPrefix: z.string(),
+  strictByok: z.boolean(),
+  sources: z.object({
+    outboundTrunkId: ProfileSource,
+    defaultFromE164: ProfileSource,
+    roomPrefix: ProfileSource,
+    sipAllowedCidrs: ProfileSource,
+    recordingPrefix: ProfileSource
+  })
+});
+z.object({
+  settings: TelephonySettings,
+  profile: EffectiveCallProfile
+});
+var SHORTENER_HOSTS = [
+  "bit.ly",
+  "tinyurl.com",
+  "t.co",
+  "goo.gl",
+  "ow.ly",
+  "is.gd",
+  "buff.ly",
+  "rebrand.ly",
+  "cutt.ly",
+  "shorturl.at",
+  "tiny.cc"
+];
+var PLACEHOLDER_HOSTS = ["acme.com", "example.com", "example.org", "test.com", "localhost"];
+var PublicUrl = z.string().url().refine((v) => v.startsWith("https://"), "must be https").refine((v) => {
+  try {
+    const host = new URL(v).hostname.toLowerCase().replace(/^www\./, "");
+    return !SHORTENER_HOSTS.includes(host);
+  } catch {
+    return false;
+  }
+}, "public URL shorteners are rejected by carriers \u2014 use your own domain").refine((v) => {
+  try {
+    const host = new URL(v).hostname.toLowerCase().replace(/^www\./, "");
+    return !PLACEHOLDER_HOSTS.some((p) => host === p || host.endsWith(`.${p}`));
+  } catch {
+    return false;
+  }
+}, "placeholder domain \u2014 reviewers will follow this link and reject the campaign");
+var A2pBusinessType = z.enum([
+  "Sole Proprietorship",
+  "Partnership",
+  "Corporation",
+  "Co-operative",
+  "Limited Liability Corporation",
+  "Non-profit Corporation"
+]);
+var A2pBusinessInfo = z.object({
+  legalName: z.string().trim().min(2).max(200),
+  /** EIN (US) or equivalent registration number. */
+  registrationNumber: z.string().trim().min(4).max(50),
+  businessType: A2pBusinessType,
+  /** Publicly reachable production site — not staging, not a 404. */
+  website: PublicUrl,
+  industry: z.string().trim().min(2).max(60),
+  address: z.object({
+    street: z.string().trim().min(2).max(200),
+    city: z.string().trim().min(1).max(100),
+    region: z.string().trim().min(1).max(100),
+    postalCode: z.string().trim().min(2).max(20),
+    isoCountry: z.string().trim().length(2)
+  }),
+  authorizedRep: z.object({
+    firstName: z.string().trim().min(1).max(100),
+    lastName: z.string().trim().min(1).max(100),
+    email: z.string().trim().email(),
+    phone: z.string().trim().regex(/^\+[1-9]\d{6,14}$/, "must be E.164"),
+    jobTitle: z.string().trim().min(2).max(100)
+  })
+});
+var A2pOptInType = z.enum(["WEB_FORM", "PAPER_FORM", "VERBAL", "VIA_TEXT", "MOBILE_QR_CODE"]);
+var A2pUseCase = z.enum([
+  "MIXED",
+  "CUSTOMER_CARE",
+  "MARKETING",
+  "ACCOUNT_NOTIFICATION",
+  "2FA",
+  "DELIVERY_NOTIFICATION",
+  "HIGHER_EDUCATION",
+  "POLLING_VOTING",
+  "PUBLIC_SERVICE_ANNOUNCEMENT",
+  "LOW_VOLUME"
+]);
+var A2pMessagingProfile = z.object({
+  useCase: A2pUseCase,
+  /** Specific, not generic. "We send texts" gets rejected; describe the actual
+   *  messages and when they are sent. */
+  description: z.string().trim().min(40).max(4096),
+  /**
+   * The single most-rejected field. Must describe HOW people opt in, state the
+   * message frequency, include the "message and data rates may apply"
+   * disclosure, and link to publicly reachable evidence. Twilio's API bounds it
+   * to 40–2049 characters.
+   */
+  messageFlow: z.string().trim().min(40).max(2049),
+  optInType: A2pOptInType,
+  /** Publicly accessible screenshots/pages showing the opt-in. Reviewers open
+   *  these; anything behind a login fails. */
+  optInEvidenceUrls: z.array(PublicUrl).min(1).max(5),
+  /** Real messages the customer will send. Must reflect the declared use case
+   *  and carry opt-out language. */
+  messageSamples: z.array(z.string().trim().min(10).max(1024)).min(2).max(5),
+  privacyPolicyUrl: PublicUrl,
+  termsAndConditionsUrl: PublicUrl,
+  hasEmbeddedLinks: z.boolean().default(false),
+  hasEmbeddedPhone: z.boolean().default(false)
+});
+z.object({
+  business: A2pBusinessInfo,
+  messaging: A2pMessagingProfile,
+  /** Register against Twilio's mock endpoints — exercises the full pipeline
+   *  with no fees and no real carrier submission. Used in CI and staging. */
+  mock: z.boolean().default(false)
+}).superRefine((v, ctx) => {
+  const flow = v.messaging.messageFlow.toLowerCase();
+  if (!/(msg|message)\s*(&|and)\s*data rates/.test(flow)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["messaging", "messageFlow"],
+      message: 'must include a "Message and data rates may apply" disclosure \u2014 carriers reject without it'
+    });
+  }
+  if (!/\d/.test(flow) || !/(msg|message|text)/.test(flow)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["messaging", "messageFlow"],
+      message: 'must state message frequency, e.g. "Up to 4 msgs/month"'
+    });
+  }
+  const hasOptOut = v.messaging.messageSamples.some((s) => /stop/i.test(s));
+  if (!hasOptOut) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["messaging", "messageSamples"],
+      message: 'at least one sample must include opt-out language (e.g. "Reply STOP to opt out")'
+    });
+  }
+});
+var A2pState = z.enum([
+  "none",
+  "profile_pending",
+  "profile_approved",
+  "profile_failed",
+  "brand_pending",
+  "brand_approved",
+  "brand_failed",
+  "campaign_pending",
+  "messaging_ready",
+  "campaign_failed"
+]);
+z.object({
+  state: A2pState,
+  customerProfileSid: z.string().nullable(),
+  trustProductSid: z.string().nullable(),
+  brandSid: z.string().nullable(),
+  messagingServiceSid: z.string().nullable(),
+  campaignSid: z.string().nullable(),
+  mock: z.boolean(),
+  /** Carrier/Twilio rejection details, surfaced verbatim so the customer can
+   *  fix the specific field rather than guess. */
+  failures: z.array(z.object({ code: z.number().nullable(), field: z.string().nullable(), message: z.string() })).default([]),
+  /** Plain-language next step for the dashboard. */
+  nextAction: z.string().nullable(),
+  updatedAt: z.string().nullable()
+});
+var ConnectorMode = z.enum(["tunnel", "direct"]);
+var ConnectorStatus = z.enum(["online", "degraded", "offline"]);
+var ConnectorNormalize = z.enum(["auto", "on", "off"]);
+z.object({
+  id: z.string().uuid(),
+  projectId: z.string().min(1),
+  name: z.string().min(1).max(128),
+  mode: ConnectorMode,
+  // Tunnel mode: a short non-secret preview of the daemon token. Null for direct.
+  tokenPreview: z.string().nullable(),
+  // Direct mode: the connections-vault row holding the URL + key. Null for tunnel.
+  connectionId: z.string().uuid().nullable(),
+  // Upstream model id / alias. Null → the brain's own default.
+  defaultModel: z.string().nullable(),
+  normalize: ConnectorNormalize,
+  enabled: z.boolean(),
+  status: ConnectorStatus,
+  lastSeenAt: z.string().datetime().nullable(),
+  metadata: z.record(z.unknown()),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime()
+});
+z.object({
+  name: z.string().trim().min(1).max(128),
+  mode: ConnectorMode,
+  // Required when mode === 'direct': the vault connection holding URL + key.
+  connectionId: z.string().uuid().optional(),
+  defaultModel: z.string().trim().min(1).max(200).optional(),
+  normalize: ConnectorNormalize.optional(),
+  metadata: z.record(z.unknown()).optional()
+});
+z.object({
+  name: z.string().trim().min(1).max(128).optional(),
+  connectionId: z.string().uuid().nullable().optional(),
+  defaultModel: z.string().trim().min(1).max(200).nullable().optional(),
+  normalize: ConnectorNormalize.optional(),
+  enabled: z.boolean().optional()
+});
+var CONNECTOR_REQUEST_CHANNEL = (connectorId) => `brain-req:${connectorId}`;
+var CONNECTOR_REPLY_CHANNEL = (streamId) => `brain-reply:${streamId}`;
+var BrainWireMessage = z.object({
+  role: z.enum(["system", "user", "assistant"]),
+  content: z.string()
+});
+var HelloFrame = z.object({
+  kind: z.literal("hello"),
+  token: z.string().min(1),
+  replicaId: z.string().min(1),
+  version: z.string().min(1),
+  caps: z.object({ streaming: z.boolean(), tools: z.boolean(), litellm: z.boolean() })
+});
+var PongFrame = z.object({ kind: z.literal("pong"), ts: z.number().int() });
+var RegisteredFrame = z.object({
+  kind: z.literal("registered"),
+  connectorId: z.string().uuid(),
+  projectId: z.string().min(1)
+});
+var PingFrame = z.object({ kind: z.literal("ping"), ts: z.number().int() });
+var ShutdownFrame = z.object({ kind: z.literal("shutdown"), reason: z.string().optional() });
+var BrainRequestFrame = z.object({
+  kind: z.literal("brain.request"),
+  streamId: z.string().min(1),
+  model: z.string().optional(),
+  temperature: z.number().optional(),
+  messages: z.array(BrainWireMessage)
+});
+var BrainCancelFrame = z.object({
+  kind: z.literal("brain.cancel"),
+  streamId: z.string().min(1)
+});
+var BrainDeltaFrame = z.object({
+  kind: z.literal("brain.delta"),
+  streamId: z.string().min(1),
+  content: z.string()
+});
+var BrainDoneFrame = z.object({
+  kind: z.literal("brain.done"),
+  streamId: z.string().min(1),
+  finishReason: z.string()
+});
+var BrainErrorFrame = z.object({
+  kind: z.literal("brain.error"),
+  streamId: z.string().min(1),
+  code: z.enum([
+    "upstream_timeout",
+    "upstream_error",
+    "bad_response",
+    "normalize_failed",
+    "unreachable"
+  ]),
+  message: z.string()
+});
+var ConnectorUpFrame = z.discriminatedUnion("kind", [
+  HelloFrame,
+  PongFrame,
+  BrainDeltaFrame,
+  BrainDoneFrame,
+  BrainErrorFrame
+]);
+z.discriminatedUnion("kind", [
+  RegisteredFrame,
+  PingFrame,
+  ShutdownFrame,
+  BrainRequestFrame,
+  BrainCancelFrame
+]);
+var EnvironmentSpec = z.enum(["draft", "live"]);
+z.object({
+  agentName: z.string().min(1),
+  draftPercent: z.number().int().min(0).max(100),
+  livePercent: z.number().int().min(0).max(100)
+});
+z.object({
+  draftPercent: z.number().int().min(0).max(100),
+  livePercent: z.number().int().min(0).max(100).optional()
+}).refine(
+  (v) => v.livePercent === void 0 || v.draftPercent + v.livePercent === 100,
+  { message: "draftPercent + livePercent must equal 100" }
+);
+z.object({
+  env: EnvironmentSpec.nullable()
+});
+var VariableType = z.enum(["string", "number", "boolean", "json"]);
+var VariableScope = z.enum(["project", "user"]);
+var VariableName = z.string().min(1).max(64).regex(
+  /^[A-Za-z_][A-Za-z0-9_]*$/,
+  "must be a valid identifier (letters, digits, underscore; no leading digit)"
+);
+z.object({
+  id: z.string().uuid(),
+  projectId: z.string(),
+  name: VariableName,
+  type: VariableType,
+  // Stored as text; interpreted per `type`. null = no default (renders '').
+  defaultValue: z.string().nullable(),
+  description: z.string().max(280).nullable(),
+  scope: VariableScope,
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime()
+});
+z.object({
+  name: VariableName,
+  type: VariableType.default("string"),
+  defaultValue: z.string().nullable().optional(),
+  description: z.string().max(280).nullable().optional(),
+  scope: VariableScope.default("project")
+});
+z.object({
+  type: VariableType.optional(),
+  defaultValue: z.string().nullable().optional(),
+  description: z.string().max(280).nullable().optional(),
+  scope: VariableScope.optional()
+}).refine((b) => Object.keys(b).length > 0, { message: "no fields to update" });
+var PlaybookExitCondition = z.object({
+  name: z.string().min(1).max(64),
+  description: z.string().max(2e3),
+  requiredVariables: z.array(z.string().min(1).max(64)).max(32)
+});
+z.object({
+  id: z.string(),
+  projectId: z.string(),
+  name: z.string().min(1).max(120),
+  // Routing signal — "what it does AND when to use it" (read by the agent router).
+  llmDescription: z.string().max(2e3),
+  instructions: z.string().max(2e4),
+  // Model overrides (null = inherit the agent's). Exactly 3 knobs, no top-p/penalties.
+  model: z.string().max(120).nullable(),
+  temperature: z.number().min(0).max(2).nullable(),
+  maxTokens: z.number().int().positive().max(32e3).nullable(),
+  // Registry HTTP tools (by name) this playbook may call. With tools the
+  // playbook runs as an agent loop (LLM-with-tools + structured exit).
+  tools: z.array(z.string().min(1).max(128)).max(64).default([]),
+  exitConditions: z.array(PlaybookExitCondition).max(24),
+  createdAt: z.string(),
+  updatedAt: z.string()
+});
+z.object({
+  name: z.string().min(1).max(120),
+  llmDescription: z.string().max(2e3).default(""),
+  instructions: z.string().max(2e4).default(""),
+  model: z.string().max(120).nullable().optional(),
+  temperature: z.number().min(0).max(2).nullable().optional(),
+  maxTokens: z.number().int().positive().max(32e3).nullable().optional(),
+  tools: z.array(z.string().min(1).max(128)).max(64).default([]),
+  exitConditions: z.array(PlaybookExitCondition).max(24).default([])
+});
+z.object({
+  name: z.string().min(1).max(120),
+  llmDescription: z.string().max(2e3),
+  instructions: z.string().max(2e4),
+  model: z.string().max(120).nullable(),
+  temperature: z.number().min(0).max(2).nullable(),
+  maxTokens: z.number().int().positive().max(32e3).nullable(),
+  tools: z.array(z.string().min(1).max(128)).max(64),
+  exitConditions: z.array(PlaybookExitCondition).max(24)
+}).partial().refine((b) => Object.keys(b).length > 0, { message: "at least one field required" });
+var PlaybookSnapshot = z.object({
+  name: z.string().min(1).max(120),
+  llmDescription: z.string().max(2e3),
+  instructions: z.string().max(2e4),
+  model: z.string().max(120).nullable(),
+  temperature: z.number().min(0).max(2).nullable(),
+  maxTokens: z.number().int().positive().max(32e3).nullable(),
+  // Registry tool names frozen with the snapshot (default keeps old rows valid).
+  tools: z.array(z.string().min(1).max(128)).max(64).default([]),
+  exitConditions: z.array(PlaybookExitCondition).max(24)
+});
+z.object({
+  id: z.string(),
+  playbookId: z.string(),
+  projectId: z.string(),
+  version: z.number().int().min(1),
+  // Frozen playbook definition at publish time.
+  definition: PlaybookSnapshot,
+  note: z.string().max(1e3).nullable(),
+  publishedByUserId: z.string().nullable(),
+  publishedAt: z.string()
+});
+z.object({
+  note: z.string().max(1e3).optional()
+});
+var EngineSeamBinding = z.object({
+  key: z.string(),
+  bound: z.boolean()
+});
+var EnginePluginDTO = z.object({
+  name: z.string(),
+  provides: z.array(EngineSeamBinding),
+  injects: z.array(z.string())
+});
+z.object({
+  plugins: z.array(EnginePluginDTO)
+});
+
+// ../contracts/src/channel-connector/capability-state.ts
+var CONDITION_CLASSES = ["authority", "operational", "observability"];
+var CONDITION_TYPES = [
+  { id: "CredentialsValid", defaultClass: "authority", summary: "credential lease resolves and is not expired/revoked" },
+  { id: "ProviderAccountGood", defaultClass: "authority", summary: "provider account / sender standing is not suspended or restricted" },
+  { id: "RegistrationApproved", defaultClass: "authority", summary: "required registration / approval is current" },
+  { id: "ResourceOwnershipConfirmed", defaultClass: "authority", summary: "the native object is confirmed to belong to this principal" },
+  { id: "InstallationPresent", defaultClass: "authority", summary: "the container installation exists and is not revoked" },
+  { id: "PermissionsHeld", defaultClass: "authority", summary: "required provider permissions/scopes/intents are held" },
+  { id: "ConsentResolved", defaultClass: "authority", summary: "consent verdict available (ch. 02; not_evaluated until it ships)" },
+  { id: "WindowOpen", defaultClass: "authority", summary: "the reply window for the peer is open" },
+  { id: "TemplateAvailable", defaultClass: "authority", summary: "an approved template exists for the operation" },
+  { id: "PeerReachable", defaultClass: "authority", summary: "the peer can be reached on this channel (e.g. RCS capability, not blocked)" },
+  { id: "WebhookRegistered", defaultClass: "operational", summary: "the provider has our ingress registered" },
+  { id: "InboundVerificationReady", defaultClass: "authority", summary: "the material the declared inbound-auth strategy needs (for the selected authorization method) resolves \u2014 REST auth alone never satisfies it (#306 L4)" },
+  { id: "WebhookHealthy", defaultClass: "operational", summary: "recent verified inbound / delivery health" },
+  { id: "TransportConnected", defaultClass: "operational", summary: "a transport lease is live (gateway / long-poll / pub-sub)" },
+  { id: "ReconcileFresh", defaultClass: "operational", summary: "the last reconcile is within its window" },
+  { id: "ProviderLatency", defaultClass: "observability", summary: "provider latency / error-rate telemetry" }
+];
+new Set(CONDITION_TYPES.map((c) => c.id));
+var SURFACES = ["direct", "group", "channel", "thread", "broadcast"];
+var TRANSPORT_KINDS = ["webhook", "long_poll", "gateway", "pubsub", "http_interactions"];
+var AGENT_INITIATION = ["always", "installed_only", "opt_in_required", "template_only", "never"];
+var TEMPLATE_REQUIREMENT = ["never", "outside_window", "always"];
+var WINDOW_OUTSIDE = ["tagged_only", "template_only", "blocked"];
+var PEER_ID_SCOPES = ["global", "app_scoped", "workspace_scoped", "installation_scoped"];
+var RECEIPT_KINDS = ["sent", "delivered", "read", "failed"];
+
+// ../contracts/src/channel-connector/channels.ts
+var TEXT_ONLY = ["text"];
+var RICH_MESSAGING = ["text", "image", "audio", "video", "document", "location", "contact", "sticker", "reaction", "interactive", "template"];
+function baseline(channel, partial) {
+  return {
+    channel,
+    connector: null,
+    version: "1.0",
+    requiredPermissions: [],
+    registration: [],
+    readinessGates: [
+      { condition: "CredentialsValid", class: "authority", blocks: "*", ttlSec: 300 },
+      { condition: "ProviderAccountGood", class: "authority", blocks: "*", ttlSec: 3600 },
+      { condition: "WebhookHealthy", class: "operational", blocks: ["receive.message", "call.receive"], ttlSec: 900, evidence: "runtime" }
+    ],
+    ...partial
+  };
+}
+var MESSAGE_CORE = ["receive.message", "send.text", "send.media", "initiate.conversation", "reply.in_window"];
+var CONTAINER_GATES = [
+  { condition: "CredentialsValid", class: "authority", blocks: "*", ttlSec: 300 },
+  { condition: "InstallationPresent", class: "authority", blocks: "*", ttlSec: 3600 },
+  { condition: "PermissionsHeld", class: "authority", blocks: ["send.text", "send.media", "channel.post", "thread.reply", "group.post"], ttlSec: 3600 },
+  { condition: "WebhookHealthy", class: "operational", blocks: ["receive.message"], ttlSec: 900, evidence: "runtime" }
+];
+var CHANNELS = [
+  {
+    id: "sms",
+    displayName: "SMS",
+    addressSpace: "phone",
+    surfaces: ["direct"],
+    bindingCapabilities: ["sms"],
+    baseline: baseline("sms", {
+      operations: [...MESSAGE_CORE, "read.receipt"],
+      direction: { inbound: true, outbound: true },
+      initiation: { agentInitiated: "always", userInitiated: true, firstContactRule: "agent-initiated with registration (10DLC / TFV per country); STOP/HELP keywords mandatory" },
+      windows: [],
+      templates: { required: "never", reviewed: false },
+      surfaces: ["direct"],
+      messageTypes: TEXT_ONLY,
+      // GSM-7 160/153, UCS-2 70/67 per segment (doc 01 §3); no body cap is a channel fact.
+      limits: { segments: true, note: "GSM-7 160/153 \xB7 UCS-2 70/67 per segment" },
+      receipts: ["sent", "delivered", "failed"],
+      edits: { edit: false, delete: false, reactions: false, commands: false },
+      transport: ["webhook"],
+      identity: { peerIdKind: "phone", peerIdScope: "global" },
+      registration: [{ kind: "campaign_vetting", blocks: ["send.text", "send.media", "initiate.conversation"] }]
+    })
+  },
+  {
+    id: "mms",
+    displayName: "MMS",
+    addressSpace: "phone",
+    surfaces: ["direct", "group"],
+    bindingCapabilities: ["mms"],
+    baseline: baseline("mms", {
+      operations: [...MESSAGE_CORE, "group.post"],
+      direction: { inbound: true, outbound: true },
+      initiation: { agentInitiated: "always", userInitiated: true, firstContactRule: "as SMS; carrier MMS size caps apply" },
+      windows: [],
+      templates: { required: "never", reviewed: false },
+      surfaces: ["direct", "group"],
+      messageTypes: ["text", "image", "audio", "video", "document"],
+      limits: { mediaBytes: 1e6, note: "carrier MMS \u22480.6\u20131 MB (doc 01 \xA73)" },
+      receipts: ["sent", "delivered", "failed"],
+      edits: { edit: false, delete: false, reactions: false, commands: false },
+      transport: ["webhook"],
+      identity: { peerIdKind: "phone", peerIdScope: "global" },
+      registration: [{ kind: "campaign_vetting", blocks: ["send.text", "send.media", "initiate.conversation"] }]
+    })
+  },
+  {
+    id: "voice",
+    displayName: "Voice (PSTN)",
+    addressSpace: "phone",
+    surfaces: ["direct"],
+    bindingCapabilities: ["voice"],
+    baseline: baseline("voice", {
+      operations: ["call.receive", "call.place"],
+      direction: { inbound: true, outbound: true },
+      initiation: { agentInitiated: "always", userInitiated: true, firstContactRule: "agent-initiated; STIR/SHAKEN attestation; emergency addressing; trunk config" },
+      windows: [],
+      templates: { required: "never", reviewed: false },
+      surfaces: ["direct"],
+      messageTypes: [],
+      limits: {},
+      receipts: [],
+      edits: { edit: false, delete: false, reactions: false, commands: false },
+      transport: ["webhook"],
+      identity: { peerIdKind: "phone", peerIdScope: "global" }
+    })
+  },
+  {
+    id: "whatsapp",
+    displayName: "WhatsApp",
+    addressSpace: "whatsapp",
+    surfaces: ["direct", "group"],
+    bindingCapabilities: ["whatsapp.message"],
+    baseline: baseline("whatsapp", {
+      operations: [...MESSAGE_CORE, "send.template", "send.interactive", "send.reaction", "read.receipt", "typing.indicate"],
+      direction: { inbound: true, outbound: true },
+      initiation: { agentInitiated: "template_only", userInitiated: true, firstContactRule: "user-initiated or a reviewed template outside the 24-h window; opt-in mandatory" },
+      windows: [{ kind: "reply", durationSec: 86400, opensOn: "inbound_message", outside: "template_only" }],
+      templates: { required: "outside_window", reviewed: true },
+      surfaces: ["direct", "group"],
+      messageTypes: RICH_MESSAGING,
+      limits: {
+        textChars: 4096,
+        mediaBytes: 1e8,
+        perSecond: 80,
+        formats: { audio: { mime: ["audio/ogg", "audio/mpeg", "audio/mp4", "audio/aac", "audio/amr"], variants: ["voice_note", "file"] } }
+      },
+      receipts: ["sent", "delivered", "read", "failed"],
+      edits: { edit: false, delete: false, reactions: true, commands: false },
+      transport: ["webhook"],
+      identity: { peerIdKind: "whatsapp", peerIdScope: "global" },
+      registration: [{ kind: "business_verification", blocks: ["initiate.conversation", "send.template"] }]
+    })
+  },
+  {
+    id: "instagram",
+    displayName: "Instagram DM",
+    addressSpace: "app",
+    surfaces: ["direct"],
+    bindingCapabilities: ["instagram.message"],
+    baseline: baseline("instagram", {
+      operations: ["receive.message", "send.text", "send.media", "send.reaction", "reply.in_window", "delete.message", "read.receipt"],
+      direction: { inbound: true, outbound: true },
+      initiation: { agentInitiated: "never", userInitiated: true, firstContactRule: "user-initiated only \u2014 the peer identifier exists only after the user messages or clicks" },
+      windows: [{ kind: "reply", durationSec: 86400, opensOn: "inbound_message", outside: "tagged_only" }],
+      templates: { required: "never", reviewed: false },
+      surfaces: ["direct"],
+      messageTypes: ["text", "image", "audio", "video", "document", "sticker", "reaction", "interactive", "template"],
+      limits: { textBytes: 1e3, mediaBytes: 25e6 },
+      receipts: ["read"],
+      edits: { edit: false, delete: true, reactions: true, commands: false },
+      transport: ["webhook"],
+      // doc 07 §3: per person × professional account, stable across apps — the
+      // account scope is embedded in the normalized value, so the id is global.
+      identity: { peerIdKind: "meta_account_user", peerIdScope: "global" },
+      registration: [{ kind: "app_review", blocks: ["send.text", "send.media"] }]
+    })
+  },
+  {
+    id: "messenger",
+    displayName: "Messenger",
+    addressSpace: "app",
+    surfaces: ["direct"],
+    bindingCapabilities: ["messenger.message"],
+    baseline: baseline("messenger", {
+      operations: ["receive.message", "send.text", "send.media", "send.reaction", "reply.in_window", "edit.message", "read.receipt", "typing.indicate"],
+      direction: { inbound: true, outbound: true },
+      initiation: { agentInitiated: "never", userInitiated: true, firstContactRule: "as Instagram plus Get Started / link / ads entry points" },
+      windows: [{ kind: "reply", durationSec: 86400, opensOn: "inbound_message", outside: "tagged_only" }],
+      templates: { required: "never", reviewed: false },
+      surfaces: ["direct"],
+      messageTypes: RICH_MESSAGING,
+      limits: { mediaBytes: 25e6 },
+      receipts: ["delivered", "read"],
+      edits: { edit: true, delete: false, reactions: true, commands: false },
+      transport: ["webhook"],
+      identity: { peerIdKind: "meta_account_user", peerIdScope: "global" },
+      registration: [{ kind: "app_review", blocks: ["send.text", "send.media"] }]
+    })
+  },
+  {
+    id: "telegram",
+    displayName: "Telegram",
+    addressSpace: "app",
+    surfaces: ["direct", "group", "channel", "thread"],
+    bindingCapabilities: ["telegram.message"],
+    baseline: baseline("telegram", {
+      operations: [...MESSAGE_CORE, "send.interactive", "send.reaction", "edit.message", "delete.message", "command.register", "group.post", "channel.post", "thread.reply"],
+      direction: { inbound: true, outbound: true },
+      // Plain bot: the user must start; no reply window. The business-account
+      // 24-h rule is an installation-level narrowing, not the channel ceiling.
+      initiation: { agentInitiated: "never", userInitiated: true, firstContactRule: "the user must start the bot (/start, deep link, group add) before it may message them" },
+      windows: [],
+      templates: { required: "never", reviewed: false },
+      surfaces: ["direct", "group", "channel", "thread"],
+      messageTypes: ["text", "image", "audio", "video", "document", "location", "contact", "sticker", "reaction", "interactive", "poll"],
+      limits: { textChars: 4096, mediaBytes: 5e7, formats: { audio: { mime: ["audio/ogg", "audio/mpeg"], variants: ["voice_note", "file"] } } },
+      receipts: [],
+      edits: { edit: true, delete: true, reactions: true, commands: true },
+      transport: ["webhook", "long_poll"],
+      identity: { peerIdKind: "telegram_user", peerIdScope: "global" }
+    })
+  },
+  {
+    id: "discord",
+    displayName: "Discord",
+    addressSpace: "app",
+    surfaces: ["direct", "group", "channel", "thread"],
+    bindingCapabilities: ["discord.message", "discord.command"],
+    baseline: baseline("discord", {
+      // The channel exposes BOTH modes (doc 04 §1): text via `send.*`, realtime
+      // audio via `call.*`. Mode is per OPERATION — the channel id never implies it.
+      operations: [...MESSAGE_CORE, "send.interactive", "send.reaction", "edit.message", "delete.message", "command.register", "channel.post", "thread.reply", "call.receive", "call.place"],
+      direction: { inbound: true, outbound: true },
+      initiation: { agentInitiated: "installed_only", userInitiated: true, firstContactRule: "guild channels by permission; DMs need a mutual guild or a user install" },
+      windows: [],
+      templates: { required: "never", reviewed: false },
+      surfaces: ["direct", "group", "channel", "thread"],
+      messageTypes: ["text", "image", "audio", "video", "document", "reaction", "interactive", "card", "poll"],
+      limits: { textChars: 2e3, mediaBytes: 10485760 },
+      receipts: [],
+      edits: { edit: true, delete: true, reactions: true, commands: true },
+      transport: ["gateway", "http_interactions"],
+      identity: { peerIdKind: "discord_user", peerIdScope: "global" },
+      readinessGates: [
+        { condition: "CredentialsValid", class: "authority", blocks: "*", ttlSec: 300 },
+        { condition: "InstallationPresent", class: "authority", blocks: "*", ttlSec: 3600 },
+        { condition: "PermissionsHeld", class: "authority", blocks: ["send.text", "send.media", "channel.post", "thread.reply", "call.receive", "call.place"], ttlSec: 3600 },
+        { condition: "TransportConnected", class: "operational", blocks: ["receive.message", "call.receive"], ttlSec: 120 }
+      ]
+    })
+  },
+  {
+    // G-3: the embeddable website chat widget. The widget key IS the identity and its evidence (a `web`-space Binding
+    // at `widget:<keyId>`, no provider connection), so no provider readiness gate applies. The agent only ever answers
+    // inside the visitor's own request — it never starts or pushes a message.
+    id: "web",
+    displayName: "Website chat",
+    addressSpace: "web",
+    surfaces: ["direct"],
+    bindingCapabilities: ["web.message"],
+    baseline: baseline("web", {
+      operations: ["receive.message", "reply.in_window"],
+      direction: { inbound: true, outbound: true },
+      initiation: { agentInitiated: "never", userInitiated: true, firstContactRule: "the visitor opens the widget and writes first" },
+      windows: [],
+      templates: { required: "never", reviewed: false },
+      surfaces: ["direct"],
+      messageTypes: TEXT_ONLY,
+      limits: { textChars: 8e3 },
+      receipts: [],
+      edits: { edit: false, delete: false, reactions: false, commands: false },
+      transport: ["http_interactions"],
+      identity: { peerIdKind: "web_visitor", peerIdScope: "app_scoped" },
+      readinessGates: []
+    })
+  },
+  {
+    id: "slack",
+    displayName: "Slack",
+    addressSpace: "app",
+    surfaces: ["direct", "group", "channel", "thread"],
+    bindingCapabilities: ["slack.message"],
+    baseline: baseline("slack", {
+      operations: [...MESSAGE_CORE, "send.interactive", "send.reaction", "edit.message", "delete.message", "command.register", "channel.post", "thread.reply"],
+      direction: { inbound: true, outbound: true },
+      initiation: { agentInitiated: "installed_only", userInitiated: true, firstContactRule: "any channel the bot is in; DMs" },
+      windows: [],
+      templates: { required: "never", reviewed: false },
+      surfaces: ["direct", "group", "channel", "thread"],
+      messageTypes: ["text", "image", "audio", "video", "document", "reaction", "interactive", "card"],
+      limits: { textChars: 4e3, note: "truncated at 40,000 (doc 01 \xA73)" },
+      receipts: [],
+      edits: { edit: true, delete: true, reactions: true, commands: true },
+      transport: ["webhook", "gateway"],
+      identity: { peerIdKind: "slack_user", peerIdScope: "workspace_scoped" },
+      readinessGates: CONTAINER_GATES
+    })
+  },
+  {
+    id: "teams",
+    displayName: "Microsoft Teams",
+    addressSpace: "app",
+    surfaces: ["direct", "group", "channel", "thread"],
+    bindingCapabilities: ["teams.message"],
+    baseline: baseline("teams", {
+      operations: [...MESSAGE_CORE, "send.interactive", "edit.message", "delete.message", "channel.post", "thread.reply", "read.receipt"],
+      direction: { inbound: true, outbound: true },
+      initiation: { agentInitiated: "installed_only", userInitiated: true, firstContactRule: "proactive send needs an installation in scope plus a conversation reference" },
+      windows: [],
+      templates: { required: "never", reviewed: false },
+      surfaces: ["direct", "group", "channel", "thread"],
+      messageTypes: ["text", "image", "document", "card", "interactive", "reaction"],
+      limits: { textBytes: 102400, note: "message payload \u2264100 KB (doc 01 \xA73)" },
+      receipts: ["read"],
+      edits: { edit: true, delete: true, reactions: false, commands: false },
+      transport: ["webhook"],
+      identity: { peerIdKind: "teams_user", peerIdScope: "installation_scoped" },
+      readinessGates: CONTAINER_GATES
+    })
+  },
+  {
+    id: "rcs",
+    displayName: "RCS",
+    addressSpace: "rcs",
+    surfaces: ["direct"],
+    bindingCapabilities: ["rcs.message"],
+    baseline: baseline("rcs", {
+      operations: [...MESSAGE_CORE, "send.interactive", "read.receipt", "typing.indicate", "delete.message"],
+      direction: { inbound: true, outbound: true },
+      initiation: { agentInitiated: "opt_in_required", userInitiated: true, firstContactRule: "agent-initiated only with consent per AUP; STOP / UNSUBSCRIBE brand-wide" },
+      windows: [],
+      templates: { required: "never", reviewed: false },
+      surfaces: ["direct"],
+      messageTypes: ["text", "image", "audio", "video", "document", "card", "carousel", "interactive"],
+      limits: { textChars: 3072, mediaBytes: 104857600 },
+      receipts: ["delivered", "read"],
+      edits: { edit: false, delete: true, reactions: false, commands: false },
+      transport: ["webhook"],
+      identity: { peerIdKind: "phone", peerIdScope: "global" },
+      registration: [{ kind: "agent_launch", blocks: ["send.text", "send.media", "send.interactive", "initiate.conversation"] }],
+      readinessGates: [
+        { condition: "CredentialsValid", class: "authority", blocks: "*", ttlSec: 300 },
+        { condition: "RegistrationApproved", class: "authority", blocks: ["send.text", "send.media", "send.interactive", "initiate.conversation"], ttlSec: 86400 },
+        { condition: "PeerReachable", class: "authority", blocks: ["send.text", "send.media", "send.interactive", "initiate.conversation"], ttlSec: 86400 },
+        { condition: "WebhookHealthy", class: "operational", blocks: ["receive.message"], ttlSec: 900, evidence: "runtime" }
+      ]
+    })
+  }
+];
+new Map(CHANNELS.map((c) => [c.id, c]));
+var CHANNEL_IDS = new Set(CHANNELS.map((c) => c.id));
+
+// ../contracts/src/channel-connector/operations.ts
+var OPERATION_MODES = ["message", "realtime"];
+var OPERATIONS = [
+  { id: "receive.message", mode: "message", summary: "accept an inbound message" },
+  { id: "send.text", mode: "message", summary: "send a text message" },
+  { id: "send.media", mode: "message", summary: "send a message carrying a content item (image, audio, video, document)" },
+  { id: "send.template", mode: "message", summary: "send a reviewed template" },
+  { id: "send.interactive", mode: "message", summary: "send structured/interactive content" },
+  { id: "send.reaction", mode: "message", summary: "react to a message" },
+  { id: "edit.message", mode: "message", summary: "edit a sent message" },
+  { id: "delete.message", mode: "message", summary: "delete a sent message" },
+  { id: "initiate.conversation", mode: "message", summary: "first contact / outside any window" },
+  { id: "reply.in_window", mode: "message", summary: "reply inside an open window" },
+  { id: "call.receive", mode: "realtime", summary: "accept an inbound realtime session" },
+  { id: "call.place", mode: "realtime", summary: "place an outbound realtime session" },
+  { id: "read.receipt", mode: "message", summary: "mark a message as read" },
+  { id: "typing.indicate", mode: "message", summary: "typing indicator" },
+  { id: "command.register", mode: "message", summary: "register slash/bot commands" },
+  { id: "thread.reply", mode: "message", summary: "reply inside a thread" },
+  { id: "group.post", mode: "message", summary: "post to a group surface" },
+  { id: "channel.post", mode: "message", summary: "post to a channel surface" }
+];
+new Map(
+  OPERATIONS.map((op) => [op.id, op])
+);
+var OPERATION_IDS = new Set(OPERATIONS.map((op) => op.id));
+
+// ../contracts/src/channel-connector/ids.ts
+var A2_SHIPPED_ROOTS = [
+  "llm",
+  "conversation",
+  "channels",
+  "tools",
+  "guard",
+  "store",
+  "compliance",
+  "carriers",
+  "agents",
+  "agentRun",
+  "telemetry"
+];
+var A2_PLATFORM_ROOTS = [
+  ...A2_SHIPPED_ROOTS,
+  "policy",
+  "identity",
+  "binding",
+  "provider",
+  "workflow",
+  "session",
+  "engine",
+  "message",
+  "connector",
+  "communication",
+  "event",
+  "reach",
+  "handler",
+  "plugin",
+  "scope",
+  "snapshot"
+];
+/* @__PURE__ */ new Set([
+  ...A2_PLATFORM_ROOTS,
+  ...[...OPERATION_IDS].map((id) => id.split(".")[0]),
+  ...CHANNEL_IDS
+]);
+var NAMESPACE_RE = /^[a-z0-9]+\.[a-z0-9]+$/;
+var SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/;
+var MODALITY_KINDS = ["text", "image", "audio", "video", "document"];
+var STRUCTURED_KINDS = [
+  "location",
+  "contact",
+  "sticker",
+  "reaction",
+  "interactive",
+  "card",
+  "carousel",
+  "poll",
+  "template"
+];
+var CONTENT_KINDS = [...MODALITY_KINDS, ...STRUCTURED_KINDS];
+new Set(CONTENT_KINDS);
+var LOSSINESS = ["lossless", "lossy", "semantic"];
+var CONTENT_REF_RE = /^content:([A-Za-z0-9_-]+)\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
+function parseContentRef(ref) {
+  const m = CONTENT_REF_RE.exec(ref);
+  return m ? { principalId: m[1], contentId: m[2] } : null;
+}
+function isContentRef(value) {
+  return typeof value === "string" && CONTENT_REF_RE.test(value);
+}
+function looksLikeProviderLocator(value) {
+  return /^(https?:\/\/|s3:\/\/|gs:\/\/)/i.test(value) || value.includes("?") || value.includes("://");
+}
+var MessageContentProvenance = z.object({
+  /** The connector that produced the item (A7 id). */
+  connector: z.string(),
+  /** The provider-native identifier — reconciliation only; never agent-facing. */
+  providerRef: z.string().optional(),
+  receivedAt: z.string().datetime().optional()
+}).strict();
+var noLocator = (label) => z.string().refine((v) => !looksLikeProviderLocator(v), { message: `${label} must not carry a provider locator \u2014 provider ids live in provenance.providerRef only` });
+var MessageContentMetadata = z.object({
+  bytes: z.number().int().nonnegative().optional(),
+  durationMs: z.number().int().nonnegative().optional(),
+  width: z.number().int().positive().optional(),
+  height: z.number().int().positive().optional(),
+  filename: noLocator("metadata.filename").optional(),
+  caption: noLocator("metadata.caption").optional(),
+  /** e.g. `voice_note` for audio. */
+  variant: z.string().regex(/^[a-z0-9_]+$/).optional(),
+  language: z.string().max(16).optional()
+}).strict();
+var contentRefSchema = z.string().refine(isContentRef, {
+  message: "ref must be an opaque platform content reference `content:<principal>/<uuid>`"
+});
+var OriginalMessageContent = z.object({
+  kind: z.enum(CONTENT_KINDS),
+  /** MIME type or registry format id. */
+  format: z.string().min(1),
+  ref: contentRefSchema,
+  metadata: MessageContentMetadata.default({}),
+  provenance: MessageContentProvenance,
+  /** Inline text for `text` kind only (the ref still names the stored item). */
+  text: z.string().optional()
+}).strict().refine((item) => item.text === void 0 || item.kind === "text", { message: "inline text is only valid on kind=text" });
+var DerivedMessageContent = OriginalMessageContent.innerType().extend({
+  derivedFrom: contentRefSchema,
+  /** The transform capability id (registry or extension id). */
+  transform: z.string().min(1),
+  /** A7 actor ref of the producer. */
+  producer: z.string().min(1),
+  lossiness: z.enum(LOSSINESS)
+}).strict().refine((item) => item.text === void 0 || item.kind === "text", { message: "inline text is only valid on kind=text" }).refine((item) => parseContentRef(item.derivedFrom)?.principalId === parseContentRef(item.ref)?.principalId, {
+  message: "a derived item must derive from content of the same principal"
+});
+z.union([DerivedMessageContent, OriginalMessageContent]);
+var STEP_KINDS = [
+  "FORM",
+  "SECRET",
+  "OAUTH",
+  "APP_INSTALL",
+  "RESOURCE_SELECT",
+  "RESOURCE_CREATE",
+  "REGISTER",
+  "SUBMIT_APPROVAL",
+  "WAIT",
+  "ACTION_REQUIRED",
+  "GATEWAY_CONNECT",
+  "PROBE",
+  "ACTIVATE"
+];
+var OWNERSHIP_MODES = ["platform_managed", "customer_owned"];
+new Set(OWNERSHIP_MODES);
+new Set(STEP_KINDS);
+var WorkflowStep = z.object({
+  id: z.string().min(1),
+  kind: z.enum(STEP_KINDS),
+  title: z.string().min(1),
+  /** JSON Schema for FORM/SECRET inputs — schema-driven, no connector UI code. */
+  schema: z.record(z.unknown()).optional(),
+  /** Credential role for SECRET/OAUTH outputs. */
+  role: z.string().optional(),
+  approvalKind: z.string().optional(),
+  resourceKind: z.string().optional(),
+  mode: z.string().optional(),
+  dependsOn: z.array(z.string()).default([]),
+  optional: z.boolean().default(false),
+  /**
+   * Ownership modes this step applies to (absent = all). A REQUIRED step out of the run's mode is ownership-skipped
+   * (`OUT_OF_MODE`), which is distinct from `optional` — the engine must skip it regardless of `optional` (#306 §9).
+   */
+  ownership: z.array(z.enum(OWNERSHIP_MODES)).optional(),
+  repeatable: z.boolean().default(false),
+  producesChannels: z.array(z.string()).default([])
+}).strict();
+var ConnectorWorkflow = z.object({
+  version: z.string().min(1),
+  steps: z.array(WorkflowStep).min(1),
+  /** What ACTIVATE requires (condition type ids). */
+  activationGates: z.array(z.string()),
+  /** The single step that re-establishes credentials. */
+  reauth: z.object({ stepId: z.string() }).strict(),
+  /** Steps that adopt existing resources on transfer / reconnect. */
+  relink: z.object({ stepIds: z.array(z.string()) }).strict()
+}).strict();
+var EXCLUSIVITY = ["exclusive", "per_connection", "shared"];
+var TIMEOUT_EFFECTS = ["UNKNOWN", "NO_EFFECT", "PROVIDER_ACCEPTS", "PROVIDER_REJECTS"];
+var RECONCILE_BY = ["provider_ref", "correlation_tag", "listing", "none"];
+var ABSENCE_PROOF_METHODS = ["provider_ref", "correlation_tag", "listing"];
+var DUPLICATE_COSTS = ["low", "high"];
+var RESOURCE_KIND_RE = /^[a-z0-9]+(\.[a-z0-9_]+)+$/;
+var ResourceKindDeclaration = z.object({
+  kind: z.string().regex(RESOURCE_KIND_RE, "resource kind must be a namespaced dotted id"),
+  /** Customer-facing name of the kind (presentation only; the connector owns its provider vocabulary). */
+  label: z.string().min(1).optional(),
+  parentKinds: z.array(z.string()).default([]),
+  /** Channels this kind enables (registry ids), if any. */
+  channels: z.array(z.string()).default([]),
+  /** An installation target (guild, workspace, tenant, business account). */
+  isContainer: z.boolean().default(false),
+  /** A channel identity (sender). */
+  isSender: z.boolean().default(false),
+  isRegulatory: z.boolean().default(false),
+  exclusivity: z.enum(EXCLUSIVITY),
+  /** Provider-side sharing cap, manifest DATA never a core constant (e.g. Meta WABA = 2). */
+  maxHolders: z.number().int().positive().optional(),
+  /** doc 06 `reconcile { by, absenceProof?, duplicateCost }`. */
+  reconcile: z.object({
+    by: z.enum(RECONCILE_BY),
+    absenceProof: z.object({ minAgeSec: z.number().int().nonnegative(), method: z.enum(ABSENCE_PROOF_METHODS) }).strict().optional(),
+    duplicateCost: z.enum(DUPLICATE_COSTS)
+  }).strict(),
+  /** doc 06 `release { destructive }`. */
+  release: z.object({ destructive: z.boolean() }).strict().default({ destructive: false }),
+  /** Timeout semantics for the effect that creates this kind (D-23). */
+  createTimeoutEffect: z.enum(TIMEOUT_EFFECTS).default("UNKNOWN")
+}).strict().superRefine((decl, ctx) => {
+  if (decl.isContainer && decl.exclusivity === "exclusive") {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: `container kind ${decl.kind} cannot be exclusive` });
+  }
+  if (decl.maxHolders !== void 0 && decl.exclusivity === "exclusive" && decl.maxHolders !== 1) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: `exclusive kind ${decl.kind} cannot declare maxHolders > 1` });
+  }
+  if (decl.exclusivity === "shared" && (decl.isSender || decl.isContainer)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: `shared kind ${decl.kind} is referenced by value and cannot be a sender or container` });
+  }
+  if (decl.reconcile.absenceProof && decl.reconcile.by === "none") {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: `kind ${decl.kind}: absenceProof needs a reconcile method other than none` });
+  }
+});
+
+// ../contracts/src/channel-connector/approvals.ts
+var APPROVAL_KINDS = [
+  "business_verification",
+  "campaign_vetting",
+  "toll_free_verification",
+  "app_review",
+  "privileged_permission_review",
+  "admin_consent",
+  "display_name_review",
+  "template_review",
+  "agent_launch",
+  "brand_verification"
+];
+new Set(APPROVAL_KINDS);
+var DEPLOYMENT_MODELS = ["per_tenant_app", "platform_app", "both"];
+var CREDENTIAL_STRENGTHS = ["ephemeral", "brokered", "exported_static"];
+var CREDENTIAL_ROLES = ["primary", "signing", "webhook", "refresh", "app_signing", "oauth_client", "partner"];
+var INSTALLATION_KINDS = ["guild", "user", "workspace", "org", "tenant", "team", "business_account", "chat"];
+new Set(INSTALLATION_KINDS);
+z.string().regex(/^cred:[a-z0-9_-]+\/[^\s]+$/, "A5 credential ref `cred:<store>/<path>`");
+var AUTHORIZATION_METHODS = ["oauth", "api_key", "api_secret", "account_token", "bot_token", "delegated_app", "installation_token", "certificate", "other"];
+var AUTHORIZATION_CAPABILITIES = ["discover", "provision", "send", "receive", "manage_resources", "manage_compliance", "manage_webhooks", "manage_installations", "manage_accounts"];
+var AuthorizationMethodDeclaration = z.object({
+  id: z.string().min(1),
+  method: z.enum(AUTHORIZATION_METHODS),
+  credentialRoles: z.array(z.enum(CREDENTIAL_ROLES)).min(1),
+  capabilities: z.array(z.enum(AUTHORIZATION_CAPABILITIES)).default([]),
+  scope: z.enum(["account", "container"]).optional()
+}).strict();
+var INBOUND_AUTH_AVAILABILITY = ["ga", "beta", "private_beta", "unavailable"];
+var InboundAuthMethodDeclaration = z.object({
+  id: z.string().min(1),
+  verifier: z.string().min(1),
+  credentialRole: z.enum(CREDENTIAL_ROLES),
+  compatibleWith: z.array(z.object({ authMethodId: z.string().min(1), reusesAuthCredential: z.boolean() }).strict()).default([]),
+  availability: z.enum(INBOUND_AUTH_AVAILABILITY).default("ga")
+}).strict();
+var MutationApprovalDeclaration = z.object({
+  effect: z.string().min(1),
+  approval: z.enum(["explicit", "implicit"]),
+  capturePriorState: z.boolean().default(false)
+}).strict();
+var ReadinessGateSchema = z.object({
+  condition: z.string().min(1),
+  class: z.enum(CONDITION_CLASSES),
+  blocks: z.union([z.literal("*"), z.array(z.string())]),
+  ttlSec: z.number().int().nonnegative(),
+  evidence: z.enum(["configuration", "runtime"]).optional()
+}).strict();
+var FormatsSchema = z.record(
+  z.enum(CONTENT_KINDS),
+  z.object({ mime: z.array(z.string()).optional(), variants: z.array(z.string()).optional() }).strict()
+);
+var LimitsSchema = z.object({
+  textChars: z.number().int().positive().optional(),
+  textBytes: z.number().int().positive().optional(),
+  mediaBytes: z.number().int().positive().optional(),
+  segments: z.boolean().optional(),
+  perSecond: z.number().positive().optional(),
+  perRecipientPerSecond: z.number().positive().optional(),
+  formats: FormatsSchema.optional(),
+  note: z.string().optional()
+}).strict();
+var DescriptorOverride = z.object({
+  version: z.string().min(1).optional(),
+  operations: z.array(z.string()).optional(),
+  direction: z.object({ inbound: z.boolean(), outbound: z.boolean() }).strict().optional(),
+  initiation: z.object({ agentInitiated: z.enum(AGENT_INITIATION), userInitiated: z.boolean(), firstContactRule: z.string() }).strict().optional(),
+  windows: z.array(
+    z.object({
+      kind: z.literal("reply"),
+      durationSec: z.number().int().positive(),
+      opensOn: z.enum(["inbound_message", "user_action"]),
+      outside: z.enum(WINDOW_OUTSIDE)
+    }).strict()
+  ).optional(),
+  templates: z.object({ required: z.enum(TEMPLATE_REQUIREMENT), reviewed: z.boolean(), categories: z.array(z.string()).optional() }).strict().optional(),
+  surfaces: z.array(z.enum(SURFACES)).optional(),
+  messageTypes: z.array(z.enum(CONTENT_KINDS)).optional(),
+  limits: LimitsSchema.optional(),
+  receipts: z.array(z.enum(RECEIPT_KINDS)).optional(),
+  edits: z.object({ edit: z.boolean(), delete: z.boolean(), reactions: z.boolean(), commands: z.boolean() }).strict().optional(),
+  transport: z.array(z.enum(TRANSPORT_KINDS)).optional(),
+  identity: z.object({ peerIdKind: z.string(), peerIdScope: z.enum(PEER_ID_SCOPES) }).strict().optional(),
+  requiredPermissions: z.array(z.string()).optional(),
+  registration: z.array(z.object({ kind: z.string(), blocks: z.array(z.string()) }).strict()).optional(),
+  readinessGates: z.array(ReadinessGateSchema).optional()
+}).strict();
+var DecisionRequestDeclaration = z.object({
+  kind: z.string().min(1),
+  responseDeadlineSec: z.number().int().positive(),
+  /** The provider's law when we stay silent. */
+  defaultOutcome: z.enum(TIMEOUT_EFFECTS)
+}).strict();
+z.object({
+  /** A7 `<publisher>/<name>`. */
+  id: z.string().min(3),
+  /** A7: semver. */
+  version: z.string().regex(SEMVER_RE, "A7: plugin versions are semver"),
+  displayName: z.string().min(1),
+  publisher: z.string().min(1),
+  /** A STABLE https URL of the provider's own console (the `provider_console` remediation carries it); absent ⇒ remediation has no link. */
+  consoleUrl: z.string().url().optional(),
+  /** The publisher's reverse-domain namespace (`com.acme`) under which every contributed extension id must sit; verified in ch. 05 (D-9). Absent for first-party connectors, which use registry ids only. */
+  namespace: z.string().regex(NAMESPACE_RE, "namespace must be <root>.<label>").optional(),
+  deployment: z.enum(DEPLOYMENT_MODELS),
+  credentialStrength: z.enum(CREDENTIAL_STRENGTHS),
+  /** Roles this connector's connections store refs under. */
+  credentialRoles: z.array(z.enum(CREDENTIAL_ROLES)).default(["primary"]),
+  /** Channels served, each with its descriptor diff over the baseline. */
+  channels: z.array(z.object({ channel: z.string().min(1), descriptor: DescriptorOverride.default({}) }).strict()).min(1),
+  /** Operations the connector implements (registry ids or its own extension ops). */
+  operations: z.array(z.string()).min(1),
+  /** Extension operations this connector defines — each MUST declare a mode. */
+  extensionOperations: z.array(z.object({ id: z.string(), mode: z.enum(OPERATION_MODES), summary: z.string() }).strict()).default([]),
+  onboarding: ConnectorWorkflow,
+  resourceKinds: z.array(ResourceKindDeclaration).default([]),
+  installationKinds: z.array(z.string()).default([]),
+  transports: z.array(z.enum(TRANSPORT_KINDS)).min(1),
+  /** doc 05 §2: transports the provider makes mutually exclusive (e.g. webhook vs long_poll). */
+  transportsExclusive: z.array(z.array(z.enum(TRANSPORT_KINDS)).min(2)).default([]),
+  /** Verifier id the ingress runs before parsing; required with the `webhook` transport. */
+  webhookVerifier: z.string().min(1).optional(),
+  /** Reconcile handler ids by resource kind (doc 02). */
+  reconcilers: z.array(z.object({ resourceKind: z.string(), handler: z.string().min(1) }).strict()).default([]),
+  /** Inbound decision requests with provider-defined defaults (D-23). */
+  decisionRequests: z.array(DecisionRequestDeclaration).default([]),
+  /** Identifier kinds contributed to the ch. 00 B-1 vocabulary. */
+  identifierKinds: z.array(z.string()).default([]),
+  /** Approval kinds used (registry or extension ids). */
+  approvalKinds: z.array(z.string()).default([]),
+  /** Attribution key names used under `platform_app` (doc 08 §4a step 3). */
+  attributionKeys: z.array(z.string()).default([]),
+  /** Quarantine window for PENDING_ATTRIBUTION (D-21), seconds. */
+  pendingAttributionTtlSec: z.number().int().positive().default(7 * 86400),
+  metadata: z.record(z.unknown()).default({}),
+  /** Which relationship ownerships this connector serves (#306 §A/C1). A managed-capable connector MUST declare it explicitly; the default serves only the common OAuth-BYO connector. */
+  ownershipModes: z.array(z.enum(OWNERSHIP_MODES)).min(1).default(["customer_owned"]),
+  /** Authorization methods the connector supports (#306 §4/C3). */
+  authorizationMethods: z.array(AuthorizationMethodDeclaration).default([]),
+  /** Inbound-event authentication strategies (#306 §4/C4); `webhookVerifier` is the single-strategy shorthand, normalized by `resolveInboundAuthMethods`. */
+  inboundAuthMethods: z.array(InboundAuthMethodDeclaration).default([]),
+  /** Provider effects that require an explicit decision, keyed on stable effect ids (#306 L5/C5). */
+  mutationApprovals: z.array(MutationApprovalDeclaration).default([])
+}).strict();
+var Label = z.string().trim().min(1).max(60);
+var Short = z.string().max(300);
+var Body = z.string().max(4e3);
+var Iso = z.string().datetime();
+var MonitoringAuthor = z.enum(["peer", "agent", "system"]);
+var MonitoringTone = z.enum(["ok", "warn", "bad", "info", "neutral"]);
+var UNSAFE_CHARS = /[\u0000-\u001f\u007f-\u009f\u00ad\u061c\u180e\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff\u{e0000}-\u{e007f}]/u;
+function isSafeMonitoringHref(href) {
+  if (href !== href.trim() || UNSAFE_CHARS.test(href) || href.includes("\\") || /%2e|%2f|%5c|%25/i.test(href)) return false;
+  if (href.startsWith("/")) {
+    if (href.startsWith("//")) return false;
+    try {
+      const u = new URL(href, "https://dashboard.invalid");
+      return u.origin === "https://dashboard.invalid" && u.pathname.startsWith("/dashboard/") && u.pathname + u.search + u.hash === href;
+    } catch {
+      return false;
+    }
+  }
+  if (!href.startsWith("https://")) return false;
+  try {
+    const u = new URL(href);
+    return u.protocol === "https:" && !u.username && !u.password && Boolean(u.hostname);
+  } catch {
+    return false;
+  }
+}
+var MonitoringBlock = z.discriminatedUnion("type", [
+  /** One line of the conversation: what was said, by whom. */
+  z.object({ type: z.literal("message"), author: MonitoringAuthor, text: Body, at: Iso.optional() }).strict(),
+  /** Channel facts worth seeing at a glance (Discord server/channel, SMS from/to, call duration). */
+  z.object({ type: z.literal("facts"), items: z.array(z.object({ label: Label, value: Short }).strict()).min(1).max(12) }).strict(),
+  /** The communication's state in words, with a tone. */
+  z.object({ type: z.literal("status"), label: Label, tone: MonitoringTone }).strict(),
+  /** Somewhere to go: the provider's own view of it (https) or a deeper dashboard page. */
+  z.object({ type: z.literal("link"), label: Label, href: z.string().max(2e3).refine(isSafeMonitoringHref, "href must be https or a /dashboard/ path") }).strict(),
+  /** A dated lifecycle fact (sent, delivered, answered, ended). */
+  z.object({ type: z.literal("event"), label: z.string().trim().min(1).max(120), at: Iso }).strict(),
+  /** A spoken exchange, turn by turn. */
+  z.object({
+    type: z.literal("transcript"),
+    turns: z.array(z.object({ author: MonitoringAuthor, text: Body, offsetMs: z.number().int().nonnegative().optional() }).strict()).max(500)
+  }).strict()
+]);
+var PresentedCommunication = z.object({
+  /** One line for lists ("Asked: What is 2 + 2?"). */
+  summary: z.string().max(140).optional(),
+  /**
+   * Something new starts at this communication — e.g. the agent began a fresh session with no memory of what came
+   * before. The page draws a labelled divider before it. Additive to v1: a reader that ignores it loses nothing else.
+   */
+  boundary: z.object({ label: z.string().trim().min(1).max(80) }).strict().optional(),
+  blocks: z.array(MonitoringBlock).max(50)
+}).strict();
+var MonitoringChannelId = z.string().regex(/^[a-z][a-z0-9_.-]{0,39}$/);
+var MonitoringChannelRef = z.object({ id: z.string(), label: z.string() }).strict();
+var MonitoredPeer = z.object({
+  kind: z.string().nullable(),
+  address: z.string().nullable(),
+  /** From the channel's presenter (`describePeer`); null when it has no better name than the address. */
+  displayName: z.string().nullable()
+}).strict();
+var MonitoredConversationSummary = z.object({
+  id: z.string().uuid(),
+  status: z.string(),
+  openedAt: z.string(),
+  lastActivityAt: z.string(),
+  agent: z.object({ id: z.string(), name: z.string() }).strict().nullable(),
+  peer: MonitoredPeer,
+  channels: z.array(MonitoringChannelRef),
+  communications: z.number().int().nonnegative(),
+  /** The latest INBOUND communication's one-liner (else the latest), as its channel presents it. */
+  summary: z.string().nullable(),
+  /** Something in it failed (a message not delivered, a call that failed). */
+  failed: z.boolean(),
+  /** A call in it is still in progress. */
+  live: z.boolean()
+}).strict();
+var MonitoredCommunication = z.object({
+  id: z.string().uuid(),
+  type: z.string(),
+  channel: MonitoringChannelRef,
+  direction: z.string(),
+  status: z.string(),
+  startedAt: z.string(),
+  endedAt: z.string().nullable(),
+  /** Which presenter shaped it (`vl/discord`, `vl/sms`, `generic`), for support. */
+  presenter: z.string(),
+  presented: PresentedCommunication
+}).strict();
+var MonitoringUnlinkedHistory = z.object({ calls: z.boolean(), messages: z.boolean() }).strict();
+z.object({
+  blocksVersion: z.number().int(),
+  scope: z.string(),
+  conversations: z.array(MonitoredConversationSummary),
+  /** Opaque; pass back as `cursor` for the next (older) page. Null on the last page. */
+  nextCursor: z.string().nullable(),
+  /** History from before a channel was linked to the ledger (not shown here, 🔒 control-plane F8/F12). */
+  unlinkedHistory: MonitoringUnlinkedHistory
+}).strict();
+z.object({
+  blocksVersion: z.number().int(),
+  scope: z.string(),
+  conversation: MonitoredConversationSummary,
+  /** Oldest first. The page holds the LATEST communications; `earlierCursor` fetches the ones before them. */
+  communications: z.array(MonitoredCommunication),
+  earlierCursor: z.string().nullable()
+}).strict();
+z.object({
+  scope: z.string(),
+  /** Channels a presenter currently shows, named by that presenter. */
+  channels: z.array(MonitoringChannelRef),
+  /** The Lines (numbers, bots) conversations in this scope arrived on. */
+  lines: z.array(z.object({ id: z.string().uuid(), label: z.string() }).strict())
+}).strict();
+var MONITORING_DIRECTIONS = ["inbound", "outbound"];
+var MONITORING_STATES = ["live", "failed", "ok"];
+var MONITORING_MAX_ID_FILTERS = 50;
+var MONITORING_MAX_CHANNEL_FILTERS = 20;
+z.object({
+  scope: z.enum(["env:dev", "env:stg", "env:prd"]).optional(),
+  limit: z.coerce.number().int().min(1).max(100).optional(),
+  cursor: z.string().max(200).optional(),
+  from: z.string().datetime().optional(),
+  to: z.string().datetime().optional(),
+  channel: z.array(MonitoringChannelId).max(MONITORING_MAX_CHANNEL_FILTERS).optional(),
+  direction: z.array(z.enum(MONITORING_DIRECTIONS)).max(2).optional(),
+  line: z.array(z.string().uuid()).max(MONITORING_MAX_ID_FILTERS).optional(),
+  agent: z.array(z.string().uuid()).max(MONITORING_MAX_ID_FILTERS).optional(),
+  status: z.array(z.enum(MONITORING_STATES)).max(3).optional(),
+  customer: z.string().trim().max(100).optional()
+}).strict();
+var WalletRefusalCode = z.enum([
+  // Prepaid balance (or an invoiced credit limit) cannot cover the action.
+  "insufficient_balance",
+  // The wallet is frozen after a card dispute, until an operator unfreezes it.
+  "account_frozen",
+  // An invoice is unpaid past its 7 days' grace (B-19): new calls, messages and answers are refused; inbound calls are
+  // still answered. Paying the invoice restores the workspace.
+  "account_suspended",
+  // The action's reservation already closed (e.g. a call ended or expired) — it cannot be re-admitted.
+  "hold_closed"
+]);
+z.object({
+  error: WalletRefusalCode,
+  code: WalletRefusalCode,
+  availableUsd: z.string(),
+  needUsd: z.string(),
+  message: z.string()
+});
+var WalletMode = z.enum(["prepaid", "invoiced"]);
+z.object({
+  mode: WalletMode,
+  status: z.enum(["active", "frozen"]),
+  // Decimal strings, six places (the ledger's micro-dollar precision).
+  balanceUsd: z.string(),
+  // Reserved for calls in progress.
+  heldUsd: z.string(),
+  // balance − held (+ credit limit when invoiced); null = unlimited.
+  availableUsd: z.string().nullable(),
+  creditLimitUsd: z.string().nullable(),
+  // A card saved by the first top-up — what auto top-up charges.
+  cardOnFile: z.boolean(),
+  autoTopup: z.object({ enabled: z.boolean(), thresholdUsd: z.string(), amountUsd: z.string() }),
+  // B-19: 'past_due' = an invoice is overdue (a pay-now banner); 'suspended' = paused for it (or by an operator).
+  standing: z.enum(["good", "past_due", "suspended"]),
+  // Why it is suspended: an invoice unpaid past grace (paying restores it) or an operator (only support lifts it).
+  suspension: z.enum(["unpaid_invoice", "operator"]).nullable(),
+  // The oldest overdue invoice, when there is one.
+  overdueInvoice: z.object({ amountUsd: z.string(), dueAt: z.string(), payUrl: z.string().nullable() }).nullable(),
+  // Invoiced wallets: what the next invoice holds so far (charges since the last invoice); null when prepaid.
+  uninvoicedUsd: z.string().nullable()
+});
+var WalletInvoiceStatus = z.enum(["draft", "open", "paid", "void", "uncollectible"]);
+var WalletInvoice = z.object({
+  id: z.string(),
+  // 'final' = issued when the workspace moved to prepaid.
+  kind: z.enum(["monthly", "final"]),
+  periodStart: z.string(),
+  periodEnd: z.string(),
+  amountUsd: z.string(),
+  status: WalletInvoiceStatus,
+  issuedAt: z.string().nullable(),
+  dueAt: z.string().nullable(),
+  paidAt: z.string().nullable(),
+  // Stripe's hosted page to view and pay it (null until issued).
+  payUrl: z.string().nullable()
+});
+z.object({ invoices: z.array(WalletInvoice) });
+var WalletEntryKind = z.enum(["grant", "topup", "usage", "refund", "refund_reversal", "dispute", "dispute_reinstated", "adjustment", "invoice_payment"]);
+var WalletEntry = z.object({
+  id: z.string(),
+  kind: WalletEntryKind,
+  // Signed: a credit is positive, a debit negative.
+  amountUsd: z.string(),
+  balanceAfterUsd: z.string(),
+  // The usage row a debit charged (usage entries only).
+  usageEventId: z.string().nullable(),
+  note: z.string().nullable(),
+  createdAt: z.string()
+});
+z.object({
+  entries: z.array(WalletEntry),
+  // Pass as `before` for the next (older) page; null when there is none.
+  nextBefore: z.string().nullable()
+});
+var TOPUP_MIN_USD = 10;
+var TOPUP_MAX_USD = 500;
+z.object({ amountUsd: z.number().int().min(TOPUP_MIN_USD).max(TOPUP_MAX_USD) });
+z.object({
+  enabled: z.boolean(),
+  thresholdUsd: z.number().min(1).max(TOPUP_MAX_USD),
+  amountUsd: z.number().int().min(TOPUP_MIN_USD).max(TOPUP_MAX_USD)
+});
+
+// src/brain/transport-tunnel.ts
+var AsyncQueue = class {
+  values = [];
+  waiting = [];
+  ended = false;
+  error = null;
+  push(value) {
+    if (this.ended) return;
+    const w = this.waiting.shift();
+    if (w) w.resolve({ value, done: false });
+    else this.values.push(value);
+  }
+  end() {
+    if (this.ended) return;
+    this.ended = true;
+    for (const w of this.waiting) w.resolve({ value: void 0, done: true });
+    this.waiting = [];
+  }
+  fail(err) {
+    if (this.ended) return;
+    this.error = err;
+    this.ended = true;
+    for (const w of this.waiting) w.reject(err);
+    this.waiting = [];
+  }
+  async *drain() {
+    for (; ; ) {
+      if (this.values.length > 0) {
+        yield this.values.shift();
+        continue;
+      }
+      if (this.ended) {
+        if (this.error) throw this.error;
+        return;
+      }
+      const result = await new Promise((resolve, reject) => {
+        this.waiting.push({ resolve, reject });
+      });
+      if (result.done) {
+        if (this.error) throw this.error;
+        return;
+      }
+      yield result.value;
+    }
+  }
+};
+function tunnelBrainTransport(options) {
+  const requestChannel = CONNECTOR_REQUEST_CHANNEL(options.connectorId);
+  const timeoutMs = options.firstChunkTimeoutMs ?? 2e4;
+  async function* stream(req, signal) {
+    const streamId = randomUUID();
+    const replyChannel = CONNECTOR_REPLY_CHANNEL(streamId);
+    const queue = new AsyncQueue();
+    let unsubscribe = null;
+    let timer = null;
+    const clearTimer = () => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    };
+    const cleanup = async () => {
+      clearTimer();
+      const u = unsubscribe;
+      unsubscribe = null;
+      if (u) await u().catch(() => {
+      });
+    };
+    const onAbort = () => {
+      void options.pubsub.publish(requestChannel, JSON.stringify({ kind: "brain.cancel", streamId })).catch(() => {
+      });
+      queue.end();
+    };
+    unsubscribe = await options.pubsub.subscribe(replyChannel, (raw) => {
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        return;
+      }
+      const frame = ConnectorUpFrame.safeParse(parsed);
+      if (!frame.success) return;
+      const f = frame.data;
+      if (!("streamId" in f) || f.streamId !== streamId) return;
+      clearTimer();
+      if (f.kind === "brain.delta") {
+        if (f.content) queue.push({ content: f.content });
+      } else if (f.kind === "brain.done") {
+        queue.end();
+      } else if (f.kind === "brain.error") {
+        queue.fail(new BrainRequestError(f.code, `brain ${f.code}: ${f.message}`));
+      }
+    });
+    if (signal.aborted) {
+      await cleanup();
+      return;
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+    timer = setTimeout(() => queue.fail(new BrainRequestError("no_response", "brain unreachable: no response from connector")), timeoutMs);
+    await options.pubsub.publish(
+      requestChannel,
+      JSON.stringify({
+        kind: "brain.request",
+        streamId,
+        ...req.model ? { model: req.model } : {},
+        ...req.temperature !== void 0 ? { temperature: req.temperature } : {},
+        messages: req.messages.map((m) => ({ role: m.role, content: m.content }))
+      })
+    );
+    try {
+      yield* queue.drain();
+    } finally {
+      signal.removeEventListener("abort", onAbort);
+      await cleanup();
+    }
+  }
+  async function complete(req, signal) {
+    let acc = "";
+    for await (const chunk of stream(req, signal)) acc += chunk.content ?? "";
+    return acc;
+  }
+  return { kind: "tunnel", stream, complete };
+}
+var RedisBrainPubSub = class {
+  constructor(sub, pub) {
+    this.sub = sub;
+    this.pub = pub;
+    sub.on("message", (channel, raw) => {
+      const ls = this.listeners.get(channel);
+      if (!ls) return;
+      for (const fn of ls) {
+        try {
+          fn(raw);
+        } catch {
+        }
+      }
+    });
+  }
+  sub;
+  pub;
+  listeners = /* @__PURE__ */ new Map();
+  async publish(channel, message) {
+    await this.pub.publish(channel, message);
+  }
+  async subscribe(channel, handler) {
+    const set = this.listeners.get(channel) ?? /* @__PURE__ */ new Set();
+    const first = set.size === 0;
+    set.add(handler);
+    this.listeners.set(channel, set);
+    if (first) await this.sub.subscribe(channel);
+    return async () => {
+      const ls = this.listeners.get(channel);
+      ls?.delete(handler);
+      if (ls && ls.size === 0) {
+        this.listeners.delete(channel);
+        try {
+          await this.sub.unsubscribe(channel);
+        } catch {
+        }
+      }
+    };
+  }
+  async close() {
+    try {
+      this.sub.disconnect();
+    } catch {
+    }
+    try {
+      this.pub.disconnect();
+    } catch {
+    }
+  }
+};
+function buildRedisBrainPubSub(redisUrl) {
+  if (!redisUrl) return null;
+  try {
+    const sub = new IORedis(redisUrl, { maxRetriesPerRequest: null, enableReadyCheck: false });
+    const pub = new IORedis(redisUrl, { maxRetriesPerRequest: null, enableReadyCheck: false });
+    return new RedisBrainPubSub(sub, pub);
+  } catch (err) {
+    console.warn("[brain pubsub] init failed", err);
+    return null;
+  }
+}
+
+export { BrainConfigError, BrainRequestError, ConnectorChatModel, RedisBrainPubSub, assertPublicHttpsUrl, buildRedisBrainPubSub, callbackTransport, chatChunkStream, chatContextToMessages, createConnectorLLM, httpBrainTransport, isDisallowedIp, lastUserText, parseChatCompletionSse, runBrainRequest, tunnelBrainTransport };