HyperionWorkspace

HyperionWorkspace is the low-level SDK entry point. It provides checkpoint creation, reconciliation, rollback, promotion, VFS interception, diagnostics, recovery, and patch export.

Constructor

new HyperionWorkspace(rootOrConfig: string | HyperionConfig)

Accepts a workspace root path string or a full HyperionConfig object. Normalizes paths, rejects non-existent or non-directory roots, and initializes the session manager, environment profile, strategy selector, VFS interceptor, and lifecycle hooks.

// Simple
const workspace = new HyperionWorkspace(process.cwd());

// Full config
const workspace = new HyperionWorkspace({
  workspaceRoot: process.cwd(),
  strictIgnoredWrites: true,
  useHotBuffer: false,
});

Throws HyperionPathError if the workspace root does not exist or is not a directory.

Properties

`config: ResolvedHyperionConfig`

The resolved configuration with all defaults applied.

console.log(workspace.config.useHotBuffer); // true
console.log(workspace.config.hotBufferMaxFileBytes); // 262144

`root: string`

The normalized absolute workspace root path.

`strategy: StorageStrategyKind`

The selected storage strategy: "tmpfs", "posix-link", "ntfs-link", or "pure-manifest".

`isDisposed: boolean`

Whether dispose() has been called on this workspace.

`isFsInterceptorInstalled: boolean`

Whether the VFS interceptor is currently patching Node’s fs module.

Methods

`snapshot(options?)`

snapshot(options?: HyperionSnapshotOptions): Promise<CheckpointId>

Creates a checkpoint of the current workspace state. Captures file metadata for all tracked paths, skipping ignored directories. Runs capacity GC before allocating a new checkpoint namespace.

const checkpointId = await workspace.snapshot();

const childId = await workspace.snapshot({
  parentId: checkpointId,
  branchId: "feature/login",
  subagentId: "planner",
  agentId: "agent-planner",
  createdBy: "run-attempt",
});

HyperionSnapshotOptions supports optional lineage tags:

parentId: requires an active checkpoint in this workspace.
branchId: non-empty string (trimmed).
subagentId: non-empty string (trimmed).
agentId: non-empty string (trimmed).
createdBy: one of snapshot, fork, run-attempt, run-in-branch, rehydrate, unknown.

Throws HyperionCapacityError if maxConcurrentCheckpoints is exceeded and disposed checkpoints cannot be freed. Throws HyperionError if the workspace has been disposed.

`fork(parentCheckpointId, options?)`

fork(
  parentCheckpointId?: CheckpointId,
  options?: Omit<HyperionSnapshotOptions, "parentId">
): Promise<CheckpointId>

Creates a child checkpoint from an active parent checkpoint.

parentId is always set to parentCheckpointId.
If parentCheckpointId is omitted, Hyperion uses the most recent active checkpoint as parent; if none exists, fork() behaves like snapshot() with createdBy: "fork".
branchId defaults to parent branchId or parent checkpoint ID.
subagentId and agentId default to parent values.
Any provided options.branchId, options.subagentId, or options.agentId overrides parent defaults.

const parentId = await workspace.snapshot({
  branchId: "feature/login",
  subagentId: "planner",
});

const childId = await workspace.fork(parentId);
const reviewerId = await workspace.fork(parentId, { subagentId: "reviewer" });

`getCheckpointLineage(checkpointId)`

getCheckpointLineage(checkpointId: CheckpointId): HyperionCheckpointSummary[]

Returns checkpoint ancestry from oldest to newest, including the target checkpoint itself.

const lineage = workspace.getCheckpointLineage(checkpointId);
// [{ checkpointId, parentId?, branchId?, subagentId?, status, createdAt, source }]

`listCheckpointChildren(parentId, options?)`

listCheckpointChildren(
  parentId: CheckpointId,
  options?: { includeInactive?: boolean }
): HyperionCheckpointSummary[]

Lists direct child checkpoints of parentId sorted by createdAt. By default it returns only active and rolling-back checkpoints; pass includeInactive: true to include disposed and promoted checkpoints.

`listBranchHeads(filter?)`

listBranchHeads(filter?: HyperionCheckpointHeadFilter): HyperionCheckpointSummary[]

