@lumenflow/cli 5.5.0 → 5.7.12

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

@@ -1,48 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-//
-// WU-2732 (INIT-060 Phase 3, ADR-013 §6 governance surface):
-// Port interface for the six remote-control tools. Both the mock
-// tracer-bullet adapter (this WU) and the real kernel-side adapter
-// (WU-2733) implement this port — so the real impl lands without
-// changing the wire contract. This mirrors ADR-013's ChannelBridge
-// port pattern (single port, multiple adapters).
-
-import type { AbortTurnInvocationResult, RemoteControlInvocationResult } from './types.js';
-
-/**
- * Minimum input shape every remote-control tool accepts. The session
- * identifier is the load-bearing field: it pins which agent-runtime
- * session the command targets. Real impls in WU-2733 will extend this
- * with per-tool specific fields (e.g. autonomy level for elevate);
- * extensions MUST be additive to preserve the wire contract.
- */
-export interface RemoteControlInvocationInput {
-  session_id?: string;
-}
-
-export interface AbortTurnInvocationInput extends RemoteControlInvocationInput {
-  /**
-   * Operator-supplied reason surfaced in the emitted
-   * `agent-runtime:turn_aborted` event in the real impl. The mock
-   * tracer-bullet records this for round-trip verification but does
-   * not emit the event (WU-2733 wires the real emission per
-   * ADR-013 §1 abort table).
-   */
-  reason?: string;
-}
-
-/**
- * Remote-control port. The six methods correspond 1:1 to the six
- * manifest-declared tool names. Keeping them as separate methods (not
- * a single `invoke(name, input)` dispatcher) lets TypeScript enforce
- * per-tool input/output types at the call site.
- */
-export interface RemoteControlPort {
-  resumeWorkflow(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult>;
-  pauseTurn(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult>;
-  abortTurn(input: AbortTurnInvocationInput): Promise<AbortTurnInvocationResult>;
-  elevateAutonomy(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult>;
-  lowerAutonomy(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult>;
-  approveInflight(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult>;
-}

package/packs/agent-runtime/remote-controls/state-store.ts

@@ -1,258 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-//
-// WU-2733 (INIT-060 Phase 3, ADR-013 §1 abort + §6 governance):
-// Sidecar persistence for remote-control session state (pause marker,
-// autonomy level, abort record, inflight approval handle). Kept
-// separate from the core orchestration workflow state store so the
-// existing strict schema validator doesn't need schema-version bumps
-// and so remote-control operations remain independently observable
-// via a dedicated on-disk artefact (`.agent-runtime/remote-controls/`).
-
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-
-export const REMOTE_CONTROL_STATE_DIRECTORY = path.join('.agent-runtime', 'remote-controls');
-
-/** Canonical autonomy bands. Declaration order = low→high. */
-export const AGENT_RUNTIME_AUTONOMY_LEVELS = {
-  MANUAL: 'manual',
-  ASSISTED: 'assisted',
-  AUTO: 'auto',
-} as const;
-
-export type AgentRuntimeAutonomyLevel =
-  (typeof AGENT_RUNTIME_AUTONOMY_LEVELS)[keyof typeof AGENT_RUNTIME_AUTONOMY_LEVELS];
-
-export const AGENT_RUNTIME_AUTONOMY_LEVEL_VALUES = [
-  AGENT_RUNTIME_AUTONOMY_LEVELS.MANUAL,
-  AGENT_RUNTIME_AUTONOMY_LEVELS.ASSISTED,
-  AGENT_RUNTIME_AUTONOMY_LEVELS.AUTO,
-] as const satisfies readonly AgentRuntimeAutonomyLevel[];
-
-export const DEFAULT_AUTONOMY_LEVEL: AgentRuntimeAutonomyLevel =
-  AGENT_RUNTIME_AUTONOMY_LEVELS.ASSISTED;
-
-export interface RemoteControlPauseState {
-  paused: boolean;
-  paused_at: string | null;
-  resumed_at: string | null;
-  reason: string | null;
-}
-
-export interface RemoteControlAbortState {
-  aborted: boolean;
-  aborted_at: string | null;
-  cleanup_status: 'clean' | 'partial' | 'needs_recovery' | null;
-  recovery_action: string | null;
-  reason: string | null;
-}
-
-export interface RemoteControlInflightApproval {
-  request_id: string;
-  tool_name: string;
-  requested_at: string;
-}
-
-export interface RemoteControlSessionState {
-  schema_version: 1;
-  session_id: string;
-  autonomy_level: AgentRuntimeAutonomyLevel;
-  pause: RemoteControlPauseState;
-  abort: RemoteControlAbortState;
-  inflight_approvals: RemoteControlInflightApproval[];
-  updated_at: string;
-}
-
-const SCHEMA_VERSION_V1 = 1 as const;
-
-export interface RemoteControlStateStore {
-  load(sessionId: string): Promise<RemoteControlSessionState | null>;
-  save(state: RemoteControlSessionState): Promise<void>;
-  loadOrDefault(sessionId: string, now: string): Promise<RemoteControlSessionState>;
-}
-
-export interface CreateRemoteControlStateStoreInput {
-  workspaceRoot: string;
-}
-
-export function createRemoteControlStateStore(
-  input: CreateRemoteControlStateStoreInput,
-): RemoteControlStateStore {
-  const stateRoot = path.join(input.workspaceRoot, REMOTE_CONTROL_STATE_DIRECTORY);
-
-  async function load(sessionId: string): Promise<RemoteControlSessionState | null> {
-    const filePath = sessionFile(stateRoot, sessionId);
-    try {
-      const raw = await readFile(filePath, 'utf8');
-      return parseState(JSON.parse(raw), filePath);
-    } catch (error) {
-      const nodeError = error as NodeJS.ErrnoException;
-      if (nodeError.code === 'ENOENT') {
-        return null;
-      }
-      throw error;
-    }
-  }
-
-  async function save(state: RemoteControlSessionState): Promise<void> {
-    const filePath = sessionFile(stateRoot, state.session_id);
-    await mkdir(stateRoot, { recursive: true });
-    await writeFile(filePath, JSON.stringify(state), 'utf8');
-  }
-
-  async function loadOrDefault(sessionId: string, now: string): Promise<RemoteControlSessionState> {
-    const existing = await load(sessionId);
-    if (existing) {
-      return existing;
-    }
-    return buildDefaultState(sessionId, now);
-  }
-
-  return { load, save, loadOrDefault };
-}
-
-export function buildDefaultState(sessionId: string, now: string): RemoteControlSessionState {
-  return {
-    schema_version: SCHEMA_VERSION_V1,
-    session_id: sessionId,
-    autonomy_level: DEFAULT_AUTONOMY_LEVEL,
-    pause: {
-      paused: false,
-      paused_at: null,
-      resumed_at: null,
-      reason: null,
-    },
-    abort: {
-      aborted: false,
-      aborted_at: null,
-      cleanup_status: null,
-      recovery_action: null,
-      reason: null,
-    },
-    inflight_approvals: [],
-    updated_at: now,
-  };
-}
-
-function sessionFile(stateRoot: string, sessionId: string): string {
-  return path.join(stateRoot, `${sessionId}.json`);
-}
-
-function parseState(value: unknown, filePath: string): RemoteControlSessionState {
-  if (value === null || typeof value !== 'object') {
-    throw new Error(
-      `Failed to parse remote-control state at ${filePath}: expected an object payload.`,
-    );
-  }
-  const record = value as Record<string, unknown>;
-  if (record.schema_version !== SCHEMA_VERSION_V1) {
-    throw new Error(
-      `Failed to parse remote-control state at ${filePath}: unsupported schema_version "${String(record.schema_version)}".`,
-    );
-  }
-  const sessionId = requireString(record.session_id, `${filePath}.session_id`);
-  const autonomyLevel = requireAutonomyLevel(record.autonomy_level, `${filePath}.autonomy_level`);
-  const pause = parsePauseState(record.pause, `${filePath}.pause`);
-  const abort = parseAbortState(record.abort, `${filePath}.abort`);
-  const inflightApprovals = parseInflightApprovals(
-    record.inflight_approvals,
-    `${filePath}.inflight_approvals`,
-  );
-  const updatedAt = requireString(record.updated_at, `${filePath}.updated_at`);
-  return {
-    schema_version: SCHEMA_VERSION_V1,
-    session_id: sessionId,
-    autonomy_level: autonomyLevel,
-    pause,
-    abort,
-    inflight_approvals: inflightApprovals,
-    updated_at: updatedAt,
-  };
-}
-
-function parsePauseState(value: unknown, filePath: string): RemoteControlPauseState {
-  if (value === null || typeof value !== 'object') {
-    throw new Error(`Failed to parse remote-control state at ${filePath}: expected pause object.`);
-  }
-  const record = value as Record<string, unknown>;
-  return {
-    paused: typeof record.paused === 'boolean' ? record.paused : false,
-    paused_at: typeof record.paused_at === 'string' ? record.paused_at : null,
-    resumed_at: typeof record.resumed_at === 'string' ? record.resumed_at : null,
-    reason: typeof record.reason === 'string' ? record.reason : null,
-  };
-}
-
-function parseAbortState(value: unknown, filePath: string): RemoteControlAbortState {
-  if (value === null || typeof value !== 'object') {
-    throw new Error(`Failed to parse remote-control state at ${filePath}: expected abort object.`);
-  }
-  const record = value as Record<string, unknown>;
-  const cleanupStatus = record.cleanup_status;
-  return {
-    aborted: typeof record.aborted === 'boolean' ? record.aborted : false,
-    aborted_at: typeof record.aborted_at === 'string' ? record.aborted_at : null,
-    cleanup_status:
-      cleanupStatus === 'clean' || cleanupStatus === 'partial' || cleanupStatus === 'needs_recovery'
-        ? cleanupStatus
-        : null,
-    recovery_action: typeof record.recovery_action === 'string' ? record.recovery_action : null,
-    reason: typeof record.reason === 'string' ? record.reason : null,
-  };
-}
-
-function parseInflightApprovals(value: unknown, filePath: string): RemoteControlInflightApproval[] {
-  if (!Array.isArray(value)) {
-    return [];
-  }
-  return value
-    .map((entry, index) => parseInflightApproval(entry, `${filePath}[${index}]`))
-    .filter((entry): entry is RemoteControlInflightApproval => entry !== null);
-}
-
-function parseInflightApproval(
-  value: unknown,
-  filePath: string,
-): RemoteControlInflightApproval | null {
-  if (value === null || typeof value !== 'object') {
-    return null;
-  }
-  const record = value as Record<string, unknown>;
-  if (
-    typeof record.request_id !== 'string' ||
-    typeof record.tool_name !== 'string' ||
-    typeof record.requested_at !== 'string'
-  ) {
-    throw new Error(
-      `Failed to parse remote-control state at ${filePath}: malformed inflight approval entry.`,
-    );
-  }
-  return {
-    request_id: record.request_id,
-    tool_name: record.tool_name,
-    requested_at: record.requested_at,
-  };
-}
-
-function requireString(value: unknown, filePath: string): string {
-  if (typeof value !== 'string' || value.length === 0) {
-    throw new Error(
-      `Failed to parse remote-control state at ${filePath}: expected a non-empty string.`,
-    );
-  }
-  return value;
-}
-
-function requireAutonomyLevel(value: unknown, filePath: string): AgentRuntimeAutonomyLevel {
-  if (
-    value === AGENT_RUNTIME_AUTONOMY_LEVELS.MANUAL ||
-    value === AGENT_RUNTIME_AUTONOMY_LEVELS.ASSISTED ||
-    value === AGENT_RUNTIME_AUTONOMY_LEVELS.AUTO
-  ) {
-    return value;
-  }
-  throw new Error(
-    `Failed to parse remote-control state at ${filePath}: unknown autonomy level "${String(value)}".`,
-  );
-}

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

@@ -1,105 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-//
-// WU-2732 (INIT-060 Phase 3, ADR-013 §1 + §6 tracer bullet):
-// Remote-control tool name registry and port/result shapes. The six
-// tools here form the conductor-mode governance surface for the
-// agent-runtime pack. Real implementations land in WU-2733; this file
-// defines the wire contract the real impl must satisfy without
-// re-deciding tool names or payload shapes.
-
-import type { AgentRuntimeCleanupStatus } from '../turn-lifecycle-events.js';
-
-/**
- * Canonical remote-control tool names. Prefixed with the pack slug per
- * ADR-013 §Event Namespacing convention (extended to tool names for
- * consistency with WU-2729 software-delivery pack exposure precedent).
- */
-export const AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES = {
-  RESUME_WORKFLOW: 'agent-runtime:resume_workflow',
-  PAUSE_TURN: 'agent-runtime:pause_turn',
-  ABORT_TURN: 'agent-runtime:abort_turn',
-  ELEVATE_AUTONOMY: 'agent-runtime:elevate_autonomy',
-  LOWER_AUTONOMY: 'agent-runtime:lower_autonomy',
-  APPROVE_INFLIGHT: 'agent-runtime:approve_inflight',
-} as const;
-
-export type AgentRuntimeRemoteControlToolName =
-  (typeof AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES)[keyof typeof AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES];
-
-/**
- * Declaration order matters: callers (HTTP surface allowlist, conductor
- * UI) render the list in this sequence without re-sorting.
- */
-export const AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAME_VALUES = [
-  AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.RESUME_WORKFLOW,
-  AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.PAUSE_TURN,
-  AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN,
-  AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ELEVATE_AUTONOMY,
-  AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.LOWER_AUTONOMY,
-  AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.APPROVE_INFLIGHT,
-] as const satisfies readonly AgentRuntimeRemoteControlToolName[];
-
-/**
- * Well-known approval identifier the agent-runtime pack requests for
- * safety-critical remote controls (abort, pause, elevate). Single
- * identifier per ADR-013 §6 governance lock — cloud renders the same
- * approval gate regardless of which of the gated tools was invoked.
- */
-export const AGENT_RUNTIME_REMOTE_CONTROL_APPROVAL_ID = 'agent-runtime:remote_control' as const;
-
-/**
- * Mapping from remote-control tool name to its declared
- * `required_approvals` manifest entry. Gated tools request an explicit
- * approval identifier; safer/read-only tools declare an empty array so
- * the manifest stays minimally descriptive (matches WU-2729 convention).
- */
-export const AGENT_RUNTIME_REMOTE_CONTROL_APPROVALS: Record<
-  AgentRuntimeRemoteControlToolName,
-  readonly string[]
-> = {
-  [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.RESUME_WORKFLOW]: [],
-  [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.PAUSE_TURN]: [AGENT_RUNTIME_REMOTE_CONTROL_APPROVAL_ID],
-  [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN]: [AGENT_RUNTIME_REMOTE_CONTROL_APPROVAL_ID],
-  [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ELEVATE_AUTONOMY]: [
-    AGENT_RUNTIME_REMOTE_CONTROL_APPROVAL_ID,
-  ],
-  [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.LOWER_AUTONOMY]: [],
-  [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.APPROVE_INFLIGHT]: [],
-};
-
-/**
- * Deterministic mock session identifier returned by tracer-bullet
- * implementations. The real impl in WU-2733 reads the session from the
- * input payload; the mock returns a fixed value so round-trip tests
- * pin the wire contract without leaking runtime state.
- */
-export const MOCK_SESSION_ID = 'agent-runtime-remote-control-mock-session' as const;
-
-/**
- * Shared result shape for the five non-abort remote controls. Real
- * impls may extend this — the additive-only rule lets WU-2733 land
- * without contract drift.
- */
-export interface RemoteControlInvocationResult {
-  status: 'ok';
-  tool_name: AgentRuntimeRemoteControlToolName;
-  session_id: string;
-}
-
-/**
- * abort_turn carries the ADR-013 §1 abort contract: cleanup_status +
- * recovery_action. Cloud renders recovery_action as a hint; NEVER
- * auto-executes (see ADR-013 §1 safety lock).
- */
-export interface AbortTurnInvocationResult {
-  status: 'ok';
-  tool_name: typeof AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN;
-  session_id: string;
-  cleanup_status: AgentRuntimeCleanupStatus;
-  recovery_action: string | null;
-}
-
-export type AnyRemoteControlInvocationResult =
-  | RemoteControlInvocationResult
-  | AbortTurnInvocationResult;