@lumenflow/cli 5.4.0 → 5.7.12

package/packs/sidekick/src/adapters/filesystem-bridge.adapter.ts

@@ -1,228 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-/**
- * WU-2735 (INIT-060 WU-7a, ADR-013 §ChannelBridge):
- * Filesystem implementation of the ChannelBridge port.
- *
- * Backing layout:
- *
- *   <rootDir>/channels/<channel-id>/envelopes.jsonl
- *   <rootDir>/channels/<channel-id>/config.json
- *   <rootDir>/registry.json       (BridgeConfig identity → ChannelId)
- *
- * Writes are atomic: a new envelope is written to a per-pid tmp file and
- * `rename(2)`'d on top of a sibling, then append to the JSONL via
- * `appendFile` with `O_APPEND` semantics (Node delegates to the kernel, which
- * guarantees single-write atomicity for writes below PIPE_BUF; our JSON lines
- * sit well below that for realistic envelopes and we additionally bound the
- * write under a per-channel in-process mutex).
- *
- * The adapter is deliberately minimal: the sidekick pack's transport registry
- * (`channel-transports.ts`) remains the runtime dispatch path for the existing
- * `channel:send` tool; WU-2735 lands the port/adapter skeleton only.
- */
-
-import { createHash } from 'node:crypto';
-import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-
-import type {
-  BridgeConfig,
-  ChannelEnvelope,
-  ChannelId,
-  SendResult,
-} from '../domain/channel.types.js';
-import type { ChannelBridge } from '../ports/channel-bridge.port.js';
-
-// ---------------------------------------------------------------------------
-// Configuration surface
-// ---------------------------------------------------------------------------
-
-export interface FilesystemChannelBridgeOptions {
-  /**
-   * Directory under which the bridge materialises channel state. Tests set
-   * this to a tmpdir; in production the caller passes
-   * `.lumenflow/state/packs/sidekick/` (or equivalent per ADR-013).
-   */
-  rootDir: string;
-}
-
-interface RegistryEntry {
-  id: ChannelId;
-  provider: string;
-  name: string;
-  options_hash: string;
-}
-
-interface Registry {
-  entries: RegistryEntry[];
-}
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-const REGISTRY_FILENAME = 'registry.json';
-const CHANNELS_SUBDIR = 'channels';
-const ENVELOPES_FILENAME = 'envelopes.jsonl';
-const CONFIG_FILENAME = 'config.json';
-
-function hashOptions(options: Record<string, unknown> | undefined): string {
-  const payload = JSON.stringify(options ?? {}, Object.keys(options ?? {}).sort());
-  return createHash('sha256').update(payload).digest('hex').slice(0, 16);
-}
-
-function mintChannelId(config: BridgeConfig): ChannelId {
-  // Deterministic id per (provider, name, options) — stable across bridge
-  // instances backed by the same rootDir so `register` is idempotent even on
-  // cold start without reading the registry.
-  const payload = `${config.provider}::${config.name}::${hashOptions(config.options as Record<string, unknown> | undefined)}`;
-  const digest = createHash('sha256').update(payload).digest('hex').slice(0, 24);
-  return `chan-${digest}` as ChannelId;
-}
-
-async function readRegistry(registryPath: string): Promise<Registry> {
-  try {
-    const raw = await readFile(registryPath, 'utf8');
-    return JSON.parse(raw) as Registry;
-  } catch (error) {
-    const err = error as NodeJS.ErrnoException;
-    if (err.code === 'ENOENT') {
-      return { entries: [] };
-    }
-    throw error;
-  }
-}
-
-async function writeRegistryAtomic(registryPath: string, registry: Registry): Promise<void> {
-  await mkdir(path.dirname(registryPath), { recursive: true });
-  const tmpPath = `${registryPath}.tmp-${process.pid}-${Date.now()}`;
-  await writeFile(tmpPath, JSON.stringify(registry, null, 2), 'utf8');
-  const { rename } = await import('node:fs/promises');
-  await rename(tmpPath, registryPath);
-}
-
-// Per-bridge-instance lock map so concurrent send() calls on a single channel
-// serialise their appends. Filesystem atomicity still holds under crash, but
-// the mutex ensures emit order is preserved (ADR-013 §3).
-function createLockGate(): {
-  withLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
-} {
-  const chains = new Map<string, Promise<unknown>>();
-  return {
-    async withLock<T>(key: string, fn: () => Promise<T>): Promise<T> {
-      const previous = chains.get(key) ?? Promise.resolve();
-      const next = previous.then(fn, fn);
-      chains.set(
-        key,
-        next.then(
-          () => undefined,
-          () => undefined,
-        ),
-      );
-      return next as Promise<T>;
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Adapter factory
-// ---------------------------------------------------------------------------
-
-export function createFilesystemChannelBridge(
-  options: FilesystemChannelBridgeOptions,
-): ChannelBridge {
-  const rootDir = path.resolve(options.rootDir);
-  const registryPath = path.join(rootDir, REGISTRY_FILENAME);
-  const lockGate = createLockGate();
-  const disconnected = new Set<ChannelId>();
-
-  function channelDir(id: ChannelId): string {
-    return path.join(rootDir, CHANNELS_SUBDIR, id);
-  }
-
-  async function ensureRegistered(config: BridgeConfig): Promise<ChannelId> {
-    const registry = await readRegistry(registryPath);
-    const id = mintChannelId(config);
-    const optionsHash = hashOptions(config.options as Record<string, unknown> | undefined);
-    const existing = registry.entries.find((entry) => entry.id === id);
-    if (existing) {
-      return existing.id;
-    }
-
-    registry.entries.push({
-      id,
-      provider: config.provider,
-      name: config.name,
-      options_hash: optionsHash,
-    });
-    await writeRegistryAtomic(registryPath, registry);
-
-    const dir = channelDir(id);
-    await mkdir(dir, { recursive: true });
-    await writeFile(
-      path.join(dir, CONFIG_FILENAME),
-      JSON.stringify({ provider: config.provider, name: config.name }, null, 2),
-      'utf8',
-    );
-    return id;
-  }
-
-  async function assertActive(channelId: ChannelId): Promise<void> {
-    if (disconnected.has(channelId)) {
-      throw new Error(`ChannelBridge: channel ${channelId} is disconnected; send rejected.`);
-    }
-    const registry = await readRegistry(registryPath);
-    if (!registry.entries.some((entry) => entry.id === channelId)) {
-      throw new Error(`ChannelBridge: channel ${channelId} is not registered.`);
-    }
-  }
-
-  return {
-    async connect(bridgeConfig: BridgeConfig): Promise<ChannelId> {
-      return ensureRegistered(bridgeConfig);
-    },
-
-    async register(bridgeConfig: BridgeConfig): Promise<ChannelId> {
-      return ensureRegistered(bridgeConfig);
-    },
-
-    async send(channelId: ChannelId, envelope: ChannelEnvelope): Promise<SendResult> {
-      await assertActive(channelId);
-      const envelopesPath = path.join(channelDir(channelId), ENVELOPES_FILENAME);
-      await lockGate.withLock(channelId, async () => {
-        await mkdir(path.dirname(envelopesPath), { recursive: true });
-        await appendFile(envelopesPath, `${JSON.stringify(envelope)}\n`, 'utf8');
-      });
-      return { accepted: true, delivery_id: envelope.id };
-    },
-
-    async *receive(channelId: ChannelId): AsyncIterable<ChannelEnvelope> {
-      if (disconnected.has(channelId)) {
-        return;
-      }
-      const envelopesPath = path.join(channelDir(channelId), ENVELOPES_FILENAME);
-      let raw: string;
-      try {
-        raw = await readFile(envelopesPath, 'utf8');
-      } catch (error) {
-        const err = error as NodeJS.ErrnoException;
-        if (err.code === 'ENOENT') {
-          return;
-        }
-        throw error;
-      }
-      for (const line of raw.split('\n')) {
-        if (line.length === 0) {
-          continue;
-        }
-        yield JSON.parse(line) as ChannelEnvelope;
-      }
-    },
-
-    async disconnect(channelId: ChannelId): Promise<void> {
-      disconnected.add(channelId);
-    },
-  };
-}

package/packs/sidekick/src/domain/channel.types.ts

@@ -1,64 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-/**
- * WU-2735 (INIT-060 WU-7a) + WU-2831 (INIT-062 WU-E):
- * Domain types for the sidekick ChannelBridge adapters.
- *
- * As of WU-2831 the port-level identity, config, and send-result shapes are
- * canonical in @lumenflow/conductor-sdk (LumenFlow Proprietary). This file re-exports
- * those types so sidekick adapters implement the neutral port without
- * parallel contract drift.
- *
- * The internal `EnvelopeKind` + `ChannelEnvelope` shape below remains the
- * sidekick-pack wire format: it predates the canonical port and is retained
- * for on-disk/control-plane compatibility of existing adapters. New
- * implementers (e.g. the cloud phone bridge) SHOULD consume
- * `@lumenflow/conductor-sdk`'s `ChannelEnvelope` instead.
- */
-
-// Re-export canonical port types from the LumenFlow Proprietary conductor SDK.
-export type {
-  BackpressurePolicy,
-  BridgeConfig,
-  ChannelId,
-  ChannelIdentity,
-  DeliveryGuarantee,
-  IdentityResolver,
-  SendResult,
-} from '@lumenflow/conductor-sdk';
-
-/**
- * Envelope dispatch classification — sidekick-internal wire format.
- *
- * Predates the canonical `BackpressurePolicy` enum in conductor-sdk.
- * Maps: `ephemeral` ↔ `ephemeral`, `queue` ↔ `buffered` (conductor-sdk).
- *
- * - `ephemeral` — observational; may fail-silent when transport is down.
- * - `queue` — commands / approvals; must be queued and replayed on reconnect.
- */
-export type EnvelopeKind = 'ephemeral' | 'queue';
-
-/**
- * A channel envelope (sidekick-internal wire format).
- * Transport-agnostic: `body` is an opaque JSON-serialisable payload,
- * `content_type` labels it so receivers can dispatch without snooping the body.
- *
- * Note: the canonical port-level envelope is
- * `@lumenflow/conductor-sdk`'s `ChannelEnvelope` (uses `policy` field).
- * Adapters translate between the two when bridging across the Apache boundary.
- */
-export interface ChannelEnvelope {
-  /** Unique id per envelope (content-hash or uuid — chosen by the emitter). */
-  id: string;
-  /** Pack-internal backpressure classification. */
-  kind: EnvelopeKind;
-  /** MIME-like content descriptor, e.g. `application/json`, `text/plain`. */
-  content_type: string;
-  /** Payload. JSON-serialisable; no host-specific handles. */
-  body: unknown;
-  /** ISO-8601 UTC timestamp of emit; per-channel ordering key (ADR-013 §3). */
-  emitted_at: string;
-  /** Optional emitter-supplied metadata (trace ids, correlation keys). */
-  metadata?: Readonly<Record<string, unknown>>;
-}

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

@@ -1,92 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-/**
- * WU-2735 (INIT-060 WU-7a, ADR-013 §ChannelBridge) + WU-2831 (INIT-062 WU-E):
- *
- * Sidekick-pack ChannelBridge port.
- *
- * As of WU-2831 the canonical neutral port lives in `@lumenflow/conductor-sdk`
- * under LumenFlow Proprietary — consumers that need an Proprietary-free surface (e.g. the
- * cloud phone bridge) MUST import from there. The sidekick port below reuses
- * the conductor-sdk identity / config / result types (no parallel drift) but
- * keeps the pack-internal wire-format envelope (`ChannelEnvelope` with
- * `kind: 'ephemeral' | 'queue'`) for on-disk and control-plane compatibility
- * of existing adapters.
- *
- * 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.
- * - `connect` (alias: `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.
- */
-
-import type {
-  BridgeConfig,
-  ChannelEnvelope,
-  ChannelId,
-  SendResult,
-} from '../domain/channel.types.js';
-
-export interface ChannelBridge {
-  /**
-   * Open (or reuse) a channel. Idempotent on `(provider, name)`.
-   *
-   * Canonical method name per the neutral conductor-sdk port (WU-2831).
-   */
-  connect(bridgeConfig: BridgeConfig): Promise<ChannelId>;
-
-  /**
-   * Legacy alias for `connect`. Retained for pack-internal call sites that
-   * predate WU-2831.
-   *
-   * @deprecated Use `connect` instead (WU-2831 port-contract alignment).
-   */
-  register(bridgeConfig: BridgeConfig): Promise<ChannelId>;
-
-  /**
-   * 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>;
-
-  /**
-   * 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

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