@deepagents/context 0.10.2 → 0.12.0

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

@@ -0,0 +1,471 @@
+import { type CommandResult, type Sandbox } from 'bash-tool';
+export type { CommandResult as ExecResult, Sandbox } from 'bash-tool';
+/**
+ * Base error for all Docker sandbox operations.
+ */
+export declare class DockerSandboxError extends Error {
+    readonly containerId?: string;
+    constructor(message: string, containerId?: string);
+}
+/**
+ * Thrown when Docker daemon is not available.
+ */
+export declare class DockerNotAvailableError extends DockerSandboxError {
+    constructor();
+}
+/**
+ * Thrown when container creation fails.
+ */
+export declare class ContainerCreationError extends DockerSandboxError {
+    readonly image: string;
+    cause?: Error;
+    constructor(message: string, image: string, cause?: Error);
+}
+/**
+ * Thrown when package installation fails.
+ */
+export declare class PackageInstallError extends DockerSandboxError {
+    readonly packages: string[];
+    readonly image: string;
+    readonly packageManager: 'apk' | 'apt-get';
+    readonly stderr: string;
+    constructor(packages: string[], image: string, packageManager: 'apk' | 'apt-get', stderr: string, containerId?: string);
+}
+/**
+ * Thrown when a binary installation from URL fails.
+ */
+export declare class BinaryInstallError extends DockerSandboxError {
+    readonly binaryName: string;
+    readonly url: string;
+    readonly reason: string;
+    constructor(binaryName: string, url: string, reason: string, containerId?: string);
+}
+/**
+ * Thrown when a mount path doesn't exist on the host.
+ */
+export declare class MountPathError extends DockerSandboxError {
+    readonly hostPath: string;
+    readonly containerPath: string;
+    constructor(hostPath: string, containerPath: string);
+}
+/**
+ * Thrown when Dockerfile build fails.
+ */
+export declare class DockerfileBuildError extends DockerSandboxError {
+    readonly stderr: string;
+    constructor(stderr: string);
+}
+/**
+ * Thrown when docker compose up fails.
+ */
+export declare class ComposeStartError extends DockerSandboxError {
+    readonly composeFile: string;
+    readonly stderr: string;
+    constructor(composeFile: string, stderr: string);
+}
+/**
+ * Configuration for mounting a host directory into the container.
+ */
+export interface DockerMount {
+    /** Absolute path on the host machine */
+    hostPath: string;
+    /** Path inside the container */
+    containerPath: string;
+    /** Whether the mount is read-only (default: true) */
+    readOnly?: boolean;
+}
+/**
+ * Resource limits for the container.
+ */
+export interface DockerResources {
+    /** Memory limit (e.g., '1g', '512m') */
+    memory?: string;
+    /** CPU limit (number of CPUs) */
+    cpus?: number;
+}
+/**
+ * Architecture-specific URL mapping for binary downloads.
+ * Maps container architecture (from `uname -m`) to download URLs.
+ */
+export interface ArchitectureUrls {
+    /** URL for x86_64 architecture (amd64) */
+    x86_64?: string;
+    /** URL for ARM64 architecture (aarch64) */
+    aarch64?: string;
+    /** URL for ARMv7 architecture */
+    armv7l?: string;
+}
+/**
+ * Configuration for installing a binary from a URL.
+ *
+ * Binaries are downloaded, extracted (if tar.gz), and installed to /usr/local/bin.
+ */
+export interface BinaryInstall {
+    /** Name of the binary (used for the final executable name) */
+    name: string;
+    /**
+     * URL or architecture-specific URLs.
+     * - If a string, used for all architectures
+     * - If ArchitectureUrls, selects based on container architecture
+     */
+    url: string | ArchitectureUrls;
+    /**
+     * Optional: The binary filename inside the archive if different from `name`.
+     * Useful when the archive contains versioned binaries like "presenterm-0.15.1".
+     */
+    binaryPath?: string;
+}
+/**
+ * Options for RuntimeStrategy - installs packages/binaries at container runtime.
+ */
+export interface RuntimeSandboxOptions {
+    /** Docker image to use (default: 'alpine:latest') */
+    image?: string;
+    /** Packages to install in the container via package manager (apk/apt) */
+    packages?: string[];
+    /** Binaries to install from URLs (for tools not in package managers) */
+    binaries?: BinaryInstall[];
+    /** Directories to mount from host */
+    mounts?: DockerMount[];
+    /** Resource limits */
+    resources?: DockerResources;
+}
+/**
+ * Options for DockerfileStrategy - builds custom image from Dockerfile.
+ */
+export interface DockerfileSandboxOptions {
+    /** Dockerfile content (if contains newlines) or path to Dockerfile */
+    dockerfile: string;
+    /** Build context directory (default: '.') */
+    context?: string;
+    /** Directories to mount from host */
+    mounts?: DockerMount[];
+    /** Resource limits */
+    resources?: DockerResources;
+}
+/**
+ * Options for ComposeStrategy - manages multi-container environments.
+ */
+export interface ComposeSandboxOptions {
+    /** Path to docker-compose.yml file */
+    compose: string;
+    /** Service name to execute commands in (required) */
+    service: string;
+    /** Resource limits (applied to target service only) */
+    resources?: DockerResources;
+}
+/**
+ * Union type for Docker sandbox options.
+ * - RuntimeSandboxOptions: Runtime package/binary installation
+ * - DockerfileSandboxOptions: Pre-built images from Dockerfile
+ * - ComposeSandboxOptions: Multi-container environments via Docker Compose
+ */
+export type DockerSandboxOptions = RuntimeSandboxOptions | DockerfileSandboxOptions | ComposeSandboxOptions;
+/**
+ * Extended sandbox interface with disposal method.
+ */
+export interface DockerSandbox extends Sandbox {
+    /** Stop and remove the container */
+    dispose(): Promise<void>;
+}
+/**
+ * Type guard to determine if options are for DockerfileStrategy.
+ */
+export declare function isDockerfileOptions(opts: DockerSandboxOptions): opts is DockerfileSandboxOptions;
+/**
+ * Type guard to determine if options are for ComposeStrategy.
+ */
+export declare function isComposeOptions(opts: DockerSandboxOptions): opts is ComposeSandboxOptions;
+/**
+ * Internal context shared across strategy methods.
+ */
+interface StrategyContext {
+    containerId: string;
+    image: string;
+}
+/**
+ * Abstract base class for Docker sandbox creation strategies.
+ *
+ * Uses the Template Method pattern to define the skeleton of the sandbox
+ * creation algorithm, deferring specific steps to subclasses.
+ *
+ * @example Extending the strategy
+ * ```typescript
+ * class CustomStrategy extends DockerSandboxStrategy {
+ *   protected async getImage(): Promise<string> {
+ *     // Custom image resolution logic
+ *     return 'my-custom-image:latest';
+ *   }
+ *
+ *   protected async configure(): Promise<void> {
+ *     // Custom configuration after container starts
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class DockerSandboxStrategy {
+    protected context: StrategyContext;
+    protected mounts: DockerMount[];
+    protected resources: DockerResources;
+    constructor(mounts?: DockerMount[], resources?: DockerResources);
+    /**
+     * Template method - defines the algorithm skeleton for creating a sandbox.
+     *
+     * Steps:
+     * 1. Validate mount paths exist on host
+     * 2. Get/build the Docker image (strategy-specific)
+     * 3. Start the container
+     * 4. Configure the container (strategy-specific)
+     * 5. Create and return sandbox methods
+     */
+    create(): Promise<DockerSandbox>;
+    /**
+     * Validates that all mount paths exist on the host filesystem.
+     */
+    protected validateMounts(): void;
+    /**
+     * Builds the docker run command arguments.
+     */
+    protected buildDockerArgs(image: string, containerId: string): string[];
+    /**
+     * Starts a Docker container with the given image.
+     */
+    protected startContainer(image: string): Promise<string>;
+    /**
+     * Stops a Docker container.
+     */
+    protected stopContainer(containerId: string): Promise<void>;
+    /**
+     * Executes a command in the container.
+     */
+    protected exec(command: string): Promise<CommandResult>;
+    /**
+     * Creates the DockerSandbox interface with all methods.
+     */
+    protected createSandboxMethods(): DockerSandbox;
+    /**
+     * Returns the Docker image to use for the container.
+     * For RuntimeStrategy: returns the image name directly.
+     * For DockerfileStrategy: builds the image and returns the tag.
+     */
+    protected abstract getImage(): Promise<string>;
+    /**
+     * Configures the container after it starts.
+     * For RuntimeStrategy: installs packages and binaries.
+     * For DockerfileStrategy: no-op (Dockerfile already configured).
+     */
+    protected abstract configure(): Promise<void>;
+}
+/**
+ * Strategy that uses an existing Docker image and installs packages/binaries
+ * at container runtime.
+ *
+ * This is the "configure-on-demand" approach - starts a vanilla image and
+ * customizes it by executing installation commands.
+ *
+ * @example
+ * ```typescript
+ * const strategy = new RuntimeStrategy(
+ *   'alpine:latest',
+ *   ['curl', 'jq'],
+ *   [{ name: 'presenterm', url: {...} }],
+ * );
+ * const sandbox = await strategy.create();
+ * ```
+ */
+export declare class RuntimeStrategy extends DockerSandboxStrategy {
+    private image;
+    private packages;
+    private binaries;
+    constructor(image?: string, packages?: string[], binaries?: BinaryInstall[], mounts?: DockerMount[], resources?: DockerResources);
+    protected getImage(): Promise<string>;
+    protected configure(): Promise<void>;
+    /**
+     * Installs packages using the appropriate package manager (apk/apt-get).
+     */
+    private installPackages;
+    /**
+     * Installs binaries from URLs.
+     */
+    private installBinaries;
+    /**
+     * Ensures curl is installed in the container.
+     */
+    private ensureCurl;
+    /**
+     * Detects the container's CPU architecture.
+     */
+    private detectArchitecture;
+    /**
+     * Installs a single binary from URL.
+     */
+    private installBinary;
+}
+/**
+ * Strategy that builds a custom Docker image from a Dockerfile.
+ *
+ * This is the "build-once, run-many" approach - builds the image upfront
+ * (with caching) and runs containers from the pre-configured image.
+ *
+ * Image caching: Uses a deterministic tag based on Dockerfile content hash.
+ * If the same Dockerfile is used, the existing image is reused (cache hit).
+ *
+ * @example Inline Dockerfile
+ * ```typescript
+ * const strategy = new DockerfileStrategy(`
+ *   FROM alpine:latest
+ *   RUN apk add --no-cache curl jq
+ * `);
+ * const sandbox = await strategy.create();
+ * ```
+ *
+ * @example Dockerfile path
+ * ```typescript
+ * const strategy = new DockerfileStrategy(
+ *   './Dockerfile.sandbox',
+ *   './docker',  // build context
+ * );
+ * const sandbox = await strategy.create();
+ * ```
+ */
+export declare class DockerfileStrategy extends DockerSandboxStrategy {
+    private imageTag;
+    private dockerfile;
+    private dockerContext;
+    constructor(dockerfile: string, dockerContext?: string, mounts?: DockerMount[], resources?: DockerResources);
+    /**
+     * Computes a deterministic image tag based on Dockerfile content.
+     * Same Dockerfile → same tag → Docker skips rebuild if image exists.
+     */
+    private computeImageTag;
+    /**
+     * Checks if the dockerfile property is inline content or a file path.
+     */
+    private isInlineDockerfile;
+    protected getImage(): Promise<string>;
+    protected configure(): Promise<void>;
+    /**
+     * Checks if the image already exists locally.
+     */
+    private imageExists;
+    /**
+     * Builds the Docker image from the Dockerfile.
+     */
+    private buildImage;
+}
+/**
+ * Strategy that manages multi-container environments using Docker Compose.
+ *
+ * Unlike other strategies that manage a single container, ComposeStrategy
+ * orchestrates multiple services as a unit using docker compose commands.
+ *
+ * @example
+ * ```typescript
+ * const strategy = new ComposeStrategy(
+ *   './docker-compose.yml',
+ *   'app',  // Service to execute commands in
+ * );
+ * const sandbox = await strategy.create();
+ *
+ * // Commands run in the 'app' service
+ * await sandbox.executeCommand('node --version');
+ *
+ * // Can communicate with other services via service names
+ * await sandbox.executeCommand('curl http://api:3000/health');
+ *
+ * // Stops ALL services
+ * await sandbox.dispose();
+ * ```
+ */
+export declare class ComposeStrategy extends DockerSandboxStrategy {
+    private projectName;
+    private composeFile;
+    private service;
+    constructor(composeFile: string, service: string, resources?: DockerResources);
+    /**
+     * Deterministic project name based on compose file content for caching.
+     * Same compose file → same project name → faster subsequent startups.
+     */
+    private computeProjectName;
+    /**
+     * Override: No image to get - compose manages its own images.
+     */
+    protected getImage(): Promise<string>;
+    /**
+     * Override: Start all services with docker compose up.
+     */
+    protected startContainer(_image: string): Promise<string>;
+    protected configure(): Promise<void>;
+    /**
+     * Override: Execute commands in the target service.
+     */
+    protected exec(command: string): Promise<CommandResult>;
+    /**
+     * Override: Stop all services with docker compose down.
+     */
+    protected stopContainer(_containerId: string): Promise<void>;
+}
+/**
+ * Creates a Docker-based sandbox for executing commands in an isolated container.
+ *
+ * Supports three strategies:
+ * - **RuntimeStrategy**: Uses existing image, installs packages/binaries at runtime
+ * - **DockerfileStrategy**: Builds custom image from Dockerfile (with caching)
+ * - **ComposeStrategy**: Multi-container environments via Docker Compose
+ *
+ * @example RuntimeStrategy (default)
+ * ```typescript
+ * const sandbox = await createDockerSandbox({
+ *   image: 'alpine:latest',
+ *   packages: ['curl', 'jq'],
+ *   binaries: [{ name: 'presenterm', url: {...} }],
+ * });
+ * await sandbox.executeCommand('curl --version');
+ * await sandbox.dispose();
+ * ```
+ *
+ * @example DockerfileStrategy
+ * ```typescript
+ * const sandbox = await createDockerSandbox({
+ *   dockerfile: `
+ *     FROM alpine:latest
+ *     RUN apk add --no-cache curl jq
+ *   `,
+ *   context: '.',
+ * });
+ * await sandbox.executeCommand('curl --version');
+ * await sandbox.dispose();
+ * ```
+ *
+ * @example ComposeStrategy
+ * ```typescript
+ * const sandbox = await createDockerSandbox({
+ *   compose: './docker-compose.yml',
+ *   service: 'app',
+ * });
+ * // Commands run in the 'app' service
+ * await sandbox.executeCommand('node --version');
+ * // Can reach other services by name
+ * await sandbox.executeCommand('curl http://db:5432');
+ * await sandbox.dispose();  // Stops ALL services
+ * ```
+ */
+export declare function createDockerSandbox(options?: DockerSandboxOptions): Promise<DockerSandbox>;
+/**
+ * Execute a function with a Docker sandbox that auto-disposes on completion.
+ * Ensures cleanup even if the function throws.
+ *
+ * @example
+ * ```typescript
+ * const output = await useSandbox(
+ *   { packages: ['curl', 'jq'] },
+ *   async (sandbox) => {
+ *     const result = await sandbox.executeCommand('curl --version');
+ *     return result.stdout;
+ *   },
+ * );
+ * // Container is automatically disposed - no try/finally needed
+ * ```
+ */
+export declare function useSandbox<T>(options: DockerSandboxOptions, fn: (sandbox: DockerSandbox) => Promise<T>): Promise<T>;
+//# sourceMappingURL=docker-sandbox.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"docker-sandbox.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/docker-sandbox.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,4 @@
+export * from './binary-bridges.ts';
+export * from './docker-sandbox.ts';
+export * from './container-tool.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AAGpC,cAAc,qBAAqB,CAAC;AAGpC,cAAc,qBAAqB,CAAC"}

