pi-workflow-engine 0.11.0 → 0.12.0

package/.pi/extensions/pi-workflow-engine/src/progress.ts

@@ -1,55 +1,20 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { TUI } from "@earendil-works/pi-tui";
-import type { WorkflowLaneItemStatus, WorkflowProgressEvent } from "./types.ts";
+import type { WorkflowProgressEvent } from "./types.ts";
+import type { AgentRowStatus, WorkflowLaneItemStatus, WorkflowProgressSnapshot } from "./progress-types.ts";
+import { formatWorkflowUsageLine, type WorkflowUsageSnapshot } from "./usage.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 import { statusTextFromCounts, type WorkflowStatusCounts } from "./ui/workflow-format.ts";
-import { createWorkflowWidget, type WorkflowWidget } from "./ui/workflow-widget.ts";
-
-export type AgentRowStatus = "queued" | "running" | "done" | "failed";
-
-export interface AgentRowSnapshot {
-  readonly id: number;
-  readonly label: string;
-  readonly status: AgentRowStatus;
-  readonly startedAt?: number;
-  readonly doneAt?: number;
-  readonly toolUses: number;
-  readonly lastTool?: string;
-  readonly error?: string;
-}
-
-export interface PhaseSnapshot {
-  readonly title: string;
-  readonly agents: readonly AgentRowSnapshot[];
-}
-
-export interface WorkflowCounterSnapshot {
-  readonly key: string;
-  readonly label: string;
-  readonly value: number;
-}
-
-export interface WorkflowLaneItemSnapshot {
-  readonly lane: string;
-  readonly title: string;
-  readonly subtitle?: string;
-  readonly status: WorkflowLaneItemStatus;
-  readonly details?: string;
-  readonly createdAt: number;
-}
-
-export interface WorkflowProgressSnapshot {
-  readonly title: string;
-  readonly startedAt: number;
-  readonly doneAt?: number;
-  readonly currentPhase: string;
-  readonly phases: readonly PhaseSnapshot[];
-  readonly counters: readonly WorkflowCounterSnapshot[];
-  readonly summary: readonly [string, string | number][];
-  readonly lanes: readonly [string, readonly WorkflowLaneItemSnapshot[]][];
-  readonly laneOverflow: readonly [string, number][];
-  readonly logs: readonly string[];
-}
+import { renderWorkflowWidgetLines } from "./ui/workflow-widget.ts";
+
+export type {
+  AgentRowSnapshot,
+  AgentRowStatus,
+  PhaseSnapshot,
+  WorkflowCounterSnapshot,
+  WorkflowLaneItemSnapshot,
+  WorkflowLaneItemStatus,
+  WorkflowProgressSnapshot,
+} from "./progress-types.ts";
 
 interface AgentRow {
   id: number;
@@ -83,6 +48,7 @@ interface WorkflowLaneItem {
 }
 
 const LOG_LIMIT = 24;
+const WIDGET_REFRESH_INTERVAL_MS = 1_000;
 export const DEFAULT_LANE_ITEM_LIMIT = 200;
 
 /**
@@ -103,17 +69,18 @@ export class ProgressTracker {
   private doneAt: number | undefined;
   private currentPhase = "Workflow";
   private nextAgentId = 1;
-  private widget: WorkflowWidget | undefined;
-  private widgetRegistered = false;
-  private tui: Pick<TUI, "requestRender"> | undefined;
-  private widgetInterval: ReturnType<typeof setInterval> | undefined;
   private lastStatusText: string | undefined;
-  private renderQueued = false;
+  private usageSnapshot: WorkflowUsageSnapshot | undefined;
+  private widgetRefreshInterval: ReturnType<typeof setInterval> | undefined;
+  private readonly surfaceKey: string;
 
   constructor(
     private readonly ctx: ExtensionContext,
     private readonly title: string,
+    private readonly runId: string,
+    private readonly onSnapshot?: (snapshot: WorkflowProgressSnapshot) => void,
   ) {
+    this.surfaceKey = `workflow:${runId}`;
     this.ensurePhase(this.currentPhase);
   }
 
@@ -130,14 +97,14 @@ export class ProgressTracker {
     this.currentPhase = title;
     this.ensurePhase(title);
     if (!this.ctx.hasUI) process.stderr.write(`[${this.title}] ${title}\n`);
-    this.render();
+    this.publish();
   }
 
   log(message: string): void {
     this.logs.push(message);
     while (this.logs.length > LOG_LIMIT) this.logs.shift();
     if (!this.ctx.hasUI) process.stderr.write(`[${this.title}] ${message}\n`);
-    this.render();
+    this.publish();
   }
 
   event(event: WorkflowProgressEvent): void {
@@ -172,7 +139,7 @@ export class ProgressTracker {
         this.summary.set(event.key, event.value);
         break;
     }
-    this.render();
+    this.publish();
   }
 
   agentQueued(phase: string | undefined, label: string): number {
@@ -181,7 +148,7 @@ export class ProgressTracker {
     this.ensurePhase(phase ?? this.currentPhase).agents.push(row);
     this.rowsById.set(id, row);
     this.agentCounts.queued++;
-    this.render();
+    this.publish();
     return id;
   }
 
@@ -203,7 +170,7 @@ export class ProgressTracker {
       this.rowsById.set(nextRow.id, nextRow);
       this.agentCounts.running++;
     }
-    this.render();
+    this.publish();
   }
 
   agentTool(label: string, tool: string, id?: number): void {
@@ -212,7 +179,7 @@ export class ProgressTracker {
       row.lastTool = tool;
       row.toolUses += 1;
     }
-    this.render();
+    this.publish();
   }
 
   agentDone(label: string, id?: number): void {
@@ -221,7 +188,7 @@ export class ProgressTracker {
       this.transitionAgentStatus(row, "done");
       row.doneAt = Date.now();
     }
-    this.render();
+    this.publish();
   }
 
   agentFailed(label: string, error: unknown, id?: number): void {
@@ -231,11 +198,17 @@ export class ProgressTracker {
       row.doneAt = Date.now();
       row.error = unknownErrorMessage(error);
     }
-    this.render();
+    this.publish();
+  }
+
+  updateUsage(snapshot: WorkflowUsageSnapshot): void {
+    this.usageSnapshot = snapshot;
+    this.publish();
   }
 
   snapshot(): WorkflowProgressSnapshot {
     return {
+      runId: this.runId,
       title: this.title,
       startedAt: this.startedAt,
       doneAt: this.doneAt,
@@ -249,6 +222,7 @@ export class ProgressTracker {
       lanes: [...this.lanes.entries()].map(([lane, items]) => [lane, items.map((item) => ({ ...item }))]),
       laneOverflow: [...this.laneOverflow.entries()],
       logs: [...this.logs],
+      usage: this.usageSnapshot,
     };
   }
 
@@ -300,25 +274,35 @@ export class ProgressTracker {
     return this.rowsById.get(id);
   }
 
-  private render(): void {
+  private publish(): void {
+    this.publishSnapshot();
     if (!this.ctx.hasUI) return;
-    this.ensureWidget();
-    this.widget?.invalidate();
-    this.requestRenderSoon();
+    this.publishWidget();
+    this.startWidgetRefresh();
     this.publishStatus();
   }
 
-  private requestRenderSoon(): void {
-    if (this.renderQueued) return;
-    this.renderQueued = true;
-    queueMicrotask(() => {
-      this.renderQueued = false;
-      this.tui?.requestRender();
-    });
+  private publishWidget(): void {
+    this.ctx.ui.setWidget(
+      this.surfaceKey,
+      renderWorkflowWidgetLines(this.snapshot(), this.ctx.ui.theme),
+      { placement: "aboveEditor" },
+    );
+  }
+
+  private startWidgetRefresh(): void {
+    if (this.widgetRefreshInterval !== undefined) return;
+    this.widgetRefreshInterval = setInterval(() => this.publishWidget(), WIDGET_REFRESH_INTERVAL_MS);
+  }
+
+  private stopWidgetRefresh(): void {
+    if (this.widgetRefreshInterval === undefined) return;
+    clearInterval(this.widgetRefreshInterval);
+    this.widgetRefreshInterval = undefined;
   }
 
   private publishStatus(): void {
-    const next = statusTextFromCounts(
+    const status = statusTextFromCounts(
       {
         title: this.title,
         doneAt: this.doneAt,
@@ -328,55 +312,26 @@ export class ProgressTracker {
       this.statusCountsSnapshot(),
       this.ctx.ui.theme,
     );
+    const usage = formatWorkflowUsageLine(this.usageSnapshot);
+    const next = usage ? `${status} · ${usage}` : status;
     if (next === this.lastStatusText) return;
-    this.ctx.ui.setStatus("workflow", next);
+    this.ctx.ui.setStatus(this.surfaceKey, next);
     this.lastStatusText = next;
   }
 
-  private ensureWidget(): void {
-    if (this.widgetRegistered) return;
-    this.widget = createWorkflowWidget(() => this.snapshot());
-    this.ctx.ui.setWidget(
-      "workflow",
-      (tui, theme) => {
-        this.tui = tui;
-        return {
-          render: (width?: number) => this.widget?.render(width ?? tui.terminal.columns, theme) ?? [],
-          invalidate: () => this.widget?.invalidate(),
-        };
-      },
-      { placement: "aboveEditor" },
-    );
-    this.widgetRegistered = true;
-    this.startWidgetTimer();
-  }
-
-  private startWidgetTimer(): void {
-    if (this.widgetInterval !== undefined) return;
-    this.widgetInterval = setInterval(() => {
-      this.widget?.nextFrame();
-      this.tui?.requestRender();
-    }, 100);
-  }
-
-  private stopWidgetTimer(): void {
-    if (this.widgetInterval === undefined) return;
-    clearInterval(this.widgetInterval);
-    this.widgetInterval = undefined;
-  }
-
-  /** Clear live workflow surfaces; optionally leave a one-line final status. */
-  done(status?: string): void {
+  /** Clear this run's live workflow surfaces. Final feedback is delivered by the result surface. */
+  done(): void {
     this.doneAt = Date.now();
-    this.stopWidgetTimer();
+    this.stopWidgetRefresh();
+    this.publishSnapshot();
     if (!this.ctx.hasUI) return;
-    this.ctx.ui.setWidget("workflow", undefined);
-    this.ctx.ui.setStatus("workflow", status);
-    this.lastStatusText = status;
-    this.renderQueued = false;
-    this.widgetRegistered = false;
-    this.widget = undefined;
-    this.tui = undefined;
+    this.ctx.ui.setWidget(this.surfaceKey, undefined);
+    this.ctx.ui.setStatus(this.surfaceKey, undefined);
+    this.lastStatusText = undefined;
+  }
+
+  private publishSnapshot(): void {
+    this.onSnapshot?.(this.snapshot());
   }
 }
 

package/.pi/extensions/pi-workflow-engine/src/provider-usage-limit.ts

@@ -0,0 +1,189 @@
+import { WorkflowPauseError } from "./cancellation.ts";
+import {
+  WORKFLOW_USAGE_LIMIT_DELAY_MIN_MS,
+  type ResolvedWorkflowRunOptions,
+} from "./options.ts";
+import type { WorkflowProviderUsageLimitPause } from "./workflow-run-record.ts";
+
+export const WORKFLOW_PROVIDER_USAGE_LIMIT_CODE = "WORKFLOW_PROVIDER_USAGE_LIMIT";
+export const WORKFLOW_USAGE_LIMIT_FALLBACK_DELAY_MS = 60_000;
+const MAX_RESET_HINT_LENGTH = 512;
+
+export interface ProviderUsageLimitDetails {
+  readonly stopReason: "error";
+  readonly providerMessage: string;
+  readonly provider?: string;
+  readonly model?: string;
+  readonly api?: string;
+  readonly resetHint?: string;
+  readonly resetAt?: number;
+}
+
+export interface ProviderUsageLimitPauseRecord {
+  readonly message: string;
+  readonly pause: WorkflowProviderUsageLimitPause;
+}
+
+/** Fatal-to-the-current-run provider limit that remains resumable from its journal boundary. */
+export class WorkflowProviderUsageLimitError extends WorkflowPauseError {
+  override readonly name = "WorkflowProviderUsageLimitError";
+  readonly code = WORKFLOW_PROVIDER_USAGE_LIMIT_CODE;
+
+  constructor(readonly details: ProviderUsageLimitDetails) {
+    super(details.providerMessage);
+  }
+
+  toJSON(): {
+    readonly name: string;
+    readonly message: string;
+    readonly code: string;
+    readonly details: ProviderUsageLimitDetails;
+  } {
+    return { name: this.name, message: this.message, code: this.code, details: this.details };
+  }
+}
+
+export function providerUsageLimitFromMessages(
+  messages: readonly unknown[],
+  now = Date.now(),
+): WorkflowProviderUsageLimitError | undefined {
+  const message = messages.findLast(isAssistantMessage);
+  if (!message || message.stopReason !== "error") return undefined;
+  const providerMessage = typeof message.errorMessage === "string" ? message.errorMessage.trim() : "";
+  if (!providerMessage || !isUsageLimitMessage(providerMessage)) return undefined;
+  const reset = parseProviderResetHint(providerMessage, now);
+  const provider = stringDetail(message.provider);
+  const model = stringDetail(message.model);
+  const api = stringDetail(message.api);
+  return new WorkflowProviderUsageLimitError({
+    stopReason: "error",
+    providerMessage,
+    ...(provider ? { provider } : {}),
+    ...(model ? { model } : {}),
+    ...(api ? { api } : {}),
+    ...reset,
+  });
+}
+
+export function createProviderUsageLimitPauseRecord(
+  error: WorkflowProviderUsageLimitError,
+  options: ResolvedWorkflowRunOptions,
+  replayableInvocation: boolean,
+  now = Date.now(),
+): ProviderUsageLimitPauseRecord {
+  const attempt = options.usageLimitAttempt + 1;
+  const hintedDelay = error.details.resetAt === undefined
+    ? WORKFLOW_USAGE_LIMIT_FALLBACK_DELAY_MS
+    : error.details.resetAt - now;
+  const delayMs = Math.min(
+    options.usageLimitMaxDelayMs,
+    Math.max(
+      WORKFLOW_USAGE_LIMIT_DELAY_MIN_MS,
+      hintedDelay > 0 ? hintedDelay : WORKFLOW_USAGE_LIMIT_FALLBACK_DELAY_MS,
+    ),
+  );
+  const autoResume = options.autoResumeOnUsageLimit
+    && attempt < options.usageLimitMaxAttempts
+    && replayableInvocation;
+  return {
+    message: autoResume
+      ? `Provider usage limit paused this run; automatic attempt ${attempt + 1}/${options.usageLimitMaxAttempts} is scheduled.`
+      : `Provider usage limit paused this run at attempt ${attempt}/${options.usageLimitMaxAttempts}.`,
+    pause: {
+      kind: "provider_usage_limit",
+      reason: "provider_usage_limit",
+      providerMessage: error.details.providerMessage,
+      provider: error.details.provider,
+      model: error.details.model,
+      api: error.details.api,
+      resetHint: error.details.resetHint,
+      attempt,
+      nextEligibleAt: now + delayMs,
+      autoResume,
+      maxAttempts: options.usageLimitMaxAttempts,
+    },
+  };
+}
+
+export function parseProviderResetHint(
+  message: string,
+  now = Date.now(),
+): { readonly resetHint?: string; readonly resetAt?: number } {
+  const iso = message.match(
+    /(?:[a-z-]*reset[a-z-]*|resets?\s+at|available\s+again\s+at)\s*[:=]?\s*(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2}))/i,
+  )?.[1];
+  if (iso) {
+    const parsed = Date.parse(iso);
+    return Number.isFinite(parsed) && parsed > now
+      ? { resetHint: boundedHint(iso), resetAt: parsed }
+      : { resetHint: boundedHint(iso) };
+  }
+
+  const labelled = message.match(
+    /(?:retry[- ]after|try again in|resets? in|available again in|x-ratelimit-reset(?:-[a-z-]+)?)\s*[:=]?\s*((?:\d+(?:\.\d+)?\s*(?:milliseconds?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d)\s*)+)/i,
+  );
+  if (labelled?.[1]) {
+    const delayMs = parseDurationMs(labelled[1]);
+    return delayMs === undefined
+      ? { resetHint: boundedHint(labelled[0]) }
+      : { resetHint: boundedHint(labelled[0]), resetAt: now + delayMs };
+  }
+
+  const retryAfter = message.match(/retry[- ]after\s*[:=]\s*([^\s,;]+)/i);
+  if (retryAfter?.[1]) {
+    const seconds = Number(retryAfter[1]);
+    return Number.isFinite(seconds) && seconds >= 0
+      ? { resetHint: boundedHint(retryAfter[0]), resetAt: now + seconds * 1_000 }
+      : { resetHint: boundedHint(retryAfter[0]) };
+  }
+  return {};
+}
+
+function isUsageLimitMessage(message: string): boolean {
+  return /(?:GoUsageLimitError|FreeUsageLimitError|insufficient_quota|rate_limit_error|ResourceExhausted)/i.test(message)
+    || /\btoo many requests\b/i.test(message)
+    || /\b(?:http|status(?: code)?|error)\s*[:=]?\s*429\b/i.test(message)
+    || /\b429\b[^\n]*(?:rate|requests?|quota|limit)/i.test(message)
+    || /\b(?:usage|quota|monthly|weekly|daily)\s+(?:window\s+)?limit\b/i.test(message)
+    || /\bquota\s+(?:has\s+been\s+)?exceeded\b/i.test(message)
+    || /\bexceeded\b[^\n]*\bquota\b/i.test(message)
+    || /\b(?:usage|rate)\s+limit\s+(?:(?:has\s+been|was)\s+)?(?:reached|exceeded)\b/i.test(message);
+}
+
+function parseDurationMs(value: string): number | undefined {
+  const unitPattern = /(\d+(?:\.\d+)?)\s*(milliseconds?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d)/gi;
+  let total = 0;
+  let matched = "";
+  for (const part of value.matchAll(unitPattern)) {
+    const amount = Number(part[1]);
+    const unit = part[2]?.toLowerCase();
+    if (!Number.isFinite(amount) || !unit) return undefined;
+    matched += part[0];
+    if (unit === "ms" || unit.startsWith("millisecond")) total += amount;
+    else if (unit === "s" || unit.startsWith("sec")) total += amount * 1_000;
+    else if (unit === "m" || unit.startsWith("min")) total += amount * 60_000;
+    else if (unit === "h" || unit.startsWith("hr") || unit.startsWith("hour")) total += amount * 3_600_000;
+    else total += amount * 86_400_000;
+  }
+  if (!matched || value.replace(/\s+/g, "") !== matched.replace(/\s+/g, "")) return undefined;
+  return Number.isFinite(total) && total >= 0 ? total : undefined;
+}
+
+function boundedHint(value: string): string {
+  return value.length <= MAX_RESET_HINT_LENGTH ? value : `${value.slice(0, MAX_RESET_HINT_LENGTH - 1)}…`;
+}
+
+function isAssistantMessage(value: unknown): value is {
+  readonly role: "assistant";
+  readonly stopReason?: unknown;
+  readonly errorMessage?: unknown;
+  readonly provider?: unknown;
+  readonly model?: unknown;
+  readonly api?: unknown;
+} {
+  return typeof value === "object" && value !== null && "role" in value && value.role === "assistant";
+}
+
+function stringDetail(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/.pi/extensions/pi-workflow-engine/src/research-contract.ts

@@ -0,0 +1,89 @@
+import { Type, type Static } from "typebox";
+
+export const MAX_RESEARCH_LANES = 4;
+export const MAX_LANE_EVIDENCE = 6;
+export const MAX_VERIFICATION_CLAIMS = 12;
+
+export const ResearchSourceSchema = Type.Object({
+  title: Type.String({ minLength: 1, description: "Human-readable title of the supporting page." }),
+  url: Type.String({ minLength: 1, description: "Direct HTTP(S) URL of the supporting page, never a search-results URL." }),
+  publishedAt: Type.Optional(Type.String({ description: "Publication or update date when the page states one." })),
+});
+
+export type ResearchSource = Static<typeof ResearchSourceSchema>;
+
+export const ResearchPlanSchema = Type.Object({
+  scopeConstraints: Type.Array(Type.String()),
+  lanes: Type.Array(
+    Type.Object({
+      id: Type.String({ minLength: 1 }),
+      title: Type.String({ minLength: 1 }),
+      objective: Type.String({ minLength: 1 }),
+      queries: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, maxItems: 4 }),
+    }),
+    { minItems: 1, maxItems: MAX_RESEARCH_LANES },
+  ),
+});
+
+export type ResearchPlan = Static<typeof ResearchPlanSchema>;
+export type ResearchLane = ResearchPlan["lanes"][number];
+
+export const ResearchEvidenceSchema = Type.Object({
+  claim: Type.String({ minLength: 1 }),
+  importance: Type.Union([Type.Literal("high"), Type.Literal("medium"), Type.Literal("low")]),
+  stance: Type.Union([Type.Literal("supports"), Type.Literal("conflicts")]),
+  evidence: Type.String({ minLength: 1, description: "A short supporting passage or precise paraphrase from the page." }),
+  source: ResearchSourceSchema,
+});
+
+export type ResearchEvidence = Static<typeof ResearchEvidenceSchema>;
+
+export const ResearchLaneResultSchema = Type.Object({
+  laneId: Type.String({ minLength: 1 }),
+  evidence: Type.Array(ResearchEvidenceSchema, { maxItems: MAX_LANE_EVIDENCE }),
+  gaps: Type.Array(Type.String()),
+});
+
+export type ResearchLaneResult = Static<typeof ResearchLaneResultSchema>;
+
+export interface ResearchClaimCandidate {
+  readonly claim: string;
+  readonly importance: ResearchEvidence["importance"];
+  readonly evidence: readonly ResearchEvidence[];
+}
+
+export const ResearchVerificationSchema = Type.Object({
+  claim: Type.String({ minLength: 1 }),
+  verdict: Type.Union([
+    Type.Literal("SUPPORTED"),
+    Type.Literal("CONFLICTED"),
+    Type.Literal("UNCERTAIN"),
+    Type.Literal("INFERENCE"),
+    Type.Literal("REJECTED"),
+  ]),
+  explanation: Type.String({ minLength: 1 }),
+  sources: Type.Array(ResearchSourceSchema, { maxItems: 8 }),
+});
+
+export type ResearchVerification = Static<typeof ResearchVerificationSchema>;
+
+export const ResearchReportEntrySchema = Type.Object({
+  claim: Type.String({ minLength: 1 }),
+  explanation: Type.String({ minLength: 1 }),
+  citations: Type.Array(ResearchSourceSchema, { maxItems: 8 }),
+});
+
+export type ResearchReportEntry = Static<typeof ResearchReportEntrySchema>;
+
+export const ResearchReportSchema = Type.Object({
+  answer: Type.String(),
+  supportedClaims: Type.Array(ResearchReportEntrySchema),
+  conflictingEvidence: Type.Array(ResearchReportEntrySchema),
+  uncertainties: Type.Array(ResearchReportEntrySchema),
+  inferences: Type.Array(ResearchReportEntrySchema),
+  sources: Type.Array(ResearchSourceSchema),
+  limitations: Type.Array(Type.String()),
+  nextSteps: Type.Array(Type.String()),
+});
+
+export type ResearchReport = Static<typeof ResearchReportSchema>;