@mrclrchtr/supi-debug 11.1.0 → 11.3.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [11.3.0]
+
+- Added package-specific release notes for SuPi Debug event capture and inspection.

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "11.1.0",
+  "version": "11.3.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-core/src/child-web-tools.ts

@@ -0,0 +1,110 @@
+// Session-provided Web tools for SuPi child sessions (Agent Runs and Reviewer Sessions).
+//
+// The loaded supi-web extension answers a synchronous request on the parent event bus.
+// Consumers never depend on supi-web; when it is absent or provides no tools, the
+// request returns undefined and the child simply lacks Web tools.
+
+import type { ExtensionAPI, ExtensionFactory } from "@earendil-works/pi-coding-agent";
+
+/** Web tools that child sessions may receive when the containing session provides them. */
+export const CHILD_WEB_TOOL_NAMES = [
+  "web_fetch_md",
+  "web_search",
+  "web_docs_search",
+  "web_docs_fetch",
+] as const;
+
+/** One session-provided Web tool name. */
+export type ChildWebToolName = (typeof CHILD_WEB_TOOL_NAMES)[number];
+
+/**
+ * Web tools currently callable in the containing session plus a child-only extension
+ * factory that registers them. The factory must not capture the parent session; it may
+ * capture plain data such as the containing session's configuration directory.
+ */
+export interface ChildWebToolProvision {
+  readonly toolNames: readonly ChildWebToolName[];
+  /** Register the requested subset of `toolNames` in a child session. */
+  readonly createFactory: (toolNames: readonly ChildWebToolName[]) => ExtensionFactory;
+}
+
+/** Plain containing-session data supplied with a child Web tool request. */
+export interface ChildWebToolsRequestContext {
+  /**
+   * Working directory whose SuPi configuration governs Web settings such as Firecrawl.
+   * Children with a different cwd (for example a frozen Review Workspace) keep this policy.
+   */
+  readonly configCwd: string;
+}
+
+type EventBusLike = Pick<ExtensionAPI["events"], "on" | "emit">;
+
+const REQUEST_CHANNEL = "supi:child-web-tools:request";
+const RESPONSE_CHANNEL = "supi:child-web-tools:response";
+
+interface ChildWebToolsRequest extends ChildWebToolsRequestContext {
+  readonly requestId: string;
+}
+
+interface ChildWebToolsResponse {
+  readonly requestId: string;
+  readonly provision: ChildWebToolProvision;
+}
+
+let nextRequestId = 0;
+
+/**
+ * Answer child Web tool requests on the parent event bus. The callback must be synchronous
+ * because Pi's event bus does not await listeners. Returns an unsubscribe function.
+ */
+export function provideChildWebTools(
+  events: EventBusLike,
+  resolve: (context: ChildWebToolsRequestContext) => ChildWebToolProvision | undefined,
+): () => void {
+  return events.on(REQUEST_CHANNEL, (data) => {
+    const request = data as Partial<ChildWebToolsRequest> | undefined;
+    if (typeof request?.requestId !== "string" || typeof request.configCwd !== "string") return;
+    const { requestId, configCwd } = request;
+    const provision = resolve({ configCwd });
+    if (!provision || provision.toolNames.length === 0) return;
+    events.emit(RESPONSE_CHANNEL, { requestId, provision } satisfies ChildWebToolsResponse);
+  });
+}
+
+/** Capture the Web tools the containing session currently provides, if any. */
+export function requestChildWebTools(
+  events: EventBusLike,
+  context: ChildWebToolsRequestContext,
+): ChildWebToolProvision | undefined {
+  const requestId = `child-web-${process.pid}-${++nextRequestId}`;
+  let provision: ChildWebToolProvision | undefined;
+  const unsubscribe = events.on(RESPONSE_CHANNEL, (data) => {
+    const response = data as Partial<ChildWebToolsResponse> | undefined;
+    if (response?.requestId === requestId && response.provision) provision = response.provision;
+  });
+  try {
+    events.emit(REQUEST_CHANNEL, { requestId, ...context } satisfies ChildWebToolsRequest);
+  } finally {
+    unsubscribe();
+  }
+  return provision;
+}
+
+/**
+ * Return the Web tools callable in a session under Pi's exposure rules: active `direct`
+ * tools, plus registered `codemode` and `deferred` tools. `model-only` and `hidden`
+ * tools are not callable.
+ */
+export function callableChildWebToolNames(
+  pi: Pick<ExtensionAPI, "getAllTools" | "getActiveTools">,
+): ChildWebToolName[] {
+  const active = new Set(pi.getActiveTools());
+  const exposures = new Map(
+    pi.getAllTools().map((tool) => [tool.name, tool.exposure ?? "direct"] as const),
+  );
+  return CHILD_WEB_TOOL_NAMES.filter((name) => {
+    const exposure = exposures.get(name);
+    if (exposure === "direct") return active.has(name);
+    return exposure === "codemode" || exposure === "deferred";
+  });
+}

