@piagent/platform 1.6.0 → 1.6.1

package/packages/piagent-core/runtime/inspection/bounded-emission-guard.ts

@@ -0,0 +1,286 @@
+import { createHash } from "node:crypto";
+
+export type EmissionSuppressionReason =
+  | "empty"
+  | "filler"
+  | "duplicate-exact"
+  | "duplicate-normalized"
+  | "update-budget";
+
+export type BoundedEmissionCandidate = {
+  channel: string;
+  identityKey: string;
+  updateKey: string;
+  text: string;
+  actionable: boolean;
+  reference: string;
+};
+
+export type EmissionDecision = {
+  accepted: boolean;
+  reason: EmissionSuppressionReason | null;
+  priorReference: string | null;
+};
+
+export type BoundedEmissionTelemetry = {
+  schemaVersion: 1;
+  capacity: number;
+  retained: number;
+  primed: number;
+  accepted: number;
+  suppressed: number;
+  suppressedByReason: Record<EmissionSuppressionReason, number>;
+};
+
+type RetainedEmission = {
+  exactKey: string;
+  normalizedKey: string;
+  updateKey: string | null;
+  reference: string;
+};
+
+const ANSI = /\u001b(?:\[[0-?]*[ -/]*[@-~]|[@-_])/g;
+const DEFAULT_CAPACITY = 512;
+const MIN_CAPACITY = 1;
+const MAX_CAPACITY = 16_384;
+
+const FILLER = new Set([
+  "abort", "all good", "carry on", "complete", "continue", "done", "finished", "halt", "lgtm",
+  "looks good", "no action", "no action needed", "no concern", "no concerns", "no further advice",
+  "no further advice needed", "no further input", "no further input needed", "no issue", "no issues",
+  "no issue continue", "no notes", "nothing to add", "nothing to flag", "nothing to report", "ok", "okay",
+  "stop", "stop here", "stop now", "task complete", "task done",
+  "da xong", "đã xong", "khong can lam gi", "không cần làm gì", "khong co gi de bao cao", "không có gì để báo cáo",
+  "khong co loi", "không có lỗi", "khong co van de", "không có vấn đề", "on", "ổn", "tiep tuc", "tiếp tục", "xong"
+]);
+
+function digest(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function exactEmissionText(value: string): string {
+  return String(value ?? "")
+    .replace(ANSI, "")
+    .normalize("NFKC")
+    .replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Stable comparison form for reviewer notes and compact runtime event summaries. */
+export function normalizeEmissionText(value: string): string {
+  return exactEmissionText(value)
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim();
+}
+
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (!value || typeof value !== "object") return value;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return String(value);
+  const record = value as Record<string, unknown>;
+  return Object.fromEntries(Object.keys(record).sort().map((key) => [key, canonical(record[key])]));
+}
+
+function canonicalText(value: unknown): string {
+  return JSON.stringify(canonical(value));
+}
+
+function textField(payload: Record<string, unknown>): string | null {
+  for (const field of ["note", "advice", "finding", "message", "summary"]) {
+    if (typeof payload[field] === "string" && payload[field].trim()) return payload[field];
+  }
+  return null;
+}
+
+function reviewerRole(payload: Record<string, unknown>): string | null {
+  for (const field of ["role", "agentRole", "actorRole", "sourceRole"]) {
+    const value = String(payload[field] ?? "").toLowerCase();
+    if (value === "reviewer" || value === "piagent-reviewer") return value;
+  }
+  const emissionType = String(payload.emissionType ?? "").toLowerCase();
+  return emissionType === "reviewer-note" || emissionType === "review-note" ? "reviewer" : null;
+}
+
+type RuntimeEmissionLike = {
+  kind: string;
+  sessionRef: string;
+  taskRunId: string | null;
+  agentOperationId: string | null;
+  turnIndex: number | null;
+  toolCallId: string | null;
+  revision: object;
+  payload: Record<string, unknown>;
+};
+
+/**
+ * Select only bounded activity, reviewer-note and operation emissions. Message
+ * deltas/completions are deliberately outside this boundary, so a final user-
+ * visible response can never be suppressed by this guard.
+ */
+export function runtimeEventEmissionCandidate(event: RuntimeEmissionLike, reference: string): BoundedEmissionCandidate | null {
+  const payload = event.payload ?? {};
+  const revision = canonicalText(event.revision);
+  // Lifecycle state is authoritative. Classify it before reviewer metadata so
+  // a note attached to a started/finished event can never hide that state.
+  if (event.kind.startsWith("activity.")) {
+    const state = payload.state ?? event.kind.slice("activity.".length);
+    return {
+      channel: "activity",
+      identityKey: canonicalText([event.agentOperationId, event.toolCallId, payload.activityRef, event.kind, state]),
+      updateKey: canonicalText([revision, event.agentOperationId, event.toolCallId, event.kind, state]),
+      text: canonicalText(payload),
+      actionable: false,
+      reference
+    };
+  }
+  if (event.kind.startsWith("agent-operation.")) {
+    const state = payload.state ?? payload.settlement ?? payload.status ?? event.kind.slice("agent-operation.".length);
+    return {
+      channel: "operation",
+      identityKey: canonicalText([event.agentOperationId, event.kind, state]),
+      updateKey: canonicalText([revision, event.agentOperationId, event.kind, state]),
+      text: canonicalText(payload),
+      actionable: false,
+      reference
+    };
+  }
+  const role = reviewerRole(payload), note = role ? textField(payload) : null;
+  if (role && note) {
+    const explicitUpdate = payload.updateRef ?? payload.reviewerRevision ?? payload.revision;
+    return {
+      channel: "reviewer",
+      // A session may host many unrelated tasks. Dedupe reviewer prose across
+      // retries/operations of one durable task, but never across task runs.
+      identityKey: canonicalText([event.sessionRef, event.taskRunId, role]),
+      updateKey: canonicalText([event.sessionRef, event.agentOperationId, event.turnIndex, explicitUpdate ?? revision]),
+      text: note,
+      actionable: true,
+      reference
+    };
+  }
+  return null;
+}
+
+/** A small in-memory policy gate. It stores only hashes, never emitted prose. */
+export class BoundedEmissionGuard {
+  readonly capacity: number;
+  readonly #retained: RetainedEmission[] = [];
+  readonly #exact = new Map<string, string>();
+  readonly #normalized = new Map<string, string>();
+  readonly #updates = new Map<string, string>();
+  #primed = 0;
+  #accepted = 0;
+  readonly #suppressed: Record<EmissionSuppressionReason, number> = {
+    empty: 0,
+    filler: 0,
+    "duplicate-exact": 0,
+    "duplicate-normalized": 0,
+    "update-budget": 0
+  };
+
+  constructor(options: { capacity?: number } = {}) {
+    const candidate = Number.isFinite(options.capacity) ? Math.floor(Number(options.capacity)) : DEFAULT_CAPACITY;
+    this.capacity = Math.max(MIN_CAPACITY, Math.min(MAX_CAPACITY, candidate));
+  }
+
+  #keys(candidate: BoundedEmissionCandidate): { exactKey: string; normalizedKey: string; updateKey: string | null; exact: string; normalized: string } {
+    const exact = exactEmissionText(candidate.text), normalized = normalizeEmissionText(exact);
+    const scope = `${candidate.channel}\0${candidate.identityKey}`;
+    return {
+      exact,
+      normalized,
+      exactKey: digest(`${scope}\0exact\0${exact}`),
+      normalizedKey: digest(`${scope}\0normalized\0${normalized}`),
+      updateKey: candidate.actionable ? digest(`${candidate.channel}\0update\0${candidate.updateKey}`) : null
+    };
+  }
+
+  #reject(reason: EmissionSuppressionReason, priorReference: string | null = null, count = true): EmissionDecision {
+    if (count) this.#suppressed[reason] += 1;
+    return { accepted: false, reason, priorReference };
+  }
+
+  #inspect(candidate: BoundedEmissionCandidate, countSuppression: boolean): EmissionDecision {
+    const keys = this.#keys(candidate);
+    if (candidate.actionable && !keys.exact) return this.#reject("empty", null, countSuppression);
+    if (candidate.actionable && FILLER.has(keys.normalized)) return this.#reject("filler", null, countSuppression);
+    const exact = this.#exact.get(keys.exactKey);
+    if (exact) return this.#reject("duplicate-exact", exact, countSuppression);
+    const normalized = this.#normalized.get(keys.normalizedKey);
+    if (normalized) return this.#reject("duplicate-normalized", normalized, countSuppression);
+    const update = keys.updateKey ? this.#updates.get(keys.updateKey) : undefined;
+    if (update) return this.#reject("update-budget", update, countSuppression);
+    return { accepted: true, reason: null, priorReference: null };
+  }
+
+  inspect(candidate: BoundedEmissionCandidate): EmissionDecision {
+    return this.#inspect(candidate, true);
+  }
+
+  /** Seed retained history without counting old suppression as live telemetry. */
+  prime(candidate: BoundedEmissionCandidate): boolean {
+    if (!this.#inspect(candidate, false).accepted) return false;
+    this.recordAccepted(candidate, { primed: true });
+    return true;
+  }
+
+  recordAccepted(candidate: BoundedEmissionCandidate, options: { primed?: boolean } = {}): void {
+    const keys = this.#keys(candidate);
+    const record = { exactKey: keys.exactKey, normalizedKey: keys.normalizedKey, updateKey: keys.updateKey, reference: candidate.reference };
+    this.#retained.push(record);
+    this.#exact.set(record.exactKey, record.reference);
+    this.#normalized.set(record.normalizedKey, record.reference);
+    if (record.updateKey) this.#updates.set(record.updateKey, record.reference);
+    if (options.primed) this.#primed += 1;
+    else this.#accepted += 1;
+    while (this.#retained.length > this.capacity) {
+      const stale = this.#retained.shift() as RetainedEmission;
+      if (this.#exact.get(stale.exactKey) === stale.reference) this.#exact.delete(stale.exactKey);
+      if (this.#normalized.get(stale.normalizedKey) === stale.reference) this.#normalized.delete(stale.normalizedKey);
+      if (stale.updateKey && this.#updates.get(stale.updateKey) === stale.reference) this.#updates.delete(stale.updateKey);
+    }
+  }
+
+  /** Remove fingerprints when their durable event leaves the retention window. */
+  forget(reference: string): boolean {
+    const kept = this.#retained.filter((record) => record.reference !== reference);
+    if (kept.length === this.#retained.length) return false;
+    this.#retained.length = 0;
+    this.#retained.push(...kept);
+    this.#exact.clear();
+    this.#normalized.clear();
+    this.#updates.clear();
+    for (const record of this.#retained) {
+      this.#exact.set(record.exactKey, record.reference);
+      this.#normalized.set(record.normalizedKey, record.reference);
+      if (record.updateKey) this.#updates.set(record.updateKey, record.reference);
+    }
+    return true;
+  }
+
+  reset(): void {
+    this.#retained.length = 0;
+    this.#exact.clear();
+    this.#normalized.clear();
+    this.#updates.clear();
+    this.#primed = 0;
+    this.#accepted = 0;
+    for (const reason of Object.keys(this.#suppressed) as EmissionSuppressionReason[]) this.#suppressed[reason] = 0;
+  }
+
+  telemetry(): BoundedEmissionTelemetry {
+    const suppressedByReason = { ...this.#suppressed };
+    return {
+      schemaVersion: 1,
+      capacity: this.capacity,
+      retained: this.#retained.length,
+      primed: this.#primed,
+      accepted: this.#accepted,
+      suppressed: Object.values(suppressedByReason).reduce((sum, value) => sum + value, 0),
+      suppressedByReason
+    };
+  }
+}

package/packages/piagent-core/runtime/inspection/runtime-event-store.ts

@@ -3,6 +3,12 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { ensurePrivateStateDirectory, resolveLocalStatePath } from "../../extensions/local-state-path.js";
+import {
+  BoundedEmissionGuard,
+  type BoundedEmissionTelemetry,
+  type EmissionSuppressionReason,
+  runtimeEventEmissionCandidate
+} from "./bounded-emission-guard.ts";
 
 export const RUNTIME_EVENT_SCHEMA_VERSION = 2 as const;
 export type RuntimeEventRevision = {
@@ -57,6 +63,9 @@ export type RuntimeEventReplay = {
   lastAvailableSequence: number | null;
   reasonCode: string | null;
 };
+export type RuntimeEventAppendResult =
+  | { event: RuntimeEventV2; appended: true; suppressionReason: null }
+  | { event: RuntimeEventV2 | null; appended: false; suppressionReason: EmissionSuppressionReason | "event-id-duplicate" };
 
 const EVENT_KINDS = new Set([
   "runtime.started", "runtime.health-changed", "runtime.disconnected", "runtime.resync-required", "runtime.resynced", "runtime.phase-changed",
@@ -158,15 +167,17 @@ function readSegment(root: string, file: string): RuntimeEventV2[] {
 export class RuntimeEventStore {
   readonly directory: string;
   readonly corruptions: string[] = [];
-  readonly options: { projectRoot: string; projectRef: string; runtimeInstanceId: string; sessionRef: string; maxEventsPerSegment?: number; maxSegments?: number };
+  readonly options: { projectRoot: string; projectRef: string; runtimeInstanceId: string; sessionRef: string; maxEventsPerSegment?: number; maxSegments?: number; emissionGuardCapacity?: number };
   private events: RuntimeEventV2[] = [];
   private segments: Array<{ file: string; start: number; count: number }> = [];
   private eventById = new Map<string, RuntimeEventV2>();
+  private readonly emissionGuard: BoundedEmissionGuard;
   private readonly maxEventsPerSegment: number;
   private readonly maxSegments: number;
 
-  constructor(options: { projectRoot: string; projectRef: string; runtimeInstanceId: string; sessionRef: string; maxEventsPerSegment?: number; maxSegments?: number }) {
+  constructor(options: { projectRoot: string; projectRef: string; runtimeInstanceId: string; sessionRef: string; maxEventsPerSegment?: number; maxSegments?: number; emissionGuardCapacity?: number }) {
     this.options = options;
+    this.emissionGuard = new BoundedEmissionGuard({ capacity: options.emissionGuardCapacity });
     this.maxEventsPerSegment = Math.max(2, Math.min(1_000, options.maxEventsPerSegment ?? 500));
     this.maxSegments = Math.max(2, Math.min(20, options.maxSegments ?? 10));
     this.directory = storeDirectory(options.projectRoot, options.runtimeInstanceId, options.sessionRef);
@@ -195,11 +206,13 @@ export class RuntimeEventStore {
           if (previous && record.writerSequence !== previous + 1) throw new Error("event sequence gap");
           if (this.eventById.has(record.eventId)) throw new Error("duplicate event identity");
           previous = record.writerSequence; this.events.push(record); this.eventById.set(record.eventId, record);
+          const candidate = runtimeEventEmissionCandidate(record, record.eventId);
+          if (candidate) this.emissionGuard.prime(candidate);
         }
         this.segments.push({ file: name, start, count: records.length });
       }
     } catch {
-      this.events = []; this.segments = []; this.eventById.clear(); this.corruptions.push("event-store-corrupt");
+      this.events = []; this.segments = []; this.eventById.clear(); this.emissionGuard.reset(); this.corruptions.push("event-store-corrupt");
     }
   }
 
@@ -208,14 +221,27 @@ export class RuntimeEventStore {
   retention(): { eventRetentionCount: number; eventRetentionSeconds: number } {
     return { eventRetentionCount: this.maxEventsPerSegment * this.maxSegments, eventRetentionSeconds: 0 };
   }
+  emissionTelemetry(): BoundedEmissionTelemetry { return this.emissionGuard.telemetry(); }
 
-  append(draft: RuntimeEventDraft, recordedAt = new Date().toISOString()): { event: RuntimeEventV2; appended: boolean } {
+  append(draft: RuntimeEventDraft, recordedAt = new Date().toISOString()): RuntimeEventAppendResult {
     if (this.resyncRequired()) throw new Error("WebUI event store requires resync");
     if (draft.projectRef !== this.options.projectRef || draft.runtimeInstanceId !== this.options.runtimeInstanceId || draft.sessionRef !== this.options.sessionRef) throw new Error("Runtime event identity does not match its store");
     const id = eventId(draft), duplicate = this.eventById.get(id);
-    if (duplicate) return { event: structuredClone(duplicate), appended: false };
+    const candidate = runtimeEventEmissionCandidate(draft, id);
+    if (duplicate) {
+      const decision = candidate ? this.emissionGuard.inspect(candidate) : null;
+      return { event: structuredClone(duplicate), appended: false,
+        suppressionReason: decision?.reason ?? "event-id-duplicate" };
+    }
     const sequence = (this.events.at(-1)?.writerSequence ?? 0) + 1;
     const event = validateRuntimeEventEnvelope({ schemaVersion: 2, eventId: id, eventCursor: eventCursor(sequence, id), writerSequence: sequence, recordedAt, ...structuredClone(draft) });
+    if (candidate) {
+      const decision = this.emissionGuard.inspect(candidate);
+      if (!decision.accepted) {
+        const prior = decision.priorReference ? this.eventById.get(decision.priorReference) ?? null : null;
+        return { event: prior ? structuredClone(prior) : null, appended: false, suppressionReason: decision.reason as EmissionSuppressionReason };
+      }
+    }
     let segment = this.segments.at(-1);
     if (!segment || segment.count >= this.maxEventsPerSegment) {
       segment = { file: segmentName(sequence), start: sequence, count: 0 }; this.segments.push(segment);
@@ -228,8 +254,9 @@ export class RuntimeEventStore {
     const descriptor = fs.openSync(target, flags, 0o600);
     try { fs.writeFileSync(descriptor, `${JSON.stringify(event)}\n`); fs.fsyncSync(descriptor); fs.fchmodSync(descriptor, 0o600); } finally { fs.closeSync(descriptor); }
     segment.count += 1; this.events.push(event); this.eventById.set(event.eventId, event);
+    if (candidate) this.emissionGuard.recordAccepted(candidate);
     try { this.enforceRetention(); } catch { this.corruptions.push("event-retention-failed"); }
-    return { event: structuredClone(event), appended: true };
+    return { event: structuredClone(event), appended: true, suppressionReason: null };
   }
 
   private enforceRetention(): void {
@@ -240,7 +267,10 @@ export class RuntimeEventStore {
       if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("event retention target is unsafe");
       fs.unlinkSync(target);
       const discarded = this.events.splice(0, removed.count);
-      for (const event of discarded) this.eventById.delete(event.eventId);
+      for (const event of discarded) {
+        this.eventById.delete(event.eventId);
+        this.emissionGuard.forget(event.eventId);
+      }
     }
   }
 

package/packages/piagent-core/runtime/inspection/task-subagent-tree.ts

@@ -5,7 +5,7 @@ import { inspectOwnedWorkBudget, type OwnedWorkReservation } from "../orchestrat
 import { taskRunOpaqueRef } from "./task-run-index.ts";
 
 type Task = { taskId: string; taskRunId: string; trace?: { outcome?: unknown }; orchestration?: Record<string, unknown>;
-  acceptanceReceipt?: { helperUsage?: { used?: unknown; helpers?: unknown[] } }; [key: string]: any };
+  acceptanceReceipt?: { helperUsage?: { used?: unknown; decision?: unknown; projectedSavingsRatio?: unknown; reasonCodes?: unknown; helpers?: unknown[] } }; [key: string]: any };
 type Identity = { projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string; taskRunId: string;
   agentOperationId: null; toolCallId: null };
 
@@ -53,9 +53,32 @@ function orchestration(task: Task) {
   };
 }
 
+function delegation(task: Task) {
+  const usage = task.acceptanceReceipt?.helperUsage;
+  const explicitDecision = usage?.decision;
+  const action = explicitDecision === "dispatch" || explicitDecision === "skip"
+    ? explicitDecision
+    : usage?.used === true ? "dispatch" : "skip";
+  const reasonCodes = Array.isArray(usage?.reasonCodes)
+    ? [...new Set(usage.reasonCodes.map((item) => String(item ?? "").trim()).filter((item) => /^[a-z0-9_.:-]+$/.test(item)).slice(0, 16))]
+    : action === "dispatch" ? ["helper-dispatched"] : ["parent-direct-default", "delegation-evidence-missing"];
+  const projected = usage?.projectedSavingsRatio;
+  return {
+    action,
+    reasonCodes,
+    projectedNetSavingsRatio: typeof projected === "number" && Number.isFinite(projected)
+      ? Math.max(-10, Math.min(1, projected))
+      : null,
+    minimumRequiredNetSavingsRatio: 0.3,
+    budget: { maxConcurrent: 1, maxTotal: 1, maxRetries: 0, maxWriters: 0 }
+  };
+}
+
 function unavailable(identity: Identity, runRef: string, generatedAt: string, reasonCode: string) {
   return { schemaVersion: 1, version: "piagent-webui-subagent-tree-v1", generatedAt, identity: structuredClone(identity), runRef,
     state: "unavailable", treeRevision: null, evidenceState: "unknown", orchestration: { mode: "unknown", subagents: "unknown" },
+    delegation: { action: "unknown", reasonCodes: [reasonCode], projectedNetSavingsRatio: null,
+      minimumRequiredNetSavingsRatio: 0.3, budget: { maxConcurrent: 1, maxTotal: 1, maxRetries: 0, maxWriters: 0 } },
     parent: null, children: [], writer: { state: "unknown", ownerNodeRef: null },
     nestedLineage: { state: "unavailable", reasonCode: "no-durable-nested-lineage" },
     summary: { total: 0, active: 0, completed: 0, staleResults: 0, readOnly: 0, singleWriter: 0 }, warnings: [],
@@ -66,7 +89,7 @@ export function projectTaskSubagentTree(input: { cwd: string; task: Task; identi
   const generatedAt = input.generatedAt ?? new Date().toISOString(), runRef = taskRunOpaqueRef(input.task.taskRunId);
   const inspected = inspectOwnedWorkBudget(input.cwd, input.task.taskId, input.task.taskRunId, generatedAt);
   if (inspected.state === "corrupt") return unavailable(input.identity, runRef, generatedAt, inspected.reasonCode ?? "helper-budget-corrupt");
-  const policy = orchestration(input.task), parentRef = opaque("parent", input.task.taskRunId), receipts = helperReceipts(input.task);
+  const policy = orchestration(input.task), delegationDecision = delegation(input.task), parentRef = opaque("parent", input.task.taskRunId), receipts = helperReceipts(input.task);
   const children = inspected.reservations.map((item) => child(input.task.taskRunId, parentRef, item, receipts.get(item.deduplicationKey)));
   const matchedReceipts = new Set(inspected.reservations.map((item) => item.deduplicationKey).filter((key) => receipts.has(key)));
   const unmatchedReceipts = Math.max(0, receipts.size - matchedReceipts.size);
@@ -90,10 +113,10 @@ export function projectTaskSubagentTree(input: { cwd: string; task: Task; identi
     staleResults: children.filter((item) => item.result.state === "stale-result").length,
     readOnly: children.filter((item) => item.authority === "read-only").length,
     singleWriter: children.filter((item) => item.authority === "single-writer").length };
-  const treeRevision = `subagent-tree.${createHash("sha256").update(JSON.stringify({ policy, parentState, terminal: inspected.terminal,
+  const treeRevision = `subagent-tree.${createHash("sha256").update(JSON.stringify({ policy, delegationDecision, parentState, terminal: inspected.terminal,
     children, writer, evidenceState })).digest("hex")}`;
   return { schemaVersion: 1, version: "piagent-webui-subagent-tree-v1", generatedAt, identity: structuredClone(input.identity), runRef,
-    state: "ready", treeRevision, evidenceState, orchestration: policy,
+    state: "ready", treeRevision, evidenceState, orchestration: policy, delegation: delegationDecision,
     parent: { nodeRef: parentRef, lifecycleState: parentState, budgetTerminal: inspected.terminal, mergeOwner: "parent" }, children, writer,
     nestedLineage: { state: "unavailable", reasonCode: "no-durable-nested-lineage" }, summary, warnings,
     health: warnings.length ? { state: "degraded", reasonCode: "subagent-tree-incomplete", message: "Some helper/subagent evidence is incomplete." }

package/packages/piagent-core/runtime/inspection/tool-failure-classification.ts

@@ -3,13 +3,19 @@ export type ToolFailureReasonCode =
   | "search-target-missing"
   | "edit-anchor-not-unique"
   | "edit-anchor-stale"
+  | "helper-dispatch-rejected"
+  | "helper-insufficient-evidence"
   | "tool-result-failed";
 
-function boundedText(content: unknown): string {
+function boundedText(content: unknown, depth = 0): string {
+  if (depth > 2) return "";
+  const nested = content && typeof content === "object" && !Array.isArray(content)
+    ? (content as { content?: unknown }).content
+    : undefined;
   const text = typeof content === "string" ? content : Array.isArray(content)
     ? content.filter((item) => item && typeof item === "object" && (item as { type?: unknown }).type === "text")
       .map((item) => String((item as { text?: unknown }).text ?? "")).join("\n")
-    : "";
+    : nested !== undefined ? boundedText(nested, depth + 1) : "";
   return text.slice(0, 8_192);
 }
 
@@ -23,8 +29,19 @@ function commandFromInput(input: unknown): string {
 }
 
 export function classifyToolFailure(toolName: string, isError: boolean, content: unknown, input?: unknown): ToolFailureReasonCode | null {
-  if (!isError) return null;
   const text = boundedText(content);
+  const subagent = /(?:^|[._-])subagents?(?:$|[._-])/i.test(toolName);
+  // Some subagent providers return a successful tool envelope even though no
+  // child was launched, or a zero-exit child explicitly reports that it could
+  // inspect no evidence. Canonical replay must not turn either outcome into a
+  // green "passed" Activity row merely because `isError` is false.
+  if (subagent && /spawn limit reached|no children were started|declared run cannot fit/i.test(text)) {
+    return "helper-dispatch-rejected";
+  }
+  if (subagent && /scope inspected:[^\n]{0,16}\bnone\b|insufficient-evidence rule|no source (?:content|evidence)[^\n]{0,80}(?:accessible|collected)/i.test(text)) {
+    return "helper-insufficient-evidence";
+  }
+  if (!isError) return null;
   // Only the registered, policy-governed `edit` tool may receive an automatic
   // current-file recovery snapshot. A similarly named third-party `replace`
   // tool is not necessarily covered by Piagent's mutation guard.

package/packages/piagent-core/runtime/inspection/webui-snapshot.ts

@@ -84,8 +84,13 @@ function scopedEvents(events: ActivityInspectorEvent[], sessionId: string, task?
   return [...deduped.values()].sort((left, right) => String(left.recordedAt).localeCompare(String(right.recordedAt))).slice(-2_000);
 }
 
-function enrichedFailureReasons(events: ActivityInspectorEvent[], sessionEntries: unknown[]): ActivityInspectorEvent[] {
-  const inputs = new Map<string, unknown>(), results = new Map<string, { content: unknown; isError: boolean; toolName: string }>();
+type CanonicalToolResult = { content: unknown; isError: boolean; toolName: string; recordedAt?: string };
+
+function canonicalToolEvidence(sessionEntries: unknown[]): {
+  inputs: Map<string, unknown>;
+  results: Map<string, CanonicalToolResult>;
+} {
+  const inputs = new Map<string, unknown>(), results = new Map<string, CanonicalToolResult>();
   for (const entry of sessionEntries) {
     if (!entry || typeof entry !== "object" || (entry as any).type !== "message") continue;
     const message = (entry as any).message;
@@ -93,16 +98,44 @@ function enrichedFailureReasons(events: ActivityInspectorEvent[], sessionEntries
       for (const block of message.content) if (block?.type === "toolCall" && typeof block.id === "string") inputs.set(block.id, block.arguments);
     }
     if (message?.role === "toolResult" && typeof message.toolCallId === "string") {
-      results.set(message.toolCallId, { content: message.content, isError: message.isError === true, toolName: String(message.toolName ?? "unknown") });
+      const recordedAt = TIMESTAMP.test(String((entry as any).timestamp ?? message.timestamp ?? ""))
+        ? String((entry as any).timestamp ?? message.timestamp) : undefined;
+      results.set(message.toolCallId, { content: message.content, isError: message.isError === true,
+        toolName: typeof message.toolName === "string" ? message.toolName : "", recordedAt });
     }
   }
-  return events.map((event) => {
-    if (event.event !== "tool_result" || !event.toolCallId || !event.isError) return event;
-    const raw = results.get(event.toolCallId);
+  return { inputs, results };
+}
+
+function reconciledToolResults(events: ActivityInspectorEvent[], evidence: ReturnType<typeof canonicalToolEvidence>): ActivityInspectorEvent[] {
+  const resultIds = new Set(events.filter((event) => event.event === "tool_result" && event.toolCallId).map((event) => event.toolCallId as string));
+  const reconciled = events.map((event) => {
+    if (event.event !== "tool_result" || !event.toolCallId) return event;
+    const raw = evidence.results.get(event.toolCallId);
     if (!raw) return event;
-    const reasonCode = classifyToolFailure(raw.toolName, raw.isError, raw.content, inputs.get(event.toolCallId));
+    const reasonCode = classifyToolFailure(raw.toolName || event.toolName, raw.isError, raw.content, evidence.inputs.get(event.toolCallId));
+    if (!event.isError) {
+      // A newer explicit success remains authoritative over an older canonical
+      // hard error. The exception is a provider-level helper soft failure:
+      // legacy telemetry could only see `isError=false`, while the canonical
+      // result proves that no useful child actually ran.
+      if (raw.isError || !["helper-dispatch-rejected", "helper-insufficient-evidence"].includes(String(reasonCode))) return event;
+      return { ...event, isError: true, reasonCode };
+    }
     return reasonCode ? { ...event, reasonCode } : event;
   });
+  for (const call of events) {
+    if (call.event !== "tool_call" || !call.toolCallId || resultIds.has(call.toolCallId)) continue;
+    const raw = evidence.results.get(call.toolCallId);
+    if (!raw) continue;
+    const reasonCode = classifyToolFailure(raw.toolName || call.toolName, raw.isError, raw.content, evidence.inputs.get(call.toolCallId));
+    const effectiveError = raw.isError || Boolean(reasonCode && !handledToolFailure(reasonCode));
+    reconciled.push({ activityId: `canonical-result:${call.toolCallId}`, event: "tool_result",
+      recordedAt: raw.recordedAt ?? call.recordedAt, sessionId: call.sessionId, taskRunId: call.taskRunId,
+      toolCallId: call.toolCallId, toolName: raw.toolName || call.toolName, isError: effectiveError,
+      ...(reasonCode ? { reasonCode } : {}) });
+  }
+  return reconciled.sort((left, right) => String(left.recordedAt ?? "").localeCompare(String(right.recordedAt ?? "")));
 }
 
 function sourceSummary(document: SourceChangeDocument | null, view: "task" | "working-tree" | "staged") {
@@ -302,12 +335,15 @@ export async function buildWebUiInspectionProjection(input: {
   const taskRevision = input.task ? webUiTaskRevision(input.task) : null;
   const views = await collectSourceChangeViews({ cwd: input.cwd, identity, generatedAt, taskRevision,
     isProtectedPath: (_root, repoPath) => Boolean(matchesProtectedPath(repoPath, effectiveProtectedPaths)) });
-  const events = enrichedFailureReasons(scopedEvents(input.events ?? [], input.sessionId, input.task), input.sessionEntries ?? []);
+  const canonicalEvidence = canonicalToolEvidence(input.sessionEntries ?? []);
+  const events = reconciledToolResults(scopedEvents(input.events ?? [], input.sessionId, input.task), canonicalEvidence);
   const linked = projectCriteriaFileVerifier({ cwd: input.cwd, task: input.task, sourceViews: views, currentSnapshot,
     protectedPaths: input.protectedPaths, events, at: new Date(generatedAt) });
   const sourceChanges = { task: sourceSummary(linked.sourceViews.task, "task"), workingTree: sourceSummary(linked.sourceViews.workingTree, "working-tree"), staged: sourceSummary(linked.sourceViews.staged, "staged") };
   const currentDigest = workingTreeSnapshotUsesCurrentAlgorithm(currentSnapshot) ? workingTreeEvidenceDigest(currentSnapshot) : null;
-  const current = input.current ?? [], controlState = input.task?.trace.outcome === "pending" ? "active" as const : "terminal" as const;
+  const current = (input.current ?? []).filter((item) => (item.status ?? "running") !== "running" || !canonicalEvidence.results.has(item.toolCallId));
+  const runningCurrent = current.find((item) => (item.status ?? "running") === "running");
+  const controlState = input.task?.trace.outcome === "pending" ? "active" as const : "terminal" as const;
   const context = contextProjection(input.contextUsage, generatedAt), usageFacts = usage(input.sessionEntries ?? []);
   const eventCursor = input.eventCursor ?? token("event-cursor", events.map((event) => event.activityId ?? [event.event, event.toolCallId, event.recordedAt]));
   const runtimeRevision = token("runtime-rev", [taskRevision, sourceChanges.workingTree.revision, sourceChanges.staged.revision, eventCursor, current]);
@@ -328,8 +364,8 @@ export async function buildWebUiInspectionProjection(input: {
     capabilities: capabilities(identity, generatedAt, input.resyncRequired === true, input.eventReplay),
     session: {
       connectionState: input.resyncRequired ? "resync-required" : "connected", connectionReason: input.resyncRequired ? "event-replay-gap" : null, displayName: input.task?.sessionName ?? null,
-      operation: current.some((item) => (item.status ?? "running") === "running")
-        ? { liveness: "running", operationRef: null, hostPhase: { state: "known", value: "tool", evidence: "derived", reasonCode: null }, startedAt: timestamp(current[0]?.startedAt, generatedAt), settledAt: null, reasonCode: null }
+      operation: runningCurrent
+        ? { liveness: "running", operationRef: null, hostPhase: { state: "known", value: "tool", evidence: "derived", reasonCode: null }, startedAt: timestamp(runningCurrent.startedAt, generatedAt), settledAt: null, reasonCode: null }
         : { liveness: "idle", operationRef: null, hostPhase: { state: "known", value: "idle", evidence: "derived", reasonCode: null }, startedAt: null, settledAt: null, reasonCode: null },
       controlState: input.task ? controlState : "active", taskOutcome: input.task?.trace.outcome ?? null, approvalState: approvals.state,
       verificationState: linked.verification.state, permissionProfile: { state: "unavailable", value: null, evidence: null, reasonCode: "permission-profile-not-projected" },