@xiaolei.shawn/mcp-server 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AL Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# @xiaolei.shawn/mcp-server
+
+Local-first MCP server for AI agent session auditing.
+
+- Records canonical session events via MCP tools
+- Persists events as local JSONL files
+- Serves a local web dashboard + API from the same process
+- Data never leaves the machine unless you explicitly move files
+
+## Open-source connector model
+
+This package is intended to be the open-source MCP connector layer.
+
+- Open source: MCP tools + canonical event capture + local storage/API serving
+- Proprietary (optional): advanced analyzer dashboard/heuristics binaries can be served separately
+
+You can point the built-in dashboard server to any static bundle via `AL_DASHBOARD_WEBAPP_DIR`.
+
+## Features
+
+- Canonical event capture with sequence ordering and timestamps
+- Gateway tools for low-friction agent instrumentation
+- Local dashboard server (`/api/sessions`, `/api/sessions/:key`)
+- Session storage on local disk (`AL_SESSIONS_DIR`)
+- Local gateway API for middleware (`/api/gateway/*`)
+- Export session JSON with normalized snapshot (`agentlens export`)
+
+## Install
+
+```bash
+npm install @xiaolei.shawn/mcp-server
+```
+
+## Run
+
+```bash
+agentlens start --open
+```
+
+This starts the local dashboard + gateway API on `http://127.0.0.1:4317` and opens a browser tab.
+
+MCP mode (for Cursor/Codex MCP config):
+
+```bash
+agentlens mcp
+```
+
+## MCP Tools
+
+### Canonical recorders
+
+- `record_session_start`
+- `record_intent`
+- `record_activity`
+- `record_decision`
+- `record_assumption`
+- `record_verification`
+- `record_session_end`
+
+### Gateway tools
+
+- `gateway_begin_run`
+- `gateway_act`
+- `gateway_end_run`
+
+## Local Dashboard
+
+When the server starts, it also runs a local HTTP server (enabled by default).
+
+Default URL:
+
+- `http://127.0.0.1:4317`
+
+API endpoints:
+
+- `GET /api/health`
+- `GET /api/sessions`
+- `GET /api/sessions/:key`
+- `GET /api/sessions/:key/export`
+- `POST /api/gateway/begin`
+- `POST /api/gateway/act`
+- `POST /api/gateway/end`
+
+If web assets are available (default `../webapp/dist`), they are served by the same server.
+
+## Automatic instrumentation defaults
+
+To reduce agent friction:
+
+- `gateway_act` auto-creates a session if no active session exists.
+- `gateway_act` auto-creates an intent when activity arrives without an active intent.
+- `record_session_end` and `gateway_end_run` persist both raw JSONL and a normalized session snapshot.
+
+## Environment Variables
+
+- `AL_SESSIONS_DIR` (default: `./sessions`): local session file directory.
+- `AL_DASHBOARD_ENABLED` (default: `true`): enable/disable dashboard server.
+- `AL_DASHBOARD_HOST` (default: `127.0.0.1`): dashboard bind host.
+- `AL_DASHBOARD_PORT` (default: `4317`): dashboard bind port.
+- `AL_DASHBOARD_WEBAPP_DIR` (default: auto): static webapp build directory.
+- `AL_WORKSPACE_ROOT` (default: `process.cwd()`): workspace root for safe path operations.
+- `AL_AUTO_GOAL` (default: `Agent task execution`): fallback goal for auto-started sessions.
+- `AL_AUTO_USER_PROMPT` (default: `Auto-instrumented run`): fallback prompt for auto-started sessions.
+
+## Cursor/Codex MCP configuration example
+
+```json
+{
+  "mcpServers": {
+    "agentlens": {
+      "command": "agentlens",
+      "args": ["mcp"],
+      "env": {
+        "AL_SESSIONS_DIR": "/absolute/path/to/sessions"
+      }
+    }
+  }
+}
+```
+
+## Build from source
+
+```bash
+pnpm install
+pnpm --filter @xiaolei.shawn/mcp-server build
+pnpm --filter @xiaolei.shawn/mcp-server start
+```
+
+## Export session JSON
+
+Export latest session:
+
+```bash
+agentlens export --latest --out ./latest.session.json
+```
+
+Export by session id:
+
+```bash
+agentlens export --session sess_1771256059058_2bd2bd8f --out ./session.json
+```
+
+## Publish checklist
+
+1. Update version in `package.json`.
+2. Confirm repository URLs in `package.json` are correct.
+3. Run:
+
+```bash
+npm run build
+npm pack --dry-run
+npm publish --access public --dry-run
+```
+
+4. Publish:
+
+```bash
+npm publish --access public
+```

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+/**
+ * MCP server config from environment.
+ */
+export declare function getSessionsDir(): string;
+export declare function isDashboardEnabled(): boolean;
+export declare function getDashboardHost(): string;
+export declare function getDashboardPort(): number;
+export declare function getDashboardWebappDir(): string;
+export declare function isWatcherEnabled(): boolean;
+export declare function getWatcherDir(): string;
+/** Workspace root for file_op: all paths are resolved and validated against this. */
+export declare function getWorkspaceRoot(): string;
+/** Resolve path relative to workspace; throw if it escapes workspace (path traversal). */
+export declare function resolveWithinWorkspace(workspaceRoot: string, rawPath: string): string;

