@drover/core

Public types and identity builders. No runtime.

The substrate every other drover package depends on. Pure types and a couple of identity builders.

Exports

import {
  defineAgent,
  defineTool,
  // types
  type AgentSpec, type AgentInput, type AgentOutput,
  type ModelSpec, type ReasoningLevel, type SubagentConfig,
  type SystemPromptFn,
  type RunContext,
  type RunResult, type RunStatus,
  type HarnessEvent, type EventOfKind,
  type ToolResult, type Usage,
  type HarnessPlugin, type ToolDecision, type ErrorRecovery,
  type HistoryMessage,
  type ToolDef, type AnyToolDef, type ToolExecutionContext,
  // errors
  type HarnessError,
  InputValidationError, OutputValidationError,
  SubagentLimitError, QuotaExceededError,
  CancelledError, PausedForConfirmationError,
  ModelError, SandboxError, StorageError, PluginError,
} from "@drover/core";

`defineAgent`

function defineAgent<I extends TSchema, O extends TSchema>(
  spec: AgentSpec<I, O>
): AgentSpec<I, O>;

Identity builder. Returns the spec unchanged; exists so TypeScript infers Static<I> and Static<O> at call sites without manual generics. See AgentSpec.

`defineTool`

function defineTool<S extends TSchema>(tool: ToolDef<S>): ToolDef<S>;

Identity builder for ToolDef. Captures the TypeBox schema once so execute sees a statically-typed input.

Errors

Every drover error is a Data.TaggedError from Effect, so consumers can match by _tag:

import { OutputValidationError } from "@drover/core";

if (err._tag === "OutputValidationError") {
  // err.attempts, err.lastIssues, err.lastText all typed
}

The aggregate union is HarnessError. Use that as the Effect error channel when composing.

`RunResult`

interface RunResult<TOutput = unknown> {
  runId: string;
  status: "success" | "quota" | "cancelled" | "error" | "paused";
  output?: TOutput;
  finalText: string;
  turns: number;
  durationMs: number;
  usage: { inputTokens: number; outputTokens: number; costUsd?: number; ... };
  toolCalls: readonly string[];
  error?: { tag: string; message: string };
}

status: "paused" only when storage was wired and handle.pause() was called. The Promise resolution NEVER rejects — typed errors fold into error.

Tagged errors quick reference

`_tag`	when
`InputValidationError`	input failed `inputSchema`
`OutputValidationError`	output failed `outputSchema` after retry budget
`SubagentLimitError`	depth/fan-out/allowed limit hit
`QuotaExceededError`	a run budget (turns / duration / cost) was exhausted
`CancelledError`	caller aborted
`PausedForConfirmationError`	confirm-gate triggered (reserved for runtime)
`ModelError`	routing miss / circuit open / provider error / auth
`SandboxError`	sandbox refused or failed an exec/read/write
`StorageError`	storage adapter failure
`PluginError`	plugin hook threw

Edit this page