@feilunxitong/arkit 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# 🛡 ARK — Agent Reliability Kit (TypeScript)
+
+> **Trust infrastructure for AI agents.** Now in TypeScript.
+> Stripe-level idempotency × Sentinel circuit breakers × OpenTelemetry tracing × IDE-style validation.
+
+[![Tests](https://img.shields.io/badge/tests-16/16-green)](https://github.com/wzg0911/ark-ts)
+[![npm](https://img.shields.io/badge/npm-ark--trust-blue)](https://www.npmjs.com/package/ark-trust)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
+
+```bash
+npm install ark-trust
+```
+
+```typescript
+import { IdempotencyGuard, CircuitBreaker, autoInit } from 'ark-trust';
+
+// 🛡 Never run duplicate tool calls
+const guard = new IdempotencyGuard();
+const safeCharge = guard.wrap('stripe.charge', (amount: number) => 
+  stripe.charges.create({ amount })
+);
+
+// ⚡ Auto-fallback when APIs fail
+const breaker = new CircuitBreaker('gpt4', 3);
+const result = await breaker.call(
+  () => gpt4.generate(prompt),
+  () => claude.generate(prompt) // falls back automatically
+);
+
+// 🔧 Validate agent output
+const { guard: g, breaker: b, validator: v, score: s } = autoInit();
+// Zero config — auto-detects your agent framework
+```
+
+## What's Included
+
+| Component | Size | Description |
+|-----------|------|-------------|
+| 🛡 IdempotencyGuard | 2.3KB | Prevents duplicate tool calls |
+| ⚡ CircuitBreaker | 2.8KB | Auto-fallback on failure |
+| 🔧 OutputValidator | 1.9KB | Validates agent output |
+| 👁 Trace | 2.7KB | Full execution tracing |
+| 🎮 ReliabilityScore | 3.4KB | Viral reliability badge |
+| 🏆 Achievements | 2.9KB | Gamification system |
+| 📦 SchemaRegistry | 4.2KB | 8 built-in tool schemas |
+| 🖥 Dashboard | 3.3KB | Trust monitor dashboard |
+| 🔍 Auto-detect | 1.4KB | Zero-config framework detection |
+
+**25KB total** · 16/16 tests · Node.js 18+ / TypeScript 5.x
+
+## Quick Demo
+
+```typescript
+import { autoInit, Dashboard, Achievements } from 'ark-trust';
+
+const ark = autoInit();
+const dash = new Dashboard(ark.guard, ark.breaker, ark.validator, ark.score, ark.achievements);
+
+// Simulate agent runs
+ark.score.recordRun({ success: true, intercepts: 2, toolCalls: 10 });
+ark.score.recordRun({ success: true, toolCalls: 15 });
+
+// Get your reliability badge to share
+console.log(ark.score.badgeUrl);  // shields.io badge URL
+console.log(dash.render());       // Trust dashboard
+```
+
+## Python SDK
+
+Also available: [`pip install ark-trust`](https://github.com/wzg0911/ark) (Python 3.9+)
+
+---
+
+**Built with 🧬 gene recombination · MIT License**

package/dist/achievements.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Achievements — 成就系统
+ * Gene source: Gaming achievement systems
+ * Makes reliability fun and shareable.
+ */
+export interface Achievement {
+    id: string;
+    name: string;
+    icon: string;
+    description: string;
+    unlocked: boolean;
+    progress: number;
+    target: number;
+}
+export declare const definitions: {
+    guardian_bronze: {
+        name: string;
+        icon: string;
+        description: string;
+        target: number;
+    };
+    guardian_silver: {
+        name: string;
+        icon: string;
+        description: string;
+        target: number;
+    };
+    guardian_gold: {
+        name: string;
+        icon: string;
+        description: string;
+        target: number;
+    };
+    survivor_bronze: {
+        name: string;
+        icon: string;
+        description: string;
+        target: number;
+    };
+    survivor_silver: {
+        name: string;
+        icon: string;
+        description: string;
+        target: number;
+    };
+    inspector_bronze: {
+        name: string;
+        icon: string;
+        description: string;
+        target: number;
+    };
+    watcher_bronze: {
+        name: string;
+        icon: string;
+        description: string;
+        target: number;
+    };
+    ark_master: {
+        name: string;
+        icon: string;
+        description: string;
+        target: number;
+    };
+};
+export declare class Achievements {
+    private achievements;
+    constructor();
+    /** Update progress for an achievement */
+    update(id: string, progress: number): boolean;
+    private checkArkMaster;
+    get list(): Achievement[];
+    get unlocked(): Achievement[];
+    get summary(): Record<string, {
+        name: string;
+        icon: string;
+        unlocked: boolean;
+        progress: string;
+    }>;
+}

package/dist/achievements.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Achievements — 成就系统
+ * Gene source: Gaming achievement systems
+ * Makes reliability fun and shareable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Achievements = exports.definitions = void 0;
+exports.definitions = {
+    guardian_bronze: { name: 'Guardian Bronze', icon: '🛡', description: 'Intercept 10 duplicate calls', target: 10 },
+    guardian_silver: { name: 'Guardian Silver', icon: '🛡', description: 'Intercept 100 duplicate calls', target: 100 },
+    guardian_gold: { name: 'Guardian Gold', icon: '🛡', description: 'Intercept 1000 duplicate calls', target: 1000 },
+    survivor_bronze: { name: 'Survivor Bronze', icon: '⚡', description: 'Recover from 3 circuit breaks', target: 3 },
+    survivor_silver: { name: 'Survivor Silver', icon: '⚡', description: 'Recover from 10 circuit breaks', target: 10 },
+    inspector_bronze: { name: 'Inspector Bronze', icon: '🔧', description: '99%+ validation pass rate over 100 checks', target: 100 },
+    watcher_bronze: { name: 'Watcher Bronze', icon: '👁', description: 'Trace 1000 spans', target: 1000 },
+    ark_master: { name: 'ARK Master', icon: '🎖', description: 'Unlock all other achievements', target: 7 },
+};
+class Achievements {
+    achievements = new Map();
+    constructor() {
+        for (const [id, def] of Object.entries(exports.definitions)) {
+            this.achievements.set(id, {
+                id,
+                name: def.name,
+                icon: def.icon,
+                description: def.description,
+                unlocked: false,
+                progress: 0,
+                target: def.target,
+            });
+        }
+    }
+    /** Update progress for an achievement */
+    update(id, progress) {
+        const a = this.achievements.get(id);
+        if (!a)
+            return false;
+        a.progress = Math.max(a.progress, progress);
+        if (a.progress >= a.target && !a.unlocked) {
+            a.unlocked = true;
+            this.checkArkMaster();
+            return true; // newly unlocked
+        }
+        return false;
+    }
+    checkArkMaster() {
+        const master = this.achievements.get('ark_master');
+        if (!master || master.unlocked)
+            return;
+        const others = [...this.achievements.values()].filter((a) => a.id !== 'ark_master');
+        if (others.every((a) => a.unlocked)) {
+            master.unlocked = true;
+            master.progress = master.target;
+        }
+    }
+    get list() {
+        return [...this.achievements.values()];
+    }
+    get unlocked() {
+        return this.list.filter((a) => a.unlocked);
+    }
+    get summary() {
+        const result = {};
+        for (const a of this.list) {
+            result[a.id] = {
+                name: a.name,
+                icon: a.icon,
+                unlocked: a.unlocked,
+                progress: `${a.progress}/${a.target}`,
+            };
+        }
+        return result;
+    }
+}
+exports.Achievements = Achievements;

package/dist/auto.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Auto-detection + zero-config bootstrap
+ */
+import { IdempotencyGuard } from './guard.js';
+import { CircuitBreaker } from './breaker.js';
+import { OutputValidator } from './validator.js';
+import { ReliabilityScore } from './score.js';
+import { SchemaRegistry } from './schema-registry.js';
+export declare function detectFrameworks(): string[];
+export interface ARKConfig {
+    frameworks: string[];
+    mode: 'standalone' | 'integrated';
+    guard: IdempotencyGuard;
+    breaker: CircuitBreaker;
+    validator: OutputValidator;
+    score: ReliabilityScore;
+    registry: SchemaRegistry;
+}
+export declare function autoInit(): ARKConfig;

package/dist/auto.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectFrameworks = detectFrameworks;
+exports.autoInit = autoInit;
+/**
+ * Auto-detection + zero-config bootstrap
+ */
+const guard_js_1 = require("./guard.js");
+const breaker_js_1 = require("./breaker.js");
+const validator_js_1 = require("./validator.js");
+const score_js_1 = require("./score.js");
+const schema_registry_js_1 = require("./schema-registry.js");
+function detectFrameworks() {
+    const frameworks = [];
+    const checks = [
+        ['langchain', 'LangChain'],
+        ['openai', 'OpenAI SDK'],
+        ['anthropic', 'Anthropic SDK'],
+        ['@google/generative-ai', 'Gemini SDK'],
+        ['llamaindex', 'LlamaIndex'],
+    ];
+    for (const [mod, name] of checks) {
+        try {
+            require.resolve(mod);
+            frameworks.push(name);
+        }
+        catch { /* not installed */ }
+    }
+    return frameworks;
+}
+function autoInit() {
+    const frameworks = detectFrameworks();
+    return {
+        frameworks,
+        mode: frameworks.length > 0 ? 'integrated' : 'standalone',
+        guard: new guard_js_1.IdempotencyGuard(),
+        breaker: new breaker_js_1.CircuitBreaker('auto-detect'),
+        validator: new validator_js_1.OutputValidator(),
+        score: new score_js_1.ReliabilityScore(),
+        registry: new schema_registry_js_1.SchemaRegistry(),
+    };
+}

package/dist/benchmarks.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Benchmarks — 性能基准测试套件
+ * Performance benchmarking for core ARK components.
+ */
+export interface BenchmarkMetrics {
+    name: string;
+    iterations: number;
+    totalMs: number;
+    avgMs: number;
+    p50Ms: number;
+    p99Ms: number;
+    stdMs: number;
+    throughputOps: number;
+}
+export declare class Benchmarks {
+    iterations: number;
+    results: BenchmarkMetrics[];
+    constructor(iterations?: number);
+    private measure;
+    benchIdempotencyKeyGen(): BenchmarkMetrics;
+    benchIdempotencyCheckHit(): BenchmarkMetrics;
+    benchIdempotencyCheckMiss(): BenchmarkMetrics;
+    benchCircuitBreakerClosed(): BenchmarkMetrics;
+    benchValidatorValid(): BenchmarkMetrics;
+    benchValidatorNone(): BenchmarkMetrics;
+    runAll(): BenchmarkMetrics[];
+    toJSON(): string;
+    summary(): Record<string, unknown>;
+}

package/dist/benchmarks.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Benchmarks — 性能基准测试套件
+ * Performance benchmarking for core ARK components.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Benchmarks = void 0;
+const guard_js_1 = require("./guard.js");
+const breaker_js_1 = require("./breaker.js");
+const validator_js_1 = require("./validator.js");
+function sortedPercentile(sorted, p) {
+    const idx = Math.floor(sorted.length * p);
+    return sorted[Math.min(idx, sorted.length - 1)];
+}
+function stdDev(values, mean) {
+    if (values.length <= 1)
+        return 0;
+    const sqDiffs = values.map((v) => (v - mean) ** 2);
+    return Math.sqrt(sqDiffs.reduce((a, b) => a + b, 0) / (values.length - 1));
+}
+class Benchmarks {
+    iterations;
+    results = [];
+    constructor(iterations = 10_000) {
+        this.iterations = iterations;
+    }
+    measure(name, fn) {
+        const timings = [];
+        for (let i = 0; i < this.iterations; i++) {
+            const start = performance.now();
+            fn();
+            const elapsed = performance.now() - start;
+            timings.push(elapsed);
+        }
+        const sorted = [...timings].sort((a, b) => a - b);
+        const total = timings.reduce((a, b) => a + b, 0);
+        const avg = total / timings.length;
+        return {
+            name,
+            iterations: this.iterations,
+            totalMs: total,
+            avgMs: avg,
+            p50Ms: sortedPercentile(sorted, 0.5),
+            p99Ms: sortedPercentile(sorted, 0.99),
+            stdMs: stdDev(timings, avg),
+            throughputOps: 1000 / avg,
+        };
+    }
+    benchIdempotencyKeyGen() {
+        const guard = new guard_js_1.IdempotencyGuard();
+        const args = { tool: 'send_email', to: 'test@ark.dev', body: 'hello'.repeat(10) };
+        return this.measure('IdempotencyGuard.key()', () => {
+            guard.key('send_email', args);
+        });
+    }
+    benchIdempotencyCheckHit() {
+        const guard = new guard_js_1.IdempotencyGuard();
+        const key = guard.key('send_payment', {
+            amount: 100,
+            currency: 'USD',
+        });
+        // Manually record so check returns hit
+        const record = {
+            idempotencyKey: key,
+            toolName: 'send_payment',
+            argsHash: 'abc123',
+            result: { status: 'ok' },
+        };
+        // Access internal cache via guard's record method
+        guard.record(key, record);
+        return this.measure('IdempotencyGuard.check() [hit]', () => {
+            guard.check(key);
+        });
+    }
+    benchIdempotencyCheckMiss() {
+        const guard = new guard_js_1.IdempotencyGuard();
+        const key = guard.key('new_tool', { foo: 'bar' });
+        return this.measure('IdempotencyGuard.check() [miss]', () => {
+            guard.check(key);
+        });
+    }
+    benchCircuitBreakerClosed() {
+        const cb = new breaker_js_1.CircuitBreaker('bench');
+        return this.measure('CircuitBreaker.call() [closed]', () => {
+            cb.callSync(() => 'ok');
+        });
+    }
+    benchValidatorValid() {
+        const v = new validator_js_1.OutputValidator();
+        return this.measure('OutputValidator.validateShape() [valid]', () => {
+            v.validateShape({ status: 'ok', data: 'test' }, { status: 'string', data: 'string' });
+        });
+    }
+    benchValidatorNone() {
+        const v = new validator_js_1.OutputValidator();
+        return this.measure('OutputValidator.validateShape() [none]', () => {
+            v.validateShape(null, {});
+        });
+    }
+    runAll() {
+        const benches = [
+            ['Idempotency Key Gen', () => this.benchIdempotencyKeyGen()],
+            ['Idempotency Check [hit]', () => this.benchIdempotencyCheckHit()],
+            ['Idempotency Check [miss]', () => this.benchIdempotencyCheckMiss()],
+            ['CircuitBreaker [closed]', () => this.benchCircuitBreakerClosed()],
+            ['Validator [valid]', () => this.benchValidatorValid()],
+            ['Validator [none]', () => this.benchValidatorNone()],
+        ];
+        console.log('\n' + '='.repeat(60));
+        console.log(`  ARK Benchmarks (${this.iterations.toLocaleString()} iterations each)`);
+        console.log('='.repeat(60));
+        console.log(`${'Benchmark'.padEnd(35)} ${'avg(μs)'.padStart(10)} ${'p50(μs)'.padStart(10)} ${'p99(μs)'.padStart(10)} ${'ops/s'.padStart(12)}`);
+        console.log(`${'-'.repeat(35)} ${'-'.repeat(10)} ${'-'.repeat(10)} ${'-'.repeat(10)} ${'-'.repeat(12)}`);
+        for (const [, benchFn] of benches) {
+            const result = benchFn();
+            this.results.push(result);
+            const μs = 1000; // convert ms → μs for display
+            console.log(`${result.name.padEnd(35)} ` +
+                `${(result.avgMs * μs).toFixed(1).padStart(10)} ` +
+                `${(result.p50Ms * μs).toFixed(1).padStart(10)} ` +
+                `${(result.p99Ms * μs).toFixed(1).padStart(10)} ` +
+                `${Math.round(result.throughputOps).toLocaleString().padStart(12)}`);
+        }
+        console.log('='.repeat(60) + '\n');
+        return this.results;
+    }
+    toJSON() {
+        return JSON.stringify(this.results, null, 2);
+    }
+    summary() {
+        if (this.results.length === 0)
+            this.runAll();
+        const fastest = this.results.reduce((a, b) => (a.avgMs < b.avgMs ? a : b));
+        const slowest = this.results.reduce((a, b) => (a.avgMs > b.avgMs ? a : b));
+        return {
+            version: '0.4.1-dev',
+            iterations: this.iterations,
+            results: this.results,
+            slowest: slowest.name,
+            fastest: fastest.name,
+            totalTimeMs: this.results.reduce((a, b) => a + b.totalMs, 0),
+        };
+    }
+}
+exports.Benchmarks = Benchmarks;

package/dist/breaker.d.ts

@@ -0,0 +1,36 @@
+/**
+ * CircuitBreaker — 熔断控制器
+ * Gene source: Sentinel microservice resilience
+ * Auto-meltdown → safe fallback
+ */
+export declare class CircuitOpenError extends Error {
+    constructor(name: string);
+}
+type CircuitState = 'closed' | 'open' | 'half-open';
+interface BreakerStats {
+    state: CircuitState;
+    failures: number;
+    totalCalls: number;
+    totalFailures: number;
+    reliability: string;
+}
+export declare class CircuitBreaker {
+    private name;
+    private failureThreshold;
+    private recoveryMs;
+    private halfOpenMaxCalls;
+    state: CircuitState;
+    private failures;
+    private totalCalls;
+    private totalFailures;
+    private lastFailure;
+    private openedAt;
+    constructor(name: string, failureThreshold?: number, recoveryMs?: number, halfOpenMaxCalls?: number);
+    call<T>(primary: () => Promise<T> | T, fallback?: () => Promise<T> | T): Promise<T>;
+    callSync<T>(primary: () => T, fallback?: () => T): T;
+    private onSuccess;
+    private onFailure;
+    reset(): void;
+    get stats(): BreakerStats;
+}
+export {};

package/dist/breaker.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * CircuitBreaker — 熔断控制器
+ * Gene source: Sentinel microservice resilience
+ * Auto-meltdown → safe fallback
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreaker = exports.CircuitOpenError = void 0;
+class CircuitOpenError extends Error {
+    constructor(name) {
+        super(`Circuit ${name} is OPEN — refusing call`);
+        this.name = 'CircuitOpenError';
+    }
+}
+exports.CircuitOpenError = CircuitOpenError;
+class CircuitBreaker {
+    name;
+    failureThreshold;
+    recoveryMs;
+    halfOpenMaxCalls;
+    state = 'closed';
+    failures = 0;
+    totalCalls = 0;
+    totalFailures = 0;
+    lastFailure = 0;
+    openedAt = 0;
+    constructor(name, failureThreshold = 3, recoveryMs = 30_000, halfOpenMaxCalls = 1) {
+        this.name = name;
+        this.failureThreshold = failureThreshold;
+        this.recoveryMs = recoveryMs;
+        this.halfOpenMaxCalls = halfOpenMaxCalls;
+    }
+    async call(primary, fallback) {
+        this.totalCalls++;
+        if (this.state === 'open') {
+            if (Date.now() - this.openedAt > this.recoveryMs) {
+                this.state = 'half-open';
+            }
+            else if (fallback) {
+                return fallback();
+            }
+            else {
+                throw new CircuitOpenError(this.name);
+            }
+        }
+        try {
+            const result = await primary();
+            this.onSuccess();
+            return result;
+        }
+        catch (err) {
+            this.onFailure();
+            if (fallback)
+                return fallback();
+            throw err;
+        }
+    }
+    callSync(primary, fallback) {
+        this.totalCalls++;
+        if (this.state === 'open') {
+            if (Date.now() - this.openedAt > this.recoveryMs) {
+                this.state = 'half-open';
+            }
+            else if (fallback) {
+                return fallback();
+            }
+            else {
+                throw new CircuitOpenError(this.name);
+            }
+        }
+        try {
+            const result = primary();
+            this.onSuccess();
+            return result;
+        }
+        catch (err) {
+            this.onFailure();
+            if (fallback)
+                return fallback();
+            throw err;
+        }
+    }
+    onSuccess() {
+        if (this.state === 'half-open')
+            this.state = 'closed';
+        this.failures = 0;
+    }
+    onFailure() {
+        this.failures++;
+        this.totalFailures++;
+        this.lastFailure = Date.now();
+        if (this.failures >= this.failureThreshold) {
+            this.state = 'open';
+            this.openedAt = Date.now();
+        }
+    }
+    reset() {
+        this.state = 'closed';
+        this.failures = 0;
+        this.totalCalls = 0;
+        this.totalFailures = 0;
+    }
+    get stats() {
+        return {
+            state: this.state,
+            failures: this.failures,
+            totalCalls: this.totalCalls,
+            totalFailures: this.totalFailures,
+            reliability: this.totalCalls > 0
+                ? `${((1 - this.totalFailures / this.totalCalls) * 100).toFixed(1)}%`
+                : '100%',
+        };
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;

package/dist/dashboard.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Dashboard — 信任仪表盘
+ * Real-time trust monitoring for AI agents.
+ */
+import { IdempotencyGuard } from './guard.js';
+import { CircuitBreaker } from './breaker.js';
+import { OutputValidator } from './validator.js';
+import { ReliabilityScore } from './score.js';
+import { Achievements } from './achievements.js';
+export interface TrustMonitor {
+    guardPasses: number;
+    guardIntercepts: number;
+    guardSaveRate: string;
+    breakerState: string;
+    breakerReliability: string;
+    validatorPassed: number;
+    validatorBlocked: number;
+    validatorBlockRate: string;
+    score: number;
+    grade: string;
+}
+export declare class Dashboard {
+    private guard;
+    private breaker;
+    private validator;
+    private score;
+    private achievements;
+    constructor(guard: IdempotencyGuard, breaker: CircuitBreaker, validator: OutputValidator, score: ReliabilityScore, achievements: Achievements);
+    get trustMonitor(): TrustMonitor;
+    /** Render a text dashboard */
+    render(): string;
+}