@contractspec/lib.ai-agent

Website: https://contractspec.io

Core AI agent runtime for ContractSpec with tool orchestration, MCP integration, session state, memory, and telemetry.

What It Provides

• Provides the central agent runtime used by chat, automation, and higher-level orchestration packages.
• Supports tools, sessions, memory, approvals, providers, telemetry, and MCP-aware workflows.
• Acts as the stable public API for agent execution across multiple runtimes and delivery surfaces.
• Consumes agent definitions from @contractspec/lib.contracts-spec/agent.
• src/providers/ contains provider integrations and provider-facing adapters.

Installation

npm install @contractspec/lib.ai-agent

or

bun add @contractspec/lib.ai-agent

Usage

Define agents in @contractspec/lib.contracts-spec/agent, then run or export them with @contractspec/lib.ai-agent.

import { defineAgent } from "@contractspec/lib.contracts-spec/agent";
import { createUnifiedAgent } from "@contractspec/lib.ai-agent/agent/unified-agent";

const SupportBot = defineAgent({
  meta: {
    key: "support.bot",
    version: "1.0.0",
    description: "Customer support assistant",
    owners: ["support"],
    tags: ["support"],
    stability: "experimental",
  },
  instructions: "Resolve tickets and escalate low-confidence cases.",
  tools: [{ name: "support.resolve" }],
});

const agent = createUnifiedAgent(SupportBot, {
  backend: "ai-sdk",
});

Runtime portability stays adapter-first:

• AgentSpec.runtime can declare checkpointing, suspend/resume, and approval-gateway capabilities.
• AgentFactory and ContractSpecAgent accept optional runtime adapter bundles for LangGraph/LangChain-style integrations.
• Session state now persists workflow, thread, trace, checkpoint, and approval metadata for replay-safe resumes.
• Escalation policies can raise approval requests on timeout, tool failure, or confidence thresholds without coupling core contracts to a vendor runtime.

Architecture

• src/agent/, src/session/, and src/memory/ contain the runtime core for execution state and persistence hooks.
• src/tools/, src.providers/, and src.interop/ connect providers, tools, and MCP-aware runtime surfaces.
• src.telemetry/, src.approval/, src.knowledge/, and src.schema/ round out runtime policy and observability surfaces.
• src/index.ts is the root public barrel and package entrypoint.
• src/types.ts is shared public type definitions.

Public Entry Points

• Large multi-subpath library exporting agent runtime, approval, memory, knowledge, providers, schema, telemetry, tools, and types.
• Export . resolves through ./src/index.ts.
• Export ./agent resolves through ./src/agent/index.ts.
• Export ./agent/agent-factory resolves through ./src/agent/agent-factory.ts.
• Export ./agent/contract-spec-agent resolves through ./src/agent/contract-spec-agent.ts.
• Export ./agent/json-runner resolves through ./src/agent/json-runner.ts.
• Export ./agent/unified-agent resolves through ./src/agent/unified-agent.ts.
• Export ./approval resolves through ./src/approval/index.ts.
• Export ./approval/workflow resolves through ./src/approval/workflow.ts.
• Export ./exporters resolves through ./src/exporters/index.ts.
• Export ./exporters/claude-agent-exporter resolves through ./src/exporters/claude-agent-exporter.ts.
• Additional runtime subpaths are published through package.json; keep docs aligned with the manifest.

Migration Note

@contractspec/lib.ai-agent no longer owns the agent-definition contract layer.

• Removed: @contractspec/lib.ai-agent/spec
• Removed: @contractspec/lib.ai-agent/spec/spec
• Removed: @contractspec/lib.ai-agent/spec/registry
• Use @contractspec/lib.contracts-spec/agent for AgentSpec, AgentToolConfig, AgentRegistry, createAgentRegistry, and defineAgent

Local Commands

• bun run dev — contractspec-bun-build dev
• bun run build — bun run prebuild && bun run build:bundle && bun run build:types
• bun run test — bun test
• bun run lint — bun lint:fix
• bun run lint:check — biome check .
• bun run lint:fix — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
• bun run typecheck — tsc --noEmit
• bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
• bun run publish:pkg:canary — bun publish:pkg --tag canary
• bun run clean — rimraf dist .turbo
• bun run build:bundle — contractspec-bun-build transpile
• bun run build:types — contractspec-bun-build types
• bun run prebuild — contractspec-bun-build prebuild

Recent Updates

• Missing dependencies (thanks to knip).
• Replace eslint+prettier by biomejs to optimize speed.
• Agentic workflows — subagents, memory tools, and next steps.
• Vnext ai-native.
• Backend operations + frontend rendering support.
• Add latest models and align defaults.

Notes

• High blast radius — used by multiple bundles and libs.
• Agent definitions are owned by @contractspec/lib.contracts-spec/agent.
• This package is runtime-focused: execution, exporters, MCP/tool bridges, sessions, memory, approvals, providers, and telemetry.
• MCP transport adapters must stay runtime-agnostic (no Node/browser-specific globals).