jeopi-cli 16.2.14 → 16.2.15

package/dist/types/eval/js/shared/runtime.d.ts

@@ -0,0 +1,59 @@
+import { type HelperBundle } from "./helpers";
+import type { JsDisplayOutput } from "./types";
+/**
+ * Per-run callbacks. Runtime globals resolve these from AsyncLocalStorage so
+ * overlapping async cells can route output/tool calls back to their own run.
+ */
+export interface RuntimeHooks {
+    onText(chunk: string): void;
+    onDisplay(output: JsDisplayOutput): void;
+    callTool(name: string, args: unknown): Promise<unknown>;
+}
+export interface RunContext {
+    runId: string;
+    hooks: RuntimeHooks;
+    cwd: string;
+    finalExpressionSet: boolean;
+    finalExpressionValue: unknown;
+}
+export interface RuntimeOptions {
+    initialCwd: string;
+    sessionId: string;
+    /**
+     * Extra globals installed alongside `__omp_helpers__` / prelude. Use for stable, lifetime-
+     * of-the-worker bindings (e.g. browser's `page`, `browser`). Per-run scope should be set
+     * via `setRunScope()` instead.
+     */
+    extraGlobals?: Record<string, unknown>;
+    /**
+     * On-disk roots the helpers substitute for internal-URL schemes (e.g.
+     * `{ local: "/…/artifacts/local" }`). Stable for the worker's lifetime.
+     */
+    localRoots?: Record<string, string>;
+}
+/**
+ * Shared JS runtime for the eval worker and the browser tab worker. Owns the prelude,
+ * helper bag, console bridge, and indirect-eval execution. Emits text/display/tool-call
+ * back through `RuntimeHooks` that the embedder supplies — wire format is the embedder's
+ * concern.
+ */
+export declare class JsRuntime {
+    #private;
+    readonly helpers: HelperBundle;
+    readonly sessionId: string;
+    constructor(opts: RuntimeOptions);
+    get cwd(): string;
+    setCwd(cwd: string): void;
+    /**
+     * Install per-run globals. Intended for run-scoped state (browser's `tab`, `display`
+     * overrides, etc.). Overwrites previous assignments — caller is responsible for any
+     * cleanup it wants.
+     */
+    setRunScope(scope: Record<string, unknown>): void;
+    run(code: string, filename: string | undefined, hooks: RuntimeHooks, options?: {
+        runId?: string;
+        cwd?: string;
+    }): Promise<unknown>;
+    displayValue(value: unknown, hooks?: RuntimeHooks | undefined): void;
+    dispose(): void;
+}

package/dist/types/eval/js/shared/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Structured status payload emitted by helpers (`read`, `write`, `env`, etc.) and the
+ * tool-call bridge. Surfaces to the model as part of `displays` so it has machine-readable
+ * context about what side effects happened.
+ */
+export interface JsStatusEvent {
+    op: string;
+    [key: string]: unknown;
+}
+/**
+ * One unit of structured output from a JS eval cell. `text` chunks flow through a separate
+ * channel.
+ */
+export type JsDisplayOutput = {
+    type: "json";
+    data: unknown;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+} | {
+    type: "status";
+    event: JsStatusEvent;
+};

package/dist/types/eval/js/tool-bridge.d.ts

@@ -0,0 +1,20 @@
+import type { ToolSession } from "../../tools";
+import { type EvalBudgetResult } from "../budget-bridge";
+import { type EvalConcurrencyResult } from "../concurrency-bridge";
+import type { JsStatusEvent } from "./shared/types";
+export type { JsStatusEvent } from "./shared/types";
+interface ToolBridgeOptions {
+    session: ToolSession;
+    signal?: AbortSignal;
+    emitStatus?: (event: JsStatusEvent) => void;
+}
+type ToolValue = string | EvalBudgetResult | EvalConcurrencyResult | {
+    text: string;
+    details?: unknown;
+    images?: Array<{
+        mimeType: string;
+        data: string;
+    }>;
+    hasError?: boolean;
+};
+export declare function callSessionTool(name: string, args: unknown, options: ToolBridgeOptions): Promise<ToolValue>;

