@lumenflow/cli 4.23.0 → 5.0.0

package/packs/sidekick/src/ports/channel-bridge.port.ts

@@ -0,0 +1,75 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * WU-2735 (INIT-060 WU-7a, ADR-013 §ChannelBridge):
+ * ChannelBridge port.
+ *
+ * Port contract — load-bearing across adapters (ADR-013 §ChannelBridge):
+ *
+ * - `send` is at-least-once for `queue` envelopes, fail-silent for
+ *   `ephemeral` envelopes (ADR-013 §4 backpressure split).
+ * - `receive` yields envelopes in emit order on a single channel (§3). No
+ *   cross-channel ordering guarantee.
+ * - `register` is idempotent on `BridgeConfig` identity — same
+ *   `(provider, name)` returns the same `ChannelId`.
+ * - `disconnect` flushes queued envelopes before closing; in-flight ephemerals
+ *   may drop.
+ *
+ * The port MUST NOT leak filesystem- or network-specific types. Both the
+ * filesystem adapter (this WU) and the cloud adapter (WU-2737) implement this
+ * interface unmodified.
+ */
+
+import type {
+  BridgeConfig,
+  ChannelEnvelope,
+  ChannelId,
+  SendResult,
+} from '../domain/channel.types.js';
+
+export interface ChannelBridge {
+  /**
+   * Send an envelope on a registered channel.
+   *
+   * @throws if `channelId` is not registered, or has been disconnected.
+   */
+  send(channelId: ChannelId, envelope: ChannelEnvelope): Promise<SendResult>;
+
+  /**
+   * Stream envelopes on the given channel in emit order. The iterator
+   * terminates after `disconnect(channelId)`; otherwise it is long-lived.
+   */
+  receive(channelId: ChannelId): AsyncIterable<ChannelEnvelope>;
+
+  /**
+   * Register a channel and return its id. Idempotent on `(provider, name)`.
+   */
+  register(bridgeConfig: BridgeConfig): Promise<ChannelId>;
+
+  /**
+   * Close the channel. Queued envelopes flush before this resolves; ephemerals
+   * in flight may be dropped.
+   */
+  disconnect(channelId: ChannelId): Promise<void>;
+}
+
+/**
+ * Structural type guard. Useful for adapter tests and runtime payload
+ * validation at the port boundary.
+ */
+export function isChannelEnvelope(value: unknown): value is ChannelEnvelope {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.id === 'string' &&
+    (v.kind === 'ephemeral' || v.kind === 'queue') &&
+    typeof v.content_type === 'string' &&
+    'body' in v &&
+    typeof v.emitted_at === 'string'
+  );
+}
+
+export type { BridgeConfig, ChannelEnvelope, ChannelId, SendResult };

package/packs/sidekick/src/routines/commit.ts

@@ -0,0 +1,74 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * WU-2738 (INIT-060, ADR-013 §6 governance): plan-to-commit envelope +
+ * content-hash helpers for the governed sidekick:routine:commit_plan
+ * tool. The commit envelope is what an agent attestation carries; the
+ * content-hash is what lands on the audit trail so cloud can correlate
+ * a `sidekick:routine_committed` event with the originating envelope
+ * without the PII-bearing body ever leaving the local workspace.
+ */
+
+import { createHash } from 'node:crypto';
+import type { RoutineRecord } from '../../tool-impl/storage.js';
+
+const CONTENT_HASH_ALGORITHM = 'sha256';
+const CONTENT_HASH_ENCODING = 'hex';
+
+export interface RoutineCommitAttestation {
+  actor: string;
+  reason: string;
+  // Intentionally untyped extension slot: attestation may carry arbitrary
+  // operator-supplied metadata which can contain PII. The envelope hash
+  // covers the entire attestation; the body never appears on the audit
+  // event surface.
+  [key: string]: unknown;
+}
+
+export interface RoutineCommitEnvelope {
+  plan_id: string;
+  routine_name: string;
+  step_count: number;
+  committed_at: string;
+  attestation: RoutineCommitAttestation;
+}
+
+export interface BuildRoutineCommitEnvelopeInput {
+  routine: RoutineRecord;
+  attestation: RoutineCommitAttestation;
+  committedAt: string;
+}
+
+export function buildRoutineCommitEnvelope(
+  input: BuildRoutineCommitEnvelopeInput,
+): RoutineCommitEnvelope {
+  return {
+    plan_id: input.routine.id,
+    routine_name: input.routine.name,
+    step_count: input.routine.steps.length,
+    committed_at: input.committedAt,
+    attestation: { ...input.attestation },
+  };
+}
+
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((entry) => canonicalize(entry));
+  }
+  if (value && typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    const sortedKeys = Object.keys(record).sort();
+    const result: Record<string, unknown> = {};
+    for (const key of sortedKeys) {
+      result[key] = canonicalize(record[key]);
+    }
+    return result;
+  }
+  return value;
+}
+
+export function hashRoutineCommitEnvelope(envelope: RoutineCommitEnvelope): string {
+  const canonical = JSON.stringify(canonicalize(envelope));
+  return createHash(CONTENT_HASH_ALGORITHM).update(canonical).digest(CONTENT_HASH_ENCODING);
+}

