@faithfulalabi/agent-lens 0.1.0

package/dist/src/project/tools.js

@@ -0,0 +1,94 @@
+import { claimsPersistedOutput, } from '../transcript/agents.js';
+import { epochMs } from './pipeline.js';
+export const INLINE_MAX = 65536;
+export const PREVIEW_MAX = 8192;
+export const NO_INPUT = Object.freeze({
+    input: undefined,
+    input_bytes: undefined,
+    input_storage: undefined,
+});
+function byteLength(text) {
+    return Buffer.byteLength(text, 'utf8');
+}
+function headPreview(text) {
+    const bytes = Buffer.from(text, 'utf8');
+    if (bytes.byteLength <= PREVIEW_MAX)
+        return text;
+    let cut = PREVIEW_MAX;
+    while (cut > 0 && (bytes[cut] & 0xc0) === 0x80)
+        cut -= 1;
+    return bytes.subarray(0, cut).toString('utf8');
+}
+export function toolInput(input) {
+    if (input === undefined) {
+        return { input: undefined, input_bytes: undefined, input_storage: 'absent' };
+    }
+    const text = JSON.stringify(input);
+    const bytes = byteLength(text);
+    return bytes > INLINE_MAX
+        ? { input: headPreview(text), input_bytes: bytes, input_storage: 'line_ref' }
+        : { input: text, input_bytes: bytes, input_storage: 'inline' };
+}
+function elapsedMs(call, result) {
+    const ms = epochMs(result) - epochMs(call);
+    return ms < 0 ? 0 : ms;
+}
+function statusOf(result) {
+    if (result.denial !== undefined)
+        return 'denied';
+    return result.is_error ? 'error' : 'ok';
+}
+function storeOutput(event, text) {
+    const bytes = byteLength(text);
+    event.text_bytes = bytes;
+    if (claimsPersistedOutput(text)) {
+        event.output_storage = 'spill';
+        event.text = undefined;
+        return;
+    }
+    if (bytes > INLINE_MAX) {
+        event.output_storage = 'line_ref';
+        event.text = headPreview(text);
+        return;
+    }
+    event.output_storage = 'inline';
+    event.text = text;
+}
+function backPatch(event, notification) {
+    const payload = notification?.result;
+    if (payload === undefined) {
+        event.text = undefined;
+        event.text_bytes = undefined;
+        event.output_storage = 'absent';
+        event.status = 'running';
+        event.agent_status = 'running';
+        return;
+    }
+    event.text = payload;
+    event.text_bytes = byteLength(payload);
+    event.output_storage = 'inline';
+    event.agent_status = notification?.status;
+}
+export function joinToolCalls(events, results, notifications, drift) {
+    const answers = new Map(notifications.flatMap((entry) => entry.toolCallId === undefined ? [] : [[entry.toolCallId, entry]]));
+    for (const event of events) {
+        if (event.kind !== 'tool_call')
+            continue;
+        const result = results.get(event.id);
+        if (result === undefined) {
+            drift.noteUnjoinedToolUse();
+            continue;
+        }
+        event.result_offset = result.result_offset;
+        event.result_len = result.result_len;
+        event.result_block = result.result_block;
+        event.duration_ms = elapsedMs(event.ts, result.ts);
+        event.duration_source = 'elapsed';
+        event.status = statusOf(result);
+        if (event.name === 'Agent' && result.launch !== undefined) {
+            backPatch(event, answers.get(event.id));
+            continue;
+        }
+        storeOutput(event, result.text);
+    }
+}

package/dist/src/server/api.js

