@superblocksteam/vite-plugin-file-sync 1.99.99-next.3 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

package/dist/ai-service/context-download.d.ts

@@ -0,0 +1,56 @@
+import type { Logger } from "../util/logger.js";
+import type { ContextManagerV2 } from "./llm/context-v2/manager.js";
+import type { ContextId, ContextRecordV2 } from "./llm/context-v2/types.js";
+export interface RestoreContextResult {
+    success: boolean;
+    savedFiles: string[];
+    failedFiles: string[];
+}
+/**
+ * Downloads context from Bucketeer and returns the parsed record.
+ * Does NOT save to local storage or clear caches — the caller is responsible for that.
+ * Returns null if no context is found (404) or if the record is not V2 format.
+ */
+export declare function downloadContextFromBucketeer({ applicationId, commitId, branchName, superblocksBaseUrl, logger, jwt, contextId, appRootDirPath, }: {
+    applicationId: string;
+    commitId: string;
+    branchName: string;
+    superblocksBaseUrl: string;
+    logger: Logger;
+    jwt: string;
+    contextId?: ContextId;
+    appRootDirPath?: string;
+}): Promise<ContextRecordV2 | null>;
+/**
+ * Downloads the most recently written context for an (application, branch) from
+ * Bucketeer, without needing the commitId it was stored under. Used by the
+ * cold-pod restore fallback so it no longer has to guess a commitId (a wrong
+ * guess resolves to an empty conversation). Returns null on a 404 — which also
+ * covers a Bucketeer that predates this endpoint, so the caller can fall back to
+ * the commitId path — or a non-V2 record.
+ */
+export declare function downloadLatestContextFromBucketeer({ applicationId, branchName, superblocksBaseUrl, logger, jwt, contextId, appRootDirPath, }: {
+    applicationId: string;
+    branchName: string;
+    superblocksBaseUrl: string;
+    logger: Logger;
+    jwt: string;
+    contextId?: ContextId;
+    appRootDirPath?: string;
+}): Promise<ContextRecordV2 | null>;
+/**
+ * Downloads and restores all context files from Bucketeer checkpoint
+ * Parses multipart/form-data response and saves files to local storage
+ */
+export declare function restoreContextFromCheckpoint({ applicationId, commitId, branchName, contextId, appRootDirPath, superblocksBaseUrl, logger, jwt, contextManagerV2, }: {
+    applicationId: string;
+    commitId: string;
+    branchName: string;
+    contextId: ContextId;
+    appRootDirPath: string;
+    superblocksBaseUrl: string;
+    logger: Logger;
+    jwt: string;
+    contextManagerV2: ContextManagerV2;
+}): Promise<RestoreContextResult>;
+//# sourceMappingURL=context-download.d.ts.map

package/dist/ai-service/context-download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-download.d.ts","sourceRoot":"","sources":["../../src/ai-service/context-download.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAMhD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAGpE,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAK5E,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAkBD;;;;GAIG;AACH,wBAAsB,4BAA4B,CAAC,EACjD,aAAa,EACb,QAAQ,EACR,UAAU,EACV,kBAAkB,EAClB,MAAM,EACN,GAAG,EACH,SAAS,EACT,cAAc,GACf,EAAE;IACD,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAclC;AAED;;;;;;;GAOG;AACH,wBAAsB,kCAAkC,CAAC,EACvD,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,MAAM,EACN,GAAG,EACH,SAAS,EACT,cAAc,GACf,EAAE;IACD,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAclC;AA8ND;;;GAGG;AACH,wBAAsB,4BAA4B,CAAC,EACjD,aAAa,EACb,QAAQ,EACR,UAAU,EACV,SAAS,EACT,cAAc,EACd,kBAAkB,EAClB,MAAM,EACN,GAAG,EACH,gBAAgB,GACjB,EAAE;IACD,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,SAAS,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,EAAE,gBAAgB,CAAC;CACpC,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAkMhC"}

package/dist/ai-service/context-download.js

