@lumenflow/packs-sidekick 4.24.0 → 5.0.0

package/dist/src/domain/channel.types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * WU-2735 (INIT-060 WU-7a, ADR-013 §ChannelBridge):
+ * Pure domain types for the ChannelBridge port.
+ *
+ * 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.
+ */
+/**
+ * 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';
+};
+/**
+ * Envelope dispatch classification per ADR-013 §4 backpressure split.
+ *
+ * - `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. Kept transport-agnostic: `body` is an opaque
+ * JSON-serialisable payload, `content_type` labels it so receivers can dispatch
+ * without snooping the body.
+ */
+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). */
+    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>>;
+}
+/**
+ * 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;
+}
+//# sourceMappingURL=channel.types.d.ts.map

package/dist/src/domain/channel.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.types.d.ts","sourceRoot":"","sources":["../../../src/domain/channel.types.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,OAAO,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,EAAE,EAAE,MAAM,CAAC;IACX,gFAAgF;IAChF,IAAI,EAAE,YAAY,CAAC;IACnB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,IAAI,EAAE,OAAO,CAAC;IACd,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC9C;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC7C;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB"}

package/dist/src/domain/channel.types.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};
+//# sourceMappingURL=channel.types.js.map

package/dist/src/domain/channel.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.types.js","sourceRoot":"","sources":["../../../src/domain/channel.types.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC"}

package/dist/src/ports/channel-bridge.port.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 declare function isChannelEnvelope(value: unknown): value is ChannelEnvelope;
+export type { BridgeConfig, ChannelEnvelope, ChannelId, SendResult };
+//# sourceMappingURL=channel-bridge.port.d.ts.map

package/dist/src/ports/channel-bridge.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-bridge.port.d.ts","sourceRoot":"","sources":["../../../src/ports/channel-bridge.port.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,eAAe,EACf,SAAS,EACT,UAAU,EACX,MAAM,4BAA4B,CAAC;AAEpC,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAE3E;;;OAGG;IACH,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,aAAa,CAAC,eAAe,CAAC,CAAC;IAE9D;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAEzD;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAY1E;AAED,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC"}

package/dist/src/ports/channel-bridge.port.js

@@ -0,0 +1,18 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Structural type guard. Useful for adapter tests and runtime payload
+ * validation at the port boundary.
+ */
+export function isChannelEnvelope(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const v = value;
+    return (typeof v.id === 'string' &&
+        (v.kind === 'ephemeral' || v.kind === 'queue') &&
+        typeof v.content_type === 'string' &&
+        'body' in v &&
+        typeof v.emitted_at === 'string');
+}
+//# sourceMappingURL=channel-bridge.port.js.map

package/dist/src/ports/channel-bridge.port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-bridge.port.js","sourceRoot":"","sources":["../../../src/ports/channel-bridge.port.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAuDzC;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,CACL,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ;QACxB,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC;QAC9C,OAAO,CAAC,CAAC,YAAY,KAAK,QAAQ;QAClC,MAAM,IAAI,CAAC;QACX,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,CACjC,CAAC;AACJ,CAAC"}

package/dist/src/routines/commit.d.ts

@@ -0,0 +1,21 @@
+import type { RoutineRecord } from '../../tool-impl/storage.js';
+export interface RoutineCommitAttestation {
+    actor: string;
+    reason: string;
+    [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 declare function buildRoutineCommitEnvelope(input: BuildRoutineCommitEnvelopeInput): RoutineCommitEnvelope;
+export declare function hashRoutineCommitEnvelope(envelope: RoutineCommitEnvelope): string;
+//# sourceMappingURL=commit.d.ts.map

package/dist/src/routines/commit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit.d.ts","sourceRoot":"","sources":["../../../src/routines/commit.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAKhE,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IAKf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,wBAAwB,CAAC;CACvC;AAED,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,aAAa,CAAC;IACvB,WAAW,EAAE,wBAAwB,CAAC;IACtC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,+BAA+B,GACrC,qBAAqB,CAQvB;AAkBD,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CAGjF"}

package/dist/src/routines/commit.js

@@ -0,0 +1,42 @@
+// 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';
+const CONTENT_HASH_ALGORITHM = 'sha256';
+const CONTENT_HASH_ENCODING = 'hex';
+export function buildRoutineCommitEnvelope(input) {
+    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) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => canonicalize(entry));
+    }
+    if (value && typeof value === 'object') {
+        const record = value;
+        const sortedKeys = Object.keys(record).sort();
+        const result = {};
+        for (const key of sortedKeys) {
+            result[key] = canonicalize(record[key]);
+        }
+        return result;
+    }
+    return value;
+}
+export function hashRoutineCommitEnvelope(envelope) {
+    const canonical = JSON.stringify(canonicalize(envelope));
+    return createHash(CONTENT_HASH_ALGORITHM).update(canonical).digest(CONTENT_HASH_ENCODING);
+}
+//# sourceMappingURL=commit.js.map

