@piagent/platform 1.6.0 → 1.7.1

package/packages/piagent-core/runtime/registration/task-evidence-tools.ts

@@ -2,6 +2,9 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 type WorkPlanStep = any;
 
+function taskErrorDetails(task: any, reasonCode: string): Record<string, unknown> {
+  return { reasonCode, taskId: task.taskId, taskRunId: task.taskRunId, outcome: task.trace?.outcome, attempt: task.attempt };
+}
 
 export function registerTaskEvidenceTools(pi: ExtensionAPI, deps: Record<string, any>): void {
   const {
@@ -9,7 +12,7 @@ export function registerTaskEvidenceTools(pi: ExtensionAPI, deps: Record<string,
     compactTaskDetails, effectiveProtectedPaths, extensionDir, extractDocument, loadProfileFromContext,
     matchesAnyPath, matchesProtectedPath, nowIso, path, permissionOverrideFromContext,
     policy, readTask, recordTaskProgressCheckpoints, redactText, registerPiagentTool,
-    resolveDocumentPath, resolveDocumentRoots, resolvePermissionProfile, safeTaskId, verifyProjectCapabilityState,
+    resolveDocumentPath, resolveDocumentRoots, resolvePermissionProfile, runtimeState, safeTaskId, verifyProjectCapabilityState,
     writeTask
   } = deps;
   registerPiagentTool(pi, {
@@ -37,24 +40,26 @@ export function registerTaskEvidenceTools(pi: ExtensionAPI, deps: Record<string,
         return { content: [{ type: "text", text: `Task not found in this session: ${params.taskId}` }], isError: true };
       }
       if (task.trace.outcome !== "pending") {
-        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; start a fresh session for another attempt.` }], details: task, isError: true };
+        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; start a fresh session for another attempt.` }], details: taskErrorDetails(task, "task-immutable"), isError: true };
       }
       const stepId = safeTaskId(params.stepId).slice(0, 40);
       const step = task.workPlan.find((item) => item.id === stepId);
       if (!step) {
-        const valid = task.workPlan.map((item) => `${item.id} (${item.status})`).join(", ");
+        const validSteps = task.workPlan.slice(0, 20).map((item) => ({ id: item.id, status: item.status }));
+        const valid = validSteps.map((item) => `${item.id} (${item.status})`).join(", ");
         const actionable = task.workPlan
           .filter((item) => item.status === "in-progress" || (
             item.status === "pending"
             && (item.dependsOn ?? []).every((dependency) => task.workPlan.some((candidate) => candidate.id === dependency && ["done", "skipped"].includes(candidate.status)))
           ))
-          .map((item) => item.id);
+          .map((item) => item.id)
+          .slice(0, 20);
         return {
           content: [{
             type: "text",
             text: `Work-plan step not found: ${stepId}. Valid step IDs: ${valid || "none"}. Currently actionable: ${actionable.join(", ") || "none"}.`
           }],
-          details: task.workPlan,
+          details: { ...taskErrorDetails(task, "work-plan-step-not-found"), stepId, validSteps, actionable },
           isError: true
         };
       }
@@ -66,7 +71,7 @@ export function registerTaskEvidenceTools(pi: ExtensionAPI, deps: Record<string,
       if ((params.status === "in-progress" || params.status === "done") && unresolved.length > 0) {
         return {
           content: [{ type: "text", text: `Step ${stepId} is blocked by unfinished dependencies: ${unresolved.join(", ")}` }],
-          details: { step, unresolved },
+          details: { ...taskErrorDetails(task, "work-plan-step-blocked"), stepId, unresolved: unresolved.slice(0, 20) },
           isError: true
         };
       }
@@ -75,13 +80,13 @@ export function registerTaskEvidenceTools(pi: ExtensionAPI, deps: Record<string,
         return { content: [{ type: "text", text: `A concrete note is required when step ${stepId} fails.` }], isError: true };
       }
       if ((step.status === "done" || step.status === "skipped") && params.status !== step.status) {
-        return { content: [{ type: "text", text: `Work-plan step ${stepId} is already ${step.status} and cannot be reopened in the same attempt.` }], details: step, isError: true };
+        return { content: [{ type: "text", text: `Work-plan step ${stepId} is already ${step.status} and cannot be reopened in the same attempt.` }], details: { ...taskErrorDetails(task, "work-plan-step-immutable"), stepId, status: step.status }, isError: true };
       }
       if (step.status === params.status) {
-        return { content: [{ type: "text", text: `Work-plan step ${stepId} is already ${params.status}; no state change was recorded.` }], details: step, isError: true };
+        return { content: [{ type: "text", text: `Work-plan step ${stepId} is already ${params.status}; no state change was recorded.` }], details: { ...taskErrorDetails(task, "work-plan-step-unchanged"), stepId, status: step.status }, isError: true };
       }
       if (step.status === "failed" && params.status === "in-progress" && !note) {
-        return { content: [{ type: "text", text: `A concrete note is required to reopen failed step ${stepId} within this attempt.` }], details: step, isError: true };
+        return { content: [{ type: "text", text: `A concrete note is required to reopen failed step ${stepId} within this attempt.` }], details: { ...taskErrorDetails(task, "work-plan-step-reopen-note-required"), stepId, status: step.status }, isError: true };
       }
 
       const recordedAt = nowIso();
@@ -254,7 +259,7 @@ export function registerTaskEvidenceTools(pi: ExtensionAPI, deps: Record<string,
   registerPiagentTool(pi, {
     name: "piagent_source_checkout",
     label: "Piagent Source Checkout",
-    description: "Cache and refresh an external Git repository for targeted local inspection.",
+    description: "Prepare an external Git repository for bounded, read-only local inspection.",
     promptSnippet: "Use this before reading a user-provided external source repository.",
     promptGuidelines: [
       "Use for GitHub/GitLab/Bitbucket source repositories supplied by the user.",
@@ -264,15 +269,19 @@ export function registerTaskEvidenceTools(pi: ExtensionAPI, deps: Record<string,
       repoRef: Type.String({ minLength: 3, description: "owner/repo, host/owner/repo, https URL, or git@host:owner/repo.git" }),
       forceUpdate: Type.Optional(Type.Boolean({ description: "Fetch immediately even if the cache was refreshed recently." }))
     }),
-    async execute(_toolCallId, params) {
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       try {
         const repo = checkoutReferenceRepo(params.repoRef, params.forceUpdate === true);
+        const grantedPath = runtimeState.grantSourceCheckoutReadRoot(ctx, repo.checkoutPath);
+        repo.checkoutPath = grantedPath;
         const text = [
           "Source cache ready:",
           `path: ${repo.checkoutPath}`,
           `url: ${repo.cloneUrl}`,
           `commit: ${repo.commit ?? "unknown"}`,
-          `fetched: ${repo.fetched ? "yes" : "no"}`
+          `fetched: ${repo.fetched ? "yes" : "no"}`,
+          "access: read-only for this session via read, grep, find, or ls",
+          "Do not run a checkout script or use shell mutation against this shared cache."
         ].join("\n");
         return {
           content: [{ type: "text", text }],

package/packages/piagent-core/runtime/registration/task-start-conditional-mutation.ts

@@ -0,0 +1,45 @@
+export function conditionalMutationPreTaskContext<ContextEntry extends { path?: string }>(
+  context: ContextEntry[],
+  scope: string[],
+  enabled: boolean,
+  matchesAnyPath: (candidate: string, patterns: string[]) => boolean
+): ContextEntry[] {
+  if (!enabled) return context;
+  return context.filter((item) => typeof item.path === "string" && matchesAnyPath(item.path, scope));
+}
+
+export function taskStartLifecycleGuidance(
+  lifecycleMode: string,
+  mutationPolicy: string,
+  taskId: string
+): string {
+  if (lifecycleMode === "automatic-readonly") {
+    return "Runtime records targeted reads and final completion automatically. Stay read-only and report cited evidence.";
+  }
+  if (lifecycleMode === "assisted-readonly") {
+    return "Runtime records read-only evidence automatically; complete only the explicit evidence-review step before handoff.";
+  }
+  if (mutationPolicy === "forbidden") {
+    return "Runtime permits bounded inspection and exact configured verifier commands only. Source mutation is blocked, and completion requires a zero task delta.";
+  }
+  if (mutationPolicy === "allowed") {
+    return "Verify and review first. Repair only findings supported by evidence; zero delta is valid, while any mutation remains guarded and every exact verifier must pass.";
+  }
+  if (lifecycleMode === "automatic") {
+    return "Runtime will record reads, changes, exact verifier results, and final completion automatically. Continue with ordinary read/edit/bash work.";
+  }
+  if (lifecycleMode === "assisted") {
+    return `Runtime records objective evidence automatically; after verification, complete only step \`review\` with piagent_task_progress using taskId \`${taskId}\` and stepId \`review\`.`;
+  }
+  return "Use the active progress/recovery tools for the custom or high-risk checkpoints.";
+}
+
+export function automaticTaskExpectedOutput(mutationPolicy: string): string {
+  if (mutationPolicy === "forbidden") {
+    return "The requested read-only investigation is answered from observed project evidence without mutating files.";
+  }
+  if (mutationPolicy === "allowed") {
+    return "The current implementation is verified and any evidence-backed failure is repaired; zero task delta remains valid when no repair is needed.";
+  }
+  return "The requested bounded change is implemented and passes the configured verification.";
+}

package/packages/piagent-core/runtime/registration/task-start-guidance.ts

@@ -24,9 +24,9 @@ type ProofTask = {
   criterionGraph?: CriterionGraph;
 };
 
-export const RUNTIME_SOURCE_REUSE_GUIDANCE = "Use runtime-delivered source; do not reread it. On edit drift/oldText mismatch, use attached recovery; otherwise reread the affected region once. Never retry guessed anchors. Otherwise read only missing source or a named criterion-focused test. Globs/directories grant scope, not file targets.";
+export const RUNTIME_SOURCE_REUSE_GUIDANCE = "Use runtime-delivered source; do not reread it. When the operator names an exact file, work from its delivered/current contents; do not list or search the repository merely to rediscover it. On edit drift/oldText mismatch, use attached recovery; otherwise reread the affected region once. Never retry guessed anchors. Otherwise read only missing source or a named criterion-focused test. Globs/directories grant scope, not file targets.";
 
-export const EXACT_VERIFIER_EXECUTION_GUIDANCE = "Keep each exact verifier command separate and unmodified. Run the set once on the final tree; rerun only after a later mutation or a runtime-authorized same-tree infrastructure retry.";
+export const EXACT_VERIFIER_EXECUTION_GUIDANCE = "Keep each exact verifier command separate and unmodified. Run the set once on the final tree; rerun only after a later mutation or a runtime-authorized same-tree infrastructure retry. Do not warm up with an unfocused command already contained in that exact set; use a genuinely criterion-focused test or run the exact set directly.";
 
 function normalizedPath(value: string): string {
   return value.trim().replaceAll("\\", "/");
@@ -102,12 +102,18 @@ export function criticalProofSection(
   acceptanceTests: FocusedTestCandidate[],
   criterionProofs: CriterionProofGuidance[]
 ): string[] {
-  if (proofGuidance.length === 0) return [];
+  if (proofGuidance.length === 0 && criterionProofs.length === 0) return [];
   const candidateMap = new Map<string, string[]>();
   for (const candidate of acceptanceTests) {
     candidateMap.set(candidate.criterionId, [...new Set([...(candidateMap.get(candidate.criterionId) ?? []), candidate.path])]);
   }
   let mappedCandidate = false;
+  const criterionTag = (criterionId: string): string => {
+    const candidates = candidateMap.get(criterionId) ?? [];
+    if (candidates.length === 0) return `[${criterionId}:fallback]`;
+    mappedCandidate = true;
+    return `[${criterionId}:candidate=${candidates.join("|")}]`;
+  };
   const proofLines = proofGuidance.flatMap((proof) => {
     const criterionIds = [...new Set(criterionProofs
       .filter((entry) => entry.guidance.includes(proof))
@@ -115,21 +121,19 @@ export function criticalProofSection(
     if (criterionIds.length === 0) {
       return [`- [fallback] ${proof}`];
     }
-    const tags = criterionIds.map((criterionId) => {
-      const candidates = candidateMap.get(criterionId) ?? [];
-      if (candidates.length === 0) {
-        return `[${criterionId}:fallback]`;
-      }
-      mappedCandidate = true;
-      return `[${criterionId}:candidate=${candidates.join("|")}]`;
-    });
+    const tags = criterionIds.map(criterionTag);
     return [`- ${tags.join("")} ${proof}`];
   });
+  const genericTags = criterionProofs.filter((entry) => entry.guidance.length === 0).map((entry) => criterionTag(entry.criterionId));
+  const genericLines = genericTags.length > 0
+    ? [`- ${genericTags.join("")} Prove every tagged observable clause with linked live assertions; the generic verifier alone is insufficient.`]
+    : [];
   return [[
     "Critical behavioral proof:",
-    ...(!mappedCandidate ? ["No concrete criterion-linked focused test was selected."] : []),
+    ...(!mappedCandidate && genericTags.length === 0 ? ["No concrete criterion-linked focused test was selected."] : []),
     ...proofLines,
-    "Candidate tags are locations, not proof; add/update durable scoped tests with live assertions and changed-test evidence. Each fallback tag requires adding/updating a durable scoped focused test with live assertions. If test scope is unavailable, report missing durable proof and do not claim completion. Run proof after the criterion's final intended mutation and before exact verifiers; rerun after later target mutation or a runtime-authorized same-tree infrastructure retry. Transient/print-only probes and prose are insufficient."
+    ...genericLines,
+    "Candidate tags are locations, not proof; add/update durable scoped tests with live assertions and changed-test evidence. Each fallback tag requires adding/updating a durable scoped focused test with live assertions. If test scope is unavailable, report missing durable proof and do not claim completion. Run proof after the criterion's final intended mutation and before exact verifiers; rerun after later target mutation or a runtime-authorized same-tree infrastructure retry. Transient/print-only probes and prose are insufficient. Claims must match diff/tests; never claim unproved behavior."
   ].join("\n")];
 }
 
@@ -139,6 +143,9 @@ export function automaticTaskExecutionGuidance(task: ProofTask): string {
       ? "Stay mutation-free. Runtime permits bounded inspection and the exact configured verifier, records completion evidence, and requires a zero task delta."
       : "Stay read-only. Runtime records targeted reads and completion evidence; do not call task-management tools.";
   }
+  if (task.mutationPolicy === "allowed") {
+    return "Verify and review the referenced implementation first. Mutate only when observed evidence identifies a repair; zero task delta is valid. Any repair remains subject to the normal mutation guards, and every exact configured verifier must pass against the final working tree. Runtime records evidence and completion; do not call task-management tools.";
+  }
   return task.criterionGraph?.mode === "criterion-graph"
     ? "Follow the execution map and implement dependency-ready criteria. The map plans work but never overrides the operator request or exact verifiers. Runtime records evidence and completion; do not call task-management tools."
     : "Privately map every operator criterion to implementation and durable focused-test coverage before mutating. Finish intended edits and a criterion-by-criterion self-review. Runtime records evidence and completion; do not call task-management tools.";
@@ -150,7 +157,8 @@ export function taskCriticalProofSection(
   repositoryFiles: string[],
   acceptanceProofGuidance: (taskOrText: unknown) => string[],
   isAcceptanceTestPath: (file: string) => boolean,
-  acceptanceLanguageAdapterForPath: (file: string) => { disposition?: string }
+  acceptanceLanguageAdapterForPath: (file: string) => { disposition?: string },
+  requireGenericFallback = true
 ): string[] {
   const proofGuidance = task.changeMode === "source-change" && task.mutationPolicy !== "forbidden"
     ? acceptanceProofGuidance(task)
@@ -158,6 +166,7 @@ export function taskCriticalProofSection(
   const acceptanceTests = concretePlannedAcceptanceTests(
     plannedContext, repositoryFiles, task.criterionGraph, isAcceptanceTestPath, acceptanceLanguageAdapterForPath
   );
-  const criterionProofs = behavioralCriterionProofGuidance(task.criterionGraph, acceptanceProofGuidance);
+  const criterionProofs = behavioralCriterionProofGuidance(task.criterionGraph, acceptanceProofGuidance)
+    .filter((entry) => requireGenericFallback || entry.guidance.length > 0);
   return criticalProofSection(proofGuidance, acceptanceTests, criterionProofs);
 }

package/packages/piagent-core/runtime/registration/task-start-manifest.ts

@@ -0,0 +1,54 @@
+type RepositoryManifestCompatibilityReason = "missing-details-provider" | "nonfunction-details-provider" | "invalid-details-result";
+
+type TaskStartRepositoryManifest = {
+  files: string[];
+  complete: boolean;
+  candidateCount: number;
+  provider: "details" | "legacy-array-fallback";
+  compatibilityReason?: RepositoryManifestCompatibilityReason;
+};
+
+function normalizedManifestFiles(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.filter((item): item is string => typeof item === "string" && item.trim().length > 0))];
+}
+
+/**
+ * Keep rolling upgrades safe when a long-lived host has the legacy extension
+ * entrypoint cached but imports a newer task-start registration module. The
+ * legacy array provider cannot prove whether its result was truncated, so the
+ * compatibility path deliberately reports `complete: false` and records the
+ * provider/reason in the durable task trace.
+ */
+export function resolveTaskStartRepositoryManifestProvider(deps: Record<string, any>): {
+  read(cwd: string, maxFiles?: number): TaskStartRepositoryManifest;
+} {
+  const legacyProvider = deps.repositoryFileManifest;
+  if (typeof legacyProvider !== "function") {
+    throw new TypeError("Piagent task-start registration requires repositoryFileManifest to be a function.");
+  }
+  const detailsProvider = deps.repositoryFileManifestDetails;
+  const compatibilityReason: RepositoryManifestCompatibilityReason | undefined = detailsProvider === undefined
+    ? "missing-details-provider"
+    : typeof detailsProvider !== "function"
+      ? "nonfunction-details-provider"
+      : undefined;
+  const legacyManifest = (cwd: string, maxFiles?: number,
+    reason: RepositoryManifestCompatibilityReason = compatibilityReason ?? "invalid-details-result"): TaskStartRepositoryManifest => {
+    const files = normalizedManifestFiles(legacyProvider(cwd, maxFiles));
+    return { files, complete: false, candidateCount: files.length, provider: "legacy-array-fallback", compatibilityReason: reason };
+  };
+  if (compatibilityReason) return { read: legacyManifest };
+  return {
+    read(cwd: string, maxFiles?: number): TaskStartRepositoryManifest {
+      const details = detailsProvider(cwd, maxFiles);
+      if (!details || typeof details !== "object" || !Array.isArray(details.files)) {
+        return legacyManifest(cwd, maxFiles, "invalid-details-result");
+      }
+      const files = normalizedManifestFiles(details.files);
+      return { files, complete: details.complete === true,
+        candidateCount: Number.isInteger(details.candidateCount) ? Math.max(files.length, details.candidateCount) : files.length,
+        provider: "details" };
+    }
+  };
+}