@piagent/platform 1.6.1 → 1.8.0

package/packages/piagent-core/runtime/session/system-prompt.ts

@@ -12,8 +12,8 @@ const RUNTIME_MANAGED_PROJECT_INSTRUCTIONS = [
   "Piagent runtime-managed task flow:",
   "1. Runtime creates the task contract automatically for a bounded source-changing request before the model starts.",
   "2. Only when runtime intake pauses for a broad, high-risk, or ambiguous task, call `piagent_task_start` exactly once with project-relative focus paths/globs; reuse an active contract.",
-  "3. Use complete runtime-delivered source directly; do not reread it normally. 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 concrete criterion-linked focused test. Task scope seeds retrieval and review; it does not limit source mutation. Follow repository evidence across packages or child repos while preserving explicit user constraints. When creating an explicitly requested new path, do not probe that destination with read first; create it, then read back or verify it. If existence matters, use a non-erroring existence check.",
-  "4. Preserve every runtime-provided verifier exactly and keep commands separate. Run the exact verifier set once on the final tree; rerun only after a later mutation, an explicit operator request, or a runtime-authorized same-tree infrastructure retry. Before any repeat, use piagent_task_gate_check and run only commands reported missing for the current tree; Piagent reuses a durable exact pass on an unchanged tree. Automatic tasks need no other management calls.",
+  "3. Use complete runtime-delivered source directly; do not reread it normally. When the operator names an exact file, work from its delivered/current contents instead of listing or searching merely to rediscover it. Once exact current context is known for a coherent source-and-test or other multi-file change, prefer one apply_patch call over serial edit/write calls. On edit drift/oldText mismatch, use attached recovery; otherwise reread the affected region once. Never retry guessed anchors or batch multiple pattern calls against an unconfirmed target; confirm it once first. Otherwise read only missing source or a concrete criterion-linked focused test. Task scope seeds retrieval and review; it does not limit source mutation. Follow repository evidence across packages or child repos while preserving explicit user constraints. Report only paths and line references actually returned by tools; label inferences and unknowns, and never reread solely to format a citation. When creating an explicitly requested new path, do not probe that destination with read first; create it, then read back or verify it. If existence matters, use a non-erroring existence check.",
+  "4. Preserve every runtime-provided verifier exactly and keep commands separate. When you change source, add or update the smallest focused executable tests that directly exercise every explicit behavior, boundary, and error criterion unless current delivered tests already do; a broad verifier pass without criterion coverage is not completion evidence for that change. Run the exact verifier set once on the final tree; rerun only after a later mutation, an explicit operator request, 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. Before any repeat, use piagent_task_gate_check and run only commands reported missing for the current tree; Piagent reuses a durable exact pass on an unchanged tree. Automatic tasks need no other management calls.",
   "5. Treat the current source, the operator request, and the durable Task Contract as authoritative. The parent model reasons and implements directly. Helpers are off unless explicitly enabled; even then, allow at most one fresh read-only helper only when runtime evidence proves two independent lanes and at least 30% projected net token saving. Never delegate writes, inherit parent history, fan out, or retry a deterministic helper failure. Preserve explicit user constraints and report unresolved risk. Runtime-derived scope is only the initial focus and may expand when implementation evidence requires FE, BE, tests, configuration, or another child repo. Runtime hooks enforce protected paths and approvals and record context, changes, current-tree verification, trace and final gate. Diagnostic groups appear only for explicit requests or manual high-risk checkpoints."
 ].join("\n");
 
