API Reference

Complete API documentation for all 18 colony-harness packages. Each package includes install commands, quick examples, and parameter tables.

---

Core Runtime

Core

colony-harness

Core runtime package. Contains HarnessBuilder, ColonyHarness, AgenticLoop, ToolRegistry, MemoryManager, TraceHub, Guardrails, and 5 built-in guards.

pnpm add colony-harness

HarnessBuilder

Declarative builder API — the single entry point. Chains LLM, tools, memory, tracing, and guards into a runtime.

import { HarnessBuilder } from 'colony-harness'

const harness = new HarnessBuilder()
  .llm(provider)
  .tool(calculatorTool)
  .memory(adapter)
  .trace(exporter)
  .guard(new PromptInjectionGuard())
  .build()

Method	Parameter	Description
llm(provider)	LLMProvider	Inject model caller (required)
tool(...tools)	ToolDefinition[]	Register tools
toolApproval(cb)	(name, input) => Promise<boolean>	High-risk tool approval callback
memory(adapter)	MemoryAdapter	Specify memory backend
memoryConfig(cfg)	See below	Configure memory strategy
trace(...exporters)	TraceExporter[]	Configure trace exporters
guard(...guards)	Guard[]	Configure guards
loopConfig(cfg)	See below	Configure Agentic Loop behavior
systemPrompt(text)	string	Override default system prompt
build()	—	Build and return ColonyHarness instance

loopConfig parameters:

Field	Default	Description
maxIterations	20	Maximum loop iterations
callTimeout	30000	Single model call timeout (ms)
modelFailStrategy	abort	Model fail strategy: abort / retry
modelRetryMax	2	Max model retries (when strategy is retry)
modelRetryBaseDelayMs	300	Base backoff delay for model retries (ms)
modelRetryMaxDelayMs	5000	Max backoff delay for model retries (ms)
modelRetryJitterRatio	0.2	Retry jitter ratio for model calls (0~1)
modelRetryMaxTotalDelayMs	15000	Max aggregate delay budget for model retries (ms)
modelCircuitBreakerEnabled	true	Enable model circuit breaker
modelCircuitBreakerFailureThreshold	5	Consecutive transient failures before opening circuit
modelCircuitBreakerCooldownMs	30000	Circuit breaker cooldown duration (ms)
maxTokens	none	Total token limit
toolConcurrency	1	Tool concurrency level
toolFailStrategy	abort	Fail strategy: abort / continue / retry
toolRetryMax	2	Max retries (when strategy is retry)

memoryConfig parameters:

Field	Default	Description
workingMemoryTokenLimit	6000	Working memory compression threshold
episodicRetentionDays	30	Episodic retention period in days
semanticTopK	5	Default semantic search result count
autoCompress	true	Enable automatic context compression
embedder	none	Semantic embedding function (text) => number[]

ColonyHarness

Runtime container. Registers task handlers, builds context, executes guards and tracing.

const harness = builder.build()

harness.task('chat', async (ctx) => {
  const result = await ctx.runLoop('User question')
  return result
})

const result = await harness.runTask('chat', { question: 'Hello' })

Method	Parameter	Description
task(capability, handler)	string, (ctx) => Promise	Register task handler
runTask(capability, input, opts?)	See below	Execute task

runTask options:

Field	Description
taskId	External task ID (aligns with control plane)
agentId	Agent identifier
sessionId	Session identifier
signal	AbortSignal for cancellation

HarnessContext

Context object available within task handlers.

harness.task('research', async (ctx) => {
  // Run Agent Loop
  const reply = await ctx.runLoop('Search for latest papers')

  // Invoke tool directly
  const calc = await ctx.invokeTool('calculator', { expression: '2+2' })

  // Memory operations
  await ctx.memory.save('key', { data: 'value' })
  const recent = await ctx.memory.recent(10)

  // Tracing
  const span = ctx.trace.startSpan('step')
  span.end()
})

Property/Method	Type	Description
runLoop(prompt)	string => Promise<string>	Start Agentic Loop
invokeTool(name, input)	(string, any) => Promise<any>	Directly invoke a registered tool
callModel(messages)	Message[] => Promise<ModelResponse>	Directly call the LLM
callModelWithTools(msgs, tools)	LLM call with tool definitions	Call LLM with tool list
memory	MemoryHandle	Memory operation interface
trace	TraceHandle	Trace operation interface
input	any	Task input data

Built-in Guards

All guards are exported from the colony-harness package.