package/dist/lib/skills/fragments.d.ts

@@ -0,0 +1,24 @@
+import type { ContextFragment } from '../fragments.ts';
+import type { SkillsFragmentOptions } from './types.ts';
+/**
+ * Create a context fragment containing available skills metadata.
+ *
+ * Follows Anthropic's progressive disclosure pattern:
+ * - At startup: only skill metadata (name, description, path) is injected
+ * - At runtime: LLM reads full SKILL.md using file tools when relevant
+ *
+ * @param options - Configuration including paths to scan and optional filtering
+ *
+ * @example
+ * ```ts
+ * const context = new ContextEngine({ userId: 'demo-user', store, chatId: 'demo' })
+ *   .set(
+ *     role('You are a helpful assistant.'),
+ *     skills({ paths: ['./skills'] }),  // Injects skill metadata into system prompt
+ *   );
+ *
+ * // LLM now sees skill metadata and can read full SKILL.md when needed
+ * ```
+ */
+export declare function skills(options: SkillsFragmentOptions): ContextFragment;
+//# sourceMappingURL=fragments.d.ts.map

package/dist/lib/skills/fragments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragments.d.ts","sourceRoot":"","sources":["../../../src/lib/skills/fragments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,KAAK,EAAiB,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,qBAAqB,GAAG,eAAe,CA0CtE"}

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

