@1agents/session-reader 0.3.0 → 0.5.0

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

@@ -0,0 +1,32 @@
+/**
+ * `1session serve` — session-reader 作为 DreamMate Network 的第一个标准 Service。
+ *
+ * 它把本地 Read Plane 原样暴露成网络能力：`1session overview <id>` 成为
+ * `sessions.read`。**不重新实现索引与事实层**，只是换一个调用入口。
+ *
+ * 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
+     * history and whatever secrets happened to scroll past, so going beyond this
+     * machine has to be a deliberate act — pass the tailnet address explicitly.
+     */
+    host?: string;
+    /** When set, every request must carry it as `Authorization: Bearer <token>`. */
+    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

@@ -0,0 +1,204 @@
+/**
+ * `1session serve` — session-reader 作为 DreamMate Network 的第一个标准 Service。
+ *
+ * 它把本地 Read Plane 原样暴露成网络能力：`1session overview <id>` 成为
+ * `sessions.read`。**不重新实现索引与事实层**，只是换一个调用入口。
+ *
+ * HTTP 层不引第三方框架，只用 node:http；端口与协议类型来自 L0 包。
+ */
+import http from 'node:http';
+import { listRecentSessions, loadSession } from '../resolver.js';
+import { buildOverview } from '../overview.js';
+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, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': Buffer.byteLength(payload),
+    });
+    res.end(payload);
+};
+const q = (ctx, name) => ctx.url.searchParams.get(name) ?? undefined;
+const qn = (ctx, name) => {
+    const raw = q(ctx, name);
+    if (raw === undefined)
+        return undefined;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : undefined;
+};
+/**
+ * `?scope=` is a path whose subtree is included; omitting it means the whole
+ * machine. The CLI defaults to the cwd instead, which is meaningless for a
+ * long-running server.
+ */
+const scopeOf = (ctx) => {
+    const scope = q(ctx, 'scope');
+    return scope && scope !== 'global' ? canonicalizePath(scope) : undefined;
+};
+/** Records `caller --references--> target` while the read is happening. */
+async function noteRead(verb, target, caller) {
+    if (!caller)
+        return;
+    try {
+        const { openStore } = await import('../store/db.js');
+        const { captureRuntimeEdge } = await import('../store/edges.js');
+        captureRuntimeEdge(await openStore(), verb, target, caller);
+    }
+    catch {
+        // An edge is a nice-to-have; never fail the read over it.
+    }
+}
+async function route(ctx) {
+    const { pathname } = ctx.url;
+    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: await buildManifest(ctx.url.origin) };
+    }
+    if (pathname === '/v1/sessions') {
+        const refs = await listRecentSessions({
+            limit: qn(ctx, 'limit') ?? 20,
+            workspace: scopeOf(ctx),
+            since: q(ctx, 'since'),
+            provider: q(ctx, 'provider'),
+            useIndex: true,
+        });
+        return {
+            status: 200,
+            body: {
+                node: identity.name,
+                sessions: refs.map((ref) => ({ ...ref, uri: sessionUri(identity.name, ref.provider, ref.id) })),
+            },
+        };
+    }
+    const detail = /^\/v1\/sessions\/([^/]+)(\/turns)?$/.exec(pathname);
+    if (detail) {
+        const id = decodeURIComponent(detail[1]);
+        const wantTurns = detail[2] !== undefined;
+        const session = await loadSession(id, { useIndex: true });
+        await noteRead(wantTurns ? 'turns' : 'overview', id, ctx.caller);
+        const uri = sessionUri(identity.name, session.ref.provider, session.ref.id);
+        return wantTurns
+            ? { status: 200, body: { uri, turns: summarizeTurns(session) } }
+            : { status: 200, body: { uri, ...buildOverview(session) } };
+    }
+    if (pathname === '/v1/search') {
+        const query = q(ctx, 'q') ?? q(ctx, 'query');
+        if (!query)
+            return { status: 400, body: { error: 'missing ?q=' } };
+        const hits = await searchSessions(query, {
+            workspace: scopeOf(ctx),
+            since: q(ctx, 'since'),
+            limit: qn(ctx, 'limit'),
+            provider: q(ctx, 'provider'),
+            kinds: q(ctx, 'kind')?.split(',').map((k) => k.trim()).filter(Boolean),
+            regex: q(ctx, 'regex') === 'true',
+            caseSensitive: q(ctx, 'case') === 'true',
+            context: qn(ctx, 'context'),
+            maxPerSession: qn(ctx, 'max-hits'),
+            useIndex: true,
+        });
+        return {
+            status: 200,
+            body: {
+                query,
+                total: hits.reduce((sum, hit) => sum + hit.totalMatches, 0),
+                hits: hits.map((hit) => ({
+                    ...hit,
+                    uri: sessionUri(identity.name, hit.session.provider, hit.session.id),
+                })),
+            },
+        };
+    }
+    const graph = /^\/v1\/graph\/([^/]+)$/.exec(pathname);
+    if (graph) {
+        const id = decodeURIComponent(graph[1]);
+        const { openStore } = await import('../store/db.js');
+        const { edgeEvidence, edgesOf } = await import('../store/edges.js');
+        const { findSessionRow } = await import('../store/read.js');
+        await loadSession(id, { useIndex: true }); // make sure it is indexed first
+        await noteRead('graph', id, ctx.caller);
+        const db = await openStore();
+        const row = findSessionRow(db, id);
+        if (!row)
+            return { status: 404, body: { error: `session not found: ${id}` } };
+        const edges = edgesOf(db, row.id).map((edge) => ({
+            ...edge,
+            evidence: edgeEvidence(db, edge.from, edge.to, edge.relation),
+        }));
+        return { status: 200, body: { session: row.id, edges } };
+    }
+    return { status: 404, body: { error: `no route: ${pathname}` } };
+}
+export function createServer(options = {}) {
+    return http.createServer((req, res) => {
+        void (async () => {
+            try {
+                if (req.method !== 'GET' && req.method !== 'HEAD') {
+                    return json(res, 405, { error: 'read-only service: GET only' });
+                }
+                const url = new URL(req.url ?? '/', options.baseUrl ?? `http://${req.headers.host ?? 'localhost'}`);
+                if (options.token) {
+                    const bearer = /^Bearer (.+)$/.exec(req.headers.authorization ?? '')?.[1];
+                    if (bearer !== options.token)
+                        return json(res, 401, { error: 'unauthorized' });
+                }
+                const caller = req.headers['x-caller-session'];
+                const { status, body } = await route({
+                    url,
+                    caller: typeof caller === 'string' ? caller : undefined,
+                });
+                json(res, status, body);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                // A bad session id reads as "not found", not as a server fault.
+                json(res, /not found|missing|no session/i.test(message) ? 404 : 500, { error: message });
+            }
+        })();
+    });
+}
+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 ?? DEFAULT_PORT, host, resolve));
+    const { port } = server.address();
+    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 历史、密钥）将对该网络开放。`);
+    }
+    return server;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * session-reader 作为 DreamMate Network Service 时的 manifest 构建。
+ *
+ * 节点身份不在这里实现——它是每台机器的公共事实，由 `@1agents/dreammate-node`
+ * 统一提供（优先 tailnet，拿不到回退本地）。本机所有服务读到同一份，不会各自
+ * 生成 id 把一台机器裂成几个 Node。
+ */
+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): 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

@@ -0,0 +1,58 @@
+/**
+ * session-reader 作为 DreamMate Network Service 时的 manifest 构建。
+ *
+ * 节点身份不在这里实现——它是每台机器的公共事实，由 `@1agents/dreammate-node`
+ * 统一提供（优先 tailnet，拿不到回退本地）。本机所有服务读到同一份，不会各自
+ * 生成 id 把一台机器裂成几个 Node。
+ */
+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
+ * spelling of the CLI verbs: `1session overview` is `sessions.read`.
+ */
+export const SESSION_CAPABILITIES = [
+    'sessions.list',
+    'sessions.read',
+    'sessions.turns',
+    'sessions.search',
+    'sessions.graph',
+];
+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 {
+        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, identity_source: identity.source },
+        services: [
+            {
+                id: 'session-registry',
+                name: 'session-reader',
+                kind: 'session_registry',
+                capabilities: [...SESSION_CAPABILITIES],
+                resources: [{ scheme: 'session', description: 'session://<node>/<runtime>/<session_id>' }],
+                access: [{ protocol: 'http', base_url: `${advertised}/v1` }],
+            },
+        ],
+    };
+}
+/**
+ * `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/edges.d.ts

