@contractspec/lib.ai-agent 1.57.0 → 1.59.0

package/dist/node/approval/index.js

@@ -0,0 +1,129 @@
+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/approval/workflow.ts
+import { randomUUID } from "node:crypto";
+
+class InMemoryApprovalStore {
+  items = new Map;
+  async create(request) {
+    this.items.set(request.id, request);
+  }
+  async get(id) {
+    return this.items.get(id) ?? null;
+  }
+  async getByToolCallId(toolCallId) {
+    for (const request of this.items.values()) {
+      if (request.toolCallId === toolCallId) {
+        return request;
+      }
+    }
+    return null;
+  }
+  async update(id, updates) {
+    const existing = this.items.get(id);
+    if (existing) {
+      this.items.set(id, { ...existing, ...updates });
+    }
+  }
+  async list(options) {
+    let results = [...this.items.values()];
+    if (options?.status) {
+      results = results.filter((r) => r.status === options.status);
+    }
+    if (options?.agentId) {
+      results = results.filter((r) => r.agentId === options.agentId);
+    }
+    if (options?.tenantId) {
+      results = results.filter((r) => r.tenantId === options.tenantId);
+    }
+    return results.sort((a, b) => b.requestedAt.getTime() - a.requestedAt.getTime());
+  }
+  clear() {
+    this.items.clear();
+  }
+}
+
+class ApprovalWorkflow {
+  store;
+  constructor(store = new InMemoryApprovalStore) {
+    this.store = store;
+  }
+  async requestApproval(params) {
+    const request = {
+      id: randomUUID(),
+      sessionId: params.sessionId,
+      agentId: params.agentId,
+      tenantId: params.tenantId,
+      toolName: params.toolName,
+      toolCallId: params.toolCallId,
+      toolArgs: params.toolArgs,
+      reason: params.reason,
+      requestedAt: new Date,
+      status: "pending",
+      payload: params.payload
+    };
+    await this.store.create(request);
+    return request;
+  }
+  async requestApprovalFromToolCall(toolCall, context) {
+    return this.requestApproval({
+      sessionId: context.sessionId,
+      agentId: context.agentId,
+      tenantId: context.tenantId,
+      toolName: toolCall.toolName,
+      toolCallId: toolCall.toolCallId,
+      toolArgs: toolCall.args,
+      reason: context.reason ?? `Tool "${toolCall.toolName}" requires approval`
+    });
+  }
+  async approve(id, reviewer, notes) {
+    await this.store.update(id, {
+      status: "approved",
+      reviewer,
+      resolvedAt: new Date,
+      notes
+    });
+  }
+  async reject(id, reviewer, notes) {
+    await this.store.update(id, {
+      status: "rejected",
+      reviewer,
+      resolvedAt: new Date,
+      notes
+    });
+  }
+  async getStatus(toolCallId) {
+    const request = await this.store.getByToolCallId(toolCallId);
+    return request?.status ?? null;
+  }
+  async isApproved(toolCallId) {
+    const status = await this.getStatus(toolCallId);
+    return status === "approved";
+  }
+  async listPending(options) {
+    return this.store.list({ ...options, status: "pending" });
+  }
+  async get(id) {
+    return this.store.get(id);
+  }
+}
+function createApprovalWorkflow(store) {
+  return new ApprovalWorkflow(store);
+}
+export {
+  createApprovalWorkflow,
+  InMemoryApprovalStore,
+  ApprovalWorkflow
+};

package/dist/node/approval/workflow.js

