npm - @piagent/platform - Versions diffs - 1.1.9 → 1.2.1 - Mend

@piagent/platform 1.1.9 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (81) hide show

package/CHANGELOG.md +175 -1
package/README.md +2 -2
package/docs/command-reference-vietnamese.md +19 -5
package/docs/distribution-standard.md +7 -7
package/docs/mcp-and-tools.md +154 -2
package/docs/model-options.md +10 -8
package/docs/operator-manual-vietnamese.md +25 -13
package/docs/publishing-for-teams.md +2 -0
package/docs/quickstart-vietnamese.md +2 -2
package/docs/release-install-policy.md +6 -6
package/docs/security-threat-model.md +4 -3
package/docs/team-onboarding.md +4 -4
package/docs/usage-observability.md +29 -0
package/docs/vercel-docs-site.md +34 -4
package/docs-site/architecture.html +152 -0
package/docs-site/assets/docs.css +1001 -0
package/docs-site/assets/docs.js +84 -0
package/docs-site/commands.html +203 -0
package/docs-site/content/architecture.html +29 -0
package/docs-site/content/commands.html +80 -0
package/docs-site/content/index.html +80 -0
package/docs-site/content/mcp-approval.html +133 -0
package/docs-site/content/mcp-auth.html +76 -0
package/docs-site/content/mcp-servers.html +111 -0
package/docs-site/content/mcp.html +120 -0
package/docs-site/content/permissions.html +54 -0
package/docs-site/content/profiles.html +68 -0
package/docs-site/content/quickstart.html +144 -0
package/docs-site/content/runtime.html +45 -0
package/docs-site/content/scope.html +71 -0
package/docs-site/content/security.html +51 -0
package/docs-site/content/team.html +23 -0
package/docs-site/content/workflows.html +47 -0
package/docs-site/index.html +131 -1534
package/docs-site/mcp-approval.html +256 -0
package/docs-site/mcp-auth.html +199 -0
package/docs-site/mcp-servers.html +234 -0
package/docs-site/mcp.html +243 -0
package/docs-site/permissions.html +177 -0
package/docs-site/profiles.html +191 -0
package/docs-site/quickstart.html +267 -0
package/docs-site/runtime.html +168 -0
package/docs-site/scope.html +194 -0
package/docs-site/security.html +174 -0
package/docs-site/team.html +142 -0
package/docs-site/workflows.html +170 -0
package/package.json +4 -2
package/packages/piagent-core/capabilities/capability-core.js +58 -5
package/packages/piagent-core/capabilities/capability-sources.js +73 -12
package/packages/piagent-core/extensions/document-intake.ts +5 -5
package/packages/piagent-core/extensions/piagent-guard.ts +432 -2
package/packages/piagent-core/extensions/policy-core.js +1586 -98
package/packages/piagent-core/mcp/mcp-approval-store.js +216 -0
package/packages/piagent-core/mcp/mcp-auth-readiness.js +225 -0
package/packages/piagent-core/mcp/mcp-command-actions.js +400 -0
package/packages/piagent-core/mcp/mcp-config-layers.js +466 -0
package/packages/piagent-core/mcp/mcp-import-kinds.js +240 -0
package/packages/piagent-core/mcp/mcp-server-catalog.js +150 -0
package/packages/piagent-core/mcp/mcp-server-entry.js +293 -0
package/packages/piagent-core/mcp/mcp-session-view.js +236 -0
package/packages/piagent-core/mcp/mcp-tool-naming.js +90 -0
package/packages/piagent-core/package.json +7 -3
package/packages/piagent-core/prompts/model-options.md +8 -8
package/scripts/build-docs-site.mjs +421 -0
package/scripts/configure-model-scope.sh +21 -5
package/scripts/configure-subagents.sh +18 -5
package/scripts/init-project.sh +15 -8
package/scripts/install-global.sh +5 -5
package/scripts/mcp-manage.mjs +656 -0
package/scripts/pi-model-catalog.sh +11 -1
package/scripts/pi-session-stats.sh +27 -1
package/scripts/pi-usage-history.mjs +567 -0
package/scripts/piagent-cli.mjs +1 -1
package/scripts/preview-docs-site.mjs +88 -0
package/scripts/quality-benchmark.sh +37 -9
package/scripts/setup.sh +23 -15
package/scripts/team-doctor.sh +18 -2
package/scripts/uninstall-global.sh +10 -4
package/scripts/verify-local.sh +65 -19
package/scripts/verify-release-identity.mjs +37 -2
package/scripts/configure-mcp.sh +0 -349

