dsh-plugin-sessiongraph-sessions 0.0.0-stage → 0.1.0

package/lib/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `dsh-plugin-sessiongraph-sessions`.
+ * @module dsh-plugin-sessiongraph-sessions/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "sessiongraph-sessions-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/invariant.js

@@ -0,0 +1,23 @@
+/**
+ * Package-owned invariant companion for `dsh-plugin-sessiongraph-sessions`.
+ * @module dsh-plugin-sessiongraph-sessions/invariant
+ */
+const PACKAGE_NAME = 'dsh-plugin-sessiongraph-sessions';
+/** Cordis companion plugin name. */
+export const name = 'sessiongraph-sessions-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: an indexer is a write path with no enumerable owned relation — it publishes
+ * no service, holds no cross-plugin registry, and its only output is a file the store verifies
+ * through `meta.schema_version`.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

package/lib/live.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Index the sessions the host still holds in memory.
+ *
+ * A session log is written when the session ends (or is checkpointed), so the conversation running
+ * right now is invisible to a file scan: asking "where did I say X" mid-session would miss the very
+ * words just typed. The host's `ctx.sessionQuery` can list live sessions and replay their event log,
+ * which is the one thing a file scanner cannot see.
+ *
+ * This is a **supplement**, never a second path over the same data: file scanning, multi-frame
+ * decompression and mtime-based incrementality stay the primary source, and this module only adds
+ * the handful of sessions that are still moving. The host interface is declared structurally rather
+ * than imported from a `@deepseek-ai/dsh-*` package — a host utility that exists in one DSH line and
+ * not another turns into a load-time failure that removes the whole plugin.
+ * @module dsh-plugin-sessiongraph-sessions/live
+ */
+import type { SessionParseLimits } from './parse.ts';
+import type { IndexedSession } from './write.ts';
+/**
+ * Prefix of the synthetic source path a live session is recorded under. It is not a filesystem
+ * path: the row is rebuilt from the in-memory log on every run, and the marker is what lets the
+ * file scanner tell those rows apart from ones a vanished log should remove.
+ */
+export declare const LIVE_SOURCE_PREFIX = "live://";
+/**
+ * The slice of the host's `sessionQuery` service this indexer uses.
+ *
+ * `listSessions` answers metadata only; `readSession` replays one session's event log, returning the
+ * header, the count of events inherited from a parent context, and the events themselves — the same
+ * shape the on-disk JSONL carries after its header line.
+ */
+export interface SessionQueryService {
+    /**
+     * List every session the host knows about, newest first, with a `live` flag on the in-memory ones.
+     * @returns one entry per session.
+     */
+    listSessions(): Promise<readonly unknown[]>;
+    /**
+     * Read one session's header and full event log.
+     * @param sessionId - the session to replay.
+     * @returns the session record, as the host assembles it.
+     */
+    readSession(sessionId: string): Promise<unknown>;
+}
+/** Bounds and filters the live pass shares with the file pass. */
+export interface LiveIndexOptions {
+    /** Most live sessions to rebuild in one run; the rest are reported as skipped. */
+    readonly maxLiveSessions: number;
+    /** Entry-text bounds, identical to the file path's. */
+    readonly limits: SessionParseLimits;
+    /**
+     * Whether a session is in the run's scope. The same predicate the file path applies, so a scoped
+     * index covers a live session and its later file under exactly the same rules.
+     */
+    readonly inScope: (workspace: string, sessionId: string) => boolean;
+}
+/** What the live pass collected. */
+export interface LiveIndexResult {
+    /** Sessions to (re)write, already parsed. */
+    readonly sessions: IndexedSession[];
+    /** Live sessions left out because of {@link LiveIndexOptions.maxLiveSessions}. */
+    readonly skipped: number;
+}
+/**
+ * Collect and parse the live sessions in scope.
+ *
+ * A live session has no stable version — its log grows with every step — so it is replayed in full
+ * on every run rather than compared against a recorded mtime. That is cheap only because there are
+ * normally one or two of them, which is why the cap exists: a host that reports dozens of live
+ * sessions must not turn one index run into dozens of log replays.
+ * @param query - the host's session-query service.
+ * @param options - the cap, entry bounds, and scope predicate.
+ * @returns the parsed sessions to write, and how many the cap left out.
+ */
+export declare function collectLiveSessions(query: SessionQueryService, options: LiveIndexOptions): Promise<LiveIndexResult>;
+/**
+ * The synthetic source path a live session is recorded under.
+ * @param sessionId - the session id.
+ * @returns the marker path.
+ */
+export declare function liveSourcePath(sessionId: string): string;
+//# sourceMappingURL=live.d.ts.map

