kernelpm 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+# kernelpm daemon
+
+Keeps **opencode sessions alive on a server** and exposes them over a local control socket. Each
+session is a headless `opencode serve` process driven over its HTTP API; the daemon normalizes
+opencode's structured events into the chat the app renders.
+
+```
+ app ──WebSocket──> broker ──SSH (streamlocal)──> ~/.kernelpm/control.sock
+                                                        │
+                                              kernelpm daemon
+                                                        │  one `opencode serve` per chat
+                                              opencode serve (headless, allow-all permissions)
+```
+
+- **One `opencode serve` per chat**, scoped to the session's working directory. The serve process survives SSH drops and daemon restarts; a restarted daemon reattaches to it by its persisted port.
+- **Auto-yes is structural.** Each serve launches with an inline permission config that allows everything (`OPENCODE_PERMISSION`), so opencode never stops to ask — the unattended equivalent of the old `bypassPermissions`.
+- **Chat = the API.** Prompts go out through `POST /session/:id/prompt_async`; the conversation comes back from the server-sent event stream (`GET /event`) as structured message parts, normalized to message-granular chat events.
+- **Forwarded options.** When a finished turn poses a numbered/multiple-choice question, it's surfaced as a tappable `decision`.
+- **Durable + resumable.** Every chat event is logged under `~/.kernelpm/`; a reconnecting client replays only what it missed. The opencode session id and serve port are persisted, so a dead serve is respawned and its session resumed.
+
+## Prerequisites (on each server)
+
+- Linux with **opencode** installed and logged in for at least one provider: `opencode auth login` (verify with `opencode auth list`).
+- Node ≥ 18 (to run the daemon).
+
+## Install
+
+Published on npm — the simplest path (Node ≥ 18 already on the server):
+
+```bash
+npm install -g kernelpm
+kernelpm daemon start
+```
+
+From source instead:
+
+```bash
+cd daemon
+npm install
+npm run build           # -> dist/
+npm link                # puts `kernelpm` on PATH (or: npm i -g .)
+kernelpm daemon start
+```
+
+State lives in `~/.kernelpm/` (`control.sock`, `token`, `sessions.json`, `sessions/<id>.jsonl`,
+`daemon.log`). Override the location with `KERNELPM_HOME`.
+
+## CLI
+
+```bash
+kernelpm daemon start|stop|status|run     # run = foreground (used by start)
+kernelpm new <cwd> [--title T] [--model M]   # model in provider/model form, e.g. anthropic/claude-...
+kernelpm list
+kernelpm attach <id>                       # stream the chat; type to send a message
+kernelpm send <id> <text...>
+kernelpm kill <id>
+```
+
+## Verification runbook (standalone, over plain SSH)
+
+This is the bottom layer of the kernelpm verification — exercise it before wiring the broker/app.
+
+1. **Schema sanity** — `kernelpm new ~/some/project`; `kernelpm attach <id>`; type `say hi in one word`. You should see the assistant reply stream in.
+2. **Auto-yes** — ask it to `create a file test.txt with the word ok`. The edit/run happens with no prompt blocking (allow-all permissions).
+3. **Forwarded options** — ask `give me three options for X, numbered, and ask me to choose`. When the turn ends you'll get a `decision`; `kernelpm attach` prints `[1]…[2]…`. (From the app these render as chips.)
+4. **Survives disconnect** — close the SSH login, reconnect, `kernelpm list` → the session is still there. `kernelpm daemon stop && kernelpm daemon start` → it reattaches with history intact. Kill the serve (`pkill -f "opencode serve"`, a reboot stand-in) then `kernelpm daemon start` → a fresh serve is spawned and the opencode session resumed.
+
+## Notes
+
+- opencode stores its own sessions under `~/.local/share/opencode/`. kernelpm keeps its own normalized event log under `~/.kernelpm/` as the source of truth for the app, and uses the persisted opencode session id only to resume.
+- The per-session serve binds to `127.0.0.1` only. There is no between-process auth on that socket (it relies on local isolation); point sessions at git-tracked / disposable trees given the allow-all permission config.
+- Chat updates are message-granular, not token-by-token — text for a turn appears once the assistant message completes, while tool start/result stream live.

