@decentrys/agent 0.1.0

package/src/client.ts

@@ -0,0 +1,392 @@
+/**
+ * AgentGuard — the client an operator wires in front of an agent.
+ *
+ * The contract differs from both of its neighbours, and the difference is the
+ * product.
+ *
+ *  - **Protect never throws and never blocks.** It sits between a person and a
+ *    signing screen; a security service having a bad minute must not cost
+ *    someone their transaction, and the person decides.
+ *  - **Sentinel throws.** It is management tooling, and an operator who
+ *    believes they are monitored when they are not is worse off than one who
+ *    saw an error.
+ *  - **AgentGuard returns a verdict, and the verdict can be `deny`.** Nothing
+ *    here throws on a call path either — an exception thrown at an agent is a
+ *    condition it will handle by retrying, or by taking the branch that skips
+ *    the guard. A decision object it must read is harder to route around.
+ *
+ * The one place this does throw is the constructor, on a missing credential or
+ * an unsealed policy. That is a wiring error made by a human at deploy time,
+ * not an event during an agent's run.
+ */
+
+import {
+  Decentrys, type Assessment, type CallOptions, type DecentrysConfig, type FetchLike,
+  type Transport,
+} from '@decentrys/protect';
+
+import type { AgentAction, AgentDecision, AgentOutcomeRecord, AgentPolicy } from './model';
+import { type SealedPolicy, evaluatePolicy, narrowPolicy, newDecisionId } from './policy';
+import {
+  SpendLedger, isReservationLedger, type AgentUsage, type ReservationLedger,
+} from './ledger';
+import { type AgentActionExplanation, explainAgentAction } from './explain';
+
+export const AGENT_SDK_VERSION = '0.1.0';
+
+const DEFAULT_AUDIT_LOG_ENTRIES = 1_000;
+
+export interface AgentGuardConfig {
+  /**
+   * The operator's policy, already sealed.
+   *
+   * Typed as `SealedPolicy`, so a plain object cannot be passed here — an
+   * agent that constructs its own limits and hands them over does not
+   * typecheck and would not survive `sealPolicy`'s cloning if it did.
+   */
+  policy: SealedPolicy;
+  /** An existing Protect client. Supply this or `apiKey`. */
+  protect?: Decentrys;
+  apiKey?: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  retries?: number;
+  fetch?: FetchLike;
+  /** For tests, and for operators routing through their own gateway. */
+  transport?: Transport;
+  /**
+   * Where cumulative spend and rate state lives. Defaults to an in-process
+   * `SpendLedger` — read its file comment before running more than one
+   * instance, because a per-process cap on N processes is an N-times cap.
+   *
+   * A source that can only be read (see `ReservationLedger`) disables holds;
+   * `reservesBudget` reports which of the two this guard got.
+   */
+  ledger?: AgentUsage | ReservationLedger;
+  /** How many decisions to keep in memory for `auditLog()` / `explain()`. */
+  auditLogEntries?: number;
+  /**
+   * Called with every decision, before it is returned.
+   *
+   * The in-memory log is a convenience, not an audit trail: it dies with the
+   * process. This hook is where a real one is written. It is invoked
+   * synchronously and its exceptions are swallowed — a logging sink must not
+   * be able to change a verdict, in either direction.
+   */
+  onDecision?: (decision: AgentDecision) => void;
+}
+
+export interface AssessAgentTransactionOptions extends CallOptions {
+  /**
+   * A per-call restriction. It can only *narrow* — see `narrowPolicy`. There
+   * is no parameter anywhere in this class that widens a policy, which is what
+   * makes "the agent cannot raise its own limits" a property of the code
+   * rather than a rule someone has to remember.
+   */
+  restrict?: AgentPolicy;
+  /** An assessment the caller already holds, to avoid a second round trip. */
+  assessment?: Assessment;
+  now?: Date;
+}
+
+interface AuditEntry {
+  decision: AgentDecision;
+  outcome?: AgentOutcomeRecord;
+}
+
+export class AgentGuard {
+  private readonly protect: Decentrys;
+  private readonly sealed: SealedPolicy;
+  private readonly ledgerImpl: AgentUsage;
+  private readonly reserving: ReservationLedger | null;
+  private readonly auditEntries: AuditEntry[] = [];
+  private readonly auditLimit: number;
+  private readonly onDecision: ((decision: AgentDecision) => void) | undefined;
+
+  constructor(config: AgentGuardConfig) {
+    if (!config.policy || typeof config.policy !== 'object' || typeof config.policy.fingerprint !== 'string') {
+      throw new Error(
+        'AgentGuard: a sealed policy is required. Build one with sealPolicy({ ... }) at wiring time, '
+        + 'from a human-owned configuration — not from anything the agent produces.',
+      );
+    }
+
+    if (config.protect) {
+      this.protect = config.protect;
+    } else if (config.apiKey || config.transport) {
+      const protectConfig: DecentrysConfig = {
+        apiKey: config.apiKey ?? 'transport-provided',
+        // Protect's own failMode only shapes the wording of an unavailable
+        // assessment; AgentGuard's `failMode` decides what actually happens.
+        // Pinning it to `open` keeps the two from being applied twice.
+        failMode: 'open',
+        ...(config.baseUrl === undefined ? {} : { baseUrl: config.baseUrl }),
+        ...(config.timeoutMs === undefined ? {} : { timeoutMs: config.timeoutMs }),
+        ...(config.retries === undefined ? {} : { retries: config.retries }),
+        ...(config.fetch === undefined ? {} : { fetch: config.fetch }),
+        ...(config.transport === undefined ? {} : { transport: config.transport }),
+      };
+      this.protect = new Decentrys(protectConfig);
+    } else {
+      throw new Error(
+        'AgentGuard: pass an apiKey or an existing Decentrys client. Screening a counterparty is the '
+        + 'part of this that no local policy can do — an allowlist cannot tell you the address on it '
+        + 'was labelled malicious yesterday.',
+      );
+    }
+
+    this.sealed = config.policy;
+    this.ledgerImpl = config.ledger ?? new SpendLedger();
+    this.reserving = isReservationLedger(this.ledgerImpl) ? this.ledgerImpl : null;
+    this.auditLimit = config.auditLogEntries ?? DEFAULT_AUDIT_LOG_ENTRIES;
+    this.onDecision = config.onDecision;
+  }
+
+  /** The policy in force. Frozen — reading it is safe, changing it is impossible. */
+  get policy(): SealedPolicy {
+    return this.sealed;
+  }
+
+  /** Configurations that are legal but worth an operator's attention. */
+  get policyWarnings(): readonly string[] {
+    return this.sealed.warnings;
+  }
+
+  /**
+   * Whether admitted actions hold budget before they execute.
+   *
+   * False when the guard was given a read-only usage source. Cumulative caps
+   * then count settled history only, so two actions that each fit under the
+   * cap can both be admitted and together exceed it. Exposed rather than
+   * assumed, because the difference is invisible until it costs something.
+   */
+  get reservesBudget(): boolean {
+    return this.reserving !== null;
+  }
+
+  // -------------------------------------------------------------------------
+  // The main path
+  // -------------------------------------------------------------------------
+
+  /**
+   * Assess a proposed action and decide whether the agent may sign it.
+   *
+   * Screening happens first and always — including when a local rule has
+   * already failed. A record saying an action exceeded its value cap, while
+   * omitting that its counterparty was confirmed malicious, would send an
+   * operator to raise the cap and ship the same hole.
+   *
+   * On `allow` or `require_human_approval` the action's value and its slot in
+   * the rate window are held immediately; call `confirm()` when it lands or
+   * `release()` when it does not. The hold is taken synchronously in the same
+   * turn as the evaluation, so two concurrent calls in one process cannot both
+   * pass a cap that only one of them fits under. Across processes they can —
+   * see `ledger.ts`, which says so plainly.
+   */
+  async assessAgentTransaction(
+    action: AgentAction, options: AssessAgentTransactionOptions = {},
+  ): Promise<AgentDecision> {
+    const policy = options.restrict ? narrowPolicy(this.sealed, options.restrict) : this.sealed;
+    const decisionId = newDecisionId();
+
+    let assessment: Assessment | undefined = options.assessment;
+    if (!assessment) {
+      assessment = await this.screen(action, options);
+    }
+    const unavailable = unavailableReason(assessment);
+
+    // Everything from here down is synchronous. That is deliberate: an `await`
+    // between the evaluation and the reservation is the gap through which an
+    // agent's parallel calls each see the same untouched budget.
+    const decision = evaluatePolicy({
+      action,
+      policy,
+      assessment: unavailable ? null : assessment,
+      ...(unavailable === undefined ? {} : { assessmentUnavailable: unavailable }),
+      usage: this.ledgerImpl,
+      decisionId,
+      ...(options.now === undefined ? {} : { now: options.now }),
+    });
+
+    if (decision.verdict !== 'deny' && this.reserving) {
+      const reservation = this.reserving.reserve({
+        decisionId,
+        agentId: action.agentId,
+        // Reaching here with no stated value means no value-based rule was
+        // configured; if one had been, this would already be a denial.
+        valueUsd: action.valueUsd ?? 0,
+        ...(action.idempotencyKey === undefined ? {} : { idempotencyKey: action.idempotencyKey }),
+        ...(options.now === undefined ? {} : { now: options.now }),
+      });
+      decision.reservationId = reservation.decisionId;
+    }
+
+    this.record(decision);
+    return decision;
+  }
+
+  /**
+   * Decide without going to the network.
+   *
+   * For an operator replaying a decision against a different policy, and for
+   * an agent runtime that already holds an assessment. It applies the same
+   * rules; what it cannot do is discover that a counterparty was labelled
+   * since the assessment was taken.
+   */
+  evaluate(
+    action: AgentAction,
+    options: { assessment?: Assessment; assessmentUnavailable?: string; restrict?: AgentPolicy; now?: Date } = {},
+  ): AgentDecision {
+    const policy = options.restrict ? narrowPolicy(this.sealed, options.restrict) : this.sealed;
+    const decision = evaluatePolicy({
+      action,
+      policy,
+      assessment: options.assessment ?? null,
+      ...(options.assessment
+        ? {}
+        : { assessmentUnavailable: options.assessmentUnavailable ?? 'no assessment was supplied to evaluate()' }),
+      usage: this.ledgerImpl,
+      ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    this.record(decision);
+    return decision;
+  }
+
+  // -------------------------------------------------------------------------
+  // Settling
+  // -------------------------------------------------------------------------
+
+  /** The agent signed and broadcast it. The held value becomes committed. */
+  confirm(decisionId: string, options: { txHash?: string; now?: Date } = {}): AgentOutcomeRecord | null {
+    const outcome = this.reserving?.confirm(decisionId, options) ?? null;
+    if (outcome) this.attachOutcome(outcome);
+    return outcome;
+  }
+
+  /** The agent did not proceed. The held value returns to the budget. */
+  release(decisionId: string, options: { note?: string; now?: Date } = {}): AgentOutcomeRecord | null {
+    const outcome = this.reserving?.release(decisionId, options) ?? null;
+    if (outcome) this.attachOutcome(outcome);
+    return outcome;
+  }
+
+  // -------------------------------------------------------------------------
+  // The trail
+  // -------------------------------------------------------------------------
+
+  /**
+   * Explain a decision, by id or by value.
+   *
+   * Returns `null` for an id this process never made or no longer holds —
+   * stated rather than reconstructed, because an explanation assembled from a
+   * decision that is no longer in hand is a guess wearing a record's clothes.
+   */
+  explain(decision: AgentDecision | string): AgentActionExplanation | null {
+    if (typeof decision !== 'string') return explainAgentAction(decision);
+    const entry = this.auditEntries.find((e) => e.decision.decisionId === decision);
+    return entry ? explainAgentAction(entry.decision) : null;
+  }
+
+  /**
+   * Recent decisions, newest last.
+   *
+   * In memory and bounded; it does not survive a restart. Use `onDecision` for
+   * a trail that does. Saying which of the two this is matters — an operator
+   * who believes this is the audit log will discover otherwise at the worst
+   * possible moment.
+   */
+  auditLog(filter: { agentId?: string; verdict?: AgentDecision['verdict'] } = {}): AuditEntry[] {
+    return this.auditEntries
+      .filter((e) => (!filter.agentId || e.decision.agentId === filter.agentId))
+      .filter((e) => (!filter.verdict || e.decision.verdict === filter.verdict))
+      .map((e) => ({ decision: e.decision, ...(e.outcome ? { outcome: e.outcome } : {}) }));
+  }
+
+  /**
+   * A guard for a narrower task, sharing this one's ledger and client.
+   *
+   * The shared ledger is the point: a sub-task that spends against a tighter
+   * per-task cap still spends against the agent's daily one.
+   */
+  withPolicy(restriction: AgentPolicy): AgentGuard {
+    return new AgentGuard({
+      policy: narrowPolicy(this.sealed, restriction),
+      protect: this.protect,
+      ledger: this.ledgerImpl,
+      auditLogEntries: this.auditLimit,
+      ...(this.onDecision === undefined ? {} : { onDecision: this.onDecision }),
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+
+  /**
+   * Route the action to the right Protect endpoint.
+   *
+   * An approval is assessed on its spender *and its allowance together*,
+   * which is a different question from "is this transaction dangerous" and
+   * the one an unlimited approval turns on.
+   */
+  private async screen(action: AgentAction, options: CallOptions): Promise<Assessment> {
+    const call: CallOptions = {
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+      ...(options.skipCache === undefined ? {} : { skipCache: options.skipCache }),
+    };
+
+    if (action.type === 'approve' && action.token && action.to) {
+      const result = await this.protect.screenApproval({
+        chain: action.chain,
+        owner: action.from,
+        spender: action.to,
+        token: action.token,
+        ...(action.approvalAmount === undefined ? {} : { amount: action.approvalAmount }),
+      }, call);
+      return result.assessment;
+    }
+
+    const result = await this.protect.assessTransaction({
+      chain: action.chain,
+      from: action.from,
+      ...(action.to === undefined ? {} : { to: action.to }),
+      ...(action.value === undefined ? {} : { value: action.value }),
+      ...(action.data === undefined ? {} : { data: action.data }),
+      ...(action.raw === undefined ? {} : { raw: action.raw }),
+      ...(action.origin === undefined ? {} : { origin: action.origin }),
+    }, call);
+    return result.assessment;
+  }
+
+  private record(decision: AgentDecision): void {
+    this.auditEntries.push({ decision });
+    while (this.auditEntries.length > this.auditLimit) this.auditEntries.shift();
+    if (!this.onDecision) return;
+    try {
+      this.onDecision(decision);
+    } catch {
+      // A sink that throws must not turn a deny into an exception the agent
+      // handles by retrying, nor an allow into a failure. The decision stands.
+    }
+  }
+
+  private attachOutcome(outcome: AgentOutcomeRecord): void {
+    const entry = this.auditEntries.find((e) => e.decision.decisionId === outcome.decisionId);
+    if (entry) entry.outcome = outcome;
+  }
+}
+
+/**
+ * Distinguish "Decentrys answered, and found nothing" from "Decentrys did not
+ * answer".
+ *
+ * Protect never throws: an unreachable service produces an assessment whose
+ * `unknowns` say so. Both of those are `NO_CRITICAL_RISK_DETECTED` on the
+ * surface, and for an autonomous signer treating the second as the first is
+ * the whole failure — it is a clean bill of health issued by an outage.
+ */
+export function unavailableReason(assessment: Assessment | undefined): string | undefined {
+  if (!assessment) return 'no assessment was obtained';
+  const unknown = assessment.unknowns.find((u) => u.reason === 'PROVIDER_UNAVAILABLE');
+  return unknown ? unknown.statement : undefined;
+}

package/src/explain.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from 'vitest';
+import { classify, type Assessment } from '@decentrys/protect';
+
+import { evaluatePolicy, sealPolicy } from './policy';
+import { explainAgentAction } from './explain';
+import type { AgentAction } from './model';
+
+/**
+ * The question this file exists to answer is not "why was that blocked".
+ *
+ * A block explains itself, loudly, at the moment it happens. The hard question
+ * is **"why was that allowed"**, asked weeks later by someone looking at a
+ * drained account — and a record that lists only what went wrong cannot answer
+ * it at all.
+ */
+
+const NOW = new Date('2026-09-06T12:00:00Z');
+const AGENT = 'agent-treasury-1';
+const CLEAN: Assessment = classify({ now: NOW });
+
+function action(overrides: Partial<AgentAction> = {}): AgentAction {
+  return {
+    agentId: AGENT,
+    chain: 'ethereum',
+    type: 'transfer',
+    from: '0x1111111111111111111111111111111111111111',
+    to: '0x2222222222222222222222222222222222222222',
+    valueUsd: 250,
+    ...overrides,
+  };
+}
+
+describe('explaining an allow', () => {
+  const policy = sealPolicy({
+    version: '2026-09-treasury-v3',
+    maxValuePerActionUsd: 1_000,
+    allowedCounterparties: ['0x2222222222222222222222222222222222222222'],
+    spendWindows: [{ label: 'daily', windowMs: 86_400_000, maxValueUsd: 10_000 }],
+  });
+  const decision = evaluatePolicy({ action: action(), policy, assessment: CLEAN, now: NOW });
+  const explanation = explainAgentAction(decision);
+
+  it('names each rule that permitted it, with the limit and what was seen', () => {
+    expect(decision.verdict).toBe('allow');
+
+    const value = explanation.rulesApplied.find((r) => r.rule === 'VALUE_PER_ACTION');
+    expect(value?.outcome).toBe('pass');
+    expect(value?.limit).toBe(1_000);
+    expect(value?.observed).toBe(250);
+
+    expect(explanation.text).toContain('VALUE_PER_ACTION');
+    expect(explanation.text).toContain('[limit 1000]');
+    expect(explanation.text).toContain('[observed 250]');
+  });
+
+  /**
+   * The difference an operator most needs and is most often denied: "the rate
+   * ceiling was checked and this was the third action this minute" versus
+   * "there is no rate ceiling". A summary renders both as a pass.
+   */
+  it('separates what was checked from what was never bounded', () => {
+    expect(explanation.unbounded.join(' ')).toMatch(/no rate ceiling/i);
+    expect(explanation.headline).toMatch(/unbounded by this policy/);
+  });
+
+  /** An allow must be tied to the exact rules and the exact action it ran on. */
+  it('carries enough provenance to reproduce the decision', () => {
+    expect(explanation.provenance.policyFingerprint).toBe(policy.fingerprint);
+    expect(explanation.provenance.policyVersion).toBe('2026-09-treasury-v3');
+    expect(explanation.provenance.actionDigest).toBe(decision.actionDigest);
+    expect(explanation.provenance.riskLevel).toBe('NO_CRITICAL_RISK_DETECTED');
+    expect(explanation.provenance.riskModelVersion).toBe(CLEAN.modelVersion);
+  });
+
+  it('asks nothing of the operator when nothing needs changing', () => {
+    expect(explanation.because).toEqual([]);
+    expect(explanation.toProceed).toEqual([]);
+  });
+});
+
+describe('explaining a refusal', () => {
+  it('leads with the rule that stopped it and what the operator would change', () => {
+    const policy = sealPolicy({ maxValuePerActionUsd: 100 });
+    const decision = evaluatePolicy({
+      action: action({ valueUsd: 5_000 }), policy, assessment: CLEAN, now: NOW,
+    });
+    const explanation = explainAgentAction(decision);
+
+    expect(explanation.verdict).toBe('deny');
+    expect(explanation.headline).toMatch(/^Denied: /);
+    expect(explanation.because.join(' ')).toMatch(/exceeds the \$100 per-action cap/);
+    expect(explanation.toProceed.join(' ')).toMatch(/maxValuePerActionUsd/);
+  });
+
+  /**
+   * The remediation is addressed to the operator, who is the only party able
+   * to change a sealed policy. An agent can read it and still cannot act on
+   * it — which is what `sealPolicy` is for.
+   */
+  it('does not repeat itself when several rules share one remedy', () => {
+    const policy = sealPolicy({ allowedCounterparties: ['0xaaa'], blockedCounterparties: ['0xbbb'] });
+    const decision = evaluatePolicy({
+      action: action({ to: '0xbbb' }), policy, assessment: CLEAN, now: NOW,
+    });
+    const explanation = explainAgentAction(decision);
+
+    expect(new Set(explanation.toProceed).size).toBe(explanation.toProceed.length);
+  });
+
+  it('distinguishes a hold for a person from a refusal', () => {
+    const policy = sealPolicy({ humanApprovalAboveUsd: 100 });
+    const explanation = explainAgentAction(evaluatePolicy({
+      action: action({ valueUsd: 5_000 }), policy, assessment: CLEAN, now: NOW,
+    }));
+
+    expect(explanation.verdict).toBe('require_human_approval');
+    expect(explanation.headline).toMatch(/^Held for human approval/);
+    expect(explanation.text).toContain('HOLD ');
+  });
+
+  it('says plainly when no risk assessment was behind the decision', () => {
+    const explanation = explainAgentAction(evaluatePolicy({
+      action: action(), policy: sealPolicy({}), assessment: null,
+      assessmentUnavailable: 'timeout after 4000ms', now: NOW,
+    }));
+
+    expect(explanation.text).toMatch(/not assessed — timeout after 4000ms/);
+    expect(explanation.provenance.riskLevel).toBeUndefined();
+  });
+});
+
+describe('the explanation is a rendering, not a second opinion', () => {
+  /**
+   * An explanation generated separately from the decision eventually explains
+   * a decision that was not made. This one can only restate the record.
+   */
+  it('reports exactly the verdict and rules the decision recorded', () => {
+    const decision = evaluatePolicy({
+      action: action({ valueUsd: 5_000 }), policy: sealPolicy({ maxValuePerActionUsd: 100 }),
+      assessment: CLEAN, now: NOW,
+    });
+    const explanation = explainAgentAction(decision);
+
+    expect(explanation.verdict).toBe(decision.verdict);
+    expect(explanation.rulesApplied).toBe(decision.evaluations);
+    expect(explanation.decisionId).toBe(decision.decisionId);
+  });
+});