@1agents/session-reader 0.4.0 → 0.5.1

package/dist/src/search.js

@@ -1,4 +1,5 @@
 import { adapters, listResolvedSessions, parseSince } from './resolver.js';
+import { turnNoAt, turnStarts } from './turns.js';
 import { canonicalizePath, isInside } from './util/paths.js';
 const DEFAULT_CONTEXT = 100;
 const DEFAULT_MAX_PER_SESSION = 5;
@@ -126,25 +127,115 @@ export function planQuery(query, options = {}) {
     const run = longestCaselessRun(raw);
     return run.length >= 2 ? { literal: run } : {};
 }
-function accumulate(hits, sessionId, candidate, pattern, context, maxPerSession) {
+// ---------------------------------------------------------------------------
+// The searcher's own footprint
+// ---------------------------------------------------------------------------
+/**
+ * How recent a `1session` invocation has to be to be this very search rather
+ * than a historical one. The agent's tool call is written to its transcript
+ * seconds before the command runs, so the window only has to survive the
+ * indexing sweep — but a past session that genuinely ran the same query must
+ * stay a real hit, which is what keeps this narrow.
+ */
+const SELF_ECHO_WINDOW_MS = 5 * 60_000;
+/** How far after the invocation its own output may land, as in `commandLedger`. */
+const RESULT_SPAN = 3;
+const INVOCATION = /(?:^|[\s"'`/])1session\s/;
+/**
+ * A `1session` invocation written in the last few minutes.
+ *
+ * Only the live transcript can hold one: a session that ended yesterday cannot
+ * have an event timestamped now, so the window is what separates "this
+ * investigation, happening" from "someone once ran this", and no past session
+ * is ever touched by it.
+ */
+function isRunningInvocation(candidate, now) {
+    if (candidate.kind !== 'tool_call' || !candidate.timestamp)
+        return false;
+    const at = Date.parse(candidate.timestamp);
+    if (!Number.isFinite(at) || at < now - SELF_ECHO_WINDOW_MS || at > now + 60_000)
+        return false;
+    return INVOCATION.test(candidate.body);
+}
+/**
+ * Folds the Read Plane's own footprint out of one session: an invocation
+ * running right now, and the result carrying what it printed.
+ *
+ * It deliberately does not require the invocation to carry *this* query. A
+ * `1session` call from a minute ago prints other sessions' content verbatim,
+ * so it matches queries it never mentioned — and whatever it echoed is still
+ * in the session it was quoting from, where the search finds it properly, with
+ * a handle that drills down to the real thing instead of to a screenful of
+ * this tool's output.
+ *
+ * Stateful because the second half is only knowable from the first, so it is
+ * built fresh per session and fed events in index order — which both search
+ * paths already produce.
+ */
+export function echoFolder(now) {
+    let lastEcho = Number.NEGATIVE_INFINITY;
+    return (candidate) => {
+        if (isRunningInvocation(candidate, now)) {
+            lastEcho = candidate.index;
+            return true;
+        }
+        return candidate.kind === 'tool_result' && candidate.index - lastEcho <= RESULT_SPAN;
+    };
+}
+/**
+ * Whether a session is the one running the search. Accepts the canonical
+ * `provider:native_id`, the bare native id, or a 6+ character prefix of it —
+ * the same spellings `resolveSession` takes.
+ */
+export function isCallerSession(ref, callerId) {
+    const caller = callerId?.trim().toLowerCase();
+    if (!caller)
+        return false;
+    const native = ref.id.toLowerCase();
+    const canonical = `${ref.provider}:${native}`;
+    const bare = caller.includes(':') ? caller.slice(caller.indexOf(':') + 1) : caller;
+    return caller === canonical || bare === native || (bare.length >= 6 && native.startsWith(bare));
+}
+function accumulate(hits, sessionId, candidate, pattern, context, maxPerSession, echo) {
     if (!candidate.body)
         return;
     pattern.lastIndex = 0;
     const found = pattern.exec(candidate.body);
     if (!found)
         return;
-    const bucket = hits.get(sessionId) ?? { matches: [], totalMatches: 0 };
+    const bucket = hits.get(sessionId) ?? { matches: [], totalMatches: 0, suppressed: 0 };
+    hits.set(sessionId, bucket);
+    if (echo(candidate)) {
+        bucket.suppressed++;
+        return;
+    }
     bucket.totalMatches++;
     if (bucket.matches.length < Math.min(maxPerSession, HARD_CAP)) {
         bucket.matches.push({
             index: candidate.index,
+            turn: 0, // filled in once the session's turn boundaries are known
             kind: candidate.kind,
             ...(candidate.toolName ? { toolName: candidate.toolName } : {}),
             ...(candidate.timestamp ? { timestamp: candidate.timestamp } : {}),
             excerpt: excerpt(candidate.body, found.index, found[0].length, context),
         });
     }
-    hits.set(sessionId, bucket);
+}
+/** Stamps the drill-down handle onto every match of one session. */
+function assignTurns(matches, starts) {
+    for (const match of matches)
+        match.turn = turnNoAt(starts, match.index);
+}
+/** A bucket as it leaves the search: empty ones only survive to be counted. */
+function toHit(session, bucket, caller) {
+    const self = isCallerSession(session, caller) || (bucket.totalMatches === 0 && bucket.suppressed > 0);
+    return {
+        session,
+        matches: bucket.matches,
+        totalMatches: bucket.totalMatches,
+        ...(bucket.suppressed ? { suppressed: bucket.suppressed } : {}),
+        ...(self ? { self: true } : {}),
+    };
 }
 /**
  * Full-text search across sessions.
@@ -159,16 +250,28 @@ export async function searchSessions(query, options = {}) {
     const pattern = buildPattern(query, options);
     const context = options.context ?? DEFAULT_CONTEXT;
     const maxPerSession = options.maxPerSession ?? DEFAULT_MAX_PER_SESSION;
+    const now = Date.now();
+    const plan = {
+        pattern,
+        context,
+        maxPerSession,
+        newEchoFolder: () => echoFolder(now),
+        caller: options.selfSessionId ?? process.env.SESSION_READER_CALLER_SESSION,
+    };
     const direct = options.useIndex === false || process.env.SESSION_READER_NO_INDEX === '1';
     const hits = direct
-        ? await searchByParsing(query, options, pattern, context, maxPerSession)
-        : await searchByIndex(query, options, pattern, context, maxPerSession);
-    return hits
-        .sort((a, b) => Date.parse(b.session.updatedAt ?? '') - Date.parse(a.session.updatedAt ?? ''))
-        .slice(0, options.limit ?? hits.length);
+        ? await searchByParsing(options, plan)
+        : await searchByIndex(query, options, plan);
+    hits.sort((a, b) => Date.parse(b.session.updatedAt ?? '') - Date.parse(a.session.updatedAt ?? ''));
+    // `limit` caps the sessions a caller has to read, so it counts the ones that
+    // will actually be shown; a folded self-hit carries nothing but its tally and
+    // must not push a real session out of the answer.
+    const limit = options.limit ?? Number.POSITIVE_INFINITY;
+    let shown = 0;
+    return hits.filter((hit) => (hit.self ? true : ++shown <= limit));
 }
 /** The oracle: parses every candidate from disk, touching no stored state. */
-async function searchByParsing(_query, options, pattern, context, maxPerSession) {
+async function searchByParsing(options, plan) {
     const kinds = options.kinds?.length ? new Set(options.kinds) : undefined;
     const hits = [];
     const handles = await listResolvedSessions({
@@ -177,10 +280,13 @@ async function searchByParsing(_query, options, pattern, context, maxPerSession)
         scan: Number.POSITIVE_INFINITY,
     });
     for (const handle of handles) {
-        const session = await handle.adapter.parse(handle.candidate).catch(() => undefined);
+        const session = await handle.adapter
+            .parse(handle.candidate)
+            .catch(() => undefined);
         if (!session)
             continue;
         const bucket = new Map();
+        const echo = plan.newEchoFolder();
         for (const turn of session.turns) {
             if (kinds && !kinds.has(turn.kind))
                 continue;
@@ -190,11 +296,13 @@ async function searchByParsing(_query, options, pattern, context, maxPerSession)
                 ...(turn.toolName ? { toolName: turn.toolName } : {}),
                 ...(turn.timestamp ? { timestamp: turn.timestamp } : {}),
                 body: haystack(turn),
-            }, pattern, context, maxPerSession);
+            }, plan.pattern, plan.context, plan.maxPerSession, echo);
         }
         const found = bucket.get(session.ref.id);
-        if (found)
-            hits.push({ session: session.ref, ...found });
+        if (!found)
+            continue;
+        assignTurns(found.matches, turnStarts(session));
+        hits.push(toHit(session.ref, found, plan.caller));
     }
     return hits;
 }
