@alisio/core 0.5.1 → 0.6.0

package/dist/forge/runtime.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Assembly of the Forja engines for one application (spec §4.1): the engine registry with the
+ * JavaScript engine's self-check, the kernel and the status the CLI and the API report. Nothing
+ * runs here: it builds the objects, and `register()` is the only step that touches the file system
+ * (to verify the WASM). Fail closed (D17): an engine that does not verify is registered as
+ * unavailable, `js_run` is not offered and `status()` says why.
+ */
+import type { EngineDescriptor } from "@alisio/sdk";
+import type { Config } from "../config.ts";
+import { JavaScriptEngine } from "./javascript/engine.ts";
+import { IsolateHostFactory } from "./javascript/hosts/factory.ts";
+import type { SqliteExecutionJournal } from "./journal.ts";
+import { ExecutionKernel } from "./kernel.ts";
+import { type ForgeLimits } from "./limits.ts";
+import { EngineRegistry } from "./registry.ts";
+import type { SqliteStateStore } from "./state-store.ts";
+export interface ForgeStatus {
+    engines: EngineDescriptor[];
+    javascript: {
+        /** The WASM verified and the host can start, whatever `enabled` says. */
+        verified: boolean;
+        /** Why it did not verify. */
+        verification?: string;
+        enabled: boolean;
+        host: "worker" | "process";
+        hostSetting: "auto" | "worker" | "process";
+        wasmSha256: string;
+        version: string;
+        limits: ForgeLimits;
+    };
+    scratch: {
+        enabled: boolean;
+        retentionDays: number;
+        maxBytes: number;
+    };
+    state: {
+        enabled: boolean;
+    };
+    guides: {
+        enabled: boolean;
+    };
+}
+export interface ForgeRuntime {
+    engines: EngineRegistry;
+    engine: JavaScriptEngine;
+    kernel: ExecutionKernel;
+    /** The JavaScript engine verified and may be offered (`js_run`). */
+    jsReady: boolean;
+    status(): Promise<ForgeStatus>;
+    /** Starts a real isolate and runs a trivial script (`alisio forge status --probe`). */
+    probe(): ReturnType<JavaScriptEngine["probe"]>;
+}
+export interface ForgeRuntimeDeps {
+    forge: () => Config["forge"];
+    journal: SqliteExecutionJournal;
+    state: SqliteStateStore;
+    /** Overrides the host factory (tests). */
+    hosts?: IsolateHostFactory;
+}
+export declare function createForgeRuntime(deps: ForgeRuntimeDeps): Promise<ForgeRuntime>;
+/** The engine's state as `alisio forge status` and the API report it. */
+export declare function describeForge(forge: Config["forge"], engine: JavaScriptEngine): Promise<ForgeStatus>;
+/** A throwaway engine for the CLI: no application, no database. */
+export declare function forgeEngineFor(forge: Config["forge"]): JavaScriptEngine;

package/dist/forge/runtime.js