package/dist/types/eval/js/worker-core.d.ts

@@ -0,0 +1,6 @@
+import type { Transport } from "./worker-protocol";
+export declare class WorkerCore {
+    #private;
+    constructor(transport: Transport);
+    dispose(): void;
+}

package/dist/types/eval/js/worker-entry.d.ts

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

package/dist/types/eval/js/worker-protocol.d.ts

@@ -0,0 +1,83 @@
+import type { JsDisplayOutput } from "./shared/types";
+export type { JsDisplayOutput } from "./shared/types";
+export interface SessionSnapshot {
+    cwd: string;
+    sessionId: string;
+    /**
+     * On-disk roots the helpers substitute for internal-URL schemes
+     * (e.g. `{ local: "/…/artifacts/local" }`). Lets `read`/`write`
+     * accept `local://…` paths instead of writing a literal `local:/` directory.
+     */
+    localRoots?: Record<string, string>;
+}
+export interface RunErrorPayload {
+    name?: string;
+    message: string;
+    stack?: string;
+    isAbort?: boolean;
+    isToolError?: boolean;
+}
+export type ToolReply = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: RunErrorPayload;
+};
+export type WorkerInbound = {
+    type: "init";
+    snapshot: SessionSnapshot;
+} | {
+    type: "run";
+    runId: string;
+    code: string;
+    filename: string;
+    snapshot: SessionSnapshot;
+} | {
+    type: "tool-reply";
+    id: string;
+    reply: ToolReply;
+} | {
+    type: "close";
+};
+export type WorkerOutbound = {
+    type: "ready";
+} | {
+    type: "init-failed";
+    error: RunErrorPayload;
+} | {
+    type: "text";
+    runId: string;
+    chunk: string;
+} | {
+    type: "display";
+    runId: string;
+    output: JsDisplayOutput;
+} | {
+    type: "tool-call";
+    id: string;
+    runId: string;
+    name: string;
+    args: unknown;
+} | {
+    type: "result";
+    runId: string;
+    ok: true;
+} | {
+    type: "result";
+    runId: string;
+    ok: false;
+    error: RunErrorPayload;
+} | {
+    type: "log";
+    level: "debug" | "warn" | "error";
+    msg: string;
+    meta?: Record<string, unknown>;
+} | {
+    type: "closed";
+};
+export interface Transport {
+    send(msg: WorkerOutbound): void;
+    onMessage(handler: (msg: WorkerInbound) => void): () => void;
+    close(): void;
+}

package/dist/types/eval/kernel-base.d.ts

