@bubblebrain-ai/bubble 0.0.10 → 0.0.12

package/dist/feishu/card/run-state.js

@@ -0,0 +1,217 @@
+/**
+ * Pure-function reducer: AgentEvent → RunState.
+ *
+ * Mutates `state` in place for performance (this runs on every streaming
+ * token). Always sets state.updatedAt. Caller is expected to immediately
+ * re-render through the (throttled) card renderer.
+ */
+const TOOL_ARGS_PREVIEW_LIMIT = 120;
+const TOOL_RESULT_PREVIEW_LIMIT = 800;
+const TEXT_BLOCK_MAX_CHARS = 12_000;
+const THINKING_BLOCK_MAX_CHARS = 4_000;
+export function reduceRunState(state, event) {
+    state.updatedAt = Date.now();
+    switch (event.type) {
+        case "turn_start":
+            // No state change — just signals a new LLM round trip.
+            return state;
+        case "text_delta": {
+            const last = state.blocks[state.blocks.length - 1];
+            if (last && last.kind === "text" && last.streaming) {
+                last.text = appendBounded(last.text, event.content, TEXT_BLOCK_MAX_CHARS);
+            }
+            else {
+                closeStreamingBlocks(state);
+                const block = {
+                    kind: "text",
+                    text: appendBounded("", event.content, TEXT_BLOCK_MAX_CHARS),
+                    streaming: true,
+                };
+                state.blocks.push(block);
+            }
+            return state;
+        }
+        case "reasoning_delta": {
+            const last = state.blocks[state.blocks.length - 1];
+            if (last && last.kind === "thinking" && last.streaming) {
+                last.text = appendBounded(last.text, event.content, THINKING_BLOCK_MAX_CHARS);
+            }
+            else {
+                closeStreamingBlocks(state);
+                const block = {
+                    kind: "thinking",
+                    text: appendBounded("", event.content, THINKING_BLOCK_MAX_CHARS),
+                    streaming: true,
+                };
+                state.blocks.push(block);
+            }
+            return state;
+        }
+        case "tool_call_start":
+        case "tool_call_delta":
+        case "tool_call_end":
+            // Args streaming is noisy; we wait for `tool_start` (parsed args) before
+            // creating the visible tool block.
+            return state;
+        case "tool_start": {
+            closeStreamingBlocks(state);
+            const block = {
+                kind: "tool",
+                id: event.id,
+                name: event.name,
+                argsPreview: formatArgsPreview(event.args),
+                status: "running",
+                startedAt: Date.now(),
+            };
+            state.blocks.push(block);
+            return state;
+        }
+        case "tool_update":
+            // Subagent updates carry rich child events; render as nested status
+            // tweak (status flips to "running" for queued→running). We keep it
+            // minimal in v1 — the parent tool block reflects high-level state.
+            return state;
+        case "tool_end": {
+            const block = findToolBlockById(state, event.id);
+            if (block) {
+                block.status = event.result.isError ? "err" : "ok";
+                block.resultPreview = truncateOneline(event.result.content, TOOL_RESULT_PREVIEW_LIMIT);
+                block.endedAt = Date.now();
+            }
+            return state;
+        }
+        case "turn_end": {
+            if (event.usage) {
+                state.usage = mergeUsage(state.usage, event.usage);
+            }
+            return state;
+        }
+        case "mode_changed":
+            state.mode = event.mode;
+            return state;
+        case "todos_updated":
+            // Todos render is deferred (would need a todos block kind). v1 ignores.
+            return state;
+        case "context_recovered":
+            // Internal recovery — silent.
+            return state;
+        case "agent_end":
+            closeStreamingBlocks(state);
+            if (state.status === "running") {
+                state.status = "completed";
+            }
+            return state;
+        default:
+            return state;
+    }
+}
+/** Mark `status="interrupted"` and close any streaming blocks. */
+export function markInterrupted(state) {
+    closeStreamingBlocks(state);
+    state.status = "interrupted";
+    state.updatedAt = Date.now();
+    return state;
+}
+/** Mark `status="error"`. */
+export function markError(state, error) {
+    closeStreamingBlocks(state);
+    state.status = "error";
+    const message = typeof error === "string" ? error : (error.message || String(error));
+    state.error = { message };
+    state.updatedAt = Date.now();
+    return state;
+}
+/** Mark `status="idle_timeout"`. */
+export function markIdleTimeout(state) {
+    closeStreamingBlocks(state);
+    if (state.status === "running") {
+        state.status = "idle_timeout";
+    }
+    state.updatedAt = Date.now();
+    return state;
+}
+/**
+ * Last-block-only check used by idle watchdog: if there's an in-flight tool,
+ * we don't count toward idle.
+ */
+export function hasInFlightTool(state) {
+    for (let i = state.blocks.length - 1; i >= 0; i--) {
+        const block = state.blocks[i];
+        if (block.kind === "tool" && block.status === "running")
+            return true;
+    }
+    return false;
+}
+function closeStreamingBlocks(state) {
+    for (const block of state.blocks) {
+        if (block.kind === "text" || block.kind === "thinking") {
+            block.streaming = false;
+        }
+    }
+}
+function findToolBlockById(state, id) {
+    for (let i = state.blocks.length - 1; i >= 0; i--) {
+        const block = state.blocks[i];
+        if (block.kind === "tool" && block.id === id)
+            return block;
+    }
+    return undefined;
+}
+function appendBounded(prev, delta, max) {
+    if (prev.length + delta.length <= max)
+        return prev + delta;
+    const next = prev + delta;
+    // Drop oldest characters; keep tail. Mark truncation only once.
+    const overflow = next.length - max;
+    return "…" + next.slice(overflow + 1);
+}
+function formatArgsPreview(args) {
+    // Pretty-print scalar fields inline; nested objects get JSON-stringified
+    // briefly. This is the user-facing one-liner under the tool name.
+    const parts = [];
+    for (const [key, value] of Object.entries(args)) {
+        let formatted;
+        if (typeof value === "string") {
+            formatted = value.length > 60 ? `"${value.slice(0, 57)}..."` : `"${value}"`;
+        }
+        else if (typeof value === "number" || typeof value === "boolean") {
+            formatted = String(value);
+        }
+        else if (value === null) {
+            formatted = "null";
+        }
+        else {
+            try {
+                const json = JSON.stringify(value);
+                formatted = json.length > 60 ? `${json.slice(0, 57)}...` : json;
+            }
+            catch {
+                formatted = "[unserializable]";
+            }
+        }
+        parts.push(`${key}=${formatted}`);
+        if (parts.join(", ").length > TOOL_ARGS_PREVIEW_LIMIT) {
+            parts[parts.length - 1] = parts[parts.length - 1].slice(0, TOOL_ARGS_PREVIEW_LIMIT - parts.slice(0, -1).join(", ").length) + "…";
+            break;
+        }
+    }
+    return parts.join(", ");
+}
+function truncateOneline(text, max) {
+    const trimmed = text.replace(/\s+/g, " ").trim();
+    if (trimmed.length <= max)
+        return trimmed;
+    return trimmed.slice(0, max - 1) + "…";
+}
+function mergeUsage(prev, next) {
+    if (!prev)
+        return { ...next };
+    return {
+        promptTokens: prev.promptTokens + (next.promptTokens ?? 0),
+        completionTokens: prev.completionTokens + (next.completionTokens ?? 0),
+        promptCacheHitTokens: (prev.promptCacheHitTokens ?? 0) + (next.promptCacheHitTokens ?? 0),
+        promptCacheMissTokens: (prev.promptCacheMissTokens ?? 0) + (next.promptCacheMissTokens ?? 0),
+        reasoningTokens: (prev.reasoningTokens ?? 0) + (next.reasoningTokens ?? 0),
+        totalTokens: (prev.totalTokens ?? 0) + (next.totalTokens ?? 0),
+    };
+}

