SDK API

Installation

npm install @honeybee-ai/hivemind-sdk

Subpath exports

Import path	Contents
`@honeybee-ai/hivemind-sdk`	`createPlatformClient`
`@honeybee-ai/hivemind-sdk/contracts`	Zod schemas for all API types
`@honeybee-ai/hivemind-sdk/integrations`	`ToolResult`, `ToolDef`, `ToolEntry`, `PluginContext`, `IncubatorPlugin`
`@honeybee-ai/hivemind-sdk/telemetry`	`TelemetryReporter`, `createTelemetryFromEnv`
`@honeybee-ai/hivemind-sdk/config`	`loadConfig`, `loadGlobalConfig`

Platform client

import { createPlatformClient } from '@honeybee-ai/hivemind-sdk';

const client = createPlatformClient({ profile: 'default' });

Hive methods

Method	Returns	Description
`listHives()`	`Hive[]`	List all hives
`createHive(opts)`	`Hive`	Create a new hive
`getHive(id)`	`Hive`	Get hive by ID
`updateHive(id, opts)`	`Hive`	Update hive config
`deleteHive(id)`	`void`	Delete a hive
`startHive(id)`	`void`	Start hive execution
`stopHive(id)`	`void`	Stop hive execution

Secret methods

Method	Returns	Description
`setSecret(opts)`	`void`	Store a provider API key
`listSecrets()`	`Secret[]`	List stored secrets
`deleteSecret(provider)`	`void`	Delete a stored secret

Marketplace methods

Method	Returns	Description
`searchMarketplace(query)`	`Protocol[]`	Search protocols
`getProtocol(name)`	`Protocol`	Get protocol details
`installProtocol(name)`	`void`	Install a protocol
`publishProtocol(spec)`	`void`	Publish a protocol

Contracts (Zod schemas)

import {
  HiveSchema,
  AgentSchema,
  ProtocolSchema,
  SecretSchema,
  TelemetryEventSchema,
} from '@honeybee-ai/hivemind-sdk/contracts';

Key schemas

Schema	Fields
`HiveSchema`	id, name, status, protocol_name, execution_mode, container_url, created_at
`AgentSchema`	id, role, type, provider, status, hive_id
`SecretSchema`	provider, scope, hive_id
`TelemetryEventSchema`	type, timestamp, payload

Integration types

import type {
  ToolResult,
  ToolDef,
  ToolEntry,
  PluginContext,
  IncubatorPlugin,
} from '@honeybee-ai/hivemind-sdk/integrations';

ToolEntry

interface ToolEntry {
  name: string;
  description: string;
  parameters: object;  // JSON Schema
  handler: (args: any, ctx?: PluginContext) => Promise<ToolResult>;
}

ToolResult

interface ToolResult {
  result?: any;
  error?: string;
}

IncubatorPlugin

interface IncubatorPlugin {
  name: string;
  getToolEntries(ctx: PluginContext): ToolEntry[];
  start?(ctx: PluginContext): Promise<void>;
  stop?(): Promise<void>;
}

PluginContext

interface PluginContext {
  workDir: string;
  guard?: any;
  verbose: boolean;
  toolFilter?: string[];
  fsBackend?: unknown;  // MemFS or RealFS
}

Telemetry reporter

import { createTelemetryFromEnv } from '@honeybee-ai/hivemind-sdk/telemetry';

const reporter = createTelemetryFromEnv('project-slug');

// Record (fire-and-forget, never throws)
reporter.record({ type: 'llm_call', model: 'claude-sonnet', promptTokens: 500, completionTokens: 200, latencyMs: 1500 });

// Snapshot (for dashboards)
const snapshot = reporter.getSnapshot();

// Flush on shutdown
await reporter.flush();

Config loader

import { loadConfig, loadGlobalConfig } from '@honeybee-ai/hivemind-sdk/config';

const config = loadConfig();           // Project .wglrc
const global = loadGlobalConfig();     // Global ~/.wglrc