Guard	Description	Configuration
PromptInjectionGuard	Regex-based injection detection	None
PIIGuard	Redact Chinese ID/phone/email	None
TokenLimitGuard	Reject inputs exceeding token threshold	{ maxTokens: number }
SensitiveWordGuard	Reject inputs with sensitive words	{ words: string[] }
RateLimitGuard	Sliding window rate limiting	{ windowMs, maxRequests }

Error Classes

Error Class	Scenario
HarnessError	Base error
ToolNotFoundError	Tool not registered
ToolInputValidationError	Tool input validation failed
ToolOutputValidationError	Tool output validation failed
ToolApprovalDeniedError	Tool approval denied
LoopMaxIterationsError	Max iterations reached
LoopMaxTokensError	Max tokens reached
GuardBlockedError	Blocked by guard
MemoryAdapterError	Memory adapter exception

---

LLM Providers

LLM

@colony-harness/llm-openai

OpenAI Chat Completions API adapter. Handles tool calling, token usage tracking, and timeout with AbortController.

pnpm add @colony-harness/llm-openai

import { OpenAIProvider } from '@colony-harness/llm-openai'

const provider = new OpenAIProvider({
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4o',
})

Parameter	Required	Default	Description
apiKey	Yes	—	OpenAI API Key
model	Yes	—	Model name
baseUrl	No	https://api.openai.com/v1	Custom endpoint
temperature	No	—	Sampling temperature
timeoutMs	No	—	Request timeout (ms)
headers	No	—	Additional request headers

LLM

@colony-harness/llm-anthropic

Anthropic Messages API adapter. Auto-separates system messages, maps tool_use format, normalizes stop_reason.

pnpm add @colony-harness/llm-anthropic

import { AnthropicProvider } from '@colony-harness/llm-anthropic'

const provider = new AnthropicProvider({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: 'claude-sonnet-4-20250514',
})

Parameter	Required	Default	Description
apiKey	Yes	—	Anthropic API Key
model	Yes	—	Claude model name
baseUrl	No	https://api.anthropic.com	Custom endpoint
maxTokens	No	—	Output token limit
temperature	No	—	Sampling temperature
timeoutMs	No	—	Timeout (ms)
anthropicVersion	No	2023-06-01	API version
headers	No	—	Additional headers

LLM

@colony-harness/llm-gemini

Google Gemini generateContent API adapter. Maps message roles and functionDeclarations, normalizes finishReason.

pnpm add @colony-harness/llm-gemini

import { GeminiProvider } from '@colony-harness/llm-gemini'

const provider = new GeminiProvider({
  apiKey: process.env.GEMINI_API_KEY!,
  model: 'gemini-1.5-pro',
})

Parameter	Required	Default	Description
apiKey	Yes	—	Gemini API Key
model	Yes	—	Model name
baseUrl	No	Gemini API URL	Custom endpoint
temperature	No	—	Sampling temperature
timeoutMs	No	—	Timeout (ms)
headers	No	—	Additional headers

LLM

@colony-harness/llm-openai-compatible

Universal adapter for any OpenAI Chat Completions-compatible endpoint. Extends OpenAIProvider. Ideal for domestic LLMs or self-hosted endpoints.

pnpm add @colony-harness/llm-openai-compatible

import { OpenAICompatibleProvider, createOpenAICompatibleProviderFromEnv } from '@colony-harness/llm-openai-compatible'

// Manual creation
const provider = new OpenAICompatibleProvider({
  apiKey: 'your-key',
  model: 'your-model',
  baseUrl: 'https://your-endpoint.com/v1',
})

// Create from environment variables
const provider2 = createOpenAICompatibleProviderFromEnv()

Parameter	Required	Description
apiKey	Yes	API Key
model	Yes	Model name
baseUrl	Yes	Compatible endpoint URL (required)
...others	—	Same as OpenAIProvider

All providers return a unified ModelResponse containing content, toolCalls, stopReason (completed | tool_calls | max_tokens | unknown), and usage.

---

Memory Adapters

Memory

@colony-harness/memory-sqlite

SQLite persistent memory adapter. Supports indexed agent+created_at queries, cosine similarity semantic search, session-based cleanup, and auto table creation.

pnpm add @colony-harness/memory-sqlite

import { SqliteMemoryAdapter } from '@colony-harness/memory-sqlite'

const memory = new SqliteMemoryAdapter({
  path: './data/agent-memory.db',
})

Parameter	Default	Description
path	./memory.db	SQLite database file path

Memory

@colony-harness/memory-redis

Redis memory adapter. Hash entries, sorted sets for time ordering, pipeline-optimized writes, JS-side cosine similarity search.

pnpm add @colony-harness/memory-redis

import { RedisMemoryAdapter } from '@colony-harness/memory-redis'

const memory = new RedisMemoryAdapter({
  url: process.env.REDIS_URL,
  namespace: 'my-agent',
})