package/dist/config.js

@@ -0,0 +1,63 @@
+/**
+ * MCP server config from environment.
+ */
+import { dirname, resolve, sep } from "node:path";
+import { existsSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+export function getSessionsDir() {
+    return process.env.AL_SESSIONS_DIR ?? process.env.MCP_AL_SESSIONS_DIR ?? "./sessions";
+}
+export function isDashboardEnabled() {
+    const raw = process.env.AL_DASHBOARD_ENABLED ?? process.env.MCP_AL_DASHBOARD_ENABLED;
+    if (raw === undefined)
+        return true;
+    return raw === "1" || raw === "true";
+}
+export function getDashboardHost() {
+    return process.env.AL_DASHBOARD_HOST ?? process.env.MCP_AL_DASHBOARD_HOST ?? "127.0.0.1";
+}
+export function getDashboardPort() {
+    const raw = process.env.AL_DASHBOARD_PORT ?? process.env.MCP_AL_DASHBOARD_PORT;
+    if (!raw)
+        return 4317;
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+        throw new Error(`Invalid AL_DASHBOARD_PORT: ${raw}`);
+    }
+    return parsed;
+}
+export function getDashboardWebappDir() {
+    const explicit = process.env.AL_DASHBOARD_WEBAPP_DIR ?? process.env.MCP_AL_DASHBOARD_WEBAPP_DIR;
+    if (explicit)
+        return resolve(explicit);
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    // dist/config.js -> ../.. lands in mcp-server root
+    const serverRoot = resolve(moduleDir, "..");
+    return resolve(serverRoot, "../webapp/dist");
+}
+export function isWatcherEnabled() {
+    return process.env.AL_WATCHER_ENABLED === "1" || process.env.AL_WATCHER_ENABLED === "true";
+}
+export function getWatcherDir() {
+    return process.env.AL_WATCHER_DIR ?? process.env.MCP_AL_WATCHER_DIR ?? "./watcher-events";
+}
+/** Workspace root for file_op: all paths are resolved and validated against this. */
+export function getWorkspaceRoot() {
+    const root = process.env.AL_WORKSPACE_ROOT ?? process.env.MCP_AL_WORKSPACE_ROOT ?? process.cwd();
+    try {
+        return realpathSync(resolve(root));
+    }
+    catch {
+        return resolve(root);
+    }
+}
+/** Resolve path relative to workspace; throw if it escapes workspace (path traversal). */
+export function resolveWithinWorkspace(workspaceRoot, rawPath) {
+    const normalized = resolve(workspaceRoot, rawPath);
+    const real = existsSync(normalized) ? realpathSync(normalized) : resolve(normalized);
+    const prefix = workspaceRoot.endsWith(sep) ? workspaceRoot : workspaceRoot + sep;
+    if (real !== workspaceRoot && !real.startsWith(prefix)) {
+        throw new Error(`Path escapes workspace: ${rawPath}`);
+    }
+    return real;
+}

package/dist/dashboard.d.ts

@@ -0,0 +1,4 @@
+export declare function startDashboardServer(): {
+    host: string;
+    port: number;
+} | null;

package/dist/dashboard.js

