packages/experimental/webworker-runtime/src/shell/process/protocol.ts

/**
 * The frames a shell process and its host exchange.
 *
 * A command runs in its own Web Worker, which owns no filesystem: the VFS
 * stays in the host worker and every read or write is a request on this
 * channel. Blocking the child on a reply is impossible here (that would need
 * `SharedArrayBuffer`, which requires a cross-origin isolation this deployment
 * cannot have), so the filesystem face is asynchronous end to end.
 * @module @deepseek-ai/dsh-experimental-webworker-runtime/src/shell/process/protocol
 */

/** The first frame a process worker receives; it also selects its role. */
export interface ShellStartFrame {
  t: 'shell-start'
  /** Command source for `bash -c`, or undefined when `argv` names a program directly. */
  script?: string | undefined
  /** The program and arguments, used when `script` is absent. */
  argv: readonly string[]
  /** Working directory the command starts in. */
  cwd: string
  /** Environment the command starts with. */
  env: Record<string, string>
  /** Everything on standard input. */
  stdin: string
}

/** Output produced by the command, forwarded as it is written. */
export interface ShellOutputFrame {
  t: 'shell-out'
  stream: 'stdout' | 'stderr'
  text: string
}

/** The command settled; the process worker closes itself right after. */
export interface ShellExitFrame {
  t: 'shell-exit'
  code: number
}

/** A signal the command is asked to honor (the terminate ladder's first rung). */
export interface ShellSignalFrame {
  t: 'shell-signal'
}

/** Filesystem operations a process worker can ask its host to perform. */
export type FilesystemOperation = 'stat' | 'list' | 'readText' | 'writeText' | 'mkdir' | 'remove' | 'rename'

/** One filesystem call, awaiting its reply by `id`. */
export interface FilesystemCallFrame {
  t: 'fs-call'
  id: number
  op: FilesystemOperation
  args: readonly unknown[]
}

/**
 * One filesystem reply. A failure carries the Node error `code` because the
 * utilities branch on it (`ENOENT` prints "No such file or directory"), and an
 * Error instance does not survive structured cloning with its class.
 */
export interface FilesystemReplyFrame {
  t: 'fs-reply'
  id: number
  value?: unknown
  failure?: { code?: string | undefined; message: string }
}

/** Everything the host sends to a process worker. */
export type ToProcessFrame = ShellStartFrame | ShellSignalFrame | FilesystemReplyFrame

/** Everything a process worker sends to its host. */
export type FromProcessFrame = ShellOutputFrame | ShellExitFrame | FilesystemCallFrame

/**
 * Whether a message is the frame that turns a fresh worker into a shell
 * process. The host worker's entry reads this to pick its role.
 * @param data - the raw message payload.
 * @returns true when the payload starts a shell process.
 */
export function isShellStartFrame(data: unknown): data is ShellStartFrame {
  return typeof data === 'object' && data !== null && (data as { t?: unknown }).t === 'shell-start'
}