Parameter	Default	Description
url	REDIS_URL env var	Redis connection URL
namespace	colony:memory	Key prefix
redis	—	Pass an existing ioredis instance

---

Trace Exporters

Trace

@colony-harness/trace-console

ANSI-colored terminal trace exporter. Displays TraceID, task info, duration, metrics, and span details.

pnpm add @colony-harness/trace-console

import { ConsoleTraceExporter } from '@colony-harness/trace-console'

const exporter = new ConsoleTraceExporter()

No configuration needed. Works out of the box.

Trace

@colony-harness/trace-file

JSONL file trace exporter. Appends completed traces to a configurable file path. Supports pretty-print JSON mode.

pnpm add @colony-harness/trace-file

import { FileTraceExporter } from '@colony-harness/trace-file'

const exporter = new FileTraceExporter({
  path: './logs/traces.jsonl',
  pretty: true,
})

Parameter	Default	Description
path	./traces.jsonl	Output file path
pretty	false	Enable pretty-print JSON

Trace

@colony-harness/trace-otel

OpenTelemetry bridge exporter. Converts traces to OTel spans, aligned with OpenInference semantics (openinference.span.kind, session.id, user.id, input/output.value and mime_type).

pnpm add @colony-harness/trace-otel

import { OpenTelemetryTraceExporter } from '@colony-harness/trace-otel'

const exporter = new OpenTelemetryTraceExporter()

Requires @opentelemetry/api SDK to be initialized first. Maps colony-harness spans as events on a root OTel span.

Trace

@colony-harness/trace-langfuse

Native Langfuse exporter. Sends traces and observations via the batch ingestion API. Supports custom fetch and tags.

pnpm add @colony-harness/trace-langfuse

import { LangfuseTraceExporter } from '@colony-harness/trace-langfuse'

const exporter = new LangfuseTraceExporter({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  baseUrl: 'https://cloud.langfuse.com',
})

Parameter	Required	Description
publicKey	Yes	Langfuse Public Key
secretKey	Yes	Langfuse Secret Key
baseUrl	No	Langfuse instance URL
fetch	No	Custom fetch implementation
tags	No	Additional tags

---

Built-in Tools

Tools

@colony-harness/tools-builtin

Eight built-in tools covering math, file ops, HTTP, shell commands, web search, JSON queries, and template rendering.

pnpm add @colony-harness/tools-builtin

Register all tools at once:

import { createBuiltinTools } from '@colony-harness/tools-builtin'

const allTools = createBuiltinTools({
  file: { baseDir: '/workspace', allowOutsideBaseDir: false },
  runCommand: { mode: 'allowlist', allowed: ['ls', 'cat', 'grep'] },
})

Individual Tool Details

calculatorTool — Safe math expression evaluation

import { calculatorTool } from '@colony-harness/tools-builtin'
// Input: { expression: "1 + 2 * 3" }
// Output: { result: 7 }

Strict character filtering — only numbers and basic operators allowed.

httpRequestTool — HTTP requests

// Input: { method: "GET", url: "https://api.example.com/data", headers: {} }
// Output: { status: 200, headers: {...}, body: "..." }

Configurable timeout and max body size.

createReadFileTool(options) — Read files

import { createReadFileTool } from '@colony-harness/tools-builtin'

const readFile = createReadFileTool({
  baseDir: '/workspace',
  allowOutsideBaseDir: false,
})

Path sandboxing prevents directory traversal attacks.

createWriteFileTool(options) — Write files

const writeFile = createWriteFileTool({
  baseDir: '/workspace',
})

Supports append mode and auto-creating directories.

createRunCommandTool(options) — Execute shell commands

import { createRunCommandTool } from '@colony-harness/tools-builtin'

const runCmd = createRunCommandTool({
  mode: 'allowlist',
  allowed: ['ls', 'cat', 'grep', 'node'],
  timeout: 30_000,
  approvalByRisk: {
    requiredFrom: 'medium',
    callback: async (cmd) => {
      return confirm(`Allow: ${cmd}?`)
    },
  },
})

Parameter	Description
mode	'allowlist' or 'blocklist'
allowed / blocked	Command allowlist/blocklist
timeout	Execution timeout (ms)
approvalByRisk	Risk-based approval configuration

Defaults to blocking dangerous commands like rm, sudo, dd. Returns an audit field for audit logging.

createSearchWebTool(provider?) — Web search

import { createSearchWebTool } from '@colony-harness/tools-builtin'

const search = createSearchWebTool() // Default: DuckDuckGo

Pluggable SearchWebProvider interface for other search engines.

jsonQueryTool — JSON queries