@@ -0,0 +1,249 @@
+import { streamSSE } from 'hono/streaming';
+import { ensureProjectedFold, fingerprint } from '../db/freshness.js';
+import { countUnprojected, readDriftRows, readEventContentRow, readEventCount, readEventPage, readHealthCounts, readMeta, readProjects, readSessionHeader, readSessionList, readTurns, searchEvents, } from '../db/read.js';
+import { deleteSessionProjection, projectSession } from '../db/write.js';
+import { aggregateDrift } from './drift-report.js';
+export { aggregateDrift } from './drift-report.js';
+export const DEFAULT_LIMIT = 50;
+export const EVENT_PAGE_LIMIT = 1000;
+export const MAX_LIMIT = 10_000;
+const NON_NEGATIVE_INT = /^\d+$/;
+const RANGE = /^(\d+)-(\d*)$/;
+export function parsePageParams(query, fallbackLimit = DEFAULT_LIMIT) {
+    let limit = fallbackLimit;
+    const rawLimit = query.limit;
+    if (rawLimit !== undefined && rawLimit !== '') {
+        if (!NON_NEGATIVE_INT.test(rawLimit))
+            return { ok: false, error: 'invalid limit' };
+        const parsed = Number(rawLimit);
+        if (parsed === 0)
+            return { ok: false, error: 'invalid limit' };
+        limit = Math.min(parsed, MAX_LIMIT);
+    }
+    let offset = 0;
+    const rawOffset = query.offset;
+    if (rawOffset !== undefined && rawOffset !== '') {
+        if (!NON_NEGATIVE_INT.test(rawOffset))
+            return { ok: false, error: 'invalid offset' };
+        offset = Number(rawOffset);
+        if (!Number.isSafeInteger(offset))
+            return { ok: false, error: 'invalid offset' };
+    }
+    return { ok: true, value: { limit, offset } };
+}
+export function parseFromSeq(raw) {
+    if (raw === undefined || raw === '')
+        return { ok: true, value: 0 };
+    if (!NON_NEGATIVE_INT.test(raw))
+        return { ok: false, error: 'invalid from_seq' };
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value))
+        return { ok: false, error: 'invalid from_seq' };
+    return { ok: true, value };
+}
+const SORTS = ['recent', 'cost', 'tokens', 'errors'];
+export function parseSort(raw) {
+    if (raw === undefined || raw === '')
+        return { ok: true, value: 'recent' };
+    const sort = SORTS.find((known) => known === raw);
+    return sort === undefined ? { ok: false, error: 'invalid sort' } : { ok: true, value: sort };
+}
+const FIELDS = ['text', 'input'];
+export function parseField(raw) {
+    if (raw === undefined || raw === '')
+        return { ok: true, value: 'text' };
+    const field = FIELDS.find((known) => known === raw);
+    return field === undefined ? { ok: false, error: 'invalid field' } : { ok: true, value: field };
+}
+export function parseRange(raw) {
+    if (raw === undefined || raw === '')
+        return { ok: true, value: undefined };
+    const match = RANGE.exec(raw);
+    if (match === null)
+        return { ok: false, error: 'invalid range' };
+    const start = Number(match[1]);
+    if (!Number.isSafeInteger(start))
+        return { ok: false, error: 'invalid range' };
+    if (match[2] === '')
+        return { ok: true, value: { start } };
+    const end = Number(match[2]);
+    if (!Number.isSafeInteger(end))
+        return { ok: false, error: 'invalid range' };
+    if (end < start)
+        return { ok: false, error: 'invalid range' };
+    return { ok: true, value: { start, end } };
+}
+export function clampRange(range, byteSize) {
+    const start = Math.min(range?.start ?? 0, byteSize);
+    const requestedEnd = range?.end ?? byteSize - 1;
+    const end = Math.max(start - 1, Math.min(requestedEnd, byteSize - 1));
+    return { start, end, length: end - start + 1 };
+}
+export function parseSearchQuery(query) {
+    const q = query.q;
+    if (q === undefined || q === '' || q.includes('\0'))
+        return { ok: false, error: 'invalid q' };
+    const page = parsePageParams(query);
+    if (!page.ok)
+        return page;
+    const value = { q, limit: page.value.limit };
+    if (query.session !== undefined && query.session !== '')
+        value.session = query.session;
+    return { ok: true, value };
+}
+export const LIVE_WINDOW_MS = 60_000;
+export function isLive(last_activity_at, now) {
+    const at = Date.parse(last_activity_at);
+    return !Number.isNaN(at) && now - at < LIVE_WINDOW_MS;
+}
+const PROJECTION_STATES = ['none', 'ready', 'failed', 'empty'];
+const ARCHIVE_UNREADABLE = 'archive unreadable: the projection could not be verified';
+export function toDetailProjection(header, outcome) {
+    const stored = header.projection;
+    if (outcome === 'failed') {
+        return { ...stored, state: 'failed', error: stored.error ?? ARCHIVE_UNREADABLE };
+    }
+    return PROJECTION_STATES.includes(stored.state) ? stored : { ...stored, state: 'none' };
+}
+function storedContent(row, field) {
+    const isText = field === 'text';
+    const resolved = {
+        storage: (isText ? row.output_storage : row.input_storage) ?? 'absent',
+        content: (isText ? row.text : row.input) ?? '',
+        byte_size: (isText ? row.text_bytes : row.input_bytes) ?? 0,
+    };
+    if (isText && row.spill_path !== null)
+        resolved.spill_path = row.spill_path;
+    return resolved;
+}
+export function jsonNotFound(c) {
+    return c.json({ error: 'not found' }, 404);
+}
+export function registerApi(app, deps) {
+    const { db, env } = deps;
+    app.get('/api/sessions', (c) => {
+        const query = c.req.query();
+        const page = parsePageParams(query);
+        if (!page.ok)
+            return c.json({ error: page.error }, 400);
+        const sort = parseSort(query.sort);
+        if (!sort.ok)
+            return c.json({ error: sort.error }, 400);
+        const filter = { ...page.value, sort: sort.value };
+        if (query.project !== undefined && query.project !== '')
+            filter.project = query.project;
+        if (query.q !== undefined && query.q !== '')
+            filter.q = query.q;
+        const listed = readSessionList(db, filter);
+        const now = Date.now();
+        return c.json({
+            ...listed,
+            items: listed.items.map((row) => ({ ...row, live: isLive(row.last_activity_at, now) })),
+        });
+    });
+    app.get('/api/projects', (c) => c.json(readProjects(db)));
+    app.get('/api/sessions/:id', (c) => {
+        const query = c.req.query();
+        const page = parsePageParams(query, EVENT_PAGE_LIMIT);
+        if (!page.ok)
+            return c.json({ error: page.error }, 400);
+        const from_seq = parseFromSeq(query.from_seq);
+        if (!from_seq.ok)
+            return c.json({ error: from_seq.error }, 400);
+        const id = c.req.param('id');
+        const gate = ensureProjectedFold(db, id, env);
+        if (gate.outcome === 'unindexed')
+            return jsonNotFound(c);
+        const header = readSessionHeader(db, id);
+        if (header === undefined)
+            return jsonNotFound(c);
+        const events = readEventPage(db, id, { from_seq: from_seq.value, limit: page.value.limit });
+        return c.json({
+            session: {
+                ...header,
+                live: isLive(header.last_activity_at, Date.now()),
+                projection: toDetailProjection(header, gate.outcome),
+            },
+            turns: readTurns(db, id),
+            events: events.items,
+            next_seq: events.next_seq,
+            has_more: events.has_more,
+            fingerprint: gate.fold === undefined ? '' : fingerprint(gate.fold),
+        });
+    });
+    app.get('/api/events/:id/content', (c) => {
+        const field = parseField(c.req.query('field'));
+        if (!field.ok)
+            return c.json({ error: field.error }, 400);
+        const range = parseRange(c.req.query('range'));
+        if (!range.ok)
+            return c.json({ error: range.error }, 400);
+        const row = readEventContentRow(db, c.req.param('id'));
+        if (row === undefined)
+            return jsonNotFound(c);
+        const stored = storedContent(row, field.value);
+        const resolved = stored.storage === 'inline' || stored.storage === 'absent'
+            ? stored
+            : (deps.resolveContent?.(row, field.value) ?? { ...stored, storage: 'missing' });
+        const bytes = Buffer.from(resolved.content, 'utf8');
+        const clamped = clampRange(range.value, bytes.length);
+        const body = {
+            id: row.id,
+            field: field.value,
+            storage: resolved.storage,
+            byte_size: resolved.byte_size,
+            range: { start: clamped.start, end: clamped.end },
+            content: bytes.subarray(clamped.start, clamped.start + clamped.length).toString('utf8'),
+            truncated: clamped.length < resolved.byte_size,
+        };
+        if (resolved.spill_path !== undefined)
+            body.spill_path = resolved.spill_path;
+        return c.json(body);
+    });
+    app.get('/api/search', (c) => {
+        const parsed = parseSearchQuery(c.req.query());
+        if (!parsed.ok)
+            return c.json({ error: parsed.error }, 400);
+        return c.json({
+            items: searchEvents(db, parsed.value),
+            scope: parsed.value.session === undefined ? 'projected' : 'session',
+            unprojected_count: countUnprojected(db),
+        });
+    });
+    app.get('/api/stream', (c) => streamSSE(c, (stream) => deps.hub.attach(stream)));
+    app.post('/api/sessions/:id/reproject', (c) => {
+        const id = c.req.param('id');
+        const started = Date.now();
+        const gate = ensureProjectedFold(db, id, env);
+        if (gate.outcome === 'unindexed')
+            return jsonNotFound(c);
+        if (gate.outcome === 'hit' && gate.fold !== undefined) {
+            deleteSessionProjection(db, id);
+            projectSession(db, id, env, gate.fold);
+        }
+        const header = readSessionHeader(db, id);
+        if (header === undefined)
+            return jsonNotFound(c);
+        return c.json({
+            session: { ...header, live: isLive(header.last_activity_at, Date.now()) },
+            event_count: readEventCount(db, id),
+            turn_count: header.turn_count,
+            took_ms: Date.now() - started,
+        });
+    });
+    app.post('/api/warm', (c) => c.json({ queued: deps.warm.start() }, 202));
+    app.get('/api/drift', (c) => c.json({
+        projector_version: readMeta(db, 'projector_version') ?? null,
+        schema_version: readMeta(db, 'schema_version') ?? null,
+        ...aggregateDrift(readDriftRows(db)),
+    }));
+    app.get('/api/health', (c) => c.json({
+        ok: true,
+        projects_root: readMeta(db, 'projects_root') ?? null,
+        index_built_at: readMeta(db, 'index_built_at') ?? null,
+        files_indexed: deps.sweep?.report().walked ?? null,
+        ...readHealthCounts(db),
+        schema_version: readMeta(db, 'schema_version') ?? null,
+        projector_version: readMeta(db, 'projector_version') ?? null,
+    }));
+}