@@ -0,0 +1,31 @@
+/**
+ * Skills module for Anthropic-style progressive disclosure.
+ *
+ * Skills are modular packages that extend an agent's capabilities with
+ * specialized knowledge, workflows, and tools. They use progressive
+ * disclosure to minimize context window usage:
+ *
+ * 1. At startup: only skill metadata (name + description) is loaded
+ * 2. At runtime: LLM reads full SKILL.md using file tools when relevant
+ * 3. As needed: LLM navigates to references/, scripts/, assets/
+ *
+ * @example
+ * ```ts
+ * import { skills } from '@deepagents/context';
+ *
+ * // Add skills metadata to context
+ * const context = new ContextEngine({ userId: 'demo-user', store, chatId: 'demo' })
+ *   .set(
+ *     role('You are a helpful assistant.'),
+ *     skills({ paths: ['./skills', '~/.deepagents/skills'] }),
+ *   );
+ *
+ * // LLM sees available skills and reads full content when needed
+ * ```
+ *
+ * @module
+ */
+export * from './fragments.ts';
+export * from './loader.ts';
+export * from './types.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/skills/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/lib/skills/loader.d.ts

@@ -0,0 +1,28 @@
+import type { ParsedSkillMd, SkillMetadata } from './types.ts';
+/**
+ * Parse YAML frontmatter from a SKILL.md file content.
+ *
+ * Frontmatter format:
+ * ```
+ * ---
+ * name: skill-name
+ * description: Skill description here
+ * ---
+ *
+ * # Markdown body
+ * ```
+ */
+export declare function parseFrontmatter(content: string): ParsedSkillMd;
+/**
+ * Load skill metadata from a SKILL.md file.
+ * Only parses frontmatter, does not load full body into memory.
+ * This is the core of progressive disclosure - metadata only at startup.
+ */
+export declare function loadSkillMetadata(skillMdPath: string): SkillMetadata;
+/**
+ * Discover all skills in a directory.
+ * Looks for subdirectories containing SKILL.md files.
+ * Only loads metadata - full content is read by LLM when needed.
+ */
+export declare function discoverSkillsInDirectory(directory: string): SkillMetadata[];
+//# sourceMappingURL=loader.d.ts.map