@@ -0,0 +1,105 @@
+import type { Subprocess } from "bun";
+import { type KernelDisplayOutput } from "./py/display";
+export type KernelRuntimeEnv = Record<string, string | null>;
+export interface KernelExecuteOptions {
+    id?: string;
+    /** Runtime working directory applied immediately before this request executes. */
+    cwd?: string;
+    /** Managed runtime environment variables applied immediately before this request executes. */
+    env?: Record<string, string | undefined> | Record<string, string | null>;
+    signal?: AbortSignal;
+    onChunk?: (text: string) => Promise<void> | void;
+    onDisplay?: (output: KernelDisplayOutput) => Promise<void> | void;
+    timeoutMs?: number;
+    silent?: boolean;
+    storeHistory?: boolean;
+    allowStdin?: boolean;
+}
+export interface KernelExecuteResult {
+    status: "ok" | "error";
+    executionCount?: number;
+    error?: {
+        name: string;
+        value: string;
+        traceback: string[];
+    };
+    cancelled: boolean;
+    timedOut: boolean;
+    stdinRequested: boolean;
+    /**
+     * True when the kernel subprocess was killed as part of settling this
+     * execution (e.g. SIGINT was ignored and we escalated to shutdown, or the
+     * kernel died unexpectedly). When false, the kernel remains reusable.
+     */
+    kernelKilled?: boolean;
+}
+export interface KernelShutdownResult {
+    confirmed: boolean;
+}
+export interface KernelShutdownOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+/** Per-language lifecycle configuration consumed by each kernel's `start()`. */
+export interface KernelStartOptions {
+    cwd: string;
+    env?: Record<string, string | undefined>;
+    /** Explicit interpreter path; skips discovery when set. */
+    interpreter?: string;
+    signal?: AbortSignal;
+    deadlineMs?: number;
+}
+/** Per-language configuration handed to {@link BaseKernel} by each subclass. */
+export interface BaseKernelOptions<TExecuteOptions extends KernelExecuteOptions = KernelExecuteOptions> {
+    /** Human-readable language label used in log messages and errors. */
+    languageName: string;
+    /** When true, every IPC frame is logged at debug level. */
+    traceIpc: boolean;
+    /** Wire payload asking the runner to exit cleanly. */
+    exitPayload: string;
+    /** How long to wait after SIGINT before escalating to subprocess termination. */
+    interruptEscalationMs: number;
+    /** Default grace period applied by {@link BaseKernel.shutdown}. */
+    shutdownGraceMs: number;
+    /** Serializes an execution request into the runner's wire protocol. */
+    buildPayload: (code: string, msgId: string, options?: TExecuteOptions) => string;
+}
+export type FrameType = "started" | "stdout" | "stderr" | "display" | "result" | "error" | "done";
+export interface Frame {
+    type: FrameType;
+    id?: string;
+    data?: string;
+    bundle?: Record<string, unknown>;
+    ename?: string;
+    evalue?: string;
+    traceback?: string[];
+    status?: "ok" | "error";
+    executionCount?: number;
+    cancelled?: boolean;
+}
+export declare function getRemainingTimeMs(deadlineMs?: number): number | undefined;
+export declare function createAbortError(name: "AbortError" | "TimeoutError", message: string): Error;
+export declare function throwIfAborted(signal: AbortSignal | undefined, fallbackReason: string): void;
+export declare function isTimeoutReason(reason: unknown): boolean;
+/**
+ * Shared subprocess-backed kernel machinery for the language runners. Each
+ * language subclasses this, supplying its binary/runner via a static `start()`
+ * and its wire protocol via {@link BaseKernelOptions.buildPayload}. The IPC loop
+ * speaks NDJSON: the runner emits one JSON {@link Frame} per line; outbound
+ * requests are serialized by `buildPayload` (which may itself be NDJSON or any
+ * other line-delimited encoding).
+ *
+ * `TExecuteOptions` is the language's own execute-options type so each runner's
+ * `buildPayload` sees its precise option shape (e.g. environment-map variants).
+ */
+export declare abstract class BaseKernel<TExecuteOptions extends KernelExecuteOptions = KernelExecuteOptions> {
+    #private;
+    readonly id: string;
+    constructor(id: string, options: BaseKernelOptions<TExecuteOptions>);
+    setProcess(proc: Subprocess<"pipe", "pipe", "pipe">): void;
+    isAlive(): boolean;
+    execute(code: string, options?: TExecuteOptions): Promise<KernelExecuteResult>;
+    interrupt(): Promise<void>;
+    shutdown(options?: KernelShutdownOptions): Promise<KernelShutdownResult>;
+    executeWithBudget(code: string, signal: AbortSignal | undefined, timeoutMs: number, label: string): Promise<void>;
+}

package/dist/types/eval/py/__tests__/prelude.test.d.ts

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

package/dist/types/eval/py/__tests__/runner-shell-output.test.d.ts

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

package/dist/types/eval/py/display.d.ts

@@ -0,0 +1,25 @@
+/** Status event emitted by prelude helpers for TUI rendering. */
+export interface PythonStatusEvent {
+    /** Operation name (e.g., "find", "read", "write") */
+    op: string;
+    /** Additional data fields (count, path, pattern, etc.) */
+    [key: string]: unknown;
+}
+export type KernelDisplayOutput = {
+    type: "json";
+    data: unknown;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+} | {
+    type: "markdown";
+} | {
+    type: "status";
+    event: PythonStatusEvent;
+};
+/** Render a MIME bundle into text + structured outputs. */
+export declare function renderKernelDisplay(content: Record<string, unknown>): Promise<{
+    text: string;
+    outputs: KernelDisplayOutput[];
+}>;