@@ -0,0 +1,88 @@
+import { JavaScriptEngine } from "./javascript/engine.js";
+import { IsolateHostFactory } from "./javascript/hosts/factory.js";
+import { JAVASCRIPT_ENGINE_VERSION, QUICKJS_WASM_SHA256 } from "./javascript/runtime-manifest.js";
+import { loadQuickJsModule } from "./javascript/wasm.js";
+import { ExecutionKernel } from "./kernel.js";
+import { mergeLimits } from "./limits.js";
+import { EngineRegistry } from "./registry.js";
+import { createJavaScriptSelector } from "./selector.js";
+import { SlotTable } from "./slots.js";
+/** One table per process: the per-process cap is shared by every application in it (D-29). */
+const processSlots = new SlotTable();
+const kernelConfig = (forge) => {
+    const js = forge.javascript;
+    return {
+        enabled: js.enabled,
+        stateEnabled: forge.state.enabled,
+        limits: {
+            timeoutMs: js.timeoutMs,
+            memoryBytes: js.memoryBytes,
+            stackBytes: js.stackBytes,
+            maxToolCalls: js.maxToolCalls,
+            maxConcurrency: js.maxConcurrency,
+            maxOutputChars: js.maxOutputChars,
+        },
+    };
+};
+export async function createForgeRuntime(deps) {
+    const hosts = deps.hosts ??
+        new IsolateHostFactory({ choice: deps.forge().javascript.host, module: loadQuickJsModule });
+    const engine = new JavaScriptEngine({ hosts });
+    const engines = new EngineRegistry();
+    let jsReady = false;
+    // A disabled engine is never loaded or verified: nothing happens at startup with Forja off.
+    if (deps.forge().javascript.enabled)
+        jsReady = (await engines.register(engine)).ready;
+    const kernel = new ExecutionKernel({
+        engines,
+        selector: createJavaScriptSelector(),
+        journal: deps.journal,
+        state: deps.state,
+        slots: processSlots,
+        config: () => kernelConfig(deps.forge()),
+    });
+    return {
+        engines,
+        engine,
+        kernel,
+        jsReady,
+        probe: () => engine.probe(),
+        status: () => describeForge(deps.forge(), engine),
+    };
+}
+/** The engine's state as `alisio forge status` and the API report it. */
+export async function describeForge(forge, engine) {
+    // Always a fresh self-check: `verified` says whether the engine WOULD run, `enabled` whether it may.
+    const verification = await engine.describe();
+    const enabled = forge.javascript.enabled;
+    const descriptor = !enabled && verification.ready
+        ? { ...verification, ready: false, reason: "disabled by config (forge.javascript.enabled)" }
+        : verification;
+    return {
+        engines: [descriptor],
+        javascript: {
+            verified: verification.ready,
+            ...(verification.ready ? {} : { verification: verification.reason ?? "not verified" }),
+            enabled,
+            host: engine.hostKind,
+            hostSetting: forge.javascript.host,
+            wasmSha256: QUICKJS_WASM_SHA256,
+            version: JAVASCRIPT_ENGINE_VERSION,
+            limits: mergeLimits({ global: kernelConfig(forge).limits }),
+        },
+        // The folder (`scratch.root`) is a host path: it stays out of what the surfaces show.
+        scratch: {
+            enabled: forge.scratch.enabled,
+            retentionDays: forge.scratch.retentionDays,
+            maxBytes: forge.scratch.maxBytes,
+        },
+        state: { enabled: forge.state.enabled },
+        guides: { enabled: forge.guides.enabled },
+    };
+}
+/** A throwaway engine for the CLI: no application, no database. */
+export function forgeEngineFor(forge) {
+    return new JavaScriptEngine({
+        hosts: new IsolateHostFactory({ choice: forge.javascript.host, module: loadQuickJsModule }),
+    });
+}

package/dist/forge/scratch-files.d.ts

@@ -0,0 +1,36 @@
+export interface ScratchFileInfo {
+    name: string;
+    size: number;
+    mtime: number;
+}
+/** Most files a listing returns. */
+export declare const SCRATCH_LIST_LIMIT = 2000;
+/** Deepest directory level a listing enters. */
+export declare const SCRATCH_LIST_MAX_DEPTH = 32;
+/**
+ * Regular files of the scratchpad in name order; links and special files are left out. The walk
+ * visits entries in the order of the final sort (a directory sorts as `name/`) and stops as soon
+ * as one file more than `limit` is known, so a huge tree costs no more than the cap. `scanned` is
+ * how many files were examined.
+ */
+export declare function listScratch(scratchpad: string, limit?: number): Promise<{
+    files: ScratchFileInfo[];
+    usedBytes: number;
+    truncated: boolean;
+    scanned: number;
+}>;
+/**
+ * A read handle for one file of the scratchpad. The path is confined (lexically and on the real
+ * file system), no segment may be a link and the file is opened with `O_NOFOLLOW` where the
+ * platform has it. Throws `INVALID_INPUT` for anything that is not a regular file inside.
+ */
+export declare function openScratchFile(scratchpad: string, relative: string): Promise<{
+    handle: import("node:fs/promises").FileHandle;
+    size: number;
+    name: string;
+}>;
+/** Removes everything inside the scratchpad and keeps the folder. Never follows a link. */
+export declare function emptyScratch(scratchpad: string): Promise<{
+    removed: number;
+    freedBytes: number;
+}>;

package/dist/forge/scratch-files.js