@@ -0,0 +1,372 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import * as path from "node:path";
+import { getBucketeerUrlFromSuperblocksUrl } from "@superblocksteam/util";
+import { getErrorMeta } from "../util/logger.js";
+import { safeArchiveFileName, safeJoinUnderRoot, SHARED_CONTEXT_SEGMENT, } from "./context-archive-paths.js";
+import { JsonlEventStore } from "./llm/context-v2/storage/jsonl-event-store.js";
+import { LocalContextStorageV2 } from "./llm/context-v2/storage/local.js";
+import { getScopedToken } from "./util/scoped-token-utils.js";
+const EVENT_LOG_ARCHIVE_PREFIX = "events__";
+/** Version literal for the V2 context record format. Kept in one place so the
+ * type guard and any record we construct stay in lockstep when V3 lands. */
+const CONTEXT_RECORD_VERSION = 2;
+/**
+ * Type guard to check if a parsed context record is V2 format.
+ */
+function isContextRecordV2(record) {
+    return (typeof record === "object" &&
+        record !== null &&
+        "version" in record &&
+        record.version === CONTEXT_RECORD_VERSION);
+}
+/**
+ * Downloads context from Bucketeer and returns the parsed record.
+ * Does NOT save to local storage or clear caches — the caller is responsible for that.
+ * Returns null if no context is found (404) or if the record is not V2 format.
+ */
+export async function downloadContextFromBucketeer({ applicationId, commitId, branchName, superblocksBaseUrl, logger, jwt, contextId, appRootDirPath, }) {
+    const bucketeerUrl = getBucketeerUrlFromSuperblocksUrl(superblocksBaseUrl);
+    const url = `${bucketeerUrl}/applications/${applicationId}/branches/${encodeURIComponent(branchName)}/commits/${encodeURIComponent(commitId)}/context`;
+    return downloadAndParseContext({
+        url,
+        applicationId,
+        superblocksBaseUrl,
+        logger,
+        jwt,
+        contextId,
+        appRootDirPath,
+        notFoundMessage: `No context found for commitId=${commitId}`,
+        logLabel: "downloadContextFromBucketeer",
+    });
+}
+/**
+ * Downloads the most recently written context for an (application, branch) from
+ * Bucketeer, without needing the commitId it was stored under. Used by the
+ * cold-pod restore fallback so it no longer has to guess a commitId (a wrong
+ * guess resolves to an empty conversation). Returns null on a 404 — which also
+ * covers a Bucketeer that predates this endpoint, so the caller can fall back to
+ * the commitId path — or a non-V2 record.
+ */
+export async function downloadLatestContextFromBucketeer({ applicationId, branchName, superblocksBaseUrl, logger, jwt, contextId, appRootDirPath, }) {
+    const bucketeerUrl = getBucketeerUrlFromSuperblocksUrl(superblocksBaseUrl);
+    const url = `${bucketeerUrl}/applications/${applicationId}/branches/${encodeURIComponent(branchName)}/context/latest`;
+    return downloadAndParseContext({
+        url,
+        applicationId,
+        superblocksBaseUrl,
+        logger,
+        jwt,
+        contextId,
+        appRootDirPath,
+        notFoundMessage: `No latest context found for branch=${branchName}`,
+        logLabel: "downloadLatestContextFromBucketeer",
+    });
+}
+/**
+ * Shared fetch + parse for the Bucketeer context endpoints. Resolves a scoped
+ * token, GETs the given URL, and returns the parsed V2 record (restoring any
+ * archived event-log files into `appRootDirPath`). Returns null on token
+ * failure, network error, 404, or a non-V2 payload.
+ *
+ * `logLabel` is the bracket prefix on every log line so each caller's logs stay
+ * attributable to the public function operators search for.
+ */
+async function downloadAndParseContext({ url, applicationId, superblocksBaseUrl, logger, jwt, contextId, appRootDirPath, notFoundMessage, logLabel, }) {
+    let scopedToken;
+    try {
+        scopedToken = await getScopedToken({
+            applicationId,
+            superblocksBaseUrl,
+            jwt,
+        });
+    }
+    catch (error) {
+        logger.error(`[${logLabel}] Failed to get scoped token`, getErrorMeta(error));
+        return null;
+    }
+    let response;
+    try {
+        response = await fetch(url, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${scopedToken}`,
+            },
+        });
+    }
+    catch (error) {
+        logger.warn(`[${logLabel}] Network error fetching context`, getErrorMeta(error));
+        return null;
+    }
+    if (!response.ok) {
+        if (response.status === 404) {
+            logger.info(`[${logLabel}] ${notFoundMessage}`);
+        }
+        else {
+            const errorText = await response
+                .text()
+                .catch(() => "Unable to read error");
+            logger.warn(`[${logLabel}] Failed to download: ${response.status} ${response.statusText} - ${errorText}`);
+        }
+        return null;
+    }
+    const contentType = response.headers.get("content-type") || "";
+    if (!contentType.includes("multipart/form-data")) {
+        try {
+            const contextJson = await response.text();
+            const contextRecord = JSON.parse(contextJson);
+            if (isContextRecordV2(contextRecord)) {
+                return contextRecord;
+            }
+            logger.warn(`[${logLabel}] Context record is not V2 format`);
+        }
+        catch (err) {
+            logger.warn(`[${logLabel}] Failed to parse JSON response`, getErrorMeta(err));
+        }
+        return null;
+    }
+    // Parse multipart response — extract main.json and restore archived event logs.
+    try {
+        const formData = await response.formData();
+        const contextFiles = formData.getAll("context");
+        let contextRecord = null;
+        const restoredEventLogFiles = [];
+        const allFileNames = [];
+        for (const file of contextFiles) {
+            if (!(file instanceof File)) {
+                continue;
+            }
+            allFileNames.push(file.name);
+            const eventLogFileName = file.name.startsWith(EVENT_LOG_ARCHIVE_PREFIX)
+                ? safeArchiveFileName(file.name.slice(EVENT_LOG_ARCHIVE_PREFIX.length))
+                : undefined;
+            if (file.name === "main.json") {
+                const fileContent = await file.text();
+                const parsed = JSON.parse(fileContent);
+                if (isContextRecordV2(parsed)) {
+                    contextRecord = parsed;
+                    continue;
+                }
+                logger.warn(`[${logLabel}] main.json is not V2 format`);
+            }
+            else if (eventLogFileName && contextId && appRootDirPath) {
+                await restoreEventLogFile({
+                    file,
+                    fileName: eventLogFileName,
+                    appRootDirPath,
+                });
+                restoredEventLogFiles.push(eventLogFileName);
+            }
+        }
+        // Defect 3 fix: log when a 200 multipart response contains no main.json.
+        if (!contextRecord && allFileNames.length > 0) {
+            logger.warn(`[${logLabel}] 200 multipart response contained no main.json (applicationId=${applicationId}, contextId=${contextId?.name ?? "unknown"}, files=${allFileNames.join(", ")}). ` +
+                `The archive may have been flushed mid-generation before the context record was persisted.`);
+        }
+        // Defect 2 fix: when the archive has event logs but no main.json, rebuild
+        // the context record from the restored event log. The replay machinery
+        // (JsonlEventStore.loadMessages) already exists for the local-storage path.
+        //
+        // After loading, delete the on-disk event log so the caller's
+        // seedEventLogFromRecord (ContextManagerV2) can re-seed it cleanly
+        // without appending duplicates to the file restoreEventLogFile wrote.
+        if (!contextRecord &&
+            restoredEventLogFiles.length > 0 &&
+            contextId &&
+            appRootDirPath) {
+            try {
+                const eventStore = new JsonlEventStore(appRootDirPath);
+                const messages = await eventStore.loadMessages(contextId);
+                if (messages.length > 0) {
+                    // Delete the restored on-disk log before publishing the record so
+                    // the caller's seedEventLogFromRecord re-seeds cleanly. If the delete
+                    // throws, contextRecord stays null and the catch leaves the next
+                    // restore attempt to retry rather than seeding duplicates.
+                    await eventStore.deleteEvents(contextId);
+                    contextRecord = { version: CONTEXT_RECORD_VERSION, messages };
+                    logger.info(`[${logLabel}] Rebuilt context record from event log (applicationId=${applicationId}, contextId=${contextId.name}, ${messages.length} messages, files=${restoredEventLogFiles.join(", ")})`);
+                }
+                else {
+                    logger.warn(`[${logLabel}] Event log restored but contained no loadable messages`);
+                }
+            }
+            catch (err) {
+                // A failure here means the conversation is unrecoverable for this
+                // restore attempt (the function returns null), so surface it at error
+                // level like the other catastrophic failures in this file.
+                logger.error(`[${logLabel}] Failed to rebuild context from event log`, getErrorMeta(err));
+            }
+        }
+        return contextRecord;
+    }
+    catch (err) {
+        logger.warn(`[${logLabel}] Failed to parse multipart response`, getErrorMeta(err));
+    }
+    return null;
+}
+async function restoreEventLogFile({ file, fileName, appRootDirPath, }) {
+    const eventRoot = path.join(appRootDirPath, ".superblocks", "events");
+    const eventDir = safeJoinUnderRoot(eventRoot, SHARED_CONTEXT_SEGMENT);
+    await mkdir(eventDir, { recursive: true });
+    const filePath = safeJoinUnderRoot(eventDir, fileName);
+    const fileContent = await file.arrayBuffer();
+    await writeFile(filePath, Buffer.from(fileContent));
+}
+async function clearLocalEventLog({ appRootDirPath, }) {
+    const eventRoot = path.join(appRootDirPath, ".superblocks", "events");
+    const eventDir = safeJoinUnderRoot(eventRoot, SHARED_CONTEXT_SEGMENT);
+    await rm(eventDir, { recursive: true, force: true });
+}
+/**
+ * Downloads and restores all context files from Bucketeer checkpoint
+ * Parses multipart/form-data response and saves files to local storage
+ */
+export async function restoreContextFromCheckpoint({ applicationId, commitId, branchName, contextId, appRootDirPath, superblocksBaseUrl, logger, jwt, contextManagerV2, }) {
+    const contextStorageV2 = new LocalContextStorageV2(appRootDirPath);
+    // Get scoped token for Bucketeer access
+    let scopedToken;
+    try {
+        scopedToken = await getScopedToken({
+            applicationId,
+            superblocksBaseUrl,
+            jwt,
+        });
+    }
+    catch (error) {
+        logger.error("[restoreContextFromCheckpoint] Failed to get scoped token", getErrorMeta(error));
+        throw error;
+    }
+    // Download context files from Bucketeer
+    const bucketeerUrl = getBucketeerUrlFromSuperblocksUrl(superblocksBaseUrl);
+    const url = `${bucketeerUrl}/applications/${applicationId}/branches/${encodeURIComponent(branchName)}/commits/${encodeURIComponent(commitId)}/context`;
+    const response = await fetch(url, {
+        method: "GET",
+        headers: {
+            Authorization: `Bearer ${scopedToken}`,
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 404) {
+            logger.info(`[restoreContextFromCheckpoint] Context files not found for commitId=${commitId}`);
+            return {
+                success: false,
+                savedFiles: [],
+                failedFiles: [],
+            };
+        }
+        const errorText = await response.text().catch(() => "Unable to read error");
+        logger.warn(`[restoreContextFromCheckpoint] Failed to download context: ${response.status} ${response.statusText} - ${errorText}`);
+        return {
+            success: false,
+            savedFiles: [],
+            failedFiles: [],
+        };
+    }
+    // Parse multipart/form-data response (always multipart, even for single file)
+    const contentType = response.headers.get("content-type") || "";
+    if (!contentType.includes("multipart/form-data")) {
+        // Fallback: if not multipart, try to parse as JSON (shouldn't happen with new endpoint)
+        const contextJson = await response.text();
+        const contextRecord = JSON.parse(contextJson);
+        // Only save if it's V2 format
+        if (isContextRecordV2(contextRecord)) {
+            await clearLocalEventLog({ appRootDirPath });
+            await contextStorageV2.saveContext(contextId, contextRecord);
+            logger.info(`[restoreContextFromCheckpoint] Saved V2 context for contextId=${contextId.name}`);
+            contextManagerV2.clearContext(contextId);
+            return {
+                success: true,
+                savedFiles: ["main.json"],
+                failedFiles: [],
+            };
+        }
+        else {
+            logger.warn(`[restoreContextFromCheckpoint] Context record is not V2 format, skipping restore`);
+            return {
+                success: false,
+                savedFiles: [],
+                failedFiles: [],
+            };
+        }
+    }
+    // Parse multipart response
+    const formData = await response.formData();
+    const savedFiles = [];
+    const failedFiles = [];
+    let mainJsonFound = false;
+    const contextFiles = formData
+        .getAll("context")
+        .filter((file) => file instanceof File);
+    const archiveIncludesEventLog = contextFiles.some((file) => file.name.startsWith(EVENT_LOG_ARCHIVE_PREFIX));
+    // Get all files with field name "context"
+    for (const file of contextFiles) {
+        const fileName = file.name;
+        try {
+            const eventLogFileName = fileName.startsWith(EVENT_LOG_ARCHIVE_PREFIX)
+                ? safeArchiveFileName(fileName.slice(EVENT_LOG_ARCHIVE_PREFIX.length))
+                : undefined;
+            // Only main.json is treated as a conversation history ContextRecord
+            if (fileName === "main.json") {
+                const fileContent = await file.text();
+                const contextRecord = JSON.parse(fileContent);
+                // Only save if it's V2 format
+                if (isContextRecordV2(contextRecord)) {
+                    if (!archiveIncludesEventLog) {
+                        await clearLocalEventLog({ appRootDirPath });
+                    }
+                    await contextStorageV2.saveContext(contextId, contextRecord);
+                    savedFiles.push(fileName);
+                    mainJsonFound = true;
+                }
+                else {
+                    logger.warn(`[restoreContextFromCheckpoint] Context record is not V2 format, skipping main.json`);
+                    failedFiles.push(fileName);
+                }
+            }
+            else if (eventLogFileName) {
+                await restoreEventLogFile({
+                    file,
+                    fileName: eventLogFileName,
+                    appRootDirPath,
+                });
+                savedFiles.push(fileName);
+            }
+            else {
+                // All other files (images, binary data, or auxiliary JSONs) are written as-is
+                const contextRoot = path.join(appRootDirPath, ".superblocks", "context");
+                const contextDir = safeJoinUnderRoot(contextRoot, SHARED_CONTEXT_SEGMENT);
+                await mkdir(contextDir, { recursive: true });
+                const filePath = safeJoinUnderRoot(contextDir, safeArchiveFileName(fileName));
+                const fileContent = await file.arrayBuffer();
+                await writeFile(filePath, Buffer.from(fileContent));
+                savedFiles.push(fileName);
+            }
+        }
+        catch (err) {
+            failedFiles.push(fileName);
+            logger.warn(`[restoreContextFromCheckpoint] Failed to save context file ${fileName}`, getErrorMeta(err));
+        }
+    }
+    // Clear in-memory cache if we replaced main.json, and let context manager to reload it
+    if (mainJsonFound) {
+        contextManagerV2.clearContext(contextId);
+    }
+    const success = mainJsonFound;
+    if (savedFiles.length > 0) {
+        logger.info(`[restoreContextFromCheckpoint] Successfully restored ${savedFiles.length} context file(s) (${savedFiles.join(", ")}) from checkpoint commitId=${commitId}`);
+        if (failedFiles.length > 0) {
+            logger.warn(`[restoreContextFromCheckpoint] Failed to restore ${failedFiles.length} file(s): ${failedFiles.join(", ")}`);
+        }
+    }
+    else if (failedFiles.length > 0) {
+        logger.warn(`[restoreContextFromCheckpoint] All context files failed to restore: ${failedFiles.join(", ")}`);
+    }
+    else {
+        logger.warn(`[restoreContextFromCheckpoint] No context files found in checkpoint`);
+    }
+    return {
+        success,
+        savedFiles,
+        failedFiles,
+    };
+}
+//# sourceMappingURL=context-download.js.map

package/dist/ai-service/context-download.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-download.js","sourceRoot":"","sources":["../../src/ai-service/context-download.ts"],"names":[],"mappings":"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"}

package/dist/ai-service/context-flush-scheduler.d.ts

@@ -0,0 +1,76 @@
+import type { Logger } from "../util/logger.js";
+/**
+ * Coalesces frequent "context changed" signals into a bounded number of
+ * uploads. Used to keep the Bucketeer copy of a Clark conversation fresh during
+ * a long generation (a single agent turn persists many times before it
+ * completes) without re-uploading on every persist.
+ *
+ * Rules:
+ * - Debounce: wait `debounceMs` of quiet after the last request before flushing,
+ *   so a burst of persists coalesces into one upload.
+ * - Hard max: never wait longer than `maxWaitMs` from the first request in a
+ *   burst, so a steady stream of persists still flushes periodically.
+ * - Single in flight: only one flush runs at a time. Requests that arrive while
+ *   a flush is running mark the scheduler dirty and trigger one more flush after
+ *   it settles.
+ * - Skip unchanged: a flush is skipped when `version()` is unchanged since the
+ *   last successful flush, so an unchanged context is never re-uploaded.
+ *
+ * The caller is responsible for only signalling at safe boundaries (a completed
+ * message, never a half-formed turn); the scheduler itself does not inspect
+ * content beyond the opaque `version()` number.
+ */
+interface ContextFlushSchedulerOptions {
+    /**
+     * Performs the upload. Resolves `true` when an upload happened (the version is
+     * then recorded as flushed), or `false` when the flush was intentionally
+     * skipped (e.g. credentials not ready) so the same version is retried on the
+     * next request. Rejections are caught and logged, not propagated.
+     */
+    flush: () => Promise<boolean>;
+    /**
+     * Opaque, monotonically-changing signal of the current content (e.g. total
+     * bytes on disk). A flush is skipped when this is unchanged since the last
+     * successful flush.
+     */
+    version: () => number;
+    /** Quiet period after the last request before flushing. */
+    debounceMs: number;
+    /** Upper bound on the wait from the first request in a burst. */
+    maxWaitMs: number;
+    logger?: Logger;
+}
+export declare class ContextFlushScheduler {
+    private readonly flush;
+    private readonly version;
+    private readonly debounceMs;
+    private readonly maxWaitMs;
+    private readonly logger?;
+    private timer;
+    /** Monotonic clock ms of the first request in the current pending burst. */
+    private firstRequestedAt;
+    private inFlight;
+    /** A request arrived while a flush was running; flush again once it settles. */
+    private dirty;
+    /** A flushNow() arrived mid-flight; the follow-up flush must skip the debounce. */
+    private flushImmediately;
+    /** `version()` value of the last successful (or skipped-as-equal) flush. */
+    private lastFlushedVersion;
+    private disposed;
+    constructor(options: ContextFlushSchedulerOptions);
+    /** Signal that the context changed at a safe boundary. */
+    requestFlush(): void;
+    /**
+     * Flush immediately if there is anything pending, bypassing the debounce.
+     * Used on a hard boundary like the end of a generation so the freshest
+     * complete turn is durable without waiting out the quiet period.
+     */
+    flushNow(): void;
+    /** Cancel any pending timer and stop accepting work. */
+    dispose(): void;
+    private scheduleTimer;
+    private runFlush;
+    private clearTimer;
+}
+export {};
+//# sourceMappingURL=context-flush-scheduler.d.ts.map

package/dist/ai-service/context-flush-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-flush-scheduler.d.ts","sourceRoot":"","sources":["../../src/ai-service/context-flush-scheduler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,UAAU,4BAA4B;IACpC;;;;;OAKG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B;;;;OAIG;IACH,OAAO,EAAE,MAAM,MAAM,CAAC;IACtB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IAEjC,OAAO,CAAC,KAAK,CAA4C;IACzD,4EAA4E;IAC5E,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAS;IACzB,gFAAgF;IAChF,OAAO,CAAC,KAAK,CAAS;IACtB,mFAAmF;IACnF,OAAO,CAAC,gBAAgB,CAAS;IACjC,4EAA4E;IAC5E,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,4BAA4B;IAQjD,0DAA0D;IAC1D,YAAY,IAAI,IAAI;IAiBpB;;;;OAIG;IACH,QAAQ,IAAI,IAAI;IAoBhB,wDAAwD;IACxD,OAAO,IAAI,IAAI;IAKf,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,QAAQ;IAiDhB,OAAO,CAAC,UAAU;CAMnB"}

package/dist/ai-service/context-flush-scheduler.js

@@ -0,0 +1,134 @@
+import { getErrorMeta } from "../util/logger.js";
+export class ContextFlushScheduler {
+    flush;
+    version;
+    debounceMs;
+    maxWaitMs;
+    logger;
+    timer;
+    /** Monotonic clock ms of the first request in the current pending burst. */
+    firstRequestedAt;
+    inFlight = false;
+    /** A request arrived while a flush was running; flush again once it settles. */
+    dirty = false;
+    /** A flushNow() arrived mid-flight; the follow-up flush must skip the debounce. */
+    flushImmediately = false;
+    /** `version()` value of the last successful (or skipped-as-equal) flush. */
+    lastFlushedVersion;
+    disposed = false;
+    constructor(options) {
+        this.flush = options.flush;
+        this.version = options.version;
+        this.debounceMs = options.debounceMs;
+        this.maxWaitMs = options.maxWaitMs;
+        this.logger = options.logger;
+    }
+    /** Signal that the context changed at a safe boundary. */
+    requestFlush() {
+        if (this.disposed) {
+            return;
+        }
+        if (this.inFlight) {
+            // Re-flush once the running upload settles; the latest content is then
+            // captured in that follow-up flush.
+            this.dirty = true;
+            return;
+        }
+        const now = Date.now();
+        if (this.firstRequestedAt === undefined) {
+            this.firstRequestedAt = now;
+        }
+        this.scheduleTimer(now);
+    }
+    /**
+     * Flush immediately if there is anything pending, bypassing the debounce.
+     * Used on a hard boundary like the end of a generation so the freshest
+     * complete turn is durable without waiting out the quiet period.
+     */
+    flushNow() {
+        if (this.disposed) {
+            return;
+        }
+        if (this.inFlight) {
+            // An upload is running; re-flush as soon as it settles, skipping the
+            // debounce so the final turn is durable right after generation end.
+            this.dirty = true;
+            this.flushImmediately = true;
+            return;
+        }
+        if (this.firstRequestedAt === undefined) {
+            // Nothing pending since the last flush; set firstRequestedAt so runFlush
+            // has a valid burst-start time. runFlush still skips if the version is
+            // unchanged since the last successful flush.
+            this.firstRequestedAt = Date.now();
+        }
+        this.runFlush();
+    }
+    /** Cancel any pending timer and stop accepting work. */
+    dispose() {
+        this.disposed = true;
+        this.clearTimer();
+    }
+    scheduleTimer(now) {
+        this.clearTimer();
+        const sinceFirst = now - (this.firstRequestedAt ?? now);
+        const remainingUntilMax = Math.max(0, this.maxWaitMs - sinceFirst);
+        const delay = Math.min(this.debounceMs, remainingUntilMax);
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.runFlush();
+        }, delay);
+    }
+    runFlush() {
+        this.clearTimer();
+        if (this.inFlight) {
+            this.dirty = true;
+            return;
+        }
+        const versionToFlush = this.version();
+        this.firstRequestedAt = undefined;
+        if (versionToFlush === this.lastFlushedVersion) {
+            // Nothing changed since the last flush.
+            return;
+        }
+        this.inFlight = true;
+        void this.flush()
+            .then((flushed) => {
+            // Only record the version when an upload actually happened. A skipped
+            // flush (e.g. credentials not ready) leaves lastFlushedVersion stale so
+            // the same content is retried on the next request.
+            if (flushed) {
+                this.lastFlushedVersion = versionToFlush;
+            }
+        })
+            .catch((error) => {
+            // Non-blocking: leave lastFlushedVersion unchanged so the next request
+            // retries this content.
+            this.logger?.warn("[context-flush] flush failed (non-blocking)", getErrorMeta(error));
+        })
+            .finally(() => {
+            this.inFlight = false;
+            if (this.disposed || !this.dirty) {
+                return;
+            }
+            this.dirty = false;
+            if (this.flushImmediately) {
+                // A flushNow() arrived while this upload was in flight; honor it
+                // immediately instead of waiting out the debounce.
+                this.flushImmediately = false;
+                this.runFlush();
+                return;
+            }
+            const now = Date.now();
+            this.firstRequestedAt = now;
+            this.scheduleTimer(now);
+        });
+    }
+    clearTimer() {
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+    }
+}
+//# sourceMappingURL=context-flush-scheduler.js.map