@code-yeongyu/senpi 2026.10.25-3 → 2026.10.25-4

package/dist/modes/interactive/session-control-rpc-commands.js

@@ -3,16 +3,23 @@
  * attaches by path or id, `subscribe_sessions`/`unsubscribe_sessions` run the host's status stream over
  * this one session, `steer`/`follow_up`/`prompt` go through the session's external admission (the
  * terminal's one delivery authority, so the user's draft still holds them) with the host's `whenIdle`
- * meaning, and `get_effect_status` reads the same effect ledger. A frame this file does not own answers
+ * meaning, and `get_effect_status` reads the same effect ledger. The rest of the host's drive set answers with the
+ * host's contract (senpi#4267): `set_client_info` declares the connection's roles, `attach_session` and
+ * `release_attachment` take and drop a live attachment on the session's identity, `abort` runs the host's effect
+ * path and its role rule (a Stop needs `interactive_user`), and input sent with a `clientMessageId` is answered
+ * with an admission receipt that a retry gets again, marked `replayed`. A frame this file does not own answers
  * `undefined` and falls through to the endpoint's other commands.
  */
 import { randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
-import { runGetEffectStatus } from "../rpc/effect-commands.js";
+import { CONNECTION_ROLE_FIXED } from "../rpc/connection-roles.js";
+import { INTERACTIVE_USER_CAPABILITY } from "../rpc/custom-capability.js";
+import { runAbort, runGetEffectStatus } from "../rpc/effect-commands.js";
 import { buildRpcSessionState } from "../rpc/rpc-session-state.js";
 import { answerSubscribeSessions, answerUnsubscribeSessions, refusal } from "../rpc/session-status-commands.js";
 import { keyOf } from "./session-control-attach.js";
+import { failure, success } from "./session-control-server.js";
 export const TUI_RPC_COMMANDS = [
     "open_session",
     "subscribe_sessions",
@@ -21,7 +28,13 @@ export const TUI_RPC_COMMANDS = [
     "follow_up",
     "prompt",
     "get_effect_status",
+    "set_client_info",
+    "attach_session",
+    "release_attachment",
+    "abort",
 ];
+/** The host's answer to a Stop from a connection that never declared the user's role (senpi#3811). */
+const STOP_REQUIRES_INTERACTIVE_CLIENT = "stop_requires_interactive_client: declare interactive_user with set_client_info first";
 /** `null` = answered on the writer already; `undefined` = not a command this file owns. */
 export async function runTuiRpcCommand(context, connection, command) {
     switch (command.type) {
@@ -36,6 +49,14 @@ export async function runTuiRpcCommand(context, connection, command) {
             return admitInput(context, command, command.type === "steer" ? "steer" : "followUp", command.whenIdle);
         case "prompt":
             return admitPrompt(context, command);
+        case "set_client_info":
+            return setClientInfo(context, connection, command);
+        case "attach_session":
+            return attachSession(context, connection, command);
+        case "release_attachment":
+            return releaseAttachment(context, connection, command);
+        case "abort":
+            return abort(context, connection, frame(command));
         case "get_effect_status":
             return runGetEffectStatus({
                 session: context.session,
@@ -74,6 +95,68 @@ function openSession(context, connection, command) {
     });
     return null;
 }
+/** Declares this connection's roles, fixed once declared, exactly as on a host; the other fields change nothing here. */
+function setClientInfo(context, connection, command) {
+    const capabilities = command.capabilities;
+    if (capabilities === undefined)
+        return success(command.id, "set_client_info");
+    if (!Array.isArray(capabilities) || !capabilities.every((entry) => typeof entry === "string"))
+        return failure(command.id, "set_client_info", "capabilities must be an array of strings");
+    if (!context.attachments.roles.declare(keyOf(connection), capabilities))
+        return failure(command.id, "set_client_info", CONNECTION_ROLE_FIXED);
+    return success(command.id, "set_client_info");
+}
+/**
+ * A live attachment on the session's identity, as on a host: `sessionId` is this terminal's routing handle,
+ * `durableSessionId` its session id, and `expectedHostInstance`, when sent, this endpoint's instance id. The answer
+ * follows the replay of the in-flight snapshot, then the session's records reach the connection.
+ */
+function attachSession(context, connection, command) {
+    const { session, attachments } = context;
+    const id = idOf(command);
+    if (command.sessionId !== attachments.handle)
+        return refusal(id, "attach_session", "unknown_session", {
+            reason: "this terminal hosts one session and the request names another",
+            action: "attach with this terminal's sessionId from list_sessions",
+        });
+    const instanceMatches = command.expectedHostInstance === undefined || command.expectedHostInstance === context.instanceId;
+    if (command.durableSessionId !== session.sessionId || !instanceMatches)
+        return refusal(id, "attach_session", "session_identity_mismatch", {
+            reason: "durableSessionId or expectedHostInstance does not name this terminal's session",
+            action: "read list_sessions and get_protocol_info again, then attach with their ids",
+        });
+    attachments.run(connection, () => {
+        attachments.attach(connection);
+        attachments.writer.enqueue(attachments.handle, {
+            id: command.id,
+            type: "response",
+            command: "attach_session",
+            success: true,
+            data: { sessionId: attachments.handle, attached: true },
+        });
+    });
+    return null;
+}
+function releaseAttachment(context, connection, command) {
+    if (command.sessionId !== context.attachments.handle || !context.attachments.detach(connection))
+        return refusal(idOf(command), "release_attachment", "session_not_attached", {
+            reason: "this connection is not attached to that session",
+            action: "attach first with attach_session or open_session",
+        });
+    // Nothing outlives the terminal's own attachment, so a release is never deferred.
+    return success(command.id, "release_attachment", { deferred: false });
+}
+/** The host's `abort`: the same effect receipts, and a Stop only from a connection that declared `interactive_user`. */
+async function abort(context, connection, command) {
+    const key = keyOf(connection);
+    if (command.intent === "stop" && !context.attachments.roles.has(key, INTERACTIVE_USER_CAPABILITY))
+        return failure(command.id, "abort", STOP_REQUIRES_INTERACTIVE_CLIENT);
+    const { session } = context;
+    return runAbort({ session, by: { connectionId: key }, sessionId: context.attachments.handle }, command, () => (command.intent === "stop" ? session.stop() : session.abort()).catch((cause) => {
+        // Reported out of band, as on a host; the answer never waits on it.
+        connection.send({ type: "rpc_error", error: String(cause) });
+    }));
+}
 function subscribe(context, connection, command) {
     const { writer } = context.attachments;
     const key = keyOf(connection);
@@ -145,6 +228,22 @@ function admitInput(context, command, deliverAs, whenIdle) {
         });
     const admission = context.session.externalAdmission;
     const clientMessageId = typeof command.clientMessageId === "string" ? command.clientMessageId : undefined;
+    const fingerprint = JSON.stringify([command.type, message, deliverAs, whenIdle ?? null]);
+    const prior = clientMessageId === undefined ? undefined : context.attachments.receipts.get(clientMessageId);
+    if (prior !== undefined) {
+        if (prior.fingerprint !== fingerprint)
+            return refusal(id, command.type, "client_message_id_conflict", {
+                reason: `clientMessageId ${clientMessageId} was already used for different input`,
+                action: "send new input with a new clientMessageId",
+            });
+        return answered(id, command.type, {
+            disposition: prior.disposition,
+            clientMessageId,
+            replayed: true,
+            duplicate: true,
+            admission: prior.admission,
+        });
+    }
     const expected = typeof command.expected_turn_id === "number" ? command.expected_turn_id : admission.turnEpoch;
     const result = admission.admit({
         delivery_id: clientMessageId ?? `tui-rpc-${randomUUID()}`,
@@ -155,12 +254,23 @@ function admitInput(context, command, deliverAs, whenIdle) {
         whenIdle: whenIdle === "start" ? "start" : "queue",
     });
     const identity = clientMessageId === undefined ? {} : { clientMessageId };
+    const admitted = (disposition) => {
+        if (clientMessageId === undefined)
+            return answered(id, command.type, { disposition });
+        const receipt = {
+            fingerprint,
+            disposition,
+            admission: { clientMessageId, durableSessionId: context.session.sessionId, disposition },
+        };
+        context.attachments.receipts.set(clientMessageId, receipt);
+        return answered(id, command.type, { disposition, clientMessageId, admission: receipt.admission });
+    };
     switch (result.kind) {
         case "started":
-            return answered(id, command.type, { disposition: "started", ...identity });
+            return admitted("started");
         case "steered":
         case "queued":
-            return answered(id, command.type, { disposition: "queued", ...identity });
+            return admitted("queued");
         case "already_admitted":
             return answered(id, command.type, { disposition: "queued", duplicate: true, ...identity });
         case "held_draft":

package/dist/modes/interactive/session-control-server.js

@@ -3,13 +3,17 @@
  * (`authenticateSocket`, the handshake every RPC transport shares); a wrong secret is disconnected
  * before a single JSONL line is read. After that it is the RPC framing: one LF-terminated JSON
  * object per request, one response per request carrying its `id`, plus pushed feed events.
+ *
+ * The socket path is the endpoint's logical address on every platform (its secret lives beside it); on win32 the
+ * listener binds the named pipe the host transport derives from that path and the secret (senpi#4267), which is
+ * the address every client already connects to.
  */
 import { chmod } from "node:fs/promises";
 import { createServer } from "node:net";
 import { attachJsonlLineReader, MAX_RPC_LINE_CHARACTERS, serializeJsonLine } from "../rpc/jsonl.js";
 import { rpcCommandShapeError } from "../rpc/rpc-input-validation.js";
 import { socketSink } from "../rpc/socket-sink.js";
-import { authenticateSocket } from "../rpc/socket-transport.js";
+import { authenticateSocket, resolveSocketTransportAddress } from "../rpc/socket-transport.js";
 export async function listenControlSocket(socketPath, secret, handlers) {
     const clients = new Set();
     let nextConnection = 0;
@@ -21,13 +25,15 @@ export async function listenControlSocket(socketPath, secret, handlers) {
     });
     await new Promise((resolve, reject) => {
         server.once("error", reject);
-        server.listen(socketPath, () => {
+        server.listen(resolveSocketTransportAddress(socketPath, process.platform, secret), () => {
             server.off("error", reject);
             resolve();
         });
     });
     server.on("error", (error) => handlers.listenerError(error));
-    await chmod(socketPath, 0o600);
+    // A named pipe has no file to restrict: the secret, 0600 beside the logical path, is its gate.
+    if (process.platform !== "win32")
+        await chmod(socketPath, 0o600);
     return { close: () => closeServer(server, clients) };
 }
 function acceptConnection(socket, id, handlers) {

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,7 @@ 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 { 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";
@@ -871,6 +871,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.
@@ -1457,43 +1458,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();

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/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/host-capabilities.js

@@ -1,7 +1,7 @@
 import { isHostOwnedToolRuntimeCapability, toolRuntimeCapabilities, } from "../../cli/tool-runtime.js";
 import { ACCEPT_EDITS_PERMISSION_PRESET_CAPABILITY, AUTO_PERMISSION_PRESET_CAPABILITY, } from "../../core/extensions/builtin/permission-system/config.js";
 import { DURABLE_CLIENT_MESSAGE_ID_CAPABILITY } from "./client-admission-record.js";
-import { ATTENDED_CAPABILITY, AUTH_KEY_VERIFY_CAPABILITY, AUTO_TITLE_PER_SESSION_CAPABILITY, AUTO_TITLE_SESSIONS_CAPABILITY, BROWSER_ENGINE_CAPABILITY, CONTINUE_FROM_LEAF_CAPABILITY, DETACH_CONNECTION_CAPABILITY, DURABLE_SESSION_ID_CAPABILITY, EVAL_CELLS_CAPABILITY, MEDIA_PLACEHOLDERS_CAPABILITY, MOVED_PATH_GUARD_CAPABILITY, PROMPT_SURFACE_CAPABILITY, PROMPT_SURFACE_CHAT_CAPABILITY, QUEUED_MESSAGE_REVISION_CAPABILITY, RESUME_SESSION_CAPABILITY, RETAIN_ON_DISCONNECT_CAPABILITY, RETRY_FALLBACK_PROFILE_CAPABILITY, SESSION_CONTEXT_CAPABILITY, SESSION_HELD_CAPABILITY, SESSION_KIND_CAPABILITY, SESSION_RELOCATION_CAPABILITY, SESSION_STATUS_CAPABILITY, TOOL_BARRIER_CAPABILITY, WARM_CAPABILITY, } from "./custom-capability.js";
+import { ATTENDED_CAPABILITY, AUTH_KEY_VERIFY_CAPABILITY, AUTO_TITLE_PER_SESSION_CAPABILITY, AUTO_TITLE_SESSIONS_CAPABILITY, BROWSER_ENGINE_CAPABILITY, CONTINUE_FROM_LEAF_CAPABILITY, DETACH_CONNECTION_CAPABILITY, DURABLE_SESSION_ID_CAPABILITY, ENTRIES_TAIL_CAPABILITY, EVAL_CELLS_CAPABILITY, MEDIA_PLACEHOLDERS_CAPABILITY, MOVED_PATH_GUARD_CAPABILITY, OBSERVE_READS_CAPABILITY, PROMPT_SURFACE_CAPABILITY, PROMPT_SURFACE_CHAT_CAPABILITY, QUEUED_MESSAGE_REVISION_CAPABILITY, RESUME_SESSION_CAPABILITY, RETAIN_ON_DISCONNECT_CAPABILITY, RETRY_FALLBACK_PROFILE_CAPABILITY, SESSION_CONTEXT_CAPABILITY, SESSION_HELD_CAPABILITY, SESSION_KIND_CAPABILITY, SESSION_RELOCATION_CAPABILITY, SESSION_STATUS_CAPABILITY, TOOL_BARRIER_CAPABILITY, WARM_CAPABILITY, } from "./custom-capability.js";
 import { EFFECT_LEDGER_CAPABILITY } from "./effect-record.js";
 import { STEER_WHEN_IDLE_CAPABILITY, USER_ACTIVITY_CAPABILITY } from "./rpc-types.js";
 import { MOVE_SESSION_CAPABILITY, MOVE_SESSION_REVOKE_CAPABILITY } from "./session-move-wire.js";
@@ -44,6 +44,9 @@ export function multiSessionHostCapabilities(options) {
             SESSION_HELD_CAPABILITY,
             RESUME_SESSION_CAPABILITY,
             ATTENDED_CAPABILITY,
+            // `get_state`/`get_entries` marked `observe` never attach, and history reads page backward too (senpi#4267).
+            OBSERVE_READS_CAPABILITY,
+            ENTRIES_TAIL_CAPABILITY,
             // Host capabilities, not client opt-ins: only a multi-session host owns the
             // attachment refcount `open_session.retain_on_disconnect` detaches from, the
             // per-session launch profile `context`/`auto_title` travel on, and the session

package/dist/modes/rpc/host-observe-request.d.ts

@@ -7,7 +7,8 @@
  * itself with `observe: true`; the supervisor classifies a connection by the requests it sends, and
  * only a connection that sends something other than an observing read becomes an attachment.
  *
- * Only the side-effect-free reads can observe (`get_effect_status` answers a receipt and changes nothing): `observe: true` on any other command is ignored
+ * Only the side-effect-free reads can observe (`get_effect_status` answers a receipt and changes nothing; `get_state` and
+ * `get_entries` read a session's state and history, senpi#4267): `observe: true` on any other command is ignored
  * and the connection attaches, so a client cannot hold a session while its host idles out under it.
  * `warm` never attaches, marked or not: it opens nothing, so a host that only received it idles out
  * on its normal deadline (senpi#2314).

package/dist/modes/rpc/host-observe-request.js

@@ -7,7 +7,8 @@
  * itself with `observe: true`; the supervisor classifies a connection by the requests it sends, and
  * only a connection that sends something other than an observing read becomes an attachment.
  *
- * Only the side-effect-free reads can observe (`get_effect_status` answers a receipt and changes nothing): `observe: true` on any other command is ignored
+ * Only the side-effect-free reads can observe (`get_effect_status` answers a receipt and changes nothing; `get_state` and
+ * `get_entries` read a session's state and history, senpi#4267): `observe: true` on any other command is ignored
  * and the connection attaches, so a client cannot hold a session while its host idles out under it.
  * `warm` never attaches, marked or not: it opens nothing, so a host that only received it idles out
  * on its normal deadline (senpi#2314).
@@ -33,6 +34,8 @@ const OBSERVING_COMMANDS = new Set([
     "get_effect_status",
     "get_pending_inputs",
     "get_subscription_limits",
+    "get_state",
+    "get_entries",
 ]);
 export function isObservingRequest(line) {
     let request;

package/dist/modes/rpc/rpc-read-response-types.d.ts

@@ -120,6 +120,8 @@ export type RpcReadResponse = {
         leafId: string | null;
         hasMore?: boolean;
         nextSince?: string;
+        /** A `tail` page's oldest entry id while older entries remain (senpi#4267). */
+        next_before?: string;
     };
 } | {
     id?: string;

package/dist/modes/rpc/rpc-session-command-types.d.ts

@@ -388,11 +388,18 @@ export type RpcSessionCommand = {
 } | {
     id?: string;
     type: "get_fork_messages";
-} | {
+}
+/**
+ * `since`/`before` bound the range (strictly after / strictly before an entry id); `limit` pages it forward from
+ * its start, `tail` backward from its end (`next_before` names the next page, senpi#4267).
+ */
+ | {
     id?: string;
     type: "get_entries";
     since?: string;
+    before?: string;
     limit?: number;
+    tail?: number;
     maxBytes?: number;
 } | {
     id?: string;