SDK API Reference

Last updated April 7, 2026

Every @kb-labs/sdk export — navigational index to the detailed SDK docs.

@kb-labs/sdk is the single import point for plugin authors. This page is a navigational index — each export group links to the detailed docs page that covers it in full.

For the full overview of what the SDK is and how it's structured, start with SDK → Overview.

Handler definitions

One helper per host type. Import from @kb-labs/sdk:

Export	Host	Docs
`defineCommand`	CLI, Workflow	SDK → Commands
`defineRoute`	REST	SDK → Routes
`defineAction`	REST (higher-level)	SDK → Routes
`defineWebhook`	Webhook	—
`defineWebSocket`	WebSocket	—

Type guards for runtime host checks: isCLIHost, isRESTHost, isWorkflowHost, isWebhookHost, isWSHost.

Runtime hooks

All hooks read from the global platform singleton. Import from @kb-labs/sdk:

Hook	Returns	Always present?	Docs
`usePlatform()`	`Platform`	✅	SDK → Hooks
`useLogger()`	`ILogger`	✅	SDK → Hooks
`useLLM()`	`ILLM \| undefined`	❌	SDK → Hooks
`useCache()`	`ICache \| undefined`	❌	SDK → Hooks
`useStorage()`	`IStorage \| undefined`	❌	SDK → Hooks
`useVectorStore()`	`IVectorStore \| undefined`	❌	SDK → Hooks
`useEmbeddings()`	`IEmbeddings \| undefined`	❌	SDK → Hooks
`useAnalytics()`	`IAnalytics \| undefined`	❌	SDK → Hooks
`useConfig<T>(key?)`	`Promise<T \| undefined>`	❌	SDK → Hooks

useLogger always returns a logger — the platform provides a no-op fallback if no logger adapter is configured. All other hooks return undefined when the adapter isn't configured; always check before use:

TypeScript

const cache = useCache();
if (cache) {
  const hit = await cache.get<Result>(key);
}

Availability guards: isPlatformConfigured, isLLMAvailable, isCacheAvailable, isVectorStoreAvailable, isEmbeddingsAvailable.

Manifest helpers

TypeScript

import {
  defineManifest,       // typed ManifestV3 builder
  defineCommandFlags,   // typed flag schemas for cli.commands[i].flags
  defineFlags,          // general-purpose typed flag schema
  generateExamples,
} from '@kb-labs/sdk';

defineCommandFlags is the most commonly used — it lets you declare flags once and get both CLI parsing and type inference. See Plugins → Manifest Reference for the full manifest schema.

Permission primitives

TypeScript

import {
  combinePermissions,   // chainable builder
  combinePresets,       // convenience: combinePresets(a, b, c)
  minimalPreset,
  gitWorkflowPreset,
  npmPublishPreset,
  fullEnvPreset,
  kbPlatformPreset,
  llmAccessPreset,
  vectorStorePreset,
  ciEnvironmentPreset,
} from '@kb-labs/sdk';

See Plugins → Permissions for the full permission model.

Key types

TypeScript

import type {
  // Context
  PluginContextV3,
  HostContext,
  HostType,
  PlatformServices,
  // Adapters
  ILLM, ICache, IStorage, ILogger, IAnalytics, IEmbeddings, IVectorStore,
  // LLM
  LLMTier,           // 'small' | 'medium' | 'large'
  LLMOptions,
  LLMResponse,
  LLMMessage,
  LLMTool,
  // Manifest
  ManifestV3,
  PermissionSpec,
  // Results
  CommandResult,
  // UI data contracts
  TableData, ListData, MetricData, SelectData,
  // WebSocket
  WSMessage, WSSender,
  // Shell
  ShellAPI, ExecResult,
} from '@kb-labs/sdk';

See SDK → Handler Context for the full PluginContextV3 shape.

Utilities

TypeScript

import {
  // UI
  useLoader,              // spinner for CLI output
  displayArtifacts,
  displayArtifactsCompact,
  displaySingleArtifact,
 
  // Errors
  defineError,
  PluginError,
  commonErrors,
 
  // Environment
  defineEnv,
  parseEnvFromRuntime,
 
  // Tools (for LLM function-calling)
  createTool,
 
  // Repo introspection
  findRepoRoot,
  discoverSubRepoPaths,
} from '@kb-labs/sdk';

LLM tiers

The SDK exposes LLM access via useLLM(). The LLMTier controls which model class to use:

Tier	Use for
`'small'`	Fast, cheap operations — classification, extraction, yes/no
`'medium'`	Default — code analysis, generation, reasoning
`'large'`	Complex multi-step reasoning, architecture analysis

See SDK → LLM Tiers for guidance on when to use each.

Testing

TypeScript

import { createTestContext } from '@kb-labs/sdk';
// Full mock builders:
import { /* ... */ } from '@kb-labs/sdk/testing';

See SDK → Testing.

Detailed SDK docs

Page	Covers
Overview	What the SDK exports and when to import what
Quickstart	Smallest possible plugin, end-to-end
Commands	`defineCommand`, flags, handler lifecycle
Routes	`defineRoute`, input/output schemas, Zod integration
Hooks	Every hook — full API of each service
Handler Context	Everything in `ctx`
LLM Tiers	When to use `small`, `medium`, `large`
Testing	`createTestContext` and mock builders
Migration	Breaking changes and upgrade paths