package/dist/feishu/channel/channel.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Thin wrapper around `LarkChannel` from @larksuiteoapi/node-sdk.
+ *
+ * We don't add much behavior — just provide a stable, mockable surface for
+ * the rest of the Feishu host. Tests construct a `MockBubbleChannel` that
+ * implements the same interface without touching real network.
+ */
+import { type LarkChannel, type NormalizedMessage, type CardActionEvent, type RejectEvent, type SendResult, type SendOptions, type WSConnectionStatus } from "@larksuiteoapi/node-sdk";
+export type { NormalizedMessage, CardActionEvent };
+export interface BubbleChannelOptions {
+    appId: string;
+    appSecret: string;
+    /** Forwarded to LarkChannelOptions.outbound.streamThrottleMs. */
+    outputThrottleMs?: number;
+    /**
+     * If true (default), group messages require @bot mention before being
+     * forwarded. Note: this is enforced at the LarkChannel policy layer; the
+     * router applies the per-scope `requireMentionInGroup` setting on top.
+     */
+    requireMentionInGroup?: boolean;
+}
+export interface BubbleChannel {
+    /** Resolve once the WebSocket has handshaken at least once. */
+    connect(): Promise<void>;
+    /** Close cleanly. */
+    disconnect(): Promise<void>;
+    /** Connection-status snapshot, for /status / /doctor commands. */
+    getStatus(): WSConnectionStatus | undefined;
+    /** Send a one-off message (text, card, etc.) — see SDK SendInput. */
+    send(chatId: string, input: SendInput, opts?: SendOptions): Promise<SendResult>;
+    /** Patch an already-sent card. */
+    updateCard(messageId: string, card: object): Promise<void>;
+    /**
+     * Open a streaming card; producer is given a controller with `update()`.
+     * The SDK handles throttling and the 30KB element auto-rollover.
+     */
+    stream(chatId: string, input: StreamInput, opts?: SendOptions): Promise<SendResult>;
+    /** Event subscriptions. Returned function unsubscribes. */
+    onMessage(handler: (msg: NormalizedMessage) => void | Promise<void>): () => void;
+    onCardAction(handler: (evt: CardActionEvent) => void | Promise<void>): () => void;
+    onReject(handler: (evt: RejectEvent) => void): () => void;
+    onError(handler: (err: Error) => void): () => void;
+    onReconnecting(handler: () => void): () => void;
+    onReconnected(handler: () => void): () => void;
+    /** Fetch the chat's mode (cached by callers, not by us). */
+    getChatMode(chatId: string): Promise<"p2p" | "group" | "topic">;
+    /** Reveal the bot's own open_id once connected. Useful for self-mention checks. */
+    botOpenId(): string | undefined;
+}
+export type SendInput = Parameters<LarkChannel["send"]>[1];
+export type StreamInput = Parameters<LarkChannel["stream"]>[1];
+export declare function createBubbleChannel(opts: BubbleChannelOptions): BubbleChannel;

