@contractspec/lib.ai-agent 7.0.10 → 8.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/README.md +45 -4
  2. package/dist/agent/agent-factory.d.ts +14 -3
  3. package/dist/agent/agent-factory.js +653 -113
  4. package/dist/agent/contract-spec-agent.d.ts +16 -2
  5. package/dist/agent/contract-spec-agent.js +649 -112
  6. package/dist/agent/index.js +660 -118
  7. package/dist/agent/json-runner.d.ts +1 -1
  8. package/dist/agent/json-runner.js +649 -112
  9. package/dist/agent/unified-agent.d.ts +2 -2
  10. package/dist/agent/unified-agent.js +660 -118
  11. package/dist/approval/index.js +6 -1
  12. package/dist/approval/workflow.js +5 -1
  13. package/dist/exporters/claude-agent-exporter.d.ts +1 -1
  14. package/dist/exporters/claude-agent-exporter.js +3 -51
  15. package/dist/exporters/index.js +8 -54
  16. package/dist/exporters/opencode-exporter.d.ts +1 -1
  17. package/dist/exporters/opencode-exporter.js +3 -51
  18. package/dist/exporters/types.d.ts +1 -1
  19. package/dist/index.d.ts +2 -1
  20. package/dist/index.js +3805 -71
  21. package/dist/interop/index.js +3 -51
  22. package/dist/interop/spec-consumer.d.ts +1 -1
  23. package/dist/interop/spec-consumer.js +3 -51
  24. package/dist/interop/tool-consumer.d.ts +1 -1
  25. package/dist/interop/types.d.ts +1 -1
  26. package/dist/knowledge/injector.d.ts +1 -1
  27. package/dist/node/agent/agent-factory.js +653 -113
  28. package/dist/node/agent/contract-spec-agent.js +649 -112
  29. package/dist/node/agent/index.js +660 -118
  30. package/dist/node/agent/json-runner.js +649 -112
  31. package/dist/node/agent/unified-agent.js +660 -118
  32. package/dist/node/approval/index.js +6 -1
  33. package/dist/node/approval/workflow.js +5 -1
  34. package/dist/node/exporters/claude-agent-exporter.js +3 -51
  35. package/dist/node/exporters/index.js +8 -54
  36. package/dist/node/exporters/opencode-exporter.js +3 -51
  37. package/dist/node/index.js +3805 -71
  38. package/dist/node/interop/index.js +3 -51
  39. package/dist/node/interop/spec-consumer.js +3 -51
  40. package/dist/node/providers/claude-agent-sdk/adapter.js +3 -51
  41. package/dist/node/providers/claude-agent-sdk/index.js +3 -51
  42. package/dist/node/providers/index.js +8 -53
  43. package/dist/node/providers/opencode-sdk/adapter.js +4 -51
  44. package/dist/node/providers/opencode-sdk/index.js +4 -51
  45. package/dist/node/telemetry/adapter.js +2 -0
  46. package/dist/node/telemetry/index.js +2 -0
  47. package/dist/providers/claude-agent-sdk/adapter.d.ts +1 -1
  48. package/dist/providers/claude-agent-sdk/adapter.js +3 -51
  49. package/dist/providers/claude-agent-sdk/index.js +3 -51
  50. package/dist/providers/claude-agent-sdk/tool-bridge.d.ts +1 -8
  51. package/dist/providers/index.js +8 -53
  52. package/dist/providers/opencode-sdk/adapter.d.ts +1 -13
  53. package/dist/providers/opencode-sdk/adapter.js +4 -51
  54. package/dist/providers/opencode-sdk/agent-bridge.d.ts +1 -10
  55. package/dist/providers/opencode-sdk/index.js +4 -51
  56. package/dist/providers/opencode-sdk/tool-bridge.d.ts +1 -4
  57. package/dist/providers/types.d.ts +1 -8
  58. package/dist/session/store.d.ts +2 -2
  59. package/dist/telemetry/adapter.d.ts +1 -0
  60. package/dist/telemetry/adapter.js +2 -0
  61. package/dist/telemetry/index.js +2 -0
  62. package/dist/tools/knowledge-tool.d.ts +1 -1
  63. package/dist/tools/mcp-server.d.ts +1 -1
  64. package/dist/tools/operation-tool-handler.d.ts +1 -1
  65. package/dist/tools/tool-adapter.d.ts +1 -1
  66. package/dist/types.d.ts +13 -0
  67. package/package.json +7 -43
  68. package/dist/node/spec/index.js +0 -2233
  69. package/dist/node/spec/registry.js +0 -2178
  70. package/dist/node/spec/spec.js +0 -2188
  71. package/dist/spec/index.d.ts +0 -2
  72. package/dist/spec/index.js +0 -2233
  73. package/dist/spec/registry.d.ts +0 -41
  74. package/dist/spec/registry.js +0 -2178
  75. package/dist/spec/spec.d.ts +0 -218
  76. package/dist/spec/spec.js +0 -2188
  77. package/dist/spec/spec.test.d.ts +0 -1
