Interface: InteractionPort

Defined in: core/interaction.ts:32

The UI side of a human-in-the-loop checkpoint: how a host shows the question and reads a person's answer. askForDecision() races it against the response file, so a port only covers the keyboard (or window) channel and never needs to know about the file.

A method that can't ask (no TTY, no window) returns a promise that never resolves, so the file wins. signal aborts once the race is settled by the other channel; a port must drop its question then and leave its UI usable.

Kept in core/ so the checkpoints never depend on a terminal (ADR-001): the terminal port lives in tui/ and is installed by the package entry point; a non-terminal host installs its own, or null to answer through the response file alone.

Methods

askChoice()?

optional askChoice(
   prompt, 
   choice, 
   signal
): Promise<string>;

Defined in: core/interaction.ts:49

A choice between options. Resolves to the raw answer: the chosen options' numbers (1-based, comma-separated, "1" or "1,3") on the first line, and the person's own answer ("Other") on the lines after it, or alone. Optional: without it the kit asks through askDecision(), with the options numbered in the prompt.

Parameters

Parameter	Type
prompt	ApprovalPrompt
choice	ChoiceSettings
signal	AbortSignal

Returns

Promise<string>

---

askDecision()

askDecision(prompt, signal): Promise<string>;

Defined in: core/interaction.ts:34

A step-gate or approval checkpoint; resolves to the raw answer ("", "y", "n", "q"...).

Parameters

Parameter	Type
prompt	ApprovalPrompt
signal	AbortSignal

Returns

Promise<string>

---

askForm()?

optional askForm(form, signal): Promise<FormAnswer>;

Defined in: core/interaction.ts:55

A form an MCP server asks for (elicitation, #58), whole: its fields, and the person's values, or that they declined or cancelled. Optional: without it the kit asks field by field through the other methods. Never written to a log: the answer is the server's.

Parameters

Parameter	Type
form	FormRequest
signal	AbortSignal

Returns

Promise<FormAnswer>

---

askManualIntervention()

askManualIntervention(prompt, signal): Promise<string>;

Defined in: core/interaction.ts:36

Waits until the person confirms they intervened by hand (e.g. logged in).

Parameters

Parameter	Type
prompt	ApprovalPrompt
signal	AbortSignal

Returns

Promise<string>

---

askText()?

optional askText(prompt, signal): Promise<string>;

Defined in: core/interaction.ts:42

A free-text answer (e.g. the path of a file the agent asked for), with case and spaces kept; "" for none. Optional: without it the kit asks through askDecision(), whose answer a plain terminal reads as text too.

Parameters

Parameter	Type
prompt	ApprovalPrompt
signal	AbortSignal

Returns

Promise<string>

---

notify()

notify(message): void;

Defined in: core/interaction.ts:57

A one-way message for the person.

Parameters

Parameter	Type
message	string

Returns

void