@@ -0,0 +1,94 @@
+/**
+ * What the HTTP surface does with a session's scratchpad (spec §9.4, §11.1): list it, open one file
+ * for download and empty it. Everything is relative to the verified scratchpad folder, symbolic links
+ * are never followed (a link is neither listed, opened nor entered; emptying removes the link itself),
+ * and nothing returned names an absolute host path.
+ */
+import { constants } from "node:fs";
+import { lstat, open, readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { ForgeError } from "./errors.js";
+import { resolveScratchPath, scratchUsage } from "./session-dir.js";
+/** Most files a listing returns. */
+export const SCRATCH_LIST_LIMIT = 2_000;
+/** Deepest directory level a listing enters. */
+export const SCRATCH_LIST_MAX_DEPTH = 32;
+/**
+ * Regular files of the scratchpad in name order; links and special files are left out. The walk
+ * visits entries in the order of the final sort (a directory sorts as `name/`) and stops as soon
+ * as one file more than `limit` is known, so a huge tree costs no more than the cap. `scanned` is
+ * how many files were examined.
+ */
+export async function listScratch(scratchpad, limit = SCRATCH_LIST_LIMIT) {
+    const files = [];
+    let scanned = 0;
+    const key = (entry) => entry.isDirectory() ? `${entry.name}/` : entry.name;
+    const walk = async (dir, prefix, depth) => {
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        entries.sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
+        for (const entry of entries) {
+            if (files.length > limit)
+                return;
+            const path = join(dir, entry.name);
+            const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (depth < SCRATCH_LIST_MAX_DEPTH)
+                    await walk(path, name, depth + 1);
+            }
+            else if (entry.isFile()) {
+                scanned++;
+                const info = await lstat(path).catch(() => undefined);
+                if (info?.isFile())
+                    files.push({ name, size: info.size, mtime: Math.floor(info.mtimeMs) });
+            }
+        }
+    };
+    await walk(scratchpad, "", 0);
+    return {
+        files: files.slice(0, limit),
+        usedBytes: await scratchUsage(scratchpad),
+        truncated: files.length > limit,
+        scanned,
+    };
+}
+/**
+ * A read handle for one file of the scratchpad. The path is confined (lexically and on the real
+ * file system), no segment may be a link and the file is opened with `O_NOFOLLOW` where the
+ * platform has it. Throws `INVALID_INPUT` for anything that is not a regular file inside.
+ */
+export async function openScratchFile(scratchpad, relative) {
+    if (!relative || relative.includes("\0") || relative.includes("\\"))
+        throw new ForgeError("INVALID_INPUT", "not a scratchpad file");
+    const target = await resolveScratchPath(scratchpad, relative);
+    let current = scratchpad;
+    const segments = relative.split("/").filter(Boolean);
+    for (const segment of segments) {
+        current = join(current, segment);
+        const info = await lstat(current).catch(() => undefined);
+        if (!info || info.isSymbolicLink())
+            throw new ForgeError("INVALID_INPUT", "not a scratchpad file");
+    }
+    const info = await lstat(target);
+    if (!info.isFile())
+        throw new ForgeError("INVALID_INPUT", "not a scratchpad file");
+    const handle = await open(target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    return { handle, size: info.size, name: segments.at(-1) ?? relative };
+}
+/** Removes everything inside the scratchpad and keeps the folder. Never follows a link. */
+export async function emptyScratch(scratchpad) {
+    const freedBytes = await scratchUsage(scratchpad);
+    let removed = 0;
+    const count = async (dir) => {
+        for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+            if (entry.isDirectory())
+                await count(join(dir, entry.name));
+            else
+                removed++;
+        }
+    };
+    await count(scratchpad);
+    for (const entry of await readdir(scratchpad)) {
+        await rm(join(scratchpad, entry), { recursive: true, force: true });
+    }
+    return { removed, freedBytes };
+}

package/dist/forge/scratch-provider.d.ts

