@elizaos/agent 0.25.9 → 2.0.0-alpha.83

package/packages/agent/src/services/sandbox-manager.d.ts

@@ -0,0 +1,104 @@
+/** Sandbox container lifecycle: create, exec, health check, teardown. */
+import { type SandboxEngineType } from "./sandbox-engine";
+export type SandboxMode = "off" | "light" | "standard" | "max";
+export type SandboxState = "uninitialized" | "initializing" | "ready" | "degraded" | "stopping" | "stopped" | "recovering";
+export interface SandboxManagerConfig {
+    /** Sandbox mode. */
+    mode: SandboxMode;
+    /** Docker image for sandbox containers. */
+    image?: string;
+    /** Container name prefix. */
+    containerPrefix?: string;
+    /** Container workdir mount path. */
+    workdir?: string;
+    /** Run rootfs read-only. */
+    readOnlyRoot?: boolean;
+    /** Container network mode. */
+    network?: string;
+    /** Container user (uid:gid). */
+    user?: string;
+    /** Drop Linux capabilities. */
+    capDrop?: string[];
+    /** Environment variables for sandbox. */
+    env?: Record<string, string>;
+    /** Container memory limit. */
+    memory?: string;
+    /** Container CPU limit. */
+    cpus?: number;
+    /** PIDs limit. */
+    pidsLimit?: number;
+    /** Root directory for sandbox workspaces. */
+    workspaceRoot?: string;
+    /** Additional bind mounts. */
+    binds?: string[];
+    /** DNS servers. */
+    dns?: string[];
+    /** Container engine type: "docker", "apple-container", or "auto" (default). */
+    engineType?: SandboxEngineType;
+    /** Browser sandbox settings. */
+    browser?: {
+        enabled?: boolean;
+        image?: string;
+        cdpPort?: number;
+        vncPort?: number;
+        noVncPort?: number;
+        headless?: boolean;
+        enableNoVnc?: boolean;
+        autoStart?: boolean;
+        autoStartTimeoutMs?: number;
+    };
+}
+export interface SandboxExecOptions {
+    command: string;
+    workdir?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    stdin?: string;
+}
+export interface SandboxExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+    executedInSandbox: boolean;
+}
+export interface SandboxEvent {
+    timestamp: number;
+    type: "state_change" | "exec" | "exec_denied" | "container_start" | "container_stop" | "health_check" | "error";
+    detail: string;
+    metadata?: Record<string, string | number | boolean>;
+}
+export declare class SandboxManager {
+    private state;
+    private config;
+    private engine;
+    private containerId;
+    private browserContainerId;
+    private eventLog;
+    constructor(config: SandboxManagerConfig);
+    getState(): SandboxState;
+    getMode(): SandboxMode;
+    isReady(): boolean;
+    private getMainContainerConfig;
+    private createMainContainer;
+    private cleanupContainer;
+    private setState;
+    start(): Promise<void>;
+    recover(): Promise<void>;
+    stop(): Promise<void>;
+    exec(options: SandboxExecOptions): Promise<SandboxExecResult>;
+    getBrowserCdpEndpoint(): string | null;
+    getBrowserWsEndpoint(): string | null;
+    getBrowserNoVncEndpoint(): string | null;
+    private createBrowserContainer;
+    private healthCheck;
+    private emitEvent;
+    getEventLog(): SandboxEvent[];
+    getStatus(): {
+        state: SandboxState;
+        mode: SandboxMode;
+        containerId: string | null;
+        browserContainerId: string | null;
+    };
+}
+//# sourceMappingURL=sandbox-manager.d.ts.map

package/packages/agent/src/services/sandbox-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-manager.d.ts","sourceRoot":"","sources":["../../../../../src/services/sandbox-manager.ts"],"names":[],"mappings":"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"}

package/packages/agent/src/services/sandbox-manager.js

