TypeScript contracts for AI tools

tool-call-contract

Define each tool once with Zod, bootstrap a starter workflow, normalize selected raw provider traces into curated regression fixtures, validate calls, redact sensitive data, and keep reviewable artifacts in sync.

Install View source

tool-call-contract init
Init: 3 created, 0 updated, 0 skipped.

tool-call-contract check
No findings.

tool-call-contract generate
Artifacts: 8 created, 0 updated

tool-call-contract artifacts --check
Generated artifacts are fresh.

tool-call-contract normalize --suite raw --format openai-responses --out-dir captures/regression --check
Normalization check: openai-responses, 0 changed, 1 unchanged.

tool-call-contract validate --suite regression
Validation results: 12 valid, 0 invalid.

tool-call-contract redact --check --suite regression
All captures already redacted.

One source of truth

From contract to confidence

Bootstrap

Start with init, then replace the sample contract with real tools.

Define

Write named tool contracts with descriptions and Zod input schemas.

Normalize

Convert selected OpenAI, Vercel AI SDK, LangChain, or custom traces into fixtures.

Regress

Validate, redact, and generate Vitest tests from committed capture suites.

Generated output

Commit-friendly artifacts for agent work

The CLI writes deterministic files that can live in source control. CI can run artifacts --check as a focused freshness gate, while check remains the broader contract and schema gate. Raw production telemetry belongs in logs or observability systems; commit only reviewed, redacted regression fixtures.

capturescurated fixtures from selected raw traces

fixturesvalid and invalid normalized calls

schemasOpenAI-compatible tool definitions

docsMarkdown references from executable contracts

testsVitest regression coverage from capture suites

manifeststable hashes for freshness checks

Get started

Install, initialize, verify

npm install -D tool-call-contract zod
npx tool-call-contract init

import { z } from "zod";
import { defineConfig, defineToolContract } from "tool-call-contract";

const createIssue = defineToolContract({
  name: "create_issue",
  description: "Create an engineering issue.",
  input: z.object({
    title: z.string().min(1),
    body: z.string().min(1),
    priority: z.enum(["low", "high"]).default("low"),
  }),
});

export default defineConfig({
  contracts: [createIssue],
  captures: {
    raw: ["captures/raw/*.json"],
    regression: ["captures/regression/*.json"],
  },
  redaction: {
    paths: ["arguments.email", "metadata.authorization"],
  },
});

npx tool-call-contract check
npx tool-call-contract artifacts --check
npx tool-call-contract normalize --suite raw --format openai-responses --out-dir captures/regression --check
npx tool-call-contract redact --check --suite regression
npx tool-call-contract validate --suite regression
npx tool-call-contract generate-tests --suite regression --dry-run