@piagent/platform 1.2.12 → 1.2.14

package/packages/piagent-core/runtime/input/chat-images.ts

@@ -0,0 +1,299 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { matchesAnyPath, matchesProtectedPath } from "../../extensions/policy-core.js";
+import { formatCount } from "../session/usage.ts";
+
+const IMAGE_EXTENSIONS = ["png", "jpg", "jpeg", "gif", "webp", "bmp"] as const;
+const MAX_CHAT_IMAGE_ATTACHMENTS = 4;
+const MAX_CHAT_IMAGE_BYTES = 8 * 1024 * 1024;
+
+export type ChatImageAttachmentResult = {
+  text: string;
+  images: Array<{ type: "image"; data: string; mimeType: string }>;
+  attached: Array<{ marker: string; path: string; mimeType: string; bytes: number }>;
+  skipped: Array<{ path: string; reason: string }>;
+};
+
+export type ChatImageAccessPolicy = {
+  roots: Array<{ path: string; source: string }>;
+  readProtectedPaths: string[];
+  filesystemRead?: string[];
+  enforceFilesystemRead: boolean;
+  onImageInspected?: (path: string) => void;
+};
+
+type ResolvedChatImage =
+  | { status: "ok"; absolutePath: string; bytes: Buffer; mimeType: string }
+  | { status: "error"; reason: string };
+
+function escapeRegExp(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function supportedImageMimeType(bytes: Buffer): string | undefined {
+  if (
+    bytes.length >= 24
+    && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
+    && bytes.readUInt32BE(8) === 13
+    && bytes.subarray(12, 16).toString("ascii") === "IHDR"
+    && bytes.readUInt32BE(16) > 0
+    && bytes.readUInt32BE(20) > 0
+  ) {
+    return "image/png";
+  }
+  if (
+    bytes.length >= 4
+    && bytes[0] === 0xff
+    && bytes[1] === 0xd8
+    && bytes[2] === 0xff
+    && bytes[bytes.length - 2] === 0xff
+    && bytes[bytes.length - 1] === 0xd9
+  ) {
+    return "image/jpeg";
+  }
+  if (bytes.length >= 10) {
+    const head = bytes.subarray(0, 6).toString("ascii");
+    if (
+      (head === "GIF87a" || head === "GIF89a")
+      && bytes.readUInt16LE(6) > 0
+      && bytes.readUInt16LE(8) > 0
+    ) {
+      return "image/gif";
+    }
+  }
+  if (
+    bytes.length >= 16
+    && bytes.subarray(0, 4).toString("ascii") === "RIFF"
+    && bytes.subarray(8, 12).toString("ascii") === "WEBP"
+    && ["VP8 ", "VP8L", "VP8X"].includes(bytes.subarray(12, 16).toString("ascii"))
+    && bytes.readUInt32LE(4) + 8 <= bytes.length
+  ) {
+    return "image/webp";
+  }
+  if (
+    bytes.length >= 26
+    && bytes[0] === 0x42
+    && bytes[1] === 0x4d
+    && bytes.readUInt32LE(2) <= bytes.length
+    && bytes.readUInt32LE(14) >= 12
+  ) {
+    return "image/bmp";
+  }
+  return undefined;
+}
+
+function normalizeImagePathCandidate(candidate: string, cwd: string, options: { allowBareRelative?: boolean } = {}): string | undefined {
+  let raw = candidate.trim().replace(/^['"`<]+|['"`>,.;:!?]+$/g, "");
+  if (!raw) return undefined;
+  const allowBareRelative = options.allowBareRelative !== false;
+  const hasExplicitPathPrefix = raw.startsWith("file://") || raw.startsWith("~/") || path.isAbsolute(raw) || raw.startsWith("./") || raw.startsWith("../");
+  if (!allowBareRelative && !hasExplicitPathPrefix) return undefined;
+  try {
+    if (raw.startsWith("file://")) raw = fileURLToPath(raw);
+  } catch {
+    return undefined;
+  }
+  if (raw.startsWith("~/")) {
+    const home = process.env.HOME;
+    if (!home) return undefined;
+    raw = path.join(home, raw.slice(2));
+  }
+  const ext = path.extname(raw).toLowerCase().replace(/^\./, "");
+  if (!IMAGE_EXTENSIONS.includes(ext as typeof IMAGE_EXTENSIONS[number])) return undefined;
+  return path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
+}
+
+function extractLocalImagePathCandidates(text: string, cwd: string): string[] {
+  const candidates = new Set<string>();
+  const imageExt = "(?:png|jpe?g|gif|webp|bmp)";
+  const wholeTextPath = normalizeImagePathCandidate(text, cwd, { allowBareRelative: false });
+  if (wholeTextPath) candidates.add(wholeTextPath);
+
+  const quoted = new RegExp(`(?:path=)?["']([^"']+\\.${imageExt})["']`, "gi");
+  for (const match of text.matchAll(quoted)) {
+    const normalized = normalizeImagePathCandidate(match[1], cwd);
+    if (normalized) candidates.add(normalized);
+  }
+
+  const fileUrl = new RegExp(`file://[^\\s"'<>]+\\.${imageExt}`, "gi");
+  for (const match of text.matchAll(fileUrl)) {
+    const normalized = normalizeImagePathCandidate(match[0], cwd);
+    if (normalized) candidates.add(normalized);
+  }
+
+  const linePathPattern = '\\s((?:/|~\\/|\\.\\.?/)[^\\n\\r"\\\'<>]*?\\.' + imageExt + ')(?=$|\\s|["\\\'`)>])';
+  const linePath = new RegExp(linePathPattern, "gi");
+  for (const match of text.matchAll(linePath)) {
+    const normalized = normalizeImagePathCandidate(match[1], cwd);
+    if (normalized) candidates.add(normalized);
+  }
+
+  return [...candidates];
+}
+
+function pathContainedBy(root: string, candidate: string): boolean {
+  if (candidate === root) return true;
+  const relative = path.relative(root, candidate);
+  return relative.length > 0
+    && relative !== ".."
+    && !relative.startsWith(`..${path.sep}`)
+    && !path.isAbsolute(relative);
+}
+
+export function readChatImage(
+  requestedPath: string,
+  cwd: string,
+  access: ChatImageAccessPolicy
+): ResolvedChatImage {
+  const lexicalRequestedPath = path.isAbsolute(requestedPath)
+    ? path.normalize(requestedPath)
+    : path.resolve(cwd, requestedPath);
+  const lexicalProjectRoot = path.resolve(cwd);
+  const requestedProjectLexicalRelative = pathContainedBy(lexicalProjectRoot, lexicalRequestedPath)
+    ? path.relative(lexicalProjectRoot, lexicalRequestedPath).split(path.sep).join("/") || "."
+    : undefined;
+  let canonicalPath: string;
+  let inspected: fs.Stats;
+  try {
+    canonicalPath = fs.realpathSync.native(requestedPath);
+    inspected = fs.statSync(canonicalPath);
+  } catch {
+    return { status: "error", reason: "file does not exist or cannot be inspected" };
+  }
+  if (!inspected.isFile()) return { status: "error", reason: "not a regular file" };
+  if (inspected.size <= 0) return { status: "error", reason: "empty file" };
+  if (inspected.size > MAX_CHAT_IMAGE_BYTES) {
+    return {
+      status: "error",
+      reason: `image is ${formatCount(inspected.size)} bytes > ${formatCount(MAX_CHAT_IMAGE_BYTES)} byte limit`
+    };
+  }
+
+  const root = access.roots.find((candidate) => pathContainedBy(candidate.path, canonicalPath));
+  if (!root) return { status: "error", reason: "outside the project and every granted additionalReadRoots directory" };
+
+  const rootRelative = path.relative(root.path, canonicalPath).split(path.sep).join("/") || ".";
+  const projectRoot = access.roots.find((candidate) => candidate.source === "project");
+  let canonicalRequestedLocation = requestedPath;
+  try {
+    canonicalRequestedLocation = path.join(
+      fs.realpathSync.native(path.dirname(requestedPath)),
+      path.basename(requestedPath)
+    );
+  } catch {
+    // The target already resolved. This form only preserves the final symlink's policy position.
+  }
+  const requestedProjectRelative = projectRoot && pathContainedBy(projectRoot.path, canonicalRequestedLocation)
+    ? path.relative(projectRoot.path, canonicalRequestedLocation).split(path.sep).join("/") || "."
+    : undefined;
+  const protectedMatch = matchesProtectedPath(canonicalPath, access.readProtectedPaths)
+    ?? matchesProtectedPath(rootRelative, access.readProtectedPaths)
+    ?? matchesProtectedPath(canonicalRequestedLocation, access.readProtectedPaths)
+    ?? matchesProtectedPath(requestedPath, access.readProtectedPaths)
+    ?? (requestedProjectLexicalRelative
+      ? matchesProtectedPath(requestedProjectLexicalRelative, access.readProtectedPaths)
+      : undefined)
+    ?? (requestedProjectRelative ? matchesProtectedPath(requestedProjectRelative, access.readProtectedPaths) : undefined);
+  if (protectedMatch) return { status: "error", reason: `matches protected path ${protectedMatch}` };
+
+  if (
+    root.source === "project"
+    && access.enforceFilesystemRead
+    && access.filesystemRead
+    && !matchesAnyPath(rootRelative, access.filesystemRead)
+  ) {
+    return {
+      status: "error",
+      reason: `outside the resolved filesystem read scope (${access.filesystemRead.join(", ")})`
+    };
+  }
+
+  access.onImageInspected?.(canonicalPath);
+  const openFlags = fs.constants.O_RDONLY | fs.constants.O_NONBLOCK | fs.constants.O_NOFOLLOW;
+  let fd: number;
+  try {
+    fd = fs.openSync(canonicalPath, openFlags);
+  } catch {
+    return { status: "error", reason: "file changed before it could be opened" };
+  }
+  try {
+    const opened = fs.fstatSync(fd);
+    if (
+      !opened.isFile()
+      || opened.dev !== inspected.dev
+      || opened.ino !== inspected.ino
+      || opened.size !== inspected.size
+    ) {
+      return { status: "error", reason: "file changed between the safety checks and the read" };
+    }
+    const bytes = Buffer.alloc(opened.size);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const read = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+      if (read <= 0) break;
+      offset += read;
+    }
+    if (offset !== bytes.length) return { status: "error", reason: "file changed while it was being read" };
+    const mimeType = supportedImageMimeType(bytes);
+    if (!mimeType) return { status: "error", reason: "file bytes are not a supported image" };
+    return { status: "ok", absolutePath: canonicalPath, bytes, mimeType };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+export function attachLocalImagesFromText(
+  text: string,
+  existingImages: unknown[] | undefined,
+  cwd: string,
+  resolveAccess: () => ChatImageAccessPolicy
+): ChatImageAttachmentResult | undefined {
+  const imagePaths = extractLocalImagePathCandidates(text, cwd);
+  if (imagePaths.length === 0) return undefined;
+  const access = resolveAccess();
+
+  const existing = Array.isArray(existingImages) ? existingImages : [];
+  const images: ChatImageAttachmentResult["images"] = [];
+  const attached: ChatImageAttachmentResult["attached"] = [];
+  const skipped: ChatImageAttachmentResult["skipped"] = [];
+  let nextText = text;
+
+  for (const imagePath of imagePaths) {
+    if (images.length + existing.length >= MAX_CHAT_IMAGE_ATTACHMENTS) {
+      skipped.push({ path: imagePath, reason: `attachment limit ${MAX_CHAT_IMAGE_ATTACHMENTS} reached` });
+      continue;
+    }
+    try {
+      const resolved = readChatImage(imagePath, cwd, access);
+      if (resolved.status === "error") {
+        skipped.push({ path: imagePath, reason: resolved.reason });
+        continue;
+      }
+      const marker = `[image${existing.length + images.length + 1}]`;
+      images.push({ type: "image", mimeType: resolved.mimeType, data: resolved.bytes.toString("base64") });
+      attached.push({ marker, path: imagePath, mimeType: resolved.mimeType, bytes: resolved.bytes.length });
+      nextText = nextText.replace(new RegExp(escapeRegExp(imagePath), "g"), marker);
+      nextText = nextText.replace(new RegExp(escapeRegExp(`file://${imagePath}`), "g"), marker);
+    } catch (error) {
+      skipped.push({ path: imagePath, reason: error instanceof Error ? error.message : String(error) });
+    }
+  }
+
+  if (attached.length === 0) {
+    return skipped.length > 0 ? { text, images: [], attached, skipped } : undefined;
+  }
+
+  const attachmentLines = attached.map((item) => `- ${item.marker}: ${path.basename(item.path)} (${item.mimeType}, ${formatCount(item.bytes)} bytes)`);
+  const skippedLines = skipped.map((item) => `- skipped ${path.basename(item.path)}: ${item.reason}`);
+  nextText = [
+    nextText.trim(),
+    "",
+    "Attached local image(s):",
+    ...attachmentLines,
+    ...(skippedLines.length > 0 ? ["", "Skipped local image path(s):", ...skippedLines] : [])
+  ].join("\n").trim();
+
+  return { text: nextText, images, attached, skipped };
+}

package/packages/piagent-core/runtime/runtime-limits.ts

@@ -0,0 +1,21 @@
+// Runtime limits live outside the Pi extension entrypoint so every feature
+// reads the same operational policy instead of carrying a private copy.
+
+export const CONTEXT_WATCH_PERCENT = 50;
+export const CONTEXT_COMPACT_PERCENT = 70;
+export const CONTEXT_FRESH_PERCENT = 82;
+export const LONG_INPUT_CHARS = 8000;
+export const MAX_INLINE_COLLAPSED_TASK_CHARS = 2200;
+
+export const TOOL_RESULT_COMPACT_CHAR_THRESHOLD = 12_000;
+export const TOOL_RESULT_COMPACT_LINE_THRESHOLD = 180;
+export const TOOL_RESULT_PREVIEW_HEAD_LINES = 24;
+export const TOOL_RESULT_PREVIEW_TAIL_LINES = 24;
+export const TOOL_RESULT_PREVIEW_INTERESTING_LINES = 24;
+export const TOOL_RESULT_PREVIEW_MAX_CHARS = 6_000;
+export const TOOL_RESULT_CAPTURE_MAX_CHARS = 500_000;
+
+export const CAPTURE_INDEX_MAX_BYTES = 4 * 1024 * 1024;
+export const CAPTURE_RETENTION_MAX_BYTES = 128 * 1024 * 1024;
+export const CAPTURE_RETENTION_MAX_FILES = 500;
+export const CAPTURE_RETENTION_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;

package/packages/piagent-core/runtime/session/message-signals.ts

@@ -0,0 +1,64 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export function assistantMessageText(message: unknown): string {
+  if (!message || typeof message !== "object" || (message as { role?: unknown }).role !== "assistant") return "";
+  const content = (message as { content?: unknown }).content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((item): item is { type: "text"; text: string } => Boolean(item && typeof item === "object" && (item as { type?: unknown }).type === "text" && typeof (item as { text?: unknown }).text === "string"))
+    .map((item) => item.text)
+    .join("\n");
+}
+
+export function assistantMessageHasToolCall(message: unknown): boolean {
+  const content = message && typeof message === "object" ? (message as { content?: unknown }).content : undefined;
+  return Array.isArray(content) && content.some((item) => item && typeof item === "object" && (item as { type?: unknown }).type === "toolCall");
+}
+
+function normalizeLanguageSignal(text: string): string {
+  return text
+    .normalize("NFKD")
+    .replace(/\p{M}/gu, "")
+    .toLowerCase()
+    .replaceAll("đ", "d");
+}
+
+export function looksLikeIncompleteHandoff(text: string): boolean {
+  const normalized = normalizeLanguageSignal(text);
+  return /\b(?:not done|not complete|not finished|still working|blocked|cannot complete|unable to complete|need clarification|tests? (?:fail|failed|failing)|verification (?:fail|failed|failing)|chua xong|chua hoan tat|chua hoan thanh|dang lam|bi chan|can lam them|test (?:loi|fail))\b/.test(normalized);
+}
+
+export function looksLikeCompletionClaim(text: string): boolean {
+  const normalized = normalizeLanguageSignal(text);
+  if (!normalized.trim() || normalized.includes("[piagent completion gate:")) return false;
+  if (looksLikeIncompleteHandoff(text)) return false;
+  return /\b(?:done|completed|complete|finished|fixed|implemented|resolved|shipped|all tests pass(?:ed)?|tests? pass(?:ed)?|da xong|da sua|da fix|da hoan tat|da hoan thanh|da trien khai|test da pass|kiem tra da pass)\b/.test(normalized);
+}
+
+export function modelLabel(ctx: ExtensionContext): string {
+  const model = ctx.model as { provider?: string; id?: string; name?: string } | undefined;
+  if (!model) return "none";
+  if (model.provider && model.id) return `${model.provider}/${model.id}`;
+  return model.name ?? model.id ?? "unknown";
+}
+
+export function currentSessionName(ctx: ExtensionContext): string {
+  try {
+    return String(ctx.sessionManager.getSessionName() ?? "").trim();
+  } catch {
+    return "";
+  }
+}
+
+export function hasOperatorSessionName(name: string): boolean {
+  const normalized = name.trim().toLowerCase();
+  return Boolean(normalized && normalized !== "session");
+}
+
+export function cleanSessionNameInput(input: string): string {
+  let name = input.trim();
+  if ((name.startsWith("\"") && name.endsWith("\"")) || (name.startsWith("'") && name.endsWith("'"))) {
+    name = name.slice(1, -1).trim();
+  }
+  return name;
+}

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

@@ -0,0 +1,175 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { toolResultFingerprint } from "../../extensions/context-engine.js";
+import { workingTreeSnapshot } from "../../extensions/task-state.js";
+import type { TaskContract } from "../../extensions/guard-types.ts";
+
+export type ObservedTaskContext = { path: string; reason: string };
+
+export type InjectedContextPack = {
+  queryHash: string;
+  confidence: string;
+  estimatedTokens: number;
+  paths: string[];
+};
+
+function evictOldest<K, V>(map: Map<K, V>, maximum: number): void {
+  while (map.size > maximum) map.delete(map.keys().next().value as K);
+}
+
+export class RuntimeSessionState {
+  readonly #maxObservedContext: number;
+  readonly #advisedTools = new Set<string>();
+  readonly #seenToolResults = new Map<string, { outputHash: string; recordedAt: string }>();
+  readonly #autoPackedPrompts = new Set<string>();
+  readonly #injectedContextPacks = new Map<string, InjectedContextPack>();
+  readonly #completionRecoveryAttempts = new Map<string, number>();
+  readonly #taskIdentityBySession = new Map<string, { taskId: string; taskRunId: string }>();
+  readonly #observedContextBySession = new Map<string, Map<string, ObservedTaskContext>>();
+  readonly #shellMutationSnapshots = new Map<string, Record<string, string>>();
+
+  constructor(options: { maxObservedContext: number }) {
+    this.#maxObservedContext = options.maxObservedContext;
+  }
+
+  sessionKey(ctx: ExtensionContext): string {
+    return `${ctx.cwd}\u0000${ctx.sessionManager.getSessionId()}`;
+  }
+
+  cacheTaskIdentity(ctx: ExtensionContext, task: TaskContract | undefined): void {
+    const key = this.sessionKey(ctx);
+    if (task) this.#taskIdentityBySession.set(key, { taskId: task.taskId, taskRunId: task.taskRunId });
+    else this.#taskIdentityBySession.delete(key);
+    evictOldest(this.#taskIdentityBySession, 100);
+  }
+
+  taskIdentity(ctx: ExtensionContext): { taskId: string; taskRunId: string } | undefined {
+    return this.#taskIdentityBySession.get(this.sessionKey(ctx));
+  }
+
+  hasAdvisedTool(ctx: ExtensionContext, toolName: string): boolean {
+    return this.#advisedTools.has(`${this.sessionKey(ctx)}\u0000${toolName}`);
+  }
+
+  rememberAdvisedTool(ctx: ExtensionContext, toolName: string): void {
+    this.#advisedTools.add(`${this.sessionKey(ctx)}\u0000${toolName}`);
+    while (this.#advisedTools.size > 500) {
+      this.#advisedTools.delete(this.#advisedTools.values().next().value as string);
+    }
+  }
+
+  rememberObservedContext(ctx: ExtensionContext, entry: ObservedTaskContext): void {
+    const key = this.sessionKey(ctx);
+    let observed = this.#observedContextBySession.get(key);
+    if (!observed) {
+      observed = new Map();
+      this.#observedContextBySession.set(key, observed);
+    }
+    if (!observed.has(entry.path)) observed.set(entry.path, entry);
+    evictOldest(observed, this.#maxObservedContext);
+    evictOldest(this.#observedContextBySession, 100);
+  }
+
+  observedContext(ctx: ExtensionContext): ObservedTaskContext[] {
+    return [...(this.#observedContextBySession.get(this.sessionKey(ctx))?.values() ?? [])];
+  }
+
+  clearObservedContext(ctx: ExtensionContext): void {
+    this.#observedContextBySession.delete(this.sessionKey(ctx));
+  }
+
+  #shellMutationSnapshotKey(ctx: ExtensionContext, toolName: string, input: unknown): string {
+    return `${this.sessionKey(ctx)}\u0000${toolResultFingerprint(toolName, input, []).key}`;
+  }
+
+  rememberShellMutationSnapshot(ctx: ExtensionContext, toolName: string, input: unknown): void {
+    this.#shellMutationSnapshots.set(
+      this.#shellMutationSnapshotKey(ctx, toolName, input),
+      workingTreeSnapshot(ctx.cwd) as Record<string, string>
+    );
+    evictOldest(this.#shellMutationSnapshots, 100);
+  }
+
+  consumeShellMutationSnapshot(ctx: ExtensionContext, toolName: string, input: unknown): Record<string, string> | undefined {
+    const key = this.#shellMutationSnapshotKey(ctx, toolName, input);
+    const snapshot = this.#shellMutationSnapshots.get(key);
+    this.#shellMutationSnapshots.delete(key);
+    return snapshot;
+  }
+
+  clearShellMutationSnapshots(ctx: ExtensionContext): void {
+    const prefix = `${this.sessionKey(ctx)}\u0000`;
+    for (const key of this.#shellMutationSnapshots.keys()) {
+      if (key.startsWith(prefix)) this.#shellMutationSnapshots.delete(key);
+    }
+  }
+
+  hasAutoPackedPrompt(key: string): boolean {
+    return this.#autoPackedPrompts.has(key);
+  }
+
+  rememberAutoPackedPrompt(key: string): void {
+    this.#autoPackedPrompts.add(key);
+    while (this.#autoPackedPrompts.size > 50) {
+      this.#autoPackedPrompts.delete(this.#autoPackedPrompts.values().next().value as string);
+    }
+  }
+
+  rememberInjectedContextPack(ctx: ExtensionContext, key: string, pack: InjectedContextPack): void {
+    this.#injectedContextPacks.set(`${this.sessionKey(ctx)}\u0000${key}`, pack);
+    evictOldest(this.#injectedContextPacks, 50);
+  }
+
+  injectedContextPack(ctx: ExtensionContext, key: string): InjectedContextPack | undefined {
+    return this.#injectedContextPacks.get(`${this.sessionKey(ctx)}\u0000${key}`);
+  }
+
+  completionRecoveryAttempt(taskRunId: string): number {
+    return this.#completionRecoveryAttempts.get(taskRunId) ?? 0;
+  }
+
+  rememberCompletionRecoveryAttempt(taskRunId: string, attempt: number): void {
+    this.#completionRecoveryAttempts.set(taskRunId, attempt);
+    evictOldest(this.#completionRecoveryAttempts, 100);
+  }
+
+  clearCompletionRecoveryAttempt(taskRunId: string): void {
+    this.#completionRecoveryAttempts.delete(taskRunId);
+  }
+
+  previousToolResult(
+    ctx: ExtensionContext,
+    fingerprintKey: string
+  ): { outputHash: string; recordedAt: string } | undefined {
+    return this.#seenToolResults.get(`${this.sessionKey(ctx)}\u0000${fingerprintKey}`);
+  }
+
+  rememberToolResult(
+    ctx: ExtensionContext,
+    fingerprintKey: string,
+    value: { outputHash: string; recordedAt: string }
+  ): void {
+    this.#seenToolResults.set(`${this.sessionKey(ctx)}\u0000${fingerprintKey}`, value);
+    evictOldest(this.#seenToolResults, 500);
+  }
+
+  clearSession(ctx: ExtensionContext): void {
+    const sessionKey = this.sessionKey(ctx);
+    const prefix = `${sessionKey}\u0000`;
+    const taskIdentity = this.#taskIdentityBySession.get(sessionKey);
+    this.#taskIdentityBySession.delete(sessionKey);
+    this.#observedContextBySession.delete(sessionKey);
+    this.clearShellMutationSnapshots(ctx);
+    if (taskIdentity) this.#completionRecoveryAttempts.delete(taskIdentity.taskRunId);
+    for (const values of [this.#advisedTools, this.#autoPackedPrompts]) {
+      for (const key of values) {
+        if (key.startsWith(prefix)) values.delete(key);
+      }
+    }
+    for (const values of [this.#seenToolResults, this.#injectedContextPacks]) {
+      for (const key of values.keys()) {
+        if (key.startsWith(prefix)) values.delete(key);
+      }
+    }
+  }
+}

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

@@ -0,0 +1,52 @@
+const LEGACY_PROJECT_INSTRUCTIONS_START = "Before implementation:\n\n1. Load `.pi/piagent-profile.json` with `piagent_context`.";
+const LEGACY_PROJECT_INSTRUCTIONS_END = "18. If the bundled `pi-subagents` parent skill is available, use it for delegation patterns, review loops, native supervisor coordination, and safety boundaries.";
+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 broad, high-risk, or ambiguous scope, call `piagent_task_start` exactly once with project-relative path/glob scope; reuse an active contract.",
+  "3. Read the narrow target and nearest relevant test, then use ordinary read/edit/bash tools.",
+  "4. Run every exact runtime-provided verifier after the latest mutation. Automatic tasks need no management calls.",
+  "5. Runtime hooks enforce policy 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");
+
+export function rewriteLegacyProjectInstructions(systemPrompt: string): {
+  systemPrompt: string;
+  rewritten: boolean;
+} {
+  const start = systemPrompt.indexOf(LEGACY_PROJECT_INSTRUCTIONS_START);
+  if (start < 0) return { systemPrompt, rewritten: false };
+  const endStart = systemPrompt.indexOf(LEGACY_PROJECT_INSTRUCTIONS_END, start);
+  if (endStart < 0) return { systemPrompt, rewritten: false };
+  const end = endStart + LEGACY_PROJECT_INSTRUCTIONS_END.length;
+  return {
+    systemPrompt: `${systemPrompt.slice(0, start)}${RUNTIME_MANAGED_PROJECT_INSTRUCTIONS}${systemPrompt.slice(end)}`,
+    rewritten: true
+  };
+}
+
+export function compactManagedProjectInstructions(
+  systemPrompt: string,
+  mode: "automatic" | "protected"
+): { 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. Use task-relevant source/tests and ordinary tools, run the exact verifier after final edits, and make no task-management calls.";
+  const markerStart = "<!-- piagent-managed:start -->";
+  const markerEnd = "<!-- piagent-managed:end -->";
+  const start = systemPrompt.indexOf(markerStart);
+  const endStart = start >= 0 ? systemPrompt.indexOf(markerEnd, start) : -1;
+  if (start >= 0 && endStart >= 0) {
+    const end = endStart + markerEnd.length;
+    return {
+      systemPrompt: `${systemPrompt.slice(0, start)}${markerStart}\n${concise}\n${markerEnd}${systemPrompt.slice(end)}`,
+      compacted: true
+    };
+  }
+  if (systemPrompt.includes(RUNTIME_MANAGED_PROJECT_INSTRUCTIONS)) {
+    return {
+      systemPrompt: systemPrompt.replace(RUNTIME_MANAGED_PROJECT_INSTRUCTIONS, concise),
+      compacted: true
+    };
+  }
+  return { systemPrompt, compacted: false };
+}