@terminaluse/vercel-ai-sdk-provider

Vercel AI SDK provider for TerminalUse agents. Implements LanguageModelV3.

Use @terminaluse/sdk to create projects, filesystems, tasks, and manage your TerminalUse resources.

Install

npm install @terminaluse/vercel-ai-sdk-provider

Usage

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' },
  },
});

Provider Options

| 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.

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:

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 and reuse its ID for all subsequent messages:

import { TerminalUseClient } from '@terminaluse/sdk';

// 1. Create task once (at conversation start)
const client = new TerminalUseClient({ token: process.env.TERMINALUSE_API_KEY! });
const task = await client.tasks.create({ agent_name: 'namespace/my-agent' });
const taskId = task.id;  // Store this for the session

// 2. Send messages to the same task
const result = await streamText({
  model: terminaluse.agent('namespace/my-agent'),
  messages,
  providerOptions: { terminaluse: { taskId } },
});

Requirements

• Node.js 18+
• ESM projects (this package is ESM-only)
• ai package v6.0.0+ (peer dependency)

Development

bun install
bun run dev      # watch mode
bun test         # run tests
bun run build    # production build

License

Apache-2.0