@deepagents/context 0.39.0 → 2.1.0

package/dist/lib/sandbox/file-events.d.ts

@@ -1,47 +1,33 @@
-import type { BufferEncoding, CpOptions, FileContent, FsStat, IFileSystem, MkdirOptions, RmOptions } from 'just-bash';
-interface ReadFileOptions {
-    encoding?: BufferEncoding | null;
-}
-interface WriteFileOptions {
-    encoding?: BufferEncoding;
-}
-interface DirentEntry {
-    name: string;
-    isFile: boolean;
-    isDirectory: boolean;
-    isSymbolicLink: boolean;
-}
+import type { DisposableSandbox } from './types.ts';
 export type FileEventOp = 'read' | 'write' | 'delete' | 'modify';
 export interface FileEvent {
     path: string;
     op: FileEventOp;
     timestamp: number;
 }
-export declare class ObservedFs implements IFileSystem {
-    #private;
-    readdirWithFileTypes?: (path: string) => Promise<DirentEntry[]>;
-    constructor(base: IFileSystem);
+export interface ObserveOptions {
+    destination: string;
+}
+export interface SandboxObserver {
+    sandbox: DisposableSandbox;
     drain(): FileEvent[];
-    readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
-    readFileBuffer(path: string): Promise<Uint8Array>;
-    writeFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
-    appendFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
-    rm(path: string, options?: RmOptions): Promise<void>;
-    cp(src: string, dest: string, options?: CpOptions): Promise<void>;
-    mv(src: string, dest: string): Promise<void>;
-    symlink(target: string, linkPath: string): Promise<void>;
-    link(existingPath: string, newPath: string): Promise<void>;
-    mkdir(path: string, options?: MkdirOptions): Promise<void>;
-    exists(path: string): Promise<boolean>;
-    stat(path: string): Promise<FsStat>;
-    lstat(path: string): Promise<FsStat>;
-    readdir(path: string): Promise<string[]>;
-    readlink(path: string): Promise<string>;
-    realpath(path: string): Promise<string>;
-    chmod(path: string, mode: number): Promise<void>;
-    utimes(path: string, atime: Date, mtime: Date): Promise<void>;
-    resolvePath(base: string, path: string): string;
-    getAllPaths(): string[];
 }
-export {};
+export declare class SnapshotFailedError extends Error {
+    readonly stderr: string;
+    constructor(message: string, stderr: string);
+}
+/**
+ * Wraps a `Sandbox` with file-event observation rooted at `destination`.
+ *
+ * - `executeCommand` and `writeFiles` are bracketed by `find -print0` +
+ *   `sha256sum` snapshots; hash diff produces write/modify/delete events.
+ * - `readFile` records a `read` event on success.
+ * - If `destination` does not exist in the sandbox at snapshot time, the
+ *   snapshot is treated as empty (graceful — supports observation rooted at
+ *   paths that the sandbox will create later). Snapshot command failures
+ *   (e.g. permission denied, missing `find`) throw `SnapshotFailedError`.
+ * - Single-flight by convention. Concurrent `executeCommand` calls are not
+ *   serialized internally and will produce interleaved diffs.
+ */
+export declare function observeSandboxFileEvents(sandbox: DisposableSandbox, options: ObserveOptions): SandboxObserver;
 //# sourceMappingURL=file-events.d.ts.map

package/dist/lib/sandbox/file-events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-events.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/file-events.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file-events.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/file-events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,WAAW,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,KAAK,IAAI,SAAS,EAAE,CAAC;CACtB;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAK5C;AAoDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,cAAc,GACtB,eAAe,CAiDjB"}

package/dist/lib/sandbox/index.d.ts

@@ -1,19 +1,15 @@
+export * from './abort.ts';
 export * from './agent-os-sandbox.ts';
-export * from './ast-utils.ts';
 export * from './bash-exception.ts';
 export * from './bash-meta.ts';
 export * from './bash-tool.ts';
-export * from './extension.ts';
 export * from './file-events.ts';
 export * from './binary-bridges.ts';
 export * from './container-tool.ts';
 export * from './docker-sandbox.ts';
-export * from './routing-sandbox.ts';
-export * from './openapi/extension.ts';
-export * from './openapi/format.ts';
-export * from './openapi/schema.ts';
-export * from './openapi/validate.ts';
+export * from './installers/index.ts';
 export * from './subcommand.ts';
 export * from './types.ts';
 export * from './upload-skills.ts';
+export * from './virtual-sandbox.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/sandbox/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC"}

package/dist/lib/sandbox/installers/github-release.d.ts

@@ -0,0 +1,46 @@
+import { Installer, type InstallerContext } from './installer.ts';
+export interface GithubReleaseOptions {
+    /** GitHub owner (user or org). */
+    owner: string;
+    /** Repository name. */
+    repo: string;
+    /** Release tag (e.g. `'v0.15.1'`). */
+    version: string;
+    /** Final executable name installed under `/usr/local/bin`. */
+    name: string;
+    /**
+     * Build the asset filename for a given container architecture
+     * (the result of `uname -m`, e.g. `'x86_64'`, `'aarch64'`).
+     *
+     * @example
+     * ```ts
+     * asset: (arch) => `presenterm-0.15.1-${arch}-unknown-linux-musl.tar.gz`
+     * ```
+     */
+    asset: (arch: string) => string;
+    /** Path inside an extracted archive, when it differs from `name`. */
+    binaryPath?: string;
+}
+export declare class GithubReleaseInstaller extends Installer {
+    readonly kind: string;
+    readonly options: GithubReleaseOptions;
+    constructor(options: GithubReleaseOptions);
+    install(ctx: InstallerContext): Promise<void>;
+}
+/**
+ * Install a binary from a GitHub release. Resolves arch-specific assets
+ * via the `asset(arch)` callback.
+ *
+ * @example
+ * ```ts
+ * githubRelease({
+ *   owner: 'mfontanini',
+ *   repo: 'presenterm',
+ *   version: 'v0.15.1',
+ *   name: 'presenterm',
+ *   asset: (arch) => `presenterm-0.15.1-${arch}-unknown-linux-musl.tar.gz`,
+ * });
+ * ```
+ */
+export declare function githubRelease(options: GithubReleaseOptions): GithubReleaseInstaller;
+//# sourceMappingURL=github-release.d.ts.map

package/dist/lib/sandbox/installers/github-release.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-release.d.ts","sourceRoot":"","sources":["../../../../src/lib/sandbox/installers/github-release.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGlE,MAAM,WAAW,oBAAoB;IACnC,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAChC,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,sBAAuB,SAAQ,SAAS;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;gBAE3B,OAAO,EAAE,oBAAoB;IAMnC,OAAO,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAepD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,oBAAoB,GAC5B,sBAAsB,CAExB"}

package/dist/lib/sandbox/installers/index.d.ts

@@ -0,0 +1,7 @@
+export { Installer, type InstallerContext, type PackageManager, createInstallerContext, isDebianBased, shellQuote, } from './installer.ts';
+export { PackageInstaller, pkg } from './package-manager.ts';
+export { type ArchitectureUrls, type UrlBinaryOptions, UrlBinaryInstaller, urlBinary, } from './url-binary.ts';
+export { type NpmInstallerOptions, NpmInstaller, npm } from './npm.ts';
+export { type PipInstallerOptions, PipInstaller, pip } from './pip.ts';
+export { type GithubReleaseOptions, GithubReleaseInstaller, githubRelease, } from './github-release.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/sandbox/installers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/sandbox/installers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,sBAAsB,EACtB,aAAa,EACb,UAAU,GACX,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,kBAAkB,EAClB,SAAS,GACV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,mBAAmB,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AACvE,OAAO,EAAE,KAAK,mBAAmB,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AACvE,OAAO,EACL,KAAK,oBAAoB,EACzB,sBAAsB,EACtB,aAAa,GACd,MAAM,qBAAqB,CAAC"}

package/dist/lib/sandbox/installers/installer.d.ts

@@ -0,0 +1,44 @@
+import { type CommandResult } from 'bash-tool';
+export type PackageManager = 'apk' | 'apt-get';
+/**
+ * Shared state passed to every installer's `install()` call.
+ *
+ * The context owns one container's installation lifecycle:
+ * - memoised architecture (one `uname -m` per sandbox)
+ * - resolved package manager
+ * - `apt-get update` runs at most once
+ * - idempotent `ensureTool` (cache keyed on install name)
+ */
+export interface InstallerContext {
+    readonly containerId: string;
+    readonly image: string;
+    readonly packageManager: PackageManager;
+    arch(): Promise<string>;
+    exec(command: string): Promise<CommandResult>;
+    /**
+     * Install OS packages via the container's package manager.
+     * `apt-get update` runs at most once per container, then subsequent calls
+     * issue install only.
+     */
+    installPackages(packages: string[]): Promise<void>;
+    /**
+     * Ensure a tool is callable.
+     *
+     * @param checkName Binary name probed via `which` (e.g. `'node'`).
+     * @param installName Package to install when missing (e.g. `'nodejs'`).
+     *   Defaults to `checkName` when binary name == package name.
+     */
+    ensureTool(checkName: string, installName?: string): Promise<void>;
+}
+export declare abstract class Installer {
+    abstract readonly kind: string;
+    abstract install(ctx: InstallerContext): Promise<void>;
+}
+export declare function isDebianBased(image: string): boolean;
+/**
+ * POSIX shell single-quote escape: wrap in `'...'`, replace any embedded
+ * `'` with `'\''`. Safe for arbitrary content inside `sh -c`.
+ */
+export declare function shellQuote(s: string): string;
+export declare function createInstallerContext(containerId: string, image: string): InstallerContext;
+//# sourceMappingURL=installer.d.ts.map

package/dist/lib/sandbox/installers/installer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../../../src/lib/sandbox/installers/installer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAQ/C,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,SAAS,CAAC;AAE/C;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC9C;;;;OAIG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD;;;;;;OAMG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED,8BAAsB,SAAS;IAC7B,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CACvD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKpD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,GACZ,gBAAgB,CAyGlB"}

package/dist/lib/sandbox/installers/npm.d.ts

@@ -0,0 +1,32 @@
+import { Installer, type InstallerContext } from './installer.ts';
+export interface NpmInstallerOptions {
+    /**
+     * Auto-install `nodejs` + `npm` via the container's package manager when
+     * they're missing. Defaults to `false` — fail loudly with `MissingRuntimeError`.
+     */
+    ensureRuntime?: boolean;
+    /** Optional version specifier (e.g. `'5.4.5'`). */
+    version?: string;
+}
+export declare class NpmInstaller extends Installer {
+    readonly kind: string;
+    readonly packageName: string;
+    readonly options: NpmInstallerOptions;
+    constructor(packageName: string, options?: NpmInstallerOptions);
+    install(ctx: InstallerContext): Promise<void>;
+}
+/**
+ * Install a globally-available CLI from the npm registry.
+ *
+ * Default: fails loudly if `node`/`npm` are missing. Pass
+ * `{ ensureRuntime: true }` to auto-install them.
+ *
+ * @example
+ * ```ts
+ * npm('prettier');                              // requires node+npm preinstalled
+ * npm('prettier', { ensureRuntime: true });     // auto-installs node+npm
+ * npm('typescript', { version: '5.4.5' });      // pinned version
+ * ```
+ */
+export declare function npm(packageName: string, options?: NpmInstallerOptions): NpmInstaller;
+//# sourceMappingURL=npm.d.ts.map

package/dist/lib/sandbox/installers/npm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"npm.d.ts","sourceRoot":"","sources":["../../../../src/lib/sandbox/installers/npm.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElE,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD,qBAAa,YAAa,SAAQ,SAAS;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;gBAE1B,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB;IAO5D,OAAO,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAiBpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,GAAG,CACjB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,YAAY,CAEd"}

package/dist/lib/sandbox/installers/package-manager.d.ts

@@ -0,0 +1,19 @@
+import { Installer, type InstallerContext } from './installer.ts';
+export declare class PackageInstaller extends Installer {
+    readonly kind: string;
+    readonly packages: readonly string[];
+    constructor(packages: readonly string[]);
+    install(ctx: InstallerContext): Promise<void>;
+}
+/**
+ * Install OS packages via the container's native package manager.
+ *
+ * Auto-detects `apk` (Alpine) vs `apt-get` (Debian/Ubuntu/Node/Python images).
+ *
+ * @example
+ * ```ts
+ * createDockerSandbox({ installers: [pkg(['curl', 'jq'])] });
+ * ```
+ */
+export declare function pkg(packages: readonly string[]): PackageInstaller;
+//# sourceMappingURL=package-manager.d.ts.map

package/dist/lib/sandbox/installers/package-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-manager.d.ts","sourceRoot":"","sources":["../../../../src/lib/sandbox/installers/package-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElE,qBAAa,gBAAiB,SAAQ,SAAS;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;gBAEzB,QAAQ,EAAE,SAAS,MAAM,EAAE;IAOjC,OAAO,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAIpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,GAAG,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,CAEjE"}

package/dist/lib/sandbox/installers/pip.d.ts

@@ -0,0 +1,37 @@
+import { Installer, type InstallerContext } from './installer.ts';
+export interface PipInstallerOptions {
+    /**
+     * Auto-install `python3` + pip when missing. Defaults to `false` — fail
+     * loudly with `MissingRuntimeError`.
+     */
+    ensureRuntime?: boolean;
+    /** Version specifier (e.g. `'2.31.0'` or `'>=2.0,<3'`). */
+    version?: string;
+    /**
+     * Pass `--break-system-packages` for PEP 668-protected images
+     * (recent Debian/Ubuntu). Default `true` since this runs in an ephemeral
+     * container where the protection adds no value.
+     */
+    breakSystemPackages?: boolean;
+}
+export declare class PipInstaller extends Installer {
+    readonly kind: string;
+    readonly packageName: string;
+    readonly options: PipInstallerOptions;
+    constructor(packageName: string, options?: PipInstallerOptions);
+    install(ctx: InstallerContext): Promise<void>;
+}
+/**
+ * Install a Python package via `pip3`.
+ *
+ * Default: fails loudly if `python3`/`pip3` are missing. Pass
+ * `{ ensureRuntime: true }` to auto-install them.
+ *
+ * @example
+ * ```ts
+ * pip('requests');
+ * pip('requests', { version: '2.31.0', ensureRuntime: true });
+ * ```
+ */
+export declare function pip(packageName: string, options?: PipInstallerOptions): PipInstaller;
+//# sourceMappingURL=pip.d.ts.map

package/dist/lib/sandbox/installers/pip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pip.d.ts","sourceRoot":"","sources":["../../../../src/lib/sandbox/installers/pip.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElE,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAID,qBAAa,YAAa,SAAQ,SAAS;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;gBAE1B,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB;IAO5D,OAAO,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAsBpD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,GAAG,CACjB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,YAAY,CAEd"}

package/dist/lib/sandbox/installers/url-binary.d.ts

@@ -0,0 +1,41 @@
+import { Installer, type InstallerContext } from './installer.ts';
+export interface ArchitectureUrls {
+    x86_64?: string;
+    aarch64?: string;
+    armv7l?: string;
+}
+export interface UrlBinaryOptions {
+    /** Final executable name installed under `/usr/local/bin`. */
+    name: string;
+    /** Single URL or arch-keyed map (selected via container's `uname -m`). */
+    url: string | ArchitectureUrls;
+    /** Path inside an extracted archive, when it differs from `name`. */
+    binaryPath?: string;
+}
+export declare class UrlBinaryInstaller extends Installer {
+    readonly kind: string;
+    readonly options: UrlBinaryOptions;
+    constructor(options: UrlBinaryOptions);
+    install(ctx: InstallerContext): Promise<void>;
+}
+/**
+ * Install a pre-built binary from a URL into `/usr/local/bin`.
+ *
+ * Supports raw binaries and `.tar.gz`/`.tgz` archives. Picks the correct
+ * URL per container architecture when a map is provided. Auto-installs `curl`
+ * if needed.
+ *
+ * @example
+ * ```ts
+ * urlBinary({
+ *   name: 'presenterm',
+ *   url: {
+ *     x86_64: 'https://.../presenterm-x86_64.tar.gz',
+ *     aarch64: 'https://.../presenterm-aarch64.tar.gz',
+ *   },
+ * });
+ * ```
+ */
+export declare function urlBinary(options: UrlBinaryOptions): UrlBinaryInstaller;
+export declare function downloadAndInstall(ctx: InstallerContext, name: string, url: string, binaryPath?: string, source?: 'url' | 'github-release'): Promise<void>;
+//# sourceMappingURL=url-binary.d.ts.map

package/dist/lib/sandbox/installers/url-binary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-binary.d.ts","sourceRoot":"","sources":["../../../../src/lib/sandbox/installers/url-binary.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAc,MAAM,gBAAgB,CAAC;AAE9E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAC/B,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,kBAAmB,SAAQ,SAAS;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;gBAEvB,OAAO,EAAE,gBAAgB;IAM/B,OAAO,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CASpD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,kBAAkB,CAEvE;AAqBD,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,UAAU,CAAC,EAAE,MAAM,EACnB,MAAM,GAAE,KAAK,GAAG,gBAAwB,GACvC,OAAO,CAAC,IAAI,CAAC,CAkBf"}

package/dist/lib/sandbox/subcommand.d.ts

@@ -1,5 +1,4 @@
-import type { CommandResult } from 'bash-tool';
-import type { ExtensionCommand, ExtensionCommandContext } from './extension.ts';
+import { type Command, type CommandContext, type ExecResult } from 'just-bash';
 /**
  * Describes one subcommand inside a subcommand group (e.g. `sql run`,
  * `sql validate`). Each subcommand has usage/description strings used to
@@ -14,21 +13,23 @@ export interface SubcommandDefinition {
      * the shell parser sees it. Return `null` to leave the raw args unchanged.
      */
     repair?: (rawArgs: string) => string | null;
-    handler: (args: string[], ctx: ExtensionCommandContext) => CommandResult | Promise<CommandResult>;
+    handler: (args: string[], ctx: CommandContext) => ExecResult | Promise<ExecResult>;
 }
 /**
- * Creates an {@link ExtensionCommand} that dispatches to one of several
- * subcommand handlers based on the first positional arg. Unknown or missing
- * subcommands print an auto-generated usage message to stderr with exit
- * code 1.
+ * Builds a `Command` for just-bash that dispatches to one of several
+ * subcommand handlers based on the first positional arg. Plug it into a
+ * `Bash` instance via `customCommands` (or feed it to any sandbox that
+ * accepts just-bash custom commands). Unknown or missing subcommands
+ * print an auto-generated usage message to stderr with exit code 1.
  *
  * @example
  * const sqlCommand = defineSubcommandGroup('sql', {
  *   run:      { usage: 'run "SELECT ..."',      description: 'Execute query',  handler: ... },
  *   validate: { usage: 'validate "SELECT ..."', description: 'Validate only', handler: ... },
  * });
+ * new Bash({ fs, customCommands: [sqlCommand] });
  */
