@1agents/session-reader 0.4.0 → 0.5.0

package/dist/src/turns.js

@@ -40,34 +40,63 @@ function assessTurn(events, native, nextPrompt, nudgeCount) {
     return { status, evidence };
 }
 /**
- * Turn boundaries: codex records them natively, the others start a new turn on
- * every user message.
+ * 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.
  */
-function boundaries(session) {
-    const starts = session.turns
-        .filter((turn) => turn.kind === 'user' && turn.text?.trim())
-        .map((turn) => turn.index);
-    if (!starts.length && session.turns.length)
-        return [0];
+export function turnStartsFrom(userEventIndices, eventCount) {
+    const starts = [...userEventIndices];
+    if (!starts.length)
+        return eventCount ? [0] : [];
     // Anything before the first user message belongs to turn 1.
-    if (starts[0] !== 0 && session.turns.length)
+    if (starts[0] !== 0 && eventCount)
         starts[0] = 0;
     return starts;
 }
+/**
+ * Turn boundaries: codex records them natively, the others start a new turn on
+ * every user message.
+ */
+export function turnStarts(session) {
+    return turnStartsFrom(session.turns.filter((turn) => turn.kind === 'user' && turn.text?.trim()).map((turn) => turn.index), session.turns.length);
+}
+/**
+ * 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 function turnNoAt(starts, index) {
+    let lo = 0;
+    let hi = starts.length - 1;
+    let found = 0;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (starts[mid] <= index) {
+            found = mid + 1;
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return found;
+}
 /**
  * Providers fire `task_started` a few seconds *before* the first event of the
  * turn it opens, so a boundary belongs to the next turn that starts, not to
  * the turn whose window happens to contain it.
  */
-function boundariesByTurn(declared, turnStarts) {
+function boundariesByTurn(declared, startTimes) {
     const byTurn = new Map();
     for (const boundary of declared) {
         if (!boundary.startedAt)
             continue;
         const at = Date.parse(boundary.startedAt);
-        let owner = turnStarts.findIndex((start) => start !== undefined && Date.parse(start) >= at);
+        let owner = startTimes.findIndex((start) => start !== undefined && Date.parse(start) >= at);
         if (owner === -1)
-            owner = turnStarts.length - 1;
+            owner = startTimes.length - 1;
         const list = byTurn.get(owner) ?? [];
         list.push(boundary);
         byTurn.set(owner, list);
@@ -75,7 +104,7 @@ function boundariesByTurn(declared, turnStarts) {
     return byTurn;
 }
 export function summarizeTurns(session) {
-    const starts = boundaries(session);
+    const starts = turnStarts(session);
     const workspace = session.ref.workspace;
     const declared = session.stats.turnBoundaries;
     const nativeByTurn = boundariesByTurn(declared, starts.map((start) => session.turns[start]?.timestamp));
@@ -138,6 +167,51 @@ export function turnDetail(session, turnNo) {
         throw new Error(`no turn ${turnNo} (session has ${summaries.length})`);
     return { summary, events: session.turns.slice(summary.events[0], summary.events[1] + 1) };
 }
+/**
+ * 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 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 function parseEventSpec(spec, eventCount) {
+    const indices = new Set();
+    for (const part of spec.split(',').map((piece) => piece.trim()).filter(Boolean)) {
+        const range = /^(\d+)\s*[-–]\s*(\d+)$/.exec(part);
+        if (range) {
+            const [from, to] = [Number(range[1]), Number(range[2])].sort((a, b) => a - b);
+            for (let i = Math.max(0, from); i <= Math.min(to, eventCount - 1); i++)
+                indices.add(i);
+            continue;
+        }
+        if (!/^\d+$/.test(part)) {
+            throw new Error(`--event 无法解析：${part}（用 214、214-218 或 214,216,218）`);
+        }
+        indices.add(Number(part));
+    }
+    if (!indices.size)
+        throw new Error(`--event ${spec} 不含该会话的任何事件（0–${eventCount - 1}）`);
+    if (indices.size > MAX_EVENT_SPAN) {
+        throw new Error(`--event ${spec} 展开为 ${indices.size} 个事件，超过上限 ${MAX_EVENT_SPAN}；` +
+            `缩小区间，或用 1session turn <id> <轮次> 看整轮概要`);
+    }
+    return [...indices].sort((a, b) => a - b);
+}
+/** `eventDetail` over a spec: `214`, `214-218`, `214,216,218`. */
+export async function eventDetails(session, spec) {
+    const indices = parseEventSpec(spec, session.turns.length);
+    const details = [];
+    for (const index of indices)
+        details.push(await eventDetail(session, index));
+    return details;
+}
 /**
  * Tier three: one event with its untruncated payload. Antigravity shortens long
  * step output in the transcript and keeps the full copy under `steps/<n>/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agents/session-reader",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Read Plane: cross-agent session discovery, turn inspection, workspace aggregation and distillation from raw local session files.",
   "keywords": [
     "claude-code",
@@ -57,6 +57,7 @@
     "typescript": "^5.7.2"
   },
   "dependencies": {
-    "@1agents/dreammate-network": "^0.1.0"
+    "@1agents/dreammate-network": "^0.3.0",
+    "@1agents/dreammate-node": "^0.1.0"
   }
 }

package/skills/1session/SKILL.md

@@ -29,7 +29,7 @@ build, not a hang.
 
 ## Pick the command from the question
 
-Users ask about the past in roughly five shapes. Match the shape, don't run the
+Users ask about the past in a handful of shapes. Match the shape, don't run the
 whole ladder by reflex:
 
 | The user is asking | Start with |
@@ -37,9 +37,17 @@ whole ladder by reflex:
 | "what have I been doing / what sessions exist" | `list` |
 | "where did I discuss X" (a word, path, error string, package name) | `search` |
 | "what happened in that session" (they named or you found one) | `overview` |
-| "what exactly did it do at step N" | `turns`, then `turn <n>` |
+| "find where we talked about X / which turn was that" | `turns` |
+| "what exactly did it do at step N" | `turn <n>`, then `--event k` |
 | "what did all the agents do in this project" | `workspace` |
 
+"What happened in that session" and "find where we talked about X" look like the
+same question and are not. `overview` compresses a session into statistics and
+an end state — the answer to *what it did*, and the one form that throws away
+what locating a conversation needs. `turns` keeps the ▸user/◂agent rhythm one
+line at a time, so you find the moment by scanning: an order of magnitude faster
+for "where in here did that happen".
+
 `<session-id>` accepts a full id, a prefix of 6+ characters, or a raw file path.
 Session ids shown by `list` and `search` are 8-char prefixes — pass them straight
 back in.
@@ -52,6 +60,16 @@ why a choice was made, what was tried and abandoned, an error and how it was
 worked around, work done over ssh or in a UI, and anything spanning projects or
 agents. The strongest answers use both — git for what changed, sessions for why.
 
+**Sessions date, and the end state dates fastest.** For any question about how
+things *are right now* — a credential, an env var, which version is installed,
+whether a file still exists — a session can only tell you when it was last true.
+Go and check. A transcript records what was said and what exit code came back,
+never the effect: a command can exit 0 having read an empty input and written an
+empty value; a turn can conclude "there are three copies now" when one was a
+shell function that never hit disk; "X is configured" can be accurate and three
+weeks stale. Say which turn the claim comes from and when, then verify it with
+the system itself before the user acts on it.
+
 ## Scope is the thing people get wrong
 
 `list`, `search` and `index --all` default to **the current pwd and everything
@@ -80,11 +98,32 @@ Each rung narrows the evidence, so climb only as far as the question needs.
 1session overview 3ab9fe0e                   # layer 1: what that session did
 1session turns 3ab9fe0e                      # layer 2: turn-by-turn summary
 1session turn 3ab9fe0e 9 --event 491         # layer 3: one tool call, untruncated
+1session turn 3ab9fe0e 9 --event 491-493     # …with its result and the verdict
 ```
 
-`overview` is the highest-value single call: goal, instruction trail, end state
-(last request, last successful command, last failed command, last file touched),
-and counts of turns/files/commands/failures/commits/tokens.
+Every `search` hit is prefixed with the handle that drills into it, and each
+session prints the command ready to paste:
+
+```text
+### claude 3ab9fe0e  2026-09-13T03:33:32Z → 2026-09-13T05:52:59Z  (2 命中)
+  T9 · E491 tool_call(Bash)  …curl --max-time 5 …
+    ↳ 1session turn 3ab9fe0e 9 --event 491
+```
+
+Reading one tool call usually means reading three events — the call, its result,
+and what the agent concluded — so `--event` takes `491-493` and `491,495,502` as
+well as a single number.
+
+`search` hides the invocation you are running right now (and what it printed)
+from its own results, since a live session is indexed as it happens and would
+otherwise match itself first. It says how many it folded; `--include-self` shows
+them.
+
+`overview` is the highest-value single call *for what a session did*: goal,
+instruction trail, end state (last request, last successful command, last failed
+command, last file touched), and counts of
+turns/files/commands/failures/commits/tokens. For *where in a session something
+happened*, start at `turns` instead.
 
 Useful narrower ledgers when the question is specifically about one dimension:
 `commands <id> [--failed]`, `files <id>`, `errors <id>`, `jobs <id>`,
@@ -108,7 +147,9 @@ you "the session is blocked on Y" — sections that would require interpretation
 say so explicitly instead of guessing. **That interpretation is your job**, and
 you should keep the two layers visibly separate when you answer.
 
-Every fact carries an evidence handle like `E221 · T9` (event 221, turn 9). When
+Every fact carries an evidence handle like `E221 · T9` (event 221, turn 9), and
+so does every search hit — `T9 · E221`, in the order `turn <id> 9 --event 221`
+wants it. When
 you assert something happened, carry the handle or the session id into your
 answer so the user can verify it with one command. A claim about the past that
 can't be traced back to a turn is worth less than saying you didn't find it.

package/skills/1session/references/cli.md

@@ -40,11 +40,24 @@ workspace basename, title.
 1session search <query> [--scope <path>|cwd|global] [--global] [--since 24h]
                 [--limit n] [--provider name]
                 [--kind user,assistant,thinking,tool_call,tool_result]
-                [--regex] [--case] [--context n] [--max-hits n] [--json]
+                [--regex] [--case] [--context n] [--max-hits n]
+                [--include-self] [--json]
 ```
 
 Full-text across sessions; prints matching turns with surrounding context.
 
+Every hit carries `T<turn> · E<event>`, in the order the drill-down wants, and
+each session ends with the command already assembled:
+
+```text
+### claude 3ab9fe0e  2026-09-13T03:33:32Z → 2026-09-13T05:52:59Z  (2 命中)
+  T9 · E491 tool_call(Bash)  …curl --max-time 5 …
+    ↳ 1session turn 3ab9fe0e 9 --event 491
+```
+
+`T?` means the session recorded no turn containing that event — drill in with
+`turns` first. In `--json`, the handle is `match.turn` and `match.index`.
+
 - `--kind user` is the sharpest filter for "what did I ask about X" — it drops
   the tool noise and leaves only the human's own words.
 - `--kind tool_result` finds error text that an agent saw but never quoted back.
@@ -54,6 +67,13 @@ Full-text across sessions; prints matching turns with surrounding context.
 - `--max-hits n` raises the per-session cap when a session is truncated with
   "另有 N 处".
 - `--context n` widens the excerpt around each hit.
+- `--include-self` stops hiding the search's own footprint. By default a
+  `1session` invocation written in the last five minutes, and the result
+  carrying what it printed, are folded out of the hits — the calling agent's
+  session is indexed live, so the query is in it because this command put it
+  there. Only the live transcript can hold an event timestamped now, so no past
+  session is affected, and the count of what was folded is always printed. In
+  `--json` these sessions stay in the array, tagged `self` and `suppressed`.
 
 Search is a SQL prefilter that narrows candidate lines, then a regex verifier
 that decides. Empty queries are rejected rather than matching everything.
@@ -89,12 +109,19 @@ Layer 2. One line per turn: time, duration, event range, file/command/failure
 counts, what the user said, what the agent replied. Use it to find the turn
 number to drill into.
 
-### `turn <id> <n> [--event k]`
+### `turn <id> <n> [--event k|a-b|a,b,c]`
 
-Layer 3. Every event in a turn. With `--event k`, a single tool call with full
-arguments and **untruncated** result — this is the only way to see what a command
+Layer 3. Every event in a turn. With `--event`, the named events with full
+arguments and **untruncated** results — the only way to see what a command
 actually printed.
 
+`--event` takes one index (`491`), a range (`491-493`), a list (`491,495,502`),
+or a mix, up to 50 events in one call; ranges are clipped to the session, so
+`560-999` means "to the end". Reading a tool call usually means reading its
+result and the assistant's verdict too, which is the range form in one process
+instead of three. `--json` returns an object for a bare index and an array for
+anything that asked for more than one.
+
 ### `digest <id> [--focus marketing|review|full]`
 
 Compact narrative: goal, changed files, commands, key moments (需求 / 转向 / 受阻 /
@@ -138,13 +165,20 @@ import the library instead of shelling out repeatedly:
 import {
   listRecentSessions, findSessionsByWorkspace, loadSession, parseSession,
   distillSession, aggregateWorkspaceSessions, searchSessions,
-  buildOverview, summarizeTurns, turnDetail, eventDetail,
+  buildOverview, summarizeTurns, turnDetail, eventDetail, eventDetails,
+  turnStarts, turnNoAt,
 } from '@1agents/session-reader';
 
 const hits = await searchSessions('小红书', { workspace: process.cwd(), since: '24h', kinds: ['user'] });
+hits[0].matches[0].turn;                       // the T of the T·E handle
 const overview = buildOverview(await loadSession('01a0907c'));
 const full = await eventDetail(session, 11);   // untruncated tool output
+const around = await eventDetails(session, '11-13');
 ```
 
+`searchSessions` takes `selfSessionId` to name the caller explicitly (it
+defaults to `SESSION_READER_CALLER_SESSION`); hits from it come back tagged
+`self` rather than dropped, so a caller decides whether to show them.
+
 `loadSession` goes through the index; `parseSession` reads the source file
 directly. Requires Node.js >= 22.5 (built-in `node:sqlite`), zero runtime deps.