package/lib/live.js

@@ -0,0 +1,97 @@
+/**
+ * Index the sessions the host still holds in memory.
+ *
+ * A session log is written when the session ends (or is checkpointed), so the conversation running
+ * right now is invisible to a file scan: asking "where did I say X" mid-session would miss the very
+ * words just typed. The host's `ctx.sessionQuery` can list live sessions and replay their event log,
+ * which is the one thing a file scanner cannot see.
+ *
+ * This is a **supplement**, never a second path over the same data: file scanning, multi-frame
+ * decompression and mtime-based incrementality stay the primary source, and this module only adds
+ * the handful of sessions that are still moving. The host interface is declared structurally rather
+ * than imported from a `@deepseek-ai/dsh-*` package — a host utility that exists in one DSH line and
+ * not another turns into a load-time failure that removes the whole plugin.
+ * @module dsh-plugin-sessiongraph-sessions/live
+ */
+import { parseSessionEvents } from "./parse.js";
+/**
+ * Prefix of the synthetic source path a live session is recorded under. It is not a filesystem
+ * path: the row is rebuilt from the in-memory log on every run, and the marker is what lets the
+ * file scanner tell those rows apart from ones a vanished log should remove.
+ */
+export const LIVE_SOURCE_PREFIX = 'live://';
+/**
+ * Collect and parse the live sessions in scope.
+ *
+ * A live session has no stable version — its log grows with every step — so it is replayed in full
+ * on every run rather than compared against a recorded mtime. That is cheap only because there are
+ * normally one or two of them, which is why the cap exists: a host that reports dozens of live
+ * sessions must not turn one index run into dozens of log replays.
+ * @param query - the host's session-query service.
+ * @param options - the cap, entry bounds, and scope predicate.
+ * @returns the parsed sessions to write, and how many the cap left out.
+ */
+export async function collectLiveSessions(query, options) {
+    const listed = await query.listSessions();
+    const candidates = [];
+    for (const entry of listed) {
+        const record = asRecord(entry);
+        if (record === undefined || record.live !== true)
+            continue;
+        const header = asRecord(record.header);
+        const id = stringField(header, 'id');
+        if (id === undefined || id === '')
+            continue;
+        const cwd = stringField(header, 'cwd') ?? '';
+        if (!options.inScope(cwd, id))
+            continue;
+        candidates.push({ id, cwd });
+    }
+    // `listSessions` is documented newest-first; taking from the front keeps the most recent
+    // conversations searchable when a host reports more live sessions than the cap allows.
+    const chosen = candidates.slice(0, options.maxLiveSessions);
+    const skipped = candidates.length - chosen.length;
+    const sessions = [];
+    for (const candidate of chosen) {
+        const record = asRecord(await query.readSession(candidate.id));
+        const events = Array.isArray(record?.events) ? record.events : [];
+        const session = parseSessionEvents(record?.session, events, candidate.id, options.limits);
+        sessions.push({
+            session,
+            sourcePath: liveSourcePath(candidate.id),
+            // No version to compare: the live row is rebuilt every run, never skipped.
+            mtime: 0,
+            size: 0,
+        });
+    }
+    return { sessions, skipped };
+}
+/**
+ * The synthetic source path a live session is recorded under.
+ * @param sessionId - the session id.
+ * @returns the marker path.
+ */
+export function liveSourcePath(sessionId) {
+    return `${LIVE_SOURCE_PREFIX}${sessionId}`;
+}
+/**
+ * Narrow a value to a plain object.
+ * @param value - candidate.
+ * @returns the object, or undefined.
+ */
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * Read a string field from a record.
+ * @param record - the record, possibly absent.
+ * @param key - field name.
+ * @returns the string, or undefined when the field is absent or not a string.
+ */
+function stringField(record, key) {
+    const value = record?.[key];
+    return typeof value === 'string' ? value : undefined;
+}
+//# sourceMappingURL=live.js.map