package/docs-site/team.html ADDED Viewed

@@ -0,0 +1,142 @@
+<!doctype html>
+<html lang="vi">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Team nên dùng như một chuẩn vận hành · Pi Agent Platform Docs</title>
+    <meta name="description" content="Mỗi repo chỉ cần link package, chọn profile đúng và giữ tài liệu project-specific ở repo của dự án đó." />
+    <meta name="theme-color" content="#050505" />
+    <link rel="canonical" href="https://piagent.io.vn/team" />
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+    <meta property="og:title" content="Team nên dùng như một chuẩn vận hành · Pi Agent Platform Docs" />
+    <meta property="og:description" content="Mỗi repo chỉ cần link package, chọn profile đúng và giữ tài liệu project-specific ở repo của dự án đó." />
+    <meta property="og:url" content="https://piagent.io.vn/team" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Be+Vietnam+Pro:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap"
+      rel="stylesheet"
+    />
+    <link rel="stylesheet" href="/assets/docs.css" />
+    <script src="/assets/docs.js" defer></script>
+  </head>
+  <body>
+    <header class="topbar">
+      <a class="brand" href="/" aria-label="Pi Agent Platform">
+        <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" /></span>
+        <span>Pi Agent Platform</span>
+      </a>
+      <div class="top-actions">
+        <span class="pill"><span class="pill-dot"></span>v1.2.1 docs</span>
+        <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
+          <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
+            <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+          </svg>
+          GitHub
+        </a>
+        <button class="button mobile-menu" type="button" data-menu>Lộ trình</button>
+        <a class="button" href="/commands">Commands</a>
+      </div>
+    </header>
+    <div class="layout with-toc">
+      <aside class="sidebar" data-sidebar>
+        <div class="sidebar-search" aria-label="Tìm trong tài liệu">
+          <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
+            <path d="M10.8 18.1a7.3 7.3 0 1 1 0-14.6 7.3 7.3 0 0 1 0 14.6Zm5.3-1.7 4.4 4.4" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
+          </svg>
+          <input type="search" placeholder="Tìm trang" data-filter />
+        </div>
+        <nav aria-label="Tài liệu">
+          <div class="nav-group">
+            <p class="nav-title">Get started</p>
+            <a class="nav-link" href="/">Overview</a>
+            <a class="nav-link" href="/quickstart">Quickstart</a>
+            <a class="nav-link" href="/scope">Phạm vi platform</a>
+          </div>
+          <div class="nav-group">
+            <p class="nav-title">Build</p>
+            <a class="nav-link" href="/profiles">Project profile</a>
+            <a class="nav-link" href="/permissions">Permission modes</a>
+            <a class="nav-link" href="/commands">Command catalog</a>
+            <a class="nav-link" href="/workflows">Workflows</a>
+          </div>
+          <div class="nav-group">
+            <p class="nav-title">MCP</p>
+            <a class="nav-link" href="/mcp">MCP overview</a>
+            <a class="nav-link" href="/mcp-servers">Quản lý server</a>
+            <a class="nav-link" href="/mcp-auth">Auth và readiness</a>
+            <a class="nav-link" href="/mcp-approval">Approval gate</a>
+          </div>
+          <div class="nav-group">
+            <p class="nav-title">Operate</p>
+            <a class="nav-link" href="/security">Security model</a>
+            <a class="nav-link" href="/architecture">Architecture</a>
+            <a class="nav-link" href="/runtime">Runtime tools</a>
+            <a class="nav-link current" href="/team" aria-current="page">Team usage</a>
+          </div>
+        </nav>
+      </aside>
+      <main>
+        <div class="content-shell" data-article>
+            <nav class="breadcrumb" aria-label="Breadcrumb">
+              <a href="/">Docs</a>
+              <span aria-hidden="true">/</span>
+              <span>Operate</span>
+              <span aria-hidden="true">/</span>
+              <span>Team usage</span>
+            </nav>
+            <div class="page-head">
+              <h1>Team nên dùng như một chuẩn vận hành</h1>
+              <p>Mỗi repo chỉ cần link package, chọn profile đúng và giữ tài liệu project-specific ở repo của dự án đó.</p>
+            </div>
+<section class="section">
+  <div class="split">
+    <article class="card">
+      <h3 id="viec-nen-lam">Việc nên làm</h3>
+      <p>Chạy <span class="inline-code">/onboard-project</span>, áp <span class="inline-code">/profile auto</span>, dùng workflow command, verify thật và ghi blockers rõ ràng.</p>
+    </article>
+    <article class="card">
+      <h3 id="viec-nen-tranh">Việc nên tránh</h3>
+      <p>Đưa token, auth file, cache, session, private examples hoặc business logic riêng vào core package public.</p>
+    </article>
+  </div>
+  <div class="callout ok-callout">
+    <strong>Chuẩn handoff</strong>
+    <p>Final response nên nói ngắn: đã đổi gì, verify nào đã chạy, có dùng subagent không, và còn rủi ro hoặc next step nào cần người review.</p>
+  </div>
+  <div class="callout">
+    <strong>Release docs gate</strong>
+    <p>Version docs mới chỉ được promote lên Vercel sau khi tag-triggered CI pass và stable dry-run resolve đúng commit SHA. Phải promote đúng tagged commit, không chèn merge commit hay docs-only edit khác. Domain canonical là <span class="inline-code">piagent.io.vn</span>; apex phải là Vercel primary và <span class="inline-code">www</span> redirect về apex.</p>
+  </div>
+</section>
+            <nav class="pager" aria-label="Trang kế tiếp">
+              <a class="pager-prev" href="/runtime">
+                <span class="pager-label">Trước</span>
+                <span class="pager-title">Runtime tools</span>
+              </a>
+            </nav>
+            <footer class="footer">
+              <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
+              <div class="footer-links" aria-label="External links">
+                <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
+                <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
+                <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
+              </div>
+            </footer>
+        </div>
+      </main>
+      <aside class="toc" aria-label="Mục lục trang">
+        <p class="toc-title">Trên trang này</p>
+        <nav data-toc></nav>
+      </aside>
+    </div>
+  </body>
+</html>

