@feilunxitong/arkit 0.1.0

package/dist/score.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ReliabilityScore — 可靠性评分引擎
+ * Gene source: Gaming achievement systems
+ * Viral badge + social sharing built-in.
+ */
+interface ScoreRecord {
+    timestamp: number;
+    score: number;
+    grade: string;
+    intercepts: number;
+    blocks: number;
+}
+export declare class ReliabilityScore {
+    totalRuns: number;
+    successfulRuns: number;
+    duplicateIntercepts: number;
+    outputBlocks: number;
+    circuitTrips: number;
+    totalToolCalls: number;
+    totalToolFailures: number;
+    history: ScoreRecord[];
+    get score(): number;
+    get grade(): string;
+    get badgeUrl(): string;
+    get markdownBadge(): string;
+    get shareText(): string;
+    recordRun(opts: {
+        success: boolean;
+        intercepts?: number;
+        blocks?: number;
+        toolCalls?: number;
+        toolFailures?: number;
+        circuitTrips?: number;
+    }): void;
+    get summary(): {
+        score: number;
+        grade: string;
+        totalRuns: number;
+        successRate: string;
+        totalIntercepts: number;
+        totalBlocks: number;
+        toolReliability: string;
+        badge: string;
+        share: string;
+    };
+}
+export {};

package/dist/score.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * ReliabilityScore — 可靠性评分引擎
+ * Gene source: Gaming achievement systems
+ * Viral badge + social sharing built-in.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReliabilityScore = void 0;
+class ReliabilityScore {
+    totalRuns = 0;
+    successfulRuns = 0;
+    duplicateIntercepts = 0;
+    outputBlocks = 0;
+    circuitTrips = 0;
+    totalToolCalls = 0;
+    totalToolFailures = 0;
+    history = [];
+    get score() {
+        if (this.totalRuns === 0)
+            return 0;
+        const base = (this.successfulRuns / this.totalRuns) * 100;
+        const penalty = (this.duplicateIntercepts + this.outputBlocks) * 0.3;
+        const failPenalty = (this.totalToolFailures / Math.max(this.totalToolCalls, 1)) * 15;
+        return Math.max(0, Math.min(100, +(base - penalty - failPenalty).toFixed(1)));
+    }
+    get grade() {
+        const s = this.score;
+        if (s >= 97)
+            return 'S+ 🏆';
+        if (s >= 93)
+            return 'S';
+        if (s >= 85)
+            return 'A+';
+        if (s >= 80)
+            return 'A';
+        if (s >= 70)
+            return 'B+';
+        if (s >= 60)
+            return 'B';
+        if (s >= 50)
+            return 'C';
+        return 'D';
+    }
+    get badgeUrl() {
+        const colors = {
+            'S+ 🏆': 'FFD700', S: '00C853', 'A+': '4CAF50',
+            A: '8BC34A', 'B+': 'FFC107', B: 'FF9800',
+            C: 'FF5722', D: 'F44336',
+        };
+        const color = colors[this.grade] || '999';
+        const label = this.grade.replace(/ /g, '_');
+        return `https://img.shields.io/badge/ARK_Score-${this.score}%25_${label}-${color}?style=for-the-badge&logo=shield`;
+    }
+    get markdownBadge() {
+        return `[![ARK Score](${this.badgeUrl})](https://github.com/wzg0911/ark)`;
+    }
+    get shareText() {
+        const templates = {
+            'S+ 🏆': `🔥 ${this.score}% reliability! ARK caught ${this.duplicateIntercepts} dupes. S+ tier agent! ${this.markdownBadge}`,
+            S: `⚡ Agent reliability: ${this.score}% (S rank). ARK = trust for AI. ${this.markdownBadge}`,
+            'A+': `📈 ${this.score}% (A+). Getting closer to perfect. ${this.markdownBadge}`,
+        };
+        return templates[this.grade] ||
+            `🛡 Agent trust: ${this.score}%. ${this.duplicateIntercepts} safe intercepts. ${this.markdownBadge}`;
+    }
+    recordRun(opts) {
+        this.totalRuns++;
+        if (opts.success)
+            this.successfulRuns++;
+        this.duplicateIntercepts += opts.intercepts ?? 0;
+        this.outputBlocks += opts.blocks ?? 0;
+        this.totalToolCalls += opts.toolCalls ?? 0;
+        this.totalToolFailures += opts.toolFailures ?? 0;
+        this.circuitTrips += opts.circuitTrips ?? 0;
+        this.history.push({
+            timestamp: Date.now(),
+            score: this.score,
+            grade: this.grade,
+            intercepts: opts.intercepts ?? 0,
+            blocks: opts.blocks ?? 0,
+        });
+    }
+    get summary() {
+        return {
+            score: this.score,
+            grade: this.grade,
+            totalRuns: this.totalRuns,
+            successRate: `${((this.successfulRuns / Math.max(this.totalRuns, 1)) * 100).toFixed(1)}%`,
+            totalIntercepts: this.duplicateIntercepts,
+            totalBlocks: this.outputBlocks,
+            toolReliability: `${((1 - this.totalToolFailures / Math.max(this.totalToolCalls, 1)) * 100).toFixed(1)}%`,
+            badge: this.markdownBadge,
+            share: this.shareText,
+        };
+    }
+}
+exports.ReliabilityScore = ReliabilityScore;

