@pouchy_ai/admin-sdk 0.33.0 → 0.36.0

package/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.36.0 — 2026-09-12
+
+- **`deleteChannel` reports what happened to the PROVIDER registration**, and
+  takes `{ deprovision: false }` to suppress it. Admin API 1.13.0. Additive:
+  the option is optional and the response field is new.
+
+  Create has registered telegram/discord connectors with their provider since
+  1.6.0 (`setWebhook` / the slash command). Delete never unregistered — and the
+  asymmetry was worse than an omission, because the delete also destroys the
+  stored bot token, so afterwards nothing on the server side could ever do it.
+  The bot kept pushing every message it could see to a dead inbound URL, which
+  on a fail-closed rate-limited prefix also keeps spending the project's
+  limiter quota.
+
+  Surfaced by an integrator asking whether `DELETE` called `deleteWebhook` —
+  the shape of question that is worth answering by reading the code.
+
+- `ChannelProvisionCode` gains `webhook_deleted`, `command_deleted` and
+  `command_absent`. The union is closed and a published member is never removed,
+  so handle an unknown code as informational. `command_absent` is a **skip**,
+  not an ok: the Discord command was already gone, and "we removed it" versus
+  "there was nothing to remove" are different facts about the provider.
+
+## 0.35.0 — 2026-09-10
+
+### Added
+
+- **Four story-package codes join `ADMIN_ERROR_CODES`**, and two of them were
+  already on the wire without being in it. `has_pins` and `pins_unknown` are
+  the two 409s of `DELETE …/story-packages/{packageId}` (world API 1.35.0):
+  an environment revision has pinned this package, versus the package predates
+  the pin stamp so whether one points at it is UNKNOWN and is not guessed. They
+  shipped through the same VARIABLE indirection that hid
+  `story_contract_v2_write_disabled` — the route forwarded `result.reason` as
+  `code`, so the vocabulary census could not see them; the route spells them
+  out now.
+
+  `story_package_limit` and `story_package_documents_limit` are the two ceiling
+  refusals, newly carrying a code at all. An integrator reported asserting on
+  the refusal SENTENCES because they were the only observation point for the
+  quota — which made a copy edit a breaking change for them and a number change
+  harmless, the exact inversion of what either should cost. The codes retire
+  the prose parsing.
+
+  Distinguishing the two delete refusals matters because their outs differ:
+  `has_pins` sends you to an environment, `pins_unknown` sends you to disable.
+
+## 0.34.0 — 2026-09-08
+
+### Fixed
+
+- **`instructions`, `knowledgeDocIds` and `agentCardExtras` were dropped by the
+  agent create/update surface, so setting any of them answered `200` and did
+  nothing.** `agent-input.ts` maps a request body onto `createAgent`/
+  `updateAgent` with an object literal that enumerates its fields, and three
+  fields the store accepts had fallen out of it — on BOTH management surfaces
+  (`/v1/admin/agents` and `/v1/projects/{id}/agents`) and therefore the
+  Dashboard too, which PATCHes the latter. `instructions` was dead the day it
+  shipped; the Dashboard's knowledge-scope picker has been a silent no-op for
+  as long as it has existed; `agentCardExtras` is documented for the DeJoy
+  integration and was unreachable over HTTP. Server-side fix — no SDK change
+  was needed to make them work.
+
+### Added
+
+- `Agent.knowledgeDocIds?: string[]` — typed alongside `instructions`, so the
+  two fields this release un-drops are both discoverable from the SDK rather
+  than only from the API reference.
+
 ## 0.33.0 — 2026-09-08
 
 ### Added

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.33.0";
+export declare const ADMIN_SDK_VERSION = "0.36.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
@@ -60,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", "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"];
+export declare const ADMIN_ERROR_CODES: readonly ["story_contract_v2_write_disabled", "story_contract_v3_write_disabled", "story_contract_v4_write_disabled", "has_pins", "pins_unknown", "story_package_limit", "story_package_documents_limit", "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`. */
@@ -165,6 +165,9 @@ export interface Agent {
      *  (concurrent headless workers under one persona). Default false since
      *  owner decision D-10 (2026-09-05). */
     spawnSubtasks?: boolean;
+    /** Restrict this agent's project-knowledge recall to the named documents
+     *  (`[]` clears). Read live off the agent row every turn — no rev bump. */
+    knowledgeDocIds?: string[];
     /** 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
@@ -398,13 +401,15 @@ export interface ChannelSecretInput {
     extra?: Record<string, string>;
 }
 /** Outcome class of the provider registration the server performs on create,
- *  and on a rotate / secret replacement. Mirrors the server's `ProvisionStatus`
- *  (`channels/provision.ts`); `admin-sdk-provision.drift.test.ts` binds them. */
+ *  on a rotate / secret replacement, and — from admin API 1.13.0 — the
+ *  UNregistration it performs on delete. Mirrors the server's
+ *  `ProvisionStatus` (`channels/provision.ts`);
+ *  `admin-sdk-provision.drift.test.ts` binds them. */
 export type ChannelProvisionStatus = 'ok' | 'skipped' | 'failed';
 /** Machine-readable reason for a `ChannelProvisionResult`. The server treats
  *  this vocabulary as part of the response contract (the dashboard keys its
  *  copy off it), so branch on `code`, never on `detail`. */
-export type ChannelProvisionCode = 'webhook_set' | 'command_registered' | 'unsupported_type' | 'no_token' | 'no_inbound_url' | 'not_requested' | 'invalid_command_name' | 'app_lookup_failed' | 'upstream_rejected' | 'upstream_unreachable';
+export type ChannelProvisionCode = 'webhook_set' | 'command_registered' | 'unsupported_type' | 'no_token' | 'no_inbound_url' | 'not_requested' | 'invalid_command_name' | 'app_lookup_failed' | 'upstream_rejected' | 'upstream_unreachable' | 'webhook_deleted' | 'command_deleted' | 'command_absent';
 /** What the provider said when the server registered this connector for you.
  *
  *  Registration is an enrichment on top of a durable write: the connector
@@ -1080,8 +1085,24 @@ export interface AdminClient {
          *  transport, when not suppressed with `autoProvision: false`. */
         provision?: ChannelProvisionResult;
     }>;
-    deleteChannel(channelId: string): Promise<{
+    /** Delete a connector — and, for telegram/discord, UNREGISTER it with the
+     *  provider first (admin API 1.13.0).
+     *
+     *  The ordering is the point: the delete also destroys the stored bot token,
+     *  so an unregistration skipped at that moment can never be done afterwards
+     *  from the server side — the bot would keep pushing every message it can see
+     *  to a dead inbound URL, and only whoever holds the token could stop it.
+     *
+     *  Same contract as create-side registration: the connector is removed
+     *  whether or not the provider answers, and a `failed` outcome carries
+     *  `manualCommand`. Pass `deprovision: false` to keep the provider
+     *  registration (for a caller who manages the bot webhook themselves). */
+    deleteChannel(channelId: string, options?: {
+        deprovision?: false;
+    }): Promise<{
         ok: boolean;
+        /** Absent for a transport with no provider registration. */
+        deprovision?: ChannelProvisionResult;
     }>;
     listSchedules(): Promise<{
         schedules: unknown[];

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.33.0';
+export const ADMIN_SDK_VERSION = '0.36.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;
@@ -73,6 +73,10 @@ export const ADMIN_ERROR_CODES = [
     'story_contract_v2_write_disabled',
     'story_contract_v3_write_disabled',
     'story_contract_v4_write_disabled',
+    'has_pins',
+    'pins_unknown',
+    'story_package_limit',
+    'story_package_documents_limit',
     'episode_history_incomplete',
     'episode_ended',
     'idempotency_key_reused',
@@ -330,7 +334,7 @@ export function createAdminClient(opts) {
         createChannel: (input) => request('POST', '/channels', input),
         getChannel: (id) => request('GET', `/channels/${encodeURIComponent(id)}`),
         updateChannel: (id, patch) => request('PATCH', `/channels/${encodeURIComponent(id)}`, patch),
-        deleteChannel: (id) => request('DELETE', `/channels/${encodeURIComponent(id)}`),
+        deleteChannel: (id, options) => request('DELETE', `/channels/${encodeURIComponent(id)}${options?.deprovision === false ? '?deprovision=false' : ''}`),
         listSchedules: () => request('GET', '/schedules'),
         createSchedule: (input) => request('POST', '/schedules', input),
         getSchedule: (id) => request('GET', `/schedules/${encodeURIComponent(id)}`),

package/package.json

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