Returns latest checkpoint heads grouped by branchId, with optional filters for branchId, subagentId, agentId, and includeInactive.

`listSubagentHeads(filter?)`

listSubagentHeads(filter?: HyperionCheckpointHeadFilter): HyperionCheckpointSummary[]

Returns latest checkpoint heads grouped by subagentId, with optional filters for branchId, subagentId, agentId, and includeInactive.

`runInBranch(branchCheckpointId, callback)`

runInBranch<T>(
  branchCheckpointId: CheckpointId,
  callback: (context: HyperionBranchContext) => T | Promise<T>
): Promise<HyperionBranchRunResult<T>>

Runs branch-scoped callback logic against an existing checkpoint and reconciles that branch before returning.

const runResult = await workspace.runInBranch(branchCheckpointId, async ({ reconcile }) => {
  // mutate files
  return "ok";
});

console.log(runResult.reconcileResult.created);

`promoteBranch(branchCheckpointId, options?)`

promoteBranch(
  branchCheckpointId: CheckpointId,
  options?: HyperionPromoteBranchOptions
): Promise<HyperionBranchPromotionResult>

Promotes a branch checkpoint with deterministic merge planning.

Fast-path applies when dirty sets do not overlap.
Current conflict mode is reject-only (conflictMode: "reject").
Overlapping paths throw HyperionBranchConflictError.

`dropBranch(branchCheckpointId)`

dropBranch(branchCheckpointId: CheckpointId): Promise<void>

Drops a branch checkpoint using rollback semantics without broad reconciliation. Overlapping active sibling dirty paths are rejected with HyperionBranchConflictError.

`reconcile(checkpointId?)`

reconcile(checkpointId?: CheckpointId): Promise<ReconcileResult>

Detects filesystem changes outside the VFS interceptor — child processes, native binaries, shell redirections. Re-runs the hybrid state engine and diffs against the checkpoint baseline.

const result = await workspace.reconcile(checkpointId);
// result.created  → string[]
// result.modified → string[]
// result.deleted  → string[]
// result.renamed  → { from, to }[]

If no checkpointId is given, reconciles the most recent active checkpoint. Returns an empty result if no active checkpoint exists.

rollback() calls reconcile() automatically — this cannot be disabled.

`rollback(checkpointId)`

rollback(checkpointId: CheckpointId): Promise<void>

Restores the workspace to the checkpoint state. Calls reconcile() first, then restores modified/deleted files from backup records, deletes created files, and cleans ghost directories.

await workspace.rollback(checkpointId);

Throws HyperionIntegrityError if a backup record is missing for a modified or deleted file. Throws HyperionRollbackError if the checkpoint is unknown, disposed, promoted, or locked by another rollback.

`promote(checkpointId, options?)`

promote(
  checkpointId: CheckpointId,
  options?: HyperionPromoteOptions
): Promise<HyperionPromotionResult>

Accepts the current worktree state in place. Reconciles first, optionally exports a patch, marks the checkpoint promoted, and frees Hyperion-owned rollback storage.

const result = await workspace.promote(checkpointId);
// result.promotedAt, result.dirtyCount, result.storageCleaned

// With patch export
const result = await workspace.promote(checkpointId, { exportPatch: true });
console.log(result.patch);

Does not run Git. Promoted checkpoints are audit records only. If patch export fails, the checkpoint remains active and rollback-capable.

Throws HyperionRollbackError if the checkpoint is already locked, disposed, or promoted.

`dispose()`

dispose(): Promise<void>

Uninstalls the VFS interceptor, cleans active checkpoint storage namespaces, removes the current session directory, unregisters lifecycle hooks, and marks the workspace disposed.

await workspace.dispose();

Idempotent — calling multiple times is safe. After disposal, snapshot(), rollback(), and promote() will throw.

`track(pathOrPaths)`

track(pathOrPaths: string | string[]): void

Manually registers paths for tracking. Use this for integrations that cannot use VFS interception. Accepts a single path string or an array.

workspace.track("src/config.json");
workspace.track(["src/a.ts", "src/b.ts"]);

Exact ignored paths can be tracked — they are stored separately and treated as explicit exceptions during reconciliation.

