@piagent/platform 1.4.0 → 1.4.1

package/packages/piagent-core/runtime/policy/block-remedy.ts

@@ -0,0 +1,139 @@
+// What to do about a refusal.
+//
+// A blocked tool call is the only conversation most operators ever have with
+// this policy, and for most of them it was one-sided: the guard states 74
+// distinct refusals and three of them said what to do next. The rest ended at
+// "no", which leaves the reader guessing at a rule they cannot see.
+//
+// Remedies are attached in one place rather than at the 29 sites that build a
+// refusal, for the reason this codebase keeps arriving at: a rule applied at
+// every call site is a rule that will be missed at the next one. Every decision
+// leaves through `registerToolCallHook`, so it is enough to answer there, and a
+// refusal added tomorrow is answered without anyone remembering to.
+
+// Matched against the refusal text in order; the first match wins, so put the
+// narrower phrase above the broader one it would otherwise be swallowed by.
+const REMEDIES: Array<{ match: RegExp; remedy: string }> = [
+  {
+    // `grep glob targeting` and `find pattern targeting` are the same refusal
+    // reached through a different tool, and matching only the shell wording left
+    // two thirds of this family answering nothing.
+    match: /glob can target protected path|glob targeting protected path|pattern targeting protected path/i,
+    remedy: "Name the exact file instead of a pattern: a pattern is refused when any name it can match is protected."
+      + " `piagent explain '<command>'` shows which name it matched."
+  },
+  {
+    match: /builds a filename this guard cannot resolve/i,
+    // This refusal already carries its own guidance, so it only gains the
+    // pointer to the tool that shows the whole chain.
+    remedy: "`piagent explain '<command>'` shows every step that ran and what each one saw."
+  },
+  {
+    match: /(touches|resolves to) protected path|access to protected path|write to protected path/i,
+    remedy: "Use an approved `piagent-context` projection if one is available. Direct access requires the operator"
+      + " to change the protected-path policy; task scope alone does not override it."
+      + " `piagent explain '<command>'` shows which pattern matched."
+  },
+  {
+    match: /write to read-only path/i,
+    remedy: "The active profile marks this path read-only. Change `readOnlyPaths` in `.pi/piagent-profile.json`"
+      + " if the project really should allow writes here, then reapply the profile."
+  },
+  {
+    match: /outside resolved filesystem scope/i,
+    remedy: "Work inside the project, or widen the filesystem scope in the active profile and reapply it."
+  },
+  {
+    match: /cannot mutate paths outside its declared scope|semantic repair must stay inside its declared task scope/i,
+    remedy: "Start a new attempt with `piagent_task_start` listing this path in the scope; a running task cannot widen its own."
+  },
+  {
+    match: /Task Implementation Contract is required/i,
+    remedy: "Call `piagent_task_start` once with explicit project-relative scope, then retry."
+  },
+  {
+    match: /Capability lock is (missing|unreadable)|does not match what this project agreed to/i,
+    remedy: "Reapply the project profile to rebuild the lock: `piagent-init <project> --force-profile`."
+  },
+  {
+    match: /runtime changed during this session/i,
+    remedy: "Restart the Pi session. The lock is re-verified and re-pinned at session start, never mid-session."
+  },
+  {
+    match: /Permission profile read-only blocked/i,
+    remedy: "This session is read-only. Change the access level in Settings, or start it with a writable permission profile."
+  },
+  {
+    match: /Tool (is not registered|registry is disabled|registry blocked)/i,
+    remedy: "Enable the tool group for this profile, or use a tool the profile already allows."
+  },
+  {
+    match: /lifecycle control blocks tool start|resume is blocked|could not enter an audited repair phase/i,
+    remedy: "Resolve the task lifecycle first — resume, repair, or close the current attempt — then retry."
+  },
+  {
+    match: /path traverses symbolic link|path resolves outside the project|path component cannot be inspected/i,
+    remedy: "Use the real path inside the project. A link that leaves the project is refused rather than followed."
+  },
+  {
+    match: /requires confirmation|requires explicit operator approval/i,
+    remedy: "Approve it in the session when prompted; this is a decision the operator makes, not a defect."
+  },
+  {
+    // The whole session is refused here, so this is the refusal most in need of
+    // a next step -- and the one the narrower MCP wording used to miss.
+    match: /Blocked every tool call/i,
+    remedy: "Every tool call is refused while a repository config can reach an ungated server."
+      + " Run `piagent-mcp doctor` to see which config stopped the session, then approve or remove those servers."
+  },
+  {
+    match: /MCP (proxy|shell carrier|command|server)/i,
+    remedy: "Check the server with `piagent-mcp doctor`, and approve it explicitly if the project should reach it."
+  },
+  {
+    match: /is read-only; .*cannot mutate|read-only inspection allowlist/i,
+    remedy: "This task was started read-only. Start a source-change task with `piagent_task_start` when the work needs to write."
+  },
+  {
+    match: /opaque shell mutation whose write target is not statically bounded/i,
+    remedy: "Use the edit, write, or apply-patch tools so the target is named, instead of a shell command that computes it."
+  },
+  {
+    match: /Context budget blocked editing large file/i,
+    remedy: "Edit a narrower range of the file, or split the change, so the edit stays inside the context budget."
+  },
+  {
+    match: /Approval became stale/i,
+    remedy: "Ask for the action again; an approval is bound to the state it was granted for and does not survive a change to it."
+  },
+  {
+    match: /Missing capability|Capability validation failed/i,
+    remedy: "Add the pack that provides it to the project profile, then reapply the profile."
+  },
+  {
+    match: /nesting exceeds inspection depth|unsafe scope pattern/i,
+    remedy: "Flatten the tool input or narrow the scope pattern: anything the guard cannot finish inspecting is refused rather than guessed at."
+  },
+  {
+    match: /start a new attempt or a fresh task/i,
+    remedy: "Start the next attempt with `piagent_task_start`; a closed attempt cannot keep mutating the project."
+  }
+];
+
+// Kept out of the appended text when the refusal already ends by saying what to
+// do, so a reader is never given the same instruction twice in one line.
+const ALREADY_GUIDED = /Write the path out|Reapply the project profile|Restart the session|then retry\.$|Start the task first/i;
+
+export function remedyForReason(reason: string): string | undefined {
+  if (typeof reason !== "string" || reason.trim().length === 0) return undefined;
+  const found = REMEDIES.find((entry) => entry.match.test(reason));
+  if (!found) return undefined;
+  if (ALREADY_GUIDED.test(reason) && !/glob can target|cannot resolve/i.test(reason)) return undefined;
+  return found.remedy;
+}
+
+export function withRemedy<T extends { block: true; reason: string }>(decision: T): T {
+  const remedy = remedyForReason(decision.reason);
+  if (!remedy || decision.reason.includes(remedy)) return decision;
+  return { ...decision, reason: `${decision.reason.replace(/\s+$/, "")} → ${remedy}` };
+}

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

