@pidgeon-ai/sdk 1.11.0 → 1.13.0

package/CHANGELOG.md

@@ -9,6 +9,26 @@ call shapes, the result shape — not to the API behind it.
 
 ## Unreleased
 
+## 1.13.0 — what the agent reads
+
+`firewall.clean_text` on every inbound message: the new text with hidden
+content and invisible characters removed, and lines posing as a chat turn
+marked, under a one-line note saying what changed. `body=clean` on
+`GET /messages/{id}` and `GET /messages/await` returns it as `text` and
+`reply_text`, with `html` and `reply_html` empty. The default is still
+`original`. The MCP server and the AI SDK ask for `clean` unless told
+otherwise.
+
+## 1.12.0 — Pidgeon Firewall
+
+Every inbound `Message` carries `firewall`: a `verdict` (`clean` or
+`suspicious`) and the `signals` that produced it — hidden text, instructions
+addressed to an AI, impersonated chat turns, directives buried in quoted
+history, look-alike senders, display-name spoofing, and requests to send
+secrets out — each with where it fired and a sentence quoting it.
+`message.received` carries the verdict and the signal kinds. Observe-only:
+nothing is held or changed. Read it before acting on what a message asks.
+
 ## 1.11.0 — a key for one pod
 
 `apiKeysCreate` takes `pod_id` in place of `identity_ids`: the key reaches

package/dist/index.d.cts

@@ -528,6 +528,34 @@ type Message = {
      * The event the calendar made of that invitation, or null. A different fact from `invitation`: that is what the mail said, this is what the calendar now holds — a meeting later moved still reports the time this message invited you to.
      */
     calendar_event_id: string | null;
+    /**
+     * Pidgeon Firewall: does this message try to steer the agent reading it — hidden text, instructions addressed to an AI, impersonated chat turns, look-alike senders, requests to send secrets out. Null on outbound mail. Read it before acting on what the message asks.
+     */
+    firewall: {
+        /**
+         * `suspicious` when any signal fired. Observe-only: nothing is held or changed.
+         */
+        verdict: 'clean' | 'suspicious';
+        /**
+         * The rules that fired, most specific first. Empty when the verdict is `clean`.
+         */
+        signals: Array<{
+            kind: 'hidden_text' | 'invisible_characters' | 'assistant_directive' | 'role_spoof' | 'quoted_directive' | 'lookalike_sender' | 'display_name_spoof' | 'unauthenticated_with_directive' | 'exfiltration_request';
+            /**
+             * What was found, with a short quote of it.
+             */
+            detail: string;
+            where: 'subject' | 'text' | 'html' | 'from' | 'quoted';
+        }>;
+        /**
+         * What an agent should read: the new text with hidden content and invisible characters removed and lines posing as a chat turn marked, under a one-line note saying what changed. The new text unchanged when nothing needed it. Ask for `body=clean` to get it in place of the body.
+         */
+        clean_text: string;
+        /**
+         * Bumped when the rules change in a way that could change a verdict.
+         */
+        version: number;
+    } | null;
     /**
      * Verification codes and links found in the message, most likely first — read from the new text, never the quoted history. Empty lists when nothing was found.
      */
@@ -681,6 +709,34 @@ type AwaitedMessage = {
          * The event the calendar made of that invitation, or null. A different fact from `invitation`: that is what the mail said, this is what the calendar now holds — a meeting later moved still reports the time this message invited you to.
          */
         calendar_event_id: string | null;
+        /**
+         * Pidgeon Firewall: does this message try to steer the agent reading it — hidden text, instructions addressed to an AI, impersonated chat turns, look-alike senders, requests to send secrets out. Null on outbound mail. Read it before acting on what the message asks.
+         */
+        firewall: {
+            /**
+             * `suspicious` when any signal fired. Observe-only: nothing is held or changed.
+             */
+            verdict: 'clean' | 'suspicious';
+            /**
+             * The rules that fired, most specific first. Empty when the verdict is `clean`.
+             */
+            signals: Array<{
+                kind: 'hidden_text' | 'invisible_characters' | 'assistant_directive' | 'role_spoof' | 'quoted_directive' | 'lookalike_sender' | 'display_name_spoof' | 'unauthenticated_with_directive' | 'exfiltration_request';
+                /**
+                 * What was found, with a short quote of it.
+                 */
+                detail: string;
+                where: 'subject' | 'text' | 'html' | 'from' | 'quoted';
+            }>;
+            /**
+             * What an agent should read: the new text with hidden content and invisible characters removed and lines posing as a chat turn marked, under a one-line note saying what changed. The new text unchanged when nothing needed it. Ask for `body=clean` to get it in place of the body.
+             */
+            clean_text: string;
+            /**
+             * Bumped when the rules change in a way that could change a verdict.
+             */
+            version: number;
+        } | null;
         /**
          * Verification codes and links found in the message, most likely first — read from the new text, never the quoted history. Empty lists when nothing was found.
          */
@@ -2878,6 +2934,7 @@ type MessagesAwaitData = {
     path?: never;
     query: {
         identity_id: string;
+        body?: 'original' | 'clean';
         from?: string;
         subject_contains?: string;
         has_code?: 'true' | 'false';
@@ -2915,7 +2972,9 @@ type MessagesGetData = {
     path: {
         id: string;
     };
-    query?: never;
+    query?: {
+        body?: 'original' | 'clean';
+    };
     url: '/messages/{id}';
 };
 type MessagesGetErrors = {

package/dist/index.d.ts

@@ -528,6 +528,34 @@ type Message = {
      * The event the calendar made of that invitation, or null. A different fact from `invitation`: that is what the mail said, this is what the calendar now holds — a meeting later moved still reports the time this message invited you to.
      */
     calendar_event_id: string | null;
+    /**
+     * Pidgeon Firewall: does this message try to steer the agent reading it — hidden text, instructions addressed to an AI, impersonated chat turns, look-alike senders, requests to send secrets out. Null on outbound mail. Read it before acting on what the message asks.
+     */
+    firewall: {
+        /**
+         * `suspicious` when any signal fired. Observe-only: nothing is held or changed.
+         */
+        verdict: 'clean' | 'suspicious';
+        /**
+         * The rules that fired, most specific first. Empty when the verdict is `clean`.
+         */
+        signals: Array<{
+            kind: 'hidden_text' | 'invisible_characters' | 'assistant_directive' | 'role_spoof' | 'quoted_directive' | 'lookalike_sender' | 'display_name_spoof' | 'unauthenticated_with_directive' | 'exfiltration_request';
+            /**
+             * What was found, with a short quote of it.
+             */
+            detail: string;
+            where: 'subject' | 'text' | 'html' | 'from' | 'quoted';
+        }>;
+        /**
+         * What an agent should read: the new text with hidden content and invisible characters removed and lines posing as a chat turn marked, under a one-line note saying what changed. The new text unchanged when nothing needed it. Ask for `body=clean` to get it in place of the body.
+         */
+        clean_text: string;
+        /**
+         * Bumped when the rules change in a way that could change a verdict.
+         */
+        version: number;
+    } | null;
     /**
      * Verification codes and links found in the message, most likely first — read from the new text, never the quoted history. Empty lists when nothing was found.
      */
@@ -681,6 +709,34 @@ type AwaitedMessage = {
          * The event the calendar made of that invitation, or null. A different fact from `invitation`: that is what the mail said, this is what the calendar now holds — a meeting later moved still reports the time this message invited you to.
          */
         calendar_event_id: string | null;
+        /**
+         * Pidgeon Firewall: does this message try to steer the agent reading it — hidden text, instructions addressed to an AI, impersonated chat turns, look-alike senders, requests to send secrets out. Null on outbound mail. Read it before acting on what the message asks.
+         */
+        firewall: {
+            /**
+             * `suspicious` when any signal fired. Observe-only: nothing is held or changed.
+             */
+            verdict: 'clean' | 'suspicious';
+            /**
+             * The rules that fired, most specific first. Empty when the verdict is `clean`.
+             */
+            signals: Array<{
+                kind: 'hidden_text' | 'invisible_characters' | 'assistant_directive' | 'role_spoof' | 'quoted_directive' | 'lookalike_sender' | 'display_name_spoof' | 'unauthenticated_with_directive' | 'exfiltration_request';
+                /**
+                 * What was found, with a short quote of it.
+                 */
+                detail: string;
+                where: 'subject' | 'text' | 'html' | 'from' | 'quoted';
+            }>;
+            /**
+             * What an agent should read: the new text with hidden content and invisible characters removed and lines posing as a chat turn marked, under a one-line note saying what changed. The new text unchanged when nothing needed it. Ask for `body=clean` to get it in place of the body.
+             */
+            clean_text: string;
+            /**
+             * Bumped when the rules change in a way that could change a verdict.
+             */
+            version: number;
+        } | null;
         /**
          * Verification codes and links found in the message, most likely first — read from the new text, never the quoted history. Empty lists when nothing was found.
          */
@@ -2878,6 +2934,7 @@ type MessagesAwaitData = {
     path?: never;
     query: {
         identity_id: string;
+        body?: 'original' | 'clean';
         from?: string;
         subject_contains?: string;
         has_code?: 'true' | 'false';
@@ -2915,7 +2972,9 @@ type MessagesGetData = {
     path: {
         id: string;
     };
-    query?: never;
+    query?: {
+        body?: 'original' | 'clean';
+    };
     url: '/messages/{id}';
 };
 type MessagesGetErrors = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pidgeon-ai/sdk",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "Thin TypeScript client for the Pidgeon email API.",
   "keywords": [
     "pidgeon",