@jopqior/pi-subagents-model-selector 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jopqior
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# @jopqior/pi-subagents-model-selector
+
+[![npm version](https://img.shields.io/npm/v/@jopqior/pi-subagents-model-selector?style=flat&logo=npm&logoColor=white)](https://www.npmjs.com/package/@jopqior/pi-subagents-model-selector) [![CI](https://img.shields.io/github/actions/workflow/status/Jopqior/gotgenes-pi-packages/ci.yml?style=flat&logo=github&label=CI)](https://github.com/Jopqior/gotgenes-pi-packages/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-6.x-3178C6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![pnpm](https://img.shields.io/badge/pnpm-%3E%3D11-F69220?style=flat&logo=pnpm&logoColor=white)](https://pnpm.io/) [![Pi Package](https://img.shields.io/badge/Pi-Package-6366F1?style=flat)](https://pi.mariozechner.at/)
+
+Ask for model and thinking before every new in-process `@jopqior/pi-subagents` child session.
+
+Installing or upgrading the core alone does not change selection.
+
+## Install
+
+Load **after** `@jopqior/pi-subagents`.
+Pi loads packages in the order they are listed in `.pi/settings.json`, and this extension registers its provider with the subagents service at load time — so the core must load first.
+
+```bash
+pi install npm:@jopqior/pi-subagents
+pi install npm:@jopqior/pi-subagents-model-selector
+```
+
+Then list those two `npm:` sources in that order:
+
+```json
+{
+  "packages": [
+    "npm:@jopqior/pi-subagents",
+    "npm:@jopqior/pi-subagents-model-selector"
+  ]
+}
+```
+
+Or load from a checkout:
+
+```json
+{
+  "packages": [
+    "../packages/pi-subagents",
+    "../packages/pi-subagents-model-selector"
+  ]
+}
+```
+
+If the core is missing, failed to load, or lacks `registerSpawnSelectionProvider`, this extension throws a configuration error at initialization and does not activate.
+
+## Behavior
+
+Every **new** run in an enabled root's in-process tree asks twice: model, then thinking.
+Foreground tool calls, background tool calls, and `SubagentsService.spawn()` all go through the same gate.
+
+The operator's pair is applied after ordinary call and config resolution.
+It overrides defaults, explicit `model`/`thinking` arguments, and `locked:` values for those two fields only.
+Other locked fields are unchanged.
+
+The catalogue is every authenticated available model of the session whose manager is spawning — not a process-global list, and not `/scoped-models`.
+A model that supports only `off` still shows `off` and requires confirmation.
+
+Concurrent requests are FIFO at the root chooser.
+A queued run does not open a dialog until it is admitted.
+Cancel either dialog stops that run without creating a workspace or child session.
+
+Missing UI, a UI that is not yet attached, an empty catalogue, or an invalid selection fails that run explicitly.
+There is no default, timeout, remembered choice, or retry.
+
+Nested children still route to the root UI, including when this package is excluded from them.
+A child that also loads this package receives an `inherited` registration and installs no second queue.
+
+`resume` does not re-ask.
+The parent's active model, thinking level, agent files, and tool-call arguments are not rewritten to carry the choice.
+
+## Lifecycle
+
+The extension captures `getSubagentsService()` once during initialization and registers the provider immediately, before any `session_start` handler can spawn.
+It attaches `ctx.ui.select` at `session_start` and closes the chooser at `session_shutdown`.
+A request that arrives before the UI is attached fails closed rather than waiting for a later sequential handler.
+
+Print, JSON, and other non-interactive sessions cannot satisfy the selection requirement.
+
+## Limitations
+
+- Out-of-process children and third-party session factories are not covered.
+- The dialogs are Pi's generic `ui.select()`, not the native `/model` picker.
+- Public task status stays `running` while waiting.
+  Pending selection is private widget, foreground, and background wording.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@jopqior/pi-subagents-model-selector",
+  "version": "0.1.0",
+  "description": "Pi extension that asks for model and thinking before every new pi-subagents run.",
+  "type": "module",
+  "imports": {
+    "#src/*": "./src/*",
+    "#test/*": "./test/*"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "subagents",
+    "model-selector"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": {
+    "name": "Jopqior"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jopqior/gotgenes-pi-packages.git",
+    "directory": "packages/pi-subagents-model-selector"
+  },
+  "homepage": "https://github.com/Jopqior/gotgenes-pi-packages/tree/main/packages/pi-subagents-model-selector#readme",
+  "bugs": {
+    "url": "https://github.com/Jopqior/gotgenes-pi-packages/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.84.4",
+    "@earendil-works/pi-coding-agent": ">=0.84.4"
+  },
+  "dependencies": {
+    "@jopqior/pi-subagents": "^1.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.11",
+    "@earendil-works/pi-ai": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@types/node": "^22.15.3",
+    "rumdl": "0.2.24",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "check": "pnpm --dir ../pi-subagents run build:types && tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint:md": "rumdl check .",
+    "lint": "biome check . && eslint . && pnpm run lint:md"
+  }
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+/**
+ * pi-subagents-model-selector — ask for model and thinking on every new run.
+ *
+ * Captures the core service once at initialization and registers the chooser
+ * before any session_start handler can spawn. An inherited registration
+ * installs nothing: the root chooser already serves the tree.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getSubagentsService } from "@jopqior/pi-subagents";
+import { ModelSelector } from "./model-selector";
+
+const MISSING_CORE_MESSAGE =
+  "@jopqior/pi-subagents-model-selector requires @jopqior/pi-subagents with registerSpawnSelectionProvider, loaded before this extension.";
+
+export default function piSubagentsModelSelectorExtension(
+  pi: ExtensionAPI,
+): void {
+  const service = getSubagentsService();
+  if (service === undefined) {
+    throw new Error(MISSING_CORE_MESSAGE);
+  }
+  const register = (service as { registerSpawnSelectionProvider?: unknown })
+    .registerSpawnSelectionProvider;
+  if (typeof register !== "function") {
+    throw new Error(MISSING_CORE_MESSAGE);
+  }
+
+  const chooser = new ModelSelector();
+  const registration = service.registerSpawnSelectionProvider(chooser);
+  if (registration.kind === "inherited") {
+    return;
+  }
+
+  pi.on("session_start", (_event, ctx) => {
+    chooser.attachUI({
+      hasUI: ctx.hasUI,
+      select: (title, options, signal) =>
+        ctx.ui.select(title, options, { signal }),
+    });
+  });
+
+  pi.on("session_shutdown", () => {
+    chooser.close();
+    registration.dispose();
+  });
+}

package/src/model-selector.ts

@@ -0,0 +1,186 @@
+/**
+ * model-selector.ts — Two public Pi dialogs for one spawn selection.
+ *
+ * Model first, then thinking. Every option — including a single `off` — is
+ * confirmed explicitly. Missing UI is an error, not an approval.
+ */
+
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
+import type {
+  SpawnSelection,
+  SpawnSelectionProvider,
+  SpawnSelectionRequest,
+} from "@jopqior/pi-subagents";
+import {
+  SelectionQueue,
+  SelectionQueueCancelledError,
+  SelectionQueueClosedError,
+} from "./selection-queue";
+
+const DESCRIPTION_LIMIT = 80;
+
+const NO_UI = "Spawn model selection requires an interactive UI.";
+const NO_MODELS = "No models are available to select.";
+const CLOSED = "Spawn model selection is closed.";
+
+export interface SelectionUIPort {
+  readonly hasUI: boolean;
+  select(
+    title: string,
+    options: string[],
+    signal: AbortSignal,
+  ): Promise<string | undefined>;
+}
+
+export class ModelSelector implements SpawnSelectionProvider {
+  private readonly levelsFor: (
+    model: Model<Api>,
+  ) => readonly SpawnSelection["thinkingLevel"][];
+  private readonly queue = new SelectionQueue();
+  private ui: SelectionUIPort | undefined;
+
+  constructor(
+    deps: {
+      supportedThinkingLevels?: (
+        model: Model<Api>,
+      ) => readonly SpawnSelection["thinkingLevel"][];
+    } = {},
+  ) {
+    this.levelsFor = deps.supportedThinkingLevels ?? getSupportedThinkingLevels;
+  }
+
+  attachUI(ui: SelectionUIPort): void {
+    this.ui = ui;
+  }
+
+  close(): void {
+    this.ui = undefined;
+    this.queue.close();
+  }
+
+  async select(
+    request: SpawnSelectionRequest,
+    signal: AbortSignal,
+  ): Promise<SpawnSelection | undefined> {
+    this.assertReady(request);
+    try {
+      return await this.queue.enqueue(
+        async (dialogSignal) => this.runDialogs(request, signal, dialogSignal),
+        signal,
+      );
+    } catch (err) {
+      if (
+        err instanceof SelectionQueueCancelledError ||
+        err instanceof SelectionQueueClosedError
+      ) {
+        return undefined;
+      }
+      throw err;
+    }
+  }
+
+  private assertReady(request: SpawnSelectionRequest): void {
+    if (this.queue.closed) {
+      throw new Error(CLOSED);
+    }
+    if (!this.ui?.hasUI) {
+      throw new Error(NO_UI);
+    }
+    if (request.availableModels.length === 0) {
+      throw new Error(NO_MODELS);
+    }
+  }
+
+  private async runDialogs(
+    request: SpawnSelectionRequest,
+    requestSignal: AbortSignal,
+    dialogSignal: AbortSignal,
+  ): Promise<SpawnSelection | undefined> {
+    if (this.abandoned(requestSignal, dialogSignal)) {
+      return undefined;
+    }
+    const ui = this.ui;
+    if (!ui?.hasUI) {
+      throw new Error(NO_UI);
+    }
+
+    const labels = request.availableModels.map(modelLabel);
+    const modelChoice = await ui.select(
+      modelTitle(request),
+      [...labels],
+      dialogSignal,
+    );
+    if (
+      modelChoice === undefined ||
+      this.abandoned(requestSignal, dialogSignal)
+    ) {
+      return undefined;
+    }
+    const modelIndex = labels.indexOf(modelChoice);
+    const model =
+      modelIndex < 0 ? undefined : request.availableModels[modelIndex];
+    if (model === undefined) {
+      throw new Error(
+        `Selected option ${JSON.stringify(modelChoice)} does not match any offered model.`,
+      );
+    }
+
+    const levels = [...this.levelsFor(model)];
+    if (levels.length === 0) {
+      throw new Error(
+        `Model ${model.provider}/${model.id} has no supported thinking levels.`,
+      );
+    }
+    const thinkingChoice = await ui.select(
+      thinkingTitle(model),
+      [...levels],
+      dialogSignal,
+    );
+    if (
+      thinkingChoice === undefined ||
+      this.abandoned(requestSignal, dialogSignal)
+    ) {
+      return undefined;
+    }
+    if (!isListedLevel(thinkingChoice, levels)) {
+      throw new Error(
+        `Selected thinking level ${JSON.stringify(thinkingChoice)} is not supported.`,
+      );
+    }
+    return { model, thinkingLevel: thinkingChoice };
+  }
+
+  private abandoned(
+    requestSignal: AbortSignal,
+    dialogSignal: AbortSignal,
+  ): boolean {
+    return this.queue.closed || requestSignal.aborted || dialogSignal.aborted;
+  }
+}
+
+function isListedLevel(
+  value: string,
+  levels: readonly SpawnSelection["thinkingLevel"][],
+): value is SpawnSelection["thinkingLevel"] {
+  return levels.some((level) => level === value);
+}
+
+function modelLabel(model: Model<Api>): string {
+  return `${model.provider}/${model.id} — ${model.name}`;
+}
+
+function boundDescription(description: string): string {
+  if (description.length <= DESCRIPTION_LIMIT) {
+    return description;
+  }
+  return `${description.slice(0, DESCRIPTION_LIMIT - 1)}…`;
+}
+
+function modelTitle(request: SpawnSelectionRequest): string {
+  return `Select model for ${request.agentType} ${request.agentId} — ${boundDescription(request.description)}`;
+}
+
+function thinkingTitle(model: Model<Api>): string {
+  return `Select thinking level for ${model.provider}/${model.id} (${model.name})`;
+}

package/src/selection-queue.ts

@@ -0,0 +1,110 @@
+/**
+ * selection-queue.ts — FIFO ownership for one root chooser's dialogs.
+ *
+ * Independent of Pi: jobs are thunks that receive a dialog AbortSignal.
+ * Cancelling a waiting request removes it without running it; cancelling the
+ * active request aborts its dialog signal. close() invalidates the active job
+ * and drains waiters without confirmation.
+ */
+
+export class SelectionQueueCancelledError extends Error {
+  constructor(message = "The selection request was cancelled.") {
+    super(message);
+    this.name = "SelectionQueueCancelledError";
+  }
+}
+
+export class SelectionQueueClosedError extends Error {
+  constructor(message = "The selection queue is closed.") {
+    super(message);
+    this.name = "SelectionQueueClosedError";
+  }
+}
+
+type Job<T> = (dialogSignal: AbortSignal) => Promise<T>;
+
+interface Waiter {
+  readonly dialog: AbortController;
+  readonly reject: (reason: unknown) => void;
+}
+
+export class SelectionQueue {
+  #closed = false;
+  #tail: Promise<void> = Promise.resolve();
+  readonly #waiters = new Set<Waiter>();
+
+  get closed(): boolean {
+    return this.#closed;
+  }
+
+  enqueue<T>(job: Job<T>, signal: AbortSignal): Promise<T> {
+    if (this.#closed) {
+      return Promise.reject(new SelectionQueueClosedError());
+    }
+    if (signal.aborted) {
+      return Promise.reject(new SelectionQueueCancelledError());
+    }
+
+    const { promise, resolve, reject } = Promise.withResolvers<T>();
+    const dialog = new AbortController();
+    const waiter: Waiter = { dialog, reject };
+    this.#waiters.add(waiter);
+
+    const onAbort = (): void => {
+      this.#failWaiter(waiter, new SelectionQueueCancelledError());
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+
+    const run = this.#tail.then(async () => {
+      if (!this.#waiters.has(waiter)) {
+        return;
+      }
+      if (this.#closed) {
+        this.#failWaiter(waiter, new SelectionQueueClosedError());
+        return;
+      }
+      if (signal.aborted) {
+        this.#failWaiter(waiter, new SelectionQueueCancelledError());
+        return;
+      }
+      try {
+        resolve(await job(dialog.signal));
+      } catch (err) {
+        reject(err);
+      } finally {
+        this.#waiters.delete(waiter);
+      }
+    });
+
+    this.#tail = run.then(
+      () => undefined,
+      () => undefined,
+    );
+
+    const detachAbort = (): void => {
+      signal.removeEventListener("abort", onAbort);
+    };
+    void promise.then(detachAbort, detachAbort);
+
+    return promise;
+  }
+
+  close(): void {
+    if (this.#closed) {
+      return;
+    }
+    this.#closed = true;
+    for (const waiter of [...this.#waiters]) {
+      this.#failWaiter(waiter, new SelectionQueueClosedError());
+    }
+  }
+
+  #failWaiter(waiter: Waiter, err: Error): void {
+    if (!this.#waiters.has(waiter)) {
+      return;
+    }
+    this.#waiters.delete(waiter);
+    waiter.dialog.abort();
+    waiter.reject(err);
+  }
+}