package/lib/parse.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Read one harness session log into the normalized shape the indexer writes.
+ *
+ * The log is a zstd-compressed JSONL file whose first line is a flat session header and whose later
+ * lines are events. It is NOT one zstd stream: the harness appends one complete zstd frame per write,
+ * so a real log is thousands of concatenated frames. `zstdDecompressSync` stops at the first frame's
+ * end, which is why {@link decompressSessionLog} walks the frames itself.
+ *
+ * What is indexed is the readable conversation, not the transcript feed: a human's messages, the
+ * model's visible text (never its reasoning), tool invocations (name and arguments, never results),
+ * and the session's final title. Injected context — runtime/skill/time blocks, team and agent
+ * messages, plugin notifications — arrives as `user/message` events too, so the `source.kind` check
+ * is what keeps them out of the index; on a real machine those injections outnumber real human
+ * messages by more than an order of magnitude.
+ *
+ * Parsing is tolerant per line: a truncated or corrupt line is skipped rather than failing the whole
+ * session, because an interrupted append must cost one event, not the conversation.
+ * @module dsh-plugin-sessiongraph-sessions/parse
+ */
+import type { SessiongraphEntryKind } from 'dsh-plugin-sessiongraph-service';
+/** Bounds applied while normalizing one session's entries. */
+export interface SessionParseLimits {
+    /** Longest message text stored whole; longer text is clipped. */
+    readonly maxEntryChars: number;
+    /** Longest tool invocation text (name plus arguments) stored whole. */
+    readonly toolCallChars: number;
+}
+/** One searchable entry extracted from a session log. */
+export interface ParsedEntry {
+    /** Event sequence number inside the session. */
+    readonly seq: number;
+    /** Event timestamp, epoch milliseconds. */
+    readonly time: number;
+    /** Turn the entry belongs to, when the event records one. */
+    readonly turn: number | undefined;
+    /** What the entry is. */
+    readonly kind: SessiongraphEntryKind;
+    /** Entry text, already bounded by the parse limits. */
+    readonly text: string;
+    /** True when the stored text is a clipped prefix. */
+    readonly clipped: boolean;
+}
+/** One session log, normalized for the index. */
+export interface ParsedSession {
+    /** Session id exactly as the header records it (`session-…` or bare uuid, never rewritten). */
+    readonly id: string;
+    /** Working directory the session ran in. */
+    readonly cwd: string;
+    /** Epoch milliseconds of the session's first event. */
+    readonly createdAt: number;
+    /** Epoch milliseconds of the session's last event. */
+    readonly lastAt: number;
+    /** Final session title, when the log records one. */
+    readonly title: string | undefined;
+    /** Parent session id when this session was delegated from another. */
+    readonly parentSession: string | undefined;
+    /** Session origin label (`user`, `subagent`, …), when recorded. */
+    readonly origin: string | undefined;
+    /** Agent preset the session ran under, when recorded. */
+    readonly agentPreset: string | undefined;
+    /** Number of turns the session contains. */
+    readonly turns: number;
+    /** Searchable entries in chronological order. */
+    readonly entries: ParsedEntry[];
+}
+/**
+ * Decompress a session log, one zstd frame at a time.
+ *
+ * Node's `zstdDecompressSync` decodes the first frame of its input and stops, so a log written by
+ * repeated appends must be split into frames first. The frame structure is parsed exactly (RFC 8878
+ * header and block headers), which is why a magic-byte sequence inside a compressed block cannot
+ * split a frame incorrectly; the magic scan remains as a fallback for a frame layout this parser
+ * cannot describe.
+ * @param buffer - the raw log file contents.
+ * @returns the concatenated decompressed bytes of every frame.
+ */
+export declare function decompressSessionLog(buffer: Buffer): Buffer;
+/**
+ * Parse one session log.
+ * @param buffer - the raw log file contents.
+ * @param fallbackId - id to use when the header is missing or has none (the session directory name).
+ * @param limits - bounds applied to stored entry text.
+ * @returns the normalized session.
+ */
+export declare function parseSessionLog(buffer: Buffer, fallbackId: string, limits: SessionParseLimits): ParsedSession;
+/**
+ * Parse an already-split JSONL log, keeping the harness's first-line header convention.
+ * @param lines - the decompressed log split on newline characters.
+ * @param fallbackId - id to use when the header is missing or has none.
+ * @param limits - bounds applied to stored entry text.
+ * @returns the normalized session.
+ */
+export declare function parseSessionLines(lines: readonly string[], fallbackId: string, limits: SessionParseLimits): ParsedSession;
+/**
+ * Parse a session the host already holds in memory.
+ *
+ * The live view carries the header and the raw events as two values, which is the same information a
+ * log's first line and remaining lines carry. Both paths normalize through {@link normalizeSession},
+ * so a live session and its later on-disk copy cannot disagree about what is searchable.
+ * @param header - the session header object, as the host reports it.
+ * @param events - raw event objects, shaped like the JSONL lines that follow the header.
+ * @param fallbackId - id to use when the header has none.
+ * @param limits - bounds applied to stored entry text.
+ * @returns the normalized session.
+ */
+export declare function parseSessionEvents(header: unknown, events: readonly unknown[], fallbackId: string, limits: SessionParseLimits): ParsedSession;
+//# sourceMappingURL=parse.d.ts.map