@contractspec/lib.ai-agent 5.0.4 → 6.0.0

package/README.md

@@ -31,6 +31,47 @@ Stateful AI agent orchestration with type-safe specs, tool execution, knowledge
 
 These ports are optional by design and keep external runtime dependencies decoupled from core agent contracts.
 
+## Operations as Tools
+
+**Preferred pattern:** One contract → multiple surfaces. Reference a ContractSpec operation in your agent; the tool handler and input schema are derived automatically.
+
+```ts
+import { defineAgent } from '@contractspec/lib.ai-agent';
+import { defineQuery } from '@contractspec/lib.contracts-spec';
+import { OperationSpecRegistry } from '@contractspec/lib.contracts-spec';
+import { createAgentFactory } from '@contractspec/lib.ai-agent/agent/agent-factory';
+
+// 1. Define operation (existing pattern)
+const SearchKnowledgeQuery = defineQuery({
+  meta: { key: 'knowledge.search', version: '1.0.0', owners: ['@platform'], goal: '...', context: '...' },
+  io: { input: SearchInputModel, output: SearchOutputModel },
+});
+
+// 2. Register and bind handler
+const ops = new OperationSpecRegistry().register(SearchKnowledgeQuery).bind(SearchKnowledgeQuery, handler);
+
+// 3. Reference in agent
+const agent = defineAgent({
+  meta: { key: 'support.bot', version: '1.0.0', owners: ['@platform'] },
+  instructions: 'Resolve support tickets.',
+  tools: [
+    { name: 'search_knowledge', operationRef: { key: 'knowledge.search', version: '1.0.0' }, automationSafe: true },
+  ],
+});
+
+// 4. Create factory with operationRegistry
+const factory = createAgentFactory({
+  defaultModel,
+  registry: agentRegistry,
+  toolHandlers: new Map(),
+  operationRegistry: ops,
+});
+```
+
+**Output rendering:** When tool output should render via PresentationSpec, FormSpec, or DataViewSpec, add `outputPresentation`, `outputForm`, or `outputDataView` to `AgentToolConfig` (at most one per tool). The tool adapter wraps raw output as `{ presentationKey, data }`, `{ formKey, defaultValues }`, or `{ dataViewKey, items }` for `ToolResultRenderer`. OperationSpec can also declare these refs; when the tool has no output refs, the operation's refs are used as fallback.
+
+**Fallback (inline tools):** When the tool is not an operation (LLM subcalls, external APIs), use inline `AgentToolConfig` with `schema` and a manual handler in `toolHandlers`.
+
 ## Bundle spec / surface-runtime integration
 
 When building planner agents for `@contractspec/lib.surface-runtime`, planner tools (e.g. `propose-patch`) from `@contractspec/lib.surface-runtime/runtime/planner-tools` map to `AgentToolConfig`. Wire `proposePatchToolConfig` into `AgentSpec.tools`; the handler should validate via `validatePatchProposal` and return `SurfacePatchProposal`. Tools from surface-runtime planner-tools are `AgentToolConfig`-compatible.

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

@@ -1,10 +1,13 @@
 import type { LanguageModel, Tool } from 'ai';
 import type { KnowledgeRetriever } from '@contractspec/lib.knowledge/retriever';
 import type { ModelSelector } from '@contractspec/lib.ai-providers/selector-types';
+import type { OperationSpecRegistry } from '@contractspec/lib.contracts-spec/operations/registry';
 import type { AgentSpec } from '../spec/spec';
 import type { AgentRegistry } from '../spec/registry';
 import type { ToolHandler } from '../types';
 import type { McpClientConfig } from '../tools/mcp-client';
+import type { SubagentRegistry } from '../tools/tool-adapter';
+import type { AgentMemoryStore } from '../tools/agent-memory-store';
 import type { AgentSessionStore } from '../session/store';
 import type { TelemetryCollector } from '../telemetry/adapter';
 import type { PostHogLLMConfig, PostHogTracingOptions } from '../telemetry/posthog-types';