// Input: { data: { a: { b: [1, 2, 3] } }, path: "$.a.b[0]" }
// Output: { result: 1 }

JSONPath-like syntax ($.a.b[0].c). Read-only, no side effects.

templateRenderTool — Template rendering

// Input: { template: "Hello {{name}}, score is {{score}}", data: { name: "Alice", score: 95 } }
// Output: { result: "Hello Alice, score is 95" }

placeholder rendering. Read-only, no side effects.

---

Evaluation

Eval

@colony-harness/evals

Complete evaluation toolkit. Contains runEvalSuite runner, seven built-in Scorers, and evaluateGate quality gate.

pnpm add @colony-harness/evals

import { runEvalSuite, exactMatchScorer, evaluateGate } from '@colony-harness/evals'

const report = await runEvalSuite({
  cases: [
    { id: 'test-1', input: '1+1', expected: '2' },
  ],
  runner: async (input) => myAgent(input),
  scorer: exactMatchScorer(),
})

const gate = evaluateGate({ report, thresholds: { minPassRate: 0.95 } })

runEvalSuite

Parameter	Type	Description
cases	EvalCase[]	Test case dataset
runner	(input) => Promise<any>	Function being evaluated
scorer	Scorer	Scoring function
signal	AbortSignal	Abort signal
failFast	boolean	Stop on first failure

Built-in Scorers

Scorer	Purpose	Configuration
exactMatchScorer()	Exact JSON structural match	None
containsScorer(opts)	Contains expected phrases	{ ignoreCase?, mode: 'all' | 'any' }
regexScorer(opts)	Regex pattern matching	{ flags? }
numericRangeScorer()	Numeric range validation	{ min?, max? }
llmJudgeScorer(opts)	LLM-based subjective scoring	{ judge, passThreshold }
safetyScorer(opts)	Safety pattern checking	{ blockedPatterns?, requiredPatterns? }
latencyScorer(opts)	Latency scoring	{ targetMs, maxMs }

evaluateGate

const gate = evaluateGate({
  report,
  thresholds: {
    minPassRate: 0.95,
    minWeightedScore: 0.85,
    maxLatencyMs: 5000,
  },
})
// gate.passed: boolean
// gate.failures: string[]

---

Control Plane

Control Plane

@colony-harness/controlplane-contract

Unified port contract for the control plane. Defines all interface types with no implementation.

pnpm add @colony-harness/controlplane-contract

Core exported types:

Type	Description
ControlPlanePort	Control plane interface: start(), stop(), onTaskAssign(), onTaskCancel(), reportProgress(), reportResult(), reportHealth()
TaskEnvelope	Task envelope (contains capability, input, etc.)
TaskResultEnvelope	Task result envelope
TaskErrorEnvelope	Task error envelope
TaskProgressEvent	Progress event
HealthStatusEvent	Health status event
TaskExecutionMetrics	Execution metrics

Control Plane

@colony-harness/controlplane-runtime

Runtime bridge. Connects ColonyHarness core with ControlPlanePort. Manages task lifecycle, registers handlers, tracks running tasks with AbortController for cancellation.

pnpm add @colony-harness/controlplane-runtime

import { HarnessControlPlaneRuntime } from '@colony-harness/controlplane-runtime'

const runtime = new HarnessControlPlaneRuntime(harness, controlPlaneAdapter)
await runtime.start()

Control Plane

@colony-harness/controlplane-mock-adapter

In-memory mock adapter. Stores progress events, results, and health events. Supports dispatchTask() for direct task injection in tests.

pnpm add @colony-harness/controlplane-mock-adapter

import { MockControlPlaneAdapter } from '@colony-harness/controlplane-mock-adapter'

const mock = new MockControlPlaneAdapter()
await mock.dispatchTask({ capability: 'chat', input: { msg: 'hello' } })

Control Plane

@colony-harness/controlplane-sdk-adapter

Queen SDK adapter. Connects to the Queen control plane via colony-bee-sdk. Uses duck-typed BeeAgentLike interface (no hard dependency). Supports dynamic SDK loading.

pnpm add @colony-harness/controlplane-sdk-adapter

import { BeeSDKControlPlaneAdapter, loadBeeAgentFromModule } from '@colony-harness/controlplane-sdk-adapter'

const adapter = new BeeSDKControlPlaneAdapter({
  colonyId: 'my-colony',
  capabilities: ['analyze', 'summarize'],
})

Exported utilities:

Export	Description
BeeSDKControlPlaneAdapter	Queen control plane adapter
loadBeeAgentFromModule(path)	Dynamic SDK module loader
InMemoryBeeAgentStub	In-memory BeeAgent stub for testing