@thurstonsand/pi-librarian 0.1.1 → 0.2.1

package/extensions/librarian/view.ts

@@ -1,21 +1,18 @@
 import path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
-import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { getMarkdownTheme, keyHint } from "@earendil-works/pi-coding-agent";
+import { type Component, Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import type { LibrarianRunDetails, TraceCall } from "./run.ts";
 import { LIBRARIAN_TOOL_NAMES } from "./tools/names.ts";
 
 const COLLAPSED_TRACE_CALLS = 3;
+// Same frames and cadence as pi's Working... loader (pi-tui loader.ts defaults).
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-const SPINNER_INTERVAL_MS = 80;
-
-interface LiveRenderContext {
-  invalidate(): void;
-  state: {
-    librarianSpinnerFrame?: number;
-    librarianSpinnerInterval?: ReturnType<typeof setInterval>;
-  };
+export const SPINNER_INTERVAL_MS = 80;
+
+interface LibrarianRenderContext {
+  lastComponent: Component | undefined;
 }
 
 export function formatDuration(milliseconds: number): string {
@@ -153,18 +150,17 @@ export function formatTraceLine(call: TraceCall, cacheDir: string): TraceLine {
   }
 }
 
-function renderTraceCallText(
-  call: TraceCall,
-  cacheDir: string,
-  theme: Theme,
-  spinnerFrame: string,
-): string {
+function currentSpinnerFrame(): string {
+  return SPINNER_FRAMES[Math.floor(Date.now() / SPINNER_INTERVAL_MS) % SPINNER_FRAMES.length] ?? "";
+}
+
+function renderTraceCallText(call: TraceCall, cacheDir: string, theme: Theme): string {
   const { verb, subject } = formatTraceLine(call, cacheDir);
   const running = call.endedAt === undefined;
   const icon = call.isError
     ? theme.fg("error", "✗")
     : running
-      ? theme.fg("warning", spinnerFrame)
+      ? theme.fg("accent", currentSpinnerFrame())
       : theme.fg("success", "✓");
   const duration = formatDuration((call.endedAt ?? Date.now()) - call.startedAt);
   const summary = call.resultSummary
@@ -189,83 +185,103 @@ function renderFooter(details: LibrarianRunDetails, theme: Theme): string {
   );
 }
 
+function collapsedFindingsHiddenText(details: LibrarianRunDetails): string | undefined {
+  const findings = details.findings;
+  if (!findings) {
+    return undefined;
+  }
+
+  const hiddenParts: string[] = [];
+  if (findings.locations.length > 0) {
+    hiddenParts.push(
+      `${findings.locations.length} location${findings.locations.length === 1 ? "" : "s"}`,
+    );
+  }
+  if (findings.description?.trim()) {
+    hiddenParts.push("details");
+  }
+
+  return hiddenParts.length > 0 ? `${hiddenParts.join(" and ")} hidden` : undefined;
+}
+
+function isLibrarianRunDetails(value: unknown): value is LibrarianRunDetails {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    typeof (value as { status?: unknown }).status === "string" &&
+    typeof (value as { query?: unknown }).query === "string" &&
+    typeof (value as { modelLabel?: unknown }).modelLabel === "string" &&
+    Array.isArray((value as { trace?: unknown }).trace)
+  );
+}
+
 function renderTrace(
   details: LibrarianRunDetails,
   expanded: boolean,
   cacheDir: string,
   theme: Theme,
-  spinnerFrame: string,
 ): string[] {
   const lines: string[] = [];
   const calls = expanded ? details.trace : details.trace.slice(-COLLAPSED_TRACE_CALLS);
   const hiddenCount = details.trace.length - calls.length;
   if (hiddenCount > 0) {
     lines.push(
-      theme.fg(
-        "muted",
-        `  … ${hiddenCount} earlier call${hiddenCount === 1 ? "" : "s"} (Ctrl+O to expand)`,
-      ),
+      theme.fg("muted", `  … ${hiddenCount} earlier call${hiddenCount === 1 ? "" : "s"} (`) +
+        keyHint("app.tools.expand", "to expand") +
+        theme.fg("muted", ")"),
     );
   }
   for (const call of calls) {
-    lines.push(renderTraceCallText(call, cacheDir, theme, spinnerFrame));
+    lines.push(renderTraceCallText(call, cacheDir, theme));
   }
   return lines;
 }
 
-function updateLiveRender(context: LiveRenderContext | undefined, running: boolean): string {
-  if (!context) {
-    return (
-      SPINNER_FRAMES[Math.floor(Date.now() / SPINNER_INTERVAL_MS) % SPINNER_FRAMES.length] ?? ""
-    );
-  }
-
-  context.state.librarianSpinnerFrame ??= 0;
-  if (running && !context.state.librarianSpinnerInterval) {
-    context.state.librarianSpinnerInterval = setInterval(() => {
-      context.state.librarianSpinnerFrame =
-        ((context.state.librarianSpinnerFrame ?? 0) + 1) % SPINNER_FRAMES.length;
-      context.invalidate();
-    }, SPINNER_INTERVAL_MS);
-  } else if (!running && context.state.librarianSpinnerInterval) {
-    clearInterval(context.state.librarianSpinnerInterval);
-    delete context.state.librarianSpinnerInterval;
-  }
-
-  return SPINNER_FRAMES[context.state.librarianSpinnerFrame] ?? "";
-}
-
 export function renderLibrarianResult(
   result: AgentToolResult<LibrarianRunDetails>,
   options: { expanded: boolean; isPartial: boolean },
   theme: Theme,
   cacheDir: string,
-  context?: LiveRenderContext,
+  context?: LibrarianRenderContext,
 ): Container {
-  const container = new Container();
+  const container =
+    context?.lastComponent instanceof Container ? context.lastComponent : new Container();
+  container.clear();
   const details = result.details;
 
-  if (!details) {
+  if (!isLibrarianRunDetails(details)) {
     const firstText = result.content.find((part) => part.type === "text");
     container.addChild(
       new Text(firstText && "text" in firstText ? firstText.text : "(no output)", 0, 0),
     );
+    container.invalidate();
     return container;
   }
 
   const running = options.isPartial || details.status === "running";
-  const spinnerFrame = updateLiveRender(context, running);
   container.addChild(new Text(renderQuestion(details, options.expanded, theme), 0, 0));
   container.addChild(new Spacer(1));
 
   if (running || !details.findings) {
-    for (const line of renderTrace(details, options.expanded, cacheDir, theme, spinnerFrame)) {
+    for (const line of renderTrace(details, options.expanded, cacheDir, theme)) {
       container.addChild(new Text(line, 0, 0));
     }
   }
 
   if (!running) {
     if (details.findings) {
+      const hiddenText = options.expanded ? undefined : collapsedFindingsHiddenText(details);
+      if (hiddenText) {
+        container.addChild(
+          new Text(
+            theme.fg("muted", `(${hiddenText}, `) +
+              keyHint("app.tools.expand", "to expand") +
+              theme.fg("muted", ")"),
+            0,
+            0,
+          ),
+        );
+      }
       const markdown = buildFindingsMarkdown(details, options.expanded);
       container.addChild(new Markdown(markdown, 0, 0, getMarkdownTheme()));
     } else if (details.error) {
@@ -275,7 +291,11 @@ export function renderLibrarianResult(
   }
 
   container.addChild(new Spacer(1));
+  if (!running && details.runId) {
+    container.addChild(new Text(theme.fg("muted", `run ${details.runId}`), 0, 0));
+  }
   container.addChild(new Text(renderFooter(details, theme), 0, 0));
+  container.invalidate();
   return container;
 }
 

package/extensions/librarian.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI, SessionStartEvent } from "@earendil-works/pi-coding-
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { applyAttachState, readAttachState, setAttachState } from "./librarian/attach.ts";
+import { collectExtraToolWarnings, resolveExtraTools } from "./librarian/extra-tools.ts";
 import { createGitHubClientProvider } from "./librarian/github.ts";
 import { resolveLibrarianModel } from "./librarian/model.ts";
 import { type LibrarianRunDetails, runLibrarian, type TraceCall } from "./librarian/run.ts";
@@ -16,6 +17,7 @@ import {
   formatTraceLine,
   renderLibrarianCall,
   renderLibrarianResult,
+  SPINNER_INTERVAL_MS,
   shorten,
 } from "./librarian/view.ts";
 
@@ -36,6 +38,12 @@ const LibrarianParams = Type.Object({
       maxItems: 20,
     }),
   ),
+  continue_from: Type.Optional(
+    Type.String({
+      description:
+        "Run id from an earlier librarian result. Pass this for follow-up questions for that prior run.",
+    }),
+  ),
 });
 
 export default function librarianExtension(pi: ExtensionAPI): void {
@@ -84,41 +92,33 @@ export default function librarianExtension(pi: ExtensionAPI): void {
       const thinkingLevel = settings.thinkingLevel ?? pi.getThinkingLevel();
       const resolution = resolveLibrarianModel(ctx, settings.model, thinkingLevel);
       if (!resolution) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "No model available for the librarian. Configure librarian.model or select a session model.",
-            },
-          ],
-          details: {
-            status: "error",
-            query: params.query,
-            modelLabel: "(none)",
-            thinkingLevel,
-            trace: [],
-            checkouts: {},
-            startedAt: Date.now(),
-            endedAt: Date.now(),
-            error: "No model available.",
-          } satisfies LibrarianRunDetails,
-          isError: true,
-        };
+        throw new Error(
+          "No model available for the librarian. Configure librarian.model or select a session model.",
+        );
       }
 
