@agentguard-run/spend 0.13.2 → 0.14.0

package/src/frameworks/hermes-kanban.ts

@@ -0,0 +1,622 @@
+import { randomUUID } from 'crypto';
+import { inferProvider } from '../cost-table';
+import { canonicalJson, computeSignerFingerprint, sha256Hex } from '../decision-log';
+import { signDagNode, verifyReceiptDag, type ReceiptCapabilityLevel, type ReceiptDagEnvelope, type ReceiptDagNode } from '../receipts/dag';
+import { AgentGuardBlockedError, SpendGuard, type SpendGuardConfig } from '../spend-guard';
+import type { CallContext, CapabilityTier, Provider, SignedDecisionLogEntry, SpendDecision, SpendPolicy, SpendScope } from '../types';
+import { safeRequestShape } from './common';
+
+export type HermesKanbanProfile = 'researcher' | 'writer' | 'reviewer' | 'director' | 'orchestrator' | string;
+export type HermesKanbanTaskState = 'governed' | 'running' | 'completed' | 'revoked';
+
+export interface HermesKanbanProfilePolicy {
+  capability: ReceiptCapabilityLevel;
+  toolAllowlist?: string[];
+  capCents?: number;
+}
+
+export interface HermesKanbanAdapterOptions {
+  policy: SpendPolicy;
+  scope: SpendScope;
+  config?: Omit<SpendGuardConfig, 'policy'>;
+  licenseKey?: string;
+  defaultModel?: string;
+  defaultCapCents?: number;
+  runtimeBudgetCentsPerMinute?: number;
+  profileMap?: Record<string, HermesKanbanProfilePolicy>;
+  reviewerCascade?: {
+    enabled?: boolean;
+    highRiskThreshold?: number;
+    drafterModel?: string;
+    reviewerModel?: string;
+    drafterMaxCostCents?: number;
+    reviewerMaxCostCents?: number;
+  };
+}
+
+export interface HermesKanbanTaskInput {
+  taskId: string;
+  boardSlug: string;
+  profile: HermesKanbanProfile;
+  parentTaskIds?: string[];
+  maxRuntimeMinutes?: number;
+  maxRuntimeMs?: number;
+  metadata?: Record<string, unknown>;
+  builderCode?: string;
+}
+
+export interface HermesKanbanEnvelope {
+  taskId: string;
+  taskHash: string;
+  boardHash: string;
+  profile: string;
+  state: HermesKanbanTaskState;
+  capabilityCeiling: ReceiptCapabilityLevel;
+  toolAllowlist: string[];
+  capCents: number;
+  parentTaskIds: string[];
+  parentEntryHashes: string[];
+  scope: SpendScope;
+  builderCode?: string;
+  createdAt: string;
+  revokedAt?: string;
+  completedAt?: string;
+}
+
+export interface HermesKanbanDispatchInput {
+  taskId: string;
+  model?: string;
+  provider?: Provider;
+  inputTokens: number;
+  outputTokens: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface HermesKanbanDispatchResult {
+  allow: boolean;
+  decision: SpendDecision;
+  signed: SignedDecisionLogEntry | null;
+}
+
+export interface HermesKanbanCapabilityInput {
+  taskId: string;
+  requestedCapability: ReceiptCapabilityLevel;
+  toolName?: string;
+  toolArgs?: Record<string, unknown>;
+}
+
+export interface HermesKanbanCapabilityResult {
+  approved: boolean;
+  reason?: string;
+  signed?: SignedDecisionLogEntry | null;
+  decision?: SpendDecision;
+  editedArgs?: Record<string, unknown>;
+}
+
+export interface HermesKanbanReceiptInput {
+  taskId: string;
+  parentTaskIds?: string[];
+  capability?: ReceiptCapabilityLevel;
+  modelIds?: string[];
+  tokenCounts?: { inputTokens?: number; outputTokens?: number };
+  totalCostCents?: number;
+  metadata?: Record<string, unknown>;
+  highRiskClassifierScore?: number;
+  keywordRisk?: boolean;
+  reviewerVerdict?: 'drafter_only' | 'review_required' | 'approved' | 'rejected';
+}
+
+export interface HermesKanbanReceiptResult {
+  node: ReceiptDagNode;
+  envelope: HermesKanbanEnvelope;
+  dag: ReceiptDagEnvelope;
+  verification?: Awaited<ReturnType<typeof verifyReceiptDag>>;
+}
+
+const DEFAULT_PROFILE_MAP: Record<string, HermesKanbanProfilePolicy> = {
+  researcher: { capability: 'READ_ONLY', toolAllowlist: ['web.fetch', 'file.read', 'notes.read', 'search.query'] },
+  writer: { capability: 'TRANSACT', toolAllowlist: ['draft.create', 'file.write', 'notes.write', 'email.draft'] },
+  reviewer: { capability: 'READ_ONLY', toolAllowlist: ['review.read', 'notes.read', 'decision.record'] },
+  director: { capability: 'ORCHESTRATE', toolAllowlist: ['task.assign', 'board.plan', 'decision.record'] },
+  orchestrator: { capability: 'ORCHESTRATE', toolAllowlist: ['task.assign', 'board.plan', 'decision.record'] },
+};
+
+const CAPABILITY_RANK: Record<ReceiptCapabilityLevel, number> = {
+  READ_ONLY: 0,
+  TRANSACT: 1,
+  ADMIN: 2,
+  ORCHESTRATE: 3,
+};
+
+const DATA_PLANE_KEYS = /^(title|summary|prompt|completion|content|messages|input|output|text|raw|source|notes|draft|body|transcript)$/i;
+const SAFE_METADATA_KEYS = new Set([
+  'assignee',
+  'board_hash',
+  'duration_ms',
+  'event',
+  'model',
+  'model_id',
+  'outcome',
+  'priority',
+  'profile',
+  'provider',
+  'risk_score',
+  'state',
+  'task_id',
+  'ticket_id',
+  'token_count',
+  'workflow_id',
+]);
+
+export function createHermesKanbanAdapter(opts: HermesKanbanAdapterOptions): HermesKanbanAdapter {
+  return new HermesKanbanAdapter(opts);
+}
+
+export class HermesKanbanAdapter {
+  private readonly taskGuards = new Map<string, SpendGuard>();
+  private readonly envelopes = new Map<string, HermesKanbanEnvelope>();
+  private readonly nodesByTaskId = new Map<string, ReceiptDagNode>();
+  private readonly nodes: ReceiptDagNode[] = [];
+  private readonly profileMap: Record<string, HermesKanbanProfilePolicy>;
+  private readonly config: Omit<SpendGuardConfig, 'policy'>;
+
+  constructor(private readonly opts: HermesKanbanAdapterOptions) {
+    this.profileMap = { ...DEFAULT_PROFILE_MAP, ...(opts.profileMap ?? {}) };
+    this.config = opts.config ?? {};
+  }
+
+  governTask(input: HermesKanbanTaskInput): HermesKanbanEnvelope {
+    assertTaskInput(input);
+    const profilePolicy = this.profilePolicy(input.profile);
+    const capCents = capForTask(input, profilePolicy, this.opts);
+    const boardHash = hashValue(input.boardSlug);
+    const taskHash = hashValue(input.taskId);
+    const scope: SpendScope = { ...this.opts.scope, taskId: input.taskId };
+    const envelope: HermesKanbanEnvelope = {
+      taskId: input.taskId,
+      taskHash,
+      boardHash,
+      profile: normalizeProfile(input.profile),
+      state: 'governed',
+      capabilityCeiling: profilePolicy.capability,
+      toolAllowlist: [...(profilePolicy.toolAllowlist ?? [])],
+      capCents,
+      parentTaskIds: [...new Set(input.parentTaskIds ?? [])],
+      parentEntryHashes: [],
+      scope,
+      builderCode: safeBuilderCode(input.builderCode),
+      createdAt: new Date().toISOString(),
+    };
+    const taskPolicy: SpendPolicy = {
+      ...this.opts.policy,
+      id: `${this.opts.policy.id}:hermes-kanban:${taskHash.slice(0, 12)}`,
+      name: `${this.opts.policy.name} Hermes Kanban task`,
+      scope,
+      caps: [{ window: 'per_day', amountCents: capCents, action: 'block', reason: 'Hermes Kanban task cap' }],
+      requiredCapability: spendCapabilityForReceiptCapability(profilePolicy.capability),
+    };
+    this.envelopes.set(input.taskId, envelope);
+    this.taskGuards.set(input.taskId, new SpendGuard({
+      policy: taskPolicy,
+      ...this.config,
+      licenseKey: this.opts.licenseKey ?? this.config.licenseKey,
+    }));
+    return { ...envelope };
+  }
+
+  async enforceProviderCall(input: HermesKanbanDispatchInput): Promise<HermesKanbanDispatchResult> {
+    const envelope = this.requireEnvelope(input.taskId);
+    assertActive(envelope);
+    assertMetadataOnly(input.metadata ?? {});
+    validateTokens(input.inputTokens, input.outputTokens);
+    const guard = this.requireGuard(input.taskId);
+    const model = safeLabel(input.model) ?? this.opts.defaultModel ?? 'openai/gpt-4o-mini';
+    const call: CallContext = {
+      provider: input.provider ?? inferProvider(model),
+      model,
+      inputTokens: input.inputTokens,
+      outputTokens: input.outputTokens,
+      scope: envelope.scope,
+      workflowId: envelope.boardHash,
+      subagentId: envelope.taskId,
+      label: 'hermes-kanban',
+      capabilityClaim: spendCapabilityForReceiptCapability(envelope.capabilityCeiling),
+      requestShape: safeRequestShape({
+        framework: 'hermes-kanban',
+        event: 'provider-call',
+        taskId: envelope.taskId,
+        taskHash: envelope.taskHash,
+        boardHash: envelope.boardHash,
+        profile: envelope.profile,
+        metadata: filterReceiptMetadata(input.metadata ?? {}),
+      }),
+    };
+    const { decision, signed } = await guard.decide(call);
+    return { allow: decision.action !== 'block', decision, signed };
+  }
+
+  async guardCapability(input: HermesKanbanCapabilityInput): Promise<HermesKanbanCapabilityResult> {
+    const envelope = this.requireEnvelope(input.taskId);
+    assertActive(envelope);
+    assertMetadataOnly(input.toolArgs ?? {});
+    if (CAPABILITY_RANK[input.requestedCapability] > CAPABILITY_RANK[envelope.capabilityCeiling]) {
+      return {
+        approved: false,
+        reason: `Hermes Kanban profile ${envelope.profile} is capped at ${envelope.capabilityCeiling}`,
+      };
+    }
+    if (input.toolName && envelope.toolAllowlist.length > 0 && !toolAllowed(input.toolName, envelope.toolAllowlist)) {
+      return { approved: false, reason: `Tool ${input.toolName} is outside the Hermes Kanban profile allowlist` };
+    }
+    const gate = await this.requireGuard(input.taskId).guardToolCall({
+      toolName: input.toolName ?? 'hermes-kanban.tool',
+      toolArgs: safeRequestShape(input.toolArgs ?? {}),
+      workflowId: envelope.boardHash,
+      scope: envelope.scope,
+    });
+    return {
+      approved: gate.approved,
+      reason: gate.decision.reasons.join('; '),
+      signed: gate.signed,
+      decision: gate.decision,
+      editedArgs: gate.editedArgs,
+    };
+  }
+
+  async revokeTask(taskId: string): 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 node = await this.signTaskNode(envelope, {
+      event: 'revoked',
+      action: 'block',
+      blocked: true,
+      capability: envelope.capabilityCeiling,
+      trustScore: 0.7,
+    });
+    this.nodesByTaskId.set(taskId, node);
+    this.nodes.push(node);
+    return this.receiptResult(envelope, node);
+  }
+
+  async emitTaskReceipt(input: HermesKanbanReceiptInput): Promise<HermesKanbanReceiptResult> {
+    const envelope = this.requireEnvelope(input.taskId);
+    assertActive(envelope);
+    assertMetadataOnly(input.metadata ?? {});
+    envelope.state = 'completed';
+    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[];
+    envelope.parentEntryHashes = parentNodes.map((node) => node.entryHash);
+    const capability = input.capability ?? envelope.capabilityCeiling;
+    const triggers = reviewerCascadeTriggers(envelope, input, this.opts);
+    const node = await this.signTaskNode(envelope, {
+      event: 'completed',
+      action: 'allow',
+      blocked: false,
+      capability,
+      trustScore: triggers.length > 0 ? 0.9 : 0.94,
+      parentNodes,
+      metadata: input.metadata,
+      modelIds: input.modelIds,
+      tokenCounts: input.tokenCounts,
+      totalCostCents: input.totalCostCents,
+      reviewerCascade: triggers.length > 0 ? buildReviewerCascadeReceipt(input, this.opts, triggers) : undefined,
+    });
+    this.nodesByTaskId.set(input.taskId, node);
+    this.nodes.push(node);
+    return this.receiptResult(envelope, node);
+  }
+
+  getEnvelope(taskId: string): HermesKanbanEnvelope | null {
+    const envelope = this.envelopes.get(taskId);
+    return envelope ? { ...envelope, parentTaskIds: [...envelope.parentTaskIds], parentEntryHashes: [...envelope.parentEntryHashes], toolAllowlist: [...envelope.toolAllowlist] } : null;
+  }
+
+  getReceiptDag(rootTaskId?: string): ReceiptDagEnvelope {
+    const root = rootTaskId ? this.nodesByTaskId.get(rootTaskId) : this.nodes[this.nodes.length - 1];
+    return {
+      nodes: [...this.nodes],
+      rootId: root?.entryHash ?? '0'.repeat(64),
+      workflowId: this.nodes[0]?.workflowId ?? null,
+    };
+  }
+
+  outboundPayloads(): Record<string, unknown>[] {
+    return [];
+  }
+
+  async verifyDag(publicKeyHex?: string): Promise<Awaited<ReturnType<typeof verifyReceiptDag>>> {
+    const key = publicKeyHex ?? this.publicKeyHex();
+    return verifyReceiptDag(this.getReceiptDag(), key);
+  }
+
+  private async signTaskNode(
+    envelope: HermesKanbanEnvelope,
+    args: {
+      event: 'completed' | 'revoked';
+      action: 'allow' | 'block';
+      blocked: boolean;
+      capability: ReceiptCapabilityLevel;
+      trustScore: number;
+      parentNodes?: ReceiptDagNode[];
+      metadata?: Record<string, unknown>;
+      modelIds?: string[];
+      tokenCounts?: { inputTokens?: number; outputTokens?: number };
+      totalCostCents?: number;
+      reviewerCascade?: Record<string, unknown>;
+    },
+  ): Promise<ReceiptDagNode> {
+    if (!this.config.signingKeys) throw new Error('Hermes Kanban receipts require signingKeys');
+    const parentNodes = args.parentNodes ?? [];
+    const decision = taskDecision(envelope, args, this.opts.policy);
+    return signDagNode({
+      sequence: this.nodes.length,
+      decision,
+      privateKey: this.config.signingKeys.privateKey,
+      publicKey: this.config.signingKeys.publicKey,
+      parents: parentNodes,
+      workflowId: envelope.boardHash,
+      trustScore: args.trustScore,
+      blocked: args.blocked,
+      capability: args.capability,
+      builderCode: envelope.builderCode ?? null,
+    });
+  }
+
+  private receiptResult(envelope: HermesKanbanEnvelope, node: ReceiptDagNode): HermesKanbanReceiptResult {
+    return {
+      node,
+      envelope: { ...envelope, parentTaskIds: [...envelope.parentTaskIds], parentEntryHashes: [...envelope.parentEntryHashes], toolAllowlist: [...envelope.toolAllowlist] },
+      dag: this.getReceiptDag(envelope.taskId),
+    };
+  }
+
+  private requireEnvelope(taskId: string): HermesKanbanEnvelope {
+    const envelope = this.envelopes.get(taskId);
+    if (!envelope) throw new Error(`Unknown Hermes Kanban task ${taskId}`);
+    return envelope;
+  }
+
+  private requireGuard(taskId: string): SpendGuard {
+    const guard = this.taskGuards.get(taskId);
+    if (!guard) throw new Error(`Unknown Hermes Kanban task ${taskId}`);
+    return guard;
+  }
+
+  private requireNode(taskId: string): ReceiptDagNode {
+    const node = this.nodesByTaskId.get(taskId);
+    if (!node) throw new Error(`Hermes Kanban task ${taskId} has no receipt`);
+    return node;
+  }
+
+  private profilePolicy(profile: string): HermesKanbanProfilePolicy {
+    return this.profileMap[normalizeProfile(profile)] ?? { capability: 'READ_ONLY', toolAllowlist: [] };
+  }
+
+  private publicKeyHex(): string {
+    if (!this.config.signingKeys) throw new Error('Hermes Kanban receipts require signingKeys');
+    return Buffer.from(this.config.signingKeys.publicKey).toString('hex');
+  }
+}
+
+function taskDecision(
+  envelope: HermesKanbanEnvelope,
+  args: {
+    event: 'completed' | 'revoked';
+    action: 'allow' | 'block';
+    capability: ReceiptCapabilityLevel;
+    parentNodes?: ReceiptDagNode[];
+    metadata?: Record<string, unknown>;
+    modelIds?: string[];
+    tokenCounts?: { inputTokens?: number; outputTokens?: number };
+    totalCostCents?: number;
+    reviewerCascade?: Record<string, unknown>;
+  },
+  policy: SpendPolicy,
+): SpendDecision {
+  const parentNodes = args.parentNodes ?? [];
+  const inputTokens = safeNonNegativeInteger(args.tokenCounts?.inputTokens);
+  const outputTokens = safeNonNegativeInteger(args.tokenCounts?.outputTokens);
+  const totalCostCents = safeNonNegativeInteger(args.totalCostCents);
+  const receipt: Record<string, unknown> = {
+    type: 'hermes_kanban_task',
+    event: args.event,
+    taskId: envelope.taskId,
+    taskHash: envelope.taskHash,
+    boardHash: envelope.boardHash,
+    profile: envelope.profile,
+    capability: args.capability,
+    capabilityCeiling: envelope.capabilityCeiling,
+    state: envelope.state,
+    parentTaskIds: [...envelope.parentTaskIds],
+    parentEntryHashes: parentNodes.map((node) => node.entryHash),
+    parentMsgHashes: parentNodes.map((node) => node.msgHash),
+    modelIds: safeModelIds(args.modelIds ?? []),
+    inputTokens,
+    outputTokens,
+    totalCostCents,
+    metadata: filterReceiptMetadata(args.metadata ?? {}),
+  };
+  if (args.reviewerCascade) receipt.reviewerCascade = args.reviewerCascade;
+  const decision: SpendDecision = {
+    decisionId: randomUUID(),
+    timestamp: new Date().toISOString(),
+    action: args.action,
+    triggeredCap: null,
+    triggeredScopeKey: null,
+    projectedCents: totalCostCents,
+    windowSpendBefore: 0,
+    windowSpendAfter: totalCostCents,
+    provider: 'unknown',
+    modelRequested: 'hermes-kanban',
+    modelResolved: 'hermes-kanban',
+    policyId: policy.id,
+    policyVersion: policy.version,
+    enforcementMode: policy.mode,
+    reasons: [`Hermes Kanban task ${args.event}: ${envelope.taskId}`],
+    entryType: 'outcome',
+    outcomeReceipt: receipt,
+  };
+  if (envelope.builderCode) decision.builderCode = envelope.builderCode;
+  return decision;
+}
+
+function buildReviewerCascadeReceipt(input: HermesKanbanReceiptInput, opts: HermesKanbanAdapterOptions, triggers: string[]): Record<string, unknown> {
+  const cascade = opts.reviewerCascade ?? {};
+  return {
+    outcome: safeLabel(input.metadata?.outcome) ?? 'hermes_kanban_task',
+    drafter: {
+      model: cascade.drafterModel ?? opts.defaultModel ?? 'openai/gpt-4o-mini',
+      maxCostCents: safeNonNegativeInteger(cascade.drafterMaxCostCents ?? 25),
+    },
+    reviewer: {
+      model: cascade.reviewerModel ?? 'anthropic/claude-sonnet-4-6',
+      maxCostCents: safeNonNegativeInteger(cascade.reviewerMaxCostCents ?? 75),
+    },
+    triggerFired: triggers,
+    reviewerVerdict: input.reviewerVerdict ?? 'review_required',
+  };
+}
+
+function reviewerCascadeTriggers(envelope: HermesKanbanEnvelope, input: HermesKanbanReceiptInput, opts: HermesKanbanAdapterOptions): string[] {
+  if (opts.reviewerCascade?.enabled === false) 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 capForTask(input: HermesKanbanTaskInput, profilePolicy: HermesKanbanProfilePolicy, opts: HermesKanbanAdapterOptions): number {
+  if (Number.isSafeInteger(profilePolicy.capCents) && profilePolicy.capCents! >= 0) return profilePolicy.capCents!;
+  const runtimeMinutes = runtimeMinutesFor(input);
+  const runtimeBudget = opts.runtimeBudgetCentsPerMinute ?? 10;
+  const cap = Math.ceil(runtimeMinutes * runtimeBudget);
+  return Math.max(1, Math.min(cap, opts.defaultCapCents ?? cap));
+}
+
+function runtimeMinutesFor(input: HermesKanbanTaskInput): number {
+  if (Number.isFinite(input.maxRuntimeMinutes) && input.maxRuntimeMinutes! > 0) return input.maxRuntimeMinutes!;
+  if (Number.isFinite(input.maxRuntimeMs) && input.maxRuntimeMs! > 0) return input.maxRuntimeMs! / 60_000;
+  return 5;
+}
+
+function spendCapabilityForReceiptCapability(capability: ReceiptCapabilityLevel): CapabilityTier {
+  if (capability === 'ORCHESTRATE') return 'payment_execute';
+  if (capability === 'ADMIN') return 'payment_initiate';
+  if (capability === 'TRANSACT') return 'data_write';
+  return 'read_only';
+}
+
+function assertTaskInput(input: HermesKanbanTaskInput): void {
+  assertPlainRecord(input, 'task');
+  const allowed = new Set(['taskId', 'boardSlug', 'profile', 'parentTaskIds', '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}`);
+  }
+  if (!safeLabel(input.taskId)) throw new Error('Hermes Kanban taskId is required');
+  if (!safeLabel(input.boardSlug)) throw new Error('Hermes Kanban boardSlug is required');
+  if (!safeLabel(input.profile)) throw new Error('Hermes Kanban profile is required');
+  assertMetadataOnly(input.metadata ?? {});
+  for (const parent of input.parentTaskIds ?? []) {
+    if (!safeLabel(parent)) throw new Error('Hermes Kanban parent task id must be a metadata identifier');
+  }
+}
+
+function assertMetadataOnly(value: unknown, path = 'metadata'): void {
+  if (value == null) return;
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) assertMetadataOnly(value[i], `${path}[${i}]`);
+    return;
+  }
+  if (typeof value !== 'object') return;
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    if (DATA_PLANE_KEYS.test(key)) throw new Error(`Hermes Kanban metadata cannot include data-plane field: ${path}.${key}`);
+    assertMetadataOnly(child, `${path}.${key}`);
+  }
+}
+
+function assertPlainRecord(value: unknown, name: string): void {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`Hermes Kanban ${name} must be an object`);
+}
+
+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);
+}
+
+function blockedDecision(envelope: HermesKanbanEnvelope, state: string): SpendDecision {
+  return {
+    decisionId: randomUUID(),
+    timestamp: new Date().toISOString(),
+    action: 'block',
+    triggeredCap: null,
+    triggeredScopeKey: null,
+    projectedCents: 0,
+    windowSpendBefore: 0,
+    windowSpendAfter: 0,
+    provider: 'unknown',
+    modelRequested: 'hermes-kanban',
+    modelResolved: 'hermes-kanban',
+    policyId: 'hermes-kanban',
+    policyVersion: 1,
+    enforcementMode: 'enforce',
+    reasons: [`Hermes Kanban task ${envelope.taskId} is ${state}`],
+  };
+}
+
+function filterReceiptMetadata(metadata: Record<string, unknown>): Record<string, unknown> {
+  assertMetadataOnly(metadata);
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (!SAFE_METADATA_KEYS.has(key)) continue;
+    if (value == null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function validateTokens(inputTokens: number, outputTokens: number): void {
+  if (!Number.isSafeInteger(inputTokens) || inputTokens < 0) throw new Error('inputTokens must be a non-negative safe integer');
+  if (!Number.isSafeInteger(outputTokens) || outputTokens < 0) throw new Error('outputTokens must be a non-negative safe integer');
+}
+
+function hashValue(value: string): string {
+  return sha256Hex(canonicalJson({ value }));
+}
+
+function normalizeProfile(profile: string): string {
+  return profile.trim().toLowerCase().replace(/[^a-z0-9_.:-]/g, '_');
+}
+
+function safeLabel(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  if (!trimmed || !/^[A-Za-z0-9_.:/-]{1,160}$/.test(trimmed)) return undefined;
+  return trimmed;
+}
+
+function safeBuilderCode(value: unknown): string | undefined {
+  const label = safeLabel(value);
+  return label ? label.slice(0, 64) : undefined;
+}
+
+function safeModelIds(models: string[]): string[] {
+  return models.map((model) => safeLabel(model)).filter(Boolean) as string[];
+}
+
+function safeNonNegativeInteger(value: unknown): number {
+  return Number.isSafeInteger(value) && (value as number) >= 0 ? value as number : 0;
+}
+
+function toolAllowed(toolName: string, allowlist: string[]): boolean {
+  return allowlist.some((allowed) => toolName === allowed || toolName.startsWith(`${allowed}.`));
+}
+
+export function hermesKanbanSignerFingerprint(opts: HermesKanbanAdapterOptions): string | null {
+  return opts.config?.signingKeys ? computeSignerFingerprint(opts.config.signingKeys.publicKey) : null;
+}

package/src/frameworks/index.ts

@@ -3,3 +3,4 @@ export * from './openrouter';
 export * from './vercel-ai';
 export * from './claude-code';
 export * from './hermes';
+export * from './hermes-kanban';

package/src/receipts/dag.ts

@@ -192,6 +192,7 @@ export async function verifyReceiptDag(
           entryHash: node.entryHash,
           signature: node.signature,
           signerFingerprint: node.signerFingerprint,
+          builderCode: node.builderCode ?? undefined,
         },
         publicKey,
       );
@@ -348,6 +349,7 @@ function normalizeDagNode(input: ReceiptDagInput): NormalizedDagNode {
     entryHash: candidate.entryHash,
     signature: candidate.signature,
     signerFingerprint: candidate.signerFingerprint,
+    builderCode: candidate.builderCode ?? null,
     timestamp: stringOrNull(decision.timestamp) ?? new Date(0).toISOString(),
     previousHash,
     legacyPreviousHash: previousHash,