package/packs/sidekick/tool-impl/channel-tools.ts

@@ -16,6 +16,14 @@ import {
   type ToolContextLike,
   type ToolOutput,
 } from './shared.js';
+import {
+  buildChannelBridgeConnectedEvent,
+  buildChannelBridgeDisconnectedEvent,
+  buildChannelMessageReceivedEvent,
+  buildChannelMessageSentEvent,
+  emitSidekickEvent,
+  serializeLocalChannelMessage,
+} from '../sidekick-events.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -115,6 +123,8 @@ async function channelConfigureTool(
     }
   });
 
+  await emitSidekickEvent(buildChannelBridgeConnectedEvent(resolvedChannel));
+
   return success({ channel: resolvedChannel as unknown as Record<string, unknown> });
 }
 
@@ -205,6 +215,13 @@ async function channelDeleteTool(input: unknown, context?: ToolContextLike): Pro
     );
   });
 
+  await emitSidekickEvent(
+    buildChannelBridgeDisconnectedEvent({
+      bridge_id: id,
+      deleted_message_count: deletedMessages.length,
+    }),
+  );
+
   return success({
     deleted_id: id,
     deleted_message_count: deletedMessages.length,
@@ -283,6 +300,17 @@ async function channelSendViaTransport(
     };
   }
 
+  await emitSidekickEvent(
+    buildChannelMessageSentEvent({
+      provider,
+      channel,
+      content,
+      ...(transportResult.externalMessageId !== undefined
+        ? { external_message_id: transportResult.externalMessageId }
+        : {}),
+    }),
+  );
+
   return success(outputData);
 }
 
@@ -361,6 +389,10 @@ async function channelSendTool(input: unknown, context?: ToolContextLike): Promi
     );
   });
 
+  await emitSidekickEvent(
+    buildChannelMessageSentEvent(serializeLocalChannelMessage(resolvedMessage, channelName)),
+  );
+
   return success({ message: resolvedMessage as unknown as Record<string, unknown> });
 }
 
@@ -430,6 +462,14 @@ async function channelReceiveViaTransport(
     };
   }
 
+  await emitSidekickEvent(
+    buildChannelMessageReceivedEvent({
+      provider,
+      channel,
+      count: transportResult.records?.length ?? 0,
+    }),
+  );
+
   return success(outputData);
 }
 
@@ -468,6 +508,13 @@ async function channelReceiveTool(input: unknown, _context?: ToolContextLike): P
 
   const items = limit && limit > 0 ? sorted.slice(-limit) : sorted;
 
+  await emitSidekickEvent(
+    buildChannelMessageReceivedEvent({
+      channel: channelName ?? DEFAULT_CHANNEL_NAME,
+      count: items.length,
+    }),
+  );
+
   return success({
     items: items as unknown as Record<string, unknown>,
     count: items.length,

package/packs/sidekick/tool-impl/memory-tools.ts

@@ -18,6 +18,12 @@ import {
   type ToolContextLike,
   type ToolOutput,
 } from './shared.js';
+import {
+  buildMemoryForgottenEvent,
+  buildMemoryRecalledEvent,
+  buildMemoryStoredEvent,
+  emitSidekickEvent,
+} from '../sidekick-events.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -87,6 +93,8 @@ async function memoryStoreTool(input: unknown, context?: ToolContextLike): Promi
     );
   });
 
