@piagent/platform 1.5.4 → 1.6.0

package/packages/piagent-core/runtime/context/context-delta-shadow.ts

@@ -0,0 +1,53 @@
+import crypto from "node:crypto";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { buildContextPack, ensureContextIndexV2 } from "../../extensions/context-engine.js";
+import { durableContextEvidenceEntries } from "../../extensions/context-evidence.js";
+import type { TaskContract } from "../../extensions/guard-types.js";
+
+export type ContextDeltaShadowMode = "off" | "sample" | "on";
+
+type ShadowInput = {
+  ctx: ExtensionContext;
+  query: string;
+  turnId: string;
+  task: TaskContract;
+  mode: ContextDeltaShadowMode;
+  protectedTarget: boolean;
+  excludePatterns: string[];
+  telemetry: (ctx: ExtensionContext, payload: Record<string, unknown>) => void;
+};
+
+function sampled(taskRunId: string, query: string): boolean {
+  const byte = crypto.createHash("sha256").update(`${taskRunId}\0${query}`).digest()[0];
+  return byte < 64;
+}
+
+export async function measureContextDeltaShadow(input: ShadowInput): Promise<void> {
+  if (input.mode === "off" || input.protectedTarget || (input.mode === "sample" && !sampled(input.task.taskRunId, input.query))) return;
+  const usage = input.ctx.getContextUsage();
+  if (usage && Number(usage.percent ?? 0) >= 80) return;
+  try {
+    const { status } = await ensureContextIndexV2(input.ctx.cwd, { excludePatterns: input.excludePatterns, rebuildMissing: false });
+    if (!status.exists || status.stale) return;
+    const pack = await buildContextPack(input.ctx.cwd, input.query, {
+      budgetTokens: 1_200,
+      includeCode: false,
+      limit: 10,
+      excludePatterns: input.excludePatterns
+    });
+    const manifested = new Set(durableContextEvidenceEntries(input.task).map((entry) => entry.path));
+    const duplicateItems = pack.selected.filter((item) => manifested.has(item.path));
+    input.telemetry(input.ctx, {
+      event: "context_delta_shadow",
+      turnId: input.turnId,
+      queryHash: pack.queryHash,
+      candidatePaths: pack.selected.map((item) => item.path),
+      pathsAlreadyManifested: duplicateItems.map((item) => item.path),
+      candidateTokens: pack.selected.reduce((sum, item) => sum + item.estimatedTokens, 0),
+      duplicateCandidateTokens: duplicateItems.reduce((sum, item) => sum + item.estimatedTokens, 0)
+    });
+  } catch (error) {
+    input.telemetry(input.ctx, { event: "context_delta_shadow", turnId: input.turnId, skipped: "error", error: error instanceof Error ? error.message : String(error) });
+  }
+}

package/packages/piagent-core/runtime/context/context-efficiency-format.ts

@@ -0,0 +1,47 @@
+type ContextEfficiencyReport = {
+  metrics: {
+    contextWasteScore: number | null;
+    contextWasteScoreEstimate: number;
+    contextWasteScoreEvidenceCoverage: number;
+    averageActiveTools: number;
+    toolSchemaPrefixShare: number;
+    toolSchemaToSystemRatio: number;
+    duplicateReads: number;
+    comparableReadCalls: number;
+    readCalls: number;
+    readEvidenceCoverage: number;
+    contextFallbackRereads: number;
+    contextSelections: number;
+    duplicateOutputRate: number;
+    lowConfidencePacks: number;
+    editRecoveryContextCount: number;
+    editRecoveryFailures: number;
+    editRecoverySuppressedFailures: number;
+    editRecoveryEstimatedTokens: number;
+    editRecoveryFailureEvidenceCoverage: number;
+  };
+  coverage: { wasteScore: { status: string } };
+  sample: { contextPacks: number };
+  recommendations: string[];
+};
+
+export function formatContextEfficiencyReport(
+  report: ContextEfficiencyReport,
+  formatPercent: (value: number) => string
+): string {
+  const wasteScore = report.metrics.contextWasteScore === null
+    ? `unavailable (diagnostic estimate ${report.metrics.contextWasteScoreEstimate}/100; evidence ${formatPercent(report.metrics.contextWasteScoreEvidenceCoverage)}, ${report.coverage.wasteScore.status})`
+    : `${report.metrics.contextWasteScore}/100 (lower is better; evidence ${formatPercent(report.metrics.contextWasteScoreEvidenceCoverage)}, ${report.coverage.wasteScore.status})`;
+  return [
+    `contextWasteScore: ${wasteScore}`,
+    `activeTools: ${report.metrics.averageActiveTools}`,
+    `toolSchemaPrefixShare: ${formatPercent(report.metrics.toolSchemaPrefixShare)}`,
+    `toolSchemaToSystemRatio: ${report.metrics.toolSchemaToSystemRatio}`,
+    `duplicateReads: ${report.metrics.duplicateReads}/${report.metrics.comparableReadCalls} comparable (${report.metrics.readCalls} observed; coverage ${formatPercent(report.metrics.readEvidenceCoverage)})`,
+    `fallbackRereads: ${report.metrics.contextFallbackRereads}/${report.metrics.contextSelections}`,
+    `duplicateOutput: ${formatPercent(report.metrics.duplicateOutputRate)}`,
+    `lowConfidencePacks: ${report.metrics.lowConfidencePacks}/${report.sample.contextPacks}`,
+    `editRecovery: ${report.metrics.editRecoveryContextCount}/${report.metrics.editRecoveryFailures} failures returned context; ${report.metrics.editRecoverySuppressedFailures} suppressed; ${report.metrics.editRecoveryEstimatedTokens} estimated tokens; classification coverage ${formatPercent(report.metrics.editRecoveryFailureEvidenceCoverage)}`,
+    ...report.recommendations.map((recommendation) => `- ${recommendation}`)
+  ].join("\n");
+}