@@ -0,0 +1,353 @@
+/** Sandbox container lifecycle: create, exec, health check, teardown. */
+import { mkdirSync } from "node:fs";
+import os from "node:os";
+import { join } from "node:path";
+import { createEngine, detectBestEngine, } from "./sandbox-engine";
+// ── Implementation ───────────────────────────────────────────────────────────
+export class SandboxManager {
+    state = "uninitialized";
+    config;
+    engine;
+    containerId = null;
+    browserContainerId = null;
+    eventLog = [];
+    constructor(config) {
+        this.config = {
+            image: "eliza-sandbox:bookworm-slim",
+            containerPrefix: "eliza-sandbox",
+            workdir: "/workspace",
+            network: "none",
+            user: "1000:1000",
+            capDrop: ["ALL"],
+            memory: "512m",
+            cpus: 1,
+            pidsLimit: 256,
+            ...config,
+        };
+        this.engine = config.engineType
+            ? createEngine(config.engineType)
+            : detectBestEngine();
+    }
+    getState() {
+        return this.state;
+    }
+    getMode() {
+        return this.config.mode;
+    }
+    isReady() {
+        return this.state === "ready";
+    }
+    getMainContainerConfig() {
+        const image = this.config.image ?? "eliza-sandbox:bookworm-slim";
+        const containerPrefix = this.config.containerPrefix ?? "eliza-sandbox";
+        const workdir = this.config.workdir ?? "/workspace";
+        const network = this.config.network ?? "none";
+        const user = this.config.user ?? "1000:1000";
+        const wsRoot = this.config.workspaceRoot ??
+            join(process.env.HOME ?? process.env.USERPROFILE ?? os.tmpdir(), ".eliza", "sandbox-workspace");
+        mkdirSync(wsRoot, { recursive: true });
+        return { image, containerPrefix, workdir, network, user, wsRoot };
+    }
+    async createMainContainer() {
+        const config = this.getMainContainerConfig();
+        return this.engine.runContainer({
+            image: config.image,
+            name: `${config.containerPrefix}-${Date.now()}`,
+            detach: true,
+            mounts: [
+                { host: config.wsRoot, container: config.workdir, readonly: false },
+            ],
+            env: this.config.env ?? {},
+            network: config.network,
+            user: config.user,
+            capDrop: this.config.capDrop ?? [],
+            memory: this.config.memory,
+            cpus: this.config.cpus,
+            pidsLimit: this.config.pidsLimit,
+            readOnlyRoot: this.config.readOnlyRoot,
+            dns: this.config.dns,
+        });
+    }
+    async cleanupContainer(containerId) {
+        if (!containerId)
+            return;
+        await this.engine.stopContainer(containerId);
+        await this.engine.removeContainer(containerId);
+    }
+    setState(newState) {
+        const oldState = this.state;
+        this.state = newState;
+        this.emitEvent({
+            timestamp: Date.now(),
+            type: "state_change",
+            detail: `${oldState} → ${newState}`,
+        });
+    }
+    async start() {
+        if (this.config.mode === "off") {
+            this.setState("stopped");
+            return;
+        }
+        if (this.config.mode === "light") {
+            // Light mode: no container, just tokenization + fetch proxy
+            this.setState("ready");
+            return;
+        }
+        // Standard / Max: create container
+        this.setState("initializing");
+        try {
+            const config = this.getMainContainerConfig();
+            if (!this.engine.isAvailable()) {
+                throw new Error(`Container engine "${this.engine.engineType}" is not available. Install Docker or Apple Container.`);
+            }
+            if (!this.engine.imageExists(config.image)) {
+                try {
+                    await this.engine.pullImage(config.image);
+                }
+                catch {
+                    throw new Error(`Sandbox image "${config.image}" not found. Build with: scripts/sandbox-setup.sh`);
+                }
+            }
+            // Cleanup orphans from previous runs
+            const orphans = this.engine.listContainers(config.containerPrefix);
+            for (const id of orphans) {
+                await this.engine.stopContainer(id);
+                await this.engine.removeContainer(id);
+            }
+            this.containerId = await this.createMainContainer();
+            this.emitEvent({
+                timestamp: Date.now(),
+                type: "container_start",
+                detail: `Container started: ${this.containerId}`,
+            });
+            // Start browser container if configured
+            if (this.config.browser?.enabled && this.config.browser?.autoStart) {
+                try {
+                    this.browserContainerId = await this.createBrowserContainer();
+                }
+                catch (err) {
+                    this.emitEvent({
+                        timestamp: Date.now(),
+                        type: "error",
+                        detail: `Browser container start failed: ${err instanceof Error ? err.message : String(err)}`,
+                    });
+                    // Non-fatal: sandbox can work without browser
+                }
+            }
+            // Health check
+            const healthy = await this.healthCheck();
+            if (healthy) {
+                this.setState("ready");
+            }
+            else {
+                this.setState("degraded");
+            }
+        }
+        catch (err) {
+            this.emitEvent({
+                timestamp: Date.now(),
+                type: "error",
+                detail: `Sandbox start failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+            this.setState("degraded");
+            throw err;
+        }
+    }
+    async recover() {
+        if (this.state !== "degraded") {
+            return; // Only recover from degraded
+        }
+        this.setState("recovering");
+        this.emitEvent({
+            timestamp: Date.now(),
+            type: "state_change",
+            detail: "Attempting recovery from degraded state",
+        });
+        try {
+            const config = this.getMainContainerConfig();
+            await this.cleanupContainer(this.containerId);
+            await this.cleanupContainer(this.browserContainerId);
+            this.containerId = null;
+            this.browserContainerId = null;
+            const orphans = this.engine.listContainers(config.containerPrefix);
+            for (const id of orphans) {
+                await this.engine.stopContainer(id);
+                await this.engine.removeContainer(id);
+            }
+            this.containerId = await this.createMainContainer();
+            const healthy = await this.healthCheck();
+            if (healthy) {
+                this.setState("ready");
+            }
+            else {
+                this.setState("degraded");
+            }
+        }
+        catch (err) {
+            this.emitEvent({
+                timestamp: Date.now(),
+                type: "error",
+                detail: `Recovery failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+            this.setState("degraded");
+        }
+    }
+    async stop() {
+        this.setState("stopping");
+        try {
+            await this.cleanupContainer(this.browserContainerId);
+            await this.cleanupContainer(this.containerId);
+            this.browserContainerId = null;
+            this.containerId = null;
+        }
+        catch (err) {
+            this.emitEvent({
+                timestamp: Date.now(),
+                type: "error",
+                detail: `Sandbox stop error: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        this.setState("stopped");
+    }
+    async exec(options) {
+        const start = Date.now();
+        if (this.config.mode === "off" || this.config.mode === "light") {
+            // In off/light mode, refuse sandbox exec — caller must use local
+            return {
+                exitCode: 1,
+                stdout: "",
+                stderr: "Sandbox exec not available in current mode",
+                durationMs: Date.now() - start,
+                executedInSandbox: false,
+            };
+        }
+        if (!this.containerId || this.state !== "ready") {
+            this.emitEvent({
+                timestamp: Date.now(),
+                type: "exec_denied",
+                detail: `Sandbox not ready (state=${this.state})`,
+            });
+            return {
+                exitCode: 1,
+                stdout: "",
+                stderr: `Sandbox not ready (state=${this.state})`,
+                durationMs: Date.now() - start,
+                executedInSandbox: false,
+            };
+        }
+        this.emitEvent({
+            timestamp: Date.now(),
+            type: "exec",
+            detail: options.command.substring(0, 200),
+            metadata: {
+                workdir: options.workdir ?? this.config.workdir ?? "/workspace",
+            },
+        });
+        try {
+            const result = await this.engine.execInContainer({
+                containerId: this.containerId,
+                command: options.command,
+                workdir: options.workdir,
+                env: options.env,
+                timeoutMs: options.timeoutMs,
+                stdin: options.stdin,
+            });
+            return {
+                ...result,
+                executedInSandbox: true,
+            };
+        }
+        catch (err) {
+            return {
+                exitCode: 1,
+                stdout: "",
+                stderr: `Exec error: ${err instanceof Error ? err.message : String(err)}`,
+                durationMs: Date.now() - start,
+                executedInSandbox: false,
+            };
+        }
+    }
+    getBrowserCdpEndpoint() {
+        if (!this.browserContainerId)
+            return null;
+        const port = this.config.browser?.cdpPort ?? 9222;
+        return `http://localhost:${port}`;
+    }
+    getBrowserWsEndpoint() {
+        if (!this.browserContainerId)
+            return null;
+        const port = this.config.browser?.cdpPort ?? 9222;
+        return `ws://localhost:${port}`;
+    }
+    getBrowserNoVncEndpoint() {
+        if (!this.browserContainerId)
+            return null;
+        const noVncEnabled = this.config.browser?.enableNoVnc ?? false;
+        const headless = this.config.browser?.headless ?? false;
+        if (!noVncEnabled || headless)
+            return null;
+        const port = this.config.browser?.noVncPort ?? 6080;
+        return `http://localhost:${port}/vnc.html?autoconnect=true&resize=scale&view_only=true`;
+    }
+    async createBrowserContainer() {
+        const name = `${this.config.containerPrefix}-browser-${Date.now()}`;
+        const cdpPort = this.config.browser?.cdpPort ?? 9222;
+        const vncPort = this.config.browser?.vncPort ?? 5900;
+        const noVncPort = this.config.browser?.noVncPort ?? 6080;
+        const enableNoVnc = this.config.browser?.enableNoVnc ?? false;
+        const headless = this.config.browser?.headless ?? false;
+        const image = this.config.browser?.image ?? "eliza-sandbox-browser:bookworm-slim";
+        return this.engine.runContainer({
+            image,
+            name,
+            detach: true,
+            mounts: [],
+            env: {
+                ELIZA_BROWSER_CDP_PORT: String(cdpPort),
+                ELIZA_BROWSER_VNC_PORT: String(vncPort),
+                ELIZA_BROWSER_NOVNC_PORT: String(noVncPort),
+                ELIZA_BROWSER_ENABLE_NOVNC: enableNoVnc ? "1" : "0",
+                ELIZA_BROWSER_HEADLESS: headless ? "1" : "0",
+            },
+            network: "bridge",
+            user: "1000:1000",
+            capDrop: [],
+            ports: [
+                { host: cdpPort, container: cdpPort },
+                { host: vncPort, container: vncPort },
+                ...(enableNoVnc && !headless
+                    ? [{ host: noVncPort, container: noVncPort }]
+                    : []),
+            ],
+        });
+    }
+    async healthCheck() {
+        if (!this.containerId)
+            return false;
+        const healthy = await this.engine.healthCheck(this.containerId);
+        this.emitEvent({
+            timestamp: Date.now(),
+            type: "health_check",
+            detail: healthy ? "healthy" : "unhealthy",
+        });
+        return healthy;
+    }
+    emitEvent(event) {
+        this.eventLog.push(event);
+        // Keep bounded
+        if (this.eventLog.length > 1000) {
+            this.eventLog = this.eventLog.slice(-500);
+        }
+    }
+    getEventLog() {
+        return [...this.eventLog];
+    }
+    getStatus() {
+        return {
+            state: this.state,
+            mode: this.config.mode,
+            containerId: this.containerId,
+            browserContainerId: this.browserContainerId,
+        };
+    }
+}

package/packages/agent/src/services/self-updater.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Detects the installation method and runs the appropriate upgrade command.
+ * Falls back to npm if detection is ambiguous.
+ */
+import type { ReleaseChannel } from "../config/types.eliza";
+export type InstallMethod = "npm-global" | "bun-global" | "homebrew" | "snap" | "apt" | "flatpak" | "local-dev" | "unknown";
+export interface UpdateResult {
+    success: boolean;
+    method: InstallMethod;
+    command: string;
+    previousVersion: string;
+    newVersion: string | null;
+    error: string | null;
+}
+export declare function detectInstallMethod(): InstallMethod;
+export declare function buildUpdateCommand(method: InstallMethod, channel: ReleaseChannel): {
+    command: string;
+    args: string[];
+} | null;
+export declare function performUpdate(currentVersion: string, channel: ReleaseChannel, method?: InstallMethod): Promise<UpdateResult>;
+//# sourceMappingURL=self-updater.d.ts.map

package/packages/agent/src/services/self-updater.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-updater.d.ts","sourceRoot":"","sources":["../../../../../src/services/self-updater.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAK5D,MAAM,MAAM,aAAa,GACrB,YAAY,GACZ,YAAY,GACZ,UAAU,GACV,MAAM,GACN,KAAK,GACL,SAAS,GACT,WAAW,GACX,SAAS,CAAC;AAEd,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AA8BD,wBAAgB,mBAAmB,IAAI,aAAa,CAyBnD;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,cAAc,GACtB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAkC5C;AA6CD,wBAAsB,aAAa,CACjC,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,YAAY,CAAC,CAsCvB"}

package/packages/agent/src/services/self-updater.js

@@ -0,0 +1,162 @@
+/**
+ * Detects the installation method and runs the appropriate upgrade command.
+ * Falls back to npm if detection is ambiguous.
+ */
+import { execSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CHANNEL_DIST_TAGS } from "./update-checker";
+const NPM_PACKAGE_NAME = "elizaos";
+function whichSync(binary) {
+    try {
+        return execSync(`which ${binary}`, {
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5_000,
+        })
+            .toString()
+            .trim();
+    }
+    catch {
+        return null;
+    }
+}
+function isLocalDev() {
+    try {
+        const rootPkg = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json");
+        const content = JSON.parse(fs.readFileSync(rootPkg, "utf-8"));
+        return content.devDependencies !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+export function detectInstallMethod() {
+    const elizaBin = whichSync("eliza");
+    if (!elizaBin) {
+        return isLocalDev() ? "local-dev" : "unknown";
+    }
+    let resolved;
+    try {
+        resolved = fs.realpathSync(elizaBin);
+    }
+    catch {
+        resolved = elizaBin;
+    }
+    if (resolved.includes("/Cellar/") || resolved.includes("/homebrew/"))
+        return "homebrew";
+    if (resolved.includes("/snap/"))
+        return "snap";
+    if (resolved.includes("/flatpak/") || resolved.includes("ai.eliza.Eliza"))
+        return "flatpak";
+    if (resolved.startsWith("/usr/") && !resolved.includes("node_modules"))
+        return "apt";
+    if (resolved.includes("/.bun/"))
+        return "bun-global";
+    if (resolved.includes("node_modules"))
+        return "npm-global";
+    return "unknown";
+}
+export function buildUpdateCommand(method, channel) {
+    const spec = `${NPM_PACKAGE_NAME}@${CHANNEL_DIST_TAGS[channel]}`;
+    switch (method) {
+        case "npm-global":
+            return { command: "npm", args: ["install", "-g", spec] };
+        case "bun-global":
+            return { command: "bun", args: ["install", "-g", spec] };
+        case "homebrew":
+            return { command: "brew", args: ["upgrade", "eliza"] };
+        case "snap": {
+            // nightly → edge (snap doesn't have a "nightly" channel)
+            const snapCh = channel === "nightly" ? "edge" : channel === "beta" ? "beta" : "stable";
+            return {
+                command: "sudo",
+                args: ["snap", "refresh", "eliza", `--channel=${snapCh}`],
+            };
+        }
+        case "apt":
+            return {
+                command: "sh",
+                args: [
+                    "-c",
+                    "sudo apt-get update && sudo apt-get install --only-upgrade -y eliza",
+                ],
+            };
+        case "flatpak":
+            return { command: "flatpak", args: ["update", "ai.eliza.Eliza"] };
+        case "local-dev":
+            return null;
+        case "unknown":
+            return { command: "npm", args: ["install", "-g", spec] };
+    }
+}
+function runCommand(command, args) {
+    return new Promise((resolve) => {
+        const child = spawn(command, args, {
+            stdio: ["inherit", "inherit", "pipe"],
+            // shell:true removed — all update commands are safe to run directly.
+            // The apt case uses sh -c explicitly, so no shell wrapper is needed.
+        });
+        let stderr = "";
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString();
+            process.stderr.write(chunk);
+        });
+        child.on("error", (err) => {
+            resolve({ exitCode: 1, stderr: err.message });
+        });
+        child.on("close", (code) => {
+            resolve({ exitCode: code ?? 1, stderr });
+        });
+    });
+}
+function readPostUpdateVersion() {
+    try {
+        const output = execSync("eliza --version", {
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 10_000,
+        })
+            .toString()
+            .trim();
+        // Version output may include a prefix like "eliza/2.0.0"
+        const match = output.match(/(\d+\.\d+\.\d+(?:-[\w.]+)?)/);
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function performUpdate(currentVersion, channel, method) {
+    method ??= detectInstallMethod();
+    const cmdInfo = buildUpdateCommand(method, channel);
+    if (!cmdInfo) {
+        return {
+            success: false,
+            method,
+            command: "",
+            previousVersion: currentVersion,
+            newVersion: null,
+            error: "Cannot auto-update a local development install. Use git pull instead.",
+        };
+    }
+    const commandString = `${cmdInfo.command} ${cmdInfo.args.join(" ")}`;
+    const { exitCode, stderr } = await runCommand(cmdInfo.command, cmdInfo.args);
+    if (exitCode !== 0) {
+        return {
+            success: false,
+            method,
+            command: commandString,
+            previousVersion: currentVersion,
+            newVersion: null,
+            error: stderr || `Update command exited with code ${exitCode}.`,
+        };
+    }
+    return {
+        success: true,
+        method,
+        command: commandString,
+        previousVersion: currentVersion,
+        newVersion: readPostUpdateVersion(),
+        error: null,
+    };
+}

package/packages/agent/src/services/signal-pairing.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Signal pairing service — manages device linking via QR code.
+ *
+ * Mirrors whatsapp-pairing.ts but uses @elizaos/signal-native instead of
+ * Baileys. Signal linking produces a single provisioning URL (not a refresh
+ * loop) — if it times out, restart the session.
+ */
+/** Validate accountId to prevent path traversal. */
+export declare function sanitizeAccountId(raw: string): string;
+export type SignalPairingStatus = "idle" | "initializing" | "waiting_for_qr" | "connected" | "disconnected" | "timeout" | "error";
+export interface SignalPairingEvent {
+    type: "signal-qr" | "signal-status";
+    accountId: string;
+    qrDataUrl?: string;
+    status?: SignalPairingStatus;
+    uuid?: string;
+    phoneNumber?: string;
+    error?: string;
+}
+export interface SignalPairingOptions {
+    authDir: string;
+    accountId: string;
+    onEvent: (event: SignalPairingEvent) => void;
+}
+export declare class SignalPairingSession {
+    private status;
+    private options;
+    private aborted;
+    constructor(options: SignalPairingOptions);
+    start(): Promise<void>;
+    stop(): void;
+    getStatus(): SignalPairingStatus;
+    private setStatus;
+}
+export declare function signalAuthExists(workspaceDir: string, accountId?: string): boolean;
+export declare function signalLogout(workspaceDir: string, accountId?: string): void;
+//# sourceMappingURL=signal-pairing.d.ts.map