@consciousclouds/conductor-sdk

Types + a thin client for the Conductor runtime — the single AI engine the platform's products consume as registered personalities. Two endpoints: a streaming turn (Server-Sent Events) and an approval resolve.

Framework-agnostic and provider-agnostic — no product nouns, no React, no model provider. The authoritative contract is the JSON Schema under platform/contracts/conductor/v1/; the generated types derive from it.

baseUrl is a configurable Conductor-compatible endpoint — the SDK never hard-codes a gateway URL, never adds a gateway route, and never mints identity. It forwards the Authorization / X-Tenant-ID headers the caller supplies.

Exports

| Subpath | What | |---|---| | . | everything below | | ./client | createConductorClient(), ConductorClientError, parseSseFrames() | | ./types | TurnRequest, ResolveResult, the SSE event payloads, CompletedResult | | ./tools | ToolDeclaration, TOOL_CATEGORIES | | ./personalities | PersonalityDeclaration, PERSONALITY_TIERS | | ./capabilities | Capability, CAPABILITY_PATTERN, isCapability() | | ./validate | validateTurnRequest(), validateResolveRequest(), validateSseEvent() |

Usage

import { createConductorClient } from '@consciousclouds/conductor-sdk';

const conductor = createConductorClient({
  baseUrl: process.env.CONDUCTOR_BASE_URL!, // a Conductor-compatible endpoint
  headers: () => ({
    Authorization: `Bearer ${getToken()}`,
    'X-Tenant-ID': getTenantId(),
  }),
});

// Stream a turn, frame by frame.
await conductor.stream({ prompt: 'Summarize my environments' }, (name, data) => {
  if (name === 'delta') process.stdout.write(data.text);
  if (name === 'approval_required') {
    void conductor.resolveApproval(data.approval_id, 'approve');
  }
});

// Or the convenience form: accumulate text + get the completed payload.
const result = await conductor.turn({ prompt: 'Hello' });
console.log(result.text, result.cost_usd);

The frozen event set

started, delta, tool_start, tool_done, approval_required, completed, error. Adding an event is additive in platform/contracts/conductor/v1/; regenerate with python platform/codegen/conductor/generate.py (or bun run generate:conductor).

SDK rule

Types + thin HTTP wrapper only — no business logic, no caching, no retries-with-elevation. The runtime authorizes every request against the caller's identity; this SDK never decides authorization.