@alexkroman1/aai 1.7.1 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "type": "module",
   "exports": {
     ".": {
@@ -47,6 +47,11 @@
       "@dev/source": "./sdk/providers/kv-barrel.ts",
       "types": "./dist/sdk/providers/kv-barrel.d.ts",
       "import": "./dist/sdk/providers/kv-barrel.js"
+    },
+    "./s2s": {
+      "@dev/source": "./sdk/providers/s2s-barrel.ts",
+      "types": "./dist/sdk/providers/s2s-barrel.d.ts",
+      "import": "./dist/sdk/providers/s2s-barrel.js"
     }
   },
   "dependencies": {

package/sdk/__snapshots__/exports.test.ts.snap

@@ -89,3 +89,10 @@ exports[`export surface stability > @alexkroman1/aai/runtime export 1`] = `
   "wireSessionSocket",
 ]
 `;
+
+exports[`export surface stability > @alexkroman1/aai/s2s export 1`] = `
+[
+  "OPENAI_REALTIME_KIND",
+  "openaiRealtime",
+]
+`;

package/sdk/__snapshots__/schema-shapes.test.ts.snap

@@ -10,6 +10,7 @@ exports[`manifest schema shapes > AgentConfigSchema shape 1`] = `
   "maxSteps",
   "mode",
   "name",
+  "s2s",
   "stt",
   "sttPrompt",
   "systemPrompt",

package/sdk/_internal-types.test.ts

@@ -5,15 +5,14 @@ import { agentToolsToSchemas } from "./_internal-types.ts";
 import type { ToolDef } from "./types.ts";
 
 test("agentToolsToSchemas - converts tool definitions to OpenAI schema", () => {
+  const noop = async () => {
+    /* no-op */
+  };
   const tools: Record<string, ToolDef> = {
     get_weather: {
       description: "Get weather",
-      parameters: z.object({
-        city: z.string().describe("City"),
-      }),
-      execute: async () => {
-        /* noop */
-      },
+      parameters: z.object({ city: z.string().describe("City") }),
+      execute: noop,
     },
     set_alarm: {
       description: "Set alarm",
@@ -21,9 +20,7 @@ test("agentToolsToSchemas - converts tool definitions to OpenAI schema", () => {
         time: z.string(),
         label: z.string().optional(),
       }),
-      execute: async () => {
-        /* noop */
-      },
+      execute: noop,
     },
   };
   const schemas = agentToolsToSchemas(tools);

package/sdk/_internal-types.ts

@@ -1,9 +1,4 @@
 // Copyright 2025 the AAI authors. MIT license.
-/**
- * Internal type definitions shared by server and CLI.
- *
- * Note: this module is for internal use only and should not be used directly.
- */
 
 import type { JSONSchema7 } from "json-schema";
 import { z } from "zod";
@@ -12,6 +7,7 @@ import {
   assertProviderTriple,
   type KvProvider,
   type LlmProvider,
+  type S2sProvider,
   type SttProvider,
   type TtsProvider,
   type VectorProvider,
@@ -19,27 +15,11 @@ import {
 import type { Message } from "./types.ts";
 import { BuiltinToolSchema, ToolChoiceSchema, type ToolDef } from "./types.ts";
 
-/**
- * Options forwarded to an {@link ExecuteTool} invocation.
- *
- * Primarily used by the pipeline orchestrator (streamText tool loop) to
- * thread an {@link AbortSignal} into tool execution. The S2S voice path
- * does not pass these options today — recipients must treat the whole
- * bag as optional.
- */
 export interface ExecuteToolOptions {
-  /** Abort signal bound to the enclosing LLM turn / request. */
   signal?: AbortSignal;
-  /** Vercel AI SDK tool-call ID for this invocation. Useful for tracing and correlation. */
   toolCallId?: string;
 }
 
-/**
- * Function signature for executing a tool by name.
- *
- * Used by session.ts to invoke tools, by direct-executor.ts and
- * harness-runtime.ts to implement the execution.
- */
 export type ExecuteTool = (
   name: string,
   args: Readonly<Record<string, unknown>>,
@@ -50,12 +30,8 @@ export type ExecuteTool = (
 
 // ─── AgentConfig ────────────────────────────────────────────────────────────
 
-/**
- * Zod schema for serializable agent configuration sent over the wire.
- *
- * This is the JSON-safe subset of the agent definition that can be
- * transmitted between the worker and the host process via structured clone.
- */
+// JSON-safe subset of the agent definition, transmitted between worker and
+// host via structured clone.
 export const AgentConfigSchema = z.object({
   name: z.string().min(1),
   systemPrompt: z.string(),
@@ -68,19 +44,16 @@ export const AgentConfigSchema = z.object({
   stt: ProviderDescriptorSchema.optional(),
   llm: ProviderDescriptorSchema.optional(),
   tts: ProviderDescriptorSchema.optional(),
+  s2s: ProviderDescriptorSchema.optional(),
   mode: z.enum(["s2s", "pipeline"]).optional(),
   kv: ProviderDescriptorSchema.optional(),
   vector: ProviderDescriptorSchema.optional(),
 });
 
-/** Serializable agent configuration — derived from {@link AgentConfigSchema}. */
 export type AgentConfig = z.infer<typeof AgentConfigSchema>;
 
-/**
- * Input shape accepted by {@link toAgentConfig}. Covers both `AgentDef`
- * (where `maxSteps` may be a function) and `IsolateConfig` (where it is
- * always a number).
- */
+// Covers both `AgentDef` (where `maxSteps` may be a function) and
+// `IsolateConfig` (where it is always a number).
 export interface AgentConfigSource {
   name: string;
   systemPrompt: string;
@@ -93,35 +66,33 @@ export interface AgentConfigSource {
   stt?: SttProvider | undefined;
   llm?: LlmProvider | undefined;
   tts?: TtsProvider | undefined;
+  s2s?: S2sProvider | undefined;
   kv?: KvProvider | undefined;
   vector?: VectorProvider | undefined;
 }
 
-/**
- * Extract the serializable {@link AgentConfig} subset from a source object.
- *
- * When `stt`, `llm`, and `tts` descriptors are present they are all three
- * required (or none) — enforced here so the server can trust the config.
- * `mode` is derived from their presence.
- */
 export function toAgentConfig(src: AgentConfigSource): AgentConfig {
+  // `assertProviderTriple` enforces that stt/llm/tts are all-or-nothing so the
+  // server can trust the resolved mode.
+  const mode = assertProviderTriple(src.stt, src.llm, src.tts, src.s2s);
+
   const config: AgentConfig = {
     name: src.name,
     systemPrompt: src.systemPrompt,
     greeting: src.greeting,
+    mode,
   };
   if (src.sttPrompt !== undefined) config.sttPrompt = src.sttPrompt;
   if (src.maxSteps !== undefined) config.maxSteps = src.maxSteps;
   if (src.toolChoice !== undefined) config.toolChoice = src.toolChoice;
   if (src.builtinTools) config.builtinTools = [...src.builtinTools];
   if (src.idleTimeoutMs !== undefined) config.idleTimeoutMs = src.idleTimeoutMs;
-
-  config.mode = assertProviderTriple(src.stt, src.llm, src.tts);
-  if (config.mode === "pipeline") {
+  if (mode === "pipeline") {
     config.stt = src.stt;
     config.llm = src.llm;
     config.tts = src.tts;
   }
+  if (src.s2s !== undefined) config.s2s = src.s2s;
   if (src.kv !== undefined) config.kv = src.kv;
   if (src.vector !== undefined) config.vector = src.vector;
   return config;
@@ -129,12 +100,8 @@ export function toAgentConfig(src: AgentConfigSource): AgentConfig {
 
 // ─── ToolSchema ─────────────────────────────────────────────────────────────
 
-/**
- * Zod schema for serialized tool definitions sent over the wire.
- *
- * `parameters` must be a valid JSON Schema object (with `type`, `properties`,
- * etc.) — the Vercel AI SDK wraps it via `jsonSchema()`.
- */
+// `parameters` must be a valid JSON Schema object — the Vercel AI SDK wraps
+// it via `jsonSchema()`.
 export const ToolSchemaSchema = z.object({
   type: z.literal("function"),
   name: z.string().min(1),
@@ -142,7 +109,6 @@ export const ToolSchemaSchema = z.object({
   parameters: z.record(z.string(), z.unknown()),
 });
 
-/** Serialized tool schema — derived from {@link ToolSchemaSchema}. */
 export type ToolSchema = {
   type: "function";
   name: string;
@@ -150,15 +116,8 @@ export type ToolSchema = {
   parameters: JSONSchema7;
 };
 
-/** Empty Zod object schema used as default when tools have no parameters. */
 export const EMPTY_PARAMS = z.object({});
 
-/**
- * Convert agent tool definitions to JSON Schema format for wire transport.
- *
- * Transforms the Zod-based `parameters` of each tool into a plain JSON Schema
- * object suitable for structured clone / JSON serialization.
- */
 export function agentToolsToSchemas(tools: Readonly<Record<string, ToolDef>>): ToolSchema[] {
   return Object.entries(tools).map(([name, def]) => ({
     type: "function",

package/sdk/_test-matchers.ts

@@ -12,16 +12,24 @@ import { ClientEventSchema } from "./protocol.ts";
 
 type MatcherResult = { pass: boolean; message: () => string };
 
-// ─── Matcher implementations ────────────────────────────────────────────────
+type EventLike = { type?: unknown; [key: string]: unknown };
+
+function fieldsSuffix(fields?: Record<string, unknown>): string {
+  return fields ? ` with fields ${JSON.stringify(fields)}` : "";
+}
 
 function toBeValidClientEvent(received: unknown): MatcherResult {
   const result = ClientEventSchema.safeParse(received);
+  if (result.success) {
+    return {
+      pass: true,
+      message: () => "expected value NOT to be a valid ClientEvent, but it parsed successfully",
+    };
+  }
+  const issues = result.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n");
   return {
-    pass: result.success,
-    message: () =>
-      result.success
-        ? "expected value NOT to be a valid ClientEvent, but it parsed successfully"
-        : `expected value to be a valid ClientEvent\n\nZod errors:\n${result.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n")}`,
+    pass: false,
+    message: () => `expected value to be a valid ClientEvent\n\nZod errors:\n${issues}`,
   };
 }
 
