@botcord/daemon 0.1.1

package/dist/agent-workspace.js

@@ -0,0 +1,221 @@
+/**
+ * Per-agent on-disk workspace. Each provisioned agent gets a dedicated
+ * directory tree under `~/.botcord/agents/{agentId}/`:
+ *
+ *   workspace/   — runtime cwd; seed Markdown files live here (LLM-owned)
+ *   state/       — daemon-owned JSON (e.g. working-memory.json)
+ *   codex-home/  — per-agent CODEX_HOME used by the codex adapter so codex
+ *                  reads a daemon-written AGENTS.md (systemContext carrier)
+ *                  and stores its sessions/ without touching ~/.codex.
+ *
+ * See docs/daemon-agent-workspace-plan.md §4 for the full layout rationale.
+ */
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readlinkSync, symlinkSync, unlinkSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+// Accepted agent id pattern. Enforced at every path-builder entry so a
+// malicious / malformed agentId (e.g. "../../etc") cannot escape
+// ~/.botcord/agents/ and end up under `rmSync(..., { recursive: true })`
+// in revokeAgent(deleteWorkspace: true).
+const AGENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+function assertSafeAgentId(agentId) {
+    if (!agentId)
+        throw new Error("agentId is required");
+    if (!AGENT_ID_PATTERN.test(agentId)) {
+        throw new Error(`unsafe agentId: ${JSON.stringify(agentId)}`);
+    }
+}
+export function agentHomeDir(agentId) {
+    assertSafeAgentId(agentId);
+    return path.join(homedir(), ".botcord", "agents", agentId);
+}
+export function agentWorkspaceDir(agentId) {
+    return path.join(agentHomeDir(agentId), "workspace");
+}
+export function agentStateDir(agentId) {
+    return path.join(agentHomeDir(agentId), "state");
+}
+/**
+ * Per-agent CODEX_HOME. The codex adapter sets the `CODEX_HOME` env var
+ * to this path so codex reads a daemon-managed `AGENTS.md` (written fresh
+ * each turn with the agent's systemContext) and stores its `sessions/`
+ * here — neither touching `~/.codex/` nor the agent's `workspace/` cwd.
+ */
+export function agentCodexHomeDir(agentId) {
+    return path.join(agentHomeDir(agentId), "codex-home");
+}
+const AGENTS_MD = `# Agent Workspace
+
+This directory is your persistent workspace. You run with \`cwd\` set here.
+
+## Files you own
+
+- \`identity.md\` — who you are, your role, your boundaries. Read before responding.
+- \`memory.md\` — long-lived facts, user preferences, past decisions. Update when
+  you learn something durable. Prune when it grows stale.
+- \`task.md\` — current task and plan. Update as you make progress. Clear when done.
+- \`notes/\` — free-form scratch space.
+
+## Boundaries
+
+- Do not modify files outside this workspace unless the user explicitly asks.
+- \`../state/\` (sibling directory, outside this workspace) is managed by the
+  daemon — do not read or edit it directly.
+
+## How to use this
+
+You are **instructed** to skim \`identity.md\`, \`memory.md\`, \`task.md\` before each
+response and to write back what changed after meaningful turns. Nothing in the
+runtime enforces this — the daemon does not auto-load these files into your
+context. Treat AGENTS.md as a convention, not a mechanism.
+`;
+const MEMORY_MD = `# Memory
+
+<!--
+Long-lived facts about the user, past decisions, and preferences that should
+survive across conversations. Organize by topic. Keep entries short. Prune
+regularly — AGENTS.md instructs the runtime to consult this file before each
+response, but nothing loads it automatically; keep it short enough to be
+worth re-reading.
+-->
+`;
+const TASK_MD = `# Current Task
+
+<!--
+What are you working on right now? What is the plan? What is blocked?
+Clear this file when the task is done.
+-->
+`;
+const BIO_PLACEHOLDER = "_(none provided at provision time — edit this section)_";
+const FIELD_PLACEHOLDER = "_(not set)_";
+function renderIdentity(agentId, seed) {
+    const bio = seed.bio && seed.bio.trim().length > 0 ? seed.bio : BIO_PLACEHOLDER;
+    return `# Identity
+
+- **Agent ID**: ${agentId}
+- **Display name**: ${seed.displayName ?? FIELD_PLACEHOLDER}
+- **Runtime**: ${seed.runtime ?? FIELD_PLACEHOLDER}
+- **Key ID**: ${seed.keyId ?? FIELD_PLACEHOLDER}
+- **Created**: ${seed.savedAt ?? FIELD_PLACEHOLDER}
+
+## Bio
+
+${bio}
+
+## Role
+
+_(Describe what you do and for whom. Edit this section.)_
+
+## Boundaries
+
+_(What you will and will not do. Edit this section.)_
+`;
+}
+function mkdirTolerant(dir) {
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err;
+    }
+    // mkdirSync with `recursive: true` only applies `mode` to directories it
+    // creates. If the agent home / workspace / state already existed with
+    // looser perms (a very common case on upgrades), tighten them now.
+    // Best-effort: some filesystems (e.g. certain Windows / SMB mounts) reject
+    // chmod and that is acceptable.
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function writeIfMissing(filePath, content) {
+    if (existsSync(filePath))
+        return;
+    writeFileSync(filePath, content, { mode: 0o600 });
+}
+/**
+ * Best-effort link user's `~/.codex/auth.json` into the per-agent CODEX_HOME.
+ * Prefers a symlink (auto-follows `codex login` refreshes) and falls back to
+ * a copy on filesystems that reject symlinks. A no-op if the user has never
+ * run `codex login` — codex will then prompt on first use.
+ */
+function linkCodexAuth(codexHome) {
+    const source = path.join(homedir(), ".codex", "auth.json");
+    if (!existsSync(source))
+        return;
+    const target = path.join(codexHome, "auth.json");
+    try {
+        if (existsSync(target) || isSymlink(target)) {
+            if (isSymlink(target) && readlinkSync(target) === source)
+                return;
+            unlinkSync(target);
+        }
+    }
+    catch {
+        // Unlink failure is rare but tolerable — symlink/copy below will fail
+        // loudly if the collision is real.
+    }
+    try {
+        symlinkSync(source, target);
+        return;
+    }
+    catch {
+        // Fall through to copy on filesystems without symlink support.
+    }
+    try {
+        copyFileSync(source, target);
+        chmodSync(target, 0o600);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function isSymlink(p) {
+    try {
+        return lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Idempotently create the per-agent CODEX_HOME directory and link the
+ * user's codex `auth.json` into it. Does NOT write an initial `AGENTS.md`
+ * — the codex adapter writes it fresh per turn from `systemContext`.
+ */
+export function ensureAgentCodexHome(agentId) {
+    const dir = agentCodexHomeDir(agentId);
+    mkdirTolerant(dir);
+    linkCodexAuth(dir);
+    return dir;
+}
+/**
+ * Idempotently create the agent's home / workspace / state directories and
+ * seed the workspace Markdown files. Existing files are never overwritten —
+ * users' edits to AGENTS.md, memory.md, etc. are preserved across calls.
+ * State files are not touched here; working-memory.ts owns `state/`.
+ */
+export function ensureAgentWorkspace(agentId, seed) {
+    if (!agentId)
+        throw new Error("ensureAgentWorkspace: agentId is required");
+    const home = agentHomeDir(agentId);
+    const workspace = agentWorkspaceDir(agentId);
+    const notes = path.join(workspace, "notes");
+    const state = agentStateDir(agentId);
+    mkdirTolerant(home);
+    mkdirTolerant(workspace);
+    mkdirTolerant(notes);
+    mkdirTolerant(state);
+    ensureAgentCodexHome(agentId);
+    const agentsMdPath = path.join(workspace, "AGENTS.md");
+    const claudeMdPath = path.join(workspace, "CLAUDE.md");
+    writeIfMissing(agentsMdPath, AGENTS_MD);
+    writeIfMissing(claudeMdPath, AGENTS_MD);
+    writeIfMissing(path.join(workspace, "identity.md"), renderIdentity(agentId, seed));
+    writeIfMissing(path.join(workspace, "memory.md"), MEMORY_MD);
+    writeIfMissing(path.join(workspace, "task.md"), TASK_MD);
+    writeIfMissing(path.join(notes, ".gitkeep"), "");
+}

package/dist/config.d.ts

@@ -0,0 +1,116 @@
+export declare const PID_PATH: string;
+export declare const SESSIONS_PATH: string;
+export declare const SNAPSHOT_PATH: string;
+/**
+ * Adapter ids. Built-in adapters are enumerated for editor hints; any string
+ * accepted by the registry is valid at runtime.
+ */
+export type AdapterName = "claude-code" | "codex" | "gemini" | (string & {});
+/**
+ * Predicates selecting messages for a route. `roomId` / `roomPrefix` are
+ * legacy aliases retained for backward compatibility with pre-P1 daemon
+ * configs; they map to `conversationId` / `conversationPrefix` at boot.
+ * First match wins.
+ */
+export interface RouteRuleMatch {
+    /** @deprecated alias for `conversationId`. */
+    roomId?: string;
+    /** @deprecated alias for `conversationPrefix`. */
+    roomPrefix?: string;
+    channel?: string;
+    accountId?: string;
+    conversationId?: string;
+    conversationPrefix?: string;
+    conversationKind?: "direct" | "group";
+    senderId?: string;
+    mentioned?: boolean;
+}
+export interface RouteRule {
+    match: RouteRuleMatch;
+    adapter: AdapterName;
+    cwd: string;
+    /** Extra CLI flags appended to the adapter invocation. */
+    extraArgs?: string[];
+}
+export interface DaemonRouteDefault {
+    adapter: AdapterName;
+    cwd: string;
+    extraArgs?: string[];
+}
+/**
+ * Daemon-layer hook controlling credential auto-discovery at boot. Kept
+ * optional so most users never need to touch it; absence means "use the
+ * default rule" (enabled unless an explicit `agents`/`agentId` list is
+ * already present).
+ */
+export interface AgentDiscoveryConfig {
+    enabled?: boolean;
+    credentialsDir?: string;
+}
+export interface DaemonConfig {
+    /**
+     * @deprecated Kept for backward compatibility with pre-multi-agent configs.
+     * Normalized in-memory to `agents: [agentId]` when present. New configs
+     * written by `init` use `agents` exclusively.
+     */
+    agentId?: string;
+    /**
+     * BotCord agent ids this daemon binds to. Each id maps to its own channel
+     * whose `id` equals the agentId. Credentials are loaded from
+     * `~/.botcord/credentials/{agentId}.json`. Canonical — prefer this over
+     * `agentId`.
+     *
+     * Optional: when both `agents` and `agentId` are absent, the daemon
+     * discovers identities from the credentials directory at boot.
+     */
+    agents?: string[];
+    /**
+     * Opt-in controls for credential discovery. When omitted, discovery runs
+     * iff no explicit `agents`/`agentId` list is present (P1 default).
+     */
+    agentDiscovery?: AgentDiscoveryConfig;
+    /** Default adapter + cwd used when no route matches. */
+    defaultRoute: DaemonRouteDefault;
+    routes: RouteRule[];
+    /** If true, stream blocks (only meaningful for rm_oc_* rooms). */
+    streamBlocks: boolean;
+}
+/**
+ * Return the explicit agent-id list written to disk, or `null` when the
+ * config has none. P1 gives discovery a chance at boot before failing,
+ * so the resolver no longer throws — callers that need a guaranteed list
+ * should fall back to `resolveAgentIds` (which still throws) or run the
+ * discovery layer first.
+ *
+ * - `agents` is present and non-empty → use it verbatim.
+ * - `agents` empty/missing + `agentId` present → synthesize `[agentId]`.
+ * - Both present: if `agentId` is not in `agents`, log a warn and let
+ *   `agents` win.
+ * - Neither present → return `null` (discovery-eligible).
+ *
+ * De-duplicates while preserving order.
+ */
+export declare function resolveConfiguredAgentIds(cfg: DaemonConfig): string[] | null;
+/**
+ * Legacy strict resolver — preserved for callers that still assume an
+ * explicit list on disk (e.g. internal tests, or codepaths that run
+ * before discovery). Throws when neither `agents` nor `agentId` is set.
+ */
+export declare function resolveAgentIds(cfg: DaemonConfig): string[];
+export declare function loadConfig(): DaemonConfig;
+export declare function saveConfig(cfg: DaemonConfig): void;
+/**
+ * Build a default config. Always writes the new `agents: [...]` shape when
+ * explicit ids are provided; the legacy scalar `agentId` field is never
+ * emitted by fresh `init` runs. When called with an empty list, `agents`
+ * is omitted entirely so the daemon auto-discovers identities at boot.
+ */
+export declare function initDefaultConfig(agentIds: string | string[] | null | undefined, cwd?: string): DaemonConfig;
+export declare const CONFIG_FILE_PATH: string;
+export declare const DAEMON_DIR_PATH: string;
+/**
+ * Make the daemon directory (`~/.botcord/daemon`) exist with mode `0700`.
+ * Tolerant of the common case where it already exists. Exported so
+ * user-auth/snapshot code can stay independent of `saveConfig`.
+ */
+export declare function ensureDaemonDir(): void;

package/dist/config.js

@@ -0,0 +1,180 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { getAdapterModule, listAdapterIds } from "./adapters/runtimes.js";
+const DAEMON_DIR = path.join(homedir(), ".botcord", "daemon");
+const CONFIG_PATH = path.join(DAEMON_DIR, "config.json");
+export const PID_PATH = path.join(DAEMON_DIR, "daemon.pid");
+export const SESSIONS_PATH = path.join(DAEMON_DIR, "sessions.json");
+export const SNAPSHOT_PATH = path.join(DAEMON_DIR, "snapshot.json");
+/**
+ * Return the explicit agent-id list written to disk, or `null` when the
+ * config has none. P1 gives discovery a chance at boot before failing,
+ * so the resolver no longer throws — callers that need a guaranteed list
+ * should fall back to `resolveAgentIds` (which still throws) or run the
+ * discovery layer first.
+ *
+ * - `agents` is present and non-empty → use it verbatim.
+ * - `agents` empty/missing + `agentId` present → synthesize `[agentId]`.
+ * - Both present: if `agentId` is not in `agents`, log a warn and let
+ *   `agents` win.
+ * - Neither present → return `null` (discovery-eligible).
+ *
+ * De-duplicates while preserving order.
+ */
+export function resolveConfiguredAgentIds(cfg) {
+    const agents = Array.isArray(cfg.agents) ? cfg.agents.filter((s) => typeof s === "string" && s.length > 0) : [];
+    const legacy = typeof cfg.agentId === "string" && cfg.agentId.length > 0 ? cfg.agentId : null;
+    if (agents.length > 0) {
+        if (legacy && !agents.includes(legacy)) {
+            // Conflicting shapes on disk; `agents` wins per spec. Logged via
+            // stderr so users running `config` or `start` can spot the drift —
+            // the `log` module isn't imported here to avoid the side-effect of
+            // opening the log file from config validation.
+            // eslint-disable-next-line no-console
+            console.warn(`daemon config: legacy agentId "${legacy}" not listed in agents [${agents.join(", ")}]; preferring agents`);
+        }
+        return dedupe(agents);
+    }
+    if (legacy)
+        return [legacy];
+    return null;
+}
+/**
+ * Legacy strict resolver — preserved for callers that still assume an
+ * explicit list on disk (e.g. internal tests, or codepaths that run
+ * before discovery). Throws when neither `agents` nor `agentId` is set.
+ */
+export function resolveAgentIds(cfg) {
+    const configured = resolveConfiguredAgentIds(cfg);
+    if (configured)
+        return configured;
+    throw new Error(`daemon config missing agents (or legacy agentId) (${CONFIG_PATH})`);
+}
+function dedupe(xs) {
+    const seen = new Set();
+    const out = [];
+    for (const x of xs) {
+        if (seen.has(x))
+            continue;
+        seen.add(x);
+        out.push(x);
+    }
+    return out;
+}
+function ensureDir() {
+    try {
+        mkdirSync(DAEMON_DIR, { recursive: true, mode: 0o700 });
+    }
+    catch {
+        // best-effort
+    }
+}
+export function loadConfig() {
+    if (!existsSync(CONFIG_PATH)) {
+        throw new Error(`daemon config not found at ${CONFIG_PATH}. Run \`botcord-daemon init\` first.`);
+    }
+    const raw = readFileSync(CONFIG_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    const hasAgents = Array.isArray(parsed.agents) && parsed.agents.some((s) => typeof s === "string" && s.length > 0);
+    const hasLegacy = typeof parsed.agentId === "string" && parsed.agentId.length > 0;
+    const discovery = parsed.agentDiscovery;
+    const discoveryExplicitlyDisabled = !!discovery && typeof discovery === "object" && discovery.enabled === false;
+    if (!hasAgents && !hasLegacy && discoveryExplicitlyDisabled) {
+        throw new Error(`daemon config has no agents/agentId and agentDiscovery.enabled=false (${CONFIG_PATH})`);
+    }
+    if (hasAgents) {
+        for (const [i, a] of parsed.agents.entries()) {
+            if (typeof a !== "string" || a.length === 0) {
+                throw new Error(`daemon config agents[${i}] must be a non-empty string (${CONFIG_PATH})`);
+            }
+        }
+    }
+    if (!parsed.defaultRoute ||
+        typeof parsed.defaultRoute.adapter !== "string" ||
+        typeof parsed.defaultRoute.cwd !== "string") {
+        throw new Error(`daemon config missing defaultRoute.adapter/cwd (${CONFIG_PATH})`);
+    }
+    validateAdapter(parsed.defaultRoute.adapter, "defaultRoute.adapter");
+    const routesRaw = parsed.routes ?? [];
+    if (!Array.isArray(routesRaw)) {
+        throw new Error(`daemon config "routes" must be an array (${CONFIG_PATH})`);
+    }
+    for (const [i, r] of routesRaw.entries()) {
+        if (!r || typeof r !== "object") {
+            throw new Error(`daemon config routes[${i}] is not an object (${CONFIG_PATH})`);
+        }
+        if (typeof r.adapter !== "string" || typeof r.cwd !== "string") {
+            throw new Error(`daemon config routes[${i}] missing string adapter/cwd (${CONFIG_PATH})`);
+        }
+        validateAdapter(r.adapter, `routes[${i}].adapter`);
+    }
+    // Preserve the on-disk shape as-is so `config` prints what the user wrote.
+    // Resolution of agents vs agentId happens at the consumption boundary
+    // (`resolveAgentIds`, `toGatewayConfig`).
+    const out = {
+        defaultRoute: parsed.defaultRoute,
+        routes: routesRaw,
+        streamBlocks: parsed.streamBlocks ?? true,
+    };
+    if (hasAgents)
+        out.agents = parsed.agents.slice();
+    if (hasLegacy)
+        out.agentId = parsed.agentId;
+    if (discovery && typeof discovery === "object") {
+        const copy = {};
+        if (typeof discovery.enabled === "boolean")
+            copy.enabled = discovery.enabled;
+        if (typeof discovery.credentialsDir === "string" && discovery.credentialsDir.length > 0) {
+            copy.credentialsDir = discovery.credentialsDir;
+        }
+        out.agentDiscovery = copy;
+    }
+    return out;
+}
+function validateAdapter(id, field) {
+    const mod = getAdapterModule(id);
+    if (!mod) {
+        throw new Error(`unknown ${field} "${id}". Registered: ${listAdapterIds().join(", ")}`);
+    }
+    if (mod.supportsRun === false) {
+        throw new Error(`${field} "${id}" is a probe-only stub and cannot handle turns yet`);
+    }
+}
+export function saveConfig(cfg) {
+    ensureDir();
+    const tmp = CONFIG_PATH + ".tmp";
+    writeFileSync(tmp, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+    renameSync(tmp, CONFIG_PATH);
+}
+/**
+ * Build a default config. Always writes the new `agents: [...]` shape when
+ * explicit ids are provided; the legacy scalar `agentId` field is never
+ * emitted by fresh `init` runs. When called with an empty list, `agents`
+ * is omitted entirely so the daemon auto-discovers identities at boot.
+ */
+export function initDefaultConfig(agentIds, cwd = homedir()) {
+    const list = Array.isArray(agentIds)
+        ? agentIds
+        : typeof agentIds === "string" && agentIds.length > 0
+            ? [agentIds]
+            : [];
+    const out = {
+        defaultRoute: { adapter: "claude-code", cwd },
+        routes: [],
+        streamBlocks: true,
+    };
+    if (list.length > 0)
+        out.agents = dedupe(list);
+    return out;
+}
+export const CONFIG_FILE_PATH = CONFIG_PATH;
+export const DAEMON_DIR_PATH = DAEMON_DIR;
+/**
+ * Make the daemon directory (`~/.botcord/daemon`) exist with mode `0700`.
+ * Tolerant of the common case where it already exists. Exported so
+ * user-auth/snapshot code can stay independent of `saveConfig`.
+ */
+export function ensureDaemonDir() {
+    ensureDir();
+}

package/dist/control-channel.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Daemon ↔ Hub control-plane WebSocket.
+ *
+ * One long-lived connection, carrying JSON {@link ControlFrame} messages.
+ * Independent from the agent data-plane WS: different auth (user access
+ * token vs agent JWT), different endpoint (`/daemon/ws`), different
+ * lifecycle (alive even when zero agents are bound).
+ *
+ * See `docs/daemon-control-plane-plan.md` §4.1, §4.3, §8.
+ */
+import WebSocket from "ws";
+import { type ControlAck, type ControlFrame } from "@botcord/protocol-core";
+import { type UserAuthManager } from "./user-auth.js";
+/**
+ * Build the canonical signing input for a control frame: RFC 8785 (JCS)
+ * canonicalization of `{id, type, params, ts}`. Per
+ * `docs/daemon-control-plane-api-contract.md` §3.3 — the Hub uses Python
+ * `jcs.canonicalize` over the same object before signing.
+ *
+ * Excludes `sig` by definition. `params` defaults to `{}` (empty object)
+ * to match the Hub-side default for paramless types like `ping`.
+ */
+export declare function controlSigningInput(frame: {
+    id: string;
+    type: string;
+    ts?: number;
+    params?: unknown;
+}): string;
+/** Handler invoked for each inbound frame. Return value is the ack payload. */
+export type ControlFrameHandler = (frame: ControlFrame) => Promise<Omit<ControlAck, "id"> | void> | Omit<ControlAck, "id"> | void;
+/** Options accepted by {@link ControlChannel}. */
+export interface ControlChannelOptions {
+    /** User-auth manager driving the access token. */
+    auth: UserAuthManager;
+    /** Dispatcher for inbound frames. Unknown types should return an error ack. */
+    handle: ControlFrameHandler;
+    /** Override the WS endpoint path; defaults to `/daemon/ws`. */
+    path?: string;
+    /**
+     * Optional human label sent to Hub on connect (`?label=...`). Hub uses it
+     * to populate `daemon_instances.label` for the dashboard listing. Plan §11.3.
+     */
+    label?: string;
+    /**
+     * Override the embedded Hub control-plane public key (raw 32-byte, base64).
+     * When omitted the channel falls back to {@link resolveHubControlPublicKey},
+     * which honors `BOTCORD_HUB_CONTROL_PUBLIC_KEY`.
+     */
+    hubPublicKey?: string | null;
+    /** Test hook — inject a WebSocket constructor. */
+    webSocketCtor?: typeof WebSocket;
+    /** Test hook — override the backoff schedule. */
+    backoffMs?: number[];
+    /** Test hook — override the keepalive interval. */
+    keepaliveIntervalMs?: number;
+}
+/**
+ * Long-lived, self-healing WS connection that carries control frames
+ * between the Hub and the local daemon. Owns reconnect/backoff and
+ * dedupe; delegates frame semantics to a caller-supplied handler.
+ */
+export declare class ControlChannel {
+    private readonly auth;
+    private readonly handle;
+    private readonly path;
+    private readonly label;
+    private readonly hubPublicKey;
+    private readonly webSocketCtor;
+    private readonly backoff;
+    private readonly keepaliveMs;
+    private ws;
+    private stopRequested;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private keepaliveTimer;
+    private readonly seenFrameIds;
+    private connectInflight;
+    private connected;
+    constructor(opts: ControlChannelOptions);
+    /** True once the initial WS handshake succeeded. Flipped back on close. */
+    get isConnected(): boolean;
+    /**
+     * Open the WS. Resolves after the first `open` event — transient
+     * reconnects after that run in the background until `stop()` is
+     * called. Throws immediately if no user-auth record is loaded.
+     */
+    start(): Promise<void>;
+    /** Close the WS and stop reconnecting. Idempotent. */
+    stop(): Promise<void>;
+    /** Actively send a frame (used for event reports like `agent_provisioned`). */
+    send(frame: ControlFrame): boolean;
+    private connect;
+    private startKeepalive;
+    private stopKeepalive;
+    private onClose;
+    private scheduleReconnect;
+    private onMessage;
+    private sendAck;
+}