@sigrun/ext-gateway 0.0.0-stage → 0.1.2

package/dist/inbound/albums.js

@@ -0,0 +1,62 @@
+/**
+ * Album merging (spec §8.4 step 6): events sharing a `groupId` that
+ * arrive within 1500 ms merge into ONE submission (a platform media
+ * group delivered as several events). There is no time-based burst
+ * merging otherwise — every non-album message submits on arrival.
+ *
+ * The window runs from the FIRST event of its group: the group is
+ * closed once a later sibling arrives past `firstAt + 1500`, and a
+ * `groupId` reused later opens a NEW group. Group state is per
+ * binding key (the chat) — two chats never share an album. Attachment
+ * arrays are preserved alongside envelope texts so every sibling's
+ * media reaches the one submission.
+ */
+/** The album merge window (ms) — the plan's pinned 1.5 s. */
+export const ALBUM_WINDOW_MS = 1_500;
+/**
+ * The in-flight album collector, one instance per engine. `add` returns
+ * `undefined` while the album stays OPEN (the caller holds the event
+ * back — no submission yet) and the collected batch when the group is
+ * COMPLETE. A follow-up event with no `groupId` returns its own batch.
+ */
+export class AlbumCollector {
+    now;
+    windowMs;
+    groups = new Map();
+    constructor(now, windowMs = ALBUM_WINDOW_MS) {
+        this.now = now;
+        this.windowMs = windowMs;
+    }
+    /** Offer one event's envelope text; undefined means still collecting. */
+    add(key, event, text) {
+        if (event.groupId === undefined) {
+            return { texts: [text], attachments: event.attachments ?? [] };
+        }
+        const at = this.now();
+        const group = this.groups.get(`${key}:${event.groupId}`);
+        if (group === undefined || at - group.firstAt > this.windowMs) {
+            this.groups.set(`${key}:${event.groupId}`, {
+                texts: [text],
+                attachments: [...(event.attachments ?? [])],
+                firstAt: at,
+            });
+            return undefined;
+        }
+        group.texts.push(text);
+        group.attachments.push(...(event.attachments ?? []));
+        // Every sibling stays held until the timer or shutdown flush.
+        return undefined;
+    }
+    /** Close and remove one open group, returning its complete batch. */
+    close(key, groupId) {
+        const group = this.groups.get(`${key}:${groupId}`);
+        if (group === undefined)
+            return { texts: [], attachments: [] };
+        this.groups.delete(`${key}:${groupId}`);
+        return { texts: group.texts, attachments: group.attachments };
+    }
+    /** Is a group OPEN (collecting) for `key`/`groupId`? */
+    isOpen(key, groupId) {
+        return this.groups.has(`${key}:${groupId}`);
+    }
+}

package/dist/inbound/envelope.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The inbound envelope (spec §8.10): the text the model sees — the
+ * group `[<label>]` prefix, the reply-quote block, and the DM
+ * pass-through. The quote truncates at 500 chars (the plan's pinned
+ * value) with a single ellipsis marker; the author line renders when
+ * the platform names the replied-to author (a reply to the bot itself
+ * carries no author name — the quote block alone keeps the thread
+ * context).
+ */
+import type { InboundEvent } from "@sigrun/sigrun/extension";
+/**
+ * Build the envelope text for one inbound event. `group` selects the
+ * `[<senderLabel>]` prefix; the reply-quote block prefixes either form
+ * when the event carries a `replyTo`.
+ */
+export declare function buildEnvelope(event: InboundEvent, opts: {
+    group: boolean;
+    senderLabel: string;
+}): string;

package/dist/inbound/envelope.js