package/dist/stateful-breaker.d.ts

@@ -0,0 +1,45 @@
+/**
+ * StatefulBreaker — 持久化熔断器
+ * Gene source: EverOS (⭐7,225) + MemBrain
+ * Circuit breaker state persisted to disk — survives process restarts.
+ */
+export declare class CircuitOpenError extends Error {
+    constructor(name: string, waitSeconds: number);
+}
+interface StatefulBreakerStats {
+    name: string;
+    state: string;
+    failureCount: number;
+    successCount: number;
+    totalCalls: number;
+    totalFailures: number;
+    recoveryTimeout: number;
+    persistPath: string;
+    reliability: string;
+}
+export declare class StatefulBreaker {
+    name: string;
+    private failureThreshold;
+    private recoveryTimeout;
+    private halfOpenMax;
+    private autoPersist;
+    private state;
+    private failureCount;
+    private lastFailure;
+    private successCount;
+    private halfOpenTries;
+    private totalCalls;
+    private totalFailures;
+    private persistPath;
+    constructor(name: string, failureThreshold?: number, recoveryTimeout?: number, halfOpenMax?: number, persistPath?: string, autoPersist?: boolean);
+    private defaultState;
+    private loadState;
+    private saveState;
+    call<T>(primary: () => Promise<T> | T, fallback?: () => Promise<T> | T): Promise<T>;
+    private onSuccess;
+    private onFailure;
+    reset(): void;
+    inspectPersistence(): Record<string, unknown>;
+    get stats(): StatefulBreakerStats;
+}
+export {};

package/dist/stateful-breaker.js