package/dist/src/server/app.js

@@ -0,0 +1,28 @@
+import { Hono } from 'hono';
+import { hostGuard, resolveBindHosts } from './middleware/host-guard.js';
+import { tokenAuth } from './middleware/token-auth.js';
+import { jsonNotFound as apiNotFound, registerApi } from './api.js';
+import { makeServeIndex, registerUi } from './static-ui.js';
+const jsonErrorOnApiPaths = (err, c) => {
+    if ('getResponse' in err) {
+        const res = err.getResponse();
+        return c.newResponse(res.body, res);
+    }
+    console.error(err);
+    if (c.req.path.startsWith('/api/')) {
+        return c.json({ error: 'internal error' }, 500);
+    }
+    return c.text('Internal Server Error', 500);
+};
+export function buildApiApp(deps) {
+    const { token, host, uiDir } = deps;
+    const app = new Hono();
+    app.use('*', hostGuard(host === undefined ? [] : resolveBindHosts(host)));
+    app.get('/', makeServeIndex({ token, uiDir }));
+    app.use('/api/*', tokenAuth(token));
+    registerApi(app, deps);
+    app.all('/api/*', apiNotFound);
+    registerUi(app, { token, uiDir });
+    app.onError(jsonErrorOnApiPaths);
+    return app;
+}

