@lumenflow/cli 4.24.0 → 5.0.0

package/packs/agent-runtime/memory-coordination-contract.ts

@@ -0,0 +1,86 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { createError, ErrorCodes } from '@lumenflow/kernel/primitives/error-handler';
+
+/**
+ * WU-2765: authoritative ADR-014 memory coordination field names.
+ *
+ * These axes are shared by mem:signal persistence and mem:context roster
+ * rendering, so they live with the agent-runtime pack rather than memory core.
+ */
+export const MEMORY_COORDINATION_SIGNAL_FIELD_NAMES = [
+  'role',
+  'target_role',
+  'initiative',
+  'delegation_id',
+] as const;
+
+export type MemoryCoordinationFieldName = (typeof MEMORY_COORDINATION_SIGNAL_FIELD_NAMES)[number];
+
+export interface MemoryCoordinationSignalFields {
+  role?: string;
+  target_role?: string;
+  initiative?: string;
+  delegation_id?: string;
+}
+
+export function isNonEmptyCoordinationFieldValue(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+export function normalizeCoordinationField(
+  value: string | undefined,
+  fieldName: MemoryCoordinationFieldName,
+): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const normalized = value.trim();
+  if (normalized.length === 0) {
+    throw createError(
+      ErrorCodes.VALIDATION_ERROR,
+      `Signal metadata fields must be non-empty strings when provided: ${fieldName}`,
+    );
+  }
+
+  return normalized;
+}
+
+/**
+ * WU-2755/WU-2765: compact signal summary attached to a roster row.
+ */
+export interface CoordinationRosterSignalSummary {
+  id: string;
+  message: string;
+  role?: string;
+  target_role?: string;
+  created_at: string;
+}
+
+/**
+ * WU-2755/WU-2765: one active delegation/session roster row.
+ */
+export interface CoordinationRosterEntry {
+  delegation_id: string;
+  target_wu_id: string;
+  lane?: string;
+  requested_role?: string;
+  actual_role?: string;
+  display_name?: string;
+  lifecycle_role?: string;
+  specialty_profile?: string;
+  current_wu?: string;
+  last_heartbeat?: string;
+  ownership_scope?: string;
+  status?: string;
+  recent_signals?: CoordinationRosterSignalSummary[];
+}
+
+/**
+ * WU-2755/WU-2765: caller-composed coordination roster input for mem:context.
+ */
+export interface CoordinationRoster {
+  entries: CoordinationRosterEntry[];
+}

package/packs/agent-runtime/memory.d.ts

@@ -0,0 +1,19 @@
+declare module '@lumenflow/memory' {
+  export interface StartSessionOptions {
+    wuId: string;
+    agentType?: string;
+    contextTier?: string;
+  }
+
+  export interface StartSessionResult {
+    success: boolean;
+    session?: {
+      id?: string | null;
+    };
+  }
+
+  export function startSession(
+    baseDir: string,
+    options: StartSessionOptions,
+  ): Promise<StartSessionResult>;
+}

package/packs/agent-runtime/orchestration.ts

@@ -16,6 +16,22 @@ import {
   AGENT_RUNTIME_AGENT_TURN_INDEX_METADATA_KEY,
   AGENT_RUNTIME_AGENT_WORKFLOW_NODE_ID_METADATA_KEY,
 } from './constants.js';
