@struktoai/mirage-core/dist/commands/builtin/general/interpreter.d.ts

A Unified Virtual Filesystem For AI Agents

import { OutputStream } from '../../../io/stream.ts';
import { IOResult, type ByteSource } from '../../../io/types.ts';
import type { LanguageRuntime } from '../../../runtime/language.ts';
import type { CommandRuntime, OutputFn, RunResult } from '../../../runtime/types.ts';
import type { PathSpec, Producer } from '../../../types.ts';
import type { CommandFnResult, Context } from '../../config.ts';
/**
 * A runtime run as a command's output, handed over as it runs.
 *
 * The one mapping from a run to a command's output shape: the interpreter
 * commands, a script CLI, a program a runtime captured and a whole line all
 * answer through here. The run starts when its output is first read and
 * writes stdout into a bounded pipe, so a reader that falls behind holds the
 * program back and the output is never held whole; what a transport could
 * not stream lands at the end. The status, and the stderr the run returned,
 * settle on the result as the output ends (`IOResult.output`), stderr after
 * what the result already held. A reader that stops early stops the run,
 * which then exits 141, as SIGPIPE leaves a program, and keeps the stderr it
 * had written. A stopped run that does not end within the stop bound is left
 * running, as a stopped handler is (`runCancellable`). Mirrors Python's
 * `run_output`, whose cancel ends the run outright.
 *
 * @param run starts the run, given where it writes stdout, where it writes
 *   stderr and the signal that stops it.
 * @param producer what made the output, for a program run past the
 *   workspace's own commands.
 * @param errors takes stderr as the run writes it, after the stdout written
 *   before it has been read; undefined lands it on the result's stderr.
 * @param stdin the run's input, closed once the output ends.
 * @param signal the command's own abort, which stops the run too.
 */
export declare function runOutput(run: (output: OutputFn, errors: OutputFn, signal: AbortSignal) => Promise<RunResult>, producer?: Producer | null, errors?: OutputFn, stdin?: ByteSource | null, signal?: AbortSignal): [OutputStream, IOResult];
/**
 * Whether a thrown error means the runtime itself is missing (exit 127),
 * not that the program it ran failed.
 *
 * Args:
 *   err: the error the runtime threw.
 */
export declare function runtimeUnavailable(err: unknown): err is Error;
export declare function runtimeVersion(label: string, runtime: LanguageRuntime, env: Record<string, string>, signal?: AbortSignal, timeoutSeconds?: number): CommandFnResult;
/**
 * The answer of an interpreter command no runtime runs: bash's
 * `command not found`, exit 127, whatever the operands say.
 */
export declare function notBound(label: string): CommandFnResult;
/**
 * Why policy will not let an interpreter command run its program; null
 * when it may.
 *
 * The x check follows the program's entry point. A script operand asks
 * the per-path entry point about the script's own path, so a session
 * whose only x grant is one show subtree runs scripts there and nowhere
 * else; inline code (-c/-e), -m and stdin keep the whole-session rule
 * (`execAllowed`: any x grant), since no path holds them. Outside a
 * workspace no per-path entry point is wired and `execAllowed` answers
 * for files too. Mirrors Python's `exec_refusal`.
 *
 * @param label the command name used in the message.
 * @param script the script operand, null for a program from -c, -m or
 *   stdin (`scriptOperand`).
 * @param placement the command's exec policy; absent allows.
 */
export declare function execRefusal(label: string, script: PathSpec | null, placement: CommandRuntime | undefined): [null, IOResult] | null;
/**
 * Run an interpreter command's operands on its bound runtime, the program's
 * output handed over as it runs (`runOutput`). A failure of the runtime
 * itself answers as the command: a missing engine 127, any other 1, an
 * in-VM limit interrupt a timeout named after the command, as the
 * workspace's own timer names it. A script the runtime could not read is
 * the command's own read failure, left to the executor to render as any
 * command's is, as Python lets it escape.
 *
 * @param label the command name used in messages.
 * @param runtime the runtime bound to the command.
 * @param paths the path operands.
 * @param texts the text operands.
 * @param ctx the command's context, its flags the runtime's switches.
 * @param script the script operand (`scriptOperand`), null for a program
 *   from -c, -m or stdin.
 */
export declare function runInterpreter(label: string, runtime: LanguageRuntime, paths: PathSpec[], texts: string[], ctx: Context, script: PathSpec | null): CommandFnResult;
//# sourceMappingURL=interpreter.d.ts.map