package/docs-site/workflows.html ADDED Viewed

@@ -0,0 +1,170 @@
+<!doctype html>
+<html lang="vi">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Các luồng chính · Pi Agent Platform Docs</title>
+    <meta name="description" content="Chọn workflow theo intent thay vì mô tả lại policy trong prompt. Cách này giảm context lãng phí và giữ hành vi nhất quán." />
+    <meta name="theme-color" content="#050505" />
+    <link rel="canonical" href="https://piagent.io.vn/workflows" />
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+    <meta property="og:title" content="Các luồng chính · Pi Agent Platform Docs" />
+    <meta property="og:description" content="Chọn workflow theo intent thay vì mô tả lại policy trong prompt. Cách này giảm context lãng phí và giữ hành vi nhất quán." />
+    <meta property="og:url" content="https://piagent.io.vn/workflows" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Be+Vietnam+Pro:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap"
+      rel="stylesheet"
+    />
+    <link rel="stylesheet" href="/assets/docs.css" />
+    <script src="/assets/docs.js" defer></script>
+  </head>
+  <body>
+    <header class="topbar">
+      <a class="brand" href="/" aria-label="Pi Agent Platform">
+        <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" /></span>
+        <span>Pi Agent Platform</span>
+      </a>
+      <div class="top-actions">
+        <span class="pill"><span class="pill-dot"></span>v1.2.1 docs</span>
+        <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
+          <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
+            <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+          </svg>
+          GitHub
+        </a>
+        <button class="button mobile-menu" type="button" data-menu>Lộ trình</button>
+        <a class="button" href="/commands">Commands</a>
+      </div>
+    </header>
+    <div class="layout with-toc">
+      <aside class="sidebar" data-sidebar>
+        <div class="sidebar-search" aria-label="Tìm trong tài liệu">
+          <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
+            <path d="M10.8 18.1a7.3 7.3 0 1 1 0-14.6 7.3 7.3 0 0 1 0 14.6Zm5.3-1.7 4.4 4.4" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
+          </svg>
+          <input type="search" placeholder="Tìm trang" data-filter />
+        </div>
+        <nav aria-label="Tài liệu">
+          <div class="nav-group">
+            <p class="nav-title">Get started</p>
+            <a class="nav-link" href="/">Overview</a>
+            <a class="nav-link" href="/quickstart">Quickstart</a>
+            <a class="nav-link" href="/scope">Phạm vi platform</a>
+          </div>
+          <div class="nav-group">
+            <p class="nav-title">Build</p>
+            <a class="nav-link" href="/profiles">Project profile</a>
+            <a class="nav-link" href="/permissions">Permission modes</a>
+            <a class="nav-link" href="/commands">Command catalog</a>
+            <a class="nav-link current" href="/workflows" aria-current="page">Workflows</a>
+          </div>
+          <div class="nav-group">
+            <p class="nav-title">MCP</p>
+            <a class="nav-link" href="/mcp">MCP overview</a>
+            <a class="nav-link" href="/mcp-servers">Quản lý server</a>
+            <a class="nav-link" href="/mcp-auth">Auth và readiness</a>
+            <a class="nav-link" href="/mcp-approval">Approval gate</a>
+          </div>
+          <div class="nav-group">
+            <p class="nav-title">Operate</p>
+            <a class="nav-link" href="/security">Security model</a>
+            <a class="nav-link" href="/architecture">Architecture</a>
+            <a class="nav-link" href="/runtime">Runtime tools</a>
+            <a class="nav-link" href="/team">Team usage</a>
+          </div>
+        </nav>
+      </aside>
+      <main>
+        <div class="content-shell" data-article>
+            <nav class="breadcrumb" aria-label="Breadcrumb">
+              <a href="/">Docs</a>
+              <span aria-hidden="true">/</span>
+              <span>Build</span>
+              <span aria-hidden="true">/</span>
+              <span>Workflows</span>
+            </nav>
+            <div class="page-head">
+              <h1>Các luồng chính</h1>
+              <p>Chọn workflow theo intent thay vì mô tả lại policy trong prompt. Cách này giảm context lãng phí và giữ hành vi nhất quán.</p>
+            </div>
+<section class="section">
+  <div class="callout ok-callout">
+    <strong>Git trong Pi Agent</strong>
+    <p>Không có namespace <span class="inline-code">/git</span> riêng. Dùng <span class="inline-code">/commit</span> để commit local đã review, dùng <span class="inline-code">/pr</span> để chuẩn bị PR. Các hành động như <span class="inline-code">git push</span> hoặc stage rộng <span class="inline-code">git add -A</span> vẫn cần operator xác nhận.</p>
+  </div>
+  <div class="callout">
+    <strong>Solo-first orchestration</strong>
+    <p>Dùng <span class="inline-code">/piagent-orchestration</span> để xem mode, max subagents, review lenses, Field Guide và writer policy. Mặc định parent agent tự làm chính; subagents chỉ dùng khi scout, planning hoặc review có lane độc lập đáng token.</p>
+  </div>
+  <div class="command-grid">
+    <article class="command-card">
+      <header><span>Implementation bounded</span><button class="clip-btn" data-clip="/task Fix the failing checkout test and verify.">Lấy lệnh</button></header>
+      <pre><code>/task Fix the failing checkout test and verify.</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Read-only scout</span><button class="clip-btn" data-clip="/scout Map the auth flow and risk areas.">Lấy lệnh</button></header>
+      <pre><code>/scout Map the auth flow and risk areas.</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Plan trước khi code</span><button class="clip-btn" data-clip="/plan Add multi-tenant billing support.">Lấy lệnh</button></header>
+      <pre><code>/plan Add multi-tenant billing support.</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Review diff</span><button class="clip-btn" data-clip="/review">Lấy lệnh</button></header>
+      <pre><code>/review</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Commit local có guard</span><button class="clip-btn" data-clip="/commit &quot;feat: add guarded git workflow&quot;">Lấy lệnh</button></header>
+      <pre><code>/commit "feat: add guarded git workflow"</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Chuẩn bị pull request</span><button class="clip-btn" data-clip="/pr &quot;Prepare PR for guarded git workflow&quot;">Lấy lệnh</button></header>
+      <pre><code>/pr "Prepare PR for guarded git workflow"</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Backend spec sang frontend</span><button class="clip-btn" data-clip="/be-to-fe Implement frontend support for the new user status endpoint.">Lấy lệnh</button></header>
+      <pre><code>/profile be-readonly-fe
+/be-to-fe Implement frontend support for the new user status endpoint.</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Cải thiện platform</span><button class="clip-btn" data-clip="/platform-improve Harden command docs and run verification.">Lấy lệnh</button></header>
+      <pre><code>/platform-improve Harden command docs and run verification.</code></pre>
+    </article>
+  </div>
+</section>
+            <nav class="pager" aria-label="Trang kế tiếp">
+              <a class="pager-prev" href="/commands">
+                <span class="pager-label">Trước</span>
+                <span class="pager-title">Command catalog</span>
+              </a>
+              <a class="pager-next" href="/mcp">
+                <span class="pager-label">Tiếp</span>
+                <span class="pager-title">MCP overview</span>
+              </a>
+            </nav>
+            <footer class="footer">
+              <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
+              <div class="footer-links" aria-label="External links">
+                <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
+                <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
+                <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
+              </div>
+            </footer>
+        </div>
+      </main>
+      <aside class="toc" aria-label="Mục lục trang">
+        <p class="toc-title">Trên trang này</p>
+        <nav data-toc></nav>
+      </aside>
+    </div>
+  </body>
+</html>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/platform",
-  "version": "1.1.9",
+  "version": "1.2.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -117,13 +117,15 @@
     "audit:runtime": "bash scripts/audit-runtime-host.sh",
     "release:identity": "node scripts/verify-release-identity.mjs",
     "vercel:preflight": "node scripts/verify-vercel-link.mjs",
