@sigrun/ext-gateway 0.0.0-stage → 0.1.2

package/dist/access/pairing.js

@@ -0,0 +1,131 @@
+/**
+ * The pairing store (spec §8.2): pending pairing requests persisted at
+ * `<stateDir>/gateway/pairing.json`.
+ *
+ * Pinned limits (the Hermes/OpenClaw shared parameters):
+ * - at most 1 pending request per sender (`limited: "sender"`);
+ * - at most 1 new request per sender per 600000 ms (`limited:
+ *   "cooldown"` — enforced even after the previous request left the
+ *   queue, so a spamming sender gets exactly one reply per window);
+ * - at most 3 pending per channel (`limited: "channel"` — a visible
+ *   DoS floor an admin clears through `/pair deny` and the status
+ *   route).
+ *
+ * Codes expire after 3600000 ms; expired entries are dropped on every
+ * read. Codes are never logged.
+ */
+import { JsonFile } from "../state/json-file.js";
+import { newCode } from "./codes.js";
+/** The pinned expiry (ms). */
+export const PAIRING_TTL_MS = 3_600_000;
+/** The pinned per-sender request cooldown (ms). */
+const REQUEST_COOLDOWN_MS = 600_000;
+/** The pinned per-sender pending cap. */
+const SENDER_PENDING_MAX = 1;
+/** The pinned per-channel pending cap. */
+const CHANNEL_PENDING_MAX = 3;
+/** The cooldown key: one clock per (channel, sender). */
+function cooldownKey(channel, senderId) {
+    return `${channel}:${senderId}`;
+}
+/**
+ * The pairing queue, one instance per engine. The public API is
+ * SYNCHRONOUS by interface (the pipeline's step 5 answers inline), so
+ * every mutation writes the file through JsonFile's SYNCHRONOUS
+ * update — a crash between the verdict and a deferred flush would
+ * silently lose a pending request (the operator's queue).
+ */
+export class PairingStore {
+    file;
+    now;
+    mirror = { pending: [], lastRequest: {} };
+    constructor(path, opts = {}) {
+        this.file = new JsonFile(path, () => ({
+            pending: [],
+            lastRequest: {},
+        }));
+        this.now = opts.now ?? Date.now;
+        // The synchronous load: the constructor cannot await, and the queue
+        // is empty here so nothing can interleave the first observation.
+        this.mirror = this.file.readSync();
+    }
+    /**
+     * Create (or refuse) a pairing request. The caller hands `now` so the
+     * pipeline can pin a clock in tests; the store's own clock seeds the
+     * cooldown record.
+     */
+    request(channel, sender, chat, now) {
+        const live = this.livePending(now);
+        if (live.some((row) => row.channel === channel && row.senderId === sender.id)) {
+            return { limited: "sender" };
+        }
+        const last = this.mirror.lastRequest[cooldownKey(channel, sender.id)];
+        if (last !== undefined && now - last < REQUEST_COOLDOWN_MS) {
+            return { limited: "cooldown" };
+        }
+        if (live.filter((row) => row.channel === channel).length >= CHANNEL_PENDING_MAX) {
+            return { limited: "channel" };
+        }
+        const row = {
+            code: newCode(),
+            channel,
+            senderId: sender.id,
+            ...(sender.name === undefined ? {} : { senderName: sender.name }),
+            chat,
+            createdAt: now,
+        };
+        this.mirror = {
+            pending: [...live, row],
+            lastRequest: {
+                ...this.mirror.lastRequest,
+                [cooldownKey(channel, sender.id)]: now,
+            },
+        };
+        this.persist();
+        return { code: row.code };
+    }
+    /** The live pending rows, optionally filtered to one channel. */
+    pending(channel) {
+        return this.livePending(this.now()).filter((row) => channel === undefined || row.channel === channel);
+    }
+    /** Approve by code: the request leaves the queue and returns. */
+    approve(code, now = this.now()) {
+        const row = this.livePending(now).find((entry) => entry.code === code);
+        if (row === undefined)
+            return undefined;
+        this.mirror = {
+            ...this.mirror,
+            pending: this.livePending(now).filter((entry) => entry.code !== code),
+        };
+        this.persist();
+        return row;
+    }
+    /** Deny by code: true when a live request was removed. */
+    deny(code) {
+        const row = this.livePending(this.now()).find((entry) => entry.code === code);
+        if (row === undefined)
+            return false;
+        this.mirror = {
+            ...this.mirror,
+            pending: this.livePending(this.now()).filter((entry) => entry.code !== code),
+        };
+        this.persist();
+        return true;
+    }
+    /** The expired-row sweep: expired requests count against no limit. */
+    livePending(now) {
+        return this.mirror.pending.filter((row) => now - row.createdAt < PAIRING_TTL_MS);
+    }
+    /**
+     * Persist the mirror: the SYNCHRONOUS atomic write (see the class
+     * doc). A failed persist is loud, never swallowed — the verdict
+     * already returned to the pipeline, but the operator must see the
+     * file diverged (the JsonFile throw names the path).
+     */
+    persist() {
+        this.mirror = this.file.updateSync((draft) => {
+            draft.pending = this.mirror.pending;
+            draft.lastRequest = this.mirror.lastRequest;
+        });
+    }
+}

