@alilis/k-hat 0.2.6 → 0.2.8

package/dist/network/server.js

@@ -0,0 +1,383 @@
+import { createServer } from 'node:http';
+import { watch } from 'node:fs';
+import { readJsonFile, saveJsonAtomic, validateConfig, providerUrl, defaultTimeouts } from '../core/config.js';
+import { LogWriter } from '../core/logger.js';
+import { join, basename } from 'node:path';
+import { findRoute, routeUpstreamModel, resolveProvider, isRouteDisabled } from '../core/router.js';
+import { WeightedSelector } from './selector.js';
+import { handleAdmin } from '../network/admin.js';
+import { enableKey } from '../data/store.js';
+import { probeKey } from '../core/probe.js';
+import { ACCESS_TOKEN_REF } from '../data/vault.js';
+const RETRYABLE = new Set([401, 402, 429]);
+const HOP_BY_HOP = new Set(['content-length', 'transfer-encoding', 'connection']);
+const ANTHROPIC_VERSION = '2023-06-01';
+/** 429 cooldown: first wait, doubling per consecutive cycle, capped. */
+const COOLDOWN_BASE_MS = 30_000;
+const COOLDOWN_MAX_MS = 10 * 60_000;
+/** An upstream Retry-After is honored, but never beyond this cap. */
+const RETRY_AFTER_MAX_MS = 30 * 60_000;
+/** Background probe cadence for permanently unavailable keys (cooldown keys revive on their own). */
+const PROBE_INTERVAL_MS = 5 * 60_000;
+/** Upper bound for buffering a non-streaming response to read its usage. */
+const USAGE_BUFFER_LIMIT = 16 * 1024 * 1024;
+/** Entry paths accepted by the proxy, mapped to the protocol family they speak. */
+const ENDPOINTS = {
+    '/v1/chat/completions': 'openai',
+    '/v1/responses': 'openai',
+    '/v1/messages': 'anthropic'
+};
+function modelList(config) {
+    const seen = new Set();
+    const data = config.routes
+        .filter((route) => route.enabled !== false && !seen.has(route.model) && seen.add(route.model))
+        .map((route) => ({ id: route.model, object: 'model', created: 0, owned_by: route.provider }));
+    return { object: 'list', data };
+}
+/** Rewrite the client-facing auth into the upstream auth convention for the target protocol. */
+function upstreamHeaders(protocol, secret, accept) {
+    if (protocol === 'anthropic')
+        return { 'content-type': 'application/json', accept: accept ?? '*/*', 'x-api-key': secret, 'anthropic-version': ANTHROPIC_VERSION };
+    return { 'content-type': 'application/json', accept: accept ?? '*/*', authorization: `Bearer ${secret}` };
+}
+async function readBody(req, limit) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const part = Buffer.from(chunk);
+        size += part.length;
+        if (size > limit)
+            throw Object.assign(new Error('Request body too large'), { statusCode: 413 });
+        chunks.push(part);
+    }
+    return Buffer.concat(chunks);
+}
+function scanUsage(protocol, text) {
+    // Usage snapshots are cumulative within a stream (Anthropic message_start/message_delta each
+    // carry a running total), so the per-field max across snapshots is the stream total; summing
+    // would double-count.
+    let tokensIn = 0;
+    let tokensOut = 0;
+    for (const line of text.split('\n')) {
+        if (!line.startsWith('data: '))
+            continue;
+        try {
+            const payload = JSON.parse(line.slice(6));
+            // Anthropic's message_start nests usage under `message`; message_delta and OpenAI carry it at the top level.
+            const usage = payload.usage ?? payload.message?.usage;
+            if (!usage || typeof usage !== 'object')
+                continue;
+            if (protocol === 'openai') {
+                tokensIn = Math.max(tokensIn, Number(usage.prompt_tokens ?? usage.input_tokens ?? 0) || 0);
+                tokensOut = Math.max(tokensOut, Number(usage.completion_tokens ?? usage.output_tokens ?? 0) || 0);
+            }
+            else {
+                tokensIn = Math.max(tokensIn, Number(usage.input_tokens ?? 0) || 0);
+                tokensOut = Math.max(tokensOut, Number(usage.output_tokens ?? 0) || 0);
+            }
+        }
+        catch { }
+    }
+    return { tokensIn, tokensOut };
+}
+function json(res, status, value) { res.writeHead(status, { 'content-type': 'application/json' }); res.end(JSON.stringify(value)); }
+/** Abort reason carrier so timeouts map to 504 instead of a generic 502. */
+function upstreamAbort(abort, message) {
+    const reason = new Error(message);
+    reason.upstreamTimeout = true;
+    abort.abort(reason);
+}
+/** Parse a Retry-After header (delta-seconds or HTTP-date) into a capped cooldown duration. */
+function retryAfterMs(value) {
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return Math.min(seconds * 1000, RETRY_AFTER_MAX_MS);
+    const date = Date.parse(value);
+    if (!Number.isNaN(date))
+        return Math.min(Math.max(date - Date.now(), 0), RETRY_AFTER_MAX_MS);
+    return undefined;
+}
+export function createKhatServer(options) {
+    const states = options.states ?? {};
+    const secrets = { ...(options.secrets ?? {}) };
+    const currentSecret = (ref) => options.store?.vault.get(ref) ?? secrets[ref];
+    const selector = new WeightedSelector();
+    const statePath = options.statePath;
+    const logger = options.store ? new LogWriter(join(options.store.dir, 'logs')) : undefined;
+    const timeouts = () => ({ ...defaultTimeouts, ...options.config.timeouts });
+    const markFailure = async (providerId, keyId, status, retryAfterHeader) => {
+        const ref = `${providerId}/${keyId}`;
+        const at = new Date().toISOString();
+        if (status === 429) {
+            // 429 is transient: cool down and auto-revive at cooldownUntil instead of dying permanently.
+            const previous = states[ref];
+            const count = previous?.status === 'cooldown' ? (previous.cooldownCount ?? 0) + 1 : 1;
+            const waitMs = retryAfterMs(retryAfterHeader) ?? Math.min(COOLDOWN_BASE_MS * 2 ** (count - 1), COOLDOWN_MAX_MS);
+            states[ref] = { status: 'cooldown', cooldownUntil: new Date(Date.now() + waitMs).toISOString(), cooldownCount: count, lastError: { http: status, at } };
+        }
+        else {
+            // 401/402 mean the key itself is bad; recovery requires a probe, manual enable, or the background prober.
+            states[ref] = { status: 'unavailable', lastError: { http: status, at } };
+        }
+        if (statePath)
+            await saveJsonAtomic(statePath, { keys: states, counters: options.store?.counters ?? {} });
+    };
+    const markHealthy = async (ref) => {
+        // A success clears cooldown residue and resets the backoff counter.
+        delete states[ref];
+        if (statePath)
+            await saveJsonAtomic(statePath, { keys: states, counters: options.store?.counters ?? {} });
+    };
+    const server = createServer(async (req, res) => {
+        try {
+            if (req.url?.startsWith('/_keys')) {
+                if (!options.store)
+                    return json(res, 503, { error: { message: 'Admin API is not available (no store attached)' } });
+                await handleAdmin(req, res, options.store, () => options.store?.vault.get(ACCESS_TOKEN_REF) ?? options.accessToken);
+                return;
+            }
+            const currentAccessToken = options.store?.vault.get(ACCESS_TOKEN_REF) ?? options.accessToken;
+            if (!currentAccessToken || req.headers.authorization !== `Bearer ${currentAccessToken}`)
+                return json(res, 401, { error: { message: 'Unauthorized' } });
+            const pathname = new URL(req.url ?? '/', 'http://localhost').pathname;
+            if (req.method === 'GET' && (pathname === '/models' || pathname === '/v1/models'))
+                return json(res, 200, modelList(options.config));
+            if (req.method !== 'POST' || !(pathname in ENDPOINTS))
+                return json(res, 404, { error: { message: 'Not found' } });
+            const protocol = ENDPOINTS[pathname];
+            const body = await readBody(req, options.config.requestBodyLimitMB * 1024 * 1024);
+            let parsed;
+            try {
+                parsed = JSON.parse(body.toString('utf8'));
+            }
+            catch {
+                return json(res, 400, { error: { message: 'Invalid JSON' } });
+            }
+            if (!parsed.model || typeof parsed.model !== 'string')
+                return json(res, 400, { error: { message: 'model is required' } });
+            const route = findRoute(options.config, parsed.model);
+            const provider = resolveProvider(options.config, parsed.model);
+            if (!provider) {
+                if (isRouteDisabled(options.config, parsed.model))
+                    return json(res, 403, { error: { message: `Route disabled for model: ${parsed.model}` } });
+                return json(res, 404, { error: { message: `No route for model: ${parsed.model}` } });
+            }
+            if (provider.protocol !== protocol)
+                return json(res, 400, { error: { message: `Model ${parsed.model} resolves to a ${provider.protocol} provider, but ${req.url} speaks ${protocol}` } });
+            const upstreamBody = JSON.stringify({ ...parsed, model: routeUpstreamModel(route) });
+            const tried = new Set();
+            while (true) {
+                const key = selector.select(provider.id, provider.keys.filter((item) => !tried.has(item.id)), states);
+                if (!key) {
+                    const now = Date.now();
+                    const waits = provider.keys
+                        .map((item) => states[`${provider.id}/${item.id}`])
+                        .filter((state) => state?.status === 'cooldown' && Date.parse(state.cooldownUntil ?? '') > now)
+                        .map((state) => Date.parse(state.cooldownUntil));
+                    const earliest = waits.length ? Math.min(...waits) : undefined;
+                    const hint = earliest !== undefined ? ` (${waits.length} cooling down, earliest retry in ~${Math.ceil((earliest - now) / 1000)}s)` : '';
+                    return json(res, 503, { error: { message: `All keys are unavailable${hint}`, keys: provider.keys.map((item) => ({ id: item.id, ...(states[`${provider.id}/${item.id}`] ?? { status: 'available' }) })) } });
+                }
+                tried.add(key.id);
+                const secret = currentSecret(key.vaultRef);
+                if (secret === undefined)
+                    continue;
+                const abort = new AbortController();
+                const clientGone = () => abort.abort(new Error('client disconnected'));
+                res.on('close', clientGone);
+                const headerTimer = setTimeout(() => upstreamAbort(abort, 'upstream response header timeout'), timeouts().headerMs);
+                let upstream;
+                try {
+                    upstream = await fetch(providerUrl(provider.baseUrl, pathname), { method: 'POST', headers: upstreamHeaders(protocol, secret, req.headers.accept), body: upstreamBody, signal: abort.signal });
+                }
+                catch (error) {
+                    if (error?.upstreamTimeout)
+                        error.statusCode = 504;
+                    throw error;
+                }
+                finally {
+                    clearTimeout(headerTimer);
+                }
+                if (RETRYABLE.has(upstream.status)) {
+                    await markFailure(provider.id, key.id, upstream.status, upstream.headers.get('retry-after'));
+                    if (tried.size < provider.keys.length) {
+                        res.off('close', clientGone);
+                        continue;
+                    }
+                }
+                const startedAt = Date.now();
+                let firstByteAt;
+                let bytes = 0;
+                let sseRemainder = '';
+                let tokensIn = 0;
+                let tokensOut = 0;
+                const responseHeaders = {};
+                upstream.headers.forEach((value, name) => { if (!HOP_BY_HOP.has(name))
+                    responseHeaders[name] = value; });
+                res.writeHead(upstream.status, responseHeaders);
+                if (upstream.body) {
+                    const idleTimer = setTimeout(() => upstreamAbort(abort, 'upstream stream idle timeout'), timeouts().streamIdleMs);
+                    // Non-streaming JSON responses carry usage at the top level instead of in SSE lines;
+                    // buffer them (bounded) so their tokens can be counted too.
+                    const isEventStream = (upstream.headers.get('content-type') ?? '').toLowerCase().includes('text/event-stream');
+                    let jsonBuffer = isEventStream ? undefined : [];
+                    let jsonSize = 0;
+                    try {
+                        for await (const chunk of upstream.body) {
+                            const buffer = Buffer.from(chunk);
+                            if (firstByteAt === undefined)
+                                firstByteAt = Date.now();
+                            bytes += buffer.length;
+                            if (isEventStream) {
+                                const combined = sseRemainder + buffer.toString('utf8');
+                                const lastNewline = combined.lastIndexOf('\n');
+                                if (lastNewline >= 0) {
+                                    const usage = scanUsage(protocol, combined.slice(0, lastNewline + 1));
+                                    tokensIn = Math.max(tokensIn, usage.tokensIn);
+                                    tokensOut = Math.max(tokensOut, usage.tokensOut);
+                                    sseRemainder = combined.slice(lastNewline + 1);
+                                }
+                                else
+                                    sseRemainder = combined;
+                            }
+                            if (jsonBuffer) {
+                                jsonSize += buffer.length;
+                                if (jsonSize > USAGE_BUFFER_LIMIT)
+                                    jsonBuffer = undefined;
+                                else
+                                    jsonBuffer.push(buffer);
+                            }
+                            res.write(buffer);
+                            idleTimer.refresh();
+                        }
+                        if (isEventStream) {
+                            const usage = scanUsage(protocol, sseRemainder);
+                            tokensIn = Math.max(tokensIn, usage.tokensIn);
+                            tokensOut = Math.max(tokensOut, usage.tokensOut);
+                        }
+                        if (jsonBuffer) {
+                            try {
+                                const payload = JSON.parse(Buffer.concat(jsonBuffer).toString('utf8'));
+                                const jsonUsage = payload?.usage;
+                                if (jsonUsage && typeof jsonUsage === 'object') {
+                                    tokensIn = Math.max(tokensIn, Number(jsonUsage.prompt_tokens ?? jsonUsage.input_tokens ?? 0) || 0);
+                                    tokensOut = Math.max(tokensOut, Number(jsonUsage.completion_tokens ?? jsonUsage.output_tokens ?? 0) || 0);
+                                }
+                            }
+                            catch { }
+                        }
+                    }
+                    catch (error) {
+                        if (error?.upstreamTimeout)
+                            res.destroy(error);
+                        throw error;
+                    }
+                    finally {
+                        clearTimeout(idleTimer);
+                    }
+                }
+                const durationMs = Date.now() - startedAt;
+                const ttfbMs = (firstByteAt ?? Date.now()) - startedAt;
+                const keyRef = `${provider.id}/${key.id}`;
+                if (upstream.ok && states[keyRef])
+                    await markHealthy(keyRef);
+                options.store?.recordCounter(keyRef, { requests: 1, failed: upstream.ok ? 0 : 1, bytesOut: bytes, tokensIn, tokensOut });
+                try {
+                    await logger?.append({ ts: new Date().toISOString(), event: 'forward', model: parsed.model, provider: provider.id, key: keyRef, status: upstream.status, ttfbMs, durationMs, bytes, tokensIn, tokensOut });
+                }
+                catch (error) {
+                    console.error(`[khat] failed to write request log: ${error?.message ?? error}`);
+                }
+                res.end();
+                res.off('close', clientGone);
+                return;
+            }
+        }
+        catch (error) {
+            if (!res.headersSent)
+                json(res, error.statusCode ?? 502, { error: { message: error.message ?? 'Proxy error' } });
+            else
+                res.destroy(error);
+        }
+    });
+    const configWatcher = options.store ? watch(options.store.dir, (_event, filename) => {
+        if (filename?.toString() !== basename(options.store.configPath))
+            return;
+        void (async () => {
+            try {
+                const next = await readJsonFile(options.store.configPath);
+                if (next === undefined)
+                    return;
+                const validated = validateConfig(next);
+                // The daemon is the single writer (ADR-0005): a disk copy older than the in-memory config
+                // can only be a stale echo of our own write, never a genuine external edit.
+                const diskRevision = validated.revision;
+                const memoryRevision = options.config.revision;
+                if (diskRevision !== undefined && memoryRevision !== undefined && diskRevision < memoryRevision)
+                    return;
+                // The socket keeps the address it was started with; adopting a new bind/port here would
+                // make status report an endpoint the process is not actually listening on.
+                if (validated.bind !== options.config.bind || validated.port !== options.config.port) {
+                    console.error(`[khat] bind/port change requires a restart; still listening on ${options.config.bind}:${options.config.port}`);
+                    validated.port = options.config.port;
+                    validated.bind = options.config.bind;
+                }
+                Object.assign(options.config, validated);
+                for (const key of Object.keys(secrets))
+                    delete secrets[key];
+                for (const provider of validated.providers)
+                    for (const key of provider.keys) {
+                        const secret = options.store?.vault.get(key.vaultRef);
+                        if (secret !== undefined)
+                            secrets[key.vaultRef] = secret;
+                    }
+            }
+            catch (error) {
+                console.error(`[khat] ignored invalid external config update: ${error?.message ?? error}`);
+            }
+        })();
+    }) : undefined;
+    // Cooldown keys revive on their own at cooldownUntil (probing them early would just re-429
+    // and extend the cooldown), so the prober only targets permanently unavailable keys.
+    const probeIntervalMs = options.probeIntervalMs ?? PROBE_INTERVAL_MS;
+    let probeInFlight = false;
+    const runProbeCycle = async () => {
+        if (probeInFlight)
+            return;
+        probeInFlight = true;
+        try {
+            for (const provider of options.config.providers) {
+                const route = options.config.routes.find((item) => item.provider === provider.id);
+                if (!route)
+                    continue;
+                for (const target of provider.keys) {
+                    if (states[`${provider.id}/${target.id}`]?.status !== 'unavailable')
+                        continue;
+                    try {
+                        const secret = currentSecret(target.vaultRef);
+                        if (secret === undefined)
+                            continue;
+                        const status = await probeKey(provider, routeUpstreamModel(route), secret);
+                        if (status >= 200 && status < 300) {
+                            await options.store.mutate(() => enableKey(options.store, provider.id, target.id));
+                            await logger?.append({ ts: new Date().toISOString(), event: 'probe', provider: provider.id, key: `${provider.id}/${target.id}`, status, outcome: 'enabled' });
+                        }
+                    }
+                    catch (error) {
+                        console.error(`[khat] background probe failed for ${provider.id}/${target.id}: ${error?.message ?? error}`);
+                    }
+                }
+            }
+        }
+        finally {
+            probeInFlight = false;
+        }
+    };
+    const prober = options.store && probeIntervalMs > 0 ? setInterval(() => { void runProbeCycle(); }, probeIntervalMs) : undefined;
+    prober?.unref();
+    server.once('close', () => { configWatcher?.close(); if (prober)
+        clearInterval(prober); });
+    return server;
+}