package/packages/piagent-core/runtime/context/context-evidence-qualification.ts

@@ -0,0 +1,32 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { TaskContract } from "../../extensions/guard-types.js";
+import type { ObservedTaskContext, RuntimeSessionState } from "../session/runtime-state.ts";
+
+type TaskIdentity = { taskId: string; taskRunId: string };
+
+type ContextEvidenceQualificationDependencies = {
+  state: RuntimeSessionState;
+  activeTask: (ctx: ExtensionContext) => TaskContract | undefined;
+};
+
+export function recordObservedContextEvidence(
+  ctx: ExtensionContext,
+  entry: ObservedTaskContext | undefined,
+  taskIdentity: TaskIdentity | undefined,
+  dependencies: ContextEvidenceQualificationDependencies
+): void {
+  if (!entry) return;
+  dependencies.state.rememberObservedContext(ctx, entry);
+  const activeTask = dependencies.activeTask(ctx);
+  if (
+    taskIdentity
+    && activeTask?.trace.outcome === "pending"
+    && activeTask.taskId === taskIdentity.taskId
+    && activeTask.taskRunId === taskIdentity.taskRunId
+  ) {
+    dependencies.state.rememberQualifiedContextEvidence(ctx, taskIdentity.taskRunId, entry);
+  } else if (!activeTask || activeTask.trace.outcome !== "pending") {
+    dependencies.state.rememberPreTaskContext(ctx, entry);
+  }
+}

package/packages/piagent-core/runtime/context/prefix-telemetry.ts