package/dist/lib/skills/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/lib/skills/loader.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAyB/D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAWpE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,EAAE,CA6B5E"}

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

@@ -0,0 +1,40 @@
+/**
+ * Skill metadata parsed from SKILL.md frontmatter.
+ * This is what gets loaded into context at startup.
+ * Full skill content is read by LLM when needed (progressive disclosure).
+ */
+export interface SkillMetadata {
+    /** Skill name from frontmatter */
+    name: string;
+    /** Skill description from frontmatter */
+    description: string;
+    /** Full path to the skill directory */
+    path: string;
+    /** Full path to the SKILL.md file */
+    skillMdPath: string;
+}
+/**
+ * Options for the skills() fragment helper.
+ */
+export interface SkillsFragmentOptions {
+    /** Directories to scan for skills (required) */
+    paths: string[];
+    /** Skill names to exclude from the fragment */
+    exclude?: string[];
+    /** Skill names to include (if set, only these are included) */
+    include?: string[];
+}
+/**
+ * Result of parsing a SKILL.md file.
+ */
+export interface ParsedSkillMd {
+    /** Parsed frontmatter */
+    frontmatter: {
+        name: string;
+        description: string;
+        [key: string]: unknown;
+    };
+    /** Markdown body after frontmatter */
+    body: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/skills/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,gDAAgD;IAChD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,yBAAyB;IACzB,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;CACd"}

package/dist/lib/store/sqlite.store.d.ts

@@ -1,4 +1,4 @@
-import type { BranchData, BranchInfo, ChatData, ChatInfo, CheckpointData, CheckpointInfo, GraphData, MessageData, SearchOptions, SearchResult, StoredChatData } from './store.ts';
+import type { BranchData, BranchInfo, ChatData, ChatInfo, CheckpointData, CheckpointInfo, DeleteChatOptions, GraphData, ListChatsOptions, MessageData, SearchOptions, SearchResult, StoredChatData } from './store.ts';
 import { ContextStore } from './store.ts';
 /**
  * SQLite-based context store using graph model.
@@ -13,11 +13,13 @@ export declare class SqliteContextStore extends ContextStore {
     upsertChat(chat: ChatData): Promise<StoredChatData>;
     getChat(chatId: string): Promise<StoredChatData | undefined>;
     updateChat(chatId: string, updates: Partial<Pick<ChatData, 'title' | 'metadata'>>): Promise<StoredChatData>;
-    listChats(): Promise<ChatInfo[]>;
+    listChats(options?: ListChatsOptions): Promise<ChatInfo[]>;
+    deleteChat(chatId: string, options?: DeleteChatOptions): Promise<boolean>;
     addMessage(message: MessageData): Promise<void>;
     getMessage(messageId: string): Promise<MessageData | undefined>;
     getMessageChain(headId: string): Promise<MessageData[]>;
     hasChildren(messageId: string): Promise<boolean>;
+    getMessages(chatId: string): Promise<MessageData[]>;
     createBranch(branch: BranchData): Promise<void>;
     getBranch(chatId: string, name: string): Promise<BranchData | undefined>;
     getActiveBranch(chatId: string): Promise<BranchData | undefined>;

package/dist/lib/store/sqlite.store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite.store.d.ts","sourceRoot":"","sources":["../../../src/lib/store/sqlite.store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,cAAc,EAGd,SAAS,EAET,WAAW,EACX,aAAa,EACb,YAAY,EACZ,cAAc,EACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAwE1C;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;;gBAGtC,IAAI,EAAE,MAAM;IAWlB,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAczC,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC;IA8BnD,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IA0B5D,UAAU,CACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,UAAU,CAAC,CAAC,GACrD,OAAO,CAAC,cAAc,CAAC;IAmCpB,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAuChC,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAwC/C,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IA8B/D,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAqCvD,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAchD,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB/C,SAAS,CACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IA4B5B,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IA4BhE,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYhE,gBAAgB,CACpB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,GACvB,OAAO,CAAC,IAAI,CAAC;IAMV,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IA0DnD,gBAAgB,CAAC,UAAU,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB3D,aAAa,CACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IA0BhC,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAuB1D,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU7D,cAAc,CAClB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,EAAE,CAAC;IAgEpB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;CA0EnD"}
+{"version":3,"file":"sqlite.store.d.ts","sourceRoot":"","sources":["../../../src/lib/store/sqlite.store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,cAAc,EACd,iBAAiB,EAGjB,SAAS,EAET,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,cAAc,EACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA0E1C;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;;gBAGtC,IAAI,EAAE,MAAM;IA2BlB,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBzC,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC;IA2CnD,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IA4B5D,UAAU,CACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,UAAU,CAAC,CAAC,GACrD,OAAO,CAAC,cAAc,CAAC;IAqCpB,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IA2D1D,UAAU,CACd,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,OAAO,CAAC;IAoCb,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAwC/C,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IA8B/D,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAqCvD,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUhD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAkBnD,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB/C,SAAS,CACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IA4B5B,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IA4BhE,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYhE,gBAAgB,CACpB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,GACvB,OAAO,CAAC,IAAI,CAAC;IAMV,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IA0DnD,gBAAgB,CAAC,UAAU,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB3D,aAAa,CACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IA0BhC,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAuB1D,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU7D,cAAc,CAClB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,EAAE,CAAC;IAgEpB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;CA0EnD"}