@faithfulalabi/agent-lens 0.1.0

package/dist/src/transcript/human.js

@@ -0,0 +1,65 @@
+import { obj, str } from './accessors.js';
+import { contentBlocks } from './blocks.js';
+export const MACHINERY_TAGS = [
+    '<task-notification>',
+    '<command-message>',
+    '<local-command-caveat>',
+    '<command-name>',
+    '<local-command-stdout>',
+    '<command-args>',
+    '<local-command-stderr>',
+    '<system-reminder>',
+    '<user-prompt-submit-hook>',
+    '<bash-input>',
+    '<bash-stdout>',
+];
+export const MACHINERY_PREFIXES = [
+    '[Request interrupted',
+    'Caveat: The messages below',
+    'This session is being continued',
+    'API Error',
+];
+const LEADING_TAG = /^<[a-z][a-z0-9-]*>/;
+function promptText(line) {
+    return contentBlocks(line)
+        .flatMap((block) => (block.kind === 'text' ? [block.text] : []))
+        .join('\n')
+        .trim();
+}
+function startsWithMachineryTag(text) {
+    return MACHINERY_TAGS.some((tag) => text.startsWith(tag)) || LEADING_TAG.test(text);
+}
+function fallbackRejection(line) {
+    if (line.kind !== 'user')
+        return 'not-a-user-line';
+    if (line.raw.isSidechain === true)
+        return 'sidechain';
+    if (line.raw.isMeta === true)
+        return 'meta';
+    if (line.raw.isCompactSummary === true)
+        return 'compact-summary';
+    const text = promptText(line);
+    if (text === '')
+        return 'no-text';
+    if (startsWithMachineryTag(text))
+        return 'machinery-tag';
+    const prefix = MACHINERY_PREFIXES.find((opener) => text.startsWith(opener));
+    return prefix === undefined ? '' : `machinery-prefix:${prefix}`;
+}
+export function fallbackIsHuman(line) {
+    return fallbackRejection(line) === '';
+}
+export function isHumanPrompt(line) {
+    if (line.kind !== 'user')
+        return { human: false, path: 'kind', reason: 'not-a-user-line' };
+    const originKind = str(obj(line.raw.origin, undefined)?.kind, undefined);
+    if (originKind !== undefined) {
+        return { human: originKind === 'human', path: 'origin', reason: `origin:${originKind}` };
+    }
+    const rejection = fallbackRejection(line);
+    return {
+        human: rejection === '',
+        path: 'fallback',
+        reason: rejection === '' ? 'prose' : rejection,
+    };
+}

package/dist/src/transcript/line.js