+import {
+  buildApprovalRequiredEvent,
+  buildBudgetThresholdEvent,
+  buildScheduledWakeupSetEvent,
+  buildToolCalledEvent,
+  buildTurnAbortedEvent,
+  buildTurnCompletedEvent,
+  buildTurnStartedEvent,
+  buildWorkflowNodeCompletedEvent,
+  buildWorkflowNodeFailedEvent,
+  buildWorkflowNodeStartedEvent,
+  buildWorkflowPausedEvent,
+  createZeroTurnCostBreakdown,
+  emitAgentRuntimeEvent,
+  type AgentRuntimeEventSink,
+} from './turn-lifecycle-events.js';
 import {
   AGENT_RUNTIME_TOOL_NAMES,
   AGENT_RUNTIME_TURN_STATUSES,
@@ -100,6 +116,7 @@ export interface RunGovernedAgentLoopInput {
   executeTurnInput: AgentRuntimeExecuteTurnInput;
   createContext: (metadata: Record<string, unknown>) => ExecutionContext;
   maxTurns?: number;
+  eventSink?: AgentRuntimeEventSink;
 }
 
 export type AgentRuntimeWorkflowStatus =
@@ -196,6 +213,7 @@ export interface ResumeGovernedAgentSessionInput {
   maxTurnsPerInvocation?: number;
   continuationMessages?: readonly AgentRuntimeMessage[];
   now?: () => string;
+  eventSink?: AgentRuntimeEventSink;
 }
 
 export interface StartGovernedAgentWorkflowInput {
@@ -205,6 +223,7 @@ export interface StartGovernedAgentWorkflowInput {
   createContext: (metadata: Record<string, unknown>) => ExecutionContext;
   maxTurnsPerInvocation?: number;
   now?: () => string;
+  eventSink?: AgentRuntimeEventSink;
 }
 
 export interface ResumeGovernedAgentWorkflowInput {
@@ -215,6 +234,7 @@ export interface ResumeGovernedAgentWorkflowInput {
   maxTurnsPerInvocation?: number;
   continuationMessagesByNodeId?: Record<string, readonly AgentRuntimeMessage[]>;
   now?: () => string;
+  eventSink?: AgentRuntimeEventSink;
 }
 
 export interface AgentRuntimeLoopCompletedResult {
@@ -542,6 +562,7 @@ export async function startGovernedAgentWorkflow(
     createContext: input.createContext,
     maxTurnsPerInvocation: input.maxTurnsPerInvocation,
     timestamp,
+    eventSink: input.eventSink,
   });
 
   const store = createAgentRuntimeWorkflowStateStore({
@@ -599,6 +620,7 @@ export async function resumeGovernedAgentWorkflow(
     createContext: input.createContext,
     maxTurnsPerInvocation: input.maxTurnsPerInvocation,
     timestamp,
+    eventSink: input.eventSink,
   });
 
   await store.save(result.state);
@@ -611,6 +633,7 @@ async function advanceGovernedAgentWorkflowState(input: {
   createContext: (metadata: Record<string, unknown>) => ExecutionContext;
   maxTurnsPerInvocation?: number;
   timestamp: string;
+  eventSink?: AgentRuntimeEventSink;
 }): Promise<{ state: AgentRuntimeWorkflowState; result: AgentRuntimeWorkflowAdvanceResult }> {
   const workflow = input.state.workflow;
   if (!workflow) {
@@ -680,6 +703,19 @@ async function advanceGovernedAgentWorkflowState(input: {
           ),
         };
 
+        for (const node of scheduledNodes) {
+          if (typeof node.wake_at === 'string') {
+            emitAgentRuntimeEvent(
+              input.eventSink,
+              buildScheduledWakeupSetEvent({
+                session_id: state.session_id,
+                node_id: node.node_id,
+                wake_at: node.wake_at,
+              }),
+            );
+          }
+        }
+
         return {
           state: scheduledState,
           result: {
@@ -712,6 +748,16 @@ async function advanceGovernedAgentWorkflowState(input: {
         };
       }
 
+      emitAgentRuntimeEvent(
+        input.eventSink,
+        buildWorkflowNodeFailedEvent({
+          session_id: state.session_id,
+          node_id: 'workflow',
+          error_code: 'AGENT_RUNTIME_WORKFLOW_STALLED',
+          error_message: 'Workflow cannot make progress because no nodes are ready or scheduled.',
+        }),
+      );
+
       return {
         state: {
           ...state,
@@ -739,6 +785,14 @@ async function advanceGovernedAgentWorkflowState(input: {
       continue;
     }
 
+    emitAgentRuntimeEvent(
+      input.eventSink,
+      buildWorkflowNodeStartedEvent({
+        session_id: state.session_id,
+        node_id: node.node_id,
+      }),
+    );
+
     const nodeResult = await runGovernedAgentLoopInternal({
       runtime: input.runtime,
       executeTurnInput: {
@@ -752,6 +806,7 @@ async function advanceGovernedAgentWorkflowState(input: {
         }),
       maxTurns: input.maxTurnsPerInvocation,
       turnBudgetBehavior: 'suspend',
+      eventSink: input.eventSink,
       initialCursor: {
         messages: node.messages,
         history: node.history,
@@ -762,6 +817,44 @@ async function advanceGovernedAgentWorkflowState(input: {
 
     state = updateWorkflowStateForNodeResult(state, node.node_id, nodeResult, input.timestamp);
 
+    if (nodeResult.kind === 'completed') {
+      emitAgentRuntimeEvent(
+        input.eventSink,
+        buildWorkflowNodeCompletedEvent({
+          session_id: state.session_id,
+          node_id: node.node_id,
+        }),
+      );
+    } else if (nodeResult.kind === 'approval_required') {
+      emitAgentRuntimeEvent(
+        input.eventSink,
+        buildWorkflowPausedEvent({
+          session_id: state.session_id,
+          node_id: node.node_id,
+          reason: WORKFLOW_WAITING_REASON,
+        }),
+      );
+    } else if (nodeResult.kind === 'suspended') {
+      emitAgentRuntimeEvent(
+        input.eventSink,
+        buildWorkflowPausedEvent({
+          session_id: state.session_id,
+          node_id: node.node_id,
+          reason: WORKFLOW_SUSPEND_REASON,
+        }),
+      );
+    } else {
+      emitAgentRuntimeEvent(
+        input.eventSink,
+        buildWorkflowNodeFailedEvent({
+          session_id: state.session_id,
+          node_id: node.node_id,
+          error_code: nodeResult.error.code,
+          error_message: nodeResult.error.message,
+        }),
+      );
+    }
+
     if (nodeResult.kind === 'approval_required') {
       return {
         state,
@@ -801,6 +894,7 @@ async function runGovernedAgentLoopInternal(
   input: RunGovernedAgentLoopInternalInput,
 ): Promise<AgentRuntimePersistedSessionResult> {
   const maxTurns = input.maxTurns ?? DEFAULT_MAX_ORCHESTRATION_TURNS;
+  const sessionId = input.executeTurnInput.session_id;
   const messages = input.initialCursor
     ? [...input.initialCursor.messages]
     : [...input.executeTurnInput.messages];
@@ -810,26 +904,71 @@ async function runGovernedAgentLoopInternal(
   let invocationTurnCount = 0;
 
   while (invocationTurnCount < maxTurns) {
-    const executeTurnOutput = await input.runtime.executeTool(
-      AGENT_RUNTIME_TOOL_NAMES.EXECUTE_TURN,
-      {
-        ...input.executeTurnInput,
-        messages: [...messages],
-      },
-      input.createContext({
-        [AGENT_RUNTIME_AGENT_TURN_INDEX_METADATA_KEY]: turnCount,
-        [AGENT_RUNTIME_AGENT_TOOL_CALL_COUNT_METADATA_KEY]: toolCallCount,
+    emitAgentRuntimeEvent(
+      input.eventSink,
+      buildTurnStartedEvent({
+        session_id: sessionId,
+        turn_index: turnCount,
+        model_profile: input.executeTurnInput.model_profile,
       }),
     );
 
+    let executeTurnOutput: ToolOutput;
+    try {
+      executeTurnOutput = await input.runtime.executeTool(
+        AGENT_RUNTIME_TOOL_NAMES.EXECUTE_TURN,
+        {
+          ...input.executeTurnInput,
+          messages: [...messages],
+        },
+        input.createContext({
+          [AGENT_RUNTIME_AGENT_TURN_INDEX_METADATA_KEY]: turnCount,
+          [AGENT_RUNTIME_AGENT_TOOL_CALL_COUNT_METADATA_KEY]: toolCallCount,
+        }),
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      emitAgentRuntimeEvent(
+        input.eventSink,
+        buildTurnAbortedEvent({
+          session_id: sessionId,
+          turn_index: turnCount,
+          cleanup_status: 'clean',
+          reason: message,
+        }),
+      );
+      return {
+        kind: 'error',
+        stage: 'execute_turn',
+        error: {
+          code: TOOL_ERROR_CODES.TOOL_EXECUTION_FAILED,
+          message,
+        },
+        messages,
+        turn_count: turnCount,
+        tool_call_count: toolCallCount,
+        history,
+      };
+    }
+
     if (!executeTurnOutput.success) {
+      const error = normalizeToolError(
+        executeTurnOutput.error,
+        'agent:execute-turn failed in the host loop.',
+      );
+      emitAgentRuntimeEvent(
+        input.eventSink,
+        buildTurnAbortedEvent({
+          session_id: sessionId,
+          turn_index: turnCount,
+          cleanup_status: 'clean',
+          reason: error.message,
+        }),
+      );
       return {
         kind: 'error',
         stage: 'execute_turn',
-        error: normalizeToolError(
-          executeTurnOutput.error,
-          'agent:execute-turn failed in the host loop.',
-        ),
+        error,
         messages,
         turn_count: turnCount,
         tool_call_count: toolCallCount,
@@ -839,6 +978,16 @@ async function runGovernedAgentLoopInternal(
 
     const normalizedTurn = normalizeTurnOutput(executeTurnOutput.data);
     if (!normalizedTurn) {
+      emitAgentRuntimeEvent(
+        input.eventSink,
+        buildTurnAbortedEvent({
+          session_id: sessionId,
+          turn_index: turnCount,
+          cleanup_status: 'clean',
+          reason:
+            'agent:execute-turn returned a payload that does not match the governed turn contract.',
+        }),
+      );
       return {
         kind: 'error',
         stage: 'execute_turn',
@@ -863,6 +1012,16 @@ async function runGovernedAgentLoopInternal(
     };
     history.push(historyEntry);
 
+    emitAgentRuntimeEvent(
+      input.eventSink,
+      buildTurnCompletedEvent({
+        session_id: sessionId,
+        turn_index: currentTurnIndex,
+        status: normalizedTurn.status,
+        cost_breakdown: createZeroTurnCostBreakdown(),
+      }),
+    );
+
     if (
       normalizedTurn.status !== AGENT_RUNTIME_TURN_STATUSES.TOOL_REQUEST ||
       !normalizedTurn.requested_tool
@@ -878,24 +1037,70 @@ async function runGovernedAgentLoopInternal(
     }
 
     const toolCallId = `${TOOL_CALL_ID_PREFIX}-${toolCallCount + 1}`;
-    const toolOutput = await input.runtime.executeTool(
-      normalizedTurn.requested_tool.name,
-      normalizedTurn.requested_tool.input,
-      input.createContext({
-        [AGENT_RUNTIME_AGENT_INTENT_METADATA_KEY]: normalizedTurn.intent,
-        [AGENT_RUNTIME_AGENT_TURN_INDEX_METADATA_KEY]: currentTurnIndex,
-        [AGENT_RUNTIME_AGENT_TOOL_CALL_COUNT_METADATA_KEY]: toolCallCount,
-      }),
-    );
+    let toolOutput: ToolOutput;
+    try {
+      toolOutput = await input.runtime.executeTool(
+        normalizedTurn.requested_tool.name,
+        normalizedTurn.requested_tool.input,
+        input.createContext({
+          [AGENT_RUNTIME_AGENT_INTENT_METADATA_KEY]: normalizedTurn.intent,
+          [AGENT_RUNTIME_AGENT_TURN_INDEX_METADATA_KEY]: currentTurnIndex,
+          [AGENT_RUNTIME_AGENT_TOOL_CALL_COUNT_METADATA_KEY]: toolCallCount,
+        }),
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      emitAgentRuntimeEvent(
+        input.eventSink,
+        buildTurnAbortedEvent({
+          session_id: sessionId,
+          turn_index: currentTurnIndex,
+          cleanup_status: 'partial',
+          reason: message,
+        }),
+      );
+      return {
+        kind: 'error',
+        stage: 'execute_turn',
+        error: {
+          code: TOOL_ERROR_CODES.TOOL_EXECUTION_FAILED,
+          message,
+        },
+        messages,
+        turn_count: turnCount,
+        tool_call_count: toolCallCount,
+        history,
+      };
+    }
 
     toolCallCount += 1;
     historyEntry.tool_call_id = toolCallId;
     historyEntry.tool_output = toolOutput;
 
+    emitAgentRuntimeEvent(
+      input.eventSink,
+      buildToolCalledEvent({
+        session_id: sessionId,
+        turn_index: currentTurnIndex,
+        tool_name: normalizedTurn.requested_tool.name,
+        tool_call_id: toolCallId,
+      }),
+    );
+
     if (!toolOutput.success && toolOutput.error?.code === TOOL_ERROR_CODES.APPROVAL_REQUIRED) {
+      const requestId = extractApprovalRequestId(toolOutput);
+      emitAgentRuntimeEvent(
+        input.eventSink,
+        buildApprovalRequiredEvent({
+          session_id: sessionId,
+          turn_index: currentTurnIndex,
+          tool_name: normalizedTurn.requested_tool.name,
+          request_id: requestId,
+        }),
+      );
       return {
         kind: 'approval_required',
-        pending_request_id: extractApprovalRequestId(toolOutput),
+        pending_request_id: requestId,
         requested_tool: normalizedTurn.requested_tool,
         last_turn: normalizedTurn,
         messages,
@@ -914,6 +1119,16 @@ async function runGovernedAgentLoopInternal(
     );
   }
 
+  emitAgentRuntimeEvent(
+    input.eventSink,
+    buildBudgetThresholdEvent({
+      session_id: sessionId,
+      budget_name: 'max_turns_per_invocation',
+      threshold: maxTurns,
+      observed_value: invocationTurnCount,
+    }),
+  );
+
   if (input.turnBudgetBehavior === 'suspend') {
     return {
       kind: 'suspended',

package/packs/agent-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-agent-runtime",
-  "version": "4.24.0",
+  "version": "5.0.0",
   "description": "Agent runtime pack scaffold for LumenFlow — governed model-turn execution, pack config, and provider capability baselines",
   "keywords": [
     "lumenflow",
@@ -23,6 +23,13 @@
   "type": "module",
   "exports": {
     ".": "./dist/index.js",
+    "./agent-heartbeat": "./dist/agent-heartbeat.js",
+    "./auto-session-integration": "./dist/auto-session-integration.js",
+    "./delegation-registry-schema": "./dist/delegation-registry-schema.js",
+    "./delegation-registry-store": "./dist/delegation-registry-store.js",
+    "./delegation-tree": "./dist/delegation-tree.js",
+    "./memory-coordination-contract": "./dist/memory-coordination-contract.js",
+    "./session-schema": "./dist/session-schema.js",
     "./tools": "./dist/tools/index.js",
     "./tool-impl": "./dist/tool-impl/index.js"
   },
@@ -42,7 +49,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@lumenflow/kernel": "workspace:^"
+    "@lumenflow/kernel": "workspace:^",
+    "yaml": "^2.8.2",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "typescript": "^5.9.3",

package/packs/agent-runtime/remote-controls/index.ts

@@ -0,0 +1,7 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+export * from './port.js';
+export * from './types.js';
+export * from './state-store.js';
+export * from './operations.js';