package/dist/feishu/channel/channel.js

@@ -0,0 +1,74 @@
+/**
+ * Thin wrapper around `LarkChannel` from @larksuiteoapi/node-sdk.
+ *
+ * We don't add much behavior — just provide a stable, mockable surface for
+ * the rest of the Feishu host. Tests construct a `MockBubbleChannel` that
+ * implements the same interface without touching real network.
+ */
+import { createLarkChannel, LoggerLevel, } from "@larksuiteoapi/node-sdk";
+export function createBubbleChannel(opts) {
+    const verbose = process.env.BUBBLE_FEISHU_DEBUG === "1";
+    const sdkOpts = {
+        appId: opts.appId,
+        appSecret: opts.appSecret,
+        transport: "websocket",
+        loggerLevel: verbose ? LoggerLevel.debug : LoggerLevel.warn,
+        includeRawEvent: verbose,
+        outbound: {
+            streamThrottleMs: opts.outputThrottleMs ?? 400,
+        },
+        policy: {
+            // Bubble enforces mention/whitelist itself in the router. Keep the
+            // SDK's policy layer permissive so we can give cleaner error
+            // feedback than a silent SDK-side reject.
+            dmMode: "open",
+            requireMention: false,
+            respondToMentionAll: false,
+        },
+    };
+    const inner = createLarkChannel(sdkOpts);
+    return {
+        async connect() {
+            await inner.connect();
+        },
+        async disconnect() {
+            await inner.disconnect();
+        },
+        getStatus() {
+            return inner.getConnectionStatus();
+        },
+        async send(chatId, input, opts) {
+            return inner.send(chatId, input, opts);
+        },
+        async updateCard(messageId, card) {
+            return inner.updateCard(messageId, card);
+        },
+        async stream(chatId, input, opts) {
+            return inner.stream(chatId, input, opts);
+        },
+        onMessage(handler) {
+            return inner.on("message", handler);
+        },
+        onCardAction(handler) {
+            return inner.on("cardAction", handler);
+        },
+        onReject(handler) {
+            return inner.on("reject", handler);
+        },
+        onError(handler) {
+            return inner.on("error", handler);
+        },
+        onReconnecting(handler) {
+            return inner.on("reconnecting", handler);
+        },
+        onReconnected(handler) {
+            return inner.on("reconnected", handler);
+        },
+        async getChatMode(chatId) {
+            return inner.getChatMode(chatId);
+        },
+        botOpenId() {
+            return inner.botIdentity?.openId;
+        },
+    };
+}

