Lucid Agents Docs

@lucid-agents/types is the single source of truth for concepts shared between packages. Runtime packages import these contracts directly instead of defining parallel internal/public shapes. The package is ESM, side-effect free, portable, and has no dependency on another @lucid-agents package.

Installation

bun add @lucid-agents/types

Most applications receive the package transitively. Install it directly when authoring extensions, adapters, stores, or other integrations against its contracts.

Domain subpaths

Prefer the narrow domain path that owns the type:

Export path	Owns
`@lucid-agents/types/core`	Agent metadata, runtime, manifest, entrypoint, extension, adapter, and network contracts.
`@lucid-agents/types/http`	Fetch handlers, route plan, SSE envelopes, and idempotency-store ports.
`@lucid-agents/types/a2a`	Agent Cards, Lucid HTTP-profile clients, owned tasks, leases, and task stores.
`@lucid-agents/types/payments`	x402 configuration, runtime, policies, authorization, tracking, and storage contracts.
`@lucid-agents/types/mpp`	MPP server/client methods, verifier, authorization, and runtime contracts.
`@lucid-agents/types/siwx`	SIWX configuration, credentials, authentication context, and nonce storage.
`@lucid-agents/types/identity`	ERC-8004 registration, trust, OASF, clients, and runtime contracts.
`@lucid-agents/types/wallets`	Wallet configuration, connectors, metadata, and runtime contracts.
`@lucid-agents/types/ap2`	AP2 roles, descriptors, configuration, and runtime contracts.
`@lucid-agents/types/scheduler`	Hires, jobs, schedules, leases, stores, and scheduler runtime.
`@lucid-agents/types/analytics`	Payment analytics, transaction, and runtime contracts.

The root entrypoint remains available, but domain subpaths make ownership and dependency direction explicit.

Core runtime

import type {
  AgentConfig,
  AgentContext,
  AgentManifest,
  AgentMeta,
  AgentRuntime,
  AgentRuntimeBase,
  BuildContext,
  EntrypointDef,
  EntrypointHandler,
  EntrypointStreamHandler,
  Extension,
  ManifestRuntime,
  PaymentProtocol,
} from '@lucid-agents/types/core';

AgentRuntime

Core owns only the protocol-neutral runtime base. Installed extensions contribute exact capability slices through the generic:

type AgentRuntimeBase<Capabilities extends object = {}> = {
  agent: AgentCore;
  entrypoints: EntrypointsRuntime<Capabilities>;
  manifest: ManifestRuntime;
  close(): Promise<void>;
};

type AgentRuntime<Capabilities extends object = {}> =
  AgentRuntimeBase<Capabilities> & Capabilities;

This keeps core independent of HTTP, payments, A2A, and other domain packages while preserving typed access after composition.

EntrypointDef

type EntrypointDef<
  TInput extends z.ZodTypeAny | undefined = z.ZodTypeAny | undefined,
  TOutput extends z.ZodTypeAny | undefined = z.ZodTypeAny | undefined,
  TRuntime extends object = AgentRuntime,
> = {
  key: string;
  description?: string;
  input?: TInput;
  output?: TOutput;
  price?: string | { invoke?: string; stream?: string };
  paymentProtocol?: 'x402' | 'mpp';
  network?: Network;
  handler?: EntrypointHandler<TInput, TOutput, TRuntime>;
  stream?: EntrypointStreamHandler<TInput, TRuntime>;
  metadata?: Record<string, unknown>;
  siwx?: SIWxEntrypointConfig;
};

Streaming is inferred from the presence of stream; there is no separate streaming flag on the definition. paymentProtocol is required for priced entrypoints when x402 and MPP are both installed.

AgentContext

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

Transports attach their details through metadata rather than changing the domain handler contract. HTTP places request headers at metadata.headers.

Extension

interface Extension<
  RuntimeSlice extends Record<string, unknown> = {},
  Dependencies extends object = {},
> {
  readonly __dependencies?: Dependencies;
  name: string;
  requires?: readonly string[];
  after?: readonly string[];
  before?: readonly string[];
  build(
    context: BuildContext<Dependencies>
  ): RuntimeSlice | Promise<RuntimeSlice>;
  initialize?(runtime: AgentRuntime): void | Promise<void>;
  onEntrypointAdded?(entrypoint: EntrypointDef, runtime: AgentRuntime): void;
  onManifestBuild?(
    manifest: AgentManifest,
    runtime: AgentRuntime
  ): AgentManifest;
  dispose?(runtime: AgentRuntime): void | Promise<void>;
}

The kernel validates missing dependencies and cycles, applies ordering constraints, initializes in dependency order, and disposes in reverse order.

HTTP contracts

import type {
  AgentHttpHandlers,
  AgentHttpRoute,
  AgentHttpRuntime,
  HttpExtensionOptions,
  HttpIdempotencyStore,
  StreamEnvelope,
  StreamPushEnvelope,
  StreamResult,
} from '@lucid-agents/types/http';

Stream envelopes

The runtime owns run-start and run-end. Entrypoint code emits StreamPushEnvelope values:

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

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

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

Every envelope may carry sequence, timestamp, run, and metadata fields. AgentHttpRoute is the canonical transport-neutral method/path/handler record used by adapters.

Idempotency store

HttpIdempotencyStore is an atomic claim/complete/release port. A claim can be new, in progress, conflicting, or completed with a stored response. Multi-instance HTTP runtimes should implement this contract over durable shared storage.

A2A contracts

import type {
  A2AClient,
  A2ARuntime,
  AgentCard,
  AgentCardWithEntrypoints,
  StoredTask,
  Task,
  TaskAccess,
  TaskStatus,
  TaskStore,
} from '@lucid-agents/types/a2a';

TaskAccess is the opaque owner capability returned by task creation:

type TaskAccess = {
  taskId: string;
  accessToken: string;
};

StoredTask persists only an owner hash plus an optional fenced execution lease. TaskStore requires atomic execution claims and compare-and-set transitions so multiple workers cannot publish competing terminal results.

Payment contracts

import type {
  IncomingPaymentAuthorization,
  PaymentRequirement,
  PaymentTracker,
  PaymentsConfig,
  PaymentsRuntime,
} from '@lucid-agents/types/payments';

import type { PaymentStorage } from '@lucid-agents/payments';

import type {
  MppConfig,
  MppCredentialVerifier,
  MppRuntime,
} from '@lucid-agents/types/mpp';

import type {
  AgentAuthContext,
  SIWxConfig,
  SIWxStorage,
} from '@lucid-agents/types/siwx';

The payment contracts separate verification from admission/finalization, expose atomic reservations and batched commits, and keep storage behind interfaces. Portable runtimes use portable implementations; Node-only SQLite, Postgres, and Stripe factories live in explicit package subpaths.

Authoring an integration

Import the contract from the owning domain and implement it without importing another package's internals:

import type { HttpIdempotencyStore } from '@lucid-agents/types/http';

export function createDurableIdempotencyStore(): HttpIdempotencyStore {
  return {
    async claim(scope, key, fingerprint, ownerId, expiresAt, now) {
      // Perform one atomic conditional write/read transaction.
      return { state: 'claimed' };
    },
    async complete(scope, key, ownerId, response, expiresAt) {
      return true;
    },
    async release(scope, key, ownerId) {},
  };
}

The same rule applies to TaskStore, payment storage, wallet connectors, scheduler stores, and SIWX nonce storage: the shared type is the boundary; the owning runtime supplies behavior.

@lucid-agents/types

On this page