@@ -0,0 +1,251 @@
+import { isoTs, num, obj, str } from './accessors.js';
+const SYSTEM_SUBTYPES = [
+    'turn_duration',
+    'stop_hook_summary',
+    'away_summary',
+    'local_command',
+    'compact_boundary',
+    'informational',
+    'api_error',
+];
+const SYSTEM_SUBTYPE_SET = new Set(SYSTEM_SUBTYPES);
+function isSystemSubtype(value) {
+    return SYSTEM_SUBTYPE_SET.has(value);
+}
+const ENVELOPE = [
+    'type',
+    'uuid',
+    'parentUuid',
+    'sessionId',
+    'session_id',
+    'timestamp',
+    'version',
+    'userType',
+    'isSidechain',
+    'isMeta',
+    'agentId',
+    'cwd',
+    'gitBranch',
+    'slug',
+    'entrypoint',
+];
+function fields(...groups) {
+    return new Set(groups.flat());
+}
+const LINE_TYPES = new Map([
+    [
+        'assistant',
+        {
+            kind: 'assistant',
+            knownFields: fields(ENVELOPE, [
+                'message',
+                'requestId',
+                'effort',
+                'attributionAgent',
+                'attributionSkill',
+                'attributionPlugin',
+                'isApiErrorMessage',
+                'error',
+            ]),
+        },
+    ],
+    [
+        'user',
+        {
+            kind: 'user',
+            knownFields: fields(ENVELOPE, [
+                'message',
+                'origin',
+                'toolUseResult',
+                'sourceToolAssistantUUID',
+                'sourceToolUseID',
+                'promptId',
+                'promptSource',
+                'permissionMode',
+                'isCompactSummary',
+                'isVisibleInTranscriptOnly',
+                'classifierMetaLines',
+                'toolEndsTurn',
+                'toolDenialKind',
+                'imagePasteIds',
+            ]),
+        },
+    ],
+    [
+        'system',
+        {
+            kind: 'system',
+            knownFields: fields(ENVELOPE, [
+                'subtype',
+                'content',
+                'level',
+                'durationMs',
+                'messageCount',
+                'stopReason',
+                'preventedContinuation',
+                'compactMetadata',
+                'logicalParentUuid',
+                'toolUseID',
+                'hasOutput',
+                'hookCount',
+                'hookErrors',
+                'hookInfos',
+                'hookAdditionalContext',
+                'pendingBackgroundAgentCount',
+                'pendingWorkflowCount',
+            ]),
+        },
+    ],
+    ['attachment', { kind: 'attachment', knownFields: fields(ENVELOPE, ['attachment']) }],
+    ['mode', { kind: 'mode', knownFields: fields(['type', 'mode', 'sessionId']) }],
+    [
+        'last-prompt',
+        {
+            kind: 'last-prompt',
+            knownFields: fields(['type', 'lastPrompt', 'leafUuid', 'sessionId']),
+        },
+    ],
+    [
+        'permission-mode',
+        {
+            kind: 'permission-mode',
+            knownFields: fields(['type', 'permissionMode', 'sessionId']),
+        },
+    ],
+    ['ai-title', { kind: 'ai-title', knownFields: fields(['type', 'aiTitle', 'sessionId']) }],
+    [
+        'file-history-snapshot',
+        {
+            kind: 'file-history-snapshot',
+            knownFields: fields(['type', 'messageId', 'snapshot', 'isSnapshotUpdate']),
+        },
+    ],
+    [
+        'file-history-delta',
+        {
+            kind: 'file-history-delta',
+            knownFields: fields([
+                'type',
+                'messageId',
+                'snapshotMessageId',
+                'trackingPath',
+                'backup',
+                'timestamp',
+            ]),
+        },
+    ],
+    [
+        'queue-operation',
+        {
+            kind: 'queue-operation',
+            knownFields: fields(['type', 'operation', 'content', 'timestamp', 'sessionId']),
+        },
+    ],
+    [
+        'pr-link',
+        {
+            kind: 'pr-link',
+            knownFields: fields(['type', 'sessionId', 'prNumber', 'prUrl', 'prRepository', 'timestamp']),
+        },
+    ],
+    ['started', { kind: 'started', knownFields: fields(['type', 'key', 'agentId']) }],
+    ['result', { kind: 'result', knownFields: fields(['type', 'key', 'agentId', 'result']) }],
+]);
+const EMPTY_RECORD = Object.freeze({});
+function rawTypeKey(value) {
+    if (typeof value === 'string')
+        return value;
+    return value === null ? '<null>' : `<${typeof value}>`;
+}
+export function classifyLine(json, ctx) {
+    const raw = obj(json, EMPTY_RECORD);
+    const base = {
+        byte_offset: ctx.byteOffset,
+        byte_length: ctx.byteLength,
+        uuid: str(raw.uuid, undefined),
+        session_id: str(raw.sessionId, undefined),
+        timestamp: isoTs(raw.timestamp, undefined),
+        raw,
+    };
+    const entry = LINE_TYPES.get(str(raw.type, ''));
+    if (entry === undefined) {
+        const raw_type = rawTypeKey(raw.type);
+        ctx.drift.noteUnknownType(raw_type);
+        return { ...base, kind: 'unknown', raw_type, raw_subtype: str(raw.subtype, '') };
+    }
+    ctx.drift.noteLine(raw, entry.knownFields);
+    if (entry.kind === 'system') {
+        const subtype = str(raw.subtype, '');
+        if (!isSystemSubtype(subtype)) {
+            ctx.drift.noteUnknownType(`system.${subtype}`);
+            return { ...base, kind: 'unknown', raw_type: 'system', raw_subtype: subtype };
+        }
+        return { ...base, kind: 'system', subtype };
+    }
+    return { ...base, kind: entry.kind };
+}
+export function foldControlLines(lines) {
+    const projection = {
+        ai_title: undefined,
+        last_prompt: undefined,
+        last_prompt_leaf_uuid: undefined,
+    };
+    for (const line of lines) {
+        if (line.kind === 'ai-title') {
+            projection.ai_title = str(line.raw.aiTitle, undefined);
+        }
+        else if (line.kind === 'last-prompt') {
+            projection.last_prompt = str(line.raw.lastPrompt, undefined);
+            projection.last_prompt_leaf_uuid = str(line.raw.leafUuid, undefined);
+        }
+    }
+    return projection;
+}
+export function promptGroupId(line) {
+    return str(line.raw.promptId, undefined);
+}
+export function toolDenialKind(line) {
+    return str(line.raw.toolDenialKind, undefined);
+}
+export function turnDurationMs(line) {
+    return line.kind === 'system' && line.subtype === 'turn_duration'
+        ? num(line.raw.durationMs, undefined)
+        : undefined;
+}
+const SYNTHETIC_MODEL = '<synthetic>';
+export function foldSessionEnvelope(lines) {
+    const envelope = {
+        project_path: undefined,
+        git_branch: undefined,
+        harness_version: undefined,
+        model: undefined,
+        started_at: undefined,
+        last_activity_at: undefined,
+    };
+    const linesPerModel = new Map();
+    for (const line of lines) {
+        envelope.project_path = str(line.raw.cwd, envelope.project_path);
+        envelope.git_branch = str(line.raw.gitBranch, envelope.git_branch);
+        envelope.harness_version = str(line.raw.version, envelope.harness_version);
+        const model = str(obj(line.raw.message, undefined)?.model, undefined);
+        if (model !== undefined && model !== SYNTHETIC_MODEL) {
+            linesPerModel.set(model, (linesPerModel.get(model) ?? 0) + 1);
+        }
+        const at = line.timestamp;
+        if (at === undefined)
+            continue;
+        if (envelope.started_at === undefined || at < envelope.started_at)
+            envelope.started_at = at;
+        if (envelope.last_activity_at === undefined || at > envelope.last_activity_at) {
+            envelope.last_activity_at = at;
+        }
+    }
+    let mostLines = 0;
+    for (const [model, count] of linesPerModel) {
+        if (count > mostLines) {
+            envelope.model = model;
+            mostLines = count;
+        }
+    }
+    return envelope;
+}

