@lumenflow/cli 4.23.0 → 5.0.0

package/packs/agent-runtime/delegation-registry-schema.ts

@@ -0,0 +1,220 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Delegation Registry Schema (ADR-014 follow-up, WU-2763)
+ *
+ * Canonical delegation schema and helpers for agent-runtime coordination
+ * records. Core now re-exports this module as a compatibility shim.
+ */
+
+import crypto from 'node:crypto';
+import { z } from 'zod';
+
+/**
+ * Delegation status values.
+ */
+const DELEGATION_STATUS_COMPLETED = 'completed';
+
+export const DelegationStatus = {
+  PENDING: 'pending',
+  COMPLETED: DELEGATION_STATUS_COMPLETED,
+  TIMEOUT: 'timeout',
+  CRASHED: 'crashed',
+  ESCALATED: 'escalated',
+} as const;
+
+/** Type for delegation status values */
+export type DelegationStatusValue = (typeof DelegationStatus)[keyof typeof DelegationStatus];
+
+/** Array of valid delegation statuses */
+export const DELEGATION_STATUSES = [
+  DelegationStatus.PENDING,
+  DelegationStatus.COMPLETED,
+  DelegationStatus.TIMEOUT,
+  DelegationStatus.CRASHED,
+  DelegationStatus.ESCALATED,
+] as const;
+
+/**
+ * Optional delegation intent source values.
+ */
+export const DelegationIntent = {
+  DELEGATION: 'delegation',
+  LEGACY_SPAWN: 'legacy-spawn',
+} as const;
+
+/** Type for delegation intent values */
+export type DelegationIntentValue = (typeof DelegationIntent)[keyof typeof DelegationIntent];
+
+/** Array of valid delegation intent values */
+export const DELEGATION_INTENTS = [
+  DelegationIntent.DELEGATION,
+  DelegationIntent.LEGACY_SPAWN,
+] as const;
+
+/**
+ * Regex patterns for delegation validation.
+ */
+export const DELEGATION_PATTERNS = {
+  DELEGATION_ID: /^dlg-[0-9a-f]{4}$/,
+  WU_ID: /^WU-\d+$/,
+};
+
+/**
+ * Delegation schema version discriminator (WU-2753, ADR-014 extension 1).
+ *
+ * v1 records have no `schemaVersion` field (legacy compat path).
+ * v2 records stamp `schemaVersion: 'v2'` and MUST carry the four ADR-014
+ * axes: requested_role, actual_role, capabilities, ownership_scope.
+ *
+ * Agent-runtime owns the role metadata contract as opaque strings. The
+ * software-delivery pack still owns the canonical vocabulary.
+ */
+export const DELEGATION_SCHEMA_VERSION_V2 = 'v2' as const;
+
+/** Known delegation schema versions (extensible by additive pack updates). */
+export const DELEGATION_SCHEMA_VERSIONS = [DELEGATION_SCHEMA_VERSION_V2] as const;
+
+/** Type union for delegation schema version values. */
+export type DelegationSchemaVersion = (typeof DELEGATION_SCHEMA_VERSIONS)[number];
+
+/**
+ * Error messages for schema validation.
+ */
+const ERROR_MESSAGES = {
+  DELEGATION_ID: 'Delegation ID must match pattern dlg-XXXX (e.g., dlg-a1b2)',
+  WU_ID: 'WU ID must match pattern WU-XXX (e.g., WU-1000)',
+  LANE_REQUIRED: 'Lane is required',
+  STATUS: `Status must be one of: ${DELEGATION_STATUSES.join(', ')}`,
+  INTENT: `Intent must be one of: ${DELEGATION_INTENTS.join(', ')}`,
+  TIMESTAMP_REQUIRED: 'Timestamp is required',
+  PICKUP_BY_REQUIRED: 'pickedUpBy must be a non-empty string when pickup is recorded',
+  BRIEF_HASH: 'briefAttestation.promptHash must be a 64-character lowercase sha256 hex digest',
+  BRIEF_ALGORITHM: 'briefAttestation.algorithm must be sha256',
+  BRIEF_CLIENT_REQUIRED: 'briefAttestation.clientName must be a non-empty string',
+} as const;
+
+const SHA256_HEX_256_REGEX = /^[a-f0-9]{64}$/;
+
+/**
+ * Optional wu:brief prompt attestation captured by wu:delegate.
+ */
+export const DelegationBriefAttestationSchema = z.object({
+  algorithm: z.literal('sha256', { error: ERROR_MESSAGES.BRIEF_ALGORITHM }),
+  promptHash: z.string().regex(SHA256_HEX_256_REGEX, { message: ERROR_MESSAGES.BRIEF_HASH }),
+  promptLength: z.number().int().nonnegative(),
+  generatedAt: z.string().datetime({ message: ERROR_MESSAGES.TIMESTAMP_REQUIRED }),
+  clientName: z.string().min(1, { message: ERROR_MESSAGES.BRIEF_CLIENT_REQUIRED }),
+});
+
+/**
+ * ADR-014 role descriptor — agent-runtime carries opaque strings; the
+ * software-delivery pack owns the AgentLifecycleRole vocabulary.
+ */
+export const DelegationRoleDescriptorSchema = z.object({
+  lifecycle_role: z.string().min(1, { message: 'lifecycle_role must be non-empty' }),
+  specialty_profile: z.string().min(1, { message: 'specialty_profile must be non-empty' }),
+  role_alias: z.string().min(1).optional(),
+  capabilities: z.array(z.string()),
+});
+
+/**
+ * ADR-014 ownership scope for agent coordination.
+ */
+export const DelegationOwnershipScopeSchema = z.object({
+  initiative_id: z.string().min(1).optional(),
+  wu_ids: z.array(z.string().min(1)).optional(),
+  lane: z.string().min(1).optional(),
+  responsibility_kinds: z.array(z.string().min(1)),
+});
+
+/**
+ * Delegation event base schema (shared by v1-compat and v2).
+ */
+const DelegationEventBaseSchema = z.object({
+  id: z.string().regex(DELEGATION_PATTERNS.DELEGATION_ID, {
+    message: ERROR_MESSAGES.DELEGATION_ID,
+  }),
+  parentWuId: z.string().regex(DELEGATION_PATTERNS.WU_ID, { message: ERROR_MESSAGES.WU_ID }),
+  targetWuId: z.string().regex(DELEGATION_PATTERNS.WU_ID, { message: ERROR_MESSAGES.WU_ID }),
+  lane: z.string().min(1, { message: ERROR_MESSAGES.LANE_REQUIRED }),
+  intent: z.enum(DELEGATION_INTENTS, { error: ERROR_MESSAGES.INTENT }).optional(),
+  delegatedAt: z.string().datetime({ message: ERROR_MESSAGES.TIMESTAMP_REQUIRED }),
+  status: z.enum(DELEGATION_STATUSES, { error: ERROR_MESSAGES.STATUS }),
+  completedAt: z.string().datetime().nullable(),
+  pickedUpAt: z.string().datetime().optional(),
+  pickedUpBy: z.string().min(1, { message: ERROR_MESSAGES.PICKUP_BY_REQUIRED }).optional(),
+  briefAttestation: DelegationBriefAttestationSchema.optional(),
+});
+
+/**
+ * Legacy v1-compat delegation event schema.
+ */
+const DelegationEventV1Schema = DelegationEventBaseSchema.extend({
+  schemaVersion: z.undefined().optional(),
+  requested_role: DelegationRoleDescriptorSchema.optional(),
+  actual_role: DelegationRoleDescriptorSchema.optional(),
+  capabilities: z.array(z.string()).optional(),
+  ownership_scope: DelegationOwnershipScopeSchema.optional(),
+});
+
+/**
+ * v2 delegation event schema (WU-2753, ADR-014 extension 1).
+ */
+const DelegationEventV2Schema = DelegationEventBaseSchema.extend({
+  schemaVersion: z.literal(DELEGATION_SCHEMA_VERSION_V2),
+  requested_role: DelegationRoleDescriptorSchema,
+  actual_role: DelegationRoleDescriptorSchema,
+  capabilities: z.array(z.string()),
+  ownership_scope: DelegationOwnershipScopeSchema,
+});
+
+/**
+ * Delegation event schema — discriminated union across v1-compat and v2.
+ */
+export const DelegationEventSchema = z.union([DelegationEventV2Schema, DelegationEventV1Schema]);
+
+/** TypeScript type inferred from schema */
+export type DelegationEvent = z.infer<typeof DelegationEventSchema>;
+export type DelegationEventV1 = z.infer<typeof DelegationEventV1Schema>;
+export type DelegationEventV2 = z.infer<typeof DelegationEventV2Schema>;
+export type DelegationBriefAttestation = z.infer<typeof DelegationBriefAttestationSchema>;
+export type DelegationRoleDescriptor = z.infer<typeof DelegationRoleDescriptorSchema>;
+export type DelegationOwnershipScope = z.infer<typeof DelegationOwnershipScopeSchema>;
+
+/**
+ * Bundle of the four ADR-014 axes that launch receipts and wu:delegate emit
+ * on every new delegation (WU-2753).
+ */
+export interface DelegationRoleContract {
+  requested_role: DelegationRoleDescriptor;
+  actual_role: DelegationRoleDescriptor;
+  capabilities: string[];
+  ownership_scope: DelegationOwnershipScope;
+}
+
+/**
+ * Validates delegation event data against schema.
+ */
+export function validateDelegationEvent(data: unknown) {
+  return DelegationEventSchema.safeParse(data);
+}
+
+/**
+ * Returns true if the delegation event carries the v2 role contract.
+ */
+export function isV2DelegationEvent(event: DelegationEvent): event is DelegationEventV2 {
+  return event.schemaVersion === DELEGATION_SCHEMA_VERSION_V2;
+}
+
+/**
+ * Generates a unique delegation ID.
+ */
+export function generateDelegationId(parentWuId: string, targetWuId: string): string {
+  const timestamp = Date.now().toString();
+  const randomBytes = crypto.randomBytes(4).toString('hex');
+  const input = `${parentWuId}:${targetWuId}:${timestamp}:${randomBytes}`;
+  const hash = crypto.createHash('sha256').update(input).digest('hex');
+  return `dlg-${hash.slice(0, 4)}`;
+}