package/dist/cli.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * kernelpm CLI — manage the daemon and its sessions over plain SSH, before any
+ * broker or app is involved.
+ *
+ *   kernelpm daemon start|stop|status|run
+ *   kernelpm list
+ *   kernelpm new <cwd> [--title T] [--model M]
+ *   kernelpm attach <id>          # stream the chat; type to send a message
+ *   kernelpm send <id> <text...>
+ *   kernelpm kill <id>
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
+const store_1 = require("./store");
+const daemon_1 = require("./daemon");
+const runtime_1 = require("./runtime");
+const client_1 = require("./client");
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    switch (cmd) {
+        case 'daemon':
+            return daemonCmd(rest);
+        case 'list':
+            return listCmd();
+        case 'new':
+            return newCmd(rest);
+        case 'attach':
+            return attachCmd(rest);
+        case 'send':
+            return sendCmd(rest);
+        case 'kill':
+            return killCmd(rest);
+        case undefined:
+        case 'help':
+        case '-h':
+        case '--help':
+            return printHelp();
+        default:
+            console.error(`unknown command: ${cmd}`);
+            printHelp();
+            process.exitCode = 1;
+    }
+}
+async function daemonCmd(args) {
+    switch (args[0]) {
+        case 'run':
+            return (0, runtime_1.runDaemon)();
+        case 'start':
+            return (0, runtime_1.startDaemonDetached)();
+        case 'stop':
+            return (0, runtime_1.stopDaemon)();
+        case 'status': {
+            if (!(await (0, runtime_1.isDaemonRunning)())) {
+                console.log('kernelpm daemon: stopped');
+                return;
+            }
+            const c = await connect();
+            const sessions = await c.list();
+            console.log(`kernelpm daemon: running (${sessions.length} session(s))`);
+            c.close();
+            return;
+        }
+        default:
+            console.error('usage: kernelpm daemon <run|start|stop|status>');
+            process.exitCode = 1;
+    }
+}
+async function listCmd() {
+    const c = await connect();
+    const sessions = await c.list();
+    if (!sessions.length)
+        console.log('(no sessions)');
+    for (const s of sessions) {
+        console.log(`${s.id}  ${pad(s.status, 16)} ${s.title}  —  ${s.cwd}`);
+    }
+    c.close();
+}
+async function newCmd(args) {
+    const { positionals, flags } = parseArgs(args);
+    const cwd = path.resolve(positionals[0] ?? '.');
+    const c = await connect();
+    const s = await c.create(cwd, flags.title, flags.model);
+    console.log(`created ${s.id} (${s.title}) in ${s.cwd}`);
+    c.close();
+}
+async function attachCmd(args) {
+    const id = args[0];
+    if (!id) {
+        console.error('usage: kernelpm attach <id>');
+        process.exitCode = 1;
+        return;
+    }
+    const c = new client_1.ControlClient();
+    await c.connect((0, daemon_1.controlSocketPath)(), await readToken(), printPush);
+    await c.attach(id);
+    console.error(`— attached to ${id}. Type a message and press Enter; Ctrl-C to quit. —`);
+    const rl = readline.createInterface({ input: process.stdin });
+    rl.on('line', (line) => {
+        if (line.trim())
+            void c.send(id, line);
+    });
+}
+async function sendCmd(args) {
+    const [id, ...words] = args;
+    const text = words.join(' ');
+    if (!id || !text) {
+        console.error('usage: kernelpm send <id> <text...>');
+        process.exitCode = 1;
+        return;
+    }
+    const c = await connect();
+    await c.send(id, text);
+    c.close();
+}
+async function killCmd(args) {
+    const id = args[0];
+    if (!id) {
+        console.error('usage: kernelpm kill <id>');
+        process.exitCode = 1;
+        return;
+    }
+    const c = await connect();
+    await c.kill(id);
+    console.log(`killed ${id}`);
+    c.close();
+}
+/* --------------------------------- helpers --------------------------------- */
+async function connect() {
+    const c = new client_1.ControlClient();
+    try {
+        await c.connect((0, daemon_1.controlSocketPath)(), await readToken());
+    }
+    catch {
+        throw new Error('cannot reach the kernelpm daemon — start it with `kernelpm daemon start`');
+    }
+    return c;
+}
+async function readToken() {
+    return (await fs.promises.readFile(path.join((0, store_1.kernelpmHome)(), 'token'), 'utf8')).trim();
+}
+function printPush(msg) {
+    if (msg.t === 'event')
+        printEvent(msg.event);
+    else if (msg.t === 'status')
+        console.error(`· ${msg.meta.status}`);
+    else if (msg.t === 'decision')
+        console.error(`· ${msg.decision.prompt}\n` +
+            msg.decision.options.map((o) => `   [${o.id}] ${o.label}`).join('\n'));
+}
+function printEvent(e) {
+    const b = e.body;
+    switch (b.kind) {
+        case 'user_text':
+            console.log(`\n> ${b.text}`);
+            break;
+        case 'assistant_text':
+            console.log(`\n${b.text}`);
+            break;
+        case 'tool_use':
+            console.log(`  ⚙ ${b.name}(${short(JSON.stringify(b.input ?? ''))})`);
+            break;
+        case 'tool_result':
+            console.log(`  ${b.ok ? '✓' : '✗'} ${short(b.summary)}`);
+            break;
+        case 'system':
+            console.log(`  · ${b.text}`);
+            break;
+        case 'assistant_thinking':
+        case 'turn_complete':
+            break;
+    }
+}
+function parseArgs(args) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith('--'))
+            flags[a.slice(2)] = args[++i] ?? '';
+        else
+            positionals.push(a);
+    }
+    return { positionals, flags };
+}
+function pad(s, n) {
+    return s.length >= n ? s : s + ' '.repeat(n - s.length);
+}
+function short(s) {
+    return s.length > 80 ? s.slice(0, 80) + '…' : s;
+}
+function printHelp() {
+    console.log([
+        'kernelpm — keep opencode sessions alive on a server',
+        '',
+        '  kernelpm daemon start|stop|status|run',
+        '  kernelpm list',
+        '  kernelpm new <cwd> [--title T] [--model M]',
+        '  kernelpm attach <id>',
+        '  kernelpm send <id> <text...>',
+        '  kernelpm kill <id>',
+    ].join('\n'));
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+});