package/dist/src/routines/commit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit.js","sourceRoot":"","sources":["../../../src/routines/commit.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,MAAM,sBAAsB,GAAG,QAAQ,CAAC;AACxC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AA0BpC,MAAM,UAAU,0BAA0B,CACxC,KAAsC;IAEtC,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE;QACzB,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI;QAChC,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM;QACtC,YAAY,EAAE,KAAK,CAAC,WAAW;QAC/B,WAAW,EAAE,EAAE,GAAG,KAAK,CAAC,WAAW,EAAE;KACtC,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,MAAM,GAAG,KAAgC,CAAC;QAChD,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QAC9C,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,MAAM,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1C,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,QAA+B;IACvE,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC;IACzD,OAAO,UAAU,CAAC,sBAAsB,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC;AAC5F,CAAC"}

package/dist/src/sidekick-events.d.ts

@@ -0,0 +1,166 @@
+import { type ChannelMessageRecord, type ChannelRecord, type MemoryRecord, type RoutineRecord, type SidekickStores, type TaskRecord } from '../tool-impl/storage.js';
+declare const SCHEMA_VERSION_V2: 2;
+export declare const SIDEKICK_CHANNEL_ID: "sidekick";
+export declare const SIDEKICK_EVENT_KINDS: {
+    readonly TASK_CREATED: "sidekick:task_created";
+    readonly TASK_COMPLETED: "sidekick:task_completed";
+    readonly TASK_SCHEDULED: "sidekick:task_scheduled";
+    readonly TASK_SNOOZED: "sidekick:task_snoozed";
+    readonly MEMORY_STORED: "sidekick:memory_stored";
+    readonly MEMORY_RECALLED: "sidekick:memory_recalled";
+    readonly MEMORY_FORGOTTEN: "sidekick:memory_forgotten";
+    readonly CHANNEL_MESSAGE_SENT: "sidekick:channel_message_sent";
+    readonly CHANNEL_MESSAGE_RECEIVED: "sidekick:channel_message_received";
+    readonly CHANNEL_BRIDGE_CONNECTED: "sidekick:channel_bridge_connected";
+    readonly CHANNEL_BRIDGE_DISCONNECTED: "sidekick:channel_bridge_disconnected";
+    readonly ROUTINE_PLANNED: "sidekick:routine_planned";
+    readonly ROUTINE_COMMITTED: "sidekick:routine_committed";
+    readonly ROUTINE_EXECUTED: "sidekick:routine_executed";
+    readonly ROUTINE_STEP_FAILED: "sidekick:routine_step_failed";
+    readonly STATE_REHYDRATED: "sidekick:state_rehydrated";
+};
+export declare const SIDEKICK_EVENT_KIND_VALUES: readonly ["sidekick:task_created", "sidekick:task_completed", "sidekick:task_scheduled", "sidekick:task_snoozed", "sidekick:memory_stored", "sidekick:memory_recalled", "sidekick:memory_forgotten", "sidekick:channel_message_sent", "sidekick:channel_message_received", "sidekick:channel_bridge_connected", "sidekick:channel_bridge_disconnected", "sidekick:routine_planned", "sidekick:routine_committed", "sidekick:routine_executed", "sidekick:routine_step_failed", "sidekick:state_rehydrated"];
+export type SidekickEventKind = (typeof SIDEKICK_EVENT_KIND_VALUES)[number];
+export type SidekickBackpressurePolicy = 'queue-with-replay' | 'ephemeral';
+export declare const SIDEKICK_EVENT_BACKPRESSURE_POLICY: Record<SidekickEventKind, SidekickBackpressurePolicy>;
+interface SidekickEventEnvelope {
+    schema_version: typeof SCHEMA_VERSION_V2;
+    timestamp: string;
+    event_id: string;
+    channel_id: typeof SIDEKICK_CHANNEL_ID;
+    seq: number;
+}
+export interface TaskCreatedEvent extends SidekickEventEnvelope {
+    kind: typeof SIDEKICK_EVENT_KINDS.TASK_CREATED;
+    task: TaskRecord;
+}
+export interface TaskCompletedEvent extends SidekickEventEnvelope {
+    kind: typeof SIDEKICK_EVENT_KINDS.TASK_COMPLETED;
+    task: TaskRecord;
+}
+export interface TaskScheduledEvent extends SidekickEventEnvelope {
+    kind: typeof SIDEKICK_EVENT_KINDS.TASK_SCHEDULED;
+    task: TaskRecord;
+}
+export interface TaskSnoozedEvent extends SidekickEventEnvelope {
+    kind: typeof SIDEKICK_EVENT_KINDS.TASK_SNOOZED;
+    task_id: string;
+    previous_due_at: string | null;
+    due_at: string;
+}
+export interface MemoryStoredEvent extends SidekickEventEnvelope {
+    kind: typeof SIDEKICK_EVENT_KINDS.MEMORY_STORED;
+    memory: MemoryRecord;
+}
+export interface MemoryRecalledEvent extends SidekickEventEnvelope {
+    kind: typeof SIDEKICK_EVENT_KINDS.MEMORY_RECALLED;
+    query: string | null;
+    count: number;
+    memory_ids: string[];
+}
+export interface MemoryForgottenEvent extends SidekickEventEnvelope {
+    kind: typeof SIDEKICK_EVENT_KINDS.MEMORY_FORGOTTEN;
+    memory_id: string;
+}
+export interface ChannelMessageSentEvent extends SidekickEventEnvelope {
+    kind: typeof SIDEKICK_EVENT_KINDS.CHANNEL_MESSAGE_SENT;
+    message: Record<string, unknown>;
+}
+export interface ChannelMessageReceivedEvent extends SidekickEventEnvelope {
+    kind: typeof SIDEKICK_EVENT_KINDS.CHANNEL_MESSAGE_RECEIVED;
+    channel: string;
+    count: number;
+    provider?: string;
+}
+export interface ChannelBridgeConnectedEvent extends SidekickEventEnvelope {
+    kind: typeof SIDEKICK_EVENT_KINDS.CHANNEL_BRIDGE_CONNECTED;
+    channel: ChannelRecord;
+}
+export interface ChannelBridgeDisconnectedEvent extends SidekickEventEnvelope {
+    kind: typeof SIDEKICK_EVENT_KINDS.CHANNEL_BRIDGE_DISCONNECTED;
+    bridge_id: string;
+    deleted_message_count: number;
+}
+export interface RoutinePlannedEvent extends SidekickEventEnvelope {
+    kind: typeof SIDEKICK_EVENT_KINDS.ROUTINE_PLANNED;
+    routine: RoutineRecord;
+}
+export interface RoutineCommittedEvent extends SidekickEventEnvelope {
+    kind: typeof SIDEKICK_EVENT_KINDS.ROUTINE_COMMITTED;
+    routine: RoutineRecord;
+    /**
+     * WU-2738 (INIT-060, ADR-013 §6 governance): content-hash of the commit
+     * envelope carried when the event is emitted by the governed
+     * `sidekick:routine:commit_plan` tool. PII stays inside the local
+     * envelope; cloud correlates on the hash. Optional so the existing
+     * update-triggered emission (routine:update) stays PII-free.
+     */
+    envelope_content_hash?: string;
+}
+export interface RoutineExecutedEvent extends SidekickEventEnvelope {
+    kind: typeof SIDEKICK_EVENT_KINDS.ROUTINE_EXECUTED;
+    routine_id: string;
+    name: string;
+    step_count: number;
+    plan_only: true;
+}
+export interface RoutineStepFailedEvent extends SidekickEventEnvelope {
+    kind: typeof SIDEKICK_EVENT_KINDS.ROUTINE_STEP_FAILED;
+    step_index: number;
+    reason: string;
+    routine_id?: string;
+    routine_name?: string;
+}
+export interface StateRehydratedEvent extends SidekickEventEnvelope {
+    kind: typeof SIDEKICK_EVENT_KINDS.STATE_REHYDRATED;
+    snapshot: SidekickStores;
+}
+export type SidekickEvent = TaskCreatedEvent | TaskCompletedEvent | TaskScheduledEvent | TaskSnoozedEvent | MemoryStoredEvent | MemoryRecalledEvent | MemoryForgottenEvent | ChannelMessageSentEvent | ChannelMessageReceivedEvent | ChannelBridgeConnectedEvent | ChannelBridgeDisconnectedEvent | RoutinePlannedEvent | RoutineCommittedEvent | RoutineExecutedEvent | RoutineStepFailedEvent | StateRehydratedEvent;
+export declare function resetSidekickSeqCounter(): void;
+export declare function readSidekickOrgId(config: unknown): string | undefined;
+export declare function emitSidekickEvent<TEvent extends SidekickEvent>(event: TEvent): Promise<TEvent>;
+export declare function snapshotSidekickState(): Promise<SidekickStores>;
+export declare function buildTaskCreatedEvent(task: TaskRecord): TaskCreatedEvent;
+export declare function buildTaskCompletedEvent(task: TaskRecord): TaskCompletedEvent;
+export declare function buildTaskScheduledEvent(task: TaskRecord): TaskScheduledEvent;
+export declare function buildTaskSnoozedEvent(input: {
+    task_id: string;
+    previous_due_at: string | null;
+    due_at: string;
+}): TaskSnoozedEvent;
+export declare function buildMemoryStoredEvent(memory: MemoryRecord): MemoryStoredEvent;
+export declare function buildMemoryRecalledEvent(input: {
+    query: string | null;
+    memories: MemoryRecord[];
+}): MemoryRecalledEvent;
+export declare function buildMemoryForgottenEvent(memory_id: string): MemoryForgottenEvent;
+export declare function buildChannelMessageSentEvent(message: Record<string, unknown>): ChannelMessageSentEvent;
+export declare function buildChannelMessageReceivedEvent(input: {
+    channel: string;
+    count: number;
+    provider?: string;
+}): ChannelMessageReceivedEvent;
+export declare function buildChannelBridgeConnectedEvent(channel: ChannelRecord): ChannelBridgeConnectedEvent;
+export declare function buildChannelBridgeDisconnectedEvent(input: {
+    bridge_id: string;
+    deleted_message_count: number;
+}): ChannelBridgeDisconnectedEvent;
+export declare function buildRoutinePlannedEvent(routine: RoutineRecord): RoutinePlannedEvent;
+export declare function buildRoutineCommittedEvent(routine: RoutineRecord, options?: {
+    envelope_content_hash?: string;
+}): RoutineCommittedEvent;
+export declare function buildRoutineExecutedEvent(input: {
+    routine_id: string;
+    name: string;
+    step_count: number;
+}): RoutineExecutedEvent;
+export declare function buildRoutineStepFailedEvent(input: {
+    step_index: number;
+    reason: string;
+    routine_id?: string;
+    routine_name?: string;
+}): RoutineStepFailedEvent;
+export declare function buildStateRehydratedEvent(snapshot: SidekickStores): StateRehydratedEvent;
+export declare function serializeLocalChannelMessage(message: ChannelMessageRecord, channelName?: string): Record<string, unknown>;
+export {};
+//# sourceMappingURL=sidekick-events.d.ts.map

package/dist/src/sidekick-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidekick-events.d.ts","sourceRoot":"","sources":["../../src/sidekick-events.ts"],"names":[],"mappings":"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"}