package/dist/feishu/config.d.ts

@@ -0,0 +1,24 @@
+/**
+ * FeishuConfig load / save. Failures surface as thrown errors with helpful
+ * remediation hints; callers (serve.ts) translate them into user-facing
+ * messages.
+ */
+import type { FeishuConfig } from "./types.js";
+export declare class FeishuConfigError extends Error {
+    readonly hint?: string | undefined;
+    constructor(message: string, hint?: string | undefined);
+}
+export declare function configExists(): boolean;
+export declare function loadConfig(): FeishuConfig;
+export declare function saveConfig(config: FeishuConfig): void;
+export declare function resolveAppSecret(config: FeishuConfig): string;
+export interface BootstrapInput {
+    appId: string;
+    appSecret: string;
+    ownerOpenId: string;
+}
+/**
+ * First-time setup: encrypt the secret, write keystore + config files.
+ * Used by the wizard after a successful registerApp() flow.
+ */
+export declare function bootstrapConfig(input: BootstrapInput): FeishuConfig;

package/dist/feishu/config.js

@@ -0,0 +1,97 @@
+/**
+ * FeishuConfig load / save. Failures surface as thrown errors with helpful
+ * remediation hints; callers (serve.ts) translate them into user-facing
+ * messages.
+ */
+import { existsSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { getConfigPath, getSecretsPath } from "./paths.js";
+import { validateFeishuConfig } from "./schema.js";
+import { DEFAULT_PREFERENCES, DEFAULT_GLOBAL_LIMITS } from "./types.js";
+import { decryptSecret, encryptWithSelfCheck, loadKeystoreFile, saveKeystoreFile } from "./secrets.js";
+export class FeishuConfigError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.hint = hint;
+        this.name = "FeishuConfigError";
+    }
+}
+export function configExists() {
+    return existsSync(getConfigPath());
+}
+export function loadConfig() {
+    const path = getConfigPath();
+    if (!existsSync(path)) {
+        throw new FeishuConfigError(`No Feishu config found at ${path}`, "Run `bubble serve --feishu --setup` to create one.");
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        throw new FeishuConfigError(`Failed to read config: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new FeishuConfigError(`Config is not valid JSON: ${err.message}`);
+    }
+    const result = validateFeishuConfig(parsed);
+    if (!result.ok || !result.value) {
+        throw new FeishuConfigError(`Config has invalid shape:\n  - ${result.errors.join("\n  - ")}`, `Edit ${path} or rerun --setup.`);
+    }
+    return result.value;
+}
+export function saveConfig(config) {
+    const path = getConfigPath();
+    writeFileSync(path, JSON.stringify(config, null, 2), { encoding: "utf8", mode: 0o600 });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // Best-effort.
+    }
+}
+export function resolveAppSecret(config) {
+    const ref = config.app.secretRef;
+    if (ref.source === "env") {
+        const value = process.env[ref.varName];
+        if (!value || !value.trim()) {
+            throw new FeishuConfigError(`Env var ${ref.varName} (referenced by config.app.secretRef) is empty or unset`, `Set it in your shell before running, e.g. \`export ${ref.varName}=...\``);
+        }
+        return value.trim();
+    }
+    if (ref.source === "keystore") {
+        try {
+            const record = loadKeystoreFile(getSecretsPath());
+            return decryptSecret(record);
+        }
+        catch (err) {
+            throw new FeishuConfigError(`Failed to load App Secret from keystore: ${err.message}`, "Rerun `bubble serve --feishu --setup` to regenerate.");
+        }
+    }
+    throw new FeishuConfigError(`Unknown secretRef.source: ${ref.source}`);
+}
+/**
+ * First-time setup: encrypt the secret, write keystore + config files.
+ * Used by the wizard after a successful registerApp() flow.
+ */
+export function bootstrapConfig(input) {
+    const { record, check } = encryptWithSelfCheck(input.appSecret);
+    saveKeystoreFile(getSecretsPath(), record);
+    const config = {
+        version: 1,
+        app: {
+            appId: input.appId,
+            ownerOpenId: input.ownerOpenId,
+            secretRef: { source: "keystore", name: "default" },
+            encryptCheck: check,
+        },
+        preferences: { ...DEFAULT_PREFERENCES },
+        globalLimits: { ...DEFAULT_GLOBAL_LIMITS },
+    };
+    saveConfig(config);
+    return config;
+}

