@pasko70/pibo 1.7.2 → 1.7.3

package/README.md

@@ -0,0 +1,183 @@
+# pibo
+
+Pibo is a thin product boundary around Pi Coding Agent. Pi remains the inner engine for model turns, tools, streaming, sessions, and compaction. Pibo adds profiles, plugins, channels, local gateways, web auth, and operator tooling.
+
+The default posture is intentionally powerful: Pibo is built for agentic coding and server operation, not for a restrictive sandbox. Install and run it as the Linux user that should own its state and credentials.
+
+## Supported platforms
+
+Pibo is Linux-first. The supported hosts are:
+
+- **Linux** (any modern distribution) — primary target
+- **macOS** — supported, same code path as Linux
+- **Windows via WSL2** — fully supported; see [docs/guides/pibo-on-windows-via-wsl.md](./docs/guides/pibo-on-windows-via-wsl.md)
+- **Native Windows** — not supported; `pibo setup doctor` and `pibo setup user-host` will print a clear error pointing to the WSL guide
+
+## Install
+
+Pibo is distributed as an npm package:
+
+```bash
+npm install -g @pasko70/pibo
+pibo --help
+```
+
+The current package declares Node.js 24+. Some Linux distributions still ship Node 22 through `apt`, so install a recent Node release first when needed. A user-local Node/npm setup through `nvm`, `fnm`, or a user-writable npm prefix works well.
+
+For a user-local global npm prefix:
+
+```bash
+mkdir -p ~/.local
+npm config set prefix ~/.local
+export PATH="$HOME/.local/bin:$PATH"
+npm install -g @pasko70/pibo
+```
+
+## State and user paths
+
+Pibo stores product-wide state under:
+
+```text
+${PIBO_HOME:-~/.pibo}
+```
+
+That means the executing Linux user owns the installation state:
+
+```text
+alice -> /home/alice/.pibo
+pibo  -> /home/pibo/.pibo
+root  -> /root/.pibo
+```
+
+There is no requirement to run as `root`. If you SSH as root and run Pibo, state naturally lands in `/root/.pibo`. If you create or use a dedicated user, state lands in that user's home. This is the preferred way to keep SSH keys, config, logs, and sessions separated.
+
+Workspace-scoped files are separate and live under the active workspace:
+
+```text
+<workspace>/.pibo
+```
+
+Examples include custom prompts and Pi package registrations.
+
+## Server notes
+
+A fresh server install usually needs only three decisions:
+
+1. Choose the Linux user that should own Pibo.
+2. Install Node.js 24+ for that user or system-wide.
+3. Install Pibo through npm.
+
+Use the setup planner to keep the first run simple:
+
+```bash
+pibo setup doctor --domain pibo.example.com --expected-ip <server-ip>
+pibo setup user-host --domain pibo.example.com --print-files
+pibo setup user-host --domain pibo.example.com --write-to /tmp/pibo-setup
+```
+
+This is the normal user path: one gateway, one `PIBO_HOME`, no required Docker, no dev gateway, and no GitHub App setup. After reviewing staged files, use `--apply --yes` to write the generated systemd/Caddy files.
+
+Developer hosts are opt-in and add production/dev separation plus Docker compute workers:
+
+```bash
+pibo setup developer-host \
+  --origin git@github.com:<your-fork>/pibo.git \
+  --prod-domain pibo.example.com \
+  --dev-domain dev.pibo.example.com \
+  --print-files
+
+pibo setup developer-host \
+  --origin git@github.com:<your-fork>/pibo.git \
+  --prod-domain pibo.example.com \
+  --dev-domain dev.pibo.example.com \
+  --write-to /tmp/pibo-setup
+```
+
+See `docs/ops/install-user-host.md`, `docs/ops/install-developer-host.md`, and `docs/ops/upgrade-user-to-developer-host.md`. Developer-host services are source-pinned so production and dev do not fight over one global `pibo` symlink. Docker and swap are developer-host prerequisites only; verify them with `pibo setup doctor --require-docker --min-swap-gb 8`.
+
+If the agent should be able to perform server administration, give that Linux user the required sudo or Docker permissions explicitly. Pibo does not need a special onboarding user to work correctly; normal Unix ownership is enough.
+
+## Docker notes
+
+Docker is optional. If you run Pibo in a container, avoid hard-coding `/root` unless the container is intentionally root-owned. Prefer mapping the host user's state into the container user's home:
+
+```text
+$HOME/.pibo -> /home/pibo/.pibo
+$HOME/code  -> /workspace/code
+```
+
+Set `HOME` and `PIBO_HOME` consistently inside the container so the same path rule applies:
+
+```text
+HOME=/home/pibo
+PIBO_HOME=/home/pibo/.pibo
+```
+
+## Web gateway auth
+
+`pibo gateway:web` starts the authenticated web runtime. It requires Better Auth configuration before production use. This step is intentionally not automated because you must create/select the Google OAuth client and allowed user list:
+
+```bash
+pibo config set auth.baseURL https://your-host.example
+pibo config set auth.secret <at-least-32-characters>
+pibo config set auth.googleClientId <google-client-id>
+pibo config set auth.googleClientSecret <google-client-secret>
+pibo config set auth.allowedEmails you@example.com
+```
+
+For local loopback testing, `auth.baseURL` can be `http://localhost:4788`.
+
+## Development from source
+
+Use source installs for development, not normal usage:
+
+```bash
+git clone git@github.com:Pascapone-server/pibo.git
+cd pibo
+npm install
+npm run build
+npm run start -- --help
+```
+
+Useful scripts:
+
+```bash
+npm run dev -- --help
+npm run profile -- codex
+npm run tui:routed -- codex
+npm run gateway
+npm run gateway:web
+npm test
+npm run typecheck
+```
+
+## Main CLI areas
+
+```bash
+pibo config       # local config under ${PIBO_HOME:-~/.pibo}/config.json
+pibo mcp          # discover and call configured MCP servers
+pibo tools        # install and inspect curated external CLI tools
+pibo pi-packages  # register Pi Coding Agent packages
+pibo debug        # inspect local Pibo data stores
+pibo setup        # plan user-host installs and developer-host upgrades
+pibo profile      # inspect runtime profiles
+pibo tui          # start the direct Pi TUI
+pibo tui:routed   # start the routed Pibo TUI
+pibo gateway      # local gateway runtime
+pibo gateway:web  # authenticated web gateway runtime
+```
+
+## Further docs
+
+- `docs/architecture.md` describes runtime architecture and boundaries.
+- `docs/mcp.md` documents MCP configuration and commands.
+- `docs/tools.md` documents curated external CLI tools.
+- `docs/pi-packages.md` documents Pi package registration.
+- `docs/chat-rooms-event-log.md` documents Chat Web rooms and durable event storage.
+- `docs/progress.md` is the short implementation status snapshot.
+
+## Philosophy
+
+Keep Pibo thin. Pi Coding Agent should remain the inner engine; Pibo owns only the product boundary: profiles, plugins, channels, routing, auth, policy, and operator tooling.
+
+Optional integrations should stay outside the core package until installed. MCP servers, Python virtual environments, external CLIs, and user skills are configured on demand rather than bundled into every runtime.