package/dist/commands/chat.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Chat commands (spec §8.5): the gateway's reserved slash commands plus
+ * non-colliding extension commands. They run inline at inbound stage 7,
+ * before the busy submission queue, and every operation acts on the
+ * chat's current binding.
+ *
+ * Unknown slash text is NOT consumed: prompt templates and skill
+ * expansion still belong to ordinary submission admission. `/link` and
+ * `/pair` are the authorization exceptions — linking needs no existing
+ * conversation access, and pairing applies its own effective-admin
+ * check. Every other command first proves write access to the bound
+ * conversation; `/attach` then separately proves write access to its
+ * target before changing the binding.
+ */
+import type { ChannelContribution, InboundEvent, SigrunHost } from "@sigrun/sigrun/extension";
+import type { Binding, BindingStore } from "../state/bindings.js";
+import type { IdentityStore } from "../state/identities.js";
+import type { PairingStore } from "../access/pairing.js";
+import type { LinkCodes } from "../access/link-codes.js";
+import type { GroupConfig } from "../config.js";
+import type { EngineLog } from "../log.js";
+/** One gateway chat command's native-menu metadata and placement rule. */
+export interface GatewayCommand {
+    readonly name: string;
+    readonly description: string;
+    readonly where: "any" | "dm" | "not-anyone-group";
+    readonly admin?: true;
+}
+/** The reserved command table, in spec §8.5 order. */
+export declare const GATEWAY_COMMANDS: readonly GatewayCommand[];
+/** The shared stores and host surfaces the command handlers use. */
+export interface ChatCommandDeps {
+    readonly host: SigrunHost;
+    readonly channel: ChannelContribution;
+    readonly bindings: BindingStore;
+    readonly identities: IdentityStore;
+    readonly pairing: PairingStore;
+    readonly linkCodes: LinkCodes;
+    readonly streams?: {
+        abandon(conversationId: number): void;
+    };
+    readonly channelOf: (channel: string) => ChannelContribution | undefined;
+    readonly log: EngineLog;
+    readonly now: () => number;
+}
+/** The admission context for one possible command. */
+export interface ChatCommandContext {
+    readonly channel: string;
+    readonly event: InboundEvent;
+    readonly bindingKey: string;
+    readonly user: string | undefined;
+    readonly binding?: Binding;
+    readonly group?: GroupConfig;
+    /** Stage 4 owns redemption when enabled; stage 7 must refuse when disabled. */
+    readonly selfLink: boolean;
+}
+/** The native menu: reserved commands plus non-colliding extension rows. */
+export declare function chatCommandMenu(host: SigrunHost): Promise<readonly {
+    readonly name: string;
+    readonly description: string;
+}[]>;
+/**
+ * Consume one gateway/extension command, or return `"not-a-command"`
+ * so admission continues with the original text.
+ */
+export declare function handleChatCommand(deps: ChatCommandDeps, ctx: ChatCommandContext): Promise<"command" | "not-a-command">;

package/dist/commands/chat.js

