@celilo/core 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/core",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Lightweight shared core for Celilo CLI tools — command registry, NDJSON API protocol, and remote SSH client. No Ink/React/drizzle/aws-sdk transitive deps, so an MCP server can reach the transport without installing the full CLI.",
   "type": "module",
   "main": "./src/index.ts",

package/src/command-registry.ts

@@ -150,6 +150,10 @@ export const COMMANDS: CommandDef[] = [
           },
         ],
       },
+      {
+        name: 'sweep',
+        description: 'Reap expired API sessions and prune retired records (hourly subscriber)',
+      },
     ],
   },
   {

package/src/remote-client.ts

@@ -240,16 +240,19 @@ interface StreamOptions {
   onBlocked: 'return' | 'wait';
 }
 
-/** Read the server's NDJSON stream until it goes terminal. */
-async function consumeStream(
-  transport: RemoteTransport,
-  opts: StreamOptions,
-): Promise<RemoteOutcome | null> {
-  const { out, display, renderInterview } = opts;
+/**
+ * The server's NDJSON stream, split into lines, as a generator that OUTLIVES a
+ * single command.
+ *
+ * `api-serve` is a persistent server: it loops reading commands until stdin
+ * closes, and its own protocol has always allowed many commands per connection.
+ * Splitting inside `consumeStream` tied the reader's lifetime to one command,
+ * so the only way to run a second was to open a second connection and re-pay
+ * the server's start-up. Hoisting the split is what lets a session reuse one.
+ */
+async function* lineStream(transport: RemoteTransport): AsyncGenerator<string> {
   const decoder = new TextDecoder();
-  const errors: string[] = [];
   let buffer = '';
-
   for await (const chunk of transport.stdout) {
     buffer += decoder.decode(chunk, { stream: true });
     let nl = buffer.indexOf('\n');
@@ -257,7 +260,32 @@ async function consumeStream(
       const line = buffer.slice(0, nl);
       buffer = buffer.slice(nl + 1);
       nl = buffer.indexOf('\n');
-      if (!line.trim()) continue;
+      if (line.trim()) yield line;
+    }
+  }
+}
+
+/**
+ * Read the server's NDJSON stream until it goes terminal.
+ *
+ * Pulls from `lines` with an explicit `next()` rather than `for await`, because
+ * `for await` calls the iterator's `return()` when this function returns — which
+ * would close the generator and make the connection single-use again. That is
+ * the whole mechanism of connection reuse, in one loop construct.
+ */
+async function consumeStream(
+  transport: RemoteTransport,
+  lines: AsyncGenerator<string>,
+  opts: StreamOptions,
+): Promise<RemoteOutcome | null> {
+  const { out, display, renderInterview } = opts;
+  const errors: string[] = [];
+
+  while (true) {
+    const next = await lines.next();
+    if (next.done === true) break;
+    {
+      const line = next.value;
 
       let msg: ServerMessage;
       try {
@@ -340,6 +368,113 @@ export async function runRemoteClient(
   return openAndConsume(dest, { type: 'command', argv }, opts);
 }
 
+/**
+ * One connection, many commands.
+ *
+ * `runRemoteClient` opens a transport, sends ONE command and kills it. That is
+ * right for a CLI invocation and wrong for a poller: `api-serve` is a
+ * persistent server whose read loop accepts commands until stdin closes, so a
+ * caller issuing a command every few seconds re-paid its start-up every time.
+ *
+ * Measured on celilo-mgr, 2026-09-28, three commands on ONE connection:
+ *
+ *     ready                    1.80s
+ *     result 1 (alerts list)   3.44s   -> 1.64s of work after start-up
+ *     result 2 (alerts list)   7.25s   -> 1.25s   (sent at 6s)
+ *     result 3 (console status) 12.06s -> 0.06s   (sent at 12s)
+ *
+ * The ~1.8s is paid ONCE. The web console was paying it on every panel read,
+ * which is most of why a panel cost 5-11s against a 15s client timeout.
+ *
+ * Commands are SERIALIZED, because the server runs one at a time — `serve.ts`
+ * holds a single `commandRunning` slot. Issuing two concurrently would
+ * interleave their output on one stream with nothing to correlate it by, so the
+ * queue here is not a policy choice, it mirrors the server.
+ *
+ * This does NOT reintroduce celilo#921. That was 656 ORPHANED ssh clients
+ * accumulating because nothing closed them; a session is one connection with an
+ * explicit `close()`, and the transport registry still kills it on exit.
+ */
+export interface RemoteSession {
+  /**
+   * Run one command and resolve on its terminal message. Queued behind any
+   * command already in flight.
+   *
+   * Rejects if the session is closed, rather than silently opening a second
+   * connection — a caller that wants a new one should say so.
+   */
+  run(argv: readonly string[], opts?: { out?: DisplayWriter }): Promise<RemoteOutcome>;
+  /** Tear the connection down. Idempotent. */
+  close(): void;
+  /** True once `close()` ran, or the server's stream ended. */
+  readonly closed: boolean;
+}
+
+export function openRemoteSession(dest: string, opts: RemoteClientOptions = {}): RemoteSession {
+  const openTransport = opts.openTransport ?? openSshTransport;
+  const transport = openTransport(dest);
+  const lines = lineStream(transport);
+
+  let closed = false;
+  // Commands run one at a time. The chain is the queue: each run appends to it,
+  // so a caller never has to know whether another is in flight.
+  let tail: Promise<unknown> = Promise.resolve();
+
+  const close = (): void => {
+    if (closed) return;
+    closed = true;
+    try {
+      transport.kill();
+    } catch {
+      // Already gone. Closing twice must not throw at a caller trying to tidy up.
+    }
+  };
+
+  const runOne = async (
+    argv: readonly string[],
+    runOpts: { out?: DisplayWriter } = {},
+  ): Promise<RemoteOutcome> => {
+    if (closed) throw new Error('remote session is closed');
+    const out = runOpts.out ?? opts.out ?? process.stdout;
+
+    transport.stdin.write(`${JSON.stringify({ type: 'command', argv: [...argv] })}\n`);
+    await transport.stdin.flush?.();
+
+    const outcome = await consumeStream(transport, lines, {
+      out,
+      display: new ProgressDisplay({ out }),
+      renderInterview: opts.renderInterview ?? defaultRenderInterview,
+      // A session is headless by construction: it is reused precisely because
+      // nobody is sitting at it. Waiting on a question would wedge every later
+      // command behind one nobody is going to answer.
+      onBlocked: opts.onBlocked ?? 'return',
+    });
+
+    if (outcome === null) {
+      // The stream ended mid-command: the server went away. Mark the session
+      // dead so the next caller opens a fresh one instead of writing into a
+      // pipe nobody reads.
+      close();
+      return { status: 'result', exitCode: await transport.exited };
+    }
+    return outcome;
+  };
+
+  return {
+    run(argv, runOpts) {
+      const result = tail.then(() => runOne(argv, runOpts));
+      // The queue must survive a failed command, or one rejection strands every
+      // command behind it forever.
+      tail = result.catch(() => undefined);
+      return result;
+    },
+    close,
+    get closed() {
+      return closed;
+    },
+  };
+}
+
 /**
  * Re-join a parked session: replays the output produced while nobody was
  * attached, then streams the rest through to the terminal `result`.
@@ -377,7 +512,7 @@ async function openAndConsume(
   transport.stdin.write(`${JSON.stringify(opening)}\n`);
   await transport.stdin.flush?.();
 
-  const outcome = await consumeStream(transport, {
+  const outcome = await consumeStream(transport, lineStream(transport), {
     out,
     display: new ProgressDisplay({ out }),
     renderInterview: opts.renderInterview ?? defaultRenderInterview,

package/src/remote-session.test.ts

@@ -0,0 +1,131 @@
+/**
+ * One connection, many commands.
+ *
+ * `runRemoteClient` opens a transport, sends one command and kills it. For a
+ * poller that re-pays the server's start-up every time: measured on celilo-mgr,
+ * `ready` at 1.80s then commands at 1.64s / 1.25s / 0.06s on the SAME
+ * connection. The web console was paying the 1.8s per panel read.
+ *
+ * WATCHED RED: switching `consumeStream`'s manual `lines.next()` back to
+ * `for await (const line of lines)` turns 'a second command reuses the
+ * connection' red — `for await` calls the generator's `return()` when the
+ * function returns, closing the reader and making the connection single-use.
+ * That one loop construct IS the mechanism.
+ */
+import { describe, expect, test } from 'bun:test';
+import { API_PROTOCOL_VERSION, type RemoteTransport, openRemoteSession } from './index';
+
+function ndjson(...messages: unknown[]): Uint8Array {
+  return new TextEncoder().encode(`${messages.map((m) => JSON.stringify(m)).join('\n')}\n`);
+}
+
+/** A server that answers each command it is sent, on one long-lived stream. */
+function fakeServer() {
+  const state = { opens: 0, sent: [] as string[], closed: false };
+  let push: ((b: Uint8Array) => void) | null = null;
+  let finish: (() => void) | null = null;
+
+  const open = (): RemoteTransport => {
+    state.opens += 1;
+    const stdout = new ReadableStream<Uint8Array>({
+      start(c) {
+        push = (b) => c.enqueue(b);
+        finish = () => {
+          try {
+            c.close();
+          } catch {
+            // already closed
+          }
+        };
+        c.enqueue(ndjson({ type: 'ready', protocolVersion: API_PROTOCOL_VERSION }));
+      },
+    });
+    return {
+      stdin: {
+        write: (s: string) => {
+          state.sent.push(s.trim());
+          const argv = JSON.parse(s).argv as string[];
+          // Answer asynchronously, as a real server would.
+          queueMicrotask(() =>
+            push?.(
+              ndjson(
+                { type: 'log', message: `ran ${argv.join(' ')}`, stream: 'stdout' },
+                { type: 'result', success: true, exitCode: 0 },
+              ),
+            ),
+          );
+        },
+        end: () => {},
+      },
+      stdout,
+      kill: () => {
+        state.closed = true;
+        finish?.();
+      },
+      exited: Promise.resolve(0),
+    };
+  };
+  return { state, open };
+}
+
+const collect = () => {
+  const lines: string[] = [];
+  return { out: { write: (s: string) => lines.push(s), isTTY: false }, lines };
+};
+
+describe('openRemoteSession', () => {
+  test('a second command reuses the connection instead of opening another', async () => {
+    const { state, open } = fakeServer();
+    const s = openRemoteSession('celilo-api@example', { openTransport: open });
+
+    const a = collect();
+    const b = collect();
+    expect(await s.run(['alerts', 'list'], { out: a.out })).toMatchObject({
+      status: 'result',
+      exitCode: 0,
+    });
+    expect(await s.run(['console', 'status'], { out: b.out })).toMatchObject({
+      status: 'result',
+      exitCode: 0,
+    });
+
+    expect(state.opens).toBe(1); // the whole point
+    expect(a.lines.join('')).toContain('ran alerts list');
+    expect(b.lines.join('')).toContain('ran console status');
+    s.close();
+  });
+
+  test('commands are serialized, because the server runs one at a time', async () => {
+    const { state, open } = fakeServer();
+    const s = openRemoteSession('celilo-api@example', { openTransport: open });
+
+    // Issued together, without awaiting between them.
+    await Promise.all([s.run(['a']), s.run(['b']), s.run(['c'])]);
+
+    expect(state.opens).toBe(1);
+    // Order preserved, and each was written only after the previous finished.
+    expect(state.sent.map((l) => JSON.parse(l).argv[0])).toEqual(['a', 'b', 'c']);
+    s.close();
+  });
+
+  test('a failed command does not strand the ones queued behind it', async () => {
+    // The queue is a promise chain; without catching, one rejection poisons the
+    // tail and every later command hangs on it forever.
+    const { open } = fakeServer();
+    const s = openRemoteSession('celilo-api@example', { openTransport: open });
+    s.close(); // force the next run to reject
+    await expect(s.run(['a'])).rejects.toThrow(/closed/);
+    await expect(s.run(['b'])).rejects.toThrow(/closed/);
+  });
+
+  test('close is idempotent and refuses further commands', async () => {
+    const { state, open } = fakeServer();
+    const s = openRemoteSession('celilo-api@example', { openTransport: open });
+    await s.run(['alerts', 'list']);
+    s.close();
+    s.close();
+    expect(state.closed).toBe(true);
+    expect(s.closed).toBe(true);
+    await expect(s.run(['again'])).rejects.toThrow(/closed/);
+  });
+});