@@ -0,0 +1,231 @@
+"use strict";
+/**
+ * StatefulBreaker — 持久化熔断器
+ * Gene source: EverOS (⭐7,225) + MemBrain
+ * Circuit breaker state persisted to disk — survives process restarts.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StatefulBreaker = exports.CircuitOpenError = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+class CircuitOpenError extends Error {
+    constructor(name, waitSeconds) {
+        super(`Circuit [${name}] OPEN. Cooldown: ${Math.max(0, waitSeconds).toFixed(0)}s`);
+        this.name = 'CircuitOpenError';
+    }
+}
+exports.CircuitOpenError = CircuitOpenError;
+class StatefulBreaker {
+    name;
+    failureThreshold;
+    recoveryTimeout;
+    halfOpenMax;
+    autoPersist;
+    state = 'closed';
+    failureCount = 0;
+    lastFailure = 0;
+    successCount = 0;
+    halfOpenTries = 0;
+    totalCalls = 0;
+    totalFailures = 0;
+    persistPath;
+    constructor(name, failureThreshold = 3, recoveryTimeout = 30, halfOpenMax = 2, persistPath, autoPersist = true) {
+        this.name = name;
+        this.failureThreshold = failureThreshold;
+        this.recoveryTimeout = recoveryTimeout;
+        this.halfOpenMax = halfOpenMax;
+        this.autoPersist = autoPersist;
+        if (persistPath) {
+            this.persistPath = persistPath;
+        }
+        else {
+            const arkDir = path.join(os.homedir(), '.ark', 'state');
+            fs.mkdirSync(arkDir, { recursive: true });
+            this.persistPath = path.join(arkDir, `breaker_${name}.json`);
+        }
+        this.loadState();
+        this.saveState();
+    }
+    defaultState() {
+        return {
+            name: this.name,
+            state: 'closed',
+            failureCount: 0,
+            lastFailure: 0,
+            successCount: 0,
+            halfOpenTries: 0,
+            totalCalls: 0,
+            totalFailures: 0,
+            updatedAt: Date.now(),
+        };
+    }
+    loadState() {
+        try {
+            if (fs.existsSync(this.persistPath)) {
+                const data = JSON.parse(fs.readFileSync(this.persistPath, 'utf-8'));
+                this.state = data.state ?? 'closed';
+                this.failureCount = data.failureCount ?? 0;
+                this.lastFailure = data.lastFailure ?? 0;
+                this.successCount = data.successCount ?? 0;
+                this.halfOpenTries = data.halfOpenTries ?? 0;
+                this.totalCalls = data.totalCalls ?? 0;
+                this.totalFailures = data.totalFailures ?? 0;
+            }
+        }
+        catch {
+            // Corrupted file → use defaults
+        }
+    }
+    saveState() {
+        if (!this.autoPersist)
+            return;
+        const snapshot = {
+            name: this.name,
+            state: this.state,
+            failureCount: this.failureCount,
+            lastFailure: this.lastFailure,
+            successCount: this.successCount,
+            halfOpenTries: this.halfOpenTries,
+            totalCalls: this.totalCalls,
+            totalFailures: this.totalFailures,
+            updatedAt: Date.now(),
+        };
+        try {
+            fs.writeFileSync(this.persistPath, JSON.stringify(snapshot, null, 2));
+        }
+        catch {
+            // Silently skip write errors
+        }
+    }
+    async call(primary, fallback) {
+        this.totalCalls++;
+        if (this.state === 'open') {
+            if (Date.now() / 1000 - this.lastFailure > this.recoveryTimeout) {
+                this.state = 'half-open';
+                this.halfOpenTries = 0;
+                this.saveState();
+            }
+            else {
+                const remaining = this.recoveryTimeout - (Date.now() / 1000 - this.lastFailure);
+                if (fallback)
+                    return fallback();
+                throw new CircuitOpenError(this.name, remaining);
+            }
+        }
+        if (this.state === 'half-open') {
+            this.halfOpenTries++;
+            if (this.halfOpenTries > this.halfOpenMax) {
+                this.state = 'open';
+                this.saveState();
+                if (fallback)
+                    return fallback();
+                throw new CircuitOpenError(this.name, this.recoveryTimeout);
+            }
+        }
+        try {
+            const result = await primary();
+            this.onSuccess();
+            this.saveState();
+            return result;
+        }
+        catch (err) {
+            this.onFailure();
+            this.totalFailures++;
+            this.saveState();
+            if (fallback)
+                return fallback();
+            throw err;
+        }
+    }
+    onSuccess() {
+        if (this.state === 'half-open') {
+            this.state = 'closed';
+        }
+        this.failureCount = 0;
+        this.successCount++;
+    }
+    onFailure() {
+        this.failureCount++;
+        this.lastFailure = Date.now() / 1000;
+        if (this.failureCount >= this.failureThreshold) {
+            this.state = 'open';
+        }
+    }
+    reset() {
+        const defaults = this.defaultState();
+        this.state = defaults.state;
+        this.failureCount = defaults.failureCount;
+        this.lastFailure = defaults.lastFailure;
+        this.successCount = defaults.successCount;
+        this.halfOpenTries = defaults.halfOpenTries;
+        this.totalCalls = defaults.totalCalls;
+        this.totalFailures = defaults.totalFailures;
+        this.saveState();
+    }
+    inspectPersistence() {
+        const result = {
+            persistPath: this.persistPath,
+            fileExists: fs.existsSync(this.persistPath),
+            currentState: this.state,
+        };
+        if (result.fileExists) {
+            try {
+                result.storedData = JSON.parse(fs.readFileSync(this.persistPath, 'utf-8'));
+            }
+            catch {
+                result.storedData = null;
+            }
+        }
+        return result;
+    }
+    get stats() {
+        return {
+            name: this.name,
+            state: this.state,
+            failureCount: this.failureCount,
+            successCount: this.successCount,
+            totalCalls: this.totalCalls,
+            totalFailures: this.totalFailures,
+            recoveryTimeout: this.recoveryTimeout,
+            persistPath: this.persistPath,
+            reliability: this.totalCalls > 0
+                ? `${((1 - this.totalFailures / this.totalCalls) * 100).toFixed(1)}%`
+                : '100%',
+        };
+    }
+}
+exports.StatefulBreaker = StatefulBreaker;

package/dist/trace.d.ts

@@ -0,0 +1,36 @@
+export interface Span {
+    spanId: string;
+    parentId?: string;
+    name: string;
+    start: number;
+    end?: number;
+    tags: Record<string, string>;
+    result?: string;
+    error?: string;
+    children: Span[];
+}
+interface TraceSummary {
+    traceId: string;
+    totalSpans: number;
+    durationMs: number;
+    maxDepth: number;
+    status: 'ok' | 'error';
+}
+export declare class Trace {
+    traceId: string;
+    spans: Span[];
+    private stack;
+    constructor(name: string);
+    startSpan(name: string, tags?: Record<string, string>): Span;
+    endSpan(result?: string, error?: string): void;
+    /** Count all spans recursively */
+    private countSpans;
+    /** Max depth of span tree */
+    private maxDepth;
+    summary(): TraceSummary;
+    /** Flatten spans into a list for table rendering */
+    flatten(spans?: Span[], depth?: number): Array<Span & {
+        depth: number;
+    }>;
+}
+export {};

