pi-sessions 0.6.0 → 0.7.1

package/extensions/{session-messaging/pi → shared/session-broker}/client.ts

@@ -1,20 +1,17 @@
 import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
 import net from "node:net";
-import { readFrames, writeFrame } from "../shared/framing.ts";
-import {
-  BROKER_FRAME_SCHEMA,
-  type SessionMessagingBrokerFrame,
-  type SessionMessagingSessionInfo,
-} from "../shared/protocol.ts";
-import { getSessionMessagingSocketPath } from "../shared/socket-path.ts";
+import { readFrames, writeFrame } from "./framing.ts";
+import { BROKER_FRAME_SCHEMA, type SessionMessagingBrokerFrame } from "./protocol.ts";
+import { getSessionMessagingSocketPath } from "./socket-path.ts";
+
 export const INCOMING_SESSION_MESSAGE_EVENT = "session_messaging.incoming_message";
 
 const REQUEST_TIMEOUT_MS = 10_000;
 const SOCKET_PATH = getSessionMessagingSocketPath();
 
 interface PendingListRequest {
-  resolve(sessions: SessionMessagingSessionInfo[]): void;
+  resolve(sessionIds: string[]): void;
   reject(error: Error): void;
   timeout: NodeJS.Timeout;
 }
@@ -42,19 +39,19 @@ export interface SendSessionMessageOptions {
 
 export class SessionMessagingClient extends EventEmitter {
   private socket: net.Socket | undefined;
-  private session: SessionMessagingSessionInfo | undefined;
+  private sessionId: string | undefined;
   private pendingLists = new Map<string, PendingListRequest>();
   private pendingSends = new Map<string, PendingSendRequest>();
 
   get isConnected(): boolean {
-    return Boolean(this.socket && !this.socket.destroyed && this.socket.writable && this.session);
+    return Boolean(this.socket && !this.socket.destroyed && this.socket.writable && this.sessionId);
   }
 
-  get registeredSession(): SessionMessagingSessionInfo | undefined {
-    return this.session;
+  get registeredSessionId(): string | undefined {
+    return this.sessionId;
   }
 
-  async connect(session: SessionMessagingSessionInfo): Promise<void> {
+  async connect(sessionId: string): Promise<void> {
     if (this.isConnected) {
       return;
     }
@@ -112,7 +109,7 @@ export class SessionMessagingClient extends EventEmitter {
       void this.readSocket(socket);
 
       socket.setKeepAlive(true, 5_000);
-      writeFrame(socket, { type: "register", session });
+      writeFrame(socket, { type: "register", sessionId });
     });
   }
 
@@ -128,7 +125,7 @@ export class SessionMessagingClient extends EventEmitter {
     this.cleanup();
   }
 
-  listSessions(): Promise<SessionMessagingSessionInfo[]> {
+  listSessionIds(): Promise<string[]> {
     const socket = this.requireSocket();
     const requestId = randomUUID();
 
@@ -197,7 +194,7 @@ export class SessionMessagingClient extends EventEmitter {
   private handleFrame(frame: SessionMessagingBrokerFrame): void {
     switch (frame.type) {
       case "registered":
-        this.session = frame.session;
+        this.sessionId = frame.sessionId;
         this.emit("registered");
         break;
       case "register_failed":
@@ -208,7 +205,7 @@ export class SessionMessagingClient extends EventEmitter {
         if (!pending) return;
         clearTimeout(pending.timeout);
         this.pendingLists.delete(frame.requestId);
-        pending.resolve(frame.sessions);
+        pending.resolve(frame.sessionIds);
         break;
       }
       case "incoming":
@@ -233,7 +230,7 @@ export class SessionMessagingClient extends EventEmitter {
   }
 
   private requireSocket(): net.Socket {
-    if (!this.socket || this.socket.destroyed || !this.socket.writable || !this.session) {
+    if (!this.socket || this.socket.destroyed || !this.socket.writable || !this.sessionId) {
       throw new Error("Session messaging is not connected.");
     }
 
@@ -241,7 +238,7 @@ export class SessionMessagingClient extends EventEmitter {
   }
 
   private cleanup(): void {
-    this.session = undefined;
+    this.sessionId = undefined;
     for (const pending of this.pendingLists.values()) {
       clearTimeout(pending.timeout);
       pending.reject(new Error("Session messaging disconnected."));

package/extensions/{session-messaging/shared → shared/session-broker}/framing.ts

@@ -1,7 +1,7 @@
 import type { Socket } from "node:net";
 import { createInterface } from "node:readline";
 import type { Static, TSchema } from "typebox";
-import { parseTypeBoxValue } from "../../shared/typebox.ts";
+import { parseTypeBoxValue } from "../typebox.ts";
 
 const MAX_FRAME_BYTES = 256 * 1024;
 

package/extensions/{session-messaging/shared → shared/session-broker}/protocol.ts

@@ -1,15 +1,9 @@
 import { type Static, Type } from "typebox";
 
-const SESSION_INFO_SCHEMA = Type.Object({
-  sessionId: Type.String(),
-  sessionName: Type.Optional(Type.String()),
-  cwd: Type.String(),
-});
-
 export const SESSION_MESSAGE_PAYLOAD_SCHEMA = Type.Object({
   messageId: Type.String(),
-  source: SESSION_INFO_SCHEMA,
-  target: SESSION_INFO_SCHEMA,
+  source: Type.String(),
+  target: Type.String(),
   body: Type.String(),
   requestResponse: Type.Optional(Type.Boolean()),
   sentAt: Type.String(),
@@ -18,7 +12,7 @@ export const SESSION_MESSAGE_PAYLOAD_SCHEMA = Type.Object({
 
 const REGISTER_CLIENT_FRAME_SCHEMA = Type.Object({
   type: Type.Literal("register"),
-  session: SESSION_INFO_SCHEMA,
+  sessionId: Type.String(),
 });
 const UNREGISTER_CLIENT_FRAME_SCHEMA = Type.Object({
   type: Type.Literal("unregister"),
@@ -47,7 +41,7 @@ const INCOMING_ACK_CLIENT_FRAME_SCHEMA = Type.Object({
 
 const REGISTERED_BROKER_FRAME_SCHEMA = Type.Object({
   type: Type.Literal("registered"),
-  session: SESSION_INFO_SCHEMA,
+  sessionId: Type.String(),
 });
 const REGISTER_FAILED_BROKER_FRAME_SCHEMA = Type.Object({
   type: Type.Literal("register_failed"),
@@ -56,7 +50,7 @@ const REGISTER_FAILED_BROKER_FRAME_SCHEMA = Type.Object({
 const SESSIONS_BROKER_FRAME_SCHEMA = Type.Object({
   type: Type.Literal("sessions"),
   requestId: Type.String(),
-  sessions: Type.Array(SESSION_INFO_SCHEMA),
+  sessionIds: Type.Array(Type.String()),
 });
 const INCOMING_BROKER_FRAME_SCHEMA = Type.Object({
   type: Type.Literal("incoming"),
@@ -92,7 +86,6 @@ export const BROKER_FRAME_SCHEMA = Type.Union([
   ERROR_BROKER_FRAME_SCHEMA,
 ]);
 
-export type SessionMessagingSessionInfo = Static<typeof SESSION_INFO_SCHEMA>;
 export type SessionMessagePayload = Static<typeof SESSION_MESSAGE_PAYLOAD_SCHEMA>;
 export type SessionMessagingSendClientFrame = Static<typeof SEND_CLIENT_FRAME_SCHEMA>;
 export type SessionMessagingIncomingAckClientFrame = Static<

package/extensions/shared/session-index/access.ts

@@ -0,0 +1,128 @@
+import { existsSync } from "node:fs";
+import { parseTypeBoxValue } from "../typebox.ts";
+import {
+  INDEX_SCHEMA_VERSION,
+  ROW_COUNT_SCHEMA,
+  type SessionIndexDatabase,
+  type SessionIndexStatus,
+} from "./common.ts";
+import { getMetadata, openIndexDatabase } from "./schema.ts";
+
+export type SessionIndexOpenMode = "read" | "write";
+
+export interface WithSessionIndexOptions {
+  mode: SessionIndexOpenMode;
+  required: boolean;
+  timeoutMs?: number | undefined;
+}
+
+export interface ValidSessionIndex {
+  db: SessionIndexDatabase;
+  status: SessionIndexStatus;
+}
+
+export function withSessionIndex<T>(
+  indexPath: string,
+  options: WithSessionIndexOptions & { required: true },
+  read: (index: ValidSessionIndex) => T,
+): T;
+export function withSessionIndex<T>(
+  indexPath: string,
+  options: WithSessionIndexOptions & { required: false },
+  read: (index: ValidSessionIndex) => T,
+): T | undefined;
+export function withSessionIndex<T>(
+  indexPath: string,
+  options: WithSessionIndexOptions,
+  read: (index: ValidSessionIndex) => T,
+): T | undefined {
+  const opened = openValidatedSessionIndexInternal(indexPath, options);
+  if (!opened) {
+    return undefined;
+  }
+
+  try {
+    return read(opened);
+  } finally {
+    opened.db.close();
+  }
+}
+
+export function openValidatedSessionIndex(
+  indexPath: string,
+  options: WithSessionIndexOptions & { required: true },
+): ValidSessionIndex;
+export function openValidatedSessionIndex(
+  indexPath: string,
+  options: WithSessionIndexOptions & { required: false },
+): ValidSessionIndex | undefined;
+export function openValidatedSessionIndex(
+  indexPath: string,
+  options: WithSessionIndexOptions,
+): ValidSessionIndex | undefined {
+  return openValidatedSessionIndexInternal(indexPath, options);
+}
+
+function openValidatedSessionIndexInternal(
+  indexPath: string,
+  options: WithSessionIndexOptions,
+): ValidSessionIndex | undefined {
+  if (!existsSync(indexPath)) {
+    return handleUnavailableIndex(indexPath, options);
+  }
+
+  let db: SessionIndexDatabase | undefined;
+  try {
+    db = openIndexDatabase(indexPath, {
+      create: false,
+      mode: options.mode,
+      ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+    });
+    const status = getIndexStatusFromDb(indexPath, db);
+    if (status.schemaVersion !== INDEX_SCHEMA_VERSION) {
+      const invalidDb = db;
+      db = undefined;
+      invalidDb.close();
+      return handleUnavailableIndex(indexPath, options);
+    }
+
+    return { db, status };
+  } catch (error) {
+    db?.close();
+    return handleUnavailableIndex(indexPath, options, error);
+  }
+}
+
+export function getIndexStatusFromDb(dbPath: string, db: SessionIndexDatabase): SessionIndexStatus {
+  const schemaVersionRaw = getMetadata(db, "schema_version");
+  const lastFullReindexAt = getMetadata(db, "indexed_at");
+  const sessionCountRow = parseTypeBoxValue(
+    ROW_COUNT_SCHEMA,
+    db.prepare(`SELECT COUNT(*) as count FROM sessions`).get(),
+    "Invalid session count row",
+  );
+
+  return {
+    dbPath,
+    exists: true,
+    schemaVersion: schemaVersionRaw ? Number(schemaVersionRaw) : undefined,
+    sessionCount: sessionCountRow.count,
+    lastFullReindexAt,
+  };
+}
+
+export function formatRequiredSessionIndexError(indexPath: string): string {
+  return `Session index missing or incompatible at ${indexPath}. Run /session-index and press r to rebuild it.`;
+}
+
+function handleUnavailableIndex(
+  indexPath: string,
+  options: WithSessionIndexOptions,
+  cause?: unknown,
+): undefined {
+  if (!options.required) {
+    return undefined;
+  }
+
+  throw new Error(formatRequiredSessionIndexError(indexPath), { cause });
+}

package/extensions/shared/session-index/common.ts

@@ -3,10 +3,11 @@ import type { FileTouchOp, FileTouchSource, PathScope } from "../../session-sear
 import { safeParseTypeBoxJson } from "../typebox.ts";
 import type { SqliteDatabase } from "./sqlite.ts";
 
-export const INDEX_SCHEMA_VERSION = 8;
+export const INDEX_SCHEMA_VERSION = 12;
 
 export type SessionOrigin = "handoff" | "fork" | "unknown_child";
 export type SessionLineageRelation =
+  | "self"
   | "parent"
   | "ancestor"
   | "child"
@@ -14,6 +15,8 @@ export type SessionLineageRelation =
   | "sibling"
   | "ancestor_sibling";
 
+export type SearchSort = "relevance" | "modified_desc" | "modified_asc";
+
 export interface SessionRow {
   sessionId: string;
   sessionPath: string;
@@ -58,7 +61,7 @@ export interface SessionRelatedSessionRow extends SessionLineageRow {
 export interface SessionTextChunkRow {
   id?: number | undefined;
   sessionId: string;
-  entryId?: string | undefined;
+  entryId: string;
   entryType: string;
   role?: string | undefined;
   ts: string;
@@ -89,9 +92,34 @@ export interface SearchSessionsParams {
   after?: string | undefined;
   before?: string | undefined;
   touched?: string[] | undefined;
+  changed?: string[] | undefined;
+  sort?: SearchSort | undefined;
   limit?: number | undefined;
   excludeSessionIds?: string[] | undefined;
-}
+  includeSessionIds?: string[] | undefined;
+  relativeToSessionId?: string | undefined;
+}
+
+export type SessionSearchEvidence =
+  | {
+      kind: "text";
+      sourceKind: string;
+      snippet: string;
+      score: number;
+      entryId: string;
+    }
+  | {
+      kind: "file_touch";
+      op: "read" | "changed";
+      query: string;
+      path: string;
+      entryId?: string | undefined;
+    }
+  | {
+      kind: "session_id";
+      match: "exact" | "prefix" | "substring";
+      score: number;
+    };
 
 export interface SearchSessionResult {
   sessionId: string;
@@ -108,8 +136,9 @@ export interface SearchSessionResult {
   sessionOrigin?: SessionOrigin | undefined;
   handoffGoal?: string | undefined;
   handoffNextTask?: string | undefined;
+  relation?: SessionLineageRelation | undefined;
   snippet: string;
-  matchedFiles: string[];
+  evidence: SessionSearchEvidence[];
   score: number;
   hitCount: number;
 }
@@ -131,6 +160,7 @@ export const SESSION_ORIGIN_SCHEMA = Type.Union([
   Type.Literal("unknown_child"),
 ]);
 export const SESSION_LINEAGE_RELATION_SCHEMA = Type.Union([
+  Type.Literal("self"),
   Type.Literal("parent"),
   Type.Literal("ancestor"),
   Type.Literal("child"),
@@ -150,7 +180,7 @@ export function parseRepoRoots(value: string): string[] {
 }
 
 export function escapeLikePrefix(value: string): string {
-  return value.replace(/[%_]/g, "\\$&");
+  return value.replace(/[%_\\]/g, "\\$&");
 }
 
 export function normalizeTimeFilter(value?: string): string | undefined {
@@ -160,7 +190,7 @@ export function normalizeTimeFilter(value?: string): string | undefined {
 
   const date = new Date(value);
   if (Number.isNaN(date.getTime())) {
-    return undefined;
+    throw new Error(`Invalid time filter value: ${value}`);
   }
 
   return date.toISOString();
@@ -174,48 +204,6 @@ export function sanitizeFilterValues(values?: string[]): string[] {
   return values.map((value) => value.trim()).filter((value) => value.length > 0);
 }
 
-export function boostIndependentHits(hitCount: number): number {
-  return hitCount > 1 ? (hitCount - 1) * 0.75 : 0;
-}
-
-export function buildFtsQuery(query: string): string | undefined {
-  const trimmed = query.trim();
-  if (!trimmed) {
-    return undefined;
-  }
-
-  if (trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.length >= 2) {
-    const exact = sanitizeFtsToken(trimmed.slice(1, -1));
-    return exact ? quoteFtsToken(exact) : undefined;
-  }
-
-  const tokens = tokenizeSearchTerms(trimmed);
-  if (tokens.length === 0) {
-    return undefined;
-  }
-
-  return tokens.map(quoteFtsPrefixToken).join(" AND ");
-}
-
-export function tokenizeSearchTerms(query: string): string[] {
-  return query
-    .split(/\s+/)
-    .flatMap((token) => sanitizeFtsToken(token).split(/\s+/))
-    .filter((token) => token.length > 0);
-}
-
-export function sanitizeFtsToken(token: string): string {
-  return token.replace(/[^A-Za-z0-9_]+/g, " ").trim();
-}
-
-export function quoteFtsToken(token: string): string {
-  return `"${token.replace(/"/g, '""')}"`;
-}
-
-export function quoteFtsPrefixToken(token: string): string {
-  return `${quoteFtsToken(token)}*`;
-}
-
 export function compactSearchValue(value: string): string {
   return value.toLowerCase().replace(/[^a-z0-9]+/g, "");
 }
@@ -223,3 +211,10 @@ export function compactSearchValue(value: string): string {
 export function compactSessionId(value: string): string {
   return value.toLowerCase().replace(/-/g, "");
 }
+
+export function tokenizeSearchText(value: string): string[] {
+  return value
+    .split(/[^A-Za-z0-9_]+/g)
+    .map((token) => token.trim())
+    .filter((token) => token.length > 0);
+}

package/extensions/shared/session-index/index.ts

@@ -1,3 +1,4 @@
+export * from "./access.ts";
 export * from "./common.ts";
 export * from "./lineage.ts";
 export * from "./schema.ts";

package/extensions/shared/session-index/lineage.ts

@@ -346,6 +346,7 @@ function queryRelatedSessions(
           WHERE r.session_id = ?${relationFilter}
           ORDER BY
             CASE r.relation
+              WHEN 'self' THEN 0
               WHEN 'parent' THEN 1
               WHEN 'child' THEN 2
               WHEN 'sibling' THEN 3
@@ -371,6 +372,13 @@ function collectMaterializedLineageRows(
   childrenByParent: Map<string, string[]>,
 ): Map<string, MaterializedLineageRow> {
   const relations = new Map<string, MaterializedLineageRow>();
+  setMaterializedLineageRow(relations, {
+    sessionId,
+    relatedSessionId: sessionId,
+    relation: "self",
+    distance: 0,
+  });
+
   const visitedAncestors = new Set<string>();
   const ancestors: Array<{ sessionId: string; distance: number }> = [];
 
@@ -476,6 +484,8 @@ function setMaterializedLineageRow(
 
 function getLineageRelationPriority(relation: SessionLineageRelation): number {
   switch (relation) {
+    case "self":
+      return 0;
     case "parent":
       return 1;
     case "child":

package/extensions/shared/session-index/query/ast.ts

@@ -0,0 +1,40 @@
+export interface QueryTermNode {
+  kind: "term";
+  value: string;
+  quoted: boolean;
+  prefix: boolean;
+}
+
+export interface QueryAndNode {
+  kind: "and";
+  children: SearchQueryNode[];
+}
+
+export interface QueryOrNode {
+  kind: "or";
+  children: SearchQueryNode[];
+}
+
+export interface QueryAdjacencyNode {
+  kind: "adjacency";
+  children: QueryTermNode[];
+}
+
+export interface QueryNotNode {
+  kind: "not";
+  child: SearchQueryNode;
+}
+
+export type SearchQueryNode =
+  | QueryTermNode
+  | QueryAndNode
+  | QueryOrNode
+  | QueryAdjacencyNode
+  | QueryNotNode;
+
+export class SearchQuerySyntaxError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SearchQuerySyntaxError";
+  }
+}

package/extensions/shared/session-index/query/compiler.ts

@@ -0,0 +1,146 @@
+import { type SearchQueryNode, SearchQuerySyntaxError } from "./ast.ts";
+import { parseSearchQuery } from "./parser.ts";
+
+export interface CompiledSearchQuery {
+  match: string;
+  relaxedMatch?: string | undefined;
+  excludes: string[];
+  positiveTerms: string[];
+}
+
+export function compileSearchQuery(input: string): CompiledSearchQuery | undefined {
+  const ast = parseSearchQuery(input);
+  if (!ast) {
+    return undefined;
+  }
+
+  const { positive, excludes } = splitTopLevelExcludes(ast);
+  if (!positive) {
+    throw new SearchQuerySyntaxError(
+      "Negative-only searches are not supported yet. Add at least one positive search term.",
+    );
+  }
+
+  validateNoNestedNegation(positive);
+  for (const exclude of excludes) {
+    validateNoNestedNegation(exclude);
+  }
+
+  const match = compilePositiveNode(positive);
+  const relaxedMatch = compilePositiveNode(positive, "OR");
+
+  return {
+    match,
+    relaxedMatch: relaxedMatch === match ? undefined : relaxedMatch,
+    excludes: excludes.map((exclude) => compilePositiveNode(exclude)),
+    positiveTerms: collectPositiveTerms(positive),
+  };
+}
+
+interface SplitQuery {
+  positive: SearchQueryNode | undefined;
+  excludes: SearchQueryNode[];
+}
+
+function splitTopLevelExcludes(node: SearchQueryNode): SplitQuery {
+  if (node.kind === "not") {
+    return { positive: undefined, excludes: [node.child] };
+  }
+
+  if (node.kind !== "and") {
+    return { positive: node, excludes: [] };
+  }
+
+  const positives: SearchQueryNode[] = [];
+  const excludes: SearchQueryNode[] = [];
+
+  for (const child of flattenAndChildren(node)) {
+    if (child.kind === "not") {
+      excludes.push(child.child);
+      continue;
+    }
+
+    positives.push(child);
+  }
+
+  return {
+    positive: buildAndNode(positives),
+    excludes,
+  };
+}
+
+function flattenAndChildren(node: SearchQueryNode): SearchQueryNode[] {
+  if (node.kind !== "and") {
+    return [node];
+  }
+
+  return node.children.flatMap(flattenAndChildren);
+}
+
+function buildAndNode(children: SearchQueryNode[]): SearchQueryNode | undefined {
+  if (children.length === 0) {
+    return undefined;
+  }
+
+  if (children.length === 1) {
+    return children[0];
+  }
+
+  return { kind: "and", children };
+}
+
+function validateNoNestedNegation(node: SearchQueryNode): void {
+  switch (node.kind) {
+    case "not":
+      throw new SearchQuerySyntaxError(
+        "Negation is only supported as a top-level AND clause in this release.",
+      );
+    case "and":
+    case "or":
+    case "adjacency":
+      for (const child of node.children) {
+        validateNoNestedNegation(child);
+      }
+      return;
+    case "term":
+      return;
+  }
+}
+
+function compilePositiveNode(node: SearchQueryNode, adjacencyOp: "AND" | "OR" = "AND"): string {
+  switch (node.kind) {
+    case "term":
+      return compileTerm(node.value, node.prefix);
+    case "and":
+      return `(${node.children.map((child) => compilePositiveNode(child, adjacencyOp)).join(" AND ")})`;
+    case "or":
+      return `(${node.children.map((child) => compilePositiveNode(child, adjacencyOp)).join(" OR ")})`;
+    case "adjacency":
+      return `(${node.children.map((child) => compileTerm(child.value, child.prefix)).join(` ${adjacencyOp} `)})`;
+    case "not":
+      throw new SearchQuerySyntaxError(
+        "Negation is only supported as a top-level AND clause in this release.",
+      );
+  }
+}
+
+function compileTerm(value: string, prefix: boolean): string {
+  return `${quoteFtsValue(value)}${prefix ? "*" : ""}`;
+}
+
+function quoteFtsValue(value: string): string {
+  return `"${value.replace(/"/g, '""')}"`;
+}
+
+function collectPositiveTerms(node: SearchQueryNode): string[] {
+  switch (node.kind) {
+    case "term":
+      return [node.value];
+    case "and":
+    case "or":
+    case "adjacency":
+      return node.children.flatMap(collectPositiveTerms);
+    case "not":
+      return [];
+  }
+}