@alisio/core 0.5.2 → 0.7.0

package/dist/forge/protocol.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The common Forja protocol (spec §5.4, D10): one logical message schema over several transports.
+ * This module is the host-side validator of what the guest sends. Shape is checked with Ajv; the
+ * stateful rules (sequence, call correlation, terminal closure, capability gate) are plain code.
+ * Every rejection is a `PROTOCOL_VIOLATION` and the caller terminates the execution.
+ */
+import type { EngineId } from "@alisio/sdk";
+import { ForgeError, type ForgeErrorCode } from "./errors.ts";
+import type { GuestLimits } from "./limits.ts";
+export declare const MAX_MESSAGE_BYTES: number;
+/** The registry's naming rule (`ToolRegistry.register`); the protocol refuses any other name. */
+export declare const TOOL_NAME_PATTERN = "^[a-zA-Z0-9_-]{1,64}$";
+export declare const MAX_JSON_DEPTH = 32;
+export type ForgeOutputItem = {
+    type: "text";
+    text: string;
+} | {
+    type: "json";
+    value: unknown;
+};
+export interface Envelope<T extends string, P> {
+    protocol: 1;
+    type: T;
+    /** Strictly increasing per direction. */
+    seq: number;
+    payload: P;
+}
+/** Guest to host. */
+export type GuestMessage = Envelope<"ready", {
+    engine: EngineId;
+    preludeHash: string;
+}> | Envelope<"progress", {
+    message: string;
+    completed?: number;
+    total?: number;
+}> | Envelope<"output", ForgeOutputItem> | Envelope<"state.set", {
+    key: string;
+    value: unknown;
+}> | Envelope<"state.delete", {
+    key: string;
+}>
+/** Only when the engine's `capabilities.toolCalls` is true. */
+ | Envelope<"call", {
+    callId: number;
+    tool: string;
+    input: unknown;
+}> | Envelope<"catalog", {
+    requestId: number;
+    op: "search" | "describe";
+    query: string;
+    limit?: number;
+}> | Envelope<"complete", {
+    value?: unknown;
+}> | Envelope<"fatal", {
+    code: ForgeErrorCode;
+    message: string;
+}>;
+/** Host to guest. */
+export type HostMessage = Envelope<"start", {
+    source: string;
+    state: Record<string, unknown>;
+    limits: GuestLimits;
+    catalogSize: number;
+}> | Envelope<"result", {
+    callId: number;
+    ok: true;
+    value: unknown;
+} | {
+    callId: number;
+    ok: false;
+    error: {
+        code: ForgeErrorCode;
+        message: string;
+    };
+}> | Envelope<"catalog.result", {
+    requestId: number;
+    entries: unknown[];
+}>
+/** Backpressure credits. */
+ | Envelope<"grant", {
+    calls: number;
+    bytes: number;
+}>;
+export type GuestMessageType = GuestMessage["type"];
+export type GuestValidation = {
+    ok: true;
+    message: GuestMessage;
+} | {
+    ok: false;
+    error: ForgeError;
+};
+export type Correlation = {
+    ok: true;
+} | {
+    ok: false;
+    error: ForgeError;
+};
+export declare class GuestMessageValidator {
+    #private;
+    constructor(options: {
+        toolCalls: boolean;
+    });
+    /** Validates one guest message. Any violation closes the validator for good. */
+    accept(raw: unknown): GuestValidation;
+    /** Marks a call as answered by the host; unknown or already answered ids are violations. */
+    resolveCall(callId: number): Correlation;
+    resolveCatalog(requestId: number): Correlation;
+    /** The execution reached a terminal state: nothing more is accepted. */
+    close(): void;
+}

package/dist/forge/protocol.js