@@ -27,7 +27,13 @@ export declare function deriveEdges(db: DatabaseSync, id: string, session: Norma
  * Injected by a hook or the ACP context as `SESSION_READER_CALLER_SESSION`;
  * absent everywhere else, in which case nothing is written.
  */
-export declare function captureRuntimeEdge(db: DatabaseSync, verb: string, target: string): void;
+export declare function captureRuntimeEdge(db: DatabaseSync, verb: string, target: string, 
+/**
+ * Who is doing the reading. Defaults to the CLI's injected caller; `1session
+ * serve` passes the `X-Caller-Session` header instead, so one process can
+ * serve several callers without going through the environment.
+ */
+callerId?: string | undefined): void;
 export interface EdgeView {
     from: string;
     to: string;

package/dist/src/store/edges.js

@@ -102,8 +102,14 @@ export function deriveEdges(db, id, session) {
  * Injected by a hook or the ACP context as `SESSION_READER_CALLER_SESSION`;
  * absent everywhere else, in which case nothing is written.
  */
-export function captureRuntimeEdge(db, verb, target) {
-    const caller = process.env.SESSION_READER_CALLER_SESSION?.trim();
+export function captureRuntimeEdge(db, verb, target, 
+/**
+ * Who is doing the reading. Defaults to the CLI's injected caller; `1session
+ * serve` passes the `X-Caller-Session` header instead, so one process can
+ * serve several callers without going through the environment.
+ */
+callerId = process.env.SESSION_READER_CALLER_SESSION) {
+    const caller = callerId?.trim();
     const relation = VERB_RELATION[verb];
     if (!caller || !relation)
         return;

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,