@@ -0,0 +1,41 @@
+export interface ScratchpadProviderOptions {
+    /** The root session of `session` (a child session shares its root's scratchpad). */
+    rootOf: (session: string) => string;
+    /** Workspace of a root session; names its folder. */
+    workspaceOf: (rootSessionId: string) => string;
+    workspaceKey: (workspace: string) => string;
+    /** Home of the `<stateHome>/scratch` fallback. */
+    stateHome: string;
+    /** `forge.scratch.root`, read on every first use so a changed setting applies. */
+    configRoot: () => string | null | undefined;
+    /** Reports the diagnostic of a session that fell back to the state folder. */
+    onDiagnostic?: (message: string) => void;
+    env?: Record<string, string | undefined>;
+}
+export type ScratchpadProvider = (session: string) => Promise<string | undefined>;
+/**
+ * The verified scratchpad of the session's ROOT session, created on first use and remembered.
+ * Any failure (no usable folder) means "no scratchpad" for that call and is retried next time.
+ */
+export declare function createScratchpadProvider(options: ScratchpadProviderOptions): ScratchpadProvider;
+/**
+ * The scratchpad of the session's ROOT session only if its folder already exists: nothing is
+ * created. For read-only surfaces (the HTTP listing).
+ */
+export declare function createScratchpadLookup(options: ScratchpadProviderOptions): ScratchpadProvider;
+export interface ScratchRootsOptions {
+    /**
+     * The store is not the user's default one (an embedder or a test passed its own database): it
+     * cannot tell which sessions of the shared temporary root exist, so that root is left alone.
+     */
+    customStore: boolean;
+    /** `<stateHome>/scratch` of this application's state. */
+    stateHome: string;
+    configRoot: string | null | undefined;
+    env?: Record<string, string | undefined>;
+    platform?: NodeJS.Platform;
+    uid?: number;
+    osTmpdir?: string;
+}
+/** The scratch roots the janitor sweeps: `<tmp>/alisio-<uid>` (default store only) and `<state>/scratch`. */
+export declare function scratchSweepRoots(options: ScratchRootsOptions): string[];

package/dist/forge/scratch-provider.js

@@ -0,0 +1,79 @@
+/**
+ * Where the application finds the scratchpad of a session and which folders the retention sweep
+ * may look at (spec §9.4, D19). Thin glue over `session-dir.ts`: the privacy rules live there, the
+ * choice of root lives in `session-path.ts`.
+ */
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ensureSessionDir, findSessionScratchpad } from "./session-dir.js";
+import { scratchBaseName, tmpRootChoice } from "./session-path.js";
+/**
+ * The verified scratchpad of the session's ROOT session, created on first use and remembered.
+ * Any failure (no usable folder) means "no scratchpad" for that call and is retried next time.
+ */
+export function createScratchpadProvider(options) {
+    const dirs = new Map();
+    return async (session) => {
+        try {
+            const rootSessionId = options.rootOf(session);
+            let pending = dirs.get(rootSessionId);
+            if (!pending) {
+                const workspace = options.workspaceOf(rootSessionId);
+                pending = ensureSessionDir({
+                    rootSessionId,
+                    workspace,
+                    workspaceKey: options.workspaceKey(workspace),
+                    stateHome: options.stateHome,
+                    configRoot: options.configRoot() ?? null,
+                    ...(options.env ? { env: options.env } : {}),
+                });
+                dirs.set(rootSessionId, pending);
+                pending.then((dir) => {
+                    if (dir.diagnostic)
+                        options.onDiagnostic?.(dir.diagnostic);
+                }, () => dirs.delete(rootSessionId));
+            }
+            return (await pending).scratchpad;
+        }
+        catch {
+            return undefined;
+        }
+    };
+}
+/**
+ * The scratchpad of the session's ROOT session only if its folder already exists: nothing is
+ * created. For read-only surfaces (the HTTP listing).
+ */
+export function createScratchpadLookup(options) {
+    return async (session) => {
+        try {
+            const rootSessionId = options.rootOf(session);
+            const workspace = options.workspaceOf(rootSessionId);
+            return await findSessionScratchpad({
+                rootSessionId,
+                workspace,
+                workspaceKey: options.workspaceKey(workspace),
+                stateHome: options.stateHome,
+                configRoot: options.configRoot() ?? null,
+                ...(options.env ? { env: options.env } : {}),
+            });
+        }
+        catch {
+            return undefined;
+        }
+    };
+}
+/** The scratch roots the janitor sweeps: `<tmp>/alisio-<uid>` (default store only) and `<state>/scratch`. */
+export function scratchSweepRoots(options) {
+    const roots = [join(options.stateHome, "scratch")];
+    if (options.customStore)
+        return roots;
+    const platform = options.platform ?? process.platform;
+    const uid = platform === "win32" ? undefined : (options.uid ?? process.getuid?.());
+    const tmp = tmpRootChoice({
+        env: (options.env ?? process.env).ALISIO_TMPDIR,
+        config: options.configRoot,
+        os: options.osTmpdir ?? tmpdir(),
+    });
+    return [join(tmp, scratchBaseName(platform, uid)), ...roots];
+}

package/dist/forge/scratch-quota.d.ts