@@ -48,7 +48,7 @@ export function compactManagedProjectInstructions(
 ): { systemPrompt: string; compacted: boolean } {
   const concise = mode === "protected"
     ? "Piagent protected-path policy: do not read, disclose, or mutate protected content. Refuse without tool calls."
-    : "Piagent runtime task is injected below. Root project instructions are already loaded; do not re-read root AGENTS.md. Treat current source, the operator request, and the durable Task Contract as authoritative; preserve explicit user constraints and report unresolved risk. The parent reasons and implements directly. Helpers are opt-in and limited to one fresh read-only helper only with two independent lanes and at least 30% projected net token saving; never delegate writes, inherit parent history, fan out, or retry a deterministic helper failure. Runtime-derived scope is an initial retrieval/review focus, not a mutation boundary; follow repository evidence across packages and child repos. Use complete runtime-delivered source directly without rereading it normally. 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 concrete criterion-linked focused test. For an explicitly requested new path, create it without a speculative read, then read back or verify it. Preserve every runtime verifier exactly and keep commands separate. Run the exact verifier set once on the final tree; rerun only after a later mutation or a runtime-authorized same-tree infrastructure retry. Make no task-management calls.";
+    : "Piagent runtime task is injected below. Root project instructions are already loaded; do not re-read root AGENTS.md. Treat current source, the operator request, and the durable Task Contract as authoritative; preserve explicit user constraints and report unresolved risk. The parent reasons and implements directly. Helpers are opt-in and limited to one fresh read-only helper only with two independent lanes and at least 30% projected net token saving; never delegate writes, inherit parent history, fan out, or retry a deterministic helper failure. Runtime-derived scope is an initial retrieval/review focus, not a mutation boundary; follow repository evidence across packages and child repos. Use complete runtime-delivered source directly without rereading it normally. For an exact operator-named file, use delivered/current contents instead of listing or searching merely to rediscover it. Once exact current context is known for a coherent source-and-test or other multi-file change, prefer one apply_patch call over serial edit/write calls. On edit drift/oldText mismatch, use attached recovery; otherwise reread the affected region once. Never retry guessed anchors or batch pattern calls against an unconfirmed target; confirm it once first. Otherwise read only missing source or a concrete criterion-linked focused test. When source is changed, add or update the smallest focused executable tests for every explicit behavior, boundary, and error criterion unless delivered tests already cover them; a broad verifier pass alone is not completion evidence for that change. Report only tool-observed paths and line references; label inferences and unknowns, and never reread solely to format a citation. For an explicitly requested new path, create it without a speculative read, then read back or verify it. Preserve every runtime verifier exactly and keep commands separate. Run the exact verifier set once on the final tree. Do not warm up with an unfocused command already contained in that exact set; rerun only after a later mutation or a runtime-authorized same-tree infrastructure retry. Make no task-management calls.";
   const markerStart = "<!-- piagent-managed:start -->";
   const markerEnd = "<!-- piagent-managed:end -->";
   const start = systemPrompt.indexOf(markerStart);

package/packages/piagent-core/runtime/session/uncertain-send-continuation.ts

@@ -0,0 +1,231 @@
+import { captureWorkspaceVerificationSnapshot } from "../../extensions/workspace-verification-snapshot.js";
+import { diagnosticDeliveryMatchesTask, type DiagnosticDelivery } from "../recovery/diagnostic-delivery.ts";
+import type { TaskContract } from "../../extensions/guard-types.js";
+import {
+  handoffIdentityMatchesTask,
+  readHandoffProjection,
+  taskAcceptanceDisposition,
+  type HandoffProjection
+} from "../recovery/handoff-projection.ts";
+
+export const UNCERTAIN_SEND_RECEIPT_TYPE = "piagent-uncertain-send-continuation-v1";
+
+function folded(value: unknown): string {
+  return String(value ?? "")
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/đ/g, "d")
+    .replace(/Đ/g, "D")
+    .replace(/\s+/g, " ")
+    .trim()
+    .toLowerCase();
+}
+
+/**
+ * Identify the narrow uncertain-delivery recovery protocol. Generic requests
+ * such as "continue" or "check the previous work" intentionally do not match:
+ * they remain free to start a different task in the same session.
+ */
+export function isUncertainSendContinuation(value: unknown): boolean {
+  const text = folded(value);
+  if (!text) return false;
+  const switchesWork = /\b(?:new|different|separate|unrelated)\s+(?:request|task|work)\b/.test(text)
+    || /\b(?:task|yeu cau|cong viec|viec)\s+moi\b/.test(text);
+  if (switchesWork) return false;
+  const interrupted = /\b(?:connection|delivery|send|session)\b.{0,100}\b(?:interrupted|disconnected|dropped|lost|uncertain)\b/.test(text)
+    || /\bket noi\b.{0,100}\b(?:gian doan|bi ngat|bi mat)\b/.test(text);
+  const mayHaveArrived = /\b(?:previous|prior|last)\s+(?:send|message|request)\b.{0,100}\b(?:may|might|could)\s+have\s+been\s+(?:delivered|sent|received)\b/.test(text)
+    || /\b(?:delivery|send|receipt)\b.{0,100}\b(?:unknown|uncertain|unconfirmed)\b/.test(text)
+    || /\b(?:tin nhan|yeu cau|lan gui)\s+(?:truoc|vua roi)\b.{0,100}\bco the\b.{0,60}\b(?:da gui|da nhan|duoc gui)\b/.test(text);
+  const sameRequest = /\bcontinue\b.{0,100}\b(?:same|original|previous|prior)\s+(?:request|task|work)\b/.test(text)
+    || /\bdurable\s+session\s+state\b/.test(text)
+    || /\bwithout\s+duplicating\b/.test(text)
+    || /\btiep tuc\b.{0,100}\b(?:cung|yeu cau|task|cong viec)\b/.test(text)
+    || /\bkhong\s+(?:lap lai|trung lap)\b/.test(text);
+  return interrupted && mayHaveArrived && sameRequest;
+}
+
+function bounded(values: unknown, maximum = 8): string[] {
+  return [...new Set((Array.isArray(values) ? values : [])
+    .filter((value): value is string => typeof value === "string" && value.trim().length > 0)
+    .map((value) => value.trim()))]
+    .slice(0, maximum);
+}
+
+export type TerminalUncertainSendReceipt = {
+  customType: typeof UNCERTAIN_SEND_RECEIPT_TYPE;
+  content: string;
+  details: {
+    schemaVersion: 1;
+    version: typeof UNCERTAIN_SEND_RECEIPT_TYPE;
+    state: "settled";
+    taskId: string;
+    taskRunId: string;
+    outcome: TaskContract["trace"]["outcome"];
+    gateDecision: "pass" | "fail";
+    completionApproved: boolean;
+    diagnosticDelivery?: DiagnosticDelivery;
+    changedFiles: string[];
+    missing: string[];
+    nextSafeAction: string;
+    replayed: false;
+    modelTurnStarted: false;
+  };
+};
+
+export type TerminalUncertainSendBinding = {
+  task: TaskContract;
+  text: string;
+  receipt?: TerminalUncertainSendReceipt;
+};
+
+export type UncertainSendRuntimeIntake = {
+  intake: {
+    started: false;
+    text: string;
+    task?: TaskContract;
+    plannedContext: [];
+    plannedContextComplete: true;
+    continuation: "terminal-uncertain-send";
+  };
+  trace: Record<string, unknown>;
+  task?: TaskContract;
+};
+
+type HandoffReader = (cwd: string, taskRunId: string) => HandoffProjection | undefined;
+
+/**
+ * Project a privacy-safe terminal receipt from the immediately prior durable
+ * task. Missing/corrupt/mismatched handoff state returns undefined so callers
+ * can fail closed without claiming that delivery or completion was observed.
+ */
+export function terminalUncertainSendReceipt(
+  cwd: string,
+  task: TaskContract | undefined,
+  readHandoff: HandoffReader = readHandoffProjection
+): TerminalUncertainSendReceipt | undefined {
+  if (!task || task.trace.outcome === "pending") return undefined;
+  let handoff;
+  try {
+    handoff = readHandoff(cwd, task.taskRunId);
+  } catch {
+    return undefined;
+  }
+  if (!handoff
+    || !handoffIdentityMatchesTask(handoff.identity, task)
+    || handoff.state.taskOutcome !== task.trace.outcome) return undefined;
+  if (handoff.state.completionApproved === true || handoff.state.diagnosticDelivery) {
+    const authoritativeAcceptance = taskAcceptanceDisposition(task);
+    if (handoff.acceptance.required !== authoritativeAcceptance.required
+      || handoff.acceptance.satisfied !== authoritativeAcceptance.satisfied
+      || handoff.acceptance.criteriaCount !== authoritativeAcceptance.criteriaCount
+      || handoff.acceptance.dispositionDigest !== authoritativeAcceptance.dispositionDigest) return undefined;
+  }
+  const diagnosticDelivery = handoff.state.diagnosticDelivery;
+  if (diagnosticDelivery && !diagnosticDeliveryMatchesTask(diagnosticDelivery, task, taskAcceptanceDisposition(task).dispositionDigest)) return undefined;
+  if (diagnosticDelivery) {
+    try {
+      const current = captureWorkspaceVerificationSnapshot(cwd);
+      if (!current.proofCapable || current.digest !== handoff.tree.currentDigest
+        || current.workspaceRevisionDigest !== handoff.tree.workspaceRevisionDigest) return undefined;
+    } catch { return undefined; }
+  }
+  const changedFiles = bounded(handoff.changedFiles.current, 12);
+  const missing = bounded(handoff.state.missing, 12);
+  const approved = handoff.state.completionApproved === true;
+  const lines = [
+    "[Piagent delivery receipt]",
+    `The immediately preceding task already settled as ${handoff.state.taskOutcome}; its durable contract was reused and no command, mutation, message, or model turn was replayed.`,
+    `Completion approved: ${approved ? "yes" : "no"}. Gate: ${handoff.state.gateDecision}.`,
+    ...(diagnosticDelivery ? ["Diagnostic delivery only: unproved criteria remain pending; no quality claim."] : []),
+    ...(changedFiles.length > 0 ? [`Changed files: ${changedFiles.join(", ")}.`] : []),
+    ...(missing.length > 0 ? [`Still missing: ${missing.join("; ")}.`] : []),
+    `Next safe action: ${handoff.nextSafeAction.action}.`
+  ];
+  return {
+    customType: UNCERTAIN_SEND_RECEIPT_TYPE,
+    content: lines.join("\n"),
+    details: {
+      schemaVersion: 1,
+      version: UNCERTAIN_SEND_RECEIPT_TYPE,
+      state: "settled",
+      taskId: task.taskId,
+      taskRunId: task.taskRunId,
+      outcome: task.trace.outcome,
+      gateDecision: handoff.state.gateDecision,
+      completionApproved: approved,
+      ...(diagnosticDelivery ? { diagnosticDelivery } : {}),
+      changedFiles,
+      missing,
+      nextSafeAction: handoff.nextSafeAction.action,
+      replayed: false,
+      modelTurnStarted: false
+    }
+  };
+}
+
+export function unavailableUncertainSendContext(task?: TaskContract): string {
+  const identity = task
+    ? `durable task ${task.taskId} (${task.taskRunId})`
+    : "the immediately preceding durable task";
+  return [
+    "[Piagent uncertain-send continuation]",
+    `Reuse ${identity}; do not create a replacement task or repeat prior mutations/messages.`,
+    "Its terminal handoff receipt is missing, corrupt, or identity-mismatched, so completion must not be inferred.",
+    "Report that the durable receipt is unavailable and require state inspection or an explicit new request before any further mutation."
+  ].join("\n");
+}
+
+/**
+ * Bind a synthetic reconnect continuation to the terminal task already bound
+ * to this durable session. This decision is intentionally separate from
+ * generic task intake so a receipt recovery cannot become a new read-only
+ * task merely because the previous operation settled before the client saw it.
+ */
+export function terminalUncertainSendBinding(
+  cwd: string,
+  task: TaskContract | undefined,
+  prompt: unknown,
+  readHandoff: HandoffReader = readHandoffProjection
+): TerminalUncertainSendBinding | undefined {
+  if (!task || task.trace.outcome === "pending" || !isUncertainSendContinuation(prompt)) return undefined;
+  const receipt = terminalUncertainSendReceipt(cwd, task, readHandoff);
+  return {
+    task,
+    text: receipt
+      ? `${receipt.content}\nRecovery-turn rule: return only this durable receipt; do not call tools, repeat work, or start another task.`
+      : unavailableUncertainSendContext(task),
+    receipt
+  };
+}
+
+export function uncertainSendRuntimeIntake(
+  cwd: string,
+  task: TaskContract | undefined,
+  prompt: unknown,
+  sessionId: string
+): UncertainSendRuntimeIntake | undefined {
+  if (!isUncertainSendContinuation(prompt) || task?.trace.outcome === "pending") return undefined;
+  const binding = terminalUncertainSendBinding(cwd, task, prompt);
+  return {
+    intake: {
+      started: false,
+      task: binding?.task,
+      text: binding?.text ?? unavailableUncertainSendContext(),
+      plannedContext: [],
+      plannedContextComplete: true,
+      continuation: "terminal-uncertain-send"
+    },
+    trace: {
+      event: binding ? "uncertain_send_terminal_task_bound" : "uncertain_send_task_binding_unavailable",
+      taskId: binding?.task.taskId,
+      taskRunId: binding?.task.taskRunId,
+      sessionId,
+      receiptAvailable: Boolean(binding?.receipt),
+      replacementTaskStarted: false,
+      replayed: false,
+      modelTurnStarted: true
+    },
+    task: binding?.task
+  };
+}

