/** Root of every staged file. */ export declare function runsRoot(): string; /** The staging directory for one run. */ export declare function runStagingDir(runId: string): string; /** * Resolve a staged file path, refusing anything outside the run's directory. * * Returns `undefined` when the path escapes - the caller reports the refusal * rather than attaching the file. */ export declare function safeStagedPath(runId: string, filePath: string | null | undefined): string | undefined; /** * Download a document's bytes into the run's staging directory. * * `fetchUrl` must be a signed, server-minted URL - the bridge never sees an * unsigned storage URL for a private asset. */ export declare function stageFile(opts: { runId: string; fileName: string; /** Where to fetch the bytes, when the caller does not already have them. */ fetchUrl?: string; /** Bytes, when the caller already has them (preferred - no second fetch). */ buffer?: Buffer; timeoutMs?: number; }): Promise<{ path: string; bytes: number; } | null>; /** Strip anything that could escape the staging directory. */ export declare function sanitizeFileName(name: string): string; /** * Stage agent-authored text (CSV/TSV/JSON/HTML source) as a file. * Same confinement as staged downloads: the run's directory only. */ export declare function stageText(opts: { runId: string; fileName: string; text: string; }): Promise<{ path: string; bytes: number; } | null>; /** * Ensure the file name carries the required extension (a generated avatar * called "logo" still needs ".png" for the site to accept it). */ export declare function ensureExtension(fileName: string, ext: string): string;