@lunora/agent 1.0.0-alpha.9 → 1.0.0-alpha.91

package/dist/telemetry/index.d.ts

@@ -60,9 +60,24 @@ interface BraintrustTelemetryOptions extends CommonOptions {
  * A dependency-injected Braintrust bridge for the ai@7 telemetry surface.
  *
  * It wraps model calls (`type: "llm"`) and tool executions (`type: "tool"`) in
- * `logger.traced` spans and logs structural metadata. Prompts / tool arguments
- * are logged only when `recordInputs` is set; generated text / tool results
- * only when `recordOutputs` is set. `onError` opens a span and logs the error.
+ * `logger.traced` spans and logs structural metadata, including the call's token
+ * usage as Braintrust `metrics`. Prompts / tool arguments are logged only when
+ * `recordInputs` is set; generated text / tool results only when `recordOutputs`
+ * is set. `onError` opens a span and logs the error.
+ *
+ * The tool span is driven by the agent LOOP, not by `ai`: Lunora exposes tools
+ * schema-only so the SDK never executes one (see `telemetry/tool-execution.ts`).
+ *
+ * **A model-call span closes when the CALL ends, not when `execute()` resolves.**
+ * On a streamed turn `execute()` resolves the instant `doStream` hands back the
+ * stream — before a token, before any usage — so a span that simply awaited it
+ * measured time-to-first-byte and logged the stream handle instead of the
+ * generation. `execute()` still runs INSIDE the traced callback, which is what
+ * parents the provider's own work under the span; the callback then parks until
+ * the SDK's terminal event for that `callId` arrives, so `traced` finishes the
+ * span at the real end of the call, with the real usage. The caller gets
+ * `execute()`'s value the moment it resolves, exactly as before — the span's
+ * lifetime and the caller's are deliberately separate.
  *
  * The app owns Braintrust initialization; pass the logger in as `logger`.
  * @experimental
@@ -173,36 +188,72 @@ interface OtlpTelemetryOptions extends CommonOptions {
  * An OTLP-over-HTTP telemetry integration for `@lunora/agent`.
  *
  * The OTLP counterpart to the `sentryTelemetry` / `braintrustTelemetry` bridges:
- * it wraps each language-model call and tool execution in an OTLP **span**
+ * it records each language-model call and each tool execution as an OTLP **span**
  * (`gen_ai.*` semantic-convention attributes — model, provider, token usage,
  * tool name) and ships it to a collector, so agent generations land in the same
  * trace store as the rest of an app's telemetry (the Lunora Cloud, or any OTel
  * collector). Plug it into `defineAgent({ telemetry: { isEnabled: true,
  * integrations: [otlpTelemetry({ endpoint, token })] } })`.
  *
- * Emitting inside the turn's execution wrapper means one span per **real** turn:
- * the agent loop memoizes each `step.do('llm:turn:N')`, so a Workflow replay
- * returns the cached result without re-invoking `execute`, and no duplicate span
- * is emitted. Privacy-safe by default — `recordInputs`/`recordOutputs` both
- * default `false`, so no prompt or generated text leaves the worker without an
- * explicit opt-in; only structural metadata + token counts are recorded.
+ * **A model-call span closes when the CALL ends, not when `execute()` resolves.**
+ * On a streamed turn `execute()` resolves the instant `doStream` hands back the
+ * stream — before a single token, before any usage, and before any mid-stream
+ * failure. Closing the span there reported every voice and workflow-streamed turn
+ * as a ~1 ms, zero-token, always-OK call. So the span opens in
+ * `executeLanguageModelCall` (which also owns the failure path, since a rejected
+ * provider call produces no end event) and closes on `onLanguageModelCallEnd`,
+ * which the SDK fires once the response is normalized — after the stream's
+ * `finish` part, where the duration and the token usage actually live.
+ * `onError` / `onAbort` close whatever is still open, so a stream that dies or is
+ * barged in on reports a failure instead of a phantom success.
+ *
+ * **Tool spans come from the agent loop.** Lunora exposes tools to the model
+ * schema-only, so `ai` never runs one and never fires its tool telemetry; the
+ * loop calls `executeTool` itself from the durable step where the tool really
+ * runs (see `telemetry/tool-execution.ts`).
+ *
+ * One span per REAL execution: the agent loop memoizes each `step.do(...)`, so a
+ * Workflow replay returns the cached result without re-invoking the wrapped work
+ * and no duplicate span is emitted. Privacy-safe by default —
+ * `recordInputs`/`recordOutputs` both default `false`, so no prompt or generated
+ * text leaves the worker without an explicit opt-in; only structural metadata +
+ * token counts are recorded.
  *
  * Each export is fire-and-forget (registered with `waitUntil` when supplied);
  * every rejection is swallowed so a flaky collector never surfaces to the run.
  *
- * Two deliberate differences from the SDK-backed bridges, which delegate to a
- * host tracer. First, no `onError`: a failed call already emits a span with
- * `status.code === 2`, so the failure is on the trace and there is no host client
- * to also notify. Second, flat not nested: every span gets `traceId` (shared when
- * `traceId` is set) but no `parentSpanId`, so model-call and tool spans are
- * siblings under the run rather than a tree — OTLP has no ambient span context to
- * parent to here.
+ * One deliberate difference from the SDK-backed bridges, which delegate to a host
+ * tracer: flat, not nested. Every span gets `traceId` (shared when `traceId` is
+ * set) but no `parentSpanId`, so model-call and tool spans are siblings under the
+ * run rather than a tree — OTLP has no ambient span context to parent to here.
  * @param options `endpoint` (+ optional `token`/`headers`/`serviceName`),
  * `traceId` to group a run's spans, `waitUntil`, and the `recordInputs`/
  * `recordOutputs` privacy flags.
  * @experimental
  */
 declare const otlpTelemetry: (options: OtlpTelemetryOptions) => Telemetry;
+/** The span context both `startSpan` and `startSpanManual` are called with. */
+interface SentrySpanContext {
+  attributes?: Record<string, unknown>;
+  name: string;
+  op?: string;
+}
+/**
+ * The subset of a Sentry `Span` this bridge drives. Structural, like
+ * {@link SentryLike} itself — a real `@sentry/*` span satisfies it.
+ * @experimental
+ */
+interface SentrySpan {
+  /** Finish the span. Called once, from whichever terminal event closes the call. */
+  end: () => void;
+  /** Attach attributes discovered after the span started (token usage). */
+  setAttributes?: (attributes: Record<string, unknown>) => unknown;
+  /** `1` = OK, `2` = ERROR (Sentry's `SPAN_STATUS_OK` / `SPAN_STATUS_ERROR`). */
+  setStatus?: (status: {
+    code: 0 | 1 | 2;
+    message?: string;
+  }) => unknown;
+}
 /**
  * The minimal, **structural** slice of `@sentry/cloudflare` (equivalently
  * `@sentry/node`/`@sentry/browser`) this bridge needs. `@sentry/cloudflare` is
@@ -214,16 +265,16 @@ declare const otlpTelemetry: (options: OtlpTelemetryOptions) => Telemetry;
 interface SentryLike {
   /** Capture a thrown value / exception. */
   captureException: (exception: unknown) => unknown;
-  /** Run `callback` inside a new span and return its result. */
-  startSpan: <T>(context: {
-    attributes?: Record<string, unknown>;
-    name: string;
-    op?: string;
-  }, callback: (span: {
-    setStatus?: (status: {
-      code: number;
-    } | string) => void;
-  }) => T) => T;
+  /** Run `callback` inside a new span, finished when the callback settles. */
+  startSpan: <T>(context: SentrySpanContext, callback: (span: SentrySpan) => T) => T;
+  /**
+   * Run `callback` inside a new span that is **not** finished automatically —
+   * the caller owns its lifetime through `span.end()`. Present on every Sentry
+   * SDK built on `@sentry/core` (verified against `@sentry/core@10.55.0`); it is
+   * what lets a streamed model call be measured to the end of the stream while
+   * still nesting the provider's own work under it.
+   */
+  startSpanManual: <T>(context: SentrySpanContext, callback: (span: SentrySpan) => T) => T;
 }
 /**
  * Options for {@link sentryTelemetry}.
@@ -241,14 +292,82 @@ interface SentryTelemetryOptions extends CommonOptions {
 /**
  * A dependency-injected Sentry bridge for the ai@7 telemetry surface.
  *
- * It wraps model calls and tool executions in Sentry spans (via
- * `Sentry.startSpan`) so nested provider/tool work is correctly parented, and
- * routes `onError` to `Sentry.captureException`. Span attributes carry only
- * structural metadata (model, provider, tool name) unless `recordInputs` is
- * set, in which case prompts / tool arguments are attached too.
+ * It wraps model calls and tool executions in Sentry spans so nested
+ * provider/tool work is correctly parented, and routes `onError` to
+ * `Sentry.captureException`. Span attributes carry only structural metadata
+ * (model, provider, tool name, token usage) unless `recordInputs` /
+ * `recordOutputs` are set, in which case prompts, tool arguments and generated
+ * text are attached too.
+ *
+ * The tool span is driven by the agent LOOP, not by `ai`: Lunora exposes tools
+ * schema-only so the SDK never executes one (see `telemetry/tool-execution.ts`).
+ *
+ * **A model-call span closes when the CALL ends, not when `execute()` resolves.**
+ * On a streamed turn `execute()` resolves the instant `doStream` hands back the
+ * stream — before a token, before any usage. The span still OPENS around
+ * `execute()`, because that is what makes it the active span nested provider work
+ * parents to, but it is opened with `startSpanManual` and so is not finished
+ * there: `onLanguageModelCallEnd` ends it, once the response is normalized and
+ * the real duration and token usage are both known. `onAbort` / `onError` end the
+ * call they name as a failure, so a stream that dies or is barged in on reports
+ * one instead of a phantom success.
  *
  * The app owns Sentry initialization; pass the namespace in as `Sentry`.
  * @experimental
  */
 declare const sentryTelemetry: (options: SentryTelemetryOptions) => Telemetry;
