@reaatech/agent-handoff

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Core types, utilities, and configuration for the Agent Handoff Protocol. This package is the foundation that all other @reaatech/agent-handoff-* packages build on.

Installation

terminal

npm install @reaatech/agent-handoff
# or
pnpm add @reaatech/agent-handoff

Feature Overview

35+ exported types — every handoff domain concept has a corresponding type: payloads, agents, routing decisions, triggers, messages, and more
7 typed error classes — HandoffError hierarchy with TransportError, ValidationError, TimeoutError, RejectionError, RoutingError, CompressionError, ConfigurationError
Typed event emitter — TypedEventEmitter<EventMap> with type-safe on/off/once/emit for lifecycle observability
Retry utility — withRetry with configurable exponential/linear backoff and full jitter
Config factory — createHandoffConfig with deeply merged sensible defaults
Zero runtime dependencies — everything is built-in or injected by the consumer
Dual ESM/CJS output — works with import and require

Quick Start

typescript

import {
  createHandoffConfig,
  defaultHandoffConfig,
  HandoffError,
  TypedEventEmitter,
  withRetry,
  pickDefined,
} from '@reaatech/agent-handoff';
import type {
  HandoffPayload,
  AgentCapabilities,
  RoutingDecision,
  HandoffConfig,
  Message,
} from '@reaatech/agent-handoff';
 
// Create a configuration with defaults
const config = createHandoffConfig({
  routing: { minConfidenceThreshold: 0.6 },
});
 
// Use the typed event emitter
const emitter = new TypedEventEmitter<{ update: { id: string } }>();
emitter.on('update', ({ id }) => console.log(id));
 
// Retry with backoff
const result = await withRetry(() => fetchSomething(), {
  maxRetries: 3,
  backoff: 'exponential',
  baseDelayMs: 100,
  maxDelayMs: 5000,
  shouldRetry: (err) => err instanceof Error,
});

Exports

Types

Export	Description
`HandoffPayload`	Complete handoff data: session history, compressed context, metadata
`CompressedContext`	Compression output: summary, key facts, intents, entities, open items
`AgentCapabilities`	Agent descriptor: skills, domains, load, languages, availability
`RoutingDecision`	Discriminated union: `PrimaryRoute` \| `ClarificationRoute` \| `FallbackRoute`
`HandoffConfig`	Compression, routing, transport, and trigger configuration
`HandoffTrigger`	Discriminated union of 5 trigger types
`HandoffContext`	Input context for `HandoffManager.executeHandoff()`
`HandoffOptions`	Optional overrides: source agent, timeout, transport preference
`HandoffResult`	Result type: success/failure, receiving agent, routing decision
`Message`	Conversation message: id, role, content, timestamp
`TransportLayer`	Interface: `sendHandoff`, `validateConnection`, `getCapabilities`
`ContextCompressor`	Interface: `compress` + `estimateTokens`
`HandoffRouter`	Interface: `route` returning a `RoutingDecision`
`DeepPartial`	Recursive partial utility type

Errors

All errors extend HandoffError which includes code: HandoffErrorCode, message: string, and optional details.

Class	Code	When
`HandoffError`	(custom)	Base class for all handoff errors
`TransportError`	`transport_error`	Transport layer failure
`ValidationError`	`validation_error`	Payload incompatible with target agent; includes `validationErrors[]`
`TimeoutError`	`timeout_error`	Handoff exceeded timeout; includes `timeoutMs`
`RejectionError`	`rejection_error`	Target agent rejected; includes `rejectionReason`
`RoutingError`	`routing_error`	No suitable agent found
`CompressionError`	`compression_error`	Context compression failed
`ConfigurationError`	`configuration_error`	Invalid configuration

Utilities

Export	Description
`TypedEventEmitter<EventMap>`	Type-safe event emitter with `on`, `off`, `once`, `emit`
`withRetry`	Async retry with exponential/linear backoff + full jitter
`pickDefined`	Build object from key-value pairs, omitting `undefined` values
`createHandoffConfig`	Deep-merge partial config with `defaultHandoffConfig`
`defaultHandoffConfig`	Sensible defaults for compression, routing, transport, triggers

@reaatech/agent-handoff-compression — Context compression strategies
@reaatech/agent-handoff-routing — Agent routing engine
@reaatech/agent-handoff-transport — MCP and A2A transports
@reaatech/agent-handoff-validation — Payload validation
@reaatech/agent-handoff-protocol — Full orchestration layer

License

MIT

@reaatech/agent-handoff

@reaatech/agent-handoff

Installation

Feature Overview

Quick Start

Exports

Types

Errors

Utilities

Related Packages

License