@sigrun/ext-gateway 0.0.0-stage → 0.1.1

package/dist/commands/link.js

@@ -0,0 +1,77 @@
+/**
+ * Self-linking (spec §8.2): the webui/TUI `/link <channel>` command
+ * issues a single-use code bound to the invoking user and channel, and
+ * the chat-side `redeemLink` (pipeline step 4) consumes it in a DM.
+ *
+ * Proof by holding both sessions: the code is the only bridge, so it is
+ * single-use, channel-bound, expires with pairing codes (3600000 ms),
+ * and a code exposed in a GROUP is invalidated (other members saw it —
+ * M9; the group refusal lives in the pipeline step, which owns the
+ * chat-shape check).
+ *
+ * A sender already linked to another user gets core's conflict refusal
+ * and the pinned reply; the code is NOT consumed until the link lands,
+ * so the user can remove the conflicting link and send the SAME code.
+ */
+import { normalizeCode } from "../access/codes.js";
+import { chatProviderOf } from "../state/identities.js";
+/** The pinned refusal for an unnamed caller (spec §8.2). */
+export const UNNAMED_CALLER = "run this as a named user";
+/** The pinned conflict reply (the code stays live). */
+export const LINK_CONFLICT_REPLY = "This chat account is already linked to another sigrun user. Remove that link under account links in sigrun, then send the code again.";
+/** The pinned invalid-code reply. */
+const INVALID_CODE_REPLY = "That code is not valid.";
+/**
+ * Handle `/link <code>` from a DM: redeem, link, and return the reply
+ * text (the pipeline sends it). Core owns the conflict check; the
+ * static allowlist never blocks a self-link (it shadows the link
+ * afterward, exactly as any stale link).
+ */
+export async function redeemLink(deps, channel, event) {
+    const code = normalizeCode(event.text.replace(/^\/link\s*/, ""));
+    const now = deps.now();
+    const user = deps.linkCodes.peek(code, channel, now);
+    if (user === undefined)
+        return INVALID_CODE_REPLY;
+    const linked = await deps.identities.link(channel, event.sender.id, user, "self", event.chat);
+    if (!linked.linked)
+        return LINK_CONFLICT_REPLY;
+    // Redeem only after the link succeeds: a conflict keeps the code live.
+    const redeemed = deps.linkCodes.redeem(code, channel, now);
+    if (redeemed === undefined) {
+        deps.log.warn(`self-link for user "${user}" on provider "${chatProviderOf(channel)}" is durable but code redemption failed`);
+        return INVALID_CODE_REPLY;
+    }
+    deps.log.info(`self-link landed on channel "${channel}" for user "${redeemed}"`);
+    return `You are linked to sigrun as ${redeemed}.`;
+}
+/** Build the `link` slash command over the engine's shared state. */
+export function createLinkCommand(deps) {
+    return {
+        name: "link",
+        description: "Link this chat account to a channel with a single-use code",
+        args: "<channel>",
+        run: async (ctx) => {
+            if (ctx.principal.user === undefined) {
+                return { notice: UNNAMED_CALLER };
+            }
+            const channel = ctx.args.trim();
+            if (channel === "") {
+                return { notice: "usage: /link <channel>" };
+            }
+            if (!deps.knownChannels().includes(channel)) {
+                return { notice: `unknown channel ${channel}.` };
+            }
+            const config = await deps.readConfig();
+            const block = config.channels[channel];
+            if (block === undefined || "failed" in block || !block.enabled) {
+                return { notice: `channel ${channel} is disabled.` };
+            }
+            const code = deps.linkCodes.issue(ctx.principal.user, channel, deps.now());
+            return {
+                notice: `Link code ${code}. Send "/link ${code}" to the bot in a direct ` +
+                    `message on ${channel} to finish linking.`,
+            };
+        },
+    };
+}