package/packs/agent-runtime/delegation-registry-store.ts

@@ -0,0 +1,269 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Delegation Registry Store (ADR-014 follow-up, WU-2763)
+ *
+ * Event-sourced state store for tracking sub-agent delegations.
+ * Stores events in .lumenflow/state/delegation-registry.jsonl (append-only, git-friendly).
+ *
+ * Core now re-exports this module as a compatibility shim.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createError, ErrorCodes } from '@lumenflow/kernel/primitives/error-handler';
+import {
+  validateDelegationEvent,
+  generateDelegationId,
+  DelegationStatus,
+  DELEGATION_SCHEMA_VERSION_V2,
+  type DelegationEvent,
+  type DelegationBriefAttestation,
+  type DelegationIntentValue,
+  type DelegationRoleContract,
+} from './delegation-registry-schema.js';
+
+interface ValidationIssueLike {
+  path: PropertyKey[];
+  message: string;
+}
+
+/** Delegation registry file name constant */
+export const DELEGATION_REGISTRY_FILE_NAME = 'delegation-registry.jsonl';
+
+function formatValidationIssues(issues: readonly ValidationIssueLike[]): string {
+  return issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join(', ');
+}
+
+/**
+ * Delegation Registry Store class
+ */
+export class DelegationRegistryStore {
+  private readonly baseDir: string;
+  private readonly registryFilePath: string;
+  private readonly delegations: Map<string, DelegationEvent>;
+  private readonly byParent: Map<string, string[]>;
+  private readonly byTarget: Map<string, string>;
+
+  /**
+   * @param {string} baseDir - Directory containing .lumenflow/state/
+   */
+  constructor(baseDir: string) {
+    this.baseDir = baseDir;
+    this.registryFilePath = path.join(baseDir, DELEGATION_REGISTRY_FILE_NAME);
+    this.delegations = new Map();
+    this.byParent = new Map();
+    this.byTarget = new Map();
+  }
+
+  /**
+   * Loads and replays events from JSONL file into current state.
+   */
+  async load(): Promise<void> {
+    this.delegations.clear();
+    this.byParent.clear();
+    this.byTarget.clear();
+
+    let content: string;
+    try {
+      content = await fs.readFile(this.registryFilePath, 'utf-8');
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return;
+      }
+      throw error;
+    }
+
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const rawLine = lines[i];
+      if (typeof rawLine !== 'string') {
+        continue;
+      }
+      const line = rawLine.trim();
+      if (!line) {
+        continue;
+      }
+
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch (error) {
+        throw createError(
+          ErrorCodes.PARSE_ERROR,
+          `Malformed JSON on line ${i + 1}: ${error.message}`,
+        );
+      }
+
+      const validation = validateDelegationEvent(parsed);
+      if (!validation.success) {
+        throw createError(
+          ErrorCodes.VALIDATION_ERROR,
+          `Validation error on line ${i + 1}: ${formatValidationIssues(validation.error.issues)}`,
+        );
+      }
+
+      this.applyEvent(validation.data);
+    }
+  }
+
+  /**
+   * Applies an event to the in-memory state.
+   */
+  private applyEvent(event: DelegationEvent): void {
+    const { id, parentWuId, targetWuId } = event;
+    this.delegations.set(id, event);
+
+    if (!this.byParent.has(parentWuId)) {
+      this.byParent.set(parentWuId, []);
+    }
+    const parentDelegations = this.byParent.get(parentWuId);
+    if (!parentDelegations) {
+      return;
+    }
+    if (!parentDelegations.includes(id)) {
+      parentDelegations.push(id);
+    }
+
+    this.byTarget.set(targetWuId, id);
+  }
+
+  /**
+   * Appends an event to the registry file.
+   */
+  private async appendEvent(event: DelegationEvent): Promise<void> {
+    const validation = validateDelegationEvent(event);
+    if (!validation.success) {
+      throw createError(
+        ErrorCodes.VALIDATION_ERROR,
+        `Validation error: ${formatValidationIssues(validation.error.issues)}`,
+      );
+    }
+
+    await fs.mkdir(this.baseDir, { recursive: true });
+    await fs.appendFile(this.registryFilePath, JSON.stringify(event) + '\n', 'utf-8');
+  }
+
+  /**
+   * Records a new delegation event with pending status.
+   */
+  async record(
+    parentWuId: string,
+    targetWuId: string,
+    lane: string,
+    intent?: DelegationIntentValue,
+    briefAttestation?: DelegationBriefAttestation,
+    delegationId?: string,
+    roleContract?: DelegationRoleContract,
+  ): Promise<string> {
+    const id = delegationId ?? generateDelegationId(parentWuId, targetWuId);
+
+    const event: DelegationEvent = {
+      id,
+      parentWuId,
+      targetWuId,
+      lane,
+      ...(intent ? { intent } : {}),
+      delegatedAt: new Date().toISOString(),
+      status: DelegationStatus.PENDING,
+      completedAt: null,
+      ...(briefAttestation ? { briefAttestation } : {}),
+      ...(roleContract
+        ? {
+            schemaVersion: DELEGATION_SCHEMA_VERSION_V2,
+            requested_role: roleContract.requested_role,
+            actual_role: roleContract.actual_role,
+            capabilities: roleContract.capabilities,
+            ownership_scope: roleContract.ownership_scope,
+          }
+        : {}),
+    } as DelegationEvent;
+
+    await this.appendEvent(event);
+    this.applyEvent(event);
+    return id;
+  }
+
+  /**
+   * Updates the status of a delegation.
+   */
+  async updateStatus(delegationId: string, status: string): Promise<void> {
+    const existing = this.delegations.get(delegationId);
+    if (!existing) {
+      throw createError(ErrorCodes.DELEGATION_NOT_FOUND, `Delegation ID ${delegationId} not found`);
+    }
+
+    const event: DelegationEvent = {
+      ...existing,
+      status: status as DelegationEvent['status'],
+      completedAt: new Date().toISOString(),
+    };
+
+    await this.appendEvent(event);
+    this.applyEvent(event);
+  }
+
+  /**
+   * Records claim-time pickup evidence for a delegation entry.
+   */
+  async recordPickup(delegationId: string, pickedUpBy: string, pickedUpAt?: string): Promise<void> {
+    const existing = this.delegations.get(delegationId);
+    if (!existing) {
+      throw createError(ErrorCodes.DELEGATION_NOT_FOUND, `Delegation ID ${delegationId} not found`);
+    }
+
+    const event: DelegationEvent = {
+      ...existing,
+      pickedUpBy,
+      pickedUpAt: pickedUpAt ?? new Date().toISOString(),
+    };
+
+    await this.appendEvent(event);
+    this.applyEvent(event);
+  }
+
+  /**
+   * Gets all delegations for a parent WU.
+   */
+  getByParent(parentWuId: string): DelegationEvent[] {
+    const delegationIds = this.byParent.get(parentWuId) ?? [];
+    return delegationIds
+      .map((id) => this.delegations.get(id))
+      .filter((event): event is DelegationEvent => event !== undefined);
+  }
+
+  /**
+   * Gets delegation for a target WU.
+   */
+  getByTarget(targetWuId: string): DelegationEvent | null {
+    const delegationId = this.byTarget.get(targetWuId);
+    if (!delegationId) {
+      return null;
+    }
+    return this.delegations.get(delegationId) ?? null;
+  }
+
+  /**
+   * Gets all pending delegations.
+   */
+  getPendingDelegations(): DelegationEvent[] {
+    return Array.from(this.delegations.values()).filter(
+      (delegation) => delegation.status === DelegationStatus.PENDING,
+    );
+  }
+
+  /**
+   * Gets all delegations as an array.
+   */
+  getAllDelegations(): DelegationEvent[] {
+    return Array.from(this.delegations.values());
+  }
+
+  /**
+   * Gets delegation by ID.
+   */
+  getById(delegationId: string): DelegationEvent | null {
+    return this.delegations.get(delegationId) ?? null;
+  }
+}