Throws HyperionPathError if paths are empty, non-string, or outside the workspace.

`declareToolOutputs(contract)`

declareToolOutputs(contract: HyperionToolOutputContract): void

Declares exact generated or ignored output paths for tools like package managers, build systems, formatters, and codegen. Declared paths bypass strictIgnoredWrites blocking and are tracked by VFS interception and reconcile().

workspace.declareToolOutputs({
  toolName: "vite",
  checkpointId,
  outputs: [
    "node_modules/.cache/vite/deps_metadata.json",
    { path: "dist/manifest.json", optional: true },
  ],
});

Contracts are exact-path only. They do not enable recursive scans.

`getDiagnostics()`

getDiagnostics(): HyperionDiagnostics

Returns a read-only snapshot of strategy, storage, hot-buffer, Windows volume, checkpoint, and ignored-write diagnostics.

const diag = workspace.getDiagnostics();
console.log(diag.strategy);
console.log(diag.windowsVolume?.fileSystemName);
console.log(diag.checkpoints[0]?.storage?.hotBuffer?.memoryHits);

Does not run Git, shell commands, or filesystem scans. The returned object is a snapshot — mutations are not reflected back.

`recoverAttempts()`

recoverAttempts(): Promise<RecoverableAttempt[]>

Inspects durable checkpoint journals and returns summaries with canRehydrate status for each abandoned attempt.

const attempts = await workspace.recoverAttempts();
// [{ checkpointId, canRehydrate, nonRehydratableReason, ... }]

Returns an empty array if durableAttemptJournals is disabled.

`rehydrateAttempt(checkpointId)`

rehydrateAttempt(checkpointId: CheckpointId): Promise<CheckpointId>

Recreates active in-memory checkpoint state from durable journal and backup metadata. Returns the rehydrated checkpoint ID.

const checkpointId = await workspace.rehydrateAttempt("ckpt_abc123");
await workspace.rollback(checkpointId);

Rejects disposed or promoted attempts, corrupt journals, missing backup manifests, missing backup files, cross-workspace journals, and volatile Hot Dirty Buffer memory-only backups.

`exportPatch(checkpointId)`

exportPatch(checkpointId: CheckpointId): Promise<string>

Emits a Git-compatible unified diff for the active checkpoint’s dirty set. Reconciles first, then produces a text-only patch.

const patch = await workspace.exportPatch(checkpointId);

Throws for binary files, symlinks, and missing backup content. Does not run Git, commit, merge, push, or dispose the checkpoint.

Interceptor control

`installFsInterceptor()`

installFsInterceptor(): void

Installs VFS interception on Node’s fs module. Patches sync, callback, promise, and write-stream mutation APIs. Idempotent — calling it when already installed is safe.

workspace.installFsInterceptor();

`uninstallFsInterceptor()`

uninstallFsInterceptor(): void

Uninstalls VFS interception and restores the original fs functions. Idempotent — safe to call even if not installed.

workspace.uninstallFsInterceptor();

Default constants

DEFAULT_HOT_BUFFER_MAX_FILE_BYTES  = 262144   // 256 KiB
DEFAULT_HOT_BUFFER_MAX_TOTAL_BYTES  = 8388608   // 8 MiB
DEFAULT_HOT_BUFFER_MAX_FILES       = 1024
DEFAULT_MAX_CONCURRENT_CHECKPOINTS  = 64

HyperionWorkspace

Constructor

Properties

config: ResolvedHyperionConfig

root: string

strategy: StorageStrategyKind

isDisposed: boolean

isFsInterceptorInstalled: boolean

Methods

snapshot(options?)

fork(parentCheckpointId, options?)

getCheckpointLineage(checkpointId)

listCheckpointChildren(parentId, options?)

listBranchHeads(filter?)

listSubagentHeads(filter?)

runInBranch(branchCheckpointId, callback)

promoteBranch(branchCheckpointId, options?)

dropBranch(branchCheckpointId)

reconcile(checkpointId?)

rollback(checkpointId)

promote(checkpointId, options?)

dispose()

track(pathOrPaths)

declareToolOutputs(contract)

getDiagnostics()

recoverAttempts()

rehydrateAttempt(checkpointId)

exportPatch(checkpointId)