@contractspec/lib.ai-agent 1.57.0 → 1.59.0

package/dist/node/telemetry/index.js

@@ -0,0 +1,86 @@
+import { createRequire } from "node:module";
+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
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// 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/telemetry/index.ts
+init_adapter();
+export {
+  trackAgentStep,
+  noopTelemetryCollector,
+  createInMemoryTelemetryCollector,
+  InMemoryTelemetryCollector
+};

package/dist/node/tools/index.js

@@ -0,0 +1,345 @@
+import { createRequire } from "node:module";
+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
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// 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/tools/mcp-client.ts
+import { experimental_createMCPClient } from "@ai-sdk/mcp";
+import { Experimental_StdioMCPTransport as StdioClientTransport } from "@ai-sdk/mcp/mcp-stdio";
+async function mcpServerToTools(config) {
+  const transport = new StdioClientTransport({
+    command: config.command,
+    args: config.args,
+    env: config.env
+  });
+  const client = await experimental_createMCPClient({ transport });
+  const tools = await client.tools();
+  return {
+    tools,
+    cleanup: () => client.close()
+  };
+}
+async function createMcpToolsets(configs) {
+  const results = await Promise.all(configs.map(mcpServerToTools));
+  const combinedTools = {};
+  for (const result of results) {
+    Object.assign(combinedTools, result.tools);
+  }
+  return {
+    tools: combinedTools,
+    cleanup: async () => {
+      await Promise.all(results.map((r) => r.cleanup()));
+    }
+  };
+}
+
+// src/tools/mcp-server.ts
+init_json_schema_to_zod();
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z3 from "zod";
+function agentToMcpServer(agent, spec) {
+  const server = new McpServer({
+    name: spec.meta.key,
+    version: `${spec.meta.version}`
+  });
+  server.registerTool(spec.meta.key, {
+    description: spec.description ?? `Interact with ${spec.meta.key} agent`,
+    inputSchema: z3.object({
+      message: z3.string().describe("The message or query to send to the agent"),
+      sessionId: z3.string().optional().describe("Optional session ID to continue a conversation")
+    })
+  }, async (args) => {
+    const { message, sessionId } = args;
+    const result = await agent.generate({
+      prompt: message,
+      options: { sessionId }
+    });
+    return {
+      content: [
+        {
+          type: "text",
+          text: result.text
+        }
+      ]
+    };
+  });
+  for (const toolConfig of spec.tools) {
+    const inputSchema = toolConfig.schema ? jsonSchemaToZodSafe(toolConfig.schema) : z3.object({});
+    server.registerTool(`${spec.meta.key}.${toolConfig.name}`, {
+      description: toolConfig.description ?? `Execute ${toolConfig.name} tool`,
+      inputSchema
+    }, async (args) => {
+      const result = await agent.generate({
+        prompt: `Execute the ${toolConfig.name} tool with the following arguments: ${JSON.stringify(args)}`
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: result.text
+          }
+        ]
+      };
+    });
+  }
+  return server;
+}
+function createAgentMcpServer(config) {
+  return agentToMcpServer(config.agent, config.spec);
+}
+
+// src/tools/index.ts
+init_tool_adapter();
+init_knowledge_tool();
+export {
+  specToolsToAISDKTools,
+  specToolToAISDKTool,
+  mcpServerToTools,
+  createToolHandler,
+  createMcpToolsets,
+  createKnowledgeQueryTool,
+  createAgentMcpServer,
+  buildToolHandlers,
+  agentToMcpServer
+};

package/dist/node/tools/knowledge-tool.js

@@ -0,0 +1,74 @@
+import { createRequire } from "node:module";
+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
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/tools/knowledge-tool.ts
+import { tool } from "ai";
+import * as z 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 tool({
+    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: z.object({
+      query: z.string().describe("The question or search query to find relevant information"),
+      spaceKey: z.enum(optionalSpaces).optional().describe("Specific knowledge space to query. If omitted, searches all available spaces."),
+      topK: z.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 = () => {};
+init_knowledge_tool();
+
+export {
+  createKnowledgeQueryTool
+};

package/dist/node/tools/mcp-client.js

@@ -0,0 +1,47 @@
+import { createRequire } from "node:module";
+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
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/tools/mcp-client.ts
+import { experimental_createMCPClient } from "@ai-sdk/mcp";
+import { Experimental_StdioMCPTransport as StdioClientTransport } from "@ai-sdk/mcp/mcp-stdio";
+async function mcpServerToTools(config) {
+  const transport = new StdioClientTransport({
+    command: config.command,
+    args: config.args,
+    env: config.env
+  });
+  const client = await experimental_createMCPClient({ transport });
+  const tools = await client.tools();
+  return {
+    tools,
+    cleanup: () => client.close()
+  };
+}
+async function createMcpToolsets(configs) {
+  const results = await Promise.all(configs.map(mcpServerToTools));
+  const combinedTools = {};
+  for (const result of results) {
+    Object.assign(combinedTools, result.tools);
+  }
+  return {
+    tools: combinedTools,
+    cleanup: async () => {
+      await Promise.all(results.map((r) => r.cleanup()));
+    }
+  };
+}
+export {
+  mcpServerToTools,
+  createMcpToolsets
+};