Interface ShellRPC

packages/rpc/src/interface.ts:93–133

// Runner is the concrete implementation today; the interface keeps
// that dependency out of the wire contract.
export interface ShellRPC {
  // Spawn a command in the container. Returns an id (caller-
  // supplied or runner-minted) and a ReadableStream of ExecEvents.
  // Capnweb streams handle backpressure end-to-end; consumer-side
  // slowness propagates to the spawned process via the kernel pipe.
  exec(input: {
    command: string;
    cwd?: string;
    id?: string;
    // Per-call timeout in milliseconds. Past this duration the
    // container sends SIGTERM (then SIGKILL after a short grace).
    // 0 disables the timeout. Omit to use the runner's default
    // (typically 320_000).
    timeoutMs?: number;
    // Environment variables inherited by this command only.
    env?: Record<string, string>;
    // Standard input bytes fed to the command.
    stdin?: Uint8Array;
  }): Promise<{
    id: string;
    events: ReadableStream<ExecEvent>;
  }>;

  // Reattach to an in-flight or recently-completed exec by id.
  // Pass `after` to resume from a known seq; "tail" yields only
  // future events; omit to receive every event from the start.
  getExec(input: { id: string; after?: number | "tail" }): Promise<{
    id: string;
    events: ReadableStream<ExecEvent>;
  }>;

  // Signal a running exec. No-op once the process has exited.
  killExec(input: {
    id: string;
    signal?: "SIGTERM" | "SIGKILL" | "SIGINT" | "SIGHUP";
  }): Promise<void>;

  // Release the event log for a completed exec. Future getExec on
  // the same id throws ENOENT.
  disposeExec(input: { id: string }): Promise<void>;
}

// Composite stub. The wire serves one of these per session; the
// two halves are independently testable. Host-side callers reach