package/dist/feishu/format.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Small formatting helpers shared across the Feishu host.
+ */
+import type { PermissionMode } from "../types.js";
+export declare function formatPermissionMode(mode: PermissionMode): string;
+export declare function isPermissionModeName(value: string): value is PermissionMode;

package/dist/feishu/format.js

@@ -0,0 +1,14 @@
+/**
+ * Small formatting helpers shared across the Feishu host.
+ */
+const MODE_LABELS = {
+    default: "default",
+    plan: "plan",
+    bypassPermissions: "bypass",
+};
+export function formatPermissionMode(mode) {
+    return MODE_LABELS[mode] ?? mode;
+}
+export function isPermissionModeName(value) {
+    return value === "default" || value === "plan" || value === "bypassPermissions";
+}

package/dist/feishu/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Public entry for the Feishu host. Most callers will only need `serveFeishu`.
+ */
+export { serveFeishu, type ServeFeishuOptions } from "./serve.js";

package/dist/feishu/index.js

@@ -0,0 +1,4 @@
+/**
+ * Public entry for the Feishu host. Most callers will only need `serveFeishu`.
+ */
+export { serveFeishu } from "./serve.js";

package/dist/feishu/logger.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Minimal JSONL logger for the Feishu host.
+ *
+ * Writes one line per event to `~/.bubble/feishu/logs/YYYY-MM-DD.log`.
+ * Auto-rotates by date; old files (>7d) are deleted at startup.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface LogFields {
+    phase?: string;
+    scope?: string;
+    chatId?: string;
+    userId?: string;
+    messageId?: string;
+    error?: {
+        message: string;
+        name?: string;
+        stack?: string;
+    };
+    [key: string]: unknown;
+}
+export declare class FeishuLogger {
+    private currentDate;
+    private currentPath;
+    log(level: LogLevel, msg: string, fields?: LogFields): void;
+    debug(msg: string, fields?: LogFields): void;
+    info(msg: string, fields?: LogFields): void;
+    warn(msg: string, fields?: LogFields): void;
+    error(msg: string, fields?: LogFields): void;
+    /** Delete log files older than `maxAgeDays`. */
+    pruneOldLogs(maxAgeDays?: number): void;
+}

package/dist/feishu/logger.js