package/node_modules/@mrclrchtr/supi-core/src/session.ts

@@ -1,5 +1,16 @@
 // supi-core session domain — session utilities and registries.
 
+export type {
+  ChildWebToolName,
+  ChildWebToolProvision,
+  ChildWebToolsRequestContext,
+} from "./child-web-tools.ts";
+export {
+  CHILD_WEB_TOOL_NAMES,
+  callableChildWebToolNames,
+  provideChildWebTools,
+  requestChildWebTools,
+} from "./child-web-tools.ts";
 export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
 export type {
   SessionCapabilitySkill,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-debug",
-  "version": "11.1.0",
+  "version": "11.3.0",
   "description": "Capture and inspect SuPi debug events",
   "license": "MIT",
   "repository": {
@@ -27,6 +27,7 @@
   ],
   "type": "module",
   "files": [
+    "CHANGELOG.md",
     "src/**/*.ts",
     "prompts",
     "skills/**/SKILL.md",
@@ -34,7 +35,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "11.1.0"
+    "@mrclrchtr/supi-core": "11.3.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/prompts/supi-tooling-retro.md

@@ -1,77 +1,58 @@
 ---
-description: Retrospect on SuPi tooling used during the completed task
+description: Find evidence-grounded tooling improvements from the preceding task
 ---
 
-Produce a compact, evidence-based retrospective of the task that just ended. Evaluate the SuPi surfaces that were available and relevant: tools, skills, prompts, extensions, injected context or guidance, documentation, settings, and human-only TUI commands. Do not evaluate the entire suite in the abstract. Do not evaluate pi-core behavior.
+Produce a compact retrospective of the task immediately preceding this prompt. Extract reusable improvements to relevant tools, skills, prompts, extensions, injected guidance, docs, settings, and human-only TUI commands. Assess what helped, what got in the way, and what could make the next similar task easier—even when no tool failed. Focus on tooling and workflow fit, not the project's code or a general grade of the agent's performance.
 
-## Evidence rules
+## Scope and evidence
 
-- Reconstruct the retrospective from this session only. Do not invent tool calls, outcomes, failures, token costs, or user impact.
-- You may query the `debug` tool to verify event-level claims. You may query `cache_forensics` when it is available to verify cache-related claims. Use such queries only for verification, and keep them few. Do not perform any other tool calls or follow-up investigation. Stop after you write the retrospective.
-- Tag every claim as `[observed]`, `[inferred]`, or `[unknown]`. An observed claim is supported by the transcript, a tool result, or an evidence query. An inferred claim is plausible but untested.
-- Rate the impact of each surfaced item as `high`, `medium`, or `low`. The impact is the degree to which the item changed the task outcome or its cost.
-- Use the exact surface name that appears in the session. Do not treat an available but unused tool as evidence of failure.
-- If no SuPi surface was used or relevant, say so explicitly. Do not build a wishlist. List only task-specific, plausible missed help.
+1. Identify the preceding task and its actual completion status from the visible session. If no task is identifiable, state that limit and stop. Keep unrelated tasks and this retrospective's own verification outside the assessment.
+2. Use the task transcript as the primary evidence. If verification would materially change a finding or recommendation, make at most two narrowly filtered `debug` calls against the live session, using sanitized data only. Use only events attributable to this task. A retained buffer can omit earlier events; empty or incomplete results do not establish that nothing failed. If verification is unavailable, disclose the limit and proceed.
+3. Make no other tool calls or follow-up investigation. Historical scans, delegation, file edits, issue creation, settings changes, and continuing the task are outside this retrospective. Stop after the report.
 
-## Evaluate
+For each finding, give a brief evidence anchor: the smallest distinguishing input and observed result (for example, query/scope and completeness reason), a retry, a user correction, or a specific instruction/context excerpt. Use exact surface names from the session. Treat tool-reported limits as observations; mark their underlying cause `[unknown]` where unresolved. Keep excerpts minimal and omit secrets or unnecessary identifying details.
 
-- SuPi surfaces that were actually used: what they enabled, where they fell short, and any failure or friction.
-- Failed or mis-parameterized tool calls: SuPi surface calls that failed or were rejected for wrong, missing, or invalid parameters, including calls corrected on retry. Name the cause: agent misuse, ambiguous tool description, missing guidance (promptSnippet or promptGuidelines), a schema gap, or a tool bug.
-- Recognized problems or bugs: concrete defects in SuPi surfaces, such as crashes, wrong output, failed calls for valid usage, regressions, inconsistent behavior, or guidance that led to a wrong action. Do not report defects in the project's own code.
-- Missed opportunities: a relevant unused tool (for example a supi-code-intelligence tool) or context source, and why it was missed. Name the cause: discoverability, guidance, timing, capability, or not applicable.
-- Missing pieces: a concrete utility, capability, documentation page, example, or output improvement that would have changed this task.
-- Noise: redundant instructions, repeated advice without added value, stale or irrelevant context, excessive output, unnecessary long paths, poor timing, or misleading guidance. Do not criticize necessary context without naming the avoidable cost.
-- Keep SuPi or tooling recommendations separate from general code or project recommendations.
+Use these evidence labels:
+- `[observed]`: directly supported by the visible transcript or verification result.
+- `[inferred]`: a plausible interpretation or missed benefit, not demonstrated.
+- `[unknown]`: an unresolved cause, ownership, or measurement; not a standalone finding.
 
-## Output rules
+Separate observed outcomes from suspected causes. Distinguish SuPi-owned surfaces, upstream Pi/provider behavior, project-local guidance, and agent behavior; mark unresolved ownership or cause `[unknown]`. Keep upstream behavior and project-code defects out of SuPi bug claims. Judge fault separately from improvement potential: agent error can still expose a useful interface or workflow change.
 
-- Keep the result under about 600 words and specific to this task.
-- Open with a one-line overall verdict on SuPi tooling for this task.
-- Give each item a confidence tag and an impact rating. `None identified` lines need neither.
-- Prefer concrete evidence and observed friction over generic praise or a feature wishlist.
-- If a section has no supported item, write `None identified` and briefly explain the evidence limit.
-- Include at most three recommendations. Each must name a changeable surface (tool, prompt, skill, docs, guidance, or feature), the proposed change, and the expected benefit. Recommended changes may target tool descriptions, parameter schemas, or guidance, especially when they address the Failed or mis-parameterized tool calls listed above. Do not recommend "use the tool more" unless discoverability is the identified cause.
-- Do not edit files, open issues, update OpenSpec artifacts, or take any other follow-up action.
+Rate each finding's impact on this task as `high`, `medium`, or `low`, based on the demonstrated effect or explicitly inferred benefit. Report time, token, cache, or cost figures only when measured in the task evidence; describe unmeasured costs qualitatively. Claims about recurring problems or suite-wide reliability require evidence beyond this retrospective's scope.
 
-## Required output
+## Assessment checklist
 
-## SuPi Tooling Retrospective
+Consider each category, but report each finding once:
+- **Help:** What a used surface enabled, including useful guidance or context—not just a list of calls.
+- **Failures, retries, and defects:** Include rejected or mis-parameterized calls even when corrected on retry. Name the parameter or error, task effect, and eventual outcome. Distinguish misuse, guidance/schema gaps, and suspected tool defects; keep uncertain causes explicit.
+- **Guidance and workflow fit:** Assess visible descriptions, parameter explanations, `promptSnippet`, `promptGuidelines`, result guidance, and skill instructions at the decision point. Look for ambiguity, poorly timed guidance, and workflow assumptions that did not fit this task. Distinguish missing or unhelpful guidance from clear guidance the agent did not follow.
+- **Missed opportunities and missing pieces:** Look for workarounds, repetitive manual steps, missing capabilities, and output improvements that could have helped. For an unused surface, establish its availability and relevance; non-use alone is not a gap. Ground ideas in a specific task moment, not a suite-wide wishlist.
+- **Context efficiency:** Identify oversized, redundant, stale, or poorly timed context. Distinguish recurring metadata/injections from results and on-demand reads; mark uncertain placement `[unknown]`. For deletion proposals, quote the overlap and name retained guidance that preserves tool selection, valid arguments, and safety. Account for mandatory reading: a required read is not agent waste, but its routing or packaging may be an improvement candidate.
+
+For consequential friction, consider a concrete tooling or guidance change as well as an agent lesson. A proposal needs an evidence anchor and a plausible mechanism; root-cause proof or demonstrated recurrence is not required to suggest an experiment. Repeating an existing instruction belongs under agent lessons; an interface, timing, or workflow change needs its own rationale.
 
-**Task completed**: <1–2 sentence summary>
+## Report
 
-**Verdict**: <one line: the overall state of SuPi tooling for this task and its biggest lever>
+Use the structure below, within 600 words; shorter when evidence is sparse. Prioritize consequential findings rather than filling categories or a recommendation quota. Use evidence labels to express uncertainty; add prose caveats only when they change the proposed action. Omit empty sections. If no SuPi surface was used or relevant, say so explicitly and omit unsupported findings and recommendations.
 
-### Tools used
-- `[observed · impact: high|medium|low]` **`<surface>`** — concrete help, friction, or failure.
-- If none: `None identified — no SuPi surface materially participated in this task.`
+## SuPi Tooling Retrospective
 
-### Failed or mis-parameterized tool calls
-- `[observed|inferred · impact: high|medium|low]` **`<surface>`** — the call, the invalid or missing parameter, the outcome, and the cause: agent misuse, ambiguous description, missing guidance, schema gap, or tool bug. Include near misses: a call rejected once and corrected on retry is stronger evidence than a clean pass.
-- If none: `None identified — every SuPi call used valid parameters.`
+**Task**: <one sentence, including actual completion status>
 
-### Recognized problems or bugs
-- `[observed|inferred · impact: high|medium|low]` **`<surface>`** — the concrete defect (crash, wrong behavior, regression, inconsistency) and how it affected the task. Do not repeat ordinary friction that belongs under Tools used, and do not repeat parameter-caused call failures that belong under Failed or mis-parameterized tool calls.
-- If none: `None identified — no defect surfaced in this task.`
+**Verdict**: <overall contribution and highest-leverage tooling opportunity, or no tooling change warranted>
 
-### Missed opportunities
-- `[inferred · impact: high|medium|low]` **`<surface>`** — task-specific help it might have provided. Name the cause: discoverability, guidance, timing, capability, or not applicable.
-- If none: `None identified — do not infer a gap from non-use alone.`
+### What helped
+- `[observed · impact: high|medium|low]` **`<surface>`** — <concrete contribution; evidence anchor>.
 
-### Missing pieces
-- `[observed|inferred · impact: high|medium|low]` **`<utility, feature, docs, example, or output change>`** — the concrete gap and how it affected this task.
-- If none: `None identified.`
+### Failures and friction
+- `[observed|inferred · impact: high|medium|low]` **`<surface>`** — <finding; evidence anchor; task effect>. <Cause or ownership, separately labeled if inferred or unknown. Include retry outcomes where visible.>
 
-### Unhelpful or noisy context
-- `[observed|inferred · impact: high|medium|low]` **`<instruction, context, or output>`** — what was unnecessary or costly, and how it could be reduced or better timed.
-- If none: `None identified.`
+### Tooling improvements
+Include at most three prioritized proposals tied to reported findings: **owner / named surface → specific change → expected benefit → validation**. Name the editable surface and changed behavior; use a file path only if known. Mark untested changes and benefits `[inferred]`. Choose one smallest next experiment per proposal, with an observable success criterion. Keep larger alternatives conditional on that result. When evidence is insufficient to choose a change, name the narrow verification that would decide it. Preserve selection, argument validity, and safety in context-reduction proposals. If none emerge, state `No tooling change warranted by the available evidence.`
 
-### Prioritized recommendations
-1. **`<named surface>`** — <specific change>; <expected benefit>; confidence: <high|medium|low>.
-2. **`<named surface>`** — <specific change>; <expected benefit>; confidence: <high|medium|low>.
-3. **`<named surface>`** — <specific change>; <expected benefit>; confidence: <high|medium|low>.
-- Include only supported recommendations. If none are supported, write `None identified`.
+### Agent lessons
+<At most two task-specific execution lessons, separate from tooling improvements. Omit when there are none.>
 
-### Confidence / evidence
-- Direct evidence: <what the session and any evidence queries demonstrate>
-- Inference: <what is plausible but untested>
-- Limits: <what the session cannot establish>
+### Evidence limits
+<State only limits that materially affect the findings or proposals; omit inventories of unassessed internals. Distinguish incomplete evidence from an uneventful observed task.>

package/src/tool/debug/input.ts

@@ -1,11 +1,10 @@
-import { StringEnum } from "@earendil-works/pi-ai";
 import type { DebugLevel } from "@mrclrchtr/supi-core/debug";
 import { Type } from "typebox";
 
 /** Shared Debug Operation ID constraint for filters and returned event identity. */
 export const debugOperationIdSchema = Type.String({ pattern: "^op-[A-Za-z0-9_-]{21}[AQgw]$" });
 
-/** Shared level vocabulary; StringEnum's string type is narrowed to the registry contract. */
+/** Shared level vocabulary, narrowed to the registry contract. */
 export const debugLevelSchema = Type.Unsafe<DebugLevel>(
-  StringEnum(["debug", "info", "warning", "error"]),
+  Type.Enum(["debug", "info", "warning", "error"], { type: "string" }),
 );

package/src/tool/debug/render.ts

@@ -1,6 +1,10 @@
 /** Transcript renderers for the debug tool. */
 
-import { keyHint, type Theme, type ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import type {
+  KeybindingHints,
+  Theme,
+  ToolRenderResultOptions,
+} from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { type DebugRenderDetails, readDebugRenderDetails } from "../../render-details.ts";
 import { renderExpandedReport } from "../../renderer.ts";
@@ -95,14 +99,12 @@ function renderProgress(details: unknown, expanded: boolean, theme: Theme): Text
   return new Text(theme.fg("warning", expanded ? line : "Reading persisted debug events…"), 0, 0);
 }
 
-/** Render the compact or expanded result for the `debug` tool. */
-
 /** Render the compact or expanded result for the `debug` tool. */
 export function renderDebugToolResult(
   result: DebugToolResult,
   options: ToolRenderResultOptions,
   theme: Theme,
-  context: { isError: boolean },
+  context: Pick<KeybindingHints, "keyText" | "keyHint"> & { isError: boolean },
 ): Text {
   if (options.isPartial) return renderProgress(result.details, options.expanded, theme);
   if (context.isError) return new Text(theme.fg("error", "debug failed"), 0, 0);
@@ -110,8 +112,8 @@ export function renderDebugToolResult(
   const details = readDebugRenderDetails(result.details);
   if (!options.expanded) {
     let summary = renderToolSummary(details, theme);
-    if (details.eventCount > 0)
-      summary += theme.fg("dim", ` ${keyHint("app.tools.expand", "to expand")}`);
+    if (details.eventCount > 0 && context.keyText("app.tools.expand"))
+      summary += theme.fg("dim", ` ${context.keyHint("app.tools.expand", "to expand")}`);
     return new Text(summary, 0, 0);
   }