@contractspec/lib.ai-agent 7.0.7 → 8.0.0

package/README.md

@@ -9,6 +9,7 @@ Website: https://contractspec.io
 - 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
@@ -21,13 +22,42 @@ or
 
 ## Usage
 
-Import the root entrypoint from `@contractspec/lib.ai-agent`, or choose a documented subpath when you only need one part of the package surface.
+Define agents in `@contractspec/lib.contracts-spec/agent`, then run or export them with `@contractspec/lib.ai-agent`.
+
+```ts
+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/`, `src.schema/`, and `src.spec/` round out agent policy and observability 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.
 
@@ -44,7 +74,17 @@ Import the root entrypoint from `@contractspec/lib.ai-agent`, or choose a docume
 - 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`.
-- The package publishes 66 total export subpaths; keep docs aligned with `package.json`.
+- 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
 
@@ -74,5 +114,6 @@ Import the root entrypoint from `@contractspec/lib.ai-agent`, or choose a docume
 ## Notes
 
 - High blast radius — used by multiple bundles and libs.
-- `AgentSpec` interface is a public contract; do not change its shape without a migration plan.
+- 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).

package/dist/agent/agent-factory.d.ts

@@ -1,16 +1,17 @@
 import type { ModelSelector } from '@contractspec/lib.ai-providers/selector-types';
+import type { AgentRegistry, AgentSpec } from '@contractspec/lib.contracts-spec/agent';
 import type { OperationSpecRegistry } from '@contractspec/lib.contracts-spec/operations/registry';
 import type { KnowledgeRetriever } from '@contractspec/lib.knowledge/retriever';
 import type { LanguageModel, Tool } from 'ai';
+import type { ApprovalWorkflow } from '../approval/workflow';
+import type { AgentRuntimeAdapterBundle } from '../interop/runtime-adapters';
 import type { AgentSessionStore } from '../session/store';
-import type { AgentRegistry } from '../spec/registry';
-import type { AgentSpec } from '../spec/spec';
 import type { TelemetryCollector } from '../telemetry/adapter';
 import type { PostHogLLMConfig, PostHogTracingOptions } from '../telemetry/posthog-types';
 import type { AgentMemoryStore } from '../tools/agent-memory-store';
 import type { McpClientConfig } from '../tools/mcp-client';
 import type { SubagentRegistry } from '../tools/tool-adapter';
-import type { ToolHandler } from '../types';
+import type { AgentEventEmitter, AgentSessionState, ToolHandler } from '../types';
 import { ContractSpecAgent } from './contract-spec-agent';
 /**
  * Factory configuration for creating agents.
@@ -44,6 +45,12 @@ export interface AgentFactoryConfig {
     mcpServers?: McpClientConfig[];
     /** Ranking-driven model selector for dynamic per-call routing */
     modelSelector?: ModelSelector;
+    /** Optional external adapter bundles keyed by runtime id. */
+    runtimeAdapters?: Partial<Record<string, AgentRuntimeAdapterBundle<AgentSessionState>>>;
+    /** Approval workflow used for escalation and tool approvals. */
+    approvalWorkflow?: ApprovalWorkflow;
+    /** Event emitter for lifecycle/audit events. */
+    eventEmitter?: AgentEventEmitter;
 }
 /**
  * Options for creating an agent instance.
@@ -61,6 +68,10 @@ export interface CreateAgentOptions {
     operationRegistry?: OperationSpecRegistry;
     /** Override SubagentRegistry for subagent-backed tools */
     subagentRegistry?: SubagentRegistry;
+    /** Override runtime adapters for this instance. */
+    runtimeAdapters?: Partial<Record<string, AgentRuntimeAdapterBundle<AgentSessionState>>>;
+    /** Override approval workflow for this instance. */
+    approvalWorkflow?: ApprovalWorkflow;
 }
 /**
  * Factory for creating ContractSpec agents from specs.