@nettee/beacon 0.3.6 → 0.4.1

package/README.md

@@ -514,7 +514,7 @@ pnpm bump-version patch
 ```
 
 For an in-repository pull request that changes production CLI inputs under
-`src/`, `package.json`, `pnpm-lock.yaml`, or `tsconfig.json` without changing
+`apps/`, `services/`, `packages/`, or workspace build configuration without changing
 the package version, CI automatically commits a patch bump to the PR branch.
 Test-only and documentation changes do not trigger a release. An explicit
 version change takes precedence over the automatic patch bump, and CI rejects
@@ -551,3 +551,18 @@ a package to exist before Trusted Publishing can be configured. After the
 The repository variable deliberately keeps publishing disabled during the
 bootstrap merge. Subsequent versions publish from GitHub Actions with OIDC and
 do not use a long-lived npm write token.
+
+## Workspace layout
+
+Beacon is a pnpm monorepo:
+
+- `apps/cli`: the published `@nettee/beacon` command-line package and its version.
+- `apps/web`: the React/Vite web application.
+- `services/daemon`: scheduling, triggers, Agent execution, storage, and HTTP endpoints.
+- `packages/shared`: browser-safe HTTP response contracts shared by daemon and web.
+
+Run `pnpm install`, `pnpm build`, `pnpm typecheck`, and `pnpm test` from the repository root. The workspace builds dependencies before consumers. Run the built CLI with `node apps/cli/dist/cli.js serve`; it defaults to `~/.beacon/config.yaml`. For web development, run `pnpm --filter @nettee/beacon-web dev` alongside the daemon; Vite proxies API and run-export requests to port 46183.
+
+The daemon and web are separate workspace packages, but the published CLI remains a single installable product. Its build assembles the daemon modules and web assets inside `apps/cli/dist`; external daemon runtime dependencies remain regular CLI dependencies and are checked for consistency during assembly. Internal packages are private and do not require separate registry releases. Run `pnpm build` before `npm pack ./apps/cli` or publishing from `apps/cli`. `pnpm test:package` checks an isolated installation.
+
+`pnpm bump-version minor` updates `apps/cli/package.json`. Package separation preserves existing runtime behavior: `serve` starts the daemon and serves web assets in one process, and manual triggers still execute locally.

package/dist/cli-app.d.ts

@@ -0,0 +1,31 @@
+export declare const defaultConfigPath: string;
+export type CliCommand = {
+    command: "serve";
+    config: string;
+} | {
+    command: "doctor";
+    config: string;
+} | {
+    command: "trigger";
+    config: string;
+    profile: string;
+} | {
+    command: "schedule-trigger";
+    config: string;
+    profile: string;
+    schedule: string;
+} | {
+    command: "version";
+} | {
+    command: "outcome-submit";
+};
+export declare function parseCli(args: string[]): CliCommand;
+export type CliDependencies = {
+    serve(config: string): Promise<void>;
+    doctor(config: string): Promise<void>;
+    trigger(config: string, profile: string, input: string): Promise<void>;
+    triggerSchedule(config: string, profile: string, schedule: string): Promise<void>;
+    submitOutcome(): Promise<void>;
+    version: string;
+};
+export declare function runCli(command: CliCommand, dependencies: CliDependencies): Promise<void>;

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -1,17 +1,20 @@
 #!/usr/bin/env node
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runBeacon, runDoctor, runManualTrigger, runScheduleTrigger, submitOutcomeFromCli, } from "./daemon/index.js";
 import { parseCli, runCli } from "./cli-app.js";
-import { runDoctor } from "./doctor.js";
-import { runManualTrigger } from "./manual-trigger.js";
-import { submitOutcomeFromCli } from "./outcome/submit.js";
-import { runScheduleTrigger } from "./schedule-trigger.js";
-import { runBeacon } from "./service.js";
 import { packageVersion } from "./version.js";
+const beaconCliPath = fileURLToPath(import.meta.url);
+const runtime = { beaconCliPath };
 async function main() {
     await runCli(parseCli(process.argv.slice(2)), {
-        serve: runBeacon,
+        serve: (config) => runBeacon(config, {
+            ...runtime,
+            uiDirectory: join(dirname(beaconCliPath), "web"),
+        }),
         doctor: runDoctor,
-        trigger: runManualTrigger,
-        triggerSchedule: runScheduleTrigger,
+        trigger: (config, profile, input) => runManualTrigger(config, profile, input, runtime),
+        triggerSchedule: (config, profile, schedule) => runScheduleTrigger(config, profile, schedule, runtime),
         submitOutcome: submitOutcomeFromCli,
         version: packageVersion,
     });

package/dist/daemon/config/channels.d.ts

@@ -0,0 +1,11 @@
+export declare const channelNamePattern: RegExp;
+export type Channel = {
+    name: string;
+    description: string;
+    chatId: string;
+};
+export type ChannelRegistry = ReadonlyMap<string, Channel>;
+export declare function defaultChannelsPath(homeDirectory?: string): string;
+export declare function emptyChannelRegistry(): ChannelRegistry;
+export declare function loadChannelRegistry(path: string): Promise<ChannelRegistry>;
+export declare function resolveChannelName(name: string, channels: ChannelRegistry, channelsPath: string): Channel;

package/dist/daemon/config/event-credentials.d.ts

@@ -0,0 +1,6 @@
+export type EventProducer = {
+    id: string;
+    token: string;
+    sources: string[];
+};
+export declare function loadEventCredentials(path: string): Promise<EventProducer[]>;

package/dist/daemon/config/global.d.ts

@@ -0,0 +1,40 @@
+export type GlobalConfig = {
+    path: string;
+    homeDirectory: string;
+    profilesDirectory: string;
+    secretsPath: string;
+    channelsPath: string;
+    runtimeEnvironmentPath: string;
+    pi: {
+        executable: string;
+        codingAgentDirectory: string;
+        sessionDirectory: string;
+    };
+    runs: {
+        maxConcurrent: number;
+        maxQueued: number;
+        timeoutSeconds: number;
+        terminateGraceSeconds: number;
+    };
+    scheduler: {
+        maxOccurrencesPerReconciliation: number;
+    };
+    events?: {
+        listen: string;
+        port: number;
+        maxBodyBytes: number;
+        maxPending: number;
+        credentialsPath: string;
+    };
+    dashboard: {
+        enabled: boolean;
+        listen: string;
+        port: number;
+    };
+};
+export declare const defaultDashboard: {
+    readonly enabled: true;
+    readonly listen: "0.0.0.0";
+    readonly port: 46183;
+};
+export declare function loadGlobalConfig(path: string): Promise<GlobalConfig>;

package/dist/daemon/config/profile.d.ts

@@ -0,0 +1,38 @@
+import { type EventListener } from "../events/cloudevent.js";
+import { type ChannelRegistry } from "./channels.js";
+export declare const profilePersonaFile = "persona.md";
+export declare const profileTaskFile = "task.md";
+export declare const workspaceProfileDirectoryName = ".beacon-profile";
+export type DeliveryDestination = {
+    chatId: string;
+    name?: string | undefined;
+    description?: string | undefined;
+};
+export type Profile = {
+    id: string;
+    directory: string;
+    persona: string;
+    task: string;
+    workspace: string;
+    runtime: "pi";
+    model: {
+        provider: string;
+        id: string;
+    };
+    admin?: DeliveryDestination | undefined;
+    listener?: EventListener | undefined;
+    schedules: Array<{
+        id: string;
+        cron: string;
+        timezone: string;
+        input: string;
+        notify?: DeliveryDestination | undefined;
+    }>;
+};
+export type LoadProfileOptions = {
+    channels?: ChannelRegistry;
+    channelsPath?: string;
+};
+export declare function workspaceProfileDirectory(workspace: string): string;
+export declare function loadProfile(profileId: string, profilesDirectory?: string, options?: LoadProfileOptions): Promise<Profile>;
+export declare function profileAdminChatId(profile: Profile): string;

package/dist/daemon/config/registry.d.ts

@@ -0,0 +1,3 @@
+import type { ChannelRegistry } from "./channels.js";
+import { type Profile } from "./profile.js";
+export declare function loadProfileRegistry(profilesDirectory: string, channels?: ChannelRegistry, channelsPath?: string): Promise<Profile[]>;

package/dist/daemon/config/runtime-environment.d.ts

@@ -0,0 +1,2 @@
+export declare function assertRuntimeEnvironmentKey(key: string): void;
+export declare function loadRuntimeEnvironment(path: string): Promise<NodeJS.ProcessEnv>;

package/dist/daemon/config/secrets.d.ts

@@ -0,0 +1,5 @@
+export type FeishuCredentials = {
+    appId: string;
+    appSecret: string;
+};
+export declare function loadFeishuCredentials(profileId: string, path?: string): Promise<FeishuCredentials>;

package/dist/daemon/config/yaml.d.ts

@@ -0,0 +1 @@
+export declare function parseStrictYaml(path: string): Promise<unknown>;

package/dist/daemon/dashboard/export.d.ts

@@ -0,0 +1,11 @@
+export type SessionExportRequest = {
+    executable: string;
+    sessionDirectory: string;
+    runId: string;
+    sessionPath: string;
+    /** Beacon `--system-prompt` text for this Run, used when JSONL has no system line. */
+    systemPrompt?: string | undefined;
+    timeoutMs?: number | undefined;
+};
+export declare function resolveSessionJsonl(sessionDirectory: string, runId: string, sessionPath: string): Promise<string>;
+export declare function exportSessionHtml(request: SessionExportRequest): Promise<string>;

package/dist/daemon/dashboard/profiles.d.ts

@@ -0,0 +1,5 @@
+import type { ProfileDetailView, ProfileListItem } from "@nettee/beacon-shared";
+export type { ProfileDetailView, ProfileListenerView, ProfileListItem, ProfileNotifyView, ProfileScheduleView, } from "@nettee/beacon-shared";
+export declare function isProfileId(value: string): boolean;
+export declare function listProfileViews(profilesDirectory: string): Promise<ProfileListItem[]>;
+export declare function getProfileDetailView(profilesDirectory: string, profileId: string): Promise<ProfileDetailView | null>;

package/dist/daemon/dashboard/records.d.ts

@@ -0,0 +1,25 @@
+import type { RunRow } from "@nettee/beacon-shared";
+import type { FeedbackRecord } from "../domain/types.js";
+export declare const runIdPattern: RegExp;
+export type RunSummary = {
+    profileId: string;
+    triggerKey: string;
+    acceptedAt: string;
+    kind: string;
+    scheduleId: string | undefined;
+    eventSource?: string | undefined;
+    eventType?: string | undefined;
+    hasNotifyTarget: boolean;
+    runId: string | undefined;
+    state: string | undefined;
+    failureCode: string | undefined;
+    deliveryState: string | undefined;
+    sessionPath: string | undefined;
+    hasSessionFile: boolean;
+    systemPrompt: string | undefined;
+    feedback: FeedbackRecord | undefined;
+};
+export declare function listRunSummaries(profilesDirectory: string): Promise<RunSummary[]>;
+export declare function kindLabel(row: Pick<RunSummary, "kind" | "scheduleId" | "eventSource" | "eventType">): string;
+export declare function toRunListItem(row: RunSummary): RunRow;
+export declare function findRunSummary(profilesDirectory: string, runId: string): Promise<RunSummary | undefined>;

package/dist/daemon/dashboard/server.d.ts

@@ -0,0 +1,15 @@
+export type DashboardOptions = {
+    listen: string;
+    port: number;
+    profilesDirectory: string;
+    sessionDirectory: string;
+    piExecutable: string;
+    exportTimeoutMs?: number | undefined;
+    uiDirectory?: string | undefined;
+};
+export type DashboardServer = {
+    port: number;
+    close(): Promise<void>;
+};
+export declare function defaultUiDirectory(): string;
+export declare function startDashboard(options: DashboardOptions): Promise<DashboardServer>;

package/dist/daemon/dashboard/session-prompt.d.ts

@@ -0,0 +1,4 @@
+/** Prefer a JSONL system message; otherwise the Beacon-owned `--system-prompt` text. */
+export declare function pickExportedSystemPrompt(jsonl: string, beaconOwned?: string | undefined): string | undefined;
+export declare function systemPromptFromJsonl(jsonl: string): string | undefined;
+export declare function fillExportedHtmlSystemPrompt(html: string, systemPrompt: string): string;

package/dist/daemon/dashboard/static.d.ts

@@ -0,0 +1,2 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare function sendStaticFile(_request: IncomingMessage, response: ServerResponse, root: string, urlPath: string): Promise<boolean>;

package/dist/daemon/doctor.d.ts

@@ -0,0 +1 @@
+export declare function runDoctor(configPath: string): Promise<void>;

package/dist/daemon/domain/types.d.ts

@@ -0,0 +1,137 @@
+import type { CloudEvent } from "../events/cloudevent.js";
+export type ReplyDeliveryTarget = {
+    kind: "reply";
+    messageId: string;
+};
+export type ChatDeliveryTarget = {
+    kind: "chat";
+    chatId: string;
+};
+export type LocalStdoutDeliveryTarget = {
+    kind: "local_stdout";
+};
+export type DeliveryTarget = ReplyDeliveryTarget | ChatDeliveryTarget | LocalStdoutDeliveryTarget;
+export type MessageSnapshot = {
+    messageId: string;
+    messageType: string;
+    senderType: string;
+    senderId?: string | undefined;
+    content: unknown;
+};
+export type FeishuMessageInput = {
+    kind: "feishu_message";
+    eventId: string;
+    chatType: "p2p" | "group";
+    quotedMessages: MessageSnapshot[];
+    currentMessage: MessageSnapshot;
+};
+export type ScheduleInput = {
+    kind: "schedule";
+    scheduleId: string;
+    scheduledFor: string;
+    text: string;
+};
+export type ManualInput = {
+    kind: "manual";
+    text: string;
+};
+export type EventInput = {
+    kind: "event";
+    event: CloudEvent;
+};
+export type TriggerInput = FeishuMessageInput | ScheduleInput | ManualInput | EventInput;
+export declare const failureCodes: readonly ["config_invalid", "secret_invalid", "gateway_terminal", "trigger_persist_failed", "trigger_normalization_failed", "schedule_state_invalid", "capacity_exceeded", "runtime_spawn_failed", "runtime_protocol_error", "runtime_timeout", "runtime_exit_failed", "outcome_missing", "outcome_invalid", "service_interrupted", "delivery_api_failed", "delivery_interrupted"];
+export type FailureCode = (typeof failureCodes)[number];
+export type RunState = "queued" | "starting" | "running" | "succeeded" | "failed";
+export type DeliveryState = "pending" | "delivering" | "delivered" | "failed";
+export type Failure = {
+    code: FailureCode;
+    summary: string;
+};
+export type TextReplyContent = {
+    kind: "text";
+    text: string;
+};
+export type NoReplyContent = {
+    kind: "no_reply";
+    reason: string;
+};
+export type CardContent = {
+    kind: "card";
+    title: string;
+    content: string;
+    buttons: Array<{
+        label: string;
+        url: string;
+    }>;
+};
+/** Text, silent, or a `reply_card` interactive message on the conversational channel. */
+export type ReplyContent = TextReplyContent | NoReplyContent | CardContent;
+export type FinalOutcomeContent = {
+    reply: ReplyContent;
+    notify?: CardContent | undefined;
+};
+export declare const feedbackPriorities: readonly ["high", "medium"];
+export type FeedbackPriority = (typeof feedbackPriorities)[number];
+export type FeedbackItem = {
+    priority: FeedbackPriority;
+    summary: string;
+};
+export type FeedbackContent = {
+    items: FeedbackItem[];
+};
+export type FeedbackRecord = {
+    items: FeedbackItem[];
+    submittedAt: string;
+};
+export type DeliveryContent = TextReplyContent | CardContent;
+export type RunRecord = {
+    runId: string;
+    /** Pi session ID. Absent only on records written before session persistence. */
+    sessionId?: string | undefined;
+    /** Dedicated directory containing this Run's Pi session JSONL file. */
+    sessionPath?: string | undefined;
+    state: RunState;
+    queuedAt: string;
+    startedAt?: string | undefined;
+    finishedAt?: string | undefined;
+    provider: string;
+    model: string;
+    workspace: string;
+    promptDigest: string;
+    /** Full `--system-prompt` text sent to Pi. Absent on records written before this field. */
+    systemPrompt?: string | undefined;
+    failure?: Failure | undefined;
+};
+export type FinalOutcomeRecord = {
+    origin: "agent" | "beacon_failure";
+    content: FinalOutcomeContent;
+    submittedAt: string;
+};
+export type DeliveryRecord = {
+    deliveryId: string;
+    target: DeliveryTarget;
+    state: DeliveryState;
+    startedAt?: string | undefined;
+    finishedAt?: string | undefined;
+    providerRequestId?: string | undefined;
+    failure?: Failure | undefined;
+};
+export type TriggerRecord = {
+    version: 1;
+    triggerKey: string;
+    triggerId: string;
+    profileId: string;
+    sourceKey: string[];
+    acceptedAt: string;
+    target: DeliveryTarget;
+    notifyTarget?: DeliveryTarget | undefined;
+    input?: TriggerInput | undefined;
+    ingress?: Record<string, unknown> | undefined;
+    run?: RunRecord | undefined;
+    finalOutcome?: FinalOutcomeRecord | undefined;
+    /** Present only when the Agent called `submit_feedback`. */
+    feedback?: FeedbackRecord | undefined;
+    delivery?: DeliveryRecord | undefined;
+    notifyDelivery?: DeliveryRecord | undefined;
+};

package/dist/daemon/events/cloudevent.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export declare const eventSourceSchema: z.ZodString;
+export type EventListener = {
+    sources: string[];
+    types: string[];
+    notify?: {
+        chatId: string;
+        name?: string | undefined;
+        description?: string | undefined;
+    } | undefined;
+};
+export declare const cloudEventSchema: z.ZodObject<{
+    specversion: z.ZodLiteral<"1.0">;
+    id: z.ZodString;
+    source: z.ZodString;
+    type: z.ZodString;
+    subject: z.ZodOptional<z.ZodString>;
+    time: z.ZodOptional<z.ZodISODateTime>;
+    dataschema: z.ZodOptional<z.ZodString>;
+    datacontenttype: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodJSONSchema>;
+}, z.core.$catchall<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber]>>>;
+export type CloudEvent = z.infer<typeof cloudEventSchema>;
+export declare function parseCloudEvent(input: unknown): CloudEvent;
+export declare function matchesListener(event: CloudEvent, listener: EventListener): boolean;

package/dist/daemon/events/pipeline.d.ts

@@ -0,0 +1,35 @@
+import type { EventProducer } from "../config/event-credentials.js";
+import type { Profile } from "../config/profile.js";
+import type { TriggerInput } from "../domain/types.js";
+import type { TriggerStore } from "../state/trigger-store.js";
+import { type CloudEvent } from "./cloudevent.js";
+import { type EventRecord, type EventStore } from "./store.js";
+export type EventContext = {
+    profile: Profile;
+    store: TriggerStore;
+    orchestrator: {
+        process(key: string, normalize: () => Promise<TriggerInput>): Promise<void>;
+    };
+};
+export declare class EventPipeline {
+    private readonly options;
+    private work;
+    private requested;
+    private stopped;
+    private failure;
+    constructor(options: {
+        store: EventStore;
+        contexts: EventContext[];
+        maxPending: number;
+        onFatal(error: Error): void;
+    });
+    accept(event: CloudEvent, producer: EventProducer): Promise<{
+        created: boolean;
+        record: EventRecord;
+    }>;
+    /** Call after Profile orchestrator recovery and after the HTTP listener binds. */
+    wake(): void;
+    private pump;
+    close(): Promise<void>;
+    drain(): Promise<void>;
+}

package/dist/daemon/events/server.d.ts

@@ -0,0 +1,15 @@
+import type { EventProducer } from "../config/event-credentials.js";
+import type { EventPipeline } from "./pipeline.js";
+import { type EventStore } from "./store.js";
+export declare function startEventServer(options: {
+    listen: string;
+    port: number;
+    maxBodyBytes: number;
+    producers: EventProducer[];
+    pipeline: EventPipeline;
+    store: EventStore;
+    onFatal(error: Error): void;
+}): Promise<{
+    port: number;
+    close(): Promise<void>;
+}>;

package/dist/daemon/events/store.d.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { type CloudEvent } from "./cloudevent.js";
+declare const recipientSchema: z.ZodObject<{
+    profileId: z.ZodString;
+    chatId: z.ZodString;
+    notifyChatId: z.ZodOptional<z.ZodString>;
+    triggerId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const recordSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    receiptId: z.ZodString;
+    producerId: z.ZodString;
+    acceptedAt: z.ZodString;
+    event: z.ZodObject<{
+        specversion: z.ZodLiteral<"1.0">;
+        id: z.ZodString;
+        source: z.ZodString;
+        type: z.ZodString;
+        subject: z.ZodOptional<z.ZodString>;
+        time: z.ZodOptional<z.ZodISODateTime>;
+        dataschema: z.ZodOptional<z.ZodString>;
+        datacontenttype: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodJSONSchema>;
+    }, z.core.$catchall<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber]>>>;
+    recipients: z.ZodArray<z.ZodObject<{
+        profileId: z.ZodString;
+        chatId: z.ZodString;
+        notifyChatId: z.ZodOptional<z.ZodString>;
+        triggerId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type EventRecipient = z.infer<typeof recipientSchema>;
+export type EventRecord = z.infer<typeof recordSchema>;
+export declare class EventIntakeError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare function eventStatus(record: EventRecord): "unmatched" | "pending" | "dispatched";
+/** Single service owner; serialized read/modify/write, atomic durable snapshots. */
+export declare class EventStore {
+    readonly directory: string;
+    private tail;
+    constructor(directory: string);
+    private exclusive;
+    private prepare;
+    private path;
+    private read;
+    private records;
+    private write;
+    accept(event: CloudEvent, producerId: string, recipients: EventRecipient[], maxPending: number): Promise<{
+        created: boolean;
+        record: EventRecord;
+    }>;
+    get(id: string): Promise<EventRecord | undefined>;
+    pending(): Promise<EventRecord[]>;
+    markDispatched(id: string, profileId: string, triggerId: string): Promise<void>;
+}
+export {};

package/dist/daemon/feishu/doctor.d.ts

@@ -0,0 +1,2 @@
+import type { FeishuCredentials } from "../config/secrets.js";
+export declare function runFeishuDoctor(credentials: FeishuCredentials): Promise<void>;

package/dist/daemon/feishu/final-outcome-card.d.ts

@@ -0,0 +1,20 @@
+import type { CardContent } from "../domain/types.js";
+type CardOutcome = CardContent;
+export type FeishuFinalOutcomeCard = {
+    config: {
+        wide_screen_mode: true;
+    };
+    header: {
+        template: "blue";
+        title: {
+            tag: "plain_text";
+            content: string;
+        };
+    };
+    elements: object[];
+};
+export declare function buildFeishuFinalOutcomeCard(outcome: CardOutcome, options?: {
+    generatedAt?: Date;
+    timeZone?: string;
+}): FeishuFinalOutcomeCard;
+export {};

package/dist/daemon/feishu/gateway.d.ts

@@ -0,0 +1,46 @@
+import type { FeishuCredentials } from "../config/secrets.js";
+import type { DeliveryContent } from "../domain/types.js";
+import type { DeliveryAdapter } from "../run/orchestrator.js";
+import type { FeishuMessageEvent } from "./intake.js";
+import type { FeishuMessageGateway } from "./message-gateway.js";
+import type { FetchedMessage } from "./trigger-input.js";
+type ApiResult = {
+    code?: number | undefined;
+    msg?: string | undefined;
+    request_id?: string | undefined;
+};
+type MessageSendResult = ApiResult & {
+    data?: {
+        message_id?: string | undefined;
+    } | undefined;
+};
+/** Prefer Feishu's outbound `message_id` so quote-replies can resume that Run's Pi session. */
+export declare function providerRequestIdFromMessageSend(result: MessageSendResult): {
+    providerRequestId?: string | undefined;
+};
+type ShutdownSignalSource = {
+    once(event: "SIGINT" | "SIGTERM", listener: () => void): unknown;
+    off(event: "SIGINT" | "SIGTERM", listener: () => void): unknown;
+};
+export declare function waitForShutdown(signals?: ShutdownSignalSource): Promise<void>;
+export declare function shouldAcceptFeishuMessage(chatType: string, senderType: string, messageId: string, processedMessageIds: ReadonlySet<string>): boolean;
+export declare function encodeFeishuFinalOutcome(outcome: DeliveryContent): {
+    msgType: "text" | "interactive";
+    content: string;
+};
+export declare class FeishuGateway implements FeishuMessageGateway {
+    private readonly credentials;
+    private readonly client;
+    constructor(credentials: FeishuCredentials);
+    checkReady(): Promise<void>;
+    run(handleEvent: (event: FeishuMessageEvent) => Promise<unknown>, shutdown?: Promise<void>): Promise<void>;
+    acknowledge(messageId: string): Promise<{
+        clear: () => Promise<void>;
+    }>;
+    fetchMessage(messageId: string): Promise<FetchedMessage>;
+    deliver(target: Parameters<DeliveryAdapter["deliver"]>[0], outcome: Parameters<DeliveryAdapter["deliver"]>[1]): Promise<{
+        providerRequestId?: string | undefined;
+    }>;
+}
+export declare function createFeishuGateway(credentials: FeishuCredentials): FeishuGateway;
+export {};