types

Shared TypeScript type definitions for the Regent SDK. This package has no dependencies on other @regent/* packages.

Installation

bun add @regent/types

Overview

Types are organized by category and can be imported via subpaths:

// Import from specific category
import type { AgentMeta, EntrypointDef } from '@regent/types/core';
import type { AgentCard, A2AClient } from '@regent/types/a2a';
import type { PaymentsConfig } from '@regent/types/payments';

// Or from root
import type { AgentMeta } from '@regent/types';

Type Categories

Core Types (@regent/types/core)

Agent runtime and extension system types.

AgentMeta

type AgentMeta = {
  name: string;
  version: string;
  description?: string;
  icon?: string;
  image?: string;      // OG image (1200x630px)
  url?: string;        // Canonical URL
  type?: 'website' | 'article';
};

AgentConfig

type AgentConfig = {
  meta: AgentMeta;
};

AgentContext

type AgentContext = {
  key: string;
  input: unknown;
  signal: AbortSignal;
  metadata?: Record<string, unknown>;
  runId?: string;
  runtime?: AgentRuntime;
};

EntrypointDef

type EntrypointDef<TInput, TOutput> = {
  key: string;
  description?: string;
  input?: TInput;              // Zod schema
  output?: TOutput;            // Zod schema
  streaming?: boolean;
  price?: EntrypointPrice;
  network?: Network;
  handler?: EntrypointHandler<TInput, TOutput>;
  stream?: EntrypointStreamHandler<TInput>;
  metadata?: Record<string, unknown>;
};

EntrypointHandler

type EntrypointHandler<TInput, TOutput> = (
  ctx: AgentContext & { input: TInput }
) => Promise<{
  output: TOutput;
  usage?: Usage;
  model?: string;
}>;

EntrypointStreamHandler

type EntrypointStreamHandler<TInput> = (
  ctx: AgentContext & { input: TInput },
  emit: (chunk: StreamPushEnvelope) => Promise<void> | void
) => Promise<StreamResult>;

Extension

interface Extension<R extends Record<string, unknown> = {}> {
  name: string;
  build(ctx: BuildContext): R;
  onEntrypointAdded?(entrypoint: EntrypointDef, runtime: AgentRuntime): void;
  onBuild?(runtime: AgentRuntime): void | Promise<void>;
  onManifestBuild?(card: AgentCardWithEntrypoints, runtime: AgentRuntime): AgentCardWithEntrypoints;
}

AgentRuntime

type AgentRuntime = {
  agent: AgentCore;
  wallets?: WalletsRuntime;
  payments?: PaymentsRuntime;
  analytics?: AnalyticsRuntime;
  a2a?: A2ARuntime;
  ap2?: AP2Runtime;
  scheduler?: SchedulerRuntime;
  handlers?: AgentHttpHandlers;
  entrypoints: EntrypointsRuntime;
  manifest: ManifestRuntime;
};

Usage

type Usage = {
  prompt_tokens?: number;
  completion_tokens?: number;
  total_tokens?: number;
};

HTTP Types (@regent/types/http)

HTTP protocol and streaming types.

Stream Envelope Types

type StreamRunStartEnvelope = {
  kind: 'run-start';
  runId: string;
  sequence?: number;
  createdAt?: string;
};

type StreamDeltaEnvelope = {
  kind: 'delta';
  delta: string;
  mime?: string;
  final?: boolean;
  role?: string;
  runId?: string;
  sequence?: number;
};

type StreamTextEnvelope = {
  kind: 'text';
  text: string;
  mime?: string;
  role?: string;
  runId?: string;
  sequence?: number;
};

type StreamAssetEnvelope = {
  kind: 'asset';
  assetId: string;
  mime: string;
  name?: string;
  sizeBytes?: number;
  runId?: string;
} & (
  | { transfer: 'inline'; data: string }
  | { transfer: 'external'; href: string; expiresAt?: string }
);

type StreamControlEnvelope = {
  kind: 'control';
  control: string;
  payload?: unknown;
  runId?: string;
};

type StreamErrorEnvelope = {
  kind: 'error';
  code: string;
  message: string;
  retryable?: boolean;
  runId?: string;
};

type StreamRunEndEnvelope = {
  kind: 'run-end';
  runId: string;
  status: 'succeeded' | 'failed' | 'cancelled';
  output?: unknown;
  usage?: Usage;
  model?: string;
  error?: { code: string; message?: string };
};

StreamEnvelope (Union)

type StreamEnvelope =
  | StreamRunStartEnvelope
  | StreamTextEnvelope
  | StreamDeltaEnvelope
  | StreamAssetEnvelope
  | StreamControlEnvelope
  | StreamErrorEnvelope
  | StreamRunEndEnvelope;

StreamPushEnvelope

Envelopes that can be pushed via emit():

type StreamPushEnvelope =
  | StreamTextEnvelope
  | StreamDeltaEnvelope
  | StreamAssetEnvelope
  | StreamControlEnvelope
  | StreamErrorEnvelope;

AgentHttpHandlers

type AgentHttpHandlers = {
  health(req: Request): Promise<Response>;
  entrypoints(req: Request): Promise<Response>;
  manifest(req: Request): Promise<Response>;
  landing?(req: Request): Promise<Response>;
  favicon(req: Request): Promise<Response>;
  invoke(req: Request, params: { key: string }): Promise<Response>;
  stream(req: Request, params: { key: string }): Promise<Response>;
  tasks(req: Request): Promise<Response>;
  getTask(req: Request, params: { taskId: string }): Promise<Response>;
  listTasks(req: Request): Promise<Response>;
  cancelTask(req: Request, params: { taskId: string }): Promise<Response>;
  subscribeTask(req: Request, params: { taskId: string }): Promise<Response>;
};

A2A Types (@regent/types/a2a)

Agent-to-Agent protocol types.

AgentCard

type AgentCard = {
  protocolVersion?: string;
  name: string;
  description?: string;
  version?: string;
  url?: string;
  iconUrl?: string;
  supportedInterfaces?: AgentInterface[];
  capabilities?: AgentCapabilities;
  skills?: Skill[];
  payments?: PaymentMethod[];
  registrations?: RegistrationEntry[];
  trustModels?: TrustModel[];
  // ... additional fields
};

AgentCapabilities

type AgentCapabilities = {
  streaming?: boolean;
  pushNotifications?: boolean;
  stateTransitionHistory?: boolean;
  extensions?: Array<AP2ExtensionDescriptor | Record<string, unknown>>;
};

Skill

type Skill = {
  id: string;
  name?: string;
  description?: string;
  tags?: string[];
  examples?: string[];
  inputModes?: string[];
  outputModes?: string[];
};

Task Types

type TaskStatus = 'running' | 'completed' | 'failed' | 'cancelled';

type Task<TOutput = unknown> = {
  taskId: string;
  status: TaskStatus;
  contextId?: string;
  result?: { output: TOutput; usage?: Usage };
  error?: { code: string; message: string };
  createdAt: string;
  updatedAt: string;
};

A2AClient

interface A2AClient {
  invoke(card: AgentCard, skillId: string, input: unknown): Promise<InvokeAgentResult>;
  stream(card: AgentCard, skillId: string, input: unknown, emit: StreamEmit): Promise<void>;
  sendMessage(card: AgentCard, skillId: string, input: unknown, options?: { contextId?: string }): Promise<SendMessageResponse>;
  getTask(card: AgentCard, taskId: string): Promise<Task>;
  subscribeTask(card: AgentCard, taskId: string, emit: (chunk: TaskUpdateEvent) => void): Promise<void>;
  listTasks(card: AgentCard, filters?: ListTasksRequest): Promise<ListTasksResponse>;
  cancelTask(card: AgentCard, taskId: string): Promise<Task>;
}

Payments Types (@regent/types/payments)

Payment configuration and limits.

PaymentsConfig

type PaymentsConfig = {
  payTo: `0x${string}` | SolanaAddress;
  facilitatorUrl: string;
  network: Network;
  policyGroups?: PaymentPolicyGroup[];
  storage?: PaymentStorageConfig;
};

PaymentPolicyGroup

type PaymentPolicyGroup = {
  name: string;
  outgoingLimits?: OutgoingLimitsConfig;
  incomingLimits?: IncomingLimitsConfig;
  allowedRecipients?: string[];
  blockedRecipients?: string[];
  allowedSenders?: string[];
  blockedSenders?: string[];
  rateLimits?: { maxPayments: number; windowMs: number };
};

EntrypointPrice

type EntrypointPrice = string | {
  invoke?: string;
  stream?: string;
};

Wallets Types (@regent/types/wallets)

Wallet configuration and signing.

WalletConnector

interface WalletConnector {
  signChallenge(challenge: AgentChallenge): Promise<string>;
  getWalletMetadata(): Promise<WalletMetadata | null>;
  getAddress?(): Promise<string | null>;
  getCapabilities?(): WalletCapabilities;
  getSigner?(): Promise<LocalEoaSigner | null>;
  getWalletClient?<T>(): Promise<T | null>;
}

WalletMetadata

type WalletMetadata = {
  id?: string | null;
  address?: string | null;
  chain?: string | null;
  chainType?: string | null;
  provider?: string | null;
  accountId?: string | null;
  label?: string | null;
  caip2?: string | null;
};

WalletsConfig

type WalletsConfig = {
  agent?: AgentWalletConfig;
  developer?: DeveloperWalletConfig;
};

type AgentWalletConfig =
  | LocalWalletOptions
  | SignerWalletOptions
  | LucidWalletOptions
  | ThirdwebWalletOptions;

AP2 Types (@regent/types/ap2)

Agent Payments Protocol types.

AP2Role

type AP2Role = 'merchant' | 'shopper' | 'credentials-provider' | 'payment-processor';

AP2Config

type AP2Config = {
  roles: AP2Role[];
  description?: string;
  required?: boolean;
};

Identity Types (@regent/types/identity)

ERC-8004 identity types.

TrustModel

type TrustModel = 'feedback' | 'inference-validation' | 'tee-attestation' | string;

RegistrationEntry

type RegistrationEntry = {
  agentId: number | string;
  agentAddress: string;
  signature?: string;
  [key: string]: unknown;
};

Scheduler Types (@regent/types/scheduler)

Task scheduling types.

Schedule

type Schedule =
  | { kind: 'interval'; everyMs: number }
  | { kind: 'once'; at: number };

Hire

type Hire = {
  id: string;
  agent: AgentRef;
  wallet?: WalletRef;
  status: 'active' | 'paused' | 'canceled';
  metadata?: Record<string, JsonValue>;
};

Job

type Job = {
  id: string;
  hireId: string;
  entrypointKey: string;
  input: JsonValue;
  schedule: Schedule;
  nextRunAt: number;
  attempts: number;
  maxRetries: number;
  status: JobStatus;
  idempotencyKey?: string;
  lease?: { workerId: string; expiresAt: number };
  lastError?: string;
};

type JobStatus = 'pending' | 'leased' | 'failed' | 'completed' | 'paused';

Analytics Types (@regent/types/analytics)

Payment analytics types.

AnalyticsSummary

type AnalyticsSummary = {
  outgoingTotal: bigint;
  incomingTotal: bigint;
  netTotal: bigint;
  outgoingCount: number;
  incomingCount: number;
  windowStart?: number;
  windowEnd?: number;
};

Subpath Exports

{
  ".": "./dist/index.d.ts",
  "./core": "./dist/core/index.d.ts",
  "./a2a": "./dist/a2a/index.d.ts",
  "./ap2": "./dist/ap2/index.d.ts",
  "./http": "./dist/http/index.d.ts",
  "./identity": "./dist/identity/index.d.ts",
  "./analytics": "./dist/analytics/index.d.ts",
  "./payments": "./dist/payments/index.d.ts",
  "./scheduler": "./dist/scheduler/index.d.ts",
  "./wallets": "./dist/wallets/index.d.ts"
}