@smart-tinker/kayla 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 smart-tinker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,34 @@
+# Kayla
+
+Kayla is a Telegram bot service that orchestrates a locally installed Claude Code CLI (`claude`).
+
+## Quick start (local)
+
+1) Install dependencies:
+```bash
+npm install
+```
+
+2) Configure:
+- `config/config.yaml` (set `telegram.allowlist.user_ids`)
+- export Telegram token:
+```bash
+export KAYLA_TELEGRAM_TOKEN="..."
+export KAYLA_CONFIG="config/config.yaml"
+```
+
+3) Run:
+```bash
+npm run dev
+```
+
+## Verification
+```bash
+npm test
+npm run typecheck
+npm run lint
+npm run build
+```
+
+More details: `docs/`.
+

package/dist/bot/bot.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildBot = buildBot;
+const grammy_1 = require("grammy");
+const handlers_1 = require("./handlers");
+const kayla_1 = require("../core/kayla");
+function buildBot(deps) {
+    const bot = new grammy_1.Bot(deps.config.telegram.token);
+    const service = new kayla_1.KaylaService({ cfg: deps.config, logger: deps.logger, storage: deps.storage, api: bot.api });
+    (0, handlers_1.registerHandlers)(bot, { ...deps, service });
+    return bot;
+}

package/dist/bot/handlers.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerHandlers = registerHandlers;
+function registerHandlers(bot, deps) {
+    bot.command("start", async (ctx) => {
+        if (ctx.chat.type !== "private")
+            return;
+        const userId = ctx.from?.id;
+        if (!userId)
+            return;
+        await deps.service.handleStartWithUser(ctx.chat.id, userId);
+    });
+    bot.command("status", async (ctx) => {
+        if (ctx.chat.type !== "private")
+            return;
+        const userId = ctx.from?.id;
+        if (!userId)
+            return;
+        if (!deps.storage.isAllowedUser("telegram", String(userId)))
+            return;
+        await deps.service.handleStatus(ctx.chat.id);
+    });
+    bot.command("new", async (ctx) => {
+        if (ctx.chat.type !== "private")
+            return;
+        const userId = ctx.from?.id;
+        if (!userId)
+            return;
+        if (!deps.storage.isAllowedUser("telegram", String(userId)))
+            return;
+        await deps.service.handleNew(ctx.chat.id, userId);
+    });
+    bot.command("reset", async (ctx) => {
+        if (ctx.chat.type !== "private")
+            return;
+        const userId = ctx.from?.id;
+        if (!userId)
+            return;
+        if (!deps.storage.isAllowedUser("telegram", String(userId)))
+            return;
+        const text = ctx.message?.text ?? "";
+        const confirm = text.trim().toLowerCase() === "/reset yes";
+        await deps.service.handleReset(ctx.chat.id, userId, confirm);
+    });
+    bot.command("cancel", async (ctx) => {
+        if (ctx.chat.type !== "private")
+            return;
+        const userId = ctx.from?.id;
+        if (!userId)
+            return;
+        if (!deps.storage.isAllowedUser("telegram", String(userId)))
+            return;
+        await deps.service.handleCancel(ctx.chat.id);
+    });
+    bot.on("message:text", async (ctx) => {
+        if (ctx.chat.type !== "private")
+            return;
+        const userId = ctx.from?.id;
+        if (!userId)
+            return;
+        if (!deps.storage.isAllowedUser("telegram", String(userId)))
+            return;
+        const text = ctx.message.text;
+        // Commands are handled separately.
+        if (text.startsWith("/"))
+            return;
+        await deps.service.enqueueUserMessage(ctx.chat.id, userId, text);
+    });
+}

package/dist/cli.js

