@piagent/platform 1.6.1 → 1.8.0

package/packages/piagent-core/runtime/product/task-usage.ts

@@ -0,0 +1,104 @@
+import { inspectContextTelemetry } from "../../extensions/context-engine.js";
+import type { TaskContract } from "../../extensions/guard-types.ts";
+import { firstCorrectEditTiming, type CompletionSource } from "./edit-verifier-timing.ts";
+
+type Event = Record<string, any>;
+type Inspection = { records: Event[]; exists: boolean; integrityFailures: number; recoverableTailBytes: number; inputTruncated: boolean };
+const FIELDS = ["input", "output", "cacheRead", "cacheWrite", "totalTokens"] as const;
+const validNumber = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value >= 0;
+
+export function projectTaskUsage(task: Pick<TaskContract, "taskId" | "taskRunId" | "sessionId">, inspection: Inspection) {
+  const records = inspection.records.filter((event) => event.taskUsageVersion === 1
+    && event.sessionId === task.sessionId && event.taskId === task.taskId && event.taskRunId === task.taskRunId);
+  const warnings = new Set<string>();
+  if (!inspection.exists) warnings.add("telemetry-unavailable");
+  if (inspection.inputTruncated || inspection.integrityFailures || inspection.recoverableTailBytes) warnings.add("telemetry-incomplete");
+  const requests = new Map<string, { start: boolean; terminal?: Event; conflict: boolean; dispatches: number }>();
+  const tools = new Map<string, string>();
+  const attempts = new Map<string, { name: string; attempted: boolean; invoked: boolean; rejected: boolean }>();
+  for (const event of records) {
+    if (event.event === "task_tool_started") warnings.add("legacy-tool-start-is-not-execution-proof");
+    if (["task_tool_attempted", "task_tool_invoked", "task_tool_not_executed"].includes(event.event)) {
+      if (typeof event.toolCallId !== "string" || !event.toolCallId || typeof event.toolName !== "string"
+        || typeof event.requestId !== "string" || !event.requestId) { warnings.add("tool-identity-unavailable"); continue; }
+      const id = `${event.requestId}\u0000${event.toolCallId}`;
+      const call = attempts.get(id) ?? { name: event.toolName, attempted: false, invoked: false, rejected: false };
+      if (call.name !== event.toolName) warnings.add("tool-identity-conflict");
+      call.attempted ||= event.event === "task_tool_attempted";
+      call.invoked ||= event.event === "task_tool_invoked";
+      call.rejected ||= event.event === "task_tool_not_executed";
+      attempts.set(id, call);
+      if (call.invoked) tools.set(id, call.name);
+      continue;
+    }
+    if (!["task_usage_request", "task_usage_dispatch", "task_usage_terminal"].includes(event.event)) continue;
+    if (typeof event.requestId !== "string" || !event.requestId) { warnings.add("request-identity-unavailable"); continue; }
+    const request = requests.get(event.requestId) ?? { start: false, conflict: false, dispatches: 0 };
+    requests.set(event.requestId, request);
+    if (event.event === "task_usage_request") request.start = true;
+    if (Number.isSafeInteger(event.providerRequests)) request.dispatches = Math.max(request.dispatches, event.providerRequests);
+    if (event.event !== "task_usage_terminal") continue;
+    if (event.usageSemantics !== "request-cumulative") { request.conflict = true; continue; }
+    const material = (value: Event) => JSON.stringify([FIELDS.map((field) => value.usage?.[field] ?? null), value.cost ?? null, value.stopReason]);
+    if (request.terminal && material(request.terminal) !== material(event)) {
+      // Late totals may fill missing fields, but cannot rewrite known terminal
+      // amounts. Deltas/session cumulative snapshots are never summed here.
+      const previous = request.terminal;
+      if (FIELDS.some((field) => previous.usage?.[field] != null && event.usage?.[field] != null && previous.usage[field] !== event.usage[field])
+        || (previous.cost != null && event.cost != null && previous.cost !== event.cost) || previous.stopReason !== event.stopReason) request.conflict = true;
+      request.terminal = { ...event, cost: previous.cost ?? event.cost,
+        usage: Object.fromEntries(FIELDS.map((field) => [field, previous.usage?.[field] ?? event.usage?.[field]])) };
+      continue;
+    }
+    request.terminal = event;
+  }
+  const sums = Object.fromEntries(FIELDS.map((field) => [field, 0])) as Record<typeof FIELDS[number], number>;
+  let unknownRequests = 0, failedAttempts = 0, estimatedCost = 0, costKnown = true;
+  for (const request of requests.values()) {
+    const event = request.terminal;
+    if (event && ["error", "aborted"].includes(event.stopReason)) failedAttempts += 1;
+    if (!request.start || !event || request.conflict || request.dispatches > 1) {
+      unknownRequests += 1; costKnown = false; continue;
+    }
+    const usage = event.usage;
+    const numeric = FIELDS.every((field) => validNumber(usage?.[field]) && Number.isSafeInteger(usage[field]));
+    const consistent = numeric && usage.totalTokens === usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
+    // SDK error messages may contain synthetic all-zero usage after a billed
+    // abort. Zero on these paths is not proof that nothing was charged.
+    if (!consistent || (["error", "aborted", "unknown"].includes(event.stopReason) && usage.totalTokens === 0)) unknownRequests += 1;
+    else for (const field of FIELDS) sums[field] += usage[field];
+    if (validNumber(event.cost) && event.costBasis === "sdk-rate-estimate") estimatedCost += event.cost;
+    else costKnown = false;
+  }
+  if (Object.values(sums).some((sum) => !Number.isSafeInteger(sum))) warnings.add("usage-overflow");
+  if (!requests.size) warnings.add("request-coverage-unavailable");
+  if (unknownRequests) warnings.add("request-usage-unknown");
+  if ([...attempts.values()].some((call) => !call.attempted || call.invoked === call.rejected)) warnings.add("tool-execution-unconfirmed");
+  const complete = warnings.size === 0;
+  const counts: Record<string, number> = {};
+  for (const name of tools.values()) Object.defineProperty(counts, name, { value: (Object.hasOwn(counts, name) ? counts[name] : 0) + 1, enumerable: true, configurable: true });
+  return {
+    scope: "observed-sdk-requests" as const,
+    status: complete ? "observed" as const : "unknown" as const,
+    requests: requests.size, unknownRequests, failedAttempts: complete ? failedAttempts : null, observedFailedAttempts: failedAttempts,
+    tokens: complete ? sums.totalTokens : null,
+    components: complete ? sums : null,
+    knownTokenSubtotal: sums.totalTokens,
+    sdkEstimatedCost: complete && costKnown ? estimatedCost : null,
+    billedCost: null, currency: null,
+    actualInvocationCounts: complete ? counts : null,
+    observedInvocationCounts: counts,
+    attemptedToolCalls: attempts.size,
+    notExecutedToolCalls: [...attempts.values()].filter((call) => call.rejected && !call.invoked).length,
+    warnings: [...warnings],
+    limitations: ["SDK reported usage; not an end-to-end billing receipt", "Coverage limited to instrumented requests; pre-instrumentation and hidden provider retries unavailable"]
+  };
+}
+
+export function readTaskUsage(cwd: string, task: TaskContract, source?: CompletionSource) {
+  let inspection: Inspection;
+  try { inspection = inspectContextTelemetry(cwd); }
+  catch { inspection = { records: [], exists: false, integrityFailures: 1, recoverableTailBytes: 0, inputTruncated: false }; }
+  const complete = inspection.exists && !inspection.integrityFailures && !inspection.recoverableTailBytes && !inspection.inputTruncated;
+  return { ...projectTaskUsage(task, inspection), editTiming: firstCorrectEditTiming(task, inspection.records, complete, source) };
+}

