@rynx-ai/daemon 0.1.0

package/dist/daemon-server.js

@@ -0,0 +1,90 @@
+/**
+ * Shared daemon composition root.
+ *
+ * The CLI/pm2 entry and the Electron app both need the same Rynx server:
+ * channel env hydration, plugin catalog loading, control deps, session log, and
+ * session registry. Keeping that wiring here avoids a second app-specific fork.
+ */
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { loadConfig, rynxHome } from "@rynx-ai/core";
+import { startServer } from "@rynx-ai/server";
+import { applyChannelEnv } from "./channel-store.js";
+import { buildControlDeps } from "./control-deps.js";
+import { cleanupLegacySessions } from "./migrations/cleanup-legacy-sessions.js";
+import { loadPlugins, resolveChannelInstances } from "./registry.js";
+import { SqliteSessionLogStore } from "./session-log-store.js";
+import { sessionRegistry } from "./session-meta-store.js";
+function defaultWarn(message) {
+    console.warn(JSON.stringify({ level: "warn", type: "channel-registry", msg: message }));
+}
+function logLegacyCleanup(config) {
+    try {
+        const result = cleanupLegacySessions({ codexStorePath: config.AGENT_SESSION_STORE_PATH });
+        if (result.deletedSessions || result.deletedLogRows || result.prunedStoreEntries) {
+            console.log(JSON.stringify({
+                level: "info",
+                type: "cleanup",
+                msg: "legacy sessions cleaned up",
+                deletedSessions: result.deletedSessions,
+                deletedLogRows: result.deletedLogRows,
+                prunedStoreEntries: result.prunedStoreEntries,
+            }));
+        }
+    }
+    catch (error) {
+        console.error(JSON.stringify({
+            level: "error",
+            type: "cleanup",
+            msg: "legacy session cleanup failed (retry next boot)",
+            error: error instanceof Error ? error.message : String(error),
+        }));
+    }
+}
+function dialableHost(host) {
+    return host === "0.0.0.0" || host === "::" || host.trim() === "" ? "127.0.0.1" : host;
+}
+function controlEndpointFile() {
+    return join(rynxHome(), "control.json");
+}
+async function writeControlEndpoint(config) {
+    const file = controlEndpointFile();
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, `${JSON.stringify({
+        origin: `http://${dialableHost(config.HOST)}:${config.PORT}`,
+        host: config.HOST,
+        port: config.PORT,
+        pid: process.pid,
+        updatedAt: new Date().toISOString(),
+    }, null, 2)}\n`, "utf8");
+}
+async function removeControlEndpointForCurrentProcess() {
+    try {
+        const file = controlEndpointFile();
+        const raw = await readFile(file, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed.pid === process.pid)
+            await rm(file, { force: true });
+    }
+    catch {
+        // Best effort only; stale endpoint files are ignored by the client fallback.
+    }
+}
+export async function startRynxDaemonServer({ config, warn = defaultWarn, } = {}) {
+    applyChannelEnv();
+    await loadPlugins(warn);
+    const appConfig = config ?? loadConfig();
+    logLegacyCleanup(appConfig);
+    const server = await startServer({
+        config: appConfig,
+        loadInstances: () => resolveChannelInstances(warn),
+        control: buildControlDeps(),
+        sessionLog: new SqliteSessionLogStore(),
+        sessionRegistry,
+    });
+    await writeControlEndpoint(appConfig);
+    server.on("close", () => {
+        void removeControlEndpointForCurrentProcess();
+    });
+    return server;
+}

package/dist/db.d.ts

@@ -0,0 +1,5 @@
+import Database from "better-sqlite3";
+/** Absolute path to the SQLite file (override via `RYNX_DB`, else `~/.rynx/rynx.db`). */
+export declare function dbPath(): string;
+/** Open (or reuse) the database at the current path, migrating + importing on first open. */
+export declare function db(): Database.Database;

package/dist/db.js

@@ -0,0 +1,170 @@
+/**
+ * `~/.rynx/rynx.db` — the daemon's SQLite store. Concerns kept apart:
+ *  - `channels`  — a channel = a plugin type + its config/credentials (`options`).
+ *    The transport/connection, configured & authorized on its own.
+ *  - `instances` — a runnable binding: a channel + an agent (1:1 with a channel,
+ *    enforced by a UNIQUE channel_id). This is what the daemon mounts.
+ *  - `plugins`   — installed plugins (CLI-managed) the loader imports.
+ *  - `session_items` — the canonical, append-only conversation log (one row per
+ *    {@link import("@rynx-ai/core").SessionItem}); see {@link import("./session-log-store.js")}.
+ *
+ * Connections are cached per resolved path so tests can point `RYNX_DB` /
+ * `RYNX_HOME` at a temp dir. Override with `RYNX_DB` (full path) or `RYNX_HOME`.
+ */
+import { randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync } from "node:fs";
+import { dirname, join } from "node:path";
+import Database from "better-sqlite3";
+import { rynxHome } from "@rynx-ai/core";
+const connections = new Map();
+/** Absolute path to the SQLite file (override via `RYNX_DB`, else `~/.rynx/rynx.db`). */
+export function dbPath() {
+    return process.env.RYNX_DB?.trim() || join(rynxHome(), "rynx.db");
+}
+/** Open (or reuse) the database at the current path, migrating + importing on first open. */
+export function db() {
+    const path = dbPath();
+    const cached = connections.get(path);
+    if (cached)
+        return cached;
+    mkdirSync(dirname(path), { recursive: true });
+    const conn = new Database(path);
+    conn.pragma("busy_timeout = 5000");
+    conn.pragma("foreign_keys = ON");
+    migrate(conn);
+    // The store may hold channel secrets (e.g. LARK_APP_SECRET) — keep it private.
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        /* best-effort on platforms without POSIX modes */
+    }
+    connections.set(path, conn);
+    return conn;
+}
+function migrate(conn) {
+    conn.exec(`
+    CREATE TABLE IF NOT EXISTS plugins (
+      name         TEXT PRIMARY KEY,
+      spec         TEXT NOT NULL,
+      source       TEXT NOT NULL,
+      version      TEXT,
+      enabled      INTEGER NOT NULL DEFAULT 1,
+      installed_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS channels (
+      id         TEXT PRIMARY KEY,
+      name       TEXT NOT NULL UNIQUE,
+      type       TEXT NOT NULL,
+      options    TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS instances (
+      id         TEXT PRIMARY KEY,
+      channel_id TEXT NOT NULL UNIQUE REFERENCES channels(id) ON DELETE CASCADE,
+      agent      TEXT,
+      enabled    INTEGER NOT NULL DEFAULT 1,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS session_items (
+      id          TEXT PRIMARY KEY,
+      session_id  TEXT NOT NULL,
+      position    INTEGER NOT NULL,
+      response_id TEXT NOT NULL,
+      type        TEXT NOT NULL,
+      status      TEXT NOT NULL,
+      data        TEXT NOT NULL,
+      created_by  TEXT,
+      created_at  INTEGER NOT NULL,
+      UNIQUE(session_id, position)
+    );
+    CREATE INDEX IF NOT EXISTS idx_session_items_session ON session_items(session_id, position);
+    CREATE TABLE IF NOT EXISTS sessions (
+      id               TEXT PRIMARY KEY,
+      agent            TEXT,
+      config           TEXT,
+      model            TEXT,
+      reasoning_effort TEXT,
+      title            TEXT,
+      source           TEXT,
+      created_at       TEXT NOT NULL,
+      updated_at       TEXT
+    );
+  `);
+    // `sessions` is the unified machine-session record (console + every channel).
+    // Add the identity columns to a pre-existing table (SQLite has no
+    // ADD COLUMN IF NOT EXISTS) and backfill the origin of rows written before
+    // this change — they were all console sessions.
+    addColumnIfMissing(conn, "sessions", "source", "TEXT");
+    addColumnIfMissing(conn, "sessions", "updated_at", "TEXT");
+    conn.exec("UPDATE sessions SET source = 'console' WHERE source IS NULL");
+    importLegacyConfig(conn);
+}
+/** Idempotently add a column to an existing table (no-op if already present). */
+function addColumnIfMissing(conn, table, column, ddl) {
+    const cols = conn.prepare(`PRAGMA table_info(${table})`).all();
+    if (cols.some((c) => c.name === column))
+        return;
+    conn.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${ddl}`);
+}
+/**
+ * One-time import of a pre-existing `~/.rynx/config.json` (the old hand-edited
+ * format, where each entry mixed channel config + agent binding). Each entry
+ * becomes a `channels` row (the config) plus an `instances` row (the binding).
+ * The instance keeps the entry's key as its `id` so per-instance on-disk state
+ * (keyed by instanceId) stays intact. Runs only when empty; the file is renamed
+ * afterwards so it's never read — or hand-edited — again.
+ */
+function importLegacyConfig(conn) {
+    const { n } = conn.prepare("SELECT COUNT(*) AS n FROM channels").get();
+    if (n > 0)
+        return;
+    const legacy = process.env.RYNX_CONFIG?.trim() || join(rynxHome(), "config.json");
+    if (!existsSync(legacy))
+        return;
+    let channels;
+    try {
+        const parsed = JSON.parse(readFileSync(legacy, "utf8"));
+        if (parsed.channels && typeof parsed.channels === "object") {
+            channels = parsed.channels;
+        }
+    }
+    catch {
+        return; // malformed legacy file — leave it alone, start empty
+    }
+    if (!channels)
+        return;
+    const now = new Date().toISOString();
+    const insertChannel = conn.prepare(`INSERT OR IGNORE INTO channels (id, name, type, options, created_at, updated_at)
+     VALUES (@id, @name, @type, @options, @now, @now)`);
+    const insertInstance = conn.prepare(`INSERT OR IGNORE INTO instances (id, channel_id, agent, enabled, created_at, updated_at)
+     VALUES (@id, @channelId, @agent, @enabled, @now, @now)`);
+    const tx = conn.transaction(() => {
+        for (const [key, entry] of Object.entries(channels)) {
+            const channelId = randomUUID();
+            insertChannel.run({
+                id: channelId,
+                name: key,
+                type: entry.type ?? key,
+                options: entry.options ? JSON.stringify(entry.options) : null,
+                now,
+            });
+            insertInstance.run({
+                id: key, // preserve the old key as the runtime instanceId
+                channelId,
+                agent: entry.agent ?? null,
+                enabled: entry.enabled === false ? 0 : 1,
+                now,
+            });
+        }
+    });
+    tx();
+    try {
+        renameSync(legacy, `${legacy}.imported`);
+    }
+    catch {
+        /* leave the source in place if it can't be renamed */
+    }
+}

package/dist/index-daemon.d.ts

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

package/dist/index-daemon.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * The resident daemon entry — this is what pm2 keeps alive.
+ *
+ * Boot order matters: install the EPIPE guard first (we're a pm2 child).
+ * Importing `@rynx-ai/core` hydrates `{RYNX_HOME}/config.json` into the environment,
+ * so `loadConfig()` sees runtime settings; then read the channel registry config,
+ * resolve enabled channel plugins, and hand the factories to the channel-agnostic
+ * `@rynx-ai/server` composition root.
+ */
+import { startRynxDaemonServer } from "./daemon-server.js";
+import { installStdioEpipeGuard } from "./stdio-epipe-guard.js";
+installStdioEpipeGuard();
+async function main() {
+    await startRynxDaemonServer();
+}
+main().catch((err) => {
+    console.error(`Fatal error: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+    process.exit(1);
+});

package/dist/instance-store.d.ts

@@ -0,0 +1,38 @@
+export interface InstanceConfig {
+    id: string;
+    channelId: string;
+    agent?: string;
+    enabled: boolean;
+}
+/** An instance joined with its channel — the shape the control plane lists. */
+export interface InstanceView {
+    id: string;
+    channelId: string;
+    channelName: string;
+    type: string;
+    agent?: string;
+    enabled: boolean;
+    options?: Record<string, unknown>;
+}
+/** A mountable binding: instance id + its channel's type/options + bound agent. */
+export interface InstanceDescriptor {
+    instanceId: string;
+    type: string;
+    options?: Record<string, unknown>;
+    agent?: string;
+}
+export declare function listInstances(): InstanceView[];
+export declare function getInstance(id: string): InstanceView | undefined;
+/** Mountable descriptors for every enabled instance (joined with its channel). */
+export declare function listEnabledDescriptors(): InstanceDescriptor[];
+/** Bind a channel to an agent. Throws if the channel already has an instance. */
+export declare function createInstance(input: {
+    channelId: string;
+    agent?: string;
+    enabled?: boolean;
+}): InstanceConfig;
+export declare function setInstanceAgent(id: string, agent: string | undefined): void;
+export declare function setInstanceEnabled(id: string, enabled: boolean): void;
+export declare function removeInstance(id: string): void;
+/** The instance bound to a channel, if any (1:1). */
+export declare function getInstanceByChannel(channelId: string): InstanceView | undefined;

package/dist/instance-store.js

@@ -0,0 +1,85 @@
+/**
+ * `instances` table CRUD — a runnable binding of a channel to an agent (1:1 with
+ * a channel, enforced by a UNIQUE channel_id). The daemon mounts enabled
+ * instances; each resolves to its channel's type + options plus the bound agent.
+ */
+import { randomUUID } from "node:crypto";
+import { db } from "./db.js";
+function parseOptions(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const JOIN_SELECT = `
+  SELECT i.id, i.channel_id, i.agent, i.enabled,
+         c.name AS channel_name, c.type AS type, c.options AS options
+  FROM instances i JOIN channels c ON c.id = i.channel_id`;
+function toView(row) {
+    return {
+        id: row.id,
+        channelId: row.channel_id,
+        channelName: row.channel_name,
+        type: row.type,
+        agent: row.agent ?? undefined,
+        enabled: row.enabled !== 0,
+        options: parseOptions(row.options),
+    };
+}
+export function listInstances() {
+    const rows = db().prepare(`${JOIN_SELECT} ORDER BY c.name`).all();
+    return rows.map(toView);
+}
+export function getInstance(id) {
+    const row = db().prepare(`${JOIN_SELECT} WHERE i.id = ?`).get(id);
+    return row ? toView(row) : undefined;
+}
+/** Mountable descriptors for every enabled instance (joined with its channel). */
+export function listEnabledDescriptors() {
+    const rows = db().prepare(`${JOIN_SELECT} WHERE i.enabled = 1`).all();
+    return rows.map((row) => ({
+        instanceId: row.id,
+        type: row.type,
+        options: parseOptions(row.options),
+        agent: row.agent ?? undefined,
+    }));
+}
+/** Bind a channel to an agent. Throws if the channel already has an instance. */
+export function createInstance(input) {
+    const id = randomUUID();
+    const now = new Date().toISOString();
+    db()
+        .prepare(`INSERT INTO instances (id, channel_id, agent, enabled, created_at, updated_at)
+       VALUES (@id, @channelId, @agent, @enabled, @now, @now)`)
+        .run({
+        id,
+        channelId: input.channelId,
+        agent: input.agent ?? null,
+        enabled: input.enabled === false ? 0 : 1,
+        now,
+    });
+    return { id, channelId: input.channelId, agent: input.agent, enabled: input.enabled !== false };
+}
+export function setInstanceAgent(id, agent) {
+    db()
+        .prepare("UPDATE instances SET agent = ?, updated_at = ? WHERE id = ?")
+        .run(agent ?? null, new Date().toISOString(), id);
+}
+export function setInstanceEnabled(id, enabled) {
+    db()
+        .prepare("UPDATE instances SET enabled = ?, updated_at = ? WHERE id = ?")
+        .run(enabled ? 1 : 0, new Date().toISOString(), id);
+}
+export function removeInstance(id) {
+    db().prepare("DELETE FROM instances WHERE id = ?").run(id);
+}
+/** The instance bound to a channel, if any (1:1). */
+export function getInstanceByChannel(channelId) {
+    const row = db().prepare(`${JOIN_SELECT} WHERE i.channel_id = ?`).get(channelId);
+    return row ? toView(row) : undefined;
+}

package/dist/migrations/cleanup-legacy-sessions.d.ts

@@ -0,0 +1,18 @@
+export interface CleanupOptions {
+    /** CodexSessionStore JSON path; defaults to `<cwd>/.codex-proxy/sessions.json`. */
+    codexStorePath?: string;
+    /** Dir holding the channel routing maps (`lark-sessions*.json`); defaults to
+     *  `<cwd>/.codex-proxy`. */
+    channelStoreDir?: string;
+    /** Report what would be removed without deleting anything. */
+    dryRun?: boolean;
+    log?: (entry: Record<string, unknown>) => void;
+}
+export interface CleanupResult {
+    dryRun: boolean;
+    deletedLogRows: number;
+    deletedSessions: number;
+    /** Legacy entries pruned from the JSON stores. */
+    prunedStoreEntries: number;
+}
+export declare function cleanupLegacySessions(opts?: CleanupOptions): CleanupResult;

package/dist/migrations/cleanup-legacy-sessions.js

@@ -0,0 +1,123 @@
+/**
+ * Self-healing cleanup of legacy, origin-encoded sessions.
+ *
+ * Sessions now carry an opaque `sess_<uuid>` id. Any session keyed by a legacy id
+ * (`session_<uuid>` console, `lark:…:session:<uuid>` / `lark:…` channel) is simply
+ * discarded — not migrated — so the system stays clean and every channel re-mints
+ * a fresh `sess_` session on its next message.
+ *
+ * Deletes:
+ *   - canonical-log rows (`session_items`) and identity rows (`sessions`) whose
+ *     id is not an opaque `sess_` id,
+ *   - the runtime thread→rollout bindings `.codex-proxy/sessions.json` and the
+ *     channel routing maps `.codex-proxy/lark-sessions*.json` entries that point
+ *     at a legacy id (the externalKey KEYS go too, so the next message bootstraps
+ *     a fresh session).
+ *
+ * Runs on every daemon boot (not marker-gated): on a healthy system it deletes
+ * nothing and writes nothing, so it is cheap; if a legacy session ever appears
+ * (e.g. an old channel plugin produced one), the next boot removes it. The
+ * `sess_` filter means it can never touch a current session.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { isMachineSessionId } from "@rynx-ai/core";
+import { db } from "../db.js";
+/** Mirrors the channel stores' own resolution (`<cwd>/.codex-proxy`). Kept local
+ *  so the daemon needn't depend on `@rynx-ai/runtime` / the lark plugin. */
+function defaultProxyDir() {
+    return path.join(process.cwd(), ".codex-proxy");
+}
+// Anything whose id isn't an opaque `sess_` id is legacy. GLOB treats `_` as a
+// literal (unlike LIKE), so `sess_*` matches exactly the new id shape.
+const LEGACY_LOG = "session_id NOT GLOB 'sess_*'";
+const LEGACY_META = "id NOT GLOB 'sess_*'";
+export function cleanupLegacySessions(opts = {}) {
+    const log = opts.log ?? (() => { });
+    const dryRun = Boolean(opts.dryRun);
+    const conn = db();
+    const codexStorePath = opts.codexStorePath ?? path.join(defaultProxyDir(), "sessions.json");
+    const channelStoreDir = opts.channelStoreDir ?? defaultProxyDir();
+    const larkFiles = listLarkStoreFiles(channelStoreDir);
+    if (dryRun) {
+        const deletedLogRows = countRows(conn, `SELECT COUNT(*) AS n FROM session_items WHERE ${LEGACY_LOG}`);
+        const deletedSessions = countRows(conn, `SELECT COUNT(*) AS n FROM sessions WHERE ${LEGACY_META}`);
+        const prunedStoreEntries = countLegacyStoreEntries(readJsonStore(codexStorePath), (key) => key) +
+            larkFiles.reduce((sum, file) => sum + countLegacyStoreEntries(readJsonStore(file), (_k, rec) => rec.sessionId), 0);
+        log({ event: "cleanup.dry_run", deletedLogRows, deletedSessions, prunedStoreEntries });
+        return { dryRun: true, deletedLogRows, deletedSessions, prunedStoreEntries };
+    }
+    let deletedLogRows = 0;
+    let deletedSessions = 0;
+    let prunedStoreEntries = 0;
+    conn.transaction(() => {
+        deletedLogRows = conn.prepare(`DELETE FROM session_items WHERE ${LEGACY_LOG}`).run().changes;
+        deletedSessions = conn.prepare(`DELETE FROM sessions WHERE ${LEGACY_META}`).run().changes;
+    })();
+    // Prune the JSON stores: a codex entry keyed by a legacy id, or a routing entry
+    // whose value points at one. Removing the routing entry makes the next message
+    // bootstrap a fresh `sess_` session for that conversation.
+    prunedStoreEntries += pruneStore(codexStorePath, (key) => key);
+    for (const file of larkFiles)
+        prunedStoreEntries += pruneStore(file, (_k, rec) => rec.sessionId);
+    if (deletedLogRows || deletedSessions || prunedStoreEntries) {
+        log({ event: "cleanup.done", deletedLogRows, deletedSessions, prunedStoreEntries });
+    }
+    return { dryRun: false, deletedLogRows, deletedSessions, prunedStoreEntries };
+}
+function countRows(conn, sql) {
+    return conn.prepare(sql).get().n;
+}
+function countLegacyStoreEntries(data, idOf) {
+    let n = 0;
+    for (const [key, record] of Object.entries(data.sessions ?? {})) {
+        const id = idOf(key, record);
+        if (typeof id === "string" && !isMachineSessionId(id))
+            n += 1;
+    }
+    return n;
+}
+/** Drop every legacy entry from a JSON store; returns how many were removed. */
+function pruneStore(file, idOf) {
+    const data = readJsonStore(file);
+    if (!data.sessions)
+        return 0;
+    let pruned = 0;
+    const kept = {};
+    for (const [key, record] of Object.entries(data.sessions)) {
+        const id = idOf(key, record);
+        if (typeof id === "string" && !isMachineSessionId(id)) {
+            pruned += 1;
+        }
+        else {
+            kept[key] = record;
+        }
+    }
+    if (pruned > 0) {
+        data.sessions = kept;
+        writeJsonStore(file, data);
+    }
+    return pruned;
+}
+function listLarkStoreFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((name) => /^lark-sessions.*\.json$/.test(name))
+        .map((name) => path.join(dir, name));
+}
+function readJsonStore(file) {
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeJsonStore(file, data) {
+    mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = path.join(path.dirname(file), `.${path.basename(file)}.cleanup.tmp`);
+    writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+    renameSync(tmp, file);
+}

package/dist/plugin-installer.d.ts

@@ -0,0 +1,27 @@
+import { type PluginRecord, type PluginSource } from "./plugin-store.js";
+export interface InstallResult {
+    name: string;
+    source: PluginSource;
+    version?: string;
+    /** True when an existing same-named plugin was kept (user declined to overwrite). */
+    skipped?: boolean;
+}
+/**
+ * Install (or re-install) a plugin from an npm spec or a local directory.
+ *  - **local**: copy the package (minus `node_modules`) into `~/.rynx/plugins/<name>`
+ *    and load it there. The plugin must be self-contained — it bundles its deps at
+ *    build time (incl. the unpublished workspace `@rynx-ai/core`) and declares a
+ *    `rynx.plugin` entry; the daemon installs nothing.
+ *  - **npm**: `npm install` into `~/.rynx/plugins` (deps resolved by npm).
+ *
+ * `onConflict` is consulted when a plugin of the same `name` already exists; if it
+ * returns false the install is aborted with `{ skipped: true }` (nothing changes).
+ * `onProgress` streams human-readable lines.
+ */
+export declare function installPlugin(spec: string, onProgress?: (line: string) => void, opts?: {
+    signal?: AbortSignal;
+    onConflict?: (existing: PluginRecord) => boolean | Promise<boolean>;
+}): Promise<InstallResult>;
+/** Uninstall a plugin: drop its record, npm-uninstall if applicable, refresh catalog. */
+export declare function uninstallPlugin(name: string, onProgress?: (line: string) => void): Promise<boolean>;
+export type { PluginRecord };