package/dist/commands/pair.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The `/pair` command (spec §8.2): the admin surface for pending
+ * pairing requests, runnable from any webui/TUI conversation through
+ * the extension-command invoke route (`POST /v1/conversations/:id/
+ * commands/pair`) — and, through the same decision functions, from
+ * chat via the pairing-notice buttons (§8.2: every admin's home DM
+ * gets the request; the buttons carry opaque tokens the pipeline
+ * resolves).
+ *
+ * Admin-only (EFFECTIVE admin — the caller's principal carries it from
+ * the stored flag OR the persisted group grant, C8). An unnamed caller
+ * (the no-auth loopback method) is refused with the pinned
+ * "run this as a named user".
+ *
+ * `approve <code> <user>` links the REQUESTER (the platform sender who
+ * asked to pair) to the named directory user via the identity store
+ * (`via: "pairing"`), sets their DM as the home chat, and sends them a
+ * "linked" message through their channel. Core refuses a sender already
+ * linked to another user; the request then stays pending for an admin
+ * to resolve (deny, or remove the link).
+ */
+import type { ChannelContribution } from "@sigrun/sigrun/extension";
+import type { EngineLog } from "../log.js";
+import type { IdentityStore } from "../state/identities.js";
+import type { PairingStore } from "../access/pairing.js";
+/** The `/pair` decision path's runtime dependencies (the engine wires them). */
+export interface PairDeps {
+    /** The host: the directory the approved user must exist in. */
+    readonly host: {
+        readonly users: {
+            list(): Promise<readonly {
+                readonly user: string;
+            }[]>;
+        };
+    };
+    readonly identities: IdentityStore;
+    readonly pairing: PairingStore;
+    /**
+     * The channel adapter for `channelOf(id)` — the "linked" reply rides
+     * the requester's own channel (undefined: the channel went away; the
+     * reply is skipped, the link still lands).
+     */
+    readonly channelOf: (channel: string) => ChannelContribution | undefined;
+    readonly log: EngineLog;
+    readonly now: () => number;
+}
+/** Who invoked the command. */
+export interface PairCaller {
+    readonly user: string | undefined;
+    readonly admin: boolean;
+}
+/** The pinned refusal for an unnamed caller (spec §8.2). */
+export declare const UNNAMED_CALLER = "run this as a named user";
+/** The pinned conflict reply (spec §8.2: never silently re-pointed). */
+export declare const PAIR_CONFLICT_REPLY = "That sender is already linked to another user.";
+/**
+ * Run `/pair` with `args` as `caller`. Every path resolves a string
+ * reply (the command's notice); nothing throws across the boundary.
+ */
+export declare function runPair(deps: PairDeps, args: string, caller: PairCaller): Promise<string>;
+/**
+ * Apply `deny <code>` (the command and the button share this path).
+ * Returns the decision reply for the admin surface.
+ */
+export declare function denyPairing(deps: PairDeps, code: string): string;
+/**
+ * Apply `approve <code> <user>` (the command and the "Approve as"
+ * buttons share this path): directory check, core-backed link, then
+ * consume the queue row and send the requester's "linked" message.
+ * Core's conflict refusal leaves the request pending.
+ */
+export declare function approvePairing(deps: PairDeps, code: string, namedUser: string): Promise<string>;

package/dist/commands/pair.js

