@wavespec/types

Pure TypeScript type definitions for Agent Harness adapters.

ZERO runtime dependencies - types + minimal runtime type guards!

Overview

This package provides the core type definitions needed to build Agent Harness adapters. It enables external adapter development without importing the full harness package.

Documentation

• 📖 API Reference - Complete reference for all exported types
• 🚀 Development Guide - Step-by-step tutorial for building adapters
• 🔧 Utility Patterns - Copy-paste patterns for common tasks
• 💡 Example Adapter - Working calculator adapter template

Quick Start

npm install @wavespec/types

See the Development Guide for a complete tutorial, or check out the Example Adapter for a working template.

Key Features

• ✅ Zero Dependencies: No runtime dependencies, only TypeScript types + minimal runtime code
• ✅ Complete Type Coverage: All adapter contract types in one package
• ✅ Framework Agnostic: Works with any TypeScript project
• ✅ Protocol Independent: Supports MCP, HTTP, OpenAI, and custom protocols
• ✅ Runtime Type Guards: Includes isProcessConfig() and isHttpConfig() for type discrimination
• ✅ Critical Runtime Code: Includes CoachingError, ERROR_CODES, and AdapterSchema for consistent error handling

Installation

npm install --save-dev @wavespec/types

Usage

Basic Adapter Implementation

import type {
  Adapter,
  TestContext,
  TestResult,
  TestSpec,
  ContentItem,
  AdapterConfig,
} from '@wavespec/types';

export class MyAdapter implements Adapter {
  name = 'my-adapter';
  version = '1.0.0';

  async run(spec: TestSpec, ctx: TestContext): Promise<TestResult> {
    // Your adapter implementation
    const content: ContentItem[] = [
      { type: 'text', text: 'Hello from my adapter!' }
    ];

    return {
      response: {
        content,
        output_text: 'Hello from my adapter!',
        isError: false,
      },
      durationMs: 100,
    };
  }
}

Error Handling

import { CoachingError, ERROR_CODES } from '@wavespec/types';

// Throw structured errors with actionable guidance
throw new CoachingError({
  code: ERROR_CODES.TOOL_NOT_FOUND,
  message: 'Tool not found: calculate',
  hint: 'The requested tool does not exist in the server',
  fix: 'Check available tools using the discovery operation',
  severity: 'error',
  context: { requestedTool: 'calculate', availableTools: ['add', 'subtract'] }
});

Adapter Schema

import type { AdapterSchema } from '@wavespec/types';

// Define your adapter's operations and response structure
export class MyAdapter implements Adapter {
  static getSchema(): AdapterSchema {
    return {
      operations: [
        {
          name: 'call',
          description: 'Make an API call',
          parameters: [
            {
              name: 'input',
              type: 'string',
              required: true,
              description: 'The input text to send'
            }
          ]
        }
      ],
      responseStructure: {
        description: 'The response contains the API output',
        fields: [
          { name: 'output', type: 'string', description: 'The API response text' }
        ]
      },
      examples: [
        {
          operation: 'call',
          description: 'Simple API call',
          yaml: 'operation: call\nparams:\n  input: "Hello"'
        }
      ]
    };
  }
}

Type Guards

import { isProcessConfig, isHttpConfig } from '@wavespec/types';
import type { AdapterConfig } from '@wavespec/types';

function handleConfig(config: AdapterConfig) {
  if (isProcessConfig(config)) {
    // TypeScript knows config is ProcessConfig
    console.log(`Command: ${config.command}`);
    console.log(`Args: ${config.args?.join(' ')}`);
  } else if (isHttpConfig(config)) {
    // TypeScript knows config is HttpConfig
    console.log(`Base URL: ${config.baseUrl}`);
    console.log(`Headers: ${JSON.stringify(config.headers)}`);
  }
}

Exported Types

Core Types

• Adapter - Main adapter interface
• AdapterCapabilities - Capability flags (discovery, validation, etc.)
• AdapterMetadata - Handshake metadata
• TestContext - Execution context
• TestResult - Test execution result
• ValidationResult - Pre-validation result
• StreamChunk - Streaming response chunk

Runtime Exports

• CoachingError - Structured error class with actionable guidance (CLASS, not just type)
• ERROR_CODES - Standard error code constants (50+ error codes)
• ERROR_CODE_CATALOG - Error code metadata with descriptions
• ErrorCode - Error code type
• ErrorSeverity - Error severity type ('error' | 'warn' | 'info')
• AdapterSchema - Schema interface for describing adapter operations
• OperationSchema - Operation schema with parameters

