@pouchy_ai/admin-sdk 0.29.0 → 0.31.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.31.0 — 2026-09-05
+
+- **`Agent.spawnSubtasks?`** and **`Agent.replyCues?`** (`ReplyCues`
+  exported) — two per-agent knobs the platform already accepts on
+  `PATCH /v1/projects/{id}/agents/{agentId}` and reports on the agent, typed
+  now instead of falling through the index signature. `spawnSubtasks` offers
+  the synthetic `spawn_subtasks` tool (default false, D-10); `replyCues`
+  opts the agent's text turns into `companion.audio` / `companion.expression`
+  (design #25). Additive.
+
+## 0.30.0 — 2026-09-04
+
+- **`internal-a2a` leaves `ChannelTransportType`.** It was a placeholder the
+  platform's union and store knew and no adapter served — `createChannel`
+  answered 400 on it, which is why `CreatableChannelType` excluded it. The
+  platform retired the id (design #24 / F-04: the friend auto-reply is a
+  companion session SURFACE, not a transport), so the union no longer names it
+  and `CreatableChannelType` is now the whole union. A caller that referenced
+  the literal type gets a compile error, which is the point; nothing that ever
+  worked changes.
+
+## 0.29.1 — 2026-09-04
+
+- **`story_contract_v4_write_disabled`** joins `ADMIN_ERROR_CODES` — a Story
+  Package publish that declares a `public: true` flag (Story Contract v4,
+  design #23) answers 409 with this code in an environment that has not
+  enabled v4 writes, the field intact. Vocabulary only; no method changed.
+
 ## 0.29.0 — 2026-08-31
 
 - **`setSkillAutoRunTools(slug, toolNames)` — the per-tool confirm exemptions

package/README.md

@@ -308,15 +308,19 @@ createAdminClient({
 });
 ```
 
-`timeoutMs` defaults to **30s**, except for the four requests whose server
-handler declares `maxDuration: 300` and therefore answers only when the work is
+`timeoutMs` defaults to **30s**, except for the requests whose server handler
+declares `maxDuration: 300` and therefore answers only when the work is
 finished — `POST /knowledge`, `POST /knowledge/file`, `POST /knowledge/url`
-(chunk + summarize + embed, after OCR / Whisper / vision or a page fetch) and
-`DELETE /users/{instanceId}` (recursive GDPR erasure). Those default to **310s**
-(`LONG_WORK_TIMEOUT_MS`), so a client abort can only ever mean "the server really
-is hung", never "the server is still working" — a shorter deadline there reports
-a failure for an ingest that is succeeding, and the retry it invites races the
-still-running first one.
+(chunk + summarize + embed, after OCR / Whisper / vision or a page fetch),
+`DELETE /users/{instanceId}` (recursive GDPR erasure) and
+`POST /capabilities/{name}/test-action` (the Action protocol verifier makes
+REAL deliveries to your endpoint, and an abort mid-test cannot undo the ones
+already made). Those default to **310s** (`LONG_WORK_TIMEOUT_MS`), so a client
+abort can only ever mean "the server really is hung", never "the server is
+still working" — a shorter deadline there reports a failure for an ingest that
+is succeeding, and the retry it invites races the still-running first one (or
+re-runs a side-effecting test whose first verdict is never read). The list is
+`LONG_WORK_REQUESTS`, exported, and a drift test binds it to the routes.
 
 Setting `timeoutMs` explicitly always wins and applies to **every** request, long
 or short. `requestDeadlineMs(method, path)` returns the default a given request
@@ -449,8 +453,8 @@ Reads (`GET`) are not covered by that bucket. `retryAfter` is available from
 | Escape hatch | `request(method, path, body?)` — any endpoint not yet typed |
 
 Channel types are checked at compile time: `createChannel` takes a
-`CreatableChannelType` (the platform's 82-transport union minus the adapterless
-`internal-a2a`), and `secret` is a named `ChannelSecretInput`. Per-transport
+`CreatableChannelType` (the platform's 81-transport union — every member has an
+adapter since 0.30.0), and `secret` is a named `ChannelSecretInput`. Per-transport
 `secret.extra` fields are listed in <https://pouchy.ai/docs/channel-setup>.
 
 **Telegram and Discord register themselves.** On create — and again on a

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.29.0";
+export declare const ADMIN_SDK_VERSION = "0.31.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
@@ -38,7 +38,8 @@ export interface AdminClientOptions {
     fetch?: typeof fetch;
     /** Per-request timeout in ms. Default 30s, EXCEPT the requests whose server
      *  handler declares `maxDuration: 300` (knowledge ingest by text/file/url,
-     *  and the GDPR user delete), which default to
+     *  the GDPR user delete, and the capability test-action verifier — the
+     *  list is {@link LONG_WORK_REQUESTS}), which default to
      *  {@link LONG_WORK_TIMEOUT_MS}. Setting this explicitly always wins and
      *  applies to every request, long or short. A request that outlives its
      *  deadline rejects with an AdminApiError(status 0).
@@ -59,7 +60,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 ["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"];
+export declare const ADMIN_ERROR_CODES: readonly ["story_contract_v2_write_disabled", "story_contract_v3_write_disabled", "story_contract_v4_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`. */
@@ -123,6 +124,16 @@ export interface AgentData {
         subscriptions?: string[];
     };
 }
+/** Opt the agent's text turns into the two outbound cue events (design #25):
+ *  `audio` → `companion.audio` (a TTS mp3 of the reply; `voiceId` picks the
+ *  voice), `expression` → `companion.expression` (a VRM 1.0 preset read from
+ *  the reply's tone). Neither delays the reply; neither fires on A2A or
+ *  channel surfaces. */
+export interface ReplyCues {
+    audio?: boolean;
+    expression?: boolean;
+    voiceId?: string;
+}
 export interface Agent {
     agentId: string;
     name: string;
@@ -132,6 +143,12 @@ export interface Agent {
     modelTier?: ModelTier;
     /** Agent Data plane flags (see AgentData). */
     data?: AgentData;
+    /** Offer the synthetic `spawn_subtasks` tool on this agent's turns
+     *  (concurrent headless workers under one persona). Default false since
+     *  owner decision D-10 (2026-09-05). */
+    spawnSubtasks?: boolean;
+    /** Reply-cue opt-in (see ReplyCues). */
+    replyCues?: ReplyCues;
     templateRev: number;
     createdAt: string;
     [k: string]: unknown;
@@ -332,11 +349,12 @@ export interface DeliveryOutcome {
  *  (`channels/types.ts`) — this package is standalone and cannot import it, so
  *  `admin-sdk-channel-types.drift.test.ts` binds the two and fails CI if either
  *  side gains a transport the other lacks. */
-export type ChannelTransportType = 'echo' | 'matrix' | 'telegram' | 'web' | 'activitypub' | 'internal-a2a' | 'discord' | 'slack' | 'nostr' | 'atproto' | 'sms' | 'email' | 'whatsapp' | 'messenger' | 'instagram' | 'line' | 'teams' | 'wechat' | 'wecom' | 'feishu' | 'dingtalk' | 'twitter' | 'xmpp' | 'qq' | 'kakao' | 'viber' | 'signal' | 'weibo' | 'alexa' | 'google-assistant' | 'voice' | 'onlyfans' | 'fansly' | 'fanvue' | 'imessage' | 'rcs' | 'intercom' | 'twitch' | 'zalo' | 'douyin' | 'kick' | 'reddit' | 'xmtp' | 'guilded' | 'youtube-live' | 'bilibili-live' | 'minecraft' | 'steam' | 'vk' | 'ok' | 'threads' | 'groupme' | 'threema' | 'mattermost' | 'rocketchat' | 'zulip' | 'farcaster' | 'tiktok' | 'crisp' | 'freshchat' | 'front' | 'gorgias' | 'kustomer' | 'helpscout' | 'livechat' | 'zohodesk' | 'hubspot' | 'zendesk' | 'salesforce' | 'webex' | 'chatwork' | 'google-chat' | 'zohocliq' | 'zoom' | 'line-works' | 'ringcentral' | 'vonage' | 'github' | 'gitlab' | 'bitbucket' | 'jira' | 'linear' | 'discourse';
-/** Transports `createChannel` accepts. `internal-a2a` is in the union but has
- *  no adapter, so the server answers 400 — excluding it here turns a runtime
- *  rejection into a compile error. */
-export type CreatableChannelType = Exclude<ChannelTransportType, 'internal-a2a'>;
+export type ChannelTransportType = 'echo' | 'matrix' | 'telegram' | 'web' | 'activitypub' | 'discord' | 'slack' | 'nostr' | 'atproto' | 'sms' | 'email' | 'whatsapp' | 'messenger' | 'instagram' | 'line' | 'teams' | 'wechat' | 'wecom' | 'feishu' | 'dingtalk' | 'twitter' | 'xmpp' | 'qq' | 'kakao' | 'viber' | 'signal' | 'weibo' | 'alexa' | 'google-assistant' | 'voice' | 'onlyfans' | 'fansly' | 'fanvue' | 'imessage' | 'rcs' | 'intercom' | 'twitch' | 'zalo' | 'douyin' | 'kick' | 'reddit' | 'xmtp' | 'guilded' | 'youtube-live' | 'bilibili-live' | 'minecraft' | 'steam' | 'vk' | 'ok' | 'threads' | 'groupme' | 'threema' | 'mattermost' | 'rocketchat' | 'zulip' | 'farcaster' | 'tiktok' | 'crisp' | 'freshchat' | 'front' | 'gorgias' | 'kustomer' | 'helpscout' | 'livechat' | 'zohodesk' | 'hubspot' | 'zendesk' | 'salesforce' | 'webex' | 'chatwork' | 'google-chat' | 'zohocliq' | 'zoom' | 'line-works' | 'ringcentral' | 'vonage' | 'github' | 'gitlab' | 'bitbucket' | 'jira' | 'linear' | 'discourse';
+/** Transports `createChannel` accepts — the whole union, since 0.30.0: the
+ *  adapterless `internal-a2a` placeholder this type used to exclude was
+ *  retired from the platform's union (design #24 / F-04). Kept as a named
+ *  alias so existing imports compile unchanged. */
+export type CreatableChannelType = ChannelTransportType;
 /** Credentials for a connector, sealed server-side as one AES-GCM blob.
  *
  *  `extra` is where the transports needing more than a token live — Twitter

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.29.0';
+export const ADMIN_SDK_VERSION = '0.31.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;
@@ -72,6 +72,7 @@ export function requestDeadlineMs(method, path) {
 export const ADMIN_ERROR_CODES = [
     'story_contract_v2_write_disabled',
     'story_contract_v3_write_disabled',
+    'story_contract_v4_write_disabled',
     'episode_history_incomplete',
     'episode_ended',
     'idempotency_key_reused',
@@ -194,8 +195,9 @@ export function createAdminClient(opts) {
         throw new AdminApiError('no fetch available — pass opts.fetch on Node <18', 0);
     async function request(method, path, body) {
         // An explicit host `timeoutMs` always wins (JS SDK contract); otherwise
-        // the deadline is sized to the ROUTE, so the four handlers that declare
-        // `maxDuration: 300` are not cut at 30s while they are still working.
+        // the deadline is sized to the ROUTE, so the handlers that declare
+        // `maxDuration: 300` (LONG_WORK_REQUESTS) are not cut at 30s while they
+        // are still working.
         // `??` (not `||`) is deliberate: 0 is a SET value meaning "no deadline",
         // and it must not fall through to the route default.
         const timeoutMs = opts.timeoutMs ?? requestDeadlineMs(method, path);

package/package.json

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