@agentguard-run/spend 0.15.1 → 0.15.3

package/src/frameworks/hermes-kanban.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from 'crypto';
+import { resolve as resolvePath } from 'path';
 import { inferProvider } from '../cost-table';
 import { canonicalJson, computeSignerFingerprint, sha256Hex } from '../decision-log';
 import { signDagNode, verifyReceiptDag, type ReceiptCapabilityLevel, type ReceiptDagEnvelope, type ReceiptDagNode } from '../receipts/dag';
@@ -7,7 +8,8 @@ import type { CallContext, CapabilityTier, Provider, SignedDecisionLogEntry, Spe
 import { safeRequestShape } from './common';
 
 export type HermesKanbanProfile = 'researcher' | 'writer' | 'reviewer' | 'director' | 'orchestrator' | string;
-export type HermesKanbanTaskState = 'governed' | 'running' | 'completed' | 'revoked';
+export type HermesKanbanTaskState = 'triage' | 'blocked' | 'scheduled' | 'running' | 'complete' | 'revoked';
+export type HermesKanbanGovernanceMode = 'lightweight' | 'full';
 
 export interface HermesKanbanProfilePolicy {
   capability: ReceiptCapabilityLevel;
@@ -23,6 +25,8 @@ export interface HermesKanbanAdapterOptions {
   defaultModel?: string;
   defaultCapCents?: number;
   runtimeBudgetCentsPerMinute?: number;
+  lightweightThresholdCents?: number;
+  lightweightCapabilityCeiling?: ReceiptCapabilityLevel;
   profileMap?: Record<string, HermesKanbanProfilePolicy>;
   reviewerCascade?: {
     enabled?: boolean;
@@ -39,6 +43,7 @@ export interface HermesKanbanTaskInput {
   boardSlug: string;
   profile: HermesKanbanProfile;
   parentTaskIds?: string[];
+  workspacePath?: string;
   maxRuntimeMinutes?: number;
   maxRuntimeMs?: number;
   metadata?: Record<string, unknown>;
@@ -56,6 +61,8 @@ export interface HermesKanbanEnvelope {
   capCents: number;
   parentTaskIds: string[];
   parentEntryHashes: string[];
+  workspacePath?: string;
+  governanceMode: HermesKanbanGovernanceMode;
   scope: SpendScope;
   builderCode?: string;
   createdAt: string;
@@ -101,6 +108,7 @@ export interface HermesKanbanReceiptInput {
   tokenCounts?: { inputTokens?: number; outputTokens?: number };
   totalCostCents?: number;
   metadata?: Record<string, unknown>;
+  workspacePath?: string;
   highRiskClassifierScore?: number;
   keywordRisk?: boolean;
   reviewerVerdict?: 'drafter_only' | 'review_required' | 'approved' | 'rejected';
@@ -146,6 +154,8 @@ const SAFE_METADATA_KEYS = new Set([
   'ticket_id',
   'token_count',
   'workflow_id',
+  'workspace_hash',
+  'workspace_path',
 ]);
 
 export function createHermesKanbanAdapter(opts: HermesKanbanAdapterOptions): HermesKanbanAdapter {
@@ -177,12 +187,14 @@ export class HermesKanbanAdapter {
       taskHash,
       boardHash,
       profile: normalizeProfile(input.profile),
-      state: 'governed',
+      state: 'running',
       capabilityCeiling: profilePolicy.capability,
       toolAllowlist: [...(profilePolicy.toolAllowlist ?? [])],
       capCents,
       parentTaskIds: [...new Set(input.parentTaskIds ?? [])],
       parentEntryHashes: [],
+      workspacePath: resolveWorkspacePath(input.workspacePath),
+      governanceMode: governanceModeFor(profilePolicy.capability, capCents, this.opts),
       scope,
       builderCode: safeBuilderCode(input.builderCode),
       createdAt: new Date().toISOString(),
@@ -263,17 +275,21 @@ export class HermesKanbanAdapter {
     };
   }
 
-  async revokeTask(taskId: string): Promise<HermesKanbanReceiptResult> {
+  async revokeTask(taskId: string, reason = 'stale_lock_reclaimed'): Promise<HermesKanbanReceiptResult> {
     const envelope = this.requireEnvelope(taskId);
     if (envelope.state === 'revoked') return this.receiptResult(envelope, this.requireNode(taskId));
     envelope.state = 'revoked';
     envelope.revokedAt = new Date().toISOString();
+    const finalSpendCents = this.spendCentsSoFar(taskId);
     const node = await this.signTaskNode(envelope, {
       event: 'revoked',
       action: 'block',
       blocked: true,
       capability: envelope.capabilityCeiling,
       trustScore: 0.7,
+      revocationReason: safeLabel(reason) ?? 'stale_lock_reclaimed',
+      finalSpendCents,
+      postRevocationSpendCents: 0,
     });
     this.nodesByTaskId.set(taskId, node);
     this.nodes.push(node);
@@ -284,7 +300,8 @@ export class HermesKanbanAdapter {
     const envelope = this.requireEnvelope(input.taskId);
     assertActive(envelope);
     assertMetadataOnly(input.metadata ?? {});
-    envelope.state = 'completed';
+    if (input.workspacePath) envelope.workspacePath = resolveWorkspacePath(input.workspacePath);
+    envelope.state = 'complete';
     envelope.completedAt = new Date().toISOString();
     const parentTaskIds = [...new Set(input.parentTaskIds ?? envelope.parentTaskIds)];
     const parentNodes = parentTaskIds.map((id) => this.nodesByTaskId.get(id)).filter(Boolean) as ReceiptDagNode[];
@@ -346,6 +363,9 @@ export class HermesKanbanAdapter {
       tokenCounts?: { inputTokens?: number; outputTokens?: number };
       totalCostCents?: number;
       reviewerCascade?: Record<string, unknown>;
+      revocationReason?: string;
+      finalSpendCents?: number;
+      postRevocationSpendCents?: number;
     },
   ): Promise<ReceiptDagNode> {
     if (!this.config.signingKeys) throw new Error('Hermes Kanban receipts require signingKeys');
@@ -373,6 +393,15 @@ export class HermesKanbanAdapter {
     };
   }
 
+  private spendCentsSoFar(taskId: string): number {
+    let total = 0;
+    for (const node of this.nodes) {
+      const receipt = node.decision?.outcomeReceipt as Record<string, unknown> | undefined;
+      if (receipt?.taskId === taskId) total += safeNonNegativeInteger(receipt.totalCostCents);
+    }
+    return total;
+  }
+
   private requireEnvelope(taskId: string): HermesKanbanEnvelope {
     const envelope = this.envelopes.get(taskId);
     if (!envelope) throw new Error(`Unknown Hermes Kanban task ${taskId}`);
@@ -413,6 +442,9 @@ function taskDecision(
     tokenCounts?: { inputTokens?: number; outputTokens?: number };
     totalCostCents?: number;
     reviewerCascade?: Record<string, unknown>;
+    revocationReason?: string;
+    finalSpendCents?: number;
+    postRevocationSpendCents?: number;
   },
   policy: SpendPolicy,
 ): SpendDecision {
@@ -433,6 +465,10 @@ function taskDecision(
     parentTaskIds: [...envelope.parentTaskIds],
     parentEntryHashes: parentNodes.map((node) => node.entryHash),
     parentMsgHashes: parentNodes.map((node) => node.msgHash),
+    boardScopeHash: envelope.boardHash,
+    workspaceProvenance: envelope.workspacePath ? { type: 'directory', location: `dir:${envelope.workspacePath}` } : null,
+    governanceMode: envelope.governanceMode,
+    lightweight: envelope.governanceMode === 'lightweight',
     modelIds: safeModelIds(args.modelIds ?? []),
     inputTokens,
     outputTokens,
@@ -440,6 +476,15 @@ function taskDecision(
     metadata: filterReceiptMetadata(args.metadata ?? {}),
   };
   if (args.reviewerCascade) receipt.reviewerCascade = args.reviewerCascade;
+  if (args.event === 'revoked') {
+    receipt.revocation = {
+      reason: args.revocationReason ?? 'stale_lock_reclaimed',
+      finalSpendCents: safeNonNegativeInteger(args.finalSpendCents),
+      postRevocationSpendCents: safeNonNegativeInteger(args.postRevocationSpendCents),
+      closedAt: envelope.revokedAt ?? new Date().toISOString(),
+      assertion: 'no_spend_after_revoke',
+    };
+  }
   const decision: SpendDecision = {
     decisionId: randomUUID(),
     timestamp: new Date().toISOString(),
@@ -481,15 +526,29 @@ function buildReviewerCascadeReceipt(input: HermesKanbanReceiptInput, opts: Herm
 }
 
 function reviewerCascadeTriggers(envelope: HermesKanbanEnvelope, input: HermesKanbanReceiptInput, opts: HermesKanbanAdapterOptions): string[] {
-  if (opts.reviewerCascade?.enabled === false) return [];
+  if (opts.reviewerCascade?.enabled === false || envelope.governanceMode === 'lightweight') return [];
   const threshold = opts.reviewerCascade?.highRiskThreshold ?? 0.55;
   const triggers: string[] = [];
-  if (envelope.profile === 'reviewer') triggers.push('reviewer_profile');
   if (typeof input.highRiskClassifierScore === 'number' && input.highRiskClassifierScore >= threshold) triggers.push(`risk_score_above:${threshold}`);
   if (input.keywordRisk === true) triggers.push('keyword_prefilter');
   return [...new Set(triggers)];
 }
 
+
+function governanceModeFor(capability: ReceiptCapabilityLevel, capCents: number, opts: HermesKanbanAdapterOptions): HermesKanbanGovernanceMode {
+  const threshold = opts.lightweightThresholdCents ?? 5;
+  const ceiling = opts.lightweightCapabilityCeiling ?? 'READ_ONLY';
+  return CAPABILITY_RANK[capability] <= CAPABILITY_RANK[ceiling] && capCents <= threshold ? 'lightweight' : 'full';
+}
+
+function resolveWorkspacePath(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  if (trimmed.length > 1024 || /[\u0000-\u001f\u007f]/.test(trimmed)) throw new Error('Hermes Kanban workspacePath must be a metadata path');
+  return resolvePath(trimmed);
+}
+
 function capForTask(input: HermesKanbanTaskInput, profilePolicy: HermesKanbanProfilePolicy, opts: HermesKanbanAdapterOptions): number {
   if (Number.isSafeInteger(profilePolicy.capCents) && profilePolicy.capCents! >= 0) return profilePolicy.capCents!;
   const runtimeMinutes = runtimeMinutesFor(input);
@@ -513,7 +572,7 @@ function spendCapabilityForReceiptCapability(capability: ReceiptCapabilityLevel)
 
 function assertTaskInput(input: HermesKanbanTaskInput): void {
   assertPlainRecord(input, 'task');
-  const allowed = new Set(['taskId', 'boardSlug', 'profile', 'parentTaskIds', 'maxRuntimeMinutes', 'maxRuntimeMs', 'metadata', 'builderCode']);
+  const allowed = new Set(['taskId', 'boardSlug', 'profile', 'parentTaskIds', 'workspacePath', 'maxRuntimeMinutes', 'maxRuntimeMs', 'metadata', 'builderCode']);
   for (const key of Object.keys(input as unknown as Record<string, unknown>)) {
     if (!allowed.has(key)) throw new Error(`Hermes Kanban task input cannot include data-plane or unknown field: ${key}`);
   }
@@ -545,7 +604,7 @@ function assertPlainRecord(value: unknown, name: string): void {
 
 function assertActive(envelope: HermesKanbanEnvelope): void {
   if (envelope.state === 'revoked') throw new AgentGuardBlockedError(blockedDecision(envelope, 'revoked'), envelope.scope);
-  if (envelope.state === 'completed') throw new AgentGuardBlockedError(blockedDecision(envelope, 'completed'), envelope.scope);
+  if (envelope.state === 'complete') throw new AgentGuardBlockedError(blockedDecision(envelope, 'complete'), envelope.scope);
 }
 
 function blockedDecision(envelope: HermesKanbanEnvelope, state: string): SpendDecision {

package/src/receipts/portability.test.ts

@@ -0,0 +1,68 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { workloadProvenance, formatLineage } from './portability';
+import type { SignedDecisionLogEntry, SpendDecision, Provider } from '../types';
+import type { ProvenanceProvider } from './schema';
+
+let seq = 0;
+function entry(model: string, fam: ProvenanceProvider, route: string, extra: Partial<SpendDecision> = {}): SignedDecisionLogEntry {
+  const decision: SpendDecision = {
+    decisionId: `d${seq}`, timestamp: `2026-07-10T14:${String(seq).padStart(2, '0')}:00.000Z`,
+    action: 'allow', triggeredCap: null, triggeredScopeKey: 'tenant:acme|agent:planner',
+    projectedCents: 10, actualCents: 10, windowSpendBefore: 0, windowSpendAfter: 0,
+    provider: (fam === 'self_hosted' ? 'unknown' : fam) as Provider,
+    modelRequested: model, modelResolved: model, policyId: 'p', policyVersion: 1,
+    enforcementMode: 'enforce', reasons: [],
+    provenance: {
+      model_identity: { provider: fam, model_id: model, model_version: '1', model_family: fam, weights_origin_country: 'US' },
+      hosting: { provider_route: route, jurisdiction_country: 'US', jurisdiction_region: 'us' },
+      compliance: { baa_in_force: false, baa_vendor: null, hipaa_eligible: false, data_retention_days: null, data_residency_attested: false, foreign_origin_weight_flag: false, foreign_origin_consent_receipt_id: null, inference_billing: 'customer_managed' },
+      captured_at: '2026-07-10T14:00:00.000Z',
+    },
+    ...extra,
+  };
+  return { sequence: seq++, decision, previousHash: '0'.repeat(64), entryHash: 'x', signature: 'y', signerFingerprint: 'f' };
+}
+
+test('lineage, swaps, and boundary crossing across a hot-swap sequence', () => {
+  seq = 0;
+  const entries = [
+    entry('claude-5', 'anthropic', 'anthropic-api'),
+    entry('claude-5', 'anthropic', 'anthropic-api'),     // repeat: no swap
+    entry('gpt-5-mini', 'openai', 'openai-api'),          // frontier→frontier swap
+    entry('glm-5.2', 'self_hosted', 'self-hosted-gpu'),   // frontier→dark swap (boundary)
+  ];
+  const report = workloadProvenance(entries, { verified: true, entries: entries.length });
+  assert.equal(report.workloads.length, 1);
+  const w = report.workloads[0];
+  assert.deepEqual(w.lineage, ['claude-5', 'gpt-5-mini', 'glm-5.2']);
+  assert.equal(formatLineage(w), 'claude-5 → gpt-5-mini → glm-5.2');
+  assert.equal(w.swaps.length, 2);
+  assert.equal(w.swaps[0].crossesBoundary, false);        // frontier→frontier
+  assert.equal(w.swaps[1].crossesBoundary, true);         // frontier→dark
+  assert.equal(w.swaps[1].fromModel, 'gpt-5-mini');
+  assert.equal(w.swaps[1].toModel, 'glm-5.2');
+  assert.equal(w.darkCents, 10);
+  assert.equal(w.frontierCents, 30);
+  assert.equal(report.continuity.verified, true);         // one chain spans all swaps
+});
+
+test('groups by keyOf; separate workloads do not merge', () => {
+  seq = 0;
+  const a = entry('claude-5', 'anthropic', 'api', { triggeredScopeKey: 'wf:A' });
+  const b = entry('glm-5.2', 'self_hosted', 'self', { triggeredScopeKey: 'wf:B' });
+  const report = workloadProvenance([a, b], { verified: true, entries: 2 });
+  assert.equal(report.workloads.length, 2);
+  assert.ok(report.workloads.every(w => w.swaps.length === 0));
+});
+
+test('settlement/outcome entries add no model steps', () => {
+  seq = 0;
+  const entries = [
+    entry('claude-5', 'anthropic', 'api'),
+    entry('claude-5', 'anthropic', 'api', { entryType: 'settlement', actualCents: 9 }),
+  ];
+  const w = workloadProvenance(entries, { verified: true, entries: 2 }).workloads[0];
+  assert.equal(w.calls, 1);
+  assert.equal(w.swaps.length, 0);
+});

package/src/receipts/portability.ts

@@ -0,0 +1,156 @@
+/**
+ * AgentGuard® — model-agnostic provenance that survives hot-swap.
+ *
+ * The "headless" / model-fungibility problem (raised on All-In E280): teams want
+ * to hot-swap models — frontier → open-weight → self-hosted — per task to cut
+ * cost, but "no one has figured out how to abstract memory/context/AUDIT away
+ * from the model." A provider console can't help: it only sees its own tokens,
+ * and the trail breaks the moment you route to a different provider.
+ *
+ * AgentGuard's signed decision log already records, per call, which model served
+ * it (provenance) inside one continuous hash chain. This module reads that log
+ * and produces a PORTABLE, model-agnostic provenance manifest per workload: the
+ * ordered model lineage, every swap, the frontier/dark origin mix, and a single
+ * tamper-evidence verdict that spans the whole swap sequence. The audit is keyed
+ * to the workload, not the model — so it survives the swap.
+ *
+ * Honest scope note (same as the dashboard): the signed SpendDecision does not
+ * carry a first-class workload/agent id (only `triggeredScopeKey`). Callers pass
+ * a `keyOf` selector to group; the default uses `triggeredScopeKey`. We never
+ * invent a grouping the ledger does not support.
+ *
+ * Patent notice: signed hash-chained decision log (U.S. application filed May
+ * 2026); composes with DAG Trust Attestation, Patent D §7.3 (App. No.
+ * 63/984,626). AgentGuard® is a U.S. registered trademark (Reg. No. 8281464) of
+ * Dunecrest Ventures Inc.
+ */
+import type { SignedDecisionLogEntry, SpendDecision } from '../types';
+import { classifyOrigin, decisionCents, type TokenOrigin } from '../dashboard/aggregate';
+
+export interface ModelUse {
+  model: string;
+  origin: TokenOrigin;
+  provider: string;
+  calls: number;
+  cents: number;
+}
+export interface ModelSwap {
+  atSequence: number;
+  fromModel: string;
+  toModel: string;
+  fromOrigin: TokenOrigin;
+  toOrigin: TokenOrigin;
+  /** True when the swap crossed the frontier↔dark boundary (the audit-risky kind). */
+  crossesBoundary: boolean;
+}
+export interface WorkloadProvenance {
+  key: string;
+  calls: number;
+  spentCents: number;
+  frontierCents: number;
+  darkCents: number;
+  firstAt: string | null;
+  lastAt: string | null;
+  models: ModelUse[];
+  /** Ordered model lineage, e.g. ['claude-5','gpt-5-mini','glm-5.2']. */
+  lineage: string[];
+  swaps: ModelSwap[];
+}
+export interface WorkloadProvenanceReport {
+  workloads: WorkloadProvenance[];
+  /** Chain-level tamper evidence spans ALL swaps — the point of the manifest. */
+  continuity: { verified: boolean; entries: number; reason?: string };
+}
+
+const defaultKeyOf = (d: SpendDecision): string => d.triggeredScopeKey ?? 'default';
+
+/**
+ * Build the portable per-workload provenance manifest from signed ledger
+ * entries. Pass the async `verifyChain` result as `continuity` so this stays a
+ * pure, synchronous function (never null-continuity in production — a manifest
+ * without tamper evidence is not the product).
+ */
+export function workloadProvenance(
+  entries: SignedDecisionLogEntry[],
+  continuity: WorkloadProvenanceReport['continuity'] = { verified: false, entries: 0, reason: 'NOT_CHECKED' },
+  keyOf: (d: SpendDecision) => string = defaultKeyOf,
+): WorkloadProvenanceReport {
+  interface Group {
+    calls: number; spent: number; frontier: number; dark: number;
+    first: string | null; last: string | null;
+    models: Map<string, ModelUse>; ordered: Array<{ seq: number; model: string; origin: TokenOrigin }>;
+  }
+  const groups = new Map<string, Group>();
+
+  for (const entry of entries) {
+    const d = entry.decision;
+    const kind = d.entryType ?? 'decision';
+    if (kind !== 'decision') continue; // settlements/outcomes don't add model steps
+
+    const key = keyOf(d);
+    const grp: Group = groups.get(key) ?? {
+      calls: 0, spent: 0, frontier: 0, dark: 0, first: null, last: null,
+      models: new Map(), ordered: [],
+    };
+    const model = d.modelResolved || d.modelRequested || 'unknown';
+    const { origin } = classifyOrigin(d);
+    const cents = decisionCents(d);
+
+    grp.calls += 1;
+    grp.spent += cents;
+    if (origin === 'frontier') grp.frontier += cents;
+    else if (origin === 'dark') grp.dark += cents;
+    if (d.timestamp) {
+      if (!grp.first || d.timestamp < grp.first) grp.first = d.timestamp;
+      if (!grp.last || d.timestamp > grp.last) grp.last = d.timestamp;
+    }
+    const mu = grp.models.get(model) ?? { model, origin, provider: d.provider ?? 'unknown', calls: 0, cents: 0 };
+    mu.calls += 1;
+    mu.cents += cents;
+    grp.models.set(model, mu);
+    grp.ordered.push({ seq: entry.sequence, model, origin });
+
+    groups.set(key, grp);
+  }
+
+  const workloads: WorkloadProvenance[] = [];
+  for (const [key, grp] of groups) {
+    grp.ordered.sort((a, b) => a.seq - b.seq);
+    const swaps: ModelSwap[] = [];
+    for (let i = 1; i < grp.ordered.length; i++) {
+      const prev = grp.ordered[i - 1];
+      const cur = grp.ordered[i];
+      if (cur.model !== prev.model) {
+        swaps.push({
+          atSequence: cur.seq,
+          fromModel: prev.model, toModel: cur.model,
+          fromOrigin: prev.origin, toOrigin: cur.origin,
+          crossesBoundary: prev.origin !== cur.origin
+            && prev.origin !== 'unknown' && cur.origin !== 'unknown',
+        });
+      }
+    }
+    // lineage = models in first-appearance order (collapse consecutive repeats)
+    const lineage: string[] = [];
+    for (const step of grp.ordered) if (lineage[lineage.length - 1] !== step.model) lineage.push(step.model);
+
+    workloads.push({
+      key,
+      calls: grp.calls,
+      spentCents: grp.spent,
+      frontierCents: grp.frontier,
+      darkCents: grp.dark,
+      firstAt: grp.first,
+      lastAt: grp.last,
+      models: [...grp.models.values()].sort((a, b) => b.cents - a.cents),
+      lineage,
+      swaps,
+    });
+  }
+
+  workloads.sort((a, b) => b.spentCents - a.spentCents);
+  return { workloads, continuity };
+}
+
+/** Human-readable lineage, e.g. "claude-5 → gpt-5-mini → glm-5.2". */
+export const formatLineage = (w: WorkloadProvenance): string => w.lineage.join(' → ');