@@ -0,0 +1,401 @@
+import { createServer } from "node:http";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join, normalize, resolve } from "node:path";
+import { getDashboardHost, getDashboardPort, getDashboardWebappDir, getSessionsDir, isDashboardEnabled, } from "./config.js";
+import { exportSessionJson } from "./store.js";
+import { handleGatewayAct, handleGatewayBeginRun, handleGatewayEndRun } from "./tools.js";
+function json(res, status, payload) {
+    res.writeHead(status, {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store",
+    });
+    res.end(JSON.stringify(payload));
+}
+async function readJsonBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const raw = Buffer.concat(chunks).toString("utf-8").trim();
+    if (!raw)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("Invalid JSON body.");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("Request body must be a JSON object.");
+    }
+    return parsed;
+}
+function parseToolResult(result) {
+    if (!result || typeof result !== "object") {
+        return { ok: false, payload: null, error: "Invalid tool response." };
+    }
+    const tool = result;
+    const text = tool.content?.[0]?.text;
+    if (tool.isError) {
+        return { ok: false, payload: null, error: text ?? "Tool failed." };
+    }
+    if (!text)
+        return { ok: true, payload: {} };
+    try {
+        return { ok: true, payload: JSON.parse(text) };
+    }
+    catch {
+        return { ok: true, payload: { message: text } };
+    }
+}
+function isCanonicalEvent(raw) {
+    if (!raw || typeof raw !== "object")
+        return false;
+    const event = raw;
+    return (typeof event.id === "string" &&
+        typeof event.session_id === "string" &&
+        typeof event.seq === "number" &&
+        typeof event.ts === "string" &&
+        typeof event.kind === "string" &&
+        !!event.actor &&
+        typeof event.actor.type === "string" &&
+        !!event.payload &&
+        typeof event.payload === "object" &&
+        typeof event.schema_version === "number");
+}
+function parseSessionContent(content) {
+    const text = content.trim();
+    if (!text)
+        throw new Error("Empty session file.");
+    if (text.startsWith("{") || text.startsWith("[")) {
+        try {
+            const parsed = JSON.parse(text);
+            if (Array.isArray(parsed)) {
+                const events = parsed.filter(isCanonicalEvent);
+                if (events.length !== parsed.length)
+                    throw new Error("Invalid event in JSON array.");
+                return toSessionPayload(events);
+            }
+            if (parsed && typeof parsed === "object") {
+                const obj = parsed;
+                if (Array.isArray(obj.events) && obj.events.every(isCanonicalEvent)) {
+                    return {
+                        session_id: obj.session_id ?? obj.events[0]?.session_id ?? "unknown",
+                        goal: typeof obj.goal === "string" ? obj.goal : undefined,
+                        user_prompt: typeof obj.user_prompt === "string" ? obj.user_prompt : undefined,
+                        started_at: typeof obj.started_at === "string" ? obj.started_at : undefined,
+                        ended_at: typeof obj.ended_at === "string" ? obj.ended_at : undefined,
+                        events: [...obj.events].sort((a, b) => (a.seq === b.seq ? a.ts.localeCompare(b.ts) : a.seq - b.seq)),
+                    };
+                }
+            }
+        }
+        catch {
+            // Fall back to JSONL parsing below.
+        }
+    }
+    const lines = text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    const events = lines.map((line, idx) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            throw new Error(`Invalid JSONL line ${idx + 1}`);
+        }
+        if (!isCanonicalEvent(parsed)) {
+            throw new Error(`Invalid canonical event at JSONL line ${idx + 1}`);
+        }
+        return parsed;
+    });
+    return toSessionPayload(events);
+}
+function toSessionPayload(events) {
+    const sorted = [...events].sort((a, b) => (a.seq === b.seq ? a.ts.localeCompare(b.ts) : a.seq - b.seq));
+    const start = sorted.find((event) => event.kind === "session_start");
+    const end = [...sorted].reverse().find((event) => event.kind === "session_end");
+    const startPayload = (start?.payload ?? {});
+    return {
+        session_id: sorted[0]?.session_id ?? "unknown",
+        goal: typeof startPayload.goal === "string" ? startPayload.goal : undefined,
+        user_prompt: typeof startPayload.user_prompt === "string" ? startPayload.user_prompt : undefined,
+        started_at: start?.ts ?? sorted[0]?.ts,
+        ended_at: end?.ts,
+        events: sorted,
+    };
+}
+function readSessionFile(absolutePath) {
+    const raw = readFileSync(absolutePath, "utf-8");
+    return parseSessionContent(raw);
+}
+function deriveOutcome(events) {
+    const end = [...events].reverse().find((event) => event.kind === "session_end");
+    const outcome = end?.payload?.outcome;
+    return outcome === "completed" || outcome === "partial" || outcome === "failed" || outcome === "aborted"
+        ? outcome
+        : "unknown";
+}
+function listSessionFiles() {
+    const sessionsDir = resolve(getSessionsDir());
+    if (!existsSync(sessionsDir))
+        return [];
+    const files = readdirSync(sessionsDir).filter((file) => file.endsWith(".jsonl") || file.endsWith(".json"));
+    const summaries = [];
+    for (const file of files) {
+        const absolutePath = join(sessionsDir, file);
+        const stats = statSync(absolutePath);
+        if (!stats.isFile())
+            continue;
+        try {
+            const payload = readSessionFile(absolutePath);
+            summaries.push({
+                key: file,
+                file,
+                absolute_path: absolutePath,
+                session_id: payload.session_id,
+                started_at: payload.started_at,
+                ended_at: payload.ended_at,
+                goal: payload.goal,
+                outcome: deriveOutcome(payload.events),
+                event_count: payload.events.length,
+                size_bytes: stats.size,
+                updated_at: stats.mtime.toISOString(),
+            });
+        }
+        catch {
+            // Skip malformed files from API listing to keep dashboard stable.
+        }
+    }
+    summaries.sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+    return summaries;
+}
+function contentType(pathname) {
+    const ext = extname(pathname).toLowerCase();
+    if (ext === ".html")
+        return "text/html; charset=utf-8";
+    if (ext === ".css")
+        return "text/css; charset=utf-8";
+    if (ext === ".js")
+        return "application/javascript; charset=utf-8";
+    if (ext === ".json")
+        return "application/json; charset=utf-8";
+    if (ext === ".svg")
+        return "image/svg+xml";
+    if (ext === ".png")
+        return "image/png";
+    if (ext === ".jpg" || ext === ".jpeg")
+        return "image/jpeg";
+    if (ext === ".ico")
+        return "image/x-icon";
+    return "application/octet-stream";
+}
+function serveMissingWebapp(res) {
+    res.writeHead(503, { "content-type": "text/html; charset=utf-8" });
+    res.end([
+        "<!doctype html>",
+        "<html><body style='font-family:sans-serif;background:#020617;color:#e2e8f0;padding:24px'>",
+        "<h1>AL Dashboard Not Built</h1>",
+        "<p>Build the web app first:</p>",
+        "<pre>cd /path/to/AL/webapp && npm run build</pre>",
+        "</body></html>",
+    ].join(""));
+}
+function safeJoin(root, requestPath) {
+    const normalizedPath = normalize(requestPath).replace(/^(\.\.(\/|\\|$))+/, "");
+    const joined = resolve(root, `.${normalizedPath}`);
+    if (joined !== root && !joined.startsWith(`${root}/`))
+        return null;
+    return joined;
+}
+async function handleApi(req, res, pathname) {
+    if (!pathname.startsWith("/api/"))
+        return false;
+    if (pathname === "/api/health") {
+        if (req.method !== "GET") {
+            json(res, 405, { error: "Method not allowed" });
+            return true;
+        }
+        json(res, 200, {
+            ok: true,
+            local_only: true,
+            sessions_dir: resolve(getSessionsDir()),
+            ts: new Date().toISOString(),
+        });
+        return true;
+    }
+    if (pathname === "/api/sessions") {
+        if (req.method !== "GET") {
+            json(res, 405, { error: "Method not allowed" });
+            return true;
+        }
+        json(res, 200, { sessions: listSessionFiles() });
+        return true;
+    }
+    if (pathname === "/api/gateway/begin") {
+        if (req.method !== "POST") {
+            json(res, 405, { error: "Method not allowed" });
+            return true;
+        }
+        try {
+            const body = await readJsonBody(req);
+            const parsed = parseToolResult(await handleGatewayBeginRun(body));
+            if (!parsed.ok) {
+                json(res, 400, { error: parsed.error });
+                return true;
+            }
+            json(res, 200, parsed.payload);
+        }
+        catch (error) {
+            json(res, 400, { error: error instanceof Error ? error.message : String(error) });
+        }
+        return true;
+    }
+    if (pathname === "/api/gateway/act") {
+        if (req.method !== "POST") {
+            json(res, 405, { error: "Method not allowed" });
+            return true;
+        }
+        try {
+            const body = await readJsonBody(req);
+            const parsed = parseToolResult(await handleGatewayAct(body));
+            if (!parsed.ok) {
+                json(res, 400, { error: parsed.error });
+                return true;
+            }
+            json(res, 200, parsed.payload);
+        }
+        catch (error) {
+            json(res, 400, { error: error instanceof Error ? error.message : String(error) });
+        }
+        return true;
+    }
+    if (pathname === "/api/gateway/end") {
+        if (req.method !== "POST") {
+            json(res, 405, { error: "Method not allowed" });
+            return true;
+        }
+        try {
+            const body = await readJsonBody(req);
+            const parsed = parseToolResult(await handleGatewayEndRun(body));
+            if (!parsed.ok) {
+                json(res, 400, { error: parsed.error });
+                return true;
+            }
+            json(res, 200, parsed.payload);
+        }
+        catch (error) {
+            json(res, 400, { error: error instanceof Error ? error.message : String(error) });
+        }
+        return true;
+    }
+    if (pathname.startsWith("/api/sessions/")) {
+        if (req.method !== "GET") {
+            json(res, 405, { error: "Method not allowed" });
+            return true;
+        }
+        const key = decodeURIComponent(pathname.slice("/api/sessions/".length));
+        if (!key) {
+            json(res, 400, { error: "Missing session key." });
+            return true;
+        }
+        if (key.endsWith("/export")) {
+            const rawKey = key.slice(0, -"/export".length);
+            const summary = listSessionFiles().find((item) => item.key === rawKey || item.session_id === rawKey);
+            if (!summary) {
+                json(res, 404, { error: "Session not found." });
+                return true;
+            }
+            try {
+                const exported = exportSessionJson(summary.session_id);
+                res.writeHead(200, {
+                    "content-type": "application/json; charset=utf-8",
+                    "cache-control": "no-store",
+                    "content-disposition": `attachment; filename="${summary.session_id}.session.json"`,
+                });
+                res.end(exported);
+            }
+            catch (error) {
+                json(res, 500, {
+                    error: error instanceof Error ? error.message : "Failed to export session.",
+                });
+            }
+            return true;
+        }
+        const summary = listSessionFiles().find((item) => item.key === key || item.session_id === key);
+        if (!summary) {
+            json(res, 404, { error: "Session not found." });
+            return true;
+        }
+        try {
+            const payload = readSessionFile(summary.absolute_path);
+            json(res, 200, payload);
+        }
+        catch (error) {
+            json(res, 500, {
+                error: error instanceof Error ? error.message : "Failed to read session file.",
+            });
+        }
+        return true;
+    }
+    json(res, 404, { error: "Unknown API endpoint." });
+    return true;
+}
+function handleStatic(req, res) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const pathname = url.pathname;
+    const webappDir = getDashboardWebappDir();
+    handleApi(req, res, pathname)
+        .then((handled) => {
+        if (handled)
+            return;
+        if (!existsSync(webappDir)) {
+            serveMissingWebapp(res);
+            return;
+        }
+        const relative = pathname === "/" ? "/index.html" : pathname;
+        const resolved = safeJoin(webappDir, relative);
+        if (!resolved) {
+            res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
+            res.end("Bad request");
+            return;
+        }
+        const hasExt = extname(relative).length > 0;
+        const target = existsSync(resolved) ? resolved : hasExt ? null : join(webappDir, "index.html");
+        if (!target || !existsSync(target)) {
+            res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+            res.end("Not found");
+            return;
+        }
+        const body = readFileSync(target);
+        res.writeHead(200, {
+            "content-type": contentType(target),
+            "cache-control": target.endsWith("index.html") ? "no-cache" : "public, max-age=3600",
+        });
+        res.end(body);
+    })
+        .catch((error) => {
+        json(res, 500, {
+            error: error instanceof Error ? error.message : "Unhandled server error.",
+        });
+    });
+}
+export function startDashboardServer() {
+    if (!isDashboardEnabled()) {
+        process.stderr.write("AL dashboard disabled (AL_DASHBOARD_ENABLED=false)\n");
+        return null;
+    }
+    const host = getDashboardHost();
+    const port = getDashboardPort();
+    const server = createServer((req, res) => handleStatic(req, res));
+    server.listen(port, host, () => {
+        process.stderr.write(`AL dashboard listening at http://${host}:${port} (sessions: ${resolve(getSessionsDir())}, webapp: ${getDashboardWebappDir()})\n`);
+    });
+    server.on("error", (error) => {
+        process.stderr.write(`AL dashboard failed: ${error instanceof Error ? error.message : String(error)}\n`);
+    });
+    return { host, port };
+}

package/dist/event-envelope.d.ts

@@ -0,0 +1,33 @@
+export type ActorType = "agent" | "user" | "system" | "tool";
+export interface CanonicalEvent {
+    id: string;
+    session_id: string;
+    seq: number;
+    ts: string;
+    kind: string;
+    actor: {
+        type: ActorType;
+        id?: string;
+    };
+    scope?: {
+        intent_id?: string;
+        file?: string;
+        module?: string;
+    };
+    payload: Record<string, unknown>;
+    derived?: boolean;
+    confidence?: number;
+    visibility?: "raw" | "review" | "debug";
+    schema_version: number;
+}
+export declare const EVENT_SCHEMA_VERSION = 1;
+export interface SessionLogFile {
+    session_id: string;
+    goal: string;
+    user_prompt?: string;
+    repo?: string;
+    branch?: string;
+    started_at: string;
+    ended_at?: string;
+    events: CanonicalEvent[];
+}