@@ -2185,56 +2185,6 @@ var init_injector = __esm(() => {
2185
2185
  init_i18n();
2186
2186
  });
2187
2187
 
2188
- // src/spec/spec.ts
2189
- function defineAgent(spec) {
2190
- const i18n = createAgentI18n(spec.locale);
2191
- if (!spec.meta?.key) {
2192
- throw new Error(i18n.t("error.agentKeyRequired"));
2193
- }
2194
- if (typeof spec.meta.version !== "string") {
2195
- throw new Error(i18n.t("error.agentMissingVersion", { key: spec.meta.key }));
2196
- }
2197
- if (!spec.instructions?.trim()) {
2198
- throw new Error(i18n.t("error.agentRequiresInstructions", { key: spec.meta.key }));
2199
- }
2200
- if (!spec.tools?.length) {
2201
- throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
2202
- }
2203
- for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
2204
- if (portRef !== undefined && portRef.trim().length === 0) {
2205
- throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
2206
- }
2207
- }
2208
- const toolNames = new Set;
2209
- for (const tool of spec.tools) {
2210
- if (toolNames.has(tool.name)) {
2211
- throw new Error(i18n.t("error.agentDuplicateTool", {
2212
- key: spec.meta.key,
2213
- name: tool.name
2214
- }));
2215
- }
2216
- toolNames.add(tool.name);
2217
- if (tool.subagentRef && tool.operationRef) {
2218
- throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" cannot have both subagentRef and operationRef. Use one.`);
2219
- }
2220
- const outputRefCount = [
2221
- tool.outputPresentation,
2222
- tool.outputForm,
2223
- tool.outputDataView
2224
- ].filter(Boolean).length;
2225
- if (outputRefCount > 1) {
2226
- throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" has multiple output refs (outputPresentation, outputForm, outputDataView). Use at most one.`);
2227
- }
2228
- }
2229
- return Object.freeze(spec);
2230
- }
2231
- function agentKey(meta) {
2232
- return `${meta.key}.v${meta.version}`;
2233
- }
2234
- var init_spec = __esm(() => {
2235
- init_i18n();
2236
- });
2237
-
2238
2188
  // src/tools/mcp-client-helpers.ts