+  await emitSidekickEvent(buildMemoryStoredEvent(memory));
+
   return success({ memory: memory as unknown as Record<string, unknown> });
 }
 
@@ -121,6 +129,13 @@ async function memoryRecallTool(input: unknown, _context?: ToolContextLike): Pro
 
   const items = limit && limit > 0 ? sorted.slice(0, limit) : sorted;
 
+  await emitSidekickEvent(
+    buildMemoryRecalledEvent({
+      query,
+      memories: items,
+    }),
+  );
+
   return success({
     items: items as unknown as Record<string, unknown>,
     count: items.length,
@@ -247,6 +262,8 @@ async function memoryForgetTool(input: unknown, context?: ToolContextLike): Prom
     );
   });
 
+  await emitSidekickEvent(buildMemoryForgottenEvent(id));
+
   return success({ deleted_id: id });
 }
 

package/packs/sidekick/tool-impl/routine-commit.ts

@@ -0,0 +1,102 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * WU-2738 (INIT-060, ADR-013 §6 governance): `sidekick:routine:commit_plan`
+ * is the only path from a planned routine to a committed one. It is
+ * registered as a runtime-callable tool (not a top-level surface) so the
+ * kernel's governed dispatch emits `agent-runtime:tool_called` inside a
+ * turn, and the commit itself emits `sidekick:routine_committed` carrying
+ * a content-hash of the commit envelope. No fast-path bypasses this tool.
+ */
+
+import {
+  buildRoutineCommitEnvelope,
+  hashRoutineCommitEnvelope,
+  type RoutineCommitAttestation,
+} from '../src/routines/commit.js';
+import { buildRoutineCommittedEvent, emitSidekickEvent } from '../sidekick-events.js';
+import { getStoragePort } from './storage.js';
+import {
+  asNonEmptyString,
+  buildAuditEvent,
+  failure,
+  nowIso,
+  success,
+  toRecord,
+  type ToolContextLike,
+  type ToolOutput,
+} from './shared.js';
+
+const ROUTINE_COMMIT_PLAN_TOOL_NAME = 'sidekick:routine:commit_plan';
+
+function readAttestation(value: unknown): RoutineCommitAttestation | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return null;
+  }
+  const record = value as Record<string, unknown>;
+  const actor = asNonEmptyString(record.actor);
+  const reason = asNonEmptyString(record.reason);
+  if (!actor || !reason) {
+    return null;
+  }
+  return {
+    ...record,
+    actor,
+    reason,
+  };
+}
+
+export default async function routineCommitPlanTool(
+  input: unknown,
+  context?: ToolContextLike,
+): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const planId = asNonEmptyString(parsed.plan_id);
+  const attestation = readAttestation(parsed.attestation);
+
+  if (!planId) {
+    return failure('INVALID_INPUT', 'plan_id is required.');
+  }
+  if (!attestation) {
+    return failure(
+      'INVALID_INPUT',
+      'attestation must be an object with non-empty actor and reason fields.',
+    );
+  }
+
+  const storage = getStoragePort();
+  const routines = await storage.readStore('routines');
+  const routine = routines.find((entry) => entry.id === planId);
+  if (!routine) {
+    return failure('NOT_FOUND', `routine ${planId} was not found.`);
+  }
+
+  const committedAt = nowIso();
+  const envelope = buildRoutineCommitEnvelope({ routine, attestation, committedAt });
+  const envelopeContentHash = hashRoutineCommitEnvelope(envelope);
+
+  await storage.appendAudit(
+    buildAuditEvent({
+      tool: ROUTINE_COMMIT_PLAN_TOOL_NAME,
+      op: 'execute',
+      context,
+      ids: [routine.id],
+      details: {
+        plan_id: routine.id,
+        envelope_content_hash: envelopeContentHash,
+      },
+    }),
+  );
+
+  await emitSidekickEvent(
+    buildRoutineCommittedEvent(routine, { envelope_content_hash: envelopeContentHash }),
+  );
+
+  return success({
+    plan_id: routine.id,
+    routine_id: routine.id,
+    envelope_content_hash: envelopeContentHash,
+    committed_at: committedAt,
+  });
+}

package/packs/sidekick/tool-impl/routine-tools.ts

@@ -15,6 +15,13 @@ import {
   type ToolContextLike,
   type ToolOutput,
 } from './shared.js';
