@deksden-com/cpa-kit 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @deksden-com/cpa-kit
 
+## 0.1.6
+
+### Patch Changes
+
+- 935caa2: Ship a reusable CPA Kit integration skill and document safe upload limits and host responsibilities.
+
 ## 0.1.5
 
 No changes in this release.

package/README.md

@@ -21,6 +21,11 @@ const status = await client.status();
 backend и authorization. Import не запускает процесс, worker или таймеры.
 Секреты, маршруты, supervised worker и maintenance/drain принадлежат приложению.
 
+Skill интеграции для Codex и совместимых агентов включён в пакет:
+скопируйте `node_modules/@deksden-com/cpa-kit/skills/cpa-kit` в
+`.agents/skills/cpa-kit` проекта. Установку с фиксацией ревизии и обновление
+описано в [README репозитория](https://github.com/deksden-com/dd-cpa-kit#с-чего-начать).
+
 - [Индекс документации](https://github.com/deksden-com/dd-cpa-kit/blob/main/docs/index.md): рецепты интеграции и API.
 - [Обновления и соединения](https://github.com/deksden-com/dd-cpa-kit/blob/main/docs/operations.md): безопасная остановка, drain, rollback и cleanup.
 

package/dist/contracts/index.d.ts

@@ -360,10 +360,10 @@ declare const acceptSchema: z.ZodObject<{
     apiVersion: z.ZodLiteral<1>;
     operationId: z.ZodString;
     state: z.ZodEnum<{
-        queued: "queued";
         running: "running";
-        succeeded: "succeeded";
         failed: "failed";
+        queued: "queued";
+        succeeded: "succeeded";
         cancelled: "cancelled";
         partially_applied: "partially_applied";
         recovery_required: "recovery_required";
@@ -390,10 +390,10 @@ declare const operationSchema: z.ZodObject<{
     }>;
     actorId: z.ZodString;
     state: z.ZodEnum<{
-        queued: "queued";
         running: "running";
-        succeeded: "succeeded";
         failed: "failed";
+        queued: "queued";
+        succeeded: "succeeded";
         cancelled: "cancelled";
         partially_applied: "partially_applied";
         recovery_required: "recovery_required";
@@ -504,8 +504,8 @@ declare const statusSchema: z.ZodObject<{
         }>;
         version: z.ZodNullable<z.ZodString>;
         state: z.ZodEnum<{
-            running: "running";
             unknown: "unknown";
+            running: "running";
             stopped: "stopped";
         }>;
     }, z.core.$strict>;
@@ -525,9 +525,9 @@ declare const statusSchema: z.ZodObject<{
             stale: "stale";
         }>;
         probeState: z.ZodEnum<{
-            failed: "failed";
             unknown: "unknown";
             passed: "passed";
+            failed: "failed";
         }>;
         checkedAt: z.ZodNullable<z.ZodISODateTime>;
     }, z.core.$strict>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/cpa-kit",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Embeddable CPA administration mechanisms",
   "type": "module",
   "license": "UNLICENSED",
@@ -37,6 +37,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "CHANGELOG.md",
     "NOTICE"

package/skills/cpa-kit/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: cpa-kit
+description: Integrate or operate CPA Kit in a Node.js application, including its protected admin API, supervised worker, credential import and optional React console. Use when working with @deksden-com/cpa-kit or its host integration; not for ordinary inference API calls.
+---
+
+# CPA Kit integration
+
+CPA Kit embeds CLIProxyAPI administration into a host application. It is not a CPA server, login system, or inference SDK. Inspect the host's existing integration, deployment, and installed package versions before changing it; preserve its authentication, settings and operational contracts.
+
+- Install `@deksden-com/cpa-kit` from public npm. Add `@deksden-com/cpa-kit-react` only for UI, with matching exact core peer and React / React DOM 19.2.x. The host runs Node >=22.23.2. Import browser-safe types from the package root or `/contracts`, the host HTTP client from `/client`, and server-only adapters from `/server`; never bundle server exports or secrets into the browser.
+- Select only capabilities the host can actually provide. The read-only backend is suitable for a remote inference endpoint; file authorization management and core switching require the documented lifecycle, durable stores, authorization and maintenance adapters. Kit never installs or starts CPA as an import side effect.
+- Expose the documented host-owned HTTP routes behind authentication, per-instance authorization and CSRF/origin and rate-limit protection for mutations. Actor identity comes from the server session. Sanitize errors and logs. HTTP 202 means queued, not completed; the UI polls operation state.
+- Run a supervised worker per instance with shared durable journal, staging and model cache. Recover operations before consuming the queue, execute accepted operations outside the request, and run staging cleanup periodically. For multi-process or multi-host deployments use compatible shared coordination; local POSIX file locks are not a distributed lock.
+- For imports, enforce matching request and staging upload limits. Keep entry, decompression and parsing limits independently bounded; allow multipart overhead at the HTTP layer and account for memory if buffering. Use upload → stage → preview → confirmed apply, preserve the intended merge/replace semantics, and reap temporary data. Never log credentials or retry an uncertain partial apply blindly.
+- Before stopping or switching CPA or its managed auth files, close admission to all inference users and drain active requests including streams; verify health and rollback/recovery according to host capabilities. If drain or recovery cannot be assured, expose those capabilities as unavailable.
+- The host creates its own AI SDK or HTTP inference client using the CPA endpoint and server-side secrets. The administrative `/client` is not the inference client.
+
+Consult the maintained [integration guide](https://github.com/deksden-com/dd-cpa-kit/blob/main/docs/integration.md) for route mappings and examples, the [operations guide](https://github.com/deksden-com/dd-cpa-kit/blob/main/docs/operations.md) for safety and recovery, and the [contract](https://github.com/deksden-com/dd-cpa-kit/blob/main/docs/contract-v1.md) for schemas and limits. For host-specific behavior, installed package types and host configuration are authoritative; guides on `main` can describe a newer release.
+
+After changes, test authentication and capability boundaries, worker recovery, temporary-file cleanup and the affected UI/API paths using synthetic data. Follow the host's deployment and test-isolation rules; do not run paid probes or change live credentials unless requested.