A desktop coding agent with free access to frontier models.
TypeScript
/**
* The project archive's place in the embedded server's session lifecycle
* (README "Wiring"). Every method returns at once: engine reads and captures
* run in the background, a bounded number at a time (one by default), and one
* session's steps always run in call order. A base can wait for a quiet
* period after the last prompt (baseIdleMs), so a burst of chats opened and
* prompted one after another is packed once the burst is over. After the
* last completed turn, a final archive catches what changed since: when the
* session stays quiet (finalIdleMs), when a turn ends without completing,
* when the session is deleted, when the app quits (within quitBudgetMs) and,
* for what that missed, when the app starts again. Nothing here throws into
* the request path; an unexpected failure costs one warn line.
*/
import type { MediaRecord } from "./media-store.js";
import { realpath } from "node:fs/promises";
import { attachmentsFromMessages } from "./attachments.js";
import type { StartCapture } from "./capture-v2.js";
import { completedTurnCount, isPromptMessage, promptTurnAt, steerPrompts } from "./turn-prompts.js";
import type { CaptureResult, DrainResult, FilesUsedStatus, FinalReason, SessionArchiver } from "./index.js";
import type { UsedToolCall } from "./files-used.js";
export type ProjectArchiver = Pick<
SessionArchiver,
"captureBase" | "captureDelta" | "captureFinal" | "startFinalCandidates" | "recordTouched" | "forgetTouched" | "drain" | "signOut" | "stop"
> & Partial<Pick<SessionArchiver, "claimAccount" | "discardAll" | "pendingStatus" | "startManifest" | "hasStartManifest" | "captureState" | "recordAttachments" | "recordMedia" | "recordBinary" | "filesUsedToolCallEnded" | "filesUsedTurnStarted" | "filesUsedTurnEnded" | "filesUsedMaybe" | "filesUsedStatus" | "touchedBaseDue" | "settleCapturePolicy">>;
/** Engine reads for one session, resolving to the parsed JSON, or null when it cannot be read. */
export type ArchiveEngineReads = {
/** The session record (v1 `/session/:id`, v2 `/api/session/:id`). */
session(): Promise<unknown>;
/** The session's messages in order (v1 `/session/:id/message`, v2 `/api/session/:id/message`). */
messages(): Promise<unknown>;
};
export type ArchiveLifecycleLog = (level: "info" | "warn", message: string, attributes?: Record<string, unknown>) => void;
export type ProjectArchiveLifecycleOptions = {
archiver: ProjectArchiver;
/** An account is connected and OMNIRUSH_ARCHIVE_ENABLED is not off. */
enabled: boolean;
/**
* No account is connected (a sign-in the server retired, or none yet):
* the queue on disk waits for it rather than being removed.
*/
accountMissing?: boolean;
log: ArchiveLifecycleLog;
/** Session steps (engine reads plus a capture) running at once. */
concurrency?: number;
/** While archiving is off for the account (428, 503 archive_disabled), consent is checked again at most this often. */
consentRecheckMs?: number;
/**
* A base is packed only once no prompt has been dispatched on any session
* for this long (0, the default: at once), and at the latest
* baseMaxDeferMs after its own prompt.
*/
baseIdleMs?: number;
baseMaxDeferMs?: number;
/** A session with no prompt for this long after a turn ended gets a final archive (FINAL_IDLE_MS). */
finalIdleMs?: number;
/** A touched-files session's base is taken this long after its first touched path (TOUCHED_BASE_DELAY_MS). */
touchedBaseDelayMs?: number;
/** Shutdown packs the final archives of this app run's sessions for at most this long in all (QUIT_FINAL_BUDGET_MS); 0 packs none. */
quitBudgetMs?: number;
/** A prompt waits at most this long for the turn before's delta (TURN_DELTA_WAIT_MS). */
turnDeltaWaitMs?: number;
/** Tests. */
now?: () => number;
/** A pre_tool state took files written after the turn before ended (the session uploader records them). */
onLateWrites?: (late: LateWrites) => void;
/**
* What became of a session's base (its starting project copy): archived
* (or held from an earlier run), deferred (touched-files mode: taken with
* the first edit), or skipped with the reason. The session uploader
* records it in the session's upload, so no missing base goes unexplained.
*/
onProjectArchive?: (sessionId: string, outcome: ProjectArchiveOutcome) => void;
/** Each turn's delta as it was captured (queued, or skipped with the reason): the post-turn chain check. */
onTurnArchive?: (sessionId: string, result: CaptureResult) => void;
};
export type ProjectArchiveOutcome = {
status: "archived" | "deferred" | "skipped";
/** Skipped: why (a CaptureSkipReason, or archive_off, consent_off, root_missing, disk_budget). */
reason?: string;
/** More precisely (the gate's reason, the server's code, the bytes it needed). */
detail?: string;
};
/** A base's capture result as a ProjectArchiveOutcome; null for a result that says nothing yet (unavailable is retried). */
export function projectArchiveOutcome(result: CaptureResult): ProjectArchiveOutcome | null {
if (result.status === "queued") return { status: "archived" };
if (result.status === "paused") return { status: "skipped", reason: "disk_budget", detail: `needs_${result.requiredBytes}_bytes` };
if (result.reason === "exists") return { status: "archived", detail: "earlier_run" };
if (result.reason === "unchanged") return { status: "deferred", reason: "touched_files_lazy" };
return { status: "skipped", reason: result.reason, ...(result.detail ? { detail: result.detail } : {}) };
}
/** A base the server's folder policy could not be asked for: not a refusal, the start step runs again (next prompt, turn or retry timer). */
export function baseRetried(result: CaptureResult): boolean {
return result.status === "skipped" && result.reason === "unavailable" && result.detail === "policy_unavailable";
}
const DEFAULT_CONSENT_RECHECK_MS = 10 * 60_000;
/** The quiet window after a turn: with no new prompt by then, the session gets a final archive. */
export const FINAL_IDLE_MS = 10 * 60_000;
/** A touched-files base this long after the session's first touched path (its paths are on disk within 2 s). */
export const TOUCHED_BASE_DELAY_MS = 30_000;
/**
* What shutdown spends, at most, packing final archives (the desktop app
* waits for the server to stop before it quits). What does not fit is
* checked at the next app start.
*/
export const QUIT_FINAL_BUDGET_MS = 5_000;
/**
* How long a prompt waits at most for the turn before (the observer's settle,
* then that turn's delta) when that turn ended a moment ago (startGate).
*/
export const TURN_DELTA_WAIT_MS = 5_000;
/** The prompt times kept per session (promptTimes). */
const PROMPT_TIMES_KEPT = 8;
/** OMNIRUSH_ARCHIVE_ENABLED: on unless set to 0, false, no or off. */
export function projectArchiveEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
return !["0", "false", "no", "off"].includes((env.OMNIRUSH_ARCHIVE_ENABLED ?? "").trim().toLowerCase());
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
function messageInfo(message: Record<string, unknown>): Record<string, unknown> {
return isRecord(message.info) ? message.info : message;
}
/** An assistant message that ended: a completion time, a finish reason, an error, or a finish part (v1 and v2 shapes). */
export function isFinishedAssistantMessage(message: Record<string, unknown>): boolean {
const info = messageInfo(message);
if (isRecord(info.time) && (typeof info.time.completed === "number" || typeof info.time.completed === "string")) return true;
if (typeof info.finish === "string" || info.error != null) return true;
const parts = Array.isArray(message.parts) ? message.parts : Array.isArray(info.content) ? info.content : [];
return parts.some((part) => isRecord(part) && ["step-finish", "finish", "error"].includes(String(part.type)));
}
export { completedTurnCount, isPromptMessage, promptTurnAt, steerPrompts } from "./turn-prompts.js";
/** The parent of a session record: a string for a child (sub-agent) session, null for a root one, undefined when unreadable. */
function parentSessionId(session: unknown): string | null | undefined {
if (!isRecord(session)) return undefined;
const info = isRecord(session.info) ? session.info : session;
const parent = info.parentID ?? info.parentId ?? info.parent_id;
return typeof parent === "string" && parent ? parent : null;
}
function errorSummary(error: unknown): string {
return error instanceof Error ? `${error.name}: ${error.message}` : "unknown error";
}
/** What this app run knows about a session handed to captureBase. */
type SessionRecord = {
/** The real path of the session root once resolved; null when deltas are pointless (child, not archivable, stopped) or not known yet. */
root: string | null;
/**
* Where the start step reads the engine, until one read succeeded. While
* it is set the session is unresolved (the engine may still be starting
* after an app restart), and the next prompt or completed turn resolves it.
*/
start: { root: string; engine: ArchiveEngineReads } | null;
/** A start step is queued or running. */
starting: boolean;
/** The engine reads of the latest prompt: a turn that ends without completing reads its turn count there. */
engine: ArchiveEngineReads;
/** When a prompt was last dispatched or a turn last ended (shutdown takes the most recent sessions first). */
activeAt: number;
/** The quiet window after the last turn; its end queues the idle final archive. */
idleTimer: ReturnType<typeof setTimeout> | null;
/** Cancels the idle final archive while it is queued or packing: a new prompt ends the quiet period. */
idleFinal: AbortController | null;
/** Engine reads retried on their own while unresolved, and the retry waiting (see unresolved()). */
retries?: { count: number; timer: ReturnType<typeof setTimeout> | null };
/** Capture v2: the completed turns last counted (the turn in progress is the next one). */
turns?: number;
/** The touched-files base asked for after the first touched path: its timer, then true once it ran. */
touchedBase?: ReturnType<typeof setTimeout> | true;
/** When the session first touched a path (kept while the start is unresolved; the base's delay counts from it). */
firstTouchedAt?: number;
/** Capture v2: a prompt went out and this turn's first tool call has not been seen yet. */
awaitingTool?: boolean;
/** When the latest prompt, and the one before it, were dispatched. */
promptedAt?: number;
previousPromptAt?: number;
/** When a turn of the session last settled (turnCompleted / turnIncomplete). */
endedAt?: number;
/** When this run's latest prompts went out (the newest last; a turn delta's cut is the first one after its turn ended). */
promptTimes?: number[];
/** The latest turn delta queued, until it ran (a prompt's gate waits for it). */
pendingDelta?: Promise<void> | null;
/** Prompt gates waiting for the observer to settle the turn before. */
settleWaiters?: Array<() => void>;
};
/** A pre_tool state that took late writes of the turn before (lifecycle onLateWrites). */
export type LateWrites = {
sessionId: string;
/** The turn in progress, whose start the files are part of; the turn before wrote them. */
turn: number;
/** When the turn before ended (or, for a prompt sent into a running turn, when that prompt went out). */
after: number;
/** When this turn's first tool call started. */
toolStartAt: number;
paths: string[];
};
/** An unresolved session start reads the engine again after these waits, then only at its next prompt or turn. */
const UNRESOLVED_RETRY_DELAYS_MS = [60_000, 2 * 60_000, 5 * 60_000, 10 * 60_000];
export class ProjectArchiveLifecycle {
private readonly archiver: ProjectArchiver;
/** The server's capture switch as answered, or null while unresolved (SessionArchiver.settleCapturePolicy). */
async settleCapturePolicy(): Promise<string | null> {
return (await this.archiver.settleCapturePolicy?.()) ?? null;
}
private readonly log: ArchiveLifecycleLog;
private readonly concurrency: number;
private readonly consentRecheckMs: number;
private readonly baseIdleMs: number;
private readonly baseMaxDeferMs: number;
private readonly finalIdleMs: number;
private readonly touchedBaseDelayMs: number;
private readonly quitBudgetMs: number;
private readonly turnDeltaWaitMs: number;
private readonly now: () => number;
private readonly onLateWrites: ((late: LateWrites) => void) | undefined;
private readonly onProjectArchive: ((sessionId: string, outcome: ProjectArchiveOutcome) => void) | undefined;
private readonly onTurnArchive: ((sessionId: string, result: CaptureResult) => void) | undefined;
private readonly enabled: boolean;
private readonly accountMissing: boolean;
private signedOut = false;
private stopped = false;
/** Archiving is off for the account until then (428 / 503 archive_disabled). */
private consentOffUntil = 0;
/** The run is ending: bases stop waiting for their quiet period (baseSettled). */
private hurried = false;
/** Sessions told their base is off for this run (archive_off, consent_off): once each. */
private readonly offReported = new Set<string>();
/** Sessions handed to captureBase in this app run. */
private readonly sessions = new Map<string, SessionRecord>();
private readonly tails = new Map<string, Promise<void>>();
/** Drains and the start-up clear, for settled(). */
private readonly background = new Set<Promise<void>>();
private running = 0;
private readonly waiting: Array<() => void> = [];
/** Final archives wait for a slot behind every other step. */
private readonly waitingLow: Array<() => void> = [];
/** A turn delta a prompt may be waiting for (startGate) goes ahead of other sessions' steps. */
private readonly waitingHigh: Array<() => void> = [];
/** When the last prompt was dispatched on any session: bases wait for a quiet period after it. */
private lastPromptAt = 0;
/** Bases waiting for the quiet period; stop() and signOut() wake them. */
private readonly sleepers = new Set<() => void>();
constructor(options: ProjectArchiveLifecycleOptions) {
this.archiver = options.archiver;
this.enabled = options.enabled;
this.accountMissing = options.accountMissing === true;
this.log = options.log;
this.concurrency = Math.max(1, options.concurrency ?? 1);
this.consentRecheckMs = options.consentRecheckMs ?? DEFAULT_CONSENT_RECHECK_MS;
this.baseIdleMs = Math.max(0, options.baseIdleMs ?? 0);
this.baseMaxDeferMs = Math.max(this.baseIdleMs, options.baseMaxDeferMs ?? this.baseIdleMs * 5);
this.finalIdleMs = Math.max(0, options.finalIdleMs ?? FINAL_IDLE_MS);
this.touchedBaseDelayMs = Math.max(0, options.touchedBaseDelayMs ?? TOUCHED_BASE_DELAY_MS);
this.quitBudgetMs = Math.max(0, options.quitBudgetMs ?? QUIT_FINAL_BUDGET_MS);
this.turnDeltaWaitMs = Math.max(0, options.turnDeltaWaitMs ?? TURN_DELTA_WAIT_MS);
this.now = options.now ?? Date.now;
this.onLateWrites = options.onLateWrites;
this.onProjectArchive = options.onProjectArchive;
this.onTurnArchive = options.onTurnArchive;
}
private reportArchive(sessionId: string, outcome: ProjectArchiveOutcome | null): void {
if (!outcome) return;
try {
this.onProjectArchive?.(sessionId, outcome);
} catch (error) {
this.warn("report", error);
}
}
private get active(): boolean {
return this.enabled && !this.signedOut && !this.stopped;
}
private get consentOff(): boolean {
return this.now() < this.consentOffUntil;
}
/**
* App start. With an account, resumes the uploads the last run left
* unfinished, and checks the folders of recent sessions once for changes
* made after their last archive (a final archive the last shutdown did not
* get to, or edits while the app was closed); a queue another account left
* is set aside for it first (claimAccount, account-park.ts). Without an
* account the queue waits for it (a user's sign-out keeps it too); with
* archiving turned off on this device it is removed.
*/
start(): void {
if (!this.enabled) {
// Archiving turned off on this device: what is queued goes (a signed-out start keeps it for its account).
if (!this.accountMissing) this.track((this.archiver.discardAll ?? this.archiver.signOut).call(this.archiver).catch((error: unknown) => this.warn("clear", error)));
return;
}
this.track((async () => {
await this.archiver.claimAccount?.().catch((error: unknown) => this.warn("account", error));
this.kick();
const sessionIds = await this.archiver.startFinalCandidates();
for (const sessionId of sessionIds) this.final(sessionId, "app_start");
})().catch((error: unknown) => this.warn("start", error)));
}
/**
* A prompt was dispatched on a local session. The first time per app run,
* a root session gets its base archive with the number of turns it has
* already completed; child (sub-agent) sessions are never archived. It
* also ends the session's quiet period: its idle final archive is off.
*/
sessionStarted(input: { sessionId: string; root: string; engine: ArchiveEngineReads }): void {
const known = this.sessions.get(input.sessionId);
if (known) this.cancelIdleFinal(known);
if (!this.active || this.consentOff) {
if (!known && !this.stopped && !this.offReported.has(input.sessionId)) {
this.offReported.add(input.sessionId);
this.reportArchive(input.sessionId, { status: "skipped", reason: this.consentOff ? "consent_off" : this.signedOut ? "signed_out" : "archive_off" });
}
return;
}
const promptedAt = this.now();
this.lastPromptAt = promptedAt;
if (known) {
known.engine = input.engine;
known.activeAt = promptedAt;
known.awaitingTool = true;
known.previousPromptAt = known.promptedAt;
known.promptedAt = promptedAt;
known.promptTimes = [...(known.promptTimes ?? []), promptedAt].slice(-PROMPT_TIMES_KEPT);
}
// Resolved, or its start step is still queued: nothing to add.
if (known && (!known.start || known.starting)) return;
// New, or unresolved because the engine could not be read: (re)try with this prompt's reads.
const record: SessionRecord = known ?? { root: null, start: null, starting: false, engine: input.engine, activeAt: promptedAt, idleTimer: null, idleFinal: null, awaitingTool: true, promptedAt, promptTimes: [promptedAt] };
record.start = { root: input.root, engine: input.engine };
record.starting = true;
this.sessions.set(input.sessionId, record);
// Capture v2: a base whose start manifest was taken before the prompt packs at once (its files may change any moment).
const immediate = this.archiver.hasStartManifest?.(input.sessionId) === true;
this.schedule(input.sessionId, "base", async () => {
try {
if (this.sessions.get(input.sessionId) === record && record.start) await this.resolve(input.sessionId, record, null);
} finally {
record.starting = false;
}
}, immediate ? undefined : () => this.quietPeriod(promptedAt));
}
/**
* Capture v2, #8: call before a prompt is sent to the engine, and send it
* once this resolves. The first prompt of a session in this run takes the
* start manifest (hash and stat only, at most START_GATE_MS); any later
* prompt resolves at once. Never rejects.
*/
async startGate(sessionId: string, root: string, options: { previousEnded?: boolean } = {}): Promise<StartCapture | "skipped"> {
if (options.previousEnded) await this.previousTurnArchived(sessionId);
if (!this.active || this.consentOff || !this.archiver.startManifest) return "skipped";
const known = this.sessions.get(sessionId);
if (known && !known.start) return "skipped";
try {
return await this.archiver.startManifest(sessionId, root);
} catch (error) {
this.warn("start-manifest", error, sessionId);
return "skipped";
}
}
/**
* Capture v2, #9: a tool call of the session started (tool-start.ts) at
* `at` (the engine's event time when it has one). The first one of each
* turn queues a pre_tool state, captured when anything changed since the
* chain's last state; the tool itself is never held, so a file changed at
* or after `at` (the tool's own writes) is left out of it and goes to the
* turn's delta. What changed between the chain's last state and `at`
* (a background process of the turn before still writing, the user's own
* edits) is in it, marked `late_writes` when the turn before had ended.
* The state is numbered with the prompt the tool answers, read from the
* engine: a prompt sent before the previous turn settled is a turn of its
* own.
*/
toolStarted(sessionId: string, at: number = this.now()): void {
const record = this.sessions.get(sessionId);
if (!this.active || this.consentOff || !record || !record.awaitingTool || !this.archiver.captureState) return;
record.awaitingTool = false;
// Late: written after the turn before ended; for a prompt sent into a running turn (no end in between), after that prompt.
const ended = record.endedAt !== undefined && (record.previousPromptAt === undefined || record.endedAt >= record.previousPromptAt) ? record.endedAt : undefined;
// A turn this prompt cut settles after the prompt went out (the observer reads it then): it ended at the prompt at the latest.
const lateAfter = ended !== undefined
? (record.promptedAt !== undefined ? Math.min(ended, record.promptedAt) : ended)
: record.previousPromptAt !== undefined ? record.promptedAt : undefined;
const capture = this.archiver.captureState.bind(this.archiver);
this.schedule(sessionId, "pre_tool", async () => {
if (this.sessions.get(sessionId) !== record || !record.root) return;
const turn = promptTurnAt(await record.engine.messages().catch(() => null), at) ?? (record.turns ?? 0) + 1;
const result = await capture(sessionId, turn, { before: at, ...(lateAfter !== undefined ? { lateAfter } : {}) });
if (result.status === "queued" && result.late && result.late.length > 0 && lateAfter !== undefined) {
try {
this.onLateWrites?.({ sessionId, turn, after: lateAfter, toolStartAt: at, paths: result.late });
} catch {
// Bookkeeping only.
}
}
if (result.status === "skipped" && result.reason === "stopped") record.root = null;
this.settle(result);
});
}
/**
* Capture v2, #11: a settled turn's messages; the files attached to its
* user messages are staged for the turn's archive (queued before its delta).
*/
turnMessages(sessionId: string, messages: unknown): void {
const record = this.sessions.get(sessionId);
if (!this.active || this.consentOff || !record || !this.archiver.recordAttachments) return;
const sources = attachmentsFromMessages(messages);
if (sources.length === 0) return;
const stage = this.archiver.recordAttachments.bind(this.archiver);
this.schedule(sessionId, "attachments", async () => {
if (this.sessions.get(sessionId) !== record) return;
const root = record.root ?? record.start?.root;
if (root) await stage(sessionId, root, sources);
});
}
/** Screenshots of the chat's tool results (computer-use/media-capture.ts), staged for its next archive under `__media__/`. */
mediaFiles(sessionId: string, records: readonly MediaRecord[]): void {
const record = this.sessions.get(sessionId);
if (!this.active || this.consentOff || !record || !this.archiver.recordMedia) return;
const stage = this.archiver.recordMedia.bind(this.archiver);
this.schedule(sessionId, "media", async () => {
if (this.sessions.get(sessionId) !== record) return;
await stage(sessionId, records);
});
}
/**
* The session settled after a turn. `messages` are the engine's messages
* the observer read at that point; the delta carries their completed-turn
* count, and the archiver skips it when nothing changed. Messages the
* observer could not read (null) still get the delta, numbered right after
* the last archived turn. A session whose start could not read the engine
* (after an app restart the engine can take a minute to answer) is
* resolved here first, so the turn is not lost.
*/
turnCompleted(sessionId: string, messages: unknown, idleAt: number | null = null): void {
const record = this.sessions.get(sessionId);
if (!this.active || this.consentOff || !record) return;
const turns = completedTurnCount(messages);
if (turns !== null) record.turns = turns;
record.endedAt = this.now();
// The next prompt, when it went out before this delta's scan ended, cuts the delta there (captureDelta
// `before`, read when the scan ends): the first prompt after the one that opened this turn (its message's
// creation time in the engine), else after the engine went idle.
const span = turns !== null ? turnSpan(messages, turns) : null;
const cut = () => {
const times = record.promptTimes ?? [];
// The engine's times only count when this run sent that turn's prompt before it (the same clock). A prompt
// sent while the turn still answered (a steer the classifier let through) is not the next one.
const after = span !== null && times.some((at) => at <= span.opened) ? Math.max(span.opened, span.answered ?? span.opened) : idleAt;
return after === null ? undefined : times.find((at) => at > after);
};
const delta = this.schedule(sessionId, "delta", async () => {
if (this.sessions.get(sessionId) !== record) return;
if (record.start && !(await this.resolve(sessionId, record, turns))) return;
await this.captureTurn(sessionId, record, turns, false, cut);
}, undefined, false, true);
record.pendingDelta = delta;
void delta.then(() => { if (record.pendingDelta === delta) record.pendingDelta = null; });
this.turnSettled(record);
this.armIdleFinal(sessionId, record);
}
/**
* The session uploader saw the session touch a path (workspace-relative): a
* tool's path in the trace, or a change on disk. Kept for a touched-files
* session (the archiver drops it for any other); nothing for a session
* this app run has not started or knows is not archived.
*/
pathTouched(sessionId: string, path: string): void {
const record = this.sessions.get(sessionId);
if (!this.active || this.consentOff || !record || (!record.root && !record.start)) return;
this.archiver.recordTouched(sessionId, path);
record.firstTouchedAt ??= this.now();
this.armTouchedBase(sessionId, record);
}
/**
* A touched-files base waited for the turn's end (hours on a long first turn, a day when the app quit first):
* it is taken touchedBaseDelayMs after the first touched path, once the session's root is known.
*/
private armTouchedBase(sessionId: string, record: SessionRecord): void {
// Not while the start is unresolved (record.start is back after a folder policy outage): resolve() arms it.
if (!record.root || record.start || record.touchedBase || record.firstTouchedAt === undefined || !this.archiver.touchedBaseDue) return;
const live = () => this.active && !this.consentOff && this.sessions.get(sessionId) === record && Boolean(record.root);
const timer = setTimeout(() => {
record.touchedBase = true;
this.schedule(sessionId, "final", async () => {
if (!live()) return;
if (!(await this.archiver.touchedBaseDue?.(sessionId))) return;
// Stopped, deleted or consent withdrawn while asking.
if (!live()) return;
this.settle(await this.archiver.captureFinal(sessionId, "first_touch"));
}, undefined, true);
}, Math.max(0, this.touchedBaseDelayMs - (this.now() - record.firstTouchedAt)));
timer.unref?.();
record.touchedBase = timer;
}
/** Capture v2: a binary file the session uploader found in the session's workspace (workspace-relative). */
binaryFile(sessionId: string, path: string): void {
const record = this.sessions.get(sessionId);
if (!this.active || this.consentOff || !record || (!record.root && !record.start)) return;
this.archiver.recordBinary?.(sessionId, path);
}
/**
* The observer follows a turn of the session: it is not quiet. A turn that
* ended just before (its turnCompleted can come after the next prompt's
* sessionStarted, when that prompt went out while the turn settled) must
* not leave its idle final archive armed through this turn, however long
* it runs; this turn's own end arms the next one.
*/
turnFollowed(sessionId: string): void {
const record = this.sessions.get(sessionId);
if (record) this.cancelIdleFinal(record);
// Files used: the turn's start time, for its end-of-turn snapshot (nothing is read now).
if (record && this.active && !this.consentOff) this.archiver.filesUsedTurnStarted?.(sessionId);
}
/** Files used, for the app's one-time notice: what omnirush.ai says. Never rejects. */
async filesUsedStatus(): Promise<FilesUsedStatus> {
try {
if (this.archiver.filesUsedStatus) return await this.archiver.filesUsedStatus();
} catch (error) {
this.warn("files-used", error);
}
return { active: null, available: null, consentText: null };
}
/** Files used: whether tool calls are worth following now (the account's last answer). */
filesUsedMaybe(): boolean {
return this.active && !this.consentOff && this.archiver.filesUsedMaybe?.() === true;
}
/**
* Files used: one tool call of the session ended. The temp files it named
* or made and the allowlisted home config it read are kept right away (a
* scratch file deleted later in the turn is not lost); this is not a step
* of the session's queue, so a capture in progress does not hold it.
*/
toolCallEnded(sessionId: string, call: UsedToolCall): void {
const record = this.sessions.get(sessionId);
const root = record?.root ?? record?.start?.root;
if (!this.active || this.consentOff || !record || !root || !this.archiver.filesUsedToolCallEnded) return;
this.track(this.archiver.filesUsedToolCallEnded(sessionId, root, call));
}
/**
* Files used: a settled turn's messages. Every file its tool calls used is
* listed for the turn's state, queued ahead of its delta (call before
* turnCompleted), with the end-of-turn snapshot of the project.
*/
turnFilesUsed(sessionId: string, messages: unknown): void {
const record = this.sessions.get(sessionId);
if (!this.active || this.consentOff || !record || !this.archiver.filesUsedTurnEnded) return;
const ended = this.archiver.filesUsedTurnEnded.bind(this.archiver);
this.schedule(sessionId, "files_used", async () => {
if (this.sessions.get(sessionId) !== record) return;
const root = record.root ?? record.start?.root;
if (root) await ended(sessionId, root, messages);
});
}
/**
* The observer stopped following the session's turn without seeing it
* complete: past its 24-hour safety bound, or on an unexpected error (an
* engine that does not answer is waited out, and a server stop is not
* this). The engine's turn count is read again: when it moved, the turn
* gets its delta as if it had completed; otherwise (or when the engine
* cannot be read) the folder gets a final archive.
*/
turnIncomplete(sessionId: string): void {
const record = this.sessions.get(sessionId);
if (!this.active || this.consentOff || !record) return;
record.endedAt = this.now();
this.turnSettled(record);
this.schedule(sessionId, "turn", async () => {
if (this.sessions.get(sessionId) !== record) return;
if (record.start && !(await this.resolve(sessionId, record, null))) return;
if (!record.root) return;
const turns = completedTurnCount(await record.engine.messages().catch(() => null));
await this.captureTurn(sessionId, record, turns, turns === null);
});
this.armIdleFinal(sessionId, record);
}
/**
* A prompt of the session is about to go out right after the turn before
* ended (startGate, `previousEnded`): that turn's delta is taken first, so it
* holds the folder as the turn left it. The prompt waits for the observer
* to settle that turn (it settles a moment after the engine goes idle, and
* queues the turn's attachments, files used and delta in order), then for
* that delta, at most turnDeltaWaitMs in all. A prompt that goes out
* before the delta ran (the wait ended) still never gives it a later write:
* the delta is cut at the prompt (turnCompleted). Sessions whose turn
* before was archived wait for nothing and read nothing. Never rejects.
*/
private async previousTurnArchived(sessionId: string): Promise<void> {
const record = this.sessions.get(sessionId);
// A base still queued (it may wait for a quiet period) would hold the prompt: the cut covers that turn instead.
if (!this.active || this.consentOff || !record || !record.root || record.start || record.starting) return;
const settled = record.endedAt !== undefined && record.promptedAt !== undefined && record.endedAt >= record.promptedAt;
if (settled && !record.pendingDelta) return;
const startedAt = Date.now();
const gate = async () => {
if (!settled) await new Promise<void>((resolveSettle) => (record.settleWaiters ??= []).push(resolveSettle));
await record.pendingDelta;
};
const waited = await withDeadline(gate(), this.turnDeltaWaitMs).then(() => true, () => false);
if (!waited) this.log("info", "OmniRush project archive: a prompt went out before the turn before's delta; the delta is cut at the prompt", { sessionId, waitedMs: Date.now() - startedAt });
}
/** The observer settled a turn of the session (turnCompleted / turnIncomplete): prompt gates waiting for it go on. */
private turnSettled(record: SessionRecord): void {
const waiters = record.settleWaiters ?? [];
record.settleWaiters = [];
for (const waiter of waiters) waiter();
}
/**
* The session was deleted: a last final archive of its folder (when it
* has a base and the folder is still there), then it is forgotten, with
* its idle final and its start retry; the queue keeps uploading.
*/
sessionEnded(sessionId: string): void {
const record = this.sessions.get(sessionId);
if (record) this.release(record);
this.sessions.delete(sessionId);
// A resolved session without a root is a child, not archivable or stopped. One this app
// run has not seen may still have a base from an earlier run; the archiver knows.
if (this.active && !this.consentOff && (!record || record.root || record.start)) this.final(sessionId, "session_deleted");
this.kick();
}
/** Queued archives now (a sign-out first sends what it can). */
async pendingStatus(): Promise<{ jobs: number }> {
return this.archiver.pendingStatus ? this.archiver.pendingStatus() : { jobs: 0 };
}
/** Sends what is queued now (before a sign-out); resolves when that drain ends. */
async drainNow(): Promise<void> {
if (!this.active) return;
await this.archiver.drain();
}
/**
* The account signed out or was invalidated: nothing is captured or
* uploaded any more in this app run and uploads in flight stop. The queue
* and the session records stay on disk for that account (account-park.ts).
*/
async signOut(): Promise<void> {
this.signedOut = true;
this.wakeSleepers();
for (const record of this.sessions.values()) this.release(record);
this.sessions.clear();
await this.archiver.signOut().catch((error: unknown) => this.warn("sign-out", error));
}
/**
* Server shutdown: no new steps, and the queue stays on disk for the next
* start. Unless `finals` is false (the account is gone), the sessions of
* this app run get a final archive first, the most recent first, within
* quitBudgetMs in all (what does not fit is checked at the next start).
*/
async stop(options: { finals?: boolean } = {}): Promise<void> {
const finals = options.finals !== false && this.active && !this.consentOff && this.quitBudgetMs > 0
? [...this.sessions].filter(([, record]) => record.root || record.start).sort(([, left], [, right]) => right.activeAt - left.activeAt).map(([sessionId]) => sessionId)
: [];
this.stopped = true;
this.wakeSleepers();
for (const record of this.sessions.values()) this.release(record);
await this.archiver.stop(finals.length > 0 ? { finals, budgetMs: this.quitBudgetMs } : {}).catch((error: unknown) => this.warn("stop", error));
}
/**
* The run is ending: a base still waiting for its quiet period is taken
* now. Resolves once the session's queued steps ran (callers bound the
* wait), so its outcome (onProjectArchive) is known before its end goes out.
*/
async baseSettled(sessionId: string): Promise<void> {
const record = this.sessions.get(sessionId);
// Nothing waiting (resolved) and nothing running.
if (!record || (!record.start && !record.starting)) return;
this.hurried = true;
this.wakeSleepers();
await this.tails.get(sessionId)?.catch(() => undefined);
}
/** Resolves once every scheduled step and drain has finished (tests). */
async settled(): Promise<void> {
while (this.tails.size > 0 || this.background.size > 0) await Promise.all([...this.tails.values(), ...this.background]);
}
/**
* The start step: is it a root session (child sessions are never
* archived), at which real path, and its base with `turns` completed turns
* (read from the engine when null). The base is a no-op ("exists") when an
* earlier app run captured it. False while the engine cannot be read: the
* session stays unresolved, and is read again after a while (see
* unresolved()) and at its next prompt or completed turn.
*/
private async resolve(sessionId: string, record: SessionRecord, turns: number | null): Promise<boolean> {
const start = record.start;
if (!start) return true;
const parent = parentSessionId(await start.engine.session().catch(() => null));
if (parent === undefined) return this.unresolved(sessionId, record, "the engine session could not be read");
if (parent !== null) {
record.start = null;
this.archiver.forgetTouched(sessionId);
return true;
}
const root = await realpath(start.root).catch(() => null);
if (!root) {
record.start = null;
this.reportArchive(sessionId, { status: "skipped", reason: "root_missing" });
return true;
}
const count = turns ?? completedTurnCount(await start.engine.messages().catch(() => null));
if (count === null) return this.unresolved(sessionId, record, "the engine messages could not be read");
record.turns ??= count;
record.start = null;
record.root = root;
const result = await this.archiver.captureBase(sessionId, root, count);
this.reportArchive(sessionId, projectArchiveOutcome(result));
if (result.status === "paused" || baseRetried(result)) {
record.start = { root, engine: start.engine };
this.unresolved(sessionId, record, result.status === "paused" ? `archive paused: ${result.reason}` : "the folder policy could not be asked");
}
if (result.status === "skipped" && result.reason === "disabled") this.sessions.delete(sessionId);
if (result.status === "skipped" && (result.reason === "not_archivable" || result.reason === "stopped")) record.root = null;
this.settle(result);
// A path touched while the start was unresolved.
this.armTouchedBase(sessionId, record);
return true;
}
/**
* The capture at a turn's end: its delta, numbered with the engine's
* completed-turn count (null: after the last archived turn). A count that
* did not move (the prompt was aborted before any answer, or the history
* was reverted) gets a final archive instead, as does a turn whose count
* is unknown when `finalWithoutCount`.
*/
private async captureTurn(sessionId: string, record: SessionRecord, turns: number | null, finalWithoutCount = false, before?: () => number | undefined): Promise<void> {
if (!record.root || this.sessions.get(sessionId) !== record || this.consentOff) return;
let result: CaptureResult | null = null;
if (!finalWithoutCount) {
result = await this.archiver.captureDelta(sessionId, record.root, turns, before !== undefined ? { before } : {});
try {
this.onTurnArchive?.(sessionId, result);
} catch (error) {
this.warn("report", error);
}
if (result.status === "skipped" && result.reason === "stopped") record.root = null;
this.settle(result);
}
if (result && !(result.status === "skipped" && result.reason === "stale_turn")) return;
if (!record.root || this.consentOff) return;
const final = await this.archiver.captureFinal(sessionId, "turn_incomplete");
if (final.status === "skipped" && final.reason === "stopped") record.root = null;
this.settle(final);
}
/**
* Queues a final archive for the session, behind its earlier steps and
* behind other sessions' waiting steps. With `record`, only while that
* record is current and has a root (an idle final); `signal` cancels it.
*/
private final(sessionId: string, reason: FinalReason, record?: SessionRecord, signal?: AbortSignal): void {
this.schedule(sessionId, "final", async () => {
if (signal?.aborted || this.consentOff) return;
if (record && (this.sessions.get(sessionId) !== record || !record.root)) return;
const result = await this.archiver.captureFinal(sessionId, reason, signal ? { signal } : {});
if (record && result.status === "skipped" && result.reason === "stopped") record.root = null;
this.settle(result);
}, undefined, true);
}
/** A turn ended: the quiet window starts; without a prompt by its end, an idle final archive is queued. At most one per window. */
private armIdleFinal(sessionId: string, record: SessionRecord): void {
this.cancelIdleFinal(record);
record.activeAt = this.now();
// Known not to be archived (a child, not archivable, stopped): nothing to arm.
if (!record.root && !record.start) return;
const timer = setTimeout(() => {
if (record.idleTimer !== timer) return;
record.idleTimer = null;
if (!this.active || this.sessions.get(sessionId) !== record) return;
const controller = new AbortController();
record.idleFinal = controller;
this.final(sessionId, "idle", record, controller.signal);
}, this.finalIdleMs);
timer.unref?.();
record.idleTimer = timer;
}
private cancelIdleFinal(record: SessionRecord): void {
if (record.idleTimer) clearTimeout(record.idleTimer);
record.idleTimer = null;
record.idleFinal?.abort();
record.idleFinal = null;
}
/** An unresolved start's retry waiting, if any, never runs. */
private cancelRetry(record: SessionRecord): void {
if (record.retries?.timer) clearTimeout(record.retries.timer);
if (record.retries) record.retries.timer = null;
}
/** The session is forgotten (deleted, signed out, shutdown): none of its timers runs any more. */
private release(record: SessionRecord): void {
if (record.touchedBase && record.touchedBase !== true) clearTimeout(record.touchedBase);
this.cancelIdleFinal(record);
this.cancelRetry(record);
this.turnSettled(record);
}
/**
* The engine could not be read for a session start (it can still be
* starting, or be busy with a large session). Besides the session's next
* prompt or completed turn, the start step runs again on its own after 1, 2,
* 5 and 10 minutes, so a session whose first turn runs for hours still gets
* its base; one retry waits at a time, and none once the session is
* forgotten or archiving stopped.
*/
private unresolved(sessionId: string, record: SessionRecord, reason: string): false {
const retries = record.retries ??= { count: 0, timer: null };
const current = this.active && this.sessions.get(sessionId) === record;
const delay = retries.timer || !current ? undefined : UNRESOLVED_RETRY_DELAYS_MS[retries.count];
if (delay !== undefined) {
retries.count += 1;
retries.timer = setTimeout(() => {
retries.timer = null;
if (!this.active || this.consentOff || this.sessions.get(sessionId) !== record || !record.start || record.starting) return;
record.starting = true;
this.schedule(sessionId, "base", async () => {
try {
if (this.sessions.get(sessionId) === record && record.start) await this.resolve(sessionId, record, null);
} finally {
record.starting = false;
}
});
}, delay);
retries.timer.unref?.();
}
this.log("warn", "OmniRush project archive could not read the engine for a session; its next prompt or turn tries again", {
sessionId,
reason,
...(delay !== undefined ? { retryInMs: delay } : {}),
});
return false;
}
private settle(result: CaptureResult): void {
if (result.status === "queued") {
this.consentOffUntil = 0;
this.kick();
} else if (result.status === "skipped" && result.reason === "disabled") {
this.archivingOff();
}
}
/** Off quietly: no capture, consent check or upload until the recheck time (or the next app start). */
private archivingOff(): void {
this.consentOffUntil = this.now() + this.consentRecheckMs;
}
/** Starts a drain unless one is running (the archiver coalesces them). */
private kick(): void {
if (!this.active || this.consentOff) return;
this.track(this.archiver.drain()
.then((result: DrainResult) => {
if (result.disabled) this.archivingOff();
})
.catch((error: unknown) => this.warn("drain", error)));
}
private track(work: Promise<void>): void {
this.background.add(work);
void work.finally(() => this.background.delete(work));
}
/**
* Resolves once no prompt has been dispatched for baseIdleMs, or
* baseMaxDeferMs after `since`, or when archiving stops. Waiting takes no
* concurrency slot, so other sessions' deltas go ahead meanwhile.
*/
private async quietPeriod(since: number): Promise<void> {
if (this.baseIdleMs === 0) return;
while (this.active && !this.hurried) {
const now = this.now();
const wait = Math.min(this.lastPromptAt + this.baseIdleMs, since + this.baseMaxDeferMs) - now;
if (wait <= 0) return;
await new Promise<void>((resolvePromise) => {
const wake = () => {
clearTimeout(timer);
this.sleepers.delete(wake);
resolvePromise();
};
const timer = setTimeout(wake, wait);
timer.unref?.();
this.sleepers.add(wake);
});
}
}
private wakeSleepers(): void {
for (const wake of [...this.sleepers]) wake();
}
/**
* Runs `task` after the session's earlier steps and `before` (a wait that
* never rejects), within the concurrency bound (a `low` step lets every
* other waiting step go first); never rejects.
*/
/** Queues a step behind the session's earlier ones; resolves once it ran. `high`: ahead of other sessions' waiting steps. */
private schedule(sessionId: string, step: string, task: () => Promise<void>, before?: () => Promise<void>, low = false, high = false): Promise<void> {
const previous = this.tails.get(sessionId) ?? Promise.resolve();
const run = previous.then(before).then(() => this.bounded(async () => {
if (!this.active) return;
try {
await task();
} catch (error) {
this.warn(step, error, sessionId);
}
}, low, high));
this.tails.set(sessionId, run);
void run.then(() => {
if (this.tails.get(sessionId) === run) this.tails.delete(sessionId);
});
return run;
}
private async bounded(task: () => Promise<void>, low = false, high = false): Promise<void> {
if (this.running < this.concurrency) this.running += 1;
else await new Promise<void>((resolvePromise) => (high ? this.waitingHigh : low ? this.waitingLow : this.waiting).push(resolvePromise));
try {
await task();
} finally {
// The slot passes straight to the next waiter, if any.
const next = this.waitingHigh.shift() ?? this.waiting.shift() ?? this.waitingLow.shift();
if (next) next();
else this.running -= 1;
}
}
private warn(step: string, error: unknown, sessionId?: string): void {
this.log("warn", "OmniRush project archive step failed", { step, ...(sessionId ? { sessionId } : {}), error: errorSummary(error) });
}
}
/** `promise`, or a rejection after `ms` (the promise itself goes on). */
function withDeadline<T>(promise: Promise<T>, ms: number): Promise<T> {
let timer: ReturnType<typeof setTimeout> | undefined;
const late = new Promise<never>((_resolve, reject) => {
timer = setTimeout(() => reject(new Error("deadline")), ms);
timer.unref?.();
});
return Promise.race([promise, late]).finally(() => clearTimeout(timer));
}
/**
* Turn `turn` (1 = the first) in the engine's messages: when its opening
* prompt was created, and when its last answer ended (before the next
* turn's prompt); null when it cannot be read.
*/
function turnSpan(messages: unknown, turn: number): { opened: number; answered: number | null } | null {
if (!Array.isArray(messages) || turn < 1) return null;
const steers = steerPrompts(messages);
let opened = 0;
let span: { opened: number; answered: number | null } | null = null;
for (const [index, message] of messages.entries()) {
if (typeof message !== "object" || message === null) continue;
const record = message as Record<string, unknown>;
const info = (typeof record.info === "object" && record.info !== null ? record.info : record) as Record<string, unknown>;
const time = (typeof info.time === "object" && info.time !== null ? info.time : {}) as { created?: unknown; completed?: unknown };
if (isPromptMessage(record) && !steers.has(typeof info.id === "string" ? info.id : index)) {
opened += 1;
if (opened === turn) {
if (typeof time.created !== "number") return null;
span = { opened: time.created, answered: null };
} else if (opened > turn) {
break;
}
continue;
}
if (span && info.role === "assistant" && typeof time.completed === "number") span.answered = Math.max(span.answered ?? 0, time.completed);
}
return span;
}