@lumenflow/cli 5.5.0 → 5.7.14

package/packs/agent-runtime/capability-factory.ts

@@ -1,104 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-import type { PackCapabilityFactory } from '@lumenflow/kernel';
-import { AGENT_RUNTIME_TOOL_NAMES } from './types.js';
-import type { AgentRuntimeModelProfileConfig, AgentRuntimePackConfig } from './types.js';
-
-export const createAgentRuntimeCapabilityFactory: PackCapabilityFactory = async (input) => {
-  if (input.tool.name !== AGENT_RUNTIME_TOOL_NAMES.EXECUTE_TURN) {
-    return {};
-  }
-
-  const packConfig = normalizePackConfig(input.packConfig);
-  if (!packConfig) {
-    return {};
-  }
-
-  const requiredEnv = new Set<string>();
-  const providerHosts = new Set<string>();
-
-  for (const [profileName, profile] of Object.entries(packConfig.models)) {
-    requiredEnv.add(profile.api_key_env);
-    if (profile.base_url_env) {
-      requiredEnv.add(profile.base_url_env);
-    }
-
-    const resolvedBaseUrl = resolveProfileBaseUrl(profileName, profile);
-    if (!resolvedBaseUrl) {
-      continue;
-    }
-    providerHosts.add(toNetworkAllowlistEntry(profileName, resolvedBaseUrl));
-  }
-
-  return {
-    ...(requiredEnv.size > 0 ? { required_env: [...requiredEnv].sort() } : {}),
-    ...(providerHosts.size > 0
-      ? {
-          required_scopes: [
-            {
-              type: 'network' as const,
-              posture: 'allowlist' as const,
-              allowlist_entries: [...providerHosts].sort(),
-            },
-          ],
-        }
-      : {}),
-  };
-};
-
-function normalizePackConfig(value: unknown): AgentRuntimePackConfig | null {
-  if (!isRecord(value) || !isRecord(value.models)) {
-    return null;
-  }
-
-  return value as unknown as AgentRuntimePackConfig;
-}
-
-function resolveProfileBaseUrl(
-  profileName: string,
-  profile: AgentRuntimeModelProfileConfig,
-): string | null {
-  if (typeof profile.base_url === 'string' && profile.base_url.trim().length > 0) {
-    return profile.base_url.trim();
-  }
-
-  if (!profile.base_url_env) {
-    return null;
-  }
-
-  const environmentValue = process.env[profile.base_url_env];
-  if (typeof environmentValue !== 'string' || environmentValue.trim().length === 0) {
-    throw new Error(
-      `agent_runtime.models.${profileName}.base_url_env references "${profile.base_url_env}" but it is not set.`,
-    );
-  }
-
-  return environmentValue.trim();
-}
-
-function toNetworkAllowlistEntry(profileName: string, baseUrl: string): string {
-  let parsed: URL;
-  try {
-    parsed = new URL(baseUrl);
-  } catch (error) {
-    throw new Error(
-      `agent_runtime.models.${profileName} must resolve to a valid absolute base URL, got "${baseUrl}".`,
-      { cause: error },
-    );
-  }
-
-  const port =
-    parsed.port || (parsed.protocol === 'https:' ? '443' : parsed.protocol === 'http:' ? '80' : '');
-  if (!port) {
-    throw new Error(
-      `agent_runtime.models.${profileName} uses protocol "${parsed.protocol}" without an explicit port.`,
-    );
-  }
-
-  return `${parsed.hostname}:${port}`;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}

package/packs/agent-runtime/constants.ts

@@ -1,21 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-export const AGENT_RUNTIME_PACK_ID = 'agent-runtime' as const;
-export const AGENT_RUNTIME_PACK_VERSION = '0.1.0' as const;
-export const AGENT_RUNTIME_DOMAIN = AGENT_RUNTIME_PACK_ID;
-export const AGENT_RUNTIME_CONFIG_KEY = 'agent_runtime' as const;
-export const AGENT_RUNTIME_POLICY_ID_PREFIX = `${AGENT_RUNTIME_PACK_ID}.policy` as const;
-export const AGENT_RUNTIME_MANIFEST_FILE_NAME = 'manifest.yaml' as const;
-export const AGENT_RUNTIME_CONFIG_SCHEMA_FILE = 'config.schema.json' as const;
-export const SHA256_ALGORITHM = 'sha256' as const;
-export const UTF8_ENCODING = 'utf8' as const;
-export const AGENT_RUNTIME_STORAGE_PATTERN = '.agent-runtime/**' as const;
-export const AGENT_RUNTIME_API_KEY_ENV = 'AGENT_RUNTIME_API_KEY' as const;
-export const AGENT_RUNTIME_BASE_URL_ENV = 'AGENT_RUNTIME_BASE_URL' as const;
-export const AGENT_RUNTIME_STATIC_PROVIDER_ALLOWLIST = ['model-provider.invalid:443'] as const;
-export const AGENT_RUNTIME_STATIC_PROVIDER_URLS = ['https://model-provider.invalid/'] as const;
-export const AGENT_RUNTIME_AGENT_INTENT_METADATA_KEY = 'agent_intent' as const;
-export const AGENT_RUNTIME_AGENT_TURN_INDEX_METADATA_KEY = 'agent_turn_index' as const;
-export const AGENT_RUNTIME_AGENT_TOOL_CALL_COUNT_METADATA_KEY = 'agent_tool_call_count' as const;
-export const AGENT_RUNTIME_AGENT_WORKFLOW_NODE_ID_METADATA_KEY = 'agent_workflow_node_id' as const;

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

@@ -1,220 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-/**
- * 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

@@ -1,269 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-/**
- * 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;
-  }
-}