package/dist/types/eval/py/executor.d.ts

@@ -0,0 +1,107 @@
+import type { ToolSession } from "../../tools";
+import type { JsStatusEvent } from "../js/shared/types";
+import { type KernelDisplayOutput, type KernelExecuteOptions, type KernelExecuteResult } from "./kernel";
+export type PythonKernelMode = "session" | "per-call";
+export interface PythonExecutorOptions {
+    /** Working directory for command execution */
+    cwd?: string;
+    /** Timeout in milliseconds */
+    timeoutMs?: number;
+    /** Absolute wall-clock deadline in milliseconds since epoch */
+    deadlineMs?: number;
+    /**
+     * Runtime-work budget (ms). Used only for timeout-annotation text when the
+     * caller drives cancellation via the eval watchdog `signal` instead of a
+     * wall-clock `deadlineMs`/`timeoutMs`. Does not arm a timer.
+     */
+    idleTimeoutMs?: number;
+    /** Callback for streaming output chunks (already sanitized) */
+    onChunk?: (chunk: string) => Promise<void> | void;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** Session identifier for kernel reuse */
+    sessionId?: string;
+    /** Logical owner identifier for retained kernel cleanup */
+    kernelOwnerId?: string;
+    /** Kernel mode (session reuse vs per-call) */
+    kernelMode?: PythonKernelMode;
+    /**
+     * Explicit interpreter path (`python.interpreter` resolved from the
+     * session's settings). Skips automatic runtime discovery when set.
+     */
+    interpreter?: string;
+    /** Restart the kernel before executing */
+    reset?: boolean;
+    /** Session file path for accessing task outputs */
+    sessionFile?: string;
+    /**
+     * Effective artifacts directory for the current session. Subagents share
+     * the parent's directory, so this can differ from `sessionFile`'s sibling
+     * dir. When present, exported to the kernel as `PI_ARTIFACTS_DIR` and
+     * preferred over `PI_SESSION_FILE`-derived paths.
+     */
+    artifactsDir?: string;
+    /** Artifact path/id for full output storage */
+    artifactPath?: string;
+    artifactId?: string;
+    /**
+     * On-disk roots the prelude helpers (`read`/`write`) substitute for
+     * internal-URL schemes (e.g. `{ local: "/…/artifacts/local" }`). Exported to
+     * the kernel as `PI_EVAL_LOCAL_ROOTS` (JSON) so `write("local://x")` lands
+     * where `read local://x` resolves instead of a literal `local:/` directory.
+     */
+    localRoots?: Record<string, string>;
+    /**
+     * ToolSession used to resolve host-side `tool.<name>(args)` calls made from
+     * the Python prelude's bridge proxy. When omitted, the bridge env vars are
+     * not injected and any `tool.foo(...)` raises in Python.
+     */
+    toolSession?: ToolSession;
+    /** Callback for status events emitted by tool bridge invocations. */
+    emitStatus?: (event: JsStatusEvent) => void;
+    /**
+     * Live status events streamed as they are emitted (both host-side bridge
+     * helpers like `agent()` and kernel-side `display`/`log`/`phase`). Mirrors
+     * what lands in `displayOutputs` so callers can render progress before the
+     * cell finishes.
+     */
+    onStatus?: (event: JsStatusEvent) => void;
+    /** @internal Bridge session id, set by `executePython` before delegating. */
+    bridgeSessionId?: string;
+    /** @internal Bridge endpoint info, set by `executePython` before delegating. */
+    bridge?: {
+        url: string;
+        token: string;
+    };
+}
+export interface PythonKernelExecutor {
+    execute: (code: string, options?: KernelExecuteOptions) => Promise<KernelExecuteResult>;
+}
+export interface PythonResult {
+    /** Combined stdout + stderr output (sanitized, possibly truncated) */
+    output: string;
+    /** Execution exit code (0 ok, 1 error, undefined if cancelled) */
+    exitCode: number | undefined;
+    /** Whether the execution was cancelled via signal */
+    cancelled: boolean;
+    /** Whether the output was truncated */
+    truncated: boolean;
+    /** Artifact ID if full output was saved to artifact storage */
+    artifactId?: string;
+    /** Total number of lines in the output stream */
+    totalLines: number;
+    /** Total number of bytes in the output stream */
+    totalBytes: number;
+    /** Number of lines included in the output text */
+    outputLines: number;
+    /** Number of bytes included in the output text */
+    outputBytes: number;
+    /** Rich display outputs captured from display_data/execute_result */
+    displayOutputs: KernelDisplayOutput[];
+    /** Whether stdin was requested */
+    stdinRequested: boolean;
+}
+export declare function disposeAllKernelSessions(): Promise<void>;
+export declare function disposeKernelSessionsByOwner(ownerId: string): Promise<void>;
+export declare function executePythonWithKernel(kernel: PythonKernelExecutor, code: string, options?: PythonExecutorOptions): Promise<PythonResult>;
+export declare function executePython(code: string, options?: PythonExecutorOptions): Promise<PythonResult>;

