@lumenflow/cli 5.0.3 → 5.2.0

package/packs/agent-runtime/turn-lifecycle-events.ts

@@ -69,6 +69,62 @@ export interface AgentRuntimeTurnCostBreakdown {
 
 export type AgentRuntimeCleanupStatus = 'clean' | 'partial' | 'needs_recovery';
 
+/**
+ * WU-2829 (INIT-062 WU-C): narrowed TurnCompletedEvent.status so cloud
+ * can resolve the turn discriminant without runtime string checks. The
+ * four values describe the lifecycle outcome of a turn; the internal
+ * per-turn semantic status (`reply | tool_request | complete | escalate`)
+ * remains on AgentRuntimeExecuteTurnOutput — it is NOT the same concept.
+ */
+export const AGENT_RUNTIME_TURN_COMPLETED_STATUSES = {
+  SUCCESS: 'success',
+  ERROR: 'error',
+  ABORTED: 'aborted',
+  PAUSED: 'paused',
+} as const;
+
+export const AGENT_RUNTIME_TURN_COMPLETED_STATUS_VALUES = [
+  AGENT_RUNTIME_TURN_COMPLETED_STATUSES.SUCCESS,
+  AGENT_RUNTIME_TURN_COMPLETED_STATUSES.ERROR,
+  AGENT_RUNTIME_TURN_COMPLETED_STATUSES.ABORTED,
+  AGENT_RUNTIME_TURN_COMPLETED_STATUSES.PAUSED,
+] as const;
+
+export type AgentRuntimeTurnCompletedStatus =
+  (typeof AGENT_RUNTIME_TURN_COMPLETED_STATUS_VALUES)[number];
+
+/**
+ * WU-2829 (INIT-062 WU-C): budget threshold enrichment. Cloud previously
+ * had to reconstruct `level` from `threshold`/`observed_value`; we now
+ * supply the discriminant directly alongside `remaining_usd`, `scope`,
+ * and `scope_id` so dashboards render without post-hoc inference.
+ */
+export const AGENT_RUNTIME_BUDGET_LEVELS = {
+  WARNING: 'warning',
+  EXCEEDED: 'exceeded',
+} as const;
+
+export const AGENT_RUNTIME_BUDGET_LEVEL_VALUES = [
+  AGENT_RUNTIME_BUDGET_LEVELS.WARNING,
+  AGENT_RUNTIME_BUDGET_LEVELS.EXCEEDED,
+] as const;
+
+export type AgentRuntimeBudgetLevel = (typeof AGENT_RUNTIME_BUDGET_LEVEL_VALUES)[number];
+
+export const AGENT_RUNTIME_BUDGET_SCOPES = {
+  SESSION: 'session',
+  WORKSPACE: 'workspace',
+  ORG: 'org',
+} as const;
+
+export const AGENT_RUNTIME_BUDGET_SCOPE_VALUES = [
+  AGENT_RUNTIME_BUDGET_SCOPES.SESSION,
+  AGENT_RUNTIME_BUDGET_SCOPES.WORKSPACE,
+  AGENT_RUNTIME_BUDGET_SCOPES.ORG,
+] as const;
+
+export type AgentRuntimeBudgetScope = (typeof AGENT_RUNTIME_BUDGET_SCOPE_VALUES)[number];
+
 export interface TurnStartedEvent extends AgentRuntimeEventEnvelope {
   kind: typeof AGENT_RUNTIME_EVENT_KINDS.TURN_STARTED;
   session_id: string;
@@ -80,7 +136,9 @@ export interface TurnCompletedEvent extends AgentRuntimeEventEnvelope {
   kind: typeof AGENT_RUNTIME_EVENT_KINDS.TURN_COMPLETED;
   session_id: string;
   turn_index: number;
-  status: string;
+  // WU-2829: narrowed from `string` to the four lifecycle outcomes so
+  // cloud gets TS exhaustiveness on the discriminated union.
+  status: AgentRuntimeTurnCompletedStatus;
   cost_breakdown: AgentRuntimeTurnCostBreakdown;
 }
 
@@ -99,6 +157,15 @@ export interface ToolCalledEvent extends AgentRuntimeEventEnvelope {
   turn_index: number;
   tool_name: string;
   tool_call_id: string;
+  /**
+   * WU-2829 (INIT-062 WU-C): approval discriminant so cloud no longer
+   * has to cross-reference APPROVAL_REQUIRED events to tell which tool
+   * calls were gated. `true` = call proceeded (either no approval
+   * required, or approval was satisfied); `false` = call blocked
+   * pending an approval (paired with a subsequent APPROVAL_REQUIRED
+   * event carrying the request_id).
+   */
+  approved: boolean;
 }
 
 export interface ApprovalRequiredEvent extends AgentRuntimeEventEnvelope {
@@ -149,6 +216,28 @@ export interface BudgetThresholdEvent extends AgentRuntimeEventEnvelope {
   budget_name: string;
   threshold: number;
   observed_value: number;
+  /**
+   * WU-2829 (INIT-062 WU-C): discriminant for cloud dashboards so the
+   * level is no longer inferred from threshold/observed_value.
+   */
+  level: AgentRuntimeBudgetLevel;
+  /**
+   * WU-2829 (INIT-062 WU-C): remaining USD headroom for the budget at
+   * emission time. Negative values are permitted when the budget is
+   * already exceeded.
+   */
+  remaining_usd: number;
+  /**
+   * WU-2829 (INIT-062 WU-C): budget scope so cloud can route the signal
+   * to the correct dashboard (session / workspace / org).
+   */
+  scope: AgentRuntimeBudgetScope;
+  /**
+   * WU-2829 (INIT-062 WU-C): identifier of the scope object (session id,
+   * workspace id, or org id) — paired with `scope` to pin the emission
+   * to a specific subject.
+   */
+  scope_id: string;
 }
 
 export interface AgentSessionEnrolledEvent extends AgentRuntimeEventEnvelope {

package/packs/sidekick/manifest.yaml

@@ -678,6 +678,9 @@ emitted_event_kinds:
   - sidekick:routine_executed
   - sidekick:routine_step_failed
   - sidekick:state_rehydrated
+  - sidekick:state_rehydration_started
+  - sidekick:state_rehydration_chunk
+  - sidekick:state_rehydration_completed
 backpressure_policy:
   sidekick:task_created: queue-with-replay
   sidekick:task_completed: queue-with-replay
@@ -695,6 +698,9 @@ backpressure_policy:
   sidekick:routine_executed: queue-with-replay
   sidekick:routine_step_failed: queue-with-replay
   sidekick:state_rehydrated: queue-with-replay
+  sidekick:state_rehydration_started: queue-with-replay
+  sidekick:state_rehydration_chunk: queue-with-replay
+  sidekick:state_rehydration_completed: queue-with-replay
 state_aliases: {}
 lane_templates: []
 # WU-2735 (INIT-060 WU-7a, ADR-013 §ChannelBridge): the sidekick pack requires

package/packs/sidekick/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-sidekick",
-  "version": "5.0.3",
+  "version": "5.2.0",
   "description": "Sidekick personal assistant pack for LumenFlow — 16 tools for task management, typed memory, channels, routines, and audit",
   "keywords": [
     "lumenflow",
@@ -53,6 +53,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@lumenflow/conductor-sdk": "workspace:^",
     "@lumenflow/kernel": "workspace:^"
   },
   "devDependencies": {

package/packs/sidekick/sidekick-events.ts

@@ -12,6 +12,7 @@ import {
   type MemoryRecord,
   type RoutineRecord,
   type SidekickStores,
+  type StoreName,
   type TaskRecord,
 } from './tool-impl/storage.js';
 
@@ -45,7 +46,17 @@ export const SIDEKICK_EVENT_KINDS = {
   ROUTINE_COMMITTED: 'sidekick:routine_committed',
   ROUTINE_EXECUTED: 'sidekick:routine_executed',
   ROUTINE_STEP_FAILED: 'sidekick:routine_step_failed',
+  /**
+   * @deprecated WU-2830 (INIT-062 WU-D): `sidekick:state_rehydrated` is
+   * unbounded and cannot stream. New emitters MUST use the chunked trio
+   * (`STATE_REHYDRATION_STARTED`, `STATE_REHYDRATION_CHUNK`,
+   * `STATE_REHYDRATION_COMPLETED`). The constant and type are retained for
+   * backwards compatibility only.
+   */
   STATE_REHYDRATED: 'sidekick:state_rehydrated',
+  STATE_REHYDRATION_STARTED: 'sidekick:state_rehydration_started',
+  STATE_REHYDRATION_CHUNK: 'sidekick:state_rehydration_chunk',
+  STATE_REHYDRATION_COMPLETED: 'sidekick:state_rehydration_completed',
 } as const;
 
 export const SIDEKICK_EVENT_KIND_VALUES = [
@@ -65,6 +76,9 @@ export const SIDEKICK_EVENT_KIND_VALUES = [
   SIDEKICK_EVENT_KINDS.ROUTINE_EXECUTED,
   SIDEKICK_EVENT_KINDS.ROUTINE_STEP_FAILED,
   SIDEKICK_EVENT_KINDS.STATE_REHYDRATED,
+  SIDEKICK_EVENT_KINDS.STATE_REHYDRATION_STARTED,
+  SIDEKICK_EVENT_KINDS.STATE_REHYDRATION_CHUNK,
+  SIDEKICK_EVENT_KINDS.STATE_REHYDRATION_COMPLETED,
 ] as const;
 
 export type SidekickEventKind = (typeof SIDEKICK_EVENT_KIND_VALUES)[number];
@@ -93,6 +107,9 @@ export const SIDEKICK_EVENT_BACKPRESSURE_POLICY: Record<
   [SIDEKICK_EVENT_KINDS.ROUTINE_EXECUTED]: QUEUE_WITH_REPLAY,
   [SIDEKICK_EVENT_KINDS.ROUTINE_STEP_FAILED]: QUEUE_WITH_REPLAY,
   [SIDEKICK_EVENT_KINDS.STATE_REHYDRATED]: QUEUE_WITH_REPLAY,
+  [SIDEKICK_EVENT_KINDS.STATE_REHYDRATION_STARTED]: QUEUE_WITH_REPLAY,
+  [SIDEKICK_EVENT_KINDS.STATE_REHYDRATION_CHUNK]: QUEUE_WITH_REPLAY,
+  [SIDEKICK_EVENT_KINDS.STATE_REHYDRATION_COMPLETED]: QUEUE_WITH_REPLAY,
 };
 
 interface SidekickEventEnvelope {
@@ -144,13 +161,23 @@ export interface MemoryForgottenEvent extends SidekickEventEnvelope {
 
 export interface ChannelMessageSentEvent extends SidekickEventEnvelope {
   kind: typeof SIDEKICK_EVENT_KINDS.CHANNEL_MESSAGE_SENT;
-  message: Record<string, unknown>;
+  /**
+   * WU-2830 (INIT-062 WU-D): typed as {@link ChannelMessageRecord} for
+   * symmetry with {@link ChannelMessageReceivedEvent.messages} and to enable
+   * static analysis cloud-side.
+   */
+  message: ChannelMessageRecord;
 }
 
 export interface ChannelMessageReceivedEvent extends SidekickEventEnvelope {
   kind: typeof SIDEKICK_EVENT_KINDS.CHANNEL_MESSAGE_RECEIVED;
   channel: string;
-  count: number;
+  /**
+   * WU-2830 (INIT-062 WU-D): full {@link ChannelMessageRecord} payloads
+   * replace the previous bare `count` field. Subscribers count via
+   * `messages.length`; symmetric with {@link ChannelMessageSentEvent.message}.
+   */
+  messages: ChannelMessageRecord[];
   provider?: string;
 }
 
@@ -199,11 +226,50 @@ export interface RoutineStepFailedEvent extends SidekickEventEnvelope {
   routine_name?: string;
 }
 
+/**
+ * @deprecated WU-2830 (INIT-062 WU-D): unbounded snapshots cannot stream.
+ * Emit {@link StateRehydrationStartedEvent} +
+ * {@link StateRehydrationChunkEvent} (one per store) +
+ * {@link StateRehydrationCompletedEvent} instead. Retained for parity with
+ * existing consumers and the compile-time parity tests.
+ */
 export interface StateRehydratedEvent extends SidekickEventEnvelope {
   kind: typeof SIDEKICK_EVENT_KINDS.STATE_REHYDRATED;
   snapshot: SidekickStores;
 }
 
+export interface StateRehydrationStartedEvent extends SidekickEventEnvelope {
+  kind: typeof SIDEKICK_EVENT_KINDS.STATE_REHYDRATION_STARTED;
+  /** Correlation id shared by the started/chunk/completed trio. */
+  rehydration_id: string;
+  /** Total chunks the receiver should expect. */
+  total_chunks: number;
+}
+
+export interface StateRehydrationChunkEvent extends SidekickEventEnvelope {
+  kind: typeof SIDEKICK_EVENT_KINDS.STATE_REHYDRATION_CHUNK;
+  /** Correlation id matching the {@link StateRehydrationStartedEvent}. */
+  rehydration_id: string;
+  /**
+   * Monotonic zero-based index identifying this chunk's position within the
+   * stream. Receivers reassemble ordered by `cursor`.
+   */
+  cursor: number;
+  /** True for the final chunk in the stream (cursor === total_chunks - 1). */
+  last_chunk: boolean;
+  /**
+   * Subset of {@link SidekickStores} keys carried by this chunk. Receivers
+   * merge `stores` into the accumulating snapshot keyed on store name.
+   */
+  stores: Partial<SidekickStores>;
+}
+
+export interface StateRehydrationCompletedEvent extends SidekickEventEnvelope {
+  kind: typeof SIDEKICK_EVENT_KINDS.STATE_REHYDRATION_COMPLETED;
+  rehydration_id: string;
+  chunk_count: number;
+}
+
 export type SidekickEvent =
   | TaskCreatedEvent
   | TaskCompletedEvent
@@ -220,7 +286,10 @@ export type SidekickEvent =
   | RoutineCommittedEvent
   | RoutineExecutedEvent
   | RoutineStepFailedEvent
-  | StateRehydratedEvent;
+  | StateRehydratedEvent
+  | StateRehydrationStartedEvent
+  | StateRehydrationChunkEvent
+  | StateRehydrationCompletedEvent;
 
 const channelSeqCounters = new Map<string, number>();
 
@@ -406,7 +475,7 @@ export function buildMemoryForgottenEvent(memory_id: string): MemoryForgottenEve
 }
 
 export function buildChannelMessageSentEvent(
-  message: Record<string, unknown>,
+  message: ChannelMessageRecord,
 ): ChannelMessageSentEvent {
   return stampSidekickEvent<ChannelMessageSentEvent>({
     kind: SIDEKICK_EVENT_KINDS.CHANNEL_MESSAGE_SENT,
@@ -416,13 +485,13 @@ export function buildChannelMessageSentEvent(
 
 export function buildChannelMessageReceivedEvent(input: {
   channel: string;
-  count: number;
+  messages: ChannelMessageRecord[];
   provider?: string;
 }): ChannelMessageReceivedEvent {
   return stampSidekickEvent<ChannelMessageReceivedEvent>({
     kind: SIDEKICK_EVENT_KINDS.CHANNEL_MESSAGE_RECEIVED,
     channel: input.channel,
-    count: input.count,
+    messages: input.messages,
     ...(input.provider ? { provider: input.provider } : {}),
   });
 }
@@ -495,6 +564,11 @@ export function buildRoutineStepFailedEvent(input: {
   });
 }
 
+/**
+ * @deprecated WU-2830 (INIT-062 WU-D): prefer
+ * {@link buildStateRehydrationChunkEvents} which emits the bounded
+ * started/chunk/completed trio. Retained for backwards compatibility.
+ */
 export function buildStateRehydratedEvent(snapshot: SidekickStores): StateRehydratedEvent {
   return stampSidekickEvent<StateRehydratedEvent>({
     kind: SIDEKICK_EVENT_KINDS.STATE_REHYDRATED,
@@ -502,16 +576,119 @@ export function buildStateRehydratedEvent(snapshot: SidekickStores): StateRehydr
   });
 }
 
-export function serializeLocalChannelMessage(
-  message: ChannelMessageRecord,
-  channelName?: string,
-): Record<string, unknown> {
-  return {
-    id: message.id,
-    channel_id: message.channel_id,
-    ...(channelName ? { channel: channelName } : {}),
-    sender: message.sender,
-    content: message.content,
-    created_at: message.created_at,
-  };
+export function buildStateRehydrationStartedEvent(input: {
+  rehydration_id: string;
+  total_chunks: number;
+}): StateRehydrationStartedEvent {
+  return stampSidekickEvent<StateRehydrationStartedEvent>({
+    kind: SIDEKICK_EVENT_KINDS.STATE_REHYDRATION_STARTED,
+    rehydration_id: input.rehydration_id,
+    total_chunks: input.total_chunks,
+  });
+}
+
+export function buildStateRehydrationChunkEvent(input: {
+  rehydration_id: string;
+  cursor: number;
+  last_chunk: boolean;
+  stores: Partial<SidekickStores>;
+}): StateRehydrationChunkEvent {
+  return stampSidekickEvent<StateRehydrationChunkEvent>({
+    kind: SIDEKICK_EVENT_KINDS.STATE_REHYDRATION_CHUNK,
+    rehydration_id: input.rehydration_id,
+    cursor: input.cursor,
+    last_chunk: input.last_chunk,
+    stores: input.stores,
+  });
+}
+
+export function buildStateRehydrationCompletedEvent(input: {
+  rehydration_id: string;
+  chunk_count: number;
+}): StateRehydrationCompletedEvent {
+  return stampSidekickEvent<StateRehydrationCompletedEvent>({
+    kind: SIDEKICK_EVENT_KINDS.STATE_REHYDRATION_COMPLETED,
+    rehydration_id: input.rehydration_id,
+    chunk_count: input.chunk_count,
+  });
+}
+
+/**
+ * WU-2830 (INIT-062 WU-D): the store order used by the chunked rehydration
+ * emitter. Exposed so receivers that care about deterministic reassembly
+ * can cross-check cursor semantics.
+ */
+export const SIDEKICK_REHYDRATION_STORE_ORDER = [
+  'tasks',
+  'memories',
+  'channels',
+  'messages',
+  'routines',
+] as const satisfies readonly StoreName[];
+
+export type SidekickRehydrationStore = (typeof SIDEKICK_REHYDRATION_STORE_ORDER)[number];
+
+/**
+ * WU-2830 (INIT-062 WU-D): emit the chunked rehydration stream.
+ *
+ * Emission order: `state_rehydration_started` → one
+ * `state_rehydration_chunk` per store in
+ * {@link SIDEKICK_REHYDRATION_STORE_ORDER} → `state_rehydration_completed`.
+ * `cursor` is a zero-based monotonic index; `last_chunk` is true on the final
+ * chunk so streaming receivers can close the reassembly window without
+ * waiting for the completion event.
+ */
+export async function emitSidekickStateRehydration(snapshot: SidekickStores): Promise<{
+  rehydration_id: string;
+  chunk_count: number;
+}> {
+  const rehydration_id = randomUUID();
+  const stores = SIDEKICK_REHYDRATION_STORE_ORDER;
+  const total_chunks = stores.length;
+
+  await emitSidekickEvent(buildStateRehydrationStartedEvent({ rehydration_id, total_chunks }));
+
+  for (let cursor = 0; cursor < stores.length; cursor++) {
+    const store = stores[cursor];
+    if (store === undefined) {
+      continue;
+    }
+    const last_chunk = cursor === stores.length - 1;
+    const chunkStores: Partial<SidekickStores> = {};
+    // Narrow the union so TS keeps the store-value type aligned with the key.
+    switch (store) {
+      case 'tasks':
+        chunkStores.tasks = snapshot.tasks;
+        break;
+      case 'memories':
+        chunkStores.memories = snapshot.memories;
+        break;
+      case 'channels':
+        chunkStores.channels = snapshot.channels;
+        break;
+      case 'messages':
+        chunkStores.messages = snapshot.messages;
+        break;
+      case 'routines':
+        chunkStores.routines = snapshot.routines;
+        break;
+    }
+    await emitSidekickEvent(
+      buildStateRehydrationChunkEvent({
+        rehydration_id,
+        cursor,
+        last_chunk,
+        stores: chunkStores,
+      }),
+    );
+  }
+
+  await emitSidekickEvent(
+    buildStateRehydrationCompletedEvent({
+      rehydration_id,
+      chunk_count: total_chunks,
+    }),
+  );
+
+  return { rehydration_id, chunk_count: total_chunks };
 }

package/packs/sidekick/src/adapters/control-plane-bridge.adapter.ts

@@ -294,18 +294,26 @@ export function createControlPlaneChannelBridge(
   // Port methods
   // -------------------------------------------------------------------------
 
+  async function registerInternal(bridgeConfig: BridgeConfig): Promise<ChannelId> {
+    const key = `${bridgeConfig.provider}::${bridgeConfig.name}::${hashOptions(
+      bridgeConfig.options as Record<string, unknown> | undefined,
+    )}`;
+    const existing = registry.get(key);
+    if (existing) {
+      return existing;
+    }
+    const id = mintChannelId(bridgeConfig);
+    registry.set(key, id);
+    return id;
+  }
+
   return {
+    async connect(bridgeConfig: BridgeConfig): Promise<ChannelId> {
+      return registerInternal(bridgeConfig);
+    },
+
     async register(bridgeConfig: BridgeConfig): Promise<ChannelId> {
-      const key = `${bridgeConfig.provider}::${bridgeConfig.name}::${hashOptions(
-        bridgeConfig.options as Record<string, unknown> | undefined,
-      )}`;
-      const existing = registry.get(key);
-      if (existing) {
-        return existing;
-      }
-      const id = mintChannelId(bridgeConfig);
-      registry.set(key, id);
-      return id;
+      return registerInternal(bridgeConfig);
     },
 
     async send(channelId: ChannelId, envelope: ChannelEnvelope): Promise<SendResult> {

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

@@ -180,6 +180,10 @@ export function createFilesystemChannelBridge(
   }
 
   return {
+    async connect(bridgeConfig: BridgeConfig): Promise<ChannelId> {
+      return ensureRegistered(bridgeConfig);
+    },
+
     async register(bridgeConfig: BridgeConfig): Promise<ChannelId> {
       return ensureRegistered(bridgeConfig);
     },

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

@@ -2,23 +2,37 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 
 /**
- * WU-2735 (INIT-060 WU-7a, ADR-013 §ChannelBridge):
- * Pure domain types for the ChannelBridge port.
+ * WU-2735 (INIT-060 WU-7a) + WU-2831 (INIT-062 WU-E):
+ * Domain types for the sidekick ChannelBridge adapters.
  *
- * These types are pure domain: they MUST NOT reference Node `fs`, network
- * sockets, cloud endpoints, or any adapter-specific concept. Both the
- * filesystem adapter (this WU) and the control-plane adapter (WU-2737) shape
- * themselves around these definitions.
+ * As of WU-2831 the port-level identity, config, and send-result shapes are
+ * canonical in @lumenflow/conductor-sdk (Apache-2.0). 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.
  */
 
-/**
- * Branded channel identifier. The bridge mints these during `register`; the
- * brand prevents callers from forging ids from raw strings.
- */
-export type ChannelId = string & { readonly __brand: 'sidekick.ChannelId' };
+// Re-export canonical port types from the Apache-2.0 conductor SDK.
+export type {
+  BackpressurePolicy,
+  BridgeConfig,
+  ChannelId,
+  ChannelIdentity,
+  DeliveryGuarantee,
+  IdentityResolver,
+  SendResult,
+} from '@lumenflow/conductor-sdk';
 
 /**
- * Envelope dispatch classification per ADR-013 §4 backpressure split.
+ * 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.
@@ -26,14 +40,18 @@ export type ChannelId = string & { readonly __brand: 'sidekick.ChannelId' };
 export type EnvelopeKind = 'ephemeral' | 'queue';
 
 /**
- * A channel envelope. Kept transport-agnostic: `body` is an opaque
- * JSON-serialisable payload, `content_type` labels it so receivers can dispatch
- * without snooping the body.
+ * 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;
-  /** §4 backpressure policy — drives send path (fail-silent vs queued replay). */
+  /** Pack-internal backpressure classification. */
   kind: EnvelopeKind;
   /** MIME-like content descriptor, e.g. `application/json`, `text/plain`. */
   content_type: string;
@@ -44,41 +62,3 @@ export interface ChannelEnvelope {
   /** Optional emitter-supplied metadata (trace ids, correlation keys). */
   metadata?: Readonly<Record<string, unknown>>;
 }
-
-/**
- * Bridge registration config — identity under which a channel is opened.
- *
- * The (`provider`, `name`) pair is the canonical identity: re-registering the
- * same pair returns the same `ChannelId` (ADR-013 §ChannelBridge contract
- * rule #3 — idempotent register).
- *
- * `options` is provider-specific bag. The port does NOT inspect it; adapters
- * interpret.
- */
-export interface BridgeConfig {
-  /** Provider slug — e.g. `filesystem`, `control-plane`. */
-  provider: string;
-  /** Human-readable channel name scoped within the provider. */
-  name: string;
-  /** Provider-specific options (paths, tokens, etc.). Opaque to the port. */
-  options?: Readonly<Record<string, unknown>>;
-}
-
-/**
- * Result of a `send` attempt. `accepted` reflects the port contract: for
- * ephemeral envelopes with an unreachable transport, adapters may return
- * `{ accepted: false, reason: '...' }` rather than throwing (§4 fail-silent).
- */
-export interface SendResult {
-  accepted: boolean;
-  /** Transport-assigned id when the sink confirms receipt (optional). */
-  delivery_id?: string;
-  /** Reason when `accepted === false` (not meant for programmatic handling). */
-  reason?: string;
-  /**
-   * `true` when the sink recognised `envelope.id` on a registered channel as
-   * an at-least-once replay (WU-2737 §Idempotency; cloud contract surface).
-   * Adapters that cannot observe dedup SHOULD omit this field.
-   */
-  deduped?: boolean;
-}