@@ -44,10 +44,11 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
   const taskStartTool = {
     name: "piagent_task_start",
     label: "Piagent Task Start",
-    description: "Create a Task Implementation Contract for the current project before editing.",
-    promptSnippet: "Start a governed implementation task and persist the task contract.",
+    description: "Create a Task Implementation Contract before governed project inspection, command execution, or source changes.",
+    promptSnippet: "Start a governed project task and persist the task contract.",
     promptGuidelines: [
       "Call this exactly once before source edits in a project managed by Pi Agent Platform.",
+      "Use source-change for project command execution, including tests, builds, lint, typecheck, verification, and package dry-runs, even when the operator requires source files to remain unchanged. Read-only intentionally blocks shell execution.",
       "Do not call context, status, policy, evidence-recording, trace, or gate tools first; runtime hooks provide those checks automatically.",
       "Use tiny for a bounded low-risk change, normal for ordinary multi-file work, and high-risk for security, data, release, migration, or external-impact work.",
       "Every scope entry must be a project-relative path or glob such as src/file.ts, src/**, or test/**; never put prose in scope.",
@@ -58,7 +59,9 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       taskId: Type.Optional(Type.String({ minLength: 1 })),
       summary: Type.String({ minLength: 10 }),
       riskLane: StringEnum(["tiny", "normal", "high-risk"] as const),
-      changeMode: Type.Optional(StringEnum(["source-change", "read-only"] as const)),
+      changeMode: Type.Optional(StringEnum(["source-change", "read-only"] as const, {
+        description: "Use source-change for project command execution as well as edits; use read-only only for inspection that needs no shell execution."
+      })),
       maxAttempts: Type.Optional(Type.Number({ minimum: 1, maximum: 10 })),
       expectedOutput: Type.String({ minLength: 10 }),
       acceptanceCriteria: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, maxItems: 12 }),