@@ -0,0 +1,188 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_child_process_1 = require("node:child_process");
+const promises_1 = __importDefault(require("node:readline/promises"));
+const storage_1 = require("./core/storage");
+const service_1 = require("./service");
+const setup_1 = require("./core/setup");
+const doctor_1 = require("./core/doctor");
+function usage() {
+    return [
+        "Usage:",
+        "  kayla run",
+        "  kayla setup",
+        "  kayla doctor",
+        "  kayla telegram users approve <code>",
+        "  kayla telegram users pending",
+        "  kayla telegram users list"
+    ].join("\n");
+}
+function fail(msg, code = 1) {
+    console.error(msg);
+    process.exit(code);
+}
+function createPrompt() {
+    const rl = promises_1.default.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    const askText = async (message) => rl.question(message);
+    const askSecret = async (message) => {
+        // Best-effort: hide user input for secrets while still showing the prompt.
+        process.stdout.write(message);
+        const anyRl = rl;
+        const prev = anyRl._writeToOutput;
+        anyRl._writeToOutput = () => { };
+        try {
+            const ans = await rl.question("");
+            process.stdout.write("\n");
+            return ans;
+        }
+        finally {
+            anyRl._writeToOutput = prev;
+        }
+    };
+    return {
+        prompt: async (q) => (q.kind === "secret" ? askSecret(q.message) : askText(q.message)),
+        close: () => rl.close()
+    };
+}
+async function main(argv) {
+    const args = argv.slice(2);
+    if (args.length < 1)
+        fail(usage(), 2);
+    const top = args[0];
+    if (top === "run") {
+        await (0, service_1.runService)();
+        return;
+    }
+    if (top === "setup") {
+        const home = node_os_1.default.homedir();
+        const username = node_os_1.default.userInfo().username;
+        const paths = (0, setup_1.computeDefaultSetupPaths)(home);
+        (0, setup_1.ensureXdgDirs)(paths);
+        if (!node_fs_1.default.existsSync(paths.configPath)) {
+            const isTty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+            const p = isTty ? createPrompt() : null;
+            try {
+                const res = await (0, setup_1.bootstrapConfig)(paths, process.env, { isTty, prompt: p?.prompt });
+                (0, setup_1.writeConfigIfMissing)(paths.configPath, res.config);
+            }
+            finally {
+                p?.close();
+            }
+        }
+        // Validate config exists and has required fields.
+        (0, setup_1.ensureConfigValidOrThrow)(paths.configPath);
+        // Render unit template.
+        const templatePath = node_path_1.default.join(__dirname, "..", "scripts", "systemd", "kayla.service.template");
+        const tpl = node_fs_1.default.readFileSync(templatePath, "utf8");
+        const nodePath = process.execPath;
+        const cliPath = node_fs_1.default.realpathSync(process.argv[1]);
+        const execStart = `${nodePath} ${cliPath} run`;
+        const unitPath = "/etc/systemd/system/kayla.service";
+        const rendered = (0, setup_1.renderSystemdTemplate)(tpl, {
+            KAYLA_USER: username,
+            KAYLA_HOME: home,
+            KAYLA_CONFIG: paths.configPath,
+            KAYLA_PATH: (0, setup_1.ensurePathHasLocalBin)(home, process.env.PATH),
+            KAYLA_EXEC_START: execStart
+        });
+        const tmp = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "kayla-unit-"));
+        const tmpUnit = node_path_1.default.join(tmp, "kayla.service");
+        node_fs_1.default.writeFileSync(tmpUnit, rendered);
+        try {
+            (0, node_child_process_1.execFileSync)("sudo", ["install", "-m", "0644", tmpUnit, unitPath], { stdio: "inherit" });
+            (0, node_child_process_1.execFileSync)("sudo", ["systemctl", "daemon-reload"], { stdio: "inherit" });
+            (0, node_child_process_1.execFileSync)("sudo", ["systemctl", "enable", "--now", "kayla.service"], { stdio: "inherit" });
+            console.log("Kayla service installed and started: kayla.service");
+        }
+        finally {
+            try {
+                node_fs_1.default.rmSync(tmp, { recursive: true, force: true });
+            }
+            catch {
+                // ignore cleanup errors
+            }
+        }
+        return;
+    }
+    if (top === "doctor") {
+        const cfgPath = (0, doctor_1.resolveConfigPath)(process.env);
+        const checks = [...(0, doctor_1.checkConfig)(cfgPath)];
+        // Best-effort runtime dirs: prefer config values; otherwise default to XDG paths.
+        const home = node_os_1.default.homedir();
+        const paths = (0, setup_1.computeDefaultSetupPaths)(home);
+        const cfgInfo = (0, doctor_1.readDoctorConfigInfo)(cfgPath);
+        const dataDir = cfgInfo.runtime?.dataDir ?? paths.dataDir;
+        const workspacesDir = cfgInfo.runtime?.workspacesDir ?? node_path_1.default.join(dataDir, "workspaces");
+        const uploadsDir = cfgInfo.runtime?.uploadsDir ?? node_path_1.default.join(dataDir, "uploads");
+        const runtime = { dataDir, workspacesDir, uploadsDir };
+        checks.push(...(0, doctor_1.checkDirs)(runtime));
+        checks.push((0, doctor_1.checkSqlite)(runtime.dataDir));
+        checks.push((0, doctor_1.checkClaude)(cfgInfo.claudeBinary ?? "claude", process.env));
+        let ok = true;
+        for (const c of checks) {
+            if (!c.ok)
+                ok = false;
+            const tag = c.ok ? "OK" : "FAIL";
+            console.log(`[${tag}] ${c.summary}`);
+            if (!c.ok && c.details)
+                console.log(`  ${c.details}`);
+        }
+        if (!ok)
+            process.exitCode = 2;
+        return;
+    }
+    if (top !== "telegram")
+        fail(`Unsupported command: ${top}\n\n${usage()}`, 2);
+    if (args.length < 3)
+        fail(usage(), 2);
+    const channel = args[0];
+    const resource = args[1];
+    const action = args[2];
+    if (channel !== "telegram")
+        fail(`Unsupported channel: ${channel}\n\n${usage()}`, 2);
+    if (resource !== "users")
+        fail(`Unsupported resource: ${resource}\n\n${usage()}`, 2);
+    const dataDir = (0, doctor_1.resolveRuntimeDataDir)(process.env);
+    const storage = (0, storage_1.openStorage)(dataDir);
+    if (action === "approve") {
+        const code = args[3];
+        if (!code)
+            fail("Missing <code>\n\n" + usage(), 2);
+        const res = storage.approveOnboardingCode("telegram", String(code), "cli");
+        console.log(`Approved telegram user_id=${res.userId} (chat_id=${res.chatId})`);
+        return;
+    }
+    if (action === "pending") {
+        const rows = storage.listPendingCodes("telegram");
+        if (rows.length === 0) {
+            console.log("No pending codes.");
+            return;
+        }
+        for (const r of rows) {
+            console.log(`${r.code}\tuser_id=${r.userId}\tchat_id=${r.chatId}\texpires_at=${new Date(r.expiresAt).toISOString()}`);
+        }
+        return;
+    }
+    if (action === "list") {
+        const rows = storage.listAllowedUsers("telegram");
+        if (rows.length === 0) {
+            console.log("No allowlisted users.");
+            return;
+        }
+        for (const r of rows) {
+            console.log(`${r.userId}\tcreated_at=${new Date(r.createdAt).toISOString()}\tadded_by=${r.addedBy ?? ""}`);
+        }
+        return;
+    }
+    fail(`Unknown action: ${action}\n\n${usage()}`, 2);
+}
+main(process.argv).catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    fail(msg, 1);
+});

