@decentrys/agent 0.1.0

package/src/explain.ts

@@ -0,0 +1,204 @@
+/**
+ * Turning a decision into something a person can be held to.
+ *
+ * The question this file exists to answer is not "why was that blocked" — a
+ * block explains itself, loudly, at the moment it happens. It is **"why was
+ * that allowed"**, asked weeks later by someone looking at a drained account.
+ * A record that lists only what went wrong cannot answer it, so
+ * `explainAgentAction` renders every rule that was applied, the bound it
+ * carried and the value it saw, alongside the axes on which the policy set no
+ * bound at all. An allow with nothing behind it reads, correctly, as an allow
+ * with nothing behind it.
+ *
+ * Nothing here recomputes anything. The explanation is a rendering of the
+ * decision record and cannot disagree with it — an explanation that is
+ * generated separately from the decision eventually explains a decision that
+ * was not made.
+ */
+
+import { RISK_LEVEL_MEANING } from '@decentrys/protect';
+
+import type { AgentDecision, AgentRuleId, AgentVerdict, RuleEvaluation } from './model';
+
+export interface AgentActionExplanation {
+  decisionId: string;
+  agentId: string;
+  verdict: AgentVerdict;
+  /** One sentence. What happened and, at the top level, why. */
+  headline: string;
+  /** The failing or escalating rules, in the words they recorded. */
+  because: string[];
+  /**
+   * Every rule that ran, passes included. This is the part that makes an
+   * allow explainable rather than merely unobjected-to.
+   */
+  rulesApplied: RuleEvaluation[];
+  /**
+   * Axes this policy left unbounded.
+   *
+   * An operator reading an allow deserves to know the difference between "the
+   * rate ceiling was checked and this was the third action this minute" and
+   * "there is no rate ceiling". Both produce a pass in the eyes of a summary;
+   * only one of them is a control.
+   */
+  unbounded: string[];
+  /**
+   * What would have to change for this to be permitted.
+   *
+   * Addressed to the operator, who is the only party that can change a sealed
+   * policy. The agent can read this and still cannot act on it, which is the
+   * point of `sealPolicy`.
+   */
+  toProceed: string[];
+  /** Enough to reproduce the decision against the same inputs. */
+  provenance: {
+    policyFingerprint: string;
+    policyVersion?: string;
+    actionDigest: string;
+    modelVersion: string;
+    riskModelVersion?: string;
+    riskLevel?: string;
+    decidedAt: string;
+  };
+  /** A plain-text rendering, for a log line, a ticket or a human review queue. */
+  text: string;
+}
+
+const VERDICT_HEADLINE: Record<AgentVerdict, string> = {
+  allow: 'Permitted',
+  require_human_approval: 'Held for human approval',
+  deny: 'Denied',
+};
+
+/** What an operator would change, per rule, to permit the action. */
+const REMEDIATION: Record<AgentRuleId, string> = {
+  AGENT_BINDING: 'Use the policy sealed for this agent, or bind this policy to it.',
+  ACTION_TYPE: 'Add this action type to `allowedActions`, or remove it from `deniedActions`.',
+  CHAIN: 'Add this chain to `allowedChains`.',
+  COUNTERPARTY: 'Add this counterparty to `allowedCounterparties`, or remove it from `blockedCounterparties`.',
+  CONTRACT: 'Add this contract to `allowedContracts`.',
+  TOKEN: 'Add this token to `allowedTokens`.',
+  APPROVAL_ALLOWANCE: 'Have the agent request a bounded allowance, or set `allowUnlimitedApprovals` — '
+    + 'which makes any later compromise of the spender unbounded.',
+  VALUE_PER_ACTION: 'Raise `maxValuePerActionUsd`, or state the action\'s `valueUsd`.',
+  CUMULATIVE_SPEND: 'Wait for the window to roll over, raise the window\'s `maxValueUsd`, or state the '
+    + 'action\'s `valueUsd`.',
+  RATE_LIMIT: 'Wait for the window to roll over, or raise the window\'s `maxActions`. A rate ceiling being '
+    + 'hit repeatedly is usually the agent looping, not the ceiling being wrong.',
+  RISK_LEVEL: 'A person should review the evidence on the decision\'s assessment before this is permitted.',
+  ASSESSMENT_AVAILABILITY: 'Restore connectivity to Decentrys, or accept unscreened actions by setting '
+    + '`failMode: \'open\'` — which signs during precisely the window an attacker would choose.',
+  HUMAN_APPROVAL_THRESHOLD: 'A person must approve this action. Raise the threshold only if the operator '
+    + 'intends actions of this size to proceed unattended.',
+};
+
+export function explainAgentAction(decision: AgentDecision): AgentActionExplanation {
+  const failing = decision.evaluations.filter((e) => e.outcome === 'fail');
+  const escalating = decision.evaluations.filter((e) => e.outcome === 'escalate');
+  const blocking = [...failing, ...escalating];
+
+  const headline = buildHeadline(decision, failing, escalating);
+  const because = blocking.map((e) => e.statement);
+
+  const unbounded = decision.evaluations
+    .filter((e) => e.outcome === 'not_configured')
+    .map((e) => e.statement);
+
+  // Deduplicated: two rules can share a remedy, and telling an operator the
+  // same thing twice trains them to skim the list.
+  const toProceed = [...new Set(blocking.map((e) => REMEDIATION[e.rule]))];
+
+  const explanation: AgentActionExplanation = {
+    decisionId: decision.decisionId,
+    agentId: decision.agentId,
+    verdict: decision.verdict,
+    headline,
+    because,
+    rulesApplied: decision.evaluations,
+    unbounded,
+    toProceed,
+    provenance: {
+      policyFingerprint: decision.policyFingerprint,
+      ...(decision.policyVersion === undefined ? {} : { policyVersion: decision.policyVersion }),
+      actionDigest: decision.actionDigest,
+      modelVersion: decision.modelVersion,
+      ...(decision.assessment === undefined ? {} : {
+        riskModelVersion: decision.assessment.modelVersion,
+        riskLevel: decision.assessment.riskLevel,
+      }),
+      decidedAt: decision.decidedAt,
+    },
+    text: '',
+  };
+
+  explanation.text = render(decision, explanation);
+  return explanation;
+}
+
+function buildHeadline(
+  decision: AgentDecision, failing: RuleEvaluation[], escalating: RuleEvaluation[],
+): string {
+  const prefix = VERDICT_HEADLINE[decision.verdict];
+  if (decision.verdict === 'allow') {
+    const checked = decision.evaluations.filter((e) => e.outcome === 'pass').length;
+    const unconfigured = decision.evaluations.filter((e) => e.outcome === 'not_configured').length;
+    return `${prefix}: ${checked} ${checked === 1 ? 'rule' : 'rules'} were applied and passed`
+      + (unconfigured > 0
+        ? `, and ${unconfigured} ${unconfigured === 1 ? 'axis was' : 'axes were'} left unbounded by this policy.`
+        : '.');
+  }
+  const driving = failing[0] ?? escalating[0];
+  return driving
+    ? `${prefix}: ${driving.statement}`
+    : `${prefix}.`;
+}
+
+function render(decision: AgentDecision, explanation: AgentActionExplanation): string {
+  const lines: string[] = [
+    `${explanation.headline}`,
+    '',
+    `Agent:    ${decision.agentId}`,
+    `Decision: ${decision.decisionId} at ${decision.decidedAt}`,
+    `Policy:   ${decision.policyVersion ? `${decision.policyVersion} ` : ''}#${decision.policyFingerprint}`,
+    `Action:   #${decision.actionDigest}`,
+  ];
+
+  if (decision.assessment) {
+    lines.push(
+      `Risk:     ${decision.assessment.riskLevel} `
+      + `(confidence ${decision.assessment.confidence}) — `
+      + `${RISK_LEVEL_MEANING[decision.assessment.riskLevel]}`,
+    );
+  } else if (decision.assessmentUnavailable) {
+    lines.push(`Risk:     not assessed — ${decision.assessmentUnavailable}`);
+  }
+
+  lines.push('', 'Rules applied:');
+  for (const rule of decision.evaluations) {
+    const bound = rule.limit === undefined ? '' : `  [limit ${rule.limit}]`;
+    const seen = rule.observed === undefined ? '' : `  [observed ${rule.observed}]`;
+    lines.push(`  ${symbolFor(rule.outcome)} ${rule.rule}: ${rule.statement}${bound}${seen}`);
+  }
+
+  if (explanation.unbounded.length > 0) {
+    lines.push('', 'Left unbounded by this policy:');
+    for (const line of explanation.unbounded) lines.push(`  - ${line}`);
+  }
+
+  if (explanation.toProceed.length > 0) {
+    lines.push('', 'For this to proceed, the operator would have to:');
+    for (const line of explanation.toProceed) lines.push(`  - ${line}`);
+  }
+
+  return lines.join('\n');
+}
+
+function symbolFor(outcome: RuleEvaluation['outcome']): string {
+  switch (outcome) {
+    case 'pass': return 'PASS ';
+    case 'fail': return 'FAIL ';
+    case 'escalate': return 'HOLD ';
+    case 'not_applicable': return 'n/a  ';
+    case 'not_configured': return 'unset';
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './model';
+export * from './policy';
+export * from './ledger';
+export * from './explain';
+export * from './client';

package/src/ledger.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, it } from 'vitest';
+import { SpendLedger, isReservationLedger } from './ledger';
+
+/**
+ * The ledger is where a cumulative limit either works or quietly does not.
+ *
+ * Its whole job is to be right about time and about double-counting: a hold
+ * that never expires strangles an agent that crashed, a hold that expires too
+ * eagerly lets one through, and a retry counted twice shrinks a budget the
+ * operator set. None of these fail loudly — they fail as a number being
+ * wrong — so they are tested against an injected clock rather than by waiting.
+ */
+
+const T0 = new Date('2026-09-06T12:00:00Z').getTime();
+const AGENT = 'agent-1';
+
+function ledgerAt(nowMs: { value: number }, options: { reservationTtlMs?: number; retentionMs?: number } = {}) {
+  return new SpendLedger({ ...options, clock: () => nowMs.value });
+}
+
+describe('reservations', () => {
+  /**
+   * The race this exists to close. An agent asking a hundred times before the
+   * first answer is recorded would otherwise get a hundred allows against a
+   * cap of one.
+   */
+  it('counts a held reservation immediately, before anything is confirmed', () => {
+    const now = { value: T0 };
+    const ledger = ledgerAt(now);
+
+    ledger.reserve({ decisionId: 'd1', agentId: AGENT, valueUsd: 400 });
+
+    expect(ledger.spentUsdSince(AGENT, T0 - 60_000)).toBe(400);
+    expect(ledger.reservation('d1')?.state).toBe('held');
+  });
+
+  it('keeps the value once the action is confirmed', () => {
+    const now = { value: T0 };
+    const ledger = ledgerAt(now);
+    ledger.reserve({ decisionId: 'd1', agentId: AGENT, valueUsd: 400 });
+
+    const outcome = ledger.confirm('d1', { txHash: '0xabc' });
+
+    expect(outcome?.state).toBe('confirmed');
+    expect(outcome?.txHash).toBe('0xabc');
+    expect(ledger.spentUsdSince(AGENT, T0 - 60_000)).toBe(400);
+  });
+
+  it('returns the value to the budget when the action did not happen', () => {
+    const now = { value: T0 };
+    const ledger = ledgerAt(now);
+    ledger.reserve({ decisionId: 'd1', agentId: AGENT, valueUsd: 400 });
+
+    ledger.release('d1', { note: 'the swap route disappeared' });
+
+    expect(ledger.spentUsdSince(AGENT, T0 - 60_000)).toBe(0);
+  });
+
+  /**
+   * An agent that crashed between the allow and the broadcast must not hold
+   * its own budget until the window rolls over — that is an outage caused by
+   * the guard rather than by anything dangerous.
+   */
+  it('expires a hold nobody settled, and gives the budget back', () => {
+    const now = { value: T0 };
+    const ledger = ledgerAt(now, { reservationTtlMs: 300_000 });
+    ledger.reserve({ decisionId: 'd1', agentId: AGENT, valueUsd: 400 });
+
+    now.value = T0 + 299_000;
+    expect(ledger.spentUsdSince(AGENT, T0 - 60_000)).toBe(400);
+
+    now.value = T0 + 301_000;
+    expect(ledger.spentUsdSince(AGENT, T0 - 60_000)).toBe(0);
+    expect(ledger.reservation('d1')?.state).toBe('expired');
+  });
+
+  /**
+   * A spend that lands after its hold lapsed is real money that escaped the
+   * cap. The total is corrected, and the record says the TTL let it through
+   * rather than quietly absorbing it — that is a tuning signal, not noise.
+   */
+  it('records that a hold had already lapsed when a late confirmation arrives', () => {
+    const now = { value: T0 };
+    const ledger = ledgerAt(now, { reservationTtlMs: 60_000 });
+    ledger.reserve({ decisionId: 'd1', agentId: AGENT, valueUsd: 400 });
+
+    now.value = T0 + 120_000;
+    ledger.spentUsdSince(AGENT, 0); // triggers expiry
+    const outcome = ledger.confirm('d1');
+
+    expect(outcome?.state).toBe('confirmed');
+    expect(outcome?.note).toMatch(/already expired/i);
+    expect(ledger.spentUsdSince(AGENT, 0)).toBe(400);
+  });
+
+  /**
+   * A retry after a timeout is one action. Counting it twice would tighten an
+   * agent's own cap against it for no reason — and would do so precisely when
+   * the network is already unreliable.
+   */
+  it('does not charge a retried action twice', () => {
+    const now = { value: T0 };
+    const ledger = ledgerAt(now);
+
+    const first = ledger.reserve({ decisionId: 'd1', agentId: AGENT, valueUsd: 400, idempotencyKey: 'task-7' });
+    const second = ledger.reserve({ decisionId: 'd2', agentId: AGENT, valueUsd: 400, idempotencyKey: 'task-7' });
+
+    expect(second.decisionId).toBe(first.decisionId);
+    expect(ledger.spentUsdSince(AGENT, 0)).toBe(400);
+  });
+
+  /** Idempotency keys are the caller's, so one agent's cannot collide with another's. */
+  it('namespaces idempotency keys per agent', () => {
+    const now = { value: T0 };
+    const ledger = ledgerAt(now);
+
+    ledger.reserve({ decisionId: 'd1', agentId: 'agent-a', valueUsd: 400, idempotencyKey: 'task-7' });
+    ledger.reserve({ decisionId: 'd2', agentId: 'agent-b', valueUsd: 400, idempotencyKey: 'task-7' });
+
+    expect(ledger.spentUsdSince('agent-a', 0)).toBe(400);
+    expect(ledger.spentUsdSince('agent-b', 0)).toBe(400);
+  });
+
+  /** A negative value would be a credit against the agent's own cap. */
+  it('refuses to let a negative value buy back budget', () => {
+    const now = { value: T0 };
+    const ledger = ledgerAt(now);
+
+    ledger.reserve({ decisionId: 'd1', agentId: AGENT, valueUsd: 1_000 });
+    ledger.reserve({ decisionId: 'd2', agentId: AGENT, valueUsd: -900 });
+
+    expect(ledger.spentUsdSince(AGENT, 0)).toBe(1_000);
+  });
+
+  it('ignores a value that is not a number at all', () => {
+    const now = { value: T0 };
+    const ledger = ledgerAt(now);
+    ledger.reserve({ decisionId: 'd1', agentId: AGENT, valueUsd: Number.NaN });
+
+    expect(ledger.spentUsdSince(AGENT, 0)).toBe(0);
+  });
+
+  it('settles nothing for a decision it never issued', () => {
+    const ledger = ledgerAt({ value: T0 });
+    expect(ledger.confirm('never-existed')).toBeNull();
+    expect(ledger.release('never-existed')).toBeNull();
+  });
+});
+
+describe('retention', () => {
+  /**
+   * Retention must outlive the longest policy window, or a cumulative cap
+   * silently stops being cumulative — the most dangerous kind of expiry,
+   * because the guard keeps answering and the answers become wrong.
+   */
+  it('drops entries only once they are older than the retention period', () => {
+    const now = { value: T0 };
+    const ledger = ledgerAt(now, { retentionMs: 86_400_000 });
+    ledger.reserve({ decisionId: 'd1', agentId: AGENT, valueUsd: 400 });
+    ledger.confirm('d1');
+
+    now.value = T0 + 86_000_000;
+    expect(ledger.list(AGENT)).toHaveLength(1);
+
+    now.value = T0 + 90_000_000;
+    ledger.spentUsdSince(AGENT, 0);
+    expect(ledger.list(AGENT)).toHaveLength(0);
+  });
+
+  it('hands out copies, so a caller cannot edit the ledger through them', () => {
+    const ledger = ledgerAt({ value: T0 });
+    ledger.reserve({ decisionId: 'd1', agentId: AGENT, valueUsd: 400 });
+
+    const snapshot = ledger.list();
+    snapshot[0]!.valueUsd = 0;
+
+    expect(ledger.spentUsdSince(AGENT, 0)).toBe(400);
+  });
+});
+
+describe('isReservationLedger', () => {
+  /**
+   * A read-only usage source (a warehouse query, a metrics store) can answer
+   * how much an agent has spent without being able to take a hold. The guard
+   * has to be able to tell, because the difference is invisible until two
+   * concurrent actions that each fit under a cap are both admitted.
+   */
+  it('distinguishes a source that can hold budget from one that can only be read', () => {
+    expect(isReservationLedger(new SpendLedger())).toBe(true);
+    expect(isReservationLedger({ spentUsdSince: () => 0, actionsSince: () => 0 })).toBe(false);
+  });
+});