package/dist/client.js

@@ -0,0 +1,137 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ControlClient = void 0;
+/**
+ * A minimal control-socket client used by the kernelpm CLI (and handy for
+ * tests). Correlates requests to replies by `rid`; everything without a pending
+ * `rid` (events, status, decisions) is delivered to the push handler.
+ */
+const net = __importStar(require("net"));
+class ControlClient {
+    socket = null;
+    buf = '';
+    ridSeq = 0;
+    pending = new Map();
+    onPush = null;
+    connect(sockPath, token, onPush) {
+        this.onPush = onPush ?? null;
+        return new Promise((resolve, reject) => {
+            const socket = net.createConnection(sockPath);
+            this.socket = socket;
+            socket.setEncoding('utf8');
+            socket.once('error', reject);
+            socket.on('data', (d) => this.onData(d));
+            socket.on('close', () => {
+                for (const p of this.pending.values())
+                    p.reject(new Error('connection closed'));
+                this.pending.clear();
+            });
+            socket.once('connect', () => {
+                socket.removeListener('error', reject);
+                socket.on('error', () => undefined);
+                this.request({ t: 'hello', rid: this.rid(), token })
+                    .then((m) => (m.t === 'hello.ok' ? resolve() : reject(new Error('handshake failed'))))
+                    .catch(reject);
+            });
+        });
+    }
+    rid() {
+        return ++this.ridSeq;
+    }
+    request(msg) {
+        return new Promise((resolve, reject) => {
+            if (!this.socket)
+                return reject(new Error('not connected'));
+            this.pending.set(msg.rid, { resolve, reject });
+            this.socket.write(JSON.stringify(msg) + '\n');
+        });
+    }
+    async list() {
+        const r = await this.request({ t: 'listSessions', rid: this.rid() });
+        return r.t === 'sessions' ? r.sessions : [];
+    }
+    async create(cwd, title, model) {
+        const r = await this.request({ t: 'createSession', rid: this.rid(), cwd, title, model });
+        if (r.t !== 'created')
+            throw new Error('create failed');
+        return r.session;
+    }
+    attach(id, sinceSeq = 0) {
+        return this.request({ t: 'attach', rid: this.rid(), id, sinceSeq });
+    }
+    send(id, text) {
+        return this.request({ t: 'sendMessage', rid: this.rid(), id, text });
+    }
+    answer(id, decisionId, optionId) {
+        return this.request({ t: 'answerDecision', rid: this.rid(), id, decisionId, optionId });
+    }
+    kill(id) {
+        return this.request({ t: 'killSession', rid: this.rid(), id });
+    }
+    close() {
+        this.socket?.end();
+    }
+    onData(chunk) {
+        this.buf += chunk;
+        let i;
+        while ((i = this.buf.indexOf('\n')) >= 0) {
+            const line = this.buf.slice(0, i).trim();
+            this.buf = this.buf.slice(i + 1);
+            if (!line)
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const rid = msg.rid;
+            const waiter = rid ? this.pending.get(rid) : undefined;
+            if (waiter) {
+                this.pending.delete(rid);
+                if (msg.t === 'error')
+                    waiter.reject(new Error(msg.message));
+                else
+                    waiter.resolve(msg);
+            }
+            else {
+                this.onPush?.(msg);
+            }
+        }
+    }
+}
+exports.ControlClient = ControlClient;

package/dist/control.js

