@jameslovespancakes/pi-plus 1.0.11 → 1.0.12

package/src/domains/workflows/workflows/refactor-scout.ts

@@ -0,0 +1,143 @@
+import { challengeFindings, parseChallengeArgs } from "../runtime/advisory-challenge.ts";
+import { Type } from "typebox";
+import {
+  type AdvisoryVerified,
+  type AdvisoryLens,
+  synthesizeAdvisoryReport,
+  finishAdvisoryReport,
+  emptyAdvisoryReport,
+  formatEvidence,
+  formatLocation,
+  publishVerifiedKeptProgress,
+  runLensVerificationPipeline,
+  DEFAULT_ADVISORY_TOOL_HINTS,
+  DEFAULT_ADVISORY_TOOLS,
+} from "../runtime/workflow-advisory-utils.ts";
+import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../runtime/types.ts";
+
+export const meta: WorkflowMeta = {
+  name: "refactor-scout",
+  description: "Advisory-only refactor scout: scope → per-lens find → independent verify → synthesize safe refactor opportunities.",
+  phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Challenge" }, { title: "Synthesize" }],
+};
+
+const ScopeSchema = Type.Object({
+  target: Type.String({ description: "Verbatim target path, module, or focus area being scouted." }),
+  files: Type.Array(Type.String(), { description: "Repository-relative files in scope." }),
+  summary: Type.String({ description: "One-paragraph summary of the scoped code." }),
+  conventions: Type.Optional(Type.String({ description: "Relevant project conventions from AGENTS.md / docs." })),
+});
+
+const REFACTOR_LENSES: AdvisoryLens[] = [
+  { label: "duplication", category: "duplication", text: "Repeated logic, copy-pasted structures, or near-duplicate flows that could share one clearer implementation." },
+  { label: "complexity", category: "complexity", text: "Oversized functions, tangled control flow, or abstractions that make local reasoning harder than necessary." },
+  { label: "type-safety", category: "type-safety", text: "Weak typing, avoidable casts, unchecked shapes, or places stronger types would prevent mistakes." },
+  { label: "boundaries", category: "boundary", text: "Leaky module boundaries, misplaced responsibilities, or imports that couple unrelated layers." },
+  { label: "dead-code", category: "dead-code", text: "Unused, obsolete, or redundant code paths that can likely be removed safely." },
+  { label: "conventions", category: "conventions", text: "Departures from project conventions, naming, dependency rules, or local idioms." },
+];
+
+const PER_LENS = 5;
+
+export default async function run(api: WorkflowApi): Promise<unknown> {
+  const { agent, phase, log, progress, args } = api;
+  const challengeConfig = parseChallengeArgs(args);
+  const target = challengeConfig.args.trim() || ".";
+  let fileCount = 0;
+  let rawCandidateCount = 0;
+  let droppedCandidateCount = 0;
+  let refutedCandidateCount = 0;
+  const makeStats = (verified: number, kept: number): WorkflowRunStats => ({
+    files: fileCount,
+    candidates: rawCandidateCount,
+    verified,
+    kept,
+    dropped: droppedCandidateCount,
+    refuted: refutedCandidateCount,
+  });
+
+  phase("Scope");
+  const scope = await agent(
+    "Establish the scope for an advisory-only refactor scout. Do not edit files.\n" +
+      `Target / focus (verbatim): ${target}\n\n` +
+      "Inspect repository structure, the target path or module, and relevant AGENTS.md / project docs conventions. " +
+      "Return the concrete files that should be considered, a short summary, and any conventions that affect refactor advice. " +
+      `This workflow will fan out across ${REFACTOR_LENSES.length} lenses with up to ${PER_LENS} candidates per lens. Structured output only.`,
+    { phase: "Scope", label: "scope", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, profile: "medium", schema: ScopeSchema },
+  );
+
+  if (!scope || scope.files.length === 0) {
+    return finishAdvisoryReport(emptyAdvisoryReport(
+      "No files were identified for refactor scouting.",
+      ["Provide a target path, module, or subsystem to scout for refactor opportunities."],
+      makeStats(0, 0),
+    ), []);
+  }
+
+  fileCount = scope.files.length;
+  progress({ type: "counter", key: "files", label: "files", value: fileCount });
+  progress({ type: "summary", key: "files", value: scope.files.join(", ") });
+  log(`${scope.files.length} files scoped for refactor scouting`);
+
+  const scopeBlock =
+    `## Target\n${scope.target}\n\n## Files in scope\n${scope.files.map((file) => `- ${file}`).join("\n")}\n\n` +
+    `## Summary\n${scope.summary}\n\n## Conventions\n${scope.conventions ?? "(none noted)"}\n` +
+    (args.trim() ? `\n## User instructions (verbatim)\n${args.trim()}\n` : "");
+
+  const pipelineResult = await runLensVerificationPipeline({
+    api,
+    lenses: REFACTOR_LENSES,
+    perLens: PER_LENS,
+    finderPrompt: (lens) =>
+      `## Refactor-scout finder — ${lens.label}\n\n${scopeBlock}\n` +
+      "This workflow is advisory-only: do not edit files and do not propose broad rewrites.\n" +
+      `Scout through ONLY this lens:\n${lens.text}\n\n` +
+      `Surface up to ${PER_LENS} candidates. Use category exactly "${lens.category}". ` +
+      "Each candidate must include a one-line summary, locations, impact on maintainability or future correctness, and an optional safe first recommendation. " +
+      "Only include opportunities where a small, reviewable first step is plausible. Structured output only.",
+    verifierPrompt: (candidate) =>
+      `## Refactor-scout verifier\n\n${scopeBlock}\n## Candidate\n` +
+      `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
+      `Recommendation: ${candidate.recommendation ?? "(none supplied)"}\n\n` +
+      "Read the relevant files and return CONFIRMED, PLAUSIBLE, NOT_SUBSTANTIATED, or REFUTED. " +
+      "Default toward REFUTED if the opportunity is generic, too broad, not evidenced by code, or lacks a safe first step. " +
+      "Evidence must quote or cite code. Structured output only.",
+  });
+  rawCandidateCount += pipelineResult.rawCandidates;
+  droppedCandidateCount += pipelineResult.dropped;
+  refutedCandidateCount += pipelineResult.refuted;
+  const { coverage } = pipelineResult;
+  const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, coverage);
+  const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
+  const stats = makeStats(verified.length, surviving.length);
+  publishVerifiedKeptProgress({ progress, log }, verified.length, surviving.length);
+
+  if (surviving.length === 0) {
+    return finishAdvisoryReport(emptyAdvisoryReport("No refactor opportunities survived verification.", ["Leave the scoped code unchanged unless a human reviewer has additional context."], stats), coverage, verified);
+  }
+
+  const ranked = [...surviving].sort((a, b) => rank(a) - rank(b));
+  const block = ranked
+    .map(
+      (finding, index) =>
+        `### [${index}] IDs: ${finding.sourceCandidateIds.join(", ")} ${formatLocation(finding)} (${finding.verdict}, ${finding.category})\n` +
+        `${finding.summary}\nImpact: ${finding.impact}\nEvidence: ${formatEvidence(finding.evidence)}\nSafe first step: ${finding.recommendation ?? "(none supplied)"}`,
+    )
+    .join("\n\n");
+
+  const resolved = await synthesizeAdvisoryReport(api,
+    `## Synthesis: final refactor-scout report\n\n${ranked.length} opportunities survived independent verification.\n\n${block}\n\n` +
+      "Merge findings with the same root cause and rank highest leverage / lowest risk first. " +
+      "Select findings by ID. " +
+      "Severity is maintenance or future-correctness impact. " +
+      "Recommendations must be safe first refactor steps, not rewrites. Include concrete nextSteps for the host developer. Structured output only.",
+    ranked, coverage,
+  );
+  return finishAdvisoryReport({ ...resolved, stats: { ...stats, kept: resolved.findings.length } }, coverage, verified);
+}
+
+function rank(finding: AdvisoryVerified): number {
+  const verdictRank = finding.verdict === "CONFIRMED" ? 0 : 1;
+  const categoryRank = finding.category === "dead-code" || finding.category === "conventions" ? 2 : 0;
+  return verdictRank + categoryRank;
+}

package/src/domains/workflows/workflows/research.ts

@@ -0,0 +1,169 @@
+import { compactResults } from "../runtime/concurrency.ts";
+import {
+  MAX_RESEARCH_LANES,
+  ResearchLaneResultSchema,
+  ResearchPlanSchema,
+  ResearchReportSchema,
+  ResearchVerificationSchema,
+  type ResearchClaimCandidate,
+  type ResearchReport,
+} from "../runtime/research-contract.ts";
+import {
+  buildClaimCandidates,
+  fallbackResearchReport,
+  normalizeResearchLanes,
+  sanitizeLaneResults,
+  sanitizeResearchReport,
+  sanitizeVerification,
+  unavailableResearchReport,
+  unavailableVerification,
+} from "../runtime/research-evidence.ts";
+import { WorkflowToolHintUnavailableError } from "../runtime/tool-capabilities.ts";
+import type { WorkflowApi, WorkflowMeta } from "../runtime/types.ts";
+
+export const meta: WorkflowMeta = {
+  name: "research",
+  description: "Source-grounded external research: decompose → gather direct-page evidence → independently verify claims → cited synthesis.",
+  phases: [{ title: "Plan" }, { title: "Gather" }, { title: "Verify" }, { title: "Synthesize" }],
+};
+
+const EXTERNAL_TOOLS: string[] = [];
+const EXTERNAL_TOOL_HINTS = ["external-search"] as const;
+
+export default async function run(api: WorkflowApi): Promise<ResearchReport> {
+  const { agent, parallel, phase, log, progress, args } = api;
+  const question = args.trim();
+  if (!question) return unavailableResearchReport("empty-question");
+
+  phase("Plan");
+  let plan;
+  try {
+    plan = await agent(
+      `Plan bounded, source-grounded research for the user's question and any scope constraints embedded in it.\n\n` +
+        `Question and constraints (verbatim):\n${question}\n\n` +
+        `Create at most ${MAX_RESEARCH_LANES} non-overlapping lanes. Each lane needs a stable short id, title, objective, and 1-4 concrete search queries. ` +
+        "Separate primary-source discovery, current status, counterevidence, or jurisdiction/timeframe only when relevant. " +
+        "Do not claim exhaustive coverage. Structured output only.",
+      {
+        phase: "Plan",
+        label: "plan",
+        tools: EXTERNAL_TOOLS,
+        toolHints: EXTERNAL_TOOL_HINTS,
+        requireToolHints: true,
+        profile: "medium",
+        resume: "off",
+        schema: ResearchPlanSchema,
+      },
+    );
+  } catch (error) {
+    if (error instanceof WorkflowToolHintUnavailableError) return unavailableResearchReport("missing-capability");
+    throw error;
+  }
+
+  if (!plan) return unavailableResearchReport("no-evidence");
+  const lanes = normalizeResearchLanes(plan);
+  if (lanes.length === 0) return unavailableResearchReport("no-evidence");
+  progress({ type: "counter", key: "research.lanes", label: "research lanes", value: lanes.length });
+  progress({ type: "summary", key: "research.question", value: question });
+
+  phase("Gather");
+  const gathered = compactResults(
+    await parallel(
+      lanes.map((lane) => async () => {
+        const result = await agent(
+          `Research one bounded lane using only installed external web-search, browsing, or URL-extraction tools.\n\n` +
+            `Question: ${question}\n` +
+            `Scope constraints: ${plan.scopeConstraints.join("; ") || "(none)"}\n` +
+            `Lane id: ${lane.id}\nLane: ${lane.title}\nObjective: ${lane.objective}\n` +
+            `Queries:\n${lane.queries.map((query) => `- ${query}`).join("\n")}\n\n` +
+            "Open the supporting pages instead of citing a search-results page. Prefer primary and authoritative sources; use independent sources when useful. " +
+            "Return concrete claims with importance, whether each page supports or conflicts with the claim, a short passage or precise paraphrase, and the exact page title and URL. " +
+            "State evidence gaps. Never invent a URL or claim that the opened page does not support. Structured output only.",
+          {
+            phase: "Gather",
+            label: `gather:${lane.id}`,
+            tools: EXTERNAL_TOOLS,
+            toolHints: EXTERNAL_TOOL_HINTS,
+            requireToolHints: true,
+            profile: "small",
+            resume: "off",
+            schema: ResearchLaneResultSchema,
+          },
+        );
+        if (!result) return null;
+        progress({ type: "counter_delta", key: "research.evidence", label: "evidence items", delta: result.evidence.length });
+        progress({
+          type: "lane_item",
+          lane: "Research lanes",
+          title: lane.title,
+          subtitle: `${result.evidence.length} evidence item(s)`,
+          status: result.evidence.length > 0 ? "success" : "warning",
+          details: result.gaps.join("; ") || lane.objective,
+        });
+        return result;
+      }),
+    ),
+  );
+
+  const laneResults = sanitizeLaneResults(gathered);
+  const candidates = buildClaimCandidates(laneResults);
+  if (candidates.length === 0) return unavailableResearchReport("no-evidence");
+  progress({ type: "counter", key: "research.claims", label: "claims to verify", value: candidates.length });
+  log(`${candidates.length} bounded claim(s) selected for independent verification`);
+
+  phase("Verify");
+  const verificationResults = await parallel(
+    candidates.map((candidate, index) => async () => {
+      const result = await agent(verificationPrompt(question, candidate), {
+        phase: "Verify",
+        label: `verify:${index + 1}`,
+        tools: EXTERNAL_TOOLS,
+        toolHints: EXTERNAL_TOOL_HINTS,
+        requireToolHints: true,
+        profile: "medium",
+        resume: "off",
+        schema: ResearchVerificationSchema,
+      });
+      return result ? sanitizeVerification(result, candidate) : null;
+    }),
+  );
+  const verifications = verificationResults.map((result, index) => result ?? unavailableVerification(candidates[index]!));
+  for (const verification of verifications) {
+    progress({ type: "counter_delta", key: `research.${verification.verdict.toLowerCase()}`, label: verification.verdict.toLowerCase(), delta: 1 });
+  }
+  const synthesisInputs = verifications.filter((verification) => verification.verdict !== "REJECTED");
+
+  phase("Synthesize");
+  const synthesis = await agent(
+    `Answer the research question using only the independently verified handoff below.\n\n` +
+      `Question: ${question}\nScope constraints: ${plan.scopeConstraints.join("; ") || "(none)"}\n\n` +
+      `Verified claims JSON:\n${JSON.stringify(synthesisInputs)}\n\n` +
+      "Keep SUPPORTED claims, CONFLICTED evidence, UNCERTAIN claims, and model INFERENCE in their separate fields. Exclude REJECTED claims. " +
+      "Copy each verified claim string exactly so its citations remain bound to that claim during validation. " +
+      "Every supported or conflicting claim must cite exact title/URL objects from its verification; do not add URLs, cite search-results pages, or turn inference into fact. " +
+      "Answer concisely, disclose limited coverage, and provide useful next steps. Structured output only.",
+    {
+      phase: "Synthesize",
+      label: "synthesize",
+      tools: [],
+      profile: "medium",
+      resume: "off",
+      schema: ResearchReportSchema,
+    },
+  );
+
+  return sanitizeResearchReport(
+    synthesis ?? fallbackResearchReport(synthesisInputs, "The model did not return a structured synthesis."),
+    synthesisInputs,
+  );
+}
+
+function verificationPrompt(question: string, candidate: ResearchClaimCandidate): string {
+  return `Independently verify one important research claim using installed external web-search, browsing, or URL-extraction tools.\n\n` +
+    `Question: ${question}\nClaim: ${candidate.claim}\nImportance: ${candidate.importance}\n\n` +
+    `Gather-stage evidence (context only; do not treat it as verified):\n${JSON.stringify(candidate.evidence)}\n\n` +
+    "Search independently and open direct supporting pages. Prefer primary/authoritative sources and actively look for credible counterevidence. " +
+    "Return SUPPORTED only when direct pages substantiate the claim, CONFLICTED when credible sources disagree, UNCERTAIN when evidence is insufficient, " +
+    "INFERENCE when the conclusion is reasoned rather than directly stated, or REJECTED when evidence refutes it. " +
+    "Include exact page titles and direct HTTP(S) URLs, never search-results URLs. Structured output only.";
+}

package/src/services/usage-service.ts

@@ -2,15 +2,7 @@ import { agentPath, readJson, writeJson } from "../core/store.ts";
 import { isClaudeAccount, type UsageRow } from "../core/quota/pool.ts";
 import { fetchAll } from "../core/quota/usage-source.ts";
 
-/**
- * The single owner of subscription usage state.
- *
- * Previously the only poller lived inside the footer extension and was gated on
- * `ctx.hasUI`, so `list_models` silently read empty rows whenever the footer was
- * hidden or the session was headless (including every workflow subagent).
- * Consumers now call `ensureFresh()` for on-demand data and `subscribe()` for
- * push updates; only one poll is ever in flight regardless of consumer count.
- */
+/** Shared subscription-usage cache and poller. */
 
 export const REFRESH_MS = 5 * 60 * 1000;
 const MIN_INTERVAL_MS = 90_000;
@@ -24,11 +16,7 @@ export interface UsageState {
   loading: boolean;
   accounts: number;
   codexPlan?: string;
-  /**
-   * Last time each account group's quota was observed to drop. This is the only
-   * available proxy for "recently used": providers expose remaining quota but
-   * never report which account served a request.
-   */
+  /** Last observed quota drop for each account group. */
   lastUsedAt?: Record<string, number>;
 }
 
@@ -77,10 +65,7 @@ function emit(): void {
   }
 }
 
