@agent-native/core 0.101.4 → 0.101.6

package/README.md

@@ -91,7 +91,7 @@ Edit local Markdown/MDX files, generate rich interactive custom blocks, and draf
 
 <a href="https://agent-native.com/templates/analytics"><img src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F4933a80cc3134d7e874631f688be828a?format=webp&width=800" alt="Analytics app" width="100%" /></a>
 
-**Agent-Native Amplitude, Fullstory**
+**Open-Source Alternative to Amplitude and FullStory**
 
 Connect analytics data sources, prompt for real charts, and build reusable dashboards.
 

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 2258
-- template files: 5628
+- template files: 5635

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @agent-native/core
 
+## 0.101.6
+
+### Patch Changes
+
+- dd47e0a: Clarify how to add a UI later while preserving a headless app's shared action and data contract.
+
+## 0.101.5
+
+### Patch Changes
+
+- 9dd88f4: Opt the dedicated `get-code-execution` and `refresh-screen` volatile reads out of the duplicate read-only tool-call guard via the new `dedupe: false` action option while retaining default duplicate protection for normal `run-code` executions. Also raise `get-extension` and `get-extension-history-version` result caps to 500,000 and 2,000,000 characters respectively so JSON serialization overhead cannot slice mid-content and corrupt source reads for large extensions or their history.
+- 9dd88f4: Prevent repeated read-only tool loops while preserving trimmed results, allow volatile reads to opt out of deduping, and enforce notification webhook allowlists at the scope that supplied each secret.
+
 ## 0.101.4
 
 ### Patch Changes

package/corpus/core/docs/content/locales/ar-SA/pure-agent-apps.mdx

@@ -68,9 +68,9 @@ Automation-first app هو Agent-Native app بلا متصفح من أجل schedul
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## أضف الدردشة لاحقاً {#add-chat-later}
+## أضف واجهة مستخدم لاحقاً {#add-chat-later}
 
-يختار `--headless` السقالة الأولية فقط، ولا يوجد أمر `agent-native` يحوّل مشروعاً قائماً بلا واجهة إلى تطبيق دردشة في مكانه. عندما يحتاج الأشخاص إلى محادثة في المتصفح، استخدم [قالب Chat](/docs/template-chat) كمرجع للترحيل: احتفظ بالـ actions وبيانات SQL والتعليمات والمهارات، ثم أضف shell المتصفح وserver plugins و`<AgentChatSurface>` وplugin للدردشة يحمّل actions الحالية. تحقّق من `pnpm typecheck` ومن محادثة تستدعي action قائمة. استخدم `agent-native add` لمخططات التكامل، لا لهذا التحويل.
+يختار `--headless` السقالة الأولية فقط، ولا يوجد أمر `agent-native` يحوّل مشروعاً قائماً بلا واجهة إلى تطبيق متصفح في مكانه. عندما يحتاج الأشخاص إلى واجهة مستخدم، استخدم [قالب Chat](/docs/template-chat) كمرجع للترحيل: احتفظ بالـ actions وبيانات SQL والتعليمات والمهارات، ثم أضف shell المتصفح وserver plugins. وإذا كانت الواجهة محادثة، أضف `<AgentChatSurface>` وplugin للدردشة يحمّل actions الحالية. تحقّق من `pnpm typecheck` ومن تدفق واجهة يستدعي action قائمة. استخدم `agent-native add` لمخططات التكامل، لا لهذا التحويل.
 
 ## ما هي الخطوة التالية
 

package/corpus/core/docs/content/locales/de-DE/pure-agent-apps.mdx

@@ -70,9 +70,9 @@ Die Box, das Gerüst, der Repo-Zugriff und die Lauffreigabe sind jetzt an einem
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## Chat später hinzufügen {#add-chat-later}
+## Später eine UI hinzufügen {#add-chat-later}
 
-`--headless` wählt nur das anfängliche Scaffold; es gibt keinen `agent-native`-Befehl, der ein bestehendes action-only-Projekt direkt in eine Chat-App umwandelt. Wenn Menschen eine Browser-Unterhaltung brauchen, nutze das [Chat-Template](/docs/template-chat) als Migrationsreferenz: Behalte Actions, SQL-Daten, Anweisungen und Skills bei und übernimm Browser-Shell, Server-Plugins, `<AgentChatSurface>` sowie ein Chat-Plugin, das die vorhandenen Actions lädt. Prüfe `pnpm typecheck` und einen Chat-Turn, der eine vorhandene Action aufruft. `agent-native add` ist für Integrations-Blaupausen gedacht, nicht für diese Umwandlung.
+`--headless` wählt nur das anfängliche Scaffold; es gibt keinen `agent-native`-Befehl, der ein bestehendes action-only-Projekt direkt in eine Browser-App umwandelt. Wenn Menschen eine UI brauchen, nutze das [Chat-Template](/docs/template-chat) als Migrationsreferenz: Behalte Actions, SQL-Daten, Anweisungen und Skills bei und übernimm Browser-Shell und Server-Plugins. Für eine Chat-Oberfläche kommen `<AgentChatSurface>` und ein Chat-Plugin hinzu, das die vorhandenen Actions lädt. Prüfe `pnpm typecheck` und einen UI-Ablauf, der eine vorhandene Action aufruft. `agent-native add` ist für Integrations-Blaupausen gedacht, nicht für diese Umwandlung.
 
 ## Was kommt als nächstes
 

