@terminaluse/vercel-ai-sdk-provider 0.2.0 → 0.4.0

package/README.md

@@ -36,9 +36,39 @@ const result = await streamText({
 | Option | Type | Description |
 |--------|------|-------------|
 | `taskId` | `string` | Task ID to send messages to (required) |
+| `event` | `object` | Optional explicit task event override (`content`, `persistMessage`, `idempotencyKey`) |
 
 Tasks must be created separately using the [`@terminaluse/sdk`](https://www.npmjs.com/package/@terminaluse/sdk).
 
+### Sending data events
+
+By default, the provider sends a text event derived from the last prompt message.
+If you need to send a structured task event (for example, AskUserQuestion answers),
+pass `providerOptions.terminaluse.event`:
+
+```typescript
+await streamText({
+  model: terminaluse.agent('namespace/agent-name'),
+  messages: [],
+  providerOptions: {
+    terminaluse: {
+      taskId,
+      event: {
+        content: {
+          type: 'data',
+          data: {
+            type: 'ask_user_answer',
+            answers: { 'Question?': 'Answer' },
+          },
+        },
+        persistMessage: false,
+        idempotencyKey: 'optional-idempotency-key',
+      },
+    },
+  },
+});
+```
+
 ## Conversation Continuity
 
 To maintain conversation history across multiple interactions, create a task once

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import { LanguageModel } from "ai";
+import { TerminalUse } from "@terminaluse/sdk";
 
 //#region src/provider.d.ts
 interface TerminalUseProviderConfig {
@@ -18,6 +19,31 @@ interface TerminalUseProvider {
 interface TerminalUseProviderOptions {
   /** Task ID to send messages to (required) */
   taskId: string;
+  /** Skip task event dispatch and only stream task output */
+  skipSend?: boolean;
+  /** Optional absolute URL override for stream endpoint */
+  streamUrl?: string;
+  /** Optional headers for stream requests (e.g. bridge auth) */
+  streamHeaders?: Record<string, string>;
+  /**
+   * Optional override for the outbound task event. If omitted, provider sends
+   * a text event derived from the latest prompt message (default behavior).
+   */
+  event?: TerminalUseProviderTaskEventOptions;
+}
+interface TerminalUseProviderTaskEventOptions {
+  /**
+   * Explicit event content to send. Supports text and data task events.
+   */
+  content: NonNullable<TerminalUse.CreateTaskEventRequest['content']>;
+  /**
+   * Whether TerminalUse should persist this event as a message.
+   */
+  persistMessage?: boolean;
+  /**
+   * Optional idempotency key for retry-safe event delivery.
+   */
+  idempotencyKey?: string;
 }
 /**
  * Creates a custom AI SDK provider for TerminalUse agents.
@@ -48,4 +74,4 @@ interface TerminalUseProviderOptions {
  */
 declare function createTerminalUseProvider(config: TerminalUseProviderConfig): TerminalUseProvider;
 //#endregion
-export { type TerminalUseProvider, type TerminalUseProviderConfig, type TerminalUseProviderOptions, createTerminalUseProvider };
+export { type TerminalUseProvider, type TerminalUseProviderConfig, type TerminalUseProviderOptions, type TerminalUseProviderTaskEventOptions, createTerminalUseProvider };

package/dist/index.mjs

@@ -1,22 +1,8 @@
 import { UnsupportedFunctionalityError } from "ai";
 import { createEventSourceResponseHandler, getFromApi } from "@ai-sdk/provider-utils";
 import { z } from "zod";
+import { TerminalUseClient } from "@terminaluse/sdk";
 
-//#region src/http.ts
-/**
-* Fetch wrapper with TerminalUse authentication headers.
-*/
-async function terminaluseFetch(config, path, options = {}) {
-	const headers = new Headers(options.headers);
-	if (config.apiKey) headers.set("Authorization", `Bearer ${config.apiKey}`);
-	if (!headers.has("Content-Type") && options.body) headers.set("Content-Type", "application/json");
-	return fetch(`${config.baseURL}${path}`, {
-		...options,
-		headers
-	});
-}
-
-//#endregion
 //#region src/ndjson-stream.ts
 /**
 * SSE streaming utility for TerminalUse task events.
@@ -64,6 +50,14 @@ const finishPartSchema = z.object({
 	totalUsage: streamUsageSchema,
 	metadata: streamMetadataSchema
 });
+const handlerCompletePartSchema = z.object({
+	type: z.literal("handler-complete"),
+	eventId: z.string(),
+	taskId: z.string(),
+	success: z.boolean(),
+	durationMs: z.number().int().nullable().optional(),
+	error: z.string().nullable().optional()
+});
 const textStartPartSchema = z.object({
 	type: z.literal("text-start"),
 	id: z.string(),
@@ -141,6 +135,7 @@ const textStreamPartSchema = z.discriminatedUnion("type", [
 	startStepPartSchema,
 	finishStepPartSchema,
 	finishPartSchema,
+	handlerCompletePartSchema,
 	textStartPartSchema,
 	textDeltaPartSchema,
 	textEndPartSchema,
@@ -159,10 +154,14 @@ const textStreamPartSchema = z.discriminatedUnion("type", [
 * Uses @ai-sdk/provider-utils for SSE parsing.
 */
 async function* createTaskEventGenerator(config, taskId, options = {}) {
-	const { signal } = options;
+	const { signal, streamUrl, streamHeaders } = options;
+	const headers = {
+		...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {},
+		...streamHeaders ?? {}
+	};
 	const { value: responseStream } = await getFromApi({
-		url: `${config.baseURL}/tasks/${encodeURIComponent(taskId)}/stream`,
-		headers: config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {},
+		url: streamUrl ?? `${config.baseURL}/tasks/${encodeURIComponent(taskId)}/stream`,
+		headers,
 		abortSignal: signal,
 		successfulResponseHandler: createEventSourceResponseHandler(textStreamPartSchema),
 		failedResponseHandler: async ({ response }) => {
@@ -189,8 +188,13 @@ async function* createTaskEventGenerator(config, taskId, options = {}) {
 * Creates a ReadableStream that transforms v2 TextStreamPart events to AI SDK v3 format.
 * Implements a thin passthrough adapter with minimal transformation logic.
 */
-function createTerminalUseTransformStream(config, taskId, signal) {
-	const eventGenerator = createTaskEventGenerator(config, taskId, { signal });
+function createTerminalUseTransformStream(config, taskId, signal, arg4, arg5) {
+	const { streamOverride, closeConfig } = resolveStreamArgs(arg4, arg5);
+	const eventGenerator = createTaskEventGenerator(config, taskId, {
+		signal,
+		streamUrl: streamOverride?.streamUrl,
+		streamHeaders: streamOverride?.streamHeaders
+	});
 	let emittedStreamStart = false;
 	return new ReadableStream({
 		async pull(controller) {
@@ -211,7 +215,7 @@ function createTerminalUseTransformStream(config, taskId, signal) {
 					}
 					const event = value;
 					const transformed = transformEvent(event, taskId);
-					if (event.type === "finish" || event.type === "error") {
+					if (shouldCloseStream(event, closeConfig)) {
 						if (transformed) controller.enqueue(transformed);
 						controller.close();
 						return;
@@ -265,6 +269,7 @@ function transformEvent(event, taskId) {
 				}
 			}
 		};
+		case "handler-complete": return null;
 		case "text-start": return {
 			type: "text-start",
 			id: event.id
@@ -331,9 +336,29 @@ function transformEvent(event, taskId) {
 		default: return null;
 	}
 }
+function shouldCloseStream(event, closeConfig) {
+	if (event.type === "error") return true;
+	if (closeConfig.closeMode === "legacy") return event.type === "finish";
+	return event.type === "handler-complete" && event.eventId === closeConfig.eventId;
+}
+function resolveStreamArgs(arg4, arg5) {
+	if (isStreamCloseConfig(arg4)) return {
+		streamOverride: void 0,
+		closeConfig: arg4
+	};
+	return {
+		streamOverride: arg4,
+		closeConfig: arg5 ?? { closeMode: "legacy" }
+	};
+}
+function isStreamCloseConfig(value) {
+	if (!value || typeof value !== "object") return false;
+	return "closeMode" in value;
+}
 
 //#endregion
 //#region src/provider.ts
+const HANDLER_COMPLETE_CLOSE_CAPABILITY = "handler-complete-close-v1";
 /**
 * Creates a custom AI SDK provider for TerminalUse agents.
 *
@@ -366,6 +391,10 @@ function createTerminalUseProvider(config) {
 		baseURL: config.baseURL,
 		apiKey: config.apiKey
 	};
+	const client = new TerminalUseClient({
+		environment: config.baseURL,
+		bearerAuth: { token: config.apiKey }
+	});
 	return { agent(agentName) {
 		return {
 			specificationVersion: "v3",
@@ -382,29 +411,68 @@ function createTerminalUseProvider(config) {
 				const { prompt, providerOptions, abortSignal } = options;
 				const tuOptions = providerOptions?.terminaluse;
 				if (!tuOptions?.taskId) throw new Error("taskId is required. Create a task via /api/tasks first.");
-				const { taskId } = tuOptions;
-				const userContent = prompt.at(-1)?.content;
-				let textContent;
-				if (Array.isArray(userContent)) {
-					const textPart = userContent.find((c) => c.type === "text");
-					if (textPart && textPart.type === "text") textContent = textPart.text;
-				} else if (typeof userContent === "string") textContent = userContent;
-				const sendResponse = await terminaluseFetch(tuConfig, `/tasks/${encodeURIComponent(taskId)}/events`, {
-					method: "POST",
-					body: JSON.stringify({ content: {
+				const { taskId, skipSend = false } = tuOptions;
+				const explicitEvent = tuOptions.event;
+				const defaultEventContent = (() => {
+					const userContent = prompt.at(-1)?.content;
+					let textContent;
+					if (Array.isArray(userContent)) {
+						const textPart = userContent.find((c) => c.type === "text");
+						if (textPart && textPart.type === "text") textContent = textPart.text;
+					} else if (typeof userContent === "string") textContent = userContent;
+					return {
 						type: "text",
 						text: textContent || ""
-					} })
-				});
-				if (!sendResponse.ok) {
-					const errorText = await sendResponse.text();
-					throw new Error(`Failed to send message: ${sendResponse.status} - ${errorText}`);
+					};
+				})();
+				if (!skipSend) {
+					const requestBody = {
+						task_id: taskId,
+						content: explicitEvent?.content ?? defaultEventContent,
+						...explicitEvent?.idempotencyKey ? { idempotency_key: explicitEvent.idempotencyKey } : {},
+						...typeof explicitEvent?.persistMessage === "boolean" ? { persist_message: explicitEvent.persistMessage } : {}
+					};
+					let sendEventResponse;
+					try {
+						sendEventResponse = await client.tasks.sendEvent(requestBody);
+					} catch (error) {
+						throw new Error(`Failed to send message: ${error instanceof Error ? error.message : String(error)}`);
+					}
+					const closeConfig = resolveStreamCloseConfig(sendEventResponse);
+					return { stream: typeof tuOptions.streamUrl === "string" || tuOptions.streamHeaders && Object.keys(tuOptions.streamHeaders).length > 0 ? createTerminalUseTransformStream(tuConfig, taskId, abortSignal, {
+						streamUrl: tuOptions.streamUrl,
+						streamHeaders: tuOptions.streamHeaders
+					}, closeConfig) : createTerminalUseTransformStream(tuConfig, taskId, abortSignal, closeConfig) };
 				}
-				return { stream: createTerminalUseTransformStream(tuConfig, taskId, abortSignal) };
+				return { stream: typeof tuOptions.streamUrl === "string" || tuOptions.streamHeaders && Object.keys(tuOptions.streamHeaders).length > 0 ? createTerminalUseTransformStream(tuConfig, taskId, abortSignal, {
+					streamUrl: tuOptions.streamUrl,
+					streamHeaders: tuOptions.streamHeaders
+				}) : createTerminalUseTransformStream(tuConfig, taskId, abortSignal) };
 			}
 		};
 	} };
 }
+function resolveStreamCloseConfig(response) {
+	const eventId = getStringProperty(response, "id");
+	const streamCapabilities = getStringArrayProperty(response, "streamCapabilities") ?? getStringArrayProperty(response, "stream_capabilities");
+	if (eventId && streamCapabilities?.includes(HANDLER_COMPLETE_CLOSE_CAPABILITY)) return {
+		closeMode: "handler-complete",
+		eventId
+	};
+	return { closeMode: "legacy" };
+}
+function getStringProperty(value, key) {
+	if (!value || typeof value !== "object") return;
+	const maybeValue = value[key];
+	return typeof maybeValue === "string" ? maybeValue : void 0;
+}
+function getStringArrayProperty(value, key) {
+	if (!value || typeof value !== "object") return;
+	const maybeArray = value[key];
+	if (!Array.isArray(maybeArray)) return;
+	if (!maybeArray.every((entry) => typeof entry === "string")) return;
+	return maybeArray;
+}
 
 //#endregion
 export { createTerminalUseProvider };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terminaluse/vercel-ai-sdk-provider",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Vercel AI SDK provider for TerminalUse agents",
   "repository": {
     "type": "git",
@@ -31,11 +31,13 @@
     "lint": "biome lint .",
     "format": "biome format --write .",
     "check": "biome check --write .",
-    "prepublishOnly": "bun run build"
+    "check:publish-manifest": "node ./scripts/check-publish-manifest.mjs",
+    "prepublishOnly": "bun run check:publish-manifest && bun run build"
   },
   "dependencies": {
     "@ai-sdk/provider": "^3.0.0",
     "@ai-sdk/provider-utils": "^4.0.0",
+    "@terminaluse/sdk": "^0.7.0",
     "zod": "^3.24.0"
   },
   "peerDependencies": {