2239
2189
  import {
2240
2190
  Experimental_StdioMCPTransport as StdioClientTransport
@@ -2664,6 +2614,9 @@ var init_tool_bridge = __esm(() => {
2664
2614
 
2665
2615
  // src/providers/claude-agent-sdk/adapter.ts
2666
2616
  import { randomUUID } from "crypto";
2617
+ import {
2618
+ agentKey
2619
+ } from "@contractspec/lib.contracts-spec/agent";
2667
2620
 
2668
2621
  class ClaudeAgentSDKProvider {
2669
2622
  name = "claude-agent-sdk";
@@ -3019,7 +2972,6 @@ ${params.systemOverride}` : context.spec.instructions;
3019
2972
  var init_adapter = __esm(() => {
3020
2973
  init_i18n();
3021
2974
  init_injector();
3022
- init_spec();
3023
2975
  init_mcp_client();
3024
2976
  init_types();
3025
2977
  init_tool_bridge();
@@ -1,11 +1,4 @@
1
- /**
2
- * Tool bridge for converting between ContractSpec and Claude Agent SDK tool formats.
3
- *
4
- * Provides bidirectional conversion:
5
- * - ContractSpec AgentToolConfig → Claude Agent SDK tool
6
- * - Claude Agent SDK tool → ContractSpec AgentToolConfig
7
- */
8
- import type { AgentToolConfig } from '../../spec/spec';
1
+ import type { AgentToolConfig } from '@contractspec/lib.contracts-spec/agent';
9
2
  import type { ToolExecutionContext, ToolHandler } from '../../types';
10
3
  import type { ExternalToolDefinition } from '../types';
11
4
  /**
@@ -2185,56 +2185,6 @@ var init_injector = __esm(() => {
2185
2185
  init_i18n();
2186
2186
  });
2187
2187
 
2188
- // src/spec/spec.ts
2189
- function defineAgent(spec) {
2190
- const i18n = createAgentI18n(spec.locale);
2191
- if (!spec.meta?.key) {
2192
- throw new Error(i18n.t("error.agentKeyRequired"));
2193
- }
2194
- if (typeof spec.meta.version !== "string") {
2195
- throw new Error(i18n.t("error.agentMissingVersion", { key: spec.meta.key }));
2196
- }
2197
- if (!spec.instructions?.trim()) {
2198
- throw new Error(i18n.t("error.agentRequiresInstructions", { key: spec.meta.key }));
2199
- }
2200
- if (!spec.tools?.length) {
2201
- throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
2202
- }
2203
- for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
2204
- if (portRef !== undefined && portRef.trim().length === 0) {
2205
- throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
2206
- }
2207
- }
2208
- const toolNames = new Set;
2209
- for (const tool of spec.tools) {
2210
- if (toolNames.has(tool.name)) {
2211
- throw new Error(i18n.t("error.agentDuplicateTool", {
2212
- key: spec.meta.key,
2213
- name: tool.name
2214
- }));
2215
- }
2216
- toolNames.add(tool.name);
2217
- if (tool.subagentRef && tool.operationRef) {
2218
- throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" cannot have both subagentRef and operationRef. Use one.`);
2219
- }
2220
- const outputRefCount = [
2221
- tool.outputPresentation,
2222
- tool.outputForm,
2223
- tool.outputDataView
2224
- ].filter(Boolean).length;
2225
- if (outputRefCount > 1) {
2226
- throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" has multiple output refs (outputPresentation, outputForm, outputDataView). Use at most one.`);
2227
- }
2228
- }
2229
- return Object.freeze(spec);
2230
- }
2231
- function agentKey(meta) {
2232
- return `${meta.key}.v${meta.version}`;
2233
- }
2234
- var init_spec = __esm(() => {
2235
- init_i18n();
2236
- });
2237
-
2238
2188
  // src/tools/mcp-client-helpers.ts