package/dist/trace.js

@@ -0,0 +1,113 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Trace = void 0;
+/**
+ * Trace — 链路追踪
+ * Gene source: OpenTelemetry distributed tracing
+ * Full execution trace visibility for agent runs.
+ */
+const crypto = __importStar(require("crypto"));
+class Trace {
+    traceId;
+    spans = [];
+    stack = [];
+    constructor(name) {
+        this.traceId = crypto.randomUUID().slice(0, 8);
+        this.startSpan(name);
+    }
+    startSpan(name, tags) {
+        const span = {
+            spanId: crypto.randomUUID().slice(0, 8),
+            parentId: this.stack.length > 0 ? this.stack[this.stack.length - 1].spanId : undefined,
+            name,
+            start: Date.now(),
+            tags: tags || {},
+            children: [],
+        };
+        if (this.stack.length > 0) {
+            this.stack[this.stack.length - 1].children.push(span);
+        }
+        else {
+            this.spans.push(span);
+        }
+        this.stack.push(span);
+        return span;
+    }
+    endSpan(result, error) {
+        const span = this.stack.pop();
+        if (!span)
+            return;
+        span.end = Date.now();
+        if (result)
+            span.result = result.slice(0, 200);
+        if (error)
+            span.error = error.slice(0, 200);
+    }
+    /** Count all spans recursively */
+    countSpans(spans) {
+        return spans.reduce((sum, s) => sum + 1 + this.countSpans(s.children), 0);
+    }
+    /** Max depth of span tree */
+    maxDepth(spans, depth = 1) {
+        return spans.reduce((max, s) => Math.max(max, ...(s.children.length > 0 ? [this.maxDepth(s.children, depth + 1)] : [depth])), depth);
+    }
+    summary() {
+        const totalSpans = this.countSpans(this.spans);
+        const durationMs = this.spans.reduce((max, s) => {
+            if (s.end)
+                return Math.max(max, s.end - s.start);
+            return max;
+        }, 0);
+        const hasError = this.spans.some((s) => s.error) ||
+            this.spans.some((s) => s.children.some((c) => c.error));
+        return {
+            traceId: this.traceId,
+            totalSpans,
+            durationMs,
+            maxDepth: this.maxDepth(this.spans),
+            status: hasError ? 'error' : 'ok',
+        };
+    }
+    /** Flatten spans into a list for table rendering */
+    flatten(spans, depth = 0) {
+        const list = spans || this.spans;
+        return list.flatMap((s) => [
+            { ...s, depth },
+            ...this.flatten(s.children, depth + 1),
+        ]);
+    }
+}
+exports.Trace = Trace;

