BuilderIO · RogierKonings · Jul 29, 2026 · Jul 29, 2026 · Jul 29, 2026 · Jul 29, 2026
diff --git a/.changeset/local-pi-app-chat.md b/.changeset/local-pi-app-chat.md
@@ -0,0 +1,5 @@
+---
+"@agent-native/core": minor
+---
+
+Add an optional full-harness execution path for app chat, including scoped session resume, approval-safe host actions, and a local Pi adapter that reuses Pi-owned configuration without copying OAuth credentials.
diff --git a/packages/core/docs/content/harness-agents.mdx b/packages/core/docs/content/harness-agents.mdx
@@ -92,20 +92,64 @@ spawn background / sub-agent runs with [Custom Agents & Teams](/docs/agent-teams
 ## Built-in harnesses {#built-in}
 
 `registerBuiltinAgentHarnesses()` registers three adapters backed by the AI SDK
-`HarnessAgent`:
+`HarnessAgent`, plus a direct local Pi adapter:
 
 | Name                         | Runtime     | Sandbox | Approvals |
 | ---------------------------- | ----------- | ------- | --------- |
 | `ai-sdk-harness:claude-code` | Claude Code | yes     | yes       |
 | `ai-sdk-harness:codex`       | Codex       | yes     | no        |
-| `ai-sdk-harness:pi`          | Pi          | no      | yes       |
+| `ai-sdk-harness:pi`          | Pi          | yes     | yes       |
+| `pi:local`                   | Local Pi    | no      | no        |
 
 Their runtime packages are **optional peer dependencies** and load lazily, so an
 app that never uses a harness does not pay for it. Each adapter carries an
-`installPackage` hint (for example `@ai-sdk/harness@canary
-@ai-sdk/harness-codex@canary`); `resolveAgentHarness` throws a clear install
-error if the packages are missing, and `isAgentHarnessPackageInstalled(entry)`
-lets you check first.
+`installPackage` hint; `resolveAgentHarness` throws a clear install error if the
+packages are missing, and `isAgentHarnessPackageInstalled(entry)` lets you check
+first.
+
+### Local Pi app chat {#local-pi-app-chat}
+
+`pi:local` runs `@earendil-works/pi-coding-agent` in the app's local Node
+process. It uses Pi's normal agent directory (by default `~/.pi/agent`) so Pi
+owns model selection and OAuth refresh. Agent-Native never reads, copies, logs,
+or stores Pi's auth file; SQL stores only the opaque Pi session-file reference
+needed to resume the thread.
+
+Install the optional runtime package, authenticate Pi once, and configure the
+normal agent-chat plugin with an explicit fail-closed local-development guard:
+
+```bash
+pnpm add @earendil-works/pi-coding-agent
+pi
+```
+
+In Pi, run `/login` and choose **OpenAI ChatGPT Plus/Pro (Codex)**.
+
+```ts
+createAgentChatPlugin({
+  harness: {
+    adapter: { name: "pi:local" },
+    cwd: process.cwd(),
+    permissionMode: "allow-edits",
+    guard: (event) => isTrustedLocalPiRequest(event),
+  },
+});
+```
+
+`isTrustedLocalPiRequest` is deliberately host-owned: require development mode
+and a verified loopback/localhost request. A denial must return false (or a
+structured 403/503 decision); it never falls back to an API-billed engine.
+`pi:local` exposes read-only Pi filesystem tools by default and routes app
+operations through the request-filtered Agent-Native action tools. In
+`allow-reads` mode, only actions explicitly marked read-only are exposed. The
+adapter currently has no native approval continuation, so actions that declare
+`needsApproval` fail closed rather than running. Harness app chat is foreground
+only, does not accept attachments yet, and is intended for a trusted single-user
+local process—not serverless or shared hosting.
+
+`ai-sdk-harness:pi` is the sandboxed AI SDK adapter. It requires a
+`HarnessV1SandboxProvider` and does not implicitly reuse local Pi OAuth; use
+`pi:local` when the goal is to reuse the user's existing Pi setup.
 
 `registerBuiltinAgentHarnesses()` also registers the [ACP](#acp) harnesses
 (`acp`, `acp:gemini`, `acp:claude-code`).

diff --git a/packages/core/docs/content/locales/ar-SA/harness-agents.mdx b/packages/core/docs/content/locales/ar-SA/harness-agents.mdx
@@ -94,14 +94,14 @@ UI مع [`AgentChatRuntime`](/docs/native-chat-ui#byo-agent-runtimes)؛ دع
 | ---------------------------- | ----------- | ----------- | --------- |
 | `ai-sdk-harness:claude-code` | رمز Claude  | نعم         | نعم       |
 | `ai-sdk-harness:codex`       | Codex       | نعم         | لا        |
-| `ai-sdk-harness:pi`          | باي         | لا          | نعم       |
-
-حزم وقت التشغيل الخاصة بها هي **تبعيات نظير اختيارية** ويتم تحميلها ببطء، لذا
-التطبيق الذي لا يستخدم أداة التثبيت مطلقًا لا يدفع ثمنه. يحمل كل محول
-تلميح `installPackage` (على سبيل المثال `@ai-sdk/harness@canary
-@ai-sdk/harness-codex@canary`); `resolveAgentHarness` يُجري تثبيتًا واضحًا
-خطأ إذا كانت الحزم مفقودة، و`isAgentHarnessPackageInstalled(entry)`
-يتيح لك التحقق أولاً.
+| `ai-sdk-harness:pi`          | Pi          | نعم         | نعم       |
+| `pi:local`                   | Pi محلي     | لا          | لا        |
+
+حزم التشغيل هي **تبعيات نظير اختيارية** تُحمّل عند الطلب. يعرض `resolveAgentHarness` تلميح التثبيت عند غياب الحزمة.
+
+### Pi المحلي في دردشة التطبيق {#local-pi-app-chat}
+
+يشغّل `pi:local` الحزمة `@earendil-works/pi-coding-agent` داخل عملية Node المحلية ويستخدم افتراضيًا دليل Pi المعتاد `~/.pi/agent`. يبقى اختيار النموذج وOAuth تحت إدارة Pi؛ ولا يقرأ Agent-Native ملف المصادقة أو ينسخه أو يخزنه، بينما تحفظ SQL مرجع الجلسة المعتم فقط. فعّله فقط مع حارس صريح مغلق افتراضيًا يتحقق من وضع التطوير وloopback. يعمل في المقدمة فقط، ويرفض المرفقات حاليًا، وتفشل إجراءات `needsApproval` بأمان. أما `ai-sdk-harness:pi` فهو محول sandbox ولا يعيد استخدام تسجيل دخول Pi المحلي تلقائيًا.
 
 يسجل `registerBuiltinAgentHarnesses()` أيضًا أحزمة [ACP](#acp)
 (`acp`, `acp:gemini`, `acp:claude-code`).

diff --git a/packages/core/docs/content/locales/de-DE/harness-agents.mdx b/packages/core/docs/content/locales/de-DE/harness-agents.mdx
@@ -94,14 +94,14 @@ Spawn-Hintergrund/Subagent läuft mit [Custom Agents & Teams](/docs/agent-teams)
 | ---------------------------- | ----------- | ------- | ------------- |
 | `ai-sdk-harness:claude-code` | Claude-Code | Ja      | Ja            |
 | `ai-sdk-harness:codex`       | Codex       | Ja      | nein          |
-| `ai-sdk-harness:pi`          | Pi          | nein    | Ja            |
-
-Ihre Laufzeitpakete sind **optionale Peer-Abhängigkeiten** und werden träge geladen, also ein
-Apps, die niemals ein Geschirr verwenden, zahlen nicht dafür. Jeder Adapter trägt eine
-`installPackage`-Hinweis (zum Beispiel „@ai-sdk/harness@canary“
-@ai-sdk/harness-codex@canary`); `resolveAgentHarness`löst eine klare Installation aus
-Fehler, wenn die Pakete fehlen, und`isAgentHarnessPackageInstalled(entry)`
-ermöglicht es Ihnen, zuerst zu prüfen.
+| `ai-sdk-harness:pi`          | Pi          | Ja      | Ja            |
+| `pi:local`                   | Lokales Pi  | nein    | nein          |
+
+Ihre Laufzeitpakete sind **optionale Peer-Abhängigkeiten** und werden verzögert geladen. `resolveAgentHarness` meldet fehlende Pakete mit einem Installationshinweis.
+
+### Lokales Pi im App-Chat {#local-pi-app-chat}
+
+`pi:local` führt `@earendil-works/pi-coding-agent` im lokalen Node-Prozess aus und verwendet standardmäßig das normale Pi-Agentenverzeichnis `~/.pi/agent`. Pi verwaltet Modellwahl und OAuth; Agent-Native liest, kopiert oder speichert die Auth-Datei nicht und speichert in SQL nur den undurchsichtigen Sitzungsverweis. Aktivieren Sie dies nur mit einem expliziten, fehlersicheren Guard für Entwicklung und Loopback. Der Lauf ist nur im Vordergrund, Anhänge werden noch abgelehnt und Aktionen mit `needsApproval` schlagen sicher fehl. `ai-sdk-harness:pi` bleibt der sandboxbasierte Adapter und übernimmt lokale Pi-Anmeldung nicht automatisch.
 
 `registerBuiltinAgentHarnesses()` registriert auch die [ACP](#acp)-Kabelbäume
 (`acp`, `acp:gemini`, `acp:claude-code`).

diff --git a/packages/core/docs/content/locales/es-ES/harness-agents.mdx b/packages/core/docs/content/locales/es-ES/harness-agents.mdx
@@ -94,14 +94,14 @@ El fondo generado/el subagente se ejecuta con [Custom Agents & Teams](/docs/agen
 | ---------------------------- | ------------------- | ------------- | ------------ |
 | `ai-sdk-harness:claude-code` | Código Claude       | sí            | sí           |
 | `ai-sdk-harness:codex`       | Codex               | sí            | no           |
-| `ai-sdk-harness:pi`          | Pi                  | no            | sí           |
-
-Sus paquetes de tiempo de ejecución son **dependencias de pares opcionales** y se cargan con pereza, por lo que
-la aplicación que nunca usa un arnés no paga por ello. Cada adaptador lleva un
-Pista `installPackage` (por ejemplo `@ai-sdk/harness@canary
-@ai-sdk/harness-codex@canary`); `resolveAgentHarness` genera una instalación clara
-error si faltan los paquetes y `isAgentHarnessPackageInstalled(entry)`
-te permite comprobarlo primero.
+| `ai-sdk-harness:pi`          | Pi                  | sí            | sí           |
+| `pi:local`                   | Pi local            | no            | no           |
+
+Sus paquetes de ejecución son **dependencias opcionales** y se cargan de forma diferida. `resolveAgentHarness` devuelve una indicación de instalación cuando falta un paquete.
+
+### Pi local en el chat de la aplicación {#local-pi-app-chat}
+
+`pi:local` ejecuta `@earendil-works/pi-coding-agent` en el proceso Node local y usa de forma predeterminada el directorio normal de Pi, `~/.pi/agent`. Pi conserva la selección de modelo y OAuth; Agent-Native nunca lee, copia ni almacena el archivo de autenticación y SQL solo guarda la referencia opaca de sesión. Actívalo únicamente con una protección explícita y cerrada por defecto para desarrollo y loopback. Solo funciona en primer plano, todavía rechaza adjuntos y las acciones con `needsApproval` fallan de forma segura. `ai-sdk-harness:pi` sigue siendo el adaptador con sandbox y no reutiliza automáticamente la sesión local de Pi.
 
 `registerBuiltinAgentHarnesses()` también registra los arneses [ACP](#acp)
 (`acp`, `acp:gemini`, `acp:claude-code`).

diff --git a/packages/core/docs/content/locales/fr-FR/harness-agents.mdx b/packages/core/docs/content/locales/fr-FR/harness-agents.mdx
@@ -94,14 +94,14 @@ apparaître en arrière-plan/sous-agent avec [Custom Agents & Teams](/docs/agent
 | ---------------------------- | ----------- | ----------- | ------------ |
 | `ai-sdk-harness:claude-code` | Code Claude | oui         | oui          |
 | `ai-sdk-harness:codex`       | Codex       | oui         | non          |
-| `ai-sdk-harness:pi`          | Pi          | non         | oui          |
-
-Leurs packages d'exécution sont des **dépendances homologues facultatives** et se chargent paresseusement, donc
-une application qui n'utilise jamais de harnais ne paie pas pour cela. Chaque adaptateur porte un
-Indice `installPackage` (par exemple `@ai-sdk/harness@canary
-@ai-sdk/harness-codex@canary`); `resolveAgentHarness` lance une installation claire
-erreur si les packages sont manquants, et `isAgentHarnessPackageInstalled(entry)`
-vous permet de vérifier en premier.
+| `ai-sdk-harness:pi`          | Pi          | oui         | oui          |
+| `pi:local`                   | Pi local    | non         | non          |
+
+Leurs paquets d’exécution sont des **dépendances homologues facultatives** chargées à la demande. `resolveAgentHarness` fournit une indication d’installation lorsqu’un paquet manque.
+
+### Pi local dans le chat de l’application {#local-pi-app-chat}
+
+`pi:local` exécute `@earendil-works/pi-coding-agent` dans le processus Node local et utilise par défaut le répertoire Pi normal, `~/.pi/agent`. Pi reste propriétaire du choix du modèle et d’OAuth ; Agent-Native ne lit, ne copie et ne stocke jamais le fichier d’authentification, et SQL ne conserve que la référence de session opaque. Activez-le uniquement avec une garde explicite et fermée par défaut pour le développement et le loopback. Il fonctionne seulement au premier plan, refuse encore les pièces jointes et les actions `needsApproval` échouent de façon sûre. `ai-sdk-harness:pi` reste l’adaptateur sandboxé et ne réutilise pas automatiquement la connexion Pi locale.
 
 `registerBuiltinAgentHarnesses()` enregistre également les harnais [ACP](#acp)
 (`acp`, `acp:gemini`, `acp:claude-code`).

diff --git a/packages/core/docs/content/locales/hi-IN/harness-agents.mdx b/packages/core/docs/content/locales/hi-IN/harness-agents.mdx
@@ -94,14 +94,14 @@ search: "हार्नेस एजेंट एजेंटहार्ने
 | ---------------------------- | ---------- | --------- | ------- |
 | `ai-sdk-harness:claude-code` | Claude कोड | हां       | हां     |
 | `ai-sdk-harness:codex`       | Codex      | हाँ       | नहीं    |
-| `ai-sdk-harness:pi`          | पी         | नहीं      | हाँ     |
-
-उनके रनटाइम पैकेज **वैकल्पिक सहकर्मी निर्भरता** हैं और आलस्य से लोड होते हैं, इसलिए एक
-ऐप जो कभी भी हार्नेस का उपयोग नहीं करता वह इसके लिए भुगतान नहीं करता है। प्रत्येक एडॉप्टर में एक
-`installPackage` संकेत (उदाहरण के लिए `@ai-sdk/harness@canary
-@ai-sdk/harness-codex@canary`); `resolveAgentHarness` एक स्पष्ट इंस्टॉल फेंकता है
-यदि पैकेज गायब हैं तो त्रुटि, और `isAgentHarnessPackageInstalled(entry)`
-आपको पहले जांच करने देता है।
+| `ai-sdk-harness:pi`          | Pi         | हाँ       | हाँ     |
+| `pi:local`                   | स्थानीय Pi | नहीं      | नहीं    |
+
+रनटाइम पैकेज मांग पर लोड होने वाली **वैकल्पिक पीयर निर्भरताएँ** हैं। पैकेज न मिलने पर `resolveAgentHarness` इंस्टॉल संकेत देता है।
+
+### ऐप चैट में स्थानीय Pi {#local-pi-app-chat}
+
+`pi:local` स्थानीय Node प्रक्रिया में `@earendil-works/pi-coding-agent` चलाता है और डिफ़ॉल्ट रूप से Pi की सामान्य डायरेक्टरी `~/.pi/agent` का उपयोग करता है। मॉडल चयन और OAuth Pi के नियंत्रण में रहते हैं; Agent-Native auth फ़ाइल को पढ़ता, कॉपी या संग्रहीत नहीं करता और SQL में केवल अपारदर्शी सत्र संदर्भ रहता है। इसे केवल विकास और loopback जाँचने वाले स्पष्ट fail-closed guard के साथ सक्षम करें। यह केवल foreground में चलता है, अभी attachments अस्वीकार करता है और `needsApproval` actions सुरक्षित रूप से विफल होते हैं। `ai-sdk-harness:pi` sandbox adapter है और स्थानीय Pi login को स्वतः पुनः उपयोग नहीं करता।
 
 `registerBuiltinAgentHarnesses()` [ACP](#acp) हार्नेस को भी पंजीकृत करता है
 (`acp`, `acp:gemini`, `acp:claude-code`).

diff --git a/packages/core/docs/content/locales/ja-JP/harness-agents.mdx b/packages/core/docs/content/locales/ja-JP/harness-agents.mdx
@@ -94,14 +94,14 @@ UI と [`AgentChatRuntime`](/docs/native-chat-ui#byo-agent-runtimes);させて
 | ---------------------------- | ------------- | -------------- | ------ |
 | `ai-sdk-harness:claude-code` | Claude コード | はい           | はい   |
 | `ai-sdk-harness:codex`       | Codex         | はい           | いいえ |
-| `ai-sdk-harness:pi`          | 円周率        | いいえ         | はい   |
-
-それらのランタイム パッケージは **オプションのピア依存関係**であり、遅延ロードされるため、
-ハーネスを使用しないアプリには料金がかかりません。各アダプターには、
-`installPackage` ヒント (例: `@ai-sdk/harness@canary
-@ai-sdk/harness-codex@canary`); `resolveAgentHarness` はクリア インストールをスローします
-パッケージが見つからない場合のエラー、および `isAgentHarnessPackageInstalled(entry)`
-最初に確認できます。
+| `ai-sdk-harness:pi`          | Pi            | はい           | はい   |
+| `pi:local`                   | ローカル Pi   | いいえ         | いいえ |
+
+ランタイム パッケージは遅延ロードされる**オプションのピア依存関係**です。パッケージがない場合、`resolveAgentHarness` はインストール方法を示します。
+
+### アプリチャットのローカル Pi {#local-pi-app-chat}
+
+`pi:local` はローカル Node プロセスで `@earendil-works/pi-coding-agent` を実行し、既定で通常の Pi ディレクトリ `~/.pi/agent` を使用します。モデル選択と OAuth は Pi が所有し、Agent-Native は認証ファイルを読み取り、コピー、保存しません。SQL には不透明なセッション参照だけを保存します。開発環境と loopback を検証する、明示的でフェイルクローズなガードがある場合だけ有効にしてください。フォアグラウンド専用で、添付ファイルはまだ拒否され、`needsApproval` アクションは安全に失敗します。`ai-sdk-harness:pi` は sandbox 用で、ローカル Pi ログインを自動再利用しません。
 
 `registerBuiltinAgentHarnesses()` は [ACP](#acp) ハーネスも登録します
 (`acp`, `acp:gemini`, `acp:claude-code`).

diff --git a/packages/core/docs/content/locales/ko-KR/harness-agents.mdx b/packages/core/docs/content/locales/ko-KR/harness-agents.mdx
@@ -94,14 +94,14 @@ UI 및 [`AgentChatRuntime`](/docs/native-chat-ui#byo-agent-runtimes); 하자
 | ---------------------------- | ----------- | ---------- | ---------- |
 | `ai-sdk-harness:claude-code` | Claude 코드 | 그렇습니다 | 그렇습니다 |
 | `ai-sdk-harness:codex`       | Codex       | 그렇습니다 | 아니요     |
-| `ai-sdk-harness:pi`          | 파이        | 아니요     | 그렇습니다 |
-
-런타임 패키지는 **선택적 피어 종속성**이며 느리게 로드되므로
-하네스를 전혀 사용하지 않는 앱은 비용을 지불하지 않습니다. 각 어댑터에는
-`installPackage` 힌트(예: `@ai-sdk/harness@canary
-@ai-sdk/harness-codex@canary`); `resolveAgentHarness`는 명확한 설치를 발생시킵니다.
-패키지가 누락된 경우 오류가 발생하고 `isAgentHarnessPackageInstalled(entry)`
-먼저 확인해 보세요.
+| `ai-sdk-harness:pi`          | Pi          | 예         | 예         |
+| `pi:local`                   | 로컬 Pi     | 아니요     | 아니요     |
+
+런타임 패키지는 요청 시 로드되는 **선택적 피어 종속성**입니다. 패키지가 없으면 `resolveAgentHarness`가 설치 힌트를 제공합니다.
+
+### 앱 채팅의 로컬 Pi {#local-pi-app-chat}
+
+`pi:local`은 로컬 Node 프로세스에서 `@earendil-works/pi-coding-agent`를 실행하고 기본적으로 Pi의 일반 디렉터리 `~/.pi/agent`를 사용합니다. 모델 선택과 OAuth는 Pi가 소유하며 Agent-Native는 인증 파일을 읽거나 복사하거나 저장하지 않습니다. SQL에는 불투명한 세션 참조만 저장됩니다. 개발 모드와 loopback을 확인하는 명시적인 fail-closed 가드가 있을 때만 활성화하세요. foreground 전용이며 아직 첨부 파일을 거부하고 `needsApproval` 작업은 안전하게 실패합니다. `ai-sdk-harness:pi`는 sandbox 어댑터이며 로컬 Pi 로그인을 자동으로 재사용하지 않습니다.
 
 `registerBuiltinAgentHarnesses()`는 [ACP](#acp) 하니스도 등록합니다
 (`acp`, `acp:gemini`, `acp:claude-code`).