agentcourt 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,192 @@
+export type AgentCourtPassport = {
+    issuer: string;
+    trustLevel: "verified" | "unverified";
+    issuedAt: string;
+};
+export type AgentCourtAgent = {
+    id: string;
+    name: string;
+    owner: string;
+    ownerAddress?: string;
+    strategy: string;
+    passport: AgentCourtPassport;
+};
+export type ToolDecision = "ALLOW" | "STOP_TOOL" | "HUMAN_IN_THE_LOOP";
+export type ToolCallEvent = {
+    id: string;
+    agent: AgentCourtAgent;
+    tool: string;
+    args: Record<string, unknown>;
+    decision: ToolDecision;
+    reason: string;
+    evidenceHash: string;
+    latencyMs: number;
+    createdAt: string;
+};
+export type AgentCourtPolicy = {
+    maxTradeUsd: number;
+    maxDailyUsd: number;
+    allowedTools: string[];
+    humanApprovalTools: string[];
+    sensitivePatterns: Array<{
+        name: string;
+        pattern: string;
+    }>;
+};
+export declare const AGENTCOURT_AGORA_POLICY: AgentCourtPolicy;
+export declare class AgentCourtOrchestrator {
+    readonly policy: AgentCourtPolicy;
+    readonly rpcUrl: string;
+    readonly contractAddress: string;
+    private dailySpendUsd;
+    constructor(policy?: AgentCourtPolicy, rpcUrl?: string, contractAddress?: string);
+    /**
+     * Low-dependency JSON-RPC client over fetch
+     */
+    ethCall(to: string, data: string): Promise<string>;
+    /**
+     * Reads profile on-chain from the AgentCourt smart contract registry
+     */
+    queryOnChainProfile(ownerAddress: string): Promise<{
+        status: "simulated";
+        reason: string;
+        id?: undefined;
+        owner?: undefined;
+        stake?: undefined;
+        reputation?: undefined;
+        totalViolations?: undefined;
+        totalSlashed?: undefined;
+        onChainStatus?: undefined;
+        rawStatusCode?: undefined;
+        error?: undefined;
+    } | {
+        status: "unregistered";
+        id: number;
+        reason?: undefined;
+        owner?: undefined;
+        stake?: undefined;
+        reputation?: undefined;
+        totalViolations?: undefined;
+        totalSlashed?: undefined;
+        onChainStatus?: undefined;
+        rawStatusCode?: undefined;
+        error?: undefined;
+    } | {
+        status: "verified";
+        id: number;
+        owner: string;
+        stake: number;
+        reputation: number;
+        totalViolations: number;
+        totalSlashed: number;
+        onChainStatus: string;
+        rawStatusCode: number;
+        reason?: undefined;
+        error?: undefined;
+    } | {
+        status: "sandbox";
+        error: any;
+        reason?: undefined;
+        id?: undefined;
+        owner?: undefined;
+        stake?: undefined;
+        reputation?: undefined;
+        totalViolations?: undefined;
+        totalSlashed?: undefined;
+        onChainStatus?: undefined;
+        rawStatusCode?: undefined;
+    }>;
+    callTool(agent: AgentCourtAgent, tool: string, args: Record<string, unknown>, execute?: () => Promise<unknown> | unknown): Promise<{
+        event: ToolCallEvent;
+        result: unknown;
+    }>;
+    evaluate(agent: AgentCourtAgent, tool: string, args: Record<string, unknown>, onChainSlashed?: boolean): ToolCallEvent;
+}
+/**
+ * The AgoraAgentClient is a zero-dependency client that interfaces with both the Arc Testnet RPC and the Megent Orchestration Gateway
+ */
+export declare class AgoraAgentClient {
+    readonly endpoint: string;
+    readonly agent: AgentCourtAgent | undefined;
+    readonly runId: string | undefined;
+    readonly rpcUrl: string;
+    readonly contractAddress: string;
+    constructor({ endpoint, agent, runId, rpcUrl, contractAddress }?: {
+        endpoint?: string;
+        agent?: AgentCourtAgent;
+        runId?: string;
+        rpcUrl?: string;
+        contractAddress?: string;
+    });
+    /**
+     * Low-dependency JSON-RPC client over fetch
+     */
+    ethCall(to: string, data: string): Promise<string>;
+    /**
+     * Queries the AgentCourt contract to verify agent's profile on-chain.
+     */
+    queryOnChainProfile(ownerAddress: string): Promise<{
+        status: "simulated";
+        reason: string;
+        id?: undefined;
+        owner?: undefined;
+        stake?: undefined;
+        reputation?: undefined;
+        totalViolations?: undefined;
+        totalSlashed?: undefined;
+        onChainStatus?: undefined;
+        rawStatusCode?: undefined;
+        error?: undefined;
+    } | {
+        status: "unregistered";
+        id: number;
+        reason?: undefined;
+        owner?: undefined;
+        stake?: undefined;
+        reputation?: undefined;
+        totalViolations?: undefined;
+        totalSlashed?: undefined;
+        onChainStatus?: undefined;
+        rawStatusCode?: undefined;
+        error?: undefined;
+    } | {
+        status: "verified";
+        id: number;
+        owner: string;
+        stake: number;
+        reputation: number;
+        totalViolations: number;
+        totalSlashed: number;
+        onChainStatus: string;
+        rawStatusCode: number;
+        reason?: undefined;
+        error?: undefined;
+    } | {
+        status: "sandbox";
+        error: any;
+        reason?: undefined;
+        id?: undefined;
+        owner?: undefined;
+        stake?: undefined;
+        reputation?: undefined;
+        totalViolations?: undefined;
+        totalSlashed?: undefined;
+        onChainStatus?: undefined;
+        rawStatusCode?: undefined;
+    }>;
+    callTool(tool: string, args: Record<string, unknown>, execute?: (args: Record<string, unknown>) => Promise<unknown> | unknown): Promise<{
+        ok: boolean;
+        needsApproval: boolean;
+        event: any;
+        result: null;
+    } | {
+        ok: boolean;
+        event: any;
+        result: unknown;
+        needsApproval?: undefined;
+    }>;
+}
+export declare function createVerifiedAgent(input: Omit<AgentCourtAgent, "passport"> & {
+    ownerAddress?: string;
+}): AgentCourtAgent;
+export declare function hashEvidence(value: unknown): string;