+      const extraTools = resolveExtraTools(pi.getAllTools(), settings);
+
       return runLibrarian({
         query: params.query,
         repos: params.repos ?? [],
         owners: params.owners ?? [],
+        continueFrom: params.continue_from,
         model: resolution.model,
         thinkingLevel: resolution.thinkingLevel,
         settings,
+        extraTools,
         githubClient,
         signal,
         onUpdate: onUpdate
           ? (details) => {
               onUpdate({
-                content: [{ type: "text", text: `Researching: ${shorten(params.query, 80)}` }],
+                content: [
+                  {
+                    type: "text",
+                    text: `Researching: ${shorten(params.query, 80)}`,
+                  },
+                ],
                 details,
               });
             }
@@ -131,6 +131,16 @@ export default function librarianExtension(pi: ExtensionAPI): void {
     },
 
     renderResult(result, options, theme, context) {
+      // Live spinner/elapsed ticking, same pattern and cadence as pi's bash
+      // tool and Working... loader: re-render on an interval while streaming.
+      const state = context.state as { interval: NodeJS.Timeout | undefined };
+      if (options.isPartial && !state.interval) {
+        state.interval = setInterval(() => context.invalidate(), SPINNER_INTERVAL_MS);
+      }
+      if ((!options.isPartial || context.isError) && state.interval) {
+        clearInterval(state.interval);
+        state.interval = undefined;
+      }
       return renderLibrarianResult(result, options, theme, settings.cacheDir, context);
     },
   });
@@ -177,5 +187,10 @@ export default function librarianExtension(pi: ExtensionAPI): void {
 
   pi.on("session_start", async (_event: SessionStartEvent, ctx) => {
     applyAttachState(pi, readAttachState(ctx));
+
+    const warnings = await collectExtraToolWarnings(pi.getAllTools(), settings);
+    for (const warning of warnings) {
+      ctx.ui.notify(warning.message, "warning");
+    }
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thurstonsand/pi-librarian",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "type": "module",
   "description": "GitHub research subagent for pi: deep-dive specific repos, discover across the ecosystem",
   "license": "MIT",
@@ -25,7 +25,8 @@
     "CONTEXT.md",
     "DEV.md",
     "AGENTS.md",
-    "docs"
+    "docs",
+    "images"
   ],
   "pi": {
     "extensions": [