@contractspec/lib.ai-agent 1.57.0 → 1.59.0

package/dist/agent/agent-factory.js

@@ -1,103 +1,661 @@
-import { ContractSpecAgent } from "./contract-spec-agent.js";
-
-//#region src/agent/agent-factory.ts
-/**
-* Factory for creating ContractSpec agents from specs.
-*
-* Provides a centralized way to instantiate agents with
-* consistent configuration.
-*
-* @example
-* ```typescript
-* const factory = createAgentFactory({
-*   defaultModel: mistral('mistral-large-latest'),
-*   registry: agentRegistry,
-*   toolHandlers: globalToolHandlers,
-*   sessionStore: mySessionStore,
-* });
-*
-* const agent = await factory.create('support.bot');
-* const result = await agent.generate({ prompt: 'Help me with...' });
-* ```
-*/
-var AgentFactory = class {
-	config;
-	cache = /* @__PURE__ */ new Map();
-	constructor(config) {
-		this.config = config;
-	}
-	/**
-	* Create an agent by name.
-	*
-	* @param name - Agent name (e.g., "support.bot")
-	* @param version - Optional specific version
-	* @param options - Optional creation options
-	*/
-	async create(name, version, options) {
-		const spec = this.config.registry.require(name, version);
-		return this.createFromSpec(spec, options);
-	}
-	/**
-	* Create an agent from a spec directly.
-	*
-	* @param spec - Agent specification
-	* @param options - Optional creation options
-	*/
-	async createFromSpec(spec, options) {
-		const mergedHandlers = new Map(this.config.toolHandlers);
-		if (options?.toolHandlers) for (const [key, handler] of options.toolHandlers) mergedHandlers.set(key, handler);
-		const mergedTools = {
-			...this.config.additionalTools,
-			...options?.additionalTools
-		};
-		return ContractSpecAgent.create({
-			spec,
-			model: options?.model ?? this.config.defaultModel,
-			toolHandlers: mergedHandlers,
-			knowledgeRetriever: this.config.knowledgeRetriever,
-			sessionStore: this.config.sessionStore,
-			telemetryCollector: this.config.telemetryCollector,
-			additionalTools: mergedTools
-		});
-	}
-	/**
-	* Get or create a cached agent instance.
-	*
-	* Use this when you want to reuse agent instances.
-	*
-	* @param name - Agent name
-	* @param version - Optional specific version
-	*/
-	async getOrCreate(name, version) {
-		const spec = this.config.registry.require(name, version);
-		const cacheKey = `${spec.meta.key}.v${spec.meta.version}`;
-		let agent = this.cache.get(cacheKey);
-		if (!agent) {
-			agent = await this.createFromSpec(spec);
-			this.cache.set(cacheKey, agent);
-		}
-		return agent;
-	}
-	/**
-	* Clear the agent cache.
-	*/
-	clearCache() {
-		this.cache.clear();
-	}
-	/**
-	* List all available agent names.
-	*/
-	listAvailable() {
-		return this.config.registry.listNames();
-	}
+// @bun
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
 };