package/corpus/core/docs/content/locales/es-ES/pure-agent-apps.mdx

@@ -70,9 +70,9 @@ la caja, el andamio, el acceso al repositorio y el uso compartido de ejecuciones
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## Añade chat más adelante {#add-chat-later}
+## Añade una UI más adelante {#add-chat-later}
 
-`--headless` solo elige el scaffold inicial; no hay un comando de `agent-native` que convierta en el sitio un proyecto existente solo de acciones en una app de chat. Cuando las personas necesiten una conversación en el navegador, usa la [plantilla Chat](/docs/template-chat) como referencia de migración: conserva las actions, los datos SQL, las instrucciones y las skills, y añade el shell del navegador, los plugins de servidor, `<AgentChatSurface>` y un plugin de chat que cargue las actions existentes. Comprueba `pnpm typecheck` y un turno de chat que llame una action existente. `agent-native add` es para planos de integración, no para esta conversión.
+`--headless` solo elige el scaffold inicial; no hay un comando de `agent-native` que convierta en el sitio un proyecto existente solo de acciones en una app de navegador. Cuando las personas necesiten una UI, usa la [plantilla Chat](/docs/template-chat) como referencia de migración: conserva las actions, los datos SQL, las instrucciones y las skills, y añade el shell del navegador y los plugins de servidor. Para una superficie de chat, añade `<AgentChatSurface>` y un plugin de chat que cargue las actions existentes. Comprueba `pnpm typecheck` y un flujo de UI que llame una action existente. `agent-native add` es para planos de integración, no para esta conversión.
 
 ## ¿Qué sigue?
 

package/corpus/core/docs/content/locales/fr-FR/pure-agent-apps.mdx

@@ -68,9 +68,9 @@ la boîte, l'échafaudage, l'accès au dépôt et le partage d'exécution se tro
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## Ajouter le chat plus tard {#add-chat-later}
+## Ajouter une UI plus tard {#add-chat-later}
 
-`--headless` choisit seulement le scaffold initial ; aucune commande `agent-native` ne convertit directement un projet existant fondé uniquement sur des actions en application de chat. Quand les personnes ont besoin d'une conversation dans le navigateur, utilisez le [modèle Chat](/docs/template-chat) comme référence de migration : conservez les actions, les données SQL, les instructions et les skills, puis ajoutez le shell navigateur, les plugins serveur, `<AgentChatSurface>` et un plugin de chat qui charge les actions existantes. Vérifiez `pnpm typecheck` et un tour de chat appelant une action existante. `agent-native add` sert aux blueprints d'intégration, pas à cette conversion.
+`--headless` choisit seulement le scaffold initial ; aucune commande `agent-native` ne convertit directement un projet existant fondé uniquement sur des actions en application navigateur. Quand les personnes ont besoin d'une UI, utilisez le [modèle Chat](/docs/template-chat) comme référence de migration : conservez les actions, les données SQL, les instructions et les skills, puis ajoutez le shell navigateur et les plugins serveur. Pour une surface de chat, ajoutez `<AgentChatSurface>` et un plugin de chat qui charge les actions existantes. Vérifiez `pnpm typecheck` et un flux UI appelant une action existante. `agent-native add` sert aux blueprints d'intégration, pas à cette conversion.
 
 ## Quelle est la prochaine étape
 

package/corpus/core/docs/content/locales/hi-IN/pure-agent-apps.mdx

@@ -68,9 +68,9 @@ Automation-first app scheduled jobs, queues, scripts, integration workers और
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## बाद में chat जोड़ें {#add-chat-later}
+## बाद में UI जोड़ें {#add-chat-later}
 