package/dist/src/server/config.js

@@ -0,0 +1,24 @@
+import { chmodSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+const CONFIG_FILE = 'config.json';
+export function writeConfig(dataDir, config) {
+    const target = join(dataDir, CONFIG_FILE);
+    const temp = join(dataDir, `${CONFIG_FILE}.tmp.${process.pid}`);
+    writeFileSync(temp, JSON.stringify(config, null, 2), { mode: 0o600 });
+    chmodSync(temp, 0o600);
+    renameSync(temp, target);
+}
+export function readConfig(dataDir) {
+    try {
+        return JSON.parse(readFileSync(join(dataDir, CONFIG_FILE), 'utf8'));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return null;
+        }
+        throw err;
+    }
+}
+export function clearConfig(dataDir) {
+    rmSync(join(dataDir, CONFIG_FILE), { force: true });
+}

package/dist/src/server/drift-report.js

@@ -0,0 +1,35 @@
+const NO_DRIFT = '{}';
+function mergeBucket(into, from) {
+    for (const [key, n] of Object.entries(from ?? {}))
+        into[key] = (into[key] ?? 0) + n;
+}
+export function aggregateDrift(rows) {
+    const report = {
+        harness_versions: {},
+        unknown_line_types: {},
+        unknown_block_types: {},
+        unknown_top_level_fields: {},
+        unjoined_tool_uses: 0,
+        unresolved_spills: 0,
+        sessions_with_drift: [],
+    };
+    for (const row of rows) {
+        const version = row.harness_version ?? 'unknown';
+        report.harness_versions[version] = (report.harness_versions[version] ?? 0) + 1;
+        if (row.drift_json === NO_DRIFT)
+            continue;
+        const counts = JSON.parse(row.drift_json);
+        mergeBucket(report.unknown_line_types, counts.unknown_line_types);
+        mergeBucket(report.unknown_block_types, counts.unknown_block_types);
+        mergeBucket(report.unknown_top_level_fields, counts.unknown_top_level_fields);
+        report.unjoined_tool_uses += counts.unjoined_tool_uses ?? 0;
+        report.unresolved_spills += counts.unresolved_spills ?? 0;
+        report.sessions_with_drift.push({
+            id: row.id,
+            title: row.title,
+            harness_version: row.harness_version,
+            counts,
+        });
+    }
+    return report;
+}