package/packages/piagent-core/runtime/quality/protected-refusal-handoff.ts

@@ -0,0 +1,35 @@
+import { hasProtectedRefusalBoundary } from "../workflows/task-intake.ts";
+
+const MARKER = /(?:^|[\s`])(REFUSAL|SAFE_ALTERNATIVE)=([a-z0-9][a-z0-9._:-]{0,127})(?=[\s`]|$)/gi;
+const SAFE_EXPLANATION = /\b(?:cannot|can't|declin(?:e|ed|ing)|non-secret|redact(?:ed|ion)|refus(?:e|ed|ing|al)|safe\s+alternative|won't|will\s+not)\b/i;
+
+function expectedMarkers(prompt: string): string[] | undefined {
+  const found = new Map<string, string>();
+  for (const match of String(prompt ?? "").matchAll(new RegExp(MARKER.source, MARKER.flags))) {
+    const key = match[1].toUpperCase(), value = match[2];
+    if (found.has(key)) return undefined;
+    found.set(key, `${key}=${value}`);
+  }
+  if (found.size !== 2 || !found.has("REFUSAL") || !found.has("SAFE_ALTERNATIVE")) return undefined;
+  return [found.get("REFUSAL")!, found.get("SAFE_ALTERNATIVE")!];
+}
+
+/** A narrow native fallback for a task that explicitly requires refusal. It
+ * recognizes only operator-declared durable markers; it never evaluates or
+ * grants access to the protected material itself. */
+export function protectedRefusalHandoffMatches(prompt: string, response: string): boolean {
+  if (!hasProtectedRefusalBoundary(String(prompt ?? ""))) return false;
+  const expected = expectedMarkers(prompt);
+  if (!expected || typeof response !== "string" || !response.trim() || !(response as any).isWellFormed()
+    || Buffer.byteLength(response) > 65_536) return false;
+  const observed = [...response.matchAll(new RegExp(MARKER.source, MARKER.flags))]
+    .map((match) => `${match[1].toUpperCase()}=${match[2]}`);
+  if (observed.length !== expected.length
+    || observed.some((marker) => !expected.includes(marker))
+    || expected.some((marker) => observed.filter((candidate) => candidate === marker).length !== 1)) return false;
+  const lines = response.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (expected.some((marker) => lines.filter((line) => line === marker).length !== 1)) return false;
+  if (lines.some((line) => /^(?:REFUSAL|SAFE_ALTERNATIVE)=/i.test(line) && !expected.includes(line))) return false;
+  const explanation = lines.filter((line) => !expected.includes(line)).join(" ");
+  return !explanation || SAFE_EXPLANATION.test(explanation);
+}

