safehands-pharos 1.5.0 → 2.8.0

package/dist/agent/agentDecisionFormatter.d.ts

@@ -0,0 +1,43 @@
+import type { GuardianDecision } from "../lib/guardian/decision.js";
+import type { AnalyzerRiskLevel } from "../lib/analysis/index.js";
+import type { AgentIntent, AgentRequest } from "./agentIntentClassifier.js";
+import type { RoutedResult } from "./agentToolRouter.js";
+import type { PolicyOutcome } from "./agentPolicyResolver.js";
+import { type CallerObligation } from "./agentRuntime.js";
+export interface AgentDecision {
+    intent: AgentIntent;
+    /** Public four-value SafeHands decision. */
+    decision: GuardianDecision;
+    riskLevel: AnalyzerRiskLevel;
+    summary: string;
+    reasons: string[];
+    recommendedAction: string;
+    /** Raw analyzer/handler output + any supporting evidence. */
+    evidence: unknown;
+    /** Always true — the agent never writes, signs, sends, or publishes. */
+    readOnly: true;
+    /** False by default (mainnet execution disabled + gates off). */
+    executionAvailable: boolean;
+    nextStep: string;
+    callerObligation: CallerObligation;
+    /** Which capability produced the verdict. */
+    tool: string;
+    /** The applied policy preset — or null when none was selected. */
+    policyPreset: string | null;
+    /** Policy semantics version — surfaced, never secret. */
+    policyVersion: string;
+    experimental?: boolean;
+}
+export interface FormatArgs {
+    intent: AgentIntent;
+    req: AgentRequest;
+    routed: RoutedResult;
+    policyOutcome: PolicyOutcome;
+    executionAvailable: boolean;
+    /** The applied policy preset name. */
+    policyPreset?: string;
+    /** The real market/security/chain evidence from the Enrich step. */
+    enrichment?: any;
+}
+export declare function formatDecision(args: FormatArgs): AgentDecision;
+//# sourceMappingURL=agentDecisionFormatter.d.ts.map

package/dist/agent/agentDecisionFormatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentDecisionFormatter.d.ts","sourceRoot":"","sources":["../../src/agent/agentDecisionFormatter.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAKlE,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAiB,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGzE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,WAAW,CAAC;IACpB,4CAA4C;IAC5C,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,EAAE,iBAAiB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,QAAQ,EAAE,OAAO,CAAC;IAClB,wEAAwE;IACxE,QAAQ,EAAE,IAAI,CAAC;IACf,iEAAiE;IACjE,kBAAkB,EAAE,OAAO,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AA2BD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,WAAW,CAAC;IACpB,GAAG,EAAE,YAAY,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa,EAAE,aAAa,CAAC;IAC7B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,UAAU,CAAC,EAAE,GAAG,CAAC;CAClB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,aAAa,CA0D9D"}

package/dist/agent/agentDecisionFormatter.js