@@ -37,30 +45,32 @@ function toContainEvent(
     };
   }
 
-  const match = received.some((event: Record<string, unknown>) => {
+  const events = received as EventLike[];
+  const match = events.some((event) => {
     if (event?.type !== type) return false;
     if (!fields) return true;
     return Object.entries(fields).every(([key, value]) => isDeepStrictEqual(event[key], value));
   });
 
+  if (match) {
+    return {
+      pass: true,
+      message: () => `expected array NOT to contain event of type "${type}"${fieldsSuffix(fields)}`,
+    };
+  }
+  const receivedTypes = events.map((e) => `"${e?.type}"`).join(", ");
   return {
-    pass: match,
+    pass: false,
     message: () =>
-      match
-        ? `expected array NOT to contain event of type "${type}"${fields ? ` with fields ${JSON.stringify(fields)}` : ""}`
-        : `expected array to contain event of type "${type}"${fields ? ` with fields ${JSON.stringify(fields)}` : ""}\n\nReceived event types: [${received.map((e: Record<string, unknown>) => `"${e?.type}"`).join(", ")}]`,
+      `expected array to contain event of type "${type}"${fieldsSuffix(fields)}\n\nReceived event types: [${receivedTypes}]`,
   };
 }
 
-// ─── Register matchers ──────────────────────────────────────────────────────
-
 expect.extend({
   toBeValidClientEvent,
   toContainEvent,
 });
 
-// ─── Type augmentation ──────────────────────────────────────────────────────
-
 declare module "vitest" {
   interface Assertion<T> {
     toBeValidClientEvent(): void;

package/sdk/allowed-hosts.test.ts

@@ -2,153 +2,89 @@
 import { describe, expect, test } from "vitest";
 import { matchesAllowedHost, validateAllowedHostPattern } from "./allowed-hosts.ts";
 
+function expectInvalid(pattern: string, reasonPattern?: RegExp): void {
+  const result = validateAllowedHostPattern(pattern);
+  // biome-ignore lint/suspicious/noMisplacedAssertion: shared assertion helper used inside test()
+  expect(result.valid).toBe(false);
+  if (reasonPattern) {
+    // biome-ignore lint/suspicious/noMisplacedAssertion: shared assertion helper used inside test()
+    expect((result as { valid: false; reason: string }).reason).toMatch(reasonPattern);
+  }
+}
+
 describe("validateAllowedHostPattern", () => {
   describe("valid patterns", () => {
-    test("accepts exact hostname", () => {
-      expect(validateAllowedHostPattern("api.weather.com")).toEqual({
-        valid: true,
-      });
-    });
-
-    test("accepts exact hostname without subdomain", () => {
-      expect(validateAllowedHostPattern("example.com")).toEqual({ valid: true });
-    });
-
-    test("accepts wildcard subdomain", () => {
-      expect(validateAllowedHostPattern("*.mycompany.com")).toEqual({
-        valid: true,
-      });
-    });
-
-    test("accepts wildcard with multiple domain levels", () => {
-      expect(validateAllowedHostPattern("*.api.mycompany.com")).toEqual({
-        valid: true,
-      });
+    test.each([
+      ["api.weather.com"],
+      ["example.com"],
+      ["*.mycompany.com"],
+      ["*.api.mycompany.com"],
+    ])("accepts %s", (pattern) => {
+      expect(validateAllowedHostPattern(pattern)).toEqual({ valid: true });
     });
   });
 
   describe("rejects bare wildcards", () => {
     test("rejects bare *", () => {
-      const result = validateAllowedHostPattern("*");
-      expect(result.valid).toBe(false);
-      expect((result as { valid: false; reason: string }).reason).toMatch(/bare/i);
+      expectInvalid("*", /bare/i);
     });
 
     test("rejects bare **", () => {
-      const result = validateAllowedHostPattern("**");
-      expect(result.valid).toBe(false);
+      expectInvalid("**");
     });
   });
 
   describe("rejects wildcard in non-leading position", () => {
-    test("rejects wildcard in middle position", () => {
-      const result = validateAllowedHostPattern("api.*.com");
-      expect(result.valid).toBe(false);
-    });
-
-    test("rejects wildcard at end", () => {
-      const result = validateAllowedHostPattern("api.com.*");
-      expect(result.valid).toBe(false);
+    test.each([["api.*.com"], ["api.com.*"]])("rejects %s", (pattern) => {
+      expectInvalid(pattern);
     });
   });
 
   describe("rejects IP addresses", () => {
-    test("rejects IPv4 address", () => {
-      const result = validateAllowedHostPattern("192.168.1.1");
-      expect(result.valid).toBe(false);
-      expect((result as { valid: false; reason: string }).reason).toMatch(/ip/i);
-    });
-
-    test("rejects IPv4 loopback", () => {
-      const result = validateAllowedHostPattern("127.0.0.1");
-      expect(result.valid).toBe(false);
-    });
-
-    test("rejects IPv6 address", () => {
-      const result = validateAllowedHostPattern("::1");
-      expect(result.valid).toBe(false);
-      expect((result as { valid: false; reason: string }).reason).toMatch(/ip/i);
-    });
-
-    test("rejects full IPv6 address", () => {
-      const result = validateAllowedHostPattern("2001:db8::1");
-      expect(result.valid).toBe(false);
-      expect((result as { valid: false; reason: string }).reason).toMatch(/ip/i);
+    test.each([
+      ["192.168.1.1", /ip/i],
+      ["127.0.0.1", undefined],
+      ["::1", /ip/i],
+      ["2001:db8::1", /ip/i],
+    ])("rejects %s", (pattern, reason) => {
+      expectInvalid(pattern, reason);
     });
   });
 
   describe("rejects private TLDs", () => {
-    test("rejects *.local", () => {
-      const result = validateAllowedHostPattern("*.local");
-      expect(result.valid).toBe(false);
-    });
-
-    test("rejects *.internal", () => {
-      const result = validateAllowedHostPattern("*.internal");
-      expect(result.valid).toBe(false);
-    });
-
-    test("rejects *.localhost", () => {
-      const result = validateAllowedHostPattern("*.localhost");
-      expect(result.valid).toBe(false);
-    });
-
-    test("rejects exact match foo.local", () => {
-      const result = validateAllowedHostPattern("foo.local");
-      expect(result.valid).toBe(false);
-    });
-
-    test("rejects exact match foo.internal", () => {
-      const result = validateAllowedHostPattern("foo.internal");
-      expect(result.valid).toBe(false);
-    });
-
-    test("rejects exact match foo.localhost", () => {
-      const result = validateAllowedHostPattern("foo.localhost");
-      expect(result.valid).toBe(false);
+    test.each([
+      ["*.local"],
+      ["*.internal"],
+      ["*.localhost"],
+      ["foo.local"],
+      ["foo.internal"],
+      ["foo.localhost"],
+    ])("rejects %s", (pattern) => {
+      expectInvalid(pattern);
     });
   });
 
   describe("rejects cloud metadata hostnames", () => {
-    test("rejects metadata.google.internal", () => {
-      const result = validateAllowedHostPattern("metadata.google.internal");
-      expect(result.valid).toBe(false);
-    });
-
-    test("rejects instance-data.ec2.internal", () => {
-      const result = validateAllowedHostPattern("instance-data.ec2.internal");
-      expect(result.valid).toBe(false);
+    test.each([
+      ["metadata.google.internal"],
+      ["instance-data.ec2.internal"],
+    ])("rejects %s", (pattern) => {
+      expectInvalid(pattern);
     });
   });
 
   describe("rejects empty and malformed patterns", () => {
     test("rejects empty string", () => {
-      const result = validateAllowedHostPattern("");
-      expect(result.valid).toBe(false);
-    });
-
-    test("rejects pattern with protocol", () => {
-      const result = validateAllowedHostPattern("https://api.example.com");
-      expect(result.valid).toBe(false);
-      expect((result as { valid: false; reason: string }).reason).toMatch(/protocol/i);
-    });
-
-    test("rejects pattern with path", () => {
-      const result = validateAllowedHostPattern("api.example.com/path");
-      expect(result.valid).toBe(false);
-      expect((result as { valid: false; reason: string }).reason).toMatch(/path/i);
-    });
-
-    test("rejects pattern with query", () => {
-      const result = validateAllowedHostPattern("api.example.com?query=1");
-      expect(result.valid).toBe(false);
-      expect((result as { valid: false; reason: string }).reason).toMatch(/query/i);
+      expectInvalid("");
     });
 
-    test("rejects pattern with port", () => {
-      const result = validateAllowedHostPattern("api.example.com:8080");
-      expect(result.valid).toBe(false);
-      expect((result as { valid: false; reason: string }).reason).toMatch(/port/i);
+    test.each([
+      ["https://api.example.com", /protocol/i],
+      ["api.example.com/path", /path/i],
+      ["api.example.com?query=1", /query/i],
+      ["api.example.com:8080", /port/i],
+    ])("rejects %s", (pattern, reason) => {
+      expectInvalid(pattern, reason);
     });
   });
 });

package/sdk/allowed-hosts.ts

@@ -9,18 +9,14 @@
  * environment (browser, Deno, Node.js sandboxes).
  */
 
-/** Private/special-use TLDs that must never appear in allowedHosts patterns. */
 const BLOCKED_TLDS = ["local", "internal", "localhost"];
 
-/**
- * Regex that matches an IPv4 address (four decimal octets separated by dots).
- * Anchored so partial matches like "192.168.1.1.example.com" don't trigger it.
- */
 const IPV4_RE = /^(\d{1,3}\.){3}\d{1,3}$/;
 
-type ValidationResult = { valid: true } | { valid: false; reason: string };
+type ValidationFailure = { valid: false; reason: string };
+type ValidationResult = { valid: true } | ValidationFailure;
 
-function fail(reason: string): { valid: false; reason: string } {
+function fail(reason: string): ValidationFailure {
   return { valid: false, reason };
 }
 
@@ -91,18 +87,16 @@ export function validateAllowedHostPattern(pattern: string): ValidationResult {
 export function matchesAllowedHost(hostname: string, patterns: string[]): boolean {
   if (patterns.length === 0) return false;
 
-  // Strip port — only when there are no brackets (IPv6 bracket notation).
+  // Strip port only when there are no brackets (preserves IPv6 bracket notation).
   const portIndex = hostname.lastIndexOf(":");
-  let host = portIndex !== -1 && !hostname.includes("[") ? hostname.slice(0, portIndex) : hostname;
-
-  // Normalise: lowercase + strip trailing dot
-  host = host.toLowerCase().replace(/\.$/, "");
+  const withoutPort =
+    portIndex !== -1 && !hostname.includes("[") ? hostname.slice(0, portIndex) : hostname;
+  const host = withoutPort.toLowerCase().replace(/\.$/, "");
 
   for (const pattern of patterns) {
     const p = pattern.toLowerCase();
     if (p.startsWith("*.")) {
-      // Wildcard: hostname must end with the suffix (e.g. ".example.com")
-      const suffix = p.slice(1); // ".example.com"
+      const suffix = p.slice(1);
       if (host.endsWith(suffix) && host.length > suffix.length) return true;
     } else if (host === p) {
       return true;

package/sdk/constants.ts

@@ -1,81 +1,34 @@
 // Copyright 2025 the AAI authors. MIT license.
-/**
- * Centralised numeric constants — timeouts, size limits, sample rates.
- *
- * Every magic number that controls a timeout, buffer size, or threshold
- * lives here so the values are discoverable in one place.
- */
-
-// ─── Audio ────────────────────────────────────────────────────────────────
 
-/** Default sample rate for speech-to-text audio in Hz (AssemblyAI). */
 export const DEFAULT_STT_SAMPLE_RATE = 16_000;
-
-/** Default sample rate for text-to-speech audio in Hz. */
 export const DEFAULT_TTS_SAMPLE_RATE = 24_000;
 
-// ─── Timeouts (ms) ───────────────────────────────────────────────────────
-
-/** Default timeout for tool execution in the worker. */
 export const TOOL_EXECUTION_TIMEOUT_MS = 30_000;
-
-/** Timeout for session.start() (S2S connection setup). */
 export const DEFAULT_SESSION_START_TIMEOUT_MS = 10_000;
-
-/** S2S session idle timeout before auto-close. */
-export const DEFAULT_IDLE_TIMEOUT_MS = 300_000; // 5 minutes
-
-/** Per-fetch timeout for network tools (web_search, visit_webpage, fetch_json). */
+export const DEFAULT_IDLE_TIMEOUT_MS = 300_000;
 export const FETCH_TIMEOUT_MS = 15_000;
-
-/** Timeout for sandboxed run_code execution. */
 export const RUN_CODE_TIMEOUT_MS = 5000;
-
-/** Maximum time to wait for sessions to stop during graceful shutdown. */
 export const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30_000;
 
 /**
- * Maximum time to wait for a pipeline-mode TTS drain after `flush()` before
- * forcing the turn to complete. Prevents a stuck TTS provider from wedging
- * the session. Short relative to `DEFAULT_SHUTDOWN_TIMEOUT_MS` so stop()
- * can still reclaim the socket cleanly.
+ * Short relative to `DEFAULT_SHUTDOWN_TIMEOUT_MS` so a stuck TTS provider
+ * can't wedge the session — stop() must still reclaim the socket cleanly.
  */
 export const PIPELINE_FLUSH_TIMEOUT_MS = 10_000;
 
-// ─── Size / length limits ────────────────────────────────────────────────
-
-/** Maximum length for tool result strings sent to clients. */
 export const MAX_TOOL_RESULT_CHARS = 4000;
-
-/** Maximum chars for webpage text after HTML-to-text conversion. */
 export const MAX_PAGE_CHARS = 10_000;
-
-/** Maximum bytes to fetch from an HTML page before conversion. */
 export const MAX_HTML_BYTES = 200_000;
-
-/** Maximum value size for KV store entries (bytes). */
 export const MAX_VALUE_SIZE = 65_536;
-
-/** Maximum conversation messages to retain (sliding window). */
 export const DEFAULT_MAX_HISTORY = 200;
-
-/** Maximum WebSocket message payload size (bytes, 1 MiB). */
 export const MAX_WS_PAYLOAD_BYTES = 1 * 1024 * 1024;
-
-/** Maximum messages buffered while session.start() is pending. */
 export const MAX_MESSAGE_BUFFER_SIZE = 100;
 
-// ─── WebSocket ──────────────────────────────────────────────────────────
-
-/** WebSocket readyState value indicating the connection is open. */
 export const WS_OPEN = 1;
 
-// ─── Security ───────────────────────────────────────────────────────────
-
 /**
- * Content-Security-Policy applied to agent UI pages (both self-hosted and
- * platform). Single source of truth — used by `secureHeaders` middleware
- * and per-response CSP headers.
+ * Single source of truth — used by `secureHeaders` middleware and
+ * per-response CSP headers across self-hosted and platform agent UIs.
  */
 export const AGENT_CSP =
   "default-src 'self'; script-src 'self' 'unsafe-eval' blob:; " +