@giladbarnea/pi-user-agents 0.0.2 → 0.0.3

package/INTERNALS.md

@@ -38,7 +38,7 @@ The shared runtime is extracted from the parent's `ModelRegistry` facade (`ctx.m
 
 ## Model name & alias resolution
 
-User-defined model aliases (`name` in `models.json` `modelOverrides`) take precedence: `-m opus` resolves to `claude-bridge/claude-opus-4-6` directly, without ambiguity. The extension checks for an exact name match before falling through to the SDK's `resolveCliModel`, which only checks `model.id` (never `model.name`) and otherwise falls back to substring matching — where "opus" collides with dozens of built-in models across the catalog.
+User-defined model aliases (`name` in `models.json` `modelOverrides`) take precedence: `-m opus` resolves to `claude-bridge/claude-opus-4-6` directly, without ambiguity. Other model values must exactly match a live model ID or canonical `provider/id` reference before the extension calls the SDK's `resolveCliModel`. Partial and custom model IDs are rejected.
 
 > **Note (known issue):** `enabledModels` (i.e., “Scoped models”) currently have no special role in how the extension resolves models. They should be promoted to the same precedence level as user-defined model names in a future fix.
 
@@ -48,7 +48,7 @@ Exact names should be unique: duplicate aliases silently select the first model,
 
 ### Semantic command coloring
 
-While you type, the editor paints `/agent` lines from the same semantic scan that drives submission parsing (see `PARSER_SPEC.md` §11): the command in the theme's `accent`, recognized leading options in `syntaxKeyword`, and valid values (quotes included) in `syntaxString`. Invalid thinking levels, unresolved model IDs or aliases, and unknown provider or tool names use `error`, as do explicitly blocked Pi options such as `-c`/`--continue` and options typed after the task prose has begun — along with their values. Validation comes from Pi's argument parser, model resolver, and live catalogs rather than a second editor grammar. Prose, unknown dash-words, quoted spans, and escaped words stay plain. All colors come from the active Pi theme, so custom themes and hot reload apply automatically.
+While you type, the editor paints `/agent` lines from the same semantic scan that drives submission parsing (see `PARSER_SPEC.md` §11): the command in the theme's `accent`, recognized leading options in `syntaxType`, and valid values (quotes included) in `syntaxString`. Invalid thinking levels, unresolved model IDs or aliases, and unknown provider or tool names use `error`, including blocked Pi options such as `-c`/`--continue` and `-p`/`--print`, plus options typed after the task prose has begun — along with their values. Validation comes from Pi's argument parser, model resolver, and live catalogs rather than a second editor grammar. Prose, unknown dash-words, quoted spans, and escaped words stay plain. All colors come from the active Pi theme, so custom themes and hot reload apply automatically.
 
 ### Eager argument completion
 

package/PARSER_SPEC.md

@@ -45,9 +45,10 @@ leading whitespace (unchanged from today).
 | `-i`, `--isolate` | boolean | Consumed here; `isolate = true` |
 | `-j`, `--join` | boolean | Consumed here; `context = true` |
 
-`-m` and `--model` are one semantic option. Both resolve once through Pi's
-`resolveCliModel()` path, and a preceding `--provider` scopes either spelling. `-j` is the
-extension's join option. A model option with no value and no remaining task ends in the normal
+`-m` and `--model` are one semantic option. Both require an exact live model ID, canonical
+`provider/id` reference, or user-defined alias before resolving through Pi's `resolveCliModel()`
+path. A preceding `--provider` scopes either spelling. `-j` is the extension's join option.
+A model option with no value and no remaining task ends in the normal
 **usage error**.
 
 ### 3b. Known pi options — declared statically; added to `forwardedArgs`
@@ -59,8 +60,7 @@ extension's join option. A model option with no value and no remaining task ends
 **Boolean** (consume no value):
 `--resume`/`-r`, `--no-session`, `--no-tools`/`-nt`, `--no-builtin-tools`/`-nbt`,
 `--no-extensions`/`-ne`, `--no-skills`/`-ns`, `--no-prompt-templates`/`-np`, `--no-themes`,
-`--no-context-files`/`-nc`, `--verbose`, `--approve`/`-a`, `--no-approve`/`-na`, `--offline`,
-`--print`/`-p`.
+`--no-context-files`/`-nc`, `--verbose`, `--approve`/`-a`, `--no-approve`/`-na`, `--offline`.
 
 Notes:
 - The shared declaration is a snapshot of `pi --help`; it is maintained by hand. There is no
