pi-sessions 0.11.2 → 0.12.1

package/README.md

@@ -142,6 +142,7 @@ If you want to override the shortcut, put this in your `~/.pi/agent/settings.jso
       "pickerShortcut": "alt+p",
       "model": "openai-codex/gpt-5.6-terra",
       "thinkingLevel": "low",
+      "roster": ["anthropic/*", "openai-codex/gpt-5.6-terra:high"],
       "deferred": {
         "copyToClipboard": true
       }
@@ -152,6 +153,8 @@ If you want to override the shortcut, put this in your `~/.pi/agent/settings.jso
 
 `model` and `thinkingLevel` configure the agent that builds handoff prompts. They default to the new session's values when absent.
 
+`roster` limits which models a handoff may launch a child session on. Defaults to pi's own `enabledModels` scoping, then to all configured models. May optionally include a thinking level; listing a model more than once adds to the levels it allows.
+
 `deferred.copyToClipboard` (default `true`) controls whether deferred handoffs copy the resume command to the clipboard. When off, the resume command is only shown in the tool call.
 
 Subagents require the handoff and messaging features. Limit recursive delegation depth with `sessions.subagents.maxDepth` (default `2`):

package/extensions/session-handoff/extract.ts

@@ -26,7 +26,7 @@ import { type Static, Type } from "typebox";
 import { freshenModel } from "../shared/model-runtime.ts";
 import { getDefaultHandoffRunsDir, type HandoffSettings } from "../shared/settings.ts";
 import { parseTypeBoxValue } from "../shared/typebox.ts";
-import { resolveModelOverride } from "./model.ts";
+import { resolveModelPattern } from "./model.ts";
 
 const MAX_HANDOFF_EXTRACTION_ATTEMPTS = 3;
 const HANDOFF_EXTRACTION_RETRY_PROMPT =
