@lumenflow/cli 4.23.0 → 5.0.0

package/packs/agent-runtime/tool-impl/remote-controls.mock.ts

@@ -0,0 +1,252 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+//
+// WU-2732 (INIT-060 Phase 3, ADR-013 §1 abort + §6 governance):
+// Pattern A tracer-bullet mock implementation for the six
+// remote-control tools. Returns deterministic fixed responses so the
+// wire contract (manifest entries, POST /tools/:name round-trip,
+// tool_called emission) can be proven BEFORE the real kernel-side
+// implementation lands in WU-2733.
+//
+// REAL IMPL WILL REPLACE THIS FILE: WU-2733 ships
+// tool-impl/remote-controls.ts with the real pause/resume/abort logic.
+// The mock's role is purely contract stabilisation.
+
+import { randomUUID } from 'node:crypto';
+import type { ExecutionContext, ToolOutput } from '@lumenflow/kernel';
+import {
+  AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES,
+  MOCK_SESSION_ID,
+  type AbortTurnInvocationResult,
+  type AgentRuntimeRemoteControlToolName,
+  type AnyRemoteControlInvocationResult,
+  type RemoteControlInvocationResult,
+} from '../remote-controls/types.js';
+import type {
+  AbortTurnInvocationInput,
+  RemoteControlInvocationInput,
+  RemoteControlPort,
+} from '../remote-controls/port.js';
+import {
+  buildToolCalledEvent,
+  emitAgentRuntimeEvent,
+  type AgentRuntimeEventSink,
+} from '../turn-lifecycle-events.js';
+
+const MOCK_TURN_INDEX = 0;
+const MOCK_CLEANUP_STATUS_CLEAN = 'clean' as const;
+const MOCK_ABORT_RECOVERY_ACTION: string | null = null;
+
+/**
+ * Mock adapter implementing RemoteControlPort. Every invocation:
+ *  1. Returns a deterministic response matching the declared contract.
+ *  2. Emits `agent-runtime:tool_called` via the supplied sink (ADR-013
+ *     §6 governance — every tool call is auditable).
+ *
+ * Fixed session_id + turn_index in the emitted event mean tests can
+ * assert exact payloads without runtime coupling.
+ */
+export class MockRemoteControlAdapter implements RemoteControlPort {
+  constructor(private readonly eventSink?: AgentRuntimeEventSink) {}
+
+  async resumeWorkflow(
+    input: RemoteControlInvocationInput,
+  ): Promise<RemoteControlInvocationResult> {
+    return this.handle(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.RESUME_WORKFLOW, input);
+  }
+
+  async pauseTurn(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult> {
+    return this.handle(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.PAUSE_TURN, input);
+  }
+
+  async abortTurn(input: AbortTurnInvocationInput): Promise<AbortTurnInvocationResult> {
+    const sessionId = resolveSessionId(input.session_id);
+    this.emitToolCalled(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN, sessionId);
+    return {
+      status: 'ok',
+      tool_name: AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN,
+      session_id: sessionId,
+      cleanup_status: MOCK_CLEANUP_STATUS_CLEAN,
+      recovery_action: MOCK_ABORT_RECOVERY_ACTION,
+    };
+  }
+
+  async elevateAutonomy(
+    input: RemoteControlInvocationInput,
+  ): Promise<RemoteControlInvocationResult> {
+    return this.handle(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ELEVATE_AUTONOMY, input);
+  }
+
+  async lowerAutonomy(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult> {
+    return this.handle(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.LOWER_AUTONOMY, input);
+  }
+
+  async approveInflight(
+    input: RemoteControlInvocationInput,
+  ): Promise<RemoteControlInvocationResult> {
+    return this.handle(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.APPROVE_INFLIGHT, input);
+  }
+
+  private handle(
+    toolName: AgentRuntimeRemoteControlToolName,
+    input: RemoteControlInvocationInput,
+  ): RemoteControlInvocationResult {
+    const sessionId = resolveSessionId(input.session_id);
+    this.emitToolCalled(toolName, sessionId);
+    return {
+      status: 'ok',
+      tool_name: toolName,
+      session_id: sessionId,
+    };
+  }
+
+  private emitToolCalled(toolName: AgentRuntimeRemoteControlToolName, sessionId: string): void {
+    if (!this.eventSink) {
+      return;
+    }
+    emitAgentRuntimeEvent(
+      this.eventSink,
+      buildToolCalledEvent({
+        session_id: sessionId,
+        turn_index: MOCK_TURN_INDEX,
+        tool_name: toolName,
+        tool_call_id: randomUUID(),
+      }),
+    );
+  }
+}
+
+function resolveSessionId(input: string | undefined): string {
+  if (input !== undefined && input.trim().length > 0) {
+    return input;
+  }
+  return MOCK_SESSION_ID;
+}
+
+/**
+ * Factory for the default mock adapter. Tests and the manifest-wired
+ * tool functions below both use this so the fixture surface has a
+ * single instantiation path.
+ */
+export function createMockRemoteControlAdapter(
+  eventSink?: AgentRuntimeEventSink,
+): MockRemoteControlAdapter {
+  return new MockRemoteControlAdapter(eventSink);
+}
+
+/**
+ * Manifest-entrypoint adapter: each of the six exported functions
+ * matches the kernel's InProcessToolFn signature
+ * `(input: unknown, ctx: ExecutionContext) => Promise<ToolOutput>`.
+ *
+ * The module-scoped sink is rebound via `setMockRemoteControlEventSink`
+ * for tests that want to assert tool_called emission. Production
+ * wiring (HTTP surface → runtime → manifest-dispatch) will ignore the
+ * sink and rely on runtime-level tool_called events; the in-process
+ * sink is a mock-only convenience for the unit suite.
+ */
+let moduleEventSink: AgentRuntimeEventSink | undefined;
+
+export function setMockRemoteControlEventSink(sink: AgentRuntimeEventSink | undefined): void {
+  moduleEventSink = sink;
+}
+
+function buildToolOutput(data: AnyRemoteControlInvocationResult): ToolOutput {
+  return {
+    success: true,
+    data,
+    metadata: {
+      mock: true,
+      tracer_bullet: 'WU-2732',
+    },
+  };
+}
+
+async function invokeMock(
+  toolName: AgentRuntimeRemoteControlToolName,
+  input: unknown,
+): Promise<ToolOutput> {
+  const adapter = createMockRemoteControlAdapter(moduleEventSink);
+  const parsed = parseInput(input);
+
+  switch (toolName) {
+    case AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.RESUME_WORKFLOW:
+      return buildToolOutput(await adapter.resumeWorkflow(parsed));
+    case AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.PAUSE_TURN:
+      return buildToolOutput(await adapter.pauseTurn(parsed));
+    case AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN:
+      return buildToolOutput(await adapter.abortTurn(parsed));
+    case AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ELEVATE_AUTONOMY:
+      return buildToolOutput(await adapter.elevateAutonomy(parsed));
+    case AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.LOWER_AUTONOMY:
+      return buildToolOutput(await adapter.lowerAutonomy(parsed));
+    case AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.APPROVE_INFLIGHT:
+      return buildToolOutput(await adapter.approveInflight(parsed));
+    default:
+      return exhaustive(toolName);
+  }
+}
+
+function parseInput(input: unknown): AbortTurnInvocationInput {
+  if (input === null || input === undefined) {
+    return {};
+  }
+  if (typeof input !== 'object') {
+    return {};
+  }
+  const record = input as Record<string, unknown>;
+  const result: AbortTurnInvocationInput = {};
+  if (typeof record.session_id === 'string') {
+    result.session_id = record.session_id;
+  }
+  if (typeof record.reason === 'string') {
+    result.reason = record.reason;
+  }
+  return result;
+}
+
+function exhaustive(value: never): never {
+  throw new Error(`Unhandled remote-control tool: ${String(value)}`);
+}
+
+export async function resumeWorkflowMockTool(
+  input: unknown,
+  _ctx: ExecutionContext,
+): Promise<ToolOutput> {
+  return invokeMock(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.RESUME_WORKFLOW, input);
+}
+
+export async function pauseTurnMockTool(
+  input: unknown,
+  _ctx: ExecutionContext,
+): Promise<ToolOutput> {
+  return invokeMock(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.PAUSE_TURN, input);
+}
+
+export async function abortTurnMockTool(
+  input: unknown,
+  _ctx: ExecutionContext,
+): Promise<ToolOutput> {
+  return invokeMock(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN, input);
+}
+
+export async function elevateAutonomyMockTool(
+  input: unknown,
+  _ctx: ExecutionContext,
+): Promise<ToolOutput> {
+  return invokeMock(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ELEVATE_AUTONOMY, input);
+}
+
+export async function lowerAutonomyMockTool(
+  input: unknown,
+  _ctx: ExecutionContext,
+): Promise<ToolOutput> {
+  return invokeMock(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.LOWER_AUTONOMY, input);
+}
+
+export async function approveInflightMockTool(
+  input: unknown,
+  _ctx: ExecutionContext,
+): Promise<ToolOutput> {
+  return invokeMock(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.APPROVE_INFLIGHT, input);
+}

package/packs/agent-runtime/tool-impl/remote-controls.ts

@@ -0,0 +1,273 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+//
+// WU-2733 (INIT-060 Phase 3, ADR-013 §1 + §6):
+// Real kernel-side RemoteControlPort adapter + manifest-entrypoint tool
+// functions. Replaces the mock tracer-bullet entries from WU-2732
+// without changing tool names, permissions, scopes, approvals, input
+// schemas, or result shapes — the wire contract survives unchanged
+// because every shape is pinned by `remote-controls/port.ts` +
+// `remote-controls/types.ts`.
+//
+// Side effects: this adapter persists remote-control state under
+// `.agent-runtime/remote-controls/<session>.json` (sidecar, isolated
+// from the core orchestration workflow state store so existing
+// workflow schema validation is untouched) and emits events through
+// the supplied sink.
+
+import type { ExecutionContext, ToolOutput } from '@lumenflow/kernel';
+import {
+  abortTurn,
+  approveInflight,
+  elevateAutonomy,
+  lowerAutonomy,
+  pauseTurn,
+  resumeWorkflow,
+  type RemoteControlOperationContext,
+} from '../remote-controls/operations.js';
+import type {
+  AbortTurnInvocationInput,
+  RemoteControlInvocationInput,
+  RemoteControlPort,
+} from '../remote-controls/port.js';
+import {
+  createRemoteControlStateStore,
+  type RemoteControlStateStore,
+} from '../remote-controls/state-store.js';
+import {
+  AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES,
+  type AbortTurnInvocationResult,
+  type AgentRuntimeRemoteControlToolName,
+  type AnyRemoteControlInvocationResult,
+  type RemoteControlInvocationResult,
+} from '../remote-controls/types.js';
+import type { AgentRuntimeEventSink } from '../turn-lifecycle-events.js';
+
+export interface RealRemoteControlAdapterInput {
+  store: RemoteControlStateStore;
+  eventSink?: AgentRuntimeEventSink;
+  now?: () => string;
+}
+
+/**
+ * Real (non-mock) implementation of RemoteControlPort. Wires each port
+ * method to the corresponding operation in `operations.ts`. Every port
+ * method load-bears a `RemoteControlStateStore` so state survives
+ * restarts; emission goes through the `AgentRuntimeEventSink` supplied
+ * at construction (matches the mock's pattern so wiring parity holds).
+ */
+export class RealRemoteControlAdapter implements RemoteControlPort {
+  private readonly context: RemoteControlOperationContext;
+
+  constructor(input: RealRemoteControlAdapterInput) {
+    this.context = {
+      store: input.store,
+      eventSink: input.eventSink,
+      now: input.now ?? (() => new Date().toISOString()),
+    };
+  }
+
+  async resumeWorkflow(
+    input: RemoteControlInvocationInput,
+  ): Promise<RemoteControlInvocationResult> {
+    return resumeWorkflow(input, this.context);
+  }
+
+  async pauseTurn(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult> {
+    return pauseTurn(input, this.context);
+  }
+
+  async abortTurn(input: AbortTurnInvocationInput): Promise<AbortTurnInvocationResult> {
+    return abortTurn(input, this.context);
+  }
+
+  async elevateAutonomy(
+    input: RemoteControlInvocationInput,
+  ): Promise<RemoteControlInvocationResult> {
+    return elevateAutonomy(input, this.context);
+  }
+
+  async lowerAutonomy(input: RemoteControlInvocationInput): Promise<RemoteControlInvocationResult> {
+    return lowerAutonomy(input, this.context);
+  }
+
+  async approveInflight(
+    input: RemoteControlInvocationInput,
+  ): Promise<RemoteControlInvocationResult> {
+    return approveInflight(input, this.context);
+  }
+}
+
+export function createRealRemoteControlAdapter(
+  input: RealRemoteControlAdapterInput,
+): RealRemoteControlAdapter {
+  return new RealRemoteControlAdapter(input);
+}
+
+// ---------------------------------------------------------------------------
+// Manifest-entrypoint wiring
+// ---------------------------------------------------------------------------
+//
+// Each exported `*Tool` below matches the kernel's InProcessToolFn
+// signature `(input, ctx) => Promise<ToolOutput>`. The `ctx` carries
+// the run identifiers and allowed_scopes; we derive the storage root
+// from the runtime's allowlist `.agent-runtime/**` path — or the
+// module-scoped override when the host wires one directly (test
+// harness + conductor runtime).
+
+let moduleEventSink: AgentRuntimeEventSink | undefined;
+let moduleStore: RemoteControlStateStore | undefined;
+let moduleNow: (() => string) | undefined;
+
+/**
+ * Test/host-wiring hooks so the manifest-entrypoint tool functions
+ * reuse a single adapter across invocations. Production wiring rebinds
+ * these during pack activation (capability factory registers the
+ * adapter once); tests clear them in beforeEach.
+ */
+export function setRealRemoteControlEventSink(sink: AgentRuntimeEventSink | undefined): void {
+  moduleEventSink = sink;
+}
+
+export function setRealRemoteControlStateStore(store: RemoteControlStateStore | undefined): void {
+  moduleStore = store;
+}
+
+export function setRealRemoteControlNow(now: (() => string) | undefined): void {
+  moduleNow = now;
+}
+
+/** Resets all module-scoped wiring. Intended for unit-test teardown. */
+export function resetRealRemoteControlModuleWiring(): void {
+  moduleEventSink = undefined;
+  moduleStore = undefined;
+  moduleNow = undefined;
+}
+
+function resolveStore(ctx: ExecutionContext): RemoteControlStateStore {
+  if (moduleStore) {
+    return moduleStore;
+  }
+  const workspaceRoot = resolveWorkspaceRoot(ctx);
+  return createRemoteControlStateStore({ workspaceRoot });
+}
+
+/**
+ * Pull the workspace root from the kernel ExecutionContext. Falls back
+ * to the process cwd when no explicit workspace_root metadata is
+ * present — matching how the rest of the agent-runtime pack resolves
+ * storage roots (keeps us on the kernel-provided path when available
+ * without hard-failing when a test harness omits it).
+ */
+function resolveWorkspaceRoot(ctx: ExecutionContext): string {
+  const metadata = (ctx as unknown as { metadata?: Record<string, unknown> }).metadata;
+  const fromMetadata = metadata?.workspace_root;
+  if (typeof fromMetadata === 'string' && fromMetadata.length > 0) {
+    return fromMetadata;
+  }
+  const fromCtx = (ctx as unknown as { workspace_root?: unknown }).workspace_root;
+  if (typeof fromCtx === 'string' && fromCtx.length > 0) {
+    return fromCtx;
+  }
+  return process.cwd();
+}
+
+function buildToolOutput(data: AnyRemoteControlInvocationResult): ToolOutput {
+  return {
+    success: true,
+    data,
+    metadata: {
+      real: true,
+      source: 'WU-2733',
+    },
+  };
+}
+
+function parseInput(input: unknown): AbortTurnInvocationInput {
+  if (input === null || input === undefined) {
+    return {};
+  }
+  if (typeof input !== 'object') {
+    return {};
+  }
+  const record = input as Record<string, unknown>;
+  const result: AbortTurnInvocationInput = {};
+  if (typeof record.session_id === 'string') {
+    result.session_id = record.session_id;
+  }
+  if (typeof record.reason === 'string') {
+    result.reason = record.reason;
+  }
+  return result;
+}
+
+async function invoke(
+  toolName: AgentRuntimeRemoteControlToolName,
+  input: unknown,
+  ctx: ExecutionContext,
+): Promise<ToolOutput> {
+  const store = resolveStore(ctx);
+  const adapter = new RealRemoteControlAdapter({
+    store,
+    eventSink: moduleEventSink,
+    now: moduleNow,
+  });
+  const parsed = parseInput(input);
+
+  switch (toolName) {
+    case AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.RESUME_WORKFLOW:
+      return buildToolOutput(await adapter.resumeWorkflow(parsed));
+    case AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.PAUSE_TURN:
+      return buildToolOutput(await adapter.pauseTurn(parsed));
+    case AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN:
+      return buildToolOutput(await adapter.abortTurn(parsed));
+    case AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ELEVATE_AUTONOMY:
+      return buildToolOutput(await adapter.elevateAutonomy(parsed));
+    case AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.LOWER_AUTONOMY:
+      return buildToolOutput(await adapter.lowerAutonomy(parsed));
+    case AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.APPROVE_INFLIGHT:
+      return buildToolOutput(await adapter.approveInflight(parsed));
+    default:
+      return exhaustive(toolName);
+  }
+}
+
+function exhaustive(value: never): never {
+  throw new Error(`Unhandled remote-control tool: ${String(value)}`);
+}
+
+export async function resumeWorkflowTool(
+  input: unknown,
+  ctx: ExecutionContext,
+): Promise<ToolOutput> {
+  return invoke(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.RESUME_WORKFLOW, input, ctx);
+}
+
+export async function pauseTurnTool(input: unknown, ctx: ExecutionContext): Promise<ToolOutput> {
+  return invoke(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.PAUSE_TURN, input, ctx);
+}
+
+export async function abortTurnTool(input: unknown, ctx: ExecutionContext): Promise<ToolOutput> {
+  return invoke(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN, input, ctx);
+}
+
+export async function elevateAutonomyTool(
+  input: unknown,
+  ctx: ExecutionContext,
+): Promise<ToolOutput> {
+  return invoke(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ELEVATE_AUTONOMY, input, ctx);
+}
+
+export async function lowerAutonomyTool(
+  input: unknown,
+  ctx: ExecutionContext,
+): Promise<ToolOutput> {
+  return invoke(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.LOWER_AUTONOMY, input, ctx);
+}
+
+export async function approveInflightTool(
+  input: unknown,
+  ctx: ExecutionContext,
+): Promise<ToolOutput> {
+  return invoke(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.APPROVE_INFLIGHT, input, ctx);
+}

package/packs/agent-runtime/tsconfig.json

@@ -15,6 +15,6 @@
     "checkJs": false,
     "noEmitOnError": true
   },
-  "include": ["*.ts", "tools/**/*.ts", "tool-impl/**/*.ts"],
+  "include": ["*.ts", "*.d.ts", "tools/**/*.ts", "tool-impl/**/*.ts"],
   "exclude": ["node_modules", "dist", "__tests__"]
 }