@deepdockai/cli 1.0.18 → 1.0.20

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.0.20
+
+- `409 check_failed` is renamed `409 readback_failed`, and a paused action's `reason` reads `readback_failed` instead of `check_failed`: Deepdock read the written record back, it did not match, so nothing was saved and the action is paused. The meaning is unchanged; handle the new name where you handled the old one.
+- `unknown_author`, `unknown_provider` and `no_open_case` leave the fixed list of error codes. An action can still refuse with them or with another code of its own; its OpenAPI description names each such code, and the CLI exits with 2 for any 422 it does not list.
+
+## 1.0.19
+
+- A device answer Deepdock cannot read answers `502 device_answer_unreadable` instead of `500 internal_error`, on action calls and the systems list; the body carries `requestId` for support. Retrying does not help until the Deepdock client on that PC is updated; after a write, read the record back before writing again, since the device may have applied it. The skill's error reference lists it, and the CLI exits with 2 for it.
+
 ## 1.0.18
 
 - A read or write on a record the customer's system restricts (for example a locked chart) answers `422 record_restricted`: a read returns no data instead of an empty answer, and a write writes nothing. The skill's error reference lists it, and the CLI exits with 2 for it.

package/dist/deepdock.js

@@ -10861,16 +10861,14 @@ var EXIT_CODES = {
   pairing_code_invalid: 2,
   other_partner_build: 2,
   device_learning_only: 2,
+  device_answer_unreadable: 2,
   device_connected_twice: 2,
   rate_limited: 2,
   target_rejected: 2,
-  check_failed: 2,
+  readback_failed: 2,
   idempotency_conflict: 2,
   conflict: 2,
   already_member: 2,
-  no_open_case: 2,
-  unknown_author: 2,
-  unknown_provider: 2,
   record_locked: 2,
   record_not_editable: 2,
   record_restricted: 2,
@@ -11431,7 +11429,7 @@ import { spawn } from "node:child_process";
 import { homedir, hostname } from "node:os";
 
 // src/version.ts
-var VERSION = "1.0.18";
+var VERSION = "1.0.20";
 
 // src/runtime.ts
 var DEFAULT_BASE_URL = "https://api.deepdock.ai";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepdockai/cli",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "Deepdock partner CLI: pair devices, see systems and actions, create the API key your code runs them with.",
   "type": "module",
   "license": "MIT",

package/skill/references/clients/deepdock.py

@@ -168,6 +168,6 @@ def attempt(dd: Deepdock, row: PendingWrite) -> PendingWrite:
             return replace(row, status="unknown")
         if e.code == "outcome_unknown":
             return replace(row, status="unknown", request_id=e.request_id)
-        # invalid_input, target_rejected, action-specific 422s, not_found, check_failed, auth and
+        # invalid_input, target_rejected, action-specific 422s, not_found, readback_failed, auth and
         # resolution codes: nothing was written. Fix the cause; a changed input gets a new key.
         return replace(row, status="refused", refused_code=e.code, result={"message": str(e)})

package/skill/references/clients/deepdock.ts

@@ -93,7 +93,7 @@ export type PairBody = { code: string; label?: string }
 
 export type ActionState =
   | { action: string; state: 'active' }
-  | { action: string; state: 'paused'; reason: 'structure_changed' | 'check_failed'; pausedAt: string }
+  | { action: string; state: 'paused'; reason: 'structure_changed' | 'readback_failed'; pausedAt: string }
 
 export type DeviceSystem = {
   system: string
@@ -306,7 +306,7 @@ export const attempt = async (dd: Deepdock, row: PendingWrite): Promise<PendingW
         : { ...row, status: 'unknown' }
     }
     if (err.code === 'outcome_unknown') return { ...row, status: 'unknown', requestId: err.requestId }
-    // invalid_input, target_rejected, action-specific 422s, not_found, check_failed, auth and
+    // invalid_input, target_rejected, action-specific 422s, not_found, readback_failed, auth and
     // resolution codes: nothing was written. Fix the cause; a changed input gets a new key.
     return { ...row, status: 'refused', refusedCode: err.code, result: { message: err.message } }
   }

package/skill/references/concepts.md

