@piagent/platform 1.4.0 → 1.5.1

package/docs-site/runtime.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.4.0 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.5.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/runtime" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/runtime" hreflang="en" lang="en">EN</a>
@@ -154,6 +154,34 @@ piagent-auto --full-access -p "Run the trusted local benchmark suite."</code></p
       <header><span>Capabilities</span><button class="clip-btn" data-clip="piagent-capabilities catalog --check&#10;piagent-capabilities doctor --profile .pi/piagent-profile.json">Lấy lệnh</button></header>
       <pre><code>piagent-capabilities catalog --check
 piagent-capabilities doctor --profile .pi/piagent-profile.json</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Session Hub</span><button class="clip-btn" data-clip="piagent dashboard&#10;piagent-webui --no-open">Lấy lệnh</button></header>
+      <pre><code>piagent dashboard
+piagent-webui --no-open</code></pre>
+      <p class="command-note">Bí danh: <code>piagent-dashboard</code>, <code>piagent-webui</code>, <code>piagent-explain</code> cũng chạy được như binary riêng.</p>
+    </article>
+    <article class="command-card">
+      <header><span>Giải thích quyết định</span><button class="clip-btn" data-clip="piagent explain &#39;cat .env*&#39;&#10;piagent explain --scope">Lấy lệnh</button></header>
+      <pre><code>piagent explain 'cat .env*'
+piagent explain --scope</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Usage và token</span><button class="clip-btn" data-clip="piagent-usage .&#10;piagent-usage --history . --days 7">Lấy lệnh</button></header>
+      <pre><code>piagent-usage .
+piagent-usage --history . --days 7</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Model và routing</span><button class="clip-btn" data-clip="piagent-models&#10;piagent-model-scope&#10;piagent-route">Lấy lệnh</button></header>
+      <pre><code>piagent-models
+piagent-model-scope
+piagent-route</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Subagents và migration</span><button class="clip-btn" data-clip="piagent-subagents --preset safe&#10;piagent-migrate . --apply&#10;piagent-import-instructions">Lấy lệnh</button></header>
+      <pre><code>piagent-subagents --preset safe
+piagent-migrate . --apply
+piagent-import-instructions</code></pre>
     </article>
     <article class="command-card">
       <header><span>Verification</span><button class="clip-btn" data-clip="npm run verify&#10;npm test&#10;npm run typecheck">Lấy lệnh</button></header>
@@ -191,5 +219,9 @@ npm run typecheck</code></pre>
         <nav data-toc></nav>
       </aside>
     </div>
+    <script>
+      window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
+    </script>
+    <script defer src="/_vercel/insights/script.js"></script>
   </body>
 </html>

package/docs-site/scope.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.4.0 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.5.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/scope" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/scope" hreflang="en" lang="en">EN</a>
@@ -201,5 +201,9 @@
         <nav data-toc></nav>
       </aside>
     </div>
+    <script>
+      window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
+    </script>
+    <script defer src="/_vercel/insights/script.js"></script>
   </body>
 </html>

package/docs-site/security.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.4.0 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.5.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/security" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/security" hreflang="en" lang="en">EN</a>
@@ -182,5 +182,9 @@
         <nav data-toc></nav>
       </aside>
     </div>
+    <script>
+      window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
+    </script>
+    <script defer src="/_vercel/insights/script.js"></script>
   </body>
 </html>

package/docs-site/team.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.4.0 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.5.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/team" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/team" hreflang="en" lang="en">EN</a>
@@ -149,5 +149,9 @@
         <nav data-toc></nav>
       </aside>
     </div>
+    <script>
+      window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
+    </script>
+    <script defer src="/_vercel/insights/script.js"></script>
   </body>
 </html>

package/docs-site/whats-new.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.4.0 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.5.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/whats-new" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/whats-new" hreflang="en" lang="en">EN</a>
@@ -237,5 +237,9 @@
         <nav data-toc></nav>
       </aside>
     </div>
+    <script>
+      window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
+    </script>
+    <script defer src="/_vercel/insights/script.js"></script>
   </body>
 </html>

