nexus-agentd 0.2.6 → 0.3.0

package/dist/artifact-store.d.ts

@@ -0,0 +1,162 @@
+import type { AgentdArtifact, AgentdRunArtifactView } from './types.js';
+/**
+ * The value is persisted with run metadata so callers can distinguish a
+ * downloadable artifact from one for which the gateway only retained
+ * protocol metadata.
+ */
+export type ArtifactStorageStatus = 'pending' | 'available' | 'metadata_only' | 'expired' | 'evicted' | 'failed';
+export interface StoredArtifactView extends AgentdRunArtifactView {
+    id: string;
+    storageStatus: ArtifactStorageStatus;
+    downloadable: boolean;
+    size?: number;
+    sha256?: string;
+    createdAt: number;
+    storedAt?: number;
+    expiresAt?: number;
+    storageError?: string;
+}
+export interface ArtifactReadResult {
+    bytes: Buffer;
+    filename: string;
+    mediaType?: string;
+}
+export interface ArtifactStoreMetrics {
+    totalPayloadBytes: number;
+    /** Short alias useful to metrics consumers. */
+    payloadBytes: number;
+    queuedBytes: number;
+    pendingWrites: number;
+    retainedPayloads: number;
+    retainedRuns: number;
+    lastWriteMs: number;
+    writeFailures: number;
+    maxTotalBytes: number;
+    maxQueuedBytes: number;
+}
+/**
+ * A small, deliberately structural IO seam. Tests can inject failures or
+ * latency without replacing the filesystem globally. Production callers can
+ * leave this unset and the node fs/promises implementation is used.
+ */
+export interface ArtifactStoreIo {
+    mkdir?: (...args: any[]) => Promise<any>;
+    readFile?: (...args: any[]) => Promise<any>;
+    writeFile?: (...args: any[]) => Promise<any>;
+    rename?: (...args: any[]) => Promise<any>;
+    chmod?: (...args: any[]) => Promise<any>;
+    readdir?: (...args: any[]) => Promise<any>;
+    lstat?: (...args: any[]) => Promise<any>;
+    unlink?: (...args: any[]) => Promise<any>;
+    rm?: (...args: any[]) => Promise<any>;
+    open?: (...args: any[]) => Promise<any>;
+}
+export interface ArtifactStoreOptions {
+    /** Directory owned by this store. Defaults to `<run-file>.artifacts`. */
+    rootDir?: string;
+    /** Alias accepted for configuration adapters. */
+    artifactRootDir?: string;
+    /** Maximum payload size for one artifact. Defaults to 12 MiB. */
+    maxArtifactBytes?: number;
+    /** Maximum number of artifact metadata entries retained per run. */
+    maxArtifactsPerRun?: number;
+    /** Maximum aggregate payload bytes owned by this store. */
+    maxTotalBytes?: number;
+    /** Alias accepted for history/disk budget configuration. */
+    maxDiskBytes?: number;
+    /** Maximum bytes awaiting asynchronous persistence. */
+    maxQueuedBytes?: number;
+    /** Payload retention duration. Zero expires payloads immediately. */
+    retentionDays?: number;
+    /** Clock seam used by retention and deterministic tests. */
+    now?: () => number;
+    /** Optional IO seam used by tests. */
+    io?: ArtifactStoreIo;
+    /** Called whenever the public metadata view changes. */
+    onViewsChanged?: (runId: string, views: StoredArtifactView[]) => void;
+    /** Active runs are protected from retention and disk-budget eviction. */
+    isRunActive?: (runId: string) => boolean;
+}
+/**
+ * Durable payload store for run artifacts.
+ *
+ * The store keeps an index in memory and a small manifest per run. Payloads
+ * are written into a hashed run directory with hashed file names; incoming
+ * artifact ids, URLs, and filenames are never used as filesystem paths.
+ */
+export declare class ArtifactStore {
+    readonly rootDir: string;
+    readonly maxArtifactBytes: number;
+    readonly maxArtifactsPerRun: number;
+    readonly maxTotalBytes: number;
+    readonly maxQueuedBytes: number;
+    readonly retentionDays: number;
+    private readonly now;
+    private readonly io;
+    private readonly onViewsChanged?;
+    private readonly isRunActive;
+    private readonly entries;
+    private readonly runIds;
+    private readonly pending;
+    private readonly inFlight;
+    private readonly pendingDeletes;
+    private queuedBytes;
+    private totalBytes;
+    private activeDrain?;
+    private initialized;
+    private lastError?;
+    private lastWriteMs;
+    private writeFailures;
+    constructor(rootDir: string, options?: ArtifactStoreOptions);
+    init(): Promise<void>;
+    /**
+     * Reconcile metadata loaded from the legacy run JSON file with manifests
+     * found on disk. A run JSON file remains the source of truth for metadata;
+     * manifests only make payload bytes durable.
+     */
+    restoreRun(runId: string, views: AgentdRunArtifactView[]): StoredArtifactView[];
+    /**
+     * Record protocol artifacts synchronously. Payload conversion and queue
+     * insertion happen in memory; disk IO is scheduled in the background.
+     */
+    recordArtifacts(runId: string, artifacts: AgentdArtifact[]): StoredArtifactView[];
+    /** Merge display metadata from a RunStore update without dropping storage state. */
+    mergeViews(runId: string, views: AgentdRunArtifactView[], notify?: boolean): StoredArtifactView[];
+    views(runId: string): StoredArtifactView[];
+    readArtifact(runId: string, artifactId: string): Promise<ArtifactReadResult | undefined>;
+    /** Queue removal of one run's own directory. Active runs are protected. */
+    removeRun(runId: string): void;
+    flush(): Promise<void>;
+    get queuedByteCount(): number;
+    get storedByteCount(): number;
+    stats(): ArtifactStoreMetrics;
+    private runDrain;
+    private scheduleDrain;
+    private drainLoop;
+    private writePending;
+    private ensureBudget;
+    private evict;
+    private prune;
+    private expire;
+    private deleteRunDirectory;
+    private writeManifest;
+    private loadManifests;
+    private cleanupTemps;
+    private ensureDirectory;
+    private realDirectory;
+    private realPath;
+    private readRegularFile;
+    private safeUnlink;
+    private runDirectory;
+    private manifestPath;
+    private payloadPath;
+    private viewsForRun;
+    private addPending;
+    private removePending;
+    private requeue;
+    private emit;
+    private assertInitialized;
+}
+export declare class ArtifactBudgetError extends Error {
+}
+export declare function artifactStorePathForRunStore(runStorePath: string): string;