+import {
+  buildRoutineCommittedEvent,
+  buildRoutineExecutedEvent,
+  buildRoutinePlannedEvent,
+  buildRoutineStepFailedEvent,
+  emitSidekickEvent,
+} from '../sidekick-events.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -36,15 +43,17 @@ const ROUTINE_ID_REQUIRED_MESSAGE = 'id is required.';
 interface NormalizeStepsResult {
   steps: RoutineStepRecord[];
   warnings: string[];
+  failed_steps: Array<{ step_index: number; reason: string }>;
 }
 
 function normalizeSteps(value: unknown): NormalizeStepsResult {
   if (!Array.isArray(value)) {
-    return { steps: [], warnings: [] };
+    return { steps: [], warnings: [], failed_steps: [] };
   }
 
   const steps: RoutineStepRecord[] = [];
   const warnings: string[] = [];
+  const failedSteps: Array<{ step_index: number; reason: string }> = [];
 
   for (let i = 0; i < value.length; i++) {
     const candidate = value[i];
@@ -55,20 +64,26 @@ function normalizeSteps(value: unknown): NormalizeStepsResult {
       if (tool) {
         steps.push({ tool, input: {} });
       } else {
-        warnings.push(`steps[${i}] invalid: expected non-empty string or object with "tool".`);
+        const reason = `steps[${i}] invalid: expected non-empty string or object with "tool".`;
+        warnings.push(reason);
+        failedSteps.push({ step_index: i, reason });
       }
       continue;
     }
 
     if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
-      warnings.push(`steps[${i}] invalid: expected object with "tool" or a tool name string.`);
+      const reason = `steps[${i}] invalid: expected object with "tool" or a tool name string.`;
+      warnings.push(reason);
+      failedSteps.push({ step_index: i, reason });
       continue;
     }
 
     const record = candidate as Record<string, unknown>;
     const tool = asNonEmptyString(record.tool);
     if (!tool) {
-      warnings.push(`steps[${i}] invalid: missing or empty "tool" property.`);
+      const reason = `steps[${i}] invalid: missing or empty "tool" property.`;
+      warnings.push(reason);
+      failedSteps.push({ step_index: i, reason });
       continue;
     }
 
@@ -80,7 +95,7 @@ function normalizeSteps(value: unknown): NormalizeStepsResult {
     steps.push({ tool, input });
   }
 
-  return { steps, warnings };
+  return { steps, warnings, failed_steps: failedSteps };
 }
 
 function asOptionalBoolean(value: unknown): boolean | null {
@@ -90,6 +105,22 @@ function asOptionalBoolean(value: unknown): boolean | null {
   return null;
 }
 
+async function emitRoutineStepFailures(
+  failedSteps: Array<{ step_index: number; reason: string }>,
+  metadata: { routine_id?: string; routine_name?: string },
+): Promise<void> {
+  for (const failedStep of failedSteps) {
+    await emitSidekickEvent(
+      buildRoutineStepFailedEvent({
+        step_index: failedStep.step_index,
+        reason: failedStep.reason,
+        ...(metadata.routine_id ? { routine_id: metadata.routine_id } : {}),
+        ...(metadata.routine_name ? { routine_name: metadata.routine_name } : {}),
+      }),
+    );
+  }
+}
+
 // ---------------------------------------------------------------------------
 // routine:create
 // ---------------------------------------------------------------------------
@@ -97,12 +128,15 @@ function asOptionalBoolean(value: unknown): boolean | null {
 async function routineCreateTool(input: unknown, context?: ToolContextLike): Promise<ToolOutput> {
   const parsed = toRecord(input);
   const name = asNonEmptyString(parsed.name);
-  const { steps, warnings } = normalizeSteps(parsed.steps);
+  const { steps, warnings, failed_steps } = normalizeSteps(parsed.steps);
 
   if (!name) {
     return failure('INVALID_INPUT', 'name is required.');
   }
   if (steps.length === 0) {
+    if (!isDryRun(parsed)) {
+      await emitRoutineStepFailures(failed_steps, { routine_name: name ?? undefined });
+    }
     const detail =
       warnings.length > 0
         ? `steps must include at least one tool step. Issues: ${warnings.join('; ')}`
@@ -144,6 +178,12 @@ async function routineCreateTool(input: unknown, context?: ToolContextLike): Pro
     );
   });
 
+  await emitRoutineStepFailures(failed_steps, {
+    routine_id: routine.id,
+    routine_name: routine.name,
+  });
+  await emitSidekickEvent(buildRoutinePlannedEvent(routine));
+
   return success({
     routine: routine as unknown as Record<string, unknown>,
     ...(warnings.length > 0 ? { warnings } : {}),
@@ -180,6 +220,7 @@ async function routineListTool(input: unknown, _context?: ToolContextLike): Prom
 async function routineUpdateTool(input: unknown, context?: ToolContextLike): Promise<ToolOutput> {
   const parsed = toRecord(input);
   const id = asNonEmptyString(parsed.id);
+  let patchFailedSteps: Array<{ step_index: number; reason: string }> = [];
 
   if (!id) {
     return failure('INVALID_INPUT', ROUTINE_ID_REQUIRED_MESSAGE);
@@ -201,8 +242,12 @@ async function routineUpdateTool(input: unknown, context?: ToolContextLike): Pro
     patch.enabled = enabled;
   }
   if (parsed.steps !== undefined) {
-    const { steps, warnings } = normalizeSteps(parsed.steps);
+    const { steps, warnings, failed_steps } = normalizeSteps(parsed.steps);
+    patchFailedSteps = failed_steps;
     if (steps.length === 0) {
+      if (!isDryRun(parsed)) {
+        await emitRoutineStepFailures(failed_steps, { routine_id: id });
+      }
       const detail =
         warnings.length > 0
           ? `steps must include at least one tool step. Issues: ${warnings.join('; ')}`
@@ -260,6 +305,13 @@ async function routineUpdateTool(input: unknown, context?: ToolContextLike): Pro
 
   const updated = await storage.readStore('routines');
   const updatedRoutine = updated.find((entry) => entry.id === id);
+  await emitRoutineStepFailures(patchFailedSteps, {
+    routine_id: id,
+    routine_name: updatedRoutine?.name,
+  });
+  if (updatedRoutine) {
+    await emitSidekickEvent(buildRoutineCommittedEvent(updatedRoutine));
+  }
   return success({ routine: updatedRoutine as unknown as Record<string, unknown> });
 }
 
@@ -339,6 +391,14 @@ async function routineRunTool(input: unknown, context?: ToolContextLike): Promis
     }),
   );
 
+  await emitSidekickEvent(
+    buildRoutineExecutedEvent({
+      routine_id: routine.id,
+      name: routine.name,
+      step_count: routine.steps.length,
+    }),
+  );
+
   return success({
     routine_id: routine.id,
     name: routine.name,

package/packs/sidekick/tool-impl/runtime-context.ts

@@ -4,10 +4,14 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import type { ChannelTransport } from './channel-transports.js';
 import type { StoragePort } from './storage.js';
+import type { SidekickEvent } from '../sidekick-events.js';
 
 export interface SidekickRuntimeContext {
   storagePort: StoragePort;
   channelTransports: Map<string, ChannelTransport>;
+  workspaceRoot?: string;
+  workspaceConfig?: unknown;
+  eventSink?: (event: SidekickEvent) => void | Promise<void>;
 }
 
 const runtimeContext = new AsyncLocalStorage<SidekickRuntimeContext>();

package/packs/sidekick/tool-impl/storage.ts

@@ -316,6 +316,9 @@ export async function runWithStoragePort<T>(port: StoragePort, fn: () => Promise
     {
       storagePort: port,
       channelTransports: existingContext?.channelTransports ?? new Map(),
+      workspaceRoot: existingContext?.workspaceRoot,
+      workspaceConfig: existingContext?.workspaceConfig,
+      eventSink: existingContext?.eventSink,
     },
     fn,
   );

package/packs/sidekick/tool-impl/system-tools.ts

@@ -12,6 +12,11 @@ import {
   type ToolContextLike,
   type ToolOutput,
 } from './shared.js';
+import {
+  buildStateRehydratedEvent,
+  emitSidekickEvent,
+  snapshotSidekickState,
+} from '../sidekick-events.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -46,6 +51,8 @@ async function initTool(context?: ToolContextLike): Promise<ToolOutput> {
     }),
   );
 
+  await emitSidekickEvent(buildStateRehydratedEvent(await snapshotSidekickState()));
+
   return success({
     initialized: true,
     root_dir: storage.getRootDir(),