@@ -0,0 +1,184 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createControlServer = createControlServer;
+/**
+ * The control socket: a line-delimited JSON server speaking the kernelpm wire
+ * protocol over a Unix domain socket. Each connection authenticates with the
+ * daemon token (read by the local CLI from disk, or by the broker over SSH),
+ * then issues requests and receives pushes for the sessions it attaches to.
+ */
+const net = __importStar(require("net"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const crypto_1 = require("crypto");
+const daemon_1 = require("./daemon");
+const files_1 = require("./files");
+class SocketClient {
+    socket;
+    daemon;
+    id = (0, crypto_1.randomUUID)();
+    authed = false;
+    buf = '';
+    constructor(socket, daemon) {
+        this.socket = socket;
+        this.daemon = daemon;
+        socket.setEncoding('utf8');
+        socket.on('data', (chunk) => this.onData(chunk));
+        socket.on('close', () => this.daemon.dropClient(this));
+        socket.on('error', () => {
+            /* a dropped client is handled on close */
+        });
+        daemon.addClient(this);
+    }
+    send(msg) {
+        try {
+            this.socket.write(JSON.stringify(msg) + '\n');
+        }
+        catch {
+            /* socket closing */
+        }
+    }
+    onData(chunk) {
+        this.buf += chunk;
+        let idx;
+        while ((idx = this.buf.indexOf('\n')) >= 0) {
+            const line = this.buf.slice(0, idx).trim();
+            this.buf = this.buf.slice(idx + 1);
+            if (line)
+                void this.dispatch(line);
+        }
+    }
+    async dispatch(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            this.send({ t: 'error', message: 'invalid json' });
+            return;
+        }
+        const rid = msg.rid ?? 0;
+        try {
+            if (msg.t === 'hello') {
+                if (msg.token !== this.daemon.token)
+                    throw new Error('bad token');
+                this.authed = true;
+                this.send({ t: 'hello.ok', rid, daemonVersion: daemon_1.DAEMON_VERSION });
+                return;
+            }
+            if (!this.authed)
+                throw new Error('not authenticated');
+            switch (msg.t) {
+                case 'listSessions':
+                    this.send({ t: 'sessions', rid, sessions: this.daemon.list() });
+                    break;
+                case 'createSession': {
+                    const session = await this.daemon.create(msg.cwd, msg.title, msg.model);
+                    this.send({ t: 'created', rid, session });
+                    break;
+                }
+                case 'attach':
+                    await this.daemon.attachClient(this, msg.id, rid, msg.sinceSeq ?? 0);
+                    break;
+                case 'detach':
+                    this.daemon.detachClient(this, msg.id);
+                    this.send({ t: 'ok', rid });
+                    break;
+                case 'sendMessage':
+                    await this.daemon.send(msg.id, msg.text);
+                    this.send({ t: 'ok', rid });
+                    break;
+                case 'answerDecision':
+                    await this.daemon.answer(msg.id, msg.decisionId, msg.optionId);
+                    this.send({ t: 'ok', rid });
+                    break;
+                case 'killSession':
+                    await this.daemon.kill(msg.id);
+                    this.send({ t: 'ok', rid });
+                    break;
+                case 'restartSession':
+                    await this.daemon.restart(msg.id);
+                    this.send({ t: 'ok', rid });
+                    break;
+                case 'listDir': {
+                    const dir = resolveDir(msg.path);
+                    this.send({ t: 'dir', rid, path: dir, entries: await readDir(dir) });
+                    break;
+                }
+                case 'getTree': {
+                    const cwd = resolveDir(msg.cwd);
+                    this.send({ t: 'tree', rid, cwd, tree: await (0, files_1.buildTree)(cwd) });
+                    break;
+                }
+                case 'readFile': {
+                    const cwd = resolveDir(msg.cwd);
+                    const r = await (0, files_1.readProjectFile)(cwd, msg.path);
+                    this.send({ t: 'file', rid, path: msg.path, git: r.git, lines: r.lines, diff: r.diff });
+                    break;
+                }
+                default:
+                    throw new Error(`unknown message: ${msg.t}`);
+            }
+        }
+        catch (err) {
+            this.send({ t: 'error', rid, message: errorMessage(err) });
+        }
+    }
+}
+function createControlServer(daemon) {
+    return net.createServer((socket) => {
+        new SocketClient(socket, daemon);
+    });
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Expand '~' / empty to the daemon user's home; otherwise normalize absolute. */
+function resolveDir(p) {
+    if (!p || p === '~')
+        return os.homedir();
+    if (p === '~/' || p.startsWith('~/'))
+        return path.join(os.homedir(), p.slice(2));
+    return path.resolve(p);
+}
+/** List a directory, folders first then files, alphabetically within each group. */
+async function readDir(dir) {
+    const dirents = await fs.promises.readdir(dir, { withFileTypes: true });
+    return dirents
+        .map((d) => ({ name: d.name, dir: d.isDirectory() }))
+        .sort((a, b) => (a.dir === b.dir ? a.name.localeCompare(b.name) : a.dir ? -1 : 1));
+}