@decentrys/agent 0.1.0

package/src/ledger.ts

@@ -0,0 +1,303 @@
+/**
+ * Cumulative spend and rate accounting.
+ *
+ * ## What this is, honestly
+ *
+ * **This ledger is in-process and in-memory.** It counts what one instance of
+ * one process admitted. It is not shared, not durable, and not correct across
+ * a restart or a horizontal scale-out: two replicas each enforcing a $10,000
+ * daily cap enforce $20,000 between them, and a restart resets the day to
+ * zero.
+ *
+ * That is stated rather than papered over, and the shape of the API is chosen
+ * so it can be fixed without a rewrite: `evaluatePolicy` depends only on the
+ * `AgentUsage` interface below, so a Redis- or Postgres-backed implementation
+ * of two methods replaces this class entirely. A distributed limit needs
+ * shared storage with atomic reservation, which is a later concern and a real
+ * one — do not deploy a fleet of agents behind this class and describe the cap
+ * as enforced.
+ *
+ * ## Why reservations, rather than counting on the way out
+ *
+ * An agent asks "may I", gets an allow, and then signs. If budget were only
+ * counted when the transaction is confirmed, an agent could ask a hundred
+ * times before the first answer was recorded and get a hundred allows against
+ * a cap of one. So an admitted decision holds its value immediately, and the
+ * hold is released when the caller says the action did not happen or when it
+ * expires unclaimed. The failure direction is a briefly over-tight budget,
+ * which is the right way for this to be wrong.
+ */
+
+import type { AgentOutcomeRecord } from './model';
+
+/**
+ * What `evaluatePolicy` needs to know about the past.
+ *
+ * Deliberately two read methods and nothing else. Anything satisfying this can
+ * be handed to the evaluator — including a shared store, which is how this
+ * becomes correct across processes.
+ */
+export interface AgentUsage {
+  /** Value held or committed by this agent at or after `sinceMs`. */
+  spentUsdSince(agentId: string, sinceMs: number): number;
+  /** Decisions this guard admitted for the agent at or after `sinceMs`. */
+  actionsSince(agentId: string, sinceMs: number): number;
+}
+
+/**
+ * A usage source that can also hold budget.
+ *
+ * Kept separate from `AgentUsage` because the two are genuinely different
+ * capabilities: a read-only source (a warehouse query, a metrics store) can
+ * answer "how much has this agent spent today" without being able to take a
+ * hold. `AgentGuard` accepts either, and says which it got — a guard running
+ * on a read-only source enforces cumulative caps against *settled* history
+ * only, which cannot stop two concurrent actions that each fit alone.
+ */
+export interface ReservationLedger extends AgentUsage {
+  reserve(input: {
+    decisionId: string;
+    agentId: string;
+    valueUsd: number;
+    idempotencyKey?: string;
+    now?: Date;
+  }): Reservation;
+  confirm(decisionId: string, options?: { txHash?: string; now?: Date }): AgentOutcomeRecord | null;
+  release(decisionId: string, options?: { note?: string; now?: Date }): AgentOutcomeRecord | null;
+}
+
+export function isReservationLedger(usage: AgentUsage): usage is ReservationLedger {
+  const candidate = usage as Partial<ReservationLedger>;
+  return typeof candidate.reserve === 'function'
+    && typeof candidate.confirm === 'function'
+    && typeof candidate.release === 'function';
+}
+
+export type ReservationState = 'held' | 'confirmed' | 'released' | 'expired';
+
+export interface Reservation {
+  decisionId: string;
+  agentId: string;
+  valueUsd: number;
+  idempotencyKey?: string;
+  state: ReservationState;
+  createdAtMs: number;
+  expiresAtMs: number;
+  settledAtMs?: number;
+  txHash?: string;
+  note?: string;
+}
+
+export interface SpendLedgerOptions {
+  /**
+   * How long an unsettled hold survives. Default 5 minutes — long enough for a
+   * signature and a broadcast, short enough that an agent that crashed
+   * mid-action does not hold its budget until the window rolls over.
+   */
+  reservationTtlMs?: number;
+  /**
+   * How long settled entries are kept. Must exceed the longest policy window,
+   * or a cumulative cap silently stops being cumulative. Default 8 days.
+   */
+  retentionMs?: number;
+  /** A hard ceiling on entries, so a runaway agent cannot exhaust memory. */
+  maxEntries?: number;
+  /**
+   * The clock, injected for the same reason Protect injects `fetch`: expiry
+   * and retention are time-dependent behaviour, and behaviour that can only be
+   * exercised by waiting is behaviour that does not get tested.
+   */
+  clock?: () => number;
+}
+
+const DEFAULT_RESERVATION_TTL_MS = 5 * 60_000;
+const DEFAULT_RETENTION_MS = 8 * 24 * 60 * 60_000;
+const DEFAULT_MAX_ENTRIES = 50_000;
+
+export class SpendLedger implements ReservationLedger {
+  private readonly reservationTtlMs: number;
+  private readonly retentionMs: number;
+  private readonly maxEntries: number;
+  private readonly clock: () => number;
+  private readonly entries: Reservation[] = [];
+  private readonly byDecision = new Map<string, Reservation>();
+  private readonly byIdempotencyKey = new Map<string, Reservation>();
+
+  constructor(options: SpendLedgerOptions = {}) {
+    this.reservationTtlMs = options.reservationTtlMs ?? DEFAULT_RESERVATION_TTL_MS;
+    this.retentionMs = options.retentionMs ?? DEFAULT_RETENTION_MS;
+    this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    this.clock = options.clock ?? (() => Date.now());
+  }
+
+  /**
+   * Hold budget for an admitted decision.
+   *
+   * A repeated `idempotencyKey` returns the existing hold instead of taking a
+   * second one. An agent retrying a call after a timeout is one action, and
+   * counting it twice would tighten its own cap against it for no reason.
+   */
+  reserve(input: {
+    decisionId: string;
+    agentId: string;
+    valueUsd: number;
+    idempotencyKey?: string;
+    now?: Date;
+  }): Reservation {
+    const nowMs = input.now ? input.now.getTime() : this.clock();
+    this.prune(nowMs);
+
+    if (input.idempotencyKey) {
+      const existing = this.byIdempotencyKey.get(this.keyFor(input.agentId, input.idempotencyKey));
+      if (existing && existing.state !== 'released' && existing.state !== 'expired') return existing;
+    }
+
+    const reservation: Reservation = {
+      decisionId: input.decisionId,
+      agentId: input.agentId,
+      // A negative value would be a credit against the agent's own cap, which
+      // is a way to spend more than the cap allows. Clamped, not trusted.
+      valueUsd: Number.isFinite(input.valueUsd) ? Math.max(0, input.valueUsd) : 0,
+      ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+      state: 'held',
+      createdAtMs: nowMs,
+      expiresAtMs: nowMs + this.reservationTtlMs,
+    };
+
+    this.entries.push(reservation);
+    this.byDecision.set(reservation.decisionId, reservation);
+    if (input.idempotencyKey) {
+      this.byIdempotencyKey.set(this.keyFor(input.agentId, input.idempotencyKey), reservation);
+    }
+    this.enforceCeiling();
+    return reservation;
+  }
+
+  /** The action happened. The hold becomes a permanent commitment. */
+  confirm(decisionId: string, options: { txHash?: string; now?: Date } = {}): AgentOutcomeRecord | null {
+    return this.settle(decisionId, 'confirmed', {
+      ...(options.txHash === undefined ? {} : { txHash: options.txHash }),
+      ...(options.now === undefined ? {} : { now: options.now }),
+    });
+  }
+
+  /** The action did not happen. The hold is returned to the budget. */
+  release(decisionId: string, options: { note?: string; now?: Date } = {}): AgentOutcomeRecord | null {
+    return this.settle(decisionId, 'released', {
+      ...(options.note === undefined ? {} : { note: options.note }),
+      ...(options.now === undefined ? {} : { now: options.now }),
+    });
+  }
+
+  /**
+   * Value held or committed in the window.
+   *
+   * Released and expired holds do not count. They are actions that did not
+   * happen, and charging an agent for them would shrink a cap the operator
+   * set for real spending.
+   */
+  spentUsdSince(agentId: string, sinceMs: number): number {
+    this.prune(this.clock());
+    let total = 0;
+    for (const entry of this.entries) {
+      if (entry.agentId !== agentId) continue;
+      if (entry.state === 'released' || entry.state === 'expired') continue;
+      if (entry.createdAtMs < sinceMs) continue;
+      total += entry.valueUsd;
+    }
+    return total;
+  }
+
+  /**
+   * Decisions admitted in the window — regardless of how they settled.
+   *
+   * A rate ceiling counts what the guard admitted, not what landed on chain.
+   * An agent that spins through assess-and-abandon at machine speed is exactly
+   * the loop the ceiling exists to catch, and it would be invisible to a
+   * counter that only saw confirmed transactions.
+   */
+  actionsSince(agentId: string, sinceMs: number): number {
+    this.prune(this.clock());
+    let count = 0;
+    for (const entry of this.entries) {
+      if (entry.agentId !== agentId) continue;
+      if (entry.createdAtMs < sinceMs) continue;
+      count += 1;
+    }
+    return count;
+  }
+
+  reservation(decisionId: string): Reservation | undefined {
+    return this.byDecision.get(decisionId);
+  }
+
+  /** Snapshot for inspection. Copies, so a caller cannot edit the ledger. */
+  list(agentId?: string): Reservation[] {
+    return this.entries
+      .filter((entry) => !agentId || entry.agentId === agentId)
+      .map((entry) => ({ ...entry }));
+  }
+
+  clear(): void {
+    this.entries.length = 0;
+    this.byDecision.clear();
+    this.byIdempotencyKey.clear();
+  }
+
+  // -------------------------------------------------------------------------
+
+  private settle(
+    decisionId: string, state: 'confirmed' | 'released',
+    options: { txHash?: string; note?: string; now?: Date },
+  ): AgentOutcomeRecord | null {
+    const now = options.now ?? new Date(this.clock());
+    const entry = this.byDecision.get(decisionId);
+    if (!entry) return null;
+    // An expired hold that later confirms is a real and dangerous case: the
+    // budget was already returned, so the spend happened outside the cap. It
+    // is recorded as confirmed so the total is right, and the note says the
+    // hold had lapsed, because that is a tuning signal for the TTL.
+    const lapsed = entry.state === 'expired';
+    entry.state = state;
+    entry.settledAtMs = now.getTime();
+    if (options.txHash !== undefined) entry.txHash = options.txHash;
+    if (options.note !== undefined) entry.note = options.note;
+
+    return {
+      decisionId,
+      state,
+      ...(entry.txHash === undefined ? {} : { txHash: entry.txHash }),
+      ...(lapsed
+        ? { note: 'The hold had already expired when this was settled; the reservation TTL may be too short.' }
+        : entry.note === undefined ? {} : { note: entry.note }),
+      at: now.toISOString(),
+    };
+  }
+
+  private prune(nowMs: number): void {
+    for (const entry of this.entries) {
+      if (entry.state === 'held' && entry.expiresAtMs <= nowMs) entry.state = 'expired';
+    }
+    for (let i = this.entries.length - 1; i >= 0; i -= 1) {
+      const entry = this.entries[i]!;
+      if (nowMs - entry.createdAtMs <= this.retentionMs) continue;
+      this.entries.splice(i, 1);
+      this.byDecision.delete(entry.decisionId);
+      if (entry.idempotencyKey) this.byIdempotencyKey.delete(this.keyFor(entry.agentId, entry.idempotencyKey));
+    }
+  }
+
+  private enforceCeiling(): void {
+    while (this.entries.length > this.maxEntries) {
+      const entry = this.entries.shift();
+      if (!entry) break;
+      this.byDecision.delete(entry.decisionId);
+      if (entry.idempotencyKey) this.byIdempotencyKey.delete(this.keyFor(entry.agentId, entry.idempotencyKey));
+    }
+  }
+
+  /** Idempotency keys are the caller's, so they are namespaced per agent. */
+  private keyFor(agentId: string, idempotencyKey: string): string {
+    return `${agentId}${idempotencyKey}`;
+  }
+}

