Skip to content

api-reference.md

Latest commit

 

History

History
433 lines (310 loc) · 11 KB

api-reference.md

File metadata and controls

433 lines (310 loc) · 11 KB
Raw

SDK API Reference

Complete reference for all public exports from @bradygaster/squad-sdk. Each section includes types, functions, and usage examples.

Overview

import {
  // Resolution
  resolveSquad, resolveGlobalSquadPath, ensureSquadPath,

  // Runtime
  MODELS, TIMEOUTS, AGENT_ROLES,
  loadConfig, loadConfigSync,

  // Agents
  onboardAgent,

  // Casting
  CastingEngine, CastingHistory,

  // Coordinator
  SquadCoordinator, selectResponseTier, getTier,

  // Tools
  defineTool, ToolRegistry,

  // OTel
  initializeOTel, shutdownOTel, getTracer, getMeter,
  bridgeEventBusToOTel, createOTelTransport,
  initSquadTelemetry,
} from '@bradygaster/squad-sdk';

Resolution

Functions to locate Squad directories.

resolveSquad(startPath?: string): string

Find .squad/ directory starting from a path and walking up to the project root. Throws if not found.

const squadPath = resolveSquad();
const squadPath = resolveSquad('/home/user/project/src');

resolveGlobalSquadPath(): string

Get the platform-specific Squad config directory (~/.config/squad/ on Linux, ~/Library/Application Support/squad/ on macOS, %APPDATA%\squad\ on Windows). Squad 2.0 keeps only externalized project state there (projects/<projectKey>/, see squad externalize); no squad is resolved from it.

ensureSquadPath(startPath?: string): string

Like resolveSquad(), but creates the directory if it doesn't exist.

Runtime Constants

MODELS: ModelCatalog

All supported models, organized by tier.

MODELS.FALLBACK_CHAINS.premium;  // ['gpt-5.6-sol', 'claude-opus-5', ...]
MODELS.FALLBACK_CHAINS.standard; // ['gpt-5.6-terra', 'claude-sonnet-5', ...]
MODELS.FALLBACK_CHAINS.fast;     // ['gpt-5.6-luna', 'claude-haiku-4.5', 'gpt-5.4-mini', ...]

TIMEOUTS: TimeoutConfig

Standard timeout values for agent operations.

TIMEOUTS.agentInitMs;        // 30000 (30s)
TIMEOUTS.agentExecuteMs;     // 300000 (5 min)
TIMEOUTS.coordinatorRouteMs; // 5000 (5s)

AGENT_ROLES: Record<string, RoleDefinition>

Standard agent roles and their default properties.

Configuration

loadConfig(squadPath: string): Promise<ConfigLoadResult>

Load configuration asynchronously. Reads squad.config.ts (if present), parses routing/model overrides, validates schemas.

const config = await loadConfig('./.squad');
console.log(config.team.name);
console.log(Object.keys(config.agents));

Types:

interface ConfigLoadResult {
  team: {
    name: string;
    root: string;
    description?: string;
  };
  agents?: Record<string, AgentConfig>;
  routing?: RoutingConfig;
  models?: ModelConfig;
}

interface AgentConfig {
  role: string;
  model?: string;
  tools?: string[];
  status?: 'active' | 'inactive';
}

loadConfigSync(squadPath: string): ConfigLoadResult

Synchronous version of loadConfig().

Agents & Onboarding

onboardAgent(options: OnboardOptions): Promise<OnboardResult>

Create a new agent directory, charter, and history file.

const result = await onboardAgent({
  teamRoot: './.squad',
  agentName: 'data-analyst',
  role: 'backend',
  displayName: 'Dana — Data Analyst',
  projectContext: 'A recipe sharing app with PostgreSQL and React',
  userName: 'Alice',
});

Types:

interface OnboardOptions {
  teamRoot: string;
  agentName: string;
  role: string;
  displayName?: string;
  projectContext?: string;
  userName?: string;
  charterTemplate?: string;
}

interface OnboardResult {
  createdFiles: string[];
  agentDir: string;
  charterPath: string;
  historyPath: string;
}

Casting

CastingEngine

Generate agent personas from universe themes.

const engine = new CastingEngine({
  universes: ['The Wire', 'Seinfeld'],
  activeUniverse: 'The Wire',
});

const members = await engine.castTeam([
  { role: 'lead', title: 'Lead Developer' },
  { role: 'backend', title: 'Backend Engineer' },
]);

CastingHistory

Track all casting decisions over time.

const history = new CastingHistory('./.squad/casting');
const records = history.getRecordsByAgent('lead');
const previousCast = history.findByName('Stringer');

Types:

interface CastMember {
  name: string;
  role: string;
  universe: string;
  displayName: string;
}

Coordinator

SquadCoordinator

Main class for routing work to agents.

const coordinator = new SquadCoordinator({
  teamRoot: './.squad',
  enableParallel: true,
});

await coordinator.initialize();

const decision = await coordinator.route('refactor the API');
console.log(decision.tier);      // 'standard' or 'full'
console.log(decision.agents);    // ['backend', 'tester']
console.log(decision.parallel);  // true if multi-agent
console.log(decision.rationale); // Explanation of routing choice