@@ -0,0 +1,96 @@
+// ─── SafeHands Agent — Decision Formatter (read-only) ─────────
+// Shapes the final AgentDecision from the routed analyzer output + policy
+// outcome. Applies the PREPARE_ONLY rule (an ALLOW execution-intent becomes
+// PREPARE_ONLY when execution is unavailable — the default) and derives the
+// caller obligation, recommended action, and next step. Pure: no execution.
+// ────────────────────────────────────────────────────────────────────────
+import { tokenRegistryEvidence } from "../lib/analysis/pharosTokens.js";
+import { rpcEvidence, gasEvidence } from "../lib/pharos/rpcEvidence.js";
+import { ecosystemEvidenceForRequest, applyEcosystemEscalation } from "../lib/pharos/ecosystemEvidence.js";
+import { getActiveNetwork } from "../lib/networks.js";
+import { obligationFor } from "./agentRuntime.js";
+import { POLICY_VERSION } from "../lib/policy/policyPresets.js";
+/** Intents that represent an action the caller intends to EXECUTE. */
+const EXECUTION_INTENTS = new Set([
+    "native_transfer",
+    "raw_transaction_intent",
+    "unknown_contract_call",
+    "erc20_approval",
+    "permit2_approval",
+    "safe_transaction",
+    "x402_payment_request",
+]);
+const RECOMMENDED = {
+    ALLOW: "Proceed: no blocking risk found. SafeHands does not execute; the caller executes externally.",
+    BLOCK: "Do not execute: the action is unsafe and must be aborted.",
+    REQUIRE_CONFIRMATION: "Obtain explicit user/admin confirmation before any execution.",
+    PREPARE_ONLY: "Prepare or hand off only: execution is disabled here; do not execute.",
+};
+const NEXT_STEP = {
+    ALLOW: "Execute externally with your own signer (SafeHands holds no keys).",
+    BLOCK: "Abort the action and surface the block reason to the user/agent.",
+    REQUIRE_CONFIRMATION: "Pause and request explicit confirmation from the user or admin.",
+    PREPARE_ONLY: "Return a prepared/handoff action for external execution; do not execute here.",
+};
+export function formatDecision(args) {
+    const { intent, req, routed, policyOutcome, executionAvailable, enrichment } = args;
+    let decision = policyOutcome.decision;
+    const reasons = [...routed.reasons, ...policyOutcome.reasons, ...policyOutcome.notes];
+    // Ecosystem awareness: classify the target/intent against the Pharos ecosystem
+    // registry. ESCALATE-ONLY — cross-chain / WASM-interop intents become
+    // REQUIRE_CONFIRMATION; ecosystem evidence NEVER relaxes a decision or makes a
+    // risky action safe (a BLOCK stays a BLOCK).
+    const ecosystemEvidence = ecosystemEvidenceForRequest(req);
+    const escalated = applyEcosystemEscalation(decision, ecosystemEvidence);
+    if (escalated !== decision) {
+        decision = escalated;
+        reasons.push(`Ecosystem awareness (${ecosystemEvidence.category}): ${ecosystemEvidence.safehandsBehavior}`);
+    }
+    // PREPARE_ONLY: a safe execution-intent the caller cannot execute here.
+    if (decision === "ALLOW" && !executionAvailable && EXECUTION_INTENTS.has(intent)) {
+        decision = "PREPARE_ONLY";
+        reasons.push("Action is safe but execution is disabled by default: prepare-only (no execution here).");
+    }
+    // Optional supporting evidence: token-registry status for token-bearing intents,
+    // plus read-only RPC + gas capability evidence (deterministic, secret-free).
+    const evidence = { analyzer: routed.evidence };
+    const tokenRef = req.token ?? (intent === "contract_check" ? req.address ?? req.to : undefined);
+    if (tokenRef) {
+        try {
+            evidence.tokenRegistry = tokenRegistryEvidence(tokenRef, getActiveNetwork());
+        }
+        catch {
+            /* evidence is best-effort */
+        }
+    }
+    evidence.rpcEvidence = rpcEvidence(getActiveNetwork());
+    evidence.gasEvidence = gasEvidence();
+    evidence.ecosystemEvidence = ecosystemEvidence;
+    if (enrichment)
+        evidence.enrichment = enrichment;
+    const summary = buildSummary(intent, decision, routed, reasons);
+    return {
+        intent,
+        decision,
+        riskLevel: routed.riskLevel,
+        summary,
+        reasons,
+        recommendedAction: RECOMMENDED[decision],
+        evidence,
+        readOnly: true,
+        executionAvailable,
+        nextStep: NEXT_STEP[decision],
+        callerObligation: obligationFor(decision).obligation,
+        tool: routed.tool,
+        policyPreset: args.policyPreset ?? null,
+        policyVersion: POLICY_VERSION,
+        experimental: routed.experimental,
+    };
+}
+function buildSummary(intent, decision, routed, reasons) {
+    const head = `SafeHands → ${decision} for ${intent.replace(/_/g, " ")}`;
+    const why = reasons[0] ?? routed.reasons[0] ?? "No additional detail.";
+    const exp = routed.experimental ? " (experimental decode)" : "";
+    return `${head}${exp}. ${why}`;
+}
+//# sourceMappingURL=agentDecisionFormatter.js.map