@@ -0,0 +1,129 @@
+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/approval/workflow.ts
+import { randomUUID } from "node:crypto";
+
+class InMemoryApprovalStore {
+  items = new Map;
+  async create(request) {
+    this.items.set(request.id, request);
+  }
+  async get(id) {
+    return this.items.get(id) ?? null;
+  }
+  async getByToolCallId(toolCallId) {
+    for (const request of this.items.values()) {
+      if (request.toolCallId === toolCallId) {
+        return request;
+      }
+    }
+    return null;
+  }
+  async update(id, updates) {
+    const existing = this.items.get(id);
+    if (existing) {
+      this.items.set(id, { ...existing, ...updates });
+    }
+  }
+  async list(options) {
+    let results = [...this.items.values()];
+    if (options?.status) {
+      results = results.filter((r) => r.status === options.status);
+    }
+    if (options?.agentId) {
+      results = results.filter((r) => r.agentId === options.agentId);
+    }
+    if (options?.tenantId) {
+      results = results.filter((r) => r.tenantId === options.tenantId);
+    }
+    return results.sort((a, b) => b.requestedAt.getTime() - a.requestedAt.getTime());
+  }
+  clear() {
+    this.items.clear();
+  }
+}
+
+class ApprovalWorkflow {
+  store;
+  constructor(store = new InMemoryApprovalStore) {
+    this.store = store;
+  }
+  async requestApproval(params) {
+    const request = {
+      id: randomUUID(),
+      sessionId: params.sessionId,
+      agentId: params.agentId,
+      tenantId: params.tenantId,
+      toolName: params.toolName,
+      toolCallId: params.toolCallId,
+      toolArgs: params.toolArgs,
+      reason: params.reason,
+      requestedAt: new Date,
+      status: "pending",
+      payload: params.payload
+    };
+    await this.store.create(request);
+    return request;
+  }
+  async requestApprovalFromToolCall(toolCall, context) {
+    return this.requestApproval({
+      sessionId: context.sessionId,
+      agentId: context.agentId,
+      tenantId: context.tenantId,
+      toolName: toolCall.toolName,
+      toolCallId: toolCall.toolCallId,
+      toolArgs: toolCall.args,
+      reason: context.reason ?? `Tool "${toolCall.toolName}" requires approval`
+    });
+  }
+  async approve(id, reviewer, notes) {
+    await this.store.update(id, {
+      status: "approved",
+      reviewer,
+      resolvedAt: new Date,
+      notes
+    });
+  }
+  async reject(id, reviewer, notes) {
+    await this.store.update(id, {
+      status: "rejected",
+      reviewer,
+      resolvedAt: new Date,
+      notes
+    });
+  }
+  async getStatus(toolCallId) {
+    const request = await this.store.getByToolCallId(toolCallId);
+    return request?.status ?? null;
+  }
+  async isApproved(toolCallId) {
+    const status = await this.getStatus(toolCallId);
+    return status === "approved";
+  }
+  async listPending(options) {
+    return this.store.list({ ...options, status: "pending" });
+  }
+  async get(id) {
+    return this.store.get(id);
+  }
+}
+function createApprovalWorkflow(store) {
+  return new ApprovalWorkflow(store);
+}
+export {
+  createApprovalWorkflow,
+  InMemoryApprovalStore,
+  ApprovalWorkflow
+};

package/dist/node/exporters/claude-agent-exporter.js