@@ -77,7 +77,6 @@ Notes:
   The dequoted value is stored as **one element** in `forwardedArgs`
   (e.g. `["--system-prompt", "I am psyched"]`), so pi's `parseArgs` maps it as a single value.
   If a value opens with a quote but has no matching close, fall back to the whitespace-delimited token.
-- `--print`/`-p` is modeled as **boolean** here (pi's optional-value form would eat prose).
 
 Value examples:
 - `--system-prompt "I am psyched"` → value `I am psyched`.
@@ -86,8 +85,8 @@ Value examples:
 - `-m "gpt56s"` → `forwardedArgs` contains `--model`, `gpt56s`.
 
 ### 3c. Blocked pi options — rejected
-`-c`/`--continue`, `--theme <path>`, `--models`, `--export`, `--list-models`, `-h`/`--help`,
-`-v`/`--version`.
+`-c`/`--continue`, `-p`/`--print`, `--theme <path>`, `--models`, `--export`, `--list-models`,
+`-h`/`--help`, `-v`/`--version`.
 Appearing in **args mode** (leading) → hard **error**:
 `"/agent does not support <opt>; it would disrupt the background agent run."`
 
@@ -239,10 +238,9 @@ source spans:
 - `option` — a recognized, non-blocked leading option (extension-owned or forwarded);
 - `value` — the value consumed by a leading value-taking option. A quoted value's span
   includes its surrounding quotes;
-- `invalid-value` — a leading closed-set value rejected by the same canonical validation
-  used at submission and session creation: Pi's argument parser for thinking levels, the
-  child model resolver for model IDs and user-defined aliases, and the live provider and
-  tool catalogs;
+- `invalid-value` — a leading closed-set value rejected by the same validation used at
+  submission and session creation: Pi's argument parser for thinking levels, exact live model
+  IDs or user-defined aliases, and the live provider and tool catalogs;
 - `blocked` — a blocked option in args mode, plus the value a blocked value-taking option
   would consume (`--theme ./theme.json` yields two `blocked` tokens). Unlike
   `parseAgentCommand`, the scan never throws: it records the first blocked token and keeps
@@ -259,6 +257,6 @@ prose → usage error), so parsing and coloring cannot drift.
 cursor analysis (§10) and shifts token spans into editor-line coordinates.
 
 The editor coloring layer (`editor-coloring.ts`) maps token semantics onto Pi theme
-variables — command `accent`, options `syntaxKeyword`, valid values `syntaxString`, and
+variables — command `accent`, options `syntaxType`, valid values `syntaxString`, and
 invalid, blocked, or misplaced tokens `error` — by repainting the laid-out chunk text after
 word-wrap layout, so editing, wrapping, cursor behavior, and autocomplete are untouched.

package/README.md

@@ -36,17 +36,26 @@ The first preserves the session's knowledge before the context window fills, wit
 
 ### 2. Watch
 
-Every agent gets a row in a widget under the editor: status, task, live activity, and a one-cell context meter.
+Every agent gets a row in a widget under the editor: status, task, model, turn count, tool uses, elapsed time, a one-cell context meter, and the last line of live activity.
 
-```text
-✓ User agents
-  ↑↓ select · Enter view · x dispose · Esc back
-└─ ⏺ ✓ /agent ▇ i am testing the widget now - read a ton...
-     ⎿  Loaded several large Pi source and documentation...
-```
+<a href="screenshots/below-editor-widget.png">
+  <img src="screenshots/below-editor-widget.png" width="100%" alt="The user agents widget under the editor, showing one finished agent and its latest output">
+</a>
+
+<div align="center"><em>The widget sits under the editor and stays out of your way.</em></div>
+
+<br>
 
 Press `←` or `↓` from the editor to focus the widget, pick an agent, press `Enter`, and its overlay opens: the full conversation, streaming live, following the tail as it grows. Scroll up to pause following; `End` resumes it. Tool calls render as proper views — `read`, `edit`, `write`, `grep`, `find`, `ls`, and `bash` each get a dedicated format, everything else a readable generic one.
 
+<a href="screenshots/overlay.png">
+  <img src="screenshots/overlay.png" width="100%" alt="The agent overlay: a rendered bash call, its output, a todo update, and the final response, over the dimmed main conversation">
+</a>
+
+<div align="center"><em>The overlay, over a main conversation that never paused.</em></div>
+
+<br>
+
 The context meter is the agent's own footer gauge in one cell: it fills `▁▂▃▄▅▆▇█` against that agent's model context window and shifts color through the same stages as Pi's footer (dim, then muted at 40%, warning at 65%, error at 85%).
 
 ### 3. Steer
