@niadra/sdk 0.1.0 → 0.7.0

package/dist/livekit.d.cts

@@ -0,0 +1,113 @@
+import { voice, llm } from '@livekit/agents';
+import { bt as Conversation, h as Handle } from './client-DsIxZxZk.cjs';
+import { a as ProofSource, A as AgentMemoryOption } from './shared-DTPWVlWm.cjs';
+export { P as Proof, c as attestationProof } from './shared-DTPWVlWm.cjs';
+
+/**
+ * Niadra for LiveKit Agents (Node, `@livekit/agents` 1.9).
+ *
+ * The same hook as LiveKit's own RAG recipe: `onUserTurnCompleted(turnCtx, newMessage)`. There
+ * the customer's final transcript is recorded, the conversation's pack goes into the turn's chat
+ * context as a system message right after the agent's instructions, and the suffix (live turns
+ * from other channels, what the caller's turn needs from memory, and deltas) goes after the new message. The read sends the caller's turn along. The turn context is
+ * a copy LiveKit builds for this reply only, so nothing piles up in the agent's history and the prompt prefix
+ * stays byte-identical turn after turn. Session events record the agent's answers (with the
+ * LLM usage LiveKit measured), handoffs between agents and the end of the call.
+ *
+ * `NiadraMemory` starts the caller's first read when it is built (`begin()`), so it runs while the
+ * session starts, and the first reply waits for it within `timeouts.contextVoiceStart` (1.5 s).
+ * After that no turn waits on a round trip for the pack: it comes from memory at once. While the
+ * caller is still speaking, each `user_input_transcribed` event (interim or final) sends the turn
+ * so far with `prefetch()`, in the background: the server warms the caller's memory, and once the
+ * words stop changing the SDK reads the turn with them, so the slots are there when LiveKit ends
+ * the turn. A turn waits at most 200 ms for such a read still on its way, then answers without
+ * the slots; a prefetch never holds or fails a turn.
+ *
+ * @example
+ * const caller = ctx.room.remoteParticipants.values().next().value;
+ * const convo = niadra.conversation({ subject: sipSubject(caller), channel: "voice", conversation_id: sipConversationId(caller, ctx.room.name) });
+ * const memory = new NiadraMemory({ conversation: convo, verify: attestationProof(caller.attributes["sip.h.x-stir-verstat"]) });
+ * const agent = new NiadraAgent({ instructions: "You are the support line of Acme.", memory });
+ * memory.attach(session);
+ * await session.start({ agent, room: ctx.room });
+ */
+
+interface NiadraMemoryOptions {
+    /** The call, opened with `channel: "voice"` so reads use the voice view and budget. */
+    conversation: Conversation;
+    /**
+     * What the call proved before the first read, such as the carrier's attestation
+     * (`attestationProof(...)`). Recorded once with `verify()` before the first context.
+     */
+    verify?: ProofSource;
+    /** Records the agent's answers from `conversation_item_added`. Defaults to `true`. */
+    recordAgent?: boolean;
+    /** Puts the agent's own notes before the caller's context and adds its memory tools. */
+    agentMemory?: AgentMemoryOption;
+}
+/** Participant fields the helpers read. A `RemoteParticipant` has them. */
+interface ParticipantLike {
+    identity: string;
+    attributes?: Record<string, string> | undefined;
+}
+/**
+ * The caller as a handle: the phone number LiveKit SIP puts in `sip.phoneNumber` (E.164, `+` added
+ * when missing), otherwise the participant identity as your app's user id.
+ */
+declare function sipSubject(participant: ParticipantLike): Handle;
+/** The call id LiveKit SIP puts in `sip.callID`, otherwise the room name. */
+declare function sipConversationId(participant: ParticipantLike, roomName: string): string;
+/**
+ * The memory of one call, shared by every agent that takes part in it. Put its
+ * `onUserTurnCompleted` in your agent (or use `NiadraAgent`), its `toolset()` in the agent's
+ * tools, and `attach()` it to the session.
+ */
+declare class NiadraMemory {
+    readonly conversation: Conversation;
+    private readonly bridge;
+    private readonly recordAgent;
+    private readonly customerTurns;
+    private usage;
+    /** The final transcript segments of the turn the caller is still speaking. */
+    private heard;
+    constructor(options: NiadraMemoryOptions);
+    /**
+     * Records the customer's final transcript, then puts the pack after the instructions and the
+     * suffix after the new message, for this reply only. Never throws.
+     */
+    onUserTurnCompleted(turnCtx: llm.ChatContext, newMessage: llm.ChatMessage): Promise<void>;
+    /**
+     * Listens to the session: the agent's answers, handoffs between agents and the end of the call.
+     * Returns a function that stops listening.
+     */
+    attach(session: voice.AgentSession): () => void;
+    /** The navigation kit as LiveKit function tools, bound to this caller. */
+    tools(): llm.FunctionTool[];
+    /** The same tools grouped as one toolset, to add next to your own. */
+    toolset(): llm.Toolset;
+    /**
+     * Records a transfer to a person, such as a SIP transfer to the queue. Call it right before
+     * the transfer, so the attendant's screen can read the context at once.
+     */
+    handoffToHuman(reason?: string): Promise<void>;
+    private onItem;
+    /** The turn so far: its final segments and, when `transcript` is interim, that one too. */
+    private hearing;
+    private recordCustomer;
+}
+interface NiadraAgentOptions<UserData> extends voice.AgentOptions<UserData> {
+    memory: NiadraMemory;
+    /** Adds the navigation kit to the agent's tools. Defaults to `true`. */
+    historyTools?: boolean;
+}
+/**
+ * A LiveKit `Agent` with Niadra wired in: context before each reply and the navigation kit
+ * among its tools. Subclasses that override `onUserTurnCompleted` call `super.onUserTurnCompleted`.
+ */
+declare class NiadraAgent<UserData = unknown> extends voice.Agent<UserData> {
+    readonly memory: NiadraMemory;
+    constructor({ memory, historyTools, ...options }: NiadraAgentOptions<UserData>);
+    onUserTurnCompleted(turnCtx: llm.ChatContext, newMessage: llm.ChatMessage): Promise<void>;
+}
+
+export { AgentMemoryOption, NiadraAgent, type NiadraAgentOptions, NiadraMemory, type NiadraMemoryOptions, type ParticipantLike, ProofSource, sipConversationId, sipSubject };