@@ -0,0 +1,265 @@
+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/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/exporters/claude-agent-exporter.ts
+class ClaudeAgentExporter {
+  format = "claude-agent";
+  export(spec, options = {}) {
+    const tools = this.exportTools(spec);
+    const config = this.buildConfig(spec, tools, options);
+    const claudeMd = options.generateClaudeMd ? this.generateClaudeMd(spec, options) : undefined;
+    return {
+      config,
+      claudeMd,
+      tools,
+      exportedAt: new Date,
+      sourceSpec: agentKey(spec.meta)
+    };
+  }
+  exportMany(specs, options = {}) {
+    return specs.map((spec) => this.export(spec, options));
+  }
+  validate(spec) {
+    const errors = [];
+    if (!spec.meta?.key) {
+      errors.push("Spec must have a meta.key");
+    }
+    if (!spec.instructions) {
+      errors.push("Spec must have instructions");
+    }
+    if (!spec.tools || spec.tools.length === 0) {
+      errors.push("Spec must have at least one tool");
+    }
+    for (const tool of spec.tools ?? []) {
+      if (!tool.name) {
+        errors.push("All tools must have a name");
+      }
+      if (!tool.description && !tool.name) {
+        errors.push(`Tool must have a description or name`);
+      }
+    }
+    return { valid: errors.length === 0, errors };
+  }
+  buildConfig(spec, tools, options) {
+    const config = {
+      model: options.model ?? "claude-sonnet-4-20250514",
+      system: this.buildSystemPrompt(spec, options),
+      tools,
+      max_turns: spec.maxSteps ?? 10
+    };
+    if (options.computerUse) {
+      config.computer_use = true;
+    }
+    if (options.extendedThinking) {
+      config.extended_thinking = true;
+    }
+    if (options.mcpServers && options.mcpServers.length > 0) {
+      config.mcp_servers = options.mcpServers;
+    }
+    return config;
+  }
+  buildSystemPrompt(spec, options) {
+    const parts = [];
+    parts.push(spec.instructions);
+    if (spec.knowledge && spec.knowledge.length > 0) {
+      parts.push("");
+      parts.push("## Knowledge Sources");
+      for (const k of spec.knowledge) {
+        if (k.instructions) {
+          parts.push(`- ${k.key}: ${k.instructions}`);
+        }
+      }
+    }
+    if (spec.policy) {
+      parts.push("");
+      parts.push("## Policy");
+      if (spec.policy.confidence?.min) {
+        parts.push(`- Minimum confidence: ${spec.policy.confidence.min}`);
+      }
+      if (spec.policy.escalation) {
+        parts.push("- Escalation policy is configured");
+      }
+    }
+    if (options.metadata) {
+      parts.push("");
+      parts.push("## Additional Context");
+      for (const [key, value] of Object.entries(options.metadata)) {
+        parts.push(`- ${key}: ${String(value)}`);
+      }
+    }
+    return parts.join(`
+`);
+  }
+  exportTools(spec) {
+    return spec.tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description ?? `Execute ${tool.name}`,
+      input_schema: this.normalizeSchema(tool.schema),
+      requires_confirmation: tool.requiresApproval ?? !tool.automationSafe
+    }));
+  }
+  normalizeSchema(schema) {
+    if (!schema) {
+      return { type: "object" };
+    }
+    if (schema.type === "object") {
+      return {
+        type: "object",
+        properties: schema.properties,
+        required: schema.required
+      };
+    }
+    return {
+      type: "object",
+      properties: { value: schema },
+      required: ["value"]
+    };
+  }
+  generateClaudeMd(spec, options) {
+    const lines = [];
+    lines.push("# Agent Configuration");
+    lines.push("");
+    if (spec.description) {
+      lines.push(`> ${spec.description}`);
+      lines.push("");
+    }
+    lines.push("## Metadata");
+    lines.push("");
+    lines.push(`- **Name**: ${spec.meta.key}`);
+    lines.push(`- **Version**: ${spec.meta.version}`);
+    if (spec.meta.owners && spec.meta.owners.length > 0) {
+      lines.push(`- **Owners**: ${spec.meta.owners.join(", ")}`);
+    }
+    if (options.model) {
+      lines.push(`- **Model**: ${options.model}`);
+    }
+    lines.push("");
+    lines.push("## Instructions");
+    lines.push("");
+    lines.push(spec.instructions);
+    lines.push("");
+    if (spec.tools.length > 0) {
+      lines.push("## Available Tools");
+      lines.push("");
+      for (const tool of spec.tools) {
+        const flags = [];
+        if (tool.requiresApproval) {
+          flags.push("requires approval");
+        }
+        if (tool.automationSafe === false) {
+          flags.push("not automation safe");
+        }
+        const flagStr = flags.length > 0 ? ` (${flags.join(", ")})` : "";
+        lines.push(`### ${tool.name}${flagStr}`);
+        lines.push("");
+        if (tool.description) {
+          lines.push(tool.description);
+          lines.push("");
+        }
+        if (tool.schema) {
+          lines.push("**Parameters:**");
+          lines.push("```json");
+          lines.push(JSON.stringify(tool.schema, null, 2));
+          lines.push("```");
+          lines.push("");
+        }
+      }
+    }
+    if (spec.knowledge && spec.knowledge.length > 0) {
+      lines.push("## Knowledge Sources");
+      lines.push("");
+      for (const k of spec.knowledge) {
+        const required = k.required ? "(required)" : "(optional)";
+        lines.push(`- **${k.key}** ${required}`);
+        if (k.instructions) {
+          lines.push(`  - ${k.instructions}`);
+        }
+      }
+      lines.push("");
+    }
+    if (spec.policy) {
+      lines.push("## Policy");
+      lines.push("");
+      if (spec.policy.confidence?.min) {
+        lines.push(`- Minimum confidence: ${spec.policy.confidence.min}`);
+      }
+      if (spec.policy.escalation) {
+        lines.push("- Escalation policy configured");
+      }
+      if (spec.policy.flags && spec.policy.flags.length > 0) {
+        lines.push(`- Feature flags: ${spec.policy.flags.join(", ")}`);
+      }
+      lines.push("");
+    }
+    if (options.mcpServers && options.mcpServers.length > 0) {
+      lines.push("## MCP Servers");
+      lines.push("");
+      for (const server of options.mcpServers) {
+        lines.push(`- **${server.name}**: \`${server.command}${server.args ? " " + server.args.join(" ") : ""}\``);
+      }
+      lines.push("");
+    }
+    lines.push("---");
+    lines.push("");
+    lines.push(`*Generated from ContractSpec: ${agentKey(spec.meta)}*`);
+    return lines.join(`
+`);
+  }
+}
+function exportToClaudeAgent(spec, options) {
+  const exporter = new ClaudeAgentExporter;
+  return exporter.export(spec, options);
+}
+function generateClaudeMd(spec, options) {
+  const exporter = new ClaudeAgentExporter;
+  const result = exporter.export(spec, { ...options, generateClaudeMd: true });
+  return result.claudeMd ?? "";
+}
+function validateForClaudeAgent(spec) {
+  const exporter = new ClaudeAgentExporter;
+  return exporter.validate(spec);
+}
+export {
+  validateForClaudeAgent,
+  generateClaudeMd,
+  exportToClaudeAgent,
+  ClaudeAgentExporter
+};