@@ -0,0 +1,110 @@
+/**
+ * The `/pair` command (spec §8.2): the admin surface for pending
+ * pairing requests, runnable from any webui/TUI conversation through
+ * the extension-command invoke route (`POST /v1/conversations/:id/
+ * commands/pair`) — and, through the same decision functions, from
+ * chat via the pairing-notice buttons (§8.2: every admin's home DM
+ * gets the request; the buttons carry opaque tokens the pipeline
+ * resolves).
+ *
+ * Admin-only (EFFECTIVE admin — the caller's principal carries it from
+ * the stored flag OR the persisted group grant, C8). An unnamed caller
+ * (the no-auth loopback method) is refused with the pinned
+ * "run this as a named user".
+ *
+ * `approve <code> <user>` links the REQUESTER (the platform sender who
+ * asked to pair) to the named directory user via the identity store
+ * (`via: "pairing"`), sets their DM as the home chat, and sends them a
+ * "linked" message through their channel. Core refuses a sender already
+ * linked to another user; the request then stays pending for an admin
+ * to resolve (deny, or remove the link).
+ */
+import { normalizeCode } from "../access/codes.js";
+/** The pinned refusal for an unnamed caller (spec §8.2). */
+export const UNNAMED_CALLER = "run this as a named user";
+/** The pinned conflict reply (spec §8.2: never silently re-pointed). */
+export const PAIR_CONFLICT_REPLY = "That sender is already linked to another user.";
+/** The usage line (the args grammar, one line). */
+const USAGE = "usage: /pair [approve <code> <user> | deny <code>]";
+/**
+ * Run `/pair` with `args` as `caller`. Every path resolves a string
+ * reply (the command's notice); nothing throws across the boundary.
+ */
+export async function runPair(deps, args, caller) {
+    if (caller.user === undefined)
+        return UNNAMED_CALLER;
+    if (!caller.admin) {
+        return "only admins can manage pairing requests.";
+    }
+    const parts = args.trim().split(/\s+/).filter((part) => part !== "");
+    if (parts.length === 0)
+        return listPending(deps);
+    const verb = parts[0];
+    if (verb === "deny" && parts.length === 2) {
+        return denyPairing(deps, normalizeCode(parts[1] ?? ""));
+    }
+    if (verb === "approve" && parts.length === 3) {
+        return approvePairing(deps, normalizeCode(parts[1] ?? ""), parts[2] ?? "");
+    }
+    return USAGE;
+}
+/** `""` — one line per pending request (channel, sender, code, age). */
+function listPending(deps) {
+    const now = deps.now();
+    const rows = deps.pairing.pending();
+    if (rows.length === 0)
+        return "no pending pairing requests.";
+    return rows
+        .map((row) => {
+        const minutes = Math.max(0, Math.round((now - row.createdAt) / 60_000));
+        const who = row.senderName === undefined ? row.senderId : row.senderName;
+        return `${row.channel}: ${who} — /pair approve ${row.code} <user> (${minutes}m ago)`;
+    })
+        .join("\n");
+}
+/**
+ * Apply `deny <code>` (the command and the button share this path).
+ * Returns the decision reply for the admin surface.
+ */
+export function denyPairing(deps, code) {
+    if (deps.pairing.deny(code))
+        return `pairing request ${code} denied.`;
+    return `unknown pairing code ${code}.`;
+}
+/**
+ * Apply `approve <code> <user>` (the command and the "Approve as"
+ * buttons share this path): directory check, core-backed link, then
+ * consume the queue row and send the requester's "linked" message.
+ * Core's conflict refusal leaves the request pending.
+ */
+export async function approvePairing(deps, code, namedUser) {
+    const directory = await deps.host.users.list();
+    if (!directory.some((row) => row.user === namedUser)) {
+        return `unknown user ${namedUser}.`;
+    }
+    // The pre-approve read: find the row WITHOUT consuming it.
+    const request = deps.pairing.pending().find((row) => row.code === code);
+    if (request === undefined) {
+        return `unknown pairing code ${code}.`;
+    }
+    const linked = await deps.identities.link(request.channel, request.senderId, namedUser, "pairing", request.chat);
+    if (!linked.linked)
+        return PAIR_CONFLICT_REPLY;
+    deps.pairing.approve(code, deps.now());
+    deps.log.info(`pairing approved on channel "${request.channel}" for user "${namedUser}"`);
+    const channel = deps.channelOf(request.channel);
+    if (channel !== undefined) {
+        try {
+            await channel.send({
+                chat: request.chat,
+                text: `You are linked to sigrun as ${namedUser}.`,
+            });
+        }
+        catch (error) {
+            // The link landed; the celebratory notice is best-effort (a
+            // down channel never rolls back an approval).
+            deps.log.error("pairing linked-notice send failed", error);
+        }
+    }
+    return `linked ${request.senderName ?? request.senderId} to ${namedUser}.`;
+}

