SessionBundleProfile

Parameters and properties

• formatRequired
  string
  Persisted format name, used in bundles, transport keys and .outpost/conversations/<format> host paths.
• rootRequired
  { readonly variable?: string; readonly directory: string; }
  CLI home inside the sandbox: the value of the variable environment variable when set, otherwise directory under the agent home.
• sessionsRequired
  string
  Directory under the CLI home that contains the session directories.
• bucketsOptional
  boolean | undefined
  Whether sessions live in <sessions>/<bucket>/<id>. Capture requires exactly one match across buckets, and restoration refuses an id already present under another bucket.
• includeRequired
  RegExp
  Bundle-relative paths to capture; a directory is tested by its own path before its files. The g and y flags are rejected.
• excludeOptional
  RegExp | undefined
  Bundle-relative paths skipped even when include matches them, such as logs or lock files.
• requiredRequired
  readonly string[]
  Files that must be present, at least one; a session missing one is refused as incomplete.
• relocatedOptional
  readonly string[] | undefined
  Files passed as text to relocate during restoration; other files are restored byte for byte.
• validateOptional
  ((files: SessionBundleFiles, id: string) => string | undefined) | undefined
  Self-contained function that returns an error message when the bundled session uses unsupported metadata. It runs in the sandbox during capture and on the host when an existing bundle is located.
• bucketOptional
  ((cwd: string, helpers: SessionBundleHelpers) => string) | undefined
  Self-contained function that names the bucket restoration uses for the destination workspace; required when buckets is true.
• relocateOptional
  ((path: string, text: string, relocation: SessionBundleRelocation) => string) | undefined
  Self-contained function that rewrites one relocated file for the destination workspace and returns its new text; throwing aborts the restoration without replacing the existing session.

Signature

export interface SessionBundleProfile {
  /** Persisted format name, used in bundles, transport keys and host paths. */
  readonly format: string;
  /** CLI home: `$variable` when set, otherwise `directory` under the agent home. */
  readonly root: {
    readonly variable?: string;
    readonly directory: string;
  };
  /** Directory under the CLI home that holds sessions. */
  readonly sessions: string;
  /** Sessions are grouped in `<sessions>/<bucket>/<id>` instead of `<sessions>/<id>`. */
  readonly buckets?: boolean;
  /** Bundle-relative paths to capture; a directory is tested by its own path. */
  readonly include: RegExp;
  readonly exclude?: RegExp;
  /** Files whose absence makes the session unusable. */
  readonly required: readonly string[];
  /** Files passed to `relocate` as text during restoration. */
  readonly relocated?: readonly string[];
  /** Returns an error message when the bundled session is unsupported. */
  readonly validate?: (
    files: SessionBundleFiles,
    id: string,
  ) => string | undefined;
  /** Bucket that restoration uses for a workspace; required with `buckets`. */
  readonly bucket?: (cwd: string, helpers: SessionBundleHelpers) => string;
  /** Rewrites one relocated file for the restored workspace. */
  readonly relocate?: (
    path: string,
    text: string,
    relocation: SessionBundleRelocation,
  ) => string;
}

Related contracts

• SessionBundleFiles
• SessionBundleHelpers
• SessionBundleRelocation