@celilo/core 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/core",
-  "version": "0.4.0",
+  "version": "0.6.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

@@ -168,6 +168,23 @@ export const COMMANDS: CommandDef[] = [
           { name: 'limit', description: 'Max rows to return', takesValue: true },
         ],
       },
+      {
+        name: 'list-failed',
+        description: 'List failed/abandoned deliveries with a true total',
+        flags: [
+          {
+            name: 'subscriber',
+            description: 'Restrict to a subscriber by name',
+            takesValue: true,
+          },
+          { name: 'limit', description: 'Max rows to return', takesValue: true },
+        ],
+      },
+      {
+        name: 'list-unanswered',
+        description: 'List interview questions nobody has answered yet',
+        flags: [{ name: 'limit', description: 'Max rows to return', takesValue: true }],
+      },
       {
         name: 'drain',
         description: 'Process pending deliveries once and return',

package/src/protocol.ts

@@ -3,8 +3,8 @@
  *
  * A versioned, Zod-validated tagged union carried as NDJSON. This is the
  * transport-neutral message layer for driving the CLI over the wire — see
- * `openspec/changes/replace-ssh-cli-api/proposal.md`. Slice 1 covers non-interactive command execution
- * + streamed output; `interview` / `answer` / `cancel` arrive in Slice 3.
+ * `openspec/changes/replace-ssh-cli-api/proposal.md` and
+ * `openspec/changes/park-unanswerable-interviews/proposal.md`.
  *
  * The command crosses the wire as a *structured, validated* `argv` array —
  * never a shell string handed to `exec`.
@@ -23,26 +23,53 @@ export const CommandMessageSchema = z.object({
 });
 export type CommandMessage = z.infer<typeof CommandMessageSchema>;
 
-/**
- * Client's answer to a server `interview` message, correlated by `id`.
- *
- * `error` is the "I cannot answer this" reply: the client had no way to reach a
- * decider (no TTY, no pre-staged answer). The server fails the waiting command
- * with that message instead of it resolving to the question's `defaultValue` —
- * an unanswered question must never become a silent "no".
- */
+/** Client's answer to a server `interview` message, correlated by `id`. */
 export const AnswerMessageSchema = z.object({
   type: z.literal('answer'),
   id: z.string(),
   value: z.unknown(),
-  error: z.string().optional(),
 });
 export type AnswerMessage = z.infer<typeof AnswerMessageSchema>;
 
+/**
+ * "I cannot decide this" — the client had no way to reach a decider (no TTY, no
+ * pre-staged answer) for the `interview` with this `id`.
+ *
+ * It is deliberately NOT an `answer`: the server must not resolve the question,
+ * because a resolution of any shape consumes it and nobody else can then answer.
+ * The server parks the command and replies `blocked` (celilo#609).
+ */
+export const UnanswerableMessageSchema = z.object({
+  type: z.literal('unanswerable'),
+  id: z.string(),
+  reason: z.string(),
+});
+export type UnanswerableMessage = z.infer<typeof UnanswerableMessageSchema>;
+
+/** Re-join a parked session's output stream. Authorized against its owner. */
+export const AttachMessageSchema = z.object({
+  type: z.literal('attach'),
+  sessionId: z.string(),
+});
+export type AttachMessage = z.infer<typeof AttachMessageSchema>;
+
+/**
+ * Deliberately abandon a parked session before its TTL expires: the outstanding
+ * query is answered `abandoned`, the command fails naming what was never
+ * decided, and the record is retained.
+ */
+export const CancelMessageSchema = z.object({
+  type: z.literal('cancel'),
+  sessionId: z.string(),
+});
+export type CancelMessage = z.infer<typeof CancelMessageSchema>;
+
 export const ClientMessageSchema = z.discriminatedUnion('type', [
   CommandMessageSchema,
   AnswerMessageSchema,
-  // Slice 3+: CancelMessageSchema
+  UnanswerableMessageSchema,
+  AttachMessageSchema,
+  CancelMessageSchema,
 ]);
 export type ClientMessage = z.infer<typeof ClientMessageSchema>;
 
@@ -119,6 +146,23 @@ export const InterviewMessageSchema = z.object({
 });
 export type InterviewMessage = z.infer<typeof InterviewMessageSchema>;
 
+/**
+ * Terminal-for-now: the command is parked on a question this client cannot
+ * decide. The command is still alive server-side under `sessionId`; answer
+ * `eventId` (`celilo events reply <eventId> <value>`) and `attach` to collect
+ * the outcome. Not a failure and not a decline — nothing was decided yet.
+ */
+export const BlockedMessageSchema = z.object({
+  type: z.literal('blocked'),
+  sessionId: z.string(),
+  /** Bus event id of the unanswered query, as a string. */
+  eventId: z.string(),
+  question: z.string(),
+  /** The question's `<scope>.<key>`, when the server sent one. */
+  key: z.string().optional(),
+});
+export type BlockedMessage = z.infer<typeof BlockedMessageSchema>;
+
 export const ServerMessageSchema = z.discriminatedUnion('type', [
   ReadyMessageSchema,
   ProgressMessageSchema,
@@ -126,6 +170,7 @@ export const ServerMessageSchema = z.discriminatedUnion('type', [
   ResultMessageSchema,
   ErrorMessageSchema,
   InterviewMessageSchema,
+  BlockedMessageSchema,
 ]);
 export type ServerMessage = z.infer<typeof ServerMessageSchema>;
 

package/src/remote-client.ts

@@ -12,7 +12,12 @@ import { spawn } from 'node:child_process';
 import { Readable } from 'node:stream';
 import { type DisplayWriter, ProgressDisplay } from '@celilo/cli-display';
 import * as clack from '@clack/prompts';
-import { type InterviewMessage, type ServerMessage, ServerMessageSchema } from './protocol';
+import {
+  type ClientMessage,
+  type InterviewMessage,
+  type ServerMessage,
+  ServerMessageSchema,
+} from './protocol';
 
 const REMOTE_FLAG = '--remote';
 
@@ -23,8 +28,9 @@ export function interviewKey(iv: InterviewMessage): string | null {
 
 /**
  * Thrown by a renderer that has no way to reach a decider. `runRemoteClient`
- * turns it into an `answer` carrying `error`, so the server fails the waiting
- * command loudly rather than the question resolving to its default.
+ * turns it into an `unanswerable` message — never an `answer` — so the server
+ * parks the command with the question still standing rather than resolving it
+ * (to a default, or to anything else) on nobody's authority.
  */
 export class InterviewUnanswerableError extends Error {
   constructor(message: string) {
@@ -86,7 +92,15 @@ async function defaultRenderInterview(iv: InterviewMessage): Promise<unknown> {
 
 /** Minimal transport surface — satisfied by a `node:child_process` spawn of `ssh`. */
 export interface RemoteTransport {
-  stdin: { write(chunk: string): void; flush?(): number | Promise<number> };
+  stdin: {
+    write(chunk: string): void;
+    flush?(): number | Promise<number>;
+    /**
+     * Close our end without tearing the server down. Used when a command parks:
+     * killing the transport kills the session we specifically want to survive.
+     */
+    end?(): void;
+  };
   stdout: ReadableStream<Uint8Array>;
   kill(): void;
   exited: Promise<number>;
@@ -121,7 +135,10 @@ function openSshTransport(dest: string): RemoteTransport {
   const proc = spawn('ssh', ['-T', dest], { stdio: ['pipe', 'pipe', 'inherit'] });
   if (!proc.stdout || !proc.stdin) throw new Error('ssh was not spawned with piped stdio');
   return {
-    stdin: { write: (chunk: string) => void proc.stdin?.write(chunk) },
+    stdin: {
+      write: (chunk: string) => void proc.stdin?.write(chunk),
+      end: () => void proc.stdin?.end(),
+    },
     stdout: Readable.toWeb(proc.stdout) as unknown as ReadableStream<Uint8Array>,
     kill: () => void proc.kill(),
     exited: new Promise<number>((resolve) => proc.once('exit', (code) => resolve(code ?? 0))),
@@ -171,6 +188,7 @@ function applyMessage(
       process.stderr.write(`${msg.error}\n`);
       return null;
     case 'interview':
+    case 'blocked':
       // Handled by the caller (needs the transport to reply) — never reached here.
       return null;
     case 'result':
@@ -178,36 +196,40 @@ function applyMessage(
   }
 }
 
-export async function runRemoteClient(
-  dest: string,
-  argv: string[],
-  opts: {
-    openTransport?: (dest: string) => RemoteTransport;
-    out?: DisplayWriter;
-    renderInterview?: (interview: InterviewMessage) => Promise<unknown>;
-  } = {},
-): Promise<number> {
-  if (argv.length === 0) {
-    process.stderr.write(
-      'celilo --remote <dest> requires a command (e.g. celilo --remote host module list)\n',
-    );
-    return 2;
-  }
+/**
+ * How a remote run ended. `blocked` is not a failure and not a decline: the
+ * command is parked server-side on a question this client could not decide, and
+ * is still alive under `sessionId`.
+ */
+export type RemoteOutcome =
+  | { status: 'result'; exitCode: number }
+  | { status: 'blocked'; sessionId: string; eventId: string; question: string; key?: string };
 
-  const openTransport = opts.openTransport ?? openSshTransport;
-  const out = opts.out ?? process.stdout;
-  const renderInterview = opts.renderInterview ?? defaultRenderInterview;
-  const display = new ProgressDisplay({ out });
+/** Exit code a caller reports when a command parked rather than finishing. */
+export const EXIT_BLOCKED = 75; // EX_TEMPFAIL — try again once it's answered.
 
-  const transport = openTransport(dest);
-  transport.stdin.write(`${JSON.stringify({ type: 'command', argv })}\n`);
-  await transport.stdin.flush?.();
+interface StreamOptions {
+  out: DisplayWriter;
+  display: ProgressDisplay;
+  renderInterview: (interview: InterviewMessage) => Promise<unknown>;
+  /**
+   * What to do with a `blocked` message. A caller that *is* a decider (an
+   * operator at a terminal) keeps waiting; a headless one returns so it can
+   * answer out-of-band and attach later.
+   */
+  onBlocked: 'return' | 'wait';
+}
 
-  let resultExit: number | null = null;
+/** 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;
   const decoder = new TextDecoder();
   let buffer = '';
 
-  outer: for await (const chunk of transport.stdout) {
+  for await (const chunk of transport.stdout) {
     buffer += decoder.decode(chunk, { stream: true });
     let nl = buffer.indexOf('\n');
     while (nl >= 0) {
@@ -226,38 +248,126 @@ export async function runRemoteClient(
       }
 
       if (msg.type === 'interview') {
-        let answer: { type: 'answer'; id: string; value: unknown; error?: string };
+        let reply: string;
         try {
-          answer = { type: 'answer', id: msg.id, value: await renderInterview(msg) };
+          const value = await renderInterview(msg);
+          reply = JSON.stringify({ type: 'answer', id: msg.id, value });
         } catch (err) {
-          // Never fabricate an answer: tell the server we can't decide, and let
-          // it fail the waiting command with this message.
-          answer = {
-            type: 'answer',
+          // Never fabricate an answer, and never resolve the question at all:
+          // say we can't decide and let the server park it.
+          reply = JSON.stringify({
+            type: 'unanswerable',
             id: msg.id,
-            value: null,
-            error: err instanceof Error ? err.message : String(err),
-          };
+            reason: err instanceof Error ? err.message : String(err),
+          });
         }
-        transport.stdin.write(`${JSON.stringify(answer)}\n`);
+        transport.stdin.write(`${reply}\n`);
         await transport.stdin.flush?.();
         continue;
       }
 
-      const exit = applyMessage(msg, display, out);
-      if (exit !== null) {
-        resultExit = exit;
-        break outer;
+      if (msg.type === 'blocked') {
+        if (opts.onBlocked === 'wait') {
+          out.write(
+            `Waiting on: ${msg.question} (answer with: celilo events reply ${msg.eventId} <value>)\n`,
+          );
+          continue;
+        }
+        return {
+          status: 'blocked',
+          sessionId: msg.sessionId,
+          eventId: msg.eventId,
+          question: msg.question,
+          key: msg.key,
+        };
       }
+
+      const exit = applyMessage(msg, display, out);
+      if (exit !== null) return { status: 'result', exitCode: exit };
     }
   }
+  return null;
+}
+
+export interface RemoteClientOptions {
+  openTransport?: (dest: string) => RemoteTransport;
+  out?: DisplayWriter;
+  renderInterview?: (interview: InterviewMessage) => Promise<unknown>;
+  onBlocked?: 'return' | 'wait';
+}
 
-  if (resultExit !== null) {
-    // Server is still looping awaiting more input — tear it down.
-    transport.kill();
-    return resultExit;
+export async function runRemoteClient(
+  dest: string,
+  argv: string[],
+  opts: RemoteClientOptions = {},
+): Promise<RemoteOutcome> {
+  if (argv.length === 0) {
+    process.stderr.write(
+      'celilo --remote <dest> requires a command (e.g. celilo --remote host module list)\n',
+    );
+    return { status: 'result', exitCode: 2 };
+  }
+
+  return openAndConsume(dest, { type: 'command', argv }, opts);
+}
+
+/**
+ * Re-join a parked session: replays the output produced while nobody was
+ * attached, then streams the rest through to the terminal `result`.
+ */
+export function attachRemoteClient(
+  dest: string,
+  sessionId: string,
+  opts: RemoteClientOptions = {},
+): Promise<RemoteOutcome> {
+  return openAndConsume(dest, { type: 'attach', sessionId }, opts);
+}
+
+/**
+ * Deliberately abandon a parked session: its outstanding question is answered
+ * `abandoned` and the command fails naming what was never decided. The
+ * operator-initiated counterpart to the TTL reaper.
+ */
+export function cancelRemoteClient(
+  dest: string,
+  sessionId: string,
+  opts: RemoteClientOptions = {},
+): Promise<RemoteOutcome> {
+  return openAndConsume(dest, { type: 'cancel', sessionId }, opts);
+}
+
+/** Open a transport, send one opening message, and consume until terminal. */
+async function openAndConsume(
+  dest: string,
+  opening: ClientMessage,
+  opts: RemoteClientOptions,
+): Promise<RemoteOutcome> {
+  const openTransport = opts.openTransport ?? openSshTransport;
+  const out = opts.out ?? process.stdout;
+  const transport = openTransport(dest);
+  transport.stdin.write(`${JSON.stringify(opening)}\n`);
+  await transport.stdin.flush?.();
+
+  const outcome = await consumeStream(transport, {
+    out,
+    display: new ProgressDisplay({ out }),
+    renderInterview: opts.renderInterview ?? defaultRenderInterview,
+    // A terminal operator is a decider, so they wait rather than being handed a
+    // session id to answer out-of-band.
+    onBlocked: opts.onBlocked ?? (process.stdin.isTTY ? 'wait' : 'return'),
+  });
+
+  if (outcome?.status === 'blocked') {
+    // Do NOT kill: the command is parked and must outlive us. Close our stdin
+    // and leave; the server keeps the child and buffers its output.
+    transport.stdin.end?.();
+    return outcome;
   }
 
-  // Stream ended without a result — surface the transport's exit (ssh failure).
-  return transport.exited;
+  // Server is still looping awaiting more input — tear our end down.
+  transport.kill();
+  if (outcome) return outcome;
+
+  // Stream ended without a terminal message — surface the transport's exit.
+  return { status: 'result', exitCode: await transport.exited };
 }