@code-yeongyu/senpi 2026.10.25-3 → 2026.10.26-1

package/dist/modes/rpc/compact-storage-io.js

@@ -0,0 +1,19 @@
+import { readFile, unlink, writeFile } from "node:fs/promises";
+export const nodeCompactStorageIo = {
+    writeFile: (path, data) => writeFile(path, data, { flag: "wx", mode: 0o600 }),
+    readFile: (path) => readFile(path),
+    unlink: (path) => unlink(path),
+};
+export function describeCause(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/** Committed storage that can no longer be read: a real error, never empty content. */
+export class CompactStorageReadError extends Error {
+    constructor(operation, path, cause) {
+        super(`compact storage ${operation} failed for ${path}: ${describeCause(cause)}`, { cause });
+        this.name = "CompactStorageReadError";
+        this.operation = operation;
+        this.path = path;
+    }
+}
+//# sourceMappingURL=compact-storage-io.js.map

package/dist/modes/rpc/connection-handler.d.ts

@@ -48,6 +48,8 @@ export interface RpcConnectionOptions {
  */
 export interface RpcConnectionSink {
     writeRaw(chunk: string): void;
+    /** Shared bindings accept correlated records synchronously, before JSONL buffering. */
+    writeRecord?(record: object): void;
     waitForBackpressure(): Promise<void>;
     /** Tears the transport down once its event queue can no longer deliver (overflow, write failure). */
     close?(): void;

package/dist/modes/rpc/connection-handler.js

@@ -42,13 +42,13 @@ import { ClientAdmissions } from "./client-admissions.js";
 import { handleClientInput } from "./client-input-handler.js";
 import { ConnectionQuestionBridge, degradeQuestion, sessionQuestionBridges } from "./connection-question-bridge.js";
 import { CONNECTION_ROLE_FIXED, ConnectionRoles, roleConnection } from "./connection-roles.js";
-import { AUTH_KEY_VERIFY_CAPABILITY, AUTO_TITLE_SESSIONS_CAPABILITY, buildCustomUnsupportedRequest, CONTINUE_FROM_LEAF_CAPABILITY, DEFAULT_CUSTOM_EXTENSION_LABEL, EVAL_CELLS_CAPABILITY, EXTENSION_EVENTS_CAPABILITY, INTERACTIVE_USER_CAPABILITY, MEDIA_PLACEHOLDERS_CAPABILITY, QUESTION_CAPABILITY, QUEUED_MESSAGE_REVISION_CAPABILITY, RESUME_SESSION_CAPABILITY, RETRY_FALLBACK_COMMAND_CAPABILITY, SESSION_HELD_CAPABILITY, TOOL_BARRIER_CAPABILITY, TASK_PARENT_CAPABILITY, } from "./custom-capability.js";
+import { AUTH_KEY_VERIFY_CAPABILITY, AUTO_TITLE_SESSIONS_CAPABILITY, buildCustomUnsupportedRequest, CONTINUE_FROM_LEAF_CAPABILITY, DEFAULT_CUSTOM_EXTENSION_LABEL, EVAL_CELLS_CAPABILITY, EXTENSION_EVENTS_CAPABILITY, ENTRIES_TAIL_CAPABILITY, INTERACTIVE_USER_CAPABILITY, MEDIA_PLACEHOLDERS_CAPABILITY, QUESTION_CAPABILITY, QUEUED_MESSAGE_REVISION_CAPABILITY, RESUME_SESSION_CAPABILITY, RETRY_FALLBACK_COMMAND_CAPABILITY, SESSION_HELD_CAPABILITY, TOOL_BARRIER_CAPABILITY, TASK_PARENT_CAPABILITY, } from "./custom-capability.js";
 import { runAbort, runGetEffectStatus, runQueuedInputChange, runSetModel, runSetThinkingLevel, } from "./effect-commands.js";
 import { EffectLedger } from "./effect-ledger.js";
 import { EFFECT_LEDGER_CAPABILITY } from "./effect-record.js";
 import { createRpcEventOutputBuffer } from "./event-output-buffer.js";
 import { settleExtensionUiResponse } from "./extension-ui-response.js";
-import { currentResponseByteBudget, endEntryWalk, entryPageBounds, holdEntryWalk, pageEntries, } from "./get-entries-page.js";
+import { answerGetEntries } from "./get-entries-command.js";
 import { runHoldInput } from "./held-input-commands.js";
 import { HostSessionControl } from "./host-session-control.js";
 import { createRpcLoginPromptCallbacks } from "./login-prompts.js";
@@ -57,7 +57,9 @@ import { protocolIdentity } from "./protocol-identity.js";
 import { buildRpcCommandsForSession, createCommandsChangedEvent, rpcCommandListDigest } from "./rpc-command-surface.js";
 import { rpcCommandPayloadError, rpcCommandShapeError, rpcMessageLengthError, sessionRetryFallbackError, } from "./rpc-input-validation.js";
 import { buildRpcSessionState } from "./rpc-session-state.js";
-import { RPC_ERROR_ENTRY_NOT_FOUND, RPC_ERROR_EVAL_CELL_NOT_FOUND, RPC_ERROR_EVAL_CELLS_UNAVAILABLE, RPC_ERROR_INVALID_ARGUMENT, RPC_ERROR_INVALID_EVAL_CELL_REQUEST, RPC_ERROR_MEDIA_NOT_FOUND, RPC_ERROR_MODEL_NOT_FOUND, RPC_ERROR_RESPONSE_TOO_LARGE, STEER_WHEN_IDLE_CAPABILITY, USER_ACTIVITY_CAPABILITY, } from "./rpc-types.js";
+import { getSnapshot } from "./get-snapshot.js";
+import { sessionUiAnswerLedger } from "./ui-answer-ledger.js";
+import { RPC_ERROR_EVAL_CELL_NOT_FOUND, RPC_ERROR_EVAL_CELLS_UNAVAILABLE, RPC_ERROR_INVALID_ARGUMENT, RPC_ERROR_INVALID_EVAL_CELL_REQUEST, RPC_ERROR_MEDIA_NOT_FOUND, RPC_ERROR_MODEL_NOT_FOUND, STEER_WHEN_IDLE_CAPABILITY, USER_ACTIVITY_CAPABILITY, } from "./rpc-types.js";
 import { runPauseForRun, runResumeForRun } from "./run-hold-commands.js";
 import { availableModelsData, interruptRunningTurn } from "./session-control-actions-data.js";
 import { SessionExtensionUiRequests, sessionDialogRequests } from "./session-extension-ui-requests.js";
@@ -197,7 +199,9 @@ export function createRpcConnectionHandler(runtimeHost, sink, options = {}) {
     let loadedSurfacesDigest;
     let rpcCommandsDigest;
     let suppressLoadedSurfaceEvents = false;
-    const eventOutput = createRpcEventOutputBuffer(sink.writeRaw, options.eventFlushScheduler);
+    const eventOutput = sink.writeRecord
+        ? undefined
+        : createRpcEventOutputBuffer(sink.writeRaw, options.eventFlushScheduler);
     const effectContext = () => ({
         session,
         by: { connectionId: options.clientInfo?.connectionId() ?? "local" },
@@ -205,10 +209,18 @@ export function createRpcConnectionHandler(runtimeHost, sink, options = {}) {
     });
     const tagSessionRecord = (value) => routingSessionId === undefined ? value : { ...value, sessionId: routingSessionId };
     const output = (obj) => {
-        eventOutput.writeImmediate(tagSessionRecord(obj));
+        const record = tagSessionRecord(obj);
+        if (sink.writeRecord)
+            sink.writeRecord(record);
+        else
+            eventOutput?.writeImmediate(record);
     };
     const outputEvent = (event) => {
-        eventOutput.enqueueEvent(tagSessionRecord(event));
+        const record = tagSessionRecord(event);
+        if (sink.writeRecord)
+            sink.writeRecord(record);
+        else
+            eventOutput?.enqueueEvent(record);
     };
     const currentLoadedSurfaces = () => {
         const extensions = loadedExtensions(session);
@@ -268,7 +280,7 @@ export function createRpcConnectionHandler(runtimeHost, sink, options = {}) {
         });
     });
     const waitForRpcBackpressure = async () => {
-        eventOutput.flushEvents();
+        eventOutput?.flushEvents();
         await sink.waitForBackpressure();
     };
     const success = (id, command, data) => {
@@ -292,10 +304,15 @@ export function createRpcConnectionHandler(runtimeHost, sink, options = {}) {
         };
     };
     // Pending extension UI requests waiting for response
-    const pendingExtensionRequests = new SessionExtensionUiRequests(() => session.refreshLifecycle());
+    const uiRequestChanged = (change) => {
+        session.refreshLifecycle();
+        if (change && routingSessionId !== undefined)
+            output(change);
+    };
+    const pendingExtensionRequests = new SessionExtensionUiRequests(uiRequestChanged);
     const grantRequests = new Map();
     sessionDialogRequests.set(session, pendingExtensionRequests);
-    const questions = new ConnectionQuestionBridge(output, () => session.refreshLifecycle());
+    const questions = new ConnectionQuestionBridge(output, uiRequestChanged);
     let shutdownRequested = false;
     // In-flight OAuth logins, keyed by provider. login_start registers one; the
     // login promise clears it on completion; login_cancel aborts it. The flow is
@@ -858,6 +875,8 @@ export function createRpcConnectionHandler(runtimeHost, sink, options = {}) {
                         capabilities: [
                             ...new Set([
                                 "multi_session",
+                                "snapshot_cursor",
+                                "ui_answer_ledger",
                                 "session_lifecycle",
                                 AUTO_TITLE_SESSIONS_CAPABILITY,
                                 MEDIA_PLACEHOLDERS_CAPABILITY,
@@ -871,6 +890,7 @@ export function createRpcConnectionHandler(runtimeHost, sink, options = {}) {
                                 TOOL_BARRIER_CAPABILITY,
                                 USER_ACTIVITY_CAPABILITY,
                                 RESUME_SESSION_CAPABILITY,
+                                ENTRIES_TAIL_CAPABILITY,
                                 ...(options.retryFallbackCommand ? [RETRY_FALLBACK_COMMAND_CAPABILITY] : []),
                                 ...(options.toolRuntime ? toolRuntimeCapabilities(options.toolRuntime) : []),
                                 // Client flags cannot advertise a host guard this classic binding does not run, nor a tool runtime.
@@ -1079,6 +1099,18 @@ export function createRpcConnectionHandler(runtimeHost, sink, options = {}) {
                     refreshGrantPresentation();
                 return success(id, "set_client_info");
             }
+            case "get_snapshot": {
+                const snapshot = getSnapshot(session, command, {
+                    lastAbortSource,
+                    enqueue: (markerId) => {
+                        if (routingSessionId !== undefined)
+                            output({ type: "snapshot_marker", markerId });
+                    },
+                });
+                return "error" in snapshot
+                    ? error(id, "get_snapshot", snapshot.error, RPC_ERROR_INVALID_ARGUMENT)
+                    : success(id, "get_snapshot", snapshot.data);
+            }
             case "get_state":
                 return success(id, "get_state", buildRpcSessionState(session, lastAbortSource));
             case "request_self_settle":
@@ -1457,43 +1489,8 @@ export function createRpcConnectionHandler(runtimeHost, sink, options = {}) {
                 const messages = session.getUserMessagesForForking();
                 return success(id, "get_fork_messages", { messages });
             }
-            case "get_entries": {
-                const sessionManager = session.sessionManager;
-                let entries = sessionManager.getEntries();
-                if (command.since !== undefined) {
-                    const sinceIndex = entries.findIndex((e) => e.id === command.since);
-                    if (sinceIndex === -1) {
-                        return error(id, "get_entries", `Entry not found: ${command.since}`, RPC_ERROR_ENTRY_NOT_FOUND);
-                    }
-                    entries = entries.slice(sinceIndex + 1);
-                }
-                const bounds = entryPageBounds(command);
-                if (!bounds.ok)
-                    return error(id, "get_entries", bounds.message, RPC_ERROR_INVALID_ARGUMENT);
-                const page = pageEntries(entries, describeUsageLimitEntry, bounds);
-                // A client walking pages asks again at once; holding the view until the last page spares each page a
-                // full re-read of the file. The hold expires on its own, so a walk the client abandons on an idle
-                // session does not pin the whole history; any other answer lets the view go now.
-                if (bounds.paged && page.hasMore)
-                    holdEntryWalk(session, () => session.releaseFullHistoryView());
-                else {
-                    endEntryWalk(session);
-                    session.releaseFullHistoryView();
-                }
-                const budget = currentResponseByteBudget();
-                if (page.firstEntryBytes > budget) {
-                    return error(id, "get_entries", `Entry ${entries[0]?.id ?? ""} alone is larger than one answer can carry (${budget} bytes), so it cannot be sent over RPC.`, RPC_ERROR_RESPONSE_TOO_LARGE);
-                }
-                if (!bounds.paged && page.hasMore) {
-                    return error(id, "get_entries", `The session history is larger than one answer can carry (${budget} bytes). Read it in pages: pass limit or maxBytes, then since: nextSince until hasMore is false.`, RPC_ERROR_RESPONSE_TOO_LARGE);
-                }
-                return success(id, "get_entries", {
-                    entries: page.entries,
-                    leafId: sessionManager.getLeafId(),
-                    ...(bounds.paged ? { hasMore: page.hasMore } : {}),
-                    ...(page.nextSince === undefined ? {} : { nextSince: page.nextSince }),
-                });
-            }
+            case "get_entries":
+                return answerGetEntries(session, command);
             case "get_tree": {
                 const sessionManager = session.sessionManager;
                 const tree = sessionManager.getTree();
@@ -1722,6 +1719,7 @@ export function createRpcConnectionHandler(runtimeHost, sink, options = {}) {
                 questions,
                 dialogs: pendingExtensionRequests,
                 routed: routingSessionId !== undefined,
+                ledger: sessionUiAnswerLedger(session),
                 // An answer is a person's input by its entry point, whatever the connection role.
                 beforeAnswer: () => session.admitHumanAnswer(),
             });
@@ -1753,7 +1751,7 @@ export function createRpcConnectionHandler(runtimeHost, sink, options = {}) {
     // A single-session connection hears its account's new limit windows as they are reported. A host
     // session's handler (it has a routing `sessionId`) does not: the host broadcasts the record once.
     const stopLimitEvents = options.sessionId === undefined
-        ? subscriptionLimits.subscribe((limits) => eventOutput.enqueueEvent({ type: "subscription_limits", ...limits }))
+        ? subscriptionLimits.subscribe((limits) => outputEvent({ type: "subscription_limits", ...limits }))
         : () => { };
     const dispose = async (disposeOptions = {}) => {
         unbindMcpForms?.();

package/dist/modes/rpc/connection-question-bridge.d.ts

@@ -1,4 +1,5 @@
 import type { ExtensionUIContext, QuestionRequest, QuestionResponse } from "../../core/extensions/types.ts";
+import type { UiRequestChange } from "./snapshot-types.ts";
 import type { RpcExtensionUIProgress, RpcExtensionUIResponse, RpcQuestionUiRequest } from "./rpc-types.ts";
 type Options = Parameters<NonNullable<ExtensionUIContext["question"]>>[1];
 export declare const sessionQuestionBridges: WeakMap<object, ConnectionQuestionBridge>;
@@ -7,7 +8,7 @@ export declare class ConnectionQuestionBridge {
     private readonly resolved;
     private readonly output;
     private readonly changed;
-    constructor(output: (record: object) => void, changed?: () => void);
+    constructor(output: (record: object) => void, changed?: (change?: UiRequestChange) => void);
     pendingQuestions(): RpcQuestionUiRequest[];
     ask(request: QuestionRequest, opts?: Options): Promise<QuestionResponse>;
     respond(response: RpcExtensionUIResponse, beforeAnswer?: () => void): boolean | "question_incomplete" | "question_already_resolved";

package/dist/modes/rpc/connection-question-bridge.js

@@ -43,7 +43,11 @@ export class ConnectionQuestionBridge {
                 clearTimeout(timer);
                 opts?.signal?.removeEventListener("abort", cancel);
                 this.pending.delete(id);
-                this.changed?.();
+                this.changed?.({
+                    type: "ui_request_settled",
+                    uiRequestId: id,
+                    disposition: status === "answered" || status === "comment-submitted" ? "answered" : "cancelled",
+                });
                 this.resolved.add(id);
                 const result = {
                     status,
@@ -121,7 +125,7 @@ export class ConnectionQuestionBridge {
                 },
             });
             arm();
-            this.changed?.();
+            this.changed?.({ type: "ui_request_pending", uiRequestId: id, method: "question", request: frame });
             this.output(frame);
             opts?.signal?.addEventListener("abort", cancel, { once: true });
             if (opts?.signal?.aborted)

package/dist/modes/rpc/custom-capability.d.ts

@@ -60,6 +60,12 @@ export declare const DETACH_CONNECTION_CAPABILITY = "detach_connection";
  * client's own `set_client_info` and fixed at that first declaration (see `connection-roles.ts`).
  */
 export declare const INTERACTIVE_USER_CAPABILITY = "interactive_user";
+/** `get_state` and `get_entries` accept `observe: true` and then never count as an attachment (senpi#4267). */
+export declare const OBSERVE_READS_CAPABILITY = "observe_reads";
+/** `get_entries` accepts `before` and `tail` and answers `next_before` (senpi#4267). */
+export declare const ENTRIES_TAIL_CAPABILITY = "entries_tail";
+/** A terminal control endpoint serves the host's observe-and-drive command set (senpi#4267). */
+export declare const TUI_OBSERVER_CAPABILITY = "tui_observer";
 /** The connection owns this session as a task child; only it may pause or resume the session for its run (senpi#3811). */
 export declare const TASK_PARENT_CAPABILITY = "task_parent";
 /**

package/dist/modes/rpc/custom-capability.js

@@ -60,6 +60,12 @@ export const DETACH_CONNECTION_CAPABILITY = "detach_connection";
  * client's own `set_client_info` and fixed at that first declaration (see `connection-roles.ts`).
  */
 export const INTERACTIVE_USER_CAPABILITY = "interactive_user";
+/** `get_state` and `get_entries` accept `observe: true` and then never count as an attachment (senpi#4267). */
+export const OBSERVE_READS_CAPABILITY = "observe_reads";
+/** `get_entries` accepts `before` and `tail` and answers `next_before` (senpi#4267). */
+export const ENTRIES_TAIL_CAPABILITY = "entries_tail";
+/** A terminal control endpoint serves the host's observe-and-drive command set (senpi#4267). */
+export const TUI_OBSERVER_CAPABILITY = "tui_observer";
 /** The connection owns this session as a task child; only it may pause or resume the session for its run (senpi#3811). */
 export const TASK_PARENT_CAPABILITY = "task_parent";
 /**

package/dist/modes/rpc/extension-ui-response.d.ts

@@ -1,5 +1,6 @@
 import type { QuestionRequest, QuestionResponse } from "../../core/extensions/types.ts";
 import type { RpcExtensionUIResponse } from "./rpc-types.ts";
+import type { UiAnswerLedger } from "./ui-answer-ledger.ts";
 /**
  * An `extension_ui_response` carries two ids: `id`, the frame's own correlation id that its reply
  * echoes, and `uiRequestId`, the extension UI request it answers. The short form every older client
@@ -23,6 +24,8 @@ export type ExtensionUiResponseReply = {
     readonly id: string;
     readonly type: "response";
     readonly command: "extension_ui_response";
+    /** The answer's outcome for its request; absent when a malformed answer was refused before settling anything. */
+    readonly disposition?: "applied" | "replay" | "already_answered" | "unknown";
 } & ({
     readonly success: true;
 } | {
@@ -37,13 +40,15 @@ type DialogAnswers = {
 };
 /**
  * Settles one response on a host connection and returns its reply, keyed by the frame `id`.
- * `undefined` only on an unrouted (single-session stdio) connection for a response no request here
- * matches: that connection has always ignored such a response, and still does.
+ * `undefined` only on an unrouted (single-session stdio) connection for an unnamed response no
+ * request here matches: that connection has always ignored such a response, and still does. A named
+ * response (`answerId`) asks for a receipt, so every connection answers it.
  */
 export declare function settleExtensionUiResponse(response: RpcExtensionUIResponse, targets: {
     readonly questions: QuestionAnswers;
     readonly dialogs: DialogAnswers;
     readonly routed: boolean;
+    readonly ledger?: UiAnswerLedger;
     readonly beforeAnswer?: () => void;
 }): ExtensionUiResponseReply | undefined;
 export {};

package/dist/modes/rpc/extension-ui-response.js

@@ -28,25 +28,45 @@ export function unansweredQuestionIds(questions, answers) {
 }
 /**
  * Settles one response on a host connection and returns its reply, keyed by the frame `id`.
- * `undefined` only on an unrouted (single-session stdio) connection for a response no request here
- * matches: that connection has always ignored such a response, and still does.
+ * `undefined` only on an unrouted (single-session stdio) connection for an unnamed response no
+ * request here matches: that connection has always ignored such a response, and still does. A named
+ * response (`answerId`) asks for a receipt, so every connection answers it.
  */
 export function settleExtensionUiResponse(response, targets) {
+    if (response.answerId !== undefined &&
+        (typeof response.answerId !== "string" || response.answerId.length < 1 || response.answerId.length > 256))
+        return refused(response.id, "invalid_answer_id");
     const requestId = answeredUiRequestId(response) ?? response.id;
+    const receipt = response.answerId === undefined ? undefined : targets.ledger?.lookup(requestId, response.answerId);
+    if (receipt === "replay")
+        return { ...reply(response.id), success: true, disposition: "replay" };
+    if (receipt === "already_answered")
+        return { ...reply(response.id), success: false, error: "already_answered", disposition: receipt };
     const answer = requestId === response.id ? response : { ...response, id: requestId };
     const question = targets.questions.respond(answer, targets.beforeAnswer);
     if (typeof question === "string")
-        return refused(response.id, question);
-    if (question || targets.dialogs.resolve(answer, targets.beforeAnswer))
-        return { ...reply(response.id), success: true };
+        return refused(response.id, response.answerId !== undefined && question === "question_already_resolved"
+            ? "unknown_extension_ui_request"
+            : question);
+    if (question || targets.dialogs.resolve(answer, targets.beforeAnswer)) {
+        targets.ledger?.record(requestId, response.answerId);
+        return { ...reply(response.id), success: true, disposition: "applied" };
+    }
     // A routed binding owns exactly one session's request map: an unmatched response is a protocol
     // error for its sender, never a cross-session match.
-    return targets.routed ? refused(response.id, "unknown_extension_ui_request") : undefined;
+    return targets.routed || response.answerId !== undefined
+        ? refused(response.id, "unknown_extension_ui_request")
+        : undefined;
 }
 function reply(id) {
     return { id, type: "response", command: "extension_ui_response" };
 }
 function refused(id, error) {
-    return { ...reply(id), success: false, error };
+    const disposition = error === "question_already_resolved"
+        ? "already_answered"
+        : error === "unknown_extension_ui_request"
+            ? "unknown"
+            : undefined;
+    return { ...reply(id), success: false, error, ...(disposition === undefined ? {} : { disposition }) };
 }
 //# sourceMappingURL=extension-ui-response.js.map

package/dist/modes/rpc/get-entries-command.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The one `get_entries` answer: a host connection and a terminal control endpoint both read history through it, so
+ * the range rules (`since`, `before`), the forward (`limit`) and backward (`tail`, senpi#4267) pages and the byte
+ * budget (senpi#3534) are the same on every surface.
+ */
+import type { AgentSession } from "../../core/agent-session.ts";
+import { type RpcCommand, type RpcResponse } from "./rpc-types.ts";
+type GetEntries = Extract<RpcCommand, {
+    type: "get_entries";
+}>;
+export declare function answerGetEntries(session: AgentSession, command: GetEntries): RpcResponse;
+export {};
+//# sourceMappingURL=get-entries-command.d.ts.map

package/dist/modes/rpc/get-entries-command.js

@@ -0,0 +1,61 @@
+import { describeUsageLimitEntry } from "../../core/retry-fallback/usage-limit.js";
+import { currentResponseByteBudget, endEntryWalk, entryPageBounds, holdEntryWalk, pageEntries, pageEntriesFromEnd, } from "./get-entries-page.js";
+import { RPC_ERROR_ENTRY_NOT_FOUND, RPC_ERROR_INVALID_ARGUMENT, RPC_ERROR_RESPONSE_TOO_LARGE, } from "./rpc-types.js";
+function refuse(id, message, errorCode) {
+    return { id, type: "response", command: "get_entries", success: false, error: message, errorCode };
+}
+export function answerGetEntries(session, command) {
+    const { id } = command;
+    const sessionManager = session.sessionManager;
+    let entries = sessionManager.getEntries();
+    if (command.before !== undefined) {
+        const beforeIndex = entries.findIndex((e) => e.id === command.before);
+        if (beforeIndex === -1)
+            return refuse(id, `Entry not found: ${command.before}`, RPC_ERROR_ENTRY_NOT_FOUND);
+        entries = entries.slice(0, beforeIndex);
+    }
+    if (command.since !== undefined) {
+        const sinceIndex = sessionManager.getEntries().findIndex((e) => e.id === command.since);
+        if (sinceIndex === -1)
+            return refuse(id, `Entry not found: ${command.since}`, RPC_ERROR_ENTRY_NOT_FOUND);
+        entries = entries.slice(sinceIndex + 1);
+    }
+    const bounds = entryPageBounds(command);
+    if (!bounds.ok)
+        return refuse(id, bounds.message, RPC_ERROR_INVALID_ARGUMENT);
+    const backward = bounds.tail !== undefined;
+    const page = backward
+        ? pageEntriesFromEnd(entries, describeUsageLimitEntry, bounds)
+        : pageEntries(entries, describeUsageLimitEntry, bounds);
+    // A client walking pages asks again at once; holding the view until the last page spares each page a
+    // full re-read of the file. The hold expires on its own, so a walk the client abandons on an idle
+    // session does not pin the whole history; any other answer lets the view go now.
+    if (bounds.paged && page.hasMore)
+        holdEntryWalk(session, () => session.releaseFullHistoryView());
+    else {
+        endEntryWalk(session);
+        session.releaseFullHistoryView();
+    }
+    const budget = currentResponseByteBudget();
+    if (page.firstEntryBytes > budget) {
+        const entry = backward ? entries.at(-1) : entries[0];
+        return refuse(id, `Entry ${entry?.id ?? ""} alone is larger than one answer can carry (${budget} bytes), so it cannot be sent over RPC.`, RPC_ERROR_RESPONSE_TOO_LARGE);
+    }
+    if (!bounds.paged && page.hasMore) {
+        return refuse(id, `The session history is larger than one answer can carry (${budget} bytes). Read it in pages: pass limit or maxBytes, then since: nextSince until hasMore is false.`, RPC_ERROR_RESPONSE_TOO_LARGE);
+    }
+    return {
+        id,
+        type: "response",
+        command: "get_entries",
+        success: true,
+        data: {
+            entries: page.entries,
+            leafId: sessionManager.getLeafId(),
+            ...(bounds.paged ? { hasMore: page.hasMore } : {}),
+            ...("nextSince" in page && page.nextSince !== undefined ? { nextSince: page.nextSince } : {}),
+            ...("nextBefore" in page && page.nextBefore !== undefined ? { next_before: page.nextBefore } : {}),
+        },
+    };
+}
+//# sourceMappingURL=get-entries-command.js.map

package/dist/modes/rpc/get-entries-page.d.ts

@@ -14,6 +14,8 @@ export declare function currentResponseByteBudget(): number;
 export declare function setResponseByteBudgetForTesting(bytes: number): () => void;
 export interface EntryPageRequest {
     readonly limit?: number;
+    /** The newest `tail` entries of the range, read backwards (senpi#4267); never combined with `limit`. */
+    readonly tail?: number;
     readonly maxBytes?: number;
 }
 export interface EntryPage<T> {
@@ -27,6 +29,7 @@ export type EntryPageBounds = {
     readonly ok: true;
     readonly paged: boolean;
     readonly limit?: number;
+    readonly tail?: number;
     readonly maxBytes: number;
 } | {
     readonly ok: false;
@@ -44,6 +47,25 @@ export declare function pageEntries<S extends {
     readonly limit?: number;
     readonly maxBytes: number;
 }): EntryPage<T>;
+export interface TailEntryPage<T> {
+    /** In append order: the oldest of the page first. */
+    readonly entries: T[];
+    readonly hasMore: boolean;
+    /** The oldest entry id the page returned, while older entries remain: pass it as the next `before`. */
+    readonly nextBefore?: string;
+    /** Serialized size of the page's newest entry (0 for an empty page). */
+    readonly firstEntryBytes: number;
+}
+/**
+ * The newest entries first, until the count or the byte size would pass the bounds, answered in append order. The
+ * newest entry is always taken, so a backward walk always moves even when one entry alone is larger than `maxBytes`.
+ */
+export declare function pageEntriesFromEnd<S extends {
+    readonly id: string;
+}, T>(entries: readonly S[], project: (entry: S) => T, bounds: {
+    readonly tail?: number;
+    readonly maxBytes: number;
+}): TailEntryPage<T>;
 /**
  * Keeps a page walk's full-history view for the next page, and lets it go after `ENTRY_WALK_HOLD_MS` without
  * one: a client that stops mid-walk must not pin the whole history of a session that is already idle.

package/dist/modes/rpc/get-entries-page.js

@@ -22,17 +22,22 @@ export function setResponseByteBudgetForTesting(bytes) {
     };
 }
 export function entryPageBounds(request) {
-    const { limit, maxBytes } = request;
+    const { limit, tail, maxBytes } = request;
     if (limit !== undefined && !(Number.isInteger(limit) && limit > 0))
         return { ok: false, message: "limit must be a positive integer" };
+    if (tail !== undefined && !(Number.isInteger(tail) && tail > 0))
+        return { ok: false, message: "tail must be a positive integer" };
+    if (limit !== undefined && tail !== undefined)
+        return { ok: false, message: "limit and tail cannot be combined: limit pages forward, tail backward" };
     if (maxBytes !== undefined && !(Number.isInteger(maxBytes) && maxBytes > 0))
         return { ok: false, message: "maxBytes must be a positive integer" };
-    if (limit === undefined && maxBytes === undefined)
+    if (limit === undefined && tail === undefined && maxBytes === undefined)
         return { ok: true, paged: false, maxBytes: responseByteBudget };
     return {
         ok: true,
         paged: true,
         ...(limit === undefined ? {} : { limit }),
+        ...(tail === undefined ? {} : { tail }),
         maxBytes: Math.min(maxBytes ?? DEFAULT_ENTRY_PAGE_BYTES, responseByteBudget),
     };
 }
@@ -68,6 +73,40 @@ export function pageEntries(entries, project, bounds) {
         firstEntryBytes,
     };
 }
+/**
+ * The newest entries first, until the count or the byte size would pass the bounds, answered in append order. The
+ * newest entry is always taken, so a backward walk always moves even when one entry alone is larger than `maxBytes`.
+ */
+export function pageEntriesFromEnd(entries, project, bounds) {
+    const page = [];
+    let bytes = 0;
+    let firstEntryBytes = 0;
+    let index = entries.length - 1;
+    for (; index >= 0; index--) {
+        if (bounds.tail !== undefined && page.length >= bounds.tail)
+            break;
+        const entry = entries[index];
+        if (entry === undefined)
+            break;
+        const projected = project(entry);
+        const size = Buffer.byteLength(JSON.stringify(projected)) + 1;
+        if (page.length > 0 && bytes + size > bounds.maxBytes)
+            break;
+        if (page.length === 0)
+            firstEntryBytes = size;
+        page.push(projected);
+        bytes += size;
+    }
+    page.reverse();
+    const oldest = entries[index + 1];
+    const hasMore = index >= 0;
+    return {
+        entries: page,
+        hasMore,
+        ...(hasMore && oldest !== undefined ? { nextBefore: oldest.id } : {}),
+        firstEntryBytes,
+    };
+}
 const heldWalks = new WeakMap();
 /**
  * Keeps a page walk's full-history view for the next page, and lets it go after `ENTRY_WALK_HOLD_MS` without

package/dist/modes/rpc/get-snapshot.d.ts

@@ -0,0 +1,18 @@
+import type { AgentAbortSource } from "../../core/agent-abort-provenance.ts";
+import type { AgentSession } from "../../core/agent-session.ts";
+import type { RpcSnapshot } from "./snapshot-types.ts";
+type SnapshotRequest = {
+    readonly tail?: unknown;
+    readonly maxBytes?: unknown;
+};
+/** Capture and mark on the source loop, before any response-writing await. */
+export declare function getSnapshot(session: AgentSession, request: SnapshotRequest, cursor: {
+    readonly enqueue: (markerId: string) => void;
+    readonly lastAbortSource?: AgentAbortSource;
+}): {
+    readonly data: RpcSnapshot;
+} | {
+    readonly error: string;
+};
+export {};
+//# sourceMappingURL=get-snapshot.d.ts.map

package/dist/modes/rpc/get-snapshot.js

@@ -0,0 +1,43 @@
+import { randomUUID } from "node:crypto";
+import { describeUsageLimitEntry } from "../../core/retry-fallback/usage-limit.js";
+import { currentResponseByteBudget, DEFAULT_ENTRY_PAGE_BYTES } from "./get-entries-page.js";
+import { buildRpcSessionState } from "./rpc-session-state.js";
+/** Capture and mark on the source loop, before any response-writing await. */
+export function getSnapshot(session, request, cursor) {
+    const tail = request.tail === undefined ? 100 : request.tail;
+    const maxBytes = request.maxBytes === undefined ? DEFAULT_ENTRY_PAGE_BYTES : request.maxBytes;
+    if (typeof tail !== "number" || !Number.isSafeInteger(tail) || tail < 0)
+        return { error: "tail must be a non-negative integer" };
+    if (typeof maxBytes !== "number" || !Number.isSafeInteger(maxBytes) || maxBytes <= 0)
+        return { error: "maxBytes must be a positive integer" };
+    const state = buildRpcSessionState(session, cursor.lastAbortSource);
+    const history = session.sessionManager.getEntries();
+    const entries = [];
+    let bytes = 2;
+    for (let i = history.length - 1; i >= 0 && entries.length < tail; i--) {
+        const entry = history[i];
+        if (entry === undefined)
+            break;
+        const projected = describeUsageLimitEntry(entry);
+        const size = Buffer.byteLength(JSON.stringify(projected)) + (entries.length > 0 ? 1 : 0);
+        if (bytes + size > Math.min(maxBytes, currentResponseByteBudget()))
+            break;
+        entries.push(projected);
+        bytes += size;
+    }
+    entries.reverse();
+    const history_truncated = entries.length < history.length;
+    const markerId = randomUUID();
+    // Some state fields and entry payloads are live references: detach them before yielding, too.
+    const data = structuredClone({
+        state,
+        entries,
+        history_truncated,
+        next_before: history_truncated ? (entries[0]?.id ?? null) : null,
+        markerId,
+    });
+    session.releaseFullHistoryView();
+    cursor.enqueue(markerId);
+    return { data };
+}
+//# sourceMappingURL=get-snapshot.js.map