pi-ui-extend 0.1.50 → 0.1.53

package/external/pi-tools-suite/src/tool-descriptions.ts

@@ -29,9 +29,8 @@ export const COMPRESS_TOOL_DESCRIPTION: ToolDescription = {
 	description: COMPRESS_RANGE_DESCRIPTION,
 	promptSnippet: "Use compress for context-pressure housekeeping: summarize closed, high-yield stale slices when context is meaningfully high or a DCP reminder gives concrete candidates; do not compress just because low-context work produced a small closed slice.",
 	promptGuidelines: [
-		"Treat completed implementation, verification, config/doc edits, answered exploration, dead ends, and log inspection as compression candidates when they are large, stale, or context pressure is meaningful.",
-		"Do not carry large stale shell/read/repo/web outputs, diffs, or passing logs across task boundaries when their exact text is no longer useful; summarize their actionable result instead.",
-		"Keep active, still-needed context raw; compress only closed ranges whose exact content is unlikely to be needed next.",
+		"Compression candidates: completed implementation, verification, config/doc edits, answered exploration, dead ends, and log inspection when large/stale or context pressure is meaningful; Low context usage by itself does not require compression.",
+		"Summarize large stale shell/read/repo/web outputs, diffs, and passing logs once exact text is no longer useful; keep active or still-needed context raw.",
 	],
 };
 
@@ -43,10 +42,8 @@ export function astGrepToolDescriptions(maxLines: number, maxBytesLabel: string)
 			description: `Read-only AST structural search/scan. Use for language-aware patterns, sgconfig/rule scans, JSON matches, and rewrite previews. Use text search for plain strings and ast_apply for mutations. Output truncates at ${maxLines} lines or ${maxBytesLabel} with full output saved to a temp file.`,
 			promptSnippet: "Use ast_grep for AST/structural code search, not plain text search. It previews rewrites only; use ast_apply to mutate files.",
 			promptGuidelines: [
-				"Use ast_grep when syntax/AST structure matters; use Grep/text search for exact strings or regex.",
-				"Keep searches narrow with paths/globs and set lang explicitly for ambiguous snippets.",
-				"ast_grep is read-only: use rewrite to preview replacements, never to apply them.",
-				"Use ast_apply for intended ast-grep rewrites or scan fixes; use command=scan with rule, inlineRules, or config for rule-based scans.",
+				"Use ast_grep when syntax/AST structure matters; use text search for exact strings/regex. Keep paths/globs narrow and set lang for ambiguous snippets.",
+				"ast_grep is read-only: use rewrite to preview only; use ast_apply for mutations or command=scan fixes.",
 			],
 		},
 		astApply: {
@@ -55,9 +52,8 @@ export function astGrepToolDescriptions(maxLines: number, maxBytesLabel: string)
 			description: `Mutating AST rewrite/fix tool powered by ast-grep. Use for structural replacements or scan fixes after you know the pattern/rule is correct. Reports changedFiles for post-edit diagnostics and truncates output at ${maxLines} lines or ${maxBytesLabel}.`,
 			promptSnippet: "Use ast_apply only when you intend to mutate files with ast-grep structural rewrites or scan fixes.",
 			promptGuidelines: [
-				"Use ast_apply for AST-aware bulk edits, not simple one-off text replacements.",
-				"For pattern rewrites, use command=run with pattern, rewrite, and lang when ambiguous; for rule fixes, use command=scan with rule, inlineRules, or config.",
-				"Run ast_grep first when the match set is uncertain; use ast_apply directly only for obvious, scoped rewrites.",
+				"Use ast_apply for AST-aware bulk edits, not simple one-off text replacements; preview with ast_grep when matches are uncertain.",
+				"Pattern rewrites: command=run with pattern/rewrite/lang; rule fixes: command=scan with rule, inlineRules, or config.",
 			],
 		},
 	} satisfies Record<string, ToolDescription>;