package/dist/agent/agentDecisionFormatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentDecisionFormatter.js","sourceRoot":"","sources":["../../src/agent/agentDecisionFormatter.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,0EAA0E;AAC1E,4EAA4E;AAC5E,4EAA4E;AAC5E,4EAA4E;AAC5E,2EAA2E;AAI3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAE,2BAA2B,EAAE,wBAAwB,EAAE,MAAM,oCAAoC,CAAC;AAC3G,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAItD,OAAO,EAAE,aAAa,EAAyB,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AA2BhE,sEAAsE;AACtE,MAAM,iBAAiB,GAA6B,IAAI,GAAG,CAAc;IACvE,iBAAiB;IACjB,wBAAwB;IACxB,uBAAuB;IACvB,gBAAgB;IAChB,kBAAkB;IAClB,kBAAkB;IAClB,sBAAsB;CACvB,CAAC,CAAC;AAEH,MAAM,WAAW,GAAqC;IACpD,KAAK,EAAE,8FAA8F;IACrG,KAAK,EAAE,2DAA2D;IAClE,oBAAoB,EAAE,+DAA+D;IACrF,YAAY,EAAE,uEAAuE;CACtF,CAAC;AAEF,MAAM,SAAS,GAAqC;IAClD,KAAK,EAAE,oEAAoE;IAC3E,KAAK,EAAE,kEAAkE;IACzE,oBAAoB,EAAE,iEAAiE;IACvF,YAAY,EAAE,+EAA+E;CAC9F,CAAC;AAcF,MAAM,UAAU,cAAc,CAAC,IAAgB;IAC7C,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,kBAAkB,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IAEpF,IAAI,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC;IACtC,MAAM,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,GAAG,aAAa,CAAC,OAAO,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEtF,+EAA+E;IAC/E,sEAAsE;IACtE,+EAA+E;IAC/E,6CAA6C;IAC7C,MAAM,iBAAiB,GAAG,2BAA2B,CAAC,GAAG,CAAC,CAAC;IAC3D,MAAM,SAAS,GAAG,wBAAwB,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC;IACxE,IAAI,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC3B,QAAQ,GAAG,SAAS,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,wBAAwB,iBAAiB,CAAC,QAAQ,MAAM,iBAAiB,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAC9G,CAAC;IAED,wEAAwE;IACxE,IAAI,QAAQ,KAAK,OAAO,IAAI,CAAC,kBAAkB,IAAI,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QACjF,QAAQ,GAAG,cAAc,CAAC;QAC1B,OAAO,CAAC,IAAI,CAAC,wFAAwF,CAAC,CAAC;IACzG,CAAC;IAED,iFAAiF;IACjF,6EAA6E;IAC7E,MAAM,QAAQ,GAA4B,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;IACxE,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,IAAI,CAAC,MAAM,KAAK,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAChG,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC;YACH,QAAQ,CAAC,aAAa,GAAG,qBAAqB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAC,CAAC;QAC/E,CAAC;QAAC,MAAM,CAAC;YACP,6BAA6B;QAC/B,CAAC;IACH,CAAC;IACD,QAAQ,CAAC,WAAW,GAAG,WAAW,CAAC,gBAAgB,EAAE,CAAC,CAAC;IACvD,QAAQ,CAAC,WAAW,GAAG,WAAW,EAAE,CAAC;IACrC,QAAQ,CAAC,iBAAiB,GAAG,iBAAiB,CAAC;IAC/C,IAAI,UAAU;QAAE,QAAQ,CAAC,UAAU,GAAG,UAAU,CAAC;IAEjD,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhE,OAAO;QACL,MAAM;QACN,QAAQ;QACR,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,OAAO;QACP,OAAO;QACP,iBAAiB,EAAE,WAAW,CAAC,QAAQ,CAAC;QACxC,QAAQ;QACR,QAAQ,EAAE,IAAI;QACd,kBAAkB;QAClB,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC;QAC7B,gBAAgB,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,UAAU;QACpD,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,IAAI;QACvC,aAAa,EAAE,cAAc;QAC7B,YAAY,EAAE,MAAM,CAAC,YAAY;KAClC,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,MAAmB,EAAE,QAA0B,EAAE,MAAoB,EAAE,OAAiB;IAC5G,MAAM,IAAI,GAAG,eAAe,QAAQ,QAAQ,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;IACxE,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,uBAAuB,CAAC;IACvE,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,EAAE,CAAC;IAChE,OAAO,GAAG,IAAI,GAAG,GAAG,KAAK,GAAG,EAAE,CAAC;AACjC,CAAC"}

package/dist/agent/agentEnrich.d.ts

@@ -0,0 +1,28 @@
+import type { AgentRequest } from "./agentIntentClassifier.js";
+export interface Enrichment {
+    enriched: boolean;
+    network: string;
+    /** SafeHands on-chain reputation for the action target (from SafeHandsRegistry). */
+    onChainReputation?: {
+        target: string;
+        currentMerkleRoot: string | null;
+        hasL2BatchRecord: boolean;
+        isAuthorizedAgent: boolean;
+        /** Count of SafeHands-verified safe broadcasts attributed to the target (0 = no track record yet → neutral). */
+        verifiedActionCount: number;
+        /** Unix seconds of the target's most recent verified action (0 = none yet). */
+        lastVerifiedActionAt: number;
+    };
+    /** Live gas context from the active network. */
+    gas?: {
+        gasPriceGwei: number;
+    };
+    /** Profile of the action target (contract vs EOA, native PROS balance). */
+    targetProfile?: {
+        isContract: boolean;
+        nativeBalancePROS: string;
+    };
+    notes: string[];
+}
+export declare function enrich(req: AgentRequest): Promise<Enrichment>;
+//# sourceMappingURL=agentEnrich.d.ts.map

package/dist/agent/agentEnrich.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentEnrich.d.ts","sourceRoot":"","sources":["../../src/agent/agentEnrich.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AA2B/D,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,iBAAiB,CAAC,EAAE;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;QACjC,gBAAgB,EAAE,OAAO,CAAC;QAC1B,iBAAiB,EAAE,OAAO,CAAC;QAC3B,gHAAgH;QAChH,mBAAmB,EAAE,MAAM,CAAC;QAC5B,+EAA+E;QAC/E,oBAAoB,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF,gDAAgD;IAChD,GAAG,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,2EAA2E;IAC3E,aAAa,CAAC,EAAE;QAAE,UAAU,EAAE,OAAO,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,wBAAsB,MAAM,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAkEnE"}

package/dist/agent/agentEnrich.js