package/dist/service.js

@@ -0,0 +1,283 @@
+import { execFile } from 'node:child_process';
+import { access, mkdir, unlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const WINDOWS_TASK_NAME = 'khat';
+const LAUNCHD_LABEL = 'local.khat';
+const SYSTEMD_UNIT = 'khat';
+async function defaultRunner(command, args) {
+    try {
+        const { stdout, stderr } = await execFileAsync(command, args, { windowsHide: true, timeout: 30_000 });
+        return { code: 0, stdout: String(stdout), stderr: String(stderr) };
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return { code: null, stdout: '', stderr: `${command} is not available` };
+        return { code: typeof error?.code === 'number' ? error.code : null, stdout: String(error?.stdout ?? ''), stderr: String(error?.stderr ?? error?.message ?? 'command failed') };
+    }
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function xmlEscape(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+function resolveOptions(options) {
+    const home = options.homeDir ?? homedir();
+    return {
+        runner: options.run ?? defaultRunner,
+        homeDir: home,
+        dataDir: options.dataDir ?? process.env.KHAT_HOME ?? join(home, '.khat'),
+        distDir: options.distDir ?? dirname(fileURLToPath(new URL('./supervisor.js', import.meta.url))),
+        execPath: options.execPath ?? process.execPath,
+        userId: options.userId ?? (process.env.USERDOMAIN && process.env.USERNAME ? `${process.env.USERDOMAIN}\\${process.env.USERNAME}` : undefined),
+        uid: options.uid ?? (typeof process.getuid === 'function' ? process.getuid() : undefined)
+    };
+}
+function commandFailure(result, action) {
+    return `${action}: ${(result.stderr || result.stdout).trim() || `command exited with code ${result.code}`}`;
+}
+export function buildTaskXml(options) {
+    const triggerUser = options.userId ? `\n      <UserId>${xmlEscape(options.userId)}</UserId>` : '';
+    return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>Khat proxy supervisor; starts the khat daemon when you log on</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>${triggerUser}
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${xmlEscape(options.command)}</Command>
+      <Arguments>${xmlEscape(options.arguments)}</Arguments>
+    </Exec>
+  </Actions>
+</Task>`;
+}
+export function buildLaunchdPlist(options) {
+    const programArgs = options.programArgs.map((arg) => `    <string>${xmlEscape(arg)}</string>`).join('\n');
+    const env = Object.entries(options.env).map(([key, value]) => `    <key>${xmlEscape(key)}</key>\n    <string>${xmlEscape(value)}</string>`).join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xmlEscape(options.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xmlEscape(options.program)}</string>
+${programArgs}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(options.workDir)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${env}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(options.logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(options.logPath)}</string>
+</dict>
+</plist>`;
+}
+export function buildSystemdUnit(options) {
+    const execStart = options.execStart.map((part) => `"${part}"`).join(' ');
+    const env = Object.entries(options.env).map(([key, value]) => `Environment="${key}=${value}"`).join('\n');
+    return `[Unit]
+Description=Khat proxy supervisor
+
+[Service]
+ExecStart=${execStart}
+WorkingDirectory="${options.workDir}"
+${env}
+Restart=no
+
+[Install]
+WantedBy=default.target
+`;
+}
+// Windows: a scheduled task with an interactive token, not an NSSM service —
+// the vault master key is protected with user-scope DPAPI (ADR 0004), which
+// LocalSystem cannot decrypt, and NSSM cannot run as the current user without
+// that user's password.
+function windowsManager(options) {
+    const { runner, dataDir, distDir, execPath, userId } = resolveOptions(options);
+    const supervisorPath = join(distDir, 'supervisor.js');
+    async function install({ startNow = true } = {}) {
+        await mkdir(dataDir, { recursive: true });
+        const xmlPath = join(dataDir, 'service-task.xml');
+        // The task XML cannot set environment variables, so a cmd wrapper pins
+        // KHAT_HOME; the quoted `set` form avoids trailing-space capture.
+        const arguments_ = `/c set "KHAT_HOME=${dataDir}" && "${execPath}" "${supervisorPath}"`;
+        const xml = buildTaskXml({ userId, command: 'cmd.exe', arguments: arguments_ });
+        await writeFile(xmlPath, Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(xml, 'utf16le')]));
+        const created = await runner('schtasks', ['/Create', '/F', '/TN', WINDOWS_TASK_NAME, '/XML', xmlPath]);
+        if (created.code !== 0)
+            throw new Error(`${commandFailure(created, 'could not register the scheduled task')} (definition kept at ${xmlPath})`);
+        await unlink(xmlPath).catch(() => undefined);
+        if (!startNow)
+            return `scheduled task '${WINDOWS_TASK_NAME}' registered; it auto-starts the daemon at your next logon`;
+        const started = await runner('schtasks', ['/Run', '/TN', WINDOWS_TASK_NAME]);
+        if (started.code !== 0)
+            throw new Error(commandFailure(started, 'task registered but could not be started'));
+        return `scheduled task '${WINDOWS_TASK_NAME}' registered and running; it auto-starts at logon`;
+    }
+    async function uninstall() {
+        const query = await runner('schtasks', ['/Query', '/TN', WINDOWS_TASK_NAME]);
+        if (query.code !== 0)
+            return 'khat service is not installed';
+        const removed = await runner('schtasks', ['/Delete', '/F', '/TN', WINDOWS_TASK_NAME]);
+        if (removed.code !== 0)
+            throw new Error(commandFailure(removed, 'could not remove the scheduled task'));
+        return `scheduled task '${WINDOWS_TASK_NAME}' removed`;
+    }
+    async function status() {
+        const query = await runner('schtasks', ['/Query', '/TN', WINDOWS_TASK_NAME]);
+        if (query.code !== 0)
+            return { installed: false, enabled: null, running: null, detail: '' };
+        // schtasks /Query status text is localized; PowerShell's StateEnum is not.
+        const state = await runner('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', `(Get-ScheduledTask -TaskName '${WINDOWS_TASK_NAME}' -ErrorAction SilentlyContinue).State`]);
+        const value = Number.parseInt(state.stdout.trim(), 10);
+        if (!Number.isInteger(value))
+            return { installed: true, enabled: null, running: null, detail: 'task state could not be read' };
+        return {
+            installed: true,
+            enabled: value !== 1,
+            running: value === 4,
+            detail: value === 4 ? 'task running' : value === 3 ? 'task ready (not running)' : value === 1 ? 'task disabled' : `task state ${value}`
+        };
+    }
+    return { install, uninstall, status };
+}
+// macOS: launchd user agent. RunAtLoad starts it at login; KeepAlive stays off
+// so the supervisor's own crash circuit breaker is the only restart authority.
+function darwinManager(options) {
+    const { runner, homeDir, dataDir, distDir, execPath, uid } = resolveOptions(options);
+    const supervisorPath = join(distDir, 'supervisor.js');
+    const plistPath = join(homeDir, 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`);
+    const target = `gui/${uid}/${LAUNCHD_LABEL}`;
+    async function install({ startNow = true } = {}) {
+        if (uid === undefined)
+            throw new Error('could not determine the user id for launchctl');
+        await mkdir(dirname(plistPath), { recursive: true });
+        await mkdir(dataDir, { recursive: true });
+        const plist = buildLaunchdPlist({
+            label: LAUNCHD_LABEL,
+            program: execPath,
+            programArgs: [supervisorPath],
+            workDir: distDir,
+            env: { KHAT_HOME: dataDir },
+            logPath: join(dataDir, 'service.log')
+        });
+        await writeFile(plistPath, plist, 'utf8');
+        if (!startNow)
+            return `launch agent ${LAUNCHD_LABEL} installed; it auto-starts the daemon at your next logon`;
+        await runner('launchctl', ['bootout', target]);
+        const boot = await runner('launchctl', ['bootstrap', `gui/${uid}`, plistPath]);
+        if (boot.code !== 0)
+            throw new Error(commandFailure(boot, 'could not load the launch agent'));
+        return `launch agent ${LAUNCHD_LABEL} installed and running; it auto-starts at logon`;
+    }
+    async function uninstall() {
+        if (!(await fileExists(plistPath)))
+            return 'khat service is not installed';
+        await runner('launchctl', ['bootout', target]);
+        await unlink(plistPath).catch(() => undefined);
+        return `launch agent ${LAUNCHD_LABEL} removed`;
+    }
+    async function status() {
+        if (!(await fileExists(plistPath)))
+            return { installed: false, enabled: null, running: null, detail: '' };
+        const printed = await runner('launchctl', ['print', target]);
+        if (printed.code !== 0)
+            return { installed: true, enabled: true, running: false, detail: 'not loaded; starts at next logon' };
+        const state = printed.stdout.match(/state\s*=\s*(\S+)/)?.[1] ?? 'unknown';
+        return { installed: true, enabled: true, running: state === 'running', detail: state === 'running' ? 'agent running' : `agent state: ${state}` };
+    }
+    return { install, uninstall, status };
+}
+// Linux: systemd user unit. Restart=no — the supervisor owns crash backoff;
+// the unit only has to launch it once per login/boot.
+function linuxManager(options) {
+    const { runner, homeDir, dataDir, distDir, execPath } = resolveOptions(options);
+    const supervisorPath = join(distDir, 'supervisor.js');
+    const unitPath = join(homeDir, '.config', 'systemd', 'user', `${SYSTEMD_UNIT}.service`);
+    async function install({ startNow = true } = {}) {
+        await mkdir(dirname(unitPath), { recursive: true });
+        const unit = buildSystemdUnit({ execStart: [execPath, supervisorPath], workDir: distDir, env: { KHAT_HOME: dataDir } });
+        await writeFile(unitPath, unit, 'utf8');
+        const reloaded = await runner('systemctl', ['--user', 'daemon-reload']);
+        if (reloaded.code !== 0)
+            throw new Error(commandFailure(reloaded, 'could not reload the systemd user units'));
+        const enable = await runner('systemctl', ['--user', ...(startNow ? ['enable', '--now'] : ['enable']), SYSTEMD_UNIT]);
+        if (enable.code !== 0)
+            throw new Error(commandFailure(enable, 'could not enable the service'));
+        // Without lingering, user units only run while the user is logged in.
+        const linger = await runner('loginctl', ['enable-linger']);
+        const lingerNote = linger.code === 0 ? '' : ' (warning: could not enable lingering, so the service starts at login rather than at boot)';
+        return `systemd user service ${SYSTEMD_UNIT} installed${startNow ? ' and running' : ''}; it auto-starts at login${lingerNote}`;
+    }
+    async function uninstall() {
+        if (!(await fileExists(unitPath)))
+            return 'khat service is not installed';
+        await runner('systemctl', ['--user', 'disable', '--now', SYSTEMD_UNIT]);
+        await unlink(unitPath).catch(() => undefined);
+        await runner('systemctl', ['--user', 'daemon-reload']);
+        return `systemd user service ${SYSTEMD_UNIT} removed`;
+    }
+    async function status() {
+        if (!(await fileExists(unitPath)))
+            return { installed: false, enabled: null, running: null, detail: '' };
+        const enabledResult = await runner('systemctl', ['--user', 'is-enabled', SYSTEMD_UNIT]);
+        const activeResult = await runner('systemctl', ['--user', 'is-active', SYSTEMD_UNIT]);
+        const enabledText = enabledResult.stdout.trim();
+        const activeText = activeResult.stdout.trim();
+        return {
+            installed: true,
+            enabled: enabledText === 'enabled' ? true : enabledText === 'disabled' ? false : null,
+            running: activeText === 'active',
+            detail: activeText === 'active' ? 'unit active' : `unit ${activeText || 'unknown'}`
+        };
+    }
+    return { install, uninstall, status };
+}
+export function createServiceManager(platform, options = {}) {
+    if (platform === 'win32')
+        return windowsManager(options);
+    if (platform === 'darwin')
+        return darwinManager(options);
+    if (platform === 'linux')
+        return linuxManager(options);
+    throw new Error(`unsupported platform '${platform}': khat service requires Windows Task Scheduler, macOS launchd, or Linux systemd`);
+}