@@ -87,24 +83,18 @@ export function asyncSubagentToolDescriptions(options: ToolDescriptionSetOptions
 					? "For one semantic code-discovery question, use repo_search; for independent tracks/hypotheses/review axes, delegate even when repo_* tools exist. Read result only after completion when findings are needed."
 					: "For one focused code-discovery question, use direct read/grep. Without repo_* tools, spawn several focused scan/quick agents first for broad multi-track discovery, incident triage, release readiness, risk strategy, or parallel reviews. Read result only after completion when findings are needed."),
 			promptGuidelines: [
-				"Use action='spawn' only for LARGE or PARALLEL tasks: independent investigations, repo-wide sweeps, deep debugging, or code review/audit that would bloat the parent context.",
-				"Treat explicit requests to delegate, use sub-agents, run parallel agents, split into independent tracks, investigate hypotheses, or run separate review axes as spawn triggers; spawn first unless the request is trivial or clearly single-file.",
+				"Use action='spawn' only for LARGE/PARALLEL work: independent investigations, repo-wide sweeps, deep debugging, code review/audit, or explicit delegate/parallelize/split requests; these are spawn triggers unless trivial/single-file.",
 				repoDiscovery
-					? "For one discovery question, use repo_search; spawn only for several independent tracks/hypotheses/review axes, and do not let repo_* availability suppress delegation."
-					: "For one discovery question, use direct read/grep; without repo_* tools, spawn a small focused swarm before parent-context search when the task spans several files/modules/hypotheses/tracks.",
+					? "For one discovery question, use repo_search; spawn for independent tracks/hypotheses/review axes, and do not let repo_* availability suppress delegation."
+					: "For one discovery question, use direct read/grep; when repo_* tools are unavailable, spawn several focused scan/quick agents first for broad multi-file/module/hypothesis work.",
 				repoDiscovery
-					? "For incident triage, release readiness, or risk/test strategy with separate hypotheses or review tracks, prefer focused review agents over serial parent-context work."
-					: "For incident triage, release readiness, or risk/test strategy with separate hypotheses or review tracks and no repo_* tools, call action='spawn' as the first discovery step; direct read/grep can follow.",
+					? "For incident triage, release readiness, or risk/test strategy with separate hypotheses/review tracks, prefer focused agents over serial parent-context work."
+					: "For incident triage, release readiness, or risk/test strategy with separate hypotheses/review tracks and no repo_* tools, call action='spawn' as the first discovery step; direct read/grep can follow.",
 				"Do not use subagents for exact-string lookups, known-file edits, typo/text replacements, obvious one-file changes, or interactive user input; use the cheapest direct path.",
-				"Spawn multiple focused agents in one action='spawn' call for independent questions; for synthetic tests or bounded probes, pass timeoutSeconds slightly above expected runtime.",
-				"For spawn, leave subagentType unset so the router chooses from configured roles. Set it only for user-named roles, deterministic tests, or another concrete override.",
-				"Use subagentType='oracle' sparingly for cross-provider second opinions on high-stakes uncertainty or final plan/risk checks.",
+				"Spawn multiple focused agents in one action='spawn' call for independent questions; for bounded probes set timeoutSeconds; omit subagentType unless user-named/deterministic, and use oracle sparingly for high-stakes uncertainty/final checks.",
 				"For screenshot/image inspection by blind models, use lookup; subagents only receive imagePaths when a broader delegated track genuinely needs them.",
-				"If the user asks to start, run, launch, or test parallel sub-agents, call action='spawn' and then stop; completion/failure notifications will wake the parent so do not immediately call action='status' or action='wait' just to see whether agents finished.",
-				"Use status for non-blocking progress/recovery, wait only when requested or needed, and result only after completion; registry mappings can recover latest runDir/agentId after reload.",
-				"Result output is compact with artifact links; inspect raw artifacts only when full details are necessary.",
-				"Use action='stop' when the user asks to stop, cancel, or kill running sub-agents.",
-				"Use action='cleanup' with delete=true after collecting all results to free disk space.",
+				"If asked to start/run/launch/test parallel sub-agents, spawn and stop; do not status/wait just for progress. Use status for recovery, wait only when needed/requested, result only after completion; compact results include artifact links.",
+				"Use action='stop' for stop/cancel/kill requests and action='cleanup' with delete=true only after collecting results.",
 			],
 		},
 		spawnAction: {
@@ -158,9 +148,8 @@ export const REPO_DISCOVERY_TOOLS: RepoDiscoveryToolDescription[] = [
 		description: "Indexed repo architecture map: entrypoints, module boundaries, cycles, and unresolved dependency classes. Use before broad reads in unfamiliar codebases; skip for exact-string lookups, known-file edits, or other trivial changes.",
 		promptSnippet: "Use repo_architecture for a compact indexed architecture overview before broad multi-file reads, not for simple literal searches or small known-scope edits.",
 		promptGuidelines: [
-			"For exact strings, filenames, known symbols, typo/text replacements, or obvious one-file edits, skip repo_architecture and use the cheapest direct path: text search/read, then edit.",
-			"For broad exploration in an unfamiliar codebase, make one narrow architecture call first; add --path-prefix in args when a subsystem is known.",
-			"Use repo_structure for file/symbol listings and repo_search for behavior questions after this overview.",
+			"Exact strings, filenames, known symbols, typo/text replacements, or obvious one-file edits: skip repo_architecture and use direct text search/read/edit.",
+			"Broad unfamiliar codebase: make one narrow repo_architecture call first, add --path-prefix when a subsystem is known, then use repo_structure for files/symbols and repo_search for behavior.",
 		],
 	},
 	{
@@ -170,8 +159,7 @@ export const REPO_DISCOVERY_TOOLS: RepoDiscoveryToolDescription[] = [
 		description: "Indexed file tree and exported-symbol view for a directory/module. Use to choose files/ranges without dumping source.",
 		promptSnippet: "Use repo_structure for file trees, module contents, and exported symbols; narrow with idx flags.",
 		promptGuidelines: [
-			"Pass --path-prefix, --kind, --max-files, or --max-depth in args whenever possible.",
-			"Use repo_ast for one large file's syntax map and repo_search for semantic behavior discovery.",
+			"Pass --path-prefix, --kind, --max-files, or --max-depth when useful; use repo_ast for one large file's syntax map and repo_search for semantic behavior discovery.",
 		],
 	},
 	{
@@ -181,8 +169,7 @@ export const REPO_DISCOVERY_TOOLS: RepoDiscoveryToolDescription[] = [
 		description: "Indexed AST map for one file. Use before repeated reads of a large file or when parent syntax structure matters.",
 		promptSnippet: "Use repo_ast with target=<file> to map one large file before choosing exact ranges to read.",
 		promptGuidelines: [
-			"Use this for one known file, not repo-wide search.",
-			"Pass --max-depth or --max-nodes in args to keep the AST map compact.",
+			"Use for one known file, not repo-wide search; pass --max-depth or --max-nodes to keep output compact.",
 		],
 		targetDescription: "File path to map, e.g. src/api/client.ts.",
 	},
@@ -193,11 +180,9 @@ export const REPO_DISCOVERY_TOOLS: RepoDiscoveryToolDescription[] = [
 		description: "Indexed hybrid/semantic repository search for behavior questions when exact identifiers or files are unknown. Use natural-language behavior queries, not synonym dumps. Defaults to hybrid ranking; read returned ranges next.",
 		promptSnippet: "Use repo_search for conceptual codebase questions; query for behavior, not a bag of synonyms. Leave default hybrid ranking for first-pass searches and use Grep/read when exact names or positions are known.",
 		promptGuidelines: [
-			"Phrase target as the behavior to locate, not a whitespace-separated pile of near-synonyms; keep exact identifiers only as useful anchors.",
-			"For initial unknown-file behavior searches, prefer the default hybrid ranking; pass --mode semantic only when lexical/symbol terms are misleading or the query is purely conceptual.",
-			"Make one targeted search, read the best returned ranges (prefer read over --include-content for full evidence), then refine only for a named gap; do not launch duplicate broad searches.",
-			"Use a specific conceptual target and narrow with --path-prefix, --max-files, --dedupe-file, or --exclude-tests when useful.",
-			"For bug/cause questions, stop when a read range shows the causal assignment/write/branch/call; continue only for a named gap such as callers, persistence, tests, or requested impact, and narrow follow-ups.",
+			"Phrase target as behavior, not synonym dumps; keep exact identifiers only as anchors. Prefer default hybrid first, using --mode semantic only when lexical/symbol terms mislead.",
+			"Make one targeted search, narrow with --path-prefix/--max-files/--dedupe-file/--exclude-tests when useful, read best ranges, then refine only for a named gap; avoid duplicate broad searches.",
+			"For bug/cause questions, stop when a read range shows the causal assignment/write/branch/call; continue only for named gaps such as callers, persistence, tests, or requested impact.",
 		],
 		targetDescription: "Natural-language behavior query, e.g. auth session token validation.",
 	},
@@ -208,8 +193,7 @@ export const REPO_DISCOVERY_TOOLS: RepoDiscoveryToolDescription[] = [
 		description: "Indexed explanation for a known symbol. Prefer file::symbol when the name may be ambiguous.",
 		promptSnippet: "Use repo_explain for a known symbol after you already know its name or file scope.",
 		promptGuidelines: [
-			"Prefer target=file::symbol for ambiguous names.",
-			"Use repo_search instead when you do not yet know the relevant symbol.",
+			"Prefer target=file::symbol for ambiguous names; use repo_search instead when the relevant symbol is still unknown.",
 		],
 		targetDescription: "Symbol or file-scoped symbol, e.g. createClient or src/api/client.ts::createClient.",
 	},
@@ -220,8 +204,7 @@ export const REPO_DISCOVERY_TOOLS: RepoDiscoveryToolDescription[] = [
 		description: "Indexed dependency/caller tracing for a known path or symbol. Use for import impact and first-hop call/dependency analysis.",
 		promptSnippet: "Use repo_deps with target=<path|path::symbol> to trace imports, imported-by, callers, or callees.",
 		promptGuidelines: [
-			"Start with --depth 1 in args; add --direction callers|callees|both, --mode calls, or --show-edges only when needed.",
-			"Use repo_search first when you do not yet know the target path or symbol.",
+			"Use repo_search first when path/symbol is unknown. Otherwise start --depth 1; add --direction, --mode calls, or --show-edges only when needed.",
 		],
 		targetDescription: "Path or file-scoped symbol, e.g. src/api/client.ts or src/api/client.ts::createClient.",
 	},
@@ -237,18 +220,13 @@ export const TODO_TOOL_DESCRIPTION: ToolDescription = {
 	promptGuidelines: [
 		"Use `todo` for complex work with 3+ steps, explicit user task lists, or new non-trivial requirements. Skip single trivial tasks and purely conversational requests.",
 		"For multi-step implementation/debugging plans, include a final user-facing report todo in the initial plan with acceptance criteria for changed files/behavior, verification results, and remaining manual actions; close it immediately before the final response, never via compression.",
-		"Resync before continuing when the user or new findings change scope, requirements, safety, feasibility, approach, dependencies, or order; update relevant tasks, add required tasks/blockers, and defer obsolete work.",
-		"Update todos when you start, finish, block, split, abandon, or materially change a step; do not leave todo maintenance for end-of-task cleanup.",
-		"Before non-trivial planned work, mark exactly one task in_progress with activeForm. Complete it only after required verification, never in batches.",
-		"If implementation is partial, tests fail, or a blocker remains, keep the task in_progress and add/update a blocker task instead of completing it.",
-		"Never use `clear`, `delete`, or batch deletion to hide unfinished, stale, or forgotten todos. Defer obsolete items or update them with the reason; only delete when the user explicitly asks or the item was created by mistake.",
-		"Before giving a final response for work that used todos, ensure every visible todo is completed, deferred, or intentionally still in_progress with a blocker/explanation. Do not leave any just-finished todo item in_progress after you stop.",
-		"Keep subjects short and imperative; put details in description only when needed. Use parentId for large plans; use blockedBy on create and addBlockedBy/removeBlockedBy on update for dependencies.",
-		"Use batch_create/batch_update for large explicit plans, but still keep exactly one visible task in_progress unless the user asks otherwise.",
-		"When starting a new plan that supersedes existing unfinished todos, use batch_create with replace:true instead of appending; only omit replace when intentionally extending the current plan.",
-		"list hides deleted tombstones unless includeDeleted:true; use status/blockedOnly filters only when needed. Use export/import for handoff or migration; import with replace:true only when explicitly overwriting todo state.",
-		"When every visible todo is completed, todo state clears automatically; do not call clear afterward just to remove completed tasks.",
-		"Persistence uses `/todos persist on|off|status` or `/todos-persist on|off|status`; when resuming, ask which ids are in scope and run `/todos scope <id...>` or `/todos-scope <id...>` so out-of-scope active tasks are deferred.",
+		"Resync before continuing when user/new findings change scope, requirements, safety, feasibility, approach, dependencies, or order; update tasks/blockers and defer obsolete work.",
+		"Update todos when starting, finishing, blocking, splitting, abandoning, or materially changing a step; before planned work mark exactly one in_progress with activeForm and complete it only after verification.",
+		"If partial, tests fail, or blocked, keep the task in_progress and add/update a blocker. Never use `clear`, `delete`, or batch deletion to hide unfinished/stale/forgotten todos; delete only on explicit request or creation mistake.",
+		"Before a final response after using todos, ensure each visible todo is completed, deferred, or intentionally still in_progress with explanation; do not leave a just-finished item in_progress.",
+		"Keep subjects short; use parentId/blockers for hierarchy/dependencies. For large explicit plans use batch_create/batch_update but keep exactly one visible in_progress unless asked otherwise; use batch_create replace:true only for superseding plans.",
+		"list hides tombstones unless includeDeleted:true; use status/blockedOnly only when needed; export/import for handoff, import replace:true only when explicitly overwriting; when all visible todos complete, state clears automatically.",
+		"Persistence: `/todos persist on|off|status` or `/todos-persist on|off|status`; on resume, ask in-scope ids and run `/todos scope <id...>` or `/todos-scope <id...>` so out-of-scope active tasks are deferred.",
 	],
 };
 
@@ -258,8 +236,7 @@ export const SESSION_NAME_TOOL_DESCRIPTION: ToolDescription = {
 	description: "Show or set the current session name so the agent can retitle the active session without relying on slash-command parsing.",
 	promptSnippet: "Use session_name to rename the current session directly when the task calls for updating the session title.",
 	promptGuidelines: [
-		"Pass a short, user-meaningful name when renaming the current session.",
-		"Call without a name only when you need to read the current session name.",
+		"Pass a short, user-meaningful name to rename; call without a name only to read the current session name.",
 	],
 };
 
@@ -271,10 +248,8 @@ export const WEB_SEARCH_TOOL_DESCRIPTIONS = {
 			"Search the web for real-time information using your local Ollama instance's web_search API. Requires Ollama running locally with web search enabled; supports per-call timeout_ms and PI_WEB_SEARCH_TIMEOUT_MS.",
 		promptSnippet: "Search the web for current or real-time information through the local Ollama web_search API.",
 		promptGuidelines: [
-			"Use web_search when the user needs current public web information that may not be in the model's training data.",
-			"Keep web_search queries focused; use max_results only when a different result count is useful.",
-			"Do not include secrets, tokens, or private repository data in web_search queries.",
-			"Do not use web_search for repository-local code discovery; use repo_* or file/search tools instead.",
+			"Use web_search only for current public web information; keep queries focused and set max_results only when useful.",
+			"Never include secrets, tokens, or private repository data; do not use web_search for repo-local discovery—use repo_* or file/search tools.",
 		],
 	},
 	webFetch: {
@@ -284,9 +259,7 @@ export const WEB_SEARCH_TOOL_DESCRIPTIONS = {
 			"Fetch and extract text content from a web page URL using your local Ollama instance's web_fetch API. Requires Ollama running locally with web fetch enabled; supports per-call timeout_ms and PI_WEB_SEARCH_TIMEOUT_MS.",
 		promptSnippet: "Fetch and extract text from a specific URL through the local Ollama web_fetch API.",
 		promptGuidelines: [
-			"Use web_fetch when the user provides a URL or after web_search returns a specific page that needs deeper reading.",
-			"Do not pass URLs containing secrets or private credentials to web_fetch.",
-			"Do not use web_fetch as a generic repository file reader; use read for local files.",
+			"Use web_fetch for user-provided URLs or web_search results needing deeper reading; never pass secret/private-credential URLs, and use read for local files.",
 		],
 	},
 } satisfies Record<string, ToolDescription>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ui-extend",
-  "version": "0.1.50",
+  "version": "0.1.53",
   "private": false,
   "type": "module",
   "bin": {
@@ -64,9 +64,9 @@
     "prepublishOnly": "npm run check && npm run build:pix && npm run generate-schemas"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": "0.79.10",
-    "@earendil-works/pi-coding-agent": "0.79.10",
-    "@earendil-works/pi-tui": "0.79.10",
+    "@earendil-works/pi-ai": "0.80.2",
+    "@earendil-works/pi-coding-agent": "0.80.2",
+    "@earendil-works/pi-tui": "0.80.2",
     "@mariozechner/clipboard": "^0.3.9",
     "jsonc-parser": "3.3.1",
     "typebox": "1.1.38",