package/dist/src/transcript/raw-types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/transcript/spill.js

@@ -0,0 +1,122 @@
+import { basename, join } from 'node:path';
+import { num, obj, str } from './accessors.js';
+const PERSISTED_MARKER = '<persisted-output>';
+const SAVED_TO = /Full output saved to: (.+)$/m;
+const SPILL_SUBDIR = 'tool-results';
+export const TRUNCATION_BYTES = 30000;
+function toolResultText(line) {
+    const content = obj(obj(line, undefined)?.message, undefined)?.content;
+    const blocks = Array.isArray(content) ? content : undefined;
+    if (blocks === undefined)
+        return undefined;
+    for (const block of blocks) {
+        const fields = obj(block, undefined);
+        if (str(fields?.type, undefined) !== 'tool_result')
+            continue;
+        const inner = fields?.content;
+        const direct = str(inner, undefined);
+        if (direct !== undefined)
+            return direct;
+        if (!Array.isArray(inner))
+            continue;
+        for (const part of inner) {
+            const text = str(obj(part, undefined)?.text, undefined);
+            if (text !== undefined)
+                return text;
+        }
+    }
+    return undefined;
+}
+function declaredPathOf(line) {
+    const tur = obj(line, undefined)?.toolUseResult;
+    const pointer = str(obj(tur, undefined)?.['persistedOutputPath'], undefined);
+    if (pointer !== undefined) {
+        const size = num(obj(tur, undefined)?.['persistedOutputSize'], undefined);
+        return {
+            path: pointer,
+            source: 'pointer',
+            declaredSize: size !== undefined && Number.isInteger(size) ? size : undefined,
+        };
+    }
+    const text = toolResultText(line);
+    if (text === undefined || !text.startsWith(PERSISTED_MARKER))
+        return undefined;
+    const marked = SAVED_TO.exec(text)?.[1];
+    return marked === undefined ? undefined : { path: marked, source: 'marker' };
+}
+function reanchor(name, env) {
+    if (name === '')
+        return undefined;
+    for (const root of [env.sessionRoot, env.archiveRoot]) {
+        if (root === undefined)
+            continue;
+        const candidate = join(root, SPILL_SUBDIR, name);
+        if (env.exists(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+export function resolvePersistedOutput(line, env) {
+    let declared;
+    try {
+        declared = declaredPathOf(line);
+    }
+    catch {
+        return { kind: 'none' };
+    }
+    if (declared === undefined) {
+        return hasMarker(line) ? { kind: 'missing', reason: 'no-path' } : { kind: 'none' };
+    }
+    const probe = (path) => {
+        try {
+            return env.exists(path) === true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const resolvedAt = (path) => ({
+        kind: 'resolved',
+        path,
+        source: declared.source,
+        ...(declared.declaredSize !== undefined && { declaredSize: declared.declaredSize }),
+    });
+    const contained = (path) => {
+        if (env.withinRoots === undefined)
+            return true;
+        try {
+            return env.withinRoots(path) === true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (contained(declared.path) && probe(declared.path))
+        return resolvedAt(declared.path);
+    let rescued;
+    try {
+        rescued = reanchor(basename(declared.path), env);
+    }
+    catch {
+        rescued = undefined;
+    }
+    if (rescued !== undefined)
+        return resolvedAt(rescued);
+    return { kind: 'missing', reason: 'not-on-disk', declaredPath: declared.path };
+}
+function hasMarker(line) {
+    try {
+        return toolResultText(line)?.startsWith(PERSISTED_MARKER) === true;
+    }
+    catch {
+        return false;
+    }
+}
+export function isHarnessTruncated(text) {
+    const value = str(text, undefined);
+    if (value === undefined)
+        return false;
+    if (value.startsWith(PERSISTED_MARKER))
+        return true;
+    return Buffer.byteLength(value, 'utf8') >= TRUNCATION_BYTES;
+}

package/dist/src/transcript/usage.js

@@ -0,0 +1,63 @@
+import { num, obj, str } from './accessors.js';
+const ONCE_PER_GROUP = [
+    'input_tokens',
+    'cache_creation_input_tokens',
+    'cache_read_input_tokens',
+];
+const ZERO = {
+    input_tokens: 0,
+    output_tokens: 0,
+    cache_creation_input_tokens: 0,
+    cache_read_input_tokens: 0,
+};
+function usageOf(line) {
+    return obj(obj(obj(line, undefined)?.message, undefined)?.usage, undefined);
+}
+export function requestIdOf(line) {
+    return str(obj(line, undefined)?.requestId, undefined);
+}
+export function foldRequestGroup(lines) {
+    const folded = { ...ZERO };
+    const taken = new Set();
+    for (const line of lines) {
+        const usage = usageOf(line);
+        if (usage === undefined)
+            continue;
+        for (const field of ONCE_PER_GROUP) {
+            if (taken.has(field))
+                continue;
+            const value = num(usage[field], undefined);
+            if (value === undefined)
+                continue;
+            folded[field] = value;
+            taken.add(field);
+        }
+        const output = num(usage['output_tokens'], undefined);
+        if (output !== undefined)
+            folded.output_tokens = output;
+    }
+    return folded;
+}
+export function modelOfRequestGroup(lines) {
+    for (const line of lines) {
+        const model = str(obj(obj(line, undefined)?.message, undefined)?.model, undefined);
+        if (model !== undefined)
+            return model;
+    }
+    return undefined;
+}
+export function groupByRequestId(lines) {
+    const groups = [];
+    let currentId;
+    for (const line of lines) {
+        const id = requestIdOf(line);
+        const last = groups[groups.length - 1];
+        if (id !== undefined && id === currentId && last !== undefined) {
+            last.push(line);
+            continue;
+        }
+        groups.push([line]);
+        currentId = id;
+    }
+    return groups;
+}

package/dist/src/transcript/version.js

@@ -0,0 +1 @@
+export const PROJECTOR_VERSION = 10;

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@faithfulalabi/agent-lens",
+  "version": "0.1.0",
+  "description": "Local-first agentic tracing platform: inspect everything your agent did in a session.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Faithful Alabi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/faithfulalabi/agent-lens.git"
+  },
+  "homepage": "https://github.com/faithfulalabi/agent-lens#readme",
+  "bugs": "https://github.com/faithfulalabi/agent-lens/issues",
+  "keywords": [
+    "claude-code",
+    "agent",
+    "tracing",
+    "observability",
+    "transcripts",
+    "local-first",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "agent-lens": "bin/agent-lens.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "ui/dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsx src/dev/server.ts",
+    "dev:ui": "npm --prefix ui run dev",
+    "render-gate": "tsx src/render-gate/index.ts",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.node.json --noEmit && npm --prefix ui run typecheck",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && npm --prefix ui run build",
+    "smoke:pack": "node --import tsx scripts/pack-smoke.mjs",
+    "smoke:ui": "playwright test",
+    "lint": "eslint .",
+    "prepublishOnly": "npm run build",
+    "format": "prettier --write .",
+    "prepare": "npm --prefix ui install"
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.0.11",
+    "hono": "^4.6.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@playwright/test": "^1.62.1",
+    "@types/node": "^24.0.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^9.1.0",
+    "fast-check": "^3.23.2",
+    "globals": "^15.15.0",
+    "playwright-core": "^1.62.1",
+    "prettier": "^3.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.2.0"
+  }
+}