package/dist/config.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Gateway configuration (spec §8.1): `settings/gateway.json` through the
+ * engine's scoped settings store, parsed PER READ (live config — every
+ * field except a group's `tools`/`extensions` is read per event).
+ *
+ * Malformed-config posture: a malformed block for one channel or group
+ * disables THAT channel or group with the reason (the `{failed}` forms)
+ * and never affects its siblings; malformed top-level scalars fall back
+ * to their defaults. The parser never throws.
+ *
+ * Types are imported from `@sigrun/sigrun/extension` type-only (the
+ * types-in-main-package contract); this module's runtime imports are
+ * none — it is a pure function over a parsed-JSON object.
+ */
+import type { SigrunHost } from "@sigrun/sigrun/extension";
+/** The DM admission policy (spec §8.2). */
+export type DmPolicy = "pairing" | "allowlist" | "disabled";
+/** One group chat's config (spec §8.1). */
+export interface GroupConfig {
+    readonly chat: string;
+    readonly owner: string;
+    readonly mention: "required" | "always";
+    readonly members: "linked" | "anyone";
+    readonly tools?: readonly string[];
+    readonly extensions?: readonly string[];
+}
+/** One channel's config (spec §8.1). */
+export interface ChannelConfig {
+    readonly enabled: boolean;
+    readonly dm: DmPolicy;
+    readonly selfLink: boolean;
+    readonly allow: readonly {
+        sender: string;
+        user: string;
+    }[];
+    readonly groups: readonly (GroupConfig | {
+        readonly chat: string;
+        readonly failed: string;
+    })[];
+    readonly busy: "followUp" | "steer";
+    readonly stream: boolean;
+    readonly allowBots: boolean;
+}
+/** The whole `settings/gateway.json` shape (spec §8.1). */
+export interface GatewayConfig {
+    readonly channels: Readonly<Record<string, ChannelConfig | {
+        readonly failed: string;
+    }>>;
+    readonly media: {
+        readonly maxBytes: number;
+    };
+    readonly notify: {
+        readonly home: boolean;
+    };
+}
+/** Default media cap (16 MiB — the readFile ceiling, spec §8.1). */
+export declare const DEFAULT_MEDIA_MAX_BYTES = 16777216;
+/** Parse the raw settings object into the validated {@link GatewayConfig}. */
+export declare function parseGatewayConfig(raw: Record<string, unknown>): GatewayConfig;
+/**
+ * Read the config LIVE through the engine's scoped settings store: the
+ * store's object parsed per call, so an operator's edit takes effect on
+ * the next event without a restart (only `enabled` is restart-required).
+ */
+export declare function readConfig(host: SigrunHost): Promise<GatewayConfig>;

package/dist/config.js

