Skip to content

A desktop coding agent with free access to frontier models.

TypeScript

feat: files used manifest

ogsamrate0f546e198d1
diff --git a/apps/app/src/app/lib/omnirush-server.ts b/apps/app/src/app/lib/omnirush-server.ts
index 0185e406..723e15d4 100644
--- a/apps/app/src/app/lib/omnirush-server.ts
+++ b/apps/app/src/app/lib/omnirush-server.ts
@@ -407,6 +407,13 @@ export type OmniRushRuntimeApprovals = {
/** Saved only on this server/device, independent of account and workspace. */
export type OmniRushBestPractices = { enabled: boolean };
+/**
+ * The files-used switch (Settings > General): `enabled` is this device's
+ * choice; `active` whether the account records files used now, `accepted`
+ * the account's answer to the consent line, `available` whether omnirush.ai
+ * offers it, `consentText` the line to show (null when it could not be asked).
+ */
+export type OmniRushFilesUsed = { enabled: boolean; active: boolean | null; accepted: boolean | null; available: boolean | null; consentText: string | null };
export type OmniRushBestPracticesChange = OmniRushBestPractices & {
ok: boolean;
changed: boolean;
@@ -1433,6 +1440,8 @@ const resolveFetch = (url?: string) => {
const DEFAULT_OMNIRUSH_SERVER_TIMEOUT_MS = 10_000;
const ENGINE_RELOAD_TIMEOUT_MS = 60_000;
+/** The files-used switch waits for omnirush.ai (10 s at most on the server side). */
+const FILES_USED_TIMEOUT_MS = 15_000;
type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
@@ -1898,6 +1907,16 @@ export function createOmniRushServerClient(options: { baseUrl: string; token?: s
body: { mode },
timeoutMs: timeouts.config,
}),
+ getFilesUsed: () =>
+ requestJson<OmniRushFilesUsed>(baseUrl, "/runtime-config/files-used", { token, hostToken, timeoutMs: FILES_USED_TIMEOUT_MS }),
+ setFilesUsed: (enabled: boolean) =>
+ requestJson<OmniRushFilesUsed>(baseUrl, "/runtime-config/files-used", {
+ token,
+ hostToken,
+ method: "PUT",
+ body: { enabled },
+ timeoutMs: FILES_USED_TIMEOUT_MS,
+ }),
getBestPractices: () =>
requestJson<OmniRushBestPractices>(baseUrl, "/runtime-config/best-practices", { token, hostToken, timeoutMs: timeouts.config }),
setBestPractices: (enabled: boolean) =>
diff --git a/apps/app/src/react-app/domains/settings/files-used.ts b/apps/app/src/react-app/domains/settings/files-used.ts
new file mode 100644
index 00000000..00cb099c
--- /dev/null
+++ b/apps/app/src/react-app/domains/settings/files-used.ts
@@ -0,0 +1,84 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import type { OmniRushFilesUsed, OmniRushServerClient } from "@/app/lib/omnirush-server";
+
+export type FilesUsedClient = Pick<OmniRushServerClient, "getFilesUsed" | "setFilesUsed">;
+
+/**
+ * The card is shown only while omnirush.ai offers it (`available`), with the
+ * consent line omnirush.ai sends (never a copy kept here).
+ */
+export function filesUsedCardShown(setting: OmniRushFilesUsed | null): boolean {
+ return setting?.available === true && typeof setting.consentText === "string" && setting.consentText.length > 0;
+}
+
+/** The card's help: omnirush.ai's consent line, and what the switch does. */
+export function filesUsedHelp(setting: OmniRushFilesUsed | null): string {
+ return `${setting?.consentText ?? ""} Turning this on accepts it for your account; turning it off stops it.`.trim();
+}
+
+/** Whether the switch shows on: this device's choice and the account's answer (an unknown answer counts as on). */
+export function filesUsedChecked(setting: OmniRushFilesUsed | null): boolean {
+ return setting !== null && setting.enabled && setting.accepted !== false;
+}
+
+/** What the card says under the switch, from the saved setting. */
+export function filesUsedStatusLine(setting: OmniRushFilesUsed | null): string {
+ if (!setting) return "";
+ if (!setting.enabled) return "Off on this computer. No session files are saved.";
+ if (setting.active === true) return "On for this account.";
+ if (setting.accepted === false) return "Off for this account.";
+ if (setting.active === false) return "Not saving yet.";
+ return "On here. omnirush.ai could not be reached to confirm.";
+}
+
+/** The Settings switch: a GET begun before a PUT never replaces the newly saved choice. */
+export function useFilesUsed(client: FilesUsedClient | null) {
+ const [setting, setSetting] = useState<OmniRushFilesUsed | null>(null);
+ const [busy, setBusy] = useState(false);
+ const [status, setStatus] = useState("");
+ const sequence = useRef(0);
+
+ useEffect(() => {
+ sequence.current += 1;
+ const startedAt = sequence.current;
+ let cancelled = false;
+ setSetting(null);
+ setBusy(false);
+ setStatus("");
+ if (client) {
+ void client.getFilesUsed()
+ .then((value) => {
+ if (!cancelled && sequence.current === startedAt) setSetting(value);
+ })
+ .catch(() => {
+ if (!cancelled && sequence.current === startedAt) setStatus("This setting could not be loaded. Try opening Settings again.");
+ });
+ }
+ return () => { cancelled = true; };
+ }, [client]);
+
+ const setEnabled = useCallback(async (enabled: boolean) => {
+ if (!client || busy) return;
+ sequence.current += 1;
+ const startedAt = sequence.current;
+ setBusy(true);
+ setStatus("Saving…");
+ try {
+ const result = await client.setFilesUsed(enabled);
+ if (sequence.current !== startedAt) return;
+ setSetting({ enabled: result.enabled, active: result.active, accepted: result.accepted, available: result.available, consentText: result.consentText });
+ setStatus("");
+ } catch {
+ if (sequence.current !== startedAt) return;
+ const saved = await client.getFilesUsed().catch(() => null);
+ if (sequence.current !== startedAt) return;
+ if (saved) setSetting(saved);
+ setStatus("This setting could not be saved. Try again.");
+ } finally {
+ if (sequence.current === startedAt) setBusy(false);
+ }
+ }, [busy, client]);
+
+ return { setting, busy, status, setEnabled };
+}
diff --git a/apps/app/src/react-app/domains/settings/pages/general-view.tsx b/apps/app/src/react-app/domains/settings/pages/general-view.tsx
index df244a38..6cea184f 100644
--- a/apps/app/src/react-app/domains/settings/pages/general-view.tsx
+++ b/apps/app/src/react-app/domains/settings/pages/general-view.tsx
@@ -3,6 +3,7 @@ import { useEffect, useState } from "react";
import {
ArrowRight,
Cog,
+ FileStack,
FolderLock,
Mic,
Paintbrush,
@@ -35,6 +36,8 @@ import {
} from "../approval-mode";
import { DiagnosticsSection } from "./diagnostics-section";
import { BEST_PRACTICES_HELP, useBestPractices, type BestPracticesClient } from "../best-practices";
+import { filesUsedCardShown, filesUsedChecked, filesUsedHelp, filesUsedStatusLine, useFilesUsed, type FilesUsedClient } from "../files-used";
+import type { OmniRushFilesUsed } from "../../../../app/lib/omnirush-server";
export type GeneralSettingsViewProps = {
onNavigateTab: (tab: SettingsTab) => void;
@@ -43,6 +46,8 @@ export type GeneralSettingsViewProps = {
omnirushClient?: ApprovalsClient | null;
/** Global guides do not depend on workspace selection or history loading. */
bestPracticesClient?: BestPracticesClient | null;
+ /** The files-used switch (desktop only); the card is hidden without one. */
+ filesUsedClient?: FilesUsedClient | null;
/** Workspace whose engine is reloaded after the approval mode changes. */
runtimeWorkspaceId?: string | null;
/** Builds the sanitized diagnostics bundle with the route's context. */
@@ -211,6 +216,40 @@ export function BestPracticesCard(props: {
);
}
+/** Settings > General > Session files: the files-used switch, with the consent line. */
+export function FilesUsedCard(props: {
+ setting: OmniRushFilesUsed | null;
+ busy: boolean;
+ status: string;
+ onToggle: (enabled: boolean) => void;
+}) {
+ const line = props.status || filesUsedStatusLine(props.setting);
+ return (
+ <div className="space-y-3">
+ <div className="text-[11px] font-semibold uppercase tracking-[0.15em] text-dls-secondary">Session files</div>
+ <div className="flex items-center gap-4 rounded-2xl border border-dls-border bg-dls-surface p-4">
+ <div className="flex h-10 w-10 shrink-0 items-center justify-center rounded-xl border border-dls-border bg-dls-hover">
+ <FileStack size={17} className="text-dls-secondary" />
+ </div>
+ <div className="min-w-0 flex-1">
+ <div className="text-[13px] font-medium text-dls-text">Save the files a session uses</div>
+ <div id="files-used-help" className="text-[11px] text-dls-secondary">{filesUsedHelp(props.setting)}</div>
+ {line ? (
+ <div className="mt-0.5 text-[11px] text-dls-secondary" role="status" data-testid="files-used-status">{line}</div>
+ ) : null}
+ </div>
+ <Switch
+ aria-label="Save the files a session uses"
+ aria-describedby="files-used-help"
+ checked={filesUsedChecked(props.setting)}
+ disabled={props.busy || props.setting === null}
+ onCheckedChange={props.onToggle}
+ />
+ </div>
+ </div>
+ );
+}
+
export function GeneralSettingsView(props: GeneralSettingsViewProps) {
const [account, setAccount] = useState<NativeAccountStatus | null>(null);
const [accountBusy, setAccountBusy] = useState(false);
@@ -219,6 +258,8 @@ export function GeneralSettingsView(props: GeneralSettingsViewProps) {
const approvalMode = useApprovalMode(approvalsClient, props.runtimeWorkspaceId ?? null);
const bestPracticesClient = props.bestPracticesClient ?? null;
const bestPractices = useBestPractices(bestPracticesClient);
+ const filesUsedClient = isElectronRuntime() ? props.filesUsedClient ?? null : null;
+ const filesUsed = useFilesUsed(filesUsedClient);
useEffect(() => {
if (!isElectronRuntime()) return;
@@ -375,6 +416,15 @@ export function GeneralSettingsView(props: GeneralSettingsViewProps) {
/>
) : null}
+ {filesUsedClient && filesUsedCardShown(filesUsed.setting) ? (
+ <FilesUsedCard
+ setting={filesUsed.setting}
+ busy={filesUsed.busy}
+ status={filesUsed.status}
+ onToggle={(enabled) => void filesUsed.setEnabled(enabled)}
+ />
+ ) : null}
+
<DiagnosticsSection buildBundle={props.buildDiagnosticsBundle} />
</div>
);
diff --git a/apps/app/src/react-app/shell/settings-route.tsx b/apps/app/src/react-app/shell/settings-route.tsx
index c7e92205..52fa74c6 100644
--- a/apps/app/src/react-app/shell/settings-route.tsx
+++ b/apps/app/src/react-app/shell/settings-route.tsx
@@ -86,6 +86,7 @@ import { isOmniRushExtensionEnabled, OMNIRUSH_EXTENSION_STATE_CHANGED } from "@/
import { PreferencesView } from "@/react-app/domains/settings/pages/preferences-view";
import { GeneralSettingsView } from "@/react-app/domains/settings/pages/general-view";
import type { BestPracticesClient } from "@/react-app/domains/settings/best-practices";
+import type { FilesUsedClient } from "@/react-app/domains/settings/files-used";
import { AuthorizedFoldersPanel } from "@/react-app/domains/settings/panels/authorized-folders-panel";
import { BrowserLoginsPanel } from "../domains/browser-logins/browser-logins-panel";
import { EffectivePermissionsPanel } from "@/react-app/domains/settings/panels/effective-permissions-panel";
@@ -515,6 +516,7 @@ function SettingsRouteContent(props: SettingsSurfaceProps = {}) {
const [token, setToken] = useState("");
const [omnirushClient, setOmniRushClient] = useState<OmniRushServerClient | null>(null);
const [bestPracticesClient, setBestPracticesClient] = useState<BestPracticesClient | null>(null);
+ const [filesUsedClient, setFilesUsedClient] = useState<FilesUsedClient | null>(null);
const [activeClient, setActiveClient] = useState<Client | null>(null);
const [busy, setBusy] = useState(false);
const [busyLabel, setBusyLabel] = useState<string | null>(null);
@@ -1292,6 +1294,7 @@ function SettingsRouteContent(props: SettingsSurfaceProps = {}) {
const attempt = refreshLifecycleRef.current.begin(options);
if (!attempt) return;
setBestPracticesClient(null);
+ setFilesUsedClient(null);
setLoading(true);
let desktopList: WorkspaceList | null = null;
let desktopWorkspaces = workspacesRef.current;
@@ -1319,6 +1322,7 @@ function SettingsRouteContent(props: SettingsSurfaceProps = {}) {
if (!normalizedBaseUrl || !resolvedToken) {
setOmniRushClient(null);
setBestPracticesClient(null);
+ setFilesUsedClient(null);
setBaseUrl("");
setToken("");
setWorkspaces(desktopWorkspaces);
@@ -1342,6 +1346,7 @@ function SettingsRouteContent(props: SettingsSurfaceProps = {}) {
// Global guides can load once this server confirms access. Workspace
// selection and task history retain their existing readiness boundary.
setBestPracticesClient(client);
+ setFilesUsedClient(client);
serverActiveWorkspaceIdRef.current = list.activeId ?? "";
const serverWorkspaceIds = new Set(list.items.map((workspace) => workspace.id));
const nextWorkspaces = mergeRouteWorkspaces(list.items, desktopWorkspaces);
@@ -2283,6 +2288,7 @@ function SettingsRouteContent(props: SettingsSurfaceProps = {}) {
developerMode={developerMode}
omnirushClient={omnirushClient}
bestPracticesClient={bestPracticesClient}
+ filesUsedClient={filesUsedClient}
runtimeWorkspaceId={runtimeWorkspaceId}
buildDiagnosticsBundle={() => buildDiagnosticsBundleJson({
developerMode,
diff --git a/apps/app/tests/files-used-settings-card.test.tsx b/apps/app/tests/files-used-settings-card.test.tsx
new file mode 100644
index 00000000..2b55d41e
--- /dev/null
+++ b/apps/app/tests/files-used-settings-card.test.tsx
@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+
+import type { OmniRushFilesUsed } from "../src/app/lib/omnirush-server";
+import { filesUsedCardShown, filesUsedChecked, filesUsedHelp, filesUsedStatusLine } from "../src/react-app/domains/settings/files-used";
+import { FilesUsedCard } from "../src/react-app/domains/settings/pages/general-view";
+
+const LINE = "OmniRush also saves the files the agent reads, runs or creates during a session (including temporary files and a few allowlisted config files, with secrets removed), so the session can be replayed.";
+const setting = (patch: Partial<OmniRushFilesUsed> = {}): OmniRushFilesUsed => ({ enabled: true, active: false, accepted: false, available: true, consentText: LINE, ...patch });
+
+function switchMarkup(markup: string): string {
+ const match = markup.match(/<[a-z]+[^>]*role="switch"[^>]*>/);
+ if (!match) throw new Error(`no switch in ${markup}`);
+ return match[0];
+}
+
+describe("session files settings card", () => {
+ test("shows omnirush.ai's consent line and the account's answer", () => {
+ const off = renderToStaticMarkup(<FilesUsedCard setting={setting()} busy={false} status="" onToggle={() => {}} />);
+ expect(off).toContain("Session files");
+ expect(off).toContain(LINE);
+ expect(switchMarkup(off)).toContain('aria-checked="false"');
+ expect(off).toContain("Off for this account.");
+
+ const on = renderToStaticMarkup(<FilesUsedCard setting={setting({ active: true, accepted: true })} busy={false} status="" onToggle={() => {}} />);
+ expect(switchMarkup(on)).toContain('aria-checked="true"');
+ expect(on).toContain("On for this account.");
+ });
+
+ test("the switch is off when this computer turned it off, whatever the account says", () => {
+ const local = setting({ enabled: false, accepted: true, active: false });
+ expect(filesUsedChecked(local)).toBe(false);
+ expect(filesUsedStatusLine(local)).toBe("Off on this computer. No session files are saved.");
+ expect(filesUsedChecked(setting({ accepted: null, active: null }))).toBe(true);
+ expect(filesUsedStatusLine(setting({ accepted: null, active: null }))).toContain("could not be reached");
+ });
+
+ test("shown only while omnirush.ai offers it, with its own wording (no copy kept in the app)", () => {
+ expect(filesUsedCardShown(setting())).toBe(true);
+ expect(filesUsedCardShown(setting({ available: false }))).toBe(false);
+ expect(filesUsedCardShown(setting({ consentText: null }))).toBe(false);
+ expect(filesUsedCardShown(null)).toBe(false);
+ expect(filesUsedHelp(setting({ consentText: "Server wording." }))).toStartWith("Server wording.");
+ });
+});
diff --git a/apps/server/src/capture-client.ts b/apps/server/src/capture-client.ts
index 3595e7f9..31e90c35 100644
--- a/apps/server/src/capture-client.ts
+++ b/apps/server/src/capture-client.ts
@@ -14,6 +14,7 @@ import { Worker } from "node:worker_threads";
import { lstat } from "node:fs/promises";
import { resolve } from "node:path";
import { START_GATE_MS } from "./session-archive/capture-v2.js";
+import type { FilesUsedSetting } from "./session-archive/index.js";
import { CaptureHost, type CaptureDiagnostics, type CaptureHostOptions, type EngineReplacement, type EngineTarget, type PromptRecord } from "./capture-host.js";
import {
@@ -85,6 +86,9 @@ export type CaptureService = {
/** Every queued capture, upload and archive step settled (tests, profiling). */
idle(): Promise<void>;
diagnostics(): Promise<CaptureDiagnostics | null>;
+ /** Files used, for Settings (null: capture is not running). */
+ filesUsedStatus(): Promise<FilesUsedSetting | null>;
+ setFilesUsed(enabled: boolean): Promise<FilesUsedSetting | null>;
};
/** How much longer than the start gate's own cap the main thread waits for the worker's answer. */
@@ -218,6 +222,14 @@ class CaptureClient implements CaptureService {
return isDiagnostics(value) ? value : null;
}
+ async filesUsedStatus(): Promise<FilesUsedSetting | null> {
+ return filesUsedSettingOf(await this.query({ kind: "call", id: null, method: "filesUsedStatus", args: [] }));
+ }
+
+ async setFilesUsed(enabled: boolean): Promise<FilesUsedSetting | null> {
+ return filesUsedSettingOf(await this.query({ kind: "call", id: null, method: "setFilesUsed", args: [enabled] }));
+ }
+
stop(options: { archiveFinals?: boolean | Promise<boolean> } = {}): Promise<void> {
this.stopping ??= this.shutdown(options.archiveFinals ?? true);
return this.stopping;
@@ -537,6 +549,15 @@ async function withinTimeout(answer: boolean | Promise<boolean>, ms: number): Pr
}
}
+function filesUsedSettingOf(value: unknown): FilesUsedSetting | null {
+ if (typeof value !== "object" || value === null) return null;
+ const record = value as Record<string, unknown>;
+ const flag = (item: unknown) => (typeof item === "boolean" ? item : null);
+ return typeof record.enabled === "boolean"
+ ? { enabled: record.enabled, active: flag(record.active), accepted: flag(record.accepted), available: flag(record.available), consentText: typeof record.consentText === "string" ? record.consentText : null }
+ : null;
+}
+
function isDiagnostics(value: unknown): value is CaptureDiagnostics {
return typeof value === "object" && value !== null && "metrics" in value && "cache" in value;
}
diff --git a/apps/server/src/capture-host.ts b/apps/server/src/capture-host.ts
index 416049ea..866b9c03 100644
--- a/apps/server/src/capture-host.ts
+++ b/apps/server/src/capture-host.ts
@@ -15,7 +15,7 @@ import {
currentEngineTarget,
engineReplaced,
observeUploadedSession,
- followToolStart, followContextToolEvents,
+ followToolStart, followContextToolEvents, followFilesUsedCalls,
projectArchiveEngineReads,
promptDispatched,
type EngineReplacement,
@@ -23,7 +23,7 @@ import {
type SessionObservers,
} from "./session-upload-observer.js";
import type { CaptureStopOptions } from "./capture-protocol.js";
-import { SessionArchiver, type SessionArchiverOptions } from "./session-archive/index.js";
+import { SessionArchiver, type FilesUsedSetting, type SessionArchiverOptions } from "./session-archive/index.js";
import { ProjectArchiveLifecycle, type ArchiveLifecycleLog } from "./session-archive/lifecycle.js";
import { SessionUploader, type TraceCapabilities, type UploadMetrics, type UploadWebVisit } from "./session-uploader.js";
@@ -182,6 +182,8 @@ export class CaptureHost {
followToolStart({ observers: this.observers, archive: this.archive, sessionId, target });
// Capture context: each tool call's start and end, for the network observer.
followContextToolEvents({ observers: this.observers, context: this.sessionUploader.context, sessionId, target });
+ // Files used: each tool call's end, so its temp files are kept before a later call deletes them.
+ followFilesUsedCalls({ observers: this.observers, archive: this.archive, sessionId, target });
}
/** Capture v2: the session-start manifest, before the first prompt reaches the engine (lifecycle.ts startGate). */
@@ -207,6 +209,16 @@ export class CaptureHost {
});
}
+ /** Files used, for Settings: the switch on this device and the account's answer. */
+ filesUsedStatus(): Promise<FilesUsedSetting> {
+ return this.archive.filesUsedStatus();
+ }
+
+ /** Files used, the Settings switch. */
+ setFilesUsed(enabled: boolean): Promise<FilesUsedSetting> {
+ return this.archive.setFilesUsed(enabled);
+ }
+
/** The session was deleted in the engine. */
sessionDeleted(sessionId: string): void {
this.sessionUploader.recordTrace(sessionId, "session.deleted");
diff --git a/apps/server/src/capture-protocol.ts b/apps/server/src/capture-protocol.ts
index cded62f7..4dfc729d 100644
--- a/apps/server/src/capture-protocol.ts
+++ b/apps/server/src/capture-protocol.ts
@@ -32,6 +32,8 @@ export type CaptureCalls = {
stop: [options?: CaptureStopOptions];
idle: [];
diagnostics: [];
+ filesUsedStatus: [];
+ setFilesUsed: [enabled: boolean];
};
export type CaptureCallName = keyof CaptureCalls;
@@ -45,7 +47,7 @@ export type HostRequest =
| { type: "uploadFile"; sessionId: string; path: string; size: number }
| { type: "capabilities" }
| { type: "refreshAccessToken" }
- | { type: "archiveRequest"; path: string; method: "GET" | "POST"; body?: string; refresh?: false }
+ | { type: "archiveRequest"; path: string; method: "GET" | "POST" | "PUT"; body?: string; refresh?: false }
| { type: "fetch"; url: string; method: string; headers: Array<[string, string]>; body?: Uint8Array<ArrayBuffer> | string };
export type RequestChannel = "uploader" | "archive";
@@ -180,5 +182,9 @@ export function invokeCapture(host: CaptureHost, call: CaptureCall): unknown {
return host.idle();
case "diagnostics":
return host.diagnostics();
+ case "filesUsedStatus":
+ return host.filesUsedStatus();
+ case "setFilesUsed":
+ return host.setFilesUsed(...call.args);
}
}
diff --git a/apps/server/src/omnirush-gateway-broker.ts b/apps/server/src/omnirush-gateway-broker.ts
index 519792d7..2d3dd979 100644
--- a/apps/server/src/omnirush-gateway-broker.ts
+++ b/apps/server/src/omnirush-gateway-broker.ts
@@ -694,7 +694,7 @@ export const VOICE_TRANSCRIPTIONS_PATH = "audio/transcriptions";
const VOICE_TRANSCRIBE_TIMEOUT_MS = 35_000;
/** The project archive routes the session archiver calls (archives, archives/key, archives/<id>/parts|complete|abort). */
-const ARCHIVE_API_PATH = /^archives(?:\/key|\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/(?:parts|complete|abort))?$/;
+const ARCHIVE_API_PATH = /^archives(?:\/key|\/files-used|\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/(?:parts|complete|abort))?$/;
/**
* Set by the omnirush-reasoning-effort engine plugin; keep the two
@@ -1270,7 +1270,7 @@ export class OmniRushGatewayBroker {
* `refresh: false` (the archiver's all-folders policy probe) it is one
* request: a 401 is returned as it is, with no refresh and no second try.
*/
- archiveRequest(path: string, init: { method: "GET" | "POST"; body?: string; signal?: AbortSignal; refresh?: false }): Promise<Response> {
+ archiveRequest(path: string, init: { method: "GET" | "POST" | "PUT"; body?: string; signal?: AbortSignal; refresh?: false }): Promise<Response> {
if (!ARCHIVE_API_PATH.test(path)) return Promise.resolve(Response.json({ error: "unsupported_archive_path" }, { status: 404 }));
return this.withDeviceBearer((state) => this.fetcher(apiUrl(state.gatewayUrl, path), {
method: init.method,
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index a615b96e..cedffca1 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -3589,6 +3589,27 @@ function createRoutes(
return jsonResponse({ ok: true, changed: result.changed, ...resolveApprovalMode(result.config) });
});
+ // Files used (session-archive/files-used.ts): the user's switch, saved on this device and sent to
+ // omnirush.ai as the account's opt-out. `active` says whether the account records files used now.
+ addRoute(routes, "GET", "/runtime-config/files-used", "client", async () => {
+ const setting = await captureServicesByServer.get(config)?.filesUsedStatus().catch(() => null);
+ return jsonResponse(setting ?? { enabled: true, active: null, accepted: null, available: null, consentText: null });
+ });
+
+ addRoute(routes, "PUT", "/runtime-config/files-used", "client", async (ctx) => {
+ ensureWritable(config);
+ requireClientScope(ctx, "collaborator");
+ const body = await readJsonBody(ctx.request);
+ if (typeof body.enabled !== "boolean" || Object.keys(body).some((key) => key !== "enabled")) {
+ throw new ApiError(400, "invalid_payload", "enabled must be a boolean and the only field");
+ }
+ const capture = captureServicesByServer.get(config);
+ if (!capture) throw new ApiError(503, "capture_unavailable", "The session capture is not running");
+ const setting = await capture.setFilesUsed(body.enabled).catch(() => null);
+ if (!setting) throw new ApiError(503, "capture_unavailable", "The setting could not be saved");
+ return jsonResponse({ ok: true, ...setting });
+ });
+
addRoute(routes, "GET", "/runtime-config/best-practices", "client", async () => {
const runtime = await readGlobalRuntimeOpencodeConfig(config);
return jsonResponse({ enabled: runtime.bestPractices !== false });
diff --git a/apps/server/src/session-archive/README.md b/apps/server/src/session-archive/README.md
index 58622076..0b9a2786 100644
--- a/apps/server/src/session-archive/README.md
+++ b/apps/server/src/session-archive/README.md
@@ -45,6 +45,10 @@ The user-facing description is `docs/project-archive.md`.
| `files.ts` | Atomic state-file writes and the GC hint |
| `index.ts` | `SessionArchiver`: durable queue, crash recovery, drain |
| `lifecycle.ts` | `ProjectArchiveLifecycle`: when the server calls the archiver (session start, turn end, a turn that ends without completing, session end, sign-out, shutdown, app start), the engine-derived turn count, the child-session check, the consent-off window, the quiet window before a final archive and the bounded background queue; `projectArchiveEnabled` (`OMNIRUSH_ARCHIVE_ENABLED`) |
+| `files-used-policy.ts` | Files used (backend spec 19.7): the `files_used` item and its reasons, the caps (64 MiB per file, 256 MiB per chat), `classifyUse` (scope, and whether the bytes are archived from the scan, staged, or held), the home config allowlist and `scrubHomeConfig`. Pure; byte-identical to the CLI's |
+| `files-used-shell.ts` | Files used: the files a shell command reads, writes or runs, from its text alone. Pure; byte-identical to the CLI's |
+| `deps.ts` | Files used: the resolved versions of each subproject from its lockfile (the state's `dependencies`). Pure; byte-identical to the CLI's |
+| `files-used.ts` | Files used, the app side: `FilesUsedStore` (staged copies and the items waiting for the next state), `FilesUsedTracker` (the end of each tool call keeps its temp files and scrubbed home config; the end of each turn lists every file its calls used, plus the end-of-turn snapshot of files changed during the turn, and reports the project and outside ones as touched), `collectDependencyProjects`, `watchToolCallEnds`. Only the agent's own tool calls are read: no hooks, no file watchers |
| `fake-archive-server.ts`, `test-helpers.ts` | Test support only |
## API
diff --git a/apps/server/src/session-archive/capture-v2.ts b/apps/server/src/session-archive/capture-v2.ts
index 3ff72cba..c44b7bed 100644
--- a/apps/server/src/session-archive/capture-v2.ts
+++ b/apps/server/src/session-archive/capture-v2.ts
@@ -16,6 +16,8 @@
import type { AttachmentRecord } from "./attachments.js";
import { attachmentStateItem } from "./attachments.js";
import type { RepoState } from "./repos.js";
+import type { FilesUsedItem } from "./files-used-policy.js";
+import type { ToolchainProject } from "./deps.js";
export const ARCHIVE_SCHEMA_V2 = "omnirush.archive.v2";
export const STATE_MEMBER = "__omnirush__/state.json";
@@ -104,6 +106,10 @@ export type StateDocumentInput = {
excluded: ExcludedList;
scrubbed: readonly string[];
attachments: readonly AttachmentRecord[];
+ /** Files used (19.7): the files the turns since the last state used; present (maybe empty) on a files-used chain. */
+ filesUsed?: readonly FilesUsedItem[];
+ /** Files used (19.7): every subproject's lockfile and resolved versions, when they were read for this state. */
+ dependencies?: readonly ToolchainProject[];
};
/** `__omnirush__/state.json` of a v2 archive. */
@@ -120,5 +126,7 @@ export function stateDocument(input: StateDocumentInput): Buffer {
excluded_truncated_count: input.excluded.truncatedCount,
scrubbed: [...input.scrubbed].sort(),
attachments: input.attachments.map(attachmentStateItem),
+ ...(input.filesUsed ? { files_used: input.filesUsed } : {}),
+ ...(input.dependencies ? { dependencies: input.dependencies } : {}),
}), "utf8");
}
diff --git a/apps/server/src/session-archive/deps.ts b/apps/server/src/session-archive/deps.ts
new file mode 100644
index 00000000..e331a421
--- /dev/null
+++ b/apps/server/src/session-archive/deps.ts
@@ -0,0 +1,293 @@
+/**
+ * Files used (backend spec 19.7): the resolved dependency versions of
+ * every subproject, read from its lockfile (no package manager is run).
+ * State documents carry them as `dependencies`:
+ *
+ * [{ dir, ecosystem, manifests, lockfile, resolved: { name: version }, count, truncated }]
+ *
+ * `dir` is the subproject folder (workspace-relative, `.` for the root),
+ * `lockfile` the lockfile the versions come from, `manifests` the manifest
+ * files beside it. The dependency folders themselves (node_modules, .venv,
+ * vendor) are never archived; a replay rebuilds them from the archived
+ * lockfile at these versions.
+ *
+ * Pure parsing; the caller reads the files (bounded by MAX_LOCKFILE_BYTES).
+ * Identical in the CLI and the desktop app.
+ */
+
+export const MAX_LOCKFILE_BYTES = 16 * 1024 * 1024;
+export const MAX_RESOLVED_PER_PROJECT = 5_000;
+export const MAX_TOOLCHAIN_PROJECTS = 50;
+
+export type Ecosystem = "npm" | "pnpm" | "yarn" | "bun" | "pip" | "poetry" | "uv" | "pipenv" | "pdm" | "cargo" | "go" | "composer" | "bundler" | "gradle" | "maven" | "deno" | "other";
+
+export type ToolchainProject = {
+ dir: string;
+ ecosystem: Ecosystem;
+ lockfile: string;
+ manifests: string[];
+ resolved: Record<string, string>;
+ count: number;
+ truncated: boolean;
+};
+
+/** Lockfile name -> ecosystem (the names touched.ts findLockfiles finds, plus the pinned requirements files). */
+export const LOCKFILE_ECOSYSTEMS: Record<string, Ecosystem> = {
+ "package-lock.json": "npm",
+ "npm-shrinkwrap.json": "npm",
+ "pnpm-lock.yaml": "pnpm",
+ "yarn.lock": "yarn",
+ "bun.lock": "bun",
+ "poetry.lock": "poetry",
+ "uv.lock": "uv",
+ "Pipfile.lock": "pipenv",
+ "pdm.lock": "pdm",
+ "Cargo.lock": "cargo",
+ "go.sum": "go",
+ "composer.lock": "composer",
+ "Gemfile.lock": "bundler",
+ "gradle.lockfile": "gradle",
+ "deno.lock": "deno",
+ "requirements.txt": "pip",
+ "requirements.lock": "pip",
+ "requirements-dev.txt": "pip",
+};
+
+/** Manifests looked for beside a lockfile. */
+export const MANIFEST_NAMES = [
+ "package.json", "pyproject.toml", "setup.py", "setup.cfg", "requirements.txt", "Pipfile", "Cargo.toml", "go.mod", "composer.json",
+ "Gemfile", "build.gradle", "build.gradle.kts", "settings.gradle", "pom.xml", "deno.json",
+];
+
+function put(out: Map<string, string>, name: string, version: string): void {
+ const n = name.trim();
+ const v = version.trim();
+ if (!n || !v || n.length > 214 || v.length > 128) return;
+ if (!out.has(n)) out.set(n, v);
+}
+
+function parseJson(text: string): unknown {
+ try {
+ return JSON.parse(text);
+ } catch {
+ return null;
+ }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function npmLock(text: string, out: Map<string, string>): void {
+ const doc = parseJson(text);
+ if (!isRecord(doc)) return;
+ if (isRecord(doc.packages)) {
+ for (const [key, value] of Object.entries(doc.packages)) {
+ if (!key || !isRecord(value) || typeof value.version !== "string") continue;
+ const at = key.lastIndexOf("node_modules/");
+ if (at === -1) continue;
+ put(out, key.slice(at + "node_modules/".length), value.version);
+ }
+ return;
+ }
+ const walk = (deps: unknown): void => {
+ if (!isRecord(deps)) return;
+ for (const [name, value] of Object.entries(deps)) {
+ if (!isRecord(value)) continue;
+ if (typeof value.version === "string") put(out, name, value.version);
+ walk(value.dependencies);
+ }
+ };
+ walk(doc.dependencies);
+}
+
+function pnpmLock(text: string, out: Map<string, string>): void {
+ // v5/v6: ` /[email protected]:` or ` /name/1.2.3:`; v9: ` [email protected]:` / ` '@scope/[email protected](peer@x)':`.
+ let section = "";
+ for (const line of text.split("\n")) {
+ if (/^\S/.test(line)) section = line.replace(/:.*$/, "");
+ if (section !== "packages" && section !== "snapshots") continue;
+ const match = /^ {2}['"]?\/?((?:@[^@/\s'"]+\/)?[^@/\s'"(]+)[@/]([0-9][^(:'"\s]*)/.exec(line);
+ if (match) put(out, match[1]!, match[2]!);
+ }
+}
+
+function yarnLock(text: string, out: Map<string, string>): void {
+ let names: string[] = [];
+ for (const line of text.split("\n")) {
+ if (/^\S/.test(line) && line.trimEnd().endsWith(":")) {
+ names = line.slice(0, -1).split(",").map((spec) => spec.trim().replace(/^"|"$/g, "")).map((spec) => {
+ const at = spec.lastIndexOf("@");
+ return at > 0 ? spec.slice(0, at) : spec;
+ }).filter(Boolean);
+ continue;
+ }
+ const version = /^ {2}version:?\s+"?([^"\s]+)"?/.exec(line);
+ if (version && names.length) {
+ for (const name of names) put(out, name, version[1]!);
+ names = [];
+ }
+ }
+}
+
+function bunLock(text: string, out: Map<string, string>): void {
+ // `"name": ["[email protected]", ...]` in the "packages" object (JSONC).
+ const re = /"([^"]+)":\s*\[\s*"((?:@[^@"]+\/)?[^@"]+)@([^"]+)"/g;
+ for (let match = re.exec(text); match; match = re.exec(text)) put(out, match[2]!, match[3]!.replace(/^npm:/, ""));
+}
+
+/** TOML `[[package]]` tables with `name` and `version` (Cargo.lock, poetry.lock, uv.lock, pdm.lock). */
+function tomlPackages(text: string, out: Map<string, string>): void {
+ let name: string | null = null;
+ let version: string | null = null;
+ let inPackage = false;
+ const flush = () => {
+ if (inPackage && name && version) put(out, name, version);
+ name = null;
+ version = null;
+ };
+ for (const line of text.split("\n")) {
+ if (/^\s*\[/.test(line)) {
+ if (/^\s*\[\[package\]\]\s*$/.test(line)) {
+ flush();
+ inPackage = true;
+ } else if (/^\s*\[\[?[^\]]*\]\]?\s*$/.test(line) && !/^\s*\[package\./.test(line)) {
+ flush();
+ inPackage = false;
+ }
+ continue;
+ }
+ if (!inPackage) continue;
+ const n = /^name\s*=\s*"([^"]+)"/.exec(line);
+ if (n && name === null) name = n[1]!;
+ const v = /^version\s*=\s*"([^"]+)"/.exec(line);
+ if (v && version === null) version = v[1]!;
+ }
+ flush();
+}
+
+function pipfileLock(text: string, out: Map<string, string>): void {
+ const doc = parseJson(text);
+ if (!isRecord(doc)) return;
+ for (const group of ["default", "develop"]) {
+ const deps = doc[group];
+ if (!isRecord(deps)) continue;
+ for (const [name, value] of Object.entries(deps)) if (isRecord(value) && typeof value.version === "string") put(out, name, value.version.replace(/^==/, ""));
+ }
+}
+
+function requirements(text: string, out: Map<string, string>): void {
+ for (const line of text.split("\n")) {
+ const match = /^\s*([A-Za-z0-9][A-Za-z0-9._-]*)(?:\[[^\]]*\])?\s*===?\s*([^\s;#\\]+)/.exec(line);
+ if (match) put(out, match[1]!, match[2]!);
+ }
+}
+
+function goSum(text: string, out: Map<string, string>): void {
+ for (const line of text.split("\n")) {
+ const match = /^(\S+)\s+(v[^\s/]+)(\/go\.mod)?\s+h1:/.exec(line);
+ if (match && !match[3]) put(out, match[1]!, match[2]!);
+ }
+ if (out.size === 0) {
+ for (const line of text.split("\n")) {
+ const match = /^(\S+)\s+(v[^\s/]+)\/go\.mod\s+h1:/.exec(line);
+ if (match) put(out, match[1]!, match[2]!);
+ }
+ }
+}
+
+function composerLock(text: string, out: Map<string, string>): void {
+ const doc = parseJson(text);
+ if (!isRecord(doc)) return;
+ for (const group of ["packages", "packages-dev"]) {
+ const list = doc[group];
+ if (!Array.isArray(list)) continue;
+ for (const item of list) if (isRecord(item) && typeof item.name === "string" && typeof item.version === "string") put(out, item.name, item.version);
+ }
+}
+
+function gemfileLock(text: string, out: Map<string, string>): void {
+ let specs = false;
+ for (const line of text.split("\n")) {
+ if (/^ {2}specs:\s*$/.test(line)) {
+ specs = true;
+ continue;
+ }
+ if (/^\S/.test(line)) specs = false;
+ if (!specs) continue;
+ const match = /^ {4}([^\s(]+) \(([^)]+)\)\s*$/.exec(line);
+ if (match) put(out, match[1]!, match[2]!);
+ }
+}
+
+function gradleLock(text: string, out: Map<string, string>): void {
+ for (const line of text.split("\n")) {
+ const match = /^([^#\s:=]+:[^\s:=]+):([^\s:=]+)=/.exec(line);
+ if (match) put(out, match[1]!, match[2]!);
+ }
+}
+
+function denoLock(text: string, out: Map<string, string>): void {
+ const doc = parseJson(text);
+ if (!isRecord(doc)) return;
+ for (const group of ["npm", "jsr"]) {
+ const list = isRecord(doc[group]) ? doc[group] : isRecord(doc.packages) && isRecord((doc.packages as Record<string, unknown>)[group]) ? (doc.packages as Record<string, unknown>)[group] : null;
+ if (!isRecord(list)) continue;
+ for (const key of Object.keys(list)) {
+ const at = key.lastIndexOf("@");
+ if (at > 0) put(out, key.slice(0, at), key.slice(at + 1).replace(/_.*$/, ""));
+ }
+ }
+}
+
+/** The resolved name -> version map of one lockfile's text (empty for an unknown or unparsable one). */
+export function resolvedVersions(lockfileName: string, text: string): Map<string, string> {
+ const out = new Map<string, string>();
+ try {
+ switch (LOCKFILE_ECOSYSTEMS[lockfileName]) {
+ case "npm": npmLock(text, out); break;
+ case "pnpm": pnpmLock(text, out); break;
+ case "yarn": yarnLock(text, out); break;
+ case "bun": bunLock(text, out); break;
+ case "poetry": case "uv": case "pdm": case "cargo": tomlPackages(text, out); break;
+ case "pipenv": pipfileLock(text, out); break;
+ case "pip": requirements(text, out); break;
+ case "go": goSum(text, out); break;
+ case "composer": composerLock(text, out); break;
+ case "bundler": gemfileLock(text, out); break;
+ case "gradle": gradleLock(text, out); break;
+ case "deno": denoLock(text, out); break;
+ default: break;
+ }
+ } catch {
+ // A malformed lockfile: what was read so far.
+ }
+ return out;
+}
+
+/** The lockfile basename `toolchainProject` reads, or null when the name is not one it knows. */
+export function lockfileEcosystem(name: string): Ecosystem | null {
+ return LOCKFILE_ECOSYSTEMS[name] ?? null;
+}
+
+/**
+ * One subproject's record. `lockfile` is workspace-relative; `manifests` the
+ * manifest names present beside it (workspace-relative); `text` the
+ * lockfile's content.
+ */
+export function toolchainProject(lockfile: string, manifests: readonly string[], text: string): ToolchainProject | null {
+ const name = lockfile.split("/").at(-1) ?? "";
+ const ecosystem = lockfileEcosystem(name);
+ if (!ecosystem) return null;
+ const dir = lockfile.includes("/") ? lockfile.slice(0, lockfile.lastIndexOf("/")) : ".";
+ const all = [...resolvedVersions(name, text)].sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+ const kept = all.slice(0, MAX_RESOLVED_PER_PROJECT);
+ return { dir, ecosystem, lockfile, manifests: [...manifests].sort(), resolved: Object.fromEntries(kept), count: all.length, truncated: all.length > kept.length };
+}
+
+/** Projects in a stable order (by dir, then lockfile), at most MAX_TOOLCHAIN_PROJECTS. */
+export function sortToolchainProjects(projects: ToolchainProject[]): ToolchainProject[] {
+ return projects
+ .sort((left, right) => (left.dir < right.dir ? -1 : left.dir > right.dir ? 1 : left.lockfile < right.lockfile ? -1 : left.lockfile > right.lockfile ? 1 : 0))
+ .slice(0, MAX_TOOLCHAIN_PROJECTS);
+}
diff --git a/apps/server/src/session-archive/files-used-policy.ts b/apps/server/src/session-archive/files-used-policy.ts
new file mode 100644
index 00000000..15a93c41
--- /dev/null
+++ b/apps/server/src/session-archive/files-used-policy.ts
@@ -0,0 +1,319 @@
+/**
+ * Files used (backend spec 19.7, `policy.files_used`): each turn's state
+ * document lists every file the agent's own tool calls used, and the chain
+ * carries the bytes of the allowed ones, so a replay can stage what the
+ * start snapshot lacks.
+ *
+ * files_used: [{ path, scope, op, size, sha256, captured, reason, call_id? }]
+ *
+ * `path` is relative to the session folder for `scope: "project"`, else
+ * absolute; `scope` is `project`, `tmp`, `home` or `outside`; `op` is the
+ * strongest use seen (`write` > `exec` > `read`); `size` and `sha256` are
+ * the file's when the turn ended (or when its copy was kept), null when it
+ * was gone or, for `sha256`, over the per-file cap. `captured` says whether
+ * the chain holds the bytes after this state; `reason` is `captured`, or
+ * why not: `dependency_dir` (node_modules, .venv, vendor, package caches:
+ * rebuilt from the state's `dependencies`), `build_output` (dist, build,
+ * target, ...), `denylisted` (credentials, keys, .env, tokens, system
+ * files, the app's own state), `not_allowlisted` (home settings outside the
+ * config allowlist), `too_large` (over the per-file or the session cap:
+ * hash only) or `missing` (gone before it could be read).
+ *
+ * The sources are the agent's own actions only (no interception of what
+ * other programs open): the paths of its file tools, the files its shell
+ * commands name (files-used-shell.ts), and, at the end of each tool call,
+ * the temp files those calls named or created in a temp folder they named.
+ * Temp files and allowlisted home config are copied into a per-session
+ * store when the call ends (a screenshot deleted later is kept), home
+ * config scrubbed first; project and other outside files are archived by
+ * the chain's own scan. The per-user switch (OMNIRUSH_FILES_USED=0, the
+ * app setting) and the server's `policy.files_used` both have to allow it.
+ *
+ * This module is the pure part: the item shape, the reasons, the caps, where a
+ * file is and what may happen to its bytes, the home config allowlist and
+ * its line filters. No I/O and no uploader imports (the caller runs its own
+ * secret scrubber over a scrubbed home config). Identical, byte for byte,
+ * in the CLI (capture/session-archive/) and the desktop app
+ * (apps/server/src/session-archive/).
+ */
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+import { scrubGitConfig } from "./git-scrub.js";
+import { isSecretFile, isSecretFolder } from "../context/privacy.js";
+
+export type FilesUsedScope = "project" | "tmp" | "home" | "outside";
+export type FilesUsedOp = "read" | "write" | "exec";
+export type FilesUsedReason = "captured" | "dependency_dir" | "build_output" | "denylisted" | "not_allowlisted" | "too_large" | "missing";
+
+/** One `files_used` item of a state document. */
+export type FilesUsedItem = {
+ path: string;
+ scope: FilesUsedScope;
+ op: FilesUsedOp;
+ size: number | null;
+ sha256: string | null;
+ captured: boolean;
+ reason: FilesUsedReason;
+ /** The tool call that first used the file, when known. */
+ call_id?: string;
+};
+
+/**
+ * A use the tracker recorded, before the archive decides `captured`:
+ * `plan` says how the bytes reach the chain (its own scan, a staged copy)
+ * or why they never do.
+ */
+export type PendingUse = Omit<FilesUsedItem, "captured" | "reason"> & {
+ plan: "scan" | "staged" | "hold";
+ reason: FilesUsedReason;
+ /** Where the chain holds the bytes (`__outside__/...` for a file outside the session folder). */
+ archive_path?: string;
+ /** The turn whose state lists it. */
+ turn?: number;
+};
+
+export const FILES_USED_REASONS: readonly FilesUsedReason[] = ["captured", "dependency_dir", "build_output", "denylisted", "not_allowlisted", "too_large", "missing"];
+/** A used file larger than this is listed with its size only (no copy, no hash). */
+export const MAX_FILES_USED_FILE_BYTES = 64 * 1024 * 1024;
+/** What staged copies may add to one session's chain; past it a file is `too_large`. */
+export const MAX_FILES_USED_SESSION_BYTES = 256 * 1024 * 1024;
+export type FilesUsedLimits = { maxFileBytes: number; maxSessionBytes: number };
+export const DEFAULT_FILES_USED_LIMITS: FilesUsedLimits = { maxFileBytes: MAX_FILES_USED_FILE_BYTES, maxSessionBytes: MAX_FILES_USED_SESSION_BYTES };
+/** Items per state document, and allowlisted home config read for scrubbing, at most. */
+export const MAX_FILES_USED_ITEMS = 2_000;
+export const MAX_HOME_CONFIG_BYTES = 256 * 1024;
+
+const OP_RANK: Record<FilesUsedOp, number> = { write: 3, exec: 2, read: 1 };
+export function strongerOp(left: FilesUsedOp, right: FilesUsedOp): FilesUsedOp {
+ return OP_RANK[right] > OP_RANK[left] ? right : left;
+}
+
+/**
+ * OMNIRUSH_ARCHIVE_FILES_USED, the per-user switch: "0"/"false"/"off"/"no"
+ * turns it off whatever the server says; "1"/"true"/"on"/"yes" turns it on
+ * (tests; the server's policy still has to offer capture v2); anything else
+ * follows the server's `policy.files_used`.
+ */
+export const FILES_USED_ENV = "OMNIRUSH_ARCHIVE_FILES_USED";
+export function filesUsedOverride(env: NodeJS.ProcessEnv = process.env): boolean | null {
+ const value = (env[FILES_USED_ENV] ?? "").trim().toLowerCase();
+ if (["1", "true", "on", "yes"].includes(value)) return true;
+ if (["0", "false", "off", "no"].includes(value)) return false;
+ return null;
+}
+
+// --- where a file is, and whether its bytes may be archived ------------------------------
+
+/** Dependency and cache folders (any path component): hash only, rebuilt from the lockfiles. */
+export const DEPENDENCY_DIR_NAMES = new Set([
+ "node_modules", ".venv", "venv", "__pycache__", ".tox", ".nox", ".mypy_cache", ".pytest_cache", ".ruff_cache", ".turbo", ".parcel-cache",
+ ".cache", ".gradle", ".dart_tool", "Pods", "vendor", "bower_components", "site-packages", "dist-packages", ".pnpm-store", ".yarn",
+]);
+/** Build output folders (any path component): hash only. */
+export const BUILD_OUTPUT_DIR_NAMES = new Set(["dist", "build", "target", "out", ".next", ".nuxt", ".svelte-kit", "DerivedData"]);
+
+const PSEUDO = /^\/(?:proc|sys|dev|run)(?:\/|$)|^\/private\/var\/run(?:\/|$)|^\/System\/Volumes(?:\/|$)/;
+const SYSTEM = /^\/(?:usr|etc|bin|sbin|lib|lib32|lib64|libx32|boot|snap|opt\/homebrew\/Cellar|var\/lib|var\/cache|var\/log|nix\/store|System|Library|Applications|private\/etc|private\/var\/db)(?:\/|$)/;
+const WINDOWS_SYSTEM = /^[A-Za-z]:[\\/](?:Windows|Program Files|Program Files \(x86\)|ProgramData)(?:[\\/]|$)/i;
+/** Under the home: caches, package stores and other apps' state (never archived; rebuilt or irrelevant). */
+const HOME_CACHE_DIRS = [
+ ".cache", ".npm", ".pnpm-store", ".yarn", ".bun/install", ".cargo/registry", ".cargo/git", ".rustup", ".gradle", ".m2", ".nuget",
+ ".local/share/pnpm", ".local/share/opencode", ".local/state/opencode", ".config/opencode", ".omnirush", ".pi", ".config/omnirush",
+ ".config/OmniRush", "Library/Application Support/OmniRush", "AppData/Roaming/OmniRush", "Library/Caches", "AppData/Local/Temp",
+ "AppData/Local/npm-cache", "go/pkg/mod", ".pyenv/versions", ".nvm/versions", ".volta/tools", ".local/lib", ".local/pipx", ".conda/pkgs",
+ "miniconda3/pkgs", "anaconda3/pkgs", ".vscode-server", ".vscode", ".cursor", ".codex", ".claude", ".agents", ".local/share/Trash",
+];
+/** Under the home: never read, whatever the allowlist says (credential stores, keychains, browser profiles). */
+const HOME_SECRET_DIRS = [
+ ".ssh", ".aws", ".gnupg", ".kube", ".docker", ".azure", ".config/gh", ".config/gcloud", ".config/hub", ".password-store",
+ ".local/share/keyrings", "Library/Keychains", "Library/Cookies", "Library/Application Support/Google", "Library/Application Support/Firefox",
+ "Library/Application Support/BraveSoftware", "Library/Safari", ".mozilla", ".config/google-chrome", ".config/chromium",
+ "AppData/Roaming/Microsoft/Credentials", "AppData/Local/Microsoft/Credentials", "AppData/Local/Google", "AppData/Roaming/Mozilla",
+];
+
+export type HomeConfigKind = "git" | "npmrc" | "ini" | "text";
+
+/**
+ * Home config files whose scrubbed copy is archived when a tool or program
+ * read them (scope P5): git's, the package managers' (registry lines only),
+ * pip/uv index settings (no userinfo) and the config of known dev tools.
+ * Shell rc files are not here: the session context records their aliases.
+ */
+export function homeConfigKind(homeRel: string): HomeConfigKind | null {
+ const rel = homeRel.replaceAll("\\", "/");
+ if ([".gitconfig", ".config/git/config"].includes(rel)) return "git";
+ if ([".gitignore_global", ".gitignore", ".config/git/ignore", ".config/git/attributes", ".gitattributes"].includes(rel)) return "text";
+ if ([".npmrc", ".yarnrc", ".yarnrc.yml", ".config/pnpm/rc", "Library/Preferences/pnpm/rc", "AppData/Local/pnpm/config/rc", ".bunfig.toml"].includes(rel)) return "npmrc";
+ if ([".config/pip/pip.conf", ".pip/pip.conf", "pip/pip.ini", "AppData/Roaming/pip/pip.ini", "Library/Application Support/pip/pip.conf", ".config/uv/uv.toml", ".pydistutils.cfg", ".condarc", ".cargo/config.toml", ".cargo/config", ".m2/settings.xml"].includes(rel)) return "ini";
+ if ([".editorconfig", ".prettierrc", ".prettierrc.json", ".prettierrc.yaml", ".prettierrc.yml", ".eslintrc", ".eslintrc.json", ".eslintrc.js", ".eslintrc.yml", ".pylintrc", ".flake8", ".pycodestyle", ".isort.cfg", ".tool-versions", ".nvmrc", ".node-version", ".python-version", ".ruby-version", ".mypy.ini", ".clang-format", ".rustfmt.toml", ".jshintrc", ".babelrc", ".browserslistrc"].includes(rel)) return "text";
+ if (/^\.config\/(?:ruff|black|pnpm|starship|mise|rtx|yamllint|flake8|pycodestyle|pylintrc|mypy|direnv|bat|fd|ripgrep|jj|lazygit|helix|nvim|zellij|tmux|alacritty|kitty|wezterm|yarn|prettier|eslint|stylua|taplo|rustfmt|clangd|pre-commit|uv|pip|git)(?:\/[^/]+)*\/[^/]+$/.test(rel) && !/(?:^|\/)(?:hosts\.ya?ml|credentials?.*|auth.*|token.*|.*\.(?:key|pem|db|sqlite))$/i.test(rel)) return "text";
+ if (/^\.config\/(?:starship|ruff|black|uv|mise)\.toml$/.test(rel)) return "text";
+ return null;
+}
+
+export type UseContext = {
+ /** The app's credential rule for a path relative to its folder (the uploader's denylist); the policy's own rules apply too. */
+ isCredentialPath?: (relPath: string) => boolean;
+ /** The session folder, as given and as its real path. */
+ roots: readonly string[];
+ home: string | null;
+ /** Temp folders, as given and as real paths. */
+ temps: readonly string[];
+ /** App state folders: never listed. */
+ appDirs: readonly string[];
+ includeCredentialFiles?: boolean;
+};
+
+function within(parent: string, child: string): string | null {
+ const rel = relative(parent, child);
+ if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return null;
+ return rel.split(sep).join("/");
+}
+
+function inside(parent: string, child: string): boolean {
+ return resolve(parent) === resolve(child) || within(parent, child) !== null;
+}
+
+const ENV_FILE = /(?:^|\/)\.env(?:\.|$)|(?:^|\/)[^/]*\.env$/i;
+const SECRET_WORD = /(?:^|[/._-])(?:secrets?|credentials?|tokens?|passwords?|passwd|private[_-]?key|api[_-]?keys?)(?:[/._-]|$)/i;
+
+/** Whether a path names a file that must never be archived (anywhere). */
+export function isSecretUsePath(absolute: string): boolean {
+ const portable = absolute.replaceAll("\\", "/");
+ if (ENV_FILE.test(portable)) return !/\.env\.(?:example|sample|template|dist|defaults)$/i.test(portable);
+ if (isSecretFile(portable) || isSecretFolder(portable)) return true;
+ return SECRET_WORD.test(portable.split("/").at(-1) ?? "");
+}
+
+export type UseClass = {
+ scope: FilesUsedScope;
+ /** The item's path: project-relative, else absolute. */
+ path: string;
+ /** How the bytes reach the chain, or why they never do. */
+ plan: "scan" | "stage" | "hold";
+ reason: FilesUsedReason;
+ /** For a staged home config: how its copy is scrubbed. */
+ scrub?: HomeConfigKind;
+ archivePath?: string;
+};
+
+/** Why a folder's files are rebuilt rather than archived: a dependency or cache folder, or build output. */
+export function regenerableReason(portableRel: string): "dependency_dir" | "build_output" | null {
+ const parts = portableRel.split("/").slice(0, -1);
+ if (parts.some((part) => part === ".git")) return null;
+ if (parts.some((part) => DEPENDENCY_DIR_NAMES.has(part))) return "dependency_dir";
+ if (parts.some((part) => BUILD_OUTPUT_DIR_NAMES.has(part))) return "build_output";
+ return null;
+}
+
+/** `/tmp/x` -> `__outside__/tmp/x`, `C:\\x\\y` -> `__outside__/C/x/y` (outside.ts outsideArchivePath); null when it cannot be one. */
+export function usedArchivePath(absolute: string, win32 = sep === "\\"): string | null {
+ if (!absolute || absolute.length > 4_096 || absolute.includes("\0")) return null;
+ let parts: string[];
+ if (win32) {
+ const match = /^([A-Za-z]):[\\/](.*)$/.exec(absolute);
+ if (!match) return null;
+ parts = [match[1]!.toUpperCase(), ...match[2]!.split(/[\\/]/)];
+ } else {
+ if (!absolute.startsWith("/")) return null;
+ parts = absolute.slice(1).split("/");
+ }
+ if (parts.length < 2 || parts.some((part) => part === "" || part === "." || part === "..")) return null;
+ return `__outside__/${parts.join("/")}`;
+}
+
+/**
+ * Where an absolute (canonical) path is and what may happen to its bytes;
+ * null for a path that is never listed (the app's own state, pseudo file
+ * systems, a relative path).
+ */
+export function classifyUse(absolute: string, context: UseContext): UseClass | null {
+ if (!isAbsolute(absolute)) return null;
+ const portable = absolute.replaceAll("\\", "/");
+ if (PSEUDO.test(portable)) return null;
+ if (context.appDirs.some((dir) => inside(dir, absolute))) return null;
+ const credentials = context.includeCredentialFiles !== true;
+ for (const root of context.roots) {
+ const rel = within(root, absolute);
+ if (rel === null) continue;
+ if (credentials && (isSecretUsePath(absolute) || context.isCredentialPath?.(rel) === true)) return { scope: "project", path: rel, plan: "hold", reason: "denylisted" };
+ const regenerable = regenerableReason(rel);
+ if (regenerable) return { scope: "project", path: rel, plan: "hold", reason: regenerable };
+ return { scope: "project", path: rel, plan: "scan", reason: "captured" };
+ }
+ const archivePath = usedArchivePath(absolute) ?? undefined;
+ const outsideRel = portable.replace(/^[A-Za-z]:/, "").replace(/^\/+/, "");
+ const secret = credentials && (isSecretUsePath(absolute) || context.isCredentialPath?.(outsideRel) === true);
+ const hold = (scope: FilesUsedScope, reason: FilesUsedReason): UseClass => ({ scope, path: absolute, plan: "hold", reason });
+ if (context.temps.some((temp) => within(temp, absolute) !== null)) {
+ if (secret) return hold("tmp", "denylisted");
+ const regenerable = regenerableReason(outsideRel);
+ if (regenerable) return hold("tmp", regenerable);
+ return archivePath ? { scope: "tmp", path: absolute, plan: "stage", reason: "captured", archivePath } : hold("tmp", "denylisted");
+ }
+ const homeRel = context.home ? within(context.home, absolute) : null;
+ if (homeRel !== null) {
+ if (HOME_SECRET_DIRS.some((dir) => homeRel === dir || homeRel.startsWith(`${dir}/`))) return hold("home", "denylisted");
+ const kind = homeConfigKind(homeRel);
+ // An allowlisted config is scrubbed before it is staged, so its name alone (.npmrc) does not hold it.
+ if (kind && archivePath) return { scope: "home", path: absolute, plan: "stage", reason: "captured", scrub: kind, archivePath };
+ if (secret) return hold("home", "denylisted");
+ if (HOME_CACHE_DIRS.some((dir) => homeRel === dir || homeRel.startsWith(`${dir}/`))) return hold("home", "dependency_dir");
+ const regenerable = regenerableReason(homeRel);
+ if (regenerable) return hold("home", regenerable);
+ const first = homeRel.split("/")[0] ?? "";
+ // Settings and app data (dot folders, rc files, Library, AppData) only through the allowlist.
+ if (first.startsWith(".") || /^(?:library|appdata|snap|application data|local settings)$/i.test(first)) return hold("home", "not_allowlisted");
+ return archivePath ? { scope: "home", path: absolute, plan: "scan", reason: "captured", archivePath } : hold("home", "denylisted");
+ }
+ if (secret) return hold("outside", "denylisted");
+ if ((sep === "/" && SYSTEM.test(portable)) || WINDOWS_SYSTEM.test(absolute)) return hold("outside", "denylisted");
+ const regenerable = regenerableReason(outsideRel);
+ if (regenerable) return hold("outside", regenerable);
+ return archivePath ? { scope: "outside", path: absolute, plan: "scan", reason: "captured", archivePath } : hold("outside", "denylisted");
+}
+
+// --- scrubbing an allowlisted home config -----------------------------------------------
+
+const URL_USERINFO = /(\b[a-z][a-z0-9+.-]*:\/\/)[^/\s@"']+@/gi;
+const NPM_SECRET_LINE = /^\s*(?:\/\/|["']?\/\/)|(?:^|[\s.:@"'])(?:_auth|_authtoken|_authToken|_password|password|token|username|email|certfile|keyfile|cert|key|npmAuthToken|npmAuthIdent|npmAlwaysAuth|always-auth|otp)["']?\s*[=:]/i;
+const INI_SECRET_KEY = /^\s*["']?[A-Za-z0-9_.@:/-]*(?:password|passwd|token|secret|auth|credential|username|user|cert|key|cookie|private)[A-Za-z0-9_.-]*["']?\s*[=:]/i;
+const XML_SECRET = /<\s*(?:password|username|privateKey|passphrase|token)\b[^>]*>[^<]*<\s*\/\s*(?:password|username|privateKey|passphrase|token)\s*>/gi;
+
+/**
+ * An allowlisted home config as archived: git's with its credentials,
+ * extraheaders and URL userinfo removed (git-scrub.ts); npm/yarn/pnpm rc
+ * keeping no auth, scope-auth (`//host/:`), user or cert line; ini/toml
+ * keeping no secret-named key; every URL without userinfo. The caller
+ * runs its own secret scrubber over the result. Null for text that is too
+ * large or not text: the file is held.
+ */
+export function scrubHomeConfig(kind: HomeConfigKind, text: string): string | null {
+ if (text.length > MAX_HOME_CONFIG_BYTES || text.includes("\0") || text.includes("\uFFFD")) return null;
+ if (kind === "git") text = scrubGitConfig(text).text;
+ else if (kind === "npmrc") text = text.split("\n").map((line) => (NPM_SECRET_LINE.test(line) ? "# [omnirush: removed]" : line)).join("\n");
+ else if (kind === "ini") text = text.split("\n").map((line) => (INI_SECRET_KEY.test(line) ? "# [omnirush: removed]" : line)).join("\n").replace(XML_SECRET, "<!-- [omnirush: removed] -->");
+ return text.replace(URL_USERINFO, "$1");
+}
+
+/**
+ * The state document's `files_used` for the pending items of an archive:
+ * `captured` from what the chain holds after it (`held`: the archive paths
+ * of every file the chain holds). A file the chain was to hold but does not
+ * is `missing` when it was gone, else `too_large` (the scan's caps).
+ */
+export function finalizeFilesUsed(pending: readonly PendingUse[], held: ReadonlySet<string>): FilesUsedItem[] {
+ const out: FilesUsedItem[] = [];
+ for (const item of pending) {
+ const { plan, archive_path: archivePath, turn: _turn, reason: planned, ...rest } = item;
+ const where = archivePath ?? (item.scope === "project" ? item.path : usedArchivePath(item.path) ?? undefined);
+ let captured = false;
+ let reason: FilesUsedReason = planned;
+ if (plan !== "hold") {
+ captured = where !== undefined && held.has(where);
+ reason = captured ? "captured" : item.size === null ? "missing" : planned === "captured" ? "too_large" : planned;
+ }
+ out.push({ ...rest, captured, reason });
+ }
+ return out.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
+}
diff --git a/apps/server/src/session-archive/files-used-shell.ts b/apps/server/src/session-archive/files-used-shell.ts
new file mode 100644
index 00000000..1829752c
--- /dev/null
+++ b/apps/server/src/session-archive/files-used-shell.ts
@@ -0,0 +1,592 @@
+/**
+ * Files used: the files a shell command reads, writes, runs or imports,
+ * from its text alone. The command is split into simple commands at the
+ * control operators (`;`, `&&`, `||`, `|`, `&`, newlines, `$(...)`); a `cd`
+ * moves the folder the following ones resolve against; redirections are
+ * writes (`>`, `>>`, `&>`, `2>`) or reads (`<`); then each command word is
+ * looked up:
+ *
+ * - readers (`cat`, `head`, `jq`, `diff`, ...) read their path arguments;
+ * pattern-first tools (`grep`, `rg`, `sed`, `awk`) read every path
+ * argument after the pattern (`-f` script files too), `sed -i` writes;
+ * - `cp`/`mv`/`install`/`rsync` read their sources and write the target,
+ * `tee`/`touch`/`truncate` write;
+ * - interpreters (`python`, `node`, `bash`, `ruby`, ...) run their script
+ * (`exec`), read the path arguments after it, and `-c`/`-e` code and
+ * heredoc bodies give the quoted paths they name (`open('x', 'w')` is a
+ * write); `source`/`.` and `./script` run a file; `node -r ./x` reads;
+ * - build and test tools read the config files they always load
+ * (`package.json`, `tsconfig.json`, `pytest.ini`, `Makefile`, ...) and
+ * the ones named with `-f`/`-c`/`--config`/`-r`.
+ *
+ * Any other path-looking word counts as a read. Candidates are absolute;
+ * whether each is a file is checked later. Nothing here touches the disk.
+ * Identical in the CLI and the desktop app.
+ */
+import { isAbsolute, join, resolve } from "node:path";
+
+export type ShellUseOp = "read" | "write" | "exec";
+export type ShellUse = { path: string; op: ShellUseOp };
+
+const MAX_COMMAND_CHARS = 256 * 1024;
+const MAX_PATH_CHARS = 4_096;
+const MAX_USES = 512;
+
+type Token = { word: string } | { op: string };
+
+const isWord = (token: Token | undefined): token is { word: string } => token !== undefined && "word" in token;
+
+/**
+ * Shell tokens: words (quotes and escapes resolved) and operators. Heredoc
+ * bodies come back as a `heredoc` operator followed by one word holding the
+ * body. A word holding `$` or a backtick substitution keeps it as text.
+ */
+export function shellTokens(command: string): Token[] {
+ const text = command.length > MAX_COMMAND_CHARS ? command.slice(0, MAX_COMMAND_CHARS) : command;
+ const tokens: Token[] = [];
+ const heredocs: Array<{ delimiter: string; strip: boolean }> = [];
+ let word = "";
+ let started = false;
+ const end = () => {
+ if (started) tokens.push({ word });
+ word = "";
+ started = false;
+ };
+ let index = 0;
+ while (index < text.length) {
+ const char = text[index]!;
+ const next = text[index + 1];
+ if (char === "'") {
+ const close = text.indexOf("'", index + 1);
+ word += close < 0 ? text.slice(index + 1) : text.slice(index + 1, close);
+ started = true;
+ index = close < 0 ? text.length : close + 1;
+ continue;
+ }
+ if (char === '"') {
+ index += 1;
+ while (index < text.length && text[index] !== '"') {
+ if (text[index] === "\\" && index + 1 < text.length && '"\\$`'.includes(text[index + 1]!)) index += 1;
+ word += text[index]!;
+ index += 1;
+ }
+ index += 1;
+ started = true;
+ continue;
+ }
+ if (char === "\\" && next !== undefined) {
+ if (next !== "\n") {
+ word += next;
+ started = true;
+ }
+ index += 2;
+ continue;
+ }
+ if (char === "#" && !started) {
+ // A comment runs to the end of the line.
+ const newline = text.indexOf("\n", index);
+ index = newline < 0 ? text.length : newline;
+ continue;
+ }
+ if (char === "$" && next === "(") {
+ end();
+ tokens.push({ op: "(" });
+ index += 2;
+ continue;
+ }
+ if (char === "`") {
+ end();
+ tokens.push({ op: ";" });
+ index += 1;
+ continue;
+ }
+ if (char === "\n") {
+ end();
+ tokens.push({ op: ";" });
+ index += 1;
+ // Heredoc bodies start on the line after their operator.
+ while (heredocs.length > 0) {
+ const { delimiter, strip } = heredocs.shift()!;
+ const body: string[] = [];
+ while (index < text.length) {
+ const newline = text.indexOf("\n", index);
+ const line = newline < 0 ? text.slice(index) : text.slice(index, newline);
+ index = newline < 0 ? text.length : newline + 1;
+ if ((strip ? line.replace(/^\t+/, "") : line) === delimiter) break;
+ body.push(line);
+ }
+ tokens.push({ op: "heredoc" }, { word: body.join("\n") });
+ }
+ continue;
+ }
+ if (/\s/.test(char)) {
+ end();
+ index += 1;
+ continue;
+ }
+ if (char === "<" && next === "<" && text[index + 2] !== "<") {
+ // `<<EOF`, `<<-EOF`, `<<'EOF'`, `<< "EOF"`.
+ end();
+ let at = index + 2;
+ const strip = text[at] === "-";
+ if (strip) at += 1;
+ while (text[at] === " " || text[at] === "\t") at += 1;
+ const match = /^(['"]?)([A-Za-z0-9_.-]+)\1/.exec(text.slice(at));
+ if (match) {
+ heredocs.push({ delimiter: match[2]!, strip });
+ index = at + match[0].length;
+ } else index += 2;
+ continue;
+ }
+ // Redirections, with an optional fd in front (`2>`, `&>`, `>>`, `>|`, `<`, `<<<`).
+ const redirect = /^(?:[0-9]*>>|[0-9]*>\||&>>|&>|[0-9]*>&?|<<<|[0-9]*<)/.exec(started && /^[0-9]+$/.test(word) ? `${word}${text.slice(index)}` : text.slice(index));
+ if ((char === ">" || char === "<" || (char === "&" && next === ">")) && redirect) {
+ const fdPrefix = started && /^[0-9]+$/.test(word) ? word.length : 0;
+ if (fdPrefix) {
+ word = "";
+ started = false;
+ } else end();
+ const op = redirect[0].slice(fdPrefix);
+ tokens.push({ op: op.replace(/^[0-9]+/, "") });
+ index += op.length;
+ continue;
+ }
+ if (char === "&" && next === "&") {
+ end();
+ tokens.push({ op: "&&" });
+ index += 2;
+ continue;
+ }
+ if (char === "|" && next === "|") {
+ end();
+ tokens.push({ op: "||" });
+ index += 2;
+ continue;
+ }
+ if (";|&()".includes(char)) {
+ end();
+ tokens.push({ op: char === "|" || char === "&" ? ";" : char });
+ index += 1;
+ continue;
+ }
+ word += char;
+ started = true;
+ index += 1;
+ }
+ end();
+ return tokens;
+}
+
+const READERS = new Set([
+ "cat", "head", "tail", "less", "more", "wc", "sort", "uniq", "cut", "nl", "tac", "od", "xxd", "hexdump", "strings", "file", "stat",
+ "md5sum", "sha1sum", "sha256sum", "sha512sum", "shasum", "b2sum", "cksum", "base64", "jq", "yq", "column", "diff", "cmp", "comm",
+ "paste", "join", "bat", "batcat", "iconv", "zcat", "gzcat", "bzcat", "xzcat", "zstdcat", "csvlook", "csvcut", "csvstat", "fold", "fmt",
+ "expand", "unexpand", "rev", "split", "readlink", "realpath", "dos2unix", "unix2dos", "pdftotext", "identify", "exiftool", "sqlite3",
+ "xmllint", "tidy", "mdcat", "glow", "view", "vim", "vi", "nano", "emacs", "code", "open", "xdg-open", "pandoc", "unzip", "gunzip", "7z",
+]);
+const PATTERN_FIRST = new Set(["grep", "egrep", "fgrep", "rg", "ag", "ack", "sed", "awk", "gawk", "mawk", "nawk"]);
+const COPIERS = new Set(["cp", "mv", "install", "rsync", "scp", "ln"]);
+const WRITERS = new Set(["tee", "touch", "truncate"]);
+const SHELLS = new Set(["bash", "sh", "zsh", "dash", "ksh", "fish", "ash"]);
+const INTERPRETERS = new Set([
+ "python", "python2", "python3", "py", "pypy", "pypy3", "node", "nodejs", "bun", "deno", "ts-node", "tsx", "ruby", "perl", "php",
+ "rscript", "julia", "lua", "luajit", "groovy", "kotlin", "scala", "swift", "elixir", "erl", "racket", "guile", "tclsh", "osascript",
+ "pwsh", "powershell", "jshell", "java",
+]);
+/** Words that run the command after them (with their own options skipped). */
+const WRAPPERS = new Set(["sudo", "env", "time", "nice", "nohup", "timeout", "exec", "command", "builtin", "stdbuf", "xargs", "caffeinate", "ionice", "taskset", "chronic", "unbuffer", "watch", "strace", "ltrace", "valgrind", "gdb", "lldb", "uv", "poetry", "pipenv", "pdm", "hatch", "rye", "conda", "mamba", "micromamba", "dotenv", "direnv", "npx", "bunx", "pnpx"]);
+/** Wrappers that take a sub-command word before the command they run (`uv run x`, `poetry run x`, `conda run -n e x`). */
+const RUN_WORDS = new Set(["run", "exec"]);
+/** Options of a wrapper that take a value (skipped with it). */
+const WRAPPER_VALUE_OPTIONS = new Set(["-u", "-g", "-n", "-p", "-C", "-k", "-s", "-o", "-e", "--name", "--prefix", "--env-file", "-I", "-L", "-P", "-d", "-a", "--with", "--python", "--package", "-w"]);
+/** Config files a tool always reads from the folder it runs in. */
+const TOOL_CONFIGS: Record<string, string[]> = {
+ npm: ["package.json", "package-lock.json", ".npmrc"],
+ pnpm: ["package.json", "pnpm-lock.yaml", "pnpm-workspace.yaml", ".npmrc"],
+ yarn: ["package.json", "yarn.lock", ".yarnrc.yml", ".yarnrc"],
+ bun: ["package.json", "bun.lock", "bunfig.toml"],
+ npx: ["package.json"],
+ tsc: ["tsconfig.json"],
+ vite: ["vite.config.ts", "vite.config.js", "vite.config.mjs", "package.json"],
+ next: ["next.config.js", "next.config.mjs", "next.config.ts", "package.json"],
+ jest: ["jest.config.js", "jest.config.ts", "package.json"],
+ vitest: ["vitest.config.ts", "vitest.config.js", "vite.config.ts", "package.json"],
+ eslint: ["eslint.config.js", "eslint.config.mjs", ".eslintrc.json", ".eslintrc.js", ".eslintrc.cjs", ".eslintrc"],
+ prettier: [".prettierrc", ".prettierrc.json", "prettier.config.js"],
+ pytest: ["pytest.ini", "pyproject.toml", "setup.cfg", "tox.ini", "conftest.py"],
+ tox: ["tox.ini", "pyproject.toml"],
+ mypy: ["mypy.ini", "pyproject.toml", "setup.cfg"],
+ ruff: ["ruff.toml", ".ruff.toml", "pyproject.toml"],
+ black: ["pyproject.toml"],
+ flake8: [".flake8", "setup.cfg", "tox.ini"],
+ pylint: [".pylintrc", "pylintrc", "pyproject.toml"],
+ pip: ["requirements.txt", "pyproject.toml", "setup.py", "setup.cfg"],
+ pip3: ["requirements.txt", "pyproject.toml", "setup.py", "setup.cfg"],
+ poetry: ["pyproject.toml", "poetry.lock"],
+ uv: ["pyproject.toml", "uv.lock"],
+ make: ["Makefile", "makefile", "GNUmakefile"],
+ cargo: ["Cargo.toml", "Cargo.lock"],
+ go: ["go.mod", "go.sum"],
+ docker: ["Dockerfile", "docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml"],
+ "docker-compose": ["docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml"],
+ composer: ["composer.json", "composer.lock"],
+ bundle: ["Gemfile", "Gemfile.lock"],
+ rake: ["Rakefile"],
+ gradle: ["build.gradle", "build.gradle.kts", "settings.gradle", "settings.gradle.kts"],
+ mvn: ["pom.xml"],
+ cmake: ["CMakeLists.txt"],
+ terraform: ["main.tf"],
+ alembic: ["alembic.ini"],
+ manage: [],
+};
+/** Options naming a file the tool reads (`-f Makefile`, `--config x`, `-r requirements.txt`). */
+const FILE_OPTIONS = new Set(["-f", "--file", "-c", "--config", "--config-file", "--rcfile", "-r", "--requirement", "--constraint", "-p", "--project", "--env-file", "--settings", "-C"]);
+const FILE_OPTION_TOOLS = new Set(["make", "docker", "docker-compose", "awk", "gawk", "pip", "pip3", "pytest", "tsc", "eslint", "prettier", "jest", "vitest", "mypy", "ruff", "pylint", "flake8", "black", "uv", "terraform", "alembic", "gradle", "mvn", "cmake", "helm", "kubectl", "ansible-playbook"]);
+/** Options of an interpreter that take a value before the script. */
+const INTERPRETER_VALUE_OPTIONS = new Set(["-W", "-X", "--import", "--loader", "--experimental-loader", "--conditions", "-C", "--inspect-port", "--max-old-space-size", "-I", "--title", "--env-file"]);
+const NODE_IMPORT_OPTIONS = new Set(["-r", "--require", "--import", "--loader", "--experimental-loader"]);
+
+function cleanPathWord(word: string): string | null {
+ if (!word || word.length > MAX_PATH_CHARS || word.includes("\0") || word.includes("\n")) return null;
+ if (word.includes("://") || /[$`*?{}[\]]/.test(word)) return null;
+ if (word === "-" || word === "--" || word === "." || word === ".." || word.startsWith("/dev/")) return null;
+ // An option's value (`head -n 5`, `cut -f 1,2`), not a file.
+ if (/^[+-]?[0-9][0-9,.:kKmMgG]*$/.test(word)) return null;
+ return word.replace(/[,;:]+$/, "") || null;
+}
+
+/** A word that looks like a path: `/abs`, `~/x`, `./x`, `../x`, `dir/file`, `file.ext`. */
+export function looksLikePath(word: string): boolean {
+ if (!word || word.startsWith("-") || word.includes("=") && !word.includes("/")) return false;
+ return /^(?:\/|~\/|\.{1,2}\/|[A-Za-z]:[\\/])/.test(word) || (word.includes("/") && !/^[a-z][a-z0-9+.-]*:/i.test(word)) || /^[^/\\\s]+\.[A-Za-z0-9]{1,12}$/.test(word);
+}
+
+/** Quoted paths a piece of code names (a `-c` script, a heredoc body), with `open(x, 'w')` as a write. */
+export function codePathUses(code: string): Array<{ word: string; op: ShellUseOp }> {
+ const out: Array<{ word: string; op: ShellUseOp }> = [];
+ const text = code.length > MAX_COMMAND_CHARS ? code.slice(0, MAX_COMMAND_CHARS) : code;
+ const writes = new Set<string>();
+ for (const match of text.matchAll(/open\(\s*(?:r|f|b)?(['"])([^'"\n]{1,4096})\1\s*,\s*(?:mode\s*=\s*)?(['"])([^'"]*)\3/g)) {
+ if (/[wax+]/.test(match[4]!)) writes.add(match[2]!);
+ }
+ for (const match of text.matchAll(/(?:writeFileSync|writeFile|appendFileSync|createWriteStream|write_text|write_bytes|to_csv|to_json|to_parquet|savefig|save|imwrite|screenshot)\(\s*(?:path\s*=\s*)?(?:Path\()?(['"`])([^'"`\n]{1,4096})\1/g)) writes.add(match[2]!);
+ for (const match of text.matchAll(/(['"`])([^'"`\n]{1,4096})\1/g)) {
+ const word = match[2]!;
+ if (!looksLikePath(word) || /\s/.test(word) && !word.startsWith("/")) continue;
+ out.push({ word, op: writes.has(word) ? "write" : "read" });
+ }
+ return out;
+}
+
+function baseName(word: string): string {
+ const name = word.split(/[\\/]/).at(-1) ?? word;
+ return name.toLowerCase().replace(/\.exe$/, "");
+}
+
+function interpreterName(word: string): string | null {
+ const name = baseName(word);
+ if (INTERPRETERS.has(name)) return name;
+ if (/^python[0-9.]*$/.test(name)) return "python";
+ if (/^pypy[0-9.]*$/.test(name)) return "python";
+ if (/^node[0-9]*$/.test(name)) return "node";
+ if (/^ruby[0-9.]*$/.test(name)) return "ruby";
+ if (/^php[0-9.]*$/.test(name)) return "php";
+ return null;
+}
+
+/** The files a shell command uses, absolute (see the module comment). Never throws. */
+export function shellCommandUses(command: string, cwd: string, home: string | null = null): ShellUse[] {
+ const out: ShellUse[] = [];
+ const seen = new Set<string>();
+ try {
+ let dir = cwd;
+ const add = (raw: string | undefined, op: ShellUseOp, at = dir) => {
+ if (out.length >= MAX_USES || raw === undefined) return;
+ const word = cleanPathWord(raw);
+ if (!word) return;
+ let path: string;
+ if (word === "~" || word.startsWith("~/")) {
+ if (!home) return;
+ path = join(home, word.slice(2));
+ } else if (word.startsWith("~")) return;
+ else path = isAbsolute(word) ? resolve(word) : resolve(at, word);
+ const key = `${op}\0${path}`;
+ if (seen.has(key)) return;
+ seen.add(key);
+ out.push({ path, op });
+ };
+ const tokens = shellTokens(command);
+ // Simple commands between control operators.
+ const commands: Array<{ words: string[]; redirects: Array<{ op: string; word: string }>; heredoc: string | null; separator: string | null }> = [];
+ let current: (typeof commands)[number] = { words: [], redirects: [], heredoc: null, separator: null };
+ for (let index = 0; index < tokens.length; index += 1) {
+ const token = tokens[index]!;
+ if (isWord(token)) {
+ current.words.push(token.word);
+ continue;
+ }
+ const op = token.op;
+ if (op === "heredoc") {
+ const body = tokens[index + 1];
+ if (isWord(body)) {
+ // The body belongs to the command that opened it (the last one with words).
+ const owner = current.words.length > 0 ? current : [...commands].reverse().find((item) => item.words.length > 0) ?? current;
+ owner.heredoc = owner.heredoc === null ? body.word : `${owner.heredoc}\n${body.word}`;
+ index += 1;
+ }
+ continue;
+ }
+ if (/^(?:>>|>\||&>>|&>|>|>&|<|<<<)$/.test(op)) {
+ const target = tokens[index + 1];
+ if (isWord(target)) {
+ current.redirects.push({ op, word: target.word });
+ index += 1;
+ }
+ continue;
+ }
+ current.separator = op;
+ commands.push(current);
+ current = { words: [], redirects: [], heredoc: null, separator: null };
+ }
+ commands.push(current);
+
+ for (const item of commands) {
+ const commandDir = dir;
+ for (const redirect of item.redirects) {
+ if (redirect.op === "<") add(redirect.word, "read", commandDir);
+ else if (redirect.op === "<<<") continue;
+ else if (redirect.op === ">&" && /^[0-9-]+$/.test(redirect.word)) continue;
+ else add(redirect.word, "write", commandDir);
+ }
+ const words = item.words.slice();
+ // Leading assignments (FOO=1 cmd) and wrappers.
+ while (words.length > 0) {
+ const first = words[0]!;
+ if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(first)) {
+ words.shift();
+ continue;
+ }
+ const name = baseName(first);
+ if (!WRAPPERS.has(name)) break;
+ words.shift();
+ if (name === "timeout" && words[0] && /^[0-9.]+[smhd]?$/.test(words[0])) words.shift();
+ while (words.length > 0 && words[0]!.startsWith("-")) {
+ const option = words.shift()!;
+ if (WRAPPER_VALUE_OPTIONS.has(option) && words.length > 0) words.shift();
+ }
+ if (words[0] && RUN_WORDS.has(words[0]) && ["uv", "poetry", "pipenv", "pdm", "hatch", "rye", "conda", "mamba", "micromamba"].includes(name)) {
+ words.shift();
+ while (words.length > 0 && words[0]!.startsWith("-")) {
+ const option = words.shift()!;
+ if (WRAPPER_VALUE_OPTIONS.has(option) && words.length > 0) words.shift();
+ }
+ }
+ // `npx foo`: a package, not a path; its own configs below.
+ if (["npx", "bunx", "pnpx"].includes(name)) {
+ add("package.json", "read", commandDir);
+ break;
+ }
+ }
+ if (words.length === 0) {
+ if (item.heredoc) for (const use of codePathUses(item.heredoc)) add(use.word, use.op, commandDir);
+ continue;
+ }
+ const head = words[0]!;
+ const name = baseName(head);
+ const args = words.slice(1);
+ const operands = (list: string[]) => {
+ const result: string[] = [];
+ let options = true;
+ for (const word of list) {
+ if (options && word === "--") {
+ options = false;
+ continue;
+ }
+ if (options && word.startsWith("-") && word.length > 1) {
+ const equals = word.indexOf("=");
+ if (equals > 0 && looksLikePath(word.slice(equals + 1))) add(word.slice(equals + 1), "read", commandDir);
+ continue;
+ }
+ result.push(word);
+ }
+ return result;
+ };
+
+ if (name === "cd" || name === "pushd") {
+ const target = args.find((word) => !word.startsWith("-"));
+ if (target && (target === "." || target === ".." || cleanPathWord(target))) {
+ const expanded = target === "~" || target.startsWith("~/") ? (home ? join(home, target.slice(2)) : null) : target;
+ if (expanded) dir = resolve(commandDir, expanded);
+ } else if (!target && home) dir = home;
+ continue;
+ }
+ if (name === "source" || name === ".") {
+ add(args[0], "exec", commandDir);
+ continue;
+ }
+ if (/^(?:\.{1,2}\/|\/|~\/)/.test(head) && !interpreterName(head) && !SHELLS.has(name)) {
+ // `./run.sh x.csv`: the program itself, then its path arguments.
+ add(head, "exec", commandDir);
+ for (const word of operands(args)) if (looksLikePath(word)) add(word, "read", commandDir);
+ continue;
+ }
+ if (SHELLS.has(name)) {
+ const c = args.indexOf("-c");
+ if (c >= 0 && args[c + 1] !== undefined) {
+ for (const use of shellCommandUses(args[c + 1]!, commandDir, home)) {
+ const key = `${use.op}\0${use.path}`;
+ if (!seen.has(key) && out.length < MAX_USES) {
+ seen.add(key);
+ out.push(use);
+ }
+ }
+ continue;
+ }
+ const rest = operands(args);
+ if (rest[0]) add(rest[0], "exec", commandDir);
+ for (const word of rest.slice(1)) if (looksLikePath(word)) add(word, "read", commandDir);
+ if (item.heredoc && !rest[0]) for (const use of shellCommandUses(item.heredoc, commandDir, home)) add(use.path, use.op, commandDir);
+ continue;
+ }
+ const interpreter = interpreterName(head);
+ if (interpreter) {
+ let script: string | null = null;
+ let code: string | null = null;
+ let module = false;
+ const rest: string[] = [];
+ for (let index = 0; index < args.length; index += 1) {
+ const word = args[index]!;
+ if (script !== null || code !== null || module) {
+ rest.push(word);
+ continue;
+ }
+ if (word === "-c" || word === "-e" || word === "-p" || word === "--eval" || word === "--print" || word === "-r" && interpreter === "ruby") {
+ code = args[index + 1] ?? "";
+ index += 1;
+ continue;
+ }
+ if (word === "-m") {
+ module = true;
+ index += 1;
+ continue;
+ }
+ if (interpreter === "node" && NODE_IMPORT_OPTIONS.has(word)) {
+ const value = args[index + 1];
+ if (value && /^(?:\.{1,2}\/|\/)/.test(value)) add(value, "read", commandDir);
+ index += 1;
+ continue;
+ }
+ if (word.startsWith("-")) {
+ if (INTERPRETER_VALUE_OPTIONS.has(word)) index += 1;
+ continue;
+ }
+ if (interpreter === "deno" && (word === "run" || word === "test" || word === "task")) continue;
+ if (interpreter === "bun" && (word === "run" || word === "test" || word === "x")) {
+ if (word !== "run") break;
+ continue;
+ }
+ if (interpreter === "java" && word === "-jar") continue;
+ script = word;
+ }
+ if (code !== null) for (const use of codePathUses(code)) add(use.word, use.op, commandDir);
+ if (script !== null && script !== "-") {
+ if (looksLikePath(script) || interpreter === "python" || interpreter === "node") add(script, "exec", commandDir);
+ } else if (item.heredoc) for (const use of codePathUses(item.heredoc)) add(use.word, use.op, commandDir);
+ for (const word of operands(rest)) if (looksLikePath(word)) add(word, "read", commandDir);
+ if (interpreter === "bun") for (const file of TOOL_CONFIGS.bun!) add(file, "read", commandDir);
+ continue;
+ }
+ if (PATTERN_FIRST.has(name)) {
+ const isSed = name === "sed";
+ const isAwk = /awk$/.test(name);
+ let patternGiven = false;
+ let inPlace = false;
+ const files: string[] = [];
+ for (let index = 0; index < args.length; index += 1) {
+ const word = args[index]!;
+ if (word === "-e" || word === "--regexp" || word === "--expression") {
+ patternGiven = true;
+ index += 1;
+ continue;
+ }
+ if (word === "-f" || word === "--file") {
+ add(args[index + 1], "read", commandDir);
+ patternGiven = true;
+ index += 1;
+ continue;
+ }
+ if (isSed && (word === "-i" || word.startsWith("-i") || word === "--in-place" || /^-[a-zA-Z]*i/.test(word))) inPlace = true;
+ if (word.startsWith("-") && word.length > 1) {
+ if (["-A", "-B", "-C", "-m", "-g", "--glob", "-t", "--type", "-v", "-F", "-d", "--max-count", "-j"].includes(word) && !isAwk && name !== "sed" && word !== "-v" && word !== "-F") index += 1;
+ else if (isAwk && (word === "-v" || word === "-F")) index += 1;
+ continue;
+ }
+ if (!patternGiven) {
+ patternGiven = true;
+ continue;
+ }
+ files.push(word);
+ }
+ for (const word of files) add(word, isSed && inPlace ? "write" : "read", commandDir);
+ continue;
+ }
+ if (COPIERS.has(name)) {
+ const rest = operands(args).filter((word) => !word.includes(":") || /^[A-Za-z]:[\\/]/.test(word) || word.startsWith("/"));
+ if (name === "ln") continue;
+ const target = rest.at(-1);
+ for (const word of rest.slice(0, -1)) add(word, "read", commandDir);
+ if (target && rest.length > 1) add(target, "write", commandDir);
+ continue;
+ }
+ if (WRITERS.has(name)) {
+ for (const word of operands(args)) add(word, "write", commandDir);
+ continue;
+ }
+ if (name === "tar") {
+ const mode = args.find((word) => /^-?[a-zA-Z]*[ctxru][a-zA-Z]*$/.test(word)) ?? "";
+ const fIndex = args.findIndex((word) => word === "-f" || word === "--file" || /^-?[a-zA-Z]*f$/.test(word));
+ const archive = fIndex >= 0 ? args[fIndex + 1] : undefined;
+ if (archive) add(archive, /c/.test(mode) ? "write" : "read", commandDir);
+ if (/c/.test(mode)) for (const word of operands(args).filter((word) => word !== archive && word !== mode)) if (looksLikePath(word)) add(word, "read", commandDir);
+ continue;
+ }
+ if (READERS.has(name)) {
+ for (const word of operands(args)) add(word, "read", commandDir);
+ continue;
+ }
+ if (["gcc", "g++", "cc", "c++", "clang", "clang++", "javac", "rustc", "nvcc", "gfortran"].includes(name)) {
+ for (let index = 0; index < args.length; index += 1) {
+ const word = args[index]!;
+ if (word === "-o") {
+ add(args[index + 1], "write", commandDir);
+ index += 1;
+ } else if (word === "-include" || word === "-imacros") {
+ add(args[index + 1], "read", commandDir);
+ index += 1;
+ } else if (["-I", "-L", "-isystem", "-D", "-U", "-l", "-cp", "-classpath", "-d", "-x", "-MF"].includes(word)) index += 1;
+ else if (!word.startsWith("-") && looksLikePath(word)) add(word, "read", commandDir);
+ }
+ continue;
+ }
+ // Build, test and package tools: the configs they load and the files their options name.
+ const configs = TOOL_CONFIGS[name] ?? (name === "docker" ? TOOL_CONFIGS.docker : undefined);
+ if (configs) for (const file of configs) add(file, "read", commandDir);
+ if (name === "docker" && args[0] === "compose") for (const file of TOOL_CONFIGS["docker-compose"]!) add(file, "read", commandDir);
+ if (FILE_OPTION_TOOLS.has(name) || configs) {
+ for (let index = 0; index < args.length; index += 1) {
+ const word = args[index]!;
+ if (FILE_OPTIONS.has(word) && args[index + 1] !== undefined && looksLikePath(args[index + 1]!)) {
+ add(args[index + 1], "read", commandDir);
+ index += 1;
+ }
+ }
+ }
+ // `python manage.py`-style tools are covered above; anything else: its path-looking words.
+ for (const word of operands(args)) if (looksLikePath(word)) add(word, "read", commandDir);
+ if (item.heredoc) for (const use of codePathUses(item.heredoc)) add(use.word, use.op, commandDir);
+ }
+ } catch {
+ // Best effort: what was found so far.
+ }
+ return out;
+}
diff --git a/apps/server/src/session-archive/files-used.test.ts b/apps/server/src/session-archive/files-used.test.ts
new file mode 100644
index 00000000..d010d83b
--- /dev/null
+++ b/apps/server/src/session-archive/files-used.test.ts
@@ -0,0 +1,457 @@
+import { afterAll, afterEach, describe, expect, test } from "bun:test";
+import { execFileSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { zstdDecompressSync } from "node:zlib";
+
+import * as deps from "./deps.js";
+import * as used from "./files-used.js";
+import * as policy from "./files-used-policy.js";
+import * as shell from "./files-used-shell.js";
+import { SessionArchiver, FILES_USED_SETTING_FILE } from "./index.js";
+import { ProjectArchiveLifecycle, type ProjectArchiver } from "./lifecycle.js";
+import { outsideExclusion } from "./outside.js";
+import { parseArchivePolicy } from "./policy.js";
+import { openSealedBuffer, SEAL_ALG, sealKeyring } from "./seal.js";
+import { readTar } from "./test-helpers.js";
+
+// Files used (backend spec 19.7), the desktop's side. The pure modules
+// (files-used-policy.ts, files-used-shell.ts, deps.ts) are byte-identical to
+// the CLI's and are checked here against the same cases as its
+// test/capture-files-used.test.js; the rest is the app side: staging at a
+// tool call's end, the end-of-turn snapshot, the Settings switch, and the
+// state document of a real chain.
+
+const cleanups: string[] = [];
+const stops: Array<() => Promise<void>> = [];
+afterAll(async () => {
+ for (const stop of stops) await stop();
+ for (const dir of cleanups) rmSync(dir, { recursive: true, force: true });
+});
+const savedEnv = process.env.OMNIRUSH_ARCHIVE_FILES_USED;
+afterEach(() => {
+ if (savedEnv === undefined) delete process.env.OMNIRUSH_ARCHIVE_FILES_USED;
+ else process.env.OMNIRUSH_ARCHIVE_FILES_USED = savedEnv;
+});
+
+const sha256 = (bytes: Uint8Array | string) => createHash("sha256").update(bytes).digest("hex");
+function git(cwd: string, ...args: string[]): string {
+ return execFileSync("git", ["-C", cwd, "-c", "[email protected]", "-c", "user.name=t", "-c", "init.defaultBranch=main", "-c", "commit.gpgSign=false", ...args], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+}
+function temp(prefix: string): string {
+ const dir = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+ cleanups.push(dir);
+ return dir;
+}
+function write(file: string, content: string | Buffer): string {
+ mkdirSync(dirname(file), { recursive: true });
+ writeFileSync(file, content);
+ return file;
+}
+
+const uses = (command: string, cwd = "/w", home = "/home/u") => shell.shellCommandUses(command, cwd, home).map((use) => `${use.op} ${use.path}`).sort();
+
+describe("shell command parsing (shared with the CLI)", () => {
+ test("readers, redirections, cd chains and copies", () => {
+ expect(uses("cat data/a.csv | head -n 5 > /tmp/out.txt")).toEqual(["read /w/data/a.csv", "write /tmp/out.txt"].sort());
+ expect(uses("cd sub && tail -f logs/app.log 2>&1")).toEqual(["read /w/sub/logs/app.log"]);
+ expect(uses("cp src/a.py /tmp/b.py && mv /tmp/b.py dist/")).toEqual(["read /tmp/b.py", "read /w/src/a.py", "write /tmp/b.py", "write /w/dist"].sort());
+ expect(uses("echo hi > /dev/null; cat ~/notes.md")).toEqual(["read /home/u/notes.md"]);
+ });
+
+ test("interpreters run their script, read its arguments; -c code and heredocs name files", () => {
+ expect(uses("python3 /tmp/gen.py --in data/x.csv out.json")).toEqual(["exec /tmp/gen.py", "read /w/data/x.csv", "read /w/out.json"].sort());
+ expect(uses(`python -c "import json; json.load(open('settings.json')); open('/tmp/r.txt', 'w').write('x')"`)).toEqual(["read /w/settings.json", "write /tmp/r.txt"].sort());
+ expect(uses("source .venv/bin/activate && . ./env.sh")).toEqual(["exec /w/.venv/bin/activate", "exec /w/env.sh"].sort());
+ expect(uses("cat > /tmp/s.sh <<EOF\necho hi\nEOF\nbash /tmp/s.sh")).toEqual(["exec /tmp/s.sh", "write /tmp/s.sh"].sort());
+ expect(uses("sed -i 's/a/b/' conf.ini")).toEqual(["write /w/conf.ini"]);
+ });
+
+ test("variables, globs, URLs and options are never paths", () => {
+ expect(uses("curl -s https://example.com/a.json -o $OUT; ls *.py; echo $HOME/x")).toEqual([]);
+ expect(uses("git commit -m 'fix: a.b'")).toEqual([]);
+ });
+});
+
+const context = { roots: ["/w"], home: "/home/u", temps: ["/tmp"], appDirs: ["/home/u/.omnirush"] };
+const classify = (absolute: string) => {
+ const value = policy.classifyUse(absolute, context);
+ return value ? `${value.scope} ${value.plan} ${value.reason}` : null;
+};
+
+describe("policy (shared with the CLI)", () => {
+ test("credentials, keys, .env and token files are never archived, wherever they are", () => {
+ expect(classify("/w/.env")).toBe("project hold denylisted");
+ expect(classify("/w/.env.example")).toBe("project scan captured");
+ expect(classify("/w/certs/server.key")).toBe("project hold denylisted");
+ expect(classify("/home/u/.ssh/config")).toBe("home hold denylisted");
+ expect(classify("/home/u/.aws/credentials")).toBe("home hold denylisted");
+ expect(classify("/home/u/.netrc")).toBe("home hold denylisted");
+ expect(classify("/tmp/token.txt")).toBe("tmp hold denylisted");
+ });
+
+ test("home settings only through the allowlist; dependency and build folders hash only; system files never", () => {
+ expect(classify("/home/u/.gitconfig")).toBe("home stage captured");
+ expect(classify("/home/u/.npmrc")).toBe("home stage captured");
+ expect(classify("/home/u/.bashrc")).toBe("home hold not_allowlisted");
+ expect(classify("/home/u/.cache/pip/x.whl")).toBe("home hold dependency_dir");
+ expect(classify("/w/node_modules/a/index.js")).toBe("project hold dependency_dir");
+ expect(classify("/w/dist/app.js")).toBe("project hold build_output");
+ expect(classify("/w/config.local.yaml")).toBe("project scan captured");
+ expect(classify("/tmp/shot.png")).toBe("tmp stage captured");
+ expect(classify("/etc/hosts")).toBe("outside hold denylisted");
+ expect(classify("/data/in.parquet")).toBe("outside scan captured");
+ expect(classify("/home/u/.omnirush/auth.json")).toBeNull();
+ });
+
+ test("home config scrub: no auth, token or credential line survives; URLs lose their userinfo", () => {
+ const npm = policy.scrubHomeConfig("npmrc", "registry=https://registry.npmjs.org/\n//registry.npmjs.org/:_authToken=npm_FAKEFAKEFAKEFAKEFAKE\n@acme:registry=https://user:[email protected]/\n")!;
+ expect(npm).not.toContain("npm_FAKE");
+ expect(npm).not.toContain("user:pw");
+ expect(npm).toContain("@acme:registry=https://npm.acme.dev/");
+ const gitText = policy.scrubHomeConfig("git", "[user]\n\tname = Sam\n[credential]\n\thelper = store\n[remote \"o\"]\n\turl = https://x:[email protected]/a/b\n")!;
+ expect(gitText).not.toContain("helper = store");
+ expect(gitText).not.toContain("ghp_FAKE");
+ expect(gitText).toContain("name = Sam");
+ expect(policy.scrubHomeConfig("text", "a\u0000b")).toBeNull();
+ });
+
+ test("manifest: the format, `captured` from what the chain holds, the reasons", () => {
+ const items = policy.finalizeFilesUsed([
+ { path: "src/a.py", scope: "project", op: "read", size: 3, sha256: "a".repeat(64), plan: "scan", reason: "captured", turn: 1 },
+ { path: "/tmp/gone.png", scope: "tmp", op: "write", size: null, sha256: null, plan: "staged", reason: "captured", archive_path: "__outside__/tmp/gone.png", turn: 1 },
+ { path: "/tmp/kept.png", scope: "tmp", op: "write", size: 9, sha256: "b".repeat(64), plan: "staged", reason: "captured", archive_path: "__outside__/tmp/kept.png", turn: 1, call_id: "call_1" },
+ { path: "/data/big.bin", scope: "outside", op: "read", size: 9e9, sha256: null, plan: "scan", reason: "captured", turn: 1 },
+ { path: "node_modules/x/i.js", scope: "project", op: "read", size: 1, sha256: "c".repeat(64), plan: "hold", reason: "dependency_dir", turn: 1 },
+ ], new Set(["src/a.py", "__outside__/tmp/kept.png"]));
+ expect(items.map((item) => `${item.path} ${item.captured} ${item.reason}`)).toEqual([
+ "/data/big.bin false too_large",
+ "/tmp/gone.png false missing",
+ "/tmp/kept.png true captured",
+ "node_modules/x/i.js false dependency_dir",
+ "src/a.py true captured",
+ ]);
+ expect(Object.keys(items[2]!).sort()).toEqual(["call_id", "captured", "op", "path", "reason", "scope", "sha256", "size"]);
+ expect(policy.FILES_USED_REASONS).toEqual(["captured", "dependency_dir", "build_output", "denylisted", "not_allowlisted", "too_large", "missing"]);
+ expect(policy.MAX_FILES_USED_FILE_BYTES).toBe(64 * 1024 * 1024);
+ expect(policy.MAX_FILES_USED_SESSION_BYTES).toBe(256 * 1024 * 1024);
+ });
+
+ test("GET /archives/key: files_used and its caps; the environment switch", () => {
+ expect(parseArchivePolicy({ policy: { capture_v2: true, files_used: true, files_used_max_file_bytes: 1024, files_used_max_session_bytes: null } }))
+ .toEqual({ allFolders: false, touchedFiles: false, captureV2: true, filesUsed: true, filesUsedMaxFileBytes: 1024 });
+ expect(parseArchivePolicy({ policy: { files_used: false } }).filesUsed).toBeUndefined();
+ expect(policy.filesUsedOverride({ OMNIRUSH_ARCHIVE_FILES_USED: "0" })).toBe(false);
+ expect(policy.filesUsedOverride({})).toBeNull();
+ });
+
+ test("dependencies: every subproject's lockfile with its resolved versions", async () => {
+ const root = temp("omnirush-fu-deps-");
+ write(join(root, "package.json"), "{}");
+ write(join(root, "package-lock.json"), JSON.stringify({ lockfileVersion: 3, packages: { "": {}, "node_modules/left-pad": { version: "1.3.0" } } }));
+ write(join(root, "api", "pyproject.toml"), "[project]\nname='a'\n");
+ write(join(root, "api", "uv.lock"), "version = 1\n\n[[package]]\nname = \"requests\"\nversion = \"2.32.3\"\n");
+ write(join(root, "node_modules", "z", "package-lock.json"), "{}");
+ const projects = await used.collectDependencyProjects(root);
+ expect(projects.map((project) => [project.dir, project.ecosystem, project.lockfile, project.resolved])).toEqual([
+ [".", "npm", "package-lock.json", { "left-pad": "1.3.0" }],
+ ["api", "uv", "api/uv.lock", { requests: "2.32.3" }],
+ ]);
+ expect(deps.lockfileEcosystem("go.sum")).toBe("go");
+ });
+});
+
+describe("the desktop side", () => {
+ test("outside scan: home settings are never archived as they are (an allowlisted config only scrubbed, through files used)", () => {
+ const home = "/home/u";
+ expect(outsideExclusion("/home/u/.gitconfig", { appDirs: [], home })).toBe("credential");
+ expect(outsideExclusion("/home/u/Library/Preferences/x.plist", { appDirs: [], home })).toBe("credential");
+ expect(outsideExclusion("/home/u/Downloads/data.csv", { appDirs: [], home })).toBeNull();
+ expect(outsideExclusion("/tmp/shot.png", { appDirs: [], home })).toBeNull();
+ });
+
+ test("end-of-turn snapshot: files changed since the turn started, gitignored ones too, never .git or dependency folders", async () => {
+ const root = temp("omnirush-fu-snap-");
+ for (const file of ["src/a.py", "README.md", ".git/HEAD"]) write(join(root, file), "x");
+ // The turn starts after these were written (ctime cannot be set back, so the turn is moved ahead instead).
+ const since = Date.now() + 2_500;
+ const later = (Date.now() + 10_000) / 1000;
+ for (const file of ["out/report.csv", "node_modules/x/i.js", ".git/index", "dist/app.js"]) {
+ write(join(root, file), "1");
+ utimesSync(join(root, file), later, later);
+ }
+ const found = (await used.changedSince(root, since, Date.now() + 5_000)).map((path) => path.slice(root.length + 1)).sort();
+ expect(found).toEqual(["dist/app.js", "out/report.csv"]);
+ // A spent budget stops the walk.
+ expect(await used.changedSince(root, since, Date.now() - 1)).toEqual([]);
+ });
+
+ test("engine events: a finished tool call (v1 and v2 shapes)", () => {
+ const v1 = used.finishedToolCallOf({ type: "message.part.updated", properties: { part: { type: "tool", tool: "bash", callID: "c1", sessionID: "s1", state: { status: "completed", input: { command: "ls" }, time: { start: 1, end: 2 } } } } });
+ expect(v1).toEqual({ sessionId: "s1", call: { callId: "c1", tool: "bash", input: { command: "ls" }, start: 1, end: 2 } });
+ expect(used.finishedToolCallOf({ type: "message.part.updated", properties: { part: { type: "tool", tool: "bash", callID: "c1", sessionID: "s1", state: { status: "running", input: {} } } } })).toBeNull();
+ expect(used.finishedToolCallOf({ directory: "/w", payload: { type: "session.tool.completed", data: { sessionID: "s2", tool: "read", callID: "c2", input: { filePath: "/w/a" } } } })?.call.tool).toBe("read");
+ });
+
+ test("lifecycle: a turn's files are listed ahead of its delta; the turn start notes the time only", async () => {
+ const order: string[] = [];
+ const archiver = {
+ captureBase: async () => ({ status: "skipped", reason: "exists" }),
+ captureDelta: async () => {
+ order.push("delta");
+ return { status: "skipped", reason: "unchanged" };
+ },
+ captureFinal: async () => ({ status: "skipped", reason: "unchanged" }),
+ startFinalCandidates: async () => [],
+ recordTouched: () => undefined,
+ forgetTouched: () => undefined,
+ drain: async () => ({ uploaded: 0, failed: 0, remaining: 0 }),
+ signOut: async () => undefined,
+ stop: async () => undefined,
+ filesUsedTurnStarted: () => order.push("started"),
+ filesUsedTurnEnded: async () => {
+ await new Promise((resolve) => setTimeout(resolve, 20));
+ order.push("files_used");
+ return { items: 1, staged: 0, ms: 20, snapshot: 0 };
+ },
+ filesUsedToolCallEnded: async () => {
+ order.push("call");
+ },
+ } as unknown as ProjectArchiver;
+ const lifecycle = new ProjectArchiveLifecycle({ archiver, enabled: true, log: () => undefined, finalIdleMs: 0 });
+ const engine = { session: async () => ({ id: "ses_l", parentID: null }), messages: async () => [] };
+ lifecycle.sessionStarted({ sessionId: "ses_l", root: temp("omnirush-fu-life-"), engine });
+ await lifecycle.settled();
+ lifecycle.turnFollowed("ses_l");
+ lifecycle.toolCallEnded("ses_l", { callId: "c", tool: "bash", input: { command: "ls" }, start: 1, end: 2 });
+ lifecycle.turnFilesUsed("ses_l", []);
+ lifecycle.turnCompleted("ses_l", []);
+ await lifecycle.settled();
+ expect(order).toEqual(["started", "call", "files_used", "delta"]);
+ });
+});
+
+type Opened = { members: Map<string, Buffer>; bytes: Buffer; manifest: { files: Array<{ path: string }> }; state: Record<string, unknown> & { files_used?: policy.FilesUsedItem[]; dependencies?: Array<{ lockfile: string }>; state: { kind: string; turn: number } } };
+
+function rig(keyPolicy: Record<string, unknown> | (() => Record<string, unknown>), routes: Record<string, (init: { method: string; body?: string }) => Response> = {}, now?: () => Date) {
+ const stateDir = temp("omnirush-fu-state-");
+ const keyring = sealKeyring([randomBytes(32)]);
+ const { publicRaw, kid } = [...keyring.values()][0]!;
+ const request = async (route: string, init: { method: string; body?: string }) => {
+ if (route === "archives/key") return Response.json({ public_key: publicRaw.toString("base64"), kid, alg: SEAL_ALG, policy: typeof keyPolicy === "function" ? keyPolicy() : keyPolicy });
+ const handler = routes[route];
+ return handler ? handler(init) : new Response("{}", { status: 404 });
+ };
+ const archiver = new SessionArchiver({ stateDir, request, excludedDirs: [stateDir], log: () => undefined, touchedFlushMs: 10, ...(now ? { now } : {}) });
+ stops.push(() => archiver.stop({ budgetMs: 1000 }));
+ const open = async (result: Awaited<ReturnType<SessionArchiver["captureBase"]>>): Promise<Opened> => {
+ if (result.status !== "queued") throw new Error(`not queued: ${JSON.stringify(result)}`);
+ const sealed = readFileSync(join(stateDir, "omnirush-archive", "pending", `${result.archiveId}.orseal`));
+ const bytes = zstdDecompressSync(await openSealedBuffer(sealed, keyring));
+ const members = new Map(readTar(bytes).map((member) => [member.name, member.content]));
+ return {
+ members,
+ bytes,
+ manifest: JSON.parse(members.get("__omnirush__/manifest.json")!.toString("utf8")),
+ state: JSON.parse(members.get("__omnirush__/state.json")!.toString("utf8")),
+ };
+ };
+ return { archiver, open, stateDir };
+}
+
+const toolPart = (callID: string, tool: string, input: Record<string, unknown>, start = Date.now() - 1000, end = Date.now()) => ({ type: "tool", tool, callID, state: { status: "completed", input, time: { start, end } } });
+const turn = (...parts: unknown[]) => [{ info: { role: "user" }, parts: [] }, { info: { role: "assistant", time: { completed: Date.now() } }, parts }];
+const callOf = (part: unknown) => used.usedToolCallOf(part)!;
+
+function project(): string {
+ const root = temp("omnirush-fu-root-");
+ write(join(root, ".gitignore"), "config.local.yaml\nnode_modules/\n.env\nresults/\n");
+ write(join(root, "app.py"), "print(1)\n");
+ write(join(root, "package.json"), "{}");
+ write(join(root, "package-lock.json"), JSON.stringify({ packages: { "node_modules/a": { version: "1.0.0" } } }));
+ git(root, "init", "-q");
+ git(root, "add", ".");
+ git(root, "commit", "-qm", "init");
+ write(join(root, "config.local.yaml"), "mode: local\n");
+ write(join(root, ".env"), "API_TOKEN=abcdefgh123\n");
+ write(join(root, "node_modules", "a", "index.js"), "module.exports = 1\n");
+ return root;
+}
+
+describe("a files-used chain", () => {
+ test("temp scripts kept at call end, gitignored inputs, scrubbed home config, a turn's new gitignored output; secrets held; an after state for a quiet turn", async () => {
+ const { archiver, open } = rig({ capture_v2: true, files_used: true });
+ const root = project();
+ const scratch = temp("omnirush-fu-tmp-");
+ const home = temp("omnirush-fu-home-");
+ write(join(home, ".gitconfig"), "[user]\n\tname = T\n[credential]\n\thelper = store\n");
+ write(join(home, ".npmrc"), "registry=https://registry.npmjs.org/\n//registry.npmjs.org/:_authToken=npm_FAKEFAKEFAKEFAKE1234\n");
+ write(join(home, ".bashrc"), "export SECRET_THING=1\n");
+ const tracker = new used.FilesUsedTracker({ archive: archiver, appDirs: [], home, temps: [scratch] });
+
+ const sessionId = "ses_files_used_gui_1";
+ await archiver.startManifest(sessionId, root);
+ const base = await open(await archiver.captureBase(sessionId, root, 0));
+ expect(base.state.files_used).toEqual([]);
+ expect(base.state.dependencies!.map((item) => item.lockfile)).toEqual(["package-lock.json"]);
+ expect(await archiver.filesUsedActive(sessionId)).toBe(true);
+
+ tracker.turnStarted(sessionId);
+ const script = write(join(scratch, "gen.py"), "print(open('config.local.yaml').read())\n");
+ const call1 = toolPart("call_1", "write", { filePath: script, content: "..." });
+ await tracker.toolCallEnded(sessionId, root, callOf(call1));
+ const call2 = toolPart("call_2", "bash", { command: `python3 ${script} config.local.yaml && cat ~/.gitconfig ~/.npmrc ~/.bashrc .env node_modules/a/index.js && rm ${script}` });
+ await tracker.toolCallEnded(sessionId, root, callOf(call2));
+ rmSync(script);
+ // Written by the script without being named: only the end-of-turn snapshot sees it.
+ write(join(root, "results", "report.csv"), "a,b\n1,2\n");
+
+ const listed = await tracker.turnEnded(sessionId, root, turn(call1, call2));
+ expect(listed.items).toBeGreaterThanOrEqual(7);
+ expect(listed.snapshot).toBeGreaterThanOrEqual(1);
+ const after = await open(await archiver.captureDelta(sessionId, root, 1));
+ expect(after.state.state).toEqual({ kind: "after", turn: 1 });
+ const items = new Map(after.state.files_used!.map((item) => [item.path, item]));
+ const expectItem = (key: string, scope: string, op: string, captured: boolean, reason: string) => {
+ const item = items.get(key);
+ expect(item, `${key} in ${[...items.keys()].join(", ")}`).toBeDefined();
+ expect([item!.scope, item!.op, item!.captured, item!.reason] as unknown[]).toEqual([scope, op, captured, reason]);
+ };
+ expectItem(script, "tmp", "write", true, "captured");
+ expectItem("config.local.yaml", "project", "read", true, "captured");
+ expectItem("results/report.csv", "project", "write", true, "captured");
+ expectItem(join(home, ".gitconfig"), "home", "read", true, "captured");
+ expectItem(join(home, ".npmrc"), "home", "read", true, "captured");
+ expectItem(join(home, ".bashrc"), "home", "read", false, "not_allowlisted");
+ expectItem(".env", "project", "read", false, "denylisted");
+ expectItem("node_modules/a/index.js", "project", "read", false, "dependency_dir");
+ expect(items.get(script)!.call_id).toBe("call_1");
+ // Hashes the turn end left to the scan come from the chain.
+ expect(items.get("config.local.yaml")!.sha256).toBe(sha256("mode: local\n"));
+ expect(items.get("results/report.csv")!.sha256).toBe(sha256("a,b\n1,2\n"));
+ expect(items.get(".env")!.sha256).toBeNull();
+ for (const item of items.values()) expect(Object.keys(item).every((key) => ["path", "scope", "op", "size", "sha256", "captured", "reason", "call_id"].includes(key))).toBe(true);
+
+ const outside = (absolute: string) => `__outside__${absolute}`;
+ expect(after.members.get(outside(script))?.toString()).toBe("print(open('config.local.yaml').read())\n");
+ expect(after.members.get("config.local.yaml")?.toString()).toBe("mode: local\n");
+ expect(after.members.get("results/report.csv")?.toString()).toBe("a,b\n1,2\n");
+ const gitconfig = after.members.get(outside(join(home, ".gitconfig")))?.toString() ?? "";
+ expect(gitconfig).toContain("name = T");
+ expect(gitconfig).not.toContain("helper = store");
+ expect(items.get(join(home, ".gitconfig"))!.sha256).toBe(sha256(gitconfig));
+ const text = after.bytes.toString("latin1");
+ for (const secret of ["npm_FAKEFAKEFAKEFAKE1234", "abcdefgh123", "SECRET_THING", "helper = store"]) expect(text.includes(secret), secret).toBe(false);
+ expect(after.members.has(outside(join(home, ".bashrc")))).toBe(false);
+ expect(after.members.has("node_modules/a/index.js")).toBe(false);
+ expect(after.members.has(".env")).toBe(false);
+
+ // A quiet turn still gets its after state; the kept temp copy stays in the chain (no deletion).
+ const quiet = await open(await archiver.captureDelta(sessionId, root, 2));
+ expect(quiet.state.state).toEqual({ kind: "after", turn: 2 });
+ expect(quiet.state.files_used).toEqual([]);
+ expect(quiet.manifest.files).toEqual([]);
+ expect((quiet.manifest as unknown as { deleted?: string[] }).deleted ?? []).toEqual([]);
+ expect(quiet.state.dependencies).toBeUndefined();
+ });
+
+ test("the Settings switch: shows omnirush.ai's line, accepts it or turns it off for the account, and gates recording at once", async () => {
+ const puts: string[] = [];
+ const line = "OmniRush also saves the files the agent reads, runs or creates during a session (including temporary files and a few allowlisted config files, with secrets removed), so the session can be replayed.";
+ let accepted = false;
+ const answer = () => Response.json({ files_used: accepted, files_used_accepted: accepted, files_used_available: true, files_used_consent_text: line });
+ const { archiver, open, stateDir } = rig(() => ({ capture_v2: true, files_used: accepted, files_used_accepted: accepted, files_used_available: true, files_used_consent_text: line }), {
+ "archives/files-used": (init) => {
+ if (init.method === "PUT") {
+ puts.push(init.body ?? "");
+ accepted = JSON.parse(init.body ?? "{}").enabled === true;
+ }
+ return answer();
+ },
+ });
+ const root = project();
+ const sessionId = "ses_files_used_gui_switch";
+ // Not accepted yet: the chain records nothing.
+ const base = await open(await archiver.captureBase(sessionId, root, 0));
+ expect(base.state.files_used).toBeUndefined();
+ expect(await archiver.filesUsedActive(sessionId)).toBe(false);
+ expect(await archiver.filesUsedStatus()).toEqual({ enabled: true, active: false, accepted: false, available: true, consentText: line });
+
+ // Accepted from Settings: recorded from the next turn.
+ expect(await archiver.setFilesUsedEnabled(true)).toEqual({ enabled: true, active: true, accepted: true, available: true, consentText: line });
+ expect(await archiver.filesUsedActive(sessionId)).toBe(true);
+ const read = toolPart("r", "read", { filePath: join(root, "config.local.yaml") });
+ // The read, and the project's files the snapshot finds changed (the test just wrote them).
+ expect((await archiver.filesUsedTurnEnded(sessionId, root, turn(read))).items).toBeGreaterThanOrEqual(1);
+ const on = await open(await archiver.captureDelta(sessionId, root, 1));
+ expect(on.state.files_used!.find((item) => item.path === "config.local.yaml")?.captured).toBe(true);
+
+ // Off: saved on this device, sent to the account, nothing more recorded; what waited is dropped.
+ expect((await archiver.filesUsedTurnEnded(sessionId, root, turn(read))).items).toBeGreaterThanOrEqual(1);
+ expect(await archiver.setFilesUsedEnabled(false)).toEqual({ enabled: false, active: false, accepted: false, available: true, consentText: line });
+ expect(puts).toEqual([JSON.stringify({ enabled: true }), JSON.stringify({ enabled: false })]);
+ expect(JSON.parse(readFileSync(join(stateDir, FILES_USED_SETTING_FILE), "utf8"))).toEqual({ enabled: false });
+ expect(await archiver.filesUsedActive(sessionId)).toBe(false);
+ expect(archiver.filesUsedMaybe()).toBe(false);
+ expect((await archiver.filesUsedTurnEnded(sessionId, root, turn(read))).items).toBe(0);
+ expect(await archiver.captureDelta(sessionId, root, 2)).toEqual({ status: "skipped", reason: "unchanged" });
+
+ // A new archiver (an app restart) reads the saved switch.
+ const again = new SessionArchiver({ stateDir, request: async () => new Response("{}", { status: 404 }), log: () => undefined });
+ stops.push(() => again.stop({ budgetMs: 100 }));
+ expect(await again.filesUsedLocalSetting()).toBe(false);
+ });
+
+ test("a withdrawal on omnirush.ai stops recording at the next turn whose answer is old", async () => {
+ let accepted = true;
+ let clock = Date.now();
+ const { archiver, open } = rig(() => ({ capture_v2: true, files_used: accepted }), {}, () => new Date(clock));
+ const root = project();
+ const sessionId = "ses_files_used_gui_withdraw";
+ await open(await archiver.captureBase(sessionId, root, 0));
+ expect(await archiver.filesUsedActive(sessionId)).toBe(true);
+ accepted = false;
+ clock += 6 * 60_000;
+ const read = toolPart("r", "read", { filePath: join(root, "config.local.yaml") });
+ expect((await archiver.filesUsedTurnEnded(sessionId, root, turn(read))).items).toBe(0);
+ expect(await archiver.filesUsedActive(sessionId)).toBe(false);
+ });
+
+ test("off: a server without files_used, or OMNIRUSH_ARCHIVE_FILES_USED=0, keeps the chain as it was", async () => {
+ for (const [keyPolicy, env] of [[{ capture_v2: true, files_used: true }, "0"], [{ capture_v2: true }, undefined]] as const) {
+ if (env === undefined) delete process.env.OMNIRUSH_ARCHIVE_FILES_USED;
+ else process.env.OMNIRUSH_ARCHIVE_FILES_USED = env;
+ const { archiver, open } = rig(keyPolicy);
+ const root = project();
+ const sessionId = `ses_files_used_gui_off_${env ?? "server"}`;
+ const base = await open(await archiver.captureBase(sessionId, root, 0));
+ expect(base.state.files_used).toBeUndefined();
+ expect(base.state.dependencies).toBeUndefined();
+ expect(await archiver.filesUsedActive(sessionId)).toBe(false);
+ expect(archiver.filesUsedMaybe()).toBe(false);
+ const result = await archiver.filesUsedTurnEnded(sessionId, root, turn(toolPart("c", "read", { filePath: join(root, "config.local.yaml") })));
+ expect(result.items).toBe(0);
+ expect(await archiver.captureDelta(sessionId, root, 1)).toEqual({ status: "skipped", reason: "unchanged" });
+ }
+ });
+
+ test("caps: a used file over the per-file cap is listed with its size only, never copied", async () => {
+ const { archiver, open } = rig({ capture_v2: true, files_used: true, files_used_max_file_bytes: 1024 });
+ const root = project();
+ const scratch = temp("omnirush-fu-cap-");
+ const big = write(join(scratch, "big.bin"), randomBytes(4096));
+ const small = write(join(scratch, "small.txt"), "ok\n");
+ const sessionId = "ses_files_used_gui_cap";
+ await open(await archiver.captureBase(sessionId, root, 0));
+ const tracker = new used.FilesUsedTracker({ archive: archiver, appDirs: [], temps: [scratch] });
+ const call = toolPart("c", "bash", { command: `cat ${big} ${small}` });
+ await tracker.turnEnded(sessionId, root, turn(call));
+ const after = await open(await archiver.captureDelta(sessionId, root, 1));
+ const items = new Map(after.state.files_used!.map((item) => [item.path, item]));
+ expect([items.get(big)!.captured, items.get(big)!.reason, items.get(big)!.size]).toEqual([false, "too_large", 4096]);
+ expect([items.get(small)!.captured, items.get(small)!.reason]).toEqual([true, "captured"]);
+ expect(after.members.has(`__outside__${big}`)).toBe(false);
+ });
+});
diff --git a/apps/server/src/session-archive/files-used.ts b/apps/server/src/session-archive/files-used.ts
new file mode 100644
index 00000000..e861fe9b
--- /dev/null
+++ b/apps/server/src/session-archive/files-used.ts
@@ -0,0 +1,911 @@
+/**
+ * Files used, the app side (files-used-policy.ts has the format and the
+ * rules): hashing, the per-session store of staged copies and pending
+ * items, and FilesUsedTracker, which turns the agent's own tool calls into
+ * `files_used` items: at the end of each tool call it keeps a copy of the
+ * temp files the call named (or created in a temp folder it named) and of
+ * the allowlisted home config it read (scrubbed); at the end of the turn it
+ * lists every file the turn's calls used, reports the project and outside
+ * ones to the archive as touched (the chain's own scan carries them), and
+ * leaves the items for the next state document. Only the agent's tool calls
+ * are looked at, never what other programs open.
+ */
+import { createHash } from "node:crypto";
+import { lstat, mkdir, open, readFile, readdir, realpath, rm, writeFile, rename } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+
+import { stateKey } from "./files.js";
+import { HASH_READ_BYTES, OPEN_ENTRY_FLAGS, isArchiveCredentialPath, statFields, type ScannedEntry } from "./manifest.js";
+import {
+ BUILD_OUTPUT_DIR_NAMES,
+ classifyUse,
+ DEPENDENCY_DIR_NAMES,
+ DEFAULT_FILES_USED_LIMITS,
+ MAX_FILES_USED_ITEMS,
+ scrubHomeConfig,
+ strongerOp,
+ type FilesUsedLimits,
+ type FilesUsedOp,
+ type PendingUse,
+ type UseContext,
+} from "./files-used-policy.js";
+import { shellCommandUses } from "./files-used-shell.js";
+import { sseFrames } from "./tool-start.js";
+import { lockfileEcosystem, MANIFEST_NAMES, MAX_LOCKFILE_BYTES, MAX_TOOLCHAIN_PROJECTS, sortToolchainProjects, toolchainProject, type ToolchainProject } from "./deps.js";
+import { redactUploadContent } from "../session-uploader.js";
+
+export * from "./files-used-policy.js";
+
+// --- hashing ------------------------------------------------------------------------------
+
+export type FileFacts = { size: number; sha256: string | null; mtimeMs: number; dev: number; ino: number };
+
+/**
+ * Size and SHA-256 of a regular file (never a symlink followed), hashing at
+ * most `maxHashBytes` (a larger one has its size only): "missing" when
+ * nothing is there, "not_file" for a folder, link or special file.
+ */
+export async function fileFacts(absolute: string, maxHashBytes: number): Promise<FileFacts | "missing" | "not_file"> {
+ let stats;
+ try {
+ stats = await lstat(absolute);
+ } catch {
+ return "missing";
+ }
+ if (!stats.isFile()) return "not_file";
+ const facts: FileFacts = { size: stats.size, sha256: null, mtimeMs: stats.mtimeMs, dev: stats.dev, ino: stats.ino };
+ if (stats.size > maxHashBytes) return facts;
+ let handle: Awaited<ReturnType<typeof open>>;
+ try {
+ handle = await open(absolute, OPEN_ENTRY_FLAGS);
+ } catch {
+ return facts;
+ }
+ try {
+ const hash = createHash("sha256");
+ const buffer = Buffer.allocUnsafe(Math.min(HASH_READ_BYTES, Math.max(1, stats.size)));
+ let remaining = stats.size;
+ while (remaining > 0) {
+ const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, remaining), null);
+ if (bytesRead === 0) break;
+ hash.update(buffer.subarray(0, bytesRead));
+ remaining -= bytesRead;
+ }
+ if (remaining === 0) facts.sha256 = hash.digest("hex");
+ } catch {
+ // Unreadable: size only.
+ } finally {
+ await handle.close().catch(() => undefined);
+ }
+ return facts;
+}
+
+// --- the per-session store of staged copies and pending items ---------------------------
+
+export type StagedFile = {
+ /** Archive path (`__outside__/...`). */
+ path: string;
+ size: number;
+ sha256: string;
+ /** The copy under the store (absolute). */
+ blob: string;
+ /** An allowlisted home config whose copy had secrets removed. */
+ scrubbed?: boolean;
+};
+
+type SessionIndex = { v: 1; staged: StagedFile[]; bytes: number; pending: PendingUse[] };
+
+/**
+ * Staged copies (content-addressed blobs) and the items recorded since the
+ * chain's last archive, per session, under `<dir>/<session key>/`. Every
+ * capture of a files-used chain holds the staged copies (so a delta sends
+ * each once), and the next state document takes the pending items.
+ */
+export class FilesUsedStore {
+ private readonly tails = new Map<string, Promise<unknown>>();
+
+ constructor(private readonly dir: string, private limits: FilesUsedLimits = DEFAULT_FILES_USED_LIMITS) {}
+
+ setLimits(limits: Partial<FilesUsedLimits>): void {
+ this.limits = { ...this.limits, ...Object.fromEntries(Object.entries(limits).filter(([, value]) => typeof value === "number" && value > 0)) };
+ }
+
+ get currentLimits(): FilesUsedLimits {
+ return this.limits;
+ }
+
+ private sessionDir(sessionId: string): string {
+ return join(this.dir, stateKey(sessionId));
+ }
+
+ private serial<T>(sessionId: string, task: () => Promise<T>): Promise<T> {
+ const previous = this.tails.get(sessionId) ?? Promise.resolve();
+ const run = previous.then(task, task);
+ this.tails.set(sessionId, run.catch(() => undefined));
+ return run;
+ }
+
+ private async load(sessionId: string): Promise<SessionIndex> {
+ try {
+ const value = JSON.parse(await readFile(join(this.sessionDir(sessionId), "index.json"), "utf8")) as SessionIndex;
+ if (value && value.v === 1 && Array.isArray(value.staged) && Array.isArray(value.pending)) return value;
+ } catch {
+ // None yet.
+ }
+ return { v: 1, staged: [], bytes: 0, pending: [] };
+ }
+
+ private async save(sessionId: string, index: SessionIndex): Promise<void> {
+ const dir = this.sessionDir(sessionId);
+ await mkdir(dir, { recursive: true, mode: 0o700 });
+ const file = join(dir, "index.json");
+ const temp = `${file}.${process.pid}.tmp`;
+ await writeFile(temp, JSON.stringify(index), { mode: 0o600 });
+ await rename(temp, file);
+ }
+
+ /**
+ * Stages `bytes` as the archive path's copy (replacing an older one of
+ * that path). Returns the record, or `too_large` past the per-file or
+ * the session cap.
+ */
+ stage(sessionId: string, path: string, bytes: Buffer, scrubbed = false): Promise<StagedFile | "too_large"> {
+ return this.serial(sessionId, async () => {
+ if (bytes.length > this.limits.maxFileBytes) return "too_large" as const;
+ const index = await this.load(sessionId);
+ const sha256 = createHash("sha256").update(bytes).digest("hex");
+ const known = index.staged.find((item) => item.path === path);
+ if (known && known.sha256 === sha256) return known;
+ const blobKnown = index.staged.some((item) => item.sha256 === sha256);
+ if (!blobKnown && index.bytes + bytes.length > this.limits.maxSessionBytes) return "too_large" as const;
+ const dir = this.sessionDir(sessionId);
+ await mkdir(dir, { recursive: true, mode: 0o700 });
+ const blob = join(dir, `${sha256}.bin`);
+ if (!blobKnown) {
+ const temp = `${blob}.${process.pid}.tmp`;
+ await writeFile(temp, bytes, { mode: 0o600 });
+ await rename(temp, blob);
+ index.bytes += bytes.length;
+ }
+ const record: StagedFile = { path, size: bytes.length, sha256, blob, ...(scrubbed ? { scrubbed: true } : {}) };
+ index.staged = [...index.staged.filter((item) => item.path !== path), record];
+ await this.save(sessionId, index);
+ return record;
+ });
+ }
+
+ /** The session's staged copies. */
+ async staged(sessionId: string): Promise<StagedFile[]> {
+ return this.serial(sessionId, async () => (await this.load(sessionId)).staged);
+ }
+
+ /** Adds items for the next state document (a path seen again keeps its first item, with the stronger op). */
+ addPending(sessionId: string, items: readonly PendingUse[]): Promise<void> {
+ return this.serial(sessionId, async () => {
+ const index = await this.load(sessionId);
+ const byKey = new Map(index.pending.map((item) => [`${item.turn ?? ""}\0${item.path}`, item]));
+ for (const item of items) {
+ const key = `${item.turn ?? ""}\0${item.path}`;
+ const known = byKey.get(key);
+ if (known) {
+ known.op = strongerOp(known.op, item.op);
+ if (item.sha256) {
+ known.sha256 = item.sha256;
+ known.size = item.size;
+ }
+ continue;
+ }
+ if (byKey.size >= MAX_FILES_USED_ITEMS) break;
+ byKey.set(key, { ...item });
+ }
+ index.pending = [...byKey.values()];
+ await this.save(sessionId, index);
+ });
+ }
+
+ /** The pending items (not removed: `commit` removes those a queued archive carried). */
+ async pending(sessionId: string): Promise<PendingUse[]> {
+ return this.serial(sessionId, async () => (await this.load(sessionId)).pending);
+ }
+
+ /** Removes the pending items an archive carried. */
+ commit(sessionId: string, carried: readonly PendingUse[]): Promise<void> {
+ return this.serial(sessionId, async () => {
+ const index = await this.load(sessionId);
+ const done = new Set(carried.map((item) => `${item.turn ?? ""}\0${item.path}`));
+ index.pending = index.pending.filter((item) => !done.has(`${item.turn ?? ""}\0${item.path}`));
+ await this.save(sessionId, index);
+ });
+ }
+
+ /** Archive entries for the staged copies (read from the blobs at pack time). */
+ async entries(sessionId: string): Promise<ScannedEntry[]> {
+ const out: ScannedEntry[] = [];
+ for (const record of await this.staged(sessionId)) {
+ try {
+ const stats = await lstat(record.blob, { bigint: true });
+ if (!stats.isFile() || Number(stats.size) !== record.size) continue;
+ out.push({ path: record.path, type: "file", size: record.size, sha256: record.sha256, source: record.blob, ...statFields(stats), mode: 0o644, ...(record.scrubbed ? { scrubbed: true } : {}) });
+ } catch {
+ // Gone (signed out meanwhile).
+ }
+ }
+ return out;
+ }
+
+ forget(sessionId: string): Promise<void> {
+ return this.serial(sessionId, async () => {
+ await rm(this.sessionDir(sessionId), { recursive: true, force: true });
+ });
+ }
+
+ async clear(): Promise<void> {
+ await rm(this.dir, { recursive: true, force: true }).catch(() => undefined);
+ }
+}
+
+// --- context helpers -----------------------------------------------------------------------
+
+export function safeHome(): string | null {
+ try {
+ return homedir() || null;
+ } catch {
+ return null;
+ }
+}
+
+/** The temp folders of this machine, as given and as real paths. */
+export async function tempRoots(): Promise<string[]> {
+ const out = new Set<string>();
+ for (const value of [tmpdir(), process.env.TMPDIR, process.env.TEMP, process.env.TMP, "/tmp", "/var/tmp", "/private/tmp", "/private/var/tmp"]) {
+ if (!value || !isAbsolute(value)) continue;
+ out.add(resolve(value));
+ try {
+ out.add(await realpath(value));
+ } catch {
+ // Not on this machine.
+ }
+ }
+ return [...out];
+}
+
+/** A folder's forms to compare against: as given and its real path. */
+export async function pathForms(dir: string): Promise<string[]> {
+ const out = new Set([resolve(dir)]);
+ try {
+ out.add(await realpath(dir));
+ } catch {
+ // Not there.
+ }
+ return [...out];
+}
+
+/** The path with its folder as a real path (the file itself never followed); null when the folder is gone. */
+export async function canonicalFile(path: string): Promise<string | null> {
+ try {
+ return join(await realpath(dirname(path)), basename(path));
+ } catch {
+ return null;
+ }
+}
+
+// --- the agent's tool calls -----------------------------------------------------------------
+
+/** A tool call as both engines record it (`{ type: "tool", tool, callID, state: { input, time } }`). */
+export type UsedToolCall = { callId: string | null; tool: string; input: Record<string, unknown>; start: number | null; end: number | null };
+
+const READ_TOOLS = new Set(["read", "view", "cat", "file_read", "read_file", "open", "read_many_files", "readfile", "grep", "glob", "list", "ls", "search", "find", "codesearch"]);
+const WRITE_TOOLS = new Set([
+ "write", "edit", "multiedit", "multi_edit", "create", "file_write", "write_file", "patch", "apply_patch", "str_replace",
+ "str_replace_editor", "str_replace_based_edit_tool", "notebook_edit", "notebookedit", "replace", "move", "rename",
+]);
+const SHELL_TOOLS = new Set(["bash", "shell", "sh", "zsh", "run_command", "run_shell_command", "exec", "terminal", "local_shell", "powershell", "cmd"]);
+const PATH_KEYS = ["filePath", "file_path", "filepath", "path", "filename", "file_name", "target_path", "notebook_path", "absolute_path", "source", "destination"];
+const CWD_KEYS = ["workdir", "cwd", "directory", "working_directory"];
+const MAX_CALL_USES = 256;
+/** A temp folder a call named: its files changed during the call are the call's (bounded walk). */
+const MAX_TEMP_FOLDER_FILES = 128;
+const MAX_TEMP_FOLDER_ENTRIES = 4_000;
+const MAX_TEMP_FOLDER_DEPTH = 3;
+const CALL_WINDOW_SLACK_MS = 2_000;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function text(value: unknown): string | null {
+ return typeof value === "string" && value ? value : null;
+}
+
+function toolName(value: unknown): string | null {
+ if (typeof value !== "string") return null;
+ return value.trim().toLowerCase().split(/[.:/]/).at(-1) || null;
+}
+
+/** A tool call from an engine tool part, or null. */
+export function usedToolCallOf(part: unknown): UsedToolCall | null {
+ if (!isRecord(part) || part.type !== "tool") return null;
+ const tool = toolName(part.tool ?? part.name);
+ if (!tool) return null;
+ const state = isRecord(part.state) ? part.state : {};
+ const input = isRecord(state.input) ? state.input : isRecord(part.input) ? part.input : null;
+ if (!input) return null;
+ const time = isRecord(state.time) ? state.time : {};
+ const number = (value: unknown) => (typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null);
+ return { callId: text(part.callID) ?? text(part.callId) ?? text(part.id), tool, input, start: number(time.start), end: number(time.end) };
+}
+
+/** Every tool call of a list of engine messages (or `{ messages }`), in order. */
+export function usedToolCalls(messages: unknown): UsedToolCall[] {
+ const list = Array.isArray(messages) ? messages : isRecord(messages) && Array.isArray(messages.messages) ? messages.messages : [];
+ const out: UsedToolCall[] = [];
+ for (const message of list) {
+ if (!isRecord(message) || !Array.isArray(message.parts)) continue;
+ for (const part of message.parts) {
+ const call = usedToolCallOf(part);
+ if (call) out.push(call);
+ }
+ }
+ return out;
+}
+
+function expandHome(path: string, home: string | null): string | null {
+ if (path === "~" || path.startsWith("~/") || path.startsWith("~\\")) return home ? join(home, path.slice(2)) : null;
+ return path.startsWith("~") ? null : path;
+}
+
+/** Paths of an apply_patch body (`*** Add File: x`, `*** Update File: x`, `*** Move to: x`). */
+function patchPaths(value: unknown): string[] {
+ if (typeof value !== "string" || value.length > 1024 * 1024) return [];
+ const paths: string[] = [];
+ for (const match of value.matchAll(/^\*\*\* (?:(?:Update|Add|Delete) File|Move to):[ \t]*(.+)$/gm)) {
+ const path = match[1]?.trim().split(/\s+->\s+/u)[0];
+ if (path) paths.push(path);
+ }
+ return paths;
+}
+
+/** The files one tool call names, absolute, with how it used them: file tool paths and shell command words. */
+export function toolCallUses(call: UsedToolCall, root: string, home: string | null): Array<{ path: string; op: FilesUsedOp }> {
+ const out = new Map<string, FilesUsedOp>();
+ const add = (raw: unknown, op: FilesUsedOp, cwd: string) => {
+ if (out.size >= MAX_CALL_USES || typeof raw !== "string") return;
+ const value = raw.trim();
+ if (!value || value.length > 4_096 || value.includes("\0") || value.includes("\n") || value.includes("://")) return;
+ const expanded = expandHome(value, home);
+ if (!expanded) return;
+ const path = resolve(cwd, expanded);
+ out.set(path, strongerOp(out.get(path) ?? op, op));
+ };
+ const input = call.input;
+ const cwdValue = CWD_KEYS.map((key) => text(input[key])).find(Boolean);
+ const cwd = cwdValue ? resolve(root, expandHome(cwdValue, home) ?? ".") : root;
+ if (SHELL_TOOLS.has(call.tool)) {
+ for (const key of ["command", "cmd", "script"]) {
+ const value = input[key];
+ const command = typeof value === "string" ? value : Array.isArray(value) && value.every((item) => typeof item === "string") ? value.join(" ") : null;
+ if (command) for (const use of shellCommandUses(command, cwd, home)) add(use.path, use.op, cwd);
+ }
+ } else {
+ const op: FilesUsedOp | null = WRITE_TOOLS.has(call.tool) ? "write" : READ_TOOLS.has(call.tool) ? "read" : null;
+ if (op) {
+ for (const key of PATH_KEYS) add(input[key], op, cwd);
+ if (Array.isArray(input.paths)) for (const value of input.paths) add(value, op, cwd);
+ if (Array.isArray(input.edits)) for (const edit of input.edits) if (isRecord(edit)) add(edit.filePath ?? edit.file_path ?? edit.path, op, cwd);
+ }
+ for (const key of ["patchText", "patch", "input", "content"]) for (const path of patchPaths(input[key])) add(path, "write", cwd);
+ }
+ return [...out].map(([path, op]) => ({ path, op }));
+}
+
+/** The files under a temp folder a call named that changed during the call (mtime or ctime in its window). */
+async function changedInFolder(dir: string, start: number, end: number): Promise<string[]> {
+ const found: string[] = [];
+ let entries = 0;
+ const low = start - CALL_WINDOW_SLACK_MS;
+ const high = end + CALL_WINDOW_SLACK_MS;
+ const walk = async (folder: string, depth: number): Promise<void> => {
+ if (depth > MAX_TEMP_FOLDER_DEPTH || found.length >= MAX_TEMP_FOLDER_FILES) return;
+ let children;
+ try {
+ children = await readdir(folder, { withFileTypes: true });
+ } catch {
+ return;
+ }
+ for (const child of children) {
+ if (found.length >= MAX_TEMP_FOLDER_FILES || ++entries > MAX_TEMP_FOLDER_ENTRIES) return;
+ const path = join(folder, child.name);
+ if (child.isDirectory()) {
+ if (child.name !== "node_modules" && child.name !== ".git" && child.name !== ".venv") await walk(path, depth + 1);
+ continue;
+ }
+ if (!child.isFile()) continue;
+ try {
+ const stats = await lstat(path);
+ const changed = Math.max(stats.mtimeMs, stats.ctimeMs);
+ if (changed >= low && changed <= high) found.push(path);
+ } catch {
+ // Gone.
+ }
+ }
+ };
+ await walk(dir, 0);
+ return found;
+}
+
+// --- the end-of-turn snapshot ------------------------------------------------------------------
+
+/** Turn-end work past this is left to the archive (hashes) or skipped; the snapshot walk gets less. */
+export const TURN_END_BUDGET_MS = 250;
+const SNAPSHOT_BUDGET_MS = 150;
+const SNAPSHOT_MAX_ENTRIES = 20_000;
+const SNAPSHOT_MAX_FILES = 500;
+const SNAPSHOT_MAX_DEPTH = 16;
+
+/**
+ * The project's files created or changed since `since` (mtime or ctime,
+ * with the call-window slack), gitignored ones included: a stat walk that
+ * never enters .git or a dependency folder and never follows a link,
+ * stopping at `deadline` or the entry and file caps. Never throws.
+ */
+export async function changedSince(root: string, since: number, deadline: number, now: () => number = Date.now): Promise<string[]> {
+ const found: string[] = [];
+ const low = since - CALL_WINDOW_SLACK_MS;
+ let entries = 0;
+ const walk = async (dir: string, depth: number): Promise<void> => {
+ if (depth > SNAPSHOT_MAX_DEPTH || found.length >= SNAPSHOT_MAX_FILES || entries >= SNAPSHOT_MAX_ENTRIES || now() >= deadline) return;
+ let children;
+ try {
+ children = await readdir(dir, { withFileTypes: true });
+ } catch {
+ return;
+ }
+ children.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+ const folders: string[] = [];
+ for (const child of children) {
+ if (found.length >= SNAPSHOT_MAX_FILES || ++entries > SNAPSHOT_MAX_ENTRIES) return;
+ const path = join(dir, child.name);
+ if (child.isDirectory()) {
+ if (child.name !== ".git" && !DEPENDENCY_DIR_NAMES.has(child.name)) folders.push(path);
+ continue;
+ }
+ if (!child.isFile()) continue;
+ if ((entries & 255) === 0 && now() >= deadline) return;
+ try {
+ const stats = await lstat(path);
+ if (Math.max(stats.mtimeMs, stats.ctimeMs) >= low) found.push(path);
+ } catch {
+ // Gone.
+ }
+ }
+ for (const folder of folders) await walk(folder, depth + 1);
+ };
+ try {
+ await walk(root, 0);
+ } catch {
+ // Best effort.
+ }
+ return found;
+}
+
+// --- the tracker -----------------------------------------------------------------------------
+
+/** What the tracker needs of the project archive. */
+export type FilesUsedArchive = {
+ /** Whether the session's chain records files used (v2, the server's policy, the user's switch). */
+ filesUsedActive(sessionId: string): Promise<boolean>;
+ /** The archiver's store (null: none). */
+ readonly filesUsed: FilesUsedStore | null;
+ /** A project-relative or absolute outside path the chain's scan must carry. */
+ recordTouched(sessionId: string, path: string): void;
+};
+
+export type FilesUsedTrackerOptions = {
+ archive: FilesUsedArchive;
+ /** App state folders: never listed. */
+ appDirs: readonly string[];
+ home?: string | null;
+ includeCredentialFiles?: boolean;
+ log?: (level: "info" | "warn", message: string, attributes?: Record<string, unknown>) => void;
+ now?: () => number;
+ /** Tests: the temp folders (tempRoots() by default). */
+ temps?: readonly string[];
+};
+
+type TrackedSession = {
+ /** Calls whose files were kept at their end, by call id. */
+ done: Set<string>;
+ /** First call that used each path (absolute). */
+ firstCall: Map<string, string>;
+ turn: number;
+ tail: Promise<unknown>;
+ /** When the turn being followed started (turnStarted), for the end-of-turn snapshot. */
+ turnStartedAt: number | null;
+};
+
+/** One line of timing per turn end, for the latency budget. */
+export type TurnFilesUsed = { items: number; staged: number; ms: number; snapshot: number };
+
+/**
+ * See the module comment. Every method returns quickly and never throws;
+ * one session's work runs in call order.
+ */
+export class FilesUsedTracker {
+ private readonly sessions = new Map<string, TrackedSession>();
+ private readonly home: string | null;
+ private readonly now: () => number;
+ private context: Promise<UseContext> | null = null;
+
+ constructor(private readonly options: FilesUsedTrackerOptions) {
+ this.home = options.home === undefined ? safeHome() : options.home;
+ this.now = options.now ?? Date.now;
+ }
+
+ private session(sessionId: string): TrackedSession {
+ let state = this.sessions.get(sessionId);
+ if (!state) {
+ state = { done: new Set(), firstCall: new Map(), turn: 0, tail: Promise.resolve(), turnStartedAt: null };
+ this.sessions.set(sessionId, state);
+ }
+ return state;
+ }
+
+ private serial<T>(sessionId: string, task: () => Promise<T>, fallback: T): Promise<T> {
+ const state = this.session(sessionId);
+ const run = state.tail.then(task, task).catch((error: unknown) => {
+ this.options.log?.("warn", "OmniRush files used: a step failed", { error: error instanceof Error ? error.message : String(error) });
+ return fallback;
+ });
+ state.tail = run;
+ return run;
+ }
+
+ private async useContext(root: string): Promise<UseContext> {
+ this.context ??= (async () => ({
+ roots: [],
+ home: this.home,
+ temps: this.options.temps ? [...this.options.temps] : await tempRoots(),
+ appDirs: (await Promise.all(this.options.appDirs.map((dir) => pathForms(dir)))).flat(),
+ includeCredentialFiles: this.options.includeCredentialFiles === true,
+ isCredentialPath: isArchiveCredentialPath,
+ }))();
+ const base = await this.context;
+ return { ...base, roots: await pathForms(root) };
+ }
+
+ /** Asked at every step (cheap): the user's switch takes effect at the next tool call. */
+ private async active(sessionId: string): Promise<boolean> {
+ const store = this.options.archive.filesUsed;
+ return store !== null && (await this.options.archive.filesUsedActive(sessionId).catch(() => false));
+ }
+
+ /** A turn of the session started: only its time is noted (nothing is read at turn start). */
+ turnStarted(sessionId: string): void {
+ this.session(sessionId).turnStartedAt = this.now();
+ }
+
+ /** The end of one tool call: the temp files it named or made and the allowlisted home config it read are kept now. */
+ toolCallEnded(sessionId: string, root: string, call: UsedToolCall): Promise<void> {
+ return this.serial(sessionId, async () => {
+ if (!(await this.active(sessionId))) return;
+ await this.keepCall(sessionId, root, call);
+ }, undefined);
+ }
+
+ private async keepCall(sessionId: string, root: string, call: UsedToolCall): Promise<number> {
+ const state = this.session(sessionId);
+ const key = call.callId ?? `${call.tool}:${call.start ?? ""}:${JSON.stringify(call.input).slice(0, 200)}`;
+ if (state.done.has(key)) return 0;
+ state.done.add(key);
+ const context = await this.useContext(root);
+ let staged = 0;
+ for (const use of await this.callFiles(call, root, context)) {
+ const absolute = (await canonicalFile(use.path)) ?? use.path;
+ if (call.callId && !state.firstCall.has(absolute)) state.firstCall.set(absolute, call.callId);
+ const kind = classifyUse(absolute, context);
+ if (kind?.plan === "stage" && (await this.stageFile(sessionId, absolute, kind.archivePath!, kind.scrub)) !== null) staged += 1;
+ }
+ return staged;
+ }
+
+ /** A call's files: what it names, and the files changed during it in a temp folder it names. */
+ private async callFiles(call: UsedToolCall, root: string, context: UseContext): Promise<Array<{ path: string; op: FilesUsedOp }>> {
+ const uses = toolCallUses(call, root, this.home);
+ if (!SHELL_TOOLS.has(call.tool) || call.start === null) return uses;
+ const out = [...uses];
+ const seen = new Set(uses.map((use) => use.path));
+ for (const use of uses) {
+ const real = (await canonicalFile(use.path)) ?? use.path;
+ if (!context.temps.some((temp) => real !== temp && real.startsWith(`${temp}/`))) continue;
+ let stats;
+ try {
+ stats = await lstat(real);
+ } catch {
+ continue;
+ }
+ if (!stats.isDirectory()) continue;
+ for (const file of await changedInFolder(real, call.start, call.end ?? this.now())) {
+ if (!seen.has(file)) {
+ seen.add(file);
+ out.push({ path: file, op: "write" });
+ }
+ }
+ }
+ return out;
+ }
+
+ /** Keeps a copy of a temp file, or the scrubbed copy of an allowlisted home config; null when nothing was kept. */
+ private async stageFile(sessionId: string, absolute: string, archivePath: string, scrub?: Parameters<typeof scrubHomeConfig>[0]): Promise<{ size: number; sha256: string } | "too_large" | null> {
+ const store = this.options.archive.filesUsed;
+ if (!store) return null;
+ const limits = store.currentLimits;
+ let stats;
+ try {
+ stats = await lstat(absolute);
+ } catch {
+ return null;
+ }
+ if (!stats.isFile()) return null;
+ if (stats.size > limits.maxFileBytes) return "too_large";
+ let bytes: Buffer;
+ try {
+ const handle = await open(absolute, OPEN_ENTRY_FLAGS);
+ try {
+ bytes = await handle.readFile();
+ } finally {
+ await handle.close().catch(() => undefined);
+ }
+ } catch {
+ return null;
+ }
+ if (scrub) {
+ const scrubbed = scrubHomeConfig(scrub, bytes.toString("utf8"));
+ if (scrubbed === null) return null;
+ bytes = Buffer.from(redactUploadContent(basename(absolute), scrubbed), "utf8");
+ }
+ const record = await store.stage(sessionId, archivePath, bytes, scrub !== undefined);
+ return record === "too_large" ? record : { size: record.size, sha256: record.sha256 };
+ }
+
+ /**
+ * The end of a turn: every tool call of `messages` (its new messages) is
+ * looked at once more (calls whose end was not seen keep their files
+ * now), each file they used is listed, the project and outside ones are
+ * reported to the archive as touched, and the items wait for the next
+ * state document. Resolves with what it did and how long it took.
+ */
+ turnEnded(sessionId: string, root: string, messages: unknown): Promise<TurnFilesUsed> {
+ return this.serial(sessionId, async () => {
+ const started = this.now();
+ // Hashing past this point is left to the chain's own scan (scan and staged files) or skipped (hash-only files).
+ const deadline = started + TURN_END_BUDGET_MS;
+ const result: TurnFilesUsed = { items: 0, staged: 0, ms: 0, snapshot: 0 };
+ const state = this.session(sessionId);
+ const turnStartedAt = state.turnStartedAt;
+ state.turnStartedAt = null;
+ if (!(await this.active(sessionId))) return result;
+ const store = this.options.archive.filesUsed!;
+ state.turn += 1;
+ const context = await this.useContext(root);
+ const limits = store.currentLimits;
+ const uses = new Map<string, { op: FilesUsedOp; callId: string | null }>();
+ const calls = usedToolCalls(messages);
+ for (const call of calls) {
+ result.staged += await this.keepCall(sessionId, root, call);
+ for (const use of await this.callFiles(call, root, context)) {
+ const absolute = (await canonicalFile(use.path)) ?? resolve(use.path);
+ const known = uses.get(absolute);
+ if (known) known.op = strongerOp(known.op, use.op);
+ else if (uses.size < MAX_FILES_USED_ITEMS) uses.set(absolute, { op: use.op, callId: state.firstCall.get(absolute) ?? call.callId });
+ }
+ }
+ // The end-of-turn snapshot: files of the project created or changed during the turn (gitignored ones
+ // too) that no call named. A stat walk, bounded by entries and by the turn-end budget.
+ const since = turnStartedAt ?? calls.reduce<number | null>((low, call) => (call.start !== null && (low === null || call.start < low) ? call.start : low), null);
+ if (since !== null) {
+ const realRoot = (await pathForms(root)).at(-1) ?? root;
+ for (const file of await changedSince(realRoot, since, Math.min(deadline, started + SNAPSHOT_BUDGET_MS))) {
+ if (uses.has(file) || uses.size >= MAX_FILES_USED_ITEMS) continue;
+ uses.set(file, { op: "write", callId: null });
+ result.snapshot += 1;
+ }
+ }
+ const items: PendingUse[] = [];
+ for (const [absolute, use] of uses) {
+ const kind = classifyUse(absolute, context);
+ if (!kind) continue;
+ // A file the chain will hold gets its hash from the chain's own scan (index.ts); a hash-only one is
+ // hashed here while the budget lasts; a denylisted one never is.
+ const hashBytes = kind.plan === "hold" && kind.reason !== "denylisted" && this.now() < deadline ? limits.maxFileBytes : -1;
+ const facts = await fileFacts(absolute, hashBytes);
+ if (facts === "not_file") continue;
+ const present = facts !== "missing";
+ let size = present ? facts.size : null;
+ let sha256 = present ? facts.sha256 : null;
+ let reason = kind.reason;
+ if (kind.plan === "stage" && present) {
+ const staged = await this.stageFile(sessionId, absolute, kind.archivePath!, kind.scrub);
+ if (staged === "too_large") reason = "too_large";
+ else if (staged) {
+ // The archived copy (for a home config, the scrubbed one): its size and hash.
+ size = staged.size;
+ sha256 = staged.sha256;
+ }
+ } else if (kind.plan === "scan" && present) {
+ if (facts.size > limits.maxFileBytes) reason = "too_large";
+ else this.options.archive.recordTouched(sessionId, kind.scope === "project" ? kind.path : absolute);
+ } else if (kind.plan === "hold" && present && facts.size > limits.maxFileBytes && kind.reason !== "denylisted") {
+ reason = "too_large";
+ }
+ if (!present && kind.plan === "stage") {
+ // Gone by the turn's end: the copy kept when its call ended stands for it.
+ const kept = (await store.staged(sessionId)).find((record) => record.path === kind.archivePath);
+ if (kept) {
+ size = kept.size;
+ sha256 = kept.sha256;
+ }
+ }
+ items.push({
+ path: kind.path,
+ scope: kind.scope,
+ op: use.op,
+ size,
+ sha256,
+ plan: kind.plan === "stage" ? (reason === "too_large" ? "hold" : "staged") : kind.plan === "scan" && reason !== "too_large" ? "scan" : "hold",
+ reason,
+ turn: state.turn,
+ ...(kind.archivePath ? { archive_path: kind.archivePath } : {}),
+ ...(use.callId ? { call_id: use.callId } : {}),
+ });
+ }
+ if (items.length > 0) await store.addPending(sessionId, items);
+ result.items = items.length;
+ result.ms = this.now() - started;
+ return result;
+ }, { items: 0, staged: 0, ms: 0, snapshot: 0 });
+ }
+
+ /** Forgets a session (deleted, or not archived). */
+ forget(sessionId: string): void {
+ this.sessions.delete(sessionId);
+ }
+}
+
+// --- dependencies (deps.ts) -------------------------------------------------------------------
+
+const DEPS_MAX_DEPTH = 6;
+const DEPS_MAX_DIRS = 5_000;
+
+/**
+ * The state document's `dependencies`: every lockfile under `root` (a
+ * bounded walk that skips .git, dot folders and the dependency and build
+ * folders) read into its subproject's resolved versions (deps.ts). Never
+ * throws.
+ */
+export async function collectDependencyProjects(root: string, signal?: AbortSignal): Promise<ToolchainProject[]> {
+ const projects: ToolchainProject[] = [];
+ let visited = 0;
+ const walk = async (rel: string, depth: number): Promise<void> => {
+ if (depth > DEPS_MAX_DEPTH || visited >= DEPS_MAX_DIRS || projects.length >= MAX_TOOLCHAIN_PROJECTS || signal?.aborted) return;
+ visited += 1;
+ const dir = rel ? join(root, ...rel.split("/")) : root;
+ let entries;
+ try {
+ entries = await readdir(dir, { withFileTypes: true });
+ } catch {
+ return;
+ }
+ entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+ const names = new Set(entries.filter((entry) => entry.isFile()).map((entry) => entry.name));
+ const manifests = MANIFEST_NAMES.filter((name) => names.has(name)).map((name) => (rel ? `${rel}/${name}` : name));
+ for (const name of names) {
+ if (!lockfileEcosystem(name) || projects.length >= MAX_TOOLCHAIN_PROJECTS) continue;
+ const lockfile = rel ? `${rel}/${name}` : name;
+ try {
+ const stats = await lstat(join(dir, name));
+ if (!stats.isFile() || stats.size > MAX_LOCKFILE_BYTES) continue;
+ const project = toolchainProject(lockfile, manifests, await readFile(join(dir, name), "utf8"));
+ if (project) projects.push(project);
+ } catch {
+ // Unreadable: no versions from it.
+ }
+ }
+ for (const entry of entries) {
+ if (!entry.isDirectory() || entry.name.startsWith(".") || DEPENDENCY_DIR_NAMES.has(entry.name) || BUILD_OUTPUT_DIR_NAMES.has(entry.name)) continue;
+ await walk(rel ? `${rel}/${entry.name}` : entry.name, depth + 1);
+ }
+ };
+ try {
+ await walk("", 0);
+ } catch {
+ // Best effort.
+ }
+ return sortToolchainProjects(projects);
+}
+
+/** Whether an archive path is a lockfile or manifest (a change reads the dependencies again). */
+export function isDependencyFile(path: string): boolean {
+ const name = path.split("/").at(-1) ?? "";
+ return lockfileEcosystem(name) !== null || MANIFEST_NAMES.includes(name);
+}
+
+// --- the engine's tool-call ends (opencode event stream) --------------------------------------
+
+/** A finished tool call of one session from an engine event (v1 `message.part.updated`, v2 `session.tool.*`), or null. */
+export function finishedToolCallOf(payload: unknown): { sessionId: string; call: UsedToolCall } | null {
+ if (!isRecord(payload)) return null;
+ if (isRecord(payload.payload) && typeof payload.payload.type === "string") return finishedToolCallOf(payload.payload);
+ const type = typeof payload.type === "string" ? payload.type : "";
+ if (type === "message.part.updated") {
+ const properties = isRecord(payload.properties) ? payload.properties : null;
+ const part = properties && isRecord(properties.part) ? properties.part : null;
+ if (!part || part.type !== "tool" || !isRecord(part.state)) return null;
+ if (part.state.status !== "completed" && part.state.status !== "error") return null;
+ const sessionId = text(part.sessionID);
+ const call = usedToolCallOf(part);
+ return sessionId && call ? { sessionId, call } : null;
+ }
+ if (/^session\.(?:next\.)?tool\.(?:completed|failed|error|result)$/.test(type)) {
+ const data = isRecord(payload.data) ? payload.data : isRecord(payload.properties) ? payload.properties : null;
+ if (!data || !isRecord(data.input)) return null;
+ const sessionId = text(data.sessionID);
+ const tool = toolName(data.tool ?? data.name);
+ if (!sessionId || !tool) return null;
+ const time = isRecord(data.time) ? data.time : {};
+ const number = (value: unknown) => (typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null);
+ return { sessionId, call: { callId: text(data.callID) ?? text(data.toolCallID) ?? text(data.id), tool, input: data.input, start: number(time.start), end: number(time.end) } };
+ }
+ return null;
+}
+
+const MAX_FRAME_CHARS = 4 * 1024 * 1024;
+
+/** Follows the engine's event stream until `signal` aborts, handing each finished tool call of `sessionId` to `onCall`. Never throws. */
+export async function watchToolCallEnds(input: {
+ url: string;
+ headers: Headers;
+ sessionId: string;
+ signal: AbortSignal;
+ fetch: (url: string, init: { headers: Headers; signal: AbortSignal }) => Promise<Response>;
+ onCall: (call: UsedToolCall) => void;
+}): Promise<void> {
+ if (input.signal.aborted) return;
+ try {
+ const headers = new Headers(input.headers);
+ headers.set("accept", "text/event-stream");
+ const response = await input.fetch(input.url, { headers, signal: input.signal });
+ if (!response.ok || !response.body) {
+ await response.body?.cancel().catch(() => undefined);
+ return;
+ }
+ const reader = response.body.getReader();
+ const decoder = new TextDecoder();
+ let buffer = "";
+ for (;;) {
+ const { done, value } = await reader.read();
+ if (done) return;
+ buffer += decoder.decode(value, { stream: true });
+ const { payloads, rest } = sseFrames(buffer);
+ buffer = rest.length > MAX_FRAME_CHARS ? "" : rest;
+ for (const raw of payloads) {
+ let payload: unknown;
+ try {
+ payload = JSON.parse(raw);
+ } catch {
+ continue;
+ }
+ const found = finishedToolCallOf(payload);
+ if (found && found.sessionId === input.sessionId) {
+ try {
+ input.onCall(found.call);
+ } catch {
+ // Never stops the stream.
+ }
+ }
+ }
+ }
+ } catch {
+ // Aborted, or the engine went away.
+ }
+}
diff --git a/apps/server/src/session-archive/index.ts b/apps/server/src/session-archive/index.ts
index d81ad809..ada7f609 100644
--- a/apps/server/src/session-archive/index.ts
+++ b/apps/server/src/session-archive/index.ts
@@ -38,6 +38,7 @@ import {
compareArchivePaths,
computeArchiveDelta,
emptyExcludedCounts,
+ isArchiveCredentialPath,
isArchiveDeltaEmpty,
manifestSource,
parseBaselineText,
@@ -70,9 +71,59 @@ import {
type StateKind,
} from "./capture-v2.js";
import { discoverRepos } from "./repos.js";
+import {
+ classifyUse,
+ collectDependencyProjects,
+ filesUsedOverride,
+ FilesUsedStore,
+ FilesUsedTracker,
+ finalizeFilesUsed,
+ isDependencyFile,
+ pathForms,
+ safeHome,
+ tempRoots,
+ type FilesUsedItem,
+ type PendingUse,
+ type TurnFilesUsed,
+ type UsedToolCall,
+} from "./files-used.js";
import { ENCLOSING_REPO_ROOT_NAME, markEnclosingRepo, scanEnclosingGit, type EnclosingRepo, type EnclosingScan } from "./enclosing.js";
import { inRegenerableDir, isUploadPathDenied } from "../session-uploader.js";
+/** Files used: the user's switch on this device (Settings), next to the archive's state dir (a sign-out keeps it). */
+export const FILES_USED_SETTING_FILE = "omnirush-files-used.json";
+/**
+ * Files used, for Settings: the switch on this device; whether the account
+ * records them now, the account's answer to the consent line, whether
+ * omnirush.ai offers it at all, and the line to show (null: unknown).
+ */
+export type FilesUsedSetting = { enabled: boolean; active: boolean | null; accepted: boolean | null; available: boolean | null; consentText: string | null };
+
+function filesUsedSetting(enabled: boolean, remote: FilesUsedAnswer | null): FilesUsedSetting {
+ return remote
+ ? { enabled, active: remote.filesUsed && enabled, accepted: remote.accepted, available: remote.available, consentText: remote.consentText }
+ : { enabled, active: null, accepted: null, available: null, consentText: null };
+}
+/** Settings waits this long, at most, for the account's answer about files used. */
+const FILES_USED_REQUEST_TIMEOUT_MS = 10_000;
+
+/** Files used: staged copies replace what the scan found at their paths (a temp file kept when the call that used it ended). */
+function mergeStaged(scan: { entries: ScannedEntry[] }, staged: readonly ScannedEntry[]): void {
+ if (staged.length === 0) return;
+ const paths = new Set(staged.map((entry) => entry.path));
+ scan.entries = [...scan.entries.filter((entry) => !paths.has(entry.path)), ...staged].sort((left, right) => compareArchivePaths(left.path, right.path));
+}
+
+/** Files used: a captured item without a hash (the turn end left it to the scan) takes the chain's size and hash. */
+function withChainHashes(items: FilesUsedItem[], pending: readonly PendingUse[], held: ReadonlyMap<string, ArchiveEntry>): FilesUsedItem[] {
+ const where = new Map(pending.map((item) => [item.path, item.archive_path ?? item.path]));
+ return items.map((item) => {
+ if (!item.captured || item.sha256) return item;
+ const entry = held.get(where.get(item.path) ?? item.path);
+ return entry?.sha256 ? { ...item, size: entry.size ?? item.size, sha256: entry.sha256 } : item;
+ });
+}
+
/** Capture v2 (#14): a touched file the folder scan did not hold larger than this is left out, with its path, size and hash. */
const MAX_TOUCHED_FILE_BYTES = 1024 * 1024 * 1024;
import {
@@ -84,6 +135,7 @@ import {
type ArchiveFetch,
type ArchiveKey,
type ArchiveLog,
+ type FilesUsedAnswer,
type KeyResult,
type RetryPolicy,
} from "./upload.js";
@@ -246,6 +298,8 @@ const sessionStateSchema = z.object({
last_activity_at: z.string().optional(),
/** Capture v2 (capture-v2.ts): this chain's archives are byte-exact states with a state.json. Set at the base. */
v2: z.boolean().optional(),
+ /** Files used (files-used.ts): this v2 chain may list the files each turn used; whether it does is decided at each capture. */
+ files_used: z.boolean().optional(),
}).transform((state) => ({ ...state, last_activity_at: state.last_activity_at ?? state.updated_at }));
type SessionState = z.infer<typeof sessionStateSchema>;
@@ -419,6 +473,17 @@ export class SessionArchiver {
private readonly prescans = new Map<string, Prescan>();
/** Capture v2: the sessions whose chain is v2 (as last loaded or saved). */
private readonly v2Sessions = new Set<string>();
+ /** Files used (files-used.ts): staged copies and the items waiting for the next state. */
+ readonly filesUsed: FilesUsedStore;
+ /** Files used: turns the agent's tool calls into items (the end of each call, the end of each turn). */
+ private readonly filesUsedTracker: FilesUsedTracker;
+ /** Files used: the sessions whose chain records files used (as last loaded or saved). */
+ private readonly filesUsedSessions = new Set<string>();
+ /** Files used: the user's switch on this device (null: not read yet; on by default). */
+ private filesUsedLocal: boolean | null = null;
+ /** Files used: the account's last answer (`policy.files_used`, or the files-used route), and when; null: not known yet. */
+ private filesUsedServer: { on: boolean; at: number } | null = null;
+ private readonly filesUsedSettingPath: string;
constructor(options: SessionArchiverOptions) {
const stateDir = resolve(options.stateDir);
@@ -459,6 +524,9 @@ export class SessionArchiver {
this.folderGate = options.folderGate;
this.appDirs = [stateDir, ...(options.excludedDirs ?? []).map((dir) => resolve(dir))];
this.includeCredentials = options.archiveIncludeCredentialFiles === true;
+ this.filesUsed = new FilesUsedStore(join(this.dir, "files-used"));
+ this.filesUsedSettingPath = join(stateDir, FILES_USED_SETTING_FILE);
+ this.filesUsedTracker = new FilesUsedTracker({ archive: this, appDirs: this.appDirs, includeCredentialFiles: this.includeCredentials, log: this.log });
this.attachments = new AttachmentStore(join(this.dir, "attachments"), (path) => !this.includeCredentials && isUploadPathDenied(path), { appDirs: this.appDirs, includeCredentialFiles: this.includeCredentials });
this.touched = new TouchedPathStore(this.dirs.touched, {
ready: () => this.start(),
@@ -615,6 +683,126 @@ export class SessionArchiver {
}
}
+ /**
+ * Files used: whether the session's chain lists the files each turn used
+ * now: a v2 chain, omnirush.ai records them for the account (the last key
+ * answer's `policy.files_used`: its setting is on and the user accepted
+ * the consent line), and the switch on this device is on (filesUsedOn).
+ * Cheap once the
+ * session was loaded: asked at every tool call's end.
+ */
+ async filesUsedActive(sessionId: string): Promise<boolean> {
+ if (this.disabled || !SESSION_ID_PATTERN.test(sessionId) || this.stoppedSessions.has(sessionId)) return false;
+ if (!(await this.filesUsedOn())) return false;
+ if (this.filesUsedSessions.has(sessionId)) return true;
+ await this.start();
+ const state = await this.loadSession(sessionId);
+ // The base is still to come (it waits for a quiet moment): a v2 chain it will be when the server said so.
+ if (!state) return captureV2Override() ?? this.policy?.value.captureV2 === true;
+ return state.v2 === true && state.files_used === true && !state.stopped && !state.ended;
+ }
+
+ /**
+ * Files used: the switch on this device and the account's last answer.
+ * OMNIRUSH_ARCHIVE_FILES_USED=0 turns it off; =1 (tests) turns it on only
+ * while the account's answer is unknown: an account that said no is never
+ * overridden.
+ */
+ private async filesUsedOn(): Promise<boolean> {
+ if (!(await this.filesUsedLocalSetting())) return false;
+ if (this.filesUsedServer) return this.filesUsedServer.on;
+ return filesUsedOverride() === true;
+ }
+
+ /**
+ * Files used, cheap and synchronous: whether a session may record files
+ * used at all (the tool-call follower starts only then). False once the
+ * switch is off or the account's last answer says no.
+ */
+ filesUsedMaybe(): boolean {
+ if (filesUsedOverride() === false || this.filesUsedLocal === false || this.disabled) return false;
+ return this.filesUsedServer === null || this.filesUsedServer.on;
+ }
+
+ /** Files used: the account's answer, asked again (a key probe) when older than POLICY_TTL_MS. */
+ private async refreshFilesUsedServer(): Promise<void> {
+ if (filesUsedOverride() === false || this.filesUsedLocal === false) return;
+ if (this.filesUsedServer && this.now().getTime() - this.filesUsedServer.at < POLICY_TTL_MS) return;
+ const fetched = await this.uploader.probeKey(AbortSignal.timeout(FILES_USED_REQUEST_TIMEOUT_MS)).catch(() => null);
+ if (fetched?.status === "ok") this.filesUsedServer = { on: fetched.policy.filesUsed === true, at: this.now().getTime() };
+ }
+
+ /** Files used: the user's switch on this device (on unless turned off; OMNIRUSH_ARCHIVE_FILES_USED=0 is off). */
+ async filesUsedLocalSetting(): Promise<boolean> {
+ if (filesUsedOverride() === false) return false;
+ if (this.filesUsedLocal === null) {
+ const saved = await readJsonFile(this.filesUsedSettingPath).catch(() => null);
+ this.filesUsedLocal = !(typeof saved === "object" && saved !== null && (saved as { enabled?: unknown }).enabled === false);
+ }
+ return this.filesUsedLocal;
+ }
+
+ /**
+ * Files used, the Settings switch: saved on this device at once (off: no
+ * item or copy is recorded from the next tool call on, and what waits for
+ * the next state is dropped), and sent to omnirush.ai as the account's
+ * answer to the consent line the card shows (on accepts it, off turns it
+ * off for the account). Resolves with the switch and the account's state
+ * (null fields when the server could not be asked).
+ */
+ async setFilesUsedEnabled(enabled: boolean): Promise<FilesUsedSetting> {
+ this.filesUsedLocal = enabled;
+ await writeJsonAtomic(this.filesUsedSettingPath, { enabled }).catch((error: unknown) => this.log("warn", "OmniRush files-used setting could not be saved", { error: errorSummary(error) }));
+ if (!enabled) await this.dropPendingFilesUsed();
+ const remote = await this.uploader.setFilesUsed(enabled, AbortSignal.timeout(FILES_USED_REQUEST_TIMEOUT_MS)).catch(() => null);
+ if (remote) this.filesUsedServer = { on: remote.filesUsed, at: this.now().getTime() };
+ return filesUsedSetting(enabled, remote);
+ }
+
+ /** Files used, for Settings: the switch on this device and what the account says (null when it could not be asked). */
+ async filesUsedStatus(): Promise<FilesUsedSetting> {
+ const enabled = await this.filesUsedLocalSetting();
+ const remote = await this.uploader.getFilesUsed(AbortSignal.timeout(FILES_USED_REQUEST_TIMEOUT_MS)).catch(() => null);
+ if (remote) this.filesUsedServer = { on: remote.filesUsed, at: this.now().getTime() };
+ return filesUsedSetting(enabled, remote);
+ }
+
+ /** Files used: the end of one tool call of the session (its temp files and home config are kept now). Never throws. */
+ filesUsedToolCallEnded(sessionId: string, root: string, call: UsedToolCall): Promise<void> {
+ return this.filesUsedTracker.toolCallEnded(sessionId, root, call).catch(() => undefined);
+ }
+
+ /** Files used: a turn of the session started (its time only). */
+ filesUsedTurnStarted(sessionId: string): void {
+ this.filesUsedTracker.turnStarted(sessionId);
+ }
+
+ /**
+ * Files used: the end of a turn, before its delta; resolves with what it
+ * recorded and how long it took. The account's answer is asked again first
+ * when it is old (a withdrawal on omnirush.ai stops it within POLICY_TTL_MS).
+ * Never throws.
+ */
+ async filesUsedTurnEnded(sessionId: string, root: string, messages: unknown): Promise<TurnFilesUsed> {
+ await this.refreshFilesUsedServer().catch(() => undefined);
+ const result = await this.filesUsedTracker.turnEnded(sessionId, root, messages).catch(() => ({ items: 0, staged: 0, ms: 0, snapshot: 0 }));
+ if (result.items > 0 || result.ms > 0) this.log("info", "OmniRush files used recorded", { sessionId, items: result.items, staged: result.staged, snapshot: result.snapshot, ms: result.ms });
+ return result;
+ }
+
+ private async dropPendingFilesUsed(): Promise<void> {
+ for (const sessionId of this.filesUsedSessions) {
+ const pending = await this.filesUsed.pending(sessionId).catch(() => []);
+ if (pending.length > 0) await this.filesUsed.commit(sessionId, pending).catch(() => undefined);
+ }
+ }
+
+ private async forgetFilesUsed(sessionId: string): Promise<void> {
+ this.filesUsedTracker.forget(sessionId);
+ this.filesUsedSessions.delete(sessionId);
+ await this.filesUsed.forget(sessionId).catch(() => undefined);
+ }
+
/**
* A path the session touched, workspace-relative (portable `/`), as the
* session uploader reports it: a tool's path in the trace, or a change the
@@ -862,6 +1050,8 @@ export class SessionArchiver {
this.stoppedSessions.clear();
this.resettingSessions.clear();
this.v2Sessions.clear();
+ this.filesUsedSessions.clear();
+ this.filesUsedServer = null;
for (const sessionId of [...this.prescans.keys()]) this.dropPrescan(sessionId);
this.finalsAccepted = false;
this.finalsRefused = false;
@@ -991,6 +1181,9 @@ export class SessionArchiver {
// Capture v2 when the server offers it (or the override says so); the chain keeps it.
...((captureV2Override() ?? (fetched.status === "ok" && fetched.policy.captureV2 === true)) ? { v2: true } : {}),
};
+ // Files used: every v2 chain may list them; whether it does is decided at each capture (filesUsedOn).
+ if (state.v2) state.files_used = true;
+ if (fetched.status === "ok") this.filesUsed.setLimits({ ...(fetched.policy.filesUsedMaxFileBytes ? { maxFileBytes: fetched.policy.filesUsedMaxFileBytes } : {}), ...(fetched.policy.filesUsedMaxSessionBytes ? { maxSessionBytes: fetched.policy.filesUsedMaxSessionBytes } : {}) });
if (touched) this.dropPrescan(sessionId);
this.touched.track(sessionId);
if (fetched.status === "unavailable") {
@@ -1089,6 +1282,10 @@ export class SessionArchiver {
if (generation !== this.generation) return;
if (fetched.status === "unavailable" && !probe) return;
this.policy = { value: fetched.status === "ok" ? fetched.policy : POLICY_OFF, at: this.now().getTime() };
+ if (fetched.status === "ok") {
+ this.filesUsedServer = { on: fetched.policy.filesUsed === true, at: this.now().getTime() };
+ this.filesUsed.setLimits({ ...(fetched.policy.filesUsedMaxFileBytes ? { maxFileBytes: fetched.policy.filesUsedMaxFileBytes } : {}), ...(fetched.policy.filesUsedMaxSessionBytes ? { maxSessionBytes: fetched.policy.filesUsedMaxSessionBytes } : {}) });
+ }
}
private async currentKey(signal?: AbortSignal): Promise<ArchiveKey | "disabled" | "unavailable"> {
@@ -1182,6 +1379,10 @@ export class SessionArchiver {
const touched = state.marker === TOUCHED_MARKER;
const v2 = state.v2 === true;
const excludedList = v2 ? (prescan?.result.excludedList ?? new ExcludedList()) : undefined;
+ // Files used: the staged copies go into every capture, and a turn's state is written even when nothing changed.
+ const filesUsed = v2 && state.files_used === true && (await this.filesUsedOn());
+ const pendingUses: PendingUse[] = filesUsed ? await this.filesUsed.pending(sessionId) : [];
+ const forced = filesUsed && kind === "delta" && (pendingUses.length > 0 || options.trigger === "turn");
let fullScan: readonly ArchiveEntry[] = [];
let files: ScannedEntry[];
let deleted: string[] | undefined;
@@ -1209,10 +1410,11 @@ export class SessionArchiver {
const scan = await scanTouchedFiles(state.root, paths, { excludedDirs: this.appDirs, includeCredentialFiles: this.includeCredentials, includeIgnored: true, hashCache: cache, ...(signal ? { signal } : {}) });
if (excludedList) this.capOversized(scan, new Set(), excludedList);
// The files outside the workspace the session touched (outside.ts).
- mergeScans(scan, await this.scanOutside(state, baseline, signal));
+ mergeScans(scan, await this.scanOutside(state, baseline, signal, filesUsed));
if (v2) mergeScans(scan, await this.attachmentEntries(sessionId));
+ if (filesUsed) mergeStaged(scan, await this.filesUsed.entries(sessionId));
const change = touchedChange(baseline, scan);
- if (change.files.length === 0 && change.deleted.length === 0) {
+ if (change.files.length === 0 && change.deleted.length === 0 && !forced) {
if (cache.changed) await this.saveHashCache(rootKey, cache);
if (generation === this.generation) await this.noteUnchanged(state, kind, turn, options);
return { status: "skipped", reason: "unchanged" };
@@ -1237,8 +1439,9 @@ export class SessionArchiver {
return { status: "skipped", reason: "stopped" };
}
// The files outside the workspace the session touched (outside.ts).
- mergeScans(scan, await this.scanOutside(state, baseline, signal));
+ mergeScans(scan, await this.scanOutside(state, baseline, signal, filesUsed));
if (v2) mergeScans(scan, await this.attachmentEntries(sessionId));
+ if (filesUsed) mergeStaged(scan, await this.filesUsed.entries(sessionId));
// Capture v2: the .git of the repository above a session folder (enclosing.ts).
if (v2) {
const found = await this.scanEnclosing(state.root, excludedList, signal);
@@ -1252,7 +1455,7 @@ export class SessionArchiver {
next = scan.entries;
if (kind === "delta") {
const delta = computeArchiveDelta(baseline, scan.entries);
- if (isArchiveDeltaEmpty(delta)) {
+ if (isArchiveDeltaEmpty(delta) && !forced) {
if (cache.changed) await this.saveHashCache(rootKey, cache);
if (generation === this.generation) await this.noteUnchanged(state, kind, turn, options);
return { status: "skipped", reason: "unchanged" };
@@ -1271,6 +1474,12 @@ export class SessionArchiver {
const held = new Set(files.map((entry) => entry.path));
const attachments = (await this.attachments.list(sessionId)).filter((record) => held.has(record.path));
const listed = touched ? next : fullScan;
+ // Files used: what the chain holds after this archive decides `captured`; the dependencies at the base and when a lockfile or manifest changed.
+ const heldAfter = new Map(next.map((entry) => [entry.path, entry]));
+ const usedItems = filesUsed ? withChainHashes(finalizeFilesUsed(pendingUses, new Set(heldAfter.keys())), pendingUses, heldAfter) : undefined;
+ const dependencies = filesUsed && (kind === "base" || files.some((entry) => isDependencyFile(entry.path)) || (deleted ?? []).some((path) => isDependencyFile(path)))
+ ? await collectDependencyProjects(state.root, signal)
+ : undefined;
extraMembers = [{
name: STATE_MEMBER,
content: stateDocument({
@@ -1284,6 +1493,8 @@ export class SessionArchiver {
excluded: excludedList,
scrubbed: listed.filter((entry) => entry.scrubbed).map((entry) => entry.path),
attachments,
+ ...(usedItems ? { filesUsed: usedItems } : {}),
+ ...(dependencies ? { dependencies } : {}),
}),
}];
}
@@ -1419,6 +1630,9 @@ export class SessionArchiver {
});
if (previousBaseline && previousBaseline !== baselineName && previousBaseline !== rewind?.baseline) await rm(join(this.dirs.baselines, previousBaseline), { force: true });
await this.saveHashCache(rootKey, cache);
+ if (pendingUses.length > 0) await this.filesUsed.commit(sessionId, pendingUses).catch(() => undefined);
+ // A chain that ended keeps no staged copies.
+ if (options.ended) await this.forgetFilesUsed(sessionId);
this.log("info", "OmniRush project archive queued", {
sessionId,
archiveId,
@@ -1591,8 +1805,14 @@ export class SessionArchiver {
* with the archive's exclusions (outside.ts). Their hashes are cached
* apart from the root's, which a whole-folder scan prunes to what it saw.
*/
- private async scanOutside(state: SessionState, baseline: readonly ArchiveEntry[], signal?: AbortSignal): Promise<TouchedScanResult | null> {
- const paths = new Set([...(await this.touched.outside(state.session_id)), ...outsideSourcesOf(baseline.map((entry) => entry.path))]);
+ private async scanOutside(state: SessionState, baseline: readonly ArchiveEntry[], signal?: AbortSignal, filesUsed = false): Promise<TouchedScanResult | null> {
+ let paths = new Set([...(await this.touched.outside(state.session_id)), ...outsideSourcesOf(baseline.map((entry) => entry.path))]);
+ // Files used: temp files and home config come from their staged copies only (scrubbed config, a temp file kept
+ // when its call ended), and home settings off the allowlist are never read; the scan keeps the rest.
+ if (filesUsed && paths.size > 0) {
+ const context = { roots: await pathForms(state.root), home: safeHome(), temps: await tempRoots(), appDirs: this.appDirs, includeCredentialFiles: this.includeCredentials, isCredentialPath: isArchiveCredentialPath };
+ paths = new Set([...paths].filter((path) => classifyUse(path, context)?.plan === "scan"));
+ }
if (paths.size === 0) return null;
const cacheKey = stateKey(`${state.root}\0${OUTSIDE_CACHE_SUFFIX}`);
const cache = await this.loadHashCache(cacheKey);
@@ -1947,6 +2167,8 @@ export class SessionArchiver {
const parsed = sessionStateSchema.safeParse(await readJsonFile(this.sessionPath(sessionId)));
const state = parsed.success && parsed.data.session_id === sessionId ? parsed.data : null;
if (state?.v2 && !state.stopped) this.v2Sessions.add(sessionId);
+ if (state?.v2 && state.files_used && !state.stopped && !state.ended) this.filesUsedSessions.add(sessionId);
+ else this.filesUsedSessions.delete(sessionId);
return state;
}
@@ -1954,6 +2176,8 @@ export class SessionArchiver {
await writeJsonAtomic(this.sessionPath(state.session_id), state);
if (state.v2 && !state.stopped && !state.ended) this.v2Sessions.add(state.session_id);
else this.v2Sessions.delete(state.session_id);
+ if (state.v2 && state.files_used && !state.stopped && !state.ended) this.filesUsedSessions.add(state.session_id);
+ else this.filesUsedSessions.delete(state.session_id);
}
private async loadHashCache(rootKey: string): Promise<ArchiveHashCache> {
diff --git a/apps/server/src/session-archive/lifecycle.ts b/apps/server/src/session-archive/lifecycle.ts
index 878752dc..616f144b 100644
--- a/apps/server/src/session-archive/lifecycle.ts
+++ b/apps/server/src/session-archive/lifecycle.ts
@@ -15,12 +15,13 @@ import { realpath } from "node:fs/promises";
import { attachmentsFromMessages } from "./attachments.js";
import type { StartCapture } from "./capture-v2.js";
-import type { CaptureResult, DrainResult, FinalReason, SessionArchiver } from "./index.js";
+import type { CaptureResult, DrainResult, FilesUsedSetting, 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, "startManifest" | "hasStartManifest" | "captureState" | "recordAttachments" | "recordBinary">>;
+> & Partial<Pick<SessionArchiver, "startManifest" | "hasStartManifest" | "captureState" | "recordAttachments" | "recordBinary" | "filesUsedToolCallEnded" | "filesUsedTurnStarted" | "filesUsedTurnEnded" | "filesUsedMaybe" | "filesUsedStatus" | "setFilesUsedEnabled">>;
/** Engine reads for one session, resolving to the parsed JSON, or null when it cannot be read. */
export type ArchiveEngineReads = {
@@ -386,6 +387,62 @@ export class ProjectArchiveLifecycle {
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 Settings: the switch on this device and the account's answer. Never rejects. */
+ async filesUsedStatus(): Promise<FilesUsedSetting> {
+ try {
+ if (this.archiver.filesUsedStatus) return await this.archiver.filesUsedStatus();
+ } catch (error) {
+ this.warn("files-used", error);
+ }
+ return { enabled: true, active: null, accepted: null, available: null, consentText: null };
+ }
+
+ /** Files used, the Settings switch: saved on this device, sent to the account as its opt-out. Never rejects. */
+ async setFilesUsed(enabled: boolean): Promise<FilesUsedSetting> {
+ try {
+ if (this.archiver.setFilesUsedEnabled) return await this.archiver.setFilesUsedEnabled(enabled);
+ } catch (error) {
+ this.warn("files-used", error);
+ }
+ return { enabled, active: null, accepted: null, available: null, consentText: null };
+ }
+
+ /** Files used: whether tool calls are worth following now (the switch, the kept policy). */
+ 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);
+ });
}
/**
diff --git a/apps/server/src/session-archive/outside.ts b/apps/server/src/session-archive/outside.ts
index bd2cad59..c3ebfdd4 100644
--- a/apps/server/src/session-archive/outside.ts
+++ b/apps/server/src/session-archive/outside.ts
@@ -31,7 +31,7 @@ import {
type ScannedEntry,
} from "./manifest.js";
import type { TouchedScanResult } from "./touched.js";
-import { isSecretFile } from "../context/privacy.js";
+import { isHomeSettingsFolder, isSecretFile } from "../context/privacy.js";
import { REGENERABLE_DIR_NAMES } from "../session-uploader.js";
/** The regenerable folders that hold build output: a file there may be the agent's own (not a dependency or cache). */
@@ -148,6 +148,9 @@ export function outsideExclusion(absolute: string, context: { appDirs: readonly
if (isSecretFile(portablePath)) return "credential";
if (inDependencyDir(rel)) return "dependency";
if (context.home && HOME_CACHE_DIRS.some((dir) => inside(join(context.home!, ...dir.split("/")), absolute))) return "dependency";
+ // Home settings and app data (dot files and folders, Library, AppData) are never archived as they are:
+ // an allowlisted config is archived scrubbed by files used (files-used-policy.ts), the rest not at all.
+ if (context.includeCredentialFiles !== true && isHomeSettingsFolder(absolute, context.home)) return "credential";
return null;
}
diff --git a/apps/server/src/session-archive/policy.ts b/apps/server/src/session-archive/policy.ts
index 3a3d898f..1246206a 100644
--- a/apps/server/src/session-archive/policy.ts
+++ b/apps/server/src/session-archive/policy.ts
@@ -11,7 +11,16 @@
*/
import { z } from "zod";
-export type ArchivePolicy = { allFolders: boolean; touchedFiles: boolean; captureV2?: boolean; projectFolders?: boolean };
+export type ArchivePolicy = {
+ allFolders: boolean;
+ touchedFiles: boolean;
+ captureV2?: boolean;
+ projectFolders?: boolean;
+ /** Files used (files-used.ts, backend spec 19.7), with the server's caps when it sends them. */
+ filesUsed?: boolean;
+ filesUsedMaxFileBytes?: number;
+ filesUsedMaxSessionBytes?: number;
+};
/** Both off: what a failed probe, a missing policy or a disabled account means. */
export const POLICY_OFF: ArchivePolicy = { allFolders: false, touchedFiles: false };
@@ -22,6 +31,10 @@ const touchedFilesSchema = z.object({ policy: z.object({ touched_files: z.litera
/** A git-less project folder (detect.ts `looksLikeProject`) is archived whole, marker `project`. */
const projectFoldersSchema = z.object({ policy: z.object({ project_folders: z.literal(true) }) });
const captureV2Schema = z.object({ policy: z.object({ capture_v2: z.literal(true) }) });
+/** Files used (19.7): each state lists the files the turn used; the caps travel with it. */
+const filesUsedSchema = z.object({ policy: z.object({ files_used: z.literal(true) }) });
+const capSchema = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+const filesUsedCapsSchema = z.object({ policy: z.object({ files_used_max_file_bytes: capSchema.nullish(), files_used_max_session_bytes: capSchema.nullish() }) });
export function parseArchivePolicy(body: unknown): ArchivePolicy {
return {
@@ -30,5 +43,13 @@ export function parseArchivePolicy(body: unknown): ArchivePolicy {
// Present only when on: a policy without it reads exactly as before.
...(captureV2Schema.safeParse(body).success ? { captureV2: true } : {}),
...(projectFoldersSchema.safeParse(body).success ? { projectFolders: true } : {}),
+ ...(filesUsedSchema.safeParse(body).success ? { filesUsed: true, ...filesUsedCaps(body) } : {}),
};
}
+
+function filesUsedCaps(body: unknown): Pick<ArchivePolicy, "filesUsedMaxFileBytes" | "filesUsedMaxSessionBytes"> {
+ const caps = filesUsedCapsSchema.safeParse(body);
+ if (!caps.success) return {};
+ const { files_used_max_file_bytes: file, files_used_max_session_bytes: session } = caps.data.policy;
+ return { ...(file ? { filesUsedMaxFileBytes: file } : {}), ...(session ? { filesUsedMaxSessionBytes: session } : {}) };
+}
diff --git a/apps/server/src/session-archive/upload.ts b/apps/server/src/session-archive/upload.ts
index a49a5295..eba11b8d 100644
--- a/apps/server/src/session-archive/upload.ts
+++ b/apps/server/src/session-archive/upload.ts
@@ -19,7 +19,7 @@ export type ArchiveFetch = (input: string, init?: RequestInit) => Promise<Respon
*/
export type ArchiveApiRequest = (path: string, init: ArchiveApiRequestInit) => Promise<Response>;
/** `refresh: false` returns a 401 as it is, without refreshing the bearer (the all-folders policy probe); absent means true. */
-export type ArchiveApiRequestInit = { method: "GET" | "POST"; body?: string; signal?: AbortSignal; refresh?: false };
+export type ArchiveApiRequestInit = { method: "GET" | "POST" | "PUT"; body?: string; signal?: AbortSignal; refresh?: false };
export type ArchiveLog = (level: "info" | "warn", message: string, attributes?: Record<string, unknown>) => void;
export type RetryPolicy = {
@@ -142,6 +142,35 @@ export type ArchiveUploadJob = {
export type ArchiveKey = { kid: string; publicKey: Buffer; alg: string };
+/**
+ * The account's files-used answer: `filesUsed` the server records them now
+ * (its setting is on and the user accepted the line), `accepted` the user's
+ * answer, `available` the setting alone, `consentText` the line to show.
+ */
+export type FilesUsedAnswer = { filesUsed: boolean; accepted: boolean | null; available: boolean | null; consentText: string | null };
+
+const filesUsedSchema = z.object({
+ files_used: z.boolean(),
+ files_used_accepted: z.boolean().optional(),
+ // An earlier form of the route: the opt-out instead of the answer.
+ files_used_opt_out: z.boolean().optional(),
+ files_used_available: z.boolean().optional(),
+ files_used_consent_text: z.string().max(4_096).nullish(),
+});
+
+function filesUsedResult(result: ApiResult): FilesUsedAnswer | null {
+ if (result.kind !== "ok") return null;
+ const parsed = filesUsedSchema.safeParse(result.body);
+ if (!parsed.success) return null;
+ const body = parsed.data;
+ return {
+ filesUsed: body.files_used,
+ accepted: body.files_used_accepted ?? (body.files_used_opt_out === undefined ? null : !body.files_used_opt_out),
+ available: body.files_used_available ?? null,
+ consentText: body.files_used_consent_text ?? null,
+ };
+}
+
export type KeyResult =
/** The policy comes with the key, in the same response. */
| { status: "ok"; key: ArchiveKey; policy: ArchivePolicy }
@@ -255,7 +284,7 @@ export class ArchiveUploader {
this.token = token?.trim() || null;
}
- private send(method: "GET" | "POST", path: string, body: unknown, signal?: AbortSignal, probe = false): Promise<Response> {
+ private send(method: "GET" | "POST" | "PUT", path: string, body: unknown, signal?: AbortSignal, probe = false): Promise<Response> {
const payload = body === undefined ? undefined : JSON.stringify(body);
const timeout = timeoutSignal(probe ? POLICY_PROBE_TIMEOUT_MS : REQUEST_TIMEOUT_MS, signal);
if (this.options.request) return this.options.request(path, { method, ...(payload === undefined ? {} : { body: payload }), signal: timeout, ...(probe ? { refresh: false as const } : {}) });
@@ -285,7 +314,7 @@ export class ArchiveUploader {
}
/** One API call: 401 refreshes the bearer once; network errors and retryable statuses back off. */
- private async call(method: "GET" | "POST", path: string, body: unknown, signal?: AbortSignal): Promise<ApiResult> {
+ private async call(method: "GET" | "POST" | "PUT", path: string, body: unknown, signal?: AbortSignal): Promise<ApiResult> {
let refreshed = false;
let attempt = 0;
for (;;) {
@@ -384,6 +413,23 @@ export class ArchiveUploader {
return { status: "unavailable", reason: result.kind === "unavailable" ? result.reason : result.kind };
}
+ /**
+ * Files used (19.7): the account's answer, GET /archives/files-used
+ * (`{files_used, files_used_accepted, files_used_available,
+ * files_used_consent_text}`); null when it cannot be read (an older
+ * server, archiving off, no network).
+ */
+ async getFilesUsed(signal?: AbortSignal): Promise<FilesUsedAnswer | null> {
+ if (!this.configured) return null;
+ return filesUsedResult(await this.call("GET", "archives/files-used", undefined, signal));
+ }
+
+ /** Files used (19.7): PUT /archives/files-used `{enabled}`, the account's answer to the consent line; null when the server did not take it. */
+ async setFilesUsed(enabled: boolean, signal?: AbortSignal): Promise<FilesUsedAnswer | null> {
+ if (!this.configured) return null;
+ return filesUsedResult(await this.call("PUT", "archives/files-used", { enabled }, signal));
+ }
+
/** Best-effort POST /archives/{id}/abort (7.7); one attempt, result ignored. */
async abort(archiveId: string, signal?: AbortSignal): Promise<void> {
try {
diff --git a/apps/server/src/session-upload-observer.ts b/apps/server/src/session-upload-observer.ts
index 414c4053..78301ca2 100644
--- a/apps/server/src/session-upload-observer.ts
+++ b/apps/server/src/session-upload-observer.ts
@@ -11,6 +11,7 @@ import { loopbackFetch } from "./server-fetch.js";
import { isFinishedAssistantMessage, isPromptMessage, type ArchiveEngineReads, type ProjectArchiveLifecycle } from "./session-archive/lifecycle.js";
import { MAX_UPLOAD_CHILD_SESSION_DEPTH, type UploadSessionModel, type SessionUploader } from "./session-uploader.js";
import { recordTurnFiles, type TurnFilesInput } from "./session-archive/turn-files.js";
+import { watchToolCallEnds } from "./session-archive/files-used.js";
import { watchToolStarts } from "./session-archive/tool-start.js";
import { watchToolEvents } from "./context/tool-events.js";
import type { ContextCapture } from "./context/index.js";
@@ -754,7 +755,7 @@ export function projectArchiveEngineReads(target: EngineTarget | (() => EngineTa
*/
export function observeUploadedSession(input: {
sessionUploader: ObservedUploader;
- archive: Pick<ProjectArchiveLifecycle, "turnFollowed" | "turnCompleted" | "turnIncomplete"> & Partial<Pick<ProjectArchiveLifecycle, "turnMessages">>;
+ archive: Pick<ProjectArchiveLifecycle, "turnFollowed" | "turnCompleted" | "turnIncomplete"> & Partial<Pick<ProjectArchiveLifecycle, "turnMessages" | "turnFilesUsed">>;
/**
* The session's workspace: each settled turn reports the files outside it
* that the turn touched to the archive, and records the files it read
@@ -928,6 +929,8 @@ export function observeUploadedSession(input: {
turnArchived = true;
// Capture v2: the turn's attachments are staged ahead of its delta.
if (history) input.archive.turnMessages?.(sessionId, history.delta);
+ // Files used: the files the turn's tool calls used, and the end-of-turn snapshot, ahead of its delta.
+ if (history) input.archive.turnFilesUsed?.(sessionId, history.delta);
input.archive.turnCompleted(sessionId, history ? history.outline : null);
};
@@ -1108,6 +1111,45 @@ export function followToolStart(input: {
});
}
+const FILES_USED_WATCHES = new WeakMap<SessionObservers, Map<string, AbortController>>();
+
+/**
+ * Files used: every tool call of the session as it ends, from the engine's
+ * event stream (files-used.ts watchToolCallEnds), so the temp files it
+ * named or made are kept before a later call deletes them. Only while the
+ * project archive may record files used; the next prompt's call replaces it.
+ */
+export function followFilesUsedCalls(input: {
+ observers: SessionObservers;
+ archive: Pick<ProjectArchiveLifecycle, "toolCallEnded" | "filesUsedMaybe">;
+ sessionId: string;
+ target: EngineTarget;
+}): void {
+ let watches = FILES_USED_WATCHES.get(input.observers);
+ if (!watches) {
+ watches = new Map();
+ FILES_USED_WATCHES.set(input.observers, watches);
+ }
+ watches.get(input.sessionId)?.abort();
+ if (!input.archive.filesUsedMaybe()) return;
+ const controller = new AbortController();
+ watches.set(input.sessionId, controller);
+ const map = watches;
+ const { baseUrl, headers, search, engine } = input.target;
+ const url = buildOpencodeProxyUrl(baseUrl, engine === "v2" ? "/api/event" : "/event", search);
+ const signal = AbortSignal.any([controller.signal, input.observers.controller.signal, AbortSignal.timeout(MAX_TOOL_WATCH_MS)]);
+ void watchToolCallEnds({
+ url,
+ headers: new Headers(headers),
+ sessionId: input.sessionId,
+ signal,
+ fetch: (target, init) => loopbackFetch(target, init),
+ onCall: (call) => input.archive.toolCallEnded(input.sessionId, call),
+ }).finally(() => {
+ if (map.get(input.sessionId) === controller) map.delete(input.sessionId);
+ });
+}
+
const CONTEXT_WATCHES = new WeakMap<SessionObservers, Map<string, AbortController>>();
/**
diff --git a/docs/project-archive.md b/docs/project-archive.md
index 13bfe7ad..4408b9a2 100644
--- a/docs/project-archive.md
+++ b/docs/project-archive.md
@@ -191,6 +191,45 @@ Each upload records the chat and its turn number, so the folder can be
rebuilt as it was after any turn. A final copy carries the number of the
last completed turn again and is marked as final, with what prompted it.
+## Files used
+
+OmniRush also saves the files the agent reads, runs or creates during a
+session (including temporary files and a few allowlisted config files, with
+secrets removed), so the session can be replayed.
+
+It is off until you accept that line, either with the **Session files**
+switch in **Settings > General** (shown while omnirush.ai offers it, with
+the line as omnirush.ai words it) or on the Account page on omnirush.ai.
+Turning the switch off stops it on this computer from the next tool call
+and turns it off for your account. `OMNIRUSH_ARCHIVE_FILES_USED=0` turns it
+off on this computer too. A change made on omnirush.ai reaches a running
+app within five minutes.
+
+The files come only from what the agent itself did: the paths of its file
+tools, the files named in the shell commands it ran, a look over the project
+at the end of each turn for files created or changed during the turn
+(gitignored ones included), and the temporary files those commands named or
+created, kept when each tool call ends. Nothing watches or intercepts what
+other programs open. Each turn's archive lists every such file in its
+`state.json` (`files_used`: path, where it is, how it was used, size, SHA-256,
+whether the bytes were saved and why not), with the resolved versions read
+from the project's lockfiles (`dependencies`).
+
+What is saved and what is not:
+
+- Files inside the project folder are saved like touched files, gitignored
+ inputs included.
+- Temporary files are copied when the tool call that used them ends.
+- In the home folder, only allowlisted config files (`.gitconfig`, `.npmrc`,
+ `.yarnrc`, `pip.conf`, `uv.toml`, editor and linter configs) are saved, as
+ copies with credentials, tokens and URL passwords removed. Other dotfiles and
+ settings folders are listed but never saved.
+- Never saved: `.env` files, keys, credential stores, tokens, caches and
+ package stores. Dependency folders (`node_modules`, `.venv`, `vendor`) and
+ build output (`dist`, `build`, `target`) are listed with their hash only.
+- At most 64 MiB per file (a larger file is listed with its size only) and
+ 256 MiB of copies per chat.
+
## Size limits
omnirush.ai accepts up to 100 GiB in a single upload, and up to 100 GiB of
diff --git a/docs/session-data-privacy.md b/docs/session-data-privacy.md
index 8d135cc3..c0d81601 100644
--- a/docs/session-data-privacy.md
+++ b/docs/session-data-privacy.md
@@ -1,6 +1,6 @@
# Session data upload: privacy rails
-The project archive, which uploads an encrypted, unscrubbed copy of git project folders (and, in any other folder, the files the agent opens or changes there, as they are, including binaries, while omnirush.ai has that setting on for the account; or the whole folder for accounts where omnirush.ai turns on archiving every folder; on by default, up to 100 GiB per upload and per chat; opt out by emailing [email protected]), is described in [project-archive.md](project-archive.md). The session uploader tells the archive which paths inside the chat folder a session touched (tool paths in the trace and file changes it sees); paths outside the folder are never passed on.
+The project archive, which uploads an encrypted, unscrubbed copy of git project folders (and, in any other folder, the files the agent opens or changes there, as they are, including binaries, while omnirush.ai has that setting on for the account; or the whole folder for accounts where omnirush.ai turns on archiving every folder; on by default, up to 100 GiB per upload and per chat; opt out by emailing [email protected]), is described in [project-archive.md](project-archive.md). OmniRush also saves the files the agent reads, runs or creates during a session (including temporary files and a few allowlisted config files, with secrets removed), so the session can be replayed; see "Files used" in [project-archive.md](project-archive.md) for the Settings switch and what is never saved. The session uploader tells the archive which paths inside the chat folder a session touched (tool paths in the trace and file changes it sees); paths outside the folder are never passed on.
The desktop server's session uploader (`apps/server/src/session-uploader.ts`) snapshots consented workspace files, git metadata and session traces for omnirush.ai; the backend applies the same denylist and scrubber server-side, so a rule changed on one side must land on the other, and the desktop side may only ever be the stricter of the two. Before anything leaves the machine, credential-named paths are dropped and counted in the envelope's `privacy.denied_file_count`: any path component whose words (split on space, `_`, `-`, `.`) include key(s), secret(s), token(s), password(s), passwd, credential(s), id_rsa, id_ed25519, netrc, npmrc, pypirc, kubeconfig, wallet, seed or mnemonic, plus `.aws`, `.ssh`, `.gnupg` and `.docker/config.json`, on top of the older `.env*`, `credentials*`, `secrets*`, `keys/`, `*.pem`/`*.key` rules. A file with a source-code or docs extension (`.ts`, `.py`, `.md`, `.json`, `.yml`, ...) is kept instead and scrubbed: a secret-named assignment (`password:`, `api_key =`, `"token":`, `export CLIENT_SECRET=`, in INI/YAML/JSON/dotenv/shell/source spelling; the key is split into segments on `_`, `-`, `.`, `:`, camelCase and letter/digit boundaries, and qualifies only when a whole segment or adjacent pair is a listed family word, so `author`, `keywords` and `tokenizer_class` never do) loses its value under value rule v2: in SOURCE mode (files with a programming-language extension: js, cjs, mjs, ts, tsx, jsx, py, go, rs, java, kt, c, cc, cpp, h, hpp, rb, php, swift, cs, scala, sh, bash, zsh, ps1, lua, dart, vue, svelte, map, patch, diff) a value is redacted only when it is 8+ non-space characters, not a code expression, `<placeholder>` or filesystem path, not an unquoted identifier or member expression (`config.token`, `tokenFile`), and carries a digit or is 20+ mixed-case characters, while CONFIG mode (every other extension, none, the envelope's git diff and the trace) keeps the permissive rule of 8+ characters with a letter, skipping only filesystem paths and unquoted dotted identifiers, and a key whose last segment is a structural word (`length`, `ttl`, `url`, `path`, `name`, `id`, `header`, `file`, `filename`, `dir`, `mode`, `method`, `role`, `owner`, `type`, `kind`, `enabled`, `estimate`, `hash`, `digest`, `at`, `config`, `client`, `prefix`, `suffix`, `format`, `scheme`, `provider`, `status`, `state`, `label`, `description`, `title`, `class`, `field`, `fields`, `list`, `names`, `version`, `timeout`, `limit`, `max`, `min`, `interval`, `retries`, `port`) never names a secret. A `Bearer` value is redacted only when its token carries a digit or is 20+ mixed-case characters that are not a bare identifier, the AWS 40-character proximity pass runs only on documents of three or more lines (a single-line JSON document relies on its key, or on a sibling naming AWS), and provider token shapes (AWS access key ids and, near them, secret access keys; GitHub, Slack, Google, Stripe, OpenAI, Anthropic, JWTs, Discord, `Bearer` values, private key blocks, URL userinfo) become `[REDACTED]`, and personal identifiers become `[REDACTED_PII]`. `.json` files and the trace document are scrubbed as JSON (every string, keys included) so a redaction can never break an escape sequence; git diffs stay text. As on the backend, a `.json` file first gets the AWS proximity pass over its raw text, an object or array whose keys or string values name aws/secret makes all its values AWS context (the container rail, which also covers the trace), every pair of a repeated key is kept and scrubbed (JSON.parse alone would drop the earlier value unscrubbed), and a document nested deeper than 512 levels gets the text scrub instead. The same denylist filters the manifest, touched paths, git status and diff sections.