@pouchy_ai/admin-sdk 0.26.1 → 0.27.1

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.27.1 — 2026-08-28
+
+- **Docs-only, but read it if you use `encodingFormat: 'base64'`.** The 0.27.0
+  README's decode snippet was `new Float32Array(Buffer.from(s,'base64').buffer)`
+  — on Node runtimes that pool small buffers (every 768-dim vector qualifies),
+  `.buffer` is the whole shared pool and that form silently decodes ~2048
+  garbage-tailed elements. Our own live acceptance probe caught it on first
+  field run. Correct, everywhere:
+  `const buf = Buffer.from(s, 'base64'); new Float32Array(buf.buffer, buf.byteOffset, buf.length / 4)`.
+  No client code changed.
+
+## 0.27.0 — 2026-08-28
+
+- **New: `embedTexts` — text → embedding vectors** (`POST
+  /v1/admin/utility/embeddings`), the vector sibling of `extractJson`:
+  stateless, no companion side effects, typed failures (`invalid_request` /
+  `unavailable` / `provider_error`). For a backend that ranks its own
+  inventory by cosine (album/asset pick, intent-gate exemplars) and wants one
+  billing/key channel instead of a second embedding vendor. Batch up to 64
+  texts per call; the response `model` is a **stable id** to persist next to
+  every stored vector and PIN in later requests — an id the deployment cannot
+  serve exactly answers 400, never a silent substitute, so a platform model
+  swap surfaces as an explicit reindex signal. `encodingFormat: 'base64'`
+  returns little-endian float32 base64 (~3.5× smaller) for bulk reindex.
+  Motivating ask: LuckyDramas' album selfie pick + L2 memory intent gate,
+  previously on a second vendor key at their BFF.
+
+## 0.26.2 — 2026-08-21
+
+- **`createAgent` / `updateAgent` responses now type the additive
+  `droppedSkills?: string[]` field.** The platform filters `skills` slugs to
+  its registered allowlist; it now names anything it filtered instead of
+  returning a 200 whose `agent.skills` is silently missing what you sent.
+  Motivating field report: a manifest said `client_action`, the platform had
+  registered `client-action`, and the diff between request and response was
+  the only clue. Additive server field (older servers simply never set it) —
+  no behavioural change in this client.
+
 ## 0.26.1 — 2026-08-09
 
 - **Docs-only.** No type, method or signature moves. `extractJson`'s failure

package/README.md

@@ -158,6 +158,62 @@ completion arrived but did not parse or satisfy the schema; the error carries
 `raw`, the text actually returned). Tokens roll into the project's month usage
 like any other model call.
 