@@ -0,0 +1,62 @@
+/**
+ * Minimal JSONL logger for the Feishu host.
+ *
+ * Writes one line per event to `~/.bubble/feishu/logs/YYYY-MM-DD.log`.
+ * Auto-rotates by date; old files (>7d) are deleted at startup.
+ */
+import { appendFileSync, readdirSync, unlinkSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { getLogsDir } from "./paths.js";
+export class FeishuLogger {
+    currentDate = "";
+    currentPath = "";
+    log(level, msg, fields = {}) {
+        const ts = new Date();
+        const dateKey = ts.toISOString().slice(0, 10);
+        if (dateKey !== this.currentDate) {
+            this.currentDate = dateKey;
+            this.currentPath = join(getLogsDir(), `${dateKey}.log`);
+        }
+        const line = JSON.stringify({
+            ts: ts.toISOString(),
+            level,
+            msg,
+            ...fields,
+        });
+        try {
+            appendFileSync(this.currentPath, line + "\n");
+        }
+        catch {
+            // Logging failures must not crash the process.
+        }
+    }
+    debug(msg, fields) { this.log("debug", msg, fields); }
+    info(msg, fields) { this.log("info", msg, fields); }
+    warn(msg, fields) { this.log("warn", msg, fields); }
+    error(msg, fields) { this.log("error", msg, fields); }
+    /** Delete log files older than `maxAgeDays`. */
+    pruneOldLogs(maxAgeDays = 7) {
+        const cutoffMs = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+        const dir = getLogsDir();
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            if (!name.endsWith(".log"))
+                continue;
+            const path = join(dir, name);
+            try {
+                const stat = statSync(path);
+                if (stat.mtimeMs < cutoffMs)
+                    unlinkSync(path);
+            }
+            catch {
+                // skip
+            }
+        }
+    }
+}

package/dist/feishu/paths.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Path helpers for the Feishu host. All state lives under
+ * `~/.bubble/feishu/` (or the dev/test variants, via getBubbleHome()).
+ */
+export declare function getFeishuHome(): string;
+export declare function getConfigPath(): string;
+export declare function getSecretsPath(): string;
+export declare function getScopesPath(): string;
+export declare function getSessionsPath(): string;
+export declare function getProcessRegistryPath(): string;
+export declare function getLogsDir(): string;
+export declare function getMediaDir(chatId: string): string;

package/dist/feishu/paths.js

@@ -0,0 +1,38 @@
+/**
+ * Path helpers for the Feishu host. All state lives under
+ * `~/.bubble/feishu/` (or the dev/test variants, via getBubbleHome()).
+ */
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { getBubbleHome } from "../bubble-home.js";
+export function getFeishuHome() {
+    const dir = join(getBubbleHome(), "feishu");
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function getConfigPath() {
+    return join(getFeishuHome(), "config.json");
+}
+export function getSecretsPath() {
+    return join(getFeishuHome(), "secrets.enc");
+}
+export function getScopesPath() {
+    return join(getFeishuHome(), "scopes.json");
+}
+export function getSessionsPath() {
+    return join(getFeishuHome(), "sessions.json");
+}
+export function getProcessRegistryPath() {
+    return join(getFeishuHome(), "processes.json");
+}
+export function getLogsDir() {
+    const dir = join(getFeishuHome(), "logs");
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function getMediaDir(chatId) {
+    const safe = chatId.replace(/[^A-Za-z0-9_-]/g, "_");
+    const dir = join(getFeishuHome(), "media", safe);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}

package/dist/feishu/process-registry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Detect concurrent `bubble serve --feishu` instances for the same App ID.
+ *
+ * Two processes against the same App ID will fight over the long
+ * connection and double-process messages. We record the running PID + appId
+ * in `~/.bubble/feishu/processes.json` at startup and remove it at exit.
+ *
+ * On startup we check the file; any entry whose pid is still alive AND
+ * whose appId matches is a conflict.
+ */
+import type { ProcessRegistryEntry } from "./types.js";
+export interface ConflictInfo {
+    entry: ProcessRegistryEntry;
+}
+export declare class ProcessRegistry {
+    private file;
+    private path;
+    constructor();
+    /** Return all entries whose pid is alive AND whose appId matches. */
+    findConflicts(appId: string): ConflictInfo[];
+    /** Kill any conflicting entry's process (SIGTERM). Returns count killed. */
+    killConflicts(appId: string): number;
+    /** Remove dead entries from disk. */
+    gc(): void;
+    register(entry: ProcessRegistryEntry): void;
+    deregister(pid: number): void;
+    private read;
+    private flush;
+}