@terminaluse/vercel-ai-sdk-provider 0.0.3 → 0.1.0

package/README.md

@@ -1,15 +1,59 @@
 # @terminaluse/vercel-ai-sdk-provider
 
-To install dependencies:
+Vercel AI SDK provider for TerminalUse agents. Implements `LanguageModelV3`.
+
+Use [`@terminaluse/sdk`](https://www.npmjs.com/package/@terminaluse/sdk) to create projects, filesystems, tasks, and manage your TerminalUse resources.
+
+## Install
 
 ```bash
-bun install
+npm install @terminaluse/vercel-ai-sdk-provider
+```
+
+## Usage
+
+```typescript
+import { createTerminalUseProvider } from '@terminaluse/vercel-ai-sdk-provider';
+import { streamText } from 'ai';
+
+const terminaluse = createTerminalUseProvider({
+  apiKey: process.env.TERMINALUSE_API_KEY!,
+  baseURL: process.env.TERMINALUSE_BASE_URL!,
+});
+
+// Stream messages to an existing task
+const result = await streamText({
+  model: terminaluse.agent('namespace/agent-name'),
+  messages: [{ role: 'user', content: 'Hello' }],
+  providerOptions: {
+    terminaluse: { taskId: 'existing-task-id' },
+  },
+});
 ```
 
-To run:
+## Provider Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `taskId` | `string` | Task ID to send messages to (required) |
+
+Tasks must be created separately using the [`@terminaluse/sdk`](https://www.npmjs.com/package/@terminaluse/sdk).
+
+## Requirements
+
+- Node.js 18+
+- ESM projects (this package is ESM-only)
+- `ai` package v6.0.0+ (peer dependency)
+
+## Development
 
 ```bash
-bun run index.ts
+bun install
+bun run dev      # watch mode
+bun test         # run tests
+bun run build    # production build
 ```
 
-This project was created using `bun init` in bun v1.3.3. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+## License
+
+Apache-2.0

package/dist/index.d.mts

@@ -1 +1,51 @@
-export { };
+import { LanguageModel } from "ai";
+
+//#region src/provider.d.ts
+interface TerminalUseProviderConfig {
+  /** API key for authentication (Bearer token) */
+  apiKey: string;
+  /** TerminalUse API base URL */
+  baseURL: string;
+}
+interface TerminalUseProvider {
+  /** Create a language model for the specified agent */
+  agent(agentName: string): LanguageModel;
+}
+/**
+ * Provider options for TerminalUse agents.
+ * Task must be created separately via the /api/tasks endpoint.
+ */
+interface TerminalUseProviderOptions {
+  /** Task ID to send messages to (required) */
+  taskId: string;
+}
+/**
+ * Creates a custom AI SDK provider for TerminalUse agents.
+ *
+ * This provider implements the LanguageModelV3 interface, bridging
+ * Vercel AI SDK's useChat/streamText to TerminalUse's RPC-based API.
+ *
+ * Note: Tasks must be created separately via the /api/tasks endpoint
+ * before sending messages.
+ *
+ * @example
+ * ```ts
+ * const terminaluse = createTerminalUseProvider({
+ *   apiKey: process.env.TERMINALUSE_API_KEY!,
+ *   baseURL: process.env.TERMINALUSE_API_BASE_URL!,
+ * });
+ *
+ * const result = await streamText({
+ *   model: terminaluse.agent('namespace/agent-name'),
+ *   messages,
+ *   providerOptions: {
+ *     terminaluse: {
+ *       taskId: 'existing-task-id',
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function createTerminalUseProvider(config: TerminalUseProviderConfig): TerminalUseProvider;
+//#endregion
+export { type TerminalUseProvider, type TerminalUseProviderConfig, type TerminalUseProviderOptions, createTerminalUseProvider };

package/dist/index.mjs

@@ -1,5 +1,412 @@
-//#region index.ts
-console.log("Hello via Bun!");
+import { UnsupportedFunctionalityError } from "ai";
+import { createEventSourceResponseHandler, getFromApi } from "@ai-sdk/provider-utils";
+import { z } from "zod";
+
+//#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.
+* Uses @ai-sdk/provider-utils for clean SSE parsing.
+*
+* This module handles the v2 TextStreamPart format from the backend,
+* which is based on Vercel AI SDK's TextStreamPart with extensions.
+*/
+const streamMetadataSchema = z.object({
+	costUsd: z.number().optional(),
+	durationMs: z.number().optional(),
+	cacheCreationInputTokens: z.number().optional(),
+	cacheReadInputTokens: z.number().optional(),
+	parentToolUseId: z.string().optional()
+}).optional();
+const streamUsageSchema = z.object({
+	inputTokens: z.number(),
+	outputTokens: z.number(),
+	totalTokens: z.number().optional()
+});
+const finishReasonSchema = z.enum([
+	"stop",
+	"tool-calls",
+	"length",
+	"content-filter",
+	"error",
+	"other"
+]);
+const startPartSchema = z.object({ type: z.literal("start") });
+const startStepPartSchema = z.object({
+	type: z.literal("start-step"),
+	request: z.record(z.unknown()).optional(),
+	warnings: z.array(z.unknown()).optional(),
+	metadata: streamMetadataSchema
+});
+const finishStepPartSchema = z.object({
+	type: z.literal("finish-step"),
+	finishReason: finishReasonSchema,
+	usage: streamUsageSchema,
+	metadata: streamMetadataSchema
+});
+const finishPartSchema = z.object({
+	type: z.literal("finish"),
+	finishReason: finishReasonSchema,
+	totalUsage: streamUsageSchema,
+	metadata: streamMetadataSchema
+});
+const textStartPartSchema = z.object({
+	type: z.literal("text-start"),
+	id: z.string(),
+	metadata: streamMetadataSchema
+});
+const textDeltaPartSchema = z.object({
+	type: z.literal("text-delta"),
+	id: z.string(),
+	text: z.string(),
+	metadata: streamMetadataSchema
+});
+const textEndPartSchema = z.object({
+	type: z.literal("text-end"),
+	id: z.string(),
+	metadata: streamMetadataSchema
+});
+const reasoningStartPartSchema = z.object({
+	type: z.literal("reasoning-start"),
+	id: z.string(),
+	metadata: streamMetadataSchema
+});
+const reasoningDeltaPartSchema = z.object({
+	type: z.literal("reasoning-delta"),
+	id: z.string(),
+	text: z.string(),
+	metadata: streamMetadataSchema
+});
+const reasoningEndPartSchema = z.object({
+	type: z.literal("reasoning-end"),
+	id: z.string(),
+	metadata: streamMetadataSchema
+});
+const toolInputStartPartSchema = z.object({
+	type: z.literal("tool-input-start"),
+	id: z.string(),
+	toolName: z.string(),
+	metadata: streamMetadataSchema
+});
+const toolInputDeltaPartSchema = z.object({
+	type: z.literal("tool-input-delta"),
+	id: z.string(),
+	delta: z.string(),
+	metadata: streamMetadataSchema
+});
+const toolInputEndPartSchema = z.object({
+	type: z.literal("tool-input-end"),
+	id: z.string(),
+	metadata: streamMetadataSchema
+});
+const toolCallPartSchema = z.object({
+	type: z.literal("tool-call"),
+	toolCallId: z.string(),
+	toolName: z.string(),
+	input: z.record(z.unknown()),
+	metadata: streamMetadataSchema
+});
+const toolResultPartSchema = z.object({
+	type: z.literal("tool-result"),
+	toolCallId: z.string(),
+	toolName: z.string(),
+	output: z.unknown(),
+	metadata: streamMetadataSchema
+});
+const errorPartSchema = z.object({
+	type: z.literal("error"),
+	error: z.string(),
+	rawContent: z.unknown().optional()
+});
+/**
+* Zod schema for v2 TextStreamPart events from the backend.
+* Based on Vercel AI SDK's TextStreamPart with extensions for reasoning and tool streaming.
+*/
+const textStreamPartSchema = z.discriminatedUnion("type", [
+	startPartSchema,
+	startStepPartSchema,
+	finishStepPartSchema,
+	finishPartSchema,
+	textStartPartSchema,
+	textDeltaPartSchema,
+	textEndPartSchema,
+	reasoningStartPartSchema,
+	reasoningDeltaPartSchema,
+	reasoningEndPartSchema,
+	toolInputStartPartSchema,
+	toolInputDeltaPartSchema,
+	toolInputEndPartSchema,
+	toolCallPartSchema,
+	toolResultPartSchema,
+	errorPartSchema
+]);
+/**
+* Creates an async generator that yields v2 TextStreamPart events.
+* Uses @ai-sdk/provider-utils for SSE parsing.
+*/
+async function* createTaskEventGenerator(config, taskId, options = {}) {
+	const { signal } = options;
+	const { value: responseStream } = await getFromApi({
+		url: `${config.baseURL}/tasks/${encodeURIComponent(taskId)}/stream`,
+		headers: config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {},
+		abortSignal: signal,
+		successfulResponseHandler: createEventSourceResponseHandler(textStreamPartSchema),
+		failedResponseHandler: async ({ response }) => {
+			const text = await response.text();
+			return { value: /* @__PURE__ */ new Error(`Stream request failed: ${response.status} - ${text}`) };
+		}
+	});
+	const reader = responseStream.getReader();
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			const parseResult = value;
+			if (parseResult.success) yield parseResult.value;
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}
+
+//#endregion
+//#region src/stream.ts
+/**
+* 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 });
+	let emittedStreamStart = false;
+	return new ReadableStream({
+		async pull(controller) {
+			if (!emittedStreamStart) {
+				emittedStreamStart = true;
+				controller.enqueue({
+					type: "stream-start",
+					warnings: []
+				});
+				return;
+			}
+			try {
+				while (true) {
+					const { value, done } = await eventGenerator.next();
+					if (done || signal?.aborted) {
+						controller.close();
+						return;
+					}
+					const event = value;
+					const transformed = transformEvent(event, taskId);
+					if (event.type === "finish" || event.type === "error") {
+						if (transformed) controller.enqueue(transformed);
+						controller.close();
+						return;
+					}
+					if (transformed) {
+						controller.enqueue(transformed);
+						return;
+					}
+				}
+			} catch (error) {
+				eventGenerator.return?.(void 0);
+				controller.error(error);
+			}
+		},
+		cancel() {
+			eventGenerator.return?.(void 0);
+		}
+	});
+}
+/**
+* Transforms a single v2 TextStreamPart event to AI SDK v3 LanguageModelV3StreamPart.
+* Returns null for events that should be skipped (e.g., finish-step, start).
+*/
+function transformEvent(event, taskId) {
+	switch (event.type) {
+		case "start": return null;
+		case "start-step": return {
+			type: "response-metadata",
+			id: taskId,
+			timestamp: /* @__PURE__ */ new Date(),
+			modelId: "terminaluse-agent"
+		};
+		case "finish-step": return null;
+		case "finish": return {
+			type: "finish",
+			finishReason: {
+				unified: event.finishReason,
+				raw: event.finishReason
+			},
+			usage: {
+				inputTokens: {
+					total: event.totalUsage.inputTokens,
+					noCache: void 0,
+					cacheRead: void 0,
+					cacheWrite: void 0
+				},
+				outputTokens: {
+					total: event.totalUsage.outputTokens,
+					text: void 0,
+					reasoning: void 0
+				}
+			}
+		};
+		case "text-start": return {
+			type: "text-start",
+			id: event.id
+		};
+		case "text-delta": return {
+			type: "text-delta",
+			id: event.id,
+			delta: event.text
+		};
+		case "text-end": return {
+			type: "text-end",
+			id: event.id
+		};
+		case "reasoning-start": return {
+			type: "reasoning-start",
+			id: event.id
+		};
+		case "reasoning-delta": return {
+			type: "reasoning-delta",
+			id: event.id,
+			delta: event.text
+		};
+		case "reasoning-end": return {
+			type: "reasoning-end",
+			id: event.id
+		};
+		case "tool-input-start": return {
+			type: "tool-input-start",
+			id: event.id,
+			toolName: event.toolName,
+			providerExecuted: true,
+			dynamic: true
+		};
+		case "tool-input-delta": return {
+			type: "tool-input-delta",
+			id: event.id,
+			delta: event.delta
+		};
+		case "tool-input-end": return {
+			type: "tool-input-end",
+			id: event.id
+		};
+		case "tool-call": return {
+			type: "tool-call",
+			toolCallId: event.toolCallId,
+			toolName: event.toolName,
+			input: JSON.stringify(event.input),
+			providerExecuted: true,
+			dynamic: true
+		};
+		case "tool-result": {
+			const result = event.output ?? "";
+			return {
+				type: "tool-result",
+				toolCallId: event.toolCallId,
+				toolName: event.toolName,
+				result
+			};
+		}
+		case "error": return {
+			type: "error",
+			error: event.error
+		};
+		default: return null;
+	}
+}
+
+//#endregion
+//#region src/provider.ts
+/**
+* Creates a custom AI SDK provider for TerminalUse agents.
+*
+* This provider implements the LanguageModelV3 interface, bridging
+* Vercel AI SDK's useChat/streamText to TerminalUse's RPC-based API.
+*
+* Note: Tasks must be created separately via the /api/tasks endpoint
+* before sending messages.
+*
+* @example
+* ```ts
+* const terminaluse = createTerminalUseProvider({
+*   apiKey: process.env.TERMINALUSE_API_KEY!,
+*   baseURL: process.env.TERMINALUSE_API_BASE_URL!,
+* });
+*
+* const result = await streamText({
+*   model: terminaluse.agent('namespace/agent-name'),
+*   messages,
+*   providerOptions: {
+*     terminaluse: {
+*       taskId: 'existing-task-id',
+*     },
+*   },
+* });
+* ```
+*/
+function createTerminalUseProvider(config) {
+	const tuConfig = {
+		baseURL: config.baseURL,
+		apiKey: config.apiKey
+	};
+	return { agent(agentName) {
+		return {
+			specificationVersion: "v3",
+			provider: "terminaluse",
+			modelId: agentName,
+			supportedUrls: {},
+			async doGenerate() {
+				throw new UnsupportedFunctionalityError({
+					functionality: "non-streaming generation",
+					message: "TerminalUse provider only supports streaming. Use streamText() instead of generateText()."
+				});
+			},
+			async doStream(options) {
+				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: {
+						type: "text",
+						content: textContent || "",
+						author: "user",
+						format: "plain"
+					} })
+				});
+				if (!sendResponse.ok) {
+					const errorText = await sendResponse.text();
+					throw new Error(`Failed to send message: ${sendResponse.status} - ${errorText}`);
+				}
+				return { stream: createTerminalUseTransformStream(tuConfig, taskId, abortSignal) };
+			}
+		};
+	} };
+}
 
 //#endregion