@@ -0,0 +1,219 @@
+/**
+ * Gateway configuration (spec §8.1): `settings/gateway.json` through the
+ * engine's scoped settings store, parsed PER READ (live config — every
+ * field except a group's `tools`/`extensions` is read per event).
+ *
+ * Malformed-config posture: a malformed block for one channel or group
+ * disables THAT channel or group with the reason (the `{failed}` forms)
+ * and never affects its siblings; malformed top-level scalars fall back
+ * to their defaults. The parser never throws.
+ *
+ * Types are imported from `@sigrun/sigrun/extension` type-only (the
+ * types-in-main-package contract); this module's runtime imports are
+ * none — it is a pure function over a parsed-JSON object.
+ */
+/** Default media cap (16 MiB — the readFile ceiling, spec §8.1). */
+export const DEFAULT_MEDIA_MAX_BYTES = 16_777_216;
+/** Parse the raw settings object into the validated {@link GatewayConfig}. */
+export function parseGatewayConfig(raw) {
+    return {
+        channels: parseChannels(raw.channels),
+        media: parseMedia(raw.media),
+        notify: parseNotify(raw.notify),
+    };
+}
+/**
+ * Read the config LIVE through the engine's scoped settings store: the
+ * store's object parsed per call, so an operator's edit takes effect on
+ * the next event without a restart (only `enabled` is restart-required).
+ */
+export async function readConfig(host) {
+    const raw = await host.stores.settings.get();
+    return parseGatewayConfig(raw);
+}
+// ---------------------------------------------------------------------------
+// Channel parsing
+// ---------------------------------------------------------------------------
+function parseChannels(value) {
+    if (!isRecord(value))
+        return {};
+    const channels = {};
+    for (const [id, block] of Object.entries(value)) {
+        channels[id] = parseChannel(block, id);
+    }
+    return channels;
+}
+function parseChannel(value, id) {
+    if (!isRecord(value)) {
+        return { failed: `channel "${id}" config is not an object` };
+    }
+    if (value.dm !== undefined && !isDmPolicy(value.dm)) {
+        return {
+            failed: `channel "${id}" dm must be "pairing" | "allowlist" | "disabled"`,
+        };
+    }
+    const dm = value.dm === undefined ? "pairing" : value.dm;
+    if (value.enabled !== undefined && typeof value.enabled !== "boolean") {
+        return { failed: `channel "${id}" enabled must be a boolean` };
+    }
+    if (value.busy !== undefined &&
+        value.busy !== "followUp" &&
+        value.busy !== "steer") {
+        return { failed: `channel "${id}" busy must be "followUp" | "steer"` };
+    }
+    const allow = parseAllow(value.allow, id);
+    if (typeof allow === "string")
+        return { failed: allow };
+    const groups = parseGroups(value.groups, id);
+    if (typeof groups === "string")
+        return { failed: groups };
+    if (value.selfLink !== undefined && typeof value.selfLink !== "boolean") {
+        return { failed: `channel "${id}" selfLink must be a boolean` };
+    }
+    if (value.stream !== undefined && typeof value.stream !== "boolean") {
+        return { failed: `channel "${id}" stream must be a boolean` };
+    }
+    if (value.allowBots !== undefined && typeof value.allowBots !== "boolean") {
+        return { failed: `channel "${id}" allowBots must be a boolean` };
+    }
+    // selfLink defaults true for pairing channels, false otherwise (spec
+    // §8.1: an allowlist channel's operator chose a closed list).
+    const selfLinkDefault = dm === "pairing";
+    return {
+        enabled: value.enabled === undefined ? true : value.enabled,
+        dm,
+        selfLink: value.selfLink === undefined ? selfLinkDefault : value.selfLink,
+        allow,
+        groups,
+        busy: value.busy === undefined ? "followUp" : value.busy,
+        stream: value.stream === undefined ? true : value.stream,
+        allowBots: value.allowBots === undefined ? false : value.allowBots,
+    };
+}
+function isDmPolicy(value) {
+    return value === "pairing" || value === "allowlist" || value === "disabled";
+}
+function parseAllow(value, id) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        return `channel "${id}" allow must be an array`;
+    }
+    const entries = [];
+    for (const entry of value) {
+        if (!isRecord(entry)) {
+            return `channel "${id}" allow entries must be objects`;
+        }
+        if (typeof entry.sender !== "string" || entry.sender === "") {
+            return `channel "${id}" allow entries need a non-empty string sender`;
+        }
+        if (typeof entry.user !== "string" || entry.user === "") {
+            return `channel "${id}" allow entries need a non-empty string user`;
+        }
+        entries.push({ sender: entry.sender, user: entry.user });
+    }
+    return entries;
+}
+function parseGroups(value, id) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        return `channel "${id}" groups must be an array`;
+    }
+    return value.map((group) => parseGroup(group));
+}
+function parseGroup(value) {
+    if (!isRecord(value)) {
+        return { chat: "", failed: "group config is not an object" };
+    }
+    // The failed-group form still names WHICH chat failed: an absent or
+    // non-string chat renders as the empty string so the row is shaped.
+    const chat = typeof value.chat === "string" ? value.chat : "";
+    if (chat === "") {
+        return { chat, failed: "group needs a non-empty string chat" };
+    }
+    if (typeof value.owner !== "string" || value.owner === "") {
+        return { chat, failed: `group "${chat}" needs a non-empty string owner` };
+    }
+    if (value.mention !== undefined &&
+        value.mention !== "required" &&
+        value.mention !== "always") {
+        return {
+            chat,
+            failed: `group "${chat}" mention must be "required" | "always"`,
+        };
+    }
+    if (value.members !== undefined &&
+        value.members !== "linked" &&
+        value.members !== "anyone") {
+        return {
+            chat,
+            failed: `group "${chat}" members must be "linked" | "anyone"`,
+        };
+    }
+    const members = value.members === undefined ? "linked" : value.members;
+    if (value.tools !== undefined && !isStringArray(value.tools)) {
+        return {
+            chat,
+            failed: `group "${chat}" tools must be an array of strings`,
+        };
+    }
+    if (value.extensions !== undefined && !isStringArray(value.extensions)) {
+        return {
+            chat,
+            failed: `group "${chat}" extensions must be an array of strings`,
+        };
+    }
+    const tools = value.tools;
+    let extensions = value.extensions;
+    if (members === "anyone") {
+        // Spec §8.1: "anyone" REQUIRES a non-empty tools array — an open
+        // group without a pinned tool set would run the full default agent
+        // for untrusted senders.
+        if (tools === undefined || tools.length === 0) {
+            return {
+                chat,
+                failed: `group "${chat}" members: "anyone" requires a non-empty tools array`,
+            };
+        }
+        // Spec §8.10: the gateway's own prompt section rides along on
+        // anyone groups (the model must see its chat context).
+        if (extensions !== undefined && !extensions.includes("gateway")) {
+            extensions = [...extensions, "gateway"];
+        }
+    }
+    return {
+        chat,
+        owner: value.owner,
+        mention: value.mention === undefined ? "required" : value.mention,
+        members,
+        ...(tools === undefined ? {} : { tools }),
+        ...(extensions === undefined ? {} : { extensions }),
+    };
+}
+// ---------------------------------------------------------------------------
+// Media / notify parsing
+// ---------------------------------------------------------------------------
+function parseMedia(value) {
+    if (isRecord(value) &&
+        typeof value.maxBytes === "number" &&
+        value.maxBytes > 0) {
+        return { maxBytes: value.maxBytes };
+    }
+    return { maxBytes: DEFAULT_MEDIA_MAX_BYTES };
+}
+function parseNotify(value) {
+    if (isRecord(value) && typeof value.home === "boolean") {
+        return { home: value.home };
+    }
+    return { home: true };
+}
+// ---------------------------------------------------------------------------
+// Small helpers
+// ---------------------------------------------------------------------------
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+    return (Array.isArray(value) && value.every((item) => typeof item === "string"));
+}