@@ -0,0 +1,47 @@
+import crypto from "node:crypto";
+
+type ProviderToolMetadata = {
+  name: string;
+  description?: unknown;
+  parameters?: unknown;
+};
+
+function canonicalValue(value: unknown): unknown {
+  if (value === null || ["string", "number", "boolean"].includes(typeof value)) return value;
+  if (Array.isArray(value)) return value.map((item) => canonicalValue(item));
+  if (!value || typeof value !== "object") return undefined;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .filter(([, item]) => item !== undefined && typeof item !== "function" && typeof item !== "symbol")
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, item]) => [key, canonicalValue(item)])
+  );
+}
+
+export function deepCanonicalJson(value: unknown): string {
+  return JSON.stringify(canonicalValue(value));
+}
+
+function hash(value: string): string {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+export function buildPrefixTelemetry(systemPrompt: string, tools: ProviderToolMetadata[]): {
+  systemPromptHash: string;
+  toolSchemaHash: string;
+  prefixSurfaceHash: string;
+  canonicalToolSurface: string;
+} {
+  const providerSurface = tools
+    .map((tool) => ({ name: tool.name, description: tool.description, parameters: tool.parameters }))
+    .sort((left, right) => left.name.localeCompare(right.name));
+  const canonicalToolSurface = deepCanonicalJson(providerSurface);
+  const systemPromptHash = hash(systemPrompt);
+  const toolSchemaHash = hash(canonicalToolSurface);
+  return {
+    systemPromptHash,
+    toolSchemaHash,
+    prefixSurfaceHash: hash(`${systemPromptHash}\0${toolSchemaHash}`),
+    canonicalToolSurface
+  };
+}

package/packages/piagent-core/runtime/context/repository-memory-hints.ts

@@ -0,0 +1,27 @@
+import { estimateContextTokens } from "../../extensions/context-engine.js";
+
+type RepositoryMemoryCandidate = {
+  record: { id?: string; fact: string; citations: Array<{ path: string }> };
+  matchedTerms: string[];
+};
+
+export function formatRepositoryMemoryHints(
+  candidates: RepositoryMemoryCandidate[],
+  budgetTokens: number
+): { text: string; ids: string[] } {
+  if (budgetTokens < 80 || candidates.length === 0) return { text: "", ids: [] };
+  const lines = [
+    "[Piagent repository memory: advisory only]",
+    "Verify every hint against the cited current file before relying on it."
+  ];
+  const ids: string[] = [];
+  for (const candidate of candidates) {
+    const paths = candidate.record.citations.slice(0, 4).map((citation) => citation.path).join(", ");
+    const line = `- ${candidate.record.fact.slice(0, 320)} [sources: ${paths}]`;
+    const proposed = [...lines, line].join("\n");
+    if (estimateContextTokens(proposed) > budgetTokens) break;
+    lines.push(line);
+    if (candidate.record.id) ids.push(candidate.record.id);
+  }
+  return ids.length > 0 ? { text: lines.join("\n"), ids } : { text: "", ids: [] };
+}

package/packages/piagent-core/runtime/hooks/agent-prompt-telemetry.ts

@@ -0,0 +1,56 @@
+import type { RuntimeModelSnapshot } from "../model/runtime-snapshot.ts";
+import { runtimeModelSnapshotDigest } from "../model/runtime-snapshot.ts";
+import type { ModelRouteEvaluation } from "../model/model-route-runtime.ts";
+import type { SolverShadowEvaluation } from "../solver/solver-shadow.ts";
+
+export function runtimeSnapshotTelemetry(snapshot?: RuntimeModelSnapshot) {
+  if (!snapshot) return undefined;
+  return {
+    schemaVersion: snapshot.schemaVersion,
+    digest: runtimeModelSnapshotDigest(snapshot),
+    provider: snapshot.provider,
+    modelId: snapshot.modelId,
+    contextWindow: snapshot.contextWindow,
+    requestedThinkingLevel: snapshot.requestedThinkingLevel,
+    effectiveThinkingLevel: snapshot.effectiveThinkingLevel,
+    warningCount: snapshot.warnings.length
+  };
+}
+
+export function solverShadowTelemetry(evaluation?: SolverShadowEvaluation) {
+  if (evaluation?.status !== "ok") return evaluation;
+  return {
+    mode: evaluation.decision.mode,
+    route: evaluation.decision.route,
+    featureHash: evaluation.features.featureHash,
+    reasonCodes: evaluation.decision.reasonCodes,
+    confidence: evaluation.decision.confidence,
+    reused: evaluation.reused,
+    persisted: evaluation.persisted,
+    durationMs: evaluation.durationMs,
+    warnings: evaluation.warnings
+  };
+}
+
+export function modelRouteTelemetry(evaluation?: ModelRouteEvaluation) {
+  if (evaluation?.status !== "ok") return evaluation;
+  return {
+    mode: evaluation.decision.mode,
+    objective: evaluation.decision.objective,
+    capabilityBand: evaluation.decision.capabilityBand,
+    safetyFloor: evaluation.decision.safetyFloor,
+    disposition: evaluation.decision.disposition,
+    selectionSource: evaluation.decision.selectionSource,
+    provider: evaluation.decision.provider,
+    modelId: evaluation.decision.modelId,
+    effort: evaluation.decision.effort,
+    downgradeSteps: evaluation.decision.downgradeSteps,
+    enforced: evaluation.decision.enforced,
+    decisionDigest: evaluation.decision.decisionDigest,
+    reasonCodes: evaluation.decision.reasonCodes,
+    reused: evaluation.reused,
+    persisted: evaluation.persisted,
+    durationMs: evaluation.durationMs,
+    warnings: evaluation.warnings
+  };
+}