package/dist/types/eval/py/index.d.ts

@@ -0,0 +1,11 @@
+import type { ToolSession } from "../../tools";
+import { type ExecutorBackendExecOptions, type ExecutorBackendResult } from "../backend";
+export declare function namespaceSessionId(sessionId: string): string;
+declare const _default: {
+    id: "python";
+    label: string;
+    highlightLang: string;
+    isAvailable(session: ToolSession): Promise<boolean>;
+    execute(code: string, opts: ExecutorBackendExecOptions): Promise<ExecutorBackendResult>;
+};
+export default _default;

package/dist/types/eval/py/kernel.d.ts

@@ -0,0 +1,17 @@
+import { BaseKernel, type KernelStartOptions } from "../kernel-base";
+import { type PythonRuntime } from "./runtime";
+export type { KernelExecuteOptions, KernelExecuteResult, KernelRuntimeEnv, KernelShutdownOptions, KernelShutdownResult, } from "../kernel-base";
+export type { KernelDisplayOutput, PythonStatusEvent } from "./display";
+export { renderKernelDisplay } from "./display";
+export interface PythonKernelAvailability {
+    ok: boolean;
+    pythonPath?: string;
+    reason?: string;
+    /** The probed-working runtime, when one was found. */
+    runtime?: PythonRuntime;
+}
+export declare function checkPythonKernelAvailability(cwd: string, interpreter?: string): Promise<PythonKernelAvailability>;
+export declare class PythonKernel extends BaseKernel {
+    private constructor();
+    static start(options: KernelStartOptions): Promise<PythonKernel>;
+}

package/dist/types/eval/py/prelude.d.ts

@@ -0,0 +1 @@
+export declare const PYTHON_PRELUDE: string;

package/dist/types/eval/py/runtime.d.ts

@@ -0,0 +1,40 @@
+export interface PythonRuntime {
+    /** Path to python executable */
+    pythonPath: string;
+    /** Filtered environment variables */
+    env: Record<string, string | undefined>;
+    /** Path to virtual environment, if detected */
+    venvPath?: string;
+}
+/**
+ * Filter environment variables to a safe allowlist for Python subprocesses.
+ * Removes sensitive API keys and limits to known-safe variables.
+ */
+export declare function filterEnv(env: Record<string, string | undefined>): Record<string, string | undefined>;
+/**
+ * Detect virtual environment path from VIRTUAL_ENV or common locations.
+ */
+export declare function resolveVenvPath(cwd: string): string | undefined;
+/**
+ * Resolve an explicitly configured interpreter (`python.interpreter`) into a
+ * runtime, bypassing discovery. Does not probe or validate the executable —
+ * callers must check it actually runs. `~` expands to the home directory and
+ * relative paths resolve against `cwd`. When the interpreter sits inside a
+ * virtualenv (a `pyvenv.cfg` above its bin dir), the venv activation env is
+ * applied so subprocesses and `pip` resolve consistently.
+ */
+export declare function resolveExplicitPythonRuntime(interpreter: string, cwd: string, baseEnv: Record<string, string | undefined>): PythonRuntime;
+/**
+ * Enumerate candidate Python runtimes in priority order: an active/project venv,
+ * the managed `~/.jeopi/python-env`, then the system interpreter on PATH. Every
+ * candidate that physically exists is returned so callers can probe each in turn
+ * rather than committing to the first — a managed env left behind by a removed
+ * `uv` install no longer shadows a working system Python.
+ */
+export declare function enumeratePythonRuntimes(cwd: string, baseEnv: Record<string, string | undefined>): PythonRuntime[];
+/**
+ * Resolve the highest-priority Python runtime. Prefer {@link enumeratePythonRuntimes}
+ * when you can probe candidates; this returns only the first one and throws when
+ * no interpreter exists.
+ */
+export declare function resolvePythonRuntime(cwd: string, baseEnv: Record<string, string | undefined>): PythonRuntime;