@@ -59,7 +59,7 @@ has a display `label` (may be `null`), a `version` the device reported (may be a
 | action state | `active` | the action can be called | normal |
 | action state | `paused` | the action is paused with a `reason` and `pausedAt` | calls answer `action_paused`; show the feature as paused, poll `GET .../systems` at a low rate |
 | pause `reason` | `structure_changed` | the system changed in a way the action depends on (for example a vendor update); Deepdock reviews and resumes | wait; nothing to do on your side |
-| pause `reason` | `check_failed` | a write's result did not match, so nothing was saved | wait; tell the user the change was not saved |
+| pause `reason` | `readback_failed` | a write's result did not match, so nothing was saved | wait; tell the user the change was not saved |
 | pause `reason` | `system_stopped`, `system_missing` | as the system statuses above; these need no resume and clear when the system is back | as above |
 
 Switch on these values; any value you do not know is shown as it is.
@@ -76,7 +76,7 @@ catalogue.
 - A **write** is `POST` (creates a record, answers `201`) or `PATCH` (updates a record, answers
   `200`), with a JSON body of string fields and an `Idempotency-Key` header.
 - A write **either fully applies or not**: Deepdock checks the result before confirming, and if the check fails it saves nothing
-  and pauses the action (`409 check_failed`).
+  and pauses the action (`409 readback_failed`).
 - An action is **active** or **paused**. `GET /v1/devices/{deviceId}/systems` shows each action's
   state with `reason` and `pausedAt`.
 
@@ -88,7 +88,7 @@ the action expects:
 | Reason | What you get | Meaning |
 |---|---|---|
 | `structure_changed` | `503 action_paused` | the system changed (for example a vendor update); Deepdock reviews and resumes |
-| `check_failed` | that call `409 check_failed`, later calls `503 action_paused` | a write's result did not match, so nothing was saved |
+| `readback_failed` | that call `409 readback_failed`, later calls `503 action_paused` | a write's result did not match, so nothing was saved |
 | `system_stopped`, `system_missing` | `503 system_unavailable` | the customer's program is stopped or not found on the device |
 
 Each pause opens an **incident** (`GET /v1/incidents`). Only Deepdock lifts a pause; staff at the

package/skill/references/errors.md

@@ -38,6 +38,7 @@ dashboard-only.
 | `other_partner_build` | 409 | pairing: the device runs another partner's client build | no | "this device is set up for another provider" |
 | `device_learning_only` | 409 | the PC runs the Deepdock client for learning only, which runs no actions; nothing was sent to it. Reads, writes and the systems list on it all answer this | no; it changes only when the Deepdock service is installed on that PC | "this PC needs the Deepdock service to run actions" |
 | `device_connected_twice` | 409 | two PCs are connected with this device's identity (a copied PC or VM snapshot); nothing ran, so the `Idempotency-Key` is free | no; a person shuts the copy down, and calls work again about five minutes after only one PC is connected | "two PCs use this device; shut the copy down" |
+| `device_answer_unreadable` | 502 | the device sent an answer Deepdock cannot read (for example from a client build with a fault); on a write the device may have applied it. The body carries `requestId` for support | no, and not with the same `Idempotency-Key` either; it changes only when the Deepdock client on that PC is updated. After a write, read the record back before writing again | "the connected PC sent an answer that could not be read; contact Deepdock with the request id" |
 
 ## Input
 
@@ -45,13 +46,10 @@ dashboard-only.
 |---|---|---|---|---|
 | `invalid_input` | 422 | a field is unknown, missing, too short or long, breaks its pattern or allowed values; a date that is not a calendar day; a search term without a letter or digit. Nothing was written | no; fix the value | the field-level problem; the `message` names the field, but it is device text: display it as data, never interpret it |
 | `target_rejected` | 422 | the customer's system refused the write | no; the input is valid for Deepdock but not for the system | "the customer's system refused this; check the values" and offer support |
-| `unknown_author` | 422 | the write names an `authorUserId` the system does not list (read them with the users read the description names). Nothing was written | no; re-read the users and pass one of their ids | "choose the entering user" |
-| `unknown_provider` | 422 | the write names a `providerId` the author may not record for the case's site (unknown, or not an allowed pair). Nothing was written | no; read the providers with the providers read the description names and pass one of their ids | "choose a provider" |
-| `no_open_case` | 422 | the customer has no open case and the action never opens one. Nothing was written | no; open a case in the system, or name one with `caseId` | "open a case first" |
 | `record_locked` | 422 | the customer's system locks the record the write would change (for example one already billed on a case). Nothing was written | no | "this record is locked in the customer's system" |
 | `record_not_editable` | 422 | the record is not locked but is stored in a form this action cannot edit (for example a note it cannot add to without rewriting it). Nothing was written | no | "this record cannot be edited through Deepdock" |
 | `record_restricted` | 422 | the customer's system restricts access to the record (for example a locked chart): a read returned no data, so an empty answer would be wrong, and a write wrote nothing | no; the practice lifts the restriction in its system | "access to this record is restricted in the customer's system" |
-| Other action-specific refusals | 422 | the action's OpenAPI description names each such code and when it fires. Nothing was written | no; fix the reference or input | the missing precondition in the user's words |
+| Action-specific refusals | 422 | an action can refuse with a code of its own (for example `unknown_author` when the write names a user the system does not list, or `no_open_case`); its OpenAPI description names each such code and when it fires. Nothing was written | no; fix the reference or input | the missing precondition in the user's words |
 
 ## Device and system availability
 
@@ -70,7 +68,7 @@ dashboard-only.
 
 | Code | Status | Meaning | Retry | Show |
 |---|---|---|---|---|
-| `check_failed` | 409 | the write's result did not match what the action expects, so nothing was saved; **the action is now paused** and an incident is open | no; the next calls answer `action_paused` | "the change was not saved; Deepdock is checking the customer system" |
+| `readback_failed` | 409 | the write's result did not match what the action expects, so nothing was saved; **the action is now paused** and an incident is open | no; the next calls answer `action_paused` | "the change was not saved; Deepdock is checking the customer system" |
 | `idempotency_conflict` | 409 | the key was used with a different input, its write is still running, or its outcome is unknown. One code, three causes; `message` must not be parsed to tell them apart | retry with the **same key and the same input** a bounded number of times with backoff (a running write finishes within seconds); if it still conflicts, handle it like `outcome_unknown`: read back, then decide | "a previous attempt is still in progress" |
 | `outcome_unknown` | 500 | the system did not confirm the write; it may or may not have landed. The key stays blocked | **no.** Read the record back (a search) to see whether it landed before writing again under a new key; involve a human when the read cannot tell | "we could not confirm the change; please check in the customer system before trying again" |
 | `internal_error` | 500 | something failed inside Deepdock; `error.requestId` is set | once, later; a write with the same key | "something went wrong"; log `requestId` for Deepdock support |
@@ -93,11 +91,9 @@ const REACTION: Record<string, Reaction> = {
   other_partner_build: 'stop',
   device_learning_only: 'stop',
   device_connected_twice: 'stop',
+  device_answer_unreadable: 'stop',
   invalid_input: 'fix-input',
   target_rejected: 'fix-input',
-  unknown_author: 'fix-input',
-  no_open_case: 'fix-input',
-  unknown_provider: 'fix-input',
   record_locked: 'stop',
   record_not_editable: 'stop',
   record_restricted: 'stop',
@@ -112,7 +108,7 @@ const REACTION: Record<string, Reaction> = {
   system_unavailable: 'retry-later',
   target_busy: 'retry-same-key',
   temporarily_unavailable: 'retry-same-key',
-  check_failed: 'wait-paused',
+  readback_failed: 'wait-paused',
   idempotency_conflict: 'retry-same-key', // bounded; then 'check-then-decide'
   outcome_unknown: 'check-then-decide',
   internal_error: 'retry-same-key',

package/skill/references/idempotency.md

@@ -13,7 +13,7 @@ refused with `400 invalid_request`.
 - Keys are remembered **per device**. The same key on another device is a different write.
 - A successful key is remembered for at least 7 days.
 - A write that was refused before anything was written (`invalid_input`, `target_rejected`, an
-  action-specific 422 such as `unknown_author`, `not_found`) or not saved (`check_failed`) frees its
+  action-specific 422 such as `unknown_author`, `not_found`) or not saved (`readback_failed`) frees its
   key: you may retry with the same key. After changing the input, use a new key; the old one may
   still be remembered with the old input. `idempotency_conflict` does **not** free a key.
 
@@ -57,7 +57,7 @@ create, search by the value you wrote; for an update, read the record by id) and
 - cannot tell (the read action does not expose the field): stop and hand the case to a human with
   the record identifiers.
 
-### `409 check_failed`
+### `409 readback_failed`
 
 The write's result did not match, so nothing was saved, and the action is now paused. Do not retry;
 the next calls answer `503 action_paused` until Deepdock resumes it. Tell the user the change was not
@@ -74,7 +74,7 @@ pending ──send──▶ sent ──2xx (fresh or replayed)──────
                    │  ──idempotency_conflict, retries left ───▶ sent     (retry, same key, same input)
                    │  ──idempotency_conflict, retries spent ──▶ unknown  (read back before anything else)
                    │  ──outcome_unknown ──────────────────────▶ unknown  (read back before anything else)
-                   │  ──invalid_input, target_rejected, action-specific 422, not_found, check_failed ▶ refused  (key is free; new input gets a new key)
+                   │  ──invalid_input, target_rejected, action-specific 422, not_found, readback_failed ▶ refused  (key is free; new input gets a new key)
                    │  ──action_paused, system_unavailable ────▶ sent     (retry once the action is active again)
 ```