@@ -114,7 +123,7 @@ Everything goes through one command: `/agent [options] <task>`.
 ## Good to know
 
 - Result cards persist across session reloads; live agent sessions don't. After a reload you keep every card, not the steerable sessions.
-- Some accepted `pi` options have no effect on a background run (the session, approval, offline, API-key, and print families). They parse; they just don't do anything yet.
+- Some accepted `pi` options have no effect on a background run (the session, approval, offline, and API-key families). They parse; they just don't do anything yet.
 - `c` copies via `pbcopy`, so it's macOS-only for now.
 - The overlay caps very large tool outputs and omits thinking entries.
 

package/command-line.ts

@@ -292,13 +292,13 @@ function booleanOptionsWithoutChildEffect(): AgentOptionDefinition[] {
 		legacyBooleanOption("approve", ["--approve", "-a"]),
 		legacyBooleanOption("no-approve", ["--no-approve", "-na"]),
 		legacyBooleanOption("offline", ["--offline"]),
-		legacyBooleanOption("print", ["--print", "-p"]),
 	];
 }
 
 function blockedOptions(): AgentOptionDefinition[] {
 	return [
 		blockedOption("continue", ["-c", "--continue"]),
+		blockedOption("print", ["-p", "--print"]),
 		blockedOption("theme", ["--theme"], "value"),
 		blockedOption("models", ["--models"]),
 		blockedOption("export", ["--export"]),

package/editor-coloring.ts

@@ -11,7 +11,7 @@ export type StyleTheme = { fg(color: ThemeColor, text: string): string };
 
 export const AGENT_SEMANTIC_COLORS: Record<AgentTokenSemantic | "command", ThemeColor> = {
 	command: "accent",
-	option: "syntaxKeyword",
+	option: "syntaxType",
 	value: "syntaxString",
 	"invalid-value": "error",
 	blocked: "error",
@@ -36,7 +36,7 @@ type ColoredEditor = ColoringRuntimeEditor & { [COLORED_EDITOR]?: true };
  * Map an editor line to theme-colored spans via the shared semantic scan.
  * Returns undefined for lines that are not agent commands.
  *
- * @example computeAgentColorSpans("/agent -m gpt56s go")?.[1] // { start: 7, end: 9, color: "syntaxKeyword" }
+ * @example computeAgentColorSpans("/agent -m gpt56s go")?.[1] // { start: 7, end: 9, color: "syntaxType" }
  */
 export function computeAgentColorSpans(
 	line: string,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giladbarnea/pi-user-agents",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Run, view, and control background Pi agents.",
   "keywords": [
     "pi-package",
@@ -23,6 +23,7 @@
   "files": [
     "*.ts",
     "tool-render",
+    "screenshots",
     "README.md",
     "PARSER_SPEC.md",
     "INTERNALS.md",

package/runner.ts

@@ -239,6 +239,30 @@ export function createAgentValueValidator(
 	};
 }
 
+/**
+ * Return whether a model value exactly names a live ID, canonical reference, or user alias.
+ *
+ * @example isExactCatalogModelReference([{ provider: "openai", id: "gpt-5" } as Model], "openai/gpt-5") // true
+ */
+function isExactCatalogModelReference(
+	models: readonly Model[],
+	value: string,
+	provider: string | undefined,
+): boolean {
+	const normalizedValue = value.toLowerCase();
+	const normalizedProvider = provider?.toLowerCase();
+	const exactAliasMatch = models.some(
+		(model) => model.name?.toLowerCase() === normalizedValue,
+	);
+	const exactReferenceMatch = models.some(
+		(model) =>
+			(normalizedProvider === undefined || model.provider.toLowerCase() === normalizedProvider) &&
+			(model.id.toLowerCase() === normalizedValue ||
+				`${model.provider}/${model.id}`.toLowerCase() === normalizedValue),
+	);
+	return exactAliasMatch || exactReferenceMatch;
+}
+
 /** Resolve forwarded runtime options against the child session's model runtime. */
 export function resolveForwardedOptions(
 	parsed: Args,
@@ -246,6 +270,10 @@ export function resolveForwardedOptions(
 ): ForwardedOptions {
 	const forwarded: ForwardedOptions = {};
 	if (parsed.model) {
+		if (!isExactCatalogModelReference(modelRuntime.getModels(), parsed.model, parsed.provider)) {
+			const display = parsed.provider ? `${parsed.provider}/${parsed.model}` : parsed.model;
+			throw new Error(`Model "${display}" not found in the live model catalog.`);
+		}
 		const nameMatch = modelRuntime
 			.getModels()
 			.find((m) => m.name?.toLowerCase() === parsed.model!.toLowerCase());