package/dist/types/eval/py/spawn-options.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Decide whether the long-lived Python kernel subprocess should be spawned
+ * with `windowsHide: true`.
+ *
+ * On Windows, Bun maps `windowsHide: true` to the `CREATE_NO_WINDOW` flag,
+ * which detaches the child from any inherited console. The Python kernel
+ * runs user code that imports NumPy/pandas; those native extensions
+ * (`numpy/_core/_multiarray_umath.pyd` + bundled OpenBLAS/SLEEF thread-pool
+ * init) can deadlock inside `LoadLibraryExW` when no console is attached,
+ * and a console-less child cannot receive SIGINT via
+ * `GenerateConsoleCtrlEvent` (the recovery path the host relies on). See
+ * issue #1960.
+ *
+ * So on Windows we hide only when the host itself has no console to share.
+ * In any launch where a console is attached — even one with every stdio
+ * stream redirected — the kernel inherits the parent's console, matching
+ * `python.exe` invoked from `cmd.exe`, which keeps native imports and
+ * SIGINT recovery working.
+ *
+ * Short-lived helper subprocesses elsewhere in the codebase (LSP probes,
+ * git, plugin installs) keep `windowsHide: true` because they don't load
+ * complex native modules and the brief console flash would be user-visible
+ * noise.
+ */
+export declare function shouldHideKernelWindow(opts: {
+    platform: NodeJS.Platform;
+    hostHasInheritableConsole: boolean;
+}): boolean;
+/**
+ * TTY-based fallback used when the Win32 console probe is unavailable.
+ *
+ * Returns `true` if any of stdin/stdout/stderr is currently a TTY. This
+ * correctly detects the common interactive launches and the partial-
+ * redirection cases (`omp -p > out.txt`, `< in.txt`, `2> err.log`) where at
+ * least one stream stays bound to the terminal. The all-stdio-redirected
+ * case (`< in > out 2> err` from a console) is the reason we prefer the
+ * Win32 probe over this fallback whenever possible.
+ */
+export declare function consoleAttachedViaTTY(opts: {
+    stdinIsTTY: boolean;
+    stdoutIsTTY: boolean;
+    stderrIsTTY: boolean;
+}): boolean;
+/** Reset the cached Win32 probe result. Test-only; not part of the public surface. */
+export declare function __resetWindowsConsoleProbeCache(): void;
+/**
+ * Whether the host process owns a console its children can inherit.
+ *
+ * - On Windows, the authoritative signal is `GetConsoleWindow()`. It returns
+ *   a non-NULL HWND whenever the process has a console attached, regardless
+ *   of how the standard streams are redirected — so an `omp -p ... < in.txt
+ *   > out.txt 2> err.log` launched from a real Windows Terminal session is
+ *   correctly classified as console-attached and the kernel keeps its
+ *   inheritable console.
+ * - On any other platform, or if the FFI probe fails, fall back to the
+ *   TTY-OR heuristic. That still catches the common interactive cases.
+ */
+export declare function hostHasInheritableConsole(): boolean;

package/dist/types/eval/py/tool-bridge.d.ts