-export {  };
+export { createTerminalUseProvider };

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@terminaluse/vercel-ai-sdk-provider",
-  "version": "0.0.3",
-  "description": "Vercel AI SDK provider for Terminal Use",
+  "version": "0.1.0",
+  "description": "Vercel AI SDK provider for TerminalUse agents",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/terminaluse/vercel-ai-sdk-provider.git"
+    "url": "git+https://github.com/terminal-use/monorepo.git",
+    "directory": "packages/vercel-ai-sdk-provider"
   },
+  "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
@@ -23,16 +25,30 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "test": "bun test",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "check": "biome check --write .",
     "prepublishOnly": "bun run build"
   },
+  "dependencies": {
+    "@ai-sdk/provider": "^3.0.0",
+    "@ai-sdk/provider-utils": "^4.0.0",
+    "zod": "^3.24.0"
+  },
+  "peerDependencies": {
+    "ai": "^6.0.0"
+  },
   "devDependencies": {
-    "@types/bun": "latest",
+    "@biomejs/biome": "^2.3.11",
+    "@types/node": "^20",
     "tsdown": "^0.16.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5",
+    "vitest": "^4.0.16"
   },
-  "peerDependencies": {
-    "typescript": "^5"
+  "engines": {
+    "node": ">=18.0.0"
   }
 }