await coordinator.execute(decision, 'refactor the API');
await coordinator.shutdown();

Types:

interface RoutingDecision {
  tier: ResponseTier;
  agents: string[];
  parallel: boolean;
  rationale: string;
}

type ResponseTier = 'direct' | 'lightweight' | 'standard' | 'full';

selectResponseTier(context: TierContext): TierName

Choose the right response tier for a task.

getTier(name: TierName): TierDefinition

Get configuration for a specific tier (max agents, default model, available tools).

Tools

defineTool<TArgs>(config: ToolConfig<TArgs>): SquadTool<TArgs>

Define a new tool with typed parameters.

const myTool = defineTool<{ query: string }>({
  name: 'search_docs',
  description: 'Search project documentation',
  parameters: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Search query' },
    },
    required: ['query'],
  },
  handler: async (args) => {
    const results = await searchDocs(args.query);
    return {
      textResultForLlm: `Found ${results.length} results`,
      resultType: 'success',
      toolTelemetry: { resultCount: results.length },
    };
  },
});

ToolRegistry

Manage the built-in tool set.

import { ToolRegistry } from '@bradygaster/squad-sdk/tools';
import type { FanOutDependencies } from '@bradygaster/squad-sdk/coordinator';

const registry = new ToolRegistry('./.squad');
const tools = registry.getTools();
const agentTools = registry.getToolsForAgent(['squad_route', 'squad_decide']);

Constructor: new ToolRegistry(squadRoot?, sessionPoolGetter?, storage?, state?, fanOutDepsGetter?)

  • fanOutDepsGetter — Required for squad_route to spawn sessions via spawnParallel. Returns a FanOutDependencies object (from @bradygaster/squad-sdk/coordinator). Without it, squad_route returns resultType: 'failure' with error: 'fan-out-deps-unavailable'.
  • state — When provided, squad_route validates that the target agent exists in the team roster before spawning.
  • Agent names must match /^[a-zA-Z0-9_-]+$/. Spawn errors are sanitized before being returned to the LLM.

Built-in tools:

Tool Purpose
squad_route Route a task to another agent (requires fanOutDepsGetter)
squad_decide Write decisions to the inbox
squad_memory Append to agent history
squad_status Query session pool state
squad_skill Read/write agent skills

Observability (OpenTelemetry)

Three-layer observability API for traces, metrics, and telemetry.

Layer 1: Low-Level Control

import { initializeOTel, shutdownOTel, getTracer, getMeter } from '@bradygaster/squad-sdk';

await initializeOTel({
  endpoint: 'http://localhost:4318',
  serviceName: 'my-squad',
});

const tracer = getTracer('my-component');
const meter = getMeter('my-component');

await shutdownOTel();

Layer 2: Mid-Level Bridge

import { bridgeEventBusToOTel, createOTelTransport } from '@bradygaster/squad-sdk';

const unsubscribe = bridgeEventBusToOTel(eventBus);
const transport = createOTelTransport();

Layer 3: High-Level Convenience

import { initSquadTelemetry } from '@bradygaster/squad-sdk';

const telemetry = await initSquadTelemetry({
  endpoint: 'http://localhost:4318',
  serviceName: 'my-squad',
  eventBus: myEventBus,
});

await telemetry.shutdown();

Streaming

createReadableStream(response: unknown): ReadableStream<string>

Convert an agent response to a readable stream.

const stream = createReadableStream(agentResponse);
const reader = stream.getReader();
let result;

while (!(result = await reader.read()).done) {
  console.log(result.value);
}

Upstream Inheritance

readUpstreamConfig(squadPath: string): Promise<UpstreamConfig>

Load upstream sources from .squad/upstream.json.

resolveUpstreams(config: UpstreamConfig, squadPath: string): Promise<ResolvedUpstream[]>

Resolve all upstreams and return their inherited content.

buildInheritedContextBlock(resolved: ResolvedUpstream[]): string

Build a markdown block of all inherited context (for agent charters).

buildSessionDisplay(resolved: ResolvedUpstream[]): string

Build a human-readable display of upstream sources (for squad status).

Glossary of Exports

Export Type Module Purpose
resolveSquad function resolution Find .squad directory
resolveGlobalSquadPath function resolution Platform config dir (externalized project state only)
ensureSquadPath function resolution Find or create .squad
MODELS constant runtime/constants Model catalog
TIMEOUTS constant runtime/constants Standard timeouts
AGENT_ROLES constant runtime/constants Agent role definitions
loadConfig function config Async config loading
loadConfigSync function config Sync config loading
onboardAgent function agents Create new agent
CastingEngine class casting Generate personas
CastingHistory class casting Track castings
SquadCoordinator class coordinator Route and orchestrate
selectResponseTier function coordinator Choose response tier
getTier function coordinator Get tier config
defineTool function tools Define custom tool
ToolRegistry class tools Manage tools
initializeOTel function runtime/otel Init OTel providers
shutdownOTel function runtime/otel Shutdown OTel
getTracer function runtime/otel Get tracer
getMeter function runtime/otel Get meter
bridgeEventBusToOTel function runtime/otel-bridge EventBus → OTel
createOTelTransport function runtime/otel-bridge Create OTel transport
initSquadTelemetry function runtime/otel-init One-call setup

See Also