package/dist/index.js

@@ -0,0 +1,323 @@
+import { createHash } from "crypto";
+export const AGENTCOURT_AGORA_POLICY = {
+    maxTradeUsd: 2500,
+    maxDailyUsd: 10000,
+    allowedTools: [
+        "market.read",
+        "risk.score",
+        "arc.quote",
+        "arc.transfer_usdc",
+        "arc.publish_trace",
+    ],
+    humanApprovalTools: ["arc.transfer_usdc"],
+    sensitivePatterns: [
+        { name: "private key", pattern: "private[_ -]?key|seed phrase|mnemonic" },
+        { name: "phone", pattern: "\\+?\\d[\\d\\s().-]{7,}\\d" },
+        { name: "email", pattern: "[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}" },
+    ],
+};
+export class AgentCourtOrchestrator {
+    policy;
+    rpcUrl;
+    contractAddress;
+    dailySpendUsd = 0;
+    constructor(policy = AGENTCOURT_AGORA_POLICY, rpcUrl = "https://rpc.testnet.arc.network", contractAddress = "0x1a6389aa779BD3C01B7867bB76a9B51f283f9B3a") {
+        this.policy = policy;
+        this.rpcUrl = rpcUrl;
+        this.contractAddress = contractAddress;
+    }
+    /**
+     * Low-dependency JSON-RPC client over fetch
+     */
+    async ethCall(to, data) {
+        try {
+            const response = await fetch(this.rpcUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: Date.now(),
+                    method: "eth_call",
+                    params: [
+                        { to, data },
+                        "latest"
+                    ]
+                })
+            });
+            const result = await response.json();
+            if (result.error) {
+                throw new Error(result.error.message);
+            }
+            return result.result;
+        }
+        catch (error) {
+            throw new Error(`RPC Connection failed: ${error.message}`);
+        }
+    }
+    /**
+     * Reads profile on-chain from the AgentCourt smart contract registry
+     */
+    async queryOnChainProfile(ownerAddress) {
+        if (!ownerAddress || !ownerAddress.startsWith("0x")) {
+            return { status: "simulated", reason: "Invalid owner address" };
+        }
+        try {
+            // 1. Get Agent ID of Owner
+            const addressClean = ownerAddress.slice(2).toLowerCase();
+            const agentIdData = `0xb3631cc9` + addressClean.padStart(64, "0");
+            const agentIdHex = await this.ethCall(this.contractAddress, agentIdData);
+            if (!agentIdHex || agentIdHex === "0x" || /^0x0*$/.test(agentIdHex)) {
+                return { status: "unregistered", id: 0 };
+            }
+            const agentId = parseInt(agentIdHex, 16);
+            // 2. Get Agent Profile from ID
+            const profileData = `0x16b06387` + agentId.toString(16).padStart(64, "0");
+            const profileHex = await this.ethCall(this.contractAddress, profileData);
+            if (!profileHex || profileHex === "0x") {
+                return { status: "unregistered", id: agentId };
+            }
+            const dataHex = profileHex.startsWith("0x") ? profileHex.slice(2) : profileHex;
+            const ownerHex = "0x" + dataHex.substring(24, 64);
+            const stake = BigInt("0x" + dataHex.substring(128, 192));
+            const reputation = parseInt(dataHex.substring(192, 256), 16);
+            const totalViolations = parseInt(dataHex.substring(256, 320), 16);
+            const totalSlashed = BigInt("0x" + dataHex.substring(320, 384));
+            const statusCode = parseInt(dataHex.substring(384, 448), 16);
+            const statuses = ["None", "Active", "Slashed"];
+            const status = statuses[statusCode] || "Unknown";
+            return {
+                status: "verified",
+                id: agentId,
+                owner: ownerHex,
+                stake: Number(stake) / 1e6, // USDC decimals
+                reputation,
+                totalViolations,
+                totalSlashed: Number(totalSlashed) / 1e6,
+                onChainStatus: status,
+                rawStatusCode: statusCode
+            };
+        }
+        catch (error) {
+            return {
+                status: "sandbox",
+                error: error.message
+            };
+        }
+    }
+    async callTool(agent, tool, args, execute) {
+        // Check status on-chain
+        let onChainSlashed = false;
+        const owner = agent.owner || agent.ownerAddress;
+        if (owner) {
+            const profile = await this.queryOnChainProfile(owner);
+            if (profile.status === "verified" && profile.onChainStatus === "Slashed") {
+                onChainSlashed = true;
+            }
+        }
+        const event = this.evaluate(agent, tool, args, onChainSlashed);
+        if (event.decision !== "ALLOW") {
+            return { event, result: null };
+        }
+        const amount = amountFromArgs(args);
+        this.dailySpendUsd += amount;
+        const result = execute ? await execute() : { accepted: true };
+        return { event, result };
+    }
+    evaluate(agent, tool, args, onChainSlashed = false) {
+        const started = performance.now();
+        const amount = amountFromArgs(args);
+        const sensitiveFindings = findSensitiveValues(this.policy, args);
+        let decision = "ALLOW";
+        let reason = "Policy checks passed.";
+        if (onChainSlashed) {
+            decision = "STOP_TOOL";
+            reason = "Agent status on-chain is Slashed. Tool calls permanently frozen.";
+        }
+        else if (!this.policy.allowedTools.includes(tool)) {
+            decision = "STOP_TOOL";
+            reason = "Tool is not allowlisted for this agent.";
+        }
+        else if (agent.passport.trustLevel !== "verified") {
+            decision = "STOP_TOOL";
+            reason = "Agent passport is missing or unverified.";
+        }
+        else if (sensitiveFindings.length > 0) {
+            decision = "STOP_TOOL";
+            reason = `Sensitive data detected: ${sensitiveFindings.join(", ")}.`;
+        }
+        else if (amount > this.policy.maxTradeUsd) {
+            decision = "HUMAN_IN_THE_LOOP";
+            reason = `Trade exceeds per-action limit of ${this.policy.maxTradeUsd} USDC.`;
+        }
+        else if (this.dailySpendUsd + amount > this.policy.maxDailyUsd) {
+            decision = "HUMAN_IN_THE_LOOP";
+            reason = `Run would exceed daily budget of ${this.policy.maxDailyUsd} USDC.`;
+        }
+        else if (this.policy.humanApprovalTools.includes(tool) && amount > 1000) {
+            decision = "HUMAN_IN_THE_LOOP";
+            reason = "High-value Arc settlement requires operator approval.";
+        }
+        const evidenceHash = hashEvidence({ agentId: agent.id, tool, args, decision, reason });
+        return {
+            id: `evt_${Date.now()}_${Math.random().toString(16).slice(2)}`,
+            agent,
+            tool,
+            args,
+            decision,
+            reason,
+            evidenceHash,
+            latencyMs: Number((performance.now() - started).toFixed(2)),
+            createdAt: new Date().toISOString(),
+        };
+    }
+}
+/**
+ * The AgoraAgentClient is a zero-dependency client that interfaces with both the Arc Testnet RPC and the Megent Orchestration Gateway
+ */
+export class AgoraAgentClient {
+    endpoint;
+    agent;
+    runId;
+    rpcUrl;
+    contractAddress;
+    constructor({ endpoint = "http://localhost:4141", agent, runId, rpcUrl = "https://rpc.testnet.arc.network", contractAddress = "0x1a6389aa779BD3C01B7867bB76a9B51f283f9B3a" } = {}) {
+        this.endpoint = endpoint.replace(/\/$/, "");
+        this.agent = agent;
+        this.runId = runId;
+        this.rpcUrl = rpcUrl;
+        this.contractAddress = contractAddress;
+    }
+    /**
+     * Low-dependency JSON-RPC client over fetch
+     */
+    async ethCall(to, data) {
+        try {
+            const response = await fetch(this.rpcUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: Date.now(),
+                    method: "eth_call",
+                    params: [
+                        { to, data },
+                        "latest"
+                    ]
+                })
+            });
+            const result = await response.json();
+            if (result.error) {
+                throw new Error(result.error.message);
+            }
+            return result.result;
+        }
+        catch (error) {
+            throw new Error(`RPC Connection failed: ${error.message}`);
+        }
+    }
+    /**
+     * Queries the AgentCourt contract to verify agent's profile on-chain.
+     */
+    async queryOnChainProfile(ownerAddress) {
+        if (!ownerAddress || !ownerAddress.startsWith("0x")) {
+            return { status: "simulated", reason: "Invalid owner address" };
+        }
+        try {
+            const addressClean = ownerAddress.slice(2).toLowerCase();
+            const agentIdData = `0xb3631cc9` + addressClean.padStart(64, "0");
+            const agentIdHex = await this.ethCall(this.contractAddress, agentIdData);
+            if (!agentIdHex || agentIdHex === "0x" || /^0x0*$/.test(agentIdHex)) {
+                return { status: "unregistered", id: 0 };
+            }
+            const agentId = parseInt(agentIdHex, 16);
+            const profileData = `0x16b06387` + agentId.toString(16).padStart(64, "0");
+            const profileHex = await this.ethCall(this.contractAddress, profileData);
+            if (!profileHex || profileHex === "0x") {
+                return { status: "unregistered", id: agentId };
+            }
+            const dataHex = profileHex.startsWith("0x") ? profileHex.slice(2) : profileHex;
+            const ownerHex = "0x" + dataHex.substring(24, 64);
+            const stake = BigInt("0x" + dataHex.substring(128, 192));
+            const reputation = parseInt(dataHex.substring(192, 256), 16);
+            const totalViolations = parseInt(dataHex.substring(256, 320), 16);
+            const totalSlashed = BigInt("0x" + dataHex.substring(320, 384));
+            const statusCode = parseInt(dataHex.substring(384, 448), 16);
+            const statuses = ["None", "Active", "Slashed"];
+            const status = statuses[statusCode] || "Unknown";
+            return {
+                status: "verified",
+                id: agentId,
+                owner: ownerHex,
+                stake: Number(stake) / 1e6, // USDC
+                reputation,
+                totalViolations,
+                totalSlashed: Number(totalSlashed) / 1e6,
+                onChainStatus: status,
+                rawStatusCode: statusCode
+            };
+        }
+        catch (error) {
+            return {
+                status: "sandbox",
+                error: error.message
+            };
+        }
+    }
+    async callTool(tool, args, execute) {
+        let onChainProfile = null;
+        const owner = this.agent?.owner || this.agent?.ownerAddress;
+        if (this.agent && owner) {
+            onChainProfile = await this.queryOnChainProfile(owner);
+        }
+        else {
+            onChainProfile = { status: "sandbox", reason: "No agent owner address provided" };
+        }
+        const response = await fetch(`${this.endpoint}/api/tool-call`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                runId: this.runId,
+                agent: {
+                    ...this.agent,
+                    onChainProfile
+                },
+                tool,
+                args
+            })
+        });
+        const event = await response.json();
+        if (event.verdict?.action === "STOP_TOOL") {
+            return { ok: false, event, result: null };
+        }
+        if (event.verdict?.action === "HUMAN_IN_THE_LOOP") {
+            return { ok: false, needsApproval: true, event, result: null };
+        }
+        const result = execute ? await execute(args) : { accepted: true };
+        return { ok: true, event, result };
+    }
+}
+export function createVerifiedAgent(input) {
+    return {
+        ...input,
+        owner: input.owner || input.ownerAddress || `0x${Math.random().toString(16).slice(2).padEnd(40, "0")}`,
+        passport: {
+            issuer: "agentcourt-arc",
+            trustLevel: "verified",
+            issuedAt: new Date().toISOString(),
+        },
+    };
+}
+export function hashEvidence(value) {
+    return `0x${createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+}
+function amountFromArgs(args) {
+    const value = args.amountUsd ?? args.notionalUsd ?? 0;
+    return typeof value === "number" ? value : Number(value) || 0;
+}
+function findSensitiveValues(policy, value) {
+    const raw = JSON.stringify(value ?? {});
+    return policy.sensitivePatterns
+        .map((item) => ({ ...item, regex: new RegExp(item.pattern, "i") }))
+        .filter((item) => item.regex.test(raw))
+        .map((item) => item.name);
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "agentcourt",
+  "version": "1.0.0",
+  "description": "Production-ready zero-dependency Web3 security gateway and orchestration SDK for AI agents on Arc Network",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "agents",
+    "arc",
+    "web3",
+    "agentcourt",
+    "security",
+    "governance"
+  ],
+  "author": "Megents Team",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,416 @@
+import { createHash } from "crypto";
+
+export type AgentCourtPassport = {
+  issuer: string;
+  trustLevel: "verified" | "unverified";
+  issuedAt: string;
+};
+
+export type AgentCourtAgent = {
+  id: string;
+  name: string;
+  owner: string;
+  ownerAddress?: string;
+  strategy: string;
+  passport: AgentCourtPassport;
+};
+
+export type ToolDecision = "ALLOW" | "STOP_TOOL" | "HUMAN_IN_THE_LOOP";
+
+export type ToolCallEvent = {
+  id: string;
+  agent: AgentCourtAgent;
+  tool: string;
+  args: Record<string, unknown>;
+  decision: ToolDecision;
+  reason: string;
+  evidenceHash: string;
+  latencyMs: number;
+  createdAt: string;
+};
+
+export type AgentCourtPolicy = {
+  maxTradeUsd: number;
+  maxDailyUsd: number;
+  allowedTools: string[];
+  humanApprovalTools: string[];
+  sensitivePatterns: Array<{ name: string; pattern: string }>;
+};
+
+export const AGENTCOURT_AGORA_POLICY: AgentCourtPolicy = {
+  maxTradeUsd: 2500,
+  maxDailyUsd: 10000,
+  allowedTools: [
+    "market.read",
+    "risk.score",
+    "arc.quote",
+    "arc.transfer_usdc",
+    "arc.publish_trace",
+  ],
+  humanApprovalTools: ["arc.transfer_usdc"],
+  sensitivePatterns: [
+    { name: "private key", pattern: "private[_ -]?key|seed phrase|mnemonic" },
+    { name: "phone", pattern: "\\+?\\d[\\d\\s().-]{7,}\\d" },
+    { name: "email", pattern: "[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}" },
+  ],
+};
+
+export class AgentCourtOrchestrator {
+  private dailySpendUsd = 0;
+
+  constructor(
+    public readonly policy: AgentCourtPolicy = AGENTCOURT_AGORA_POLICY,
+    public readonly rpcUrl: string = "https://rpc.testnet.arc.network",
+    public readonly contractAddress: string = "0x1a6389aa779BD3C01B7867bB76a9B51f283f9B3a"
+  ) {}
+
+  /**
+   * Low-dependency JSON-RPC client over fetch
+   */
+  async ethCall(to: string, data: string): Promise<string> {
+    try {
+      const response = await fetch(this.rpcUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: Date.now(),
+          method: "eth_call",
+          params: [
+            { to, data },
+            "latest"
+          ]
+        })
+      });
+      const result = await response.json();
+      if (result.error) {
+        throw new Error(result.error.message);
+      }
+      return result.result;
+    } catch (error: any) {
+      throw new Error(`RPC Connection failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Reads profile on-chain from the AgentCourt smart contract registry
+   */
+  async queryOnChainProfile(ownerAddress: string) {
+    if (!ownerAddress || !ownerAddress.startsWith("0x")) {
+      return { status: "simulated" as const, reason: "Invalid owner address" };
+    }
+
+    try {
+      // 1. Get Agent ID of Owner
+      const addressClean = ownerAddress.slice(2).toLowerCase();
+      const agentIdData = `0xb3631cc9` + addressClean.padStart(64, "0");
+      const agentIdHex = await this.ethCall(this.contractAddress, agentIdData);
+      
+      if (!agentIdHex || agentIdHex === "0x" || /^0x0*$/.test(agentIdHex)) {
+        return { status: "unregistered" as const, id: 0 };
+      }
+      
+      const agentId = parseInt(agentIdHex, 16);
+      
+      // 2. Get Agent Profile from ID
+      const profileData = `0x16b06387` + agentId.toString(16).padStart(64, "0");
+      const profileHex = await this.ethCall(this.contractAddress, profileData);
+
+      if (!profileHex || profileHex === "0x") {
+        return { status: "unregistered" as const, id: agentId };
+      }
+
+      const dataHex = profileHex.startsWith("0x") ? profileHex.slice(2) : profileHex;
+      const ownerHex = "0x" + dataHex.substring(24, 64);
+      const stake = BigInt("0x" + dataHex.substring(128, 192));
+      const reputation = parseInt(dataHex.substring(192, 256), 16);
+      const totalViolations = parseInt(dataHex.substring(256, 320), 16);
+      const totalSlashed = BigInt("0x" + dataHex.substring(320, 384));
+      const statusCode = parseInt(dataHex.substring(384, 448), 16);
+
+      const statuses = ["None", "Active", "Slashed"];
+      const status = statuses[statusCode] || "Unknown";
+
+      return {
+        status: "verified" as const,
+        id: agentId,
+        owner: ownerHex,
+        stake: Number(stake) / 1e6, // USDC decimals
+        reputation,
+        totalViolations,
+        totalSlashed: Number(totalSlashed) / 1e6,
+        onChainStatus: status,
+        rawStatusCode: statusCode
+      };
+    } catch (error: any) {
+      return {
+        status: "sandbox" as const,
+        error: error.message
+      };
+    }
+  }
+
+  async callTool(
+    agent: AgentCourtAgent,
+    tool: string,
+    args: Record<string, unknown>,
+    execute?: () => Promise<unknown> | unknown
+  ) {
+    // Check status on-chain
+    let onChainSlashed = false;
+    const owner = agent.owner || agent.ownerAddress;
+    if (owner) {
+      const profile = await this.queryOnChainProfile(owner);
+      if (profile.status === "verified" && profile.onChainStatus === "Slashed") {
+        onChainSlashed = true;
+      }
+    }
+
+    const event = this.evaluate(agent, tool, args, onChainSlashed);
+
+    if (event.decision !== "ALLOW") {
+      return { event, result: null };
+    }
+
+    const amount = amountFromArgs(args);
+    this.dailySpendUsd += amount;
+    const result = execute ? await execute() : { accepted: true };
+    return { event, result };
+  }
+
+  evaluate(
+    agent: AgentCourtAgent, 
+    tool: string, 
+    args: Record<string, unknown>,
+    onChainSlashed: boolean = false
+  ): ToolCallEvent {
+    const started = performance.now();
+    const amount = amountFromArgs(args);
+    const sensitiveFindings = findSensitiveValues(this.policy, args);
+    let decision: ToolDecision = "ALLOW";
+    let reason = "Policy checks passed.";
+
+    if (onChainSlashed) {
+      decision = "STOP_TOOL";
+      reason = "Agent status on-chain is Slashed. Tool calls permanently frozen.";
+    } else if (!this.policy.allowedTools.includes(tool)) {
+      decision = "STOP_TOOL";
+      reason = "Tool is not allowlisted for this agent.";
+    } else if (agent.passport.trustLevel !== "verified") {
+      decision = "STOP_TOOL";
+      reason = "Agent passport is missing or unverified.";
+    } else if (sensitiveFindings.length > 0) {
+      decision = "STOP_TOOL";
+      reason = `Sensitive data detected: ${sensitiveFindings.join(", ")}.`;
+    } else if (amount > this.policy.maxTradeUsd) {
+      decision = "HUMAN_IN_THE_LOOP";
+      reason = `Trade exceeds per-action limit of ${this.policy.maxTradeUsd} USDC.`;
+    } else if (this.dailySpendUsd + amount > this.policy.maxDailyUsd) {
+      decision = "HUMAN_IN_THE_LOOP";
+      reason = `Run would exceed daily budget of ${this.policy.maxDailyUsd} USDC.`;
+    } else if (this.policy.humanApprovalTools.includes(tool) && amount > 1000) {
+      decision = "HUMAN_IN_THE_LOOP";
+      reason = "High-value Arc settlement requires operator approval.";
+    }
+
+    const evidenceHash = hashEvidence({ agentId: agent.id, tool, args, decision, reason });
+
+    return {
+      id: `evt_${Date.now()}_${Math.random().toString(16).slice(2)}`,
+      agent,
+      tool,
+      args,
+      decision,
+      reason,
+      evidenceHash,
+      latencyMs: Number((performance.now() - started).toFixed(2)),
+      createdAt: new Date().toISOString(),
+    };
+  }
+}
+
+/**
+ * The AgoraAgentClient is a zero-dependency client that interfaces with both the Arc Testnet RPC and the Megent Orchestration Gateway
+ */
+export class AgoraAgentClient {
+  public readonly endpoint: string;
+  public readonly agent: AgentCourtAgent | undefined;
+  public readonly runId: string | undefined;
+  public readonly rpcUrl: string;
+  public readonly contractAddress: string;
+
+  constructor({
+    endpoint = "http://localhost:4141",
+    agent,
+    runId,
+    rpcUrl = "https://rpc.testnet.arc.network",
+    contractAddress = "0x1a6389aa779BD3C01B7867bB76a9B51f283f9B3a"
+  }: {
+    endpoint?: string;
+    agent?: AgentCourtAgent;
+    runId?: string;
+    rpcUrl?: string;
+    contractAddress?: string;
+  } = {}) {
+    this.endpoint = endpoint.replace(/\/$/, "");
+    this.agent = agent;
+    this.runId = runId;
+    this.rpcUrl = rpcUrl;
+    this.contractAddress = contractAddress;
+  }
+
+  /**
+   * Low-dependency JSON-RPC client over fetch
+   */
+  async ethCall(to: string, data: string): Promise<string> {
+    try {
+      const response = await fetch(this.rpcUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: Date.now(),
+          method: "eth_call",
+          params: [
+            { to, data },
+            "latest"
+          ]
+        })
+      });
+      const result = await response.json();
+      if (result.error) {
+        throw new Error(result.error.message);
+      }
+      return result.result;
+    } catch (error: any) {
+      throw new Error(`RPC Connection failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Queries the AgentCourt contract to verify agent's profile on-chain.
+   */
+  async queryOnChainProfile(ownerAddress: string) {
+    if (!ownerAddress || !ownerAddress.startsWith("0x")) {
+      return { status: "simulated" as const, reason: "Invalid owner address" };
+    }
+
+    try {
+      const addressClean = ownerAddress.slice(2).toLowerCase();
+      const agentIdData = `0xb3631cc9` + addressClean.padStart(64, "0");
+      const agentIdHex = await this.ethCall(this.contractAddress, agentIdData);
+      
+      if (!agentIdHex || agentIdHex === "0x" || /^0x0*$/.test(agentIdHex)) {
+        return { status: "unregistered" as const, id: 0 };
+      }
+      
+      const agentId = parseInt(agentIdHex, 16);
+
+      const profileData = `0x16b06387` + agentId.toString(16).padStart(64, "0");
+      const profileHex = await this.ethCall(this.contractAddress, profileData);
+
+      if (!profileHex || profileHex === "0x") {
+        return { status: "unregistered" as const, id: agentId };
+      }
+
+      const dataHex = profileHex.startsWith("0x") ? profileHex.slice(2) : profileHex;
+      
+      const ownerHex = "0x" + dataHex.substring(24, 64);
+      const stake = BigInt("0x" + dataHex.substring(128, 192));
+      const reputation = parseInt(dataHex.substring(192, 256), 16);
+      const totalViolations = parseInt(dataHex.substring(256, 320), 16);
+      const totalSlashed = BigInt("0x" + dataHex.substring(320, 384));
+      const statusCode = parseInt(dataHex.substring(384, 448), 16);
+
+      const statuses = ["None", "Active", "Slashed"];
+      const status = statuses[statusCode] || "Unknown";
+
+      return {
+        status: "verified" as const,
+        id: agentId,
+        owner: ownerHex,
+        stake: Number(stake) / 1e6, // USDC
+        reputation,
+        totalViolations,
+        totalSlashed: Number(totalSlashed) / 1e6,
+        onChainStatus: status,
+        rawStatusCode: statusCode
+      };
+    } catch (error: any) {
+      return {
+        status: "sandbox" as const,
+        error: error.message
+      };
+    }
+  }
+
+  async callTool(
+    tool: string,
+    args: Record<string, unknown>,
+    execute?: (args: Record<string, unknown>) => Promise<unknown> | unknown
+  ) {
+    let onChainProfile = null;
+    const owner = this.agent?.owner || this.agent?.ownerAddress;
+    if (this.agent && owner) {
+      onChainProfile = await this.queryOnChainProfile(owner);
+    } else {
+      onChainProfile = { status: "sandbox" as const, reason: "No agent owner address provided" };
+    }
+
+    const response = await fetch(`${this.endpoint}/api/tool-call`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        runId: this.runId,
+        agent: {
+          ...this.agent,
+          onChainProfile
+        },
+        tool,
+        args
+      })
+    });
+    const event = await response.json();
+
+    if (event.verdict?.action === "STOP_TOOL") {
+      return { ok: false, event, result: null };
+    }
+
+    if (event.verdict?.action === "HUMAN_IN_THE_LOOP") {
+      return { ok: false, needsApproval: true, event, result: null };
+    }
+
+    const result = execute ? await execute(args) : { accepted: true };
+    return { ok: true, event, result };
+  }
+}
+
+export function createVerifiedAgent(input: Omit<AgentCourtAgent, "passport"> & { ownerAddress?: string }): AgentCourtAgent {
+  return {
+    ...input,
+    owner: input.owner || input.ownerAddress || `0x${Math.random().toString(16).slice(2).padEnd(40, "0")}`,
+    passport: {
+      issuer: "agentcourt-arc",
+      trustLevel: "verified",
+      issuedAt: new Date().toISOString(),
+    },
+  };
+}
+
+export function hashEvidence(value: unknown) {
+  return `0x${createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+}
+
+function amountFromArgs(args: Record<string, unknown>) {
+  const value = args.amountUsd ?? args.notionalUsd ?? 0;
+  return typeof value === "number" ? value : Number(value) || 0;
+}
+
+function findSensitiveValues(policy: AgentCourtPolicy, value: Record<string, unknown>) {
+  const raw = JSON.stringify(value ?? {});
+
+  return policy.sensitivePatterns
+    .map((item) => ({ ...item, regex: new RegExp(item.pattern, "i") }))
+    .filter((item) => item.regex.test(raw))
+    .map((item) => item.name);
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"]
+}