-`--headless` केवल शुरुआती scaffold चुनता है; कोई `agent-native` command किसी मौजूदा action-only project को in-place chat app में नहीं बदलती। जब लोगों को browser conversation चाहिए, [Chat template](/docs/template-chat) को migration reference की तरह उपयोग करें: actions, SQL data, instructions और skills रखें, फिर browser shell, server plugins, `<AgentChatSurface>` और मौजूदा actions लोड करने वाला chat plugin जोड़ें। `pnpm typecheck` और एक ऐसा chat turn जाँचें जो किसी मौजूदा action को call करे। `agent-native add` integration blueprints के लिए है, इस conversion के लिए नहीं।
+`--headless` केवल शुरुआती scaffold चुनता है; कोई `agent-native` command किसी मौजूदा action-only project को in-place browser app में नहीं बदलती। जब लोगों को UI चाहिए, [Chat template](/docs/template-chat) को migration reference की तरह उपयोग करें: actions, SQL data, instructions और skills रखें, फिर browser shell और server plugins जोड़ें। Chat surface के लिए `<AgentChatSurface>` और मौजूदा actions लोड करने वाला chat plugin भी जोड़ें। `pnpm typecheck` और एक ऐसा UI flow जाँचें जो किसी मौजूदा action को call करे। `agent-native add` integration blueprints के लिए है, इस conversion के लिए नहीं।
 
 ## आगे क्या है
 

package/corpus/core/docs/content/locales/ja-JP/pure-agent-apps.mdx

@@ -68,9 +68,9 @@ Automation-first app は、scheduled jobs、queues、scripts、integration worke
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## 後からチャットを追加する {#add-chat-later}
+## 後から UI を追加する {#add-chat-later}
 
-`--headless` が選ぶのは初期 scaffold だけで、既存の action-only プロジェクトをその場で Chat アプリに変換する `agent-native` コマンドはありません。ブラウザーでの会話が必要になったら、移行の参照として [Chat template](/docs/template-chat) を使います。actions、SQL データ、instructions、skills は保持し、browser shell、server plugins、`<AgentChatSurface>`、既存 actions を読み込む chat plugin を追加してください。`pnpm typecheck` と既存 action を呼ぶ chat turn を確認します。`agent-native add` は integration blueprints 用であり、この変換用ではありません。
+`--headless` が選ぶのは初期 scaffold だけで、既存の action-only プロジェクトをその場でブラウザーアプリに変換する `agent-native` コマンドはありません。UI が必要になったら、移行の参照として [Chat template](/docs/template-chat) を使います。actions、SQL データ、instructions、skills は保持し、browser shell と server plugins を追加してください。チャット surface には `<AgentChatSurface>` と既存 actions を読み込む chat plugin も追加します。`pnpm typecheck` と既存 action を呼ぶ UI フローを確認します。`agent-native add` は integration blueprints 用であり、この変換用ではありません。
 
 ## 次は何ですか
 

package/corpus/core/docs/content/locales/ko-KR/pure-agent-apps.mdx

@@ -66,9 +66,9 @@ Automation-first app은 scheduled jobs, queues, scripts, integration workers, ex
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## 나중에 채팅 추가하기 {#add-chat-later}
+## 나중에 UI 추가하기 {#add-chat-later}
 
-`--headless`는 초기 scaffold만 선택하며, 기존 action-only 프로젝트를 제자리에서 Chat 앱으로 변환하는 `agent-native` 명령은 없습니다. 브라우저 대화가 필요해지면 [Chat 템플릿](/docs/template-chat)을 마이그레이션 기준으로 사용하세요. actions, SQL 데이터, instructions, skills를 유지하고 browser shell, server plugins, `<AgentChatSurface>`, 기존 actions를 로드하는 chat plugin을 추가합니다. `pnpm typecheck`와 기존 action을 호출하는 chat turn을 확인하세요. `agent-native add`는 이 변환이 아니라 integration blueprints용입니다.
+`--headless`는 초기 scaffold만 선택하며, 기존 action-only 프로젝트를 제자리에서 브라우저 앱으로 변환하는 `agent-native` 명령은 없습니다. UI가 필요해지면 [Chat 템플릿](/docs/template-chat)을 마이그레이션 기준으로 사용하세요. actions, SQL 데이터, instructions, skills를 유지하고 browser shell과 server plugins를 추가합니다. Chat surface에는 `<AgentChatSurface>`와 기존 actions를 로드하는 chat plugin도 추가합니다. `pnpm typecheck`와 기존 action을 호출하는 UI flow를 확인하세요. `agent-native add`는 이 변환이 아니라 integration blueprints용입니다.
 
 ## 다음 단계
 

package/corpus/core/docs/content/locales/pt-BR/pure-agent-apps.mdx

@@ -68,9 +68,9 @@ a caixa, o scaffold, o acesso ao repositório e o compartilhamento de execução
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## Adicione chat depois {#add-chat-later}
+## Adicione uma UI depois {#add-chat-later}
 