@@ -0,0 +1,171 @@
+import Ajv from "ajv";
+import { FORGE_ERROR_CODES, ForgeError } from "./errors.js";
+export const MAX_MESSAGE_BYTES = 256 * 1024;
+/** The registry's naming rule (`ToolRegistry.register`); the protocol refuses any other name. */
+export const TOOL_NAME_PATTERN = "^[a-zA-Z0-9_-]{1,64}$";
+export const MAX_JSON_DEPTH = 32;
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+const ENGINE_IDS = [
+    "javascript-quickjs",
+    "python-managed",
+    "python-oci",
+    "python-wasm",
+];
+const obj = (properties, required) => ({
+    type: "object",
+    properties,
+    required,
+    additionalProperties: false,
+});
+const count = { type: "number", minimum: 0 };
+const id = { type: "integer", minimum: 0 };
+const PAYLOAD_SCHEMAS = {
+    ready: obj({ engine: { enum: ENGINE_IDS }, preludeHash: { type: "string" } }, [
+        "engine",
+        "preludeHash",
+    ]),
+    progress: obj({ message: { type: "string" }, completed: count, total: count }, ["message"]),
+    output: {
+        oneOf: [
+            obj({ type: { const: "text" }, text: { type: "string" } }, ["type", "text"]),
+            obj({ type: { const: "json" }, value: {} }, ["type", "value"]),
+        ],
+    },
+    "state.set": obj({ key: { type: "string", minLength: 1 }, value: {} }, ["key", "value"]),
+    "state.delete": obj({ key: { type: "string", minLength: 1 } }, ["key"]),
+    call: obj({
+        callId: id,
+        tool: { type: "string", minLength: 1, maxLength: 128, pattern: TOOL_NAME_PATTERN },
+        input: {},
+    }, ["callId", "tool", "input"]),
+    catalog: obj({
+        requestId: id,
+        op: { enum: ["search", "describe"] },
+        query: { type: "string" },
+        limit: { type: "integer", minimum: 1 },
+    }, ["requestId", "op", "query"]),
+    complete: obj({ value: {} }, []),
+    fatal: obj({ code: { enum: [...FORGE_ERROR_CODES] }, message: { type: "string" } }, [
+        "code",
+        "message",
+    ]),
+};
+const ENVELOPE_SCHEMA = obj({
+    protocol: { const: 1 },
+    type: { enum: Object.keys(PAYLOAD_SCHEMAS) },
+    seq: { type: "integer", minimum: 0 },
+    payload: { type: "object" },
+}, ["protocol", "type", "seq", "payload"]);
+const ajv = new Ajv({ allErrors: true, strict: true });
+const validateEnvelope = ajv.compile(ENVELOPE_SCHEMA);
+const validatePayload = new Map(Object.entries(PAYLOAD_SCHEMAS).map(([type, schema]) => [type, ajv.compile(schema)]));
+/** Returns why `value` is not plain JSON within the depth bound, or undefined when it is. */
+function jsonViolation(value, depth) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return undefined;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? undefined : "non-finite number";
+    if (typeof value !== "object")
+        return `non-JSON value (${typeof value})`;
+    if (depth > MAX_JSON_DEPTH)
+        return `JSON deeper than ${MAX_JSON_DEPTH} levels`;
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            const reason = jsonViolation(value[i], depth + 1);
+            if (reason)
+                return reason;
+        }
+        return undefined;
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        return "non-plain object";
+    for (const key of Object.keys(value)) {
+        if (FORBIDDEN_KEYS.has(key))
+            return `forbidden key ${key}`;
+        const reason = jsonViolation(value[key], depth + 1);
+        if (reason)
+            return reason;
+    }
+    return undefined;
+}
+const violation = (reason) => ({
+    ok: false,
+    error: new ForgeError("PROTOCOL_VIOLATION", reason),
+});
+export class GuestMessageValidator {
+    #toolCalls;
+    #lastSeq = -1;
+    #closed = false;
+    #pendingCalls = new Set();
+    #usedCalls = new Set();
+    #pendingCatalog = new Set();
+    #usedCatalog = new Set();
+    constructor(options) {
+        this.#toolCalls = options.toolCalls;
+    }
+    /** Validates one guest message. Any violation closes the validator for good. */
+    accept(raw) {
+        const result = this.#check(raw);
+        if (!result.ok)
+            this.#closed = true;
+        return result;
+    }
+    /** Marks a call as answered by the host; unknown or already answered ids are violations. */
+    resolveCall(callId) {
+        if (!this.#pendingCalls.delete(callId)) {
+            return violation(`callId ${callId} is unknown or already resolved`);
+        }
+        return { ok: true };
+    }
+    resolveCatalog(requestId) {
+        if (!this.#pendingCatalog.delete(requestId)) {
+            return violation(`catalog requestId ${requestId} is unknown or already resolved`);
+        }
+        return { ok: true };
+    }
+    /** The execution reached a terminal state: nothing more is accepted. */
+    close() {
+        this.#closed = true;
+    }
+    #check(raw) {
+        if (this.#closed)
+            return violation("message after the channel was closed");
+        const unsafe = jsonViolation(raw, 1);
+        if (unsafe)
+            return violation(unsafe);
+        if (Buffer.byteLength(JSON.stringify(raw), "utf8") > MAX_MESSAGE_BYTES) {
+            return violation(`message larger than ${MAX_MESSAGE_BYTES} bytes`);
+        }
+        if (!validateEnvelope(raw))
+            return violation("malformed envelope or unknown message type");
+        const message = raw;
+        if (!validatePayload.get(message.type)?.(message.payload)) {
+            return violation(`invalid payload for ${message.type}`);
+        }
+        if (message.seq <= this.#lastSeq)
+            return violation(`seq ${message.seq} is not increasing`);
+        if ((message.type === "call" || message.type === "catalog") && !this.#toolCalls) {
+            return violation(`${message.type} is not allowed: this engine cannot call tools`);
+        }
+        if (message.type === "call") {
+            const callId = message.payload.callId;
+            if (this.#usedCalls.has(callId))
+                return violation(`callId ${callId} was already used`);
+            this.#usedCalls.add(callId);
+            this.#pendingCalls.add(callId);
+        }
+        else if (message.type === "catalog") {
+            const requestId = message.payload.requestId;
+            if (this.#usedCatalog.has(requestId)) {
+                return violation(`catalog requestId ${requestId} was already used`);
+            }
+            this.#usedCatalog.add(requestId);
+            this.#pendingCatalog.add(requestId);
+        }
+        this.#lastSeq = message.seq;
+        if (message.type === "complete" || message.type === "fatal")
+            this.#closed = true;
+        return { ok: true, message };
+    }
+}

package/dist/forge/python/backend-selector.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `PythonBackendSelector` (Python spec §6.1): a chain of pure rules, each `(context) -> decision |
+ * next`. It decides once, before anything is prepared (PD5: no fallback after a run started), from
+ * facts the caller already gathered; it never probes.
+ *
+ *  1. an explicit `analysis.runtime` (`managed`, `oci`, `wasm`) runs there or fails with the reason
+ *     and the way out; a policy (`analysis.isolation`) that forbids it is an error too;
+ *  2. `auto` + `rerunOf`: back to the original backend when it is ready, fits and the policy allows;
+ *  3. `auto`: oci -> wasm -> managed, the first eligible one;
+ *  4. nothing eligible: `ENGINE_UNAVAILABLE` with every reason and the shortest command.
+ */
+import type { EngineId } from "@alisio/sdk";
+import { EngineSelector } from "../selector.ts";
+import type { BackendReadiness, PythonBackendId, SupportVerdict } from "./backend.ts";
+export type PythonRuntimeSetting = "auto" | PythonBackendId;
+export type IsolationPolicy = "preferred" | "required" | "strict";
+export interface PythonSelectionContext {
+    /** `analysis.runtime`. */
+    runtime: PythonRuntimeSetting;
+    /** `analysis.isolation`; `preferred` when absent. */
+    isolation?: IsolationPolicy;
+    /** Backend of the execution a `rerunOf` repeats. */
+    rerunOfBackend?: PythonBackendId;
+    /** What the caller found out; a backend missing here was not checked and is not ready. */
+    readiness: Partial<Record<PythonBackendId, BackendReadiness>>;
+    /** `backend.supports(requirements)` per backend; a backend missing here fits. */
+    support?: Partial<Record<PythonBackendId, SupportVerdict>>;
+    /** `networkDeniedByOS` of each backend's descriptor; missing means open. Needed by `strict`. */
+    networkDenied?: Partial<Record<PythonBackendId, boolean>>;
+}
+export declare const engineIdOf: (backend: PythonBackendId) => EngineId;
+/** The backends worth probing for this call. */
+export declare function neededBackends(context: {
+    runtime: PythonRuntimeSetting;
+    isolation?: IsolationPolicy;
+    rerunOfBackend?: PythonBackendId;
+}): PythonBackendId[];
+export declare function createPythonBackendSelector(): EngineSelector<PythonSelectionContext, PythonBackendId>;

package/dist/forge/python/backend-selector.js

@@ -0,0 +1,111 @@
+import { EngineSelector, reject, select } from "../selector.js";
+/** Candidates of `auto`, most isolated first. */
+const AUTO_ORDER = ["oci", "wasm", "managed"];
+/** Higher is more isolated. */
+const ISOLATION_RANK = { managed: 0, wasm: 1, oci: 2 };
+/** The command that would make a not-ready backend ready; `fix: ""` says none would. */
+const fixOf = (state, backend) => (state.fix !== undefined ? state.fix || undefined : SETUP[backend]);
+/** The setup command of a backend that can be made ready. */
+const SETUP = {
+    oci: "alisio analysis setup --oci",
+    wasm: "alisio analysis setup --wasm",
+};
+export const engineIdOf = (backend) => `python-${backend}`;
+/** The backends worth probing for this call. */
+export function neededBackends(context) {
+    const hostAllowed = (context.isolation ?? "preferred") === "preferred";
+    const wanted = context.runtime === "auto"
+        ? AUTO_ORDER.filter((backend) => backend !== "managed" || hostAllowed)
+        : [context.runtime];
+    if (context.rerunOfBackend && (context.rerunOfBackend !== "managed" || hostAllowed))
+        wanted.push(context.rerunOfBackend);
+    return [...new Set(wanted)];
+}
+const readyOf = (context, backend) => context.readiness[backend] ?? { ready: false, reason: `${backend} was not checked` };
+const isolationOf = (context) => context.isolation ?? "preferred";
+/** Why the policy alone rules a backend out, or undefined. */
+function policyExclusion(context, backend) {
+    const policy = isolationOf(context);
+    if (backend === "managed" && policy !== "preferred")
+        return `excluded by analysis.isolation=${policy} (it runs on the host)`;
+    if (policy === "strict" && context.networkDenied?.[backend] !== true)
+        return `excluded by analysis.isolation=strict (its network is not denied by the OS)`;
+    return undefined;
+}
+/** Policy, then readiness, then fit. */
+function eligibility(context, backend) {
+    const excluded = policyExclusion(context, backend);
+    if (excluded)
+        return { ok: false, reason: excluded };
+    const state = readyOf(context, backend);
+    if (!state.ready) {
+        const fix = fixOf(state, backend);
+        return { ok: false, reason: `not ready (${state.reason})`, ...(fix ? { fix } : {}) };
+    }
+    const verdict = context.support?.[backend];
+    if (verdict && !verdict.ok)
+        return { ok: false, reason: verdict.reason, ...(verdict.fix ? { fix: verdict.fix } : {}) };
+    return { ok: true };
+}
+/** Why a rerun did not use its original backend, for the reason line. */
+function rerunNote(context, chosen) {
+    const original = context.rerunOfBackend;
+    if (!original || original === chosen)
+        return "";
+    const state = eligibility(context, original);
+    return state.ok ? "" : `; rerun: original backend ${original} not used (${state.reason})`;
+}
+/** Rule 1: the explicit runtime, as is. Not ready or not fitting is an error with the way out. */
+const explicitRuntime = (context) => {
+    const { runtime } = context;
+    if (runtime === "auto")
+        return null;
+    const policy = policyExclusion(context, runtime);
+    if (policy)
+        return reject(`${runtime} ${policy.replace(/^excluded/, "is excluded")}; set analysis.runtime=auto (or another backend) or relax analysis.isolation`);
+    const state = readyOf(context, runtime);
+    const setup = state.ready ? undefined : fixOf(state, runtime);
+    const way = (fix) => `; set analysis.runtime=auto${fix ? ` or run "${fix}"` : ""}`;
+    if (!state.ready)
+        return reject(`${runtime} is not ready: ${state.reason}${runtime === "managed" ? "" : way(setup)}`);
+    const verdict = context.support?.[runtime];
+    if (verdict && !verdict.ok)
+        return reject(`${runtime} cannot run this script: ${verdict.reason}${way(verdict.fix)}`);
+    // A rerun of an execution that ran right here is a repeat, and the reason says so.
+    return select(runtime, context.rerunOfBackend === runtime
+        ? `rerun: original backend ${runtime}`
+        : `analysis.runtime=${runtime}`);
+};
+/** Rule 2: under `auto`, a rerun goes back to the backend that ran the original when it can. */
+const rerunOriginalBackend = (context) => {
+    const original = context.rerunOfBackend;
+    if (!original || context.runtime !== "auto")
+        return null;
+    return eligibility(context, original).ok
+        ? select(original, `rerun: original backend ${original}`)
+        : null;
+};
+/** Rules 3 and 4: the first eligible candidate of `auto`, or the reasons nothing was. */
+const autoChain = (context) => {
+    if (context.runtime !== "auto")
+        return null;
+    const skipped = [];
+    const fixes = [];
+    for (const backend of AUTO_ORDER) {
+        const state = eligibility(context, backend);
+        if (state.ok) {
+            const why = skipped.length ? `; ${skipped.join("; ")}` : "";
+            return select(backend, `analysis.runtime=auto, analysis.isolation=${isolationOf(context)}: ${backend} is ready${why}${rerunNote(context, backend)}`);
+        }
+        skipped.push(`${backend}: ${state.reason}`);
+        if (state.fix)
+            fixes.push({ backend, fix: state.fix });
+    }
+    // The least effort first: wasm needs no container engine, so its command comes before oci's.
+    const fix = [...fixes].sort((a, b) => ISOLATION_RANK[a.backend] - ISOLATION_RANK[b.backend])[0];
+    return reject(`no Python backend can run this script (analysis.isolation=${isolationOf(context)}): ${skipped.join("; ")}${fix ? `. Shortest fix: run "${fix.fix}"` : ""}`);
+};
+const RULES = [explicitRuntime, rerunOriginalBackend, autoChain];
+export function createPythonBackendSelector() {
+    return new EngineSelector(RULES);
+}

package/dist/forge/python/backend.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The strategy behind `PythonEngine` (Python spec §4.2, PD1). A backend knows how to start a
+ * prepared job and how to stop it; everything else of an execution (job folders, the frame
+ * transport, publication, journal, state) is shared. The three implementations are `managed`, `oci`
+ * and `wasm` (Pyodide in a restricted Node child process).
+ */
+import type { EngineDescriptor } from "@alisio/sdk";
+import type { JobPaths } from "../../analysis/jobs.ts";
+import type { ProcessResult } from "../../runtime/process.ts";
+import type { TerminationReason, TerminationReport } from "../ports.ts";
+export type PythonBackendId = "managed" | "oci" | "wasm";
+/** What the selector may ask of a backend before choosing it (pure, no I/O). */
+export interface PythonRequirements {
+    extras: Array<"analysis" | "science">;
+    /** Top-level modules the script imports (`scanImports`). */
+    importedModules: string[];
+    /** Sum of the input sizes. */
+    inputBytes: number;
+    rerunOfBackend?: PythonBackendId;
+}
+export type SupportVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    code: "PROFILE_UNSUPPORTED" | "PACKAGE_UNAVAILABLE" | "INPUT_TOO_LARGE" | "NOT_READY";
+    /** The command that would make it fit, when there is one (`alisio analysis setup --wasm …`). */
+    fix?: string;
+};
+/** The live answer of "can this backend run now?", gathered before selection. */
+export type BackendReadiness = {
+    ready: true;
+} | {
+    ready: false;
+    /** Actionable, as the user reads it. */
+    reason: string;
+    /** The backend's own diagnosis (managed: the failed interpreter resolution), for rendering. */
+    detail?: unknown;
+    /** The command that makes it ready when it differs from the usual setup one; "" = none helps. */
+    fix?: string;
+};
+/** A job whose folders exist, handed to a backend to start. */
+export interface PreparedJob {
+    executionId: string;
+    paths: JobPaths;
+    /** Variables for the script on top of the job paths: the frame nonce, the scratchpad. */
+    env: Record<string, string>;
+    /** The Forja scratchpad, exposed read-only (managed: env var; oci: `:ro` mount). */
+    scratch?: string;
+    /** Aborted when the kernel stops the execution (deadline or cancellation). */
+    signal: AbortSignal;
+    /** A backstop for the process, longer than the kernel's own deadline. */
+    backstopMs: number;
+    maxBytes: number;
+    maxLogBytes: number;
+    logFiles: {
+        stdout: string;
+        stderr: string;
+    };
+}
+export interface ProcessSink {
+    /** Live text of the script; `stdout` is where frames travel. */
+    onData(chunk: string, stream: "stdout" | "stderr"): void;
+}
+export interface RunningProcess {
+    /** Settles when the process ended; rejects with an abort error when it was stopped. */
+    readonly result: Promise<ProcessResult>;
+    /** The public runtime facts for the artifacts' provenance (`runtime`). */
+    readonly runtime: Record<string, unknown>;
+    /** Backend-private stop handle. */
+    readonly stop: AbortController;
+    /**
+     * A limit the BACKEND enforced by killing the process (the wasm memory watchdog). The engine
+     * reports it as the failure instead of a bare non-zero exit.
+     */
+    readonly limit?: () => {
+        code: "MEMORY_LIMIT";
+        message: string;
+    } | undefined;
+}
+export interface PythonBackend {
+    readonly id: PythonBackendId;
+    describe(): Promise<EngineDescriptor>;
+    /** Live readiness. May run a process (interpreter discovery) or call the container engine. */
+    check(signal?: AbortSignal): Promise<BackendReadiness>;
+    supports(requirements: PythonRequirements): SupportVerdict;
+    launch(job: PreparedJob, sink: ProcessSink): Promise<RunningProcess>;
+    terminate(process: RunningProcess, reason: TerminationReason): Promise<TerminationReport>;
+}

package/dist/forge/python/backend.js

@@ -0,0 +1 @@
+export {};

package/dist/forge/python/engine.d.ts

@@ -0,0 +1,84 @@
+import type { EngineDescriptor, EngineId } from "@alisio/sdk";
+import type { DatasetService } from "../../analysis/data/datasets.ts";
+import type { AnalysisJobs, JobInput, JobPaths } from "../../analysis/jobs.ts";
+import type { RerunPlan } from "../../analysis/rerun.ts";
+import type { CoreArtifactPublisher, PublishedArtifactInfo } from "../../core/contracts.ts";
+import type { ProcessResult } from "../../runtime/process.ts";
+import type { EngineOutcome, ExecutionEngine, ExecutionRequest, KernelChannel, PreparedExecution, TerminationReason, TerminationReport, TrustedExecutionContext } from "../ports.ts";
+import type { PythonBackend } from "./backend.ts";
+/** Key of the plan in `ExecutionRequest.payload`. */
+export declare const PYTHON_PLAN_KEY = "python";
+/** The terminal text the model and the UI read is bounded to this many bytes. */
+export declare const TERMINAL_BYTES: number;
+/** What the tool learns about a run besides the kernel's result. Filled by the engine. */
+export interface PythonRunReport {
+    job?: JobPaths & {
+        scriptSha256: string;
+    };
+    inputs: JobInput[];
+    /** The frame nonce of this run, to clean captured output. */
+    nonce?: string;
+    /** Raw result of the process (stdout already without frames). */
+    process?: ProcessResult;
+    /** The process could not run at all (spawn failure), or crashed outside the script's own exit. */
+    crash?: unknown;
+    /** Why `prepare` failed, as the original error (the tool rethrows it). */
+    prepareError?: unknown;
+    published: PublishedArtifactInfo[];
+    publishError?: string;
+    warnings: string[];
+    /** Wall time of the process, for the head line. */
+    durationMs?: number;
+    /** The public runtime facts of the backend that ran it (`runtime` in the provenance). */
+    runtime?: Record<string, unknown>;
+}
+export declare const newPythonRunReport: () => PythonRunReport;
+/** Everything one `python_run` call hands to the engine. Built by the tool; never by the model. */
+export interface PythonRunPlan {
+    code: string;
+    rerun?: RerunPlan;
+    inputs: Array<{
+        path?: string;
+        datasetId?: string;
+    }>;
+    /** Extras the run asked for (also recorded for reruns). */
+    extrasAsked: string[];
+    resolvePath: (path: string) => Promise<string>;
+    datasets?: DatasetService;
+    rootSessionId: string;
+    sessionId: string;
+    workspace: string;
+    runId?: string;
+    callId?: string;
+    publisher: CoreArtifactPublisher;
+    title?: string;
+    publishOnError: boolean;
+    /** Live text of the script (frames removed), for the terminal view. */
+    onText: (text: string) => void;
+    /** The Forja scratchpad to expose read-only, when there is one. */
+    scratch?: string;
+    maxLogBytes: number;
+    /** Engine, isolation and reason go to the artifacts' provenance (PD12). */
+    engine: {
+        id: EngineId;
+        isolation: string;
+        selectionReason: string;
+    };
+    report: PythonRunReport;
+}
+export interface PythonEngineDeps {
+    backend: PythonBackend;
+    jobs: AnalysisJobs;
+}
+export declare class PythonEngine implements ExecutionEngine {
+    #private;
+    readonly id: EngineId;
+    constructor(deps: PythonEngineDeps);
+    describe(): Promise<EngineDescriptor>;
+    prepare(request: ExecutionRequest, ctx: TrustedExecutionContext): Promise<PreparedExecution>;
+    run(prepared: PreparedExecution, channel: KernelChannel): Promise<EngineOutcome>;
+    /** Publishes the files the script left, when the run earned it (exit 0, or `publishOnError`). */
+    collect(prepared: PreparedExecution, outcome: EngineOutcome): Promise<EngineOutcome>;
+    terminate(prepared: PreparedExecution, reason: TerminationReason): Promise<TerminationReport>;
+    dispose(prepared: PreparedExecution): Promise<void>;
+}