@konglx/rotom 2.21.0

package/dist/master/db/schedules.js

@@ -0,0 +1,135 @@
+/**
+ * Scheduled tasks — at-most-once cron-style triggers with run history.
+ *
+ * Methods attach via `Object.assign`. The scheduler module (./scheduler.ts)
+ * pulls `getDueScheduledTasks` each tick and calls `markScheduledTaskRun`
+ * after the run completes. `next_run_at` is the integer-ms epoch field the
+ * scheduler indexes on; `markScheduledTaskRun` preserves `last_issue_id`
+ * when `issueId=null` is passed so the agent mode can re-bind to the same
+ * issue across repeat iterations.
+ */
+import { buildUpdate } from "./build-update.js";
+export const scheduleMethods = {
+    listScheduledTasks(filter) {
+        let sql = "SELECT * FROM scheduled_tasks WHERE 1=1";
+        const params = [];
+        if (filter?.groupId) {
+            sql += " AND group_id = ?";
+            params.push(filter.groupId);
+        }
+        sql += " ORDER BY id DESC";
+        return this.db.prepare(sql).all(...params);
+    },
+    getScheduledTask(id) {
+        return this.db.prepare("SELECT * FROM scheduled_tasks WHERE id = ?")
+            .get(id);
+    },
+    /** 返回所有已启用、且 next_run_at <= now 的任务。调度器串行消费。 */
+    getDueScheduledTasks(now) {
+        return this.db.prepare("SELECT * FROM scheduled_tasks WHERE enabled = 1 AND next_run_at <= ? ORDER BY next_run_at ASC").all(now);
+    },
+    /** 新建任务;返回插入后的完整 row(包含自动算出的首个 next_run_at)。 */
+    createScheduledTask(input) {
+        const now = Date.now();
+        const enabled = input.enabled === false ? 0 : 1;
+        const nextRunAt = input.scheduleKind === "once"
+            ? (input.runAt ?? now)
+            : now + (input.intervalSec ?? 0) * 1000;
+        const info = this.db.prepare(`
+      INSERT INTO scheduled_tasks (
+        name, group_id, mode, agent_name, schedule_kind, interval_sec, run_at,
+        prompt, enabled, next_run_at, repeat_times, repeat_count, created_at, updated_at,
+        handler_key, handler_payload
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?)
+    `).run(input.name, input.groupId, input.mode, input.agentName ?? null, input.scheduleKind, input.intervalSec ?? null, input.runAt ?? null, input.prompt, enabled, nextRunAt, input.repeatTimes ?? null, now, now, input.handlerKey ?? null, input.handlerPayload ?? null);
+        return this.getScheduledTask(Number(info.lastInsertRowid));
+    },
+    /** 部分更新;改 schedule 字段会触发 next_run_at 重算。 */
+    updateScheduledTask(id, patch) {
+        const task = this.getScheduledTask(id);
+        if (!task)
+            return undefined;
+        // schedule_kind / interval_sec / run_at 任一变化都重算 next_run_at
+        const scheduleChanged = patch.scheduleKind !== undefined ||
+            patch.intervalSec !== undefined ||
+            patch.runAt !== undefined;
+        const extraSets = [];
+        if (scheduleChanged) {
+            const kind = patch.scheduleKind ?? task.schedule_kind;
+            const intervalSec = patch.intervalSec !== undefined ? patch.intervalSec : task.interval_sec;
+            const runAt = patch.runAt !== undefined ? patch.runAt : task.run_at;
+            const now = Date.now();
+            const nextRunAt = kind === "once"
+                ? (runAt ?? now)
+                : now + (intervalSec ?? 0) * 1000;
+            extraSets.push({ column: "schedule_kind", value: kind }, { column: "interval_sec", value: intervalSec }, { column: "run_at", value: runAt }, { column: "next_run_at", value: nextRunAt });
+        }
+        const built = buildUpdate({
+            table: "scheduled_tasks",
+            sets: {
+                name: patch.name,
+                mode: patch.mode,
+                agent_name: patch.agentName,
+                prompt: patch.prompt,
+                enabled: patch.enabled !== undefined ? (patch.enabled ? 1 : 0) : undefined,
+                repeat_times: patch.repeatTimes,
+                handler_key: patch.handlerKey,
+                handler_payload: patch.handlerPayload,
+            },
+            where: "id = ?",
+            whereParams: [id],
+            updatedAt: "epoch",
+            extraSets,
+        });
+        if (!built)
+            return task;
+        this.db.prepare(built.sql).run(...built.params);
+        return this.getScheduledTask(id);
+    },
+    deleteScheduledTask(id) {
+        const result = this.db.prepare("DELETE FROM scheduled_tasks WHERE id = ?").run(id);
+        return result.changes > 0;
+    },
+    /** at-most-once 推进:先把 next_run_at 推到下一个未来时间点,再执行。 */
+    rescheduleTask(id, nextRunAt) {
+        this.db.prepare("UPDATE scheduled_tasks SET next_run_at = ?, updated_at = ? WHERE id = ?").run(nextRunAt, Date.now(), id);
+    },
+    /** 立刻触发:把 next_run_at 设为 now,下一个 tick 就跑。 */
+    triggerScheduledTask(id, now = Date.now()) {
+        const result = this.db.prepare("UPDATE scheduled_tasks SET next_run_at = ?, updated_at = ? WHERE id = ? AND enabled = 1").run(now, Date.now(), id);
+        return result.changes > 0;
+    },
+    /** 记录本次执行结果。repeat_count 由调度器计算后传入,这里直接覆写。
+     *  issueId=null 保留上一次 last_issue_id（用于 agent skip 的防堆积场景 —— 下一轮继续反查同一个 prev issue）;
+     *  传字符串才覆写。
+     *  没有显式 clear 路径 —— last_issue_id 一旦被 agent 模式写入就持续追踪到 disable 为止。 */
+    markScheduledTaskRun(id, runAt, status, error, issueId, repeatCount) {
+        if (issueId !== null) {
+            this.db.prepare(`
+        UPDATE scheduled_tasks SET
+          last_run_at = ?,
+          last_status = ?,
+          last_error = ?,
+          last_issue_id = ?,
+          repeat_count = ?,
+          updated_at = ?
+        WHERE id = ?
+      `).run(runAt, status, error, issueId, repeatCount, Date.now(), id);
+        }
+        else {
+            this.db.prepare(`
+        UPDATE scheduled_tasks SET
+          last_run_at = ?,
+          last_status = ?,
+          last_error = ?,
+          repeat_count = ?,
+          updated_at = ?
+        WHERE id = ?
+      `).run(runAt, status, error, repeatCount, Date.now(), id);
+        }
+    },
+    /** 一次性任务跑完,或 repeat_times 用尽,自动 enabled=0。 */
+    disableScheduledTask(id) {
+        this.db.prepare("UPDATE scheduled_tasks SET enabled = 0, updated_at = ? WHERE id = ?").run(Date.now(), id);
+    },
+};