@@ -0,0 +1,99 @@
+// ─── SafeHands Operator — Enrich step (read-only) ───────────────────────
+// Composes REAL on-chain + market intelligence into the SafeHands verdict so a
+// decision is data-backed, not just a static policy result. Best-effort: every
+// enricher is wrapped so a failure (offline / RPC hiccup) only omits that signal
+// — it never breaks the verdict. No signing, no writes.
+//
+// This enricher adds on-chain signals only (contract profile, SafeHands
+// reputation oracle, gas). Token-security intelligence (GoPlus, queried live
+// for Pharos by checkTokenSecurity) is applied separately in the check
+// pipeline — it is not duplicated here.
+// ────────────────────────────────────────────────────────────────────────
+import { isAddress, formatGwei, formatEther } from "viem";
+import { publicClient } from "../lib/pharosClient.js";
+import { queryRegistryForTarget } from "../lib/safeHandsRegistry.js";
+import { getAgentReputation } from "../lib/pharos/attestationPublisher.js";
+import { getActiveNetwork } from "../lib/networks.js";
+const DEFAULT_ENRICHMENT_TIMEOUT_MS = 4_000;
+function getEnrichmentTimeoutMs() {
+    const parsed = Number.parseInt(process.env.SAFEHANDS_ENRICH_TIMEOUT_MS ?? "", 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_ENRICHMENT_TIMEOUT_MS;
+}
+async function withEnrichmentTimeout(promise, label) {
+    const timeoutMs = getEnrichmentTimeoutMs();
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+export async function enrich(req) {
+    const notes = [];
+    const out = { enriched: false, network: getActiveNetwork().name, notes };
+    // 1. On-chain SafeHands reputation for the target (composable oracle).
+    const target = req.to ?? req.address ?? req.token;
+    if (target && isAddress(target)) {
+        try {
+            const [reg, rep] = await withEnrichmentTimeout(Promise.all([
+                queryRegistryForTarget(target),
+                getAgentReputation(target),
+            ]), "on-chain SafeHands reputation");
+            out.onChainReputation = {
+                target,
+                currentMerkleRoot: reg.currentMerkleRoot ?? null,
+                hasL2BatchRecord: reg.hasRiskRecord,
+                isAuthorizedAgent: reg.authorized,
+                verifiedActionCount: rep.verifiedCount,
+                lastVerifiedActionAt: rep.lastAttestationAt,
+            };
+            out.enriched = true;
+            if (rep.verifiedCount > 0) {
+                notes.push(`Target has ${rep.verifiedCount} SafeHands-verified on-chain action(s); positive track record.`);
+            }
+            if (reg.error)
+                notes.push(reg.error);
+        }
+        catch {
+            notes.push("on-chain SafeHands reputation unavailable");
+        }
+    }
+    // 2. Target profile: contract vs EOA + native balance (real on-chain reads).
+    if (target && isAddress(target)) {
+        try {
+            const [code, balance] = await withEnrichmentTimeout(Promise.all([
+                publicClient.getCode({ address: target }),
+                publicClient.getBalance({ address: target }),
+            ]), "target profile");
+            out.targetProfile = {
+                isContract: Boolean(code && code !== "0x"),
+                nativeBalancePROS: formatEther(balance),
+            };
+            out.enriched = true;
+        }
+        catch {
+            notes.push("target profile unavailable");
+        }
+    }
+    // 3. Live gas context.
+    try {
+        const gasPrice = await withEnrichmentTimeout(publicClient.getGasPrice(), "gas context");
+        out.gas = { gasPriceGwei: Number(formatGwei(gasPrice)) };
+        out.enriched = true;
+    }
+    catch {
+        notes.push("gas context unavailable");
+    }
+    notes.push("security signals in this enrichment are on-chain reads (contract profile + SafeHands reputation oracle); GoPlus token-security intelligence is applied separately by the token-security check");
+    return out;
+}
+//# sourceMappingURL=agentEnrich.js.map

package/dist/agent/agentEnrich.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentEnrich.js","sourceRoot":"","sources":["../../src/agent/agentEnrich.ts"],"names":[],"mappings":"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"}

package/dist/agent/agentIntentClassifier.d.ts

@@ -0,0 +1,44 @@
+/** Canonical Permit2 singleton (lowercased). */
+export declare const PERMIT2_ADDRESS = "0x000000000022d473030f116ddee9f6b43ac78ba3";
+export type AgentIntent = "tx_hash_check" | "contract_check" | "raw_transaction_intent" | "erc20_approval" | "permit2_approval" | "safe_transaction" | "x402_payment_request" | "native_transfer" | "unknown_contract_call" | "policy_question" | "risk_explanation";
+/** A request to the SafeHands Agent. Every field optional — the agent decides. */
+export interface AgentRequest {
+    /** Free-text question (used for policy/risk-explanation intents). */
+    text?: string;
+    /** Transaction target. */
+    to?: string;
+    /** Calldata, e.g. 0x095ea7b3… */
+    data?: string;
+    /** Value in wei (decimal or 0x-hex string). */
+    value?: string;
+    /** Existing transaction hash to inspect. */
+    txHash?: string;
+    /** Explicit contract address to vet (contract_check). */
+    address?: string;
+    /** Token contract an approval targets. */
+    token?: string;
+    /** x402 resource URL. */
+    url?: string;
+    paymentAmountUsdc?: string;
+    paymentTokenAddress?: string;
+    payTo?: string;
+    agentId?: string;
+    network?: string;
+    chainId?: number;
+    /** Optional ecosystem provider hint (e.g. "LayerZero") — evidence only. */
+    provider?: string;
+    /** Optional ecosystem category hint (e.g. "cross_chain") — evidence only. */
+    ecosystemCategory?: string;
+    /** Optional explicit override of the classification. */
+    inputType?: AgentIntent;
+}
+export interface IntentResult {
+    intent: AgentIntent;
+    /** 0..1 — 1.0 for unambiguous structural matches, lower for text heuristics. */
+    confidence: number;
+    /** Human-readable signals that led to the classification. */
+    signals: string[];
+}
+/** Classify a request into a SafeHands intent. Deterministic and offline. */
+export declare function classifyIntent(req: AgentRequest): IntentResult;
+//# sourceMappingURL=agentIntentClassifier.d.ts.map

package/dist/agent/agentIntentClassifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentIntentClassifier.d.ts","sourceRoot":"","sources":["../../src/agent/agentIntentClassifier.ts"],"names":[],"mappings":"AASA,gDAAgD;AAChD,eAAO,MAAM,eAAe,+CAA+C,CAAC;AAI5E,MAAM,MAAM,WAAW,GACnB,eAAe,GACf,gBAAgB,GAChB,wBAAwB,GACxB,gBAAgB,GAChB,kBAAkB,GAClB,kBAAkB,GAClB,sBAAsB,GACtB,iBAAiB,GACjB,uBAAuB,GACvB,iBAAiB,GACjB,kBAAkB,CAAC;AAEvB,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAgBD,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CAyD9D"}

package/dist/agent/agentIntentClassifier.js

@@ -0,0 +1,77 @@
+// ─── SafeHands Agent — Intent Classifier (read-only) ──────────
+// Deterministic, offline classification of a user/agent request into one of the
+// supported SafeHands intents. Pure: no RPC, no keys, no side effects. The
+// classifier only *labels* a request — it never executes anything.
+// ────────────────────────────────────────────────────────────────────────
+import { APPROVE_SELECTOR } from "../lib/analysis/approval.js";
+import { MULTISEND_SELECTOR, SAFE_EXEC_SELECTOR } from "../lib/analysis/safeTx.js";
+/** Canonical Permit2 singleton (lowercased). */
+export const PERMIT2_ADDRESS = "0x000000000022d473030f116ddee9f6b43ac78ba3";
+/** Permit2.approve(token,spender,amount,expiration) selector. */
+const PERMIT2_APPROVE_SELECTOR = "0x87517c45";
+function selectorOf(data) {
+    if (!data || !data.startsWith("0x") || data.length < 10)
+        return null;
+    return data.slice(0, 10).toLowerCase();
+}
+function valuePositive(value) {
+    if (value === undefined)
+        return false;
+    try {
+        return BigInt(value) > 0n;
+    }
+    catch {
+        return false;
+    }
+}
+/** Classify a request into a SafeHands intent. Deterministic and offline. */
+export function classifyIntent(req) {
+    if (req.inputType) {
+        return { intent: req.inputType, confidence: 1, signals: ["explicit inputType override"] };
+    }
+    const selector = selectorOf(req.data);
+    const hasValue = valuePositive(req.value);
+    const lowerTo = (req.to ?? req.token ?? "").toLowerCase();
+    if (req.txHash) {
+        return { intent: "tx_hash_check", confidence: 1, signals: ["txHash present"] };
+    }
+    if (req.url || req.paymentAmountUsdc !== undefined) {
+        return { intent: "x402_payment_request", confidence: 1, signals: ["x402 url/payment fields present"] };
+    }
+    if (selector) {
+        if (selector === APPROVE_SELECTOR || selector === PERMIT2_APPROVE_SELECTOR) {
+            if (selector === PERMIT2_APPROVE_SELECTOR || lowerTo === PERMIT2_ADDRESS) {
+                return { intent: "permit2_approval", confidence: 1, signals: ["Permit2 approval selector/target"] };
+            }
+            return { intent: "erc20_approval", confidence: 1, signals: ["ERC-20 approve selector"] };
+        }
+        if (selector === MULTISEND_SELECTOR || selector === SAFE_EXEC_SELECTOR) {
+            return { intent: "safe_transaction", confidence: 1, signals: ["Safe/MultiSend selector"] };
+        }
+        return {
+            intent: hasValue ? "raw_transaction_intent" : "unknown_contract_call",
+            confidence: 0.9,
+            signals: [hasValue ? "value-bearing call with unrecognized selector" : "unrecognized calldata selector"],
+        };
+    }
+    if (hasValue) {
+        return { intent: "native_transfer", confidence: 1, signals: ["positive value, no calldata"] };
+    }
+    if (req.address && !req.to) {
+        return { intent: "contract_check", confidence: 1, signals: ["explicit contract address"] };
+    }
+    const text = (req.text ?? "").toLowerCase();
+    if (text) {
+        if (/\bpolic(y|ies)\b|\blimit\b|\ballow ?list\b|\btrusted\b/.test(text)) {
+            return { intent: "policy_question", confidence: 0.7, signals: ["policy keywords in text"] };
+        }
+        if (/\bexplain\b|\bwhy\b|\bwhat does\b|\brisk\b|\bmean(s)?\b/.test(text)) {
+            return { intent: "risk_explanation", confidence: 0.7, signals: ["explanation keywords in text"] };
+        }
+    }
+    if (req.to) {
+        return { intent: "unknown_contract_call", confidence: 0.6, signals: ["target present, intent ambiguous"] };
+    }
+    return { intent: "unknown_contract_call", confidence: 0.3, signals: ["no actionable fields"] };
+}
+//# sourceMappingURL=agentIntentClassifier.js.map

package/dist/agent/agentIntentClassifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentIntentClassifier.js","sourceRoot":"","sources":["../../src/agent/agentIntentClassifier.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,gFAAgF;AAChF,2EAA2E;AAC3E,mEAAmE;AACnE,2EAA2E;AAE3E,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEnF,gDAAgD;AAChD,MAAM,CAAC,MAAM,eAAe,GAAG,4CAA4C,CAAC;AAC5E,iEAAiE;AACjE,MAAM,wBAAwB,GAAG,YAAY,CAAC;AAuD9C,SAAS,UAAU,CAAC,IAAa;IAC/B,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,EAAE;QAAE,OAAO,IAAI,CAAC;IACrE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AACzC,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,cAAc,CAAC,GAAiB;IAC9C,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;QAClB,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,6BAA6B,CAAC,EAAE,CAAC;IAC5F,CAAC;IAED,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAE1D,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QACf,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,gBAAgB,CAAC,EAAE,CAAC;IACjF,CAAC;IAED,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QACnD,OAAO,EAAE,MAAM,EAAE,sBAAsB,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,iCAAiC,CAAC,EAAE,CAAC;IACzG,CAAC;IAED,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,QAAQ,KAAK,gBAAgB,IAAI,QAAQ,KAAK,wBAAwB,EAAE,CAAC;YAC3E,IAAI,QAAQ,KAAK,wBAAwB,IAAI,OAAO,KAAK,eAAe,EAAE,CAAC;gBACzE,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,kCAAkC,CAAC,EAAE,CAAC;YACtG,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,yBAAyB,CAAC,EAAE,CAAC;QAC3F,CAAC;QACD,IAAI,QAAQ,KAAK,kBAAkB,IAAI,QAAQ,KAAK,kBAAkB,EAAE,CAAC;YACvE,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,yBAAyB,CAAC,EAAE,CAAC;QAC7F,CAAC;QACD,OAAO;YACL,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,uBAAuB;YACrE,UAAU,EAAE,GAAG;YACf,OAAO,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,+CAA+C,CAAC,CAAC,CAAC,gCAAgC,CAAC;SACzG,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,6BAA6B,CAAC,EAAE,CAAC;IAChG,CAAC;IAED,IAAI,GAAG,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QAC3B,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,2BAA2B,CAAC,EAAE,CAAC;IAC7F,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5C,IAAI,IAAI,EAAE,CAAC;QACT,IAAI,wDAAwD,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACxE,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,yBAAyB,CAAC,EAAE,CAAC;QAC9F,CAAC;QACD,IAAI,yDAAyD,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACzE,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,8BAA8B,CAAC,EAAE,CAAC;QACpG,CAAC;IACH,CAAC;IAED,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC;QACX,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,kCAAkC,CAAC,EAAE,CAAC;IAC7G,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,sBAAsB,CAAC,EAAE,CAAC;AACjG,CAAC"}

package/dist/agent/agentPolicyResolver.d.ts

@@ -0,0 +1,44 @@
+import type { GuardianDecision } from "../lib/guardian/decision.js";
+import type { AgentIntent, AgentRequest } from "./agentIntentClassifier.js";
+/** Who owns the policy. backend = the public default; the rest are advanced. */
+export type PolicyOwner = "backend" | "user" | "dapp" | "agent";
+export interface GuardianPolicy {
+    /** Max native transfer (wei) before confirmation is required. */
+    maxNativeTransferWei: string;
+    /** Max ERC-20 approval amount (raw token units) before confirmation. */
+    maxApprovalAmount: string;
+    /** Max single x402 payment (USDC) before confirmation. */
+    maxX402PaymentUsdc: string;
+    /** Max cumulative daily agent spend (USDC) — advisory ceiling. */
+    maxDailyAgentSpendUsdc: string;
+    /** Recipients exempt from the native-transfer confirmation (annotated, not relaxed past BLOCK). */
+    trustedRecipients: string[];
+    /** Spenders treated as known for approvals (annotation only). */
+    trustedSpenders: string[];
+    /** Escalate unlimited approvals to BLOCK even for known spenders. */
+    blockUnlimitedApproval: boolean;
+    /** Require confirmation for any unknown / unrecognized contract call. */
+    requireConfirmationForUnknownContract: boolean;
+}
+/** The public default backend policy (conservative, read-only). */
+export declare const DEFAULT_BACKEND_POLICY: GuardianPolicy;
+/** Merge owner defaults with explicit overrides. */
+export declare function resolvePolicy(owner?: PolicyOwner, overrides?: Partial<GuardianPolicy>): GuardianPolicy;
+export interface PolicyOutcome {
+    decision: GuardianDecision;
+    reasons: string[];
+    notes: string[];
+    escalated: boolean;
+}
+/**
+ * Apply policy to a base (analyzer) decision. Escalates severity only.
+ * @param analyzerDetails the primary analyzer's `details` object (read-only).
+ */
+export declare function applyPolicy(args: {
+    base: GuardianDecision;
+    intent: AgentIntent;
+    req: AgentRequest;
+    policy: GuardianPolicy;
+    analyzerDetails?: Record<string, unknown>;
+}): PolicyOutcome;
+//# sourceMappingURL=agentPolicyResolver.d.ts.map

package/dist/agent/agentPolicyResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentPolicyResolver.d.ts","sourceRoot":"","sources":["../../src/agent/agentPolicyResolver.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE5E,gFAAgF;AAChF,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEhE,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kEAAkE;IAClE,sBAAsB,EAAE,MAAM,CAAC;IAC/B,mGAAmG;IACnG,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,iEAAiE;IACjE,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,qEAAqE;IACrE,sBAAsB,EAAE,OAAO,CAAC;IAChC,yEAAyE;IACzE,qCAAqC,EAAE,OAAO,CAAC;CAChD;AAED,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,EAAE,cASpC,CAAC;AAEF,oDAAoD;AACpD,wBAAgB,aAAa,CAAC,KAAK,GAAE,WAAuB,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAIjH;AASD,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAWD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB,GAAG,EAAE,YAAY,CAAC;IAClB,MAAM,EAAE,cAAc,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C,GAAG,aAAa,CA+ChB"}

package/dist/agent/agentPolicyResolver.js

@@ -0,0 +1,94 @@
+// ─── SafeHands Agent — Policy Resolver (read-only) ────────────
+// Configurable SafeHands policy and an ESCALATE-ONLY enforcement step. Policy may
+// only raise severity (ALLOW → REQUIRE_CONFIRMATION → BLOCK) or annotate — it can
+// never relax a BLOCK or weaken an analyzer verdict. Pure: no RPC, no keys.
+// ────────────────────────────────────────────────────────────────────────
+import { isUnlimitedApprovalAmount } from "../lib/policy/actionPolicyEngine.js";
+/** The public default backend policy (conservative, read-only). */
+export const DEFAULT_BACKEND_POLICY = {
+    maxNativeTransferWei: "10000000000000000000", // 10 native
+    maxApprovalAmount: "1000000000000", // 1e12 raw units
+    maxX402PaymentUsdc: "1",
+    maxDailyAgentSpendUsdc: "100",
+    trustedRecipients: [],
+    trustedSpenders: [],
+    blockUnlimitedApproval: true,
+    requireConfirmationForUnknownContract: true,
+};
+/** Merge owner defaults with explicit overrides. */
+export function resolvePolicy(owner = "backend", overrides) {
+    // Every owner currently starts from the conservative backend baseline.
+    void owner;
+    return { ...DEFAULT_BACKEND_POLICY, ...(overrides ?? {}) };
+}
+const SEVERITY = { BLOCK: 3, REQUIRE_CONFIRMATION: 2, PREPARE_ONLY: 1, ALLOW: 0 };
+/** Return the more severe of two decisions (escalate-only). */
+function escalate(current, to) {
+    return SEVERITY[to] > SEVERITY[current] ? to : current;
+}
+function bigintOrNull(v) {
+    if (typeof v !== "string" && typeof v !== "number" && typeof v !== "bigint")
+        return null;
+    try {
+        return BigInt(v);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Apply policy to a base (analyzer) decision. Escalates severity only.
+ * @param analyzerDetails the primary analyzer's `details` object (read-only).
+ */
+export function applyPolicy(args) {
+    const { intent, req, policy } = args;
+    const details = args.analyzerDetails ?? {};
+    let decision = args.base;
+    const reasons = [];
+    const notes = [];
+    const before = decision;
+    if (intent === "native_transfer") {
+        const value = bigintOrNull(req.value);
+        const max = bigintOrNull(policy.maxNativeTransferWei);
+        const trusted = req.to && policy.trustedRecipients.map((r) => r.toLowerCase()).includes(req.to.toLowerCase());
+        if (trusted)
+            notes.push(`Recipient ${req.to} is in trustedRecipients.`);
+        if (value !== null && max !== null && value > max && !trusted) {
+            decision = escalate(decision, "REQUIRE_CONFIRMATION");
+            reasons.push(`Native transfer ${value} wei exceeds policy max ${policy.maxNativeTransferWei} wei.`);
+        }
+    }
+    else if (intent === "erc20_approval" || intent === "permit2_approval") {
+        const unlimited = details.unlimited === true || (typeof details.amountRaw === "string" && isUnlimitedApprovalAmount(details.amountRaw));
+        const spender = typeof details.spender === "string" ? details.spender : null;
+        const trusted = spender && policy.trustedSpenders.map((s) => s.toLowerCase()).includes(spender.toLowerCase());
+        if (trusted)
+            notes.push(`Spender ${spender} is in trustedSpenders.`);
+        if (unlimited && policy.blockUnlimitedApproval) {
+            decision = escalate(decision, "BLOCK");
+            reasons.push("Policy blocks unlimited approvals (blockUnlimitedApproval=true).");
+        }
+        const amount = bigintOrNull(details.amountRaw);
+        const max = bigintOrNull(policy.maxApprovalAmount);
+        if (!unlimited && amount !== null && max !== null && amount > max && !trusted) {
+            decision = escalate(decision, "REQUIRE_CONFIRMATION");
+            reasons.push(`Approval amount ${amount} exceeds policy max ${policy.maxApprovalAmount}.`);
+        }
+    }
+    else if (intent === "x402_payment_request") {
+        const amt = Number(details.paymentAmountUsdc ?? req.paymentAmountUsdc);
+        const max = Number(policy.maxX402PaymentUsdc);
+        if (Number.isFinite(amt) && Number.isFinite(max) && amt > max) {
+            decision = escalate(decision, "REQUIRE_CONFIRMATION");
+            reasons.push(`x402 payment ${amt} USDC exceeds policy max ${policy.maxX402PaymentUsdc} USDC.`);
+        }
+    }
+    else if (intent === "unknown_contract_call" || intent === "raw_transaction_intent") {
+        if (policy.requireConfirmationForUnknownContract) {
+            decision = escalate(decision, "REQUIRE_CONFIRMATION");
+            reasons.push("Policy requires confirmation for unknown/unrecognized contract calls.");
+        }
+    }
+    return { decision, reasons, notes, escalated: SEVERITY[decision] > SEVERITY[before] };
+}
+//# sourceMappingURL=agentPolicyResolver.js.map

package/dist/agent/agentPolicyResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentPolicyResolver.js","sourceRoot":"","sources":["../../src/agent/agentPolicyResolver.ts"],"names":[],"mappings":"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"}

package/dist/agent/agentRuntime.d.ts

@@ -0,0 +1,12 @@
+import type { GuardianDecision } from "../lib/guardian/decision.js";
+/** What the calling agent is obligated to do. */
+export type CallerObligation = "proceed" | "stop" | "ask_user_or_admin" | "prepare_handoff_no_execute";
+export interface ObligationSpec {
+    obligation: CallerObligation;
+    /** One-line caller responsibility. */
+    responsibility: string;
+}
+/** The public Agent-to-Agent contract, keyed by SafeHands decision. */
+export declare const OBLIGATION_CONTRACT: Record<GuardianDecision, ObligationSpec>;
+export declare function obligationFor(decision: GuardianDecision): ObligationSpec;
+//# sourceMappingURL=agentRuntime.d.ts.map

package/dist/agent/agentRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentRuntime.d.ts","sourceRoot":"","sources":["../../src/agent/agentRuntime.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,iDAAiD;AACjD,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,MAAM,GACN,mBAAmB,GACnB,4BAA4B,CAAC;AAEjC,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,gBAAgB,EAAE,cAAc,CAiBxE,CAAC;AAEF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,gBAAgB,GAAG,cAAc,CAExE"}

package/dist/agent/agentRuntime.js

@@ -0,0 +1,31 @@
+// ─── SafeHands Agent — Runtime & Agent-to-Agent Contract ──────
+// The A2A obligation contract: what a CALLING agent must do given a SafeHands
+// decision. SafeHands only advises — it never executes. The caller is solely
+// responsible for honoring the obligation. Leaf module: no value imports from
+// the agent/formatter (keeps the module graph acyclic).
+// ────────────────────────────────────────────────────────────────────────
+/** The public Agent-to-Agent contract, keyed by SafeHands decision. */
+export const OBLIGATION_CONTRACT = {
+    ALLOW: {
+        obligation: "proceed",
+        responsibility: "Caller MAY proceed. SafeHands found no blocking risk; the caller still executes externally.",
+    },
+    BLOCK: {
+        obligation: "stop",
+        responsibility: "Caller MUST stop. The action is unsafe and must not be executed.",
+    },
+    REQUIRE_CONFIRMATION: {
+        obligation: "ask_user_or_admin",
+        responsibility: "Caller MUST pause and obtain explicit user/admin confirmation before any execution.",
+    },
+    PREPARE_ONLY: {
+        obligation: "prepare_handoff_no_execute",
+        responsibility: "Caller MUST NOT execute. It may only prepare/hand off the action; execution is disabled here.",
+    },
+};
+export function obligationFor(decision) {
+    return OBLIGATION_CONTRACT[decision];
+}
+// NOTE: the former describeObligation / GuardianAgentLike / runScenario exports
+// were removed as dead code — no consumer in src/, test/, or scripts/ used them.
+//# sourceMappingURL=agentRuntime.js.map