Interface Surface

Readonlycapabilities

Optionalaside

• aside?<T>(waiting: Promise<T>): Promise<T>

  Waits without holding the session: the command steps out of its turn while the wait lasts, so other lines run (a pane's reads among them), and takes its turn again before going on. Waiting is not working. A host that runs one command at a time and nothing else has no need of it; the command then simply waits.

  Type Parameters

  • T

  Parameters

  • waiting: Promise<T>

    What the command waits on (a task's next line).

  Returns Promise<T>

  What it resolved with.

fileDeliver

• fileDeliver(request: FileDeliverRequest): Promise<FileDeliverResult>

  Places one file where this surface's operator can reach it.

  The mechanics are the surface's: a write to the resolved path for the local CLI, a write on the client machine for a remote CLI, a saved file for a browser. A daemon never writes to its own disk on a surface's behalf, for the same reason it never spawns a shell there.

  Parameters

  • request: FileDeliverRequest

    What to deliver and where the operator asked for it.

  Returns Promise<FileDeliverResult>

  Where it landed and how large it was.

  Throws

  When the surface lacks fileDelivery.

Optionalhold

• hold?(holds: string[] | "all"): Promise<() => void>

  Takes a hold on the session for work outside any line the host ran (a joblet): it waits until nothing running holds what the work changes, as a line does, and gives it back when released. A host that runs one line at a time and nothing else has no need of it.

  Parameters

  • holds: string[] | "all"

    The pieces the work changes, or 'all'.

  Returns Promise<() => void>

  Gives the hold back.

localEdit

• localEdit(request: LocalEditRequest): Promise<LocalEditResult>

  Opens content in the surface's local editor and returns the result. The editor mechanics are the surface's business — a temp file and $EDITOR for the local CLI, the client's editor for a remote CLI, an editor component in a browser.

  Parameters

  • request: LocalEditRequest

    The content to edit and an optional extension.

  Returns Promise<LocalEditResult>

  The edited content and whether it changed.

  Throws

  When the surface lacks the localEdit capability.

Optionalpeers

• peers?(): SurfacePeer[]

  The surfaces attached to this session, when the host knows of more than itself (a daemon does; a local shell is alone). Absent means unknown.

  Returns SurfacePeer[]

pipeSegment

• pipeSegment(
      command: string,
      input: Buffer,
      signal?: AbortSignal,
  ): Promise<Buffer<ArrayBufferLike>>

  Runs one pipeline segment against an input, returning its output. Where this runs is the surface's business — in-process for the local CLI, on the client machine for a remote CLI — but never on a daemon host.

  Parameters

  • command: string

    The segment command line (e.g. grep foo).

  • input: Buffer

    The bytes to feed the segment on stdin.

  • Optionalsignal: AbortSignal

    Aborted when the operator cancels the command; a surface that started a process kills it.

  Returns Promise<Buffer<ArrayBufferLike>>

  The segment's stdout.

  Throws

  When the surface lacks the pipeSegments capability.

prompt

• prompt(request: PromptRequest): Promise<string>

  Prompts for a line of input.

  Parameters

  • request: PromptRequest

    The prompt message and whether to hide the input.

  Returns Promise<string>

  The entered line, trimmed.

  Throws

  When hidden input is requested but the surface lacks the hiddenInput capability, or the surface cannot prompt.

shellCommand

• shellCommand(command: string, signal?: AbortSignal): Promise<number>

  Runs one host-shell command on the surface machine.

  Parameters

  • command: string

    The shell command without the leading !.

  • Optionalsignal: AbortSignal

    Aborted when the operator cancels the command; a surface that started a process kills it.

  Returns Promise<number>

  The process exit code.

  Throws

  When the surface lacks shellCommands.