package/dist/livekit.d.ts

@@ -0,0 +1,113 @@
+import { voice, llm } from '@livekit/agents';
+import { bt as Conversation, h as Handle } from './client-DsIxZxZk.js';
+import { a as ProofSource, A as AgentMemoryOption } from './shared-Bb5B59Bu.js';
+export { P as Proof, c as attestationProof } from './shared-Bb5B59Bu.js';
+
+/**
+ * Niadra for LiveKit Agents (Node, `@livekit/agents` 1.9).
+ *
+ * The same hook as LiveKit's own RAG recipe: `onUserTurnCompleted(turnCtx, newMessage)`. There
+ * the customer's final transcript is recorded, the conversation's pack goes into the turn's chat
+ * context as a system message right after the agent's instructions, and the suffix (live turns
+ * from other channels, what the caller's turn needs from memory, and deltas) goes after the new message. The read sends the caller's turn along. The turn context is
+ * a copy LiveKit builds for this reply only, so nothing piles up in the agent's history and the prompt prefix
+ * stays byte-identical turn after turn. Session events record the agent's answers (with the
+ * LLM usage LiveKit measured), handoffs between agents and the end of the call.
+ *
+ * `NiadraMemory` starts the caller's first read when it is built (`begin()`), so it runs while the
+ * session starts, and the first reply waits for it within `timeouts.contextVoiceStart` (1.5 s).
+ * After that no turn waits on a round trip for the pack: it comes from memory at once. While the
+ * caller is still speaking, each `user_input_transcribed` event (interim or final) sends the turn
+ * so far with `prefetch()`, in the background: the server warms the caller's memory, and once the
+ * words stop changing the SDK reads the turn with them, so the slots are there when LiveKit ends
+ * the turn. A turn waits at most 200 ms for such a read still on its way, then answers without
+ * the slots; a prefetch never holds or fails a turn.
+ *
+ * @example
+ * const caller = ctx.room.remoteParticipants.values().next().value;
+ * const convo = niadra.conversation({ subject: sipSubject(caller), channel: "voice", conversation_id: sipConversationId(caller, ctx.room.name) });
+ * const memory = new NiadraMemory({ conversation: convo, verify: attestationProof(caller.attributes["sip.h.x-stir-verstat"]) });
+ * const agent = new NiadraAgent({ instructions: "You are the support line of Acme.", memory });
+ * memory.attach(session);
+ * await session.start({ agent, room: ctx.room });
+ */
+
+interface NiadraMemoryOptions {
+    /** The call, opened with `channel: "voice"` so reads use the voice view and budget. */
+    conversation: Conversation;
+    /**
+     * What the call proved before the first read, such as the carrier's attestation
+     * (`attestationProof(...)`). Recorded once with `verify()` before the first context.
+     */
+    verify?: ProofSource;
+    /** Records the agent's answers from `conversation_item_added`. Defaults to `true`. */
+    recordAgent?: boolean;
+    /** Puts the agent's own notes before the caller's context and adds its memory tools. */
+    agentMemory?: AgentMemoryOption;
+}
+/** Participant fields the helpers read. A `RemoteParticipant` has them. */
+interface ParticipantLike {
+    identity: string;
+    attributes?: Record<string, string> | undefined;
+}
+/**
+ * The caller as a handle: the phone number LiveKit SIP puts in `sip.phoneNumber` (E.164, `+` added
+ * when missing), otherwise the participant identity as your app's user id.
+ */
+declare function sipSubject(participant: ParticipantLike): Handle;
+/** The call id LiveKit SIP puts in `sip.callID`, otherwise the room name. */
+declare function sipConversationId(participant: ParticipantLike, roomName: string): string;
+/**
+ * The memory of one call, shared by every agent that takes part in it. Put its
+ * `onUserTurnCompleted` in your agent (or use `NiadraAgent`), its `toolset()` in the agent's
+ * tools, and `attach()` it to the session.
+ */
+declare class NiadraMemory {
+    readonly conversation: Conversation;
+    private readonly bridge;
+    private readonly recordAgent;
+    private readonly customerTurns;
+    private usage;
+    /** The final transcript segments of the turn the caller is still speaking. */
+    private heard;
+    constructor(options: NiadraMemoryOptions);
+    /**
+     * Records the customer's final transcript, then puts the pack after the instructions and the
+     * suffix after the new message, for this reply only. Never throws.
+     */
+    onUserTurnCompleted(turnCtx: llm.ChatContext, newMessage: llm.ChatMessage): Promise<void>;
+    /**
+     * Listens to the session: the agent's answers, handoffs between agents and the end of the call.
+     * Returns a function that stops listening.
+     */
+    attach(session: voice.AgentSession): () => void;
+    /** The navigation kit as LiveKit function tools, bound to this caller. */
+    tools(): llm.FunctionTool[];
+    /** The same tools grouped as one toolset, to add next to your own. */
+    toolset(): llm.Toolset;
+    /**
+     * Records a transfer to a person, such as a SIP transfer to the queue. Call it right before
+     * the transfer, so the attendant's screen can read the context at once.
+     */
+    handoffToHuman(reason?: string): Promise<void>;
+    private onItem;
+    /** The turn so far: its final segments and, when `transcript` is interim, that one too. */
+    private hearing;
+    private recordCustomer;
+}
+interface NiadraAgentOptions<UserData> extends voice.AgentOptions<UserData> {
+    memory: NiadraMemory;
+    /** Adds the navigation kit to the agent's tools. Defaults to `true`. */
+    historyTools?: boolean;
+}
+/**
+ * A LiveKit `Agent` with Niadra wired in: context before each reply and the navigation kit
+ * among its tools. Subclasses that override `onUserTurnCompleted` call `super.onUserTurnCompleted`.
+ */
+declare class NiadraAgent<UserData = unknown> extends voice.Agent<UserData> {
+    readonly memory: NiadraMemory;
+    constructor({ memory, historyTools, ...options }: NiadraAgentOptions<UserData>);
+    onUserTurnCompleted(turnCtx: llm.ChatContext, newMessage: llm.ChatMessage): Promise<void>;
+}
+
+export { AgentMemoryOption, NiadraAgent, type NiadraAgentOptions, NiadraMemory, type NiadraMemoryOptions, type ParticipantLike, ProofSource, sipConversationId, sipSubject };