+    "site:build": "node scripts/build-docs-site.mjs",
+    "site:preview": "node scripts/preview-docs-site.mjs",
     "site:check": "node scripts/check-published-site.mjs",
     "smoke": "bash scripts/runtime-policy-smoke.sh",
     "usage": "bash scripts/pi-session-stats.sh",
     "auto": "bash scripts/pi-auto.sh",
     "models": "bash scripts/pi-model-catalog.sh",
     "model-scope": "bash scripts/configure-model-scope.sh",
-    "mcp": "bash scripts/configure-mcp.sh",
+    "mcp": "node scripts/mcp-manage.mjs",
     "subagents": "bash scripts/configure-subagents.sh",
     "capabilities:check": "node scripts/capability-catalog.mjs catalog --check",
     "capabilities:catalog": "node scripts/capability-catalog.mjs catalog --write",

package/packages/piagent-core/capabilities/capability-core.js CHANGED Viewed

@@ -238,8 +238,13 @@ export function validateCapabilityPack(document, options = {}) {
     if (rejectUnknownKeys(spec.activation, new Set(["mode", "profiles", "triggers"]), `${source}.spec.activation`, errors)) {
       if (!ACTIVATION_MODES.has(spec.activation.mode)) pushError(errors, `${source}.spec.activation.mode`, "must be explicit, profile, or trigger");
-      validateStringArray(spec.activation.profiles ?? [], `${source}.spec.activation.profiles`, errors, { maxItems: 64, pattern: NAME_PATTERN });
+      const profiles = validateStringArray(spec.activation.profiles ?? [], `${source}.spec.activation.profiles`, errors, { maxItems: 64, pattern: NAME_PATTERN });
       const triggers = validateStringArray(spec.activation.triggers ?? [], `${source}.spec.activation.triggers`, errors, { maxItems: 64 });
+      // Both modes name the thing that switches them on, so both are checked for
+      // it. Only `trigger` was, which let a pack declare profile activation and
+      // list no profiles: resolution then read `.includes` off an absent array
+      // and died with a TypeError where it should have refused with a reason.
+      if (spec.activation.mode === "profile" && profiles.length === 0) pushError(errors, `${source}.spec.activation.profiles`, "must not be empty for profile activation");
       if (spec.activation.mode === "trigger" && triggers.length === 0) pushError(errors, `${source}.spec.activation.triggers`, "must not be empty for trigger activation");
     }
@@ -808,7 +813,23 @@ function buildCoreIntegrity(root) {
     // for a different reason: it starts a process on session start and puts a
     // line in the operator's terminal, so tampering with it buys code execution
     // and a message the operator has been trained to trust.
-    "packages/piagent-core/extensions/update-check.js"
+    "packages/piagent-core/extensions/update-check.js",
+    // The MCP files decide which servers a session may call. mcp-approval-store.js
+    // holds the decision itself, mcp-auth-readiness.js turns it into the verdict
+    // the guard acts on, and mcp-config-layers.js says which layers a repository
+    // can reach and therefore which servers the gate covers at all. Editing any of
+    // the three turns off the gate that stops a cloned repository from running its
+    // own MCP server here.
+    "packages/piagent-core/mcp/mcp-approval-store.js",
+    "packages/piagent-core/mcp/mcp-auth-readiness.js",
+    "packages/piagent-core/mcp/mcp-config-layers.js",
+    // mcp-session-view.js reports which servers are approved and which are not,
+    // and mcp-command-actions.js is what `/piagent-mcp approve` runs. An
+    // operator decides based on the definition these two put in front of them,
+    // so a file that can lie about what a server runs is a way to collect a
+    // decision that was never really made.
+    "packages/piagent-core/mcp/mcp-session-view.js",
+    "packages/piagent-core/mcp/mcp-command-actions.js"
   ];
   return files.map((relativePath) => {
     const resolved = resolveRegularFile(root, relativePath, MAX_ARTIFACT_BYTES);
@@ -843,7 +864,10 @@ export function resolveCapabilityProfileDocument(root, profile, options = {}) {
     const key = `${selector.name}@${selector.version}`;
     const directPack = byKey.get(key);
     if (!directPack) throw new CapabilityValidationError(`profile selects unknown capability pack ${key}`);
-    if (directPack.activation.mode === "profile" && !directPack.activation.profiles.includes(profile.mode)) throw new CapabilityValidationError(`${key} is not enabled for profile mode ${profile.mode}`);
+    // Defaulted rather than assumed present. The validator now requires the list
+    // for this mode, but this line runs against whatever is on disk, and reading
+    // through to a TypeError would turn a refusal into a crash.
+    if (directPack.activation.mode === "profile" && !(directPack.activation.profiles ?? []).includes(profile.mode)) throw new CapabilityValidationError(`${key} is not enabled for profile mode ${profile.mode}`);
     select(key);
   }
@@ -979,22 +1003,51 @@ export function resolveCapabilityProfile(root, profilePath, options = {}) {
 const GRANTING_PERMISSIONS = ["capabilities", "filesystemRead", "filesystemWrite", "networkDomains", "externalActions"];
 const RESTRICTING_PERMISSIONS = ["protectedPaths", "readOnlyPaths", "shellProtectedPaths"];
+// Everything above is about artifacts the platform ships. A pack vendored from
+// somewhere else is a different question, and gets a different answer.
+//
+// None of the reasons for leaving artifact content on the build side apply to
+// it. Its bytes change when that source decides they change, not when this
+// project updates. The manifest digest pins which artifacts a pack declares, not
+// what is in them, so a rewritten prompt or policy file keeps the same manifest.
+// And the argument that the platform can rewrite its own verifier is an argument
+// about the platform: an external source cannot, which is exactly why its
+// content is worth pinning. Prompts and policy files are what a hostile source
+// would edit, and it would rather not be asked again.
+//
+// `workspace` is the platform's own origin and is a reserved source name, so a
+// vendored source cannot claim it.
+function externalArtifacts(document) {
+  const external = new Set(
+    (document?.packs ?? [])
+      .filter((pack) => pack?.origin && pack.origin !== "workspace")
+      .map((pack) => `${pack.name}@${pack.version}`)
+  );
+  if (external.size === 0) return undefined;
+  return (document?.artifacts ?? []).filter((artifact) => external.has(artifact?.pack));
+}
 function consentedShape(document) {
   return {
     schemaVersion: document?.schemaVersion,
     apiVersion: document?.core?.apiVersion,
     packageSource: document?.core?.packageSource,
     profile: document?.profile,
-    packs: document?.packs
+    packs: document?.packs,
+    externalArtifacts: externalArtifacts(document)
   };
 }
+const CONSENT_DRIFT_REASONS = {
+  externalArtifacts: "an artifact shipped by a vendored capability source changed content"
+};
 function consentDrift(expected, actual) {
   const before = consentedShape(actual);
   const after = consentedShape(expected);
   return Object.keys(after)
     .filter((key) => stableJson(after[key]) !== stableJson(before[key]))
-    .map((key) => `${key} no longer matches the locked value`);
+    .map((key) => CONSENT_DRIFT_REASONS[key] ?? `${key} no longer matches the locked value`);
 }
 function permissionDrift(expected, actual) {

package/packages/piagent-core/capabilities/capability-sources.js CHANGED Viewed

@@ -110,6 +110,39 @@ function assertContainedDirectory(projectRoot, target, label) {
   return targetReal;
 }
+/**
+ * Verify a path this code is about to create, empty or write sits inside the
+ * project, without requiring it to exist yet.
+ *
+ * The read path can lstat its target and be done with it. A write path cannot:
+ * the destination is normally absent, and the failure that matters is an
+ * *ancestor* leading somewhere else. A repository shipping `.pi` as a symlink is
+ * the whole attack — `mkdir -p` follows it, the directory that appears below is
+ * a real directory, so a check on the immediate parent sees nothing wrong, and
+ * the recursive delete that comes next lands outside the project.
+ *
+ * @param {string} rootReal a project root already through realpath
+ * @param {string} target
+ * @param {string} label
+ */
+function assertContainedWritePath(rootReal, target, label) {
+  const relative = path.relative(rootReal, path.resolve(rootReal, target));
+  if (relative.startsWith("..") || path.isAbsolute(relative)) fail(`${label} resolves outside the project`);
+  let current = rootReal;
+  for (const segment of relative.split(path.sep)) {
+    if (!segment) continue;
+    current = path.join(current, segment);
+    let stat;
+    try {
+      stat = fs.lstatSync(current);
+    } catch {
+      // Absent from here down, so there is nothing further to follow.
+      return;
+    }
+    if (stat.isSymbolicLink()) fail(`${label} must not resolve through a symbolic link (${segment})`);
+  }
+}
 function assertNoSymbolicLinks(root, label, budget = { remaining: MAX_VENDOR_ENTRIES }) {
   for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
     if (budget.remaining-- <= 0) fail(`${label} contains more than ${MAX_VENDOR_ENTRIES} entries`);
@@ -212,27 +245,55 @@ export function vendorRemoteSource(projectRoot, entry) {
   const [validated] = validateCapabilitySources([entry]);
   if (!validated.source) fail(`capability source ${validated.name} is a local path and does not need vendoring`);
-  const destination = vendorDirectoryFor(projectRoot, validated.name);
+  // Resolved the same way the read path resolves it, so the containment check
+  // below compares two paths of the same form.
+  const rootReal = fs.realpathSync(projectRoot);
+  const destination = vendorDirectoryFor(rootReal, validated.name);
+  const label = `capability source ${validated.name}`;
+  // Before anything is created and well before anything is removed: every call
+  // after this line writes or deletes, and the point of the check is to have
+  // happened first.
+  assertContainedWritePath(rootReal, destination, label);
   const parent = path.dirname(destination);
   fs.mkdirSync(parent, { recursive: true, mode: 0o755 });
-  if (fs.lstatSync(parent).isSymbolicLink()) fail(`${parent} must not be a symbolic link`);
-  fs.rmSync(destination, { recursive: true, force: true });
-  fs.mkdirSync(destination, { mode: 0o755 });
+  // Re-checked after the directories exist. The first pass ran against a path
+  // that was mostly absent, so it proved nothing about the components this call
+  // just created or about one swapped underneath in between.
+  assertContainedWritePath(rootReal, destination, label);
+  // Fetched beside the destination and moved into place at the end, so a fetch
+  // that fails leaves the reviewed tree that was already there. Emptying the
+  // destination first meant a network error or a hostile archive destroyed a
+  // working vendor directory and left the project with neither version.
+  const staging = `${destination}.incoming.${process.pid}`;
+  assertContainedWritePath(rootReal, staging, label);
+  for (const sibling of fs.readdirSync(parent)) {
+    // Debris from a run that died between creating this and moving it.
+    if (sibling.startsWith(`${validated.name}.incoming.`)) fs.rmSync(path.join(parent, sibling), { recursive: true, force: true });
+  }
+  fs.mkdirSync(staging, { mode: 0o755 });
   try {
-    if (validated.source.startsWith("npm:")) fetchNpmSource(validated.source.slice("npm:".length), destination);
-    else fetchGitSource(validated.source, destination);
+    if (validated.source.startsWith("npm:")) fetchNpmSource(validated.source.slice("npm:".length), staging);
+    else fetchGitSource(validated.source, staging);
     // The fetched tree is untrusted until this passes. Checking here means a
-    // hostile archive is rejected before anything reads a manifest out of it.
-    assertNoSymbolicLinks(destination, `capability source ${validated.name}`);
-    if (!fs.existsSync(path.join(destination, "packs"))) {
+    // hostile archive is rejected before anything reads a manifest out of it,
+    // and before it can replace the tree already in place.
+    assertNoSymbolicLinks(staging, `capability source ${validated.name}`);
+    if (!fs.existsSync(path.join(staging, "packs"))) {
       fail(`capability source ${validated.name} provides no packs directory`);
     }
-  } catch (error) {
-    // A half-written vendor directory would resolve on the next run and hide
-    // the failure, so remove it.
+    // Everything above succeeded, so the old tree can go.
     fs.rmSync(destination, { recursive: true, force: true });
+    fs.renameSync(staging, destination);
+  } catch (error) {
+    // Only the half-written fetch is removed. The destination is either
+    // untouched, because the failure happened before the swap, or already
+    // replaced by a tree that passed every check.
+    fs.rmSync(staging, { recursive: true, force: true });
     throw error;
   }

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

@@ -13,11 +13,11 @@ import zlib from "node:zlib";
 // operator has to copy files into the repository just to be read, which is how
 // vendor PDFs end up committed.
 //
-// Both reference CLIs treat read as the permissive axis and write as the scoped
-// one: Claude Code grants extra directories through `additionalDirectories` and
-// `--add-dir` and then reads them without prompting, and Codex scopes
-// `writable_roots` while leaving reads broad. This follows that shape with one
-// extra restriction — inside a granted root only document extensions open, so
+// The established shape for agent CLIs is to treat read as the permissive axis
+// and write as the scoped one: extra directories are granted and then read
+// without prompting, while the set of writable roots stays narrow. This follows
+// that shape with one extra restriction — inside a granted root only document
+// extensions open, so
 // granting ~/Downloads does not also hand over an installer or a key file that
 // happens to be sitting there.
 //