package/dist/validator.d.ts

@@ -0,0 +1,25 @@
+/**
+ * OutputValidator — 输出验证器
+ * Gene source: IDE static type checking
+ * Validates agent output against Zod schemas.
+ */
+import { ZodSchema } from 'zod';
+export interface ValidationResult {
+    valid: boolean;
+    data?: unknown;
+    errors?: string[];
+}
+export declare class OutputValidator {
+    passed: number;
+    blocked: number;
+    private validations;
+    validate<T>(schema: ZodSchema<T>, output: unknown): ValidationResult;
+    /** Quick-check an object against a simple shape */
+    validateShape(output: unknown, expected: Record<string, string>): ValidationResult;
+    get stats(): {
+        passed: number;
+        blocked: number;
+        validations: number;
+        blockRate: string;
+    };
+}

package/dist/validator.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutputValidator = void 0;
+class OutputValidator {
+    passed = 0;
+    blocked = 0;
+    validations = 0;
+    validate(schema, output) {
+        this.validations++;
+        const result = schema.safeParse(output);
+        if (result.success) {
+            this.passed++;
+            return { valid: true, data: result.data };
+        }
+        this.blocked++;
+        return {
+            valid: false,
+            errors: result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`),
+        };
+    }
+    /** Quick-check an object against a simple shape */
+    validateShape(output, expected) {
+        if (output === null || output === undefined) {
+            return { valid: false, errors: ['Output is null/undefined'] };
+        }
+        if (typeof output !== 'object') {
+            return { valid: false, errors: ['Output is not an object'] };
+        }
+        const obj = output;
+        const errors = [];
+        for (const [key, type] of Object.entries(expected)) {
+            if (!(key in obj))
+                errors.push(`${key} is missing`);
+            else if (typeof obj[key] !== type)
+                errors.push(`${key} should be ${type}, got ${typeof obj[key]}`);
+        }
+        this.validations++;
+        if (errors.length === 0) {
+            this.passed++;
+            return { valid: true, data: obj };
+        }
+        this.blocked++;
+        return { valid: false, errors };
+    }
+    get stats() {
+        return {
+            passed: this.passed,
+            blocked: this.blocked,
+            validations: this.validations,
+            blockRate: this.validations > 0
+                ? `${((this.blocked / this.validations) * 100).toFixed(1)}%`
+                : '0%',
+        };
+    }
+}
+exports.OutputValidator = OutputValidator;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@feilunxitong/arkit",
+  "version": "0.1.0",
+  "description": "🛡 ARKit — Agent Reliability Kit. Trust infrastructure for AI agents. TypeScript/Node.js SDK. (feilunxitong fork)",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "reliability",
+    "trust",
+    "idempotency",
+    "circuit-breaker",
+    "langchain"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wzg0911/ark-ts.git"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "author": "feilunxitong",
+  "bugs": {
+    "url": "https://github.com/wzg0911/ark-ts/issues"
+  },
+  "homepage": "https://github.com/wzg0911/ark-ts#readme"
+}