API & SDK

# Core types and utilities
npm install @colineapp/kairo-core

# OAuth authentication helpers
npm install @colineapp/kairo-auth

# AI agent streaming client
npm install @colineapp/kairo-agent

# Kairo Code client with ACP/A2A adapter helpers
npm install @colineapp/kairo-code

# ACP CLI bridge for editors
npm install @colineapp/kairo-code-acp

import {
  createAuthorizationRequest,
  exchangeAuthorizationCode,
  createTokenManager,
  MemoryTokenStorage,
} from '@colineapp/kairo-auth';

// 1. Create authorization request with PKCE
const authRequest = await createAuthorizationRequest({
  clientId: 'your-client-id',
  redirectUri: 'https://yourapp.com/callback',
  scope: ['kairo.agent:stream', 'kairo.models:read'],
});

// 2. Redirect user to authRequest.url
// User authorizes and is redirected back with ?code=...

// 3. Exchange code for tokens
const result = await exchangeAuthorizationCode({
  clientId: 'your-client-id',
  redirectUri: 'https://yourapp.com/callback',
  code: authorizationCode,
  codeVerifier: authRequest.pkce.codeVerifier,
});

// 4. Use token manager for automatic refresh
const tokenManager = createTokenManager({
  storage: new MemoryTokenStorage(),
  clientId: 'your-client-id',
});

await tokenManager.setTokens(result.tokens);

import {
  startDeviceAuthorization,
  pollDeviceAuthorization,
} from '@colineapp/kairo-auth';

// 1. Start device authorization
const device = await startDeviceAuthorization({
  clientId: 'your-client-id',
  scope: ['kairo.agent:stream', 'kairo.models:read'],
});

// 2. Display instructions to user
console.log(`Go to: ${device.verification_uri}`);
console.log(`Enter code: ${device.user_code}`);

// 3. Poll for authorization (blocks until user completes flow)
const result = await pollDeviceAuthorization({
  clientId: 'your-client-id',
  deviceCode: device.device_code,
  intervalSeconds: device.interval,
  expiresInSeconds: device.expires_in,
  onPending: ({ attempt }) => {
    console.log(`Waiting for authorization... (attempt ${attempt})`);
  },
});

console.log('Authorized! Access token:', result.tokens.accessToken);

import { createKairoAgent } from '@colineapp/kairo-agent';

const agent = createKairoAgent({
  auth: tokenManager, // or access token string
});

// Stream with full control
const { events } = await agent.stream({
  contents: [
    {
      role: 'user',
      parts: [{ text: 'Explain how OAuth 2.0 works' }],
    },
  ],
  modelType: 'claude-opus-4.6', // optional, defaults to gpt-5.2
  reasoningLevel: 1, // 0 disables thinking, >0 enables it
  thinkingEffort: 'high', // Opus 4.6 only: low | medium | high | max
});

for await (const event of events) {
  if (event.parsed && event.data?.candidate_content?.parts) {
    for (const part of event.data.candidate_content.parts) {
      if (part.text) {
        process.stdout.write(part.text);
      }
    }
  }
}

// Or use streamText for simple text accumulation
const text = await agent.streamText({
  contents: [
    {
      role: 'user',
      parts: [{ text: 'Write a haiku about APIs' }],
    },
  ],
});

console.log(text);

import { createKairoCode } from '@colineapp/kairo-code';

const code = createKairoCode({ auth: tokenManager });

const { events } = await code.streamAcp({
  modelId: 'claude-opus-4.6',
  enableTools: false,
  reasoningEnabled: true,
  thinkingEffort: 'high',
  messages: [
    { role: 'user', content: 'Create a README for this repo.' },
  ],
});

for await (const event of events) {
  if (event.type === 'message_delta') {
    process.stdout.write(event.text);
  }
  if (event.type === 'workspace_unavailable') {
    console.error(event.message);
  }
}

bun add -g --no-cache @colineapp/kairo-code-acp

import { listKairoModels } from '@colineapp/kairo-core';

const { models, defaultModel } = await listKairoModels();
console.log('Default:', defaultModel);
console.log('Available:', models);

import {
  createTokenManager,
  MemoryTokenStorage,
} from '@colineapp/kairo-auth';

const tokenManager = createTokenManager({
  storage: new MemoryTokenStorage(), // or implement KairoTokenStorage
  clientId: 'your-client-id',
  minValidityMs: 30000, // refresh 30s before expiry
});

// Get a valid access token (refreshes automatically if needed)
const accessToken = await tokenManager.getAccessToken();

// Manually refresh
await tokenManager.refresh();

// Clear stored tokens
await tokenManager.clear();

interface KairoTokenStorage {
  getTokens(): Promise<KairoTokenSet | null> | KairoTokenSet | null;
  setTokens(tokens: KairoTokenSet | null): Promise<void> | void;
}

import { KairoError } from '@colineapp/kairo-core';

try {
  const { events } = await agent.stream({ contents: [...] });
} catch (error) {
  if (error instanceof KairoError) {
    console.error('Code:', error.code);
    console.error('Message:', error.message);
    console.error('Status:', error.status);
    console.error('Details:', error.details);
  }
}