@@ -204,11 +312,11 @@ async function searchByParsing(_query, options, pattern, context, maxPerSession)
  * Sessions are never materialized — rebuilding 622 of them into objects cost
  * more than every other part of a search put together.
  */
-async function searchByIndex(query, options, pattern, context, maxPerSession) {
+async function searchByIndex(query, options, plan) {
     const { openStore } = await import('./store/db.js');
     const { refreshSession } = await import('./store/indexer.js');
     const { searchRows } = await import('./store/rows.js');
-    const { refOf } = await import('./store/read.js');
+    const { refOf, turnStartsOf } = await import('./store/read.js');
     const db = await openStore();
     const sinceMs = parseSince(options.since);
     const ids = [];
@@ -223,16 +331,21 @@ async function searchByIndex(query, options, pattern, context, maxPerSession) {
                 ids.push(result.id);
         }
     }
-    const plan = planQuery(query, options);
+    const prefilter = planQuery(query, options);
     const workspace = options.workspace ? canonicalizePath(options.workspace) : undefined;
     const buckets = new Map();
+    let folding = { sessionId: '', echo: plan.newEchoFolder() };
     for (const row of searchRows(db, {
         ids,
         ...(workspace ? { workspace } : {}),
         ...(options.kinds?.length ? { kinds: options.kinds } : {}),
-        ...(plan.literal ? { literal: plan.literal } : {}),
-        ...(plan.fold ? { fold: true } : {}),
+        ...(prefilter.literal ? { literal: prefilter.literal } : {}),
+        ...(prefilter.fold ? { fold: true } : {}),
     })) {
+        // `searchRows` orders by (session_id, idx), which is what the folder needs.
+        if (row.session_id !== folding.sessionId) {
+            folding = { sessionId: row.session_id, echo: plan.newEchoFolder() };
+        }
         const args = row.tool_args_json ?? '';
         accumulate(buckets, row.session_id, {
             index: row.idx,
@@ -241,7 +354,7 @@ async function searchByIndex(query, options, pattern, context, maxPerSession) {
             ...(row.ts ? { timestamp: row.ts } : {}),
             // Rebuilt exactly as `haystack` does, so an excerpt cannot shift.
             body: [row.text ?? undefined, row.tool_result ?? undefined, args].filter(Boolean).join('\n'),
-        }, pattern, context, maxPerSession);
+        }, plan.pattern, plan.context, plan.maxPerSession, folding.echo);
     }
     const hits = [];
     for (const [id, bucket] of buckets) {
@@ -251,7 +364,10 @@ async function searchByIndex(query, options, pattern, context, maxPerSession) {
         const ref = refOf(row);
         if (workspace && !isInside(workspace, ref.workspace ?? ''))
             continue;
-        hits.push({ session: ref, ...bucket });
+        // Only the sessions that actually matched pay for this — a handful of
+        // index lookups, not the 622-session rebuild the row path exists to avoid.
+        assignTurns(bucket.matches, turnStartsOf(db, id, row.event_count));
+        hits.push(toHit(ref, bucket, plan.caller));
     }
     return hits;
 }

