@mrclrchtr/supi-debug 11.2.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.2.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.2.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.2.0"
+    "@mrclrchtr/supi-core": "11.3.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/prompts/supi-tooling-retro.md

@@ -1,8 +1,8 @@
 ---
-description: Assess SuPi tooling for the preceding task with evidence-linked improvements
+description: Find evidence-grounded tooling improvements from the preceding task
 ---
 
-Produce a compact retrospective of the task immediately preceding this prompt. Assess SuPi tooling, not the project's code or general development practices. Cover relevant tools, skills, prompts, extensions, injected guidance, docs, settings, and human-only TUI commands—not the suite in the abstract. Assess context efficiency where the task provides concrete evidence, preserving correct tool selection and use.
+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.
 
 ## Scope and evidence
 
@@ -10,14 +10,14 @@ Produce a compact retrospective of the task immediately preceding this prompt. A
 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.
 
-For each finding, give a brief evidence anchor: a tool result or error, a retry, a user correction, or a specific instruction/context excerpt. Use exact surface names from the session. Keep excerpts minimal and omit secrets or unnecessary identifying details.
+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.
 
 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.
 
-Separate the observed outcome from its explanation. An observed failure does not make its suspected cause observed. Distinguish SuPi-owned surfaces, upstream Pi/provider behavior, project-local guidance, and agent behavior. Attribute ownership and cause only when supported; otherwise mark them `[unknown]`. Keep upstream behavior and project-code defects out of SuPi bug claims.
+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.
 
 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.
 
@@ -25,31 +25,34 @@ Rate each finding's impact on this task as `high`, `medium`, or `low`, based on
 
 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.
-- **Tool guidance quality:** Assess visible tool descriptions, parameter explanations, `promptSnippet`, `promptGuidelines`, and result guidance for clarity, correctness, and sufficiency at the decision point. Rate relevant guidance as `effective`, `needs improvement`, or `not assessable`, citing evidence. Distinguish unclear guidance from the agent failing to follow clear guidance.
-- **Context efficiency:** Where concrete task evidence supports a finding, distinguish recurring tool metadata and injected guidance from result text and on-demand content. For deletion proposals, quote the exact overlapping excerpt and identify retained guidance that preserves pre-call selection, argument validity, and safety. Visible overlap is a candidate for reduction, not proof of redundancy; non-use alone does not justify removal. Mark uncertain request placement `[unknown]`; quantify savings only from task evidence.
-- **Failures and retries:** Rejected, failed, or mis-parameterized SuPi calls, including ones corrected on retry. Name the relevant parameter or error and eventual outcome. Distinguish agent misuse, ambiguous descriptions, missing guidance, schema gaps, and tool bugs; leave the cause unknown when the evidence cannot decide.
-- **Defects:** Wrong output, crashes, regressions, or inconsistent behavior under valid usage. Label suspected defects as inferred and state what remains unverified.
-- **Missed or missing help:** A specific unused surface or absent capability that plausibly would have changed this task. For unused surfaces, establish that they were available and relevant at the decision point; non-use alone is not a gap. Infer a reason such as discoverability, guidance, or timing only when supported.
-- **Noise:** Identify redundant, stale, misleading, oversized, or poorly timed results/on-demand context and their avoidable cost. Account for visible mandatory-reading requirements before calling a read unnecessary. Explain what could be reduced or deferred while preserving necessary guidance.
+- **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.
 
 ## Report
 
-Use the structure below, within 600 words; shorter when evidence is sparse. Prioritize consequential findings rather than filling categories. If a findings section is empty, write `None observed in the available task context.` If no SuPi surface was used or relevant, say so explicitly and omit unsupported findings and recommendations.
+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.
 
 ## SuPi Tooling Retrospective
 
 **Task**: <one sentence, including actual completion status>
 
-**Verdict**: <overall contribution and biggest supported improvement, or no change warranted>
+**Verdict**: <overall contribution and highest-leverage tooling opportunity, or no tooling change warranted>
 
 ### What helped
 - `[observed · impact: high|medium|low]` **`<surface>`** — <concrete contribution; evidence anchor>.
 
-### Friction and gaps
-- `[observed|inferred · impact: high|medium|low]` **`<surface>`** — <category and finding; evidence anchor; task effect>. <Cause or ownership, separately labeled if inferred or unknown. For failed calls, include the retry outcome if visible.>
+### 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.>
+
+### 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 changes
-Include at most three recommendations, each tied to a reported finding: **owner / named surface → specific change → expected benefit**. Rank by supported task benefit or context reduction; mark benefits as untested. Keep agent-behavior lessons distinct from persistent tooling or guidance changes. Prefer the smallest intervention: persistent changes require a concrete editable target and evidence that changing the surface, rather than following existing guidance, addresses the finding. When ownership or necessity is unresolved, recommend narrow verification rather than deletion. Recommend increased tool use only when a supported discoverability or guidance gap explains the miss. If no change is supported, write `None warranted by the available evidence.`
+### Agent lessons
+<At most two task-specific execution lessons, separate from tooling improvements. Omit when there are none.>
 
 ### Evidence limits
-<Briefly state material limits: missing or compacted task context, unavailable verification, uncertain attribution, or unmeasured costs. Distinguish an uneventful observed task from incomplete evidence.>
+<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);
   }