-export declare function defineSubcommandGroup(name: string, subcommands: Record<string, SubcommandDefinition>): ExtensionCommand;
+export declare function defineSubcommandGroup(name: string, subcommands: Record<string, SubcommandDefinition>): Command;
 /**
  * Strips a single layer of matching outer `"` or `'` quotes from a string,
  * trimming surrounding whitespace. If the input is not wrapped in a matching
@@ -36,9 +37,8 @@ export declare function defineSubcommandGroup(name: string, subcommands: Record<
  */
 export declare function stripQuoteArtifacts(raw: string): string;
 /**
- * Pre-parse repair for a subcommand's raw arg string. Fires when the
- * surrounding command fails to parse (via `buildSubcommandRepair`). Strips
- * any leading/trailing quote, escapes inner single quotes with the POSIX
+ * Pre-parse repair for a subcommand's raw arg string. Strips any
+ * leading/trailing quote, escapes inner single quotes with the POSIX
  * `'\''` idiom, and wraps the result in single quotes so the shell parser
  * will treat the payload as an opaque literal on the next pass.
  *

package/dist/lib/sandbox/subcommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subcommand.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/subcommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAEhF;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC5C,OAAO,EAAE,CACP,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,uBAAuB,KACzB,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC7C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,GAChD,gBAAgB,CAsBlB;AAMD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAUvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK9D;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,IAO1B,KAAK,MAAM,KAAG,MAAM,CA2B5C"}
+{"version":3,"file":"subcommand.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/subcommand.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,UAAU,EAGhB,MAAM,WAAW,CAAC;AAEnB;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC5C,OAAO,EAAE,CACP,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,cAAc,KAChB,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,GAChD,OAAO,CAmBT;AAMD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAUvD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK9D;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,IAO1B,KAAK,MAAM,KAAG,MAAM,CA2B5C"}

package/dist/lib/sandbox/types.d.ts

@@ -1,7 +1,50 @@
 import type { Tool } from 'ai';
-import type { BashToolkit, CommandResult } from 'bash-tool';
+import type { BashToolkit, CommandResult, Sandbox as UpstreamSandbox } from 'bash-tool';
 import type { SkillPathMapping } from '../skills/types.ts';
 import type { FileEvent } from './file-events.ts';
+/**
+ * Options accepted by `DisposableSandbox.executeCommand`. Currently only
+ * `signal` (cooperative cancellation); shaped as an object so we can add
+ * more without breaking backends.
+ */
+export interface ExecuteCommandOptions {
+    signal?: AbortSignal;
+}
+export interface SpawnOptions {
+    signal?: AbortSignal;
+    env?: Record<string, string>;
+    cwd?: string;
+}
+export interface ExitInfo {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    /** Convenience for `code === 0`. */
+    success: boolean;
+}
+export interface SandboxProcess {
+    readonly stdout: ReadableStream<Uint8Array>;
+    readonly stderr: ReadableStream<Uint8Array>;
+    readonly exit: Promise<ExitInfo>;
+}
+/**
+ * Sandbox contract used throughout this package: upstream's three-method
+ * shape plus a lifecycle hook, with `executeCommand` widened to accept
+ * optional cancellation. Every backend (virtual, docker, agent-os)
+ * implements this so callers can dispose uniformly. Backends that honor
+ * `options.signal` forward it to their runner; others ignore. Pure
+ * backends with no external resources (e.g. virtual-sandbox) supply a
+ * no-op `dispose()`.
+ *
+ * `spawn` is optional: only backends that can honestly expose unbuffered
+ * stdio (e.g. docker-sandbox) implement it. Callers feature-detect with
+ * `if (!sandbox.spawn) ...` — no silent fallback that aggregates output
+ * and flushes on completion.
+ */
+export interface DisposableSandbox extends Omit<UpstreamSandbox, 'executeCommand'> {
+    executeCommand(command: string, options?: ExecuteCommandOptions): Promise<CommandResult>;
+    spawn?(command: string, options?: SpawnOptions): SandboxProcess;
+    dispose(): Promise<void>;
+}
 /**
  * Declarative skill upload: a host directory whose contents are copied into
  * the sandbox at startup. The factory also parses each skill's frontmatter
@@ -29,18 +72,20 @@ export type WrappedBashTool = Tool<BashToolInput, CommandResult>;
  * the `skills()` fragment. The `bash` tool is widened to require a
  * `reasoning` input on every call.
  */
