Terminal tools

A terminal session gives DataMind Oda six actions: open, send, read, signal, close and list. This page covers what each one returns, with the notes, markers, limits and refusals to expect.

In the chat, a foreground send appears as a terminal card you can expand, and the other actions as ordinary step rows.

The sessions themselves are on Terminal sessions, the shell and sandbox behind them on Terminal shells and sandboxing, and the rows and cards in the chat on Commands Oda runs.

The six actions

Open. Oda starts a session of a type, usually the shell, and can give it a name such as main or gdb. The result reads started terminal session pty-1 [type: shell] and carries a short startup message (or (no startup output)).
Send. Oda writes text into the session and waits for it to settle. By default the text ends with Enter; for control characters or an incomplete line in an interactive program, Oda sends the text without pressing Enter. A send that is stopped before it settles reports terminal send aborted.
Read. Oda reads the output the session has kept, starting at the beginning and 500 lines at a time by default. A read can also start at a later line; a start before the beginning, or a count below one line, is refused.
Signal. Oda sends SIGINT, SIGTERM, SIGKILL, SIGTSTP or SIGHUP to what is running in the session. The result reads delivered <signal> to foreground process group <pgid>. A SIGKILL aimed at the shell itself is refused; Oda closes the session instead.
Close. Oda ends the session, its shell and everything running in it. Closing is safe to repeat: the result reads closed terminal session <id>, or terminal session <id> was already closing when it was already on its way out.
List. Oda lists the sessions it holds, one per line, for example pty-1 [shell] running. With none, the result reads (no terminal sessions).

Notes that come back with a result

Every result is bounded: 256 KiB by default, and the cap is never set below 64 bytes. A result over the cap is cut at a character boundary and marked [output truncated]; the earlier part is kept.

Note	What it means
`(no new output)`	A send had nothing new to show; output you already read is not repeated.
`[wait: <reason>]`	Why a wait ended: one of `stdin_read`, `inferred_idle`, `timeout` or `session_exit`. What each reason means is on Terminal sessions.
`[session: running]`	The session is still open after the wait.
`[session: exited code=<code> signal=<signal>]`	The shell ended during the wait; the note carries its exit code, the signal that ended it, or `null` where there is none.
`(no retained output)`	The session had nothing kept to read.
`[lines: <first>-<last> of <total>]`	Which lines of the kept output a read returned, and how many lines are kept in all.
`[output truncated]`	The result was cut to fit; the earlier part is kept.

Sends in the background

A send can run in the background: Oda passes the text to the session and carries on. The send becomes a job, and its start reads started background job <id>; the job is labelled with the session's id and the text sent.
Oda collects the output by reading the job. Each read continues from where the previous one stopped, so nothing is shown twice; a read taken before the send starts comes back empty rather than failing.
Stopping the job ends the send; the job then reads killed.
Background sending is available by default. Where it is turned off, the option is not offered and sends run in the foreground.

When an action is refused

Every terminal action belongs to a chat. Outside a chat, nothing runs.
Every action must name the session it works on, and a new session must name its type. A missing session id or type is refused.

Questions, answered

A step says `started terminal session pty-1 [type: shell]`. What does it mean?

Oda opened a terminal session. pty-1 is the session's id, which Oda uses to tell sessions apart, and [type: shell] is the session's type, here the shell. The result also carries a short startup message; when there is none, it says (no startup output).

A send came back with `(no new output)`. Why?

The send settled without producing anything new to show, so there was nothing to add to the result; output you already read is not repeated. If you expected fresh output, have Oda read the session again, and check the wait and session notes for how it ended.

What do `code` and `signal` mean in a session note?

They say how the shell ended. code=2 signal=null means it exited with code 2; code=null signal=SIGTERM means a signal ended it; when both read null, it ended without reporting a code or a signal. While the session is still open, the note simply reads [session: running].

Why is part of a result marked `[output truncated]`?

The full result was longer than the size cap (256 KiB by default). Oda cuts it at a character boundary and keeps the earlier part, and the marker shows where text was left out. When you need the rest, ask Oda to read further.

Can Oda start reading the output from a specific point?

Yes. A read names a start and a count; by default it starts at the beginning of the kept output and returns up to 500 lines. A start before the beginning, or a count below one line, is refused.

The read says `(no retained output)`. Why?

The session had nothing kept to return: it had not produced output yet, or what it had kept was already dropped. Once the session produces output, the next read returns it.

Which signals can Oda send?

SIGINT, SIGTERM, SIGKILL, SIGTSTP and SIGHUP. The result reads delivered <signal> to foreground process group <pgid>, so you can see the signal and what received it. A SIGKILL aimed at the shell itself is refused; Oda closes the session instead.

How does Oda collect a background send's output?

By reading the job the send started. Each read continues from where the previous one stopped, so nothing is shown twice, and a read taken before the send starts comes back empty rather than failing.

Can a background send be stopped?

Yes. Stopping its job ends the send, and the job then reads killed.

What happens if I stop Oda while a send is running?

The send ends before it settles; a foreground send then reports terminal send aborted. The session itself stays open, ready for the next action.

Why is there no background option for a send?

Background sending is available by default. Where it is turned off, the option is not offered and Oda sends in the foreground.