@struktoai/mirage-core/dist/workspace/snapshot/state.d.ts

A Unified Virtual Filesystem For AI Agents

import type { FileCacheMixin } from '../../cache/file/mixin.ts';
import { CLI } from '../../commands/cli/types.ts';
import type { NetworkSetting } from '../../io/network.ts';
import type { Observer } from '../../observe/observer.ts';
import type { OpRecord } from '../../observe/record.ts';
import { type SessionProfile } from '../../policy/profile.ts';
import { type JobTable } from '../../shell/job_table/index.ts';
import { type WritePolicy } from '../../types.ts';
import { BaseVFS } from '../../vfs/base.ts';
import type { Documents } from '../documentation/documents.ts';
import type { MountEntry } from '../mount/mount.ts';
import { type Namespace } from '../mount/namespace/namespace.ts';
import type { MountRegistry } from '../mount/registry.ts';
import { Mount } from '../mount/spec.ts';
import type { SessionManager } from '../session/manager.ts';
import type { MountArgs } from './config.ts';
import type { MountSnapshot, WorkspaceStateDict } from './types.ts';
/**
 * Per-name overrides for restoring installed CLIs: a plain mapping is a
 * fresh config (the spec resolves from the snapshot's registry key); a
 * [spec, config] tuple carries a live spec too, which is how copy()
 * shares directly installed programs.
 */
export type CLIOverrides = Record<string, Record<string, unknown> | [CLI, Record<string, unknown> | null]>;
/** What a snapshot reads from a workspace and restores into it (`Workspace`). */
export interface WorkspaceLike {
    readonly registry: MountRegistry;
    readonly syntheticRoot: boolean;
    readonly sessionManager: SessionManager;
    readonly jobTable: JobTable;
    readonly writeDefault: WritePolicy;
    readonly cache: FileCacheMixin & BaseVFS;
    readonly namespace: Namespace;
    readonly observer: Observer;
    readonly documents: Documents;
    readonly records: OpRecord[];
    readonly defaultSessionId: string;
    readonly profiles: Readonly<Record<string, SessionProfile>>;
    readonly defaultProfileName: string | null;
    readonly network: NetworkSetting;
    readonly systemTime: string | null;
    adoptDefaultSession(sessionId: string): Promise<void>;
    forgetReads(): void;
    quiesced<T>(capture: () => Promise<T>): Promise<T>;
}
export declare function toStateDict(ws: WorkspaceLike): Promise<WorkspaceStateDict>;
/**
 * Refuse a snapshot in another format than this loader's, older or newer.
 *
 * An absent version is v3 or older, not "current". It used to be
 * harmless because every key the loader read had a default; v4 makes the
 * read policy required, so an unversioned dict would land on a bad
 * ReadSpec instead of this message.
 *
 * Both entry points run it, mirroring Python's `check_format_version`.
 * `buildMountArgs` builds a workspace from the state; `applyStateDict`
 * restores into one that already exists, and is what `version checkout`,
 * `version restore` and the agent sandbox's hydrate call. Checking in one
 * entry point only meant the same bytes were refused through `Workspace.load`
 * and half-restored through a checkout.
 */
export declare function checkFormatVersion(state: WorkspaceStateDict): void;
export declare function buildMountArgs(state: WorkspaceStateDict, overrides?: Record<string, BaseVFS | Mount>, cliOverrides?: CLIOverrides, userOverrides?: ReadonlySet<string>): MountArgs;
/**
 * Whether `buildMountArgs` restores a saved mount itself, into a fresh
 * RAMVFS, so no registry is asked about it: `disk` (its content
 * rides the state, and reopening the original root is exactly what a
 * restore must not do), and `ram` declared by its builtin name or
 * constructed in code. A `ram` mount whose ref points elsewhere is an
 * alias registered over RAMVFS, and rebuilds through that alias so
 * the subclass survives; Python's `_construct_vfs` calls `cls()` on
 * the class its ladder found for the same reason.
 */
export declare function restoresAsFreshRAM(entry: MountSnapshot): boolean;
/**
 * What a saved mount asks a registry to build: the name and config, or
 * null when the registry has nothing to say. The `vfs_ref` the
 * registry built the mount from when one was recorded (a registered name,
 * or a code reference, which is how a mount declared as
 * `./wiki.mjs:WikiVFS` comes back), else the VFS's `type`, the
 * one locator a VFS constructed in code leaves. The ref comes first
 * because `type` is the class's `name` and a subclass inherits it: an
 * alias registered over a builtin reports the builtin's type and rebuilt
 * as the builtin while the type was consulted first. A recorded ref this
 * registry cannot resolve is not a reason to fall back to that guess: the
 * answer is null, and `buildMountArgs` then asks for the mount live.
 */
export declare function savedVfsBuild(entry: MountSnapshot, known: (name: string) => boolean): {
    name: string;
    config: Record<string, unknown>;
} | null;
/**
 * The overrides `buildMountArgs` restores with: the caller's, plus every
 * mount the builder can rebuild from its saved state. A mount that asks
 * to be handed back live (`vfsStateRequiresOverride`) is never
 * built here, so the refusal `buildMountArgs` raises for it stands.
 */
export declare function withRebuiltMounts(state: WorkspaceStateDict, overrides: Record<string, BaseVFS | Mount>, build: (entry: MountSnapshot) => Promise<BaseVFS | null>): Promise<Record<string, BaseVFS | Mount>>;
/**
 * Restore post-construction state into an already-built Workspace.
 *
 * Every session table and the env template clear the target's
 * `preSession` gate first (`gateRestoredState`), before any mount,
 * session or template lands, so a refusal aborts the load with the
 * workspace as it was. A snapshot mount with no mount at that exact
 * prefix here is not restored and is reported. `replaceCache` drops
 * the live cache once the gate has passed, ahead of the mounts'
 * loadState, so the snapshot's entries are all that is left: a
 * checkout onto a running workspace asks for it, a workspace built for
 * the state has nothing to drop. It sits behind the gate because the
 * callers used to clear before calling, and a refused checkout then
 * still sent every cached read back to an origin that may have moved.
 * `builtForState` says the workspace was just built from this state,
 * under its profile table, and has run nothing: each session then lands
 * the narrowing and ask decisions its table recorded, as a stored record
 * hydrates, where a checkout onto a running workspace keeps its own
 * sessions' narrowing and decisions, and a table's mount caps only narrow
 * them. `shared` names the prefixes whose mount a copy shares with its
 * origin: their content is already there, so no state is loaded into
 * them.
 * The target's VFS.md and SKILL.md bindings are dropped, since a
 * snapshot never carries them. Mirrors Python `apply_state_dict`.
 */
export declare function applyStateDict(ws: WorkspaceLike, state: WorkspaceStateDict, options?: {
    replaceCache?: boolean;
    builtForState?: boolean;
    shared?: ReadonlySet<string>;
}): Promise<void>;
/** Live mounts a copy should share with its origin. Mirrors Python's `reusable_mounts`. */
export declare function reusableMounts(mounts: readonly MountEntry[], state: WorkspaceStateDict): Record<string, Mount>;
/**
 * Live-install overrides a same-process copy reinstalls from: every CLI's
 * spec and validated config, the way remote mounts share their live
 * mounts, so a directly installed spec and a redacted secret both survive
 * without a registry lookup.
 */
export declare function reusableClis(ws: WorkspaceLike): CLIOverrides;
//# sourceMappingURL=state.d.ts.map