package/src/model.ts

@@ -0,0 +1,324 @@
+/**
+ * AgentGuard — the types.
+ *
+ * Protect informs a person, who then decides. AgentGuard sits in front of
+ * something with no judgement that will do exactly what it was told, at
+ * machine speed, as many times as its loop runs. Three consequences shape
+ * everything in this file:
+ *
+ *  1. **A warning is not a control.** Protect deliberately warns and never
+ *     blocks, because the person holding the keys should decide. An agent
+ *     cannot heed a warning — a warning it ignores is an allow with extra
+ *     words. So AgentGuard's outcomes are `allow`, `require_human_approval`
+ *     and `deny`, and the middle one means *stop and hand this to a person*.
+ *
+ *  2. **The operator is not the agent.** Limits are set by a human ahead of
+ *     time. The agent must not be able to widen them — not by argument, not by
+ *     mutating the object it was handed, not by passing an override. That is
+ *     enforced structurally in `policy.ts` (`sealPolicy`, `narrowPolicy`),
+ *     not by convention.
+ *
+ *  3. **Every decision must survive being questioned later.** "The agent spent
+ *     the treasury" is answered by an audit record that names each rule, the
+ *     limit it enforced and the value it observed. An allow that cannot be
+ *     explained is as bad as a wrong one, so a passing rule is recorded just
+ *     as loudly as a failing one.
+ *
+ * The risk model is *not* reimplemented here. Classification, the seven risk
+ * levels and `applyPolicy` come from `@decentrys/protect` unchanged; this
+ * package adds the limits an autonomous actor needs and a human does not.
+ */
+
+import type { Assessment, Policy, RiskLevel } from '@decentrys/protect';
+
+export const AGENT_MODEL_VERSION = 'agent-1.0.0';
+
+// ---------------------------------------------------------------------------
+// What an agent proposes to do
+// ---------------------------------------------------------------------------
+
+/**
+ * The kinds of action a policy can talk about.
+ *
+ * These are coarse on purpose. "May swap, may not approve" is a sentence an
+ * operator can write and check; "may call selector 0x095ea7b3" is not. An
+ * action whose type the integrator cannot determine is `unknown`, which is a
+ * first-class value rather than a default — see `deniedActions` below.
+ */
+export const AGENT_ACTION_TYPES = [
+  'transfer',
+  'swap',
+  'approve',
+  'contract_call',
+  'bridge',
+  'stake',
+  'unstake',
+  'deploy',
+  'sign_message',
+  'unknown',
+] as const;
+export type AgentActionType = (typeof AGENT_ACTION_TYPES)[number];
+
+export interface AgentAction {
+  /** Which agent proposes it. Limits are held per agent, not per process. */
+  agentId: string;
+  chain: string;
+  type: AgentActionType;
+  /** The wallet the agent signs with. */
+  from: string;
+  /** Counterparty or contract. Absent for a deploy or a bare message signature. */
+  to?: string;
+  /** Token contract, for a transfer, swap or approval. */
+  token?: string;
+  /** Base units, as a string. Numbers lose precision at these magnitudes. */
+  value?: string;
+  /**
+   * The action's value in USD, as the integrator prices it.
+   *
+   * **`undefined` is not zero.** An action with no value at all (a message
+   * signature, a zero-value call) should say `0`; leaving this out means "I do
+   * not know what this is worth", and a value cap cannot be enforced against
+   * an unknown. See `VALUE_UNKNOWN` in `policy.ts` for what happens then, and
+   * why it is the only defensible answer for an autonomous signer.
+   *
+   * AgentGuard never prices anything itself. Pricing belongs to whoever runs
+   * the agent, with the feed and the staleness rules they are willing to be
+   * accountable for.
+   */
+  valueUsd?: number;
+  /** EVM calldata. */
+  data?: string;
+  /** Non-EVM families carry their serialized payload here. */
+  raw?: string;
+  /** The site or service that asked for this, when there is one. */
+  origin?: string;
+  /** Base units, or `unlimited`. Only meaningful for `type: 'approve'`. */
+  approvalAmount?: string;
+  /** What the agent believes it is doing, in its own words. Recorded, never trusted. */
+  intent?: string;
+  /**
+   * Set by the caller so a retried action is not counted twice against a
+   * cumulative cap. Two calls carrying the same key reuse one reservation.
+   */
+  idempotencyKey?: string;
+  proposedAt?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Policy
+// ---------------------------------------------------------------------------
+
+/** A cumulative limit: how much may be committed inside a rolling window. */
+export interface SpendWindow {
+  /** A name an operator recognises in an audit record — 'daily', 'per-hour'. */
+  label: string;
+  windowMs: number;
+  maxValueUsd: number;
+}
+
+/** A rate ceiling: how many actions may be admitted inside a rolling window. */
+export interface RateWindow {
+  label: string;
+  windowMs: number;
+  maxActions: number;
+}
+
+/**
+ * What an operator can express.
+ *
+ * Every field is optional and every omitted field means *unconstrained on that
+ * axis* — with one deliberate exception, `allowUnlimitedApprovals`, which
+ * defaults to refusing. An unlimited approval is the single action that turns
+ * a bounded mistake into an unbounded one, and defaulting it open would make
+ * the safe configuration the one you have to remember to write.
+ */
+export interface AgentPolicy {
+  /** Free text for the operator's own change control. Recorded in every decision. */
+  version?: string;
+  /**
+   * Bind this policy to one agent. When set, an action from a different
+   * `agentId` is denied rather than evaluated — a policy leaking across agents
+   * is how one agent's generous limits become another's.
+   */
+  agentId?: string;
+
+  // --- risk, from @decentrys/protect ---------------------------------------
+
+  /**
+   * Risk level → action, exactly the `Policy` type Protect uses. Merged over
+   * `DEFAULT_AGENT_RISK_POLICY`; see that constant for why the agent default
+   * differs from the consumer one.
+   */
+  risk?: Policy;
+  /** Shorthand: deny anything strictly above this level. Applied on top of `risk`. */
+  maxRiskLevel?: RiskLevel;
+
+  // --- value ---------------------------------------------------------------
+
+  maxValuePerActionUsd?: number;
+  /** Rolling cumulative caps. Several may run at once — per-hour and per-day. */
+  spendWindows?: SpendWindow[];
+
+  // --- counterparties and contracts ----------------------------------------
+
+  /**
+   * When present, an allowlist: any counterparty not in it is denied. Absent
+   * means unconstrained, which is a real choice an operator may make and not
+   * one AgentGuard makes for them.
+   */
+  allowedCounterparties?: string[];
+  /** Always denied, even if also allowlisted. Denial wins. */
+  blockedCounterparties?: string[];
+  /** When present, an allowlist over the contract the action calls. */
+  allowedContracts?: string[];
+  /** When present, an allowlist over `token`. */
+  allowedTokens?: string[];
+
+  // --- what the agent may do -----------------------------------------------
+
+  allowedActions?: AgentActionType[];
+  deniedActions?: AgentActionType[];
+  allowedChains?: string[];
+  /** Default `false`. Set true only if an unbounded allowance is genuinely intended. */
+  allowUnlimitedApprovals?: boolean;
+
+  // --- rate ----------------------------------------------------------------
+
+  /** An agent stuck in a loop is a real failure mode, not a hypothetical one. */
+  rateWindows?: RateWindow[];
+
+  // --- escalation and availability -----------------------------------------
+
+  /** Above this value, a human decides even when every other rule passes. */
+  humanApprovalAboveUsd?: number;
+  /** At or above this level, a human decides even when the risk policy allows. */
+  humanApprovalAtRiskLevel?: RiskLevel;
+  /** What to do when Decentrys could not be reached. Default `escalate`. */
+  failMode?: AgentFailMode;
+}
+
+/**
+ * What AgentGuard does when the risk check could not run.
+ *
+ * Protect offers `open | warn | closed` and defaults to `warn`, which is right
+ * for a wallet: tell the person, let them decide. **`warn` is not offered
+ * here, because there is nobody to warn.** A warning delivered to an
+ * autonomous process is an allow that logs.
+ *
+ *  - `open`     — proceed on operator-set limits alone.
+ *  - `escalate` — the local policy still applies and still binds; only the
+ *                 external risk check is missing, so a human decides. **Default.**
+ *  - `closed`   — stop.
+ *
+ * `escalate` is the default because it is the only one of the three that
+ * loses nothing. `open` signs unscreened transactions during exactly the
+ * window an attacker would choose to create. `closed` halts the agent
+ * completely, which for a liquidation or a market-making agent is its own
+ * loss and pushes operators to configure `open` to avoid it. `escalate`
+ * spends a human's attention instead of the treasury, and where an integrator
+ * has no approval path it degrades to a stop — the safe direction.
+ *
+ * Note that a local rule that *denies* still denies during an outage. An
+ * unreachable Decentrys removes one input; it does not suspend the operator's
+ * limits.
+ */
+export type AgentFailMode = 'open' | 'escalate' | 'closed';
+
+// ---------------------------------------------------------------------------
+// Decisions
+// ---------------------------------------------------------------------------
+
+/**
+ * Three outcomes, never two.
+ *
+ * Collapsing `require_human_approval` into `deny` loses the difference between
+ * "this must not happen" and "a person needs to look at this", and an operator
+ * who cannot see that difference in the log cannot tune the policy.
+ */
+export type AgentVerdict = 'allow' | 'require_human_approval' | 'deny';
+
+/** The rules AgentGuard can apply. Stable identifiers — they end up in logs. */
+export const AGENT_RULES = [
+  'AGENT_BINDING',
+  'ACTION_TYPE',
+  'CHAIN',
+  'COUNTERPARTY',
+  'CONTRACT',
+  'TOKEN',
+  'APPROVAL_ALLOWANCE',
+  'VALUE_PER_ACTION',
+  'CUMULATIVE_SPEND',
+  'RATE_LIMIT',
+  'RISK_LEVEL',
+  'ASSESSMENT_AVAILABILITY',
+  'HUMAN_APPROVAL_THRESHOLD',
+] as const;
+export type AgentRuleId = (typeof AGENT_RULES)[number];
+
+/**
+ * `not_configured` and `not_applicable` are distinct and both are recorded.
+ *
+ * "There was no counterparty allowlist" and "there was one and this
+ * counterparty was on it" produce the same allow and mean completely
+ * different things to whoever reads the record afterwards.
+ */
+export type RuleOutcome = 'pass' | 'fail' | 'escalate' | 'not_applicable' | 'not_configured';
+
+export interface RuleEvaluation {
+  rule: AgentRuleId;
+  outcome: RuleOutcome;
+  /** One sentence naming the limit and what was seen against it. */
+  statement: string;
+  /** The configured bound, when there was one. */
+  limit?: string | number;
+  /** What this action presented against that bound. */
+  observed?: string | number;
+}
+
+export interface AgentDecision {
+  /** Stable id for this decision, carried into the reservation and the log. */
+  decisionId: string;
+  agentId: string;
+  verdict: AgentVerdict;
+  /** The failing or escalating rules, in evaluation order. Empty on a clean allow. */
+  reasons: string[];
+  /**
+   * Every rule that was considered, passing ones included.
+   *
+   * This is what makes an *allow* explainable. A record that lists only what
+   * went wrong cannot answer "why was this permitted", which is the question
+   * asked after the money is gone.
+   */
+  evaluations: RuleEvaluation[];
+  /** The Protect assessment this decision used, when one was obtained. */
+  assessment?: Assessment;
+  /** Why no assessment was available, when none was. */
+  assessmentUnavailable?: string;
+  /** Fingerprint of the sealed policy in force, so the record is reproducible. */
+  policyFingerprint: string;
+  policyVersion?: string;
+  /**
+   * Present on `allow` and `require_human_approval`. Value and rate budget is
+   * held against this id until it is confirmed or released; see `ledger.ts`.
+   */
+  reservationId?: string;
+  /** A digest of the action, so a log entry can be tied to what was proposed. */
+  actionDigest: string;
+  modelVersion: string;
+  decidedAt: string;
+}
+
+/**
+ * What actually happened to a reserved action.
+ *
+ * Recorded separately from the decision, because "AgentGuard allowed it" and
+ * "the agent then executed it" are different facts and an audit trail that
+ * conflates them cannot show an allow that was never used.
+ */
+export interface AgentOutcomeRecord {
+  decisionId: string;
+  state: 'confirmed' | 'released' | 'expired';
+  txHash?: string;
+  note?: string;
+  at: string;
+}