/**
 * @fileoverview In-memory attachment registry for live external document references.
 *
 * Session-local files keep using the existing workspace-scoped file routes. This
 * registry is only for explicit, live external attachments that need a stable ID
 * so browser requests never contain arbitrary absolute paths.
 */
import type { AttachmentDetectedEvent, AttachmentDetectedType } from './types.js';
export type AttachmentSource = 'detected' | 'external';
export interface AttachmentRecord {
    attachmentId: string;
    sessionId: string;
    filePath: string;
    fileName: string;
    extension: string;
    attachmentType: AttachmentDetectedType;
    size: number;
    mtimeMs: number;
    timestamp: number;
    source: AttachmentSource;
}
export interface AttachmentRegistrationResult extends AttachmentDetectedEvent {
    attachmentId: string;
    source: AttachmentSource;
    rawUrl: string;
    previewUrl: string;
    thumbnailUrl: string;
}
export declare class AttachmentRegistrationError extends Error {
    readonly statusCode: number;
    constructor(message: string, statusCode?: number);
}
declare class AttachmentRegistry {
    private recordsBySession;
    register(record: AttachmentRecord): void;
    get(sessionId: string, attachmentId: string): AttachmentRecord | undefined;
    findByFilePath(sessionId: string, filePath: string): AttachmentRecord | undefined;
    clearSession(sessionId: string): void;
}
export declare const attachmentRegistry: AttachmentRegistry;
export declare function isSupportedAttachmentExtension(extension: string): boolean;
export declare function getAttachmentType(extension: string): AttachmentDetectedType;
export declare function buildAttachmentRoutes(sessionId: string, attachmentId: string): {
    rawUrl: string;
    previewUrl: string;
    thumbnailUrl: string;
};
export declare function buildFileThumbnailRoute(sessionId: string, relativePath: string): string;
export declare function attachmentRecordToEvent(record: AttachmentRecord): AttachmentRegistrationResult;
/** Options for {@link registerExternalAttachment}. */
export interface RegisterExternalAttachmentOptions {
    /**
     * The registering session's working directory. Required to enforce workspace
     * confinement — either when the global mode is enabled
     * (`attachmentConfineToWorkspace` / `CODEMAN_ATTACHMENT_CONFINE`) or when
     * {@link forceWorkspaceConfinement} is set for this call.
     */
    sessionWorkingDir?: string;
    /**
     * Force workspace confinement for THIS registration regardless of the global
     * setting. Used by the terminal-output `codeman://attach` magic-link scanner:
     * terminal output is attacker-influenceable (a prompt-injected session can
     * print an arbitrary path), so passive magic links may only reference files
     * inside the session workspace. Deliberate cross-workspace attachment still
     * works through the explicit, Origin-guarded `POST /attachments` route and the
     * `codeman attach` CLI (which POSTs directly when a session id is known).
     */
    forceWorkspaceConfinement?: boolean;
}
export declare function registerExternalAttachment(sessionId: string, requestedPath: string, options?: RegisterExternalAttachmentOptions): Promise<AttachmentRegistrationResult>;
export {};
//# sourceMappingURL=attachment-registry.d.ts.map