@revisium/orchestrator 0.0.0 → 0.1.0-alpha.10

package/dist/observability/agent-observability.service.js

@@ -0,0 +1,1142 @@
+import { open, readdir, readFile, lstat, realpath } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { isAbsolute, join, relative, resolve, win32 } from 'node:path';
+import { TextDecoder } from 'node:util';
+import { redactTokens } from '../runners/gh-identity.js';
+import { AGENT_ACTIVITY_EVENT_KEY, AGENT_OUTPUT_STREAM_KEY, AgentObservabilityError, } from './types.js';
+const DEFAULT_READ_BYTES = 65_536;
+const MAX_READ_BYTES = 1_048_576;
+const MAX_METADATA_BYTES = 65_536;
+const SAFE_SEGMENT_RE = /^[A-Za-z0-9_.:-]+$/;
+const LOG_FILES = {
+    stdout: 'stdout.log',
+    stderr: 'stderr.log',
+    events: 'events.jsonl',
+};
+const STDOUT_MARKER = '--- stdout ---\n';
+const STDERR_MARKER = '\n--- stderr ---\n';
+const UTF8_DECODER = new TextDecoder('utf-8', { fatal: true });
+const UTF8_BOUNDARY_CONTEXT_BYTES = 3;
+const SENSITIVE_BOUNDARY_SCAN_BYTES = 65_536;
+const TOKEN_PATTERN = /\b(?:gh[opsru]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})\b/g;
+const WINDOWS_PATH_PATTERN = /\b[A-Za-z]:\\[^\s'"`]+/g;
+const POSIX_PATH_PATTERN = /\/(?:Users|private|tmp|var|opt|home|workspace|Volumes)\/[^\s'"`)]+/g;
+const DEFAULT_STREAM_EVENT_LIMIT = 100;
+const MAX_STREAM_EVENT_LIMIT = 1_000;
+const DEFAULT_STREAM_READ_TIMEOUT_MS = 250;
+const DEFAULT_IDLE_THRESHOLD_MS = 120_000;
+const MAX_STREAM_ACTIVITY_SCAN_EVENTS = 10_000;
+const SAFE_CURSOR_RE = /^[A-Za-z0-9_.:-]+$/;
+const OUTPUT_EVENT_KINDS = new Set(['activity', 'output', 'parsed_event', 'status']);
+const ACTIVITY_STATUSES = new Set([
+    'starting',
+    'running',
+    'idle',
+    'permission_blocked',
+    'cancelled',
+    'exited',
+    'timed_out',
+    'failed',
+]);
+export class AgentObservabilityService {
+    artifactRoot;
+    runExists;
+    dbos;
+    idleThresholdMs;
+    now;
+    constructor(options) {
+        this.artifactRoot = resolve(options.artifactRoot);
+        this.runExists = options.runExists;
+        this.dbos = options.dbos;
+        this.idleThresholdMs = validateIdleThreshold(options.idleThresholdMs);
+        this.now = options.now ?? (() => Date.now());
+    }
+    async getAgentActivity(runId) {
+        const safeRunId = validateSegment(runId, 'runId');
+        await this.assertRunExists(safeRunId);
+        const eventSnapshot = await this.dbos?.getEvent(safeRunId, AGENT_ACTIVITY_EVENT_KEY, { timeoutSeconds: 0 });
+        if (eventSnapshot)
+            return this.classifyActivity(eventSnapshot);
+        const streamActivity = await this.readLatestAgentActivityFromStream(safeRunId);
+        if (streamActivity)
+            return streamActivity;
+        return this.getAgentActivityFromArtifacts(safeRunId);
+    }
+    async readAgentOutputEvents(input) {
+        const safeRunId = validateSegment(input.runId, 'runId');
+        const cursor = input.cursor === undefined ? undefined : validateCursor(input.cursor);
+        const limit = validateEventLimit(input.limit);
+        const timeoutMs = validateStreamTimeout(input.timeoutMs);
+        await this.assertRunExists(safeRunId);
+        if (!this.dbos) {
+            return { runId: safeRunId, events: [], cursorExpired: cursor !== undefined };
+        }
+        const generator = this.dbos.readStream(safeRunId, AGENT_OUTPUT_STREAM_KEY);
+        return withGeneratorCleanup(generator, async () => {
+            const page = await readBoundedOutputEvents({
+                generator,
+                runId: safeRunId,
+                cursor,
+                limit,
+                timeoutMs,
+            });
+            return {
+                runId: safeRunId,
+                events: page.events,
+                nextCursor: page.events.at(-1)?.cursor,
+                cursorExpired: hasExpiredCursor(cursor, page.cursorFound),
+            };
+        });
+    }
+    async *watchAgentOutput(input) {
+        const safeRunId = validateSegment(input.runId, 'runId');
+        const cursor = input.cursor === undefined ? undefined : validateCursor(input.cursor);
+        if (!this.dbos) {
+            throw new AgentObservabilityError('DBOS_STREAM_UNAVAILABLE', 'DBOS stream reader is not configured');
+        }
+        let cursorFound = cursor === undefined;
+        let scannedBeforeCursor = 0;
+        for await (const raw of this.dbos.readStream(safeRunId, AGENT_OUTPUT_STREAM_KEY)) {
+            if (!cursorFound)
+                scannedBeforeCursor += 1;
+            const event = normalizeOutputEvent(safeRunId, raw);
+            if (!event) {
+                if (scannedBeforeCursor >= MAX_STREAM_EVENT_LIMIT)
+                    throw cursorExpiredError();
+                continue;
+            }
+            if (cursorFound) {
+                yield event;
+                continue;
+            }
+            cursorFound = event.cursor === cursor;
+            if (cursorFound)
+                continue;
+            if (scannedBeforeCursor >= MAX_STREAM_EVENT_LIMIT)
+                throw cursorExpiredError();
+        }
+        if (hasExpiredCursor(cursor, cursorFound)) {
+            throw cursorExpiredError();
+        }
+    }
+    async *watchAgentActivity(input) {
+        const snapshots = new Map();
+        for await (const event of this.watchAgentOutput(input)) {
+            if (!event.snapshot)
+                continue;
+            snapshots.set(event.attemptId, this.classifySnapshot(event.snapshot));
+            yield this.buildRunActivity(event.runId, [...snapshots.values()]);
+        }
+    }
+    async listAgentAttempts(runId) {
+        const safeRunId = validateSegment(runId, 'runId');
+        const runDir = await this.resolveRunDirectory(safeRunId);
+        if (!runDir.exists)
+            return [];
+        const entries = await readdir(runDir.path, { withFileTypes: true });
+        const attempts = [];
+        for (const entry of entries) {
+            if (entry.isSymbolicLink()) {
+                throw validationFailure('artifact attempt must not be a symlink');
+            }
+            if (!entry.isDirectory())
+                continue;
+            const attemptId = validateSegment(entry.name, 'attemptId');
+            const attemptDir = join(runDir.path, attemptId);
+            await ensureDirectoryInsideRoot(attemptDir, runDir.realRoot, 'agent attempt');
+            attempts.push(await this.readAttemptSummary(safeRunId, attemptId, attemptDir, runDir.realRoot));
+        }
+        return attempts
+            .sort((a, b) => {
+            const timeDiff = compareOptionalTimeAsc(a.startedSortAt, b.startedSortAt);
+            return timeDiff !== 0 ? timeDiff : a.attemptId.localeCompare(b.attemptId);
+        })
+            .map(({ latestSortAt: _latestSortAt, startedSortAt: _startedSortAt, ...summary }) => summary);
+    }
+    async getAgentLog(input) {
+        const safeRunId = validateSegment(input.runId, 'runId');
+        const stream = validateStream(input.stream);
+        const bounds = validateBounds(input);
+        const explicitAttemptId = input.attemptId !== undefined ? validateSegment(input.attemptId, 'attemptId') : undefined;
+        const runDir = await this.resolveRunDirectory(safeRunId);
+        const attemptId = explicitAttemptId ?? (await this.selectLatestAttemptId(safeRunId));
+        if (!runDir.exists) {
+            throw new AgentObservabilityError('NO_AGENT_ATTEMPT_AVAILABLE', 'no agent attempt artifacts are available');
+        }
+        const attemptDir = join(runDir.path, attemptId);
+        const attemptExists = await directoryExistsInsideRoot(attemptDir, runDir.realRoot, 'agent attempt');
+        if (!attemptExists) {
+            throw new AgentObservabilityError('NO_AGENT_ATTEMPT_AVAILABLE', 'agent attempt artifacts are not available');
+        }
+        if (stream === 'combined') {
+            return this.readCombinedLog(safeRunId, attemptId, attemptDir, runDir.realRoot, bounds);
+        }
+        const file = await resolveOptionalFile(join(attemptDir, LOG_FILES[stream]), runDir.realRoot, `${stream} log`);
+        if (!file.exists)
+            return emptyChunk(safeRunId, attemptId, stream);
+        const chunk = await readFileChunk(file, bounds);
+        return {
+            runId: safeRunId,
+            attemptId,
+            stream,
+            ...chunk,
+        };
+    }
+    async selectLatestAttemptId(runId) {
+        const attempts = await this.listAgentAttempts(runId);
+        if (attempts.length === 0) {
+            throw new AgentObservabilityError('NO_AGENT_ATTEMPT_AVAILABLE', 'no agent attempt artifacts are available');
+        }
+        return attempts
+            .map((attempt) => ({
+            ...attempt,
+            latestSortAt: parseDate(attempt.finishedAt) ?? parseDate(attempt.startedAt),
+        }))
+            .sort((a, b) => {
+            const timeDiff = compareOptionalTimeAsc(a.latestSortAt, b.latestSortAt);
+            return timeDiff !== 0 ? timeDiff : a.attemptId.localeCompare(b.attemptId);
+        })
+            .at(-1).attemptId;
+    }
+    async getAgentActivityFromArtifacts(runId) {
+        let attempts;
+        try {
+            attempts = await this.listAgentAttempts(runId);
+        }
+        catch (err) {
+            if (err instanceof AgentObservabilityError) {
+                if (err.code === 'NO_AGENT_ATTEMPT_AVAILABLE')
+                    return null;
+            }
+            throw err;
+        }
+        if (attempts.length === 0)
+            return null;
+        return this.buildRunActivity(runId, attempts.map((attempt) => {
+            const finishedAt = attempt.finishedAt;
+            const latestAt = finishedAt ?? attempt.startedAt;
+            const snapshot = {
+                runId,
+                attemptId: attempt.attemptId,
+                stepId: attempt.stepId,
+                ...(attempt.stepKey ? { stepKey: attempt.stepKey } : {}),
+                role: attempt.role,
+                runner: attempt.runner,
+                status: statusFromArtifact(attempt.status, attempt.timedOut),
+                startedAt: attempt.startedAt,
+                lastEventAt: latestAt,
+                stdoutBytes: attempt.stdoutBytes,
+                stderrBytes: attempt.stderrBytes,
+                eventCount: 0,
+                artifactRef: attempt.artifactRef,
+            };
+            if (finishedAt)
+                snapshot.lastOutputAt = finishedAt;
+            const exitCode = attempt.exitCode;
+            if (exitCode === null || typeof exitCode === 'number')
+                snapshot.exitCode = exitCode;
+            const timedOut = attempt.timedOut;
+            if (typeof timedOut === 'boolean')
+                snapshot.timedOut = timedOut;
+            return snapshot;
+        }));
+    }
+    async readLatestAgentActivityFromStream(runId) {
+        if (!this.dbos)
+            return null;
+        const generator = this.dbos.readStream(runId, AGENT_OUTPUT_STREAM_KEY);
+        const snapshots = new Map();
+        let scanned = 0;
+        await withGeneratorCleanup(generator, async () => {
+            while (scanned < MAX_STREAM_ACTIVITY_SCAN_EVENTS) {
+                const next = await nextWithTimeout(generator, DEFAULT_STREAM_READ_TIMEOUT_MS);
+                if (next === 'timeout' || next.done)
+                    break;
+                scanned += 1;
+                const event = normalizeOutputEvent(runId, next.value);
+                if (event?.snapshot)
+                    snapshots.set(event.attemptId, event.snapshot);
+            }
+        });
+        if (scanned >= MAX_STREAM_ACTIVITY_SCAN_EVENTS)
+            return null;
+        if (snapshots.size === 0)
+            return null;
+        return this.buildRunActivity(runId, [...snapshots.values()]);
+    }
+    buildRunActivity(runId, attempts) {
+        return buildRunActivity(runId, attempts.map((attempt) => this.classifySnapshot(redactActivitySnapshot(attempt))));
+    }
+    classifyActivity(activity) {
+        return this.buildRunActivity(activity.runId, activity.attempts);
+    }
+    classifySnapshot(snapshot) {
+        if (snapshot.status !== 'starting' && snapshot.status !== 'running')
+            return snapshot;
+        const latestAt = parseDate(snapshot.lastOutputAt) ?? parseDate(snapshot.lastEventAt);
+        if (latestAt === undefined)
+            return snapshot;
+        if (this.now() - latestAt < this.idleThresholdMs)
+            return snapshot;
+        return { ...snapshot, status: 'idle' };
+    }
+    async assertRunExists(runId) {
+        if (!this.runExists)
+            return;
+        const exists = await this.runExists(runId);
+        if (!exists)
+            throw new AgentObservabilityError('RUN_NOT_FOUND', 'run was not found');
+    }
+    async resolveRunDirectory(runId) {
+        if (this.runExists) {
+            const exists = await this.runExists(runId);
+            if (!exists)
+                throw new AgentObservabilityError('RUN_NOT_FOUND', 'run was not found');
+        }
+        const realRoot = await resolveRootIfPresent(this.artifactRoot);
+        const runPath = join(this.artifactRoot, runId);
+        const exists = realRoot
+            ? await directoryExistsInsideRoot(runPath, realRoot, 'run artifact')
+            : false;
+        if (!exists) {
+            if (this.runExists)
+                return { exists: false, realRoot };
+            throw new AgentObservabilityError('RUN_NOT_FOUND', 'run artifact directory was not found');
+        }
+        if (!realRoot)
+            throw new AgentObservabilityError('RUN_NOT_FOUND', 'run artifact directory was not found');
+        return { exists: true, path: runPath, realRoot };
+    }
+    async readAttemptSummary(runId, attemptId, attemptDir, realRoot) {
+        const dirStat = await lstat(attemptDir);
+        const meta = await readMetadata(join(attemptDir, 'meta.json'), realRoot);
+        const stdoutBytes = await optionalFileSize(join(attemptDir, 'stdout.log'), realRoot, 'stdout log');
+        const stderrBytes = await optionalFileSize(join(attemptDir, 'stderr.log'), realRoot, 'stderr log');
+        const startedAt = stringValue(meta.startedAt) ?? dirStat.mtime.toISOString();
+        const finishedAt = stringValue(meta.finishedAt);
+        const exitCode = numberOrNull(meta.exitCode) ?? numberOrNull(meta.code);
+        const timedOut = booleanValue(meta.timedOut);
+        const summary = {
+            runId,
+            attemptId,
+            stepId: redactPublicText(stringValue(meta.stepId) ?? ''),
+            role: redactPublicText(stringValue(meta.role) ?? 'unknown'),
+            runner: redactPublicText(stringValue(meta.runner) ?? 'unknown'),
+            artifactRef: validateArtifactRef(`${runId}/${attemptId}`),
+            startedAt: redactPublicText(startedAt),
+            status: redactPublicText(stringValue(meta.status) ?? 'unknown'),
+            stdoutBytes,
+            stderrBytes,
+            startedSortAt: parseDate(startedAt),
+            latestSortAt: parseDate(finishedAt) ?? parseDate(startedAt),
+        };
+        const stepKey = stringValue(meta.stepKey);
+        if (stepKey)
+            summary.stepKey = redactPublicText(stepKey);
+        if (finishedAt)
+            summary.finishedAt = redactPublicText(finishedAt);
+        if (exitCode !== undefined)
+            summary.exitCode = exitCode;
+        if (timedOut !== undefined)
+            summary.timedOut = timedOut;
+        return summary;
+    }
+    async readCombinedLog(runId, attemptId, attemptDir, realRoot, bounds) {
+        const stdout = await resolveOptionalFile(join(attemptDir, 'stdout.log'), realRoot, 'stdout log');
+        const stderr = await resolveOptionalFile(join(attemptDir, 'stderr.log'), realRoot, 'stderr log');
+        const segments = [
+            bufferSegment(STDOUT_MARKER),
+            { kind: 'file', file: stdout, size: stdout.size },
+            bufferSegment(STDERR_MARKER),
+            { kind: 'file', file: stderr, size: stderr.size },
+        ];
+        const chunk = await readSyntheticChunk(segments, bounds);
+        return {
+            runId,
+            attemptId,
+            stream: 'combined',
+            ...chunk,
+        };
+    }
+}
+function validateSegment(value, label) {
+    if (value.length === 0 ||
+        value.includes('\0') ||
+        value.includes('/') ||
+        value.includes('\\') ||
+        value === '.' ||
+        value === '..' ||
+        isAbsolute(value) ||
+        win32.isAbsolute(value) ||
+        !SAFE_SEGMENT_RE.test(value)) {
+        throw validationFailure(`invalid ${label}`);
+    }
+    return value;
+}
+function validateArtifactRef(value) {
+    const parts = value.split('/');
+    if (parts.length !== 2)
+        throw validationFailure('invalid artifactRef');
+    return `${validateSegment(parts[0] ?? '', 'artifactRef runId')}/${validateSegment(parts[1] ?? '', 'artifactRef attemptId')}`;
+}
+function validateStream(stream) {
+    if (stream !== 'stdout' && stream !== 'stderr' && stream !== 'events' && stream !== 'combined') {
+        throw validationFailure('invalid log stream');
+    }
+    return stream;
+}
+function validateBounds(input) {
+    const hasTail = input.tailBytes !== undefined;
+    const hasOffsetOrLimit = input.offsetBytes !== undefined || input.limitBytes !== undefined;
+    if (hasTail && hasOffsetOrLimit) {
+        throw validationFailure('tailBytes cannot be combined with offsetBytes or limitBytes');
+    }
+    if (hasTail) {
+        const tailBytes = validatePositiveByteCount(input.tailBytes, 'tailBytes');
+        return { mode: 'tail', tailBytes };
+    }
+    if (hasOffsetOrLimit) {
+        const offsetBytes = input.offsetBytes ?? 0;
+        if (!Number.isInteger(offsetBytes) || offsetBytes < 0)
+            throw validationFailure('offsetBytes must be non-negative');
+        const limitBytes = validatePositiveByteCount(input.limitBytes ?? DEFAULT_READ_BYTES, 'limitBytes');
+        return { mode: 'offset', offsetBytes, limitBytes };
+    }
+    return { mode: 'tail', tailBytes: DEFAULT_READ_BYTES };
+}
+function validatePositiveByteCount(value, label) {
+    if (value === undefined || !Number.isInteger(value) || value <= 0) {
+        throw validationFailure(`${label} must be a positive integer`);
+    }
+    if (value > MAX_READ_BYTES)
+        throw validationFailure(`${label} exceeds maximum allowed bytes`);
+    return value;
+}
+function validateEventLimit(value) {
+    const limit = value ?? DEFAULT_STREAM_EVENT_LIMIT;
+    if (!Number.isInteger(limit) || limit <= 0)
+        throw validationFailure('limit must be a positive integer');
+    if (limit > MAX_STREAM_EVENT_LIMIT)
+        throw validationFailure('limit exceeds maximum allowed events');
+    return limit;
+}
+function validateStreamTimeout(value) {
+    const timeout = value ?? DEFAULT_STREAM_READ_TIMEOUT_MS;
+    if (!Number.isInteger(timeout) || timeout <= 0)
+        throw validationFailure('timeoutMs must be a positive integer');
+    return timeout;
+}
+function validateIdleThreshold(value) {
+    const threshold = value ?? DEFAULT_IDLE_THRESHOLD_MS;
+    if (!Number.isInteger(threshold) || threshold <= 0) {
+        throw validationFailure('idleThresholdMs must be a positive integer');
+    }
+    return threshold;
+}
+function validateCursor(value) {
+    if (value.length === 0 || value.length > 512 || !SAFE_CURSOR_RE.test(value)) {
+        throw validationFailure('invalid cursor');
+    }
+    return value;
+}
+async function readBoundedOutputEvents(input) {
+    const events = [];
+    let cursorFound = input.cursor === undefined;
+    let scannedBeforeCursor = 0;
+    while (events.length < input.limit) {
+        const next = await nextWithTimeout(input.generator, input.timeoutMs);
+        if (next === 'timeout' || next.done)
+            break;
+        const state = processOutputEventCandidate(input.runId, input.cursor, next.value, cursorFound, scannedBeforeCursor);
+        cursorFound = state.cursorFound;
+        scannedBeforeCursor = state.scannedBeforeCursor;
+        if (state.event)
+            events.push(state.event);
+        if (state.stop)
+            break;
+    }
+    return { events, cursorFound };
+}
+function processOutputEventCandidate(runId, cursor, value, cursorFound, scannedBeforeCursor) {
+    const nextScanned = cursorFound ? scannedBeforeCursor : scannedBeforeCursor + 1;
+    const event = normalizeOutputEvent(runId, value);
+    if (event) {
+        if (cursorFound)
+            return { event, cursorFound, scannedBeforeCursor: nextScanned, stop: false };
+        const found = event.cursor === cursor;
+        return {
+            cursorFound: found,
+            scannedBeforeCursor: nextScanned,
+            stop: cursorMissedScanLimit(found, nextScanned),
+        };
+    }
+    return {
+        cursorFound,
+        scannedBeforeCursor: nextScanned,
+        stop: cursor !== undefined && cursorFound === false && nextScanned >= MAX_STREAM_EVENT_LIMIT,
+    };
+}
+function hasExpiredCursor(cursor, cursorFound) {
+    return typeof cursor === 'string' && cursorFound === false;
+}
+function cursorExpiredError() {
+    return new AgentObservabilityError('STREAM_CURSOR_EXPIRED', 'stream cursor was not found before the scan limit');
+}
+function cursorMissedScanLimit(cursorFound, scannedBeforeCursor) {
+    if (cursorFound)
+        return false;
+    return scannedBeforeCursor >= MAX_STREAM_EVENT_LIMIT;
+}
+async function nextWithTimeout(generator, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([
+            generator.next(),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve('timeout'), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function withGeneratorCleanup(generator, read) {
+    let result;
+    let hasResult = false;
+    let primaryError;
+    try {
+        result = await read();
+        hasResult = true;
+    }
+    catch (error) {
+        primaryError = error;
+    }
+    let cleanupError;
+    try {
+        await generator.return(undefined);
+    }
+    catch (error) {
+        cleanupError = error;
+    }
+    if (primaryError !== undefined)
+        throw primaryError;
+    if (cleanupError !== undefined)
+        throw cleanupError;
+    if (hasResult)
+        return result;
+    throw validationFailure('stream reader did not produce a result');
+}
+function normalizeOutputEvent(runId, value) {
+    const event = asRecord(value);
+    if (event?.runId !== runId)
+        return null;
+    const fields = normalizeOutputEventFields(event);
+    if (!fields)
+        return null;
+    const normalized = {
+        cursor: fields.cursor,
+        runId,
+        attemptId: fields.attemptId,
+        stepId: redactPublicText(fields.stepId),
+        at: fields.at,
+        kind: fields.kind,
+    };
+    applyOutputEventOptionalFields(normalized, event, runId, fields.attemptId);
+    return normalized;
+}
+function normalizeOutputEventFields(event) {
+    const cursor = normalizeCursorValue(event.cursor);
+    const attemptId = normalizeSegmentValue(event.attemptId, 'attemptId');
+    const stepId = normalizeNonEmptyString(event.stepId);
+    const at = normalizeNonEmptyString(event.at);
+    const kind = normalizeOutputEventKind(event.kind);
+    if (!cursor || !attemptId || !stepId || !at || !kind)
+        return undefined;
+    return { cursor, attemptId, stepId, at, kind };
+}
+function applyOutputEventOptionalFields(normalized, event, runId, attemptId) {
+    applyOutputEventIdentityFields(normalized, event);
+    applyOutputEventByteFields(normalized, event);
+    applyOutputEventTextFields(normalized, event);
+    const statusHint = normalizeActivityStatus(event.statusHint);
+    if (statusHint)
+        normalized.statusHint = statusHint;
+    const snapshot = normalizeActivitySnapshotForOutput(runId, attemptId, event.snapshot);
+    if (snapshot)
+        normalized.snapshot = snapshot;
+}
+function applyOutputEventIdentityFields(normalized, event) {
+    const stepKey = normalizeNonEmptyString(event.stepKey);
+    if (stepKey)
+        normalized.stepKey = redactPublicText(stepKey);
+    const attemptSeq = normalizeNonNegativeInteger(event.attemptSeq);
+    if (attemptSeq !== undefined)
+        normalized.attemptSeq = attemptSeq;
+    const stream = normalizeOutputStream(event.stream);
+    if (stream)
+        normalized.stream = stream;
+}
+function applyOutputEventByteFields(normalized, event) {
+    const bytes = normalizeNonNegativeInteger(event.bytes);
+    if (bytes !== undefined)
+        normalized.bytes = bytes;
+    const outputOffsetBytes = normalizeNonNegativeInteger(event.outputOffsetBytes);
+    if (outputOffsetBytes !== undefined)
+        normalized.outputOffsetBytes = outputOffsetBytes;
+}
+function applyOutputEventTextFields(normalized, event) {
+    if (typeof event.preview === 'string')
+        normalized.preview = redactPublicText(event.preview);
+    if (typeof event.parsedType === 'string')
+        normalized.parsedType = redactPublicText(event.parsedType);
+}
+function normalizeCursorValue(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    try {
+        return validateCursor(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeSegmentValue(value, name) {
+    if (typeof value !== 'string')
+        return undefined;
+    try {
+        return validateSegment(value, name);
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function normalizeString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function normalizeOutputEventKind(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const kind = value;
+    return OUTPUT_EVENT_KINDS.has(kind) ? kind : undefined;
+}
+function normalizeOutputStream(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === 'stdout' || value === 'stderr' || value === 'agent-jsonl')
+        return value;
+    return undefined;
+}
+function normalizeActivityStatus(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const status = value;
+    return ACTIVITY_STATUSES.has(status) ? status : undefined;
+}
+function normalizeActivitySnapshotForOutput(runId, attemptId, value) {
+    const snapshot = asRecord(value);
+    if (!snapshot)
+        return undefined;
+    if (snapshot.runId !== runId || snapshot.attemptId !== attemptId)
+        return undefined;
+    const fields = normalizeActivitySnapshotFields(snapshot);
+    if (!fields)
+        return undefined;
+    const normalized = {
+        runId,
+        attemptId,
+        stepId: redactPublicText(fields.stepId),
+        role: redactPublicText(fields.role),
+        runner: redactPublicText(fields.runner),
+        status: fields.status,
+        startedAt: fields.startedAt,
+        lastEventAt: fields.lastEventAt,
+        stdoutBytes: fields.stdoutBytes,
+        stderrBytes: fields.stderrBytes,
+        eventCount: fields.eventCount,
+        artifactRef: redactPublicText(fields.artifactRef),
+    };
+    applyActivitySnapshotOptionalFields(normalized, snapshot);
+    return normalized;
+}
+function normalizeActivitySnapshotFields(snapshot) {
+    const fields = {
+        stepId: normalizeNonEmptyString(snapshot.stepId),
+        role: normalizeString(snapshot.role),
+        runner: normalizeString(snapshot.runner),
+        status: normalizeActivityStatus(snapshot.status),
+        startedAt: normalizeString(snapshot.startedAt),
+        lastEventAt: normalizeString(snapshot.lastEventAt),
+        stdoutBytes: normalizeNonNegativeInteger(snapshot.stdoutBytes),
+        stderrBytes: normalizeNonNegativeInteger(snapshot.stderrBytes),
+        eventCount: normalizeNonNegativeInteger(snapshot.eventCount),
+        artifactRef: normalizeNonEmptyString(snapshot.artifactRef),
+    };
+    if (Object.values(fields).includes(undefined))
+        return undefined;
+    return fields;
+}
+function applyActivitySnapshotOptionalFields(normalized, snapshot) {
+    const stepKey = normalizeNonEmptyString(snapshot.stepKey);
+    if (stepKey)
+        normalized.stepKey = redactPublicText(stepKey);
+    if (typeof snapshot.pid === 'number' && Number.isInteger(snapshot.pid) && snapshot.pid > 0)
+        normalized.pid = snapshot.pid;
+    if (typeof snapshot.lastOutputAt === 'string')
+        normalized.lastOutputAt = snapshot.lastOutputAt;
+    const lastStream = normalizeOutputStream(snapshot.lastStream);
+    if (lastStream)
+        normalized.lastStream = lastStream;
+    if (typeof snapshot.exitCode === 'number' && Number.isInteger(snapshot.exitCode))
+        normalized.exitCode = snapshot.exitCode;
+    if (snapshot.exitCode === null)
+        normalized.exitCode = null;
+    if (typeof snapshot.timedOut === 'boolean')
+        normalized.timedOut = snapshot.timedOut;
+    if (typeof snapshot.error === 'string')
+        normalized.error = redactPublicText(snapshot.error);
+}
+function normalizeNonNegativeInteger(value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        return undefined;
+    return value;
+}
+function asRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    return value;
+}
+function redactActivitySnapshot(snapshot) {
+    return {
+        ...snapshot,
+        stepId: redactPublicText(snapshot.stepId),
+        ...(snapshot.stepKey ? { stepKey: redactPublicText(snapshot.stepKey) } : {}),
+        role: redactPublicText(snapshot.role),
+        runner: redactPublicText(snapshot.runner),
+        artifactRef: redactPublicText(snapshot.artifactRef),
+        ...(snapshot.error ? { error: redactPublicText(snapshot.error) } : {}),
+    };
+}
+function buildRunActivity(runId, attempts) {
+    const sorted = [...attempts];
+    sorted.sort((a, b) => {
+        const startedDiff = (parseDate(a.startedAt) ?? 0) - (parseDate(b.startedAt) ?? 0);
+        if (startedDiff === 0)
+            return a.attemptId.localeCompare(b.attemptId);
+        return startedDiff;
+    });
+    const activityTimes = sorted
+        .map((attempt) => attempt.lastEventAt || attempt.startedAt)
+        .sort((a, b) => a.localeCompare(b));
+    const latestActivityAt = activityTimes.at(-1) ?? new Date(0).toISOString();
+    const outputTimes = sorted
+        .map((attempt) => attempt.lastOutputAt)
+        .filter((value) => typeof value === 'string' && value.length > 0)
+        .sort((a, b) => a.localeCompare(b));
+    const latestOutputAt = outputTimes.at(-1);
+    return {
+        runId,
+        aggregateStatus: aggregateStatus(sorted),
+        latestActivityAt,
+        ...(latestOutputAt ? { latestOutputAt } : {}),
+        attempts: sorted,
+    };
+}
+function aggregateStatus(attempts) {
+    const statuses = new Set(attempts.map((attempt) => attempt.status));
+    if (statuses.has('timed_out'))
+        return 'timed_out';
+    if (statuses.has('cancelled'))
+        return 'cancelled';
+    if (statuses.has('failed'))
+        return 'failed';
+    if (statuses.has('permission_blocked'))
+        return 'permission_blocked';
+    if (statuses.has('running') || statuses.has('starting'))
+        return 'running';
+    if (statuses.has('idle'))
+        return 'idle';
+    return 'exited';
+}
+function statusFromArtifact(status, timedOut) {
+    if (timedOut || status === 'timed_out')
+        return 'timed_out';
+    if (status === 'error' || status === 'failed')
+        return 'failed';
+    if (status === 'running' || status === 'starting')
+        return 'running';
+    if (status === 'cancelled')
+        return 'cancelled';
+    if (status === 'permission_blocked')
+        return 'permission_blocked';
+    if (status === 'idle')
+        return 'idle';
+    return 'exited';
+}
+async function resolveRootIfPresent(root) {
+    try {
+        const rootStat = await lstat(root);
+        if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+            throw validationFailure('artifact root must be a directory');
+        }
+        return await realpath(root);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw error;
+    }
+}
+async function directoryExistsInsideRoot(path, realRoot, label) {
+    try {
+        await ensureDirectoryInsideRoot(path, realRoot, label);
+        return true;
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return false;
+        throw error;
+    }
+}
+async function ensureDirectoryInsideRoot(path, realRoot, label) {
+    const itemStat = await lstat(path);
+    if (itemStat.isSymbolicLink())
+        throw validationFailure(`${label} must not be a symlink`);
+    if (!itemStat.isDirectory())
+        throw validationFailure(`${label} must be a directory`);
+    assertInsideRoot(await realpath(path), realRoot);
+}
+async function resolveOptionalFile(path, realRoot, label) {
+    try {
+        const itemStat = await lstat(path);
+        if (itemStat.isSymbolicLink())
+            throw validationFailure(`${label} must not be a symlink`);
+        if (!itemStat.isFile())
+            throw validationFailure(`${label} must be a file`);
+        const realFilePath = await realpath(path);
+        assertInsideRoot(realFilePath, realRoot);
+        return { exists: true, path: realFilePath, size: itemStat.size };
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return { exists: false, size: 0 };
+        throw error;
+    }
+}
+async function optionalFileSize(path, realRoot, label) {
+    return (await resolveOptionalFile(path, realRoot, label)).size;
+}
+async function readMetadata(path, realRoot) {
+    const file = await resolveOptionalFile(path, realRoot, 'metadata');
+    if (!file.exists)
+        return {};
+    if (file.size > MAX_METADATA_BYTES) {
+        throw validationFailure('artifact metadata exceeds maximum allowed bytes');
+    }
+    try {
+        const content = await readFile(file.path, 'utf8');
+        const parsed = JSON.parse(content);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        throw validationFailure('invalid artifact metadata');
+    }
+}
+async function readFileChunk(file, bounds) {
+    const totalBytes = file.size;
+    const range = rangeForBounds(totalBytes, bounds);
+    if (range.start === range.end) {
+        return {
+            offsetBytes: range.start,
+            nextOffsetBytes: range.end,
+            totalBytes,
+            truncated: range.truncated,
+            content: '',
+        };
+    }
+    const expanded = expandRange(range.start, range.end, totalBytes, SENSITIVE_BOUNDARY_SCAN_BYTES);
+    const expandedWindow = alignUtf8Window(await readFileRange(file.path, expanded.start, expanded.end), expanded.start);
+    const aligned = alignUtf8Range(expandedWindow.buffer, range.start - expandedWindow.absoluteStart, range.end - expandedWindow.absoluteStart, expandedWindow.absoluteStart);
+    const content = redactPublicChunk(expandedWindow, aligned, totalBytes);
+    return {
+        offsetBytes: aligned.start,
+        nextOffsetBytes: aligned.end,
+        totalBytes,
+        truncated: bounds.mode === 'tail' ? aligned.start > 0 : aligned.end < totalBytes,
+        content,
+    };
+}
+async function readSyntheticChunk(segments, bounds) {
+    const totalBytes = segments.reduce((sum, segment) => sum + segment.size, 0);
+    const range = rangeForBounds(totalBytes, bounds);
+    if (range.start === range.end) {
+        return {
+            offsetBytes: range.start,
+            nextOffsetBytes: range.end,
+            totalBytes,
+            truncated: range.truncated,
+            content: '',
+        };
+    }
+    const expanded = expandRange(range.start, range.end, totalBytes, SENSITIVE_BOUNDARY_SCAN_BYTES);
+    const expandedWindow = alignUtf8Window(await readSyntheticRange(segments, expanded.start, expanded.end), expanded.start);
+    const aligned = alignUtf8Range(expandedWindow.buffer, range.start - expandedWindow.absoluteStart, range.end - expandedWindow.absoluteStart, expandedWindow.absoluteStart);
+    const content = redactPublicChunk(expandedWindow, aligned, totalBytes);
+    return {
+        offsetBytes: aligned.start,
+        nextOffsetBytes: aligned.end,
+        totalBytes,
+        truncated: bounds.mode === 'tail' ? aligned.start > 0 : aligned.end < totalBytes,
+        content,
+    };
+}
+function rangeForBounds(totalBytes, bounds) {
+    if (bounds.mode === 'tail') {
+        const start = Math.max(0, totalBytes - bounds.tailBytes);
+        return { start, end: totalBytes, truncated: start > 0 };
+    }
+    const start = Math.min(bounds.offsetBytes, totalBytes);
+    const end = Math.min(totalBytes, start + bounds.limitBytes);
+    return { start, end, truncated: end < totalBytes };
+}
+function expandRange(start, end, totalBytes, contextBytes) {
+    return {
+        start: Math.max(0, start - contextBytes - UTF8_BOUNDARY_CONTEXT_BYTES),
+        end: Math.min(totalBytes, end + contextBytes + UTF8_BOUNDARY_CONTEXT_BYTES),
+    };
+}
+async function readFileRange(path, start, end) {
+    const length = Math.max(0, end - start);
+    const buffer = Buffer.alloc(length);
+    const handle = await open(path, constants.O_RDONLY);
+    try {
+        let filled = 0;
+        while (filled < length) {
+            const { bytesRead } = await handle.read(buffer, filled, length - filled, start + filled);
+            if (bytesRead === 0)
+                break;
+            filled += bytesRead;
+        }
+        return filled === length ? buffer : buffer.subarray(0, filled);
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readSyntheticRange(segments, start, end) {
+    const chunks = [];
+    let cursor = 0;
+    for (const segment of segments) {
+        const segmentStart = cursor;
+        const segmentEnd = cursor + segment.size;
+        cursor = segmentEnd;
+        if (end <= segmentStart || start >= segmentEnd)
+            continue;
+        const localStart = Math.max(0, start - segmentStart);
+        const localEnd = Math.min(segment.size, end - segmentStart);
+        if (segment.kind === 'buffer') {
+            chunks.push(segment.buffer.subarray(localStart, localEnd));
+        }
+        else if (segment.file.exists) {
+            chunks.push(await readFileRange(segment.file.path, localStart, localEnd));
+        }
+    }
+    return Buffer.concat(chunks);
+}
+function alignUtf8Range(buffer, requestedStartIndex, requestedEndIndex, absoluteBufferStart) {
+    let startIndex = Math.max(0, requestedStartIndex);
+    while (startIndex < buffer.length && isUtf8ContinuationByte(buffer[startIndex]))
+        startIndex += 1;
+    let endIndex = Math.min(buffer.length, requestedEndIndex);
+    while (endIndex > startIndex && endIndex < buffer.length && isUtf8ContinuationByte(buffer[endIndex]))
+        endIndex -= 1;
+    if (endIndex < startIndex)
+        endIndex = startIndex;
+    return {
+        startIndex,
+        endIndex,
+        start: absoluteBufferStart + startIndex,
+        end: absoluteBufferStart + endIndex,
+    };
+}
+function isUtf8ContinuationByte(value) {
+    return value !== undefined && (value & 0b1100_0000) === 0b1000_0000;
+}
+function decodeUtf8(buffer) {
+    try {
+        return UTF8_DECODER.decode(buffer);
+    }
+    catch {
+        throw validationFailure('log content is not valid UTF-8');
+    }
+}
+function redactPublicChunk(expandedWindow, aligned, totalBytes) {
+    const expandedText = decodeUtf8(expandedWindow.buffer);
+    const absoluteBufferStart = expandedWindow.absoluteStart;
+    const absoluteBufferEnd = expandedWindow.absoluteStart + expandedWindow.buffer.byteLength;
+    const sensitiveSpans = findSensitiveSpans(expandedText, absoluteBufferStart, absoluteBufferEnd, totalBytes, aligned.start, aligned.end);
+    const requestedStart = aligned.start;
+    const requestedEnd = aligned.end;
+    let cursor = requestedStart;
+    let content = '';
+    for (const span of sensitiveSpans) {
+        if (span.end <= cursor || span.start >= requestedEnd)
+            continue;
+        const safeEnd = Math.min(span.start, requestedEnd);
+        if (cursor < safeEnd) {
+            content += decodeUtf8(expandedWindow.buffer.subarray(cursor - absoluteBufferStart, safeEnd - absoluteBufferStart));
+        }
+        content += span.replacement;
+        cursor = Math.min(Math.max(cursor, span.end), requestedEnd);
+    }
+    if (cursor < requestedEnd) {
+        content += decodeUtf8(expandedWindow.buffer.subarray(cursor - absoluteBufferStart, requestedEnd - absoluteBufferStart));
+    }
+    return redactPublicText(content);
+}
+function alignUtf8Window(buffer, absoluteStart) {
+    let startIndex = 0;
+    while (startIndex < buffer.length && isUtf8ContinuationByte(buffer[startIndex]))
+        startIndex += 1;
+    for (let endIndex = buffer.length; endIndex >= startIndex; endIndex -= 1) {
+        const candidate = buffer.subarray(startIndex, endIndex);
+        try {
+            UTF8_DECODER.decode(candidate);
+            return {
+                buffer: candidate,
+                absoluteStart: absoluteStart + startIndex,
+            };
+        }
+        catch {
+            if (buffer.length - endIndex > UTF8_BOUNDARY_CONTEXT_BYTES)
+                break;
+        }
+    }
+    throw validationFailure('log content is not valid UTF-8');
+}
+function findSensitiveSpans(text, absoluteBufferStart, absoluteBufferEnd, totalBytes, requestedStart, requestedEnd) {
+    return [
+        ...findPatternSpans(text, TOKEN_PATTERN, '[REDACTED]', absoluteBufferStart),
+        ...findPatternSpans(text, WINDOWS_PATH_PATTERN, '[REDACTED_PATH]', absoluteBufferStart),
+        ...findPatternSpans(text, POSIX_PATH_PATTERN, '[REDACTED_PATH]', absoluteBufferStart),
+        ...findUnprovenSensitiveSpans(text, absoluteBufferStart, absoluteBufferEnd, totalBytes, requestedStart, requestedEnd),
+    ].sort((a, b) => {
+        const diff = a.start - b.start;
+        if (diff !== 0)
+            return diff;
+        return b.end - a.end;
+    });
+}
+function findUnprovenSensitiveSpans(text, absoluteBufferStart, absoluteBufferEnd, totalBytes, requestedStart, requestedEnd) {
+    const spans = [];
+    let runStartIndex;
+    for (let index = 0; index <= text.length; index += 1) {
+        const char = index < text.length ? text[index] : undefined;
+        if (char !== undefined && !isSensitiveDelimiter(char)) {
+            runStartIndex ??= index;
+            continue;
+        }
+        if (runStartIndex === undefined)
+            continue;
+        const runEndIndex = index;
+        const runStart = absoluteBufferStart + Buffer.byteLength(text.slice(0, runStartIndex), 'utf8');
+        const runEnd = absoluteBufferStart + Buffer.byteLength(text.slice(0, runEndIndex), 'utf8');
+        const leftBoundaryProven = runStartIndex > 0 || absoluteBufferStart === 0;
+        const rightBoundaryProven = runEndIndex < text.length || absoluteBufferEnd === totalBytes;
+        if (runEnd > requestedStart &&
+            runStart < requestedEnd &&
+            (!leftBoundaryProven || !rightBoundaryProven)) {
+            spans.push({
+                start: runStart,
+                end: runEnd,
+                replacement: runContainsPathSeparator(text.slice(runStartIndex, runEndIndex))
+                    ? '[REDACTED_PATH]'
+                    : '[REDACTED]',
+            });
+        }
+        runStartIndex = undefined;
+    }
+    return spans;
+}
+function isSensitiveDelimiter(char) {
+    return /\s/.test(char) || '"\'`<>(){}[],;'.includes(char);
+}
+function runContainsPathSeparator(value) {
+    return value.includes('/') || value.includes('\\');
+}
+function findPatternSpans(text, pattern, replacement, absoluteBufferStart) {
+    const spans = [];
+    pattern.lastIndex = 0;
+    for (const match of text.matchAll(pattern)) {
+        const matchText = match[0];
+        if (match.index === undefined || matchText.length === 0)
+            continue;
+        const start = absoluteBufferStart + Buffer.byteLength(text.slice(0, match.index), 'utf8');
+        const end = start + Buffer.byteLength(matchText, 'utf8');
+        spans.push({ start, end, replacement });
+    }
+    return spans;
+}
+function bufferSegment(value) {
+    const buffer = Buffer.from(value, 'utf8');
+    return { kind: 'buffer', buffer, size: buffer.byteLength };
+}
+function assertInsideRoot(candidateRealPath, realRoot) {
+    const rel = relative(realRoot, candidateRealPath);
+    if (rel === '..' || rel.startsWith('../') || rel.startsWith('..\\') || isAbsolute(rel) || win32.isAbsolute(rel)) {
+        throw validationFailure('artifact path escapes the artifact root');
+    }
+}
+function emptyChunk(runId, attemptId, stream) {
+    return {
+        runId,
+        attemptId,
+        stream,
+        offsetBytes: 0,
+        totalBytes: 0,
+        truncated: false,
+        content: '',
+    };
+}
+function stringValue(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function numberOrNull(value) {
+    if (value === null)
+        return null;
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function booleanValue(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
+function parseDate(value) {
+    if (!value)
+        return undefined;
+    const time = Date.parse(value);
+    return Number.isNaN(time) ? undefined : time;
+}
+function compareOptionalTimeAsc(left, right) {
+    if (left !== undefined && right !== undefined)
+        return left - right;
+    if (left === undefined && right !== undefined)
+        return -1;
+    if (left !== undefined && right === undefined)
+        return 1;
+    return 0;
+}
+function redactPublicText(text) {
+    return redactTokens(text)
+        .replace(/\b[A-Za-z]:\\[^\s'"`]+/g, '[REDACTED_PATH]')
+        .replace(/(^|[\s"'`=:(])\/(?:Users|private|tmp|var|opt|home|workspace|Volumes)\/[^\s"'`)]+/g, '$1[REDACTED_PATH]');
+}
+function validationFailure(message) {
+    return new AgentObservabilityError('VALIDATION_FAILURE', message);
+}
+function isNotFound(error) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+}
+//# sourceMappingURL=agent-observability.service.js.map