package/dist/src/server/index.js

@@ -0,0 +1 @@
+export { startServer } from './start.js';

package/dist/src/server/live.js

@@ -0,0 +1,109 @@
+import { ensureProjectedFold, fingerprint } from '../db/freshness.js';
+import { readEventsByIds, readRunningEventIds, readSessionHeader, readTurns, } from '../db/read.js';
+const INTERVAL_MS = 1000;
+const SLOW_MS = 100;
+const SLOW_INTERVAL_MS = 5000;
+const DEADLINE_MS = 250;
+function ownRollups(header) {
+    return {
+        last_activity_at: header.last_activity_at,
+        turn_count: header.turn_count,
+        tool_call_count: header.tool_call_count,
+        error_count: header.error_count,
+        tokens_in: header.tokens_in,
+        tokens_out: header.tokens_out,
+        tokens_cache_read: header.tokens_cache_read,
+        tokens_cache_write: header.tokens_cache_write,
+        est_cost: header.est_cost,
+    };
+}
+export function startLiveTick(options) {
+    const { db, env, sweep, hub } = options;
+    const now = options.now ?? Date.now;
+    const intervalMs = options.intervalMs ?? INTERVAL_MS;
+    const backoffAt = new Map();
+    const pending = new Set();
+    const announced = new Set();
+    const tick = async () => {
+        const startedAt = now();
+        const report = sweep.wave1();
+        for (const id of report.indexed_ids) {
+            if (announced.has(id))
+                continue;
+            announced.add(id);
+            const frame = { session_id: id };
+            await hub.publish('session_indexed', frame);
+        }
+        const candidates = [...pending, ...report.indexed_ids.filter((id) => !pending.has(id))];
+        let visited = 0;
+        for (const id of candidates) {
+            if ((backoffAt.get(id) ?? 0) > now()) {
+                pending.add(id);
+                continue;
+            }
+            if (visited > 0 && now() - startedAt >= DEADLINE_MS) {
+                pending.add(id);
+                continue;
+            }
+            visited += 1;
+            const before = new Set(readRunningEventIds(db, id));
+            const startedProjection = now();
+            const gate = ensureProjectedFold(db, id, env);
+            if (now() - startedProjection > SLOW_MS)
+                backoffAt.set(id, now() + SLOW_INTERVAL_MS);
+            if (gate.outcome === 'failed') {
+                pending.add(id);
+                continue;
+            }
+            if (gate.outcome !== 'projected' || gate.fold === undefined) {
+                pending.delete(id);
+                continue;
+            }
+            pending.delete(id);
+            const header = readSessionHeader(db, id);
+            if (header === undefined)
+                continue;
+            const after = new Set(readRunningEventIds(db, id));
+            const stopped = [...before].filter((eventId) => !after.has(eventId));
+            const turns = readTurns(db, id);
+            const last = turns[turns.length - 1];
+            const frame = {
+                session_id: id,
+                fingerprint: fingerprint(gate.fold),
+                from_seq: last === undefined ? 0 : last.first_seq,
+                patched: readEventsByIds(db, id, stopped),
+                rollups: ownRollups(header),
+            };
+            await hub.publish('session_changed', frame);
+        }
+        sweep.wave2();
+    };
+    let inFlight = false;
+    const fire = async () => {
+        if (inFlight)
+            return;
+        inFlight = true;
+        try {
+            await tick();
+        }
+        catch (error) {
+            console.error(error);
+        }
+        finally {
+            inFlight = false;
+        }
+    };
+    let timer;
+    if (intervalMs !== 0) {
+        timer = setInterval(() => void fire(), intervalMs);
+        timer.unref?.();
+    }
+    return {
+        tick,
+        close: () => {
+            if (timer !== undefined)
+                clearInterval(timer);
+            timer = undefined;
+        },
+    };
+}

