@pi-harness/pi-harness 0.1.13 → 0.1.14

package/packages/core/src/plugins/session-compare.ts

@@ -3,6 +3,7 @@ import { basename } from "node:path";
 import type { Context } from "@deepseek-ai/cordis";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, parseSessionEntries, SessionManager, type AgentToolResult, type SessionInfo } from "@earendil-works/pi-coding-agent";
+import { EmptyConfig } from "../config.js";
 
 const maxSessions = 200;
 const maxSessionFileBytes = 4 * 1024 * 1024;
@@ -146,6 +147,7 @@ function renderReport(report: SessionCompareReport): string {
 export default {
   name: "pi-session-compare",
   inject: ["piHarnessLaunch", "piSession", "piPluginUi", "piTools"],
+  Config: EmptyConfig,
   apply(context: Context) {
     let latest: SessionCompareReport | undefined;
     const unregister = context.piTools.register(
@@ -154,10 +156,14 @@ export default {
         label: "Compare sessions",
         description: "Compare two persisted Pi JSONL sessions by message role and text without modifying either file.",
         promptSnippet: "compare two persisted Pi sessions",
-        parameters: Type.Object({
-          left: Type.String({ description: "Left session id or session filename" }),
-          right: Type.String({ description: "Right session id or session filename" }),
-        }),
+        parameters: Type.Object(
+          {
+            left: Type.String({ description: "Left session id or session filename" }),
+            right: Type.String({ description: "Right session id or session filename" }),
+          },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
         async execute(_toolCallId, params): Promise<AgentToolResult<SessionCompareReport>> {
           latest = await compareSessions(context, params.left, params.right);
           return { content: [{ type: "text", text: renderReport(latest) }], details: latest };

package/packages/core/src/plugins/session-export.ts

@@ -1,9 +1,9 @@
-import { randomUUID } from "node:crypto";
-import { rename, writeFile } from "node:fs/promises";
 import type { Context } from "@deepseek-ai/cordis";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { atomicWriteFile } from "../atomic-write.js";
 import { prepareWorkspaceFile } from "../workspace-path.js";
+import { EmptyConfig } from "../config.js";
 
 const maxOutputBytes = 1024 * 1024;
 const defaultFileName = "pi-session.md";
@@ -51,6 +51,7 @@ function normalizedOutputPath(requested: string): string {
 export default {
   name: "pi-session-export",
   inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  Config: EmptyConfig,
   apply(context: Context) {
     let latest: ExportState | undefined;
     const unregisterTool = context.piTools.register(
@@ -59,10 +60,14 @@ export default {
         label: "Export session",
         description: "Export the current Pi session as bounded Markdown without changing the conversation history.",
         promptSnippet: "export the current session to a Markdown file",
-        parameters: Type.Object({
-          path: Type.Optional(Type.String({ description: "Markdown path relative to the workspace" })),
-          confirm: Type.Optional(Type.Boolean({ description: "Must be true to overwrite an existing file" })),
-        }),
+        parameters: Type.Object(
+          {
+            path: Type.Optional(Type.String({ description: "Markdown path relative to the workspace" })),
+            confirm: Type.Optional(Type.Boolean({ description: "Must be true to overwrite an existing file" })),
+          },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
         async execute(_toolCallId, params): Promise<AgentToolResult<ExportState>> {
           const runtime = context.get("piRuntime");
           if (runtime === undefined) throw new Error("Pi runtime is not ready");
@@ -75,9 +80,7 @@ export default {
           const markdown = renderSessionMarkdown(runtime.session.messages);
           const bytes = Buffer.byteLength(markdown, "utf8");
           if (bytes > maxOutputBytes) throw new Error("Session export exceeds the 1 MiB output limit");
-          const temporary = `${prepared.target}.${randomUUID()}.tmp`;
-          await writeFile(temporary, markdown, { encoding: "utf8", mode: 0o600 });
-          await rename(temporary, prepared.target);
+          await atomicWriteFile(prepared.target, markdown, { encoding: "utf8", mode: 0o600 });
           latest = { path: prepared.relativePath, bytes, messages: runtime.session.messages.length };
           return { content: [{ type: "text", text: `Session exported to ${latest.path}.` }], details: latest };
         },

package/packages/core/src/plugins/session-insights.ts

@@ -1,47 +1,470 @@
 import type { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
 import { Type } from "@earendil-works/pi-ai";
-import { defineTool, type AgentToolResult, type SessionStats } from "@earendil-works/pi-coding-agent";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+
+export type SessionInsightsPluginConfig = Record<never, never>;
+
+export const Config: z<SessionInsightsPluginConfig> = z.object({});
+
+const toolParameterNames = new Set(["compact", "confirm"]);
+const statsRefreshEvents = new Set(["message_end", "tool_execution_end", "agent_end", "agent_settled", "compaction_end", "entry_appended"]);
+const maxSessionIdLength = 512;
+const maxSessionFileLength = 4_096;
+const maxCost = 1_000_000_000;
+const maxErrorLength = 2_000;
+
+function assertEmptyConfig(value: unknown): void {
+  if (value === null || typeof value !== "object") throw new Error("Unknown session-insights config; supported keys are (none)");
+  let hasUnknownKeys: boolean;
+  try {
+    hasUnknownKeys = Array.isArray(value) || Reflect.ownKeys(Object.getOwnPropertyDescriptors(value)).length > 0;
+  } catch (error) {
+    throw new Error("Unknown session-insights config could not be inspected safely", { cause: error });
+  }
+  if (hasUnknownKeys) throw new Error("Unknown session-insights config keys; supported keys are (none)");
+}
+
+export interface SessionInsightsStats {
+  readonly sessionFile: string | null;
+  readonly sessionId: string;
+  readonly userMessages: number;
+  readonly assistantMessages: number;
+  readonly toolCalls: number;
+  readonly toolResults: number;
+  readonly totalMessages: number;
+  readonly tokens: {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly total: number;
+  };
+  readonly cost: number;
+  readonly contextUsage: {
+    readonly tokens: number | null;
+    readonly contextWindow: number;
+    readonly percent: number | null;
+  } | null;
+}
+
+interface SessionInsightsCompactionState {
+  readonly status: "idle" | "queued" | "running" | "completed" | "failed" | "cancelled";
+  readonly requestedAt?: string;
+  readonly startedAt?: string;
+  readonly finishedAt?: string;
+  readonly error?: string;
+}
+
+export interface SessionInsightsDetails extends SessionInsightsStats {
+  readonly compaction: SessionInsightsCompactionState;
+}
+
+function ownDataRecord(value: unknown): Record<string, unknown> | undefined {
+  try {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+    const prototype = Object.getPrototypeOf(value) as unknown;
+    if (prototype !== Object.prototype && prototype !== null) return undefined;
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string")) return undefined;
+    const output = Object.create(null) as Record<string, unknown>;
+    for (const [key, descriptor] of Object.entries(descriptors)) {
+      if (!("value" in descriptor)) return undefined;
+      output[key] = descriptor.value;
+    }
+    return output;
+  } catch {
+    return undefined;
+  }
+}
+
+function count(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+function boundedText(value: unknown, maximum: number, allowUndefined: true): string | null | undefined;
+function boundedText(value: unknown, maximum: number, allowUndefined: false): string | undefined;
+function boundedText(value: unknown, maximum: number, allowUndefined: boolean): string | null | undefined {
+  if (allowUndefined && value === undefined) return null;
+  if (typeof value !== "string" || value.length === 0 || value.length > maximum || /[\0\p{Cc}]/u.test(value)) return undefined;
+  return value;
+}
+
+function snapshotStats(value: unknown): SessionInsightsStats {
+  const source = ownDataRecord(value);
+  const tokens = ownDataRecord(source?.tokens);
+  const sessionFile = boundedText(source?.sessionFile, maxSessionFileLength, true);
+  const sessionId = boundedText(source?.sessionId, maxSessionIdLength, false);
+  const userMessages = count(source?.userMessages);
+  const assistantMessages = count(source?.assistantMessages);
+  const toolCalls = count(source?.toolCalls);
+  const toolResults = count(source?.toolResults);
+  const totalMessages = count(source?.totalMessages);
+  const input = count(tokens?.input);
+  const output = count(tokens?.output);
+  const cacheRead = count(tokens?.cacheRead);
+  const cacheWrite = count(tokens?.cacheWrite);
+  const total = count(tokens?.total);
+  const cost = source?.cost;
+  if (
+    source === undefined ||
+    tokens === undefined ||
+    sessionFile === undefined ||
+    sessionId === undefined ||
+    userMessages === undefined ||
+    assistantMessages === undefined ||
+    toolCalls === undefined ||
+    toolResults === undefined ||
+    totalMessages === undefined ||
+    !Number.isSafeInteger(userMessages + assistantMessages + toolResults) ||
+    userMessages + assistantMessages + toolResults > totalMessages ||
+    input === undefined ||
+    output === undefined ||
+    cacheRead === undefined ||
+    cacheWrite === undefined ||
+    total === undefined ||
+    !Number.isSafeInteger(input + output + cacheRead + cacheWrite) ||
+    total !== input + output + cacheRead + cacheWrite ||
+    typeof cost !== "number" ||
+    !Number.isFinite(cost) ||
+    cost < 0 ||
+    cost > maxCost
+  )
+    throw new Error("Session statistics response is invalid");
+
+  let contextUsage: SessionInsightsStats["contextUsage"] = null;
+  if (source.contextUsage !== undefined) {
+    const usage = ownDataRecord(source.contextUsage);
+    const usageTokens = usage?.tokens;
+    const contextWindow = count(usage?.contextWindow);
+    const percent = usage?.percent;
+    const tokensValid = usageTokens === null || count(usageTokens) !== undefined;
+    const percentValid = percent === null || (typeof percent === "number" && Number.isFinite(percent) && percent >= 0);
+    const nullabilityMatches = (usageTokens === null) === (percent === null);
+    const expectedPercent = typeof usageTokens === "number" && contextWindow !== undefined && contextWindow > 0 ? (usageTokens / contextWindow) * 100 : null;
+    const percentMatches =
+      expectedPercent === null ||
+      (typeof percent === "number" && Math.abs(percent - expectedPercent) <= Math.max(1e-9, Math.abs(expectedPercent) * Number.EPSILON * 8));
+    if (usage === undefined || !tokensValid || contextWindow === undefined || contextWindow <= 0 || !percentValid || !nullabilityMatches || !percentMatches)
+      throw new Error("Session statistics context usage is invalid");
+    contextUsage = { tokens: usageTokens as number | null, contextWindow, percent };
+  }
+
+  return {
+    sessionFile,
+    sessionId,
+    userMessages,
+    assistantMessages,
+    toolCalls,
+    toolResults,
+    totalMessages,
+    tokens: { input, output, cacheRead, cacheWrite, total },
+    cost,
+    contextUsage,
+  };
+}
+
+function cloneDetails(stats: SessionInsightsStats, compaction: SessionInsightsCompactionState): SessionInsightsDetails {
+  return {
+    ...stats,
+    tokens: { ...stats.tokens },
+    contextUsage: stats.contextUsage === null ? null : { ...stats.contextUsage },
+    compaction: { ...compaction },
+  };
+}
+
+function dataProperty(value: unknown, key: PropertyKey): unknown {
+  if (value === null || typeof value !== "object") return undefined;
+  try {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor !== undefined && "value" in descriptor ? descriptor.value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function boundedError(error: unknown): string {
+  const message = typeof error === "string" ? error : dataProperty(error, "message");
+  return (typeof message === "string" ? message : "Unknown session compaction error").replaceAll("\0", "�").slice(0, maxErrorLength);
+}
+
+function boundedInspectionError(error: unknown): string {
+  const message = typeof error === "string" ? error : dataProperty(error, "message");
+  return `Session statistics inspection failed: ${typeof message === "string" ? message.replaceAll("\0", "�") : "unknown error"}`.slice(0, maxErrorLength);
+}
+
+function cancellationError(signal: AbortSignal, fallback: string): Error {
+  return signal.reason instanceof Error ? signal.reason : new Error(fallback, { cause: signal.reason });
+}
+
+function throwIfCancelled(signal: AbortSignal): void {
+  if (signal.aborted) throw cancellationError(signal, "Session report operation was cancelled");
+}
+
+function waitForOperation<T>(operation: Promise<T>, signal: AbortSignal): Promise<T> {
+  throwIfCancelled(signal);
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => reject(cancellationError(signal, "Session report operation was cancelled"));
+    signal.addEventListener("abort", onAbort, { once: true });
+    void operation.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error: unknown) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error instanceof Error ? error : new Error("Session compaction failed with a non-error rejection", { cause: error }));
+      },
+    );
+  });
+}
+
+function parseToolParams(value: unknown): { compact: boolean } {
+  if (value === null || typeof value !== "object") throw new Error("Session report parameters must be an object");
+  let prototype: unknown;
+  let descriptors: PropertyDescriptorMap;
+  let array: boolean;
+  try {
+    array = Array.isArray(value);
+    prototype = Object.getPrototypeOf(value) as unknown;
+    descriptors = Object.getOwnPropertyDescriptors(value);
+  } catch (error) {
+    throw new Error("Session report parameters could not be inspected safely", { cause: error });
+  }
+  if (array) throw new Error("Session report parameters must be an object");
+  if (prototype !== Object.prototype && prototype !== null) throw new Error("Session report parameters must be a plain object");
+  if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string" || !toolParameterNames.has(key)))
+    throw new Error("Session report parameters contain an unknown property");
+  if (Object.values(descriptors).some((descriptor) => !("value" in descriptor))) throw new Error("Session report parameters must use data properties");
+  const compact = descriptors.compact?.value as unknown;
+  const confirm = descriptors.confirm?.value as unknown;
+  if (compact !== undefined && typeof compact !== "boolean") throw new Error("Session report parameters compact must be a boolean");
+  if (confirm !== undefined && typeof confirm !== "boolean") throw new Error("Session report parameters confirm must be a boolean");
+  if (compact === true && confirm !== true) throw new Error("Session report compaction requires confirm=true");
+  return { compact: compact === true };
+}
 
 export default {
   name: "pi-session-insights",
   inject: ["piPluginUi", "piTools"],
-  apply(context: Context) {
+  Config,
+  apply(context: Context, config: SessionInsightsPluginConfig = {}) {
+    assertEmptyConfig(config);
     const runtime = () => context.get("piRuntime");
-    const readStats = (): SessionStats => {
+    const lifecycle = new AbortController();
+    const uninitializedSession = Symbol("uninitialized session");
+    let cachedSession: unknown = uninitializedSession;
+    let cachedStats: SessionInsightsStats | undefined;
+    let cachedError: string | undefined;
+    let compaction: SessionInsightsCompactionState = { status: "idle" };
+    let active: Promise<void> | undefined;
+    let activeRequest: { session: unknown; controller: AbortController } | undefined;
+    let queued:
+      | {
+          session: NonNullable<ReturnType<typeof runtime>>["session"];
+          signal: AbortSignal;
+          requestedAt: string;
+          removeAbortListener: () => void;
+        }
+      | undefined;
+    const refreshStats = (): void => {
       const service = runtime();
-      if (service === undefined) throw new Error("Pi runtime is not ready");
-      return service.session.getSessionStats();
+      cachedSession = service?.session;
+      cachedStats = undefined;
+      cachedError = undefined;
+      if (service === undefined) {
+        cachedError = "Pi runtime is not ready";
+        return;
+      }
+      try {
+        cachedStats = snapshotStats(service.session.getSessionStats());
+      } catch (error) {
+        cachedError = boundedInspectionError(error);
+      }
+    };
+    const cancelForSessionChange = (session: unknown): void => {
+      if (queued !== undefined && queued.session !== session) {
+        const request = queued;
+        queued = undefined;
+        request.removeAbortListener();
+        compaction = {
+          status: "cancelled",
+          requestedAt: request.requestedAt,
+          finishedAt: new Date().toISOString(),
+          error: "Session changed before the queued session compaction could start",
+        };
+      }
+      if (activeRequest !== undefined && activeRequest.session !== session && !activeRequest.controller.signal.aborted) {
+        activeRequest.controller.abort(new Error("Session changed while session compaction was running"));
+      }
     };
-    const unregisterTool = context.piTools.register(
-      defineTool({
-        name: "session_report",
-        label: "Session report",
-        description: "Inspect the current session token, message, tool, cost, and context statistics.",
-        promptSnippet: "inspect current session usage and context statistics",
-        parameters: Type.Object({ compact: Type.Optional(Type.Boolean({ description: "Compact the session when true" })) }),
-        async execute(_toolCallId, params): Promise<AgentToolResult<SessionStats>> {
-          const service = runtime();
-          if (service === undefined) throw new Error("Pi runtime is not ready");
-          if (params.compact === true) await service.session.compact();
-          const report = readStats();
-          return {
-            content: [{ type: "text", text: `Session has ${report.totalMessages} messages and ${report.tokens.total} tracked tokens.` }],
-            details: report,
+    const readDetails = (): SessionInsightsDetails => {
+      const session = runtime()?.session;
+      cancelForSessionChange(session);
+      if (session !== cachedSession) refreshStats();
+      if (cachedError !== undefined) throw new Error(cachedError);
+      if (cachedStats === undefined) throw new Error("Session statistics are unavailable");
+      return cloneDetails(cachedStats, compaction);
+    };
+    const startCompaction = (session: NonNullable<ReturnType<typeof runtime>>["session"], callerSignal: AbortSignal, requestedAt: string): Promise<void> => {
+      const controller = new AbortController();
+      const signal = AbortSignal.any([callerSignal, controller.signal]);
+      const startedAt = new Date().toISOString();
+      compaction = { status: "running", requestedAt, startedAt };
+      const operation = Promise.resolve().then(async () => {
+        throwIfCancelled(signal);
+        const abort = (): void => {
+          try {
+            session.abortCompaction();
+          } catch {
+            // Cancellation remains authoritative even if the runtime is already tearing down.
+          }
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        try {
+          await waitForOperation(
+            Promise.resolve().then(async () => session.compact()),
+            signal,
+          );
+          throwIfCancelled(signal);
+          compaction = { status: "completed", requestedAt, startedAt, finishedAt: new Date().toISOString() };
+          if (runtime()?.session === session) refreshStats();
+        } catch (error) {
+          compaction = {
+            status: signal.aborted ? "cancelled" : "failed",
+            requestedAt,
+            startedAt,
+            finishedAt: new Date().toISOString(),
+            error: boundedError(signal.aborted ? cancellationError(signal, "Session compaction was cancelled") : error),
           };
+          if (runtime()?.session === session) refreshStats();
+          throw error;
+        } finally {
+          signal.removeEventListener("abort", abort);
+        }
+      });
+      active = operation;
+      activeRequest = { session, controller };
+      void operation.then(
+        () => {
+          if (active === operation) active = undefined;
+          if (activeRequest?.controller === controller) activeRequest = undefined;
         },
-      }),
-    );
-    const disposePanel = context.piPluginUi.register({
-      id: "session-insights-panel",
-      pluginId: "@pi-harness/core/plugins/session-insights",
-      title: "Session Insights",
-      description: "查看当前会话的消息、工具、token、成本和上下文统计，并可触发压缩。",
-      icon: "▥",
-      read: readStats,
+        () => {
+          if (active === operation) active = undefined;
+          if (activeRequest?.controller === controller) activeRequest = undefined;
+        },
+      );
+      return operation;
+    };
+    const unsubscribe = context.on("pi/session-event", (event) => {
+      const type = dataProperty(event, "type");
+      if (typeof type !== "string") return;
+      const service = runtime();
+      cancelForSessionChange(service?.session);
+      if (statsRefreshEvents.has(type)) refreshStats();
+      if (type !== "agent_settled" || queued === undefined) return;
+      const request = queued;
+      queued = undefined;
+      request.removeAbortListener();
+      if (service === undefined || service.session !== request.session) {
+        compaction = {
+          status: "cancelled",
+          requestedAt: request.requestedAt,
+          finishedAt: new Date().toISOString(),
+          error: "Session changed before the queued session compaction could start",
+        };
+        return;
+      }
+      void startCompaction(service.session, request.signal, request.requestedAt).catch(() => undefined);
+    });
+    const tool = defineTool({
+      name: "session_report",
+      label: "Session report",
+      description: "Inspect the current session token, message, tool, cost, and context statistics.",
+      promptSnippet: "inspect current session usage and context statistics",
+      promptGuidelines: ["Set compact=true only with confirm=true after the user approves model-backed compaction that may incur usage and cost."],
+      parameters: Type.Object(
+        {
+          compact: Type.Optional(Type.Boolean({ description: "Compact the session with the active model; this may incur usage and cost" })),
+          confirm: Type.Optional(Type.Boolean({ description: "Must be true when compaction is requested" })),
+        },
+        { additionalProperties: false },
+      ),
+      executionMode: "sequential",
+      async execute(_toolCallId, params, signal): Promise<AgentToolResult<SessionInsightsDetails>> {
+        const request = parseToolParams(params);
+        const actionSignal = signal === undefined ? lifecycle.signal : AbortSignal.any([signal, lifecycle.signal]);
+        throwIfCancelled(actionSignal);
+        const service = runtime();
+        if (service === undefined) throw new Error("Pi runtime is not ready");
+        cancelForSessionChange(service.session);
+        refreshStats();
+        if (request.compact) {
+          if (active !== undefined || queued !== undefined) throw new Error("A session compaction is already in progress");
+          const requestedAt = new Date().toISOString();
+          if (service.session.isIdle === false) {
+            const onAbort = (): void => {
+              if (queued?.signal !== actionSignal) return;
+              queued = undefined;
+              compaction = {
+                status: "cancelled",
+                requestedAt,
+                finishedAt: new Date().toISOString(),
+                error: "Session compaction was cancelled before it started",
+              };
+            };
+            actionSignal.addEventListener("abort", onAbort, { once: true });
+            queued = {
+              session: service.session,
+              signal: actionSignal,
+              requestedAt,
+              removeAbortListener: () => actionSignal.removeEventListener("abort", onAbort),
+            };
+            compaction = { status: "queued", requestedAt };
+            const queuedReport = readDetails();
+            return {
+              content: [{ type: "text", text: "Session compaction queued until the current agent run settles." }],
+              details: queuedReport,
+            };
+          }
+          await startCompaction(service.session, actionSignal, requestedAt);
+        }
+        const report = readDetails();
+        return {
+          content: [{ type: "text", text: `Session has ${report.totalMessages} messages and ${report.tokens.total} tracked tokens.` }],
+          details: report,
+        };
+      },
     });
+    let unregisterTool: (() => void) | undefined;
+    let disposePanel: (() => void) | undefined;
+    try {
+      unregisterTool = context.piTools.register(tool);
+      disposePanel = context.piPluginUi.register({
+        id: "session-insights-panel",
+        pluginId: "@pi-harness/core/plugins/session-insights",
+        title: "Session Insights",
+        description: "查看当前会话的消息、工具、token、成本和上下文统计，并可触发确认后的会话压缩。",
+        icon: "▥",
+        read: readDetails,
+      });
+    } catch (error) {
+      lifecycle.abort(new Error("Session Insights plugin registration failed"));
+      unsubscribe();
+      unregisterTool?.();
+      disposePanel?.();
+      throw error;
+    }
     context.effect(() => () => {
-      unregisterTool();
-      disposePanel();
+      lifecycle.abort(new Error("Session Insights plugin disposed"));
+      if (queued !== undefined) {
+        queued.removeAbortListener();
+        queued = undefined;
+      }
+      unsubscribe();
+      unregisterTool?.();
+      disposePanel?.();
     });
   },
 };

package/packages/core/src/plugins/session-search.ts

@@ -2,6 +2,7 @@ import { readFile, stat } from "node:fs/promises";
 import type { Context } from "@deepseek-ai/cordis";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, parseSessionEntries, SessionManager, type AgentToolResult, type SessionInfo } from "@earendil-works/pi-coding-agent";
+import { EmptyConfig } from "../config.js";
 
 const maxQueryLength = 120;
 const maxPreviewLength = 500;
@@ -79,6 +80,7 @@ async function searchSessions(sessions: readonly SessionInfo[], query: string):
 export default {
   name: "pi-session-search",
   inject: ["piHarnessLaunch", "piSession", "piPluginUi", "piTools"],
+  Config: EmptyConfig,
   apply(context: Context) {
     let latest: { query: string; total: number; items: SessionSearchItem[] } | undefined;
     const search = async (query: string): Promise<SessionSearchItem[]> => {
@@ -95,7 +97,8 @@ export default {
         label: "Search sessions",
         description: "Search persisted Pi JSONL sessions for a bounded text query without modifying session files.",
         promptSnippet: "search previous Pi sessions for a phrase",
-        parameters: Type.Object({ query: Type.String({ description: "Text to search for, 1-120 characters" }) }),
+        parameters: Type.Object({ query: Type.String({ description: "Text to search for, 1-120 characters" }) }, { additionalProperties: false }),
+        executionMode: "sequential",
         async execute(_toolCallId, params): Promise<AgentToolResult<{ query: string; total: number; items: SessionSearchItem[] }>> {
           const items = await search(params.query);
           return {

package/packages/core/src/plugins/session.ts

@@ -1,3 +1,4 @@
+import { statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import type { Context } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
@@ -9,9 +10,12 @@ export interface SessionPluginConfig {
   directory?: string;
 }
 
+const maxSessionDirectoryLength = 4_096;
+const sessionDirectoryPattern = /^(?=[\s\S]*\S)\P{Cc}+$/u;
+
 export const Config: z<SessionPluginConfig> = z.object({
   storage: z.union(["memory", "jsonl"]).default("jsonl"),
-  directory: z.string().min(1),
+  directory: z.string().min(1).max(maxSessionDirectoryLength).pattern(sessionDirectoryPattern),
 });
 
 export default {
@@ -21,6 +25,7 @@ export default {
   apply(context: Context, config: SessionPluginConfig) {
     assertKnownConfigKeys("pi-session", config, ["storage", "directory"]);
     const storage = config.storage ?? "jsonl";
+    if (storage === "memory" && config.directory != null) throw new Error("Pi session directory cannot be configured with memory storage");
     const manager =
       storage === "memory"
         ? SessionManager.inMemory(context.piHarnessLaunch.cwd)
@@ -28,6 +33,8 @@ export default {
             context.piHarnessLaunch.cwd,
             config.directory == null ? join(context.piHarnessLaunch.agentDir, "sessions") : resolve(context.piHarnessLaunch.cwd, config.directory),
           );
+    if (storage === "jsonl" && !statSync(manager.getSessionDir()).isDirectory())
+      throw new Error(`Pi session directory must be a directory: ${manager.getSessionDir()}`);
     context.provide("piSession", { manager });
   },
 };