pi-spark 0.9.5 → 0.10.1

package/README.md

@@ -80,8 +80,8 @@ Example:
 ### Models
 
 - The agent can call the `model` tool with two actions:
-  - `list`: lists models with their metadata, with optional `scope`, `provider` and `model` substring filters, and `offset`/`limit` paging.
-  - `current`: gets the active provider, model, and thinking level.
+  - `active`: gets the active provider, model, and thinking level.
+  - `list`: lists models with their metadata, with an optional [Liqe](https://github.com/gajus/liqe) (Lucene-like) `query` over model fields and `offset`/`limit` paging.
 
 ### Name
 

package/extensions/models/index.ts

@@ -1,10 +1,11 @@
 import { clampThinkingLevel, getSupportedThinkingLevels, StringEnum } from "@earendil-works/pi-ai";
-import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, keyText, truncateHead } from "@earendil-works/pi-coding-agent";
+import { keyText, truncateHead } from "@earendil-works/pi-coding-agent";
 import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import { filter, parse } from "liqe";
 import { Type } from "typebox";
 
 import { loadConfig } from "../shared/config";
-import { formatModel } from "../shared/format";
+import { formatModel, formatTokens } from "../shared/format";
 
 import type { Api, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, TruncationResult } from "@earendil-works/pi-coding-agent";
@@ -12,6 +13,12 @@ import type { ExtensionAPI, TruncationResult } from "@earendil-works/pi-coding-a
 /** Pi's built-in default thinking level, clamped per model. Not exported by pi's public API. */
 const DEFAULT_THINKING_LEVEL: ModelThinkingLevel = "medium";
 
