@telnyx/ai-agent-lib 0.4.5 → 0.5.0-beta.0

package/dist/message.d.ts

@@ -1,3 +1,4 @@
+import type { FunctionCallItem, IAIConversationMessageEvent } from "@telnyx/webrtc";
 export type TranscriptMessage = {
     id: string;
     jsonrpc: "2.0";
@@ -48,6 +49,22 @@ export type ConversationItemCreatedMessage = {
     voice_sdk_id: string;
 };
 export declare function isConversationItemCreatedMessage(message: unknown): message is ConversationItemCreatedMessage;
+/**
+ * PR-531 `function_call` payload delivered by `@telnyx/webrtc` over the
+ * `SwEvent.AIConversationMessage` (`telnyx.ai.conversation`) event.
+ *
+ * These items intentionally have NO `params.item.content`, so they are never
+ * mistaken for transcript items by {@link isConversationItemCreatedMessage}
+ * (which requires `params.item.content`). Tool-call handling stays fully
+ * separate from transcript parsing.
+ */
+export declare function isAIConversationMessageEvent(event: unknown): event is IAIConversationMessageEvent;
+/**
+ * Extracts a PR-531 `function_call` item from an inbound
+ * `telnyx.ai.conversation` event, or returns `null` when the event is not an
+ * inbound function call (e.g. transcript / state / output messages).
+ */
+export declare function getFunctionCallItem(event: unknown): FunctionCallItem | null;
 export type ConversationItemDeletedMessage = {
     id: string;
     jsonrpc: "2.0";

package/dist/types.d.ts

@@ -1,5 +1,7 @@
 import type { INotification, Call, ICallOptions } from "@telnyx/webrtc";
 import { SwEvent } from "@telnyx/webrtc";
+import { isFunctionCallParams, isFunctionCallOutputParams } from "@telnyx/webrtc";
+import type { FunctionCallItem, FunctionCallOutputItem, AIConversationParams, IAIConversationMessageEvent } from "@telnyx/webrtc";
 export type Attachment = {
     type: "image";
     url: string;
@@ -11,6 +13,51 @@ export type TranscriptItem = {
     timestamp: Date;
     attachments?: Array<Attachment>;
 };
+/**
+ * Context passed to a client-side tool handler when ACA invokes a
+ * PR-531 `function_call`. Lets handlers correlate the invocation and read
+ * metadata without reaching into SDK internals.
+ */
+export type ClientSideToolContext = {
+    /** The PR-531 `call_id`. Must round-trip into the `function_call_output`. */
+    callId: string;
+    /** The registered tool name ACA asked to invoke. */
+    toolName: string;
+    /** Raw JSON `arguments` string exactly as received from ACA. */
+    rawArguments: string;
+};
+/**
+ * A client-side tool implementation. Receives the parsed `arguments` object
+ * (or `undefined` when ACA sends empty arguments) plus invocation context.
+ *
+ * The return value is serialized and sent back to ACA as the
+ * `function_call_output.output`. Strings are sent verbatim; anything else is
+ * JSON-stringified. Throwing (or rejecting) is caught and reported back to ACA
+ * as a safe error output so the conversation can continue.
+ */
+export type ClientSideToolHandler = (args: unknown, context: ClientSideToolContext) => unknown | Promise<unknown>;
+/** Map of tool name -> handler, accepted by the constructor. */
+export type ClientSideToolMap = Record<string, ClientSideToolHandler>;
+/** Reason a tool invocation produced an error output. */
+export type ClientSideToolErrorReason = "unknown_tool" | "invalid_arguments" | "handler_error" | "timeout" | "shutdown";
+/** Emitted when a client-side tool invocation begins. */
+export type ClientSideToolInvokedInfo = {
+    callId: string;
+    toolName: string;
+};
+/** Emitted when a client-side tool invocation produced an output for ACA. */
+export type ClientSideToolCompletedInfo = {
+    callId: string;
+    toolName: string;
+    /** True when the output represents a handled error rather than a result. */
+    isError: boolean;
+};
+/** Emitted when a client-side tool invocation failed and reported a safe error. */
+export type ClientSideToolErrorInfo = {
+    callId: string;
+    toolName: string;
+    reason: ClientSideToolErrorReason;
+};
 export type AgentStateData = {
     state: AgentState;
     /** Latency in milliseconds from when user stopped speaking until agent response began. Only present when state is "speaking". */
@@ -71,6 +118,9 @@ export type AIAgentEvents = {
     "conversation.update": (call: INotification) => void;
     "conversation.agent.state": (data: AgentStateData) => void;
     "agent.audio.mute": (muted: boolean) => void;
+    "client.tool.invoked": (info: ClientSideToolInvokedInfo) => void;
+    "client.tool.completed": (info: ClientSideToolCompletedInfo) => void;
+    "client.tool.error": (info: ClientSideToolErrorInfo) => void;
 };
 export type AgentState = "speaking" | "listening" | "thinking";
 export type TranscriptEvents = Pick<AIAgentEvents, "transcript.item">;
@@ -108,3 +158,5 @@ export type VADOptions = {
 };
 export type { INotification, Call, ICallOptions };
 export { SwEvent };
+export type { FunctionCallItem, FunctionCallOutputItem, AIConversationParams, IAIConversationMessageEvent, };
+export { isFunctionCallParams, isFunctionCallOutputParams };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@telnyx/ai-agent-lib",
   "private": false,
-  "version": "0.4.5",
+  "version": "0.5.0-beta.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -21,6 +21,8 @@
     "dev": "vite",
     "build": "tsc -p tsconfig.build.json && vite build",
     "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "format": "prettier --write .",
     "preview": "vite preview",
     "release": "release-it"
@@ -30,7 +32,7 @@
     "react-dom": "^19.1.0"
   },
   "dependencies": {
-    "@telnyx/webrtc": "2.27.1",
+    "@telnyx/webrtc": "2.27.2-beta.0",
     "eventemitter3": "^5.0.1",
     "jotai": "^2.12.5",
     "loglevel": "^1.9.2"
@@ -54,7 +56,8 @@
     "release-it": "^19.0.4",
     "typescript": "~5.8.3",
     "typescript-eslint": "^8.52.0",
-    "vite": "^7.0.4"
+    "vite": "^7.0.4",
+    "vitest": "^3.2.4"
   },
   "lint-staged": {
     "**/*.{ts,tsx,js,jsx}": [