@@ -0,0 +1,8 @@
+/** Whether the quota can be enforced beforehand for this tool. */
+export declare const hasScratchEstimator: (tool: string) => boolean;
+/**
+ * The bytes the file(s) will hold after the call: what `PathAccess.scratchQuotaProblem` takes as
+ * `incomingBytes` (the current size of the replaced `targets` is subtracted there). A tool with no
+ * estimator that a policy allowed anyway counts its `content` string, as before.
+ */
+export declare function scratchIncomingBytes(tool: string, input: Record<string, unknown>, targets: readonly string[]): Promise<number>;

package/dist/forge/scratch-quota.js

@@ -0,0 +1,25 @@
+/**
+ * How many bytes a write into the scratchpad leaves in it (spec §9.4, FJ-AC-34), per tool. The
+ * quota check needs the size the file WILL have, and only the tool knows its own semantics:
+ * `write_file` stores `content`; `edit_file` replaces one occurrence, so the new size is the
+ * current size minus `oldText` plus `newText`. A write-effect tool without an estimate here is not
+ * let into the scratchpad without an approval (its size cannot be bounded beforehand).
+ */
+import { lstat } from "node:fs/promises";
+const ESTIMATED = new Set(["write_file", "edit_file"]);
+/** Whether the quota can be enforced beforehand for this tool. */
+export const hasScratchEstimator = (tool) => ESTIMATED.has(tool);
+const bytesOf = (value) => typeof value === "string" ? Buffer.byteLength(value) : 0;
+/**
+ * The bytes the file(s) will hold after the call: what `PathAccess.scratchQuotaProblem` takes as
+ * `incomingBytes` (the current size of the replaced `targets` is subtracted there). A tool with no
+ * estimator that a policy allowed anyway counts its `content` string, as before.
+ */
+export async function scratchIncomingBytes(tool, input, targets) {
+    if (tool === "edit_file") {
+        const target = targets[0];
+        const current = target ? ((await lstat(target).catch(() => undefined))?.size ?? 0) : 0;
+        return Math.max(0, current - bytesOf(input.oldText) + bytesOf(input.newText));
+    }
+    return bytesOf(input.content);
+}

package/dist/forge/selector.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Engine selection as a chain of responsibility (spec §4.2, §7.2): ordered, deterministic rules,
+ * each returning a decision with its reason or passing to the next. The model never picks the
+ * engine. The chain is generic so the Python backend selector reuses it with its own context.
+ */
+import type { EngineDescriptor, EngineId, EngineLanguage } from "@alisio/sdk";
+import { type ForgeErrorCode } from "./errors.ts";
+export interface Selection<I extends string> {
+    engine: I;
+    reason: string;
+}
+export interface Rejection {
+    rejected: true;
+    reason: string;
+    code: ForgeErrorCode;
+}
+/** `null` passes to the next rule. */
+export type RuleOutcome<I extends string> = Selection<I> | Rejection | null;
+export type SelectionRule<C, I extends string> = (context: C) => RuleOutcome<I>;
+export declare const select: <I extends string>(engine: I, reason: string) => Selection<I>;
+export declare const reject: (reason: string, code?: ForgeErrorCode) => Rejection;
+export declare class EngineSelector<C, I extends string> {
+    #private;
+    constructor(rules: readonly SelectionRule<C, I>[]);
+    /** The first rule that decides wins; a rejection throws and no rule means unavailable. */
+    select(context: C): Selection<I>;
+}
+export interface JavaScriptSelectionContext {
+    language: EngineLanguage;
+    /** `forge.javascript.enabled`. */
+    javascriptEnabled: boolean;
+    descriptors: Partial<Record<EngineId, EngineDescriptor>>;
+}
+/** The JavaScript chain of §7.2. Python's chain lives with the Python backend. */
+export declare function createJavaScriptSelector(): EngineSelector<JavaScriptSelectionContext, EngineId>;

package/dist/forge/selector.js