-/**
-* Create an agent factory.
-*/
-function createAgentFactory(config) {
-	return new AgentFactory(config);
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/spec/spec.ts
+function defineAgent(spec) {
+  if (!spec.meta?.key) {
+    throw new Error("Agent key is required");
+  }
+  if (typeof spec.meta.version !== "string") {
+    throw new Error(`Agent ${spec.meta.key} is missing a string version`);
+  }
+  if (!spec.instructions?.trim()) {
+    throw new Error(`Agent ${spec.meta.key} requires instructions`);
+  }
+  if (!spec.tools?.length) {
+    throw new Error(`Agent ${spec.meta.key} must expose at least one tool`);
+  }
+  const toolNames = new Set;
+  for (const tool of spec.tools) {
+    if (toolNames.has(tool.name)) {
+      throw new Error(`Agent ${spec.meta.key} has duplicate tool name: ${tool.name}`);
+    }
+    toolNames.add(tool.name);
+  }
+  return Object.freeze(spec);
+}
+function agentKey(meta) {
+  return `${meta.key}.v${meta.version}`;
+}
+
+// src/schema/json-schema-to-zod.ts
+import { z } from "zod";
+function jsonSchemaToZod(schema) {
+  const s = schema;
+  const makeNullable = (zodSchema) => {
+    return s.nullable ? z.union([zodSchema, z.null()]) : zodSchema;
+  };
+  if (s.const !== undefined) {
+    return z.literal(s.const);
+  }
+  if (s.enum) {
+    const values = s.enum;
+    return makeNullable(z.enum(values.map(String)));
+  }
+  if (s.anyOf && s.anyOf.length > 0) {
+    const schemas = s.anyOf.map((sub) => jsonSchemaToZod(sub));
+    if (schemas.length === 1)
+      return schemas[0] ?? z.unknown();
+    return z.union([
+      schemas[0] ?? z.unknown(),
+      schemas[1] ?? z.unknown(),
+      ...schemas.slice(2)
+    ]);
+  }
+  if (s.oneOf && s.oneOf.length > 0) {
+    const schemas = s.oneOf.map((sub) => jsonSchemaToZod(sub));
+    if (schemas.length === 1)
+      return schemas[0] ?? z.unknown();
+    return z.union([
+      schemas[0] ?? z.unknown(),
+      schemas[1] ?? z.unknown(),
+      ...schemas.slice(2)
+    ]);
+  }
+  if (s.allOf && s.allOf.length > 0) {
+    const schemas = s.allOf.map((sub) => jsonSchemaToZod(sub));
+    return schemas.reduce((acc, curr) => z.intersection(acc, curr));
+  }
+  switch (s.type) {
+    case "string":
+      return makeNullable(buildStringSchema(s));
+    case "number":
+    case "integer":
+      return makeNullable(buildNumberSchema(s));
+    case "boolean":
+      return makeNullable(z.boolean());
+    case "null":
+      return z.null();
+    case "array":
+      return makeNullable(buildArraySchema(s));
+    case "object":
+      return makeNullable(buildObjectSchema(s));
+    default:
+      return z.unknown();
+  }
+}
+function buildStringSchema(schema) {
+  let zodSchema = z.string();
+  if (schema.description) {
+    zodSchema = zodSchema.describe(schema.description);
+  }
+  switch (schema.format) {
+    case "email":
+      zodSchema = zodSchema.email();
+      break;
+    case "uri":
+    case "url":
+      zodSchema = zodSchema.url();
+      break;
+    case "uuid":
+      zodSchema = zodSchema.uuid();
+      break;
+    case "date-time":
+      zodSchema = zodSchema.datetime();
+      break;
+    case "date":
+      zodSchema = zodSchema.date();
+      break;
+  }
+  if (schema.minLength !== undefined) {
+    zodSchema = zodSchema.min(schema.minLength);
+  }
+  if (schema.maxLength !== undefined) {
+    zodSchema = zodSchema.max(schema.maxLength);
+  }
+  if (schema.pattern) {
+    zodSchema = zodSchema.regex(new RegExp(schema.pattern));
+  }
+  return zodSchema;
+}
+function buildNumberSchema(schema) {
+  let zodSchema = schema.type === "integer" ? z.number().int() : z.number();
+  if (schema.description) {
+    zodSchema = zodSchema.describe(schema.description);
+  }
+  if (schema.minimum !== undefined) {
+    zodSchema = zodSchema.min(schema.minimum);
+  }
+  if (schema.maximum !== undefined) {
+    zodSchema = zodSchema.max(schema.maximum);
+  }
+  return zodSchema;
+}
+function buildArraySchema(schema) {
+  const itemsSchema = schema.items ? jsonSchemaToZod(schema.items) : z.unknown();
+  let zodSchema = z.array(itemsSchema);
+  if (schema.description) {
+    zodSchema = zodSchema.describe(schema.description);
+  }
+  return zodSchema;
+}
+function buildObjectSchema(schema) {
+  const properties = schema.properties ?? {};
+  const required = new Set(schema.required ?? []);
+  const shape = {};
+  for (const [key, propSchema] of Object.entries(properties)) {
+    const zodProp = jsonSchemaToZod(propSchema);
+    shape[key] = required.has(key) ? zodProp : zodProp.optional();
+  }
+  let zodSchema = z.object(shape);
+  if (schema.description) {
+    zodSchema = zodSchema.describe(schema.description);
+  }
+  return zodSchema;
+}
+function jsonSchemaToZodSafe(schema) {
+  if (!schema || Object.keys(schema).length === 0) {
+    return z.object({});
+  }
+  return jsonSchemaToZod(schema);
+}
+var init_json_schema_to_zod = () => {};
+
+// src/tools/tool-adapter.ts
+import { tool } from "ai";
+function specToolToAISDKTool(specTool, handler, context = {}) {
+  return tool({
+    description: specTool.description ?? specTool.name,
+    inputSchema: jsonSchemaToZodSafe(specTool.schema),
+    needsApproval: specTool.requiresApproval ?? !specTool.automationSafe,
+    execute: async (input) => {
+      const result = await handler(input, {
+        agentId: context.agentId ?? "unknown",
+        sessionId: context.sessionId ?? "unknown",
+        tenantId: context.tenantId,
+        actorId: context.actorId,
+        metadata: context.metadata,
+        signal: context.signal
+      });
+      return typeof result === "string" ? result : JSON.stringify(result);
+    }
+  });
+}
+function specToolsToAISDKTools(specTools, handlers, context = {}) {
+  const tools = {};
+  for (const specTool of specTools) {
+    const handler = handlers.get(specTool.name);
+    if (!handler) {
+      throw new Error(`Missing handler for tool: ${specTool.name}`);
+    }
+    tools[specTool.name] = specToolToAISDKTool(specTool, handler, context);
+  }
+  return tools;
+}
+function createToolHandler(handler) {
+  return async (input, context) => {
+    return handler(input, context);
+  };
+}
+function buildToolHandlers(handlersObj) {
+  return new Map(Object.entries(handlersObj));
+}
+var init_tool_adapter = __esm(() => {
+  init_json_schema_to_zod();
+});
+
+// src/tools/knowledge-tool.ts
+import { tool as tool2 } from "ai";
+import * as z2 from "zod";
+function createKnowledgeQueryTool(retriever, knowledgeRefs) {
+  const optionalSpaces = knowledgeRefs.filter((k) => !k.required).map((k) => k.key).filter((key) => retriever.supportsSpace(key));
+  if (optionalSpaces.length === 0) {
+    return null;
+  }
+  const spaceDescriptions = knowledgeRefs.filter((k) => !k.required && retriever.supportsSpace(k.key)).map((k) => `- ${k.key}: ${k.instructions ?? "Knowledge space"}`).join(`
+`);
+  return tool2({
+    description: `Query knowledge bases for relevant information. Use this tool when you need to look up specific information that may not be in your context.
+
+Available knowledge spaces:
+${spaceDescriptions}`,
+    inputSchema: z2.object({
+      query: z2.string().describe("The question or search query to find relevant information"),
+      spaceKey: z2.enum(optionalSpaces).optional().describe("Specific knowledge space to query. If omitted, searches all available spaces."),
+      topK: z2.number().optional().default(5).describe("Maximum number of results to return")
+    }),
+    execute: async ({ query, spaceKey, topK }) => {
+      const spacesToSearch = spaceKey ? [spaceKey] : optionalSpaces;
+      const allResults = [];
+      for (const space of spacesToSearch) {
+        try {
+          const results = await retriever.retrieve(query, {
+            spaceKey: space,
+            topK: topK ?? 5
+          });
+          for (const result of results) {
+            allResults.push({
+              space,
+              content: result.content,
+              score: result.score
+            });
+          }
+        } catch (error) {
+          console.warn(`Failed to query knowledge space ${space}:`, error);
+        }
+      }
+      if (allResults.length === 0) {
+        return "No relevant information found in the knowledge bases.";
+      }
+      allResults.sort((a, b) => b.score - a.score);
+      const topResults = allResults.slice(0, topK ?? 5);
+      return topResults.map((r, i) => `[Source ${i + 1} - ${r.space}] (relevance: ${(r.score * 100).toFixed(0)}%)
+${r.content}`).join(`
+
+---
+
+`);
+    }
+  });
+}
+var init_knowledge_tool = () => {};
+
+// src/knowledge/injector.ts
+async function injectStaticKnowledge(instructions, knowledgeRefs, retriever) {
+  if (!retriever)
+    return instructions;
+  const requiredRefs = knowledgeRefs.filter((ref) => ref.required);
+  if (requiredRefs.length === 0)
+    return instructions;
+  const blocks = [];
+  for (const ref of requiredRefs) {
+    if (!retriever.supportsSpace(ref.key)) {
+      console.warn(`Required knowledge space "${ref.key}" is not available`);
+      continue;
+    }
+    try {
+      const content = await retriever.getStatic(ref.key);
+      if (content) {
+        const header = ref.instructions ? `## ${ref.key}
+${ref.instructions}` : `## ${ref.key}`;
+        blocks.push(`${header}
+
+${content}`);
+      }
+    } catch (error) {
+      console.warn(`Failed to load required knowledge "${ref.key}":`, error);
+    }
+  }
+  if (blocks.length === 0)
+    return instructions;
+  return `${instructions}
+
+---
+
+# Reference Knowledge
+
+The following information is provided for your reference. Use it to inform your responses.
+
+${blocks.join(`
+
+---
+
+`)}`;
+}
+function createKnowledgeInjector(retriever) {
+  return {
+    inject: (instructions, knowledgeRefs) => injectStaticKnowledge(instructions, knowledgeRefs, retriever),
+    hasSpace: (spaceKey) => retriever?.supportsSpace(spaceKey) ?? false,
+    listSpaces: () => retriever?.listSpaces() ?? []
+  };
+}
+
+// src/session/store.ts
+class InMemorySessionStore {
+  sessions = new Map;
+  async get(sessionId) {
+    return this.sessions.get(sessionId) ?? null;
+  }
+  async create(session) {
+    const now = new Date;
+    const fullSession = {
+      ...session,
+      createdAt: now,
+      updatedAt: now
+    };
+    this.sessions.set(session.sessionId, fullSession);
+    return fullSession;
+  }
+  async appendStep(sessionId, step) {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      session.steps.push(step);
+      session.updatedAt = new Date;
+    }
+  }
+  async appendMessage(sessionId, message) {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      session.messages.push(message);
+      session.updatedAt = new Date;
+    }
+  }
+  async update(sessionId, updates) {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      Object.assign(session, updates, { updatedAt: new Date });
+    }
+  }
+  async delete(sessionId) {
+    return this.sessions.delete(sessionId);
+  }
+  async listByAgent(agentId, limit = 100) {
+    const results = [];
+    for (const session of this.sessions.values()) {
+      if (session.agentId === agentId) {
+        results.push(session);
+        if (results.length >= limit)
+          break;
+      }
+    }
+    return results.sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+  }
+  async listByTenant(tenantId, limit = 100) {
+    const results = [];
+    for (const session of this.sessions.values()) {
+      if (session.tenantId === tenantId) {
+        results.push(session);
+        if (results.length >= limit)
+          break;
+      }
+    }
+    return results.sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+  }
+  clear() {
+    this.sessions.clear();
+  }
+}
+function createInMemorySessionStore() {
+  return new InMemorySessionStore;
+}
+function generateSessionId() {
+  return `sess_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
+}
+
+// src/telemetry/adapter.ts
+function parseAgentId(agentId) {
+  const match = agentId.match(/^(.+)\.v(\s+)$/);
+  if (match) {
+    return { name: match[1], version: match[2] };
+  }
+  return { name: agentId, version: "1.0.0" };
+}
+async function trackAgentStep(collector, agentId, step, durationMs) {
+  const { name, version } = parseAgentId(agentId);
+  for (const toolCall of step.toolCalls ?? []) {
+    const toolSample = {
+      operation: { name: `${name}.${toolCall.toolName}`, version },
+      durationMs: durationMs ?? 0,
+      success: step.toolResults?.some((r) => r.toolCallId === toolCall.toolCallId && r.output !== undefined) ?? false,
+      timestamp: new Date,
+      metadata: {
+        agentId,
+        toolName: toolCall.toolName,
+        finishReason: step.finishReason
+      }
+    };
+    await collector.collect(toolSample);
+  }
+  const stepSample = {
+    operation: { name, version },
+    durationMs: durationMs ?? 0,
+    success: step.finishReason !== "error",
+    timestamp: new Date,
+    metadata: {
+      agentId,
+      finishReason: step.finishReason,
+      tokenUsage: step.usage,
+      toolCallCount: step.toolCalls?.length ?? 0
+    }
+  };
+  await collector.collect(stepSample);
+}
+
+class InMemoryTelemetryCollector {
+  samples = [];
+  async collect(sample) {
+    this.samples.push(sample);
+  }
+  getSamples() {
+    return [...this.samples];
+  }
+  getSamplesForOperation(operationName) {
+    return this.samples.filter((s) => s.operation.name === operationName);
+  }
+  clear() {
+    this.samples.length = 0;
+  }
 }
+function createInMemoryTelemetryCollector() {
+  return new InMemoryTelemetryCollector;
+}
+var noopTelemetryCollector;
+var init_adapter = __esm(() => {
+  noopTelemetryCollector = {
+    collect: async () => {}
+  };
+});
+
+// src/agent/contract-spec-agent.ts
+var exports_contract_spec_agent = {};
+__export(exports_contract_spec_agent, {
+  ContractSpecAgent: () => ContractSpecAgent
+});
+import {
+  Experimental_Agent as ToolLoopAgent,
+  stepCountIs
+} from "ai";
+import * as z3 from "zod";
+
+class ContractSpecAgent {
+  version = "agent-v1";
+  id;
+  spec;
+  tools;
+  inner;
+  config;
+  instructions;
+  constructor(config, instructions, tools) {
+    this.config = config;
+    this.spec = config.spec;
+    this.id = agentKey(config.spec.meta);
+    this.tools = tools;
+    this.instructions = instructions;
+    this.inner = new ToolLoopAgent({
+      model: config.model,
+      instructions,
+      tools,
+      stopWhen: stepCountIs(config.spec.maxSteps ?? 10),
+      callOptionsSchema: ContractSpecCallOptionsSchema,
+      onStepFinish: async (step) => {
+        await this.handleStepFinish(step);
+      }
+    });
+  }
+  static async create(config) {
+    const instructions = await injectStaticKnowledge(config.spec.instructions, config.spec.knowledge ?? [], config.knowledgeRetriever);
+    const specTools = specToolsToAISDKTools(config.spec.tools, config.toolHandlers, { agentId: agentKey(config.spec.meta) });
+    const knowledgeTool = config.knowledgeRetriever ? createKnowledgeQueryTool(config.knowledgeRetriever, config.spec.knowledge ?? []) : null;
+    const tools = {
+      ...specTools,
+      ...knowledgeTool ? { query_knowledge: knowledgeTool } : {},
+      ...config.additionalTools ?? {}
+    };
+    return new ContractSpecAgent(config, instructions, tools);
+  }
+  async generate(params) {
+    const sessionId = params.options?.sessionId ?? generateSessionId();
+    if (this.config.sessionStore) {
+      const existing = await this.config.sessionStore.get(sessionId);
+      if (!existing) {
+        await this.config.sessionStore.create({
+          sessionId,
+          agentId: this.id,
+          tenantId: params.options?.tenantId,
+          actorId: params.options?.actorId,
+          status: "running",
+          messages: [],
+          steps: [],
+          metadata: params.options?.metadata
+        });
+      }
+    }
+    const prompt = params.systemOverride ? `${this.instructions}
+
+${params.systemOverride}
 
-//#endregion
-export { AgentFactory, createAgentFactory };
-//# sourceMappingURL=agent-factory.js.map
+${params.prompt}` : params.prompt;
+    const result = await this.inner.generate({
+      prompt,
+      abortSignal: params.signal,
+      options: {
+        tenantId: params.options?.tenantId,
+        actorId: params.options?.actorId,
+        sessionId,
+        metadata: params.options?.metadata
+      }
+    });
+    if (this.config.sessionStore) {
+      await this.config.sessionStore.update(sessionId, {
+        status: "completed"
+      });
+    }
+    return {
+      text: result.text,
+      steps: result.steps,
+      toolCalls: result.toolCalls.map((tc) => ({
+        type: "tool-call",
+        toolCallId: tc.toolCallId,
+        toolName: tc.toolName,
+        args: "args" in tc ? tc.args : ("input" in tc) ? tc.input : undefined
+      })),
+      toolResults: result.toolResults.map((tr) => ({
+        type: "tool-result",
+        toolCallId: tr.toolCallId,
+        toolName: tr.toolName,
+        output: tr.output
+      })),
+      finishReason: result.finishReason,
+      usage: result.usage
+    };
+  }
+  async stream(params) {
+    const sessionId = params.options?.sessionId ?? generateSessionId();
+    const prompt = params.systemOverride ? `${this.instructions}
+
+${params.systemOverride}
+
+${params.prompt}` : params.prompt;
+    return this.inner.stream({
+      prompt,
+      abortSignal: params.signal,
+      options: {
+        tenantId: params.options?.tenantId,
+        actorId: params.options?.actorId,
+        sessionId,
+        metadata: params.options?.metadata
+      }
+    });
+  }
+  async handleStepFinish(step) {
+    const sessionId = step.options?.sessionId;
+    if (sessionId && this.config.sessionStore) {
+      await this.config.sessionStore.appendStep(sessionId, step);
+    }
+    if (this.config.telemetryCollector) {
+      await trackAgentStep(this.config.telemetryCollector, this.id, step);
+    }
+  }
+}
+var ContractSpecCallOptionsSchema;
+var init_contract_spec_agent = __esm(() => {
+  init_tool_adapter();
+  init_knowledge_tool();
+  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()
+  });
+});
+
+// src/agent/agent-factory.ts
+init_contract_spec_agent();
+
+class AgentFactory {
+  config;
+  cache = new Map;
+  constructor(config) {
+    this.config = config;
+  }
+  async create(name, version, options) {
+    const spec = this.config.registry.require(name, version);
+    return this.createFromSpec(spec, options);
+  }
+  async createFromSpec(spec, options) {
+    const mergedHandlers = new Map(this.config.toolHandlers);
+    if (options?.toolHandlers) {
+      for (const [key, handler] of options.toolHandlers) {
+        mergedHandlers.set(key, handler);
+      }
+    }
+    const mergedTools = {
+      ...this.config.additionalTools,
+      ...options?.additionalTools
+    };
+    return ContractSpecAgent.create({
+      spec,
+      model: options?.model ?? this.config.defaultModel,
+      toolHandlers: mergedHandlers,
+      knowledgeRetriever: this.config.knowledgeRetriever,
+      sessionStore: this.config.sessionStore,
+      telemetryCollector: this.config.telemetryCollector,
+      additionalTools: mergedTools
+    });
+  }
+  async getOrCreate(name, version) {
+    const spec = this.config.registry.require(name, version);
+    const cacheKey = `${spec.meta.key}.v${spec.meta.version}`;
+    let agent = this.cache.get(cacheKey);
+    if (!agent) {
+      agent = await this.createFromSpec(spec);
+      this.cache.set(cacheKey, agent);
+    }
+    return agent;
+  }
+  clearCache() {
+    this.cache.clear();
+  }
+  listAvailable() {
+    return this.config.registry.listNames();
+  }
+}
+function createAgentFactory(config) {
+  return new AgentFactory(config);
+}
+export {
+  createAgentFactory,
+  AgentFactory
+};