package/dist/src/server/middleware/host-guard.js

@@ -0,0 +1,42 @@
+import { networkInterfaces } from 'node:os';
+const ALLOWED_HOSTNAMES = new Set([
+    'localhost',
+    '127.0.0.1',
+    '[::1]',
+    '::1',
+]);
+function isLoopbackBind(host) {
+    return ALLOWED_HOSTNAMES.has(host);
+}
+export function resolveBindHosts(host) {
+    if (isLoopbackBind(host)) {
+        return [];
+    }
+    const hosts = [];
+    for (const addrs of Object.values(networkInterfaces())) {
+        for (const addr of addrs ?? []) {
+            if (addr.internal)
+                continue;
+            hosts.push(addr.family === 'IPv6' ? `[${addr.address}]` : addr.address);
+        }
+    }
+    return hosts;
+}
+function hostnameOf(host) {
+    if (host.startsWith('[')) {
+        const end = host.indexOf(']');
+        return end === -1 ? host : host.slice(0, end + 1);
+    }
+    const colon = host.indexOf(':');
+    return colon === -1 ? host : host.slice(0, colon);
+}
+export function hostGuard(extraHosts = []) {
+    const allowed = new Set([...ALLOWED_HOSTNAMES, ...extraHosts]);
+    return async (c, next) => {
+        const host = c.req.header('host');
+        if (host === undefined || !allowed.has(hostnameOf(host))) {
+            return c.text('Forbidden', 403);
+        }
+        return next();
+    };
+}

package/dist/src/server/middleware/token-auth.js

@@ -0,0 +1,19 @@
+import { timingSafeEqual } from 'node:crypto';
+import { TOKEN_HEADER } from '../../shared/index.js';
+function safeEqual(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    if (ab.length !== bb.length) {
+        return false;
+    }
+    return timingSafeEqual(ab, bb);
+}
+export function tokenAuth(expected) {
+    return async (c, next) => {
+        const provided = c.req.header(TOKEN_HEADER);
+        if (provided === undefined || !safeEqual(provided, expected)) {
+            return c.text('Unauthorized', 401);
+        }
+        return next();
+    };
+}