@@ -19,6 +22,12 @@ export interface AgentFactoryConfig {
     registry: AgentRegistry;
     /** Global tool handlers map */
     toolHandlers: Map<string, ToolHandler>;
+    /** Optional OperationSpecRegistry for operation-backed tools (operationRef) */
+    operationRegistry?: OperationSpecRegistry;
+    /** Optional registry for subagent-backed tools (subagentRef) */
+    subagentRegistry?: SubagentRegistry;
+    /** Optional storage for memory tools (when spec.memoryTools.provider is anthropic) */
+    agentMemoryStore?: AgentMemoryStore;
     /** Optional knowledge retriever */
     knowledgeRetriever?: KnowledgeRetriever;
     /** Optional session store */
@@ -48,6 +57,10 @@ export interface CreateAgentOptions {
     additionalTools?: Record<string, Tool<unknown, unknown>>;
     /** MCP servers for this instance */
     mcpServers?: McpClientConfig[];
+    /** Override OperationSpecRegistry for operation-backed tools */
+    operationRegistry?: OperationSpecRegistry;
+    /** Override SubagentRegistry for subagent-backed tools */
+    subagentRegistry?: SubagentRegistry;
 }
 /**
  * Factory for creating ContractSpec agents from specs.

package/dist/agent/agent-factory.js

@@ -2156,6 +2156,17 @@ function defineAgent(spec) {
       }));
     }
     toolNames.add(tool.name);
+    if (tool.subagentRef && tool.operationRef) {
+      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" cannot have both subagentRef and operationRef. Use one.`);
+    }
+    const outputRefCount = [
+      tool.outputPresentation,
+      tool.outputForm,
+      tool.outputDataView
+    ].filter(Boolean).length;
+    if (outputRefCount > 1) {
+      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" has multiple output refs (outputPresentation, outputForm, outputDataView). Use at most one.`);
+    }
   }
   return Object.freeze(spec);
 }
@@ -2299,15 +2310,124 @@ function jsonSchemaToZodSafe(schema) {
 }
 var init_json_schema_to_zod = () => {};
 
+// src/tools/operation-tool-handler.ts
+function toolCtxToHandlerCtx(ctx) {
+  return {
+    traceId: ctx.metadata?.traceId,
+    organizationId: ctx.tenantId ?? null,
+    userId: ctx.actorId ?? null,
+    actor: ctx.actorId ? "user" : "anonymous",
+    channel: "agent",
+    roles: []
+  };
+}
+function createOperationToolHandler(registry, operationRef) {
+  return async (input, context) => {
+    const handlerCtx = toolCtxToHandlerCtx(context);
+    const result = await registry.execute(operationRef.key, operationRef.version, input ?? {}, handlerCtx);
+    return result;
+  };
+}
+
+// src/tools/subagent-tool.ts
+import { readUIMessageStream, tool } from "ai";
+import { z as z2 } from "zod";
+function toReadableStream(iterable) {
+  if (iterable instanceof ReadableStream) {
+    return iterable;
+  }
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const chunk of iterable) {
+          controller.enqueue(chunk);
+        }
+      } finally {
+        controller.close();
+      }
+    }
+  });
+}
+function createSubagentTool(options) {
+  const {
+    subagent,
+    description = "Research a topic or question in depth.",
+    taskParam = "task",
+    toModelSummary = true,
+    passConversationHistory = false
+  } = options;
+  const inputSchema = z2.object({
+    [taskParam]: z2.string().describe("The research task to complete")
+  });
+  const execute = async function* (input, options2) {
+    const task = String(input[taskParam] ?? input.task ?? "");
+    const { abortSignal, messages } = options2 ?? {};
+    if (passConversationHistory && messages && messages.length > 0 && typeof subagent.generate === "function") {
+      const result2 = await subagent.generate({
+        messages: [...messages, { role: "user", content: task }],
+        abortSignal
+      });
+      yield { parts: [{ type: "text", text: result2.text }] };
+      return;
+    }
+    const result = await subagent.stream({
+      prompt: task,
+      abortSignal
+    });
+    const uiStream = result.toUIMessageStream();
+    const stream = toReadableStream(uiStream);
+    for await (const message of readUIMessageStream({
+      stream
+    })) {
+      yield message;
+    }
+  };
+  const toolOptions = {
+    description,
+    inputSchema,
+    execute,
+    ...toModelSummary && {
+      toModelOutput: ({
+        output
+      }) => {
+        const parts = output?.parts;
+        if (!Array.isArray(parts)) {
+          return { type: "text", value: "Task completed." };
+        }
+        const lastTextPart = [...parts].reverse().find((p) => p?.type === "text");
+        return {
+          type: "text",
+          value: lastTextPart?.text ?? "Task completed."
+        };
+      }
+    }
+  };
+  return tool(toolOptions);
+}
+var init_subagent_tool = () => {};
+
 // src/tools/tool-adapter.ts
-import { tool } from "ai";
-function specToolToAISDKTool(specTool, handler, context = {}) {
+import { tool as tool2 } from "ai";
+function isAsyncGenerator(value) {
+  return typeof value === "object" && value !== null && typeof value.next === "function" && typeof value[Symbol.asyncIterator] === "function";
+}
+function specToolToAISDKTool(specTool, handler, context = {}, effectiveInputSchema, operationSpec) {
   let lastInvocationAt;
-  return tool({
+  const inputSchema = effectiveInputSchema ?? jsonSchemaToZodSafe(specTool.schema);
+  const buildContext = (signal) => ({
+    agentId: context.agentId ?? "unknown",
+    sessionId: context.sessionId ?? "unknown",
+    tenantId: context.tenantId,
+    actorId: context.actorId,
+    locale: context.locale,
+    metadata: context.metadata,
+    signal
+  });
+  return tool2({
     description: specTool.description ?? specTool.name,
-    inputSchema: jsonSchemaToZodSafe(specTool.schema),
+    inputSchema,
     needsApproval: specTool.requiresApproval ?? !specTool.automationSafe,
-    execute: async (input) => {
+    execute: async function* (input, options) {
       const now = Date.now();
       const cooldownMs = normalizeDuration(specTool.cooldownMs);
       if (cooldownMs && lastInvocationAt !== undefined) {
@@ -2318,19 +2438,20 @@ function specToolToAISDKTool(specTool, handler, context = {}) {
         }
       }
       const timeoutMs = normalizeDuration(specTool.timeoutMs);
-      const { signal, dispose } = createTimeoutSignal(context.signal, timeoutMs);
+      const signal = options?.abortSignal ?? context.signal;
+      const { signal: timeoutSignal, dispose } = createTimeoutSignal(signal, timeoutMs);
       try {
-        const execution = handler(input, {
-          agentId: context.agentId ?? "unknown",
-          sessionId: context.sessionId ?? "unknown",
-          tenantId: context.tenantId,
-          actorId: context.actorId,
-          locale: context.locale,
-          metadata: context.metadata,
-          signal
-        });
-        const result = timeoutMs ? await withTimeout(execution, timeoutMs, specTool.name) : await execution;
-        return typeof result === "string" ? result : JSON.stringify(result);
+        const execution = handler(input, buildContext(timeoutSignal));
+        if (isAsyncGenerator(execution)) {
+          for await (const raw of execution) {
+            const wrapped = wrapToolOutputForRendering(specTool, raw, operationSpec);
+            yield typeof wrapped === "string" ? wrapped : wrapped;
+          }
+        } else {
+          const raw = timeoutMs ? await withTimeout(Promise.resolve(execution), timeoutMs, specTool.name) : await Promise.resolve(execution);
+          const wrapped = wrapToolOutputForRendering(specTool, raw, operationSpec);
+          yield typeof wrapped === "string" ? wrapped : wrapped;
+        }
       } finally {
         dispose();
         lastInvocationAt = Date.now();
@@ -2338,27 +2459,83 @@ function specToolToAISDKTool(specTool, handler, context = {}) {
     }
   });
 }
-function specToolsToAISDKTools(specTools, handlers, context = {}) {
+function specToolsToAISDKTools(specTools, handlers, context = {}, options) {
   const tools = {};
   for (const specTool of specTools) {
-    const handler = handlers.get(specTool.name);
-    if (!handler) {
-      throw new Error(createAgentI18n(context.locale).t("error.missingToolHandler", {
-        name: specTool.name
-      }));
+    if (specTool.subagentRef && options?.subagentRegistry) {
+      const subagent = options.subagentRegistry.get(specTool.subagentRef.agentId);
+      if (!subagent) {
+        throw new Error(`Subagent not found: ${specTool.subagentRef.agentId}. Register it in subagentRegistry.`);
+      }
+      if (specTool.requiresApproval === true || specTool.automationSafe === false) {
+        console.warn(`[ContractSpec] Subagent tool "${specTool.name}" cannot use needsApproval. ` + `requiresApproval and automationSafe are ignored for subagent tools (AI SDK limitation). ` + `See https://ai-sdk.dev/docs/agents/subagents#no-tool-approvals-in-subagents`);
+      }
+      tools[specTool.name] = createSubagentTool({
+        subagent,
+        description: specTool.description ?? specTool.name,
+        toModelSummary: specTool.subagentRef.toModelSummary ?? true,
+        passConversationHistory: specTool.subagentRef.passConversationHistory
+      });
+      continue;
+    }
+    let handler;
+    let effectiveInputSchema;
+    let op;
+    if (specTool.operationRef && options?.operationRegistry) {
+      op = options.operationRegistry.get(specTool.operationRef.key, specTool.operationRef.version);
+      if (!op) {
+        throw new Error(`Operation not found: ${specTool.operationRef.key}${specTool.operationRef.version ? `.v${specTool.operationRef.version}` : ""}`);
+      }
+      handler = createOperationToolHandler(options.operationRegistry, specTool.operationRef);
+      effectiveInputSchema = op.io.input?.getZod?.();
+    } else {
+      const manualHandler = handlers.get(specTool.name);
+      if (!manualHandler) {
+        if (specTool.subagentRef) {
+          throw new Error(`Subagent tool "${specTool.name}" requires subagentRegistry. Pass subagentRegistry in ContractSpecAgentConfig.`);
+        }
+        throw new Error(createAgentI18n(context.locale).t("error.missingToolHandler", {
+          name: specTool.name
+        }));
+      }
+      handler = manualHandler;
     }
-    tools[specTool.name] = specToolToAISDKTool(specTool, handler, context);
+    tools[specTool.name] = specToolToAISDKTool(specTool, handler, context, effectiveInputSchema, op);
   }
   return tools;
 }
 function createToolHandler(handler) {
-  return async (input, context) => {
+  return (input, context) => {
     return handler(input, context);
   };
 }
 function buildToolHandlers(handlersObj) {
   return new Map(Object.entries(handlersObj));
 }
+function wrapToolOutputForRendering(specTool, result, operationSpec) {
+  const presentation = specTool.outputPresentation ?? operationSpec?.outputPresentation;
+  const form = specTool.outputForm ?? operationSpec?.outputForm;
+  const dataView = specTool.outputDataView ?? operationSpec?.outputDataView;
+  if (presentation) {
+    return {
+      presentationKey: presentation.key,
+      data: result
+    };
+  }
+  if (form) {
+    return {
+      formKey: form.key,
+      defaultValues: typeof result === "object" && result !== null ? result : {}
+    };
+  }
+  if (dataView) {
+    return {
+      dataViewKey: dataView.key,
+      items: Array.isArray(result) ? result : result != null ? [result] : []
+    };
+  }
+  return result;
+}
 function normalizeDuration(value) {
   if (value === undefined) {
     return;
@@ -2420,11 +2597,12 @@ function createToolExecutionError(message, code, retryAfterMs) {
 var init_tool_adapter = __esm(() => {
   init_json_schema_to_zod();
   init_i18n();
+  init_subagent_tool();
 });
 
 // src/tools/knowledge-tool.ts
-import { tool as tool2 } from "ai";
-import * as z2 from "zod";
+import { tool as tool3 } from "ai";
+import * as z3 from "zod";
 function createKnowledgeQueryTool(retriever, knowledgeRefs, locale) {
   const i18n = createAgentI18n(locale);
   const optionalSpaces = knowledgeRefs.filter((k) => !k.required).map((k) => k.key).filter((key) => retriever.supportsSpace(key));
@@ -2433,15 +2611,15 @@ function createKnowledgeQueryTool(retriever, knowledgeRefs, locale) {
   }
   const spaceDescriptions = knowledgeRefs.filter((k) => !k.required && retriever.supportsSpace(k.key)).map((k) => `- ${k.key}: ${k.instructions ?? i18n.t("tool.knowledge.spaceDefault")}`).join(`
 `);
-  return tool2({
+  return tool3({
     description: `${i18n.t("tool.knowledge.description")}
 
 ${i18n.t("tool.knowledge.availableSpaces")}
 ${spaceDescriptions}`,
-    inputSchema: z2.object({
-      query: z2.string().describe(i18n.t("tool.knowledge.param.query")),
-      spaceKey: z2.enum(optionalSpaces).optional().describe(i18n.t("tool.knowledge.param.spaceKey")),
-      topK: z2.number().optional().default(5).describe(i18n.t("tool.knowledge.param.topK"))
+    inputSchema: z3.object({
+      query: z3.string().describe(i18n.t("tool.knowledge.param.query")),
+      spaceKey: z3.enum(optionalSpaces).optional().describe(i18n.t("tool.knowledge.param.spaceKey")),
+      topK: z3.number().optional().default(5).describe(i18n.t("tool.knowledge.param.topK"))
     }),
     execute: async ({ query, spaceKey, topK }) => {
       const spacesToSearch = spaceKey ? [spaceKey] : optionalSpaces;
@@ -2481,6 +2659,33 @@ var init_knowledge_tool = __esm(() => {
   init_i18n();
 });
 
+// src/tools/memory-tools.ts
+import { anthropic } from "@ai-sdk/anthropic";
+function createAnthropicMemoryTool(store) {
+  const memory = anthropic.tools.memory_20250818({
+    execute: async (action) => {
+      switch (action.command) {
+        case "view":
+          return store.view(action.path ?? "/memories", action.view_range);
+        case "create":
+          return store.create(action.path ?? "/memories/untitled", action.file_text ?? "");
+        case "str_replace":
+          return store.strReplace(action.path ?? "/memories", action.old_str ?? "", action.new_str ?? "");
+        case "insert":
+          return store.insert(action.path ?? "/memories", action.insert_line ?? 0, action.insert_text ?? "");
+        case "delete":
+          return store.delete(action.path ?? "/memories");
+        case "rename":
+          return store.rename(action.old_path ?? "/memories", action.new_path ?? "/memories");
+        default:
+          return `Unknown command: ${action.command}`;
+      }
+    }
+  });
+  return memory;
+}
+var init_memory_tools = () => {};
+
 // src/tools/mcp-client-helpers.ts
 import {
   Experimental_StdioMCPTransport as StdioClientTransport
@@ -2511,8 +2716,8 @@ function prefixToolNames(config, tools) {
     return tools;
   }
   const prefixedTools = {};
-  for (const [toolName, tool3] of Object.entries(tools)) {
-    prefixedTools[`${prefix}_${toolName}`] = tool3;
+  for (const [toolName, tool4] of Object.entries(tools)) {
+    prefixedTools[`${prefix}_${toolName}`] = tool4;
   }
   return prefixedTools;
 }
@@ -2618,12 +2823,12 @@ async function createMcpToolsets(configs, options = {}) {
       for (const [serverName, toolNames] of Object.entries(result.serverToolNames)) {
         serverToolNames[serverName] = toolNames;
       }
-      for (const [toolName, tool3] of Object.entries(result.tools)) {
+      for (const [toolName, tool4] of Object.entries(result.tools)) {
         const hasCollision = combinedTools[toolName] !== undefined;
         if (hasCollision && collisionStrategy === "error") {
           throw new Error(`Duplicate MCP tool name "${toolName}" detected. Use "toolPrefix" or set onNameCollision to "overwrite".`);
         }
-        combinedTools[toolName] = tool3;
+        combinedTools[toolName] = tool4;
       }
     }
   } catch (error) {
@@ -3146,7 +3351,7 @@ import {
   stepCountIs
 } from "ai";
 import { randomUUID } from "crypto";
-import * as z3 from "zod";
+import * as z4 from "zod";
 
 class ContractSpecAgent {
   version = "agent-v1";
@@ -3175,12 +3380,19 @@ class ContractSpecAgent {
     }
     try {
       const instructions = await injectStaticKnowledge(effectiveConfig.spec.instructions, effectiveConfig.spec.knowledge ?? [], effectiveConfig.knowledgeRetriever);
-      const specTools = specToolsToAISDKTools(effectiveConfig.spec.tools, effectiveConfig.toolHandlers, { agentId: agentKey(effectiveConfig.spec.meta) });
+      const specTools = specToolsToAISDKTools(effectiveConfig.spec.tools, effectiveConfig.toolHandlers, { agentId: agentKey(effectiveConfig.spec.meta) }, {
+        operationRegistry: effectiveConfig.operationRegistry,
+        subagentRegistry: effectiveConfig.subagentRegistry
+      });
       const knowledgeTool = effectiveConfig.knowledgeRetriever ? createKnowledgeQueryTool(effectiveConfig.knowledgeRetriever, effectiveConfig.spec.knowledge ?? []) : null;
+      const memoryTool = effectiveConfig.spec.memoryTools?.provider === "anthropic" && effectiveConfig.agentMemoryStore ? createAnthropicMemoryTool(effectiveConfig.agentMemoryStore) : null;
       const reservedToolNames = new Set(Object.keys(specTools));
       if (knowledgeTool) {
         reservedToolNames.add("query_knowledge");
       }
+      if (memoryTool) {
+        reservedToolNames.add("memory");
+      }
       const conflictingMcpTools = Object.keys(mcpToolset?.tools ?? {}).filter((toolName) => reservedToolNames.has(toolName));
       if (conflictingMcpTools.length > 0) {
         throw new Error(`MCP tools conflict with agent tools: ${conflictingMcpTools.join(", ")}. Configure MCP toolPrefix values to avoid collisions.`);
@@ -3188,6 +3400,7 @@ class ContractSpecAgent {
       const tools = {
         ...specTools,
         ...knowledgeTool ? { query_knowledge: knowledgeTool } : {},
+        ...memoryTool ? { memory: memoryTool } : {},
         ...mcpToolset?.tools ?? {},
         ...effectiveConfig.additionalTools ?? {}
       };
@@ -3219,7 +3432,7 @@ class ContractSpecAgent {
       stepIndex: 0,
       stepStartedAt: new Date
     });
-    if (this.config.sessionStore) {
+    if (this.config.sessionStore && !params.messages?.length) {
       const existing = await this.config.sessionStore.get(sessionId);
       if (!existing) {
         await this.config.sessionStore.create({
@@ -3237,14 +3450,9 @@ class ContractSpecAgent {
       }
       await this.config.sessionStore.appendMessage(sessionId, {
         role: "user",
-        content: params.prompt
+        content: params.prompt ?? ""
       });
     }
-    const prompt = params.systemOverride ? `${this.instructions}
-
-${params.systemOverride}
-
-${params.prompt}` : params.prompt;
     const model = await this.resolveModelForCall({
       sessionId,
       traceId,
@@ -3252,18 +3460,33 @@ ${params.prompt}` : params.prompt;
     });
     const effectiveMaxSteps = resolveMaxSteps(params.maxSteps, this.spec.maxSteps);
     const inner = this.createInnerAgent(model, effectiveMaxSteps);
+    const generateOptions = {
+      abortSignal: params.signal,
+      options: {
+        tenantId: params.options?.tenantId,
+        actorId: params.options?.actorId,
+        sessionId,
+        metadata: params.options?.metadata
+      }
+    };
     let result;
     try {
-      result = await inner.generate({
-        prompt,
-        abortSignal: params.signal,
-        options: {
-          tenantId: params.options?.tenantId,
-          actorId: params.options?.actorId,
-          sessionId,
-          metadata: params.options?.metadata
-        }
-      });
+      if (params.messages && params.messages.length > 0) {
+        result = await inner.generate({
+          messages: params.messages,
+          ...generateOptions
+        });
+      } else {
+        const prompt = params.systemOverride && params.prompt ? `${this.instructions}
+
+${params.systemOverride}
+
+${params.prompt}` : params.prompt ?? "";
+        result = await inner.generate({
+          prompt,
+          ...generateOptions
+        });
+      }
     } catch (error) {
       if (this.config.sessionStore) {
         await this.config.sessionStore.update(sessionId, {
@@ -3323,11 +3546,11 @@ ${params.prompt}` : params.prompt;
       stepIndex: 0,
       stepStartedAt: new Date
     });
-    const prompt = params.systemOverride ? `${this.instructions}
+    const prompt = params.systemOverride && params.prompt ? `${this.instructions}
 
 ${params.systemOverride}
 
-${params.prompt}` : params.prompt;
+${params.prompt}` : params.prompt ?? "";
     const model = await this.resolveModelForCall({
       sessionId,
       traceId,
@@ -3351,7 +3574,7 @@ ${params.prompt}` : params.prompt;
       }
       await this.config.sessionStore.appendMessage(sessionId, {
         role: "user",
-        content: params.prompt
+        content: prompt
       });
       await this.config.sessionStore.update(sessionId, { status: "running" });
     }
@@ -3482,14 +3705,15 @@ var init_contract_spec_agent = __esm(() => {
   init_spec();
   init_tool_adapter();
   init_knowledge_tool();
+  init_memory_tools();
   init_mcp_client();
   init_injector();
   init_adapter();
-  ContractSpecCallOptionsSchema = z3.object({
-    tenantId: z3.string().optional(),
-    actorId: z3.string().optional(),
-    sessionId: z3.string().optional(),
-    metadata: z3.record(z3.string(), z3.unknown()).optional()
+  ContractSpecCallOptionsSchema = z4.object({
+    tenantId: z4.string().optional(),
+    actorId: z4.string().optional(),
+    sessionId: z4.string().optional(),
+    metadata: z4.record(z4.string(), z4.unknown()).optional()
   });
 });
 
@@ -3525,6 +3749,9 @@ class AgentFactory {
       spec,
       model: options?.model ?? this.config.defaultModel,
       toolHandlers: mergedHandlers,
+      operationRegistry: options?.operationRegistry ?? this.config.operationRegistry,
+      subagentRegistry: options?.subagentRegistry ?? this.config.subagentRegistry,
+      agentMemoryStore: this.config.agentMemoryStore,
       knowledgeRetriever: this.config.knowledgeRetriever,
       sessionStore: this.config.sessionStore,
       telemetryCollector: this.config.telemetryCollector,

package/dist/agent/contract-spec-agent.d.ts

@@ -1,8 +1,11 @@
 import { type LanguageModel, type Tool, type ToolSet } from 'ai';
 import type { KnowledgeRetriever } from '@contractspec/lib.knowledge/retriever';
+import type { OperationSpecRegistry } from '@contractspec/lib.contracts-spec/operations/registry';
 import type { AgentSpec } from '../spec/spec';
 import type { ModelSelector } from '@contractspec/lib.ai-providers/selector-types';
 import type { AgentGenerateParams, AgentGenerateResult, AgentStreamParams, ToolHandler } from '../types';
+import { type SubagentRegistry } from '../tools/tool-adapter';
+import type { AgentMemoryStore } from '../tools/agent-memory-store';
 import { type McpClientConfig } from '../tools/mcp-client';
 import { type AgentSessionStore } from '../session/store';
 import { type TelemetryCollector } from '../telemetry/adapter';
@@ -21,6 +24,8 @@ export interface ContractSpecAgentConfig {
     model: LanguageModel;
     /** Map of tool name to handler function */
     toolHandlers: Map<string, ToolHandler>;
+    /** Optional OperationSpecRegistry for operation-backed tools (operationRef) */
+    operationRegistry?: OperationSpecRegistry;
     /** Optional knowledge retriever for RAG */
     knowledgeRetriever?: KnowledgeRetriever;
     /** Optional session store for persistence */
@@ -34,6 +39,10 @@ export interface ContractSpecAgentConfig {
     };
     /** Additional AI SDK tools (e.g., from MCP servers) */
     additionalTools?: Record<string, ExecutableTool>;
+    /** Registry for subagent-backed tools (subagentRef) */
+    subagentRegistry?: SubagentRegistry;
+    /** Storage for memory tools (when memoryTools.provider is anthropic) */
+    agentMemoryStore?: AgentMemoryStore;
     /** MCP servers to connect and expose as tools */
     mcpServers?: McpClientConfig[];
     /** Ranking-driven model selector for dynamic per-call routing */