@piagent/platform 1.37.1 → 1.38.1

package/packages/piagent-core/extensions/path-suggestions.ts

@@ -0,0 +1,137 @@
+import { inspectWorkspaceEntry } from "../security/workspace-file-reader.ts";
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// What an @ in the composer offers, as Pi's terminal does: files and folders
+// of the project matched loosely by name (fd, which honours .gitignore), and,
+// after a folder and a slash (src/, ~/Documents/, /Volumes/), the names under
+// that folder anywhere on this Mac. Only names reach the browser; no file is
+// opened.
+export type PathSuggestion = { value: string; label: string; detail: string; kind: "file" | "directory" };
+type Entry = { path: string; directory: boolean };
+
+const LIMIT = 20;
+const SEARCH_RESULTS = 100;
+const LISTED_ENTRIES = 5_000;
+// Outside the project a search stays shallow and skips app data and
+// dependency folders: a home folder is far larger than a repository.
+const OUTSIDE_DEPTH = 4;
+const fold = (value: string) => value.normalize("NFC").toLowerCase();
+const escape = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+// A name typed composed (Dự án) may be stored decomposed on disk: either form matches.
+const either = (value: string) => value.normalize("NFC") === value.normalize("NFD") ? escape(value)
+  : `(?:${escape(value.normalize("NFC"))}|${escape(value.normalize("NFD"))})`;
+const inside = (file: string, root: string) => file === root || file.startsWith(root + path.sep);
+
+// fd where it is commonly installed, then on PATH (Debian and Ubuntu name it
+// fdfind; Windows adds .exe).
+export function findFd(home = os.homedir()): string | null {
+  const names = process.platform === "win32" ? ["fd.exe"] : ["fd", "fdfind"];
+  const onPath = String(process.env.PATH ?? "").split(path.delimiter).filter(Boolean).flatMap((dir) => names.map((name) => path.join(dir, name)));
+  for (const candidate of ["/opt/homebrew/bin/fd", "/usr/local/bin/fd", path.join(home, ".pi/agent/bin", names[0]), ...onPath]) {
+    try { fs.accessSync(candidate, fs.constants.X_OK); return candidate; } catch { /* next */ }
+  }
+  return null;
+}
+// macOS: the system's git, always there; elsewhere git from PATH.
+const GIT = process.platform === "darwin" ? "/usr/bin/git" : "git";
+
+// Higher is better: the name itself, then its start, then anywhere in it,
+// then anywhere in the path; a folder before a file with the same score.
+function score(entry: string, query: string, directory: boolean): number {
+  const name = fold(path.basename(entry)), wanted = fold(query);
+  const value = name === wanted ? 100 : name.startsWith(wanted) ? 80 : name.includes(wanted) ? 50 : fold(entry).includes(wanted) ? 30 : 0;
+  return value && directory ? value + 10 : value;
+}
+
+function run(file: string, args: string[], signal?: AbortSignal, input?: string): Promise<string> {
+  return new Promise((resolve) => {
+    const child = execFile(file, args, { encoding: "utf8", timeout: 4_000, maxBuffer: 8 << 20, signal }, (error, stdout) => resolve(error ? "" : stdout));
+    child.stdin?.on("error", () => {}); child.stdin?.end(input ?? "");
+  });
+}
+
+// The folder's own names, without what its repository ignores (dist/,
+// node_modules/), as fd lists them for Pi.
+async function listed(folder: string, signal?: AbortSignal, projectOnly = false): Promise<Entry[]> {
+  const entries: Entry[] = [];
+  try {
+    for await (const entry of await fs.promises.opendir(folder)) {
+      let directory = entry.isDirectory();
+      if (entry.isSymbolicLink() && projectOnly) continue;
+      if (entry.isSymbolicLink()) try { directory = fs.statSync(path.join(folder, entry.name)).isDirectory(); } catch { /* broken link */ }
+      entries.push({ path: entry.name, directory });
+      if (entries.length >= LISTED_ENTRIES) break;
+    }
+  } catch { /* unreadable */ }
+  if (!entries.length) return entries;
+  const ignored = new Set((await run(GIT, ["-C", folder, "check-ignore", "-z", "--stdin"], signal, entries.map((entry) => `${entry.path}\0`).join("")))
+    .split("\0").filter(Boolean));
+  return ignored.size ? entries.filter((entry) => !ignored.has(entry.path)) : entries;
+}
+
+// Names deeper down that match: fd as Pi runs it in the project; shallow and
+// without hidden folders elsewhere; without fd, the files git knows about.
+async function searched(folder: string, query: string, options: { fd: string | null; project: boolean; atRoot: boolean; projectOnly?: boolean; signal?: AbortSignal }): Promise<Entry[]> {
+  if (options.fd) {
+    const args = ["--base-directory", folder, "--type", "f", "--type", "d", "--max-results", String(SEARCH_RESULTS), "--ignore-case", "--exclude", ".git",
+      ...(options.project ? [...(options.projectOnly ? [] : ["--follow"]), "--hidden"] : ["--max-depth", String(OUTSIDE_DEPTH), "--exclude", "Library", "--exclude", "node_modules", ...(query.startsWith(".") ? ["--hidden"] : [])]),
+      ...(query.includes("/") ? ["--full-path", query.split("/").filter(Boolean).map(either).join("/")] : [either(query)])];
+    return (await run(options.fd, args, options.signal)).split("\n").filter(Boolean)
+      .map((line) => ({ path: line.replace(/^\.\//, "").replace(/\/$/, ""), directory: line.endsWith("/") }));
+  }
+  if (!options.atRoot) return [];
+  const files = (await run(GIT, ["-C", folder, "ls-files", "--cached", "--others", "--exclude-standard", "-z"], options.signal))
+    .split("\0").filter(Boolean).slice(0, 50_000);
+  const folders = new Set<string>();
+  for (const file of files) for (let dir = path.posix.dirname(file); dir !== "."; dir = path.posix.dirname(dir)) folders.add(dir);
+  const wanted = fold(query);
+  return [...[...folders].map((dir) => ({ path: dir, directory: true })), ...files.map((file) => ({ path: file, directory: false }))]
+    .filter((entry) => fold(entry.path).includes(wanted));
+}
+
+export async function suggestPaths(options: { root: string; query: string; home?: string; fd?: string | null; projectOnly?: boolean; isAllowed?: (path: string) => boolean; signal?: AbortSignal }): Promise<{ suggestions: PathSuggestion[] }> {
+  const home = options.home ?? os.homedir(), fd = options.fd === undefined ? findFd(home) : options.fd;
+  const root = fs.realpathSync(options.root);
+  const typed = options.query.trim() === "~" ? "~/" : options.query.trim();
+  // Text up to the last slash names a folder: search under it (Pi's scoped
+  // search). When it is not a folder, the whole text is matched in the project.
+  if (options.projectOnly && (path.isAbsolute(typed) || typed.startsWith("~") || /[\\\x00-\x1f]/.test(typed)
+    || typed.split("/").includes(".."))) return { suggestions: [] };
+  const cut = typed.lastIndexOf("/") + 1;
+  let base = typed.slice(0, cut), name = typed.slice(cut), folder = root;
+  if (base) {
+    try {
+      const candidate = fs.realpathSync(base.startsWith("~/") ? path.join(home, base.slice(2)) : path.resolve(root, base));
+      if (fs.statSync(candidate).isDirectory()) folder = candidate; else { base = ""; name = typed; }
+    } catch { base = ""; name = typed; }
+  }
+  const project = inside(folder, root);
+  if (options.projectOnly && (!inside(folder, root) || (base && (() => {
+    try { return inspectWorkspaceEntry(root, base.replace(/\/$/, "")).isSymbolicLink(); } catch { return true; }
+  })()))) return { suggestions: [] };
+  const near = await listed(folder, options.signal, options.projectOnly);
+  const deep = name ? await searched(folder, name, { fd, project, atRoot: folder === root, projectOnly: options.projectOnly, signal: options.signal }) : [];
+  const seen = new Set<string>(), entries: Array<Entry & { score: number }> = [];
+  for (const entry of [...near, ...deep]) {
+    if (options.projectOnly) {
+      try {
+        const relative = `${base}${entry.path}`;
+        if (inspectWorkspaceEntry(root, relative).isSymbolicLink() || options.isAllowed && !options.isAllowed(relative)) continue;
+      } catch { continue; }
+    }
+    if (seen.has(entry.path)) continue; seen.add(entry.path);
+    // Hidden entries (.github, .ssh, .zshrc) for a name typed with a dot, and
+    // in the project for any name typed, as Pi's search finds them there.
+    if (entry.path.split("/").some((part) => part.startsWith(".")) && !name.startsWith(".") && !(project && name)) continue;
+    const value = name ? score(entry.path, name.split("/").filter(Boolean).at(-1) ?? name, entry.directory) : 1;
+    if (value > 0) entries.push({ ...entry, score: value });
+  }
+  const depth = (entry: Entry) => entry.path.split("/").length;
+  entries.sort((a, b) => b.score - a.score || depth(a) - depth(b)
+    || (name ? a.path.length - b.path.length : Number(b.directory) - Number(a.directory)) || a.path.localeCompare(b.path));
+  return { suggestions: entries.slice(0, LIMIT).map((entry) => ({ value: `${base}${entry.path}${entry.directory ? "/" : ""}`,
+    label: path.basename(entry.path) + (entry.directory ? "/" : ""), detail: `${base}${entry.path}`, kind: entry.directory ? "directory" : "file" })) };
+}

package/packages/piagent-core/extensions/piagent-guard.ts

@@ -1,3 +1,4 @@
+import { sessionMutationObserver } from "../runtime/inspection/session-mutation-observer.ts";
 import { unresolvedFocusedVerification } from "./acceptance-focused-verification.js";
 import fs from "node:fs";
 import os from "node:os";
@@ -21,10 +22,10 @@ import {
 import { grantedSourceCheckoutRootForPath, piToolPathInput, referenceReadRootForPath, shellTouchesGrantedSourceCheckout } from "./source-checkout-paths.ts";
 import { experimentLoopDecision } from "./experiment-loop-policy.ts";
 import { extractShellWritePathCandidates } from "./shell-write-targets.js";
-import { isProjectMutatingShellCommand } from "./readonly-inline-inspection.ts";
+import { isProjectMutatingShellCommand, isReadOnlyTaskShellCommand } from "./readonly-inline-inspection.ts";
 import { commandMatchesVerifyPlan, createBashResultLedger, findMatchingObservedBashResult, readObservedBashResults } from "./runtime-evidence.js";
 import { findPackageRoot, findPlatformRoot, readJsonFile } from "./guard-io.js";
-import { registerCompanySessionGuard } from "./company-session-guard.ts";
+import { isCompanySession, registerCompanySessionGuard } from "./company-session-guard.ts";
 import {
   extractDocument,
   resolveDocumentPath,
@@ -93,6 +94,8 @@ import { ensurePrivateStateDirectory, resolveLocalStatePath } from "./local-stat
 import { hasDurableContextEvidence } from "./context-evidence.js";
 import { piApprovalBroker, type ApprovalActionDraft, type ApprovalUnavailableFallback } from "../runtime/inspection/approval-broker.ts";
 import { createSourceMutationGuardBindings } from "../runtime/policy/source-mutation-guard-binding.ts";
+import { createWorkspaceWriteAuthorityBindings } from "../runtime/policy/workspace-write-authority.ts";
+import { registerWorkspaceMemberEdits } from "../runtime/session/workspace-member-edits.mjs";
 import {
   TOOL_RESULT_CAPTURE_MAX_CHARS,
   TOOL_RESULT_COMPACT_CHAR_THRESHOLD,
@@ -136,6 +139,8 @@ import { registerAgentStartHook } from "../runtime/hooks/agent-start-hook.ts";
 import { registerSessionHooks } from "../runtime/hooks/session-hooks.ts";
 import { registerSessionStartHook } from "../runtime/hooks/session-start-hook.ts";
 import { registerToolCallHook } from "../runtime/hooks/tool-call-hook.ts";
+import { PersonalCheckpointRuntime } from "../runtime/checkpoints/personal-runtime.ts";
+import { checkpointOwnershipError } from "../runtime/checkpoints/turn-checkpoints.mjs";
 import { registerToolResultHook } from "../runtime/hooks/tool-result-hook.ts";
 import { readRuntimeVersionMetadata, RuntimeSnapshotCapture } from "../runtime/model/runtime-snapshot.ts";
 import { recordRuntimeSnapshotTelemetry } from "../runtime/model/snapshot-telemetry.ts";
@@ -339,7 +344,12 @@ const PERMISSION_PROFILE_ALIASES: Record<string, PermissionProfileMode> = {
   "trusted-full-access": "trusted-full-access",
   "trusted_full_access": "trusted-full-access",
   "danger-full-access": "trusted-full-access",
-  "danger_full_access": "trusted-full-access"
+  "danger_full_access": "trusted-full-access",
+  bypass: "bypass",
+  yolo: "bypass",
+  "dangerously-bypass": "bypass",
+  "danger-bypass": "bypass",
+  "dangerously-bypass-approvals-and-sandbox": "bypass"
 };
 const READ_ONLY_TOOL_NAMES = new Set(["read", "grep", "find", "ls"]);
 const WRITE_TOOL_NAMES = new Set(["write", "edit"]);
@@ -1121,6 +1131,7 @@ function normalizePermissionProfileMode(value: unknown): PermissionProfileMode |
 function runtimeEquivalentForPermissionProfile(mode: PermissionProfileMode): string {
   if (mode === "read-only") return "sandbox_mode=read-only";
   if (mode === "trusted-full-access") return "sandbox_mode=danger-full-access + approval_policy=never, with Piagent protected-path and human-action gates still enforced";
+  if (mode === "bypass") return "sandbox_mode=danger-full-access + approval_policy=never; every Piagent gate off (output redaction and turn checkpoints remain)";
   return "sandbox_mode=workspace-write + approval_policy=on-request";
 }
 
@@ -1198,6 +1209,9 @@ function isPiagentTool(toolName: string): boolean {
   return toolName.startsWith("piagent_");
 }
 
+// Full access or more: the profile does not narrow reads or the tool registry.
+const broadAccess = (mode: PermissionProfileMode) => mode === "trusted-full-access" || mode === "bypass";
+
 function evaluatePermissionProfileToolAccess(
   toolName: string,
   permissionProfile: ResolvedPermissionProfile
@@ -3453,7 +3467,29 @@ export default function piagentGuard(pi: ExtensionAPI) {
   // task-contract retirement, so it uses one session-wide key; the guard itself
   // is already per session.
   const FREEFORM_EDIT_SCOPE = "freeform";
-  const sourceMutationGuardBindings = createSourceMutationGuardBindings(policy, loadProfileFromContext);
+  const workspaceWritable = (ctx: ExtensionContext, profile: ProjectProfile) => {
+    const permission = resolvePermissionProfile(profile, policy, permissionOverrideFromContext(ctx));
+    return permission.mode !== "read-only" && !permission.warning;
+  };
+  const sourceMutationGuardBindings = createSourceMutationGuardBindings(policy, loadProfileFromContext, workspaceWritable);
+  registerWorkspaceMemberEdits(pi);
+  const workspaceWriteBindings = createWorkspaceWriteAuthorityBindings(policy, loadProfileFromContext, workspaceWritable);
+  const personalCheckpoints = new PersonalCheckpointRuntime(ctx => ({
+    policy: policy as unknown as Record<string, unknown>,
+    profile: loadProfileFromContext(ctx) as unknown as Record<string, unknown>,
+    readOnly: !workspaceWritable(ctx, loadProfileFromContext(ctx))
+  }));
+  registerRuntimeCommand(pi, "undo", {
+    description: "Hoàn tác thay đổi của lượt trước; giữ nguyên commit.",
+    handler: async (_args, ctx) => {
+      try {
+        const undo = await personalCheckpoints.undo(ctx);
+        emitRuntimeMessage(ctx, "agent-watch-process", undo.text, { phase: "undo", undo });
+      } catch (error) {
+        emitRuntimeMessage(ctx, "agent-watch-process", `Không hoàn tác: ${redactText(String(error))}`, { phase: "undo", undo: { result: "failed" } });
+      }
+    }
+  });
   const runtimeSnapshotCapture = new RuntimeSnapshotCapture(), runtimeVersions = readRuntimeVersionMetadata(PLATFORM_ROOT);
   const solverShadow = solverMode === "off" ? undefined : new SolverShadowRuntime(solverMode);
   const modelRouteRuntime = new ModelRouteRuntime(parentRoutingMode, routingObjective);
@@ -3699,6 +3735,8 @@ export default function piagentGuard(pi: ExtensionAPI) {
         ctx.ui.notify("Piagent Fast mode is enabled, but the active provider is not OpenAI Codex; no service tier was changed.", "warning");
       }
       sourceMutationGuardBindings.bind(ctx);
+      workspaceWriteBindings.bind(ctx);
+      personalCheckpoints.bind(ctx);
       await activityInspector.refresh(ctx);
     }
   });
@@ -3713,13 +3751,18 @@ export default function piagentGuard(pi: ExtensionAPI) {
     appendTrace,
     flushObservedTaskContext: noTask,
     onTurnEnd: activityInspector.refresh,
-    onAgentSettled: activityInspector.refresh,
+    onAgentSettled: async ctx => { await personalCheckpoints.finish(ctx); await activityInspector.refresh(ctx); },
     beforeShutdown: async (ctx) => {
+      try { await personalCheckpoints.close(ctx); }
+      finally {
       serviceTierRuntime.forget(ctx);
       sourceMutationGuardBindings.unbind(ctx);
+      workspaceWriteBindings.unbind(ctx);
+      sessionMutationObserver.clear(ctx.cwd, ctx.sessionManager.getSessionId());
       editFreshnessGuard.clear(ctx);
       activityInspector.dispose(ctx);
       sessionCapabilityDigests.delete(`${ctx.cwd}\0${ctx.sessionManager.getSessionId()}`);
+      }
     }
   });
   registerTaskUsageHooks(pi, { activeTask: noTask, telemetry });
@@ -3742,7 +3785,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
         }),
         readProtectedPaths: effectiveProtectedPaths(policy, profile).readProtectedPaths,
         filesystemRead: capabilityState.filesystemRead,
-        enforceFilesystemRead: permissionProfile.mode !== "trusted-full-access"
+        enforceFilesystemRead: !broadAccess(permissionProfile.mode)
       };
     },
     activateToolGroups,
@@ -3795,6 +3838,8 @@ export default function piagentGuard(pi: ExtensionAPI) {
         disposition: result.disposition, reasonCode: result.reasonCode, calls: result.calls, tokens: result.tokens });
     },
     observeEditFreshness: (ctx, event, metadata) => {
+      sessionMutationObserver.finish(ctx.cwd, ctx.sessionManager.getSessionId(), event.toolCallId ?? "", event.toolName, metadata.successful,
+        { policy: policy as unknown as Record<string, unknown>, profile: loadProfileFromContext(ctx) as unknown as Record<string, unknown> });
       if (!metadata.successful) return;
       const protectedPaths = effectiveProtectedPaths(policy, loadProfileFromContext(ctx)).readProtectedPaths;
       const source = event.toolName === "read" ? "read" : ["edit", "write", "apply_patch"].includes(event.toolName) ? "mutation" : undefined;
@@ -3805,11 +3850,35 @@ export default function piagentGuard(pi: ExtensionAPI) {
     },
   });
 