-/**
- * Stamps an account as recently used when its headline window falls. A rise
- * (quota reset) or an unchanged figure is not a usage signal.
- */
+/** Records use when an account's headline quota falls. */
 function recordUsageDrops(fresh: UsageRow[]): void {
   const previous = new Map(
     state.rows.filter((row) => row.label === "5h").map((row) => [row.group, row.remaining]),
@@ -98,10 +83,7 @@ export function usageState(): UsageState {
   return state;
 }
 
-/**
- * Account groups ordered by most recent observed use, capped at `limit`.
- * Accounts never seen in use fall back to alphabetical, so the list is stable.
- */
+/** Returns recently used account groups with stable fallback ordering. */
 export function recentAccounts(limit: number): string[] {
   const stamps = state.lastUsedAt ?? {};
   const groups = [...new Set(state.rows.filter(isClaudeAccount).map((row) => row.group))];
@@ -116,10 +98,7 @@ export function subscribe(listener: () => void): () => void {
   return () => listeners.delete(listener);
 }
 
-/**
- * The endpoints are rate limited, so results are cached and refreshes are
- * throttled. Failures keep the previous figures on screen.
- */
+/** Refreshes cached usage without overlapping requests. */
 export async function refreshUsage(ctx: any, force = false): Promise<void> {
   if (inFlight) return inFlight;
   const now = Date.now();
@@ -160,10 +139,7 @@ export async function refreshUsage(ctx: any, force = false): Promise<void> {
   return inFlight;
 }
 
-/**
- * Guarantees usable data for a caller that does not own the poll loop.
- * This is what makes `list_models` correct in headless sessions.
- */
+/** Refreshes stale data for UI and headless callers. */
 export async function ensureFresh(ctx: any): Promise<UsageState> {
   const stale = !state.updatedAt || Date.now() - state.updatedAt > REFRESH_MS;
   if (stale) await refreshUsage(ctx);