package/docs-site/workflows.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.4.0 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.5.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/workflows" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/workflows" hreflang="en" lang="en">EN</a>
@@ -237,5 +237,9 @@
         <nav data-toc></nav>
       </aside>
     </div>
+    <script>
+      window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
+    </script>
+    <script defer src="/_vercel/insights/script.js"></script>
   </body>
 </html>

package/evals/fixtures/piagent-webui/document-workspace-v1.invalid.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": 1,
+  "version": "piagent-webui-document-workspace-v1",
+  "messageType": "document",
+  "generatedAt": "2026-08-17T09:00:00.000Z",
+  "documentRef": "document_01",
+  "state": "unavailable",
+  "name": null,
+  "relativePath": null,
+  "rootRef": null,
+  "format": null,
+  "text": "# Ke hoach quy ba\n\nContent that must never accompany a refusal.\n",
+  "sizeBytes": null,
+  "truncated": false,
+  "redacted": false,
+  "reasonCode": "document-protected"
+}

package/evals/fixtures/piagent-webui/document-workspace-v1.valid.json

@@ -0,0 +1,42 @@
+{
+  "schemaVersion": 1,
+  "version": "piagent-webui-document-workspace-v1",
+  "messageType": "listing",
+  "generatedAt": "2026-08-17T09:00:00.000Z",
+  "state": "ready",
+  "roots": [
+    { "rootRef": "document-root_01", "path": "/workspace/project", "source": "project", "documentCount": 2 },
+    { "rootRef": "document-root_02", "path": "/home/operator/Downloads", "source": "profile", "documentCount": 1 }
+  ],
+  "documents": [
+    {
+      "documentRef": "document_01",
+      "rootRef": "document-root_01",
+      "name": "ke-hoach.md",
+      "relativePath": "tai-lieu/ke-hoach.md",
+      "extension": "md",
+      "sizeBytes": 4096,
+      "modifiedAt": "2026-08-17T08:30:00.000Z"
+    },
+    {
+      "documentRef": "document_02",
+      "rootRef": "document-root_01",
+      "name": "bao-cao.docx",
+      "relativePath": "tai-lieu/bao-cao.docx",
+      "extension": "docx",
+      "sizeBytes": 245760,
+      "modifiedAt": "2026-08-17T08:45:00.000Z"
+    },
+    {
+      "documentRef": "document_03",
+      "rootRef": "document-root_02",
+      "name": "vendor-spec.pdf",
+      "relativePath": "vendor-spec.pdf",
+      "extension": "pdf",
+      "sizeBytes": 1048576,
+      "modifiedAt": "2026-08-16T17:10:00.000Z"
+    }
+  ],
+  "truncated": false,
+  "reasonCode": null
+}

package/evals/fixtures/piagent-webui/session-command-v1.valid.json

@@ -14,6 +14,7 @@
     "delivery": "new-operation",
     "message": "Continue the gateway implementation.",
     "messageRequestId": "message_request_01",
-    "expectedOperationRef": null
+    "expectedOperationRef": null,
+    "attachmentRefs": ["attachment_01"]
   }
 }

package/package.json