-export interface AgentSandbox extends Omit<BashToolkit, 'bash' | 'tools'> {
+export interface AgentSandbox extends Omit<BashToolkit, 'bash' | 'tools' | 'sandbox'> {
     /** Discovered skills — empty array if none were configured. */
     skills: SkillPathMapping[];
     bash: WrappedBashTool;
     tools: Omit<BashToolkit['tools'], 'bash'> & {
         bash: WrappedBashTool;
     };
+    sandbox: DisposableSandbox;
     /**
-     * Drain and return file events observed since the last call. Attached by
-     * callers who composed an `ObservedFs` into their backend; omitted
-     * otherwise. The chat pipeline reads this via optional chaining.
+     * Drain and return file events observed since the last `drain()`. The
+     * observation root is the `destination` passed to `createBashTool`; every
+     * `executeCommand` / `writeFiles` call is bracketed by a snapshot, and
+     * `readFile` records a `read` event.
      */
-    drainFileEvents?(): FileEvent[];
+    drainFileEvents(): FileEvent[];
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/lib/sandbox/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IACvE,+DAA+D;IAC/D,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,GAAG;QAAE,IAAI,EAAE,eAAe,CAAA;KAAE,CAAC;IACtE;;;;OAIG;IACH,eAAe,CAAC,IAAI,SAAS,EAAE,CAAC;CACjC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EACb,OAAO,IAAI,eAAe,EAC3B,MAAM,WAAW,CAAC;AAEnB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IAC9B,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAC7C,eAAe,EACf,gBAAgB,CACjB;IACC,cAAc,CACZ,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1B,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,cAAc,CAAC;IAChE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,IAAI,CACxC,WAAW,EACX,MAAM,GAAG,OAAO,GAAG,SAAS,CAC7B;IACC,+DAA+D;IAC/D,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,GAAG;QAAE,IAAI,EAAE,eAAe,CAAA;KAAE,CAAC;IACtE,OAAO,EAAE,iBAAiB,CAAC;IAC3B;;;;;OAKG;IACH,eAAe,IAAI,SAAS,EAAE,CAAC;CAChC"}

package/dist/lib/sandbox/upload-skills.d.ts

@@ -1,6 +1,12 @@
 import type { Sandbox } from 'bash-tool';
 import type { SkillPathMapping } from '../skills/types.ts';
 import type { SkillUploadInput } from './types.ts';
+/**
+ * Discover skill metadata and map each host SKILL.md path to its sandbox path
+ * without uploading any files. Later inputs override earlier ones when the same
+ * skill name appears twice.
+ */
+export declare function discoverSkillMappings(inputs: SkillUploadInput[]): SkillPathMapping[];
 /**
  * Discover skills under each host directory, write all non-dotfile, non-symlink
  * files into the sandbox under the mapped path, and return the discovered

package/dist/lib/sandbox/upload-skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upload-skills.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/upload-skills.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAenD;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,gBAAgB,EAAE,GACzB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAqC7B"}
+{"version":3,"file":"upload-skills.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/upload-skills.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAenD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,gBAAgB,EAAE,GACzB,gBAAgB,EAAE,CAwBpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,gBAAgB,EAAE,GACzB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAqB7B"}

package/dist/lib/sandbox/virtual-sandbox.d.ts

@@ -0,0 +1,10 @@
+import { type CustomCommand, type IFileSystem } from 'just-bash';
+import type { DisposableSandbox } from './types.ts';
+export interface CreateVirtualSandboxOptions {
+    fs: IFileSystem;
+    cwd?: string;
+    env?: Record<string, string>;
+    customCommands?: CustomCommand[];
+}
+export declare function createVirtualSandbox(options: CreateVirtualSandboxOptions): Promise<DisposableSandbox>;
+//# sourceMappingURL=virtual-sandbox.d.ts.map

package/dist/lib/sandbox/virtual-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-sandbox.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/virtual-sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAEvE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,WAAW,2BAA2B;IAC1C,EAAE,EAAE,WAAW,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;CAClC;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,iBAAiB,CAAC,CAsC5B"}

package/dist/lib/save/reminder-target-handler.d.ts

@@ -0,0 +1,36 @@
+import type { UIMessage } from 'ai';
+import type { ChainSummary } from '../chain-summary.ts';
+import type { ContextFragment } from '../fragments.ts';
+import type { ConditionalReminder, ReminderResolution, ReminderTarget, WhenContext } from '../fragments/message/user.ts';
+export type BaseWhenCtx = Omit<WhenContext, 'content' | 'currentMessage' | 'lastAssistantMessage' | 'lastAssistantMessages'>;
+export interface PreparedCarrier {
+    message: UIMessage;
+    fragmentIndex: number;
+}
+export interface ReminderHandlerInput {
+    pending: ContextFragment[];
+    base: BaseWhenCtx;
+    chain: ChainSummary;
+    sharedUserMessage?: UIMessage & {
+        role: 'user';
+    };
+}
+export interface ReminderApplyInput {
+    pending: ContextFragment[];
+    carrier: PreparedCarrier;
+    fired: ConditionalReminder[];
+    resolved: ReminderResolution[];
+}
+export interface PreparedHandler {
+    whenCtx: WhenContext;
+    carrier: PreparedCarrier;
+    sharedUserMessage?: UIMessage & {
+        role: 'user';
+    };
+}
+export interface ReminderTargetHandler {
+    readonly target: ReminderTarget;
+    prepare(input: ReminderHandlerInput): PreparedHandler | null;
+    apply(input: ReminderApplyInput): void;
+}
+//# sourceMappingURL=reminder-target-handler.d.ts.map

package/dist/lib/save/reminder-target-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reminder-target-handler.d.ts","sourceRoot":"","sources":["../../../src/lib/save/reminder-target-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAEpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,WAAW,EACZ,MAAM,8BAA8B,CAAC;AAEtC,MAAM,MAAM,WAAW,GAAG,IAAI,CAC5B,WAAW,EACT,SAAS,GACT,gBAAgB,GAChB,sBAAsB,GACtB,uBAAuB,CAC1B,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,SAAS,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,YAAY,CAAC;IACpB,iBAAiB,CAAC,EAAE,SAAS,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,OAAO,EAAE,eAAe,CAAC;IACzB,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,QAAQ,EAAE,kBAAkB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,WAAW,CAAC;IACrB,OAAO,EAAE,eAAe,CAAC;IACzB,iBAAiB,CAAC,EAAE,SAAS,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,OAAO,CAAC,KAAK,EAAE,oBAAoB,GAAG,eAAe,GAAG,IAAI,CAAC;IAC7D,KAAK,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACxC"}

package/dist/lib/save/save-pipeline.d.ts

@@ -0,0 +1,28 @@
+import type { ChainSummary } from '../chain-summary.ts';
+import type { ContextFragment } from '../fragments.ts';
+import type { ContextStore } from '../store/store.ts';
+import type { BaseWhenCtx, ReminderTargetHandler } from './reminder-target-handler.ts';
+export interface SavePipelineEngine {
+    readonly store: ContextStore;
+    readonly chatId: string;
+    readonly branchName: string;
+    getActiveBranch(): {
+        id: string;
+        headMessageId: string | null;
+    };
+    commitHead(headMessageId: string): Promise<void>;
+    rewindForUpdate(parentId: string): Promise<void>;
+    getChainSummary(): Promise<ChainSummary>;
+    buildBaseWhenCtx(chain: ChainSummary): BaseWhenCtx;
+}
+export interface SaveResult {
+    headMessageId: string | undefined;
+}
+export declare class SavePipeline {
+    #private;
+    constructor(engine: SavePipelineEngine, pending: ContextFragment[], fragments: ContextFragment[]);
+    applyUpdateBranching(shouldBranch: boolean): Promise<this>;
+    evaluateReminders(handlers: ReminderTargetHandler[]): Promise<this>;
+    persist(): Promise<SaveResult>;
+}
+//# sourceMappingURL=save-pipeline.d.ts.map