@pasko70/pibo 2.5.1 → 3.0.0

package/dist/agent-runtimes/omp/history.js

@@ -1,5 +1,15 @@
-import { OMP_ADAPTER_ID } from "./thread.js";
-import { OMP_ADAPTER_VERSION } from "./thread.js";
+import { historyReconciliationDigest } from "../../agent-runtime/history.js";
+import { TRACE_RECONCILIATION_ENTRY_CAP } from "../../shared/trace-limits.js";
+import { OMP_ADAPTER_ID, OMP_ADAPTER_VERSION } from "./thread.js";
+const OMP_HISTORY_CURSOR_PREFIX = "omp-history:";
+const OMP_HISTORY_PAGE_LIMIT = 200;
+const DEFAULT_HISTORY_LIMIT = 100;
+class OmpHistoryResponseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "OmpHistoryResponseError";
+    }
+}
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -16,15 +26,26 @@ export function inspectOmpHistory(input, runtimeInstanceId) {
     };
 }
 function messageEntryRole(message) {
-    if (isRecord(message)) {
-        if (typeof message.role === "string") {
-            const role = message.role;
-            if (role === "user" || role === "assistant" || role === "tool" || role === "system")
-                return role;
-        }
+    if (isRecord(message) && typeof message.role === "string") {
+        const role = message.role;
+        if (role === "user" || role === "assistant" || role === "tool" || role === "system")
+            return role;
     }
     return "system";
 }
+function messageString(message, keys) {
+    if (!isRecord(message))
+        return undefined;
+    for (const key of keys) {
+        const value = message[key];
+        if (typeof value === "string" && value.trim())
+            return value;
+    }
+    return undefined;
+}
+function messageEntryId(message) {
+    return messageString(message, ["entryId", "id", "messageId"]);
+}
 function messageText(message) {
     if (typeof message === "string")
         return message;
@@ -44,48 +65,187 @@ function messageText(message) {
     }
     return "";
 }
-function toHistoryEntry(message, sequence, binding) {
+function jsonValue(value, depth = 0) {
+    if (depth > 32)
+        return "[maximum depth reached]";
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : String(value);
+    if (Array.isArray(value))
+        return value.map((child) => jsonValue(child, depth + 1));
+    if (isRecord(value)) {
+        const result = {};
+        for (const [key, child] of Object.entries(value)) {
+            if (child !== undefined)
+                result[key] = jsonValue(child, depth + 1);
+        }
+        return result;
+    }
+    return String(value);
+}
+function toHistoryEntry(message, sequence, binding, historyScopeId) {
     const role = messageEntryRole(message);
-    const content = messageText(message);
+    const content = messageText(message) || "[empty message]";
+    const nativeEntryId = messageEntryId(message);
+    const nativeTurnId = messageString(message, ["turnId", "nativeTurnId"]);
+    const nativeSessionId = binding.nativeSessionId ?? "omp";
+    const historyPosition = `omp:${nativeSessionId}:message:${sequence}`;
+    const toolCallId = role === "tool"
+        ? messageString(message, ["toolCallId", "callId"]) ?? `omp-tool:${nativeSessionId}:${sequence}`
+        : undefined;
+    const toolName = role === "tool" ? messageString(message, ["toolName", "name"]) ?? "OMP Tool" : undefined;
     return {
-        id: `${binding.nativeSessionId ?? "omp"}-${sequence}`,
+        id: `omp:${nativeSessionId}:message:${sequence}`,
         type: "message",
         source: "native",
         createdAt: isRecord(message) && typeof message.timestamp === "string"
             ? message.timestamp
-            : new Date().toISOString(),
+            : new Date(0).toISOString(),
         sequence,
+        historyPosition,
+        historyScopeId,
+        ...(nativeTurnId ? { nativeTurnId } : {}),
+        ...(nativeEntryId ? { nativeEntryId } : {}),
         role,
-        content: content || "[empty message]",
+        content,
+        ...(toolCallId ? {
+            toolCallId,
+            toolName,
+            result: isRecord(message) && message.result !== undefined ? jsonValue(message.result) : content,
+            isError: isRecord(message) && message.isError === true,
+            status: isRecord(message) && message.isError === true ? "error" : "complete",
+        } : {}),
     };
 }
-export async function readOmpHistory(client, input, runtimeInstanceId, binding) {
+function selectedLimit(value) {
+    if (value === undefined)
+        return DEFAULT_HISTORY_LIMIT;
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new OmpHistoryResponseError("OMP native history limit must be a positive integer.");
+    return Math.min(value, OMP_HISTORY_PAGE_LIMIT);
+}
+function encodeCursor(cursor) {
+    return `${OMP_HISTORY_CURSOR_PREFIX}${Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url")}`;
+}
+function decodeCursor(value, nativeSessionId) {
+    if (!value)
+        return undefined;
+    if (!value.startsWith(OMP_HISTORY_CURSOR_PREFIX))
+        throw new OmpHistoryResponseError("Invalid OMP native history cursor.");
     try {
+        const parsed = JSON.parse(Buffer.from(value.slice(OMP_HISTORY_CURSOR_PREFIX.length), "base64url").toString("utf8"));
+        if (parsed.v !== 1
+            || parsed.nativeSessionId !== nativeSessionId
+            || !Number.isSafeInteger(parsed.beforeIndex)
+            || Number(parsed.beforeIndex) < 0)
+            throw new Error("invalid cursor");
+        return parsed;
+    }
+    catch {
+        throw new OmpHistoryResponseError("Invalid OMP native history cursor.");
+    }
+}
+function messagesPageData(result) {
+    const data = isRecord(result) ? result.data : undefined;
+    if (!isRecord(data)
+        || !Array.isArray(data.messages)
+        || !Number.isSafeInteger(data.totalMessages)
+        || Number(data.totalMessages) < 0)
+        throw new OmpHistoryResponseError("OMP returned an invalid native history page.");
+    return {
+        messages: data.messages,
+        ...(typeof data.nextCursor === "string" && data.nextCursor.length > 0 ? { nextCursor: data.nextCursor } : {}),
+        totalMessages: Number(data.totalMessages),
+    };
+}
+async function readCompleteOmpMessages(client) {
+    const pages = [];
+    const seenCursors = new Set();
+    let cursor;
+    let expectedTotal;
+    let collected = 0;
+    let pageRequests = 0;
+    do {
+        pageRequests += 1;
+        if (pageRequests > TRACE_RECONCILIATION_ENTRY_CAP + 1) {
+            throw new OmpHistoryResponseError("OMP native history exceeded the bounded provider page sequence.");
+        }
         const result = await client.request({
             type: "get_messages_page",
-            ...(input.cursor ? { cursor: input.cursor } : {}),
-            ...(input.limit ? { limit: input.limit } : {}),
+            ...(cursor ? { cursor } : {}),
+            limit: OMP_HISTORY_PAGE_LIMIT,
         }, "get_messages_page");
-        const data = result["data"];
-        if (!isRecord(data) || !Array.isArray(data.messages)) {
-            return emptyPage(runtimeInstanceId);
+        const page = messagesPageData(result);
+        expectedTotal ??= page.totalMessages;
+        if (page.totalMessages !== expectedTotal) {
+            throw new OmpHistoryResponseError("OMP native history changed while its proof was collected.");
+        }
+        if (page.messages.length > OMP_HISTORY_PAGE_LIMIT) {
+            throw new OmpHistoryResponseError("OMP native history exceeded the requested provider page bound.");
+        }
+        if (expectedTotal > TRACE_RECONCILIATION_ENTRY_CAP) {
+            throw new OmpHistoryResponseError(`OMP native history exceeds the ${TRACE_RECONCILIATION_ENTRY_CAP}-entry proof bound.`);
+        }
+        if (collected + page.messages.length > expectedTotal) {
+            throw new OmpHistoryResponseError("OMP native history pages exceed their declared total.");
         }
-        const entries = [];
-        let sequence = 0;
-        for (const message of data.messages) {
-            entries.push(toHistoryEntry(message, sequence++, binding));
+        pages.push(page.messages);
+        collected += page.messages.length;
+        if (collected === expectedTotal) {
+            if (page.nextCursor) {
+                throw new OmpHistoryResponseError("OMP native history cursor extends beyond its declared total.");
+            }
+            break;
+        }
+        if (!page.nextCursor || seenCursors.has(page.nextCursor)) {
+            throw new OmpHistoryResponseError("OMP native history cannot prove a complete bounded page sequence.");
+        }
+        seenCursors.add(page.nextCursor);
+        cursor = page.nextCursor;
+    } while (true);
+    if (collected !== expectedTotal)
+        throw new OmpHistoryResponseError("OMP native history proof is incomplete.");
+    return pages.reverse().flat();
+}
+export async function readOmpHistory(client, input, runtimeInstanceId, binding) {
+    const nativeSessionId = binding.nativeSessionId ?? "omp";
+    const historyScopeId = `omp:${runtimeInstanceId}:${nativeSessionId}`;
+    try {
+        const messages = await readCompleteOmpMessages(client);
+        const allEntries = messages.map((message, sequence) => toHistoryEntry(message, sequence, binding, historyScopeId));
+        const beforeTimestampMs = input.beforeTimestamp === undefined ? undefined : Date.parse(input.beforeTimestamp);
+        if (beforeTimestampMs !== undefined && Number.isNaN(beforeTimestampMs)) {
+            throw new OmpHistoryResponseError("OMP native history beforeTimestamp is invalid.");
         }
+        const filtered = beforeTimestampMs === undefined
+            ? allEntries
+            : allEntries.filter((entry) => Date.parse(entry.createdAt) < beforeTimestampMs);
+        const cursor = decodeCursor(input.cursor, nativeSessionId);
+        const end = Math.min(cursor?.beforeIndex ?? filtered.length, filtered.length);
+        const limit = selectedLimit(input.limit);
+        const start = Math.max(0, end - limit);
+        const entries = filtered.slice(start, end);
         return {
             runtimeInstanceId,
             adapterId: OMP_ADAPTER_ID,
             source: "native",
             entries,
-            ...(typeof data.nextCursor === "string" ? { nextCursor: data.nextCursor } : {}),
-            hasMore: typeof data.nextCursor === "string" && data.nextCursor.length > 0,
+            reconciliationProof: {
+                complete: true,
+                scopeId: historyScopeId,
+                fullScope: { entryCount: allEntries.length, digest: historyReconciliationDigest(allEntries) },
+                entries: allEntries,
+            },
+            orderOffset: start,
+            ...(start > 0 ? { nextCursor: encodeCursor({ v: 1, nativeSessionId, beforeIndex: start }) } : {}),
+            hasMore: start > 0,
         };
     }
-    catch {
-        return emptyPage(runtimeInstanceId);
+    catch (error) {
+        if (error instanceof OmpHistoryResponseError)
+            throw error;
+        throw new OmpHistoryResponseError("OMP native history could not establish a complete bounded proof.");
     }
 }
 function emptyPage(runtimeInstanceId) {
@@ -94,15 +254,10 @@ function emptyPage(runtimeInstanceId) {
         adapterId: OMP_ADAPTER_ID,
         source: "native",
         entries: [],
+        reconciliationProof: { complete: false, entries: [] },
         hasMore: false,
     };
 }
 export function emptyOmpHistoryPage(runtimeInstanceId) {
-    return {
-        runtimeInstanceId,
-        adapterId: OMP_ADAPTER_ID,
-        source: "native",
-        entries: [],
-        hasMore: false,
-    };
+    return emptyPage(runtimeInstanceId);
 }

package/dist/agent-runtimes/omp/thread.js

@@ -1,6 +1,13 @@
+import { OmpRpcResponseError } from "./client.js";
 import { OMP_RPC_PROTOCOL_NAME, OMP_RPC_PROTOCOL_VERSION } from "./protocol-types.js";
 export const OMP_ADAPTER_ID = "orp";
 export const OMP_ADAPTER_VERSION = "1.0.0";
+function isUnsupportedForkCommand(error) {
+    if (!(error instanceof OmpRpcResponseError))
+        return false;
+    return /unknown_command|unsupported_command|method_not_found|(?:unknown|unsupported|unrecognized|invalid)\s+(?:rpc\s+)?(?:command|method)|(?:command|method)\s+(?:is\s+)?(?:unknown|unsupported|unrecognized|not implemented|not found)/i
+        .test(`${error.errorCode ?? ""} ${error.error}`);
+}
 /**
  * OMP session-file lifecycle controller. OMP owns its session files (JSONL
  * session transcripts) under the isolated `PI_CODING_AGENT_DIR` sessions dir.
@@ -11,7 +18,6 @@ export class OmpThreadController {
     client;
     cwd;
     snapshot;
-    forkCandidatesCache = [];
     constructor(client, cwd, initial) {
         this.client = client;
         this.cwd = cwd;
@@ -56,49 +62,89 @@ export class OmpThreadController {
         const snapshot = this.getSessionSnapshot(runtimeInstanceId);
         return [{ ...snapshot, messageCount: this.snapshot.messageCount, name: this.snapshot.sessionName }];
     }
-    /** Fetch branch candidates from OMP and cache them for the sync SPI. */
-    async loadForkCandidates(runtimeInstanceId) {
+    /** Fetch fork candidates from current OMP RPC names with legacy branch compatibility. */
+    async loadForkCandidates(_runtimeInstanceId) {
+        let result;
         try {
-            const result = await this.client.request({ type: "get_branch_messages" }, "get_branch_messages");
-            const data = result["data"];
-            if (data && typeof data === "object" && !Array.isArray(data) && "messages" in data) {
-                const messages = data.messages;
-                if (Array.isArray(messages)) {
-                    const candidates = [];
-                    for (const entry of messages) {
-                        if (entry && typeof entry === "object" && !Array.isArray(entry)) {
-                            const rec = entry;
-                            if (typeof rec.entryId === "string") {
-                                candidates.push({
-                                    entryId: rec.entryId,
-                                    text: typeof rec.text === "string" ? rec.text : "",
-                                });
-                            }
-                        }
-                    }
-                    this.forkCandidatesCache = candidates;
-                    return candidates;
-                }
+            result = await this.client.request({ type: "get_fork_messages" }, "get_fork_messages");
+        }
+        catch (error) {
+            if (!isUnsupportedForkCommand(error))
+                throw error;
+            try {
+                result = await this.client.request({ type: "get_branch_messages" }, "get_branch_messages");
+            }
+            catch (legacyError) {
+                if (isUnsupportedForkCommand(legacyError))
+                    return [];
+                throw legacyError;
             }
         }
-        catch {
-            // Branch candidates are optional; fall through to empty.
+        const data = result["data"];
+        if (!data || typeof data !== "object" || Array.isArray(data) || !("messages" in data))
+            return [];
+        const messages = data.messages;
+        if (!Array.isArray(messages))
+            return [];
+        const candidates = [];
+        const seenEntryIds = new Set();
+        for (const entry of messages) {
+            if (!entry || typeof entry !== "object" || Array.isArray(entry))
+                continue;
+            const record = entry;
+            if (typeof record.entryId !== "string" || !record.entryId.trim() || seenEntryIds.has(record.entryId))
+                continue;
+            seenEntryIds.add(record.entryId);
+            candidates.push({
+                entryId: record.entryId,
+                text: typeof record.text === "string" ? record.text : "",
+            });
         }
-        this.forkCandidatesCache = [];
-        return [];
-    }
-    /** Sync accessor for the SPI (get_available_commands via a warm-up load). */
-    cachedForkCandidates() {
-        return this.forkCandidatesCache;
+        return candidates;
     }
     async forkSession(runtimeInstanceId, entryId) {
+        if (!entryId.trim())
+            throw new Error("OMP session fork requires a native user-message id.");
+        const previousState = structuredClone(this.snapshot);
         const previous = structuredClone(this.getSessionSnapshot(runtimeInstanceId));
-        const result = await this.client.request({ type: "branch", entryId }, "branch");
+        let result;
+        try {
+            result = await this.client.request({ type: "fork", entryId }, "fork");
+        }
+        catch (error) {
+            if (!isUnsupportedForkCommand(error))
+                throw error;
+            result = await this.client.request({ type: "branch", entryId }, "branch");
+        }
         const data = result["data"];
-        const cancelled = Boolean(data && typeof data === "object" && !Array.isArray(data) && data.cancelled === true);
-        await this.refresh();
-        const current = this.getSessionSnapshot(runtimeInstanceId);
-        return { previous, current, cancelled };
+        const record = data && typeof data === "object" && !Array.isArray(data) ? data : undefined;
+        const cancelled = record?.cancelled === true;
+        try {
+            await this.refresh();
+            const current = this.getSessionSnapshot(runtimeInstanceId);
+            if (!cancelled && current.nativeSessionId === previous.nativeSessionId) {
+                throw new Error("OMP session fork returned the source native session id.");
+            }
+            return {
+                previous,
+                current,
+                cancelled,
+                summaryEntryId: entryId,
+                ...(typeof record?.text === "string" ? { selectedText: record.text } : {}),
+            };
+        }
+        catch (error) {
+            if (!cancelled && previousState.sessionFile) {
+                try {
+                    await this.client.request({ type: "switch_session", sessionPath: previousState.sessionFile }, "switch_session");
+                    await this.refresh();
+                }
+                catch (rollbackError) {
+                    throw new AggregateError([error, rollbackError], "OMP session fork failed and the source session could not be restored.");
+                }
+            }
+            throw error;
+        }
     }
     async switchSession(runtimeInstanceId, sessionPath) {
         const previous = structuredClone(this.getSessionSnapshot(runtimeInstanceId));

package/dist/agent-runtimes/pi/adapter.js

@@ -8,11 +8,36 @@ import { unsupportedAgentRuntimeCapability, } from "../../agent-runtime/capabili
 import { RoutedSession as PiRoutedSession } from "./routed-session.js";
 import { loadModelCatalog as loadPiModelCatalog, piAgentRuntimeModelCatalog, } from "./model-catalog.js";
 import { inspectPiAgentRuntimeHistory, readPiAgentRuntimeHistory, } from "./history.js";
+import { historyReconciliationDigest, } from "../../agent-runtime/history.js";
 import { PiAgentRuntimeAuthController } from "./auth.js";
 import { importPortableHistoryIntoPi } from "./portable-history.js";
 import { piIntentTracingEnabled } from "./intent-tracing.js";
+import { isWebSearchProviderTool } from "../../tools/web-search.js";
 const PI_ADAPTER_ID = "pi";
 export const PI_PROTOCOL_VERSION = "0.84.2";
+const piCompleteHistoryProofs = new WeakMap();
+function bindPiCompleteHistoryProof(page) {
+    const claim = page.reconciliationProof;
+    if (!claim?.complete)
+        return page;
+    const entries = Object.freeze([...claim.entries]);
+    const fullScope = Object.freeze({ entryCount: entries.length, digest: historyReconciliationDigest(entries) });
+    const proof = Object.freeze({
+        complete: true,
+        ...(claim.scopeId ? { scopeId: claim.scopeId } : {}),
+        fullScope,
+        entries,
+    });
+    piCompleteHistoryProofs.set(proof, { ...(claim.scopeId ? { scopeId: claim.scopeId } : {}), fullScope });
+    return { ...page, reconciliationProof: proof };
+}
+export function isPiBuiltInHistoryReconciliationProof(proof) {
+    const bound = piCompleteHistoryProofs.get(proof);
+    return proof.complete
+        && bound !== undefined
+        && proof.scopeId === bound.scopeId
+        && proof.fullScope === bound.fullScope;
+}
 export const PI_AGENT_RUNTIME_CAPABILITIES = {
     lifecycle: {
         persistent: true,
@@ -251,7 +276,7 @@ class PiAgentRuntimeSession {
     bindingNativeSessionId;
     nativePresenceExpected;
     disposed = false;
-    constructor(runtimeInstanceId, piboSessionId, runtime, binding, initialFastMode) {
+    constructor(runtimeInstanceId, piboSessionId, runtime, binding, initialFastMode, providerWebSearchEnabled) {
         this.runtimeInstanceId = runtimeInstanceId;
         this.piboSessionId = piboSessionId;
         this.runtime = runtime;
@@ -260,6 +285,8 @@ class PiAgentRuntimeSession {
         this.bindingNativeSessionId = runtime.session.sessionId;
         this.nativePresenceExpected = runtime.session.sessionManager.buildSessionContext().messages.length > 0;
         this.routed = new PiRoutedSession(piboSessionId, runtime, (event) => this.handlePiboEvent(event), PiboPluginRegistry.create(), true, undefined, initialFastMode, undefined, undefined, (state) => this.handleEngineState(state));
+        if (providerWebSearchEnabled)
+            this.routed.enableProviderWebSearchObservation();
         this.controls = this.createControls();
         this.compatibilityHandle = this.createCompatibilityHandle();
     }
@@ -517,7 +544,7 @@ class PiAgentRuntimeAdapter {
         return await inspectPiAgentRuntimeHistory(this.instanceId, input);
     }
     async readHistory(input) {
-        return await readPiAgentRuntimeHistory(this.instanceId, input);
+        return bindPiCompleteHistoryProof(await readPiAgentRuntimeHistory(this.instanceId, input));
     }
     validateProfile(input) {
         const diagnostics = [];
@@ -658,7 +685,7 @@ class PiAgentRuntimeAdapter {
                     && runtime.session.sessionManager.buildSessionContext().messages.length > 0,
             },
         };
-        return new PiAgentRuntimeSession(this.instanceId, input.piboSession.id, runtime, binding, compatibility?.initialFastMode ?? false);
+        return new PiAgentRuntimeSession(this.instanceId, input.piboSession.id, runtime, binding, compatibility?.initialFastMode ?? false, profile.tools.some((tool) => tool.enabled !== false && isWebSearchProviderTool(tool)));
     }
     loadModelCatalog() {
         const now = Date.now();

package/dist/agent-runtimes/pi/history.js

@@ -3,6 +3,8 @@ import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, s
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { parseSessionEntries, SessionManager } from "@earendil-works/pi-coding-agent";
+import { historyReconciliationDigest } from "../../agent-runtime/history.js";
+import { TRACE_RECONCILIATION_ENTRY_CAP } from "../../shared/trace-limits.js";
 export const PI_HISTORY_TAIL_MAX_BYTES = 2 * 1024 * 1024;
 export const PI_HISTORY_PAGE_MAX_BYTES = 512 * 1024;
 export const PI_HISTORY_SCAN_MAX_BYTES = 16 * 1024 * 1024;
@@ -76,11 +78,35 @@ export async function readPiAgentRuntimeHistory(runtimeInstanceId, input) {
         beforeTimestamp: input.beforeTimestamp ?? decoded.beforeTimestamp,
         limit: input.limit,
     });
+    const historyScopeId = `pi:${runtimeInstanceId}:${input.binding.nativeSessionId ?? "unbound"}`;
+    const completeProof = inspection.sizeBytes !== undefined && inspection.sizeBytes <= PI_HISTORY_SCAN_MAX_BYTES
+        ? readPiTranscriptEntriesWithPositions(inspection.locator.value, PI_HISTORY_SCAN_MAX_BYTES, TRACE_RECONCILIATION_ENTRY_CAP)
+        : undefined;
+    const proofEntries = completeProof
+        ? piSessionEntriesToAgentRuntimeHistoryEntries(completeProof.entries, completeProof.entryPositions, historyScopeId)
+        : undefined;
+    const proofEntriesByPosition = proofEntries
+        ? new Map(proofEntries.map((entry) => [entry.historyPosition, entry]))
+        : undefined;
+    const entries = proofEntriesByPosition
+        ? page.entryPositions.flatMap((position) => {
+            const entry = proofEntriesByPosition.get(position);
+            return entry ? [entry] : [];
+        })
+        : piSessionEntriesToAgentRuntimeHistoryEntries(page.entries, page.entryPositions, historyScopeId);
     return {
         runtimeInstanceId,
         adapterId: "pi",
         source: "native",
-        entries: piSessionEntriesToAgentRuntimeHistoryEntries(page.entries),
+        entries,
+        reconciliationProof: completeProof && proofEntries
+            ? {
+                complete: true,
+                scopeId: historyScopeId,
+                fullScope: { entryCount: proofEntries.length, digest: historyReconciliationDigest(proofEntries) },
+                entries: proofEntries,
+            }
+            : { complete: false, scopeId: historyScopeId, entries },
         orderOffset: page.startByte,
         nextCursor: page.hasOlder && page.nextBeforeByte !== undefined
             ? encodePiHistoryCursor({ beforeByte: page.nextBeforeByte, beforeTimestamp: input.beforeTimestamp ?? decoded.beforeTimestamp })
@@ -89,11 +115,12 @@ export async function readPiAgentRuntimeHistory(runtimeInstanceId, input) {
         inspection,
     };
 }
-export function piSessionEntriesToAgentRuntimeHistoryEntries(entries) {
+export function piSessionEntriesToAgentRuntimeHistoryEntries(entries, historyPositions = [], historyScopeId) {
     const normalized = [];
     let nativeTurnId;
     for (let sequence = 0; sequence < entries.length; sequence += 1) {
         const entry = entries[sequence];
+        const historyPosition = historyPositions[sequence];
         if (entry.type === "session_info" && entry.name) {
             normalized.push({
                 id: `pi:${entry.id}`,
@@ -101,6 +128,8 @@ export function piSessionEntriesToAgentRuntimeHistoryEntries(entries) {
                 source: "native",
                 createdAt: entry.timestamp,
                 sequence,
+                ...(historyPosition ? { historyPosition } : {}),
+                ...(historyScopeId ? { historyScopeId } : {}),
                 nativeEntryId: entry.id,
                 name: entry.name,
             });
@@ -117,6 +146,8 @@ export function piSessionEntriesToAgentRuntimeHistoryEntries(entries) {
                 source: "native",
                 createdAt: entry.timestamp,
                 sequence,
+                ...(historyPosition ? { historyPosition } : {}),
+                ...(historyScopeId ? { historyScopeId } : {}),
                 nativeTurnId,
                 nativeEntryId: entry.id,
                 role: "user",
@@ -132,6 +163,8 @@ export function piSessionEntriesToAgentRuntimeHistoryEntries(entries) {
                 source: "native",
                 createdAt: entry.timestamp,
                 sequence,
+                ...(historyPosition ? { historyPosition } : {}),
+                ...(historyScopeId ? { historyScopeId } : {}),
                 nativeTurnId,
                 nativeEntryId: entry.id,
                 role: "assistant",
@@ -153,6 +186,8 @@ export function piSessionEntriesToAgentRuntimeHistoryEntries(entries) {
                 source: "native",
                 createdAt: entry.timestamp,
                 sequence,
+                ...(historyPosition ? { historyPosition } : {}),
+                ...(historyScopeId ? { historyScopeId } : {}),
                 nativeTurnId,
                 nativeEntryId: entry.id,
                 role: "tool",
@@ -228,7 +263,7 @@ export function readPiTranscriptTailEntries(path, maxBytes = PI_HISTORY_TAIL_MAX
 }
 export function readPiTranscriptHistoryPage(path, input = {}) {
     if (!existsSync(path))
-        return { entries: [], hasOlder: false, scannedBytes: 0, startByte: 0, endByte: 0 };
+        return { entries: [], entryPositions: [], hasOlder: false, scannedBytes: 0, startByte: 0, endByte: 0 };
     const stats = statSync(path);
     const fileSize = Math.max(0, stats.size);
     const initialEnd = input.beforeByte === undefined
@@ -261,7 +296,7 @@ export function readPiTranscriptHistoryPage(path, input = {}) {
                 const entry = parsed[entryIndex];
                 if (beforeTime !== undefined && entryTimestampMs(entry) >= beforeTime)
                     continue;
-                entries.push({ entry, startByte: record.startByte });
+                entries.push({ entry, startByte: record.startByte, parsedIndex: entryIndex });
                 if (entries.length >= limit)
                     break;
             }
@@ -271,8 +306,10 @@ export function readPiTranscriptHistoryPage(path, input = {}) {
         closeSync(fd);
     }
     const nextBeforeByte = cursorEnd > 0 ? cursorEnd : undefined;
+    const orderedEntries = entries.reverse();
     return {
-        entries: entries.reverse().map((item) => item.entry),
+        entries: orderedEntries.map((item) => item.entry),
+        entryPositions: orderedEntries.map((item) => `pi-byte:${item.startByte}:${item.parsedIndex}`),
         nextBeforeByte,
         hasOlder: nextBeforeByte !== undefined,
         scannedBytes,
@@ -280,6 +317,30 @@ export function readPiTranscriptHistoryPage(path, input = {}) {
         endByte: initialEnd,
     };
 }
+function readPiTranscriptEntriesWithPositions(path, maxBytes, maxEntries) {
+    if (statSync(path).size > maxBytes)
+        return undefined;
+    const content = readFileSync(path);
+    if (content.length > maxBytes)
+        return undefined;
+    const entries = [];
+    const entryPositions = [];
+    let lineStart = 0;
+    for (let cursor = 0; cursor <= content.length; cursor += 1) {
+        if (cursor < content.length && content[cursor] !== 0x0a)
+            continue;
+        const line = content.subarray(lineStart, cursor).toString("utf8");
+        const parsed = parseTranscriptLine(line);
+        for (let parsedIndex = 0; parsedIndex < parsed.length; parsedIndex += 1) {
+            if (entries.length >= maxEntries)
+                return undefined;
+            entries.push(parsed[parsedIndex]);
+            entryPositions.push(`pi-byte:${lineStart}:${parsedIndex}`);
+        }
+        lineStart = cursor + 1;
+    }
+    return { entries, entryPositions };
+}
 function normalizePiAssistantContent(content) {
     if (typeof content === "string")
         return [{ type: "text", text: content }];