package/packages/piagent-core/runtime/recovery/acceptance-recovery-guidance.ts

@@ -0,0 +1,21 @@
+export type CriticalRecoveryProjection = { criterionText: string; targets: string[]; missingDimensions: string[]; proofHints: string[]; diagnosticHints?: string[] };
+
+function compactRecoveryField(value: unknown, maximum: number): string {
+  const text = String(value ?? "").replace(/\s+/g, " ").trim();
+  return text.length > maximum ? `${text.slice(0, Math.max(0, maximum - 1)).trimEnd()}…` : text;
+}
+export function criticalAcceptanceRecoveryGuidance(projections: CriticalRecoveryProjection[], includeProofHints = true): string[] {
+  if (projections.length === 0) return [];
+  const lines = ["Critical proof targets (derived only from the current task contract and working tree):"];
+  for (const projection of projections.slice(0, 8)) {
+    const targets = projection.targets.map((item) => compactRecoveryField(item, 80)).filter(Boolean).slice(0, 8);
+    const dimensions = projection.missingDimensions.map((item) => compactRecoveryField(item, 80)).filter(Boolean).slice(0, 8);
+    const criterion = compactRecoveryField(projection.criterionText, 700);
+    lines.push(`- Target: ${targets.join(", ") || "task-scoped behavior"}; missing proof: ${dimensions.join(", ") || "focused-evidence"}; criterion: ${criterion}`);
+  }
+  const hints = [...new Set(projections.flatMap((projection) => includeProofHints ? projection.proofHints : projection.diagnosticHints ?? [])
+    .map((hint) => compactRecoveryField(hint, 300))
+    .filter(Boolean))].slice(0, 8);
+  if (hints.length > 0) lines.push(includeProofHints ? "Proof requirements:" : "Diagnostic evidence (does not grant repair authority):", ...hints.map((hint) => `- ${hint}`));
+  return lines;
+}

package/packages/piagent-core/runtime/recovery/continuation-budget.ts

@@ -66,6 +66,16 @@ export function continuationDenialReasonCode(reason: ContinuationReservation["re
   return "continuation-journal-unavailable";
 }
 
+export function terminalRecoveryForContinuationDenial(
+  decision: RecoveryDecision,
+  reason: ContinuationReservation["reason"]
+): RecoveryDecision {
+  return {
+    ...decision, action: "handoff", continuation: "none", nextPhase: null, sourceMutationAllowed: false,
+    reasonCodes: [...new Set([...decision.reasonCodes, continuationDenialReasonCode(reason)])]
+  };
+}
+
 export function reserveSemanticReviewContinuation(
   cwd: string,
   task: TaskContract,
@@ -97,10 +107,9 @@ export function planRecoveryContinuation(
     missingVerifyCommands: input.missingVerifyCommands, evidenceDigest: decision.evidenceDigest, reasonCodes: decision.reasonCodes
   });
   if (reservation?.allowed) return { recovery: decision, classification, reservation };
-  const reason = continuationDenialReasonCode(reservation?.reason ?? "journal-unavailable");
   return {
     classification, reservation,
-    recovery: { ...decision, action: "handoff", continuation: "none", nextPhase: null, sourceMutationAllowed: false, reasonCodes: [...decision.reasonCodes, reason] }
+    recovery: terminalRecoveryForContinuationDenial(decision, reservation?.reason ?? "journal-unavailable")
   };
 }
 