@@ -0,0 +1,16 @@
+import type { ToolSession } from "../../tools";
+import { type JsStatusEvent } from "../js/tool-bridge";
+export interface PyToolBridgeEntry {
+    toolSession: ToolSession;
+    signal?: AbortSignal;
+    emitStatus?: (event: JsStatusEvent) => void;
+}
+export interface PyToolBridgeInfo {
+    url: string;
+    token: string;
+}
+/** Starts the bridge server lazily and returns its connection info. */
+export declare function ensurePyToolBridge(): Promise<PyToolBridgeInfo>;
+export declare function registerPyToolBridge(sessionId: string, runId: string, entry: PyToolBridgeEntry): () => void;
+/** Stop the bridge and clear registrations. Test-only / shutdown helper. */
+export declare function disposePyToolBridge(): Promise<void>;

package/dist/types/eval/rb/executor.d.ts

@@ -0,0 +1,77 @@
+import type { ToolSession } from "../../tools";
+import type { JsStatusEvent } from "../js/shared/types";
+import { type KernelDisplayOutput, type KernelExecuteOptions, type KernelExecuteResult } from "./kernel";
+export interface RubyExecutorOptions {
+    /** Working directory for command execution */
+    cwd?: string;
+    /** Timeout in milliseconds */
+    timeoutMs?: number;
+    /** Absolute wall-clock deadline in milliseconds since epoch */
+    deadlineMs?: number;
+    /**
+     * Runtime-work budget (ms). Used only for timeout-annotation text when the
+     * caller drives cancellation via the eval watchdog `signal`. Does not arm a timer.
+     */
+    idleTimeoutMs?: number;
+    /** Callback for streaming output chunks (already sanitized) */
+    onChunk?: (chunk: string) => Promise<void> | void;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** Session identifier for kernel reuse */
+    sessionId?: string;
+    /** Logical owner identifier for retained kernel cleanup */
+    kernelOwnerId?: string;
+    /** Explicit interpreter path (`ruby.interpreter`). Skips discovery when set. */
+    interpreter?: string;
+    /** Restart the kernel before executing */
+    reset?: boolean;
+    /** Session file path for accessing task outputs */
+    sessionFile?: string;
+    /** Effective artifacts directory for the current session. */
+    artifactsDir?: string;
+    /** Artifact path/id for full output storage */
+    artifactPath?: string;
+    artifactId?: string;
+    /**
+     * On-disk roots the prelude helpers substitute for internal-URL schemes
+     * (e.g. `{ local: "/…/artifacts/local" }`). Exported to the kernel as
+     * `PI_EVAL_LOCAL_ROOTS` (JSON).
+     */
+    localRoots?: Record<string, string>;
+    /**
+     * ToolSession used to resolve host-side `tool.<name>(args)` calls. When
+     * omitted, the bridge env vars are not injected and `tool.foo(...)` raises.
+     */
+    toolSession?: ToolSession;
+    /** Callback for status events emitted by tool bridge invocations. */
+    emitStatus?: (event: JsStatusEvent) => void;
+    /** Live status events streamed as they are emitted. */
+    onStatus?: (event: JsStatusEvent) => void;
+    /** @internal Bridge session id, set by `executeRuby` before delegating. */
+    bridgeSessionId?: string;
+    /** @internal Bridge endpoint info, set by `executeRuby` before delegating. */
+    bridge?: {
+        url: string;
+        token: string;
+    };
+}
+export interface RubyKernelExecutor {
+    execute: (code: string, options?: KernelExecuteOptions) => Promise<KernelExecuteResult>;
+}
+export interface RubyResult {
+    output: string;
+    exitCode: number | undefined;
+    cancelled: boolean;
+    truncated: boolean;
+    artifactId?: string;
+    totalLines: number;
+    totalBytes: number;
+    outputLines: number;
+    outputBytes: number;
+    displayOutputs: KernelDisplayOutput[];
+    stdinRequested: boolean;
+}
+export declare function disposeAllRubyKernelSessions(): Promise<void>;
+export declare function disposeRubyKernelSessionsByOwner(ownerId: string): Promise<void>;
+export declare function executeRubyWithKernel(kernel: RubyKernelExecutor, code: string, options?: RubyExecutorOptions): Promise<RubyResult>;
+export declare function executeRuby(code: string, options?: RubyExecutorOptions): Promise<RubyResult>;