@@ -1,19 +1,30 @@
 {
   "name": "@piagent/platform",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "type": "module",
-  "description": "Reusable Pi agent platform, project adapters, MCP/tool policy, and coding workflow harness.",
+  "description": "Guardrails for AI coding agents: blocks secret reads, destructive commands, and unapproved MCP servers before the tool call runs. Ships project profiles, capability locks, a context engine, and task verification.",
   "homepage": "https://piagent.io.vn",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Vt-mmm/piagent.git"
   },
   "keywords": [
+    "ai-agent",
+    "coding-agent",
+    "agent-guardrails",
+    "agent-security",
+    "llm-tool-policy",
+    "prompt-injection",
+    "mcp",
+    "mcp-security",
+    "secret-redaction",
+    "context-engineering",
+    "developer-tools",
     "pi-package",
     "pi-extension",
     "pi-skill",
@@ -75,6 +86,7 @@
     "piagent-import-instructions": "scripts/piagent-cli.mjs",
     "piagent-auto": "scripts/piagent-cli.mjs",
     "piagent-context": "scripts/piagent-cli.mjs",
+    "piagent-explain": "scripts/piagent-cli.mjs",
     "piagent-webui": "scripts/piagent-cli.mjs"
   },
   "pi": {

package/packages/piagent-core/README.md

@@ -179,8 +179,9 @@ Project-local state belongs in `.pi/.gitignore`.
 Task files use schema v2 and bind one unique `taskRunId` to one Pi `sessionId`.
 They record attempt/max-attempt history, dependency-safe work-plan progress,
 Git baseline/final digests, observed changes, all exact verify results and final
-trace. A terminal task is immutable; retry starts in a fresh session and carries
-the prior failure/ruled-out evidence. Legacy v1 state is migrated and archived
+trace. A terminal task is immutable; the same conversation may bind a new task
+or retry attempt after the prior task closes, while keeping only one task pending
+at a time and carrying prior failure/ruled-out evidence. Legacy v1 state is migrated and archived
 without requiring project onboarding again.
 
 Local state directories are owner-only. Task state, context telemetry, trace,

package/packages/piagent-core/capabilities/capability-verification-cache.js

@@ -148,12 +148,21 @@ function lexicalAncestors(target) {
   return ancestors;
 }
 
-function metadataSignature(targets) {
+// The directories above every target, sorted, derived once per snapshot. The
+// set is a pure function of the target list, and a cached entry's target list
+// cannot change while the entry lives, so deriving it per call was repeating
+// work that could not produce a different answer -- and at 296 pinned files it
+// was the single most expensive part of a cache hit, more than every `lstat`
+// this function performs put together.
+function ancestorPaths(targets) {
+  return [...new Set(targets.flatMap((target) => lexicalAncestors(target.path)))].sort(compare);
+}
+
+function metadataSignature(targets, ancestors) {
   if (!targets) return undefined;
   const records = [];
-  const ancestors = new Set(targets.flatMap((target) => lexicalAncestors(target.path)));
   try {
-    for (const ancestor of [...ancestors].sort(compare)) {
+    for (const ancestor of ancestors ?? ancestorPaths(targets)) {
       const stat = fs.lstatSync(ancestor, { bigint: true });
       const symbolic = stat.isSymbolicLink();
       const identity = symbolic ? statIdentity(stat, true) : ancestorIdentity(stat);
@@ -194,13 +203,14 @@ function cacheIdentity(lockDocument, options = {}) {
 }
 
 function snapshotTargets(targets) {
-  const signature = metadataSignature(targets);
-  return signature ? { signature, targets } : undefined;
+  const ancestors = ancestorPaths(targets);
+  const signature = metadataSignature(targets, ancestors);
+  return signature ? { signature, targets, ancestors } : undefined;
 }
 
 function stableSnapshot(snapshot) {
   if (!snapshot) return false;
-  const current = metadataSignature(snapshot.targets);
+  const current = metadataSignature(snapshot.targets, snapshot.ancestors);
   return Boolean(current && current === snapshot.signature);
 }
 
@@ -209,7 +219,7 @@ export function verifyCapabilityLockCached(cache, root, profilePath, lockPath, l
   const identity = cacheIdentity(lockDocument, options);
   const cached = options.forceFull === true ? undefined : cache?.get(key);
   if (cached?.identity === identity) {
-    const signature = metadataSignature(cached.targets);
+    const signature = metadataSignature(cached.targets, cached.ancestors);
     if (signature && signature === cached.signature) return { ...cached.verification, cacheStatus: "hit" };
   }
   cache?.delete(key);

package/packages/piagent-core/capabilities/runtime-integrity.js

@@ -164,6 +164,11 @@ const EXECUTABLE_SOURCE = /\.(?:[cm]?js|ts|json|sh)$/;
 const IMPORT_SPECIFIER = /(?:\bimport\s*(?:type\s+)?(?:[^"'`]*?\s+from\s*)?|\bexport\s+(?:type\s+)?[^"'`]*?\s+from\s*)["']([^"']+)["']/g;
 const DYNAMIC_IMPORT = /\bimport\(\s*["']([^"']+)["']\s*\)/g;
 const RUNTIME_LITERAL = /["']((?:packages|scripts)\/[A-Za-z0-9_./-]+\.(?:[cm]?js|ts|json|sh))["']/g;
+// A shell entrypoint reaches a sibling program through the directory it computed
+// for itself -- `"$SCRIPT_DIR/pi-usage-history.mjs"` -- so the repository-relative
+// literal the scanner above looks for never appears in the source. `piagent-usage`
+// is a pinned command that ran a 567-line unpinned program this way.
+const SHELL_SIBLING = /\$(?:\{)?(?:SCRIPT_DIR|ROOT|REPO_ROOT|PLATFORM_ROOT)(?:\})?\/([A-Za-z0-9_./-]+\.(?:[cm]?js|ts|json|sh))/g;
 const MAX_INTEGRITY_FILES = 5_000;
 
 function normalizedRelative(root, absolute) {
@@ -172,7 +177,16 @@ function normalizedRelative(root, absolute) {
   return relative.split(path.sep).join("/");
 }
 
-function executableFilesBelow(root, relativeDirectory) {
+// A served bundle is more than its scripts: the document names which script runs,
+// so pinning the JavaScript while leaving the HTML free would leave the choice of
+// program unpinned.
+const SERVED_BUNDLE_ASSET = /\.(?:[cm]?js|css|html|json|svg|woff2)$/;
+
+function bundleFilesBelow(root, relativeDirectory) {
+  return executableFilesBelow(root, relativeDirectory, SERVED_BUNDLE_ASSET);
+}
+
+function executableFilesBelow(root, relativeDirectory, accept = EXECUTABLE_SOURCE) {
   const directory = path.join(root, relativeDirectory);
   if (!fs.existsSync(directory)) return [];
   const files = [];
@@ -182,7 +196,7 @@ function executableFilesBelow(root, relativeDirectory) {
       const target = path.join(absolute, entry.name), stat = fs.lstatSync(target);
       if (stat.isSymbolicLink()) throw new Error(`runtime-integrity-symlink:${normalizedRelative(root, target) ?? "outside-root"}`);
       if (stat.isDirectory()) visit(target);
-      else if (stat.isFile() && EXECUTABLE_SOURCE.test(entry.name)) files.push(normalizedRelative(root, target));
+      else if (stat.isFile() && accept.test(entry.name)) files.push(normalizedRelative(root, target));
     }
   };
   visit(directory);
@@ -192,7 +206,13 @@ function executableFilesBelow(root, relativeDirectory) {
 function localImportTarget(root, importer, specifier) {
   if (!specifier.startsWith(".")) return undefined;
   const base = path.resolve(path.dirname(path.join(root, importer)), specifier);
-  const candidates = [base, `${base}.ts`, `${base}.js`, `${base}.mjs`, path.join(base, "index.ts"), path.join(base, "index.js")];
+  // TypeScript sources import a sibling module by its emitted name, so `./x.js`
+  // is how a `.ts` file refers to `x.ts`. Without that rewrite the specifier
+  // resolves to nothing and the reference is dropped in silence -- a module
+  // that decides what the guard enforces would then sit outside the lock while
+  // this list still claimed to cover the whole import graph.
+  const rewritten = base.endsWith(".js") ? [`${base.slice(0, -3)}.ts`] : [];
+  const candidates = [base, ...rewritten, `${base}.ts`, `${base}.js`, `${base}.mjs`, path.join(base, "index.ts"), path.join(base, "index.js")];
   for (const candidate of candidates) {
     const relative = normalizedRelative(root, candidate);
     if (!relative || !fs.existsSync(candidate)) continue;
@@ -204,8 +224,24 @@ function localImportTarget(root, importer, specifier) {
 }
 
 function sourceReferences(root, relativeFile) {
-  if (!/\.(?:[cm]?js|ts)$/.test(relativeFile)) return [];
+  // Shell entrypoints are scanned too. They were skipped here, so a pinned
+  // command could execute an unpinned program and the lock reported a complete
+  // graph while missing it.
+  const shell = relativeFile.endsWith(".sh");
+  if (!shell && !/\.(?:[cm]?js|ts)$/.test(relativeFile)) return [];
   const source = fs.readFileSync(path.join(root, relativeFile), "utf8"), references = new Set();
+  if (shell) {
+    const directory = path.posix.dirname(relativeFile);
+    for (const pattern of [RUNTIME_LITERAL, SHELL_SIBLING]) {
+      pattern.lastIndex = 0;
+      for (let match = pattern.exec(source); match; match = pattern.exec(source)) {
+        const candidate = pattern === SHELL_SIBLING ? path.posix.join(directory, match[1]) : match[1];
+        const absolute = path.join(root, candidate), relative = normalizedRelative(root, absolute);
+        if (relative && fs.existsSync(absolute) && fs.lstatSync(absolute).isFile()) references.add(relative);
+      }
+    }
+    return [...references];
+  }
   for (const pattern of [IMPORT_SPECIFIER, DYNAMIC_IMPORT]) {
     pattern.lastIndex = 0;
     for (let match = pattern.exec(source); match; match = pattern.exec(source)) {
@@ -231,6 +267,17 @@ export function discoverRuntimeIntegrityFiles(root) {
     ...CORE_RUNTIME_INTEGRITY_FILES,
     "packages/piagent-core/extensions/piagent-guard.ts",
     ...executableFilesBelow(root, "packages/piagent-core/runtime"),
+    // The browser bundle the WebUI serves. The published package ships the built
+    // assets and not the sources they came from, so on an installed platform
+    // this code cannot be regenerated or cross-checked against anything -- and it
+    // runs inside the origin that holds the session cookie and the CSRF token,
+    // with the authority to drive session commands, source mutation and provider
+    // auth. The server that serves it was pinned; what it serves was not.
+    //
+    // The tree is absent in a source checkout until the workspace is built, and
+    // absence is not a failure here: a lock recorded with these entries still
+    // fails verification if they later disappear.
+    ...bundleFilesBelow(root, "packages/piagent-webui/dist/client"),
     ...declaredExtensions,
     ...declaredBins,
     ...declaredEntrypoints

package/packages/piagent-core/extensions/document-intake.ts

@@ -51,7 +51,7 @@ export type DocumentExtraction =
   | { status: "ok"; text: string; truncated: boolean; kind: "text" | "docx" | "pdf" }
   | { status: "error"; reason: string };
 
-type DocumentCommandResult = { status: number | null; stdout: string; stderr: string; error?: Error };
+export type DocumentCommandResult = { status: number | null; stdout: string; stderr: string; error?: Error };
 
 export function expandHome(candidate: string, home: string | undefined): string {
   if (candidate === "~") return home ?? candidate;
@@ -450,7 +450,10 @@ export function extractPdfFromDescriptor(
   // stdout out. The converter is handed the already-open descriptor rather than
   // a path, so it reads the file whose identity was verified and cannot be
   // pointed somewhere else by a name that changed in the meantime.
-  const result = run("pdftotext", ["-layout", "-enc", "UTF-8", "-", "-"], fd);
+  return extractPdfCommandResult(run("pdftotext", ["-layout", "-enc", "UTF-8", "-", "-"], fd));
+}
+
+export function extractPdfCommandResult(result: DocumentCommandResult): DocumentExtraction {
   if (result.error) {
     return {
       status: "error",
@@ -471,7 +474,7 @@ export function extractPdfFromDescriptor(
 
 // spawnSync blocks the whole runtime, so an external converter that never
 // returns would hang the session rather than fail the read.
-const PDF_TIMEOUT_MS = 20_000;
+export const PDF_TIMEOUT_MS = 20_000;
 
 export function probeExecutableOnPath(executable: string): DocumentCommandResult {
   const result = spawnSync("/bin/sh", ["-c", 'command -v "$1"', "piagent-command-probe", executable], {