@ank1015/agents-contracts

@ank1015/agents-contracts

Shared runtime schemas and TypeScript contracts for the @ank1015/agents packages.

This package is the lowest-level public boundary for agent messages, LLM requests, model metadata, provider registration types, tool definitions, usage accounting, and streaming events. It intentionally does not depend on any provider SDK or runtime adapter.

Install

pnpm add @ank1015/agents-contracts

What This Package Provides

• Zod schemas for provider-neutral structural validation.
• TypeScript types inferred from those schemas.
• Provider augmentation maps for provider-specific native messages, config, options, and model IDs.
• Optional prompt-token pricing tiers and shared model-cost resolution.
• Shared LLM transport and adapter interfaces.
• Shared assistant event-stream types and createEventStream.

Import Paths

import {
  llmRequestSchema,
  messageSchema,
  createEventStream,
} from '@ank1015/agents-contracts';

import { contentSchema } from '@ank1015/agents-contracts/content';
import type { AssistantEvent } from '@ank1015/agents-contracts/llm';
import type { Message } from '@ank1015/agents-contracts/messages';
import type { Model } from '@ank1015/agents-contracts/models';
import type { ModelSelection } from '@ank1015/agents-contracts/providers';

Contract Areas

Content

Content parts are provider-neutral user/tool payloads:

• text
• image

Images use base64 data plus a MIME type. Provider adapters are responsible for enforcing provider-specific MIME support.

Messages

The shared message union includes:

• user
• assistant
• toolResult
• custom

Assistant messages carry normalized assistant content plus optional provider-native data.

Models And Providers

Model and provider contracts are open by design. Provider packages can augment:

• ProviderNativeMessageMap
• ProviderOptionsMap
• ProviderModelIdMap
• ProviderConfigMap

That lets provider packages narrow generic contracts without making this package depend on provider implementations.

Models always provide a base cost and may provide ordered pricingTiers keyed by prompt-token intervals. resolveModelCost returns the first matching tier, falling back to the base cost so existing flat-priced models remain compatible.

LLM Requests And Streams

LLMRequest describes a provider-neutral request shape. LLMTransport and LLMProviderAdapter describe the streaming transport boundary.

createEventStream creates a queue-backed EventStreamSource that buffers pushed events until consumed and resolves a final result when ended.

Runtime Validation Scope

The schemas in this package validate provider-neutral structure. They do not validate provider-specific semantics such as:

• whether a model ID exists for a provider,
• whether providerOptions matches a provider SDK,
• whether an image MIME type is supported by a provider,
• whether a native provider message matches that provider's SDK shape.

Provider packages should add provider-specific validation at their adapter boundaries.

Versioning

This package is currently 0.1.11. Until 1.0.0, public contracts may still evolve as the runtime packages settle.