Content Model

• ContentItem - Universal content representation (text, image, resource)

Test Specifications

• TestSpec - Test specification format
• Assertion - Assertion types (success, error, contains_text, etc.)
• SuiteSpec - Suite specification format
• SuiteConfig - Suite configuration

Adapter Configuration

• AdapterConfig - Adapter configuration union type
• ProcessConfig - Process-based adapter config (MCP)
• HttpConfig - HTTP adapter config
• AuthConfig - Authentication configuration

Adapter Metadata

• AdapterInfo - Adapter discovery metadata
• Operation - Operation definition
• SDKInfo - SDK information

Utilities

• CoachingErrorData - Error structure with helpful hints
• DiscoveryCache - Discovery cache interface
• ServerInstance - Server information

Utilities vs. Contracts

What's in the Contract (this package)

This package provides pure type definitions that define the adapter API contract:

• ✅ DiscoveryCache: Clear API for lazy-loaded caching (in TestContext)

  • Purpose: Enables discovery-capable adapters to cache tools/prompts/resources
  • Score: 8.6/10 on high-value criteria
  • When to use: Your adapter has a discovery phase (e.g., MCP)
  • When NOT to use: Your adapter doesn't have discovery (e.g., HTTP)

• ✅ Adapter lifecycle: connect, run, disconnect, reset, etc.

• ✅ Type definitions: ContentItem, TestContext, TestResult, CoachingErrorData, etc.

What's NOT in the Contract (Optional Utilities)

The main agent-harness package provides optional implementation utilities that are convenient but not required:

• ResponseNormalizer: Schema-driven response transformation

  • Adapters can use this utility OR implement custom normalization
  • OpenAI adapter implements custom normalization (435 lines)
  • MCP/HTTP adapters use the utility for convenience

• ErrorTranslator: Pattern-based error translation

  • Adapters can use this utility OR implement custom error handling
  • Each adapter translates errors differently based on protocol

• FuzzyMatcher: String similarity for "did you mean?" suggestions

  • Adapters can use this utility OR implement custom fuzzy matching
  • Only discovery-capable adapters typically need this

Design Philosophy

We only include interfaces in this package that:

1. Score ≥8.0 on high-value criteria (Universal Applicability, Contract Clarity, Type Safety, Independence, Multi-Language)
2. Define clear, stable API contracts (not implementation details)
3. Enable adapter independence (don't create coupling)
4. Translate to multiple languages (Python, Go, Rust, etc.)

Everything else remains flexible implementation detail left to adapter developers. This approach:

• Maximizes adapter independence
• Avoids prescriptive patterns
• Works across programming languages
• Keeps the contract minimal and stable

Package Philosophy

This package follows strict principles:

1. Minimal Runtime Code: TypeScript interfaces and types, plus critical runtime code (CoachingError, ERROR_CODES, AdapterSchema)
2. Zero Dependencies: Self-contained with no external dependencies
3. Stable API: Types and runtime exports are the contract - changes are breaking
4. Well Documented: Every type and class includes JSDoc comments
5. Tested: Comprehensive test suite (49 tests) covering type guards, exports, and build outputs
6. Small Package Size: Under 150KB total (includes 50+ error codes with metadata)

Development

# Build types
npm run build

# Type check
npm run type-check

# Run tests
npm test

# Watch mode for tests
npm run test:watch

Roadmap

Adapter SDK extraction progress:

• ✅ Phase 1: Extract types to @wavespec/types (pure type definitions)
• ✅ Phase 2.1: Add critical runtime exports (CoachingError, ERROR_CODES, AdapterSchema)
• ✅ Phase 2.2: Migrate adapters to import from @wavespec/types (75% interface purity)
• ✅ Phase 3: Documentation & External Adapter Guide (API Reference, Development Guide, Utility Patterns, Example)
• ❌ Phase 2 (SKIPPED): No shared utilities package - accept code duplication for adapter independence
• 🔄 Phase 2.3 (Optional): Clean up internal harness to use adapter-types package (defer until npm publish)
• 🔄 Phase 4 (Future): IPC protocol for multi-language adapters

See INTERFACE-LAYER-ROADMAP.md for detailed implementation plan.

License

MIT

Contributing

See the main agent-harness repository.