package/dist/src/serve/http.d.ts

@@ -4,10 +4,13 @@
  * 它把本地 Read Plane 原样暴露成网络能力：`1session overview <id>` 成为
  * `sessions.read`。**不重新实现索引与事实层**，只是换一个调用入口。
  *
- * 零运行时依赖：只用 node:http。
+ * HTTP 层不引第三方框架，只用 node:http；端口与协议类型来自 L0 包。
  */
 import http from 'node:http';
+/** 约定端口，由 L0 协议包定义——Control Plane 的 pull 探测照着它找服务。 */
+export declare const DEFAULT_PORT: 7777;
 export interface ServeOptions {
+    /** 默认 {@link DEFAULT_PORT}。换端口就探测不到了，得自己 register。 */
     port?: number;
     /**
      * Defaults to loopback. Session transcripts contain source code, shell
@@ -19,6 +22,11 @@ export interface ServeOptions {
     token?: string;
     /** Advertised base url, when behind a proxy or a different tailnet name. */
     baseUrl?: string;
+    /**
+     * 向本机 node agent 报备自己。默认开——agent 没起时是静默 no-op，没有代价。
+     * 报备后外部探一个 36908 就能看见本服务，不必碰运气猜端口。
+     */
+    report?: boolean;
 }
 export declare function createServer(options?: ServeOptions): http.Server;
 export declare function serve(options?: ServeOptions): Promise<http.Server>;