@@ -0,0 +1,51 @@
+import { ForgeError } from "./errors.js";
+export const select = (engine, reason) => ({
+    engine,
+    reason,
+});
+export const reject = (reason, code = "ENGINE_UNAVAILABLE") => ({
+    rejected: true,
+    reason,
+    code,
+});
+export class EngineSelector {
+    #rules;
+    constructor(rules) {
+        this.#rules = rules;
+    }
+    /** The first rule that decides wins; a rejection throws and no rule means unavailable. */
+    select(context) {
+        for (const rule of this.#rules) {
+            const outcome = rule(context);
+            if (outcome === null)
+                continue;
+            if ("rejected" in outcome)
+                throw new ForgeError(outcome.code, outcome.reason);
+            return outcome;
+        }
+        throw new ForgeError("ENGINE_UNAVAILABLE", "No selection rule matched the request");
+    }
+}
+const JAVASCRIPT_ENGINE = "javascript-quickjs";
+const javascriptDisabled = (c) => c.language === "javascript" && !c.javascriptEnabled ? reject("disabled by config") : null;
+const javascriptNotReady = (c) => {
+    if (c.language !== "javascript")
+        return null;
+    const descriptor = c.descriptors[JAVASCRIPT_ENGINE];
+    if (!descriptor)
+        return reject(`engine ${JAVASCRIPT_ENGINE} is not registered`);
+    if (!descriptor.ready)
+        return reject(descriptor.reason ?? `engine ${JAVASCRIPT_ENGINE} is not ready`);
+    return null;
+};
+const javascriptDefault = (c) => c.language === "javascript" ? select(JAVASCRIPT_ENGINE, "language=javascript") : null;
+const NO_ENGINE_FOR_LANGUAGE = (c) => c.language === "javascript" ? null : reject(`no engine rule for language ${c.language}`);
+/** The JavaScript chain of §7.2. Python's chain lives with the Python backend. */
+export function createJavaScriptSelector() {
+    return new EngineSelector([
+        javascriptDisabled,
+        javascriptNotReady,
+        javascriptDefault,
+        NO_ENGINE_FOR_LANGUAGE,
+    ]);
+}

package/dist/forge/session-dir.d.ts

@@ -0,0 +1,59 @@
+export declare const SESSION_MARKER = ".alisio-session";
+export interface SessionDirOptions {
+    rootSessionId: string;
+    /** Absolute path of the workspace. */
+    workspace: string;
+    /** `workspaceKey(workspace)` from runtime/paths.ts. */
+    workspaceKey: string;
+    /** `stateHome()`; home of the fallback. */
+    stateHome: string;
+    /** `forge.scratch.root`. */
+    configRoot?: string | null;
+    /** Defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Defaults to `process.platform`. */
+    platform?: NodeJS.Platform;
+    /** Defaults to `process.getuid()`. */
+    uid?: number;
+    /** Defaults to `os.tmpdir()`. */
+    osTmpdir?: string;
+    now?: () => number;
+}
+export interface SessionDir {
+    /** `<...>/<rootSessionId>` */
+    root: string;
+    scratchpad: string;
+    tasks: string;
+    /** The shared temporary root could not be trusted and the state folder is used instead. */
+    fallback: boolean;
+    diagnostic?: string;
+}
+export interface SessionMarker {
+    sessionId: string;
+    workspaceKey: string;
+    createdAt: number;
+}
+export declare function ensureSessionDir(options: SessionDirOptions): Promise<SessionDir>;
+/**
+ * The scratchpad folder of a session if it already exists and is a private directory, else
+ * undefined. Unlike `ensureSessionDir` it never creates anything, so a read-only look (the HTTP
+ * listing) leaves no trace. Tries the shared temporary root first, then the state fallback.
+ */
+export declare function findSessionScratchpad(options: SessionDirOptions): Promise<string | undefined>;
+/** The marker of a session folder, or undefined when it is missing or not valid. */
+export declare function readSessionMarker(root: string): Promise<SessionMarker | undefined>;
+/**
+ * A scratchpad path the model gave (relative, or absolute inside), checked lexically and then
+ * against the real file system: the deepest existing ancestor must resolve inside the real
+ * scratchpad, so a symlink that points out is refused. Throws `INVALID_INPUT`.
+ */
+export declare function resolveScratchPath(scratchpad: string, input: string): Promise<string>;
+/** Bytes held by the files of a folder (symlinks are counted as links, never followed). */
+export declare function scratchUsage(dir: string): Promise<number>;
+/**
+ * Writes a file into the scratchpad with mode `0600`, refusing paths that escape it and writes
+ * that would take the scratchpad past `maxBytes`. Nothing is ever deleted to make room.
+ */
+export declare function writeScratchFile(scratchpad: string, path: string, data: string | Uint8Array, options: {
+    maxBytes: number;
+}): Promise<string>;