package/dist/apps/chat/chat-trace-helpers.js

@@ -75,10 +75,12 @@ export function annotateTracePage(trace, events, input) {
         eventLimit: input.pageSize,
         pageSize: input.pageSize,
         beforeSequence: input.beforeSequence,
+        beforeCursor: input.beforeCursor,
         firstEventSequence,
         lastEventSequence,
         nextBeforeSequence: firstEventSequence,
-        hasOlderEvents: firstEventSequence !== undefined ? firstEventSequence > 1 : false,
+        nextBeforeCursor: input.nextBeforeCursor ?? (firstEventSequence !== undefined ? String(firstEventSequence) : undefined),
+        hasOlderEvents: input.hasOlderEvents ?? (firstEventSequence !== undefined ? firstEventSequence > 1 : false),
     };
 }
 export function setTraceCache(cache, key, trace, maxEntries, maxBytes = TRACE_CACHE_MAX_BYTES) {

package/dist/apps/chat/trace-v2.js

@@ -20,6 +20,10 @@ export function traceTimelinePageFromView(input) {
         limit: Math.max(1, Math.min(input.limit, TRACE_V2_MAX_TIMELINE_LIMIT)),
         fromTail: input.fromTail,
     });
+    const transcriptTailCursor = input.fromTail ? input.transcriptTailCursor : undefined;
+    const hasOlder = input.trace.hasOlderEvents === true || transcriptTailCursor !== undefined;
+    const nextBeforeCursor = transcriptTailCursor ?? (hasOlder ? input.trace.nextBeforeCursor : undefined);
+    const nextBeforeSequence = transcriptTailCursor ? undefined : (hasOlder ? input.trace.nextBeforeSequence : undefined);
     let page = {
         piboSessionId: input.trace.piboSessionId,
         piSessionId: input.trace.piSessionId,
@@ -28,9 +32,9 @@ export function traceTimelinePageFromView(input) {
         latestStreamId: input.trace.latestStreamId,
         projectionStatus: "ready",
         cursor: {
-            before: input.trace.nextBeforeSequence !== undefined ? String(input.trace.nextBeforeSequence) : undefined,
+            before: nextBeforeCursor ?? (nextBeforeSequence !== undefined ? String(nextBeforeSequence) : undefined),
             after: input.trace.lastEventSequence !== undefined ? String(input.trace.lastEventSequence) : undefined,
-            hasOlder: input.trace.hasOlderEvents === true,
+            hasOlder,
             hasNewer: false,
         },
         nodes,
@@ -43,8 +47,9 @@ export function traceTimelinePageFromView(input) {
         pageSize: input.trace.pageSize,
         firstEventSequence: input.trace.firstEventSequence,
         lastEventSequence: input.trace.lastEventSequence,
-        nextBeforeSequence: input.trace.nextBeforeSequence,
-        hasOlderEvents: input.trace.hasOlderEvents,
+        nextBeforeSequence,
+        nextBeforeCursor,
+        hasOlderEvents: hasOlder,
     };
     while (Buffer.byteLength(JSON.stringify(page), "utf8") > byteLimit && page.nodes.length > 1) {
         page = {

package/dist/apps/chat/trace.js

@@ -8,6 +8,8 @@ import { isChatWebSessionArchived } from "./session-metadata.js";
 import { workflowSessionKindFromMetadata } from "../../sessions/workflow-session-kind.js";
 export { compareTraceNodes, sortTraceNodes, nestTraceNodes, flattenTraceNodes, mapTraceNodesById, buildTraceViewFromEvents, traceNodesFromEntries, } from "../../shared/trace-engine.js";
 export const TRACE_TRANSCRIPT_TAIL_MAX_BYTES = 2 * 1024 * 1024;
+export const TRACE_TRANSCRIPT_HISTORY_PAGE_MAX_BYTES = 512 * 1024;
+export const TRACE_TRANSCRIPT_HISTORY_SCAN_MAX_BYTES = 16 * 1024 * 1024;
 export async function loadPiSessionMetadata(session, cwd = process.cwd()) {
     const piSession = await findPiSession(session, cwd);
     return metadataFromPiSession(piSession);
@@ -133,6 +135,9 @@ export async function buildTraceView(input) {
         includeRawEvents: input.includeRawEvents,
         rawEventsLimit: input.rawEventsLimit,
     });
+    if (input.transcriptOrderOffset && input.transcriptOrderOffset > 0) {
+        offsetTranscriptTraceOrder(view.nodes, input.transcriptOrderOffset);
+    }
     annotateForkableUserMessageNodes(view.nodes, allEntries);
     return {
         ...view,
@@ -324,6 +329,127 @@ export function readTailEntries(path, maxBytes = TRACE_TRANSCRIPT_TAIL_MAX_BYTES
         closeSync(fd);
     }
 }
+export function readTranscriptHistoryPage(path, input = {}) {
+    if (!existsSync(path))
+        return { entries: [], hasOlder: false, scannedBytes: 0, startByte: 0, endByte: 0 };
+    const stats = statSync(path);
+    const fileSize = Math.max(0, stats.size);
+    const initialEnd = input.beforeByte === undefined
+        ? fileSize
+        : Math.max(0, Math.min(input.beforeByte, fileSize));
+    const limit = Math.max(1, Math.min(input.limit ?? 50, 500));
+    const pageBytes = Math.max(1024, Math.min(input.pageBytes ?? TRACE_TRANSCRIPT_HISTORY_PAGE_MAX_BYTES, TRACE_TRANSCRIPT_HISTORY_SCAN_MAX_BYTES));
+    const maxScanBytes = Math.max(pageBytes, Math.min(input.maxScanBytes ?? TRACE_TRANSCRIPT_HISTORY_SCAN_MAX_BYTES, 32 * 1024 * 1024));
+    const beforeTime = input.beforeTimestamp ? Date.parse(input.beforeTimestamp) : undefined;
+    const entries = [];
+    let cursorEnd = initialEnd;
+    let scannedBytes = 0;
+    let nextBeforeByte;
+    while (cursorEnd > 0 && entries.length < limit && scannedBytes < maxScanBytes) {
+        const chunkStart = Math.max(0, cursorEnd - pageBytes);
+        const chunk = readUtf8Range(path, chunkStart, cursorEnd);
+        scannedBytes += cursorEnd - chunkStart;
+        const records = transcriptLineRecords(chunk, chunkStart, cursorEnd);
+        for (let index = records.length - 1; index >= 0; index -= 1) {
+            const record = records[index];
+            const parsed = parseTranscriptLine(record.text);
+            for (let entryIndex = parsed.length - 1; entryIndex >= 0; entryIndex -= 1) {
+                const entry = parsed[entryIndex];
+                if (beforeTime !== undefined && entryTimestampMs(entry) >= beforeTime)
+                    continue;
+                entries.push({ entry, startByte: record.startByte });
+                if (entries.length >= limit) {
+                    nextBeforeByte = record.startByte;
+                    break;
+                }
+            }
+            if (entries.length >= limit)
+                break;
+        }
+        cursorEnd = chunkStart;
+    }
+    if (nextBeforeByte === undefined)
+        nextBeforeByte = cursorEnd > 0 ? cursorEnd : undefined;
+    return {
+        entries: entries.reverse().map((item) => item.entry),
+        nextBeforeByte,
+        hasOlder: nextBeforeByte !== undefined && nextBeforeByte > 0,
+        scannedBytes,
+        startByte: nextBeforeByte ?? 0,
+        endByte: initialEnd,
+    };
+}
+function readUtf8Range(path, start, end) {
+    const length = Math.max(0, end - start);
+    if (length === 0)
+        return "";
+    const buffer = Buffer.alloc(length);
+    const fd = openSync(path, "r");
+    try {
+        const bytesRead = readSync(fd, buffer, 0, length, start);
+        return buffer.subarray(0, bytesRead).toString("utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function transcriptLineRecords(content, startByte, endByte) {
+    let text = content;
+    let byteOffset = startByte;
+    if (startByte > 0) {
+        const firstNewline = text.indexOf("\n");
+        if (firstNewline < 0)
+            return [];
+        const skipped = text.slice(0, firstNewline + 1);
+        byteOffset += Buffer.byteLength(skipped, "utf8");
+        text = text.slice(firstNewline + 1);
+    }
+    if (endByte > startByte && text && !text.endsWith("\n")) {
+        const lastNewline = text.lastIndexOf("\n");
+        if (lastNewline >= 0)
+            text = text.slice(0, lastNewline + 1);
+    }
+    const records = [];
+    const segments = text.match(/[^\n]*(?:\n|$)/g) ?? [];
+    for (const segment of segments) {
+        if (!segment)
+            continue;
+        const lineStart = byteOffset;
+        byteOffset += Buffer.byteLength(segment, "utf8");
+        const line = segment.replace(/\r?\n$/, "");
+        if (line.trim())
+            records.push({ text: line, startByte: lineStart });
+    }
+    return records;
+}
+function parseTranscriptLine(line) {
+    try {
+        return parseSessionEntries(`${line}\n`).filter((entry) => entry.type !== "session");
+    }
+    catch {
+        return [];
+    }
+}
+function entryTimestampMs(entry) {
+    const timestamp = entry.timestamp;
+    if (typeof timestamp !== "string")
+        return Number.POSITIVE_INFINITY;
+    const parsed = Date.parse(timestamp);
+    return Number.isFinite(parsed) ? parsed : Number.POSITIVE_INFINITY;
+}
+function offsetTranscriptTraceOrder(nodes, offset) {
+    for (const node of nodes) {
+        if (node.source === "transcript" && node.orderKey) {
+            const transcriptIndex = node.orderKey.transcriptIndex;
+            node.orderKey = {
+                ...node.orderKey,
+                turnSeq: node.orderKey.turnSeq + offset,
+                transcriptIndex: transcriptIndex === undefined ? undefined : transcriptIndex + offset,
+            };
+        }
+        offsetTranscriptTraceOrder(node.children, offset);
+    }
+}
 function annotateForkableUserMessageNodes(nodes, entries) {
     const candidates = userMessageForkCandidates(entries);
     if (!candidates.length)

package/dist/apps/chat/web-app.js

@@ -6,7 +6,7 @@ import { OutputCompactor } from "./output-compactor.js";
 import { isLiveOnlyOutputEvent, isPersistableOutputEvent } from "./output-event-policy.js";
 import { chatRoomIdFromMetadata, isDefaultPiboRoom, isPiboRoomArchived, roomWorkspaceFromMetadata, withChatRoomId, withPiboRoomWorkspace, } from "./types/rooms.js";
 import { chatStreamFramesFromOutputEvent, createChatStreamState, nextTransientChatStreamFrameId } from "./stream.js";
-import { buildSessionNodes, buildTraceView, createTraceViewVersion, loadPiSessionMetadata, readTailEntries } from "./trace.js";
+import { buildSessionNodes, buildTraceView, createTraceViewVersion, loadPiSessionMetadata, readTailEntries, readTranscriptHistoryPage } from "./trace.js";
 import { DEFAULT_TRACE_EVENTS_PAGE_SIZE, annotateTracePage, etagForVersion, estimateTraceViewBytes, traceCacheEstimatedBytes, liveSnapshotVersion, requestMatchesVersion, setTraceCache, traceCacheKey, withLiveSnapshots, withRawTraceTail, } from "./chat-trace-helpers.js";
 import { TRACE_V2_DEFAULT_TIMELINE_LIMIT, TRACE_V2_MAX_TIMELINE_LIMIT, TRACE_V2_PAYLOAD_DEFAULT_LIMIT_BYTES, TRACE_V2_PAYLOAD_MAX_LIMIT_BYTES, TRACE_V2_RAW_EVENTS_DEFAULT_LIMIT, TRACE_V2_RAW_EVENTS_MAX_LIMIT, TRACE_V2_TIMELINE_HARD_BYTES, parseTracePayloadRef, readTracePayloadChunk, traceRawEventsPageFromEvents, traceTimelinePageFromView, } from "./trace-v2.js";
 import { isChatWebSessionArchived } from "./session-metadata.js";
@@ -2254,14 +2254,76 @@ function recordTransientReplayEvent(state, event) {
 function parseTimelineBeforeCursor(url) {
     const before = parseOptionalPositiveIntSearchParam(url, "beforeSequence");
     if (before !== undefined)
-        return before;
+        return { kind: "event", beforeSequence: before, raw: String(before) };
     const cursor = url.searchParams.get("before") ?? url.searchParams.get("cursor");
     if (!cursor || cursor === "tail")
-        return undefined;
+        return { kind: "tail" };
+    const transcript = parseTranscriptTimelineCursor(cursor);
+    if (transcript)
+        return transcript;
     const parsed = Number.parseInt(cursor, 10);
     if (!Number.isFinite(parsed) || parsed <= 0)
-        throw new PiboWebHttpError("Trace cursor must be tail or a positive sequence", 400);
-    return parsed;
+        throw new PiboWebHttpError("Trace cursor must be tail, transcript, or a positive sequence", 400);
+    return { kind: "event", beforeSequence: parsed, raw: String(parsed) };
+}
+function parseTranscriptTimelineCursor(cursor) {
+    if (!cursor.startsWith("transcript:"))
+        return undefined;
+    const [, byteValue, encodedTimestamp] = cursor.split(":");
+    const beforeByte = Number.parseInt(byteValue ?? "", 10);
+    if (!Number.isFinite(beforeByte) || beforeByte < 0)
+        throw new PiboWebHttpError("Invalid transcript trace cursor", 400);
+    let beforeTimestamp;
+    if (encodedTimestamp) {
+        try {
+            const decoded = Buffer.from(encodedTimestamp, "base64url").toString("utf8");
+            if (decoded)
+                beforeTimestamp = decoded;
+        }
+        catch {
+            throw new PiboWebHttpError("Invalid transcript trace cursor", 400);
+        }
+    }
+    return { kind: "transcript", beforeByte, beforeTimestamp, raw: cursor };
+}
+function encodeTranscriptTimelineCursor(beforeByte, beforeTimestamp) {
+    const encodedTimestamp = beforeTimestamp ? Buffer.from(beforeTimestamp, "utf8").toString("base64url") : "";
+    return `transcript:${Math.max(0, Math.floor(beforeByte))}:${encodedTimestamp}`;
+}
+function compactionCutoffTimestamp(events) {
+    const compaction = events.find((event) => event.type === "execution_result" && event.payload.type === "execution_result" && event.payload.action === "compact")
+        ?? events.find((event) => event.type === "compaction_end" || event.type === "compaction_start");
+    return compaction?.createdAt;
+}
+function originTranscriptTailCursor(input) {
+    if (!input.session.originId)
+        return undefined;
+    const sessionPath = input.metadata?.sessionPath;
+    const sessionSize = input.metadata?.sessionSize;
+    if (!sessionPath || !sessionSize || sessionSize <= 0)
+        return undefined;
+    const firstVisibleTranscript = firstVisibleTailTranscriptNode(input.trace.nodes, input.limit);
+    if (!firstVisibleTranscript?.startedAt)
+        return undefined;
+    const probe = readTranscriptHistoryPage(sessionPath, {
+        beforeByte: sessionSize,
+        beforeTimestamp: firstVisibleTranscript.startedAt,
+        limit: 1,
+    });
+    if (probe.entries.length === 0)
+        return undefined;
+    return encodeTranscriptTimelineCursor(sessionSize, firstVisibleTranscript.startedAt);
+}
+function firstVisibleTailTranscriptNode(nodes, limit) {
+    const flat = [];
+    const visit = (items) => {
+        for (const item of items) {
+            flat.push(item);
+            visit(item.children);
+        }
+    };
+    visit(nodes);
+    return flat.slice(-Math.max(1, limit)).find((node) => node.source === "transcript" && node.startedAt);
 }
 function transientReplayScopeKeys(input) {
     const keys = [];
@@ -4002,7 +4064,8 @@ export function createChatWebApp(options = {}) {
             if (url.pathname === `${CHAT_WEB_API_PREFIX}/trace/timeline` && request.method === "GET") {
                 const startedAt = performance.now();
                 const webSession = await requireSession(request, context);
-                const beforeSequence = parseTimelineBeforeCursor(url);
+                const timelineCursor = parseTimelineBeforeCursor(url);
+                const beforeSequence = timelineCursor.kind === "event" ? timelineCursor.beforeSequence : undefined;
                 const limit = parsePositiveIntSearchParam(url, "limit", TRACE_V2_DEFAULT_TIMELINE_LIMIT, TRACE_V2_MAX_TIMELINE_LIMIT);
                 const selectedSession = resolveRequestedSession(state, context, webSession, defaultProfile, url.searchParams.get("piboSessionId") || undefined);
                 state.sessionQuery.upsertSession(selectedSession);
@@ -4011,8 +4074,8 @@ export function createChatWebApp(options = {}) {
                 let metadataMs = 0;
                 const lastEventSequence = state.timelineQuery.getLatestEventSequence(selectedSession.id);
                 const latestStreamId = state.timelineQuery.getLatestStreamId({ piboSessionId: selectedSession.id });
-                const liveSnapshots = beforeSequence === undefined ? state.outputCompactor.snapshotsForSession(selectedSession.id) : [];
-                const transcriptMetadata = beforeSequence === undefined
+                const liveSnapshots = timelineCursor.kind === "tail" ? state.outputCompactor.snapshotsForSession(selectedSession.id) : [];
+                const transcriptMetadata = timelineCursor.kind === "tail" || timelineCursor.kind === "transcript"
                     ? await loadPiSessionMetadata(selectedSession, selectedSession.workspace ?? process.cwd())
                     : undefined;
                 const baseVersion = createFastTraceV2Version({
@@ -4026,7 +4089,7 @@ export function createChatWebApp(options = {}) {
                 });
                 const snapshotVersion = liveSnapshotVersion(liveSnapshots);
                 const version = snapshotVersion ? `${baseVersion}:live:${snapshotVersion}` : baseVersion;
-                const pageCursorKey = beforeSequence === undefined ? "tail" : `before:${beforeSequence}`;
+                const pageCursorKey = timelineCursor.kind === "tail" ? "tail" : `before:${timelineCursor.raw}`;
                 const cacheKey = traceCacheKey(selectedSession.id, `${baseVersion}:v2:limit:${limit}:${pageCursorKey}`);
                 const pageCacheKey = traceCacheKey(selectedSession.id, `${version}:v2-page:limit:${limit}:${pageCursorKey}`);
                 const cachedPage = state.traceTimelinePageCache.get(pageCacheKey);
@@ -4036,7 +4099,7 @@ export function createChatWebApp(options = {}) {
                     "x-pibo-trace-version": version,
                     "cache-control": "no-store",
                 };
-                if (beforeSequence === undefined && requestMatchesVersion(request, version)) {
+                if (timelineCursor.kind === "tail" && requestMatchesVersion(request, version)) {
                     return new Response(null, { status: 304, headers: baseHeaders });
                 }
                 if (cachedPage) {
@@ -4055,26 +4118,79 @@ export function createChatWebApp(options = {}) {
                 let trace = cached;
                 let eventCount = 0;
                 if (!trace) {
-                    const events = state.timelineQuery.listTraceEvents({
-                        piboSessionId: selectedSession.id,
-                        limit,
-                        ...(beforeSequence !== undefined ? { beforeSequence } : {}),
-                    });
-                    const transcriptEntries = beforeSequence === undefined && transcriptMetadata?.sessionPath
-                        ? readTailEntries(transcriptMetadata.sessionPath)
-                        : [];
-                    eventCount = events.length;
-                    trace = await buildTraceView({
-                        session: selectedSession,
-                        sessions: ownedSessions,
-                        events,
-                        status: indexedSession?.status,
-                        metadata: transcriptMetadata ?? {},
-                        transcriptEntries,
-                        includeRawEvents: false,
-                        latestStreamId,
-                    });
-                    trace = annotateTracePage(trace, events, { lastEventSequence, pageSize: limit, beforeSequence });
+                    if (timelineCursor.kind === "transcript") {
+                        const history = transcriptMetadata?.sessionPath
+                            ? readTranscriptHistoryPage(transcriptMetadata.sessionPath, {
+                                beforeByte: timelineCursor.beforeByte,
+                                beforeTimestamp: timelineCursor.beforeTimestamp,
+                                limit,
+                            })
+                            : { entries: [], hasOlder: false, scannedBytes: 0, startByte: 0, endByte: 0 };
+                        trace = await buildTraceView({
+                            session: selectedSession,
+                            sessions: ownedSessions,
+                            events: [],
+                            status: indexedSession?.status,
+                            metadata: transcriptMetadata ?? {},
+                            transcriptEntries: history.entries,
+                            transcriptOrderOffset: history.startByte,
+                            includeRawEvents: false,
+                            latestStreamId,
+                        });
+                        trace = {
+                            ...trace,
+                            eventCount: lastEventSequence,
+                            eventLimit: limit,
+                            pageSize: limit,
+                            beforeCursor: timelineCursor.raw,
+                            nextBeforeCursor: history.hasOlder && history.nextBeforeByte !== undefined
+                                ? encodeTranscriptTimelineCursor(history.nextBeforeByte, timelineCursor.beforeTimestamp)
+                                : undefined,
+                            hasOlderEvents: history.hasOlder,
+                        };
+                    }
+                    else {
+                        const events = state.timelineQuery.listTraceEvents({
+                            piboSessionId: selectedSession.id,
+                            limit,
+                            ...(beforeSequence !== undefined ? { beforeSequence } : {}),
+                        });
+                        const transcriptEntries = timelineCursor.kind === "tail" && transcriptMetadata?.sessionPath
+                            ? readTailEntries(transcriptMetadata.sessionPath)
+                            : [];
+                        eventCount = events.length;
+                        trace = await buildTraceView({
+                            session: selectedSession,
+                            sessions: ownedSessions,
+                            events,
+                            status: indexedSession?.status,
+                            metadata: transcriptMetadata ?? {},
+                            transcriptEntries,
+                            includeRawEvents: false,
+                            latestStreamId,
+                        });
+                        trace = annotateTracePage(trace, events, {
+                            lastEventSequence,
+                            pageSize: limit,
+                            beforeSequence,
+                            beforeCursor: timelineCursor.kind === "event" ? timelineCursor.raw : undefined,
+                        });
+                        if (trace.hasOlderEvents !== true && events.length > 0) {
+                            const cutoff = compactionCutoffTimestamp(events);
+                            if (cutoff) {
+                                const metadataStartedAt = performance.now();
+                                const metadata = transcriptMetadata ?? await loadPiSessionMetadata(selectedSession, selectedSession.workspace ?? process.cwd());
+                                metadataMs += performance.now() - metadataStartedAt;
+                                if (metadata.sessionPath && metadata.sessionSize && metadata.sessionSize > 0) {
+                                    trace = {
+                                        ...trace,
+                                        nextBeforeCursor: encodeTranscriptTimelineCursor(metadata.sessionSize, cutoff),
+                                        hasOlderEvents: true,
+                                    };
+                                }
+                            }
+                        }
+                    }
                     setTraceCache(state.traceCache, cacheKey, trace, TRACE_CACHE_MAX_ENTRIES);
                 }
                 trace = withLiveSnapshots(trace, liveSnapshots, {
@@ -4083,12 +4199,21 @@ export function createChatWebApp(options = {}) {
                     status: liveSnapshots.length ? "running" : indexedSession?.status,
                 });
                 trace = { ...trace, version };
+                const transcriptTailCursor = timelineCursor.kind === "tail"
+                    ? originTranscriptTailCursor({
+                        session: selectedSession,
+                        trace,
+                        metadata: transcriptMetadata,
+                        limit,
+                    })
+                    : undefined;
                 const page = traceTimelinePageFromView({
                     trace,
                     payloadStore: state.dataStore.payloads,
                     limit,
                     byteLimit: TRACE_V2_TIMELINE_HARD_BYTES,
-                    fromTail: beforeSequence === undefined,
+                    fromTail: timelineCursor.kind === "tail",
+                    transcriptTailCursor,
                 });
                 setTraceTimelinePageCache(state.traceTimelinePageCache, pageCacheKey, page);
                 return responseJson(page, {
@@ -4119,7 +4244,10 @@ export function createChatWebApp(options = {}) {
             }
             if (url.pathname === `${CHAT_WEB_API_PREFIX}/trace/raw-events` && request.method === "GET") {
                 const webSession = await requireSession(request, context);
-                const beforeSequence = parseTimelineBeforeCursor(url);
+                const rawCursor = parseTimelineBeforeCursor(url);
+                if (rawCursor.kind === "transcript")
+                    throw new PiboWebHttpError("Raw event cursor must be tail or a positive sequence", 400);
+                const beforeSequence = rawCursor.kind === "event" ? rawCursor.beforeSequence : undefined;
                 const limit = parsePositiveIntSearchParam(url, "limit", TRACE_V2_RAW_EVENTS_DEFAULT_LIMIT, TRACE_V2_RAW_EVENTS_MAX_LIMIT);
                 const selectedSession = resolveRequestedSession(state, context, webSession, defaultProfile, url.searchParams.get("piboSessionId") || undefined);
                 const events = state.timelineQuery.listTraceEvents({