@pouchy_ai/admin-sdk 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.33.0 — 2026-09-08
+
+### Added
+
+- `Agent.instructions?: boolean` — the template flag that grants
+  `chat.instructions` on an agent's session mints, so a turn may carry an
+  `instructions` field (developer-authored rules for THAT turn, joined to the
+  prompt and never scored as user speech by inbound moderation; issue #3379).
+
+  Typed here because it is the **only** way to obtain that scope, and an
+  integrator's first instinct is to request it at mint time — which silently
+  does nothing: the scope sits outside the mintable default set on purpose
+  (the field it unlocks skips moderation, and a session token is routinely
+  held by the end user's own client), and `validateSessionRequest` narrows a
+  requested scope to that set. Flip the template flag instead, from the
+  Dashboard or `PATCH /v1/projects/{id}/agents/{agentId}` with
+  `{"instructions": true}`. Settings-class: no `templateRev` bump; existing
+  session tokens gain the scope on re-mint.
+
+## 0.32.1 — 2026-09-06
+
+- **A transport failure now names the request.** `AdminApiError.message` on a
+  timeout or a network error is `GET /agents — request timed out after 30000ms`
+  / `POST /knowledge — network error: fetch failed`, where it used to be the
+  bare tail. Status 0 failures carry no `code` and no `errorId`, and ~70
+  methods share one request funnel, so the message was the only place the call
+  could have been named and it was the one place that did not name it — the
+  README's own `console.error(e.status, e.message)` read identically for every
+  route. The sibling `@pouchy_ai/world-sdk` has always spelled `${method}
+  ${path}` here. The non-2xx path is UNCHANGED: the server's own `error` string
+  is still passed through verbatim, because that is the message this SDK
+  documents and integrators match on. Only its no-body fallback gained the
+  prefix (`GET /agents → HTTP 502`, previously `HTTP 502`), where there was no
+  server text to displace. If you assert on exact message text for a timeout or
+  network error, match on a substring.
+
 ## 0.32.0 — 2026-09-06
 
 - **Diff entries are `{ field, before, after }`** — `diffAgentVersions` and

package/README.md

@@ -351,6 +351,20 @@ occurred.") and `AdminApiError.errorId` carries the server's `err_…` lookup
 reference (0.31.1) — quote it in a support request; it is what resolves to the
 real cause.
 
+A **transport** failure has no status, no `code` and no `errorId`, so since
+0.32.1 its message names the request that failed:
+
+```text
+GET /agents — request timed out after 30000ms
+POST /knowledge/url — network error: fetch failed
+```
+
+Every method shares one request funnel, so without that prefix a timeout on a
+five-minute knowledge ingest and a timeout on `listAgents` printed the same
+line. HTTP errors are unchanged: the message is the server's own `error` string
+(`"unknown agent"`), and only its no-body fallback names the request
+(`GET /agents → HTTP 502`).
+
 ### Failure codes (409)
 
 **Every machine-readable failure on this API is a 409**, so `status` separates

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.32.0";
+export declare const ADMIN_SDK_VERSION = "0.33.0";
 export declare const DEFAULT_BASE_URL = "https://pouchy.ai/v1/admin";
 /** Deadline for the routes whose server handler declares `maxDuration: 300` —
  *  the server's own ceiling plus headroom, so a client abort can only ever mean
@@ -65,10 +65,21 @@ export declare const ADMIN_ERROR_CODES: readonly ["story_contract_v2_write_disab
  *  codes newer than this SDK build while preserving autocomplete — same
  *  doctrine as the companion SDK's `CompanionErrorCodeValue`. */
 export type AdminErrorCode = (typeof ADMIN_ERROR_CODES)[number] | (string & {});
-/** Thrown on any non-2xx response. `status` is the HTTP status; `message` is the
- *  server's `error` string when present; `retryAfter` is the throttle's own
- *  backoff in SECONDS on a 429 (undefined on every other failure); `code` is the
- *  server's machine tag when it named one (undefined otherwise).
+/** Thrown on any non-2xx response AND on a transport failure that never reached
+ *  the server (network / DNS / timeout), which carries `status: 0`. `status` is
+ *  the HTTP status; `retryAfter` is the throttle's own backoff in SECONDS on a
+ *  429 (undefined on every other failure); `code` is the server's machine tag
+ *  when it named one (undefined otherwise).
+ *
+ *  `message` has two shapes, and which one you get follows `status`. On a
+ *  non-2xx it is the server's own `error` string, verbatim — that is what this
+ *  package documents and what integrators read. On a status-0 transport failure
+ *  there IS no server string, and no `code` or `errorId` either, so the message
+ *  names the request instead (`GET /agents — request timed out after 30000ms`);
+ *  ~70 methods share one funnel, and without it a hung five-minute knowledge
+ *  ingest printed the same line as a hung `listAgents` (0.32.1). The non-2xx
+ *  fallback for a body with no `error` at all is named the same way
+ *  (`GET /agents → HTTP 502`). Prose either way: switch on `code`, not on this.
  *
  *  Why `code` exists: the Admin API's machine-readable failures are ALL on
  *  409, so `status` cannot separate them and this package used to discard the
@@ -154,6 +165,14 @@ export interface Agent {
      *  (concurrent headless workers under one persona). Default false since
      *  owner decision D-10 (2026-09-05). */
     spawnSubtasks?: boolean;
+    /** Grant `chat.instructions` on this agent's session mints, so a turn may
+     *  carry an `instructions` field — developer-authored rules for THAT turn,
+     *  joined to the prompt and never scored as user speech by inbound
+     *  moderation (issue #3379). Default false, and this template flag is the
+     *  ONLY way to obtain the scope: it sits outside the mintable default set
+     *  on purpose, so asking for it in the session-mint body is narrowed away.
+     *  Leave it off unless your backend assembles per-turn rules itself. */
+    instructions?: boolean;
     /** Reply-cue opt-in (see ReplyCues). */
     replyCues?: ReplyCues;
     templateRev: number;

package/dist/index.js

@@ -8,7 +8,7 @@
 //   import { createAdminClient } from '@pouchy_ai/admin-sdk';
 //   const admin = createAdminClient({ adminKey: process.env.POUCHY_ADMIN_KEY! });
 //   const { agents } = await admin.listAgents();
-export const ADMIN_SDK_VERSION = '0.32.0';
+export const ADMIN_SDK_VERSION = '0.33.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1/admin';
 /** Default per-request timeout (ms). A hung upstream otherwise never rejects. */
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -94,10 +94,21 @@ export const ADMIN_ERROR_CODES = [
     'run_not_waiting',
     'event_mismatch'
 ];
-/** Thrown on any non-2xx response. `status` is the HTTP status; `message` is the
- *  server's `error` string when present; `retryAfter` is the throttle's own
- *  backoff in SECONDS on a 429 (undefined on every other failure); `code` is the
- *  server's machine tag when it named one (undefined otherwise).
+/** Thrown on any non-2xx response AND on a transport failure that never reached
+ *  the server (network / DNS / timeout), which carries `status: 0`. `status` is
+ *  the HTTP status; `retryAfter` is the throttle's own backoff in SECONDS on a
+ *  429 (undefined on every other failure); `code` is the server's machine tag
+ *  when it named one (undefined otherwise).
+ *
+ *  `message` has two shapes, and which one you get follows `status`. On a
+ *  non-2xx it is the server's own `error` string, verbatim — that is what this
+ *  package documents and what integrators read. On a status-0 transport failure
+ *  there IS no server string, and no `code` or `errorId` either, so the message
+ *  names the request instead (`GET /agents — request timed out after 30000ms`);
+ *  ~70 methods share one funnel, and without it a hung five-minute knowledge
+ *  ingest printed the same line as a hung `listAgents` (0.32.1). The non-2xx
+ *  fallback for a body with no `error` at all is named the same way
+ *  (`GET /agents → HTTP 502`). Prose either way: switch on `code`, not on this.
  *
  *  Why `code` exists: the Admin API's machine-readable failures are ALL on
  *  409, so `status` cannot separate them and this package used to discard the
@@ -239,11 +250,29 @@ export function createAdminClient(opts) {
         }
         catch (e) {
             const isTimeout = e instanceof Error && (e.name === 'TimeoutError' || e.name === 'AbortError');
-            throw new AdminApiError(isTimeout ? `request timed out after ${timeoutMs}ms` : `network error: ${e instanceof Error ? e.message : String(e)}`, 0);
+            // The REQUEST is named, because nothing else in the envelope can name it.
+            // ~70 methods share this one funnel and a transport failure has status 0,
+            // no `code` and no `errorId` — so the README's own
+            // `console.error(e.status, e.message)` read `0 "request timed out after
+            // 30000ms"` for every route alike, and an operator could not tell a hung
+            // knowledge ingest from a hung `listAgents`. The sibling world-sdk has
+            // spelled `${method} ${path}` on both of its transport throws since it
+            // shipped; this is the same prefix, for the same reason.
+            throw new AdminApiError(isTimeout
+                ? `${method} ${path} — request timed out after ${timeoutMs}ms`
+                : `${method} ${path} — network error: ${e instanceof Error ? e.message : String(e)}`, 0);
         }
         const data = (await res.json().catch(() => ({})));
         if (!res.ok)
-            throw new AdminApiError(data?.error ?? `HTTP ${res.status}`, res.status, retryAfterFrom(res, data), codeFrom(data), errorIdFrom(data));
+            throw new AdminApiError(
+            // The server's own `error` string is passed through UNCHANGED — it is
+            // the message this SDK documents (`404 "unknown agent"`), integrators
+            // match on it, and `status` / `code` / `errorId` already disambiguate a
+            // coded failure. Only the FALLBACK is prefixed, and only because there
+            // is no server text there to displace: an edge 502 whose body is HTML
+            // (`res.json()` rejects → `{}`) used to read `HTTP 502` with nothing
+            // saying which of ~70 calls produced it.
+            data?.error ?? `${method} ${path} → HTTP ${res.status}`, res.status, retryAfterFrom(res, data), codeFrom(data), errorIdFrom(data));
         return data;
     }
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pouchy_ai/admin-sdk",
-	"version": "0.32.0",
+	"version": "0.33.0",
 	"description": "Typed TypeScript client for the Pouchy Admin API \u2014 manage agents, keys, end users, knowledge, skills, channels, schedules, webhooks and credentials headlessly, with a project Admin key.",
 	"type": "module",
 	"license": "SEE LICENSE IN LICENSE",