package/packages/piagent-core/runtime/session/usage.ts

@@ -6,6 +6,7 @@ import {
   CONTEXT_WATCH_PERCENT,
   LONG_INPUT_CHARS
 } from "../runtime-limits.ts";
+import type { WorkflowId } from "../workflows/webui-workflow.ts";
 import { modelLabel } from "./message-signals.ts";
 
 export type UsageSnapshot = {
@@ -32,7 +33,7 @@ export type UsageSnapshot = {
 };
 
 export type ContextPreflight = {
-  workflow: string;
+  workflow: WorkflowId;
   inputChars: number;
   inputTokenEstimate: number;
   liveContext?: UsageSnapshot["contextUsage"];
@@ -107,7 +108,7 @@ function estimateTokensFromChars(chars: number): number {
   return Math.max(0, Math.ceil(chars / 4));
 }
 
-export function buildContextPreflight(snapshot: UsageSnapshot, workflow = "task", inputChars = 0): ContextPreflight {
+export function buildContextPreflight(snapshot: UsageSnapshot, workflow: WorkflowId = "task", inputChars = 0): ContextPreflight {
   const inputTokenEstimate = estimateTokensFromChars(inputChars);
   const live = snapshot.contextUsage;
   let projectedContext: ContextPreflight["projectedContext"];
@@ -151,7 +152,7 @@ export function buildContextPreflight(snapshot: UsageSnapshot, workflow = "task"
     commands: [
       "/task-preflight",
       "/task-preflight compact",
-      `/fresh ${workflow === "be-to-fe" ? "be-to-fe" : workflow === "scout" ? "scout" : "task"} <request>`,
+      `/fresh ${workflow} <request>`,
       "/usage",
       "/session"
     ]

package/packages/piagent-core/runtime/tools/apply-patch-tool.ts

@@ -162,9 +162,9 @@ function parseUpdateHunks(section: string[], repoPath: string): UpdateHunk[] {
       if (line[0] !== "-") newLines.push(line.slice(1));
       if (line[0] === "+" || line[0] === "-") changed = true;
     }
-    if (!bodyLines || !changed || oldLines.length === 0) {
-      fail("malformed-hunk", `Hunk must contain a change with stable old-side context: ${repoPath}`);
-    }
+    if (!bodyLines) fail("malformed-hunk", `Hunk body is empty: ${repoPath}. Put @@ on its own line, then add body lines prefixed by space, +, or -; no file was changed.`);
+    if (!changed) fail("malformed-hunk", `Hunk contains no change line: ${repoPath}. Include at least one + or - body line in addition to any exact unchanged context; no file was changed.`);
+    if (oldLines.length === 0) fail("malformed-hunk", `Hunk must contain a change and at least one exact old-side line: ${repoPath}. A plus-only Update File hunk is invalid; for an insertion or append, place an adjacent existing anchor line (prefixed by one space) before or after the new + lines according to the intended position. Keep @@ on its own line and put removed lines on separate - lines; no file was changed.`);
     hunks.push({ oldLines, newLines });
   }
   if (!hunkCount) fail("malformed-hunk", `Update contains no hunks: ${repoPath}`);
@@ -481,10 +481,10 @@ export function registerApplyPatchTool(
     name: "apply_patch",
     label: "Apply Patch",
     description: "Apply one validated OpenAI-style patch across multiple project files in a single guarded tool call.",
-    promptSnippet: "Use apply_patch for bounded multi-file Add File and Update File changes when exact old context is available.",
+    promptSnippet: "Prefer one coherent apply_patch call for a bounded source-and-test or other multi-file change only when exact old context for every target is available. Update hunks require an exact old-side anchor; plus-only insertions are invalid. Otherwise use one bounded writer per file.",
     promptGuidelines: [
-      "Wrap the patch in exact *** Begin Patch and *** End Patch delimiters.",
-      "Use each project-relative target once and include enough unchanged context for every update hunk to match exactly once."
+      "The patch value must contain only the raw patch: its first line is exactly *** Begin Patch, its last line is exactly *** End Patch, and no prose, JSON, code fence, or other content may appear before or after those delimiters. For each *** Update File hunk, put @@ on its own line. Put every old, new, or unchanged body line below it with a leading -, +, or space; never write @@ -old or @@ +new.",
+      "Use each project-relative target once. Every Update File hunk must include at least one exact old-side line prefixed by space or -; for append/insert, put an adjacent existing space-prefixed anchor before or after the + lines to preserve the intended position. Include enough context to match exactly once."
     ],
     parameters: Type.Object({ patch: Type.String({ minLength: 1, maxLength: MAX_PATCH_BYTES }) }, { additionalProperties: false }),
     executionMode: "sequential",

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

@@ -12,7 +12,7 @@ export type PhaseMutationInput = {
   verificationCarrier?: boolean;
 };
 
-const MANAGED_HOST_TOOL_ORDER = Object.freeze(["read", "grep", "find", "ls", "edit", "write", "apply_patch", "bash", "shell", "exec"]);
+const MANAGED_HOST_TOOL_ORDER = Object.freeze(["read", "grep", "find", "ls", "apply_patch", "edit", "write", "bash", "shell", "exec"]);
 
 function phaseHostToolName(toolName: string): string {
   return toolName === "shell" || toolName === "exec" ? "bash" : toolName;

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

@@ -10,6 +10,7 @@ export const PIAGENT_PRIMARY_TOOL_GROUP = Object.freeze({
   piagent_context: "intake",
   piagent_context_preflight: "intake",
   piagent_task_progress: "mutation",
+  piagent_wait: "retrieval",
   piagent_context_record: "recovery",
   piagent_verify_record: "verification",
   piagent_trace_record: "handoff",
@@ -49,7 +50,7 @@ export const PIAGENT_MUTATION_CAPABLE_TOOLS = new Set<string>([
   "piagent_profile_tech_context_record", "piagent_project_onboarding_record", "piagent_context_index_record", "piagent_memory_note"
 ]);
 export const PIAGENT_SEQUENTIAL_TOOLS = new Set<string>([
-  ...PIAGENT_MUTATION_CAPABLE_TOOLS, "piagent_source_checkout", "piagent_tools", "piagent_task_start", "piagent_task_progress", "piagent_context_record",
+  ...PIAGENT_MUTATION_CAPABLE_TOOLS, "piagent_wait", "piagent_source_checkout", "piagent_tools", "piagent_task_start", "piagent_task_progress", "piagent_context_record",
   "piagent_verify_record", "piagent_trace_record", "piagent_memory_citation_record"
 ]);
 
@@ -111,7 +112,7 @@ export function phaseToolPolicy(phase: TrajectoryPhase, changeMode: PhaseToolPol
   const readOnlySurface = changeMode === "read-only" || phase === "review";
   const modelVisiblePiagentTools = PIAGENT_TOOL_ORDER.filter((tool) => {
     const group = PIAGENT_PRIMARY_TOOL_GROUP[tool as keyof typeof PIAGENT_PRIMARY_TOOL_GROUP];
-    return PHASE_TOOL_ALLOW[phase].includes(tool)
+    return (PHASE_TOOL_ALLOW[phase].includes(tool) || tool === "piagent_wait" && primaryGroups.includes("retrieval"))
       && primaryGroups.includes(group)
       && !PIAGENT_OPERATOR_TOOLS.has(tool)
       && !PIAGENT_DIAGNOSTIC_TOOLS.has(tool)

package/packages/piagent-core/runtime/tools/session-wait.ts

@@ -0,0 +1,42 @@
+import { performance } from "node:perf_hooks";
+
+export const MAX_SESSION_WAIT_SECONDS = 3600;
+export const SESSION_WAIT_ENTRY = "piagent-session-wait-v1";
+
+export type WaitReceipt = {
+  outcome: "elapsed" | "interrupted";
+  elapsedMs: number;
+};
+
+/** One timer, no polling, provider dispatch, shell, or detached continuation. */
+export class SessionWaitRuntime {
+  private readonly active = new Map<string, () => void>();
+
+  interrupt(key: string): void { this.active.get(key)?.(); }
+
+  wait(key: string, seconds: number, signal?: AbortSignal): Promise<WaitReceipt> {
+    if (!Number.isInteger(seconds) || seconds < 1 || seconds > MAX_SESSION_WAIT_SECONDS) {
+      throw new Error(`Wait seconds must be an integer between 1 and ${MAX_SESSION_WAIT_SECONDS}.`);
+    }
+    if (this.active.has(key)) throw new Error("A wait is already active for this session.");
+    if (signal?.aborted) return Promise.resolve({ outcome: "interrupted", elapsedMs: 0 });
+    return new Promise((resolve) => {
+      const started = performance.now();
+      let settled = false;
+      const finish = (outcome: WaitReceipt["outcome"]) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", interrupt);
+        this.active.delete(key);
+        resolve({ outcome, elapsedMs: Math.max(0, Math.round(performance.now() - started)) });
+      };
+      const interrupt = () => finish("interrupted");
+      const timer = setTimeout(() => finish("elapsed"), seconds * 1000);
+      this.active.set(key, interrupt);
+      signal?.addEventListener("abort", interrupt, { once: true });
+      // Covers an abort observed between entry and listener registration.
+      if (signal?.aborted) interrupt();
+    });
+  }
+}

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

@@ -10,6 +10,7 @@ export const PIAGENT_TOOL_GROUPS = {
     "piagent_context_preflight"
   ],
   task: ["piagent_task_progress"],
+  waiting: ["piagent_wait"],
   recovery: [
     "piagent_context_record",
     "piagent_verify_record",
@@ -53,6 +54,10 @@ export type PiagentToolGroup = keyof typeof PIAGENT_TOOL_GROUPS;
 export const PIAGENT_TOOL_ORDER = Object.values(PIAGENT_TOOL_GROUPS).flat();
 export const PIAGENT_TOOL_NAMES = new Set<string>(PIAGENT_TOOL_ORDER);
 
+function waitingGroups(prompt: string): PiagentToolGroup[] {
+  return /\b(?:wait|poll|monitor|check back|follow up|follow-up)\b|(?:chờ|theo dõi|kiểm tra lại)/iu.test(prompt) ? ["waiting"] : [];
+}
+
 const SUPPORTED_GIT_REPOSITORY_URL = /(?:^|[\s("'\[])https?:\/\/(?:www\.)?(?:github\.com|gitlab\.com|bitbucket\.org)\/[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+(?:\.git)?(?:[\/?#][^\s)"'\]]*)?/i;
 const SUPPORTED_GIT_SSH_REFERENCE = /(?:^|[\s("'\[])git@(?:github\.com|gitlab\.com|bitbucket\.org):[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+(?:\.git)?(?:$|[\s)"'\]])/i;
 
@@ -71,6 +76,7 @@ export function toolGroupsForPrompt(prompt: string): PiagentToolGroup[] {
   }
 
   groups.add("intake");
+  for (const group of waitingGroups(prompt)) groups.add(group);
   if (signal.lane !== "tiny") groups.add("task");
   if (/\b(context (?:engine|index|search|diagnostic)|source checkout|vendor checkout)\b/.test(lower)) {
     groups.add("retrieval");
@@ -90,7 +96,8 @@ export function toolGroupsForPrompt(prompt: string): PiagentToolGroup[] {
 
 export function activeTaskToolGroups(task: TaskContract): PiagentToolGroup[] {
   const mode = runtimeLifecycleMode(task);
-  if (mode.startsWith("automatic")) return [];
-  if (mode.startsWith("assisted")) return ["task"];
-  return ["task", "recovery"];
+  const waiting = waitingGroups(task.operatorRequest ?? task.summary ?? "");
+  if (mode.startsWith("automatic")) return waiting;
+  if (mode.startsWith("assisted")) return ["task", ...waiting];
+  return ["task", "recovery", ...waiting];
 }