@@ -0,0 +1,371 @@
+/**
+ * Chat commands (spec §8.5): the gateway's reserved slash commands plus
+ * non-colliding extension commands. They run inline at inbound stage 7,
+ * before the busy submission queue, and every operation acts on the
+ * chat's current binding.
+ *
+ * Unknown slash text is NOT consumed: prompt templates and skill
+ * expansion still belong to ordinary submission admission. `/link` and
+ * `/pair` are the authorization exceptions — linking needs no existing
+ * conversation access, and pairing applies its own effective-admin
+ * check. Every other command first proves write access to the bound
+ * conversation; `/attach` then separately proves write access to its
+ * target before changing the binding.
+ */
+import { redeemLink } from "./link.js";
+import { runPair } from "./pair.js";
+/** The reserved command table, in spec §8.5 order. */
+export const GATEWAY_COMMANDS = [
+    { name: "new", description: "Start a fresh conversation and bind this chat to it", where: "any" },
+    { name: "stop", description: "Stop the live run", where: "any" },
+    { name: "model", description: "Show or change the conversation model", where: "any" },
+    { name: "thinking", description: "Show or change the thinking level", where: "any" },
+    { name: "compact", description: "Compact this conversation's history", where: "any" },
+    { name: "attach", description: "Bind this chat to an existing conversation", where: "not-anyone-group" },
+    { name: "status", description: "Show this chat's conversation status", where: "any" },
+    { name: "home", description: "Make this DM your home chat on this channel", where: "dm" },
+    { name: "link", description: "Link this chat account with a single-use code", where: "dm" },
+    { name: "pair", description: "Manage pending pairing requests (admin)", where: "dm", admin: true },
+    { name: "help", description: "List gateway and extension commands", where: "any" },
+];
+const THINKING_LEVELS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+];
+/** The native menu: reserved commands plus non-colliding extension rows. */
+export async function chatCommandMenu(host) {
+    const extensions = await extensionCommands(host);
+    return [
+        ...GATEWAY_COMMANDS.map(({ name, description }) => ({ name, description })),
+        ...extensions.map(({ name, description }) => ({ name, description })),
+    ];
+}
+/**
+ * Consume one gateway/extension command, or return `"not-a-command"`
+ * so admission continues with the original text.
+ */
+export async function handleChatCommand(deps, ctx) {
+    const parsed = parseCommand(ctx.event.text);
+    if (parsed === undefined)
+        return "not-a-command";
+    try {
+        return await dispatchChatCommand(deps, ctx, parsed);
+    }
+    catch (error) {
+        // User input must not turn an expected op rejection into an engine
+        // failure: the pipeline would release `seen` and the platform would
+        // redeliver the identical invalid command forever (the M12 posture).
+        const notice = expectedCommandError(error, parsed.name);
+        if (notice === undefined)
+            throw error;
+        await reply(deps, ctx, notice);
+        return "command";
+    }
+}
+/** Dispatch after parsing, under the public handler's expected-error boundary. */
+async function dispatchChatCommand(deps, ctx, parsed) {
+    const gateway = GATEWAY_COMMANDS.find((command) => command.name === parsed.name);
+    if (gateway === undefined) {
+        const extension = (await extensionCommands(deps.host)).find((command) => command.name === parsed.name);
+        if (extension === undefined)
+            return "not-a-command";
+        if (!(await hasBoundWriteAccess(deps, ctx))) {
+            await reply(deps, ctx, "You do not have write access to this conversation.");
+            return "command";
+        }
+        if (ctx.user === undefined || ctx.binding === undefined) {
+            await reply(deps, ctx, "You do not have write access to this conversation.");
+            return "command";
+        }
+        const result = await deps.host.commands.run(ctx.binding.conversationId, extension.name, parsed.args, { user: ctx.user });
+        if (result.notice !== undefined && result.notice !== "") {
+            await reply(deps, ctx, result.notice);
+        }
+        return "command";
+    }
+    if (gateway.where === "dm" && ctx.event.chat.chatType !== "dm") {
+        await reply(deps, ctx, "send this in a direct message");
+        return "command";
+    }
+    if (gateway.name === "link" && !ctx.selfLink) {
+        await reply(deps, ctx, "Self-linking is disabled on this channel.");
+        return "command";
+    }
+    if (gateway.where === "not-anyone-group" && ctx.group?.members === "anyone") {
+        await reply(deps, ctx, "/attach is not available in this group.");
+        return "command";
+    }
+    if (gateway.name !== "link" && gateway.name !== "pair") {
+        if (!(await hasBoundWriteAccess(deps, ctx))) {
+            await reply(deps, ctx, "You do not have write access to this conversation.");
+            return "command";
+        }
+    }
+    switch (gateway.name) {
+        case "new":
+            await newConversation(deps, ctx);
+            break;
+        case "stop":
+            await stopRun(deps, ctx);
+            break;
+        case "model":
+            await configureModel(deps, ctx, parsed.args);
+            break;
+        case "thinking":
+            await configureThinking(deps, ctx, parsed.args);
+            break;
+        case "compact":
+            await requireBinding(deps, ctx, async (conversationId) => {
+                await deps.host.conversations.compact(conversationId);
+                await reply(deps, ctx, "Compaction queued.");
+            });
+            break;
+        case "attach":
+            await attachConversation(deps, ctx, parsed.args);
+            break;
+        case "status":
+            await showStatus(deps, ctx);
+            break;
+        case "home":
+            if (ctx.user !== undefined) {
+                await deps.identities.setHome(ctx.user, ctx.channel, ctx.event.chat);
+                await reply(deps, ctx, "This DM is now your home chat on this channel.");
+            }
+            break;
+        case "link": {
+            const notice = await redeemLink({
+                identities: deps.identities,
+                linkCodes: deps.linkCodes,
+                log: deps.log,
+                now: deps.now,
+            }, ctx.channel, { ...ctx.event, text: `/link ${parsed.args}` });
+            await reply(deps, ctx, notice);
+            break;
+        }
+        case "pair": {
+            const record = ctx.user === undefined
+                ? undefined
+                : await deps.host.users.get(ctx.user);
+            const notice = await runPair({
+                host: deps.host,
+                identities: deps.identities,
+                pairing: deps.pairing,
+                channelOf: deps.channelOf,
+                log: deps.log,
+                now: deps.now,
+            }, parsed.args, {
+                user: ctx.user,
+                admin: record?.admin === true || record?.groupAdmin === true,
+            });
+            await reply(deps, ctx, notice);
+            break;
+        }
+        case "help": {
+            const menu = await chatCommandMenu(deps.host);
+            await reply(deps, ctx, menu.map((command) => `/${command.name} — ${command.description}`).join("\n"));
+            break;
+        }
+    }
+    return "command";
+}
+/** Map only expected user-input/op failures; all other errors remain engine failures. */
+function expectedCommandError(error, commandName) {
+    if (!(error instanceof Error))
+        return undefined;
+    if (error.name === "ConversationOpError") {
+        const body = error.body;
+        if (isRecord(body) && typeof body.error === "string") {
+            const field = typeof body.field === "string" ? ` ${body.field}` : "";
+            return `Could not run /${commandName}: ${body.error}${field}.`;
+        }
+    }
+    // The host bridge deliberately uses a plain Error for an unknown id.
+    if (commandName === "attach" && /^conversation .+ not found$/.test(error.message)) {
+        return error.message.endsWith(".") ? error.message : `${error.message}.`;
+    }
+    return undefined;
+}
+/** Parse `/name[@bot] args`; names outside the command grammar stay text. */
+function parseCommand(text) {
+    const match = text.match(/^\/([a-z][a-z0-9-]*)(?:@[^\s]+)?(?:\s+([\s\S]*))?$/);
+    if (match === null)
+        return undefined;
+    return { name: match[1] ?? "", args: match[2]?.trim() ?? "" };
+}
+/** Only catalog rows carrying an extension slug are chat-invokable. */
+async function extensionCommands(host) {
+    const reserved = new Set(GATEWAY_COMMANDS.map((command) => command.name));
+    return (await host.commands.list()).flatMap((command) => command.extension === undefined || reserved.has(command.name)
+        ? []
+        : [{ name: command.name, description: command.description, extension: command.extension }]);
+}
+/** The common bound-conversation write gate (link/pair are exempt). */
+async function hasBoundWriteAccess(deps, ctx) {
+    if (ctx.user === undefined || ctx.binding === undefined)
+        return false;
+    const meta = await deps.host.conversations.meta(ctx.binding.conversationId);
+    const access = await deps.host.access.accessOf({ user: ctx.user }, { owner: meta.owner, sharing: meta.sharing });
+    return access === "write";
+}
+/** Run one operation that requires an existing bound conversation. */
+async function requireBinding(deps, ctx, operation) {
+    if (ctx.binding === undefined) {
+        await reply(deps, ctx, "This chat is not bound to a conversation.");
+        return;
+    }
+    await operation(ctx.binding.conversationId);
+}
+/** `/new`: the same creation shape as first admission, then rebind. */
+async function newConversation(deps, ctx) {
+    const owner = ctx.group?.owner ?? ctx.user;
+    if (owner === undefined) {
+        await reply(deps, ctx, "run this as a named user");
+        return;
+    }
+    const conversationId = await deps.host.conversations.create({
+        owner,
+        source: "gateway",
+        name: ctx.event.chat.title ?? `${deps.channel.label} DM`,
+        ...(ctx.group?.members !== "anyone"
+            ? {}
+            : {
+                agent: {
+                    ...(ctx.group.tools === undefined ? {} : { tools: ctx.group.tools }),
+                    ...(ctx.group.extensions === undefined ? {} : { extensions: ctx.group.extensions }),
+                },
+            }),
+    });
+    await deps.bindings.bind(ctx.bindingKey, conversationId, ctx.event.chat);
+    await reply(deps, ctx, `Started conversation ${String(conversationId)}.`);
+}
+/** `/stop`: Task 5 owns the live abort's exact "Stopped." notice. */
+async function stopRun(deps, ctx) {
+    await requireBinding(deps, ctx, async (conversationId) => {
+        const latest = await latestView(deps.host, conversationId);
+        if (latest?.steer.busy !== true && (latest?.steer.queued ?? 0) === 0) {
+            await reply(deps, ctx, "Nothing is running.");
+            return;
+        }
+        await deps.host.conversations.abort(conversationId);
+        // An aborted preview never finalizes: release its watch/timers so
+        // Task 5's origin notice is the command's only reply.
+        deps.streams?.abandon(conversationId);
+    });
+}
+/** `/model`: no args lists the current and served refs; args configure. */
+async function configureModel(deps, ctx, args) {
+    await requireBinding(deps, ctx, async (conversationId) => {
+        if (args !== "") {
+            await deps.host.conversations.configure(conversationId, { model: args });
+            await reply(deps, ctx, `Model set to ${args}.`);
+            return;
+        }
+        const latest = await latestView(deps.host, conversationId);
+        const current = modelRef(latest) ?? "not configured";
+        const models = await deps.host.models.list();
+        await reply(deps, ctx, [`Current model: ${current}`, ...models.map((model) => model.id)].join("\n"));
+    });
+}
+/** `/thinking`: no args lists levels; an arg configures the next run. */
+async function configureThinking(deps, ctx, args) {
+    await requireBinding(deps, ctx, async (conversationId) => {
+        if (args !== "") {
+            if (!THINKING_LEVELS.includes(args)) {
+                await reply(deps, ctx, `usage: /thinking [${THINKING_LEVELS.join(" | ")}]`);
+                return;
+            }
+            await deps.host.conversations.configure(conversationId, {
+                thinking: args,
+            });
+            await reply(deps, ctx, `Thinking level set to ${args}.`);
+            return;
+        }
+        const latest = await latestView(deps.host, conversationId);
+        const current = thinkingLevel(latest) ?? "not configured";
+        await reply(deps, ctx, [`Current thinking level: ${current}`, ...THINKING_LEVELS].join("\n"));
+    });
+}
+/** `/attach`: authorize the target independently, then rebind. */
+async function attachConversation(deps, ctx, args) {
+    if (!/^[1-9][0-9]*$/.test(args) || ctx.user === undefined) {
+        await reply(deps, ctx, "usage: /attach <conversation-id>");
+        return;
+    }
+    const numericId = Number(args);
+    // Numeric conversion above 2^53 loses identity, and >=1e21 formats in
+    // exponential notation. Reject before any host lookup or ConversationId cast.
+    if (!Number.isSafeInteger(numericId)) {
+        await reply(deps, ctx, "Unknown conversation.");
+        return;
+    }
+    const conversationId = numericId;
+    const meta = await deps.host.conversations.meta(conversationId);
+    const access = await deps.host.access.accessOf({ user: ctx.user }, { owner: meta.owner, sharing: meta.sharing });
+    if (access !== "write") {
+        await reply(deps, ctx, "You do not have write access to that conversation.");
+        return;
+    }
+    await deps.bindings.bind(ctx.bindingKey, conversationId, ctx.event.chat);
+    await reply(deps, ctx, `Attached to conversation ${args}.`);
+}
+/** `/status`: name, resolved model, live queue state, and binding id. */
+async function showStatus(deps, ctx) {
+    await requireBinding(deps, ctx, async (conversationId) => {
+        const [meta, latest] = await Promise.all([
+            deps.host.conversations.meta(conversationId),
+            latestView(deps.host, conversationId),
+        ]);
+        const state = latest?.steer.busy === true
+            ? `busy, ${latest.steer.queued} queued`
+            : `idle, ${latest?.steer.queued ?? 0} queued`;
+        await reply(deps, ctx, [
+            `Conversation: ${meta.name ?? "unnamed"}`,
+            `Model: ${modelRef(latest) ?? "not configured"}`,
+            `State: ${state}`,
+            `Bound conversation: ${String(conversationId)}`,
+        ].join("\n"));
+    });
+}
+/** Read the newest frame and release the one-shot watch immediately. */
+async function latestView(host, conversationId) {
+    let latest;
+    const release = await host.conversations.watch(conversationId, (view) => {
+        latest = view;
+    });
+    await release();
+    return latest;
+}
+/** Structural read of the resolved agent document (wire docs are JSON). */
+function agentDoc(view) {
+    const doc = view?.docs["pi.agent"];
+    return isRecord(doc) ? doc : undefined;
+}
+function modelRef(view) {
+    const model = agentDoc(view)?.model;
+    if (!isRecord(model))
+        return undefined;
+    return typeof model.provider === "string" && typeof model.modelId === "string"
+        ? `${model.provider}/${model.modelId}`
+        : undefined;
+}
+function thinkingLevel(view) {
+    const level = agentDoc(view)?.thinkingLevel;
+    return typeof level === "string" ? level : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Command replies are best-effort transport notices, like pipeline notices. */
+async function reply(deps, ctx, text) {
+    try {
+        await deps.channel.send({ chat: ctx.event.chat, text });
+    }
+    catch (error) {
+        deps.log.error("chat command reply send failed", error);
+    }
+}

package/dist/commands/link.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 type { InboundEvent } from "@sigrun/sigrun/extension";
+import type { EngineLog } from "../log.js";
+import type { IdentityStore } from "../state/identities.js";
+import type { LinkCodes } from "../access/link-codes.js";
+import type { GatewayConfig } from "../config.js";
+/** 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 (the code stays live). */
+export declare 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 chat-side redeem dependencies (the engine wires them). */
+export interface LinkDeps {
+    readonly identities: IdentityStore;
+    readonly linkCodes: LinkCodes;
+    readonly log: EngineLog;
+    readonly now: () => number;
+}
+/**
+ * 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 declare function redeemLink(deps: LinkDeps, channel: string, event: InboundEvent): Promise<string>;
+/** The `/link <channel>` webui/TUI command's dependencies. */
+export interface LinkCommandDeps {
+    /** The live config read (channel enablement is per-read). */
+    readonly readConfig: () => Promise<GatewayConfig>;
+    readonly linkCodes: LinkCodes;
+    /** The channel ids the engine recorded at start (unknown-channel refusal). */
+    readonly knownChannels: () => readonly string[];
+    readonly now: () => number;
+}
+/** The command contribution shape (the loader validates name/run). */
+export interface LinkCommand {
+    readonly name: string;
+    readonly description: string;
+    readonly args: string;
+    run(ctx: {
+        readonly principal: {
+            readonly user: string | undefined;
+        };
+        readonly args: string;
+    }): Promise<{
+        readonly notice: string;
+    }>;
+}
+/** Build the `link` slash command over the engine's shared state. */
+export declare function createLinkCommand(deps: LinkCommandDeps): LinkCommand;