package/dist/core/config.js

@@ -0,0 +1,314 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const yaml_1 = __importDefault(require("yaml"));
+function defaultConfigPath(env) {
+    if (env.KAYLA_CONFIG && env.KAYLA_CONFIG.trim().length)
+        return env.KAYLA_CONFIG.trim();
+    const home = env.HOME?.trim();
+    if (home && home.length)
+        return node_path_1.default.join(home, ".config", "kayla", "config.yaml");
+    return node_path_1.default.join(process.cwd(), "config", "config.yaml");
+}
+function defaultDataDir(env) {
+    const home = env.HOME?.trim();
+    if (home && home.length)
+        return node_path_1.default.join(home, ".local", "share", "kayla");
+    return ".kayla-data";
+}
+const DEFAULT_CONFIG = {
+    telegram: {
+        token: "",
+        mode: "polling",
+        admin_user_ids: [],
+        allowlist: { user_ids: [] }
+    },
+    runtime: {
+        data_dir: "",
+        workspaces_dir: "",
+        uploads_dir: ""
+    },
+    claude: {
+        binary: "claude",
+        default_model: "",
+        max_turns: 10,
+        timeout_seconds: 900,
+        streaming: true,
+        output_format: "stream-json",
+        tools: "default",
+        allowed_tools: [],
+        disallowed_tools: [],
+        mcp: { strict: false }
+    },
+    jobs: {
+        per_chat_concurrency: 1,
+        global_concurrency: 2,
+        queue_size_per_chat: 20
+    },
+    logging: {
+        level: "info",
+        json: true
+    }
+};
+function isRecord(v) {
+    return !!v && typeof v === "object" && !Array.isArray(v);
+}
+function optionalPath(v) {
+    if (typeof v !== "string")
+        return undefined;
+    const trimmed = v.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function optionalString(v) {
+    if (typeof v !== "string")
+        return undefined;
+    const trimmed = v.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function parseBool(v) {
+    const s = v.trim().toLowerCase();
+    if (s === "1" || s === "true" || s === "yes" || s === "on")
+        return true;
+    if (s === "0" || s === "false" || s === "no" || s === "off")
+        return false;
+    throw new Error(`Invalid boolean env value: ${v}`);
+}
+function parseNumber(v) {
+    const n = Number(v.trim());
+    if (!Number.isFinite(n))
+        throw new Error(`Invalid number env value: ${v}`);
+    return n;
+}
+function parseCsv(v) {
+    const raw = v.split(",").map((x) => x.trim()).filter((x) => x.length > 0);
+    return raw;
+}
+function parseCsvNumbers(v) {
+    return parseCsv(v).map((x) => {
+        const n = Number(x);
+        if (!Number.isFinite(n))
+            throw new Error(`Invalid number in CSV: ${x}`);
+        return n;
+    });
+}
+function readYamlIfExists(p) {
+    try {
+        if (!node_fs_1.default.existsSync(p))
+            return undefined;
+        const raw = node_fs_1.default.readFileSync(p, "utf8");
+        return yaml_1.default.parse(raw);
+    }
+    catch {
+        throw new Error(`Failed to read config file: ${p}`);
+    }
+}
+function applyEnv(cfg, env) {
+    const get = (k) => env[k];
+    // Telegram
+    const t = get("KAYLA_TELEGRAM_TOKEN");
+    if (t && t.trim().length)
+        cfg.telegram.token = t.trim();
+    const mode = get("KAYLA_TELEGRAM_MODE");
+    if (mode && mode.trim().length)
+        cfg.telegram.mode = mode.trim() === "webhook" ? "webhook" : "polling";
+    const allowCsv = get("KAYLA_TELEGRAM_ALLOWLIST_USER_IDS");
+    if (allowCsv && allowCsv.trim().length)
+        cfg.telegram.allowlist.user_ids = parseCsvNumbers(allowCsv);
+    const adminCsv = get("KAYLA_TELEGRAM_ADMIN_USER_IDS");
+    if (adminCsv && adminCsv.trim().length)
+        cfg.telegram.admin_user_ids = parseCsvNumbers(adminCsv);
+    // Runtime
+    const dataDir = get("KAYLA_RUNTIME_DATA_DIR");
+    const wDir = get("KAYLA_RUNTIME_WORKSPACES_DIR");
+    const uDir = get("KAYLA_RUNTIME_UPLOADS_DIR");
+    const dataDirSet = !!(dataDir && dataDir.trim().length);
+    const wDirSet = !!(wDir && wDir.trim().length);
+    const uDirSet = !!(uDir && uDir.trim().length);
+    if (dataDirSet)
+        cfg.runtime.data_dir = dataDir.trim();
+    if (wDirSet)
+        cfg.runtime.workspaces_dir = wDir.trim();
+    if (uDirSet)
+        cfg.runtime.uploads_dir = uDir.trim();
+    if (dataDirSet && !wDirSet)
+        cfg.runtime.workspaces_dir = node_path_1.default.join(cfg.runtime.data_dir, "workspaces");
+    if (dataDirSet && !uDirSet)
+        cfg.runtime.uploads_dir = node_path_1.default.join(cfg.runtime.data_dir, "uploads");
+    // Claude (no backend/auth settings, only runner-level knobs)
+    const cb = get("KAYLA_CLAUDE_BINARY");
+    if (cb && cb.trim().length)
+        cfg.claude.binary = cb.trim();
+    const dm = get("KAYLA_CLAUDE_DEFAULT_MODEL");
+    if (dm && dm.trim().length)
+        cfg.claude.default_model = dm.trim();
+    const mt = get("KAYLA_CLAUDE_MAX_TURNS");
+    if (mt && mt.trim().length)
+        cfg.claude.max_turns = parseNumber(mt);
+    const ts = get("KAYLA_CLAUDE_TIMEOUT_SECONDS");
+    if (ts && ts.trim().length)
+        cfg.claude.timeout_seconds = parseNumber(ts);
+    const st = get("KAYLA_CLAUDE_STREAMING");
+    if (st && st.trim().length)
+        cfg.claude.streaming = parseBool(st);
+    const tools = get("KAYLA_CLAUDE_TOOLS");
+    if (tools && tools.trim().length)
+        cfg.claude.tools = tools.trim();
+    const at = get("KAYLA_CLAUDE_ALLOWED_TOOLS");
+    if (at && at.trim().length)
+        cfg.claude.allowed_tools = parseCsv(at);
+    const dt = get("KAYLA_CLAUDE_DISALLOWED_TOOLS");
+    if (dt && dt.trim().length)
+        cfg.claude.disallowed_tools = parseCsv(dt);
+    const ap = get("KAYLA_CLAUDE_APPEND_SYSTEM_PROMPT_FILE");
+    if (ap && ap.trim().length)
+        cfg.claude.append_system_prompt_file = ap.trim();
+    const af = get("KAYLA_CLAUDE_AGENTS_FILE");
+    if (af && af.trim().length)
+        cfg.claude.agents_file = af.trim();
+    const mcpStrict = get("KAYLA_CLAUDE_MCP_STRICT");
+    if (mcpStrict && mcpStrict.trim().length) {
+        cfg.claude.mcp = cfg.claude.mcp ?? { strict: false };
+        cfg.claude.mcp.strict = parseBool(mcpStrict);
+    }
+    const mcpCfg = get("KAYLA_CLAUDE_MCP_CONFIG_FILE");
+    if (mcpCfg && mcpCfg.trim().length) {
+        cfg.claude.mcp = cfg.claude.mcp ?? { strict: false };
+        cfg.claude.mcp.config_file = mcpCfg.trim();
+    }
+    // Jobs
+    const pcc = get("KAYLA_JOBS_PER_CHAT_CONCURRENCY");
+    if (pcc && pcc.trim().length)
+        cfg.jobs.per_chat_concurrency = parseNumber(pcc);
+    const gcc = get("KAYLA_JOBS_GLOBAL_CONCURRENCY");
+    if (gcc && gcc.trim().length)
+        cfg.jobs.global_concurrency = parseNumber(gcc);
+    const qsz = get("KAYLA_JOBS_QUEUE_SIZE_PER_CHAT");
+    if (qsz && qsz.trim().length)
+        cfg.jobs.queue_size_per_chat = parseNumber(qsz);
+    // Logging
+    const lvl = get("KAYLA_LOGGING_LEVEL");
+    if (lvl && lvl.trim().length)
+        cfg.logging.level = lvl.trim();
+    const js = get("KAYLA_LOGGING_JSON");
+    if (js && js.trim().length)
+        cfg.logging.json = parseBool(js);
+}
+function applyYaml(cfg, doc) {
+    if (!isRecord(doc))
+        return;
+    const t = isRecord(doc.telegram) ? doc.telegram : undefined;
+    if (t) {
+        const token = optionalString(t.token);
+        if (token)
+            cfg.telegram.token = token;
+        const mode = optionalString(t.mode);
+        if (mode)
+            cfg.telegram.mode = mode === "webhook" ? "webhook" : "polling";
+        if (isRecord(t.allowlist) && Array.isArray(t.allowlist.user_ids) && t.allowlist.user_ids.every((x) => typeof x === "number")) {
+            cfg.telegram.allowlist.user_ids = t.allowlist.user_ids;
+        }
+        if (Array.isArray(t.admin_user_ids) && t.admin_user_ids.every((x) => typeof x === "number")) {
+            cfg.telegram.admin_user_ids = t.admin_user_ids;
+        }
+    }
+    const r = isRecord(doc.runtime) ? doc.runtime : undefined;
+    if (r) {
+        const dd = optionalString(r.data_dir);
+        const wd = optionalString(r.workspaces_dir);
+        const ud = optionalString(r.uploads_dir);
+        if (dd)
+            cfg.runtime.data_dir = dd;
+        if (wd)
+            cfg.runtime.workspaces_dir = wd;
+        if (ud)
+            cfg.runtime.uploads_dir = ud;
+        if (dd && !wd)
+            cfg.runtime.workspaces_dir = node_path_1.default.join(cfg.runtime.data_dir, "workspaces");
+        if (dd && !ud)
+            cfg.runtime.uploads_dir = node_path_1.default.join(cfg.runtime.data_dir, "uploads");
+    }
+    const c = isRecord(doc.claude) ? doc.claude : undefined;
+    if (c) {
+        const bin = optionalString(c.binary);
+        if (bin)
+            cfg.claude.binary = bin;
+        const dm = optionalString(c.default_model);
+        if (dm)
+            cfg.claude.default_model = dm;
+        if (typeof c.max_turns === "number")
+            cfg.claude.max_turns = c.max_turns;
+        if (typeof c.timeout_seconds === "number")
+            cfg.claude.timeout_seconds = c.timeout_seconds;
+        if (typeof c.streaming === "boolean")
+            cfg.claude.streaming = c.streaming;
+        const tools = optionalString(c.tools);
+        if (tools)
+            cfg.claude.tools = tools;
+        if (Array.isArray(c.allowed_tools) && c.allowed_tools.every((x) => typeof x === "string"))
+            cfg.claude.allowed_tools = c.allowed_tools;
+        if (Array.isArray(c.disallowed_tools) && c.disallowed_tools.every((x) => typeof x === "string"))
+            cfg.claude.disallowed_tools = c.disallowed_tools;
+        cfg.claude.append_system_prompt_file = optionalPath(c.append_system_prompt_file) ?? cfg.claude.append_system_prompt_file;
+        cfg.claude.agents_file = optionalPath(c.agents_file) ?? cfg.claude.agents_file;
+        if (isRecord(c.mcp)) {
+            cfg.claude.mcp = cfg.claude.mcp ?? { strict: false };
+            if (typeof c.mcp.strict === "boolean")
+                cfg.claude.mcp.strict = c.mcp.strict;
+            cfg.claude.mcp.config_file = optionalPath(c.mcp.config_file) ?? cfg.claude.mcp.config_file;
+        }
+    }
+    const j = isRecord(doc.jobs) ? doc.jobs : undefined;
+    if (j) {
+        if (typeof j.per_chat_concurrency === "number")
+            cfg.jobs.per_chat_concurrency = j.per_chat_concurrency;
+        if (typeof j.global_concurrency === "number")
+            cfg.jobs.global_concurrency = j.global_concurrency;
+        if (typeof j.queue_size_per_chat === "number")
+            cfg.jobs.queue_size_per_chat = j.queue_size_per_chat;
+    }
+    const l = isRecord(doc.logging) ? doc.logging : undefined;
+    if (l) {
+        const level = optionalString(l.level);
+        if (level)
+            cfg.logging.level = level;
+        if (typeof l.json === "boolean")
+            cfg.logging.json = l.json;
+    }
+}
+function validate(cfg) {
+    if (cfg.jobs.per_chat_concurrency !== 1)
+        throw new Error("Invalid config: jobs.per_chat_concurrency must be 1 (MVP constraint)");
+    if (cfg.jobs.global_concurrency < 1)
+        throw new Error("Invalid config: jobs.global_concurrency must be >= 1");
+    // Derive output_format from streaming by default (kept for compatibility).
+    cfg.claude.output_format = cfg.claude.streaming ? "stream-json" : "json";
+    if (!cfg.telegram.token || cfg.telegram.token.trim().length === 0) {
+        throw new Error("Missing telegram token: set telegram.token in config.yaml or KAYLA_TELEGRAM_TOKEN in env");
+    }
+    if (cfg.telegram.admin_user_ids.length === 0 && cfg.telegram.allowlist.user_ids.length === 0) {
+        throw new Error("Missing bootstrap allowlist: set telegram.admin_user_ids (or telegram.allowlist.user_ids) in config/env");
+    }
+}
+function loadConfig(opts) {
+    const env = opts?.env ?? process.env;
+    const configPath = opts?.configPath ?? defaultConfigPath(env);
+    const cfg = JSON.parse(JSON.stringify(DEFAULT_CONFIG));
+    // HOME-aware defaults (XDG-ish) for production; can be overridden by env/yaml.
+    const dd = defaultDataDir(env);
+    cfg.runtime.data_dir = dd;
+    cfg.runtime.workspaces_dir = node_path_1.default.join(dd, "workspaces");
+    cfg.runtime.uploads_dir = node_path_1.default.join(dd, "uploads");
+    // 1) env defaults
+    applyEnv(cfg, env);
+    // 2) yaml overrides
+    const doc = readYamlIfExists(configPath);
+    if (doc !== undefined)
+        applyYaml(cfg, doc);
+    validate(cfg);
+    return cfg;
+}