-export { type BraintrustLike, type BraintrustSpan, type BraintrustTelemetryOptions, type CommonOptions, type ConsoleLogLevel, type ConsoleLogger, type ConsoleTelemetryOptions, type OtlpTelemetryOptions, type SentryLike, type SentryTelemetryOptions, braintrustTelemetry, combineTelemetry, consoleTelemetry, otlpTelemetry, sentryTelemetry };
+export {
+/**
+ * `@lunora/agent/telemetry` — observability integrations for `@lunora/agent`.
+ *
+ * Every export here produces an ai@7 `Telemetry` object suitable for the
+ * `integrations` array of `TelemetryOptions` (`defineAgent({ telemetry: {
+ * isEnabled: true, integrations: [...] } })`). `consoleTelemetry` is a
+ * zero-dependency structured console tracer; `combineTelemetry` fans the
+ * lifecycle out to several integrations and nests their execution wrappers;
+ * `sentryTelemetry` / `braintrustTelemetry` are dependency-injected bridges (the
+ * app passes its own Sentry namespace / Braintrust logger, so the heavy SDKs are
+ * never imported here); and `otlpTelemetry` ships `gen_ai.*` spans over
+ * OTLP-over-HTTP to any collector (the Lunora Cloud, or your own), so agent
+ * generations land in the same trace store as the rest of the app.
+ *
+ * All integrations are privacy-safe by default (`recordInputs` / `recordOutputs`
+ * both default `false`), so nothing sensitive is recorded without opt-in.
+ */
+type BraintrustLike,
+/**
+ * `@lunora/agent/telemetry` — observability integrations for `@lunora/agent`.
+ *
+ * Every export here produces an ai@7 `Telemetry` object suitable for the
+ * `integrations` array of `TelemetryOptions` (`defineAgent({ telemetry: {
+ * isEnabled: true, integrations: [...] } })`). `consoleTelemetry` is a
+ * zero-dependency structured console tracer; `combineTelemetry` fans the
+ * lifecycle out to several integrations and nests their execution wrappers;
+ * `sentryTelemetry` / `braintrustTelemetry` are dependency-injected bridges (the
+ * app passes its own Sentry namespace / Braintrust logger, so the heavy SDKs are
+ * never imported here); and `otlpTelemetry` ships `gen_ai.*` spans over
+ * OTLP-over-HTTP to any collector (the Lunora Cloud, or your own), so agent
+ * generations land in the same trace store as the rest of the app.
+ *
+ * All integrations are privacy-safe by default (`recordInputs` / `recordOutputs`
+ * both default `false`), so nothing sensitive is recorded without opt-in.
+ */
+type BraintrustSpan,
+/**
+ * `@lunora/agent/telemetry` — observability integrations for `@lunora/agent`.
+ *
+ * Every export here produces an ai@7 `Telemetry` object suitable for the
+ * `integrations` array of `TelemetryOptions` (`defineAgent({ telemetry: {
+ * isEnabled: true, integrations: [...] } })`). `consoleTelemetry` is a
+ * zero-dependency structured console tracer; `combineTelemetry` fans the
+ * lifecycle out to several integrations and nests their execution wrappers;
+ * `sentryTelemetry` / `braintrustTelemetry` are dependency-injected bridges (the
+ * app passes its own Sentry namespace / Braintrust logger, so the heavy SDKs are
+ * never imported here); and `otlpTelemetry` ships `gen_ai.*` spans over
+ * OTLP-over-HTTP to any collector (the Lunora Cloud, or your own), so agent
+ * generations land in the same trace store as the rest of the app.
+ *
+ * All integrations are privacy-safe by default (`recordInputs` / `recordOutputs`
+ * both default `false`), so nothing sensitive is recorded without opt-in.
+ */
+type BraintrustTelemetryOptions, type CommonOptions, type ConsoleLogLevel, type ConsoleLogger, type ConsoleTelemetryOptions, type OtlpTelemetryOptions, type SentryLike, type SentrySpan, type SentryTelemetryOptions, braintrustTelemetry, combineTelemetry, consoleTelemetry, otlpTelemetry, sentryTelemetry };