-`--headless` escolhe somente o scaffold inicial; não há um comando `agent-native` que converta no lugar um projeto existente apenas com actions em um app de chat. Quando as pessoas precisarem de uma conversa no navegador, use o [template Chat](/docs/template-chat) como referência de migração: mantenha as actions, os dados SQL, as instructions e as skills e adicione o shell do navegador, os server plugins, `<AgentChatSurface>` e um chat plugin que carregue as actions existentes. Verifique `pnpm typecheck` e um turno de chat que chame uma action existente. `agent-native add` é para integration blueprints, não para essa conversão.
+`--headless` escolhe somente o scaffold inicial; não há um comando `agent-native` que converta no lugar um projeto existente apenas com actions em um app de navegador. Quando as pessoas precisarem de uma UI, use o [template Chat](/docs/template-chat) como referência de migração: mantenha as actions, os dados SQL, as instructions e as skills e adicione o shell do navegador e os server plugins. Para uma superfície de chat, adicione `<AgentChatSurface>` e um chat plugin que carregue as actions existentes. Verifique `pnpm typecheck` e um fluxo de UI que chame uma action existente. `agent-native add` é para integration blueprints, não para essa conversão.
 
 ## O que vem a seguir
 

package/corpus/core/docs/content/locales/zh-CN/pure-agent-apps.mdx

@@ -66,9 +66,9 @@ Automation-first app 是无浏览器的 Agent-Native app，用于 scheduled jobs
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## 稍后添加聊天 {#add-chat-later}
+## 稍后添加 UI {#add-chat-later}
 
-`--headless` 只选择初始 scaffold；没有可将现有仅 actions 项目原地转换为聊天应用的 `agent-native` 命令。当用户需要浏览器对话时，请将 [Chat 模板](/docs/template-chat) 用作迁移参考：保留 actions、SQL 数据、instructions 和 skills，并添加浏览器 shell、server plugins、`<AgentChatSurface>` 以及加载现有 actions 的 chat plugin。验证 `pnpm typecheck`，并完成一次调用现有 action 的聊天。`agent-native add` 用于 integration blueprints，不用于此转换。
+`--headless` 只选择初始 scaffold；没有可将现有仅 actions 项目原地转换为浏览器应用的 `agent-native` 命令。当用户需要 UI 时，请将 [Chat 模板](/docs/template-chat) 用作迁移参考：保留 actions、SQL 数据、instructions 和 skills，并添加浏览器 shell 和 server plugins。对于聊天界面，再添加 `<AgentChatSurface>` 以及加载现有 actions 的 chat plugin。验证 `pnpm typecheck`，并完成一次调用现有 action 的 UI 流程。`agent-native add` 用于 integration blueprints，不用于此转换。
 
 ## 下一步是什么
 

package/corpus/core/docs/content/locales/zh-TW/pure-agent-apps.mdx

@@ -66,9 +66,9 @@ Automation-first app 是無瀏覽器的 Agent-Native app，用於 scheduled jobs
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## 稍後新增聊天 {#add-chat-later}
+## 稍後新增 UI {#add-chat-later}
 
-`--headless` 只會選擇初始 scaffold；沒有可將現有僅 actions 專案原地轉換為聊天應用程式的 `agent-native` 命令。當使用者需要瀏覽器對話時，請將 [Chat 範本](/docs/template-chat) 作為遷移參考：保留 actions、SQL 資料、instructions 和 skills，並新增瀏覽器 shell、server plugins、`<AgentChatSurface>` 與載入現有 actions 的 chat plugin。請驗證 `pnpm typecheck`，並完成一次呼叫現有 action 的聊天。`agent-native add` 用於 integration blueprints，不用於此轉換。
+`--headless` 只會選擇初始 scaffold；沒有可將現有僅 actions 專案原地轉換為瀏覽器應用程式的 `agent-native` 命令。當使用者需要 UI 時，請將 [Chat 範本](/docs/template-chat) 作為遷移參考：保留 actions、SQL 資料、instructions 和 skills，並新增瀏覽器 shell 與 server plugins。對於聊天介面，再新增 `<AgentChatSurface>` 與載入現有 actions 的 chat plugin。請驗證 `pnpm typecheck`，並完成一次呼叫現有 action 的 UI 流程。`agent-native add` 用於 integration blueprints，不用於此轉換。
 
 ## 下一步是什麼
 

package/corpus/core/docs/content/pure-agent-apps.mdx

@@ -95,22 +95,66 @@ The `--headless` flag only chooses the initial scaffold. It does not choose a
 different architecture. You can later move the same `actions/`, instructions,
 skills, and SQL state into a chat app or full application surface.
 
