import type { SandboxEnv, SandboxFactory } from './sandbox.js';
import type { SandboxBackend } from './types.js';
/**
 * A read-only content source that can be mounted into a sandbox at
 * sandbox-creation time. The agent then has built-in `read`, `glob`,
 * and `grep` tools available over the mounted content — no retrieval
 * pipeline, no embeddings, no vector store required.
 *
 * Sources are intentionally minimal: they yield (path, content) pairs.
 * Implementations decide how to enumerate (eager vs lazy is up to the
 * source author) — the mount step pulls the full set into the sandbox.
 */
export interface FilesystemSource {
    /** Stable name for telemetry / logs. */
    readonly name?: string;
    /** Yield path/content pairs. Paths are relative to the mount root. */
    entries(): AsyncIterable<FilesystemEntry>;
}
export interface FilesystemEntry {
    /** Path relative to the mount point (no leading slash). */
    path: string;
    content: string | Uint8Array;
    /** Optional metadata; reserved for future use (mtime, content-type). */
    metadata?: Record<string, unknown>;
}
export interface MountedSource {
    source: FilesystemSource;
    /** Absolute path inside the sandbox where this source is mounted. */
    mountAt?: string;
}
/**
 * Read a host directory recursively as a read-only source.
 *
 * `include` is called for each candidate file path (relative to
 * `hostPath`). Return `false` to skip. Defaults to including everything.
 */
export declare function localDirectorySource(hostPath: string, options?: {
    name?: string;
    include?: (relativePath: string) => boolean;
}): FilesystemSource;
/**
 * Build a source from an in-memory map of `path -> content`. Useful for
 * tests, fixtures, and small static knowledge bases bundled into the
 * agent module itself.
 */
export declare function inMemorySource(files: Record<string, string | Uint8Array>, options?: {
    name?: string;
}): FilesystemSource;
/**
 * Wrap a sandbox backend or factory so each new sandbox is pre-populated
 * with the contents of one or more `FilesystemSource`s. The result is a
 * `SandboxFactory` that can be passed directly to `init({ sandbox })`.
 *
 * ```ts
 * const sandbox = withFilesystemSources('empty', [{
 *   mountAt: '/workspace/kb',
 *   source: localDirectorySource('./knowledge-base'),
 * }]);
 *
 * const agent = await init({ sandbox, model: 'openai/gpt-5.5' });
 * ```
 *
 * The agent's built-in `grep`, `glob`, and `read` tools then operate on
 * the mounted content directly. Writes to mounted paths are not blocked
 * by the SDK — sources are conventionally read-only; treat the agent's
 * role/skill prompts as the place to enforce that.
 */
/**
 * One-liner helper for the most common pattern: mount a single read-only
 * source into a virtual sandbox. Equivalent to:
 *
 * ```ts
 * withFilesystemSources('virtual', [{ mountAt, source }])
 * ```
 *
 * Used for support agents, runbook lookup, FAQ assistants — anywhere a
 * small Markdown corpus needs to be searchable via the agent's built-in
 * `grep`/`glob`/`read` tools.
 *
 * ```ts
 * import { defineAgent, getVirtualSandbox, localDirectorySource } from '@fabric-harness/sdk';
 *
 * export default defineAgent({
 *   run: async ({ init, payload }) => {
 *     const sandbox = getVirtualSandbox(localDirectorySource('./kb'));
 *     const session = await (await init({ sandbox })).session();
 *     const message = typeof payload === 'object' && payload && 'message' in payload ? String((payload as { message: unknown }).message ?? '') : '';
 *     return { reply: await session.prompt<string>(message) };
 *   },
 * });
 * ```
 */
export declare function getVirtualSandbox(source: FilesystemSource, options?: {
    mountAt?: string;
}): SandboxFactory;
export declare function withFilesystemSources(base: SandboxBackend | SandboxFactory | SandboxEnv, sources: MountedSource[]): SandboxFactory;
export interface HttpResource {
    url: string;
    /** Path relative to the mount point. Falls back to a sanitized URL pathname. */
    path?: string;
    /** Optional request headers (e.g. an API token). */
    headers?: Record<string, string>;
}
/**
 * Fetch a list of URLs and mount each response body as a file. Useful
 * for pulling a small published docs set into the sandbox so the
 * built-in `read`/`grep`/`glob` tools can search it like local files.
 */
export declare function httpFilesystemSource(resources: HttpResource[] | (() => Promise<HttpResource[]>), options?: {
    name?: string;
    fetchImpl?: typeof fetch;
}): FilesystemSource;
/**
 * Mount a local Fumadocs content directory as a knowledge base. Strips
 * MDX frontmatter by default for cleaner agent context.
 *
 * For a published Fumadocs site, fetch its `llms.txt` / sitemap and
 * pass the URLs to `httpFilesystemSource`.
 */
export declare function fumadocsSource(contentRoot: string, options?: {
    name?: string;
    stripFrontmatter?: boolean;
    include?: (relativePath: string) => boolean;
}): FilesystemSource;
/**
 * Mount a checked-out Mintlify content directory. For a hosted Mintlify
 * MCP server, use `connectMcpServer('mintlify', { url, transport: 'streamable-http' })`
 * instead.
 */
export declare function mintlifySource(contentRoot: string, options?: {
    name?: string;
    include?: (relativePath: string) => boolean;
}): FilesystemSource;
//# sourceMappingURL=filesystem-source.d.ts.map