package/dist/livekit.js

@@ -0,0 +1,398 @@
+import { llm, voice } from '@livekit/agents';
+
+// src/integrations/livekit.ts
+
+// src/handles.ts
+function build(type, value, scope, options) {
+  const handle = { type, value };
+  if (scope !== void 0) handle.scope = scope;
+  if (options?.subjectKind !== void 0) handle.subject_kind = options.subjectKind;
+  return handle;
+}
+var handles = {
+  /** A phone number in E.164 form, such as `+5511987654321`. */
+  phone: (e164, options) => build("phone_e164", e164, void 0, options),
+  email: (address, options) => build("email", address, void 0, options),
+  /** The WhatsApp id (`wa_id`) the Cloud API reports for a contact. */
+  waId: (value, options) => build("wa_id", value, void 0, options),
+  waJid: (value, options) => build("wa_jid", value, void 0, options),
+  waLid: (value, options) => build("wa_lid", value, void 0, options),
+  /** A business-scoped WhatsApp user id; `businessAccount` is the WhatsApp Business account it belongs to. */
+  waBsuid: (value, businessAccount, options) => build("wa_bsuid", value, businessAccount, options),
+  /** The user id in your own app or site. */
+  appUserId: (value, options) => build("app_user_id", value, void 0, options),
+  /** The id of a person or organization in a system of record; `system` names that system, such as `crm`. */
+  systemId: (value, system, options) => build("system_id", value, system, options),
+  /** An HMAC of a national document number; `country` is its ISO 3166-1 alpha-2 code. */
+  govIdHmac: (value, country, options) => build("gov_id_hmac", value, country, options),
+  /** An HMAC of a company registry number. Identifies an organization. */
+  orgRegistryHmac: (value, country) => build("org_registry_hmac", value, country, { subjectKind: "account" }),
+  /** An e-mail domain, such as `acme.com`. Identifies an organization. */
+  emailDomain: (domain) => build("email_domain", domain, void 0, { subjectKind: "account" }),
+  /** An anonymous visitor or device id, before the person is known. */
+  anonId: (value, options) => build("anon_id", value, void 0, options)
+};
+
+// src/context.ts
+function emptyResult(error) {
+  return { text: "", suffix: "", variables: {}, pack: null, source: "none", response: null, error, constraints: null, state: null, coordination: null };
+}
+
+// src/integrations/shared.ts
+var ATTESTED = { A: "V2", B: "V1", C: "V1" };
+function attestationProof(attestation) {
+  if (!attestation) return null;
+  const value = attestation.trim().toUpperCase();
+  if (value.includes("FAILED") || value.startsWith("NO-")) return null;
+  const letter = value.length === 1 ? value : /PASSED-([ABC])$/.exec(value)?.[1];
+  const level = letter ? ATTESTED[letter] : void 0;
+  return level ? { method: "network_attestation", level } : null;
+}
+function isConversation(session) {
+  return "customer" in session && typeof session.customer === "function";
+}
+function errorName(error) {
+  return error instanceof Error ? error.name : typeof error;
+}
+var Bridge = class {
+  constructor(session, proof, memory = false) {
+    this.session = session;
+    this.proof = proof;
+    this.memory = memory;
+  }
+  session;
+  proof;
+  memory;
+  proving = null;
+  /** `begin()` started the first read of a call: the first `context()` waits for it with `ready()`. */
+  begun = false;
+  opened = false;
+  /**
+   * The context and, when enabled, the agent's notes, read side by side within the same budget.
+   * Never rejects.
+   */
+  async read(options = {}) {
+    const memoryParams = this.memory === false ? null : this.memory === true ? {} : withoutWrite(this.memory);
+    const [context, memory] = await Promise.all([
+      this.context(options),
+      memoryParams ? this.agentMemory(memoryParams, options) : Promise.resolve("")
+    ]);
+    return { context, memory, prefix: [memory, context.text].filter(Boolean).join("\n\n"), suffix: context.suffix };
+  }
+  get logger() {
+    return this.session.logger;
+  }
+  /**
+   * Starts the first read of a call now, in the background, after the proof when one was given (the
+   * pack depends on the level it proves): at call start, so the read runs while the call is set up.
+   * The first `context()` then waits for it within `timeouts.contextVoiceStart`. Never throws.
+   */
+  begin() {
+    const session = this.session;
+    if (!isConversation(session)) return;
+    const start = () => {
+      this.safe("start the first read", () => {
+        this.begun = session.begin();
+      });
+    };
+    if (this.proof === void 0 || this.proof === null) start();
+    else void this.verifyOnce().then(start);
+  }
+  /** Verifies once (when a proof was given), then reads the context. Never rejects. */
+  async context(options = {}) {
+    await this.verifyOnce();
+    try {
+      const session = this.session;
+      if (this.begun && !this.opened && isConversation(session)) {
+        this.opened = true;
+        await session.ready(options.timeout === void 0 ? {} : { timeout: options.timeout });
+      }
+      return await this.session.context(options);
+    } catch (error) {
+      this.logger.warn(`could not read context (${errorName(error)})`);
+      return emptyResult(null);
+    }
+  }
+  /** Records that `context` went into the prompt, unless it was empty for a reason other than the holdout. */
+  injected(context) {
+    if (!context.text && !context.suffix && context.response?.path !== "holdout") return;
+    this.safe("mark the injection", () => {
+      this.session.markInjected(context);
+    });
+  }
+  customer(text, options = {}) {
+    const session = this.session;
+    if (!text.trim() || !isConversation(session)) return;
+    this.safe("record the customer's turn", () => session.customer(text, options));
+  }
+  /** Sends the customer's turn so far, while they speak. In the background; never throws. */
+  prefetch(text) {
+    const session = this.session;
+    if (!text.trim() || !isConversation(session)) return;
+    this.safe("prefetch the turn", () => session.prefetch(text));
+  }
+  agent(text, options = {}) {
+    if (!text.trim()) return;
+    this.safe("record the agent's turn", () => this.session.agent(text, options));
+  }
+  /** Records a transfer. Tasks have no transfer; the call is ignored for them. */
+  async handoff(target, reason) {
+    const session = this.session;
+    if (!isConversation(session)) return;
+    try {
+      await session.handoff(reason ? { target, reason } : { target });
+    } catch (error) {
+      this.logger.warn(`could not record the handoff (${errorName(error)})`);
+    }
+  }
+  async end() {
+    try {
+      await this.session.end();
+    } catch (error) {
+      this.logger.warn(`could not end the session (${errorName(error)})`);
+    }
+  }
+  /** The navigation kit as plain specs (with the agent's memory tools when enabled), or none for a task about an object only. */
+  tools() {
+    let bound;
+    try {
+      const memory = this.memory;
+      bound = this.session.tools(memory === false ? {} : { agentMemory: true, writeAgentMemory: memory !== true && memory.write === true });
+    } catch (error) {
+      this.logger.warn(`could not build the tools (${errorName(error)})`);
+      return [];
+    }
+    return bound ? toolSpecs(bound) : [];
+  }
+  async agentMemory(params, options) {
+    try {
+      const result = await this.session.agentMemory(params, options.timeout === void 0 ? {} : { timeout: options.timeout });
+      return result.text;
+    } catch (error) {
+      this.logger.warn(`could not read the agent's memory (${errorName(error)})`);
+      return "";
+    }
+  }
+  async verifyOnce() {
+    if (this.proof === void 0 || this.proof === null) return;
+    this.proving ??= this.runVerify();
+    await this.proving;
+  }
+  async runVerify() {
+    try {
+      const source = this.proof;
+      const proof = typeof source === "function" ? await source() : source;
+      if (!proof) return;
+      await this.session.verify(proof);
+    } catch (error) {
+      this.logger.warn(`could not record the verification (${errorName(error)})`);
+    }
+  }
+  safe(what, run) {
+    try {
+      run();
+    } catch (error) {
+      this.logger.warn(`could not ${what} (${errorName(error)})`);
+    }
+  }
+};
+function withoutWrite(option) {
+  const { write: _, ...params } = option;
+  return params;
+}
+function toolSpecs(bound) {
+  return bound.definitions.map(({ function: definition }) => ({
+    name: definition.name,
+    description: definition.description,
+    parameters: definition.parameters,
+    execute: (args) => bound.call(definition.name, args)
+  }));
+}
+function count(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+// src/integrations/livekit.ts
+var LEADING_IDS = /* @__PURE__ */ new Set(["lk.agent_task.instructions", "lk.expressive.instructions"]);
+var INSTRUCTION_ROLES = /* @__PURE__ */ new Set(["system", "developer"]);
+var CONTEXT_ID = "niadra.context";
+var rawTool = llm.tool;
+var SUFFIX_ID = "niadra.suffix";
+function sipSubject(participant) {
+  const phone = participant.attributes?.["sip.phoneNumber"]?.trim();
+  if (phone) return handles.phone(phone.startsWith("+") ? phone : `+${phone}`);
+  return handles.appUserId(participant.identity);
+}
+function sipConversationId(participant, roomName) {
+  const callId = participant.attributes?.["sip.callID"]?.trim();
+  if (callId) return callId;
+  return roomName;
+}
+var NiadraMemory = class {
+  conversation;
+  bridge;
+  recordAgent;
+  customerTurns = /* @__PURE__ */ new Set();
+  usage = null;
+  /** The final transcript segments of the turn the caller is still speaking. */
+  heard = [];
+  constructor(options) {
+    this.conversation = options.conversation;
+    this.bridge = new Bridge(options.conversation, options.verify, options.agentMemory);
+    this.bridge.begin();
+    this.recordAgent = options.recordAgent ?? true;
+  }
+  /**
+   * Records the customer's final transcript, then puts the pack after the instructions and the
+   * suffix after the new message, for this reply only. Never throws.
+   */
+  async onUserTurnCompleted(turnCtx, newMessage) {
+    this.recordCustomer(newMessage);
+    const read = await this.bridge.read();
+    try {
+      const items = turnCtx.items;
+      for (const id of [CONTEXT_ID, SUFFIX_ID]) {
+        const index = items.findIndex((item) => item.id === id);
+        if (index >= 0) items.splice(index, 1);
+      }
+      if (read.prefix) {
+        let position = 0;
+        while (position < items.length && isInstruction(items[position])) position++;
+        const message = turnCtx.addMessage({ id: CONTEXT_ID, role: "system", content: read.prefix });
+        items.splice(items.indexOf(message), 1);
+        items.splice(position, 0, message);
+      }
+      if (read.suffix) turnCtx.addMessage({ id: SUFFIX_ID, role: "system", content: read.suffix });
+      this.bridge.injected(read.context);
+    } catch (error) {
+      this.bridge.logger.warn(`could not inject context (${errorName(error)})`);
+    }
+  }
+  /**
+   * Listens to the session: the agent's answers, handoffs between agents and the end of the call.
+   * Returns a function that stops listening.
+   */
+  attach(session) {
+    const onItem = (event) => {
+      this.onItem(event.item);
+    };
+    const onMetrics = (event) => {
+      const metrics = event.metrics;
+      if (metrics.type === "llm_metrics") this.usage = usageOf(metrics);
+    };
+    const onClose = () => {
+      void this.bridge.end();
+    };
+    const onTranscribed = (event) => {
+      this.bridge.prefetch(this.hearing(event.transcript, event.isFinal));
+    };
+    session.on(voice.AgentSessionEventTypes.ConversationItemAdded, onItem);
+    session.on(voice.AgentSessionEventTypes.MetricsCollected, onMetrics);
+    session.on(voice.AgentSessionEventTypes.UserInputTranscribed, onTranscribed);
+    session.on(voice.AgentSessionEventTypes.Close, onClose);
+    return () => {
+      session.off(voice.AgentSessionEventTypes.ConversationItemAdded, onItem);
+      session.off(voice.AgentSessionEventTypes.MetricsCollected, onMetrics);
+      session.off(voice.AgentSessionEventTypes.UserInputTranscribed, onTranscribed);
+      session.off(voice.AgentSessionEventTypes.Close, onClose);
+    };
+  }
+  /** The navigation kit as LiveKit function tools, bound to this caller. */
+  tools() {
+    return this.bridge.tools().map(
+      (spec) => rawTool({
+        name: spec.name,
+        description: spec.description,
+        parameters: spec.parameters,
+        // LiveKit serializes what a tool returns; the parsed result keeps the model's JSON unescaped.
+        execute: async (args) => parsed(await spec.execute(args ?? {}))
+      })
+    );
+  }
+  /** The same tools grouped as one toolset, to add next to your own. */
+  toolset() {
+    return new llm.Toolset({ id: "niadra", tools: this.tools() });
+  }
+  /**
+   * Records a transfer to a person, such as a SIP transfer to the queue. Call it right before
+   * the transfer, so the attendant's screen can read the context at once.
+   */
+  handoffToHuman(reason) {
+    return this.bridge.handoff("human", reason);
+  }
+  onItem(item) {
+    if (item.type === "agent_handoff") {
+      const reason = item.oldAgentId ? `${item.oldAgentId} to ${item.newAgentId}` : `to ${item.newAgentId}`;
+      void this.bridge.handoff("agent", reason);
+      return;
+    }
+    if (item.role === "user") {
+      this.recordCustomer(item);
+      return;
+    }
+    if (item.role !== "assistant" || !this.recordAgent) return;
+    const text = item.textContent ?? "";
+    const usage = this.usage;
+    this.usage = null;
+    this.bridge.agent(text, usage ? { usage, idempotency_key: item.id } : { idempotency_key: item.id });
+  }
+  /** The turn so far: its final segments and, when `transcript` is interim, that one too. */
+  hearing(transcript, isFinal) {
+    const text = transcript.trim();
+    if (isFinal && text) {
+      this.heard.push(text);
+      return this.heard.join(" ");
+    }
+    return (text ? [...this.heard, text] : this.heard).join(" ");
+  }
+  recordCustomer(message) {
+    if (this.customerTurns.has(message.id)) return;
+    this.customerTurns.add(message.id);
+    this.heard = [];
+    const confidence = message.transcriptConfidence;
+    this.bridge.customer(message.textContent ?? "", {
+      idempotency_key: message.id,
+      ...typeof confidence === "number" && confidence >= 0 && confidence <= 1 ? { stt_confidence: confidence } : {}
+    });
+  }
+};
+var NiadraAgent = class extends voice.Agent {
+  memory;
+  constructor({ memory, historyTools = true, ...options }) {
+    const tools = historyTools ? withToolset(options.tools, memory.toolset()) : options.tools;
+    super(tools === void 0 ? options : { ...options, tools });
+    this.memory = memory;
+  }
+  async onUserTurnCompleted(turnCtx, newMessage) {
+    await this.memory.onUserTurnCompleted(turnCtx, newMessage);
+  }
+};
+function withToolset(tools, toolset) {
+  const base = tools === void 0 ? [] : llm.toToolContext(tools).tools;
+  return new llm.ToolContext([...base, toolset]);
+}
+function parsed(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function isInstruction(item) {
+  if (!item) return false;
+  if (LEADING_IDS.has(item.id)) return true;
+  return item.type === "message" && INSTRUCTION_ROLES.has(item.role);
+}
+function usageOf(metrics) {
+  const provider = metrics.metadata?.modelProvider?.toLowerCase();
+  const model = metrics.metadata?.modelName;
+  const prompt = count(metrics.promptTokens);
+  if (!provider || !model || provider === "unknown" || model === "unknown" || !prompt) return null;
+  const cached = count(metrics.promptCachedTokens) ?? 0;
+  const written = count(metrics.cacheCreationTokens) ?? 0;
+  return { provider, model, prompt_tokens: Math.max(prompt, cached + written), cached_tokens: cached, cache_write_tokens: written };
+}
+
+export { NiadraAgent, NiadraMemory, attestationProof, sipConversationId, sipSubject };
+//# sourceMappingURL=livekit.js.map
+//# sourceMappingURL=livekit.js.map