-## Add chat later {#add-chat-later}
+## Add a UI later {#add-chat-later}
 
 `--headless` is not a permanent runtime mode, and there is no `agent-native`
-command that converts an existing action-only project into a chat app in place.
-When people need a browser conversation surface, use the [Chat template](/docs/template-chat)
-as the migration reference and keep the durable action and database contract:
-
-1. Scaffold a temporary Chat app with the framework version you are migrating
-   to: `npx @agent-native/core@latest create my-chat-reference --template chat`.
-2. Bring its browser shell, server plugins, and UI dependencies into the
-   existing project. In particular, add the full-page `<AgentChatSurface>` and
-   an `agent-chat` plugin that loads the existing action registry.
-3. Keep your action names, Zod schemas, SQL data, instructions, and skills.
-   Chat calls those same actions; it does not replace them.
-4. Verify both surfaces: run `pnpm typecheck`, start the browser app with
-   `pnpm dev`, then complete one chat turn that calls an existing action.
+command that converts an existing action-only project into a browser app in
+place. When people need a UI, use the [Chat template](/docs/template-chat) as
+the migration reference and keep the durable action and database contract:
+
+<Diagram id="doc-block-ui-later" title="One contract, multiple surfaces" summary={"Start with a headless workflow, then add a browser UI without rewriting the actions, data, instructions, or skills underneath."}>
+
+```html
+<div class="diagram-ui-path">
+  <div class="diagram-panel" data-rough>
+    <span class="diagram-pill accent">Start headless</span
+    ><small class="diagram-muted">jobs · CLI · external agents</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel" data-rough>
+    <span class="diagram-pill">Add a UI</span
+    ><small class="diagram-muted">chat · routes · durable pages</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel ok" data-rough>
+    <span class="diagram-pill ok">Keep the contract</span
+    ><small class="diagram-muted">actions · SQL · instructions · skills</small>
+  </div>
+</div>
+```
+
+```css
+.diagram-ui-path {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 14px;
+  flex-wrap: wrap;
+}
+.diagram-ui-path .diagram-panel {
+  display: flex;
+  min-width: 150px;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+  text-align: center;
+}
+.diagram-ui-path .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+1. Scaffold the first workflow with `npx @agent-native/core@latest create my-agent --headless`.
+2. When a browser surface becomes useful, bring in the template's shell, server
+   plugins, and UI dependencies. For chat, that includes `<AgentChatSurface>`
+   and an `agent-chat` plugin that loads the existing action registry.
+3. Keep your action names, Zod schemas, SQL data, instructions, and skills. A
+   UI calls those same actions; it does not replace them.
+4. Verify both surfaces with `pnpm typecheck`, `pnpm dev`, and one UI flow that
+   calls an existing action.
 
 Use `agent-native add` for integration blueprints, not for this conversion.
 Choose chat when people need conversational steering, approvals, or durable

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.101.4",
+  "version": "0.101.6",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/action.ts

@@ -373,6 +373,14 @@ interface DefineActionWithSchema<
    *  Only set this for mutating actions that are internally concurrency-safe
    *  and order-independent for same-turn execution. */
   parallelSafe?: boolean;
+  /** Set false to exempt a read-only tool from the agent loop's duplicate
+   *  read-only call guard (per-turn result cache + "Skipped duplicate..."
+   *  repeat detection). Default true (deduped). Use this for volatile/polling
+   *  reads where an identical call is expected to return a different result
+   *  each time — e.g. polling a code-execution status by id, or re-fetching
+   *  current on-screen state. Has no effect on non-read-only actions, which
+   *  are never deduped in the first place. */
+  dedupe?: boolean;
   /** Whether this action may be invoked from the tools (Alpine iframe) bridge
    *  via `appAction(name, params)` — see `packages/core/docs/content/actions.mdx`
    *  ("Tools Callability"). **Default-allow opt-out**: undefined / `true` both
@@ -493,6 +501,9 @@ interface DefineActionWithParams<
   /** If true, the agent may execute this action concurrently with other
    *  read-only or parallel-safe tool calls emitted in the same model turn. */
   parallelSafe?: boolean;
+  /** Set false to exempt a read-only tool from the duplicate read-only call
+   *  guard. Default true. See the schema overload above. */
+  dedupe?: boolean;
   /** Whether this action may be invoked from the tools (Alpine iframe) bridge
    *  via `appAction(name, params)`. See the schema overload above for details
    *  and the `toolCallable` section in actions.md. */
@@ -557,6 +568,7 @@ export interface ActionDefinition<TInput, TReturn> {
   readonly readOnly?: boolean;
   readonly allowInPlanMode?: boolean;
   readonly parallelSafe?: boolean;
+  readonly dedupe?: boolean;
   readonly toolCallable?: boolean;
   readonly publicAgent?: PublicAgentActionConfig;
   readonly link?: ActionLinkBuilder;
@@ -752,6 +764,8 @@ export function defineAction(options: any) {
     typeof options.parallelSafe === "boolean"
       ? options.parallelSafe
       : undefined;
+  const dedupe: boolean | undefined =
+    typeof options.dedupe === "boolean" ? options.dedupe : undefined;
   const publicAgent: PublicAgentActionConfig | undefined =
     options.publicAgent &&
     typeof options.publicAgent === "object" &&
@@ -806,6 +820,7 @@ export function defineAction(options: any) {
       ? { allowInPlanMode: options.allowInPlanMode }
       : {}),
     ...(typeof parallelSafe === "boolean" ? { parallelSafe } : {}),
+    ...(typeof dedupe === "boolean" ? { dedupe } : {}),
     ...(typeof toolCallable === "boolean" ? { toolCallable } : {}),
     ...(publicAgent ? { publicAgent } : {}),
     ...(link ? { link } : {}),

package/corpus/core/src/agent/production-agent.ts

@@ -583,6 +583,11 @@ export interface ActionEntry {
    *  read-only/parallel-safe tool calls. Only use for actions that handle
    *  their own write ordering and idempotency. */
   parallelSafe?: boolean;
+  /** Set false to exempt a read-only tool from the duplicate read-only
+   *  tool-call guard (per-turn result cache + repeat-kill). Default true. Use
+   *  for volatile/polling reads that are expected to return a different
+   *  result on each identical call. See `defineAction`'s `dedupe` option. */
+  dedupe?: boolean;
   /** Whether this action may be invoked from the tools-iframe bridge.
    *  **Default-allow opt-out**: only an explicit `false` returns 403.
    *  - `true` / `undefined` — allow.
@@ -2170,16 +2175,26 @@ function seedReadOnlyToolResultsFromHistory(
   const cache = new Map<string, string>();
   if (!isInternalContinuationTurn(messages)) return cache;
 
-  const pendingToolCalls = new Map<string, { name: string; input: unknown }>();
-  for (const message of messages) {
+  // Scoped to the current turn only (same slice as
+  // seedWriteToolInterruptionsFromHistory) — reads from a prior turn are no
+  // longer relevant context and must not seed skip-as-duplicate behavior.
+  const turnStart = findCurrentTurnStartForContinuation(messages);
+  const turnMessages = messages.slice(turnStart);
+
+  const pendingToolCalls = new Map<
+    string,
+    { name: string; input: unknown; readOnly: boolean; dedupe: boolean }
+  >();
+  for (const message of turnMessages) {
     if (message.role === "assistant") {
       for (const part of message.content) {
         if (part.type !== "tool-call") continue;
         const entry = actions[part.name];
-        if (entry?.readOnly !== true) continue;
         pendingToolCalls.set(part.id, {
           name: part.name,
           input: part.input,
+          readOnly: entry?.readOnly === true,
+          dedupe: entry?.dedupe !== false,
         });
       }
       continue;
@@ -2189,6 +2204,17 @@ function seedReadOnlyToolResultsFromHistory(
       if (part.type !== "tool-result") continue;
       const call = pendingToolCalls.get(part.toolCallId);
       if (!call) continue;
+      if (!call.readOnly) {
+        // Mirror the live loop: a successful write invalidates all cached
+        // reads (see the `readOnlyToolResultCache.clear()` call below), so a
+        // read seeded from before an intervening write must not be replayed
+        // as still-fresh.
+        if (part.isError !== true) cache.clear();
+        continue;
+      }
+      // dedupe:false read-only tools (volatile/polling reads) are never
+      // cached — every call must execute fresh, seeded or not.
+      if (!call.dedupe) continue;
       if (!isReusableReadOnlyToolResult(part)) continue;
       cache.set(toolCallCacheKey(call.name, call.input), part.content);
     }
@@ -2197,11 +2223,100 @@ function seedReadOnlyToolResultsFromHistory(
   return cache;
 }
 
+function visibleDuplicateReadOnlyToolResult(toolName: string): string {
+  return (
+    `Skipped duplicate read-only call to ${toolName}: identical input already ran in this turn. ` +
+    `Use the previous result already in the conversation instead of calling this tool again.`
+  );
+}
+
+function resurfacedDuplicateReadOnlyToolResultPrefix(toolName: string): string {
+  return (
+    `Skipped duplicate read-only call to ${toolName}: identical input already ran in this turn. ` +
+    `Its earlier result is no longer in view, so here it is again:\n\n`
+  );
+}
+
+function resurfacedDuplicateReadOnlyToolResult(
+  toolName: string,
+  cachedResult: string,
+): string {
+  return `${resurfacedDuplicateReadOnlyToolResultPrefix(toolName)}${cachedResult}`;
+}
+
+/** Restore visible-repeat strike counts for this continuation's active turn. */
+function seedDuplicateReadOnlyToolCallsFromHistory(
+  messages: EngineMessage[],
+  actions: Record<string, ActionEntry>,
+): Map<string, number> {
+  const repeats = new Map<string, number>();
+  if (!isInternalContinuationTurn(messages)) return repeats;
+
+  const turnStart = findCurrentTurnStartForContinuation(messages);
+  const pendingToolCalls = new Map<
+    string,
+    { name: string; input: unknown; readOnly: boolean; dedupe: boolean }
+  >();
+  const reusableReadKeys = new Set<string>();
+
+  for (const message of messages.slice(turnStart)) {
+    if (message.role === "assistant") {
+      for (const part of message.content) {
+        if (part.type !== "tool-call") continue;
+        const entry = actions[part.name];
+        pendingToolCalls.set(part.id, {
+          name: part.name,
+          input: part.input,
+          readOnly: entry?.readOnly === true,
+          dedupe: entry?.dedupe !== false,
+        });
+      }
+      continue;
+    }
+
+    for (const part of message.content) {
+      if (part.type !== "tool-result") continue;
+      const call = pendingToolCalls.get(part.toolCallId);
+      if (!call) continue;
+      if (!call.readOnly) {
+        if (part.isError !== true) {
+          repeats.clear();
+          reusableReadKeys.clear();
+        }
+        continue;
+      }
+      if (!call.dedupe || part.isError === true) continue;
+
+      const cacheKey = toolCallCacheKey(call.name, call.input);
+      if (part.content === visibleDuplicateReadOnlyToolResult(call.name)) {
+        if (reusableReadKeys.has(cacheKey)) {
+          repeats.set(cacheKey, (repeats.get(cacheKey) ?? 0) + 1);
+        }
+        continue;
+      }
+      if (
+        part.content.startsWith(
+          resurfacedDuplicateReadOnlyToolResultPrefix(call.name),
+        )
+      ) {
+        if (reusableReadKeys.has(cacheKey)) repeats.set(cacheKey, 0);
+        continue;
+      }
+      if (isReusableReadOnlyToolResult(part)) {
+        reusableReadKeys.add(cacheKey);
+      }
+    }
+  }
+
+  return repeats;
+}
+
 function isReusableReadOnlyToolResult(part: EngineToolResultPart): boolean {
   if (part.isError) return false;
   const lower = part.content.trim().toLowerCase();
   if (!lower) return false;
   return !(
+    lower.startsWith("skipped duplicate read-only call to ") ||
     lower.startsWith("invalid action parameters for ") ||
     lower.startsWith("error running ") ||
     lower.includes("run aborted") ||
@@ -2211,6 +2326,56 @@ function isReusableReadOnlyToolResult(part: EngineToolResultPart): boolean {
   );
 }
 
+/**
+ * Whether a cached read-only tool result is still something the model can
+ * actually see in `contextMessages` — the trimmed/summarized view the engine
+ * is streamed (NOT the raw, ever-growing `messages` array the cache is keyed
+ * off of). Context-xray `evict` drops tool-result parts entirely, `summarize`
+ * replaces their content with a placeholder, and observational-memory
+ * trimming drops whole older messages once active. When the cached result
+ * has fallen out of that view, re-serving "use the previous result" is not
+ * actionable — the model has nothing to point back to.
+ *
+ * A visible result must belong to the same tool name + normalized input and
+ * contain either the exact cached body or the exact wrapper used when that
+ * body was re-served after trimming. Matching only by a content suffix is too
+ * loose: short results such as "ok" can also end unrelated tool output.
+ */
+export function isCachedToolResultVisibleInContext(
+  contextMessages: EngineMessage[],
+  toolCall: { name: string; input: unknown },
+  cachedResult: string,
+): boolean {
+  if (cachedResult.length === 0) return true;
+  const cacheKey = toolCallCacheKey(toolCall.name, toolCall.input);
+  const matchingToolCallIds = new Set<string>();
+  for (const message of contextMessages) {
+    if (message.role !== "assistant") continue;
+    for (const part of message.content) {
+      if (part.type !== "tool-call") continue;
+      if (toolCallCacheKey(part.name, part.input) === cacheKey) {
+        matchingToolCallIds.add(part.id);
+      }
+    }
+  }
+
+  const resurfacedResult = resurfacedDuplicateReadOnlyToolResult(
+    toolCall.name,
+    cachedResult,
+  );
+  for (const message of contextMessages) {
+    if (message.role !== "user") continue;
+    for (const part of message.content) {
+      if (part.type !== "tool-result") continue;
+      if (!matchingToolCallIds.has(part.toolCallId)) continue;
+      if (part.content === cachedResult || part.content === resurfacedResult) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
 /**
  * Counts how many times each write (non-read-only) tool call was interrupted
  * before returning a result in the continuation history. When a connection
@@ -3106,7 +3271,10 @@ export async function runAgentLoop(opts: {
     messages,
     actions,
   );
-  const duplicateReadOnlyToolCalls = new Map<string, number>();
+  const duplicateReadOnlyToolCalls = seedDuplicateReadOnlyToolCallsFromHistory(
+    messages,
+    actions,
+  );
   const writeToolInterruptions = seedWriteToolInterruptionsFromHistory(
     messages,
     actions,
@@ -4339,18 +4507,49 @@ export async function runAgentLoop(opts: {
         };
       }
 
+      // dedupe: false opts a read-only tool out of the guard entirely — the
+      // cacheKey stays null so it never gets skipped-as-duplicate and never
+      // populates the cache (see the success handler below, which also
+      // leaves dedupe:false results uncached and un-cleared).
       const cacheKey =
-        actionEntry.readOnly === true
+        actionEntry.readOnly === true && actionEntry.dedupe !== false
           ? toolCallCacheKey(toolCall.name, toolCall.input)
           : null;
       if (cacheKey && readOnlyToolResultCache.has(cacheKey)) {
-        const repeats = (duplicateReadOnlyToolCalls.get(cacheKey) ?? 0) + 1;
-        duplicateReadOnlyToolCalls.set(cacheKey, repeats);
         const previousResult = readOnlyToolResultCache.get(cacheKey) ?? "";
-        const result =
-          `Skipped duplicate read-only call to ${toolCall.name}: identical input already ran in this turn. ` +
-          `Use the previous result already in the conversation instead of calling this tool again.\n\n` +
-          `Previous result:\n${previousResult}`;
+        // `contextMessages` (not `messages`) is what the model actually sees
+        // this iteration — context-xray eviction/summarization and
+        // observational-memory trimming can drop the earlier result from
+        // view even though it's still cached here. Only strike-count the
+        // repeat when the model could have looked back and found it itself.
+        const visible = isCachedToolResultVisibleInContext(
+          contextMessages,
+          toolCall,
+          previousResult,
+        );
+        let result: string;
+        if (visible) {
+          const repeats = (duplicateReadOnlyToolCalls.get(cacheKey) ?? 0) + 1;
+          duplicateReadOnlyToolCalls.set(cacheKey, repeats);
+          result = visibleDuplicateReadOnlyToolResult(toolCall.name);
+          if (repeats >= 3) {
+            requestedActionStop ??= {
+              message:
+                "I stopped because the agent kept asking for the same read-only context it already had. Please send the request again if you want me to retry from a fresh turn.",
+              errorCode: "duplicate_read_only_tool",
+            };
+          }
+        } else {
+          // The earlier result was trimmed out of the model's visible
+          // context — this isn't a repetitive loop, the model legitimately
+          // can't see the answer anymore. Re-serve it in full and don't
+          // count a strike.
+          duplicateReadOnlyToolCalls.set(cacheKey, 0);
+          result = resurfacedDuplicateReadOnlyToolResult(
+            toolCall.name,
+            previousResult,
+          );
+        }
         send({
           type: "tool_done",
           id: toolCall.id,
@@ -4360,13 +4559,6 @@ export async function runAgentLoop(opts: {
           completedSideEffect: false,
         });
         recordToolResult(result, false);
-        if (repeats >= 3) {
-          requestedActionStop ??= {
-            message:
-              "I stopped because the agent kept asking for the same read-only context it already had. Please send the request again if you want me to retry from a fresh turn.",
-            errorCode: "duplicate_read_only_tool",
-          };
-        }
         return {
           type: "tool-result" as const,
           toolCallId: toolCall.id,
@@ -4638,7 +4830,11 @@ export async function runAgentLoop(opts: {
       if (!isError) {
         if (cacheKey) {
           readOnlyToolResultCache.set(cacheKey, result);
-        } else {
+        } else if (actionEntry.readOnly !== true) {
+          // A genuine write invalidates all cached reads. A dedupe:false
+          // read-only tool also has a null cacheKey (see above) but must NOT
+          // clear the cache — it isn't a write and other tools' cached reads
+          // are still valid.
           readOnlyToolResultCache.clear();
           duplicateReadOnlyToolCalls.clear();
         }