@@ -111,7 +111,7 @@ export async function generateHandoffDraftFromSessionManager({
   requestResponse?: boolean | undefined;
 }): Promise<HandoffDraftResult | undefined> {
   const modelOverride = settings.model
-    ? resolveModelOverride(modelRuntime, settings.model, settings.thinkingLevel)
+    ? resolveModelPattern(modelRuntime, settings.model, settings.thinkingLevel)
     : undefined;
   let model = modelOverride?.model;
   if (!model) {

package/extensions/session-handoff/install.ts

@@ -19,6 +19,7 @@ import type { HandoffLaunchTarget } from "./launch-target.ts";
 import { HANDOFF_BOOTSTRAP_FAILED_CUSTOM_TYPE } from "./metadata.ts";
 import { openSessionReferencePicker } from "./picker.ts";
 import { SESSION_TOKEN_PREFIX } from "./query.ts";
+import { type HandoffRoster, resolveHandoffRoster } from "./roster.ts";
 import {
   executeSessionHandoffTool,
   type HandoffToolParams,
@@ -57,6 +58,7 @@ export function installHandoff(
   function registerHandoffTool(
     models: readonly Model<Api>[],
     launchTargets: readonly HandoffLaunchTarget[],
+    roster: HandoffRoster | undefined,
   ): void {
     pi.registerTool({
       name: "session_handoff",
@@ -64,7 +66,7 @@ export function installHandoff(
       description: "Start a new Pi session with a self-contained task.",
       promptSnippet:
         "Delegate bounded work to a background subagent or hand off context to another Pi session",
-      promptGuidelines: buildHandoffPromptGuidelines(launchTargets, models),
+      promptGuidelines: buildHandoffPromptGuidelines(launchTargets, models, roster),
       parameters: Type.Object({
         goal: Type.String({
           description:
@@ -141,6 +143,7 @@ export function installHandoff(
           ctx,
           modelRuntime,
           launchTargets,
+          roster,
           (sessionId, status) => clipboardStatusBySessionId.set(sessionId, status),
         );
       },
@@ -202,14 +205,20 @@ export function installHandoff(
 
   return {
     async onSessionStart(_event, ctx) {
+      const models = ctx.modelRegistry.getAvailable();
       registerHandoffTool(
-        ctx.modelRegistry.getAvailable(),
+        models,
         createHandoffLaunchTargets({
           pi,
           splitBackend,
           copyDeferredToClipboard: settings.handoff.deferred.copyToClipboard,
           additionalTargets: deps.getLaunchTargets?.() ?? [],
         }),
+        resolveHandoffRoster({
+          models,
+          patterns: settings.handoff.roster,
+          scopedModels: ctx.scopedModels,
+        }),
       );
 
       await consumePendingHandoffBootstrap(

package/extensions/session-handoff/model.ts

@@ -1,34 +1,20 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import {
+  type ExactModelReference,
+  findModelByReference,
+  formatModelSelection,
+  selectModel,
+} from "../shared/model.ts";
 import { formatAvailableModelList, resolveAuthenticatedModel } from "../shared/model-resolution.ts";
-import { isThinkingLevel } from "../shared/thinking-levels.ts";
+import { type HandoffRoster, selectFromRoster } from "./roster.ts";
 
 export function formatModelArgument(
   model: Model<Api> | undefined,
   thinkingLevel: ThinkingLevel | undefined,
 ): string | undefined {
-  if (!model) {
-    return undefined;
-  }
-
-  const base = `${model.provider}/${model.id}`;
-  return thinkingLevel ? `${base}:${thinkingLevel}` : base;
-}
-
-export function parseModelArgument(value: string): {
-  model: string;
-  thinkingLevel?: ThinkingLevel | undefined;
-} {
-  const separator = value.lastIndexOf(":");
-  const suffix = separator >= 0 ? value.slice(separator + 1) : undefined;
-  if (!isThinkingLevel(suffix)) {
-    return { model: value };
-  }
-  return {
-    model: value.slice(0, separator),
-    thinkingLevel: suffix,
-  };
+  return model ? formatModelSelection(selectModel(model, thinkingLevel)) : undefined;
 }
 
 export interface HandoffModelOverride {
@@ -36,7 +22,41 @@ export interface HandoffModelOverride {
   thinkingLevel: ThinkingLevel | undefined;
 }
 
-export function resolveModelOverride(
+/**
+ * Resolves the model a handoff launches its child on. A roster replaces Pi's CLI
+ * matching entirely: fuzzy aliases resolve across every authenticated provider,
+ * which is how delegated work lands on a metered provider that happens to serve
+ * the same model id, so a rostered handoff accepts only an exact roster entry.
+ */
+export function resolveChildModel(
+  modelRuntime: ModelRuntime,
+  roster: HandoffRoster | undefined,
+  requested: ExactModelReference,
+  thinkingLevel: ThinkingLevel | undefined,
+): HandoffModelOverride {
+  if (!roster) {
+    return resolveModelPattern(
+      modelRuntime,
+      formatModelSelection({ ...requested, thinkingLevel: undefined }),
+      thinkingLevel,
+    );
+  }
+
+  const level = selectFromRoster(roster, requested, thinkingLevel);
+  const model = findModelByReference(modelRuntime.getAvailableSnapshot(), requested);
+  if (!model) {
+    throw new Error(
+      `Model "${requested.provider}/${requested.modelId}" is no longer an available authenticated model.`,
+    );
+  }
+  return { model, thinkingLevel: level };
+}
+
+/**
+ * Resolves a user-configured model pattern with Pi's CLI grammar, including fuzzy
+ * aliases. Only for settings the user writes by hand; never for a model's choice.
+ */
+export function resolveModelPattern(
   modelRuntime: ModelRuntime,
   modelPattern: string,
   thinkingLevel?: ThinkingLevel | undefined,

package/extensions/session-handoff/roster.ts

@@ -0,0 +1,162 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ScopedModel } from "@earendil-works/pi-coding-agent";
+import type { ExactModelReference, ModelSelection } from "../shared/model.ts";
+
+export interface HandoffRosterEntry extends ExactModelReference {
+  /** The thinking levels this model may run at, or undefined for the agent's choice. */
+  thinkingLevels: readonly ThinkingLevel[] | undefined;
+}
+
+export type HandoffRoster = readonly HandoffRosterEntry[];
+
+/**
+ * Chooses the roster a handoff selects from, in descending priority: an explicit
+ * `sessions.handoff.roster`, the session's own scoped models (`enabledModels`),
+ * then everything authenticated. The middle tier lets a curated model cycle
+ * govern delegation too; the top tier exists for when the two should disagree.
+ */
+export function resolveHandoffRoster(options: {
+  models: readonly Model<Api>[];
+  patterns: readonly ModelSelection[];
+  scopedModels: readonly ScopedModel[];
+}): HandoffRoster | undefined {
+  const configured = buildHandoffRoster(options.models, options.patterns);
+  if (configured) {
+    return configured;
+  }
+  return options.scopedModels.length > 0 ? options.scopedModels.map(scopedEntry) : undefined;
+}
+
+function scopedEntry(scoped: ScopedModel): HandoffRosterEntry {
+  return {
+    provider: scoped.model.provider,
+    modelId: scoped.model.id,
+    thinkingLevels: scoped.thinkingLevel ? [scoped.thinkingLevel] : undefined,
+  };
+}
+
+/**
+ * Expands configured roster patterns against the authenticated models. A roster
+ * only ever narrows what a handoff may launch, so patterns that match nothing
+ * are dropped rather than raised; the resulting roster is still safe, just
+ * smaller. An unconfigured roster returns undefined, deferring to the next tier.
+ */
+export function buildHandoffRoster(
+  models: readonly Model<Api>[],
+  patterns: readonly ModelSelection[],
+): HandoffRoster | undefined {
+  if (patterns.length === 0) {
+    return undefined;
+  }
+
+  const entries = new Map<string, HandoffRosterEntry>();
+  for (const pattern of patterns) {
+    const provider = globMatcher(pattern.provider);
+    const modelId = globMatcher(pattern.modelId);
+    for (const model of models) {
+      if (!provider.test(model.provider) || !modelId.test(model.id)) {
+        continue;
+      }
+      const key = `${model.provider}/${model.id}`;
+      const existing = entries.get(key);
+      entries.set(key, {
+        provider: model.provider,
+        modelId: model.id,
+        thinkingLevels: mergeThinkingLevels(existing, pattern.thinkingLevel),
+      });
+    }
+  }
+
+  return [...entries.values()];
+}
+
+/**
+ * Narrows a requested model to its roster entry. An entry listing a single
+ * thinking level pins it, so the agent may leave the level out; an entry listing
+ * several makes the choice mandatory.
+ */
+export function selectFromRoster(
+  roster: HandoffRoster,
+  requested: ExactModelReference,
+  thinkingLevel: ThinkingLevel | undefined,
+): ThinkingLevel | undefined {
+  if (roster.length === 0) {
+    throw new Error(
+      "session_handoff cannot override the model: sessions.handoff.roster matches no authenticated model.",
+    );
+  }
+
+  const entry = roster.find(
+    (candidate) =>
+      candidate.provider === requested.provider && candidate.modelId === requested.modelId,
+  );
+  if (!entry) {
+    throw new Error(
+      `Model "${requested.provider}/${requested.modelId}" is not on the handoff roster. Allowed models: ${formatRoster(roster)}.`,
+    );
+  }
+
+  const allowed = entry.thinkingLevels;
+  if (!allowed) {
+    return thinkingLevel;
+  }
+  if (!thinkingLevel) {
+    if (allowed.length > 1) {
+      throw new Error(
+        `The handoff roster requires a thinking level for "${formatEntryReference(entry)}": one of ${allowed.join(", ")}.`,
+      );
+    }
+    return allowed[0];
+  }
+  if (!allowed.includes(thinkingLevel)) {
+    throw new Error(
+      `The handoff roster does not allow thinking level ${thinkingLevel} for "${formatEntryReference(entry)}"; allowed: ${allowed.join(", ")}.`,
+    );
+  }
+  return thinkingLevel;
+}
+
+export function formatRoster(roster: HandoffRoster): string {
+  return roster.map(formatRosterEntry).join(", ");
+}
+
+export function formatRosterEntry(entry: HandoffRosterEntry): string {
+  const reference = formatEntryReference(entry);
+  if (!entry.thinkingLevels) {
+    return reference;
+  }
+  return entry.thinkingLevels.length === 1
+    ? `${reference}:${entry.thinkingLevels[0]}`
+    : `${reference}:{${entry.thinkingLevels.join(",")}}`;
+}
+
+function formatEntryReference(entry: ExactModelReference): string {
+  return `${entry.provider}/${entry.modelId}`;
+}
+
+function mergeThinkingLevels(
+  existing: HandoffRosterEntry | undefined,
+  added: ThinkingLevel | undefined,
+): readonly ThinkingLevel[] | undefined {
+  if (!added) {
+    return undefined;
+  }
+  if (!existing) {
+    return [added];
+  }
+  if (!existing.thinkingLevels) {
+    return undefined;
+  }
+  return existing.thinkingLevels.includes(added)
+    ? existing.thinkingLevels
+    : [...existing.thinkingLevels, added];
+}
+
+function globMatcher(pattern: string): RegExp {
+  const source = pattern
+    .split("*")
+    .map((segment) => segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join(".*");
+  return new RegExp(`^${source}$`);
+}

package/extensions/session-handoff/tool-schema.ts

@@ -1,7 +1,7 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
-import { formatAvailableModelList } from "../shared/model-resolution.ts";
 import { type HandoffLaunchTarget, SUBAGENT_LAUNCH } from "./launch-target.ts";
+import { formatRosterEntry, type HandoffRoster } from "./roster.ts";
 
 export function buildHandoffLaunchSchema(targets: readonly HandoffLaunchTarget[]) {
   const descriptions = targets.flatMap((target) =>
@@ -31,6 +31,9 @@ const MODEL_INHERITANCE_GUIDELINES = [
   "To run the handoff on a different model, set both provider and model together (both are required).",
 ];
 
+const RESTRICTED_THINKING_GUIDELINE =
+  'A ":level" suffix on a listed model limits it to those thinking levels; set thinkingLevel to one of them, or leave it unset when only one is listed.';
+
 const SUBAGENT_MODEL_OVERRIDE_GUIDELINE =
   "For subagents, choose the model that best fits the delegated task; for directional or deferred handoffs, only override the model when the task clearly warrants it. When unsure, ask the user for their preference.";
 
@@ -40,15 +43,19 @@ const DEFAULT_MODEL_OVERRIDE_GUIDELINE =
 export function buildHandoffPromptGuidelines(
   targets: readonly HandoffLaunchTarget[],
   models: readonly Model<Api>[],
+  roster: HandoffRoster | undefined,
 ): string[] {
   const hasSubagent = targets.some((target) => target.value === SUBAGENT_LAUNCH);
+  const selectable =
+    roster?.map(formatRosterEntry) ?? models.map((model) => `${model.provider}/${model.id}`);
   return [
     ...(hasSubagent ? SUBAGENT_GUIDELINES : []),
     LAUNCH_TARGET_GUIDELINE,
     ...MODEL_INHERITANCE_GUIDELINES,
     hasSubagent ? SUBAGENT_MODEL_OVERRIDE_GUIDELINE : DEFAULT_MODEL_OVERRIDE_GUIDELINE,
-    ...(models.length > 0
-      ? [`Available models, given as provider/model-id: ${formatAvailableModelList(models)}.`]
+    ...(selectable.length > 0
+      ? [`Available models, given as provider/model-id: ${selectable.join(", ")}.`]
       : []),
+    ...(roster?.some((entry) => entry.thinkingLevels) ? [RESTRICTED_THINKING_GUIDELINE] : []),
   ];
 }

package/extensions/session-handoff/tool.ts

@@ -12,8 +12,9 @@ import {
   type HandoffLaunchValue,
 } from "./launch-target.ts";
 import { createChildGeneratedHandoffBootstrap } from "./metadata.ts";
-import { formatModelArgument, resolveModelOverride } from "./model.ts";
+import { formatModelArgument, resolveChildModel } from "./model.ts";
 import { buildLaunchReceipt } from "./receipt.ts";
+import type { HandoffRoster } from "./roster.ts";
 import { formatHandoffLaunchFailure, prepareHandoffLaunch } from "./spawn.ts";
 import type { HandoffToolDetails } from "./tool-contract.ts";
 
@@ -39,6 +40,7 @@ export async function executeSessionHandoffTool(
   ctx: ExtensionContext,
   modelRuntime: ModelRuntime,
   launchTargets: readonly HandoffLaunchTarget[],
+  roster: HandoffRoster | undefined,
   recordClipboardStatus: (sessionId: string, status: ClipboardStatus) => void,
 ) {
   const goal = params.goal.trim();
@@ -90,7 +92,7 @@ export async function executeSessionHandoffTool(
   }
   const override =
     provider && modelId
-      ? resolveModelOverride(modelRuntime, `${provider}/${modelId}`, params.thinkingLevel)
+      ? resolveChildModel(modelRuntime, roster, { provider, modelId }, params.thinkingLevel)
       : undefined;
   const childModel = override?.model ?? ctx.model;
   const thinkingLevel = override?.thinkingLevel ?? params.thinkingLevel ?? pi.getThinkingLevel();

package/extensions/session-search/install.ts

@@ -88,7 +88,8 @@ export function installSearch(pi: ExtensionAPI, deps: SearchInstallDeps): void {
         Type.Union(
           [Type.Literal("relevance"), Type.Literal("modified_desc"), Type.Literal("modified_asc")],
           {
-            description: "Display order for returned matches",
+            description:
+              "Display order for returned matches: `relevance`, `modified_desc`, or `modified_asc`. Defaults to `relevance` when a query is present and `modified_desc` otherwise.",
           },
         ),
       ),

package/extensions/shared/model.ts

@@ -1,10 +1,51 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Api, Model } from "@earendil-works/pi-ai";
+import { isThinkingLevel } from "./thinking-levels.ts";
 
 export interface ExactModelReference {
   provider: string;
   modelId: string;
 }
 
+/**
+ * The structured representation of "which model, at which thinking level". Pi's
+ * CLI grammar spells this `provider/model-id[:level]`; that string is an edge
+ * format, parsed on the way in and rebuilt on the way out.
+ */
+export interface ModelSelection extends ExactModelReference {
+  thinkingLevel: ThinkingLevel | undefined;
+}
+
+export function parseModelSelection(value: string): ModelSelection {
+  const separator = value.lastIndexOf(":");
+  const suffix = separator >= 0 ? value.slice(separator + 1) : undefined;
+  const thinkingLevel = isThinkingLevel(suffix) ? suffix : undefined;
+  const reference = thinkingLevel ? value.slice(0, separator) : value;
+
+  const boundary = reference.indexOf("/");
+  if (boundary <= 0 || boundary === reference.length - 1) {
+    throw new Error(`Expected a "provider/model-id" reference; got "${value}".`);
+  }
+
+  return {
+    provider: reference.slice(0, boundary),
+    modelId: reference.slice(boundary + 1),
+    thinkingLevel,
+  };
+}
+
+export function formatModelSelection(selection: ModelSelection): string {
+  const reference = `${selection.provider}/${selection.modelId}`;
+  return selection.thinkingLevel ? `${reference}:${selection.thinkingLevel}` : reference;
+}
+
+export function selectModel(
+  model: Model<Api>,
+  thinkingLevel: ThinkingLevel | undefined,
+): ModelSelection {
+  return { provider: model.provider, modelId: model.id, thinkingLevel };
+}
+
 export function findModelByReference(
   availableModels: readonly Model<Api>[],
   reference: ExactModelReference,

package/extensions/shared/settings.ts

@@ -4,6 +4,7 @@ import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
 import type { KeyId } from "@earendil-works/pi-tui";
 import { type Static, Type } from "typebox";
+import { type ModelSelection, parseModelSelection } from "./model.ts";
 import { isThinkingLevel } from "./thinking-levels.ts";
 import { parseTypeBoxValue } from "./typebox.ts";
 
@@ -30,6 +31,7 @@ const SESSION_FILE_SETTINGS_SCHEMA = Type.Object({
       persistRuns: Type.Optional(Type.Boolean()),
       model: Type.Optional(Type.String()),
       thinkingLevel: Type.Optional(Type.String()),
+      roster: Type.Optional(Type.Array(Type.String())),
       deferred: Type.Optional(
         Type.Object({
           copyToClipboard: Type.Optional(Type.Boolean()),
@@ -97,6 +99,8 @@ export interface AskSettings extends AgentModelSettings {
 export interface HandoffSettings extends AgentModelSettings {
   pickerShortcut: KeyId;
   persistRuns: boolean;
+  /** Patterns naming the models a handoff may launch a child on. Empty means unrestricted. */
+  roster: readonly ModelSelection[];
   deferred: {
     copyToClipboard: boolean;
   };
@@ -182,6 +186,19 @@ function normalizePickerShortcut(value: string | undefined): KeyId {
   return (trimmed ? trimmed : "alt+o") as KeyId;
 }
 
+function normalizeRoster(value: readonly string[] | undefined): readonly ModelSelection[] {
+  return (value ?? [])
+    .map((pattern) => pattern.trim())
+    .filter(Boolean)
+    .map((pattern) => {
+      try {
+        return parseModelSelection(pattern);
+      } catch (error) {
+        throw new Error(`Invalid sessions.handoff.roster entry: ${(error as Error).message}`);
+      }
+    });
+}
+
 function parseThinkingLevel(value: string | undefined): ThinkingLevel | undefined {
   const trimmed = value?.trim();
   return isThinkingLevel(trimmed) ? trimmed : undefined;
@@ -238,6 +255,7 @@ function resolveSessionSettings(fileSettings: SessionFileSettings): SessionSetti
       ...resolveAgentModelSettings(fileSettings.handoff),
       pickerShortcut: normalizePickerShortcut(fileSettings.handoff?.pickerShortcut),
       persistRuns: fileSettings.handoff?.persistRuns ?? false,
+      roster: normalizeRoster(fileSettings.handoff?.roster),
       deferred: {
         copyToClipboard: fileSettings.handoff?.deferred?.copyToClipboard ?? true,
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sessions",
-  "version": "0.11.2",
+  "version": "0.12.1",
   "type": "module",
   "description": "Pi session search, ask, handoff, messaging, auto-titling, and indexing tools",
   "license": "MIT",
@@ -38,10 +38,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@earendil-works/pi-agent-core": "^0.83.0",
-    "@earendil-works/pi-ai": "^0.83.0",
-    "@earendil-works/pi-coding-agent": "^0.83.0",
-    "@earendil-works/pi-tui": "^0.83.0",
+    "@earendil-works/pi-agent-core": "^0.84.1",
+    "@earendil-works/pi-ai": "^0.84.1",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@earendil-works/pi-tui": "^0.84.1",
     "@types/node": "^25.6.2",
     "strip-ansi": "^7.2.0",
     "typebox": "^1.1.38",