@agentcontract/core 0.1.0

package/dist/cli.js

@@ -0,0 +1,577 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// node_modules/tsup/assets/cjs_shims.js
+var init_cjs_shims = __esm({
+  "node_modules/tsup/assets/cjs_shims.js"() {
+    "use strict";
+  }
+});
+
+// src/audit.ts
+var init_audit = __esm({
+  "src/audit.ts"() {
+    "use strict";
+    init_cjs_shims();
+  }
+});
+
+// src/cli.ts
+init_cjs_shims();
+var import_fs2 = require("fs");
+var import_commander = require("commander");
+
+// src/loader.ts
+init_cjs_shims();
+var import_fs = require("fs");
+var import_path = require("path");
+var import_js_yaml = __toESM(require("js-yaml"));
+
+// src/models.ts
+init_cjs_shims();
+var import_zod = require("zod");
+var JudgeType = import_zod.z.enum(["deterministic", "llm"]).default("deterministic");
+var ViolationAction = import_zod.z.enum(["warn", "block", "rollback", "halt_and_alert"]).default("block");
+var AssertionType = import_zod.z.enum(["pattern", "schema", "llm", "cost", "latency", "custom"]);
+var ClauseObject = import_zod.z.object({
+  text: import_zod.z.string().min(1),
+  judge: JudgeType,
+  description: import_zod.z.string().default("")
+});
+var Clause = import_zod.z.union([import_zod.z.string().min(1), ClauseObject]);
+var PreconditionClause = import_zod.z.union([
+  import_zod.z.string().min(1),
+  import_zod.z.object({
+    text: import_zod.z.string().min(1),
+    judge: JudgeType,
+    on_fail: import_zod.z.enum(["block", "warn"]).default("block"),
+    description: import_zod.z.string().default("")
+  })
+]);
+var Assertion = import_zod.z.object({
+  name: import_zod.z.string().regex(/^[a-z][a-z0-9_]*$/),
+  type: AssertionType,
+  description: import_zod.z.string().default(""),
+  // pattern
+  must_not_match: import_zod.z.string().optional(),
+  must_match: import_zod.z.string().optional(),
+  // schema
+  schema: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional(),
+  // llm
+  prompt: import_zod.z.string().optional(),
+  pass_when: import_zod.z.string().optional(),
+  model: import_zod.z.string().optional(),
+  // cost
+  max_usd: import_zod.z.number().nonnegative().optional(),
+  // latency
+  max_ms: import_zod.z.number().int().positive().optional(),
+  // custom
+  plugin: import_zod.z.string().optional()
+}).passthrough();
+var Limits = import_zod.z.object({
+  max_tokens: import_zod.z.number().int().positive().optional(),
+  max_input_tokens: import_zod.z.number().int().positive().optional(),
+  max_latency_ms: import_zod.z.number().int().positive().optional(),
+  max_cost_usd: import_zod.z.number().nonnegative().optional(),
+  max_tool_calls: import_zod.z.number().int().nonnegative().optional(),
+  max_steps: import_zod.z.number().int().positive().optional()
+}).default({});
+var OnViolation = import_zod.z.object({
+  default: ViolationAction
+}).catchall(import_zod.z.string()).default({ default: "block" });
+var Contract = import_zod.z.object({
+  agent: import_zod.z.string().min(1),
+  "spec-version": import_zod.z.string(),
+  version: import_zod.z.string(),
+  description: import_zod.z.string().default(""),
+  author: import_zod.z.string().default(""),
+  created: import_zod.z.string().default(""),
+  tags: import_zod.z.array(import_zod.z.string()).default([]),
+  extends: import_zod.z.string().optional(),
+  must: import_zod.z.array(Clause).default([]),
+  must_not: import_zod.z.array(Clause).default([]),
+  can: import_zod.z.array(import_zod.z.string()).default([]),
+  requires: import_zod.z.array(PreconditionClause).default([]),
+  ensures: import_zod.z.array(Clause).default([]),
+  invariant: import_zod.z.array(Clause).default([]),
+  assert: import_zod.z.array(Assertion).default([]),
+  limits: Limits,
+  on_violation: OnViolation
+});
+function getClauseText(clause) {
+  return typeof clause === "string" ? clause : clause.text;
+}
+function getClauseJudge(clause) {
+  return typeof clause === "string" ? "deterministic" : clause.judge;
+}
+function getViolationAction(onViolation, name) {
+  return onViolation[name] ?? onViolation.default;
+}
+
+// src/exceptions.ts
+init_cjs_shims();
+var ContractError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ContractError";
+  }
+};
+var ContractLoadError = class extends ContractError {
+  constructor(message) {
+    super(message);
+    this.name = "ContractLoadError";
+  }
+};
+
+// src/loader.ts
+function loadContract(filePath) {
+  const ext = (0, import_path.extname)(filePath).toLowerCase();
+  if (![".yaml", ".yml", ".json"].includes(ext)) {
+    throw new ContractLoadError(
+      `Unsupported file format: ${ext}. Use .contract.yaml or .contract.json`
+    );
+  }
+  let raw;
+  try {
+    raw = (0, import_fs.readFileSync)(filePath, "utf-8");
+  } catch {
+    throw new ContractLoadError(`Contract file not found: ${filePath}`);
+  }
+  let data;
+  try {
+    data = ext === ".json" ? JSON.parse(raw) : import_js_yaml.default.load(raw);
+  } catch (e) {
+    throw new ContractLoadError(`Failed to parse contract file: ${e}`);
+  }
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    throw new ContractLoadError("Contract file must be a YAML/JSON object at the root level.");
+  }
+  const result = Contract.safeParse(data);
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n");
+    throw new ContractLoadError(`Contract schema validation failed:
+${issues}`);
+  }
+  return result.data;
+}
+
+// src/runner.ts
+init_cjs_shims();
+var import_crypto = require("crypto");
+
+// src/validators/pattern.ts
+init_cjs_shims();
+var PatternValidator = class {
+  constructor(name, mustNotMatch, mustMatch, description = "") {
+    this.name = name;
+    this.mustNotMatch = mustNotMatch;
+    this.mustMatch = mustMatch;
+    this.description = description;
+  }
+  validate(context) {
+    const output = context.output;
+    if (this.mustNotMatch) {
+      const re = new RegExp(this.mustNotMatch);
+      const match = re.exec(output);
+      if (match) {
+        return {
+          passed: false,
+          clauseName: this.name,
+          clauseText: this.description || `must_not_match: ${this.mustNotMatch}`,
+          clauseType: "assert",
+          judge: "deterministic",
+          details: `Forbidden pattern found: '${match[0].slice(0, 50)}'`
+        };
+      }
+    }
+    if (this.mustMatch) {
+      const re = new RegExp(this.mustMatch);
+      if (!re.test(output)) {
+        return {
+          passed: false,
+          clauseName: this.name,
+          clauseText: this.description || `must_match: ${this.mustMatch}`,
+          clauseType: "assert",
+          judge: "deterministic",
+          details: "Required pattern not found in output."
+        };
+      }
+    }
+    return {
+      passed: true,
+      clauseName: this.name,
+      clauseText: this.description || this.name,
+      clauseType: "assert",
+      judge: "deterministic",
+      details: ""
+    };
+  }
+};
+
+// src/validators/cost.ts
+init_cjs_shims();
+var CostValidator = class {
+  constructor(name, maxUsd, description = "") {
+    this.name = name;
+    this.maxUsd = maxUsd;
+    this.description = description;
+  }
+  validate(context) {
+    const passed = context.costUsd <= this.maxUsd;
+    return {
+      passed,
+      clauseName: this.name,
+      clauseText: this.description || `cost must not exceed $${this.maxUsd.toFixed(4)} USD`,
+      clauseType: "assert",
+      judge: "deterministic",
+      details: passed ? "" : `Run cost $${context.costUsd.toFixed(4)} exceeded limit $${this.maxUsd.toFixed(4)}`
+    };
+  }
+};
+
+// src/validators/latency.ts
+init_cjs_shims();
+var LatencyValidator = class {
+  constructor(name, maxMs, description = "") {
+    this.name = name;
+    this.maxMs = maxMs;
+    this.description = description;
+  }
+  validate(context) {
+    const passed = context.durationMs <= this.maxMs;
+    return {
+      passed,
+      clauseName: this.name,
+      clauseText: this.description || `latency must not exceed ${this.maxMs}ms`,
+      clauseType: "assert",
+      judge: "deterministic",
+      details: passed ? "" : `Run took ${Math.round(context.durationMs)}ms, exceeded limit of ${this.maxMs}ms`
+    };
+  }
+};
+
+// src/validators/llm.ts
+init_cjs_shims();
+var DEFAULT_JUDGE_MODEL = "claude-haiku-4-5-20251001";
+var JUDGE_SYSTEM_PROMPT = "You are an impartial compliance judge evaluating an AI agent's behavior against a specific contract clause. Evaluate objectively based only on the evidence provided. Your response must be a single word: YES or NO, followed optionally by one sentence of reasoning.";
+var LLMValidator = class {
+  constructor(name, clauseText, clauseType, prompt, passWhen = "NO", model = DEFAULT_JUDGE_MODEL, description = "") {
+    this.name = name;
+    this.clauseText = clauseText;
+    this.clauseType = clauseType;
+    this.prompt = prompt;
+    this.passWhen = passWhen;
+    this.model = model;
+    this.description = description;
+  }
+  async validate(context) {
+    let Anthropic;
+    try {
+      const mod = await import("@anthropic-ai/sdk");
+      Anthropic = mod.default;
+    } catch {
+      return {
+        passed: false,
+        clauseName: this.name,
+        clauseText: this.clauseText,
+        clauseType: this.clauseType,
+        judge: "llm",
+        details: "@anthropic-ai/sdk not installed. Run: npm install @anthropic-ai/sdk"
+      };
+    }
+    const client = new Anthropic();
+    const userPrompt = this.prompt ? `${this.prompt}
+
+--- AGENT INPUT ---
+${context.input}
+
+--- AGENT OUTPUT ---
+${context.output}` : `Contract clause: "${this.clauseText}"
+
+--- AGENT INPUT ---
+${context.input}
+
+--- AGENT OUTPUT ---
+${context.output}
+
+Does the agent's output satisfy the contract clause? Answer YES if satisfied, NO if violated.`;
+    try {
+      const response = await client.messages.create({
+        model: this.model,
+        max_tokens: 64,
+        system: JUDGE_SYSTEM_PROMPT,
+        messages: [{ role: "user", content: userPrompt }]
+      });
+      const raw = response.content[0].type === "text" ? response.content[0].text.trim() : "";
+      const firstWord = raw.split(/\s+/)[0]?.toUpperCase().replace(/[.,;:]$/, "") ?? "";
+      const passed = firstWord === this.passWhen.toUpperCase();
+      const reasoning = raw.slice(firstWord.length).trim();
+      return {
+        passed,
+        clauseName: this.name,
+        clauseText: this.clauseText,
+        clauseType: this.clauseType,
+        judge: "llm",
+        details: reasoning
+      };
+    } catch (e) {
+      return {
+        passed: false,
+        clauseName: this.name,
+        clauseText: this.clauseText,
+        clauseType: this.clauseType,
+        judge: "llm",
+        details: `Judge model error: ${e}`
+      };
+    }
+  }
+};
+
+// src/runner.ts
+var ContractRunner = class {
+  constructor(contract) {
+    this.contract = contract;
+  }
+  async run(context, runId) {
+    const rid = runId ?? (0, import_crypto.randomUUID)();
+    const violations = [];
+    const c = this.contract;
+    const ov = c.on_violation;
+    violations.push(...this._checkLimits(context));
+    for (const assertion of c.assert) {
+      const result = await this._runAssertion(assertion, context);
+      if (!result.passed) {
+        const action = getViolationAction(ov, assertion.name);
+        violations.push({
+          clauseType: "assert",
+          clauseName: assertion.name,
+          clauseText: result.clauseText,
+          severity: action,
+          actionTaken: action,
+          judge: result.judge,
+          details: result.details
+        });
+      }
+    }
+    for (const clause of c.must) {
+      const text = getClauseText(clause);
+      const judge = getClauseJudge(clause);
+      const result = await this._evaluateClause(text, "must", judge, context);
+      if (!result.passed) {
+        const action = getViolationAction(ov, `must:${text.slice(0, 30)}`);
+        violations.push({ clauseType: "must", clauseName: `must:${text.slice(0, 30)}`, clauseText: text, severity: action, actionTaken: action, judge, details: result.details });
+      }
+    }
+    for (const clause of c.must_not) {
+      const text = getClauseText(clause);
+      const judge = getClauseJudge(clause);
+      const result = await this._evaluateClause(text, "must_not", judge, context);
+      if (!result.passed) {
+        const action = getViolationAction(ov, `must_not:${text.slice(0, 30)}`);
+        violations.push({ clauseType: "must_not", clauseName: `must_not:${text.slice(0, 30)}`, clauseText: text, severity: action, actionTaken: action, judge, details: result.details });
+      }
+    }
+    for (const clause of c.ensures) {
+      const text = getClauseText(clause);
+      const judge = getClauseJudge(clause);
+      const result = await this._evaluateClause(text, "ensures", judge, context);
+      if (!result.passed) {
+        const action = getViolationAction(ov, `ensures:${text.slice(0, 30)}`);
+        violations.push({ clauseType: "ensures", clauseName: `ensures:${text.slice(0, 30)}`, clauseText: text, severity: action, actionTaken: action, judge, details: result.details });
+      }
+    }
+    const blocking = ["block", "rollback", "halt_and_alert"];
+    const passed = !violations.some((v) => blocking.includes(v.actionTaken));
+    return { passed, runId: rid, agent: c.agent, contractVersion: c.version, violations, context, outcome: passed ? "pass" : "violation" };
+  }
+  _checkLimits(context) {
+    const records = [];
+    const limits = this.contract.limits;
+    const ov = this.contract.on_violation;
+    if (limits.max_latency_ms != null) {
+      const r = new LatencyValidator("max_latency_ms", limits.max_latency_ms).validate(context);
+      if (!r.passed) {
+        const action = getViolationAction(ov, "max_latency_ms");
+        records.push({ clauseType: "limits", clauseName: "max_latency_ms", clauseText: r.clauseText, severity: action, actionTaken: action, judge: "deterministic", details: r.details });
+      }
+    }
+    if (limits.max_cost_usd != null) {
+      const r = new CostValidator("max_cost_usd", limits.max_cost_usd).validate(context);
+      if (!r.passed) {
+        const action = getViolationAction(ov, "max_cost_usd");
+        records.push({ clauseType: "limits", clauseName: "max_cost_usd", clauseText: r.clauseText, severity: action, actionTaken: action, judge: "deterministic", details: r.details });
+      }
+    }
+    if (limits.max_tokens != null && context.output) {
+      const estimated = Math.floor(context.output.length / 4);
+      if (estimated > limits.max_tokens) {
+        const action = getViolationAction(ov, "max_tokens");
+        records.push({ clauseType: "limits", clauseName: "max_tokens", clauseText: `output must not exceed ${limits.max_tokens} tokens`, severity: action, actionTaken: action, judge: "deterministic", details: `Estimated ${estimated} tokens exceeds limit of ${limits.max_tokens}` });
+      }
+    }
+    return records;
+  }
+  async _runAssertion(assertion, context) {
+    switch (assertion.type) {
+      case "pattern":
+        return new PatternValidator(assertion.name, assertion.must_not_match, assertion.must_match, assertion.description).validate(context);
+      case "cost":
+        return new CostValidator(assertion.name, assertion.max_usd ?? 0, assertion.description).validate(context);
+      case "latency":
+        return new LatencyValidator(assertion.name, assertion.max_ms ?? 0, assertion.description).validate(context);
+      case "llm":
+        return new LLMValidator(assertion.name, assertion.description || assertion.name, "assert", assertion.prompt, assertion.pass_when ?? "NO", assertion.model).validate(context);
+      default:
+        return { passed: false, clauseName: assertion.name, clauseText: assertion.description || assertion.name, clauseType: "assert", judge: "deterministic", details: `Unsupported assertion type: ${assertion.type}` };
+    }
+  }
+  async _evaluateClause(text, clauseType, judge, context) {
+    if (judge === "llm") {
+      return new LLMValidator(`${clauseType}:${text.slice(0, 30)}`, text, clauseType).validate(context);
+    }
+    return { passed: true, clauseName: `${clauseType}:${text.slice(0, 30)}`, clauseText: text, clauseType, judge: "deterministic", details: "" };
+  }
+};
+
+// src/validators/base.ts
+init_cjs_shims();
+function makeContext(partial) {
+  return {
+    durationMs: 0,
+    costUsd: 0,
+    toolCalls: [],
+    steps: 0,
+    metadata: {},
+    ...partial
+  };
+}
+
+// src/index.ts
+init_cjs_shims();
+
+// src/enforce.ts
+init_cjs_shims();
+
+// src/index.ts
+init_audit();
+var VERSION = "0.1.0";
+
+// src/cli.ts
+import_commander.program.name("agentcontract").description("AgentContract \u2014 behavioral contracts for AI agents").version(VERSION);
+import_commander.program.command("check <contract>").description("Validate a contract file against the AgentContract schema").action((contractFile) => {
+  try {
+    const contract = loadContract(contractFile);
+    console.log("\u2713 Contract is valid");
+    console.log(`  Agent:    ${contract.agent}`);
+    console.log(`  Version:  ${contract.version}`);
+    console.log(`  Spec:     ${contract["spec-version"]}`);
+    console.log(`  Clauses:  ${contract.must.length} must, ${contract.must_not.length} must_not, ${contract.assert.length} assertions`);
+  } catch (e) {
+    console.error(`\u2717 Invalid contract: ${e instanceof Error ? e.message : e}`);
+    process.exit(1);
+  }
+});
+import_commander.program.command("validate <contract> <runLog>").description("Validate a JSONL run log against a contract").option("--format <format>", "Output format: text or json", "text").action(async (contractFile, runLogFile, opts) => {
+  let contract;
+  try {
+    contract = loadContract(contractFile);
+  } catch (e) {
+    console.error(`\u2717 ${e instanceof Error ? e.message : e}`);
+    process.exit(1);
+  }
+  const runner = new ContractRunner(contract);
+  const lines = (0, import_fs2.readFileSync)(runLogFile, "utf-8").split("\n").filter(Boolean);
+  const results = [];
+  let failed = 0;
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+      const ctx = makeContext({
+        input: entry.input ?? "",
+        output: entry.output ?? "",
+        durationMs: entry.duration_ms ?? 0,
+        costUsd: entry.cost_usd ?? 0
+      });
+      const result = await runner.run(ctx);
+      results.push(result);
+      if (!result.passed) failed++;
+    } catch {
+    }
+  }
+  if (opts.format === "json") {
+    console.log(JSON.stringify(results.map((r) => ({
+      run_id: r.runId,
+      outcome: r.outcome,
+      violations: r.violations
+    })), null, 2));
+  } else {
+    const total = results.length;
+    const passed = total - failed;
+    console.log(`
+AgentContract Validation Report`);
+    console.log(`Contract: ${contractFile}  |  Runs: ${total}  |  Passed: ${passed}  |  Failed: ${failed}`);
+    for (const r of results) {
+      if (r.violations.length > 0) {
+        console.log(`
+  Run ${r.runId.slice(0, 8)}... \u2014 VIOLATION`);
+        for (const v of r.violations) {
+          const icon = v.actionTaken !== "warn" ? "\u2717" : "\u26A0";
+          console.log(`    ${icon} [${v.actionTaken.toUpperCase()}] ${v.clauseType}: "${v.clauseText}"`);
+          if (v.details) console.log(`      ${v.details}`);
+        }
+      }
+    }
+  }
+  process.exit(failed > 0 ? 1 : 0);
+});
+import_commander.program.command("info <contract>").description("Display a summary of a contract file").action((contractFile) => {
+  try {
+    const c = loadContract(contractFile);
+    console.log(`
+AgentContract \u2014 ${c.agent} v${c.version}`);
+    console.log(`  Spec version : ${c["spec-version"]}`);
+    if (c.description) console.log(`  Description  : ${c.description}`);
+    if (c.author) console.log(`  Author       : ${c.author}`);
+    if (c.tags.length) console.log(`  Tags         : ${c.tags.join(", ")}`);
+    console.log(`
+  Clauses:`);
+    console.log(`    must         : ${c.must.length}`);
+    console.log(`    must_not     : ${c.must_not.length}`);
+    console.log(`    can          : ${c.can.length}`);
+    console.log(`    requires     : ${c.requires.length}`);
+    console.log(`    ensures      : ${c.ensures.length}`);
+    console.log(`    assert       : ${c.assert.length}`);
+    console.log(`
+  Violation default: ${c.on_violation.default}`);
+  } catch (e) {
+    console.error(`\u2717 ${e instanceof Error ? e.message : e}`);
+    process.exit(1);
+  }
+});
+import_commander.program.parse();
+//# sourceMappingURL=cli.js.map