2239
2189
  import {
2240
2190
  Experimental_StdioMCPTransport as StdioClientTransport
@@ -2664,6 +2614,9 @@ var init_tool_bridge = __esm(() => {
2664
2614
 
2665
2615
  // src/providers/claude-agent-sdk/adapter.ts
2666
2616
  import { randomUUID } from "crypto";
2617
+ import {
2618
+ agentKey
2619
+ } from "@contractspec/lib.contracts-spec/agent";
2667
2620
 
2668
2621
  class ClaudeAgentSDKProvider {
2669
2622
  name = "claude-agent-sdk";
@@ -3019,7 +2972,6 @@ ${params.systemOverride}` : context.spec.instructions;
3019
2972
  var init_adapter = __esm(() => {
3020
2973
  init_i18n();
3021
2974
  init_injector();
3022
- init_spec();
3023
2975
  init_mcp_client();
3024
2976
  init_types();
3025
2977
  init_tool_bridge();
@@ -3342,6 +3294,10 @@ var init_agent_bridge = __esm(() => {
3342
3294
  });
3343
3295
 
3344
3296
  // src/providers/opencode-sdk/adapter.ts
3297
+ import {
3298
+ agentKey as agentKey2
3299
+ } from "@contractspec/lib.contracts-spec/agent";
3300
+
3345
3301
  class OpenCodeSDKProvider {
3346
3302
  name = "opencode-sdk";
3347
3303
  version = "1.0.0";
@@ -3392,7 +3348,7 @@ class OpenCodeSDKProvider {
3392
3348
  toolSet[tool.name] = specToolToExternalToolForOpenCode(tool);
3393
3349
  }
3394
3350
  const instructions = await injectStaticKnowledge(spec.instructions, spec.knowledge ?? [], undefined);
3395
- const contextId = `opencode-${agentKey(spec.meta)}-${Date.now()}`;
3351
+ const contextId = `opencode-${agentKey2(spec.meta)}-${Date.now()}`;
3396
3352
  const metadata = {
3397
3353
  sessionId: session.id,
3398
3354
  agentType: this.config.agentType ?? inferAgentType(spec),
@@ -3607,7 +3563,6 @@ ${params.systemOverride}` : context.spec.instructions;
3607
3563
  var init_adapter2 = __esm(() => {
3608
3564
  init_i18n();
3609
3565
  init_injector();
3610
- init_spec();
3611
3566
  init_types();
3612
3567
  init_agent_bridge();
3613
3568
  init_tool_bridge2();
@@ -1,16 +1,4 @@
1
- /**
2
- * OpenCode SDK Provider
3
- *
4
- * Enables ContractSpec agents to run via OpenCode server:
5
- * - Session-based execution
6
- * - Multiple agent types (Build, Plan, General, Explore)
7
- * - Type-safe client interface
8
- * - Real-time streaming support
9
- *
10
- * This adapter wraps @opencode-ai/sdk to work as a backend
11
- * for ContractSpec agents.
12
- */
13
- import type { AgentSpec } from '../../spec/spec';
1
+ import { type AgentSpec } from '@contractspec/lib.contracts-spec/agent';
14
2
  import type { ExternalAgentContext, ExternalAgentProvider, ExternalExecuteParams, ExternalExecuteResult, ExternalStreamChunk, OpenCodeSDKConfig } from '../types';
15
3
  /**
16
4
  * OpenCode SDK Provider implementation.
@@ -2185,56 +2185,6 @@ var init_injector = __esm(() => {
2185
2185
  init_i18n();
2186
2186
  });
2187
2187
 
2188
- // src/spec/spec.ts
2189
- function defineAgent(spec) {
2190
- const i18n = createAgentI18n(spec.locale);
2191
- if (!spec.meta?.key) {
2192
- throw new Error(i18n.t("error.agentKeyRequired"));
2193
- }
2194
- if (typeof spec.meta.version !== "string") {
2195
- throw new Error(i18n.t("error.agentMissingVersion", { key: spec.meta.key }));
2196
- }
2197
- if (!spec.instructions?.trim()) {
2198
- throw new Error(i18n.t("error.agentRequiresInstructions", { key: spec.meta.key }));
2199
- }
2200
- if (!spec.tools?.length) {
2201
- throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
2202
- }
2203
- for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
2204
- if (portRef !== undefined && portRef.trim().length === 0) {
2205
- throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
2206
- }
2207
- }
2208
- const toolNames = new Set;
2209
- for (const tool of spec.tools) {
2210
- if (toolNames.has(tool.name)) {
2211
- throw new Error(i18n.t("error.agentDuplicateTool", {
2212
- key: spec.meta.key,
2213
- name: tool.name
2214
- }));
2215
- }
2216
- toolNames.add(tool.name);
2217
- if (tool.subagentRef && tool.operationRef) {
2218
- throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" cannot have both subagentRef and operationRef. Use one.`);
2219
- }
2220
- const outputRefCount = [
2221
- tool.outputPresentation,
2222
- tool.outputForm,
2223
- tool.outputDataView
2224
- ].filter(Boolean).length;
2225
- if (outputRefCount > 1) {
2226
- throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" has multiple output refs (outputPresentation, outputForm, outputDataView). Use at most one.`);
2227
- }
2228
- }
2229
- return Object.freeze(spec);
2230
- }
2231
- function agentKey(meta) {
2232
- return `${meta.key}.v${meta.version}`;
2233
- }
2234
- var init_spec = __esm(() => {
2235
- init_i18n();
2236
- });
2237
-
2238
2188
  // src/providers/types.ts
2239
2189
  var ExternalProviderError, ProviderNotAvailableError, ProviderExecutionError, ContextCreationError;
2240
2190
  var init_types = __esm(() => {
@@ -2562,6 +2512,10 @@ var init_agent_bridge = __esm(() => {
2562
2512
  });
2563
2513
 
2564
2514
  // src/providers/opencode-sdk/adapter.ts
2515
+ import {
2516
+ agentKey
2517
+ } from "@contractspec/lib.contracts-spec/agent";
2518
+
2565
2519
  class OpenCodeSDKProvider {
2566
2520
  name = "opencode-sdk";
2567
2521
  version = "1.0.0";
@@ -2827,7 +2781,6 @@ ${params.systemOverride}` : context.spec.instructions;
2827
2781
  var init_adapter = __esm(() => {
2828
2782
  init_i18n();
2829
2783
  init_injector();
2830
- init_spec();
2831
2784
  init_types();
2832
2785
  init_agent_bridge();
2833
2786
  init_tool_bridge();
@@ -1,13 +1,4 @@
1
- /**
2
- * Agent bridge for mapping between ContractSpec AgentSpec and OpenCode agent configuration.
3
- *
4
- * OpenCode has four built-in agent types:
5
- * - build: Primary agent with all tools enabled (default for code generation)
6
- * - plan: Restricted agent for analysis/planning (file edits and bash in "ask" mode)
7
- * - general: Subagent for complex questions and multi-step tasks
8
- * - explore: Fast subagent for codebase exploration
9
- */
10
- import type { AgentSpec } from '../../spec/spec';
1
+ import type { AgentSpec } from '@contractspec/lib.contracts-spec/agent';
11
2
  import type { OpenCodeAgentType } from '../types';
12
3
  import { type OpenCodeTool } from './tool-bridge';
13
4
  /**
@@ -2185,56 +2185,6 @@ var init_injector = __esm(() => {
2185
2185
  init_i18n();
2186
2186
  });
2187
2187
 
2188
- // src/spec/spec.ts
2189
- function defineAgent(spec) {
2190
- const i18n = createAgentI18n(spec.locale);
2191
- if (!spec.meta?.key) {
2192
- throw new Error(i18n.t("error.agentKeyRequired"));
2193
- }
2194
- if (typeof spec.meta.version !== "string") {
2195
- throw new Error(i18n.t("error.agentMissingVersion", { key: spec.meta.key }));
2196
- }
2197
- if (!spec.instructions?.trim()) {
2198
- throw new Error(i18n.t("error.agentRequiresInstructions", { key: spec.meta.key }));
2199
- }
2200
- if (!spec.tools?.length) {
2201
- throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
2202
- }
2203
- for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
2204
- if (portRef !== undefined && portRef.trim().length === 0) {
2205
- throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
2206
- }
2207
- }
2208
- const toolNames = new Set;
2209
- for (const tool of spec.tools) {
2210
- if (toolNames.has(tool.name)) {
2211
- throw new Error(i18n.t("error.agentDuplicateTool", {
2212
- key: spec.meta.key,
2213
- name: tool.name
2214
- }));
2215
- }
2216
- toolNames.add(tool.name);
2217
- if (tool.subagentRef && tool.operationRef) {
2218
- throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" cannot have both subagentRef and operationRef. Use one.`);
2219
- }
2220
- const outputRefCount = [
2221
- tool.outputPresentation,
2222
- tool.outputForm,
2223
- tool.outputDataView
2224
- ].filter(Boolean).length;
2225
- if (outputRefCount > 1) {
2226
- throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" has multiple output refs (outputPresentation, outputForm, outputDataView). Use at most one.`);
2227
- }
2228
- }
2229
- return Object.freeze(spec);
2230
- }
2231
- function agentKey(meta) {
2232
- return `${meta.key}.v${meta.version}`;
2233
- }
2234
- var init_spec = __esm(() => {
2235
- init_i18n();
2236
- });
2237
-
2238
2188
  // src/providers/types.ts
2239
2189
  var ExternalProviderError, ProviderNotAvailableError, ProviderExecutionError, ContextCreationError;
2240
2190
  var init_types = __esm(() => {
@@ -2562,6 +2512,10 @@ var init_agent_bridge = __esm(() => {
2562
2512
  });
2563
2513
 
2564
2514
  // src/providers/opencode-sdk/adapter.ts
2515
+ import {
2516
+ agentKey
2517
+ } from "@contractspec/lib.contracts-spec/agent";
2518
+
2565
2519
  class OpenCodeSDKProvider {
2566
2520
  name = "opencode-sdk";
2567
2521
  version = "1.0.0";
@@ -2827,7 +2781,6 @@ ${params.systemOverride}` : context.spec.instructions;
2827
2781
  var init_adapter = __esm(() => {
2828
2782
  init_i18n();
2829
2783
  init_injector();
2830
- init_spec();
2831
2784
  init_types();
2832
2785
  init_agent_bridge();
2833
2786
  init_tool_bridge();
@@ -1,7 +1,4 @@
1
- /**
2
- * Tool bridge for converting between ContractSpec and OpenCode SDK tool formats.
3
- */
4
- import type { AgentToolConfig } from '../../spec/spec';
1
+ import type { AgentToolConfig } from '@contractspec/lib.contracts-spec/agent';
5
2
  import type { ToolExecutionContext, ToolHandler } from '../../types';
6
3
  import type { ExternalToolDefinition } from '../types';
7
4
  /**
@@ -1,11 +1,4 @@
1
- /**
2
- * External SDK provider types for ContractSpec agents.
3
- *
4
- * These interfaces define the contract for integrating external agent SDKs
5
- * (like @anthropic-ai/claude-agent-sdk and @opencode-ai/sdk) with ContractSpec's
6
- * agent system.
7
- */
8
- import type { AgentSpec } from '../spec/spec';
1
+ import type { AgentSpec } from '@contractspec/lib.contracts-spec/agent';
9
2
  import type { McpClientConfig } from '../tools/mcp-client';
10
3
  import type { AgentCallOptions, AgentFinishReason, ToolCallInfo, ToolResultInfo } from '../types';
11
4
  /**
@@ -26,7 +26,7 @@ export interface AgentSessionStore {
26
26
  /**
27
27
  * Update session properties.
28
28
  */
29
- update(sessionId: string, updates: Partial<Pick<AgentSessionState, 'status' | 'metadata'>>): Promise<void>;
29
+ update(sessionId: string, updates: Partial<Pick<AgentSessionState, 'status' | 'metadata' | 'workflowId' | 'threadId' | 'traceId' | 'checkpointId' | 'pendingApprovalRequestId' | 'lastError'>>): Promise<void>;
30
30
  /**
31
31
  * Delete a session.
32
32
  */
@@ -58,7 +58,7 @@ export declare class InMemorySessionStore implements AgentSessionStore {
58
58
  create(session: Omit<AgentSessionState, 'createdAt' | 'updatedAt'>): Promise<AgentSessionState>;
59
59
  appendStep(sessionId: string, step: StepResult<ToolSet>): Promise<void>;
60
60
  appendMessage(sessionId: string, message: ModelMessage): Promise<void>;
61
- update(sessionId: string, updates: Partial<Pick<AgentSessionState, 'status' | 'metadata'>>): Promise<void>;
61
+ update(sessionId: string, updates: Partial<Pick<AgentSessionState, 'status' | 'metadata' | 'workflowId' | 'threadId' | 'traceId' | 'checkpointId' | 'pendingApprovalRequestId' | 'lastError'>>): Promise<void>;
62
62
  delete(sessionId: string): Promise<boolean>;
63
63
  listByAgent(agentId: string, limit?: number): Promise<AgentSessionState[]>;
64
64
  listByTenant(tenantId: string, limit?: number): Promise<AgentSessionState[]>;
@@ -30,6 +30,7 @@ interface TrackAgentStepContext {
30
30
  sessionId?: string;
31
31
  tenantId?: string;
32
32
  actorId?: string;
33
+ workflowId?: string;
33
34
  traceId?: string;
34
35
  stepIndex?: number;
35
36
  stepStartedAt?: Date;
@@ -83,6 +83,7 @@ async function trackAgentStep(collector, agentId, step, durationMs, context) {
83
83
  agentId,
84
84
  actorId: context?.actorId,
85
85
  tenantId: context?.tenantId,
86
+ workflowId: context?.workflowId,
86
87
  stepIndex: context?.stepIndex,
87
88
  toolName: toolCall.toolName,
88
89
  toolCallArgs: toolCall.input,
@@ -108,6 +109,7 @@ async function trackAgentStep(collector, agentId, step, durationMs, context) {
108
109
  agentId,
109
110
  actorId: context?.actorId,
110
111
  tenantId: context?.tenantId,
112
+ workflowId: context?.workflowId,
111
113
  stepIndex: context?.stepIndex,
112
114
  stepStartedAt: context?.stepStartedAt,
113
115
  finishReason: step.finishReason,
@@ -2198,6 +2198,7 @@ async function trackAgentStep(collector, agentId, step, durationMs, context) {
2198
2198
  agentId,
2199
2199
  actorId: context?.actorId,
2200
2200
  tenantId: context?.tenantId,
2201
+ workflowId: context?.workflowId,
2201
2202
  stepIndex: context?.stepIndex,
2202
2203
  toolName: toolCall.toolName,
2203
2204
  toolCallArgs: toolCall.input,
@@ -2223,6 +2224,7 @@ async function trackAgentStep(collector, agentId, step, durationMs, context) {
2223
2224
  agentId,
2224
2225
  actorId: context?.actorId,
2225
2226
  tenantId: context?.tenantId,
2227
+ workflowId: context?.workflowId,
2226
2228
  stepIndex: context?.stepIndex,
2227
2229
  stepStartedAt: context?.stepStartedAt,
2228
2230
  finishReason: step.finishReason,
@@ -1,6 +1,6 @@
1
+ import type { AgentKnowledgeRef } from '@contractspec/lib.contracts-spec/agent';
1
2
  import type { KnowledgeRetriever } from '@contractspec/lib.knowledge/retriever';
2
3
  import { type Tool } from 'ai';
3
- import type { AgentKnowledgeRef } from '../spec/spec';
4
4
  /**
5
5
  * Create a knowledge query tool for dynamic RAG.
6
6
  *
@@ -1,6 +1,6 @@
1
+ import type { AgentSpec } from '@contractspec/lib.contracts-spec/agent';
1
2
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
3
  import type { ContractSpecAgent } from '../agent/contract-spec-agent';
3
- import type { AgentSpec } from '../spec/spec';
4
4
  /**
5
5
  * Generate an MCP server that exposes a ContractSpec agent as a tool.
6
6
  *
@@ -5,8 +5,8 @@
5
5
  * operationRef, this module provides the handler that delegates to
6
6
  * OperationSpecRegistry.execute.
7
7
  */
8
+ import type { OperationRef } from '@contractspec/lib.contracts-spec/agent';
8
9
  import type { OperationSpecRegistry } from '@contractspec/lib.contracts-spec/operations/registry';
9
- import type { OperationRef } from '../spec/spec';
10
10
  import type { ToolHandler } from '../types';
11
11
  /**
12
12
  * Create a ToolHandler that executes a ContractSpec operation.
@@ -1,8 +1,8 @@
1
+ import type { AgentToolConfig } from '@contractspec/lib.contracts-spec/agent';
1
2
  import type { AnyOperationSpec } from '@contractspec/lib.contracts-spec/operations/operation';
2
3
  import type { OperationSpecRegistry } from '@contractspec/lib.contracts-spec/operations/registry';
3
4
  import { type Tool } from 'ai';
4
5
  import * as z from 'zod';
5
- import type { AgentToolConfig } from '../spec/spec';
6
6
  import type { ToolExecutionContext, ToolHandler } from '../types';
7
7
  import { type SubagentLike } from './subagent-tool';
8
8
  export declare function specToolToAISDKTool(specTool: AgentToolConfig, handler: ToolHandler, context?: Partial<ToolExecutionContext>, effectiveInputSchema?: z.ZodType,
package/dist/types.d.ts CHANGED
@@ -47,6 +47,9 @@ export interface AgentEventPayload {
47
47
  sessionId: string;
48
48
  agentId: string;
49
49
  tenantId?: string;
50
+ workflowId?: string;
51
+ traceId?: string;
52
+ checkpointId?: string;
50
53
  stepIndex?: number;
51
54
  toolName?: string;
52
55
  metadata?: Record<string, unknown>;
@@ -62,6 +65,10 @@ export interface AgentCallOptions {
62
65
  actorId?: string;
63
66
  /** Session to resume; new session created when omitted */
64
67
  sessionId?: string;
68
+ /** Parent workflow execution id when the agent runs inside a workflow. */
69
+ workflowId?: string;
70
+ /** External thread id used by checkpoint-capable runtimes. */
71
+ threadId?: string;
65
72
  /** Arbitrary metadata forwarded to events and tool handlers */
66
73
  metadata?: Record<string, string>;
67
74
  /** Locale override for this call */
@@ -80,11 +87,17 @@ export interface AgentSessionState {
80
87
  agentId: string;
81
88
  tenantId?: string;
82
89
  actorId?: string;
90
+ workflowId?: string;
91
+ threadId?: string;
92
+ traceId?: string;
93
+ checkpointId?: string;
83
94
  /** Active locale for this session */
84
95
  locale?: string;
85
96
  status: AgentStatus;
86
97
  messages: ModelMessage[];
87
98
  steps: StepResult<ToolSet>[];
99
+ pendingApprovalRequestId?: string;
100
+ lastError?: AgentExecutionError;
88
101
  createdAt: Date;
89
102
  updatedAt: Date;
90
103
  metadata?: Record<string, string>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@contractspec/lib.ai-agent",
3
- "version": "7.0.10",
3
+ "version": "8.0.2",
4
4
  "description": "AI agent orchestration with MCP and tool support",
5
5
  "keywords": [
6
6
  "contractspec",
@@ -42,9 +42,9 @@
42
42
  "@modelcontextprotocol/sdk": "^1.27.1",
43
43
  "@posthog/react": "^1.8.2",
44
44
  "@posthog/ai": "7.12.2",
45
- "@contractspec/lib.contracts-spec": "4.1.2",
46
- "@contractspec/lib.ai-providers": "3.7.8",
47
- "@contractspec/lib.knowledge": "3.7.10",
45
+ "@contractspec/lib.contracts-spec": "5.0.2",
46
+ "@contractspec/lib.ai-providers": "3.7.10",
47
+ "@contractspec/lib.knowledge": "3.7.14",
48
48
  "compare-versions": "^6.1.1",
49
49
  "zod": "^4.3.5"
50
50
  },
@@ -52,7 +52,7 @@
52
52
  "@anthropic-ai/claude-agent-sdk": ">=0.1.0",
53
53
  "@opencode-ai/sdk": ">=1.0.0",
54
54
  "posthog-node": ">=4.0.0",
55
- "@contractspec/lib.surface-runtime": "0.5.10"
55
+ "@contractspec/lib.surface-runtime": "0.5.14"
56
56
  },
57
57
  "peerDependenciesMeta": {
58
58
  "@anthropic-ai/claude-agent-sdk": {
@@ -72,9 +72,9 @@
72
72
  }
73
73
  },
74
74
  "devDependencies": {
75
- "@contractspec/tool.typescript": "3.7.8",
75
+ "@contractspec/tool.typescript": "3.7.10",
76
76
  "typescript": "^5.9.3",
77
- "@contractspec/tool.bun": "3.7.8"
77
+ "@contractspec/tool.bun": "3.7.10"
78
78
  },
79
79
  "exports": {
80
80
  ".": {
@@ -353,24 +353,6 @@
353
353
  "node": "./dist/node/session/store.js",
354
354
  "default": "./dist/session/store.js"
355
355
  },
356
- "./spec": {
357
- "types": "./dist/spec/index.d.ts",
358
- "bun": "./dist/spec/index.js",
359
- "node": "./dist/node/spec/index.js",
360
- "default": "./dist/spec/index.js"
361
- },
362
- "./spec/registry": {
363
- "types": "./dist/spec/registry.d.ts",
364
- "bun": "./dist/spec/registry.js",
365
- "node": "./dist/node/spec/registry.js",
366
- "default": "./dist/spec/registry.js"
367
- },
368
- "./spec/spec": {
369
- "types": "./dist/spec/spec.d.ts",
370
- "bun": "./dist/spec/spec.js",
371
- "node": "./dist/node/spec/spec.js",
372
- "default": "./dist/spec/spec.js"
373
- },
374
356
  "./telemetry": {
375
357
  "types": "./dist/telemetry/index.d.ts",
376
358
  "bun": "./dist/telemetry/index.js",
@@ -752,24 +734,6 @@
752
734
  "node": "./dist/node/session/store.js",
753
735
  "default": "./dist/session/store.js"
754
736
  },
755
- "./spec": {
756
- "types": "./dist/spec/index.d.ts",
757
- "bun": "./dist/spec/index.js",
758
- "node": "./dist/node/spec/index.js",
759
- "default": "./dist/spec/index.js"
760
- },
761
- "./spec/registry": {
762
- "types": "./dist/spec/registry.d.ts",
763
- "bun": "./dist/spec/registry.js",
764
- "node": "./dist/node/spec/registry.js",
765
- "default": "./dist/spec/registry.js"
766
- },
767
- "./spec/spec": {
768
- "types": "./dist/spec/spec.d.ts",
769
- "bun": "./dist/spec/spec.js",
770
- "node": "./dist/node/spec/spec.js",
771
- "default": "./dist/spec/spec.js"
772
- },
773
737
  "./telemetry": {
774
738
  "types": "./dist/telemetry/index.d.ts",
775
739
  "bun": "./dist/telemetry/index.js",