package/dist/engine.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The gateway engine (spec §8.0, gateway C2): chat-transport supervision
+ * over the boot's channel bindings. ONE engine per boot; `start` runs
+ * after the server listens, `stopIntake` before the shutdown drain,
+ * `stop` after it.
+ *
+ * Task 2 owns supervision: `start` reads the LIVE config once for the
+ * restart-required enablement (a channel absent from `channels`, an
+ * `enabled: false`, or a `{failed}` config block never starts its
+ * adapter — the engine records a static row instead), then hands every
+ * enabled channel a {@link Supervisor}. Health (§8.12) reads the
+ * supervisors' unhealthy dwell plus the ledger's failed-in-last-hour
+ * count (Task 5: the engine-owned ledger feeds the `failedRecently`
+ * seam — tests may still override it).
+ *
+ * The inbound pipeline (Task 3) drives `receive` (§8.4): the config
+ * block is read LIVE per event, admission runs the ordered steps, and
+ * the supervisor counts every outcome. `action` (button taps) stays a
+ * no-op until the token table lands (Tasks 4/9).
+ *
+ * `EngineInternals` is the test/task-internal surface (the state-dir
+ * path, the status read) — NOT part of the loader contract, which sees
+ * only the {@link GatewayEngine} four.
+ */
+import type { GatewayEngine, SigrunHost } from "@sigrun/sigrun/extension";
+import { type EngineLog } from "./log.js";
+import { createPipeline } from "./inbound/pipeline.js";
+import { type ChannelStatus } from "./supervisor.js";
+import type { PairDeps } from "./commands/pair.js";
+import { Ledger } from "./state/ledger.js";
+import type { AccessState } from "./inbound/pipeline.js";
+import type { StatusPairingRow } from "./status-route.js";
+import type { ToolDeps } from "./tools.js";
+import type { ChannelSectionDeps } from "./section.js";
+/**
+ * The engine's injectable dependencies (tests and later tasks). Task 1
+ * carried only the log; every later seam lands here so the constructor
+ * signature never changes twice.
+ */
+export interface EngineDeps {
+    readonly log?: EngineLog;
+    /** The timer bundle supervision rides. Default: real clock, real
+     *  timers, crypto random (the factory never wires a timer at
+     *  construction — the pi lifecycle rule; the supervisor starts them
+     *  only from its `start`). */
+    readonly timers?: {
+        now(): number;
+        random(): number;
+        setTimer(fn: () => void, ms: number): () => void;
+    };
+    /**
+     * The ledger's failed-in-last-hour count (§8.12's second health
+     * input). Default: the engine's OWN ledger over the real clock —
+     * tests inject a stub for the pre-ledger engine tests.
+     */
+    readonly failedRecently?: () => number;
+    /** Test/task-internal ledger seam for shutdown and recovery tests. */
+    readonly deliveryLedger?: Ledger;
+    /** Construction-count test seam; production uses the real pipeline. */
+    readonly pipelineFactory?: typeof createPipeline;
+    /** Test seam for the receipt wait; production keeps the pinned 30 s. */
+    readonly toolReceiptWaitMs?: number;
+}
+/** The task-internal surface over the contract four (see the module doc). */
+export interface EngineInternals {
+    /** The engine's state directory: `<stateDir>/gateway` (the scoped
+     *  `host.stores.paths.state` plus the engine's own segment). */
+    readonly stateDir: string;
+    /** The channel ids the last `start` recorded, in order. */
+    readonly channelIds: () => readonly string[];
+    /**
+     * The status route's read (Task 2): every channel's current row —
+     * supervised and static (config-error/disabled) alike.
+     */
+    status(): {
+        readonly channels: Readonly<Record<string, ChannelStatus>>;
+    };
+    /**
+     * The status route's pairing read (Task 4): every live pending
+     * request WITHOUT the code (hashed sender — §8.12's rule that
+     * operator output never carries raw platform ids).
+     */
+    pairingStatus(): readonly StatusPairingRow[];
+    /** The engine-wide access state (pipelines and commands share it). */
+    accessState(): AccessState;
+    /** The `/pair` decision deps over the shared state (the factory's
+     *  command closes over these — `host` is the factory's own host). */
+    pairDeps(host: SigrunHost): PairDeps;
+    /**
+     * The settled-run fan-out (the factory's `runSettled` closes over
+     * this): enqueues the finals/notices, then kicks the affected
+     * channels' workers.
+     */
+    settle(event: import("@sigrun/sigrun/extension").RunSettledEvent, api: import("@sigrun/sigrun/extension").MemoryEventApi, context: import("@sigrun/sigrun/extension").HandlerContext): Promise<void>;
+    /** The home-chat notifier and its enqueue-then-kick delivery path. */
+    notifier(): import("@sigrun/sigrun/extension").NotifierContribution;
+    /** Delivered prompt edits and bound-chat outcome notices. */
+    interactionSettled(event: import("@sigrun/sigrun/extension").ExtensionLifecyclePayload["interactionSettled"], context: import("@sigrun/sigrun/extension").HandlerContext): Promise<void>;
+    /** Agent tools and bound-chat prompt section over the same shared stores. */
+    toolDeps(): ToolDeps;
+    sectionDeps(): ChannelSectionDeps;
+}
+/**
+ * Build the engine over the host. The factory wires the real
+ * dependencies; tests inject the clock/log/timer seams through the same
+ * parameter.
+ */
+export declare function createEngine(host: SigrunHost, deps?: EngineDeps): GatewayEngine & EngineInternals;