package/dist/src/serve/http.js

@@ -4,7 +4,7 @@
  * 它把本地 Read Plane 原样暴露成网络能力：`1session overview <id>` 成为
  * `sessions.read`。**不重新实现索引与事实层**，只是换一个调用入口。
  *
- * 零运行时依赖：只用 node:http。
+ * HTTP 层不引第三方框架，只用 node:http；端口与协议类型来自 L0 包。
  */
 import http from 'node:http';
 import { listRecentSessions, loadSession } from '../resolver.js';
@@ -13,6 +13,11 @@ import { summarizeTurns } from '../turns.js';
 import { searchSessions } from '../search.js';
 import { canonicalizePath } from '../util/paths.js';
 import { buildManifest, nodeIdentity, sessionUri } from './node.js';
+import { DEFAULT_PORTS } from '@1agents/dreammate-network';
+import { reportAndHoldRegistration } from '@1agents/dreammate-node/client';
+import { SESSION_CAPABILITIES } from './node.js';
+/** 约定端口，由 L0 协议包定义——Control Plane 的 pull 探测照着它找服务。 */
+export const DEFAULT_PORT = DEFAULT_PORTS['session-registry'];
 const json = (res, status, body) => {
     const payload = JSON.stringify(body, null, 2);
     res.writeHead(status, {
@@ -53,14 +58,13 @@ async function noteRead(verb, target, caller) {
 }
 async function route(ctx) {
     const { pathname } = ctx.url;
-    const identity = nodeIdentity();
+    const identity = await nodeIdentity();
     if (pathname === '/health') {
         return { status: 200, body: { status: 'ok', node_id: identity.node_id, service: 'session-registry' } };
     }
-    // `/manifest` is the network-wide contract; `/v1/node` is the same document
-    // under this service's own prefix.
-    if (pathname === '/manifest' || pathname === '/v1/node') {
-        return { status: 200, body: buildManifest(ctx.url.origin) };
+    // 只报本服务自己——节点全貌在本机 agent 的 :36908/manifest。
+    if (pathname === '/manifest') {
+        return { status: 200, body: await buildManifest(ctx.url.origin) };
     }
     if (pathname === '/v1/sessions') {
         const refs = await listRecentSessions({
@@ -168,12 +172,30 @@ export function createServer(options = {}) {
 export async function serve(options = {}) {
     const host = options.host ?? '127.0.0.1';
     const server = createServer(options);
-    await new Promise((resolve) => server.listen(options.port ?? 7777, host, resolve));
+    await new Promise((resolve) => server.listen(options.port ?? DEFAULT_PORT, host, resolve));
     const { port } = server.address();
-    const identity = nodeIdentity();
+    const identity = await nodeIdentity();
+    // 只听回环的服务，外部发现得了却连不上——如实说，别让调用方白跑一趟。
+    const reachability = host === '127.0.0.1' || host === 'localhost' || host === '::1' ? 'localhost' : 'network';
+    const reported = options.report === false
+        ? undefined
+        : await reportAndHoldRegistration({
+            id: 'session-registry',
+            name: 'session-reader',
+            kind: 'session_registry',
+            capabilities: [...SESSION_CAPABILITIES],
+            port,
+            reachability,
+            resources: [{ scheme: 'session' }],
+        });
     console.log(`1session serve — node ${identity.name} (${identity.node_id})`);
     console.log(`  http://${host}:${port}/manifest`);
     console.log(`  capabilities: sessions.list, sessions.read, sessions.turns, sessions.search, sessions.graph`);
+    if (reported) {
+        console.log(reported.ok
+            ? `  已向本机 node agent 报备（reachability=${reachability}）`
+            : `  未报备：${reported.reason}——不影响本服务，只是外部得靠约定端口找它`);
+    }
     if (host !== '127.0.0.1' && host !== 'localhost' && !options.token) {
         console.warn(`  ⚠️  绑定在 ${host} 且未设置 --token：会话原文（代码、shell 历史、密钥）将对该网络开放。`);
     }

package/dist/src/serve/node.d.ts

@@ -1,26 +1,25 @@
-import { PROTOCOL_VERSION, type AccessDescriptor, type NodeManifest, type Service as NetworkService, type SessionURI } from '@1agents/dreammate-network';
-export { PROTOCOL_VERSION };
-export type { AccessDescriptor, NetworkService, NodeManifest };
-/** Where the node identity is kept, next to the index db. */
-export declare function nodeIdentityPath(): string;
-interface StoredIdentity {
-    node_id: string;
-    name: string;
-    type: string;
-}
 /**
- * A stable node id that survives restarts, generated on first use and kept in
- * `~/.1agents/session-reader/node.json`.
+ * session-reader 作为 DreamMate Network Service 时的 manifest 构建。
  *
- * `DREAMMATE_NODE_ID` / `DREAMMATE_NODE_NAME` override it without touching the
- * file, which is what a container or a second instance on one host wants.
+ * 节点身份不在这里实现——它是每台机器的公共事实，由 `@1agents/dreammate-node`
+ * 统一提供（优先 tailnet，拿不到回退本地）。本机所有服务读到同一份，不会各自
+ * 生成 id 把一台机器裂成几个 Node。
  */
-export declare function nodeIdentity(): StoredIdentity;
+import { nodeIdentity, type NodeIdentity } from '@1agents/dreammate-node';
+import { PROTOCOL_VERSION, type AccessDescriptor, type NodeManifest, type Reachability, type Service as NetworkService, type SessionURI } from '@1agents/dreammate-network';
+export { nodeIdentity, PROTOCOL_VERSION };
+export type { AccessDescriptor, NetworkService, NodeIdentity, NodeManifest, Reachability };
 /**
  * The capabilities this Service answers for. Names are the network-facing
  * spelling of the CLI verbs: `1session overview` is `sessions.read`.
  */
 export declare const SESSION_CAPABILITIES: readonly ["sessions.list", "sessions.read", "sessions.turns", "sessions.search", "sessions.graph"];
-export declare function buildManifest(baseUrl: string): NodeManifest;
-/** `session://<node>/<runtime>/<session_id>` — the network-wide address of one session. */
+export declare function buildManifest(baseUrl: string): Promise<NodeManifest>;
+/**
+ * `session://<node>/<runtime>/<session_id>` — 一个会话在网络中的地址。
+ *
+ * `nodeName` 应该来自 {@link nodeIdentity}，也就是 tailnet 的 DNSName 前缀。
+ * **不要传 `os.hostname()`**：iOS 设备的 hostname 全是 `localhost`，几台手机
+ * 接进来会产出一模一样的 `session://localhost/yima/...`。
+ */
 export declare function sessionUri(nodeName: string, provider: string, id: string): SessionURI;

package/dist/src/serve/node.js

@@ -1,57 +1,13 @@
 /**
- * Node identity and Manifest — session-reader 作为 DreamMate Network 的第一个标准 Service。
+ * session-reader 作为 DreamMate Network Service 时的 manifest 构建。
  *
- * 协议类型直接来自 L0 包 `@1agents/dreammate-network`，不再本地抄一份：
- * 单向依赖 L2 → L0 是允许的，而共用同一份定义才谈得上「公共语言」。
+ * 节点身份不在这里实现——它是每台机器的公共事实，由 `@1agents/dreammate-node`
+ * 统一提供（优先 tailnet，拿不到回退本地）。本机所有服务读到同一份，不会各自
+ * 生成 id 把一台机器裂成几个 Node。
  */
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { randomUUID } from 'node:crypto';
-import { PROTOCOL_VERSION, } from '@1agents/dreammate-network';
-export { PROTOCOL_VERSION };
-/* ---------- 身份 ---------- */
-/** Where the node identity is kept, next to the index db. */
-export function nodeIdentityPath() {
-    return path.join(os.homedir(), '.1agents', 'session-reader', 'node.json');
-}
-const PLATFORM_TYPE = {
-    darwin: 'macos',
-    linux: 'linux',
-    win32: 'windows',
-};
-/**
- * A stable node id that survives restarts, generated on first use and kept in
- * `~/.1agents/session-reader/node.json`.
- *
- * `DREAMMATE_NODE_ID` / `DREAMMATE_NODE_NAME` override it without touching the
- * file, which is what a container or a second instance on one host wants.
- */
-export function nodeIdentity() {
-    const type = PLATFORM_TYPE[process.platform] ?? process.platform;
-    const envId = process.env.DREAMMATE_NODE_ID?.trim();
-    const envName = process.env.DREAMMATE_NODE_NAME?.trim();
-    if (envId && envName)
-        return { node_id: envId, name: envName, type };
-    const file = nodeIdentityPath();
-    let stored = {};
-    try {
-        stored = JSON.parse(fs.readFileSync(file, 'utf8'));
-    }
-    catch {
-        // First run, or an unreadable file we are about to overwrite.
-    }
-    if (!stored.node_id) {
-        stored = { node_id: `node_${randomUUID().replace(/-/g, '').slice(0, 12)}`, name: os.hostname(), type };
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, `${JSON.stringify(stored, null, 2)}\n`);
-    }
-    return {
-        node_id: envId ?? stored.node_id,
-        name: envName ?? stored.name ?? os.hostname(),
-        type,
-    };
-}
+import { nodeIdentity } from '@1agents/dreammate-node';
+import { DEFAULT_PORTS, PROTOCOL_VERSION, } from '@1agents/dreammate-network';
+export { nodeIdentity, PROTOCOL_VERSION };
 /* ---------- Manifest ---------- */
 /**
  * The capabilities this Service answers for. Names are the network-facing
@@ -64,13 +20,20 @@ export const SESSION_CAPABILITIES = [
     'sessions.search',
     'sessions.graph',
 ];
-export function buildManifest(baseUrl) {
-    const identity = nodeIdentity();
+export async function buildManifest(baseUrl) {
+    const identity = await nodeIdentity();
+    // 有 MagicDNS 就用它：`http://scott-mac:7777` 跨网络稳定，不怕 IP 变，
+    // 而请求里的 Host 只是"调用方碰巧用了哪个地址"。
+    const advertised = identity.dnsName
+        ? baseUrl.replace(/\/\/[^/]+/, `//${identity.dnsName}:${new URL(baseUrl).port || String(DEFAULT_PORTS['session-registry'])}`)
+        : baseUrl;
     return {
-        ...identity,
-        tailscale_name: process.env.DREAMMATE_TAILSCALE_NAME?.trim() ?? identity.name,
+        node_id: identity.node_id,
+        name: identity.name,
+        type: identity.type,
+        tailscale_name: identity.dnsName ?? process.env.DREAMMATE_TAILSCALE_NAME?.trim() ?? null,
         online: true,
-        metadata: { protocol_version: PROTOCOL_VERSION },
+        metadata: { protocol_version: PROTOCOL_VERSION, identity_source: identity.source },
         services: [
             {
                 id: 'session-registry',
@@ -78,12 +41,18 @@ export function buildManifest(baseUrl) {
                 kind: 'session_registry',
                 capabilities: [...SESSION_CAPABILITIES],
                 resources: [{ scheme: 'session', description: 'session://<node>/<runtime>/<session_id>' }],
-                access: [{ protocol: 'http', base_url: `${baseUrl}/v1` }],
+                access: [{ protocol: 'http', base_url: `${advertised}/v1` }],
             },
         ],
     };
 }
-/** `session://<node>/<runtime>/<session_id>` — the network-wide address of one session. */
+/**
+ * `session://<node>/<runtime>/<session_id>` — 一个会话在网络中的地址。
+ *
+ * `nodeName` 应该来自 {@link nodeIdentity}，也就是 tailnet 的 DNSName 前缀。
+ * **不要传 `os.hostname()`**：iOS 设备的 hostname 全是 `localhost`，几台手机
+ * 接进来会产出一模一样的 `session://localhost/yima/...`。
+ */
 export function sessionUri(nodeName, provider, id) {
     return `session://${nodeName}/${provider}/${id}`;
 }

package/dist/src/store/read.d.ts

@@ -39,5 +39,13 @@ export interface ListQuery {
  * workspace never silently loses its older sessions to a candidate cap.
  */
 export declare function listSessionRows(db: DatabaseSync, query: ListQuery): SessionRow[];
+/**
+ * Turn starts for one indexed session, without rebuilding it.
+ *
+ * The rule has to stay the rule `turnStarts` applies to a parsed session — a
+ * user event carrying real text opens a turn — so the two are fed to the same
+ * `turnStartsFrom`; only the source of the indices differs.
+ */
+export declare function turnStartsOf(db: DatabaseSync, sessionId: string, eventCount: number): number[];
 export declare function refOf(row: SessionRow): SessionRef;
 export declare function readSession(db: DatabaseSync, row: SessionRow): NormalizedSession;

package/dist/src/store/read.js

@@ -1,3 +1,4 @@
+import { turnStartsFrom } from '../turns.js';
 import { emptyProviderStats, } from '../types.js';
 export function sessionRow(db, id) {
     return db.prepare('SELECT * FROM sessions WHERE id = ?').get(id);
@@ -49,6 +50,21 @@ export function listSessionRows(db, query) {
         'ORDER BY (ended_at IS NULL), ended_at DESC LIMIT ?')
         .all(...params);
 }
+/**
+ * Turn starts for one indexed session, without rebuilding it.
+ *
+ * The rule has to stay the rule `turnStarts` applies to a parsed session — a
+ * user event carrying real text opens a turn — so the two are fed to the same
+ * `turnStartsFrom`; only the source of the indices differs.
+ */
+export function turnStartsOf(db, sessionId, eventCount) {
+    const rows = db
+        .prepare(`SELECT idx FROM events
+        WHERE session_id = ? AND kind = 'user' AND trim(coalesce(text, '')) != ''
+        ORDER BY idx`)
+        .all(sessionId);
+    return turnStartsFrom(rows.map((row) => row.idx), eventCount);
+}
 export function refOf(row) {
     return {
         id: row.native_id,

package/dist/src/turns.d.ts

@@ -1,4 +1,23 @@
 import type { NormalizedSession, TurnDetail, TurnEvent, TurnSummary } from './types.js';
+/**
+ * Turn boundaries from the user messages that open them.
+ *
+ * Split out from `turnStarts` so the index path can feed it the same indices
+ * straight from SQL without materializing the session: a `T` printed by
+ * `search` then means exactly what a `T` printed by `turns` means.
+ */
+export declare function turnStartsFrom(userEventIndices: number[], eventCount: number): number[];
+/**
+ * Turn boundaries: codex records them natively, the others start a new turn on
+ * every user message.
+ */
+export declare function turnStarts(session: NormalizedSession): number[];
+/**
+ * The turn (1-based) an event index falls in, or 0 when it falls before the
+ * first one. Turns tile the event stream, so "the last start at or before the
+ * index" is the whole rule.
+ */
+export declare function turnNoAt(starts: number[], index: number): number;
 export declare function summarizeTurns(session: NormalizedSession): TurnSummary[];
 export declare function turnDetail(session: NormalizedSession, turnNo: number): TurnDetail;
 export interface EventDetail extends TurnEvent {
@@ -7,6 +26,23 @@ export interface EventDetail extends TurnEvent {
     /** Set when the transcript is short and the full copy could not be found. */
     truncationNote?: string;
 }
+/**
+ * How many events one `--event` spec may expand to. Reading a tool call with
+ * its result and the assistant's verdict takes three; a spec asking for
+ * hundreds wanted `turn <n>` instead, and silently truncating would be worse
+ * than saying so.
+ */
+export declare const MAX_EVENT_SPAN = 50;
+/**
+ * `214`, `214-218`, `214,216,218` and any mix, as ascending unique indices.
+ *
+ * Ranges are clipped to the session — asking for `210-999` on a 300-event
+ * session is a reasonable way to say "to the end" — while a bare index is left
+ * alone so an out-of-range one still errors naming the number that was typed.
+ */
+export declare function parseEventSpec(spec: string, eventCount: number): number[];
+/** `eventDetail` over a spec: `214`, `214-218`, `214,216,218`. */
+export declare function eventDetails(session: NormalizedSession, spec: string): Promise<EventDetail[]>;
 /**
  * Tier three: one event with its untruncated payload. Antigravity shortens long
  * step output in the transcript and keeps the full copy under `steps/<n>/`.