@struktoai/mirage-core/dist/workspace/executor/traps.d.ts

A Unified Virtual Filesystem For AI Agents

import { IOResult, type ByteSource } from '../../io/types.ts';
import { CallStack } from '../../shell/call_stack.ts';
import type { ExecuteStringFn } from './builtins/types.ts';
import type { SessionState } from '../session/session.ts';
import type { ExecutionNode } from '../types.ts';
import { type Written } from './statement.ts';
import { type TSNodeLike } from '../../shell/types.ts';
/**
 * Start a child shell: `( )`, a pipeline stage, a job, `$( )`.
 *
 * The session's `exitTrap` is the `trap ... EXIT` action, '' for an
 * ignored EXIT. A child shell keeps its parent's with `exitTrapInherited`
 * set: it lists it, as bash's `trap -p` does there, and runs none of it
 * until it registers its own. It keeps the ERR action hidden unless
 * `set -E` and the RETURN action unless `set -T`, and lists them all the
 * same. It is live shell state, which a session store keeps none of.
 */
export declare function inheritTraps(session: SessionState): void;
/** Start a new shell (`bash -c`, a script): it has no actions. */
export declare function clearTraps(session: SessionState): void;
/**
 * Take the caller's ERR and RETURN actions from a function's body unless
 * `set -E` / `set -T`: the body neither runs nor lists them. Returns the
 * actions taken, for `restoreFunctionTraps`.
 */
export declare function liftFunctionTraps(session: SessionState): [string | null, string | null];
/**
 * Give the actions `liftFunctionTraps` took back as the function returns,
 * each unless the body set one of its own, as bash does.
 */
export declare function restoreFunctionTraps(session: SessionState, lifted: readonly [string | null, string | null]): void;
/**
 * Whether the ERR action is set and seen here, taken as a statement starts:
 * bash answers a failure only when the action was armed before the command
 * ran, so a function that sets one is not answered for. A line run as a
 * program (`env`, `timeout`, `find -exec`, a `/usr/bin` path) is no shell,
 * so its statements arm nothing: the shell's statement running it answers
 * its failure once.
 */
export declare function errTrapArmed(session: SessionState): boolean;
/**
 * Run the ERR action after a statement finished with `status`.
 *
 * It runs where `set -e` would act: not in a test, the left of `&&`/`||`
 * or after `!`, and not again for a group, `if`, a loop, `case` or
 * `&&`/`||` list, whose own failing command ran it already, unless the
 * statement failed to open a redirect and never ran (`execNode.unopened`,
 * which this consumes, so a group returning the same node does not answer
 * the failure again). `$?` is
 * `status` while it runs and again after it, whatever the action returns,
 * and the action does not run while it is running, nor once `set -e` is
 * ending the shell. An `exit` or `return` in it leaves as the statement's
 * would. Hidden in a function or a child shell unless `set -E`, as bash's
 * is. `armed` is `errTrapArmed` as the statement started. Returns what the
 * action wrote, for the caller to land; empty when none runs. Mirrors
 * Python.
 */
export declare function runErrTrap(executeFn: ExecuteStringFn | null, node: TSNodeLike, status: number, session: SessionState, armed: boolean, stdin?: ByteSource | null, callStack?: CallStack | null, execNode?: ExecutionNode | null): Promise<Written[]>;
/**
 * Run the RETURN action as a function or a sourced file returns. It runs in
 * the frames of what is returning, with `$?` as the last command left it;
 * what returns keeps its own status. Hidden in a function or a child shell
 * unless `set -T` or it set its own, and it does not run while it is
 * running, nor once `set -e` is ending the shell. Returns what the action
 * wrote, for the caller to land; empty when none runs. Mirrors Python.
 */
export declare function runReturnTrap(executeFn: ExecuteStringFn | null, session: SessionState, stdin?: ByteSource | null, callStack?: CallStack | null): Promise<Written[]>;
/**
 * Run the shell's EXIT action as the shell ends with `status`.
 *
 * bash clears the action before it runs it, and an `exit` in it, or one
 * it registers there, does not run again. `$?` starts at `status`, and a
 * bare `exit` keeps it. The status the shell ends with stays `status`
 * unless the action exits, or fails where `set -e` acts (not in a test,
 * the left of `&&`/`||` or after `!`), which exits too; its commands
 * answer ERR and RETURN afresh. Hard stops (cancellation, a killed job, a
 * closed workspace) are not an end the shell reaches, and never get here.
 * `callStack` holds the frames the action runs in: the function that
 * called `exit` is still on them. Returns null when no action of this
 * shell's own is set.
 */
export declare function runExitTrap(executeFn: ExecuteStringFn | null, session: SessionState, status: number, stdin?: ByteSource | null, callStack?: CallStack | null): Promise<IOResult | null>;
/**
 * End a child shell whose line returned `io`: a `bash -c`, a script, a
 * `$( )`. Its EXIT action runs after what it wrote.
 */
export declare function finishShell(executeFn: ExecuteStringFn | null, session: SessionState, io: IOResult, stdin?: ByteSource | null, callStack?: CallStack | null): Promise<IOResult>;
/**
 * Run the whole of a child shell, a pipeline stage or a job, then its EXIT
 * action. An `exit` or a fatal error that ends it carries the action's
 * output and status on out to the boundary containing it.
 */
export declare function endShell(executeFn: ExecuteStringFn | null, session: SessionState, stdin: ByteSource | null, callStack: CallStack | null, body: Promise<[ByteSource | null, IOResult, ExecutionNode]>): Promise<[ByteSource | null, IOResult, ExecutionNode]>;
//# sourceMappingURL=traps.d.ts.map