package/dist/telemetry/index.mjs

@@ -1,5 +1 @@
-export { braintrustTelemetry } from '../packem_shared/braintrustTelemetry-TP7Kwuuj.mjs';
-export { combineTelemetry } from '../packem_shared/combineTelemetry-DCyaaWAI.mjs';
-export { consoleTelemetry } from '../packem_shared/consoleTelemetry--3sWfu1R.mjs';
-export { otlpTelemetry } from '../packem_shared/otlpTelemetry-CKgmWVLg.mjs';
-export { sentryTelemetry } from '../packem_shared/sentryTelemetry-A4F5ndh9.mjs';
+import{braintrustTelemetry as o}from"../packem_shared/braintrustTelemetry-Byne8uPK.mjs";import{combineTelemetry as m}from"../packem_shared/combineTelemetry-DgE9W9G8.mjs";import{consoleTelemetry as p}from"../packem_shared/consoleTelemetry-BZY3Y-Ly.mjs";import{otlpTelemetry as f}from"../packem_shared/otlpTelemetry-ByqrB-72.mjs";import{sentryTelemetry as T}from"../packem_shared/sentryTelemetry-BHeydiAB.mjs";export{o as braintrustTelemetry,m as combineTelemetry,p as consoleTelemetry,f as otlpTelemetry,T as sentryTelemetry};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/agent",
-  "version": "1.0.0-alpha.9",
+  "version": "1.0.0-alpha.91",
   "description": "Durable AI agents for Lunora: defineAgent compiles a replay-safe tool-loop onto Cloudflare Workflows, with DO SQLite threads and live message subscriptions",
   "keywords": [
     "agent",
@@ -62,6 +62,14 @@
       "types": "./dist/naming.d.ts",
       "import": "./dist/naming.mjs"
     },
