@agentcontract/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,259 @@
+import { z } from 'zod';
+
+/** Zod schemas for the AgentContract specification. */
+
+declare const Clause: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    text: z.ZodString;
+    judge: z.ZodDefault<z.ZodEnum<{
+        deterministic: "deterministic";
+        llm: "llm";
+    }>>;
+    description: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>]>;
+type Clause = z.infer<typeof Clause>;
+declare const Assertion: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        llm: "llm";
+        pattern: "pattern";
+        schema: "schema";
+        cost: "cost";
+        latency: "latency";
+        custom: "custom";
+    }>;
+    description: z.ZodDefault<z.ZodString>;
+    must_not_match: z.ZodOptional<z.ZodString>;
+    must_match: z.ZodOptional<z.ZodString>;
+    schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    prompt: z.ZodOptional<z.ZodString>;
+    pass_when: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    max_usd: z.ZodOptional<z.ZodNumber>;
+    max_ms: z.ZodOptional<z.ZodNumber>;
+    plugin: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+type Assertion = z.infer<typeof Assertion>;
+declare const Limits: z.ZodDefault<z.ZodObject<{
+    max_tokens: z.ZodOptional<z.ZodNumber>;
+    max_input_tokens: z.ZodOptional<z.ZodNumber>;
+    max_latency_ms: z.ZodOptional<z.ZodNumber>;
+    max_cost_usd: z.ZodOptional<z.ZodNumber>;
+    max_tool_calls: z.ZodOptional<z.ZodNumber>;
+    max_steps: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>>;
+type Limits = z.infer<typeof Limits>;
+declare const OnViolation: z.ZodDefault<z.ZodObject<{
+    default: z.ZodDefault<z.ZodEnum<{
+        warn: "warn";
+        block: "block";
+        rollback: "rollback";
+        halt_and_alert: "halt_and_alert";
+    }>>;
+}, z.core.$catchall<z.ZodString>>>;
+type OnViolation = z.infer<typeof OnViolation>;
+declare const Contract: z.ZodObject<{
+    agent: z.ZodString;
+    'spec-version': z.ZodString;
+    version: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    author: z.ZodDefault<z.ZodString>;
+    created: z.ZodDefault<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    extends: z.ZodOptional<z.ZodString>;
+    must: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        text: z.ZodString;
+        judge: z.ZodDefault<z.ZodEnum<{
+            deterministic: "deterministic";
+            llm: "llm";
+        }>>;
+        description: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>]>>>;
+    must_not: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        text: z.ZodString;
+        judge: z.ZodDefault<z.ZodEnum<{
+            deterministic: "deterministic";
+            llm: "llm";
+        }>>;
+        description: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>]>>>;
+    can: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    requires: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        text: z.ZodString;
+        judge: z.ZodDefault<z.ZodEnum<{
+            deterministic: "deterministic";
+            llm: "llm";
+        }>>;
+        on_fail: z.ZodDefault<z.ZodEnum<{
+            warn: "warn";
+            block: "block";
+        }>>;
+        description: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>]>>>;
+    ensures: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        text: z.ZodString;
+        judge: z.ZodDefault<z.ZodEnum<{
+            deterministic: "deterministic";
+            llm: "llm";
+        }>>;
+        description: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>]>>>;
+    invariant: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        text: z.ZodString;
+        judge: z.ZodDefault<z.ZodEnum<{
+            deterministic: "deterministic";
+            llm: "llm";
+        }>>;
+        description: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>]>>>;
+    assert: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            llm: "llm";
+            pattern: "pattern";
+            schema: "schema";
+            cost: "cost";
+            latency: "latency";
+            custom: "custom";
+        }>;
+        description: z.ZodDefault<z.ZodString>;
+        must_not_match: z.ZodOptional<z.ZodString>;
+        must_match: z.ZodOptional<z.ZodString>;
+        schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        prompt: z.ZodOptional<z.ZodString>;
+        pass_when: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        max_usd: z.ZodOptional<z.ZodNumber>;
+        max_ms: z.ZodOptional<z.ZodNumber>;
+        plugin: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    limits: z.ZodDefault<z.ZodObject<{
+        max_tokens: z.ZodOptional<z.ZodNumber>;
+        max_input_tokens: z.ZodOptional<z.ZodNumber>;
+        max_latency_ms: z.ZodOptional<z.ZodNumber>;
+        max_cost_usd: z.ZodOptional<z.ZodNumber>;
+        max_tool_calls: z.ZodOptional<z.ZodNumber>;
+        max_steps: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    on_violation: z.ZodDefault<z.ZodObject<{
+        default: z.ZodDefault<z.ZodEnum<{
+            warn: "warn";
+            block: "block";
+            rollback: "rollback";
+            halt_and_alert: "halt_and_alert";
+        }>>;
+    }, z.core.$catchall<z.ZodString>>>;
+}, z.core.$strip>;
+type Contract = z.infer<typeof Contract>;
+
+/** Contract loading and validation. */
+
+declare function loadContract(filePath: string): Contract;
+
+/** enforce() — wraps any agent function with contract validation. */
+
+interface EnforceOptions {
+    audit?: boolean;
+    auditPath?: string;
+    costFn?: (result: unknown) => number;
+}
+type AgentFn<T extends string | Promise<string>> = (input: string) => T;
+declare function enforce<T extends string | Promise<string>>(contract: Contract, fn: AgentFn<T>, options?: EnforceOptions): AgentFn<Promise<string>>;
+
+/** Base validator types. */
+interface RunContext {
+    input: string;
+    output: string;
+    durationMs: number;
+    costUsd: number;
+    toolCalls: unknown[];
+    steps: number;
+    metadata: Record<string, unknown>;
+}
+declare function makeContext(partial: Partial<RunContext> & {
+    input: string;
+    output: string;
+}): RunContext;
+interface ValidationResult {
+    passed: boolean;
+    clauseName: string;
+    clauseText: string;
+    clauseType: string;
+    judge: 'deterministic' | 'llm';
+    details: string;
+}
+interface Validator {
+    validate(context: RunContext): ValidationResult | Promise<ValidationResult>;
+}
+
+/** Contract validation runner — orchestrates all validators per spec §6.1. */
+
+interface ViolationRecord {
+    clauseType: string;
+    clauseName: string;
+    clauseText: string;
+    severity: string;
+    actionTaken: string;
+    judge: string;
+    details: string;
+}
+interface RunResult {
+    passed: boolean;
+    runId: string;
+    agent: string;
+    contractVersion: string;
+    violations: ViolationRecord[];
+    context: RunContext;
+    outcome: 'pass' | 'violation';
+}
+declare class ContractRunner {
+    private contract;
+    constructor(contract: Contract);
+    run(context: RunContext, runId?: string): Promise<RunResult>;
+    private _checkLimits;
+    private _runAssertion;
+    private _evaluateClause;
+}
+
+/** Audit trail — tamper-evident JSONL entries for every run. */
+
+declare class AuditWriter {
+    private logPath;
+    constructor(logPath?: string);
+    write(result: RunResult, contractPath?: string): Record<string, unknown>;
+    private _buildEntry;
+}
+
+/** AgentContract exceptions. */
+declare class ContractError extends Error {
+    constructor(message: string);
+}
+declare class ContractLoadError extends ContractError {
+    constructor(message: string);
+}
+declare class ContractPreconditionError extends ContractError {
+    clause: string;
+    details: string;
+    constructor(clause: string, details?: string);
+}
+declare class ContractViolation extends ContractError {
+    violations: Array<{
+        clause_type: string;
+        clause_text: string;
+        action_taken: string;
+    }>;
+    constructor(violations: Array<{
+        clause_type: string;
+        clause_text: string;
+        action_taken: string;
+    }>);
+}
+
+/**
+ * @agentcontract/core — Behavioral contracts for AI agents.
+ * TypeScript reference implementation of the AgentContract specification.
+ * https://github.com/agentcontract/spec
+ */
+declare const VERSION = "0.1.0";
+declare const SPEC_VERSION = "0.1.0";
+
+export { Assertion, AuditWriter, Clause, Contract, ContractError, ContractLoadError, ContractPreconditionError, ContractRunner, ContractViolation, type EnforceOptions, Limits, OnViolation, type RunContext, type RunResult, SPEC_VERSION, VERSION, type ValidationResult, type Validator, type ViolationRecord, enforce, loadContract, makeContext };