@@ -103,15 +106,8 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       const migrationRetry = active?.taskId === taskId
         && active?.workingTreeDigestMigration?.status === "new-attempt-required";
       const authorityRetry = active?.taskId === taskId && activeAuthorityReplacement?.required === true;
-      if (active && !migrationRetry && !authorityRetry) {
+      if (active?.trace.outcome === "pending" && !migrationRetry && !authorityRetry) {
         if (active.taskId === taskId) {
-          if (active.trace.outcome !== "pending") {
-            return {
-              content: [{ type: "text", text: `Session already belongs to terminal task ${active.taskId} (${active.trace.outcome}). Start a fresh Pi session for a retry or new task.` }],
-              details: active,
-              isError: true
-            };
-          }
           const manifest = repositoryFileManifest(ctx.cwd);
           const currentScopeResolution = resolveTaskScopePatterns(active.scope, manifest);
           const proposedScopeResolution = Array.isArray(params.scope)
@@ -151,7 +147,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
           };
         }
         return {
-          content: [{ type: "text", text: `Session already belongs to task ${active.taskId} (${active.taskRunId}, ${active.trace.outcome}). Use one Pi session per task and start a fresh session before another task.` }],
+          content: [{ type: "text", text: `Session already has pending task ${active.taskId} (${active.taskRunId}). Complete or stop it before starting another task in this conversation.` }],
           details: active,
           isError: true
         };
@@ -428,7 +424,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
     const started = await taskStartTool.execute(
       `runtime-intake-${ctx.sessionManager.getSessionId()}`,
       {
-        taskId: hasOperatorSessionName(sessionName) ? sessionName : summary,
+        taskId: active && active.trace.outcome !== "pending" ? summary : hasOperatorSessionName(sessionName) ? sessionName : summary,
         summary,
         riskLane: automaticTaskRiskLane(prompt),
         intakeMode: "runtime",

package/packages/piagent-core/runtime/session/token-economics.js

@@ -0,0 +1,34 @@
+// What a session's token counts mean, in one place.
+//
+// `fresh` is the benchmark's own definition -- input + output, the tokens billed
+// at full rate -- restated here rather than recomputed differently by each
+// reader. The published benchmark and the terminal must never mean two things by
+// the same word.
+//
+// The cache hit rate is reported beside `fresh`, never instead of it. In that
+// same benchmark the baseline surface held the *higher* hit rate, 84.9% against
+// 53.0%, while spending more than twice the fresh tokens: a high rate on a large
+// prompt is not a cheap session. The rate explains a cost, it does not report one.
+
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+
+export function sessionTokenEconomics(tokens = {}) {
+  const { input, output, cacheRead } = tokens ?? {};
+  const fresh = finite(input) && finite(output) ? input + output : null;
+  const prompt = finite(cacheRead) && finite(input) ? cacheRead + input : null;
+  return {
+    fresh,
+    // A session that has read nothing has no rate to report, which is not the
+    // same as a rate of zero.
+    cacheHitRate: prompt !== null && prompt > 0 ? cacheRead / prompt : null
+  };
+}
+
+export function formatTokenEconomics(economics, formatNumber, formatPercent) {
+  return {
+    fresh: economics.fresh === null ? "unknown" : `${formatNumber(economics.fresh)} billed at full rate`,
+    cache: economics.cacheHitRate === null
+      ? "unknown"
+      : `${formatPercent(100 * economics.cacheHitRate)} of prompt tokens served from cache`
+  };
+}

package/packages/piagent-core/runtime/tools/phase-tool-runtime.ts

@@ -80,7 +80,8 @@ export class PhaseToolRuntime {
 
   toolDecision(ctx: ExtensionContext, toolName: string): { block: true; reason: string } | undefined {
     if (this.effectiveMode(ctx) !== "on") return undefined;
-    if (toolName === "piagent_task_start" && this.digestMigrationStatus(ctx) === "new-attempt-required") return undefined;
+    if (toolName === "piagent_task_start"
+      && (this.digestMigrationStatus(ctx) === "new-attempt-required" || this.states.get(this.key(ctx))?.currentPhase === "terminal")) return undefined;
     const state = this.states.get(this.key(ctx));
     if (!state) return undefined;
     const policy = phaseToolPolicy(state.currentPhase, state.changeMode);

package/packages/piagent-core/runtime/workflows/task-intake.ts

@@ -12,6 +12,7 @@ const AUTO_INTAKE_READ_ONLY_LEAD = /^\s*\/?(?:analy[sz]e|audit|check|discuss|exp
 const AUTO_INTAKE_MANUAL_RISK = /\b(?:credential|database|deploy|destructive|encryption|external provider|payment|permission|production|publish|secret|token rotation)\b/i;
 const AUTO_READ_ONLY_INTENT = /\b(?:analy[sz]e|audit|check|diagnos(?:e|is)|explain|inspect|investigate|plan|research|review|scout|summari[sz]e|triage|kiem tra|nghien cuu|giai thich|danh gia)\b/i;
 const AUTO_READ_ONLY_BOUNDARY = /\b(?:read-only|no edits?|do not edit(?: files?| source| project| repo)?|do not change (?:files?|source|project|repo)|do not mutate (?:files?|source|project|repo|workspace)|khong sua(?: file| source| project)?|khong edit(?: file| source| project)?|khong doi(?: file| source| project)?)\b/i;
+const AUTO_EXECUTION_INTENT = /(?:\b(?:run|execute|execution|rerun|re-run|chay)\b.{0,80}\b(?:tests?|build|checks?|gates?|lint|typecheck|package|pack|verify|verification)\b|\b(?:npm|pnpm|yarn|bun)\s+(?:test|pack|run\s+(?:build|check|lint|typecheck|verify))\b)/i;
 
 export const AUTO_INTAKE_SNAPSHOT_PATTERNS = [
   "src/**", "app/**", "lib/**", "packages/**", "test/**", "tests/**", "spec/**", "__tests__/**"
@@ -49,6 +50,10 @@ export function automaticTaskIntakeEligible(prompt: string, readProtectedPaths:
   const text = String(prompt ?? "").trim();
   if (!text || text.length > AUTO_INTAKE_MAX_PROMPT_CHARS) return false;
   const signal = classifyContextTask(text);
+  if (AUTO_EXECUTION_INTENT.test(text)) {
+    if (/\bpiagent_task_start\b/i.test(text)) return false;
+    return !signal.paths.some((candidate) => matchesProtectedPath(candidate, readProtectedPaths));
+  }
   if (signal.workflow !== "task" || !AUTO_INTAKE_CHANGE_INTENT.test(text)) return false;
   if (AUTO_INTAKE_READ_ONLY_LEAD.test(text) || AUTO_INTAKE_MANUAL_RISK.test(text)) return false;
   if (/\bpiagent_task_start\b/i.test(text)) return false;

package/packages/piagent-core/security/sensitive-data.js

@@ -8,6 +8,13 @@ const TOKEN_PATTERNS = [
   /\bsk-(?:(?:proj|svcacct|admin|ant)-)?[A-Za-z0-9_-]{20,}\b/g,
   /\bsk_(?:live|test)_[A-Za-z0-9]{16,}\b/g,
   /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g,
+  // An npm token was recognised only where something named it -- `NPM_TOKEN=...`
+  // caught the assignment, a field called `token` caught the field -- so the one
+  // place it actually appears was missed: `//registry.npmjs.org/:_authToken=npm_…`
+  // is the whole of an `.npmrc`, and a `cat` of that file or a failing publish log
+  // carried the credential through unredacted. Every other provider here is
+  // recognised by the shape of its token; npm was the gap.
+  /\bnpm_[A-Za-z0-9]{30,}\b/g,
   /\bAIza[0-9A-Za-z_-]{20,}\b/g,
   /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g
 ];