+/** Maximum number of models returned per list call; byte size is unrestricted. */
+const LIST_MAX_LINES = 200;
+
+/** Maximum number of model rows shown when the result is collapsed. */
+const COLLAPSED_MAX_ROWS = 10;
+
 type ModelMetadata = Omit<Model<Api>, "headers" | "compat"> & {
   thinkingLevels: ModelThinkingLevel[];
   defaultThinkingLevel: ModelThinkingLevel;
@@ -19,9 +26,17 @@ type ModelMetadata = Omit<Model<Api>, "headers" | "compat"> & {
 };
 
 type ModelToolDetails =
-  | { action: "current"; current: { model: ModelMetadata; thinkingLevel: ModelThinkingLevel } }
+  | { action: "active"; active: { model: ModelMetadata; thinkingLevel: ModelThinkingLevel } }
   | { action: "list"; models: ModelMetadata[]; total: number; truncation?: TruncationResult }
 
+/** One display row of model metadata: label, cost per 1M tokens, and context window. */
+type ModelRow = {
+  label: string;
+  cost: string;
+  context: string;
+  available: boolean;
+};
+
 function toMetadata(model: Model<Api>, available: boolean): ModelMetadata {
   const { headers: _headers, compat: _compat, ...metadata } = model;
 
@@ -33,6 +48,30 @@ function toMetadata(model: Model<Api>, available: boolean): ModelMetadata {
   };
 }
 
+function toModelRow(model: ModelMetadata, thinkingLevel?: ModelThinkingLevel): ModelRow {
+  return {
+    label: formatModel(model.provider, model.id, thinkingLevel),
+    cost: `$${formatPrice(model.cost.input)}/$${formatPrice(model.cost.output)}`,
+    context: formatTokens(model.contextWindow),
+    available: model.available,
+  };
+}
+
+/** Round to at most 2 decimals and trim float noise: 0.7999... -> 0.8, 0.0983 -> 0.1, 15 -> 15. */
+function formatPrice(value: number): string {
+  return String(parseFloat(value.toFixed(2)));
+}
+
+/** Notice line describing truncation or remaining pages, shared by the text result and the TUI. */
+function formatListNotice(truncated: boolean, startIndex: number, endDisplay: number, total: number): string | undefined {
+  const nextOffset = endDisplay + 1;
+
+  if (truncated) return `[Truncated: showing models ${startIndex + 1}-${endDisplay} of ${total}. Use offset=${nextOffset} to continue.]`;
+  if (endDisplay < total) return `[${total - endDisplay} more models in list. Use offset=${nextOffset} to continue.]`;
+
+  return undefined;
+}
+
 export default function (pi: ExtensionAPI) {
   pi.on("session_start", (_event, ctx) => {
     const config = loadConfig(ctx, "models");
@@ -42,48 +81,52 @@ export default function (pi: ExtensionAPI) {
       name: "model",
       label: "model",
       description:
-        "Inspect pi's model state. The \"current\" action returns the active model with metadata " +
-        "and thinking level. The \"list\" action returns models with metadata such as provider, " +
-        "id, name, API type, reasoning support, input modalities, cost, context window, and max " +
-        "output tokens. Lists can be filtered with scope/provider/model queries and paged with " +
-        `offset/limit. List output is one JSON object per line, truncated to ${DEFAULT_MAX_LINES} ` +
-        `models or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first).`,
-      promptSnippet: "List models or show the current model in use",
+        "Show the active model or list pi models. \"active\" returns the active model with " +
+        "metadata and thinking level. \"list\" returns models with metadata such as provider, id, name, " +
+        "API type, reasoning support, cost, context window, thinking levels, and availability, " +
+        "filterable with a Liqe (Lucene-like) query and paged with offset/limit. List output is " +
+        `one JSON object per line, truncated to ${LIST_MAX_LINES} models.`,
+      promptSnippet: "Show the active model or list pi models",
       promptGuidelines: [
-        "Use model when you need to know pi models, the active provider or model, or the current thinking level.",
+        "Use the model tool when you need pi model metadata, the active model, or the thinking level, rather than guessing.",
+        "When listing models with the model tool, include available:true in the query unless unavailable models are explicitly needed.",
       ],
       parameters: Type.Object({
-        action: StringEnum(["list", "current"] as const, {
-          description:
-            "\"current\" returns the active model with metadata and thinking level; " +
-            "\"list\" returns models with metadata.",
+        action: StringEnum(["active", "list"] as const, {
+          description: "\"active\" shows the active model; \"list\" lists the model catalog.",
         }),
-        scope: Type.Optional(StringEnum(["all", "available"] as const, {
+        query: Type.Optional(Type.String({
           description:
-            "For list: \"all\" lists every pi model; \"available\" (default) lists only " +
-            "models with auth configured.",
-        })),
-        provider: Type.Optional(Type.String({
-          description: "For list: filter by provider, case-insensitive substring (e.g., \"vercel\", \"moonshot\")",
-        })),
-        model: Type.Optional(Type.String({
-          description: "For list: filter by model id or display name, case-insensitive substring (e.g., \"claude\", \"deepseek\")",
+            "For list: filter models with a Liqe (Lucene-like) query. Bare terms match any " +
+            "field, and unquoted terms are case-insensitive substrings. The syntax supports " +
+            "AND/OR/NOT, grouping, wildcards, and numeric comparisons; quote values containing " +
+            "special characters (e.g., id:\"deepseek/deepseek-v4\"). Queryable fields are id, " +
+            "name, provider, api, reasoning (boolean), input (modalities), cost.input and " +
+            "cost.output (USD per 1M tokens), contextWindow, maxTokens, thinkingLevels, and " +
+            "available (boolean, true when auth is configured). The catalog is large, so " +
+            "include available:true unless every model is needed (e.g., \"claude " +
+            "available:true\", \"provider:openrouter cost.input:<1\").",
         })),
         offset: Type.Optional(Type.Number({
-          description: "For list: model number to start from (1-indexed)"
+          description: "For list: start from this model number (1-indexed)."
         })),
         limit: Type.Optional(Type.Number({
-          description: "For list: maximum number of models to return"
+          description: "For list: return at most this many models."
         })),
       }),
       renderCall(args, theme) {
         let text = `${theme.bold(theme.fg("toolTitle", "model"))} ${theme.fg("accent", args.action)}`;
 
-        if (args.action === "list") text += theme.fg("muted", ` ${args.scope ?? "available"}`);
-        if (args.provider) text += theme.fg("muted", ` provider:${args.provider}`);
-        if (args.model) text += theme.fg("muted", ` model:${args.model}`);
-        if (args.offset !== undefined || args.limit !== undefined) text += theme.fg("warning", ` from ${args.offset ?? 1}`);
-        if (args.limit !== undefined) text += theme.fg("warning", ` to ${(args.offset ?? 1) + args.limit - 1}`);
+        if (args.action === "list") {
+          const query = args.query?.trim();
+          if (query) text += theme.fg("muted", ` ${query}`);
+
+          if (args.offset !== undefined || args.limit !== undefined) {
+            const start = args.offset ?? 1;
+            const end = args.limit !== undefined ? start + args.limit - 1 : "end";
+            text += theme.fg("warning", ` ${start}-${end}`);
+          }
+        }
 
         return new Text(text, 0, 0);
       },
@@ -103,65 +146,92 @@ export default function (pi: ExtensionAPI) {
           return container;
         }
 
-        if (details.action === "current") {
-          const { model, thinkingLevel } = details.current;
-          container.addChild(new Text(theme.fg("muted", formatModel(model.provider, model.id, thinkingLevel)), 0, 0));
+        const addRows = (rows: ModelRow[]) => {
+          const widths = {
+            label: Math.max(...rows.map((row) => row.label.length)),
+            cost: Math.max(...rows.map((row) => row.cost.length)),
+            context: Math.max(...rows.map((row) => row.context.length)),
+          };
+
+          for (const row of rows) {
+            const cells = [
+              row.label.padEnd(widths.label),
+              row.cost.padStart(widths.cost),
+              row.context.padStart(widths.context),
+            ].join("  ");
+            const noAuthHint = row.available ? "" : theme.fg("dim", "  (no auth)");
+            container.addChild(new Text(theme.fg("muted", cells) + noAuthHint, 0, 0));
+          }
+        };
+
+        if (details.action === "active") {
+          const { model, thinkingLevel } = details.active;
+          addRows([toModelRow(model, thinkingLevel)]);
 
           return container;
         }
 
-        const filtered = context.args.provider !== undefined || context.args.model !== undefined;
+        const filtered = Boolean(context.args.query?.trim());
         const models = details.models ?? [];
         const total = details.total ?? models.length;
 
-        if (models.length > 0 && expanded) {
-          models.forEach((model) => {
-            const label = formatModel(model.provider, model.id);
-            const noAuthHint = !model.available ? theme.fg("dim", " (unavailable)") : "";
-            container.addChild(new Text(theme.fg("muted", label) + noAuthHint, 0, 0));
-          });
+        if (models.length > 0) {
+          const maxRows = expanded ? models.length : Math.min(models.length, COLLAPSED_MAX_ROWS);
+          addRows(models.slice(0, maxRows).map((model) => toModelRow(model)));
 
+          const hiddenRows = models.length - maxRows;
+          if (hiddenRows > 0) container.addChild(new Text(theme.fg("dim", `... (${hiddenRows} more, ${keyText("app.tools.expand")} to expand)`), 0, 0));
           container.addChild(new Spacer(1));
         }
 
-        const summary = total > 0 ? `${models.length !== total ? `${models.length} of ` : ""}${total} ${filtered ? "matched " : ""}model${total === 1 ? "" : "s"} listed` : `0 models${filtered ? " matched" : ""}`;
-        const truncatedHint = details.truncation?.truncated ? theme.fg("warning", " (truncated)") : "";
-        const expandHint = models.length > 0 && !expanded ? theme.fg("dim", ` (${keyText("app.tools.expand")} to expand)`) : "";
-        container.addChild(new Text(theme.fg("muted", summary) + truncatedHint + expandHint, 0, 0));
+        if (details.truncation?.truncated) {
+          const startIndex = context.args.offset ? Math.max(0, context.args.offset - 1) : 0;
+          const endDisplay = startIndex + models.length;
+          const notice = formatListNotice(true, startIndex, endDisplay, total);
+          if (notice) {
+            container.addChild(new Text(theme.fg("warning", notice), 0, 0));
+            container.addChild(new Spacer(1));
+          }
+        }
+
+        const summary = `${models.length !== total ? `${models.length} of ` : ""}${total} ${filtered ? "matched " : ""}model${total === 1 ? "" : "s"} listed.`;
+        container.addChild(new Text(theme.fg("muted", total > 0 ? summary : `No models ${filtered ? "matched" : "found"}.`), 0, 0));
 
         return container;
       },
       async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-        if (params.action === "current") {
+        if (params.action === "active") {
           const model = ctx.model;
-          if (!model) throw new Error("No model is currently selected");
+          if (!model) throw new Error("No model is active.");
 
           const thinkingLevel = pi.getThinkingLevel();
-          const current = { model: toMetadata(model, true), thinkingLevel };
+          const active = { model: toMetadata(model, true), thinkingLevel };
 
           return {
-            content: [{ type: "text", text: JSON.stringify(current) }],
-            details: { action: "current", current } satisfies ModelToolDetails,
+            content: [{ type: "text", text: JSON.stringify(active) }],
+            details: { action: "active", active } satisfies ModelToolDetails,
           };
         }
 
-        const providerQuery = params.provider?.trim().toLowerCase();
-        const modelQuery = params.model?.trim().toLowerCase();
-        const filtered = providerQuery !== undefined || modelQuery !== undefined;
+        const queryText = params.query?.trim();
+        const filtered = Boolean(queryText);
 
-        const scope = params.scope ?? "available";
-        const source = scope === "all" ? ctx.modelRegistry.getAll() : ctx.modelRegistry.getAvailable();
+        let listQuery = null;
+        if (queryText) {
+          try {
+            listQuery = parse(queryText);
+          } catch (error) {
+            throw new Error(`Invalid Liqe query ${JSON.stringify(queryText)}: ${error instanceof Error ? error.message : String(error)}`);
+          }
+        }
 
-        const matched = source.filter((model) => {
-          if (providerQuery && !model.provider.toLowerCase().includes(providerQuery)) return false;
-          if (modelQuery && !model.id.toLowerCase().includes(modelQuery) && !model.name.toLowerCase().includes(modelQuery)) return false;
-          return true;
-        }).map((model) => toMetadata(model, scope === "all" ? ctx.modelRegistry.hasConfiguredAuth(model) : true));
+        const models = ctx.modelRegistry.getAll().map((model) => toMetadata(model, ctx.modelRegistry.hasConfiguredAuth(model)));
+        const matched = listQuery ? filter(listQuery, models) : models;
         const total = matched.length;
 
         if (total === 0) {
           return {
-            content: [{ type: "text", text: `0 models${filtered ? " matched" : ""}` }],
+            content: [{ type: "text", text: `No models ${filtered ? "matched" : "found"}.` }],
             details: { action: "list", models: [], total } satisfies ModelToolDetails,
           };
         }
@@ -169,7 +239,7 @@ export default function (pi: ExtensionAPI) {
         // Convert from 1-indexed offset to 0-indexed array access.
         const startIndex = params.offset ? Math.max(0, params.offset - 1) : 0;
         if (startIndex >= total) {
-          throw new Error(`Offset ${params.offset} is beyond end of list (${total} models total)`);
+          throw new Error(`Offset ${params.offset} is beyond the end of the list (${total} models total).`);
         }
 
         const endIndex = params.limit !== undefined ? Math.min(startIndex + params.limit, total) : total;
@@ -177,20 +247,16 @@ export default function (pi: ExtensionAPI) {
 
         // JSONL: one compact object per line, so truncation cuts at record boundaries.
         const truncation = truncateHead(selected.map((model) => JSON.stringify(model)).join("\n"), {
-          maxLines: DEFAULT_MAX_LINES,
-          maxBytes: DEFAULT_MAX_BYTES,
+          maxLines: LIST_MAX_LINES,
+          maxBytes: Infinity,
         });
 
         const delivered = truncation.truncated ? selected.slice(0, truncation.outputLines) : selected;
         const endDisplay = startIndex + delivered.length;
-        const nextOffset = endDisplay + 1;
 
         let text = truncation.content;
-        if (truncation.truncated) {
-          text += `\n\n[Truncated: showing models ${startIndex + 1}-${endDisplay} of ${total}; use offset=${nextOffset} to continue]`;
-        } else if (endDisplay < total) {
-          text += `\n\n[${total - endDisplay} more models in list; use offset=${nextOffset} to continue]`;
-        }
+        const notice = formatListNotice(truncation.truncated, startIndex, endDisplay, total);
+        if (notice) text += `\n\n${notice}`;
 
         return {
           content: [{ type: "text", text }],

package/extensions/name/index.ts

@@ -17,33 +17,29 @@ export default function (pi: ExtensionAPI) {
       name: "name",
       label: "name",
       description:
-        "Set or refresh the current session's concise name, shown in the session selector " +
-        "instead of the first-message preview.",
-      promptSnippet: "Set or refresh the current session's concise name",
+        "Name or rename the current session. The name is a concise label shown in the session " +
+        "selector instead of the first-message preview.",
+      promptSnippet: "Name or rename the current session",
       promptGuidelines: [
-        "Use name when the session would benefit from a concise, recognizable name, especially after a long, vague, or pasted opening prompt.",
-        "Use name to refresh the session's name only after a substantial shift in the conversation's focus; do not rename for minor follow-ups.",
-        "Include a concise reason for name when it would help explain why the name identifies the session.",
+        "Use the name tool when the session needs a concise, recognizable label, especially after a long, vague, or pasted opening prompt.",
+        "Use the name tool to rename the session only after a substantial shift in the conversation's focus, not for minor follow-ups.",
+        "Use the name tool with a reason when it helps explain why the name identifies the session.",
       ],
       parameters: Type.Object({
         name: Type.String({
           minLength: 1,
           maxLength: 120,
           description:
-            "Concise session name. Use a short, recognizable phrase in sentence case, " +
-            "ideally <= 72 characters. Do not use surrounding quotes, trailing punctuation, or " +
-            "generic prefixes like \"Chat about\". Examples: \"Refactor auth module\", " +
-            "\"Debug flaky CI pipeline\", \"Draft Q3 planning doc\".",
+            "Use a short, recognizable phrase in sentence case, ideally <= 72 characters " +
+            "(e.g., \"Refactor auth module\", \"Debug flaky CI pipeline\"). Do not use " +
+            "surrounding quotes, trailing punctuation, or generic prefixes like \"Chat about\".",
         }),
         reason: Type.Optional(Type.String({
           maxLength: 240,
           description:
-            "Optional concise reason for naming or renaming the current session. Explain what " +
-            "made the name useful, such as a long pasted prompt, ambiguous first message, task " +
-            "handoff, or substantial topic shift. Write a complete sentence, and keep it brief " +
-            "and user-facing. Examples: \"The long pasted prompt needed a stable label.\", " +
-            "\"The focus shifted from debugging to README updates.\", " +
-            "\"The task migrated from a previous session.\"",
+            "Explain briefly why the session was named or renamed, such as a long pasted " +
+            "prompt, an ambiguous first message, or a topic shift. Write one user-facing " +
+            "sentence (e.g., \"The focus shifted from debugging to README updates.\").",
         })),
       }),
       renderCall(args, theme) {
@@ -70,12 +66,12 @@ export default function (pi: ExtensionAPI) {
       },
       async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
         const name = sanitizeText(params.name);
-        if (!name) throw new Error("Session name was empty after normalization; provide a short, non-empty phrase");
+        if (!name) throw new Error("Session name was empty after normalization; provide a short, non-empty phrase.");
 
         const previous = pi.getSessionName() ?? null;
         if (previous === name) {
           return {
-            content: [{ type: "text", text: `Session is already named "${name}"; no change` }],
+            content: [{ type: "text", text: `Session is already named "${name}". Nothing changed.` }],
             details: { changed: false, previous },
           };
         }
@@ -83,7 +79,7 @@ export default function (pi: ExtensionAPI) {
         pi.setSessionName(name);
 
         return {
-          content: [{ type: "text", text: `${previous ? `Renamed session from "${previous}" to "${name}"` : `Named session "${name}"`}` }],
+          content: [{ type: "text", text: `${previous ? `Renamed session from "${previous}" to "${name}".` : `Named session "${name}".`}` }],
           details: { changed: true, previous },
         };
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-spark",
-  "version": "0.9.5",
+  "version": "0.10.1",
   "description": "A small, opinionated collection of pi extensions",
   "keywords": [
     "pi-coding-agent",
@@ -28,6 +28,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "liqe": "^3.8.7",
     "ms": "4.0.0-nightly.202508271359",
     "zod": "^4.4.3"
   },