Persistent PowerShell shell

While DataMind Oda works on a task, it can run PowerShell commands in a shell that stays alive between commands. What one command sets up, the next one can use, so a multi-step task builds on what the last command did. This page explains what the shell keeps, what closes it, and how to read what its results say. For commands that run in a fresh process each time instead, see Shell commands.

One shell per agent

Oda keeps one PowerShell shell per agent and reuses it for every command that agent runs. The first command starts the shell, and later commands reuse it.

One at a time. If a command arrives while another is still running, it waits its turn in the same shell.
Not shared. A helper Oda starts for part of the task, or another chat, gets its own shell; nothing is passed between them.
Kept for its agent. The shell lives while the agent that owns it lives, and closes with it.

What a command may change follows the chat's access mode; see Command sandbox and approvals.

What stays between commands

The shell is kept alive as one process, so it carries context from each command to the next:

The current folder. If a command moves to another folder, the next command starts there.
Exported variables. A value a command exports stays in effect for the commands after it.
Functions. A function the shell defines stays available to later commands.
Work it started. A background job the shell started keeps running while the shell lives.

What closes the shell

A closed shell is not repaired. When the next command needs a shell, Oda starts a fresh one; that command starts from the chat's workspace folder, with a fresh current directory and environment. The command that closed the shell leaves this note in its result:

The persistent pwsh shell was reset; the next pwsh call starts from the workspace with a fresh current directory and environment.

The shell closes when:

A command ends it, for example by running exit.
A command reaches its time limit. Each command gets a limited time, five minutes by default; the command is stopped, its partial output is kept, and the shell closes.
A command runs out of memory.
You stop a running command, with Stop in the message box.
A signal ends the shell.

A command stopped by its time limit or by a memory problem keeps the output it had produced so far. Its result starts with this line and then shows that partial output:

Your command timed out after <n> seconds or experienced an OOM error. Below is partial output:

The notes at the end of a result

A settled command keeps its output; the shell's own prompt and the echo of the command are not part of the result. The result usually ends with a short note saying how it went:

Note	What it means
`[exit code: N]`	The command finished and reported this code. The note appears only when the code is not zero: a successful command shows no note. A terminating PowerShell error reports `1`.
`[shell exited: code N]`	The shell itself ended with this code, for example when a command ran `exit`. The result also carries the reset note, and the next command starts a new shell.
`[shell killed by signal: SIG]`	The shell was ended by a signal.
`[shell exited]`	The shell ended without reporting a code or a signal.

When the output is cut

Oda keeps the earliest part of a command's output, up to a limit of 16,000 characters by default. When a command produces more:

A cut end. The result keeps the earliest part and marks the rest as clipped with <response clipped>, with a note that only part of the output was shown.
A dropped beginning. If the terminal had to drop the beginning of the output, the result says the shown text is the earliest retained part instead, so it is never passed off as the complete output.

Treat what you see as partial. If you need every line, ask Oda to write the output to a file.

Refusals you may see

Rarely, Oda reports one of these instead of running the command:

persistent pwsh shell did not accept initialization: the shell could not be started on this computer, so the command did not run. Ask Oda to try again; if it repeats, contact your DataMind OS administrator with the message.
command must be a non-empty string: the step was refused because it carried nothing to run, so nothing ran. Ask Oda to try again.
pwsh requires an owning agent session: the command was not attached to an agent, so it did not run. Start the task from a chat; if it repeats, contact your DataMind OS administrator with the message.

Questions, answered

Do the folder, variables and functions carry over between commands?

Yes. The shell stays alive, so a folder change, an exported variable or a function defined by one command is still in effect for the next. They are cleared only when the shell closes and a fresh one starts.

Can the shell run two commands at the same time?

No. The shell runs one command at a time, so a command that arrives while another is still running waits its turn, and then runs in the same shell.

Why did the shell close after a command ran `exit`?

A command that ends the shell, for example by running exit, closes it. The result carries the reset note, and the next command starts a fresh shell from the workspace folder.

What happens when a command reaches its time limit?

Each command gets a limited time, five minutes by default. When the limit is reached, the command is stopped, the output it had produced so far is kept, and the shell closes. The result starts with the timeout line and then shows that partial output, followed by the reset note. The next command starts fresh from the workspace.

What does `[exit code: N]` mean?

The command finished and reported this code. The note appears only when the code is not zero: a successful command shows no note. A terminating PowerShell error reports 1.

What does `[shell killed by signal: SIG]` mean?

Something ended the shell with a signal. The command did not finish; run the task again and check why the shell was killed.

Why does the result say the beginning of the output was dropped?

The terminal keeps a limited amount of a command's output. If it had to drop the beginning, the result says so and shows the earliest retained text. Treat what you see as partial.

Can I get the full output of a long command?

The shell keeps only a limited window of output, 16,000 characters by default. If you need every line, ask Oda to write the output to a file and read from there.

What does `pwsh requires an owning agent session` mean?

The command was not attached to an agent, so it did not run. Start the task from a chat and try again; if it repeats, contact your DataMind OS administrator with the message.

What does `persistent pwsh shell did not accept initialization` mean?

The shell could not be started on this computer, so the command did not run. Ask Oda to try again; if it repeats, contact your DataMind OS administrator with the message.