package/packages/piagent-core/runtime/recovery/diagnostic-delivery.ts

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import crypto from "node:crypto";
+import type { TaskContract } from "../../extensions/guard-types.ts";
+
+export type DiagnosticDelivery = { mode: "diagnostic"; qualityClaim: "withheld";
+  policySha256: string; acceptanceDigest: string; pendingCriterionIds: string[] };
+
+export function installedDiagnosticPolicyDigest(): string | undefined {
+  try {
+    const bytes = fs.readFileSync(new URL("../../policies/base-policy.json", import.meta.url));
+    return JSON.parse(bytes.toString()).finalGate?.acceptanceProofMode === "diagnostic"
+      ? crypto.createHash("sha256").update(bytes).digest("hex") : undefined;
+  } catch { return undefined; }
+}
+
+export function validDiagnosticDelivery(value: unknown, acceptanceDigest: unknown): value is DiagnosticDelivery {
+  const d = value as DiagnosticDelivery;
+  return Boolean(d && Object.keys(d).sort().join(",") === "acceptanceDigest,mode,pendingCriterionIds,policySha256,qualityClaim"
+    && d.mode === "diagnostic" && d.qualityClaim === "withheld"
+    && /^[a-f0-9]{64}$/.test(d.policySha256) && /^[a-f0-9]{64}$/.test(d.acceptanceDigest)
+    && d.acceptanceDigest === acceptanceDigest && Array.isArray(d.pendingCriterionIds)
+    && d.pendingCriterionIds.length > 0 && d.pendingCriterionIds.length <= 12
+    && new Set(d.pendingCriterionIds).size === d.pendingCriterionIds.length
+    && d.pendingCriterionIds.every(id => typeof id === "string" && id.length > 0 && id.length <= 160));
+}
+
+export function diagnosticDeliveryMatchesTask(d: DiagnosticDelivery, task: TaskContract, acceptanceDigest: string): boolean {
+  const pending = (task.acceptanceReceipt?.criteria ?? []).filter(c => c.status !== "satisfied").map(c => c.id).sort();
+  return validDiagnosticDelivery(d, acceptanceDigest) && d.policySha256 === installedDiagnosticPolicyDigest()
+    && JSON.stringify([...d.pendingCriterionIds].sort()) === JSON.stringify(pending);
+}
+
+export function diagnosticDeliveryStateErrors(state: Record<string, any> | null, acceptance: Record<string, any> | null): string[] {
+  const d = state?.diagnosticDelivery;
+  if (d === undefined) return [];
+  return !validDiagnosticDelivery(d, acceptance?.dispositionDigest) || state?.completionApproved !== false
+    || acceptance?.satisfied !== false || state?.gateDecision !== "pass" || state?.taskOutcome !== "completed"
+    || d.pendingCriterionIds.length > (acceptance?.criteriaCount ?? 0) ? ["diagnostic delivery is invalid"] : [];
+}
+
+export function buildDiagnosticDelivery(task: TaskContract,
+  gate: { decision: string; missing: string[]; missingVerifyCommands: string[];
+    acceptanceProof?: { mode: string; pendingCriterionIds: string[] } },
+  acceptance: { satisfied: boolean; dispositionDigest: string }, operationalEvidenceCurrent: boolean): DiagnosticDelivery | undefined {
+  const policySha256 = installedDiagnosticPolicyDigest();
+  return !acceptance.satisfied && policySha256 && gate.acceptanceProof?.mode === "diagnostic"
+    && gate.decision === "pass" && task.trace.outcome === "completed" && operationalEvidenceCurrent
+    && gate.missing.length === 0 && gate.missingVerifyCommands.length === 0
+    ? { mode: "diagnostic", qualityClaim: "withheld", policySha256,
+      acceptanceDigest: acceptance.dispositionDigest, pendingCriterionIds: [...gate.acceptanceProof.pendingCriterionIds] }
+    : undefined;
+}
+
+export function diagnosticCompletionMissing(decision: string, missing: string[], acceptanceSatisfied: boolean,
+  evidenceCurrent: boolean, gateDigestCurrent: boolean, currentExactVerifier: boolean): string[] {
+  return [...missing,
+    ...(decision === "pass" && !acceptanceSatisfied ? ["acceptance-criteria-pending"] : []),
+    ...(decision === "pass" && !evidenceCurrent ? ["working-tree-evidence-not-current"] : []),
+    ...(decision === "pass" && !gateDigestCurrent ? ["completion-gate-tree-digest-untrusted-or-mismatched"] : []),
+    ...(decision === "pass" && !currentExactVerifier ? ["current exact verifier evidence"] : [])];
+}