+    "./skill-markdown": {
+      "types": "./dist/skill-markdown.d.ts",
+      "import": "./dist/skill-markdown.mjs"
+    },
+    "./reply": {
+      "types": "./dist/reply.d.ts",
+      "import": "./dist/reply.mjs"
+    },
     "./sandbox": {
       "types": "./dist/sandbox.d.ts",
       "import": "./dist/sandbox.mjs"
@@ -76,14 +84,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/ai": "1.0.0-alpha.24",
-    "@lunora/errors": "1.0.0-alpha.7",
-    "@lunora/mail": "1.0.0-alpha.17",
-    "@lunora/server": "1.0.0-alpha.30",
-    "@lunora/values": "1.0.0-alpha.10",
-    "@lunora/workflow": "1.0.0-alpha.12",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "ai": "7.0.31"
+    "@lunora/ai": "1.0.0-alpha.74",
+    "@lunora/errors": "1.0.0-alpha.33",
+    "@lunora/mail": "1.0.0-alpha.65",
+    "@lunora/server": "1.0.0-alpha.105",
+    "@lunora/values": "1.0.0-alpha.41",
+    "@lunora/workflow": "1.0.0-alpha.47",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "ai": "7.0.59",
+    "yaml": "^2.9.0"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"

package/dist/packem_shared/AGENT_MODULE-Dnt_-AAT.mjs

@@ -1,24 +0,0 @@
-const AGENT_MODULE = "agents";
-const SANDBOX_MODULE = "sandbox";
-const SANDBOX_INVOKE_PATH = `${SANDBOX_MODULE}:invoke`;
-const DEFAULT_AGENT_FUNCTION_PATHS = {
-  appendMessage: `${AGENT_MODULE}:agentAppendMessage`,
-  ensureThread: `${AGENT_MODULE}:agentEnsureThread`,
-  episodeRecall: `${AGENT_MODULE}:agentEpisodeRecall`,
-  episodeUpsert: `${AGENT_MODULE}:agentEpisodeUpsert`,
-  graphTraverse: `${AGENT_MODULE}:agentGraphTraverse`,
-  graphUpsert: `${AGENT_MODULE}:agentGraphUpsert`,
-  listMessages: `${AGENT_MODULE}:agentMessages`,
-  patchThread: `${AGENT_MODULE}:agentPatchThread`,
-  run: `${AGENT_MODULE}:agentRun`,
-  setState: `${AGENT_MODULE}:agentSetState`,
-  state: `${AGENT_MODULE}:agentState`
-};
-const toFunctionReference = (source) => {
-  if (typeof source === "string") {
-    return { __lunoraRef: source };
-  }
-  return source;
-};
-
-export { AGENT_MODULE, DEFAULT_AGENT_FUNCTION_PATHS, SANDBOX_INVOKE_PATH, SANDBOX_MODULE, toFunctionReference };

package/dist/packem_shared/VoiceSessionDO-BdwlLaXC.mjs

@@ -1,297 +0,0 @@
-import { createAi } from '@lunora/ai';
-import { c as createDispatchRunner } from './createDispatchRunner-DSbp_dph-ZHTtxy3f.mjs';
-import { t as toBase64 } from './base64-BVwtgRJV.mjs';
-import { createStreamGenerate } from './createAgentGenerate-DO7Z96zX.mjs';
-import { DEFAULT_AGENT_FUNCTION_PATHS, toFunctionReference } from './AGENT_MODULE-Dnt_-AAT.mjs';
-import { parseIdentity, pcmToWav, readTranscriptionText, readSynthesisAudio, runVoiceTurn, toByteIterable } from './runVoiceTurn-LnqLvCRR.mjs';
-
-const DEFAULT_STT_MODEL = "@cf/openai/whisper-large-v3-turbo";
-const DEFAULT_TTS_MODEL = "@cf/deepgram/aura-1";
-const MAX_UTTERANCE_BYTES = 8 * 1024 * 1024;
-const MAX_SOCKET_BUFFER_BYTES = 256 * 1024;
-const DRAIN_POLL_MS = 15;
-const MAX_DRAIN_WAIT_MS = 5e3;
-class VoiceSessionDO {
-  agent;
-  ai;
-  env;
-  exportName;
-  paths;
-  streamGenerate;
-  sttModel;
-  ttsModel;
-  audioBuffers = /* @__PURE__ */ new Map();
-  bufferedBytes = /* @__PURE__ */ new Map();
-  controllers = /* @__PURE__ */ new Map();
-  state;
-  constructor(state, env, agent, exportName) {
-    this.state = state;
-    this.env = env;
-    this.agent = agent;
-    this.exportName = exportName;
-    this.paths = DEFAULT_AGENT_FUNCTION_PATHS;
-    this.ai = createAi({ binding: env["AI"], env });
-    this.streamGenerate = createStreamGenerate(agent, env);
-    this.sttModel = agent.voice?.stt ?? DEFAULT_STT_MODEL;
-    this.ttsModel = agent.voice?.tts ?? DEFAULT_TTS_MODEL;
-  }
-  /** HTTP entry — only a WebSocket upgrade carrying a `threadKey` is accepted. */
-  fetch(request) {
-    if (request.headers.get("Upgrade") !== "websocket") {
-      return new Response("Expected a WebSocket upgrade", { status: 426 });
-    }
-    const url = new URL(request.url);
-    const threadKey = url.searchParams.get("threadKey");
-    if (!threadKey) {
-      return new Response("Missing threadKey", { status: 400 });
-    }
-    const WebSocketPairConstructor = globalThis.WebSocketPair;
-    const pair = new WebSocketPairConstructor();
-    const client = pair[0];
-    const server = pair[1];
-    this.state.acceptWebSocket(server);
-    const connectionId = crypto.randomUUID();
-    const identity = parseIdentity(request.headers.get("x-lunora-identity"));
-    const userId = request.headers.get("x-lunora-userid") ?? void 0;
-    server.serializeAttachment?.({
-      connectionId,
-      threadKey,
-      turn: 0,
-      ...identity === void 0 ? {} : { identity },
-      ...userId === void 0 ? {} : { userId }
-    });
-    this.send(server, { audioFormat: this.agent.voice?.audioFormat ?? "mp3", type: "ready" });
-    const greeting = this.agent.voice?.greeting;
-    if (greeting && greeting.length > 0) {
-      this.state.waitUntil?.(this.speakGreeting(server, connectionId, threadKey, userId, identity, greeting));
-    }
-    return new Response(null, { status: 101, webSocket: client });
-  }
-  /** Hibernation message handler — never throws (a thrown handler is fatal to the socket). */
-  async webSocketMessage(ws, message) {
-    const attachment = ws.deserializeAttachment?.();
-    if (!attachment) {
-      return;
-    }
-    try {
-      if (typeof message === "string") {
-        await this.handleControl(ws, attachment, message);
-        return;
-      }
-      this.bufferAudio(attachment.connectionId, new Uint8Array(message), ws);
-    } catch (error) {
-      this.send(ws, { message: error instanceof Error ? error.message : String(error), type: "error" });
-    }
-  }
-  /** Abort any in-flight turn + free the socket's buffers on close. Never throws. */
-  webSocketClose(ws) {
-    this.cleanupSocket(ws);
-  }
-  /** Abort any in-flight turn + free the socket's buffers on error. Never throws. */
-  webSocketError(ws) {
-    this.cleanupSocket(ws);
-  }
-  /**
-   * The runtime dispatch seam reaching the shared agent thread functions. When
-   * the socket carries a verified identity it is forwarded so the `agents:*`
-   * thread writes are attributed to the caller (RLS / row ownership) rather
-   * than the anonymous system dispatch.
-   */
-  resolveRun(userId, claims) {
-    const identity = userId === void 0 && claims === void 0 ? void 0 : { ...claims === void 0 ? {} : { claims }, ...userId === void 0 ? {} : { userId } };
-    return createDispatchRunner({ env: this.env, label: "@lunora/agent voice", ...identity === void 0 ? {} : { identity } });
-  }
-  /** Production STT seam: WAV-wrap the utterance and run the batch transcription model. */
-  async transcribe(pcm) {
-    const wav = pcmToWav(pcm);
-    return readTranscriptionText(await this.ai.run(this.sttModel, { audio: toBase64(wav) }));
-  }
-  /** Production TTS seam: synthesize one sentence to a normalized audio source; `signal` aborts an in-flight barge-in. */
-  async synthesize(text, signal) {
-    const speaker = this.agent.voice?.speaker;
-    return readSynthesisAudio(
-      await this.ai.run(this.ttsModel, { text, ...speaker === void 0 ? {} : { speaker } }, signal === void 0 ? void 0 : { signal })
-    );
-  }
-  /** Route a JSON control frame (`commit` / `interrupt` / `text`). */
-  async handleControl(ws, attachment, raw) {
-    let frame;
-    try {
-      frame = JSON.parse(raw);
-    } catch {
-      return;
-    }
-    if (frame.type === "interrupt") {
-      this.controllers.get(attachment.connectionId)?.abort();
-      return;
-    }
-    if (this.controllers.has(attachment.connectionId)) {
-      this.send(ws, { message: "a turn is already in progress — send an interrupt before the next utterance", type: "error" });
-      return;
-    }
-    if (frame.type === "commit") {
-      const pcm = this.drainAudio(attachment.connectionId);
-      await this.runTurn(ws, attachment, { pcm });
-      return;
-    }
-    await this.runTurn(ws, attachment, { text: frame.text });
-  }
-  /** Append a binary audio frame to the socket's utterance buffer (bounded). */
-  bufferAudio(connectionId, chunk, ws) {
-    const total = (this.bufferedBytes.get(connectionId) ?? 0) + chunk.byteLength;
-    if (total > MAX_UTTERANCE_BYTES) {
-      this.audioBuffers.delete(connectionId);
-      this.bufferedBytes.delete(connectionId);
-      this.send(ws, { message: "utterance exceeded the maximum buffer — send a commit sooner", type: "error" });
-      return;
-    }
-    const chunks = this.audioBuffers.get(connectionId) ?? [];
-    chunks.push(chunk);
-    this.audioBuffers.set(connectionId, chunks);
-    this.bufferedBytes.set(connectionId, total);
-  }
-  /** Concatenate + clear the socket's buffered utterance. */
-  drainAudio(connectionId) {
-    const chunks = this.audioBuffers.get(connectionId) ?? [];
-    this.audioBuffers.delete(connectionId);
-    this.bufferedBytes.delete(connectionId);
-    const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
-    const pcm = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-      pcm.set(chunk, offset);
-      offset += chunk.byteLength;
-    }
-    return pcm;
-  }
-  /** Execute a turn under a fresh abort controller, advancing the socket's turn index. */
-  async runTurn(ws, attachment, input) {
-    const controller = new AbortController();
-    this.controllers.set(attachment.connectionId, controller);
-    try {
-      await runVoiceTurn({
-        agent: this.agent,
-        connectionId: attachment.connectionId,
-        env: this.env,
-        exportName: this.exportName,
-        paths: this.paths,
-        run: this.resolveRun(attachment.userId, attachment.identity),
-        send: (frame) => {
-          this.send(ws, frame);
-        },
-        sendAudio: (bytes) => {
-          this.sendAudio(ws, bytes);
-        },
-        signal: controller.signal,
-        streamGenerate: this.streamGenerate,
-        synthesize: async (text, signal) => this.synthesizeWithSignal(text, signal),
-        threadKey: attachment.threadKey,
-        transcribe: async (pcm) => this.transcribe(pcm),
-        turn: attachment.turn,
-        waitForDrain: async () => this.waitForSocketDrain(ws),
-        ...attachment.userId === void 0 ? {} : { owner: attachment.userId },
-        ...input.pcm === void 0 ? {} : { pcm: input.pcm },
-        ...input.text === void 0 ? {} : { text: input.text }
-      });
-    } finally {
-      if (this.controllers.get(attachment.connectionId) === controller) {
-        this.controllers.delete(attachment.connectionId);
-      }
-      ws.serializeAttachment?.({ ...attachment, turn: attachment.turn + 1 });
-    }
-  }
-  /** Synthesize a greeting on connect and persist it as the thread's opening assistant turn. */
-  async speakGreeting(ws, connectionId, threadKey, userId, identity, greeting) {
-    const run = this.resolveRun(userId, identity);
-    const controller = new AbortController();
-    const isAborted = () => controller.signal.aborted;
-    this.controllers.set(connectionId, controller);
-    try {
-      await run(toFunctionReference(this.paths.ensureThread), {
-        agent: this.exportName,
-        key: threadKey,
-        ...this.agent.initialState === void 0 ? {} : { initialState: this.agent.initialState },
-        ...userId === void 0 ? {} : { owner: userId }
-      });
-      for await (const chunk of toByteIterable(await this.synthesizeWithSignal(greeting, controller.signal))) {
-        if (isAborted()) {
-          break;
-        }
-        await this.waitForSocketDrain(ws);
-        if (isAborted()) {
-          break;
-        }
-        this.sendAudio(ws, chunk);
-      }
-      if (!isAborted()) {
-        await run(toFunctionReference(this.paths.appendMessage), {
-          content: greeting,
-          messageKey: "voice:greeting:assistant",
-          role: "assistant",
-          threadKey
-        });
-        this.send(ws, { text: greeting, type: "assistant_done" });
-      }
-    } catch (error) {
-      this.send(ws, { message: error instanceof Error ? error.message : String(error), type: "error" });
-    } finally {
-      if (this.controllers.get(connectionId) === controller) {
-        this.controllers.delete(connectionId);
-      }
-    }
-  }
-  /** Bridge the pipeline's `(text, signal)` synthesize seam onto the class TTS method, forwarding the barge-in signal. */
-  async synthesizeWithSignal(text, signal) {
-    if (signal.aborted) {
-      return new Uint8Array(0);
-    }
-    return this.synthesize(text, signal);
-  }
-  /** Abort an in-flight turn and free a socket's transient buffers. */
-  cleanupSocket(ws) {
-    const attachment = ws.deserializeAttachment?.();
-    if (!attachment) {
-      return;
-    }
-    this.controllers.get(attachment.connectionId)?.abort();
-    this.controllers.delete(attachment.connectionId);
-    this.audioBuffers.delete(attachment.connectionId);
-    this.bufferedBytes.delete(attachment.connectionId);
-  }
-  /** Send a JSON control frame, swallowing a closed-socket error (never throw from a handler). */
-  // eslint-disable-next-line class-methods-use-this -- instance method (kept non-static for subclass override symmetry); acts on the passed socket
-  send(ws, frame) {
-    try {
-      ws.send(JSON.stringify(frame));
-    } catch {
-    }
-  }
-  /** Send a binary audio frame, swallowing a closed-socket error. */
-  // eslint-disable-next-line class-methods-use-this -- instance method (kept non-static for subclass override symmetry); acts on the passed socket
-  sendAudio(ws, bytes) {
-    try {
-      ws.send(bytes);
-    } catch {
-    }
-  }
-  /**
-   * Outbound backpressure: if the socket exposes `bufferedAmount`, yield in
-   * short polls until the send buffer drains below the cap so a slow client
-   * can't balloon DO memory. Bounded by {@link MAX_DRAIN_WAIT_MS} so a stuck
-   * socket never blocks a turn forever, and never throws (a socket without
-   * `bufferedAmount` resolves immediately).
-   */
-  // eslint-disable-next-line class-methods-use-this -- instance method (kept non-static for subclass override symmetry); acts on the passed socket
-  async waitForSocketDrain(ws) {
-    const socket = ws;
-    let waited = 0;
-    while (typeof socket.bufferedAmount === "number" && socket.bufferedAmount > MAX_SOCKET_BUFFER_BYTES && waited < MAX_DRAIN_WAIT_MS) {
-      await new Promise((resolve) => {
-        setTimeout(resolve, DRAIN_POLL_MS);
-      });
-      waited += DRAIN_POLL_MS;
-    }
-  }
-}
-
-export { VoiceSessionDO as default };