Full example

import { ApiError, classifyTurn, createKortix, narrowChatEvent } from '@kortix/sdk';
import type { MessageWithParts } from '@kortix/sdk';

async function main() {
  // 1. One client, one auth seam. getToken returns your API key
  //    (kortix_pat_…) or a logged-in user's Supabase JWT — nothing else.
  const kortix = createKortix({
    backendUrl: 'https://api.kortix.com/v1',
    getToken: async () => process.env.KORTIX_API_KEY!,
  });

  // 2. Platform REST: list projects, pick one (or provision your first).
  const projects = await kortix.projects.list();
  const project = projects[0] ?? (await kortix.projects.provision({ name: 'sdk-quickstart' }));
  console.log(`using project ${project.name} (${project.project_id})`);

  // 3. Create a session — a cheap platform call. No sandbox exists yet.
  const created = await kortix.projects.createSession(project.project_id, {
    name: 'sdk full example',
  });
  const session = kortix.session(project.project_id, created.session_id);

  // 4. Ready the session. This provisions (or resumes) the real cloud
  //    sandbox. Each ensureReady() call is ONE bounded long-poll — on a
  //    cold boot it throws a typed RUNTIME_UNAVAILABLE ApiError while the
  //    sandbox is still coming up, so retry until it resolves.
  const { opencodeSessionId } = await retryUntilReady(() => session.ensureReady());

  // 5. Connect the event stream BEFORE sending, so no early events are
  //    missed. narrowChatEvent() collapses the wire events into a small
  //    typed union you can switch over.
  let resolveIdle!: () => void;
  const idle = new Promise<void>((resolve) => (resolveIdle = resolve));

  const stream = await session.stream({
    onEvent: (event) => {
      const e = narrowChatEvent(event);
      if (!e) return;
      if (e.type === 'message.part.updated') process.stdout.write('.');
      if (e.type === 'session.error') console.error('\nerror:', e.error);
      if (e.type === 'session.idle' && e.sessionID === opencodeSessionId) {
        resolveIdle(); // the turn is finished
      }
    },
  });

  // 6. Send. Per-send overrides let you pick the model and the agent for
  //    just this prompt (ids come from projects.llmCatalog() and
  //    projects.detail().config.agents).
  await session.send('What files are in this repo?', {
    model: { providerID: 'kortix', modelID: 'claude-sonnet-4.6' },
  });

  // 7. Wait for the turn to finish — the session.idle event, not a sleep.
  await idle;
  stream.close();

  // 8. Render the transcript. classifyTurn() collapses ~50 wire part
  //    variants into a compile-time-exhaustive union, so a renderer can
  //    switch (part.kind) and TypeScript proves no case is missed.
  const result = await session.runtime.session.messages({
    sessionID: opencodeSessionId,
  });
  for (const message of (result.data ?? []) as MessageWithParts[]) {
    for (const part of classifyTurn(message).parts) {
      if (part.kind === 'text') console.log(`\n[${message.info.role}] ${part.text}`);
    }
  }
}

/** Retry ensureReady() while the sandbox is provisioning (cold boots take a while). */
async function retryUntilReady<T>(ensure: () => Promise<T>): Promise<T> {
  const deadline = Date.now() + 300_000;
  for (;;) {
    try {
      return await ensure();
    } catch (error) {
      const provisioning = error instanceof ApiError && error.code === 'RUNTIME_UNAVAILABLE';
      if (!provisioning || Date.now() > deadline) throw error;
      await new Promise((r) => setTimeout(r, 3_000));
    }
  }
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

KORTIX_API_KEY=kortix_pat_... npx tsx full-example.ts

const project = kortix.project(projectId);

// Workspace files inside the session's live sandbox
const tree = await session.files.list('/workspace');
const readme = await session.files.read('/workspace/README.md');

// Project secrets — env vars every session's agent can read at runtime
await project.secrets.upsert({ name: 'MY_API_KEY', value: 'sk-…' });

// The project's agents, skills, and slash commands (config files in the repo)
const { config } = await kortix.projects.detail(projectId);
console.log(
  config.agents.map((a) => a.name),
  config.skills.length,
);

// LLM gateway observability — cost, latency, per-model breakdown
const overview = await project.gateway.overview(7);

// Channels: connect the project to Slack, email, or a meeting bot
const slack = await project.channels.slack.installation();