@@ -0,0 +1,39 @@
+/**
+ * The inbound envelope (spec §8.10): the text the model sees — the
+ * group `[<label>]` prefix, the reply-quote block, and the DM
+ * pass-through. The quote truncates at 500 chars (the plan's pinned
+ * value) with a single ellipsis marker; the author line renders when
+ * the platform names the replied-to author (a reply to the bot itself
+ * carries no author name — the quote block alone keeps the thread
+ * context).
+ */
+/** The reply-quote truncation cap (the plan's pinned 500 chars). */
+const QUOTE_MAX = 500;
+/**
+ * Build the envelope text for one inbound event. `group` selects the
+ * `[<senderLabel>]` prefix; the reply-quote block prefixes either form
+ * when the event carries a `replyTo`.
+ */
+export function buildEnvelope(event, opts) {
+    const body = opts.group
+        ? `[${opts.senderLabel}] ${event.text}`
+        : event.text;
+    if (event.replyTo === undefined)
+        return body;
+    const parts = [];
+    if (event.replyTo.text !== undefined) {
+        parts.push(`> ${truncate(event.replyTo.text)}`);
+    }
+    if (event.replyTo.authorName !== undefined) {
+        parts.push(`(replying to ${event.replyTo.authorName})`);
+    }
+    if (parts.length === 0)
+        return body;
+    return `${parts.join("\n")}\n\n${body}`;
+}
+/** The 500-char truncation with a bare ellipsis marker. */
+function truncate(text) {
+    return text.length <= QUOTE_MAX
+        ? text
+        : `${text.slice(0, QUOTE_MAX)}…`;
+}

package/dist/inbound/groups.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Group admission and sharing (spec §8.2): group config is consulted for
+ * every event, linked identities retain their own sender attribution,
+ * and unlinked `anyone` senders act only through the group owner's
+ * restricted conversation. Identity resolution reads core's link table.
+ */
+import type { InboundEvent, SigrunHost } from "@sigrun/sigrun/extension";
+import type { ConversationId } from "@earendil-works/pi-durable";
+import type { ChannelConfig, GroupConfig } from "../config.js";
+import type { IdentityStore } from "../state/identities.js";
+/** The terminal result of group admission. */
+export type GroupAdmission = {
+    readonly admit: false;
+    readonly reason: "unlisted" | "failed" | "mention" | "unlinked";
+} | {
+    readonly admit: true;
+    readonly group: GroupConfig;
+    /** The linked user, or the group owner for an unlinked sender. */
+    readonly user: string;
+    readonly linked: boolean;
+    readonly senderLabel: string;
+};
+/** Resolve one event against the channel's current group configuration. */
+export declare function admitGroupEvent(config: ChannelConfig, channel: string, event: InboundEvent, identities: IdentityStore): Promise<GroupAdmission>;
+/**
+ * Give a linked speaker write access without discarding existing people.
+ * The owner already has write access and must not also appear as a guest.
+ */
+export declare function ensureGroupShare(host: SigrunHost, conversationId: ConversationId, user: string): Promise<void>;

package/dist/inbound/groups.js

@@ -0,0 +1,55 @@
+/**
+ * Group admission and sharing (spec §8.2): group config is consulted for
+ * every event, linked identities retain their own sender attribution,
+ * and unlinked `anyone` senders act only through the group owner's
+ * restricted conversation. Identity resolution reads core's link table.
+ */
+/** Resolve one event against the channel's current group configuration. */
+export async function admitGroupEvent(config, channel, event, identities) {
+    const row = config.groups.find((group) => group.chat === event.chat.chatId);
+    if (row === undefined)
+        return { admit: false, reason: "unlisted" };
+    if ("failed" in row)
+        return { admit: false, reason: "failed" };
+    if (row.mention === "required" && event.mentioned !== true) {
+        return { admit: false, reason: "mention" };
+    }
+    const resolved = await identities.userFor(config, channel, event.sender.id);
+    if (resolved === undefined && row.members === "linked") {
+        return { admit: false, reason: "unlinked" };
+    }
+    if (resolved === undefined) {
+        return {
+            admit: true,
+            group: row,
+            user: row.owner,
+            linked: false,
+            senderLabel: `${event.sender.name ?? event.sender.id} (not linked)`,
+        };
+    }
+    return {
+        admit: true,
+        group: row,
+        user: resolved.user,
+        linked: true,
+        // The pipeline replaces this platform fallback with the directory
+        // display name when the directory supplies one.
+        senderLabel: event.sender.name ?? resolved.user,
+    };
+}
+/**
+ * Give a linked speaker write access without discarding existing people.
+ * The owner already has write access and must not also appear as a guest.
+ */
+export async function ensureGroupShare(host, conversationId, user) {
+    const meta = await host.conversations.meta(conversationId);
+    if (meta.owner === user)
+        return;
+    const sharing = meta.sharing;
+    if (sharing?.scope === "people" && sharing.users.includes(user))
+        return;
+    const users = sharing?.scope === "people" ? [...sharing.users, user] : [user];
+    await host.conversations.patchMeta(conversationId, {
+        sharing: { scope: "people", users, level: "write" },
+    });
+}

package/dist/inbound/media.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Inbound attachments (spec §8.11): lazy, capped fetches become
+ * upload-backed submission parts. A failed attachment never rejects the
+ * whole chat message; its pinned note is the model-visible outcome.
+ */
+import type { InboundAttachment, SigrunHost, SubmissionInputPart } from "@sigrun/sigrun/extension";
+import type { EngineLog } from "../log.js";
+export declare const TOO_LARGE_NOTE = "[attachment skipped: too large]";
+export declare const VOICE_NOTE = "[voice note attached; transcription unavailable]";
+export declare const ATTACHMENT_FAILED_NOTE = "[attachment failed]";
+export interface MediaDeps {
+    readonly host: SigrunHost;
+    readonly log: EngineLog;
+}
+export interface CollectedAttachments {
+    readonly parts: SubmissionInputPart[];
+    readonly notes: string[];
+}
+/** Collect every attachment independently, preserving event order. */
+export declare function collectAttachments(deps: MediaDeps, conversationId: number, attachments: readonly InboundAttachment[], maxBytes: number, signal: AbortSignal): Promise<CollectedAttachments>;

package/dist/inbound/media.js

@@ -0,0 +1,88 @@
+/**
+ * Inbound attachments (spec §8.11): lazy, capped fetches become
+ * upload-backed submission parts. A failed attachment never rejects the
+ * whole chat message; its pinned note is the model-visible outcome.
+ */
+export const TOO_LARGE_NOTE = "[attachment skipped: too large]";
+export const VOICE_NOTE = "[voice note attached; transcription unavailable]";
+export const ATTACHMENT_FAILED_NOTE = "[attachment failed]";
+/** Collect every attachment independently, preserving event order. */
+export async function collectAttachments(deps, conversationId, attachments, maxBytes, signal) {
+    const parts = [];
+    const notes = [];
+    const usedNames = new Set();
+    for (const attachment of attachments) {
+        // The declared size is the cheap gate: an already-oversize object
+        // must not even open its platform download stream.
+        if (attachment.size !== undefined && attachment.size > maxBytes) {
+            notes.push(TOO_LARGE_NOTE);
+            continue;
+        }
+        let bytes;
+        try {
+            bytes = await attachment.fetch({ maxBytes, signal });
+        }
+        catch (error) {
+            if (thrownName(error) === "AttachmentTooLarge") {
+                notes.push(TOO_LARGE_NOTE);
+            }
+            else {
+                deps.log.warn(`attachment fetch failed: ${errorMessage(error)}`);
+                notes.push(ATTACHMENT_FAILED_NOTE);
+            }
+            continue;
+        }
+        try {
+            const name = uniqueUploadName(uploadName(attachment), usedNames);
+            const uploaded = await deps.host.conversations.upload(conversationId, {
+                name,
+                ...(attachment.mime === undefined ? {} : { mime: attachment.mime }),
+                bytes,
+            });
+            parts.push({
+                type: attachment.kind === "image" ? "image" : "file",
+                path: uploaded.path,
+                ...(attachment.mime === undefined ? {} : { mime: attachment.mime }),
+            });
+            if (attachment.kind === "voice")
+                notes.push(VOICE_NOTE);
+        }
+        catch (error) {
+            deps.log.error("attachment upload failed", error);
+            notes.push(ATTACHMENT_FAILED_NOTE);
+        }
+    }
+    return { parts, notes };
+}
+/** Preserve every same-named sibling by appending its batch position. */
+function uniqueUploadName(base, used) {
+    let candidate = base;
+    let suffix = 2;
+    while (used.has(candidate)) {
+        const dot = base.lastIndexOf(".");
+        candidate = dot > 0
+            ? `${base.slice(0, dot)}-${suffix}${base.slice(dot)}`
+            : `${base}-${suffix}`;
+        suffix++;
+    }
+    used.add(candidate);
+    return candidate;
+}
+/** Match adapter errors by name across realms and non-Error throw shapes. */
+function thrownName(error) {
+    return typeof error === "object" && error !== null && "name" in error &&
+        typeof error.name === "string"
+        ? error.name
+        : undefined;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Keep upload names to the host's single-path-segment contract. */
+function uploadName(attachment) {
+    const supplied = attachment.filename?.split(/[\\/]/).pop();
+    if (supplied !== undefined && supplied !== "" && supplied !== "." && supplied !== "..") {
+        return supplied;
+    }
+    return attachment.kind === "image" ? "attachment.image" : "attachment.file";
+}

package/dist/inbound/pipeline.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The inbound pipeline (spec §8.4): one `receive` runs the ordered
+ * steps. Task 3 landed steps 2 (dedupe), 3 (self/bot drops), 6 (album
+ * merge) and 10 (submit) plus the M12 submit-error outcomes; Task 4
+ * fills step 1 (the claimed gate), step 4 (self-link) and step 5 (the
+ * DM access policies) INLINE over the shared {@link AccessState} — the
+ * access stores are engine-wide (one pairing queue, one link-code
+ * table, one token table, one loop guard), so the engine builds the
+ * state and hands it to every channel's pipeline. Steps 7 (commands),
+ * 8 (interaction answers) and 9 (attachments) remain INJECTABLE STAGES
+ * (`PipelineDeps.stages`) filled by their own tasks — the design keeps
+ * the step ORDER in one place while each task lands its logic.
+ *
+ * The channel's config is read LIVE per event by the CALLER (the
+ * engine's `receive` wrapper reads `readConfig(host)` and passes the
+ * channel's block in) — every field except `enabled` is per-event.
+ *
+ * On admission the pipeline records `submissionId → { bindingKey,
+ * channel }` in `deps.origins` (the in-memory map the outbound tasks
+ * consume — which chat a run came from, so settled answers route).
+ *
+ * The notice/error replies go through `deps.channel.send` — the
+ * adapter-bound transport, host-independent (the loopback fixture's
+ * `sent` array records them, which is how the sigrun e2e asserts reply
+ * text). A failed notice send is logged, never thrown: the submit
+ * error already resolved the event's fate.
+ */
+import type { ActionEvent, ChannelContribution, InboundEvent, SigrunHost } from "@sigrun/sigrun/extension";
+import type { SubmissionId } from "@earendil-works/pi-durable";
+import type { ChannelConfig } from "../config.js";
+import type { JsonValue } from "@sigrun/shared/blocks";
+import type { EngineLog } from "../log.js";
+import type { StreamOrigin } from "../outbound/stream.js";
+import { BindingStore } from "../state/bindings.js";
+import { IdentityStore } from "../state/identities.js";
+import { PairingStore } from "../access/pairing.js";
+import { LinkCodes } from "../access/link-codes.js";
+import { LoopGuard } from "../access/loop-guard.js";
+import { ButtonTokens } from "./tokens.js";
+/** A receive's terminal outcome (the adapter acks on any resolution). */
+export type PipelineOutcome = {
+    readonly outcome: "admitted";
+} | {
+    readonly outcome: "dropped";
+} | {
+    readonly outcome: "command";
+};
+/**
+ * The origin record: which chat a submission came from. The outbound
+ * tasks (streaming hand-off, unanswered notices) read it.
+ */
+export interface SubmissionOrigin extends StreamOrigin {
+}
+/**
+ * The engine-wide access state (Task 4): every store the access steps
+ * and the pair/link commands share. The ENGINE builds one and threads
+ * it into every channel pipeline AND the command closures; a pipeline
+ * constructed WITHOUT one builds a private state over its own state
+ * dir (the stand-alone Task 3 shape).
+ */
+export interface AccessState {
+    readonly identities: IdentityStore;
+    readonly pairing: PairingStore;
+    readonly linkCodes: LinkCodes;
+    readonly tokens: ButtonTokens;
+    readonly loopGuard: LoopGuard;
+}
+/** The stages later tasks inject (§8.4 steps 8, 9). */
+export interface PipelineStages {
+    /** Step 8 (interaction text answers): consumed-or-continue, as above. */
+    readonly interactionAnswer?: (channelId: string, event: InboundEvent) => Promise<PipelineOutcome | undefined>;
+    /** Step 9 (attachments): render the event's media into submit parts. */
+    readonly attachments?: (event: InboundEvent) => Promise<import("./media.js").CollectedAttachments>;
+}
+/** The pipeline's injectable dependencies. */
+export interface PipelineDeps {
+    readonly host: SigrunHost;
+    /** The channel adapter (send for notice replies; the label for names). */
+    readonly channel: ChannelContribution;
+    /** The engine's state dir (`<stateDir>/gateway`). */
+    readonly stateDir: string;
+    readonly log: EngineLog;
+    /** submissionId → the origin record (the outbound seam). */
+    readonly origins: Map<SubmissionId, SubmissionOrigin>;
+    /** The engine-wide binding store (the settled fan-out and the
+     *  delivery workers share this ONE instance — cross-instance writes
+     *  would interleave JsonFile queues and lose updates). Absent → a
+     *  private instance (the stand-alone Task 3 shape). */
+    readonly bindings?: BindingStore;
+    /** The injectable stages (§8.4 steps 8, 9). */
+    readonly stages?: PipelineStages;
+    /** Task 9's write-gated interaction answer seam (button taps). */
+    readonly interactionAnswer?: (answer: {
+        readonly conversationId: number;
+        readonly callId: string;
+        readonly values: Record<string, JsonValue>;
+        readonly user: string | undefined;
+    }) => Promise<string>;
+    /** Cross-channel lookup for `/pair` approval notices. Stand-alone
+     *  pipelines fall back to their own adapter. */
+    readonly channelOf?: (channel: string) => ChannelContribution | undefined;
+    /** The engine-wide access state (Task 4). Absent → a private one. */
+    readonly access?: AccessState;
+    /** The origin-chat stream registry (Task 6). Absent in stand-alone
+     *  pipeline tests disables streaming; the engine always wires it. */
+    readonly streams?: PipelineStreams;
+    /** The clock (tests inject a fake). Default: real. */
+    readonly now?: () => number;
+}
+/** The pipeline's narrow stream seam; StreamRegistry and test fakes fit it. */
+export interface PipelineStreams {
+    open(conversationId: number, origin: StreamOrigin): Promise<boolean>;
+    abandon(conversationId: number): void;
+}
+/**
+ * The engine's per-receive handler: `(channelId, event, config) →
+ * outcome`. The config is the LIVE channel block (the caller read it
+ * per event through `readConfig`).
+ */
+export type Receive = (channelId: string, event: InboundEvent, config: ChannelConfig) => Promise<PipelineOutcome>;
+/**
+ * A pipeline's receive, carrying the engine-owned flush handle and the
+ * tap handler: ONE pipeline per supervised channel (the binding key
+ * carries the channel) — the engine
+ * wires every supervised channel's `ChannelContext.receive` through
+ * the callable, calls `flushAlbums` from its `stopIntake`, and routes
+ * `ChannelContext.action` through `action`.
+ */
+export interface PipelineHandle extends Receive {
+    /**
+     * Close every open album window and submit its merged batch; the
+     * engine's `stopIntake` runs this before intake closes (the §8.0
+     * ordering: flush, then stop admitting).
+     */
+    flushAlbums(): Promise<void>;
+    /**
+     * A button tap (§8.7): resolve the token, guard the tapper (a pair
+     * decision needs an EFFECTIVE admin — C8), apply the decision.
+     * Foreign or replayed tokens are ignored; a tap never throws across
+     * the adapter boundary.
+     */
+    action(channelId: string, event: ActionEvent, config: ChannelConfig): Promise<void>;
+}
+export declare function createPipeline(deps: PipelineDeps): PipelineHandle;