package/dist/master/db/skills.js

@@ -0,0 +1,144 @@
+import { nowBeijing } from "../../shared/time.js";
+import { buildUpdate } from "./build-update.js";
+// ─── Methods ──────────────────────────────────────────────────────────────
+export const skillMethods = {
+    /** 全局 skill 索引(不含 content)。默认只返回 active。 */
+    listSkills(filter = {}) {
+        const { category, activeOnly = true } = filter;
+        const where = [];
+        const params = [];
+        if (activeOnly) {
+            where.push("active = 1");
+        }
+        if (category) {
+            where.push("category = ?");
+            params.push(category);
+        }
+        const whereClause = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+        return this.db.prepare(`SELECT id, name, description, category, source_type, created_by, created_at, view_count
+       FROM agent_skills ${whereClause} ORDER BY name ASC`).all(...params);
+    },
+    /** 关键词搜索(LIKE 匹配 name/description/category/content)。只搜 active。 */
+    searchSkills(keyword) {
+        const kw = `%${keyword}%`;
+        return this.db.prepare(`SELECT id, name, description, category, source_type, created_by, created_at, view_count
+       FROM agent_skills
+       WHERE active = 1 AND (name LIKE ? OR description LIKE ? OR category LIKE ? OR content LIKE ?)
+       ORDER BY view_count DESC, name ASC`).all(kw, kw, kw, kw);
+    },
+    /** 详情(content 全文)。view_count += 1。 */
+    getSkill(id) {
+        const row = this.db.prepare("SELECT * FROM agent_skills WHERE id = ?").get(id);
+        if (!row)
+            return undefined;
+        if (row.active === 1) {
+            this.db.prepare("UPDATE agent_skills SET view_count = view_count + 1, last_viewed_at = datetime('now') WHERE id = ?").run(id);
+        }
+        return row;
+    },
+    getSkillByName(name) {
+        return this.db.prepare("SELECT * FROM agent_skills WHERE name = ?").get(name);
+    },
+    createSkill(input) {
+        const now = nowBeijing();
+        this.db.prepare(`
+      INSERT INTO agent_skills (id, name, description, content, category, source_type, source_ref, created_by, created_at, updated_at, active, view_count, last_viewed_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, 0, NULL)
+    `).run(input.id, input.name, input.description, input.content, input.category ?? null, input.sourceType ?? "manual", input.sourceRef ?? null, input.createdBy, now, now);
+    },
+    updateSkill(id, fields) {
+        const built = buildUpdate({
+            table: "agent_skills",
+            sets: {
+                name: fields.name,
+                description: fields.description,
+                content: fields.content,
+                category: fields.category,
+            },
+            where: "id = ?",
+            whereParams: [id],
+            updatedAt: "datetime-now",
+        });
+        if (!built)
+            return false;
+        const result = this.db.prepare(built.sql).run(...built.params);
+        return result.changes > 0;
+    },
+    deactivateSkill(id) {
+        const result = this.db.prepare("UPDATE agent_skills SET active = 0, updated_at = datetime('now') WHERE id = ?").run(id);
+        return result.changes > 0;
+    },
+    // ─── 绑定关系 ───────────────────────────────────────────────────────────
+    /** 绑定 (group, agent, skill)。UNIQUE 冲突时 ignore。 */
+    bindSkill(input) {
+        const now = nowBeijing();
+        const result = this.db.prepare(`INSERT OR IGNORE INTO agent_skill_bindings (group_id, agent_name, skill_id, created_by, created_at)
+       VALUES (?, ?, ?, ?, ?)`).run(input.groupId, input.agentName, input.skillId, input.createdBy, now);
+        return result.changes > 0;
+    },
+    unbindSkill(input) {
+        const result = this.db.prepare("DELETE FROM agent_skill_bindings WHERE group_id = ? AND agent_name = ? AND skill_id = ?").run(input.groupId, input.agentName, input.skillId);
+        return result.changes > 0;
+    },
+    /** 绑定关系查询(群设置/工具箱管理用)。 */
+    listBindings(filter = {}) {
+        const where = [];
+        const params = [];
+        if (filter.groupId) {
+            where.push("group_id = ?");
+            params.push(filter.groupId);
+        }
+        if (filter.agentName) {
+            where.push("agent_name = ?");
+            params.push(filter.agentName);
+        }
+        if (filter.skillId) {
+            where.push("skill_id = ?");
+            params.push(filter.skillId);
+        }
+        const whereClause = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+        return this.db.prepare(`SELECT * FROM agent_skill_bindings ${whereClause} ORDER BY created_at DESC`).all(...params);
+    },
+    /** 该 agent 在该群绑定的 skill 数(供 prompt 极简指针)。只算 active skill。 */
+    countSkillsForAgent(groupId, agentName) {
+        const row = this.db.prepare(`SELECT COUNT(*) as n
+       FROM agent_skill_bindings b
+       JOIN agent_skills s ON s.id = b.skill_id
+       WHERE b.group_id = ? AND b.agent_name = ? AND s.active = 1`).get(groupId, agentName);
+        return row?.n ?? 0;
+    },
+    /** 该 agent 在该群绑定的 skill 索引(供 agent `rotom skill mine` 拉取)。 */
+    listSkillsForAgent(groupId, agentName) {
+        return this.db.prepare(`SELECT s.id, s.name, s.description, s.category, s.source_type, s.created_by, s.created_at, s.view_count
+       FROM agent_skill_bindings b
+       JOIN agent_skills s ON s.id = b.skill_id
+       WHERE b.group_id = ? AND b.agent_name = ? AND s.active = 1
+       ORDER BY s.name ASC`).all(groupId, agentName);
+    },
+    // ─── playbook memory → skill 沉淀 ───────────────────────────────────────
+    /** 把一条 playbook memory 升级成 skill。
+     *  memory.value → skill.content,memory.key → skill.name(或显式),
+     *  memory.summary → skill.description(或显式)。
+     *  memory 保留 active=1,skill.source_ref 指向 memory_id。 */
+    promoteMemoryToSkill(memoryId, opts) {
+        const mem = this.db.prepare("SELECT * FROM agent_memory WHERE id = ?").get(memoryId);
+        if (!mem)
+            throw new Error(`memory ${memoryId} not found`);
+        const name = (opts.name ?? mem.key).trim();
+        if (!name)
+            throw new Error("skill name 不能为空(memory.key 为空且未传 --name)");
+        const description = (opts.description ?? mem.summary ?? mem.value.slice(0, 120)).trim();
+        const skillId = randomUUIDLike();
+        const now = nowBeijing();
+        this.db.prepare(`
+      INSERT INTO agent_skills (id, name, description, content, category, source_type, source_ref, created_by, created_at, updated_at, active, view_count, last_viewed_at)
+      VALUES (?, ?, ?, ?, 'playbook', 'promoted', ?, ?, ?, ?, 1, 0, NULL)
+    `).run(skillId, name, description, mem.value, memoryId, opts.createdBy, now, now);
+        return { skillId, name };
+    },
+};
+/** 生成 UUID-like ID(避免引入 crypto 依赖到 db 层,用 Date+random 兜底)。
+ *  调用方一般用 randomUUID;promote 路径在 db 层内自调,用此兜底。 */
+function randomUUIDLike() {
+    return `sk_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}

package/dist/master/db/team.js

@@ -0,0 +1,88 @@
+/**
+ * team / team_peers / human_membership CRUD。
+ *
+ * - team 表存"本机 master 加入了哪些团队"(本机视角,每行一个团队)
+ * - team_peers 存"团队里有哪些其他 master"(协调侧权威 + member 侧缓存)
+ * - human_membership 存"本机真人加入了哪些团队"
+ *
+ * agent_visibility 在 ./agent-visibility.ts(单独模块,方法较多)。
+ *
+ * 历史命名:Phase 2 叫 department,migration 058 改名 team。所有 department_id
+ * 列同步改为 team_id。底层 federation 协议字段 departmentId → teamId。
+ */
+import { buildUpdate } from "./build-update.js";
+export const teamMethods = {
+    // ─── team ──────────────────────────────────────────────────────────────
+    listTeams() {
+        return this.db.prepare("SELECT * FROM team ORDER BY name").all();
+    },
+    getTeam(id) {
+        return this.db.prepare("SELECT * FROM team WHERE id = ?").get(id);
+    },
+    insertTeam(input) {
+        this.db.prepare("INSERT INTO team (id, name, description, my_role, coord_endpoints) VALUES (?, ?, ?, ?, ?)").run(input.id, input.name, input.description ?? null, input.my_role, input.coord_endpoints);
+    },
+    updateTeamMeta(id, meta) {
+        const built = buildUpdate({
+            table: "team",
+            sets: { name: meta.name, description: meta.description },
+            where: "id = ?",
+            whereParams: [id],
+            updatedAt: false,
+        });
+        if (built)
+            this.db.prepare(built.sql).run(...built.params);
+    },
+    deleteTeam(id) {
+        this.db.prepare("DELETE FROM team WHERE id = ?").run(id);
+    },
+    // ─── team_peers ────────────────────────────────────────────────────────
+    listPeers(teamId) {
+        return this.db.prepare("SELECT * FROM team_peers WHERE team_id = ? ORDER BY hostname").all(teamId);
+    },
+    getPeer(teamId, masterId) {
+        return this.db.prepare("SELECT * FROM team_peers WHERE team_id = ? AND master_id = ?").get(teamId, masterId);
+    },
+    /** hostname 冲突检测:团队内同 hostname 是否已有 peer */
+    findPeerByHostname(teamId, hostname) {
+        return this.db.prepare("SELECT * FROM team_peers WHERE team_id = ? AND hostname = ?").get(teamId, hostname);
+    },
+    upsertPeer(input) {
+        const existing = this.db.prepare("SELECT 1 FROM team_peers WHERE team_id = ? AND master_id = ?").get(input.team_id, input.master_id);
+        if (existing) {
+            this.db.prepare(`
+        UPDATE team_peers SET
+          hostname = ?,
+          endpoint = COALESCE(?, endpoint),
+          role = ?,
+          last_seen_at = datetime('now')
+        WHERE team_id = ? AND master_id = ?
+      `).run(input.hostname, input.endpoint ?? null, input.role, input.team_id, input.master_id);
+            return;
+        }
+        this.db.prepare(`
+      INSERT INTO team_peers (team_id, master_id, hostname, endpoint, role, last_seen_at)
+      VALUES (?, ?, ?, ?, ?, datetime('now'))
+    `).run(input.team_id, input.master_id, input.hostname, input.endpoint ?? null, input.role);
+    },
+    touchPeerHeartbeat(teamId, masterId) {
+        this.db.prepare("UPDATE team_peers SET last_seen_at = datetime('now') WHERE team_id = ? AND master_id = ?").run(teamId, masterId);
+    },
+    deletePeer(teamId, masterId) {
+        this.db.prepare("DELETE FROM team_peers WHERE team_id = ? AND master_id = ?").run(teamId, masterId);
+    },
+    /** member 离开团队时清掉所有本地缓存的 peer */
+    clearPeers(teamId) {
+        this.db.prepare("DELETE FROM team_peers WHERE team_id = ?").run(teamId);
+    },
+    // ─── human_membership ──────────────────────────────────────────────────
+    listHumanMemberships(agentId) {
+        return this.db.prepare("SELECT * FROM human_membership WHERE agent_id = ? ORDER BY joined_at").all(agentId);
+    },
+    addHumanMembership(agentId, teamId) {
+        this.db.prepare("INSERT OR IGNORE INTO human_membership (agent_id, team_id) VALUES (?, ?)").run(agentId, teamId);
+    },
+    removeHumanMembership(agentId, teamId) {
+        this.db.prepare("DELETE FROM human_membership WHERE agent_id = ? AND team_id = ?").run(agentId, teamId);
+    },
+};

package/dist/master/db/types.js

@@ -0,0 +1,10 @@
+/**
+ * Row type definitions for the mesh SQLite database.
+ *
+ * Each interface mirrors the SQLite column names exactly — the runtime
+ * layer in `db/internal.ts` maps SELECT results onto these types.
+ *
+ * Kept in its own module so consumers (api/, executor/worker.ts, tests,
+ * dashboard) can import row types without dragging in better-sqlite3.
+ */
+export {};

package/dist/master/db.js

@@ -0,0 +1,12 @@
+/**
+ * Backwards-compatible facade for the database layer.
+ *
+ * The implementation has moved into `./db/`:
+ *   • `./db/types.ts`   — Row interfaces (no better-sqlite3 import)
+ *   • `./db/internal.ts` — MeshDb runtime class (currently still monolithic;
+ *                          method-by-method extraction lands in follow-up PRs)
+ *   • `./db/index.ts`   — Public surface
+ *
+ * Existing callers (`import { MeshDb } from "../db.js"`) continue to work.
+ */
+export * from "./db/index.js";

package/dist/master/embedded.js

@@ -0,0 +1,133 @@
+/**
+ * Digital Employee Mesh — Embedded Master
+ *
+ * Starts Master HTTP+WS server programmatically (non-standalone).
+ * Used by startEmbeddedMaster() for in-process Master startup.
+ *
+ * Unlike server.ts (standalone entry), this does NOT call process.exit()
+ * or listen for SIGINT/SIGTERM — the host process manages lifecycle.
+ */
+import express from "express";
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { MeshDb } from "./db.js";
+import { AuthService } from "./auth.js";
+import { WSHub } from "./ws-hub.js";
+import { Router } from "./router.js";
+import { OfflineQueue } from "./offline-queue.js";
+import { createApi } from "./api/index.js";
+import { createLogger, enableFileLogging, closeFileLogging } from "../shared/logger.js";
+import { ShareTokenStore } from "./share-tokens.js";
+import { getMasterIdentity } from "./federation/identity.js";
+import { runOpcBootstrap, ensureLocalExecutor } from "./opc-bootstrap.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+export async function startEmbeddedMaster(config, logger = createLogger("mesh-master")) {
+    const host = config.host ?? "0.0.0.0";
+    // Ensure data directory exists
+    const dataDir = path.resolve(config.dataDir);
+    if (!fs.existsSync(dataDir)) {
+        fs.mkdirSync(dataDir, { recursive: true });
+    }
+    // Enable daily-rotated file logging under data directory
+    enableFileLogging(path.join(dataDir, "logs"));
+    // Database
+    const db = new MeshDb(path.join(dataDir, "mesh.db"));
+    // OPC bootstrap — 与命令行入口一致:解析 master 身份 + 首次启动建默认 agent/group。
+    // 嵌入式场景失败(hostname 校验等)也直接抛错 —— 身份不能没有。
+    const identity = getMasterIdentity({ rotomHome: dataDir });
+    const opcResult = runOpcBootstrap(db, identity);
+    // Reset stale online status from previous run
+    const resetCount = db.resetAllOnline();
+    if (resetCount > 0) {
+        logger.info(`[mesh-master] Reset ${resetCount} stale online agent(s) to offline`);
+    }
+    // Services — single AuthService shared between WSHub and API
+    const auth = new AuthService(db);
+    const offlineQueue = new OfflineQueue(db);
+    const router = new Router(db, logger);
+    const shareTokens = new ShareTokenStore();
+    // HTTP + Express
+    const app = express();
+    app.use(express.json({ limit: "1mb" }));
+    // Create HTTP server first — needed by WSHub
+    const httpServer = http.createServer(app);
+    // WebSocket Hub — shares auth service with API
+    const hub = new WSHub(httpServer, db, auth, router, offlineQueue, logger);
+    hub.start();
+    // REST API — shares auth service and hub with WSHub
+    app.use("/api", createApi(db, auth, hub, router, config.port, shareTokens));
+    // Dashboard static files
+    // Prod (running from dist/master): build:master copies React dashboard
+    // build output to dist/master/dashboard.
+    // Dev (running src/master via tsx): fall back to packages/dashboard build
+    // output — run `pnpm dashboard:build` first.
+    let dashboardDir = path.resolve(__dirname, "dashboard");
+    if (!fs.existsSync(dashboardDir)) {
+        dashboardDir = path.resolve(__dirname, "../../packages/dashboard/dist/src/master/dashboard");
+    }
+    if (fs.existsSync(dashboardDir)) {
+        app.use("/dashboard", express.static(dashboardDir));
+        // SPA fallback — serve index.html for all /dashboard/* routes (client-side routing)
+        app.get("/dashboard/*", (_req, res) => {
+            res.sendFile(path.join(dashboardDir, "index.html"));
+        });
+    }
+    // Root redirect
+    app.get("/", (_req, res) => res.redirect("/dashboard"));
+    // Health check (unauthenticated — for load balancer probes)
+    app.get("/health", (_req, res) => {
+        res.json({ status: "ok", ...db.stats() });
+    });
+    // Listen
+    await new Promise((resolve, reject) => {
+        httpServer.on("error", (err) => {
+            if (err.code === "EADDRINUSE") {
+                reject(new Error(`Port ${config.port} already in use`));
+            }
+            else {
+                reject(err);
+            }
+        });
+        httpServer.listen(config.port, host, () => {
+            logger.info(`[mesh-master] Embedded master running on http://${host}:${config.port}`);
+            logger.info(`[mesh-master] Dashboard: http://localhost:${config.port}/dashboard`);
+            resolve();
+        });
+    });
+    // 自动 spawn 本机 executor(可选,默认关闭)。嵌入式场景通常 host 自己管 executor。
+    let localExecutor = null;
+    if (config.autoSpawnExecutor && opcResult.defaultAgent) {
+        localExecutor = ensureLocalExecutor({
+            rotomHome: dataDir,
+            masterPort: config.port,
+            defaultAgentName: opcResult.defaultAgent.name,
+        });
+    }
+    // Read or ensure API key for return value
+    const apiKey = db.getConfig("api_key") || "";
+    // Return handle for lifecycle management
+    return {
+        port: config.port,
+        db,
+        hub,
+        apiKey,
+        stop: async () => {
+            logger.info("[mesh-master] Embedded master stopping...");
+            localExecutor?.stop();
+            hub.stop();
+            router.stop();
+            db.close();
+            await new Promise((resolve) => {
+                httpServer.close(() => resolve());
+                setTimeout(resolve, 3000); // Force after 3s
+            });
+            closeFileLogging();
+            logger.info("[mesh-master] Embedded master stopped.");
+        },
+    };
+}