@struktoai/mirage-core/dist/runtime/language.d.ts

A Unified Virtual Filesystem For AI Agents

import type { Context } from '../commands/config.ts';
import type { PathSpec } from '../types.ts';
import { Runtime } from './base.ts';
import { type Argv0Rules } from './source.ts';
import type { Language, OutputFn, Program, RunResult } from './types.ts';
/**
 * A runtime that interprets one language's code inside a command.
 *
 * The engine inside a single command (python3, node): the workspace
 * splits the line, and a captured stage's operands land here as run().
 * Never the whole line; that is LineExecutorMixin's entry point.
 *
 * The language it interprets is declared once, on its language tier
 * (PythonRuntime, JsRuntime), and a script CLI finds its interpreter by
 * it (runtimeForLanguage).
 *
 * run() resolves the program from the operands the way a real
 * interpreter does (`-c` in `ctx.flags`, else the script operand read
 * through `ctx.vfs`, else piped stdin) and hands it to interpret(). A
 * guest sees `ctx.env`, a copy whose writes do not mutate the Mirage
 * session; an adapter that means to write the session uses `ctx.session`.
 */
export declare abstract class LanguageRuntime<E = unknown> extends Runtime<E> {
    /**
     * The head words of this language's interpreter commands, the first
     * naming a program run with no command of its own.
     */
    static readonly commands: readonly string[];
    abstract readonly language: Language;
    /** What this interpreter calls itself where no file names the program. */
    readonly argv0Rules: Argv0Rules;
    /**
     * Resolve the program from the operands, then interpret it.
     *
     * @param engine the install's engine.
     * @param paths the script operand, if any.
     * @param texts the program's argv.
     * @param ctx the run's context.
     * @param output receives stdout as it comes.
     * @param errors receives stderr as it comes.
     */
    run(engine: E, paths: PathSpec[], texts: string[], ctx: Context, output?: OutputFn, errors?: OutputFn): Promise<RunResult>;
    /**
     * The program `-m name` runs; null where this runtime cannot run a
     * module.
     *
     * @param _name the module.
     * @param _label the command name a not-found message uses.
     */
    moduleCode(_name: string, _label: string): string | null;
    /** Report the bound interpreter's version. */
    version(_env: Record<string, string>, _signal?: AbortSignal, _timeoutSeconds?: number): Promise<RunResult>;
    /**
     * Execute one program and return its outcome.
     *
     * Each call represents an independent language command, such as
     * python3 or node. Guest globals, imports and builtin mutations
     * do not carry over from earlier commands or evaluator sessions.
     * The adapter owns engine reuse; this does not reset workspace
     * state or undo external effects.
     *
     * @param engine the install's engine.
     * @param program the source and argv to run.
     * @param ctx the run's context: working directory, environment,
     *   switches, files, signal and limit.
     * @param output receives stdout as the program writes it, which the
     *   result then leaves out; undefined, or an engine that cannot stream,
     *   returns it whole.
     * @param errors the same for stderr.
     */
    abstract interpret(engine: E, program: Program, ctx: Context, output?: OutputFn, errors?: OutputFn): Promise<RunResult>;
}
//# sourceMappingURL=language.d.ts.map