+  // Bypass is for personal sessions only: a company session keeps Studio's rules.
+  const bypassActive = (ctx: ExtensionContext) => !isCompanySession(ctx) && ctx.model?.provider !== "agent_watch_managed"
+    && resolvePermissionProfile(loadProfileFromContext(ctx), policy, permissionOverrideFromContext(ctx)).mode === "bypass";
   registerToolCallHook(pi, {
     extractLikelyPath: extractLikelyPathFromInput,
     redactText,
     telemetry,
     activity: recordActivity,
+    beforeStart: async (event, ctx) => {
+      const input = isPlainRecord(event.input) ? event.input : {};
+      const target = authorizationMutationTargetInspection(ctx.cwd, event.toolName, input);
+      let mutating = ["write", "edit", "apply_patch"].includes(event.toolName) || target.exactLocalPatchExecutor;
+      if (SHELL_TOOL_NAMES.has(event.toolName)) {
+        const shell = extractShellCommandInput(input);
+        if (shell.command) {
+          // Anything not provably read-only may change files (`prettier --write`,
+          // `git stash`, a generator): it gets the turn's checkpoint first.
+          const command = normalizeShellCommandForPolicy(shell.command), segments = evaluateExecPolicy(command, loadProfileFromContext(ctx), policy).segments;
+          mutating ||= isProjectMutatingShellCommand(command, segments, ctx.cwd) || !isReadOnlyTaskShellCommand(command, segments, ctx.cwd);
+        }
+      }
+      if (!mutating) return;
+      // A missing checkpoint costs this turn its undo, never the edit itself;
+      // only another live owner of the session's history makes the edit wait.
+      try { await personalCheckpoints.beforeMutation(ctx); }
+      catch (error) {
+        if (checkpointOwnershipError(error)) return { block: true, reason: `Checkpoint failed before tool start: ${redactText(String(error))}` };
+      }
+    },
     beforeAuthorize: (event, ctx) => {
       const toolInput = isPlainRecord(event.input) ? event.input : {};
       const helperPreflight = evaluateDirectSubagentDispatch({ toolName: event.toolName, toolInput, cwd: ctx.cwd, helpersMode: helpersMode(),
@@ -3819,9 +3888,10 @@ export default function piagentGuard(pi: ExtensionAPI) {
           role: helperPreflight.role, requestCount: helperPreflight.requestCount });
         return { block: true, reason: `Blocked ${event.toolName}: ${helperPreflight.reason} Do not retry this helper; continue in the parent.` };
       }
+      if (bypassActive(ctx)) return;
       const targetInspection = authorizationMutationTargetInspection(ctx.cwd, event.toolName, toolInput);
       if (targetInspection.reason) return { block: true, reason: `Blocked ${event.toolName}: ${targetInspection.reason}.` };
-      if (event.toolName === "edit" || targetInspection.exactLocalPatchExecutor) {
+      if (event.toolName === "edit" || event.toolName === "write" || targetInspection.exactLocalPatchExecutor) {
         const freshness = editFreshnessGuard.evaluate(ctx, FREEFORM_EDIT_SCOPE, targetInspection.targets);
         if (freshness.decision === "stale") {
           telemetry(ctx, { event: "edit_freshness_stale", toolCallId: event.toolCallId, enforce: freshness.enforce, paths: freshness.stalePaths.map(redactText) });
@@ -3831,6 +3901,10 @@ export default function piagentGuard(pi: ExtensionAPI) {
       return;
     },
     afterAuthorized: (event, ctx, metadata) => {
+      const input = isPlainRecord(event.input) ? event.input : {};
+      sessionMutationObserver.begin(ctx.cwd, ctx.sessionManager.getSessionId(), metadata.toolCallId, event.toolName, input,
+        authorizationMutationTargetInspection(ctx.cwd, event.toolName, input).targets,
+        { policy: policy as unknown as Record<string, unknown>, profile: loadProfileFromContext(ctx) as unknown as Record<string, unknown> });
       const helperPreflight = evaluateDirectSubagentDispatch({ toolName: event.toolName, toolInput: event.input, cwd: ctx.cwd, helpersMode: helpersMode(),
         taskPending: false, dispatchAuthority: false, durableSubagentState: undefined });
       if (helperPreflight.applicable && helperPreflight.dispatch && helperPreflight.allowed) {
@@ -3840,6 +3914,10 @@ export default function piagentGuard(pi: ExtensionAPI) {
       return undefined;
     },
     authorize: async (event, ctx) => {
+    // Bypass: no Piagent gate asks or blocks, as with Codex's
+    // --dangerously-bypass-approvals-and-sandbox. Tool output is still
+    // redacted and the turn still gets its checkpoint; neither stops a command.
+    if (bypassActive(ctx)) return;
     const preInput = isPlainRecord(event.input) ? event.input : {};
     const authorizationTargetInspection = authorizationMutationTargetInspection(ctx.cwd, event.toolName, preInput);
     if (authorizationTargetInspection.reason) {

package/packages/piagent-core/extensions/workspace-inspection.ts

@@ -0,0 +1,145 @@
+import { suggestPaths } from "./path-suggestions.ts";
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import { effectiveProtectedPaths, matchesProtectedPath } from "./workspace-policy.js";
+import { inspectWorkspaceEntry, readWorkspaceFile, WorkspaceReadError } from "../security/workspace-file-reader.ts";
+
+export type WorkspacePolicy = { policy: Record<string, unknown>; profile: Record<string, unknown>; readOnly?: boolean };
+export type WorkspaceEntry = { name: string; path: string; kind: "file" | "directory" | "symlink" | "other";
+  protected: boolean; readOnly: boolean; ignored: boolean };
+const MAX_ENTRIES = 1_000, MAX_FILE_BYTES = 1 << 20;
+const git = process.platform === "darwin" ? "/usr/bin/git" : "git";
+
+function validPath(value: string, rootAllowed = false): void {
+  if (rootAllowed && value === "") return;
+  if (!value || value.length > 4096 || /[\\\x00-\x1f\x7f]/.test(value) || path.isAbsolute(value)
+    || value.split("/").some(part => !part || part === "." || part === "..")) {
+    throw new WorkspaceReadError("outside-root", "Workspace path is not a safe relative path");
+  }
+}
+
+// Ancestors inherit restrictions too: a protected folder cannot be opened via
+// a direct file URL that avoids the explorer's locked entry.
+export function workspacePathFlags(value: string, options: WorkspacePolicy): { protected: boolean; readOnly: boolean } {
+  const effective = effectiveProtectedPaths(options.policy, options.profile);
+  const parts = value.split("/");
+  const candidates = parts.map((_, index) => parts.slice(0, index + 1).join("/"));
+  return {
+    protected: candidates.some(candidate => !!matchesProtectedPath(candidate, effective.readProtectedPaths)),
+    readOnly: !!options.readOnly || candidates.some(candidate => !!matchesProtectedPath(candidate, effective.writeProtectedPaths))
+  };
+}
+
+function directory(root: string, relative: string): { absolute: string; stat: fs.Stats } {
+  validPath(relative, true);
+  const absolute = relative ? path.join(root, relative) : root;
+  const stat = relative ? inspectWorkspaceEntry(root, relative) : fs.lstatSync(root);
+  if (stat.isSymbolicLink()) throw new WorkspaceReadError("symlink-ancestor", "Workspace directory is a symbolic link");
+  if (!stat.isDirectory()) throw new WorkspaceReadError("not-file", "Workspace entry is not a directory");
+  return { absolute, stat };
+}
+
+export function inspectWorkspaceTree(rootPath: string, relative: string, options: WorkspacePolicy, limit = MAX_ENTRIES) {
+  const root = fs.realpathSync(rootPath);
+  const folder = directory(root, relative);
+  if (relative && workspacePathFlags(relative, options).protected) throw new Error("workspace-path-protected");
+  const cap = Math.max(1, Math.min(MAX_ENTRIES, Number.isFinite(limit) ? Math.floor(limit) : MAX_ENTRIES));
+  const names = new Set<string>(), directories = new Set<string>();
+  let truncated = false, source: "git" | "directory" = "git";
+  let output: string | null = null;
+  try {
+    output = execFileSync(git, ["-C", folder.absolute, "ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", "."],
+      { encoding: "utf8", timeout: 3000, maxBuffer: 4 << 20, stdio: ["ignore", "pipe", "ignore"] });
+  } catch (error) {
+    const failure = error as NodeJS.ErrnoException & { stdout?: string | Buffer };
+    if (failure.code === "ENOBUFS" && failure.stdout) {
+      const partial = String(failure.stdout);
+      output = partial.slice(0, partial.lastIndexOf("\0") + 1);
+      truncated = true;
+    } else {
+      let repository = false;
+      try { repository = execFileSync(git, ["-C", root, "rev-parse", "--is-inside-work-tree"],
+        { encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "ignore"] }).trim() === "true"; } catch { /* no repository */ }
+      // A Git timeout must not turn ignored paths into visible fallback entries.
+      if (repository) throw new Error("workspace-tree-unavailable");
+    }
+  }
+  if (output !== null) {
+    for (const entry of output.split("\0")) {
+      const name = entry.split("/")[0];
+      if (!name || name === ".git") continue;
+      names.add(name);
+      if (entry.includes("/")) directories.add(name);
+      if (names.size > cap) { truncated = true; break; }
+    }
+  } else {
+    // Even without Git, never materialize an unbounded directory listing.
+    source = "directory";
+    const handle = fs.opendirSync(folder.absolute);
+    try {
+      let entry: fs.Dirent | null;
+      while ((entry = handle.readSync())) {
+        if (entry.name === ".git") continue;
+        names.add(entry.name);
+        if (entry.isDirectory()) directories.add(entry.name);
+        if (names.size > cap) { truncated = true; break; }
+      }
+    } finally { handle.closeSync(); }
+  }
+  const entries: WorkspaceEntry[] = [];
+  for (const name of [...names].slice(0, cap)) {
+    const entryPath = relative ? `${relative}/${name}` : name;
+    try {
+      validPath(entryPath);
+      const flags = workspacePathFlags(entryPath, options);
+      if (flags.protected) {
+        entries.push({ name, path: entryPath, kind: directories.has(name) ? "directory" : "file", ...flags, ignored: false });
+        continue;
+      }
+      const stat = inspectWorkspaceEntry(root, entryPath);
+      const kind = stat.isSymbolicLink() ? "symlink" : stat.isDirectory() ? "directory" : stat.isFile() ? "file" : "other";
+      entries.push({ name, path: entryPath, kind, ...workspacePathFlags(entryPath, options), ignored: false });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+      throw error;
+    }
+  }
+  const after = directory(root, relative).stat;
+  if (after.dev !== folder.stat.dev || after.ino !== folder.stat.ino || after.mtimeMs !== folder.stat.mtimeMs) {
+    throw new WorkspaceReadError("changed-during-read", "Workspace directory changed during inspection");
+  }
+  entries.sort((a, b) => Number(b.kind === "directory") - Number(a.kind === "directory") || a.name.localeCompare(b.name));
+  return { path: relative, entries, truncated, source };
+}
+
+const LANGUAGES: Record<string, string> = { ts: "typescript", tsx: "tsx", js: "javascript", jsx: "jsx", mjs: "javascript", cjs: "javascript",
+  json: "json", md: "markdown", css: "css", html: "html", py: "python", rs: "rust", go: "go", sh: "shell", yaml: "yaml", yml: "yaml" };
+
+export function inspectWorkspaceFile(root: string, relative: string, options: WorkspacePolicy) {
+  validPath(relative);
+  const flags = workspacePathFlags(relative, options);
+  const base = { path: relative, language: LANGUAGES[relative.split(".").at(-1)?.toLowerCase() ?? ""] ?? "text", ...flags,
+    binary: false, oversized: false, content: null as string | null, digest: null as string | null, revision: null as string | null };
+  // Do not stat or hash protected files: even their digest would expose data.
+  if (flags.protected) return base;
+  let bytes: Buffer;
+  try { bytes = readWorkspaceFile(root, relative, MAX_FILE_BYTES); }
+  catch (error) { if (error instanceof WorkspaceReadError && error.code === "oversized") return { ...base, oversized: true }; throw error; }
+  const digest = createHash("sha256").update(bytes).digest("hex");
+  let content: string;
+  try {
+    if (bytes.includes(0)) return { ...base, binary: true, digest, revision: `sha256:${digest}` };
+    content = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch { return { ...base, binary: true, digest, revision: `sha256:${digest}` }; }
+  return { ...base, content, digest, revision: `sha256:${digest}` };
+}
+
+export async function inspectWorkspacePaths(root: string, query: string, options: WorkspacePolicy) {
+  if (query.length > 512 || /[\x00-\x1f\x7f]/.test(query)) throw new Error("workspace-query-invalid");
+  const result = await suggestPaths({ root, query, projectOnly: true,
+    isAllowed: relative => !workspacePathFlags(relative, options).protected });
+  return { query, ...result, truncated: result.suggestions.length >= 20 };
+}

package/packages/piagent-core/extensions/workspace-policy.d.ts

@@ -0,0 +1,7 @@
+export function effectiveProtectedPaths(policy?: Record<string, unknown>, profile?: Record<string, unknown>): {
+  readProtectedPaths: string[]; writeProtectedPaths: string[]; shellProtectedPaths: string[]; readOnlyPaths: string[];
+};
+export function matchesProtectedPath(candidate: string, patterns: string[]): string | undefined;
+export function loadProjectContextIndexPolicy(platformRoot: string, projectPath: string, options?: { profilePath?: string }): {
+  policy: Record<string, unknown>; profile: Record<string, unknown>; profilePath: string; profileSource: string; excludePatterns: string[];
+};

package/packages/piagent-core/extensions/workspace-policy.js

@@ -0,0 +1,3 @@
+// The typed workspace API shares the existing policy implementation.
+export { effectiveProtectedPaths, loadProjectContextIndexPolicy } from "./context-index-policy.js";
+export { matchesProtectedPath } from "./policy-core.js";

package/packages/piagent-core/extensions/workspace-search-index.mjs

@@ -0,0 +1,8 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { searchContextIndexV2 } from './context-engine.js';
+// Isolate synchronous SQLite work so the caller can enforce its deadline.
+try {
+  const result = await searchContextIndexV2(workerData.root, workerData.query,
+    { excludePatterns: workerData.excludePatterns, limit: 50 });
+  parentPort.postMessage({ paths: result.results.map(row => row.path), available: result.status.exists });
+} catch { parentPort.postMessage({ paths: [], available: false }); }

package/packages/piagent-core/extensions/workspace-search.ts

@@ -0,0 +1,74 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { Worker } from "node:worker_threads";
+import { inspectWorkspaceFile, workspacePathFlags, type WorkspacePolicy } from "./workspace-inspection.ts";
+import { effectiveProtectedPaths } from "./workspace-policy.js";
+
+export type WorkspaceMatch = { path: string; line: number; column: number; preview: string };
+const TIMEOUT = 3000, LIMIT = 100;
+function findRipgrep(): string | null {
+  for (const dir of String(process.env.PATH ?? "").split(path.delimiter)) {
+    const file = path.join(dir, process.platform === "win32" ? "rg.exe" : "rg");
+    try { fs.accessSync(file, fs.constants.X_OK); return file; } catch { /* next */ }
+  }
+  return null;
+}
+
+function ftsCandidates(root: string, query: string, excludePatterns: string[], timeout: number) {
+  return new Promise<{ paths: string[]; available: boolean; timedOut: boolean }>((resolve) => {
+    const worker = new Worker(new URL("./workspace-search-index.mjs", import.meta.url), { workerData: { root, query, excludePatterns } });
+    let settled = false;
+    const finish = (value: { paths: string[]; available: boolean; timedOut: boolean }) => {
+      if (settled) return; settled = true; clearTimeout(timer); void worker.terminate(); resolve(value);
+    };
+    const timer = setTimeout(() => finish({ paths: [], available: true, timedOut: true }), timeout);
+    worker.once("message", value => finish({ ...value, timedOut: false }));
+    worker.once("error", () => finish({ paths: [], available: false, timedOut: false }));
+    worker.once("exit", () => finish({ paths: [], available: false, timedOut: false }));
+  });
+}
+
+export async function searchWorkspace(root: string, query: string, options: WorkspacePolicy, config: { rg?: string | null; timeout?: number } = {}) {
+  if (!query.trim() || query.length > 512 || /[\x00-\x1f\x7f]/.test(query)) throw new Error("workspace-query-invalid");
+  const deadline = Date.now() + Math.max(1, Math.min(TIMEOUT, config.timeout ?? TIMEOUT));
+  const effective = effectiveProtectedPaths(options.policy, options.profile);
+  const excludePatterns = [...new Set([...effective.readProtectedPaths, ".git/**"])];
+  const rg = config.rg === undefined ? findRipgrep() : config.rg;
+  let paths: string[] = [], truncated = false, available = true;
+  const backend = rg ? "ripgrep" : "fts";
+  if (rg) {
+    const result = await new Promise<{ output: string; limited: boolean }>((resolve) => {
+      execFile(rg, ["--files-with-matches", "--null", "--hidden", "--fixed-strings", "--max-filesize", "1M", "--no-messages",
+        ...excludePatterns.flatMap(pattern => ["--iglob", `!${pattern}`, "--iglob", `!${pattern}/**`]), "--", query, "."],
+      { cwd: root, timeout: Math.max(1, deadline - Date.now()), maxBuffer: 1 << 20, encoding: "utf8" }, (error, stdout) => {
+        resolve({ output: stdout, limited: !!error && (error as { code?: unknown }).code !== 1 });
+      });
+    });
+    truncated = result.limited;
+    paths = result.output.slice(0, result.output.lastIndexOf("\0") + 1).split("\0").filter(Boolean).map(file => file.replace(/^\.\//, ""));
+  } else {
+    const result = await ftsCandidates(root, query, excludePatterns, Math.max(1, deadline - Date.now()));
+    paths = result.paths; available = result.available; truncated = result.timedOut || paths.length >= 50;
+  }
+  const matches: WorkspaceMatch[] = [];
+  for (const relative of [...new Set(paths)]) {
+    if (Date.now() >= deadline || matches.length >= LIMIT) { truncated = true; break; }
+    if (workspacePathFlags(relative, options).protected) continue;
+    try {
+      // Never return stale index text or rg output; apply the file reader's
+      // symlink/policy checks and calculate positions from current bytes.
+      const file = inspectWorkspaceFile(root, relative, options);
+      if (file.content === null) continue;
+      const lines = file.content.split(/\r?\n/);
+      for (let index = 0; index < lines.length; index++) {
+        if (Date.now() >= deadline || matches.length >= LIMIT) { truncated = true; break; }
+        const column = lines[index].indexOf(query);
+        if (column < 0) continue;
+        const start = Math.max(0, column - 80);
+        matches.push({ path: relative, line: index + 1, column: column + 1, preview: lines[index].slice(start, start + 400) });
+      }
+    } catch { /* moved, unsafe, or unreadable candidate */ }
+  }
+  return { query, matches, truncated, backend, available };
+}