+### Embedding vectors — use `embedTexts`, not a second vendor key
+
+The vector sibling of `extractJson`: text → embedding vectors, stateless, no
+companion side effects. For a backend that ranks its **own** inventory by cosine
+(album/asset pick, memory intent-gate exemplars) and wants one billing/key
+channel instead of holding a separate embedding vendor's key beside its Pouchy
+keys — retrieval stays yours; Pouchy only turns text into vectors.
+
+```ts
+const res = await admin.embedTexts({
+  input: ['Send me a casual home coffee selfie', '来张咖啡店自拍'] // ≤ 64 per call
+});
+// res.model      → 'openai-text-embedding-3-small-768'  (STABLE id — persist it)
+// res.dimensions → 768                                   (== every vector's length)
+// res.data[i]    → { index: i, embedding: number[] }     (index-aligned)
+```
+
+Two rules keep a stored index honest:
+
+1. **Persist `res.model` next to every stored vector and refuse mixed-model
+   cosine.** Then **pin** it in later requests (`model:
+   'openai-text-embedding-3-small-768'`): an id the deployment cannot serve
+   exactly answers `400` — never a silent substitute — so a platform model swap
+   surfaces on your side as an explicit reindex signal.
+2. **Texts are never silently truncated.** An over-cap text (> 8000 chars) is a
+   `400` naming its index; split or summarize it yourself, so what you embedded
+   is always exactly what you stored.
+
+For bulk reindex, `encodingFormat: 'base64'` returns each vector as
+little-endian float32 base64 (~3.5× smaller at 768 dims). Decode with the
+**offset-safe** form:
+
+```ts
+const res = await admin.embedTexts({
+  input: ['来张咖啡店自拍'],
+  encodingFormat: 'base64'
+});
+for (const { embedding } of res.data) {
+  const buf = Buffer.from(embedding as string, 'base64');
+  const vec = new Float32Array(buf.buffer, buf.byteOffset, buf.length / 4);
+  // vec.length === res.dimensions, always
+  void vec;
+}
+```
+
+Not `new Float32Array(buf.buffer)` — on Node runtimes that pool small buffers
+(every 768-dim vector qualifies), `.buffer` is the whole shared pool and the
+naive form silently decodes ~2048 garbage-tailed elements. Caught live by our
+own acceptance probe; the three-arg form is correct everywhere.
+
+Failures are typed: `invalid_request` (400 — fix and resend), `unavailable`
+(503 — transient, back off and retry), `provider_error` (502 — the upstream
+embedder rejected a request the platform believed valid; short provider message
+included). Prompt tokens roll into the project's month usage (tagged
+`utility_embed`); there is no separate platform credit rate.
+
 ### Spoken audio — use `synthesizeSpeech`, not `/call`
 
 The audio sibling of `extractJson`: text → a downloadable **mp3 file**, OUTSIDE

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.26.1";
+export declare const ADMIN_SDK_VERSION = "0.27.1";
 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
@@ -59,7 +59,7 @@ export interface AdminClientOptions {
  *  published: on this plane the status line never disambiguates, so two of the
  *  durable-run routes answer 409 for two entirely different reasons each, with
  *  different recoveries. `code` is the only thing that tells them apart. */
-export declare const ADMIN_ERROR_CODES: readonly ["schedule_limit_reached", "one_shot_spent", "ghost_row", "channel_limit_reached", "webhook_limit_reached", "run_limit_reached", "reembed_required", "run_terminal", "run_not_parked", "stale_token", "run_not_waiting", "event_mismatch"];
+export declare const ADMIN_ERROR_CODES: readonly ["story_contract_v2_write_disabled", "story_contract_v3_write_disabled", "episode_history_incomplete", "episode_ended", "idempotency_key_reused", "stale_deliberation", "deliberation_disabled", "deliberation_uncalibrated", "deliberation_not_enabled", "deliberation_candidates_exceeded", "schedule_limit_reached", "one_shot_spent", "ghost_row", "channel_limit_reached", "webhook_limit_reached", "run_limit_reached", "reembed_required", "run_terminal", "run_not_parked", "stale_token", "run_not_waiting", "event_mismatch"];
 /** `AdminApiError.code` values. The `(string & {})` arm keeps the type open for
  *  codes newer than this SDK build while preserving autocomplete — same
  *  doctrine as the companion SDK's `CompanionErrorCodeValue`. */
@@ -444,18 +444,24 @@ export interface AdminClient {
     listAgents(): Promise<{
         agents: Agent[];
     }>;
+    /** `droppedSkills` (when present) names any `skills` slugs the platform's
+     *  registered-skill allowlist filtered out — a slug typo (e.g. `client_action`
+     *  vs the registered `client-action`) is named, never silently absent. */
     createAgent(input: {
         name: string;
         archetype: string;
         systemPrompt?: string;
     } & Record<string, unknown>): Promise<{
         agent: Agent;
+        droppedSkills?: string[];
     }>;
     getAgent(agentId: string): Promise<{
         agent: Agent;
     }>;
+    /** See createAgent — `droppedSkills` echoes allowlist-filtered slugs. */
     updateAgent(agentId: string, patch: Partial<Agent> & Record<string, unknown>): Promise<{
         agent: Agent;
+        droppedSkills?: string[];
     }>;
     deleteAgent(agentId: string): Promise<{
         deleted: boolean;
@@ -717,6 +723,52 @@ export interface AdminClient {
             completionTokens: number;
         };
     }>;
+    /** Text → embedding vectors, OUTSIDE the companion — the vector sibling of
+     *  `extractJson`: stateless (no session, no persona, no memory), one provider
+     *  call, typed failures. For a backend that ranks its OWN inventory by cosine
+     *  (album/asset pick, intent-gate exemplars) and wants one billing/key channel
+     *  instead of a second embedding vendor beside its Pouchy keys.
+     *
+     *  `input` is one text or a batch (≤ 64 per request, each ≤ 8000 chars — an
+     *  over-cap text is a 400 naming its index; texts are NEVER silently
+     *  truncated, because a clipped vector poisons a stored index invisibly).
+     *
+     *  The response `model` is a STABLE id (e.g.
+     *  `openai-text-embedding-3-small-768`): persist it next to every stored
+     *  vector, refuse mixed-model cosine, and PIN it in later requests — an id
+     *  the deployment cannot serve exactly answers 400 rather than silently
+     *  substituting, so a platform model swap surfaces as an explicit reindex
+     *  signal. `dimensions` always equals every vector's length.
+     *
+     *  `encodingFormat: 'base64'` returns each vector as little-endian float32
+     *  base64 (~3.5× smaller at 768 dims — use for bulk reindex); default
+     *  `'float'` returns `number[]`.
+     *
+     *  Failures: `invalid_request` (400 — fix and resend), `unavailable` (503 —
+     *  transient, back off and retry), `provider_error` (502 — upstream rejected
+     *  a request the platform believed valid, short provider message included).
+     *
+     *  Prompt tokens roll into the project's month usage (tagged
+     *  `utility_embed`); no separate platform credit rate. */
+    embedTexts(input: {
+        input: string | string[];
+        model?: string;
+        dimensions?: number;
+        encodingFormat?: 'float' | 'base64';
+    }): Promise<{
+        object: 'list';
+        model: string;
+        dimensions: number;
+        data: Array<{
+            object: 'embedding';
+            index: number;
+            embedding: number[] | string;
+        }>;
+        usage?: {
+            promptTokens: number;
+            totalTokens: number;
+        };
+    }>;
     /** Text → a spoken-audio FILE, OUTSIDE the companion and OUTSIDE a realtime
      *  call. The audio sibling of `extractJson`: stateless (no session, no
      *  persona, no memory), one synthesis call, a downloadable clip back. Use it

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.26.1';
+export const ADMIN_SDK_VERSION = '0.27.1';
 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;
@@ -70,6 +70,16 @@ export function requestDeadlineMs(method, path) {
  *  durable-run routes answer 409 for two entirely different reasons each, with
  *  different recoveries. `code` is the only thing that tells them apart. */
 export const ADMIN_ERROR_CODES = [
+    'story_contract_v2_write_disabled',
+    'story_contract_v3_write_disabled',
+    'episode_history_incomplete',
+    'episode_ended',
+    'idempotency_key_reused',
+    'stale_deliberation',
+    'deliberation_disabled',
+    'deliberation_uncalibrated',
+    'deliberation_not_enabled',
+    'deliberation_candidates_exceeded',
     'schedule_limit_reached',
     'one_shot_spent',
     'ghost_row',
@@ -250,6 +260,7 @@ export function createAdminClient(opts) {
         ingestKnowledgeUrl: (input) => request('POST', '/knowledge/url', input),
         searchKnowledge: (query) => request('POST', '/knowledge/search', { query }),
         extractJson: (input) => request('POST', '/utility/json', input),
+        embedTexts: (input) => request('POST', '/utility/embeddings', input),
         synthesizeSpeech: (input) => request('POST', '/utility/tts', input),
         deleteKnowledge: (id) => request('DELETE', `/knowledge/${encodeURIComponent(id)}`),
         listSkills: () => request('GET', '/skills'),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pouchy_ai/admin-sdk",
-	"version": "0.26.1",
+	"version": "0.27.1",
 	"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",