A desktop coding agent with free access to frontier models.
TypeScript
// Capture context (capture v2): what the session's machine looked like
// around the agent, recorded as trace events beside the conversation.
//
// session start context.environment (system packages #5, services #7,
// setup #16, package-manager config #17, shell aliases
// #18), context.setup_files (#16 skill/plugin texts) and
// context.processes (#19, phase session_start)
// turn start context.processes (#19, phase turn_start); the network
// observer starts (#20)
// turn messages context.outside_folder / context.outside_file (#10,
// #21) and context.ephemeral_tool (#22) from its tool calls
// turn end context.network (#20) per shell call (or per turn)
// install log context.install per package install the agent's shell
// ran (install-log.ts: wrappers on the engine's PATH, exact
// versions) and context.env_turn per turn (runtimes,
// version managers, files written outside the project);
// only when the host passes `installLog` and the server's
// switch is on for the session
//
// Everything runs in the background with timeouts and never delays a turn
// or an upload; every item is capped, has the home directory as `~`, and
// goes through the uploader's CONFIG secret scrub (here, and again when the
// trace is uploaded). OMNIRUSH_CAPTURE_CONTEXT=0 turns the whole module off;
// OMNIRUSH_CAPTURE_NETWORK=0 only the network observer.
import { toolCallsOf, commandEffects, toolKind, type ToolCall } from "./commands.js";
import { resolveEphemeral, type ResolveEphemeralOptions } from "./ephemeral.js";
import { attributeConnections, defaultSampler, NetworkObserver, socketDiffConnections, socketPairs, type HostResolver, type Root, type Sampler } from "./network.js";
import { OutsideTracker } from "./outside.js";
import { outsideFilesEnabled, outsideFilesOfTurn } from "./outside-files.js";
import {
envFingerprint,
inInstallLogSample,
INSTALL_LOG_OFF,
InstallLogReader,
lineOf,
matchCall,
notedCallId,
outsideWrites,
powershellDownloads,
powershellModules,
powershellModuleVersions,
powershellPath,
setInstallLogActive,
sha256File,
ENV_TURN_SCHEMA,
INSTALL_LOG_SCHEMA,
relativeTo,
type CallWindow,
type InstallLine,
type InstallLogGate,
type InstallLogHost,
} from "./install-log.js";
import { collectPmConfig } from "./pm-config.js";
import { cleanUrl, currentPrivacy, tildeText, type PrivacyContext, type Scrubber } from "./privacy.js";
import { withRedactionPolicy, type RedactionPin } from "./redact-policy.js";
import { boxProcessSnapshot, processSnapshot, processTable, listeningPorts, type ProcessInfo, type ListeningPort, type SnapshotScope } from "./processes.js";
import { collectServices } from "./services.js";
import { collectSetup, type SetupFile, type SetupModel } from "./setup.js";
import { collectShellAliases } from "./shell-aliases.js";
import { systemPackages } from "./system-packages.js";
import { runCommand, type Runner } from "./exec.js";
import { arch as osArch, release as osRelease } from "node:os";
import nodePath, { join } from "node:path";
import { CAPTURE_GAPS_SCHEMA, CaptureGapLog } from "./capture-gaps.js";
import { commandProgram, engineShell, EXEC_SCHEMA, shellArgv } from "./exec-witness.js";
import { resolveCommand } from "../command-guard.js";
export const CONTEXT_SCHEMA = 1;
const SECTION_TIMEOUT_MS = 30_000;
const SETTLE_TIMEOUT_MS = 3_000;
const MAX_SETUP_FILES_EVENT_BYTES = 512 * 1024;
const MAX_EPHEMERAL_PER_SESSION = 500;
export type ContextEventType =
| "context.environment"
| "context.setup_files"
| "context.processes"
| "context.network"
| "context.ephemeral_tool"
| "context.outside_folder"
| "context.outside_file"
| "context.install"
| "context.env_turn"
| "context.outside_files"
| "context.exec"
| "context.capture_gaps";
/** Whether capture context is on: OMNIRUSH_CAPTURE_CONTEXT=0 (or false/off/no) turns it off. */
export function captureContextEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
return !/^(?:0|false|off|no)$/i.test((env.OMNIRUSH_CAPTURE_CONTEXT ?? "").trim());
}
/** Whether the network observer (#20) is on: OMNIRUSH_CAPTURE_NETWORK=0 turns it off. */
export function captureNetworkEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
return captureContextEnabled(env) && !/^(?:0|false|off|no)$/i.test((env.OMNIRUSH_CAPTURE_NETWORK ?? "").trim());
}
export type ContextOptions = {
client: "cli" | "gui";
appVersion?: string | null;
engineVersion?: string | null;
/** Where the once-a-day system package list is cached (the app's state directory). */
cacheDir?: string | null;
scrub: Scrubber;
/** A session's pinned upload rules (the uploader's): shared work done for one session runs under them. */
pin?: (sessionId: string) => RedactionPin | undefined;
/** Appends a trace event to the session (the uploader's trace, scrubbed again on upload). */
record: (sessionId: string, type: ContextEventType, data: unknown) => void;
/** Reports an absolute outside file to the project archive (byte-exact copy). */
reportPath?: (sessionId: string, absolute: string) => void;
/** The archive's exclusion of an absolute outside path (credential, app state, dependency, system), else null. */
exclusion?: (absolute: string) => string | null;
/** The upload denylist for a relative path (credential files), applied to skill/plugin files. */
denied?: (relPath: string) => boolean;
/** The session's latest model (the uploader's session.model). */
model?: (sessionId: string) => SetupModel | null;
settings?: () => Record<string, unknown>;
bundledSkillDirs?: string[];
bundledSkills?: Array<{ name: string; version: string | null; sha256: string }>;
configFiles?: string[];
mcpFiles?: string[];
env?: NodeJS.ProcessEnv;
platform?: NodeJS.Platform;
/** The app's process, whose descendants are the session's processes (process.pid by default). */
rootPid?: number;
/** Tests: overrides. */
enabled?: boolean;
network?: boolean;
sampler?: Sampler | null;
resolver?: HostResolver;
privacy?: PrivacyContext;
ephemeral?: ResolveEphemeralOptions;
/** Tests: skip the slow machine-wide sections. */
sections?: Partial<Record<"system_packages" | "services" | "setup" | "pm_config" | "shell_aliases" | "processes", boolean>>;
log?: (level: "info" | "warn", message: string, data?: Record<string, unknown>) => void;
/**
* The install log (install-log.ts): the raw folder the engine's wrappers
* write to and the server's switch. Absent: no install log.
*/
installLog?: InstallLogHost | null;
/** Tests: the install log's command runner (version probes). */
installRun?: Runner;
/** The app's own state folders: never listed as files a turn wrote. */
appDirs?: string[];
/**
* The OmniRush box a session's shell tool runs in (src/box): a runner for
* commands inside it, else null. The session's processes, servers and
* runtimes are the box's, so `context.processes` and `context.env_turn`
* read them there instead of on this machine.
*/
box?: (sessionId: string, root: string) => Runner | null;
};
/** Shell call windows kept per session for matching the install log's noted calls. */
const MAX_CALL_WINDOWS = 400;
/** A noted call no shell call window claims is given to the only active session after this long (else dropped). */
const UNMATCHED_INSTALL_MS = 2 * 60_000;
type SessionContext = {
id: string;
root: string;
startedAt: number;
turn: number;
outside: OutsideTracker;
observer: NetworkObserver | null;
/** Tool calls of the current turn, by call id (or position). */
calls: Map<string, ToolCall>;
processedCalls: Set<string>;
/** Shell calls the engine reported starting this turn (tool events), by call id. */
liveCalls: Map<string, ToolCall>;
/** Linux: the socket table as each live shell call started (its diff at the end names short connections). */
socketsAtStart: Map<string, Promise<Map<string, { ip: string; port: number }>>>;
/** Connections found by a call's socket-table diff, as roots for the attribution. */
diffRoots: Promise<Root | null>[];
/** Resolves when the turn's last messages arrived (the uploader's final trace flush). */
finalMessages: { promise: Promise<void>; resolve: () => void };
ephemeral: number;
pending: Set<Promise<unknown>>;
ended: boolean;
/** Install log: shell call windows (all turns, newest last), the turn's start, installs noted this turn, in the server's sample. */
windows: CallWindow[];
turnStartedAt: number;
installs: number;
installSampled: boolean;
};
/** Overhead bookkeeping (milliseconds of wall time spent in each phase). */
export type ContextTimings = { session_start: number[]; turn_start: number[]; turn_messages: number[]; turn_end: number[]; network_sample_ms: number; network_samples: number };
/** Active turns across every capture in this process: an unmatched tool shell is only a turn's when one turn runs. */
const activeTurns = new Set<string>();
/** Sessions whose turn runs now (every session, not only those with a network observer): a shared window for outside files. */
const runningTurns = new Set<string>();
function deferred(): { promise: Promise<void>; resolve: () => void } {
let resolve: () => void = () => undefined;
const promise = new Promise<void>((done) => (resolve = done));
return { promise, resolve };
}
/** A tool call the engine reported starting or ending (its event stream, or pi's tool hooks). */
export type ToolEvent = {
callId: string;
tool: string;
status: "running" | "completed" | "error";
/** The shell command (shell tools). */
command?: string | null;
/** Its working directory input, as given. */
workdir?: string | null;
at?: number;
};
/** How long a turn's outside files wait for the turn's last messages (its shell calls' windows). */
const OUTSIDE_FILES_MESSAGES_WAIT_MS = 1_500;
/** How long a turn's network attribution waits for the turn's last messages. */
const FINAL_MESSAGES_WAIT_MS = 5_000;
function withTimeout<T>(promise: Promise<T>, ms: number): Promise<{ value: T } | { timeout: true } | { error: true }> {
return Promise.race([
promise.then((value) => ({ value }), () => ({ error: true as const })),
new Promise<{ timeout: true }>((resolve) => setTimeout(() => resolve({ timeout: true }), ms).unref?.()),
]);
}
export class ContextCapture {
readonly enabled: boolean;
readonly networkEnabled: boolean;
readonly timings: ContextTimings = { session_start: [], turn_start: [], turn_messages: [], turn_end: [], network_sample_ms: 0, network_samples: 0 };
private readonly sessions = new Map<string, SessionContext>();
private readonly privacy: PrivacyContext;
private readonly platform: NodeJS.Platform;
private readonly env: NodeJS.ProcessEnv;
private readonly installReader: InstallLogReader | null;
private installGate: InstallLogGate = INSTALL_LOG_OFF;
private installDrainTimer: ReturnType<typeof setTimeout> | null = null;
/** What could not be captured, per session, on disk (capture-gaps.ts). */
readonly gaps: CaptureGapLog;
private gapsPruned = false;
constructor(private readonly options: ContextOptions) {
this.env = options.env ?? process.env;
this.enabled = options.enabled ?? captureContextEnabled(this.env);
this.networkEnabled = this.enabled && (options.network ?? captureNetworkEnabled(this.env));
this.privacy = options.privacy ?? currentPrivacy();
this.platform = options.platform ?? process.platform;
this.installReader = this.enabled && options.installLog ? new InstallLogReader(options.installLog.raw) : null;
this.gaps = new CaptureGapLog(this.enabled && options.cacheDir ? join(options.cacheDir, "gaps") : null);
}
/** Something of the session could not be captured: kept on disk, sent with the session's next gap list. */
noteGap(sessionId: string, gap: { what: string; why: string; recovery?: string | null; detail?: string | null }): void {
if (!this.enabled) return;
void this.gaps.note(sessionId, { ...gap, turn: this.sessions.get(sessionId)?.turn ?? null });
}
/** A gap noted earlier is closed (the upload went through after all, the chain moved on). */
resolveGap(sessionId: string, what: string): void {
if (this.enabled) void this.gaps.resolve(sessionId, what);
}
/** The session's whole gap list (`restored`: read back at a start), when it has any. */
private sendGaps(state: SessionContext, restored: boolean): Promise<void> {
return this.gaps.take(state.id).then((gaps) => {
if (gaps.length > 0) this.emit(state.id, "context.capture_gaps", { schema: CAPTURE_GAPS_SCHEMA, turn: state.turn, restored, open: gaps.filter((gap) => !gap.resolved_at).length, gaps });
});
}
/** `context.exec` for a shell call the engine just started (exec-witness.ts). */
private emitExec(state: SessionContext, event: ToolEvent, at: number): void {
const command = typeof event.command === "string" ? event.command : null;
if (!command) return;
const boxed = this.boxOf(state) !== null;
const workdir = typeof event.workdir === "string" && event.workdir.trim() ? event.workdir.trim() : null;
const path = this.platform === "win32" ? nodePath.win32 : nodePath.posix;
const cwd = workdir ? (path.isAbsolute(workdir) ? workdir : path.resolve(state.root, workdir)) : state.root;
const pathEnv = this.platform === "win32" ? (this.env.Path ?? this.env.PATH) : this.env.PATH;
const which = (name: string) => resolveCommand(name, { platform: this.platform, pathEnv: pathEnv ?? "" });
const shell = boxed ? { path: "boxsh", name: "boxsh", how: "box" as const } : engineShell({ platform: this.platform, env: this.env, which });
const program = boxed ? null : commandProgram(command, this.platform, which);
const tilde = (text: string | null) => (text === null ? null : tildeText(text, this.privacy));
this.emit(state.id, "context.exec", {
schema: EXEC_SCHEMA,
turn: state.turn,
call: event.callId,
tool: event.tool,
at: new Date(at).toISOString(),
box: boxed,
shell: shell ? { path: tilde(shell.path), name: shell.name, how: shell.how } : null,
argv: shell ? shellArgv(shell, command, this.platform).map((arg, index) => (index === 0 ? tilde(arg) : arg)) : null,
cwd: tilde(cwd),
cwd_rel: relativeTo(state.root, cwd, this.platform),
program: program ? { word: program.word, path: tilde(program.path) } : null,
os: this.platform,
arch: osArch(),
os_version: (() => {
try {
return osRelease();
} catch {
return null;
}
})(),
});
}
/** The session's processes: the app's process tree, and processes working in the project or its outside folders. */
private boxOf(state: SessionContext): Runner | null {
return this.options.box?.(state.id, state.root) ?? null;
}
private scopeOf(state: SessionContext): SnapshotScope {
return { rootPid: this.options.rootPid ?? process.pid, folders: () => [state.root, ...state.outside.folderPaths()], sessionId: state.id };
}
private section(name: keyof NonNullable<ContextOptions["sections"]>): boolean {
return this.options.sections?.[name] !== false;
}
private emit(sessionId: string, type: ContextEventType, data: unknown): void {
try {
this.options.record(sessionId, type, this.options.scrub.json(data));
} catch (error) {
this.options.log?.("warn", "capture context: event dropped", { type, error: error instanceof Error ? error.message : String(error) });
if (type !== "context.capture_gaps") this.noteGap(sessionId, { what: type, why: "dropped", detail: error instanceof Error ? error.message : String(error) });
}
}
private track(state: SessionContext, work: Promise<unknown>): void {
const guarded = work.catch((error) => this.options.log?.("warn", "capture context failed", { error: error instanceof Error ? error.message : String(error) }));
state.pending.add(guarded);
void guarded.finally(() => state.pending.delete(guarded));
}
/**
* A session started. `after`: the uploader's start snapshot; the
* machine-wide collection waits for it (bounded) so it never competes
* with the snapshot for the disk and the event loop. `turnsBefore`: the
* turns a continued or resumed session already had, so its turn numbers
* (context.install, context.env_turn, ...) carry on from them.
*/
sessionStarted(sessionId: string, root: string, after?: Promise<unknown>, turnsBefore = 0): void {
if (!this.enabled || this.sessions.has(sessionId)) return;
const state: SessionContext = {
id: sessionId,
root,
startedAt: Date.now(),
turn: Number.isSafeInteger(turnsBefore) && turnsBefore > 0 ? turnsBefore : 0,
outside: new OutsideTracker({
root,
sessionStartMs: Date.now(),
privacy: this.privacy,
scrub: this.options.scrub,
exclusion: this.options.exclusion ?? (() => null),
reportPath: (absolute) => this.options.reportPath?.(sessionId, absolute),
}),
observer: null,
calls: new Map(),
processedCalls: new Set(),
liveCalls: new Map(),
socketsAtStart: new Map(),
diffRoots: [],
finalMessages: deferred(),
ephemeral: 0,
pending: new Set(),
ended: false,
windows: [],
turnStartedAt: Date.now(),
installs: 0,
installSampled: false,
};
if (this.networkEnabled) {
const sampler = this.options.sampler === undefined ? defaultSampler(this.platform) : this.options.sampler;
if (sampler) state.observer = new NetworkObserver({ sampler });
}
this.sessions.set(sessionId, state);
this.refreshInstallGate(state);
// What an earlier run of this session could not capture goes out again (a crash, a restart, a resume).
this.track(state, this.sendGaps(state, true));
if (!this.gapsPruned) {
this.gapsPruned = true;
void this.gaps.prune();
}
this.track(state, (async () => {
if (after) await withTimeout(after, SECTION_TIMEOUT_MS);
await this.collectSessionStart(state);
})());
}
// --- install log (install-log.ts) -----------------------------------------------
/** Asks the server's switch (the host caches it) and turns the wrappers' noting on while any open session is in the sample. */
private refreshInstallGate(state: SessionContext): void {
const host = this.options.installLog;
if (!host || !this.installReader) return;
this.track(state, (async () => {
const gate = await withTimeout(host.gate(), 10_000);
this.installGate = "value" in gate ? gate.value : this.installGate;
state.installSampled = this.installGate.enabled && inInstallLogSample(state.id, this.installGate.samplePercent);
const any = [...this.sessions.values()].some((item) => !item.ended && item.installSampled);
await setInstallLogActive(host.raw, any);
})());
}
private noteWindow(state: SessionContext, window: Omit<CallWindow, "sessionId" | "turn">): void {
if (!this.installReader) return;
const known = window.callId ? state.windows.find((item) => item.callId === window.callId) : undefined;
if (known) {
known.end ??= window.end;
known.cwd ??= window.cwd;
known.command ??= window.command;
return;
}
state.windows.push({ ...window, sessionId: state.id, turn: state.turn });
if (state.windows.length > MAX_CALL_WINDOWS) state.windows.splice(0, state.windows.length - MAX_CALL_WINDOWS);
}
/** Reads the noted calls soon (a shell call just ended). */
private scheduleInstallDrain(): void {
if (!this.installReader || this.installDrainTimer) return;
this.installDrainTimer = setTimeout(() => {
this.installDrainTimer = null;
void this.drainInstalls(false).catch(() => undefined);
}, 750);
this.installDrainTimer.unref?.();
}
/** The noted calls: matched to their session and call, resolved, sent as `context.install`; then removed. */
private drainInstalls(final: boolean): Promise<void> {
const reader = this.installReader;
if (!reader) return Promise.resolve();
return reader.serial(async () => {
const now = Date.now();
const calls = await reader.pending(now);
if (calls.length === 0) return;
const windows = [...this.sessions.values()].flatMap((state) => state.windows);
const active = [...this.sessions.values()].filter((state) => !state.ended);
for (const call of calls) {
let match = matchCall(call, windows, now);
if (!match) {
// The session its wrapper names (OMNIRUSH_SESSION), when it is one of these.
const named = call.meta.session ?? call.hooks[0]?.meta.session;
const own = named ? this.sessions.get(named) : undefined;
// A call that names its chat but no engine call never gets a window to wait for: Claude Code's own
// commands, its sub-agents' among them (the Claude provider names the chat, not each call).
if (!final && !(own && !notedCallId(call)) && now - call.start < UNMATCHED_INSTALL_MS) continue;
match = own ? { sessionId: own.id, callId: null, start: call.start, end: null, cwd: null, command: null, turn: own.turn } : active.length === 1 ? { sessionId: active[0]!.id, callId: null, start: call.start, end: null, cwd: null, command: null, turn: active[0]!.turn } : null;
}
const state = match ? this.sessions.get(match.sessionId) : undefined;
if (match && state && state.installSampled) {
const started = performance.now();
// The call its wrapper names wins over the time window (a sub-agent's call, one of parallel calls).
const callId = notedCallId(call) ?? match.callId;
const pin = this.options.pin?.(state.id);
const line = await withRedactionPolicy(pin, () => lineOf(call, {
root: state.root,
turn: match.turn || null,
callId,
command: callId !== null && callId === match.callId ? match.command : null,
privacy: this.privacy,
scrub: this.options.scrub,
platform: this.platform,
env: this.env,
run: this.options.installRun ?? runCommand,
})).catch(() => null);
if (line) {
state.installs += 1;
withRedactionPolicy(pin, () => this.emit(state.id, "context.install", line));
}
this.timings.turn_messages.push(Math.round(performance.now() - started));
}
await reader.remove(call);
}
});
}
/** PowerShell downloads and Gallery installs of the turn's calls (cmdlets are not programs: no PATH wrapper sees them). */
private async commandDownloads(state: SessionContext, calls: ToolCall[]): Promise<void> {
const tilde = (text: string) => this.options.scrub.text(tildeText(text, this.privacy));
const os = this.platform === "win32" ? "windows" : this.platform === "darwin" ? "darwin" : "linux";
const line = (call: ToolCall, fields: Partial<InstallLine>): InstallLine => {
const cwd = call.cwd || state.root;
const start = call.start ?? Date.now();
return {
v: 1,
schema: INSTALL_LOG_SCHEMA,
ts: new Date(start).toISOString(),
end: call.end ? new Date(call.end).toISOString() : null,
dur_ms: call.end ? Math.max(0, call.end - start) : null,
turn: state.turn,
call: call.callId,
tool: "powershell",
via: "command",
real: null,
argv: [],
cwd: tilde(cwd),
cwd_rel: relativeTo(state.root, cwd, this.platform),
exit: call.status === "completed" ? 0 : null,
os,
scope: "project",
ecosystem: "url",
target: null,
target_rel: null,
python: null,
requested: [],
resolved: [],
removed: [],
downloads: [],
lockfile: null,
lockfile_rel: null,
lockfile_sha256: null,
...fields,
};
};
for (const call of calls) {
if (toolKind(call.tool) !== "shell" || !call.command) continue;
const cwd = call.cwd || state.root;
for (const found of powershellDownloads(call.command)) {
const expanded = found.out ? powershellPath(found.out, this.env, this.privacy.home) : null;
const file = expanded ? (/^[A-Za-z]:[\\/]|^[\\/]/.test(expanded) ? expanded : `${cwd}${this.platform === "win32" ? "\\" : "/"}${expanded}`) : null;
const hashed = file ? await sha256File(file) : null;
state.installs += 1;
this.emit(state.id, "context.install", line(call, {
downloads: [{
url: cleanUrl(found.url),
path: file ? tilde(file) : found.unresolved ? "(unknown)" : "(piped)",
path_rel: file ? relativeTo(state.root, file, this.platform) : null,
...(hashed?.sha256 ? { sha256: hashed.sha256 } : {}),
...(hashed ? { size: hashed.size } : {}),
}],
}));
}
for (const found of powershellModules(call.command)) {
const resolved = [];
for (const name of found.names.slice(0, 20)) {
const versions = await powershellModuleVersions(name, this.env, this.privacy.home);
const version = found.version && versions.includes(found.version) ? found.version : versions[0];
if (version) resolved.push({ name, version, source: "https://www.powershellgallery.com/api/v2" });
}
state.installs += 1;
this.emit(state.id, "context.install", line(call, {
ecosystem: "psgallery",
scope: found.scope,
argv: [found.cmdlet],
requested: found.names.map((name) => (found.version ? `${name}@${found.version}` : name)),
resolved,
}));
}
}
}
/**
* The turn's end: the files its commands wrote outside the project's
* tracked files (`context.outside_files`, outside-files.ts), whatever the
* install log's switch; off with OMNIRUSH_OUTSIDE_FILES=0.
*/
private outsideFilesTurnEnded(state: SessionContext): void {
if (!outsideFilesEnabled(this.env) || state.turn < 1) return;
const turn = state.turn;
const since = state.turnStartedAt;
const until = Date.now();
const finalMessages = state.finalMessages.promise;
const sharedWindow = [...runningTurns].some((id) => id !== state.id);
const live = state.liveCalls;
this.track(state, (async () => {
// The turn's calls are known once its last messages arrived (a short wait: they only attribute files).
await withTimeout(finalMessages, OUTSIDE_FILES_MESSAGES_WAIT_MS);
const shells = [...state.calls.values(), ...[...live.values()].filter((call) => !state.calls.has(call.callId ?? ""))]
.filter((call) => toolKind(call.tool) === "shell");
const calls = shells.map((call) => ({ callId: call.callId, start: call.start, end: call.end }));
const effects = shells.filter((call) => call.command).map((call) => {
try {
return commandEffects(call.command!, call.cwd ?? state.root, this.privacy.home);
} catch {
return { folders: [], writes: [] };
}
});
const host = this.options.installLog;
const event = await outsideFilesOfTurn({
root: state.root,
turn,
since,
until,
home: this.privacy.home,
platform: this.platform,
env: this.env,
privacy: this.privacy,
scrub: this.options.scrub,
exclude: [...(host ? [host.raw, ...(host.bin ? [host.bin] : []), ...(host.appDirs ?? [])] : []), ...(this.options.cacheDir ? [this.options.cacheDir] : []), ...(this.options.appDirs ?? [])],
commandFolders: [...state.outside.folderPaths(), ...effects.flatMap((effect) => effect.folders.filter((folder) => folder.created).map((folder) => folder.path))],
commandFiles: effects.flatMap((effect) => effect.writes),
calls,
sharedWindow,
box: this.boxOf(state) !== null,
});
if (event) this.emit(state.id, "context.outside_files", event);
})());
}
/** The turn's end: its noted calls, its PowerShell downloads, then `context.env_turn`. */
private installTurnEnded(state: SessionContext): void {
const host = this.options.installLog;
if (!host || !this.installReader || !state.installSampled) return;
const turn = state.turn;
const since = state.turnStartedAt;
const until = Date.now();
const finalMessages = state.finalMessages.promise;
this.track(state, (async () => {
await withTimeout(finalMessages, FINAL_MESSAGES_WAIT_MS);
await this.drainInstalls(false);
const started = performance.now();
const turnCalls = [...state.calls.values()].filter((call) => call.start === null || call.start >= since - 1_000);
await this.commandDownloads(state, turnCalls);
const timings: Record<string, number> = {};
let at = performance.now();
const pathKey = Object.keys(this.env).find((key) => key.toUpperCase() === "PATH") ?? "PATH";
const fingerprint = await envFingerprint({
root: state.root,
pathValue: this.env[pathKey] ?? "",
skipDir: host.bin ?? null,
env: this.env,
platform: this.platform,
arch: osArch(),
osVersion: (() => {
try {
return osRelease();
} catch {
return null;
}
})(),
privacy: this.privacy,
run: this.options.installRun ?? runCommand,
box: this.boxOf(state),
});
timings.fingerprint = Math.round(performance.now() - at);
at = performance.now();
const outside = await outsideWrites({
root: state.root,
since,
until: Date.now(),
home: this.privacy.home,
platform: this.platform,
env: this.env,
privacy: this.privacy,
scrub: this.options.scrub,
exclude: [host.raw, ...(host.bin ? [host.bin] : []), ...(host.appDirs ?? []), ...(this.options.cacheDir ? [this.options.cacheDir] : [])],
});
timings.outside = Math.round(performance.now() - at);
timings.outside_scanned = outside.scanned;
this.emit(state.id, "context.env_turn", {
schema: ENV_TURN_SCHEMA,
turn,
at: new Date(until).toISOString(),
...fingerprint,
installs: state.installs,
outside_writes: outside.files,
outside_truncated: outside.truncated,
timings_ms: timings,
});
this.timings.turn_end.push(Math.round(performance.now() - started));
})());
}
private async collectSessionStart(state: SessionContext): Promise<void> {
const started = performance.now();
const timings: Record<string, number> = {};
const errors: Record<string, string> = {};
const timed = async <T>(name: string, work: () => Promise<T>): Promise<T | undefined> => {
const at = performance.now();
const result = await withTimeout(work(), SECTION_TIMEOUT_MS);
timings[name] = Math.round(performance.now() - at);
if ("value" in result) return result.value;
errors[name] = "timeout" in result ? "timeout" : "failed";
this.noteGap(state.id, { what: `context.environment.${name}`, why: errors[name]! });
return undefined;
};
const { privacy } = this;
const scrub = this.options.scrub;
const runOpts = { platform: this.platform };
// Processes and ports first: services reads the listening ports.
let table: ProcessInfo[] = [];
let listening: ListeningPort[] = [];
if (this.section("processes")) {
const box = this.boxOf(state);
const snapshot = await timed("processes", async () => {
if (box) return boxProcessSnapshot("session_start", 0, box, { ...runOpts, privacy, scrub });
const { processes, method } = await processTable(runOpts);
table = processes;
const ports = await listeningPorts(processes, runOpts);
listening = ports.ports;
return processSnapshot("session_start", 0, { ...runOpts, privacy, scrub, scope: this.scopeOf(state), precomputed: { processes, listening, method: `${method}+${ports.method}` } });
});
if (snapshot) this.emit(state.id, "context.processes", snapshot);
}
const [packages, services, setup, pmConfig, aliases] = await Promise.all([
this.section("system_packages") ? timed("system_packages", () => systemPackages({ platform: this.platform, cacheDir: this.options.cacheDir ?? null })) : undefined,
this.section("services") ? timed("services", () => collectServices({ root: state.root, listening, processes: table, privacy, scrub, platform: this.platform, sessionStartMs: state.startedAt, folders: state.outside.folderPaths() })) : undefined,
this.section("setup")
? timed("setup", () => collectSetup({
root: state.root,
client: this.options.client,
appVersion: this.options.appVersion ?? null,
engineVersion: this.options.engineVersion ?? null,
model: this.options.model?.(state.id) ?? null,
settings: this.options.settings?.() ?? {},
bundledSkillDirs: this.options.bundledSkillDirs ?? [],
bundledSkills: this.options.bundledSkills ?? [],
configFiles: this.options.configFiles ?? [],
mcpFiles: this.options.mcpFiles ?? [],
privacy,
scrub,
...(this.options.denied ? { denied: this.options.denied } : {}),
env: this.env,
}))
: undefined,
this.section("pm_config") ? timed("pm_config", () => collectPmConfig({ privacy, scrub, platform: this.platform, env: this.env })) : undefined,
this.section("shell_aliases") ? timed("shell_aliases", () => collectShellAliases({ privacy, scrub, platform: this.platform, env: this.env })) : undefined,
]);
timings.total = Math.round(performance.now() - started);
this.timings.session_start.push(timings.total);
this.emit(state.id, "context.environment", {
schema: CONTEXT_SCHEMA,
collected_at: new Date().toISOString(),
platform: this.platform,
...(packages ? { system_packages: packages } : {}),
...(services ? { services } : {}),
...(setup ? { setup: setup.setup } : {}),
...(pmConfig ? { pm_config: pmConfig } : {}),
...(aliases ? { shell_aliases: aliases } : {}),
timings_ms: timings,
...(Object.keys(errors).length > 0 ? { errors } : {}),
});
if (setup && setup.files.length > 0) this.emitSetupFiles(state.id, setup.files);
}
/** The skill/plugin texts in events of at most ~512 KiB each. */
private emitSetupFiles(sessionId: string, files: SetupFile[]): void {
const parts: SetupFile[][] = [[]];
let bytes = 0;
for (const file of files) {
const size = Buffer.byteLength(JSON.stringify(file));
if (bytes + size > MAX_SETUP_FILES_EVENT_BYTES && parts[parts.length - 1]!.length > 0) {
parts.push([]);
bytes = 0;
}
parts[parts.length - 1]!.push(file);
bytes += size;
}
parts.forEach((part, index) => this.emit(sessionId, "context.setup_files", { files: part, part: index + 1, parts: parts.length }));
}
/**
* A prompt was dispatched. `after`: work the turn's own capture does first
* (the uploader's artifact baseline listing); the process snapshot waits
* for it so the two never compete for the disk and the event loop.
*/
turnStarted(sessionId: string, after?: Promise<unknown>): void {
const state = this.sessions.get(sessionId);
if (!state || state.ended) return;
state.turn += 1;
state.turnStartedAt = Date.now();
state.installs = 0;
this.refreshInstallGate(state);
state.calls = new Map();
state.liveCalls = new Map();
state.socketsAtStart = new Map();
state.diffRoots = [];
state.finalMessages = deferred();
runningTurns.add(sessionId);
if (state.observer) {
activeTurns.add(sessionId);
state.observer.start();
}
if (!this.section("processes")) return;
const turn = state.turn;
this.track(state, (async () => {
if (after) await withTimeout(after, SECTION_TIMEOUT_MS);
const started = performance.now();
const box = this.boxOf(state);
const snapshot = await withTimeout(box
? boxProcessSnapshot("turn_start", turn, box, { platform: this.platform, privacy: this.privacy, scrub: this.options.scrub })
: processSnapshot("turn_start", turn, { platform: this.platform, privacy: this.privacy, scrub: this.options.scrub, scope: this.scopeOf(state) }), SECTION_TIMEOUT_MS);
this.timings.turn_start.push(Math.round(performance.now() - started));
// A box that did not answer gives no snapshot (null), never an empty one.
if ("value" in snapshot && snapshot.value) this.emit(sessionId, "context.processes", snapshot.value);
})());
}
/**
* A tool call started or ended (the engine's event stream, pi's tool
* hooks). A shell call's start makes the network observer sample every
* 50 ms for its first 2 s and, on Linux, notes the socket table so that a
* connection too short to be sampled is still found from the table's
* diff at its end (only for hosts its command names).
*/
toolEvent(sessionId: string, event: ToolEvent): void {
const state = this.sessions.get(sessionId);
if (!state || state.ended || !event.callId || toolKind(event.tool) !== "shell") return;
const at = event.at ?? Date.now();
const known = state.liveCalls.get(event.callId);
if (this.installReader) {
const command = typeof event.command === "string" ? event.command : null;
const workdir = typeof event.workdir === "string" && event.workdir.trim() ? event.workdir.trim() : null;
if (event.status === "running") this.noteWindow(state, { callId: event.callId, start: at, end: null, cwd: workdir ?? state.root, command });
else {
this.noteWindow(state, { callId: event.callId, start: known?.start ?? at, end: at, cwd: workdir, command });
this.scheduleInstallDrain();
}
}
if (event.status === "running") {
if (known) return;
const command = typeof event.command === "string" ? event.command : null;
const workdir = typeof event.workdir === "string" && event.workdir.trim() ? event.workdir.trim() : null;
state.liveCalls.set(event.callId, { callId: event.callId, tool: event.tool, input: {}, status: "running", start: at, end: null, command, cwd: workdir ? workdir : state.root });
state.observer?.boost();
if (this.platform === "linux" && state.observer && command) state.socketsAtStart.set(event.callId, socketPairs().catch(() => new Map()));
// After the network observer's first sample: the PATH lookups never delay it.
this.emitExec(state, event, at);
return;
}
if (!known) return;
known.end = at;
known.status = event.status;
if (typeof event.command === "string" && !known.command) known.command = event.command;
const before = state.socketsAtStart.get(event.callId);
state.socketsAtStart.delete(event.callId);
if (before && known.command) {
const command = known.command;
const callId = event.callId;
state.diffRoots.push((async () => {
const connections = await socketDiffConnections(await before, await socketPairs().catch(() => new Map()), command, known.start ?? at, this.options.resolver);
return connections.size > 0 ? { pid: -1, command, firstSeen: known.start ?? at, connections, callId, method: "socket_table" } : null;
})().catch(() => null));
}
}
/** The turn's engine messages (possibly in several parts): its tool calls feed #10, #21 and #22. `final`: the turn's last part. */
turnMessages(sessionId: string, messages: unknown, final = false): void {
const state = this.sessions.get(sessionId);
if (!state) return;
if (final) queueMicrotask(() => state.finalMessages.resolve());
const calls = toolCallsOf(messages, state.root, this.privacy.home);
const fresh: ToolCall[] = [];
calls.forEach((call, index) => {
const key = call.callId ?? `${state.turn}:${index}:${call.tool}:${call.start ?? ""}`;
state.calls.set(key, call);
if (this.installReader && toolKind(call.tool) === "shell" && call.start !== null) this.noteWindow(state, { callId: call.callId, start: call.start, end: call.end, cwd: call.cwd, command: call.command });
if (state.processedCalls.has(key) || (call.status !== null && call.status !== "completed" && call.status !== "error")) return;
state.processedCalls.add(key);
fresh.push(call);
});
if (fresh.length === 0) return;
this.track(state, (async () => {
const started = performance.now();
const outside = await state.outside.processCalls(fresh);
for (const folder of outside.folders) this.emit(sessionId, "context.outside_folder", folder);
for (const file of outside.files) this.emit(sessionId, "context.outside_file", file);
for (const call of fresh) {
if (toolKind(call.tool) !== "shell" || !call.command) continue;
for (const tool of commandEffects(call.command, call.cwd, this.privacy.home).ephemeral) {
if (state.ephemeral >= MAX_EPHEMERAL_PER_SESSION) break;
state.ephemeral += 1;
const runner = tool.runner === "bun x" ? "bunx" : tool.runner;
const resolved = await resolveEphemeral(
{ tool_call_id: call.callId, runner, package: tool.package, requested: tool.requested },
{ home: this.privacy.home, platform: this.platform, env: this.env, ...(this.options.ephemeral ?? {}) },
);
this.emit(sessionId, "context.ephemeral_tool", resolved);
}
}
this.timings.turn_messages.push(Math.round(performance.now() - started));
})());
}
/** The turn ended: the network observer stops and its connections are attributed to the turn's calls. */
turnEnded(sessionId: string): void {
const found = this.sessions.get(sessionId);
if (found && !found.ended) {
this.installTurnEnded(found);
this.outsideFilesTurnEnded(found);
if (this.gaps.pending(sessionId)) this.track(found, this.sendGaps(found, false));
}
runningTurns.delete(sessionId);
const state = found;
if (!state || !state.observer) return;
const observer = state.observer;
const turn = state.turn;
const alone = activeTurns.size <= 1;
activeTurns.delete(sessionId);
const finalMessages = state.finalMessages.promise;
const live = state.liveCalls;
const diffs = state.diffRoots;
this.track(state, (async () => {
const roots: Root[] = await observer.stop();
// The turn's calls are known once its last messages arrived (the uploader flushes them right after this milestone).
await withTimeout(finalMessages, FINAL_MESSAGES_WAIT_MS);
const started = performance.now();
for (const root of await Promise.all(diffs)) if (root) roots.push(root);
const calls = [...state.calls.values()];
// Calls the tool events saw but no message carried yet (the engine had not stored them).
for (const call of live.values()) if (!calls.some((known) => known.callId === call.callId)) calls.push(call);
// A message's call takes the tool event's start and end when it has none.
for (const call of calls) {
const seen = call.callId ? live.get(call.callId) : undefined;
if (seen) {
call.start ??= seen.start;
call.end ??= seen.end;
}
}
this.timings.network_sample_ms = observer.sampleMs;
this.timings.network_samples = observer.samples;
const events = await attributeConnections(roots, calls, { turn, method: observer.method, pollMs: observer.pollMs, ...(this.options.resolver ? { resolver: this.options.resolver } : {}) });
for (const event of events) {
// Another session's turn ran at the same time: an unmatched shell may be its.
if (event.scope === "turn" && !alone) continue;
this.emit(sessionId, "context.network", event);
}
this.timings.turn_end.push(Math.round(performance.now() - started));
})());
}
/** Resolves once the session's background work is done (or after `timeoutMs`). */
async settled(sessionId: string, timeoutMs = SETTLE_TIMEOUT_MS): Promise<void> {
const state = this.sessions.get(sessionId);
if (!state) return;
const deadline = Date.now() + timeoutMs;
while (state.pending.size > 0 && Date.now() < deadline) {
await withTimeout(Promise.all([...state.pending]), Math.max(1, deadline - Date.now()));
}
}
sessionEnded(sessionId: string): void {
const state = this.sessions.get(sessionId);
if (!state || state.ended) return;
if (state.observer && activeTurns.has(sessionId)) this.turnEnded(sessionId);
state.finalMessages.resolve();
state.ended = true;
runningTurns.delete(sessionId);
if (this.installReader) {
this.track(state, this.drainInstalls(true));
const host = this.options.installLog;
if (host && ![...this.sessions.values()].some((item) => !item.ended && item.installSampled)) this.track(state, setInstallLogActive(host.raw, false));
}
void this.settled(sessionId, SETTLE_TIMEOUT_MS).finally(() => this.sessions.delete(sessionId));
}
}