@deepdockai/cli 1.0.6 → 1.0.8

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.0.8
+
+- The CLI knows `system_version_unverified` (exit code 3, retry later): a write on a customer system whose vendor version Deepdock has not verified yet is refused before anything is sent, and works once Deepdock has verified that version (`reason: unverified_version`). A version the API cannot parse (`reason: unparseable`) does not clear by waiting: contact Deepdock. Reads are unaffected.
+- A device's systems carry `writes` (`verified`, `unknown`, `partial`, or `unverified` with a `reason`) in the agent skill's TypeScript client, and the skill's error, idempotency and concepts references describe the refusal.
+
+## 1.0.7
+
+- The CLI knows `device_syncing` and `device_outdated` (exit code 3, retry later) instead of falling back on the HTTP status.
+- The agent skill's error reference and both clients' pending-write helpers retry them with the same key.
+- `--help`, the README and the skill's CLI and idempotency references list every exit-3 code, `outcome_unknown` and the access codes included.
+
 ## 1.0.6
 
 - The agent skill's TypeScript client types a device's `hostname`, `os` and `clientVersion` as `string | null`, as the API answers them before the device has reported them. The skill names `GET /v1/devices` and `GET /v1/devices/{deviceId}`.

package/README.md

@@ -154,14 +154,14 @@ your code will receive; `auth`, `org select` and `keys create` build it from nam
 failure is one document on stderr, `{ "error": { "code", "message" }, "meta": { "hint" } }`,
 with the API's error object unchanged. Switch on `code` or on the exit code, never on `message`.
 
-| Exit | Meaning                                                                                                                                              |
-| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 0    | done                                                                                                                                                 |
-| 1    | something on the command line to fix (`invalid_usage`, `org_required`)                                                                               |
-| 2    | the API refused the request; do not repeat it unchanged (`invalid_request`, `not_found`, `forbidden`, `rate_limited` and the other refusals)         |
-| 3    | retry later (`device_offline`, `action_paused`, `system_unavailable`, `target_busy`, `temporarily_unavailable`, `internal_error`, `connection_lost`) |
-| 4    | the CLI is too old for the API (`client_outdated`): run `npx @deepdockai/cli@latest`                                                                 |
-| 5    | sign-in needed (`sign_in_needed`, `approval_denied`, `approval_expired`); `auth status` when nobody is signed in                                     |
+| Exit | Meaning                                                                                                                                                                                                                                                                        |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 0    | done                                                                                                                                                                                                                                                                           |
+| 1    | something on the command line to fix (`invalid_usage`, `org_required`)                                                                                                                                                                                                         |
+| 2    | the API refused the request; do not repeat it unchanged (`invalid_request`, `not_found`, `forbidden`, `rate_limited` and the other refusals)                                                                                                                                   |
+| 3    | retry later (`device_offline`, `device_syncing`, `device_outdated`, `system_version_unverified`, `action_paused`, `access_outdated`, `access_missing`, `system_unavailable`, `target_busy`, `temporarily_unavailable`, `internal_error`, `outcome_unknown`, `connection_lost`) |
+| 4    | the CLI is too old for the API (`client_outdated`): run `npx @deepdockai/cli@latest`                                                                                                                                                                                           |
+| 5    | sign-in needed (`sign_in_needed`, `approval_denied`, `approval_expired`); `auth status` when nobody is signed in                                                                                                                                                               |
 
 The CLI never retries on its own: exit 3 says retry, you decide when. `deepdock commands --json`
 prints the whole command tree.

package/dist/deepdock.js

@@ -10872,6 +10872,9 @@ var EXIT_CODES = {
   record_not_editable: 2,
   payload_too_large: 2,
   device_offline: 3,
+  device_syncing: 3,
+  device_outdated: 3,
+  system_version_unverified: 3,
   action_paused: 3,
   access_outdated: 3,
   access_missing: 3,
@@ -11424,7 +11427,7 @@ import { spawn } from "node:child_process";
 import { homedir, hostname } from "node:os";
 
 // src/version.ts
-var VERSION = "1.0.6";
+var VERSION = "1.0.8";
 
 // src/runtime.ts
 var DEFAULT_BASE_URL = "https://api.deepdock.ai";
@@ -12149,8 +12152,10 @@ var EXIT_CODES_HELP = `Exit codes
   0  done
   1  usage: something on the command line to fix (invalid_usage, org_required)
   2  the API refused the request; do not repeat it unchanged
-  3  retry later (device_offline, action_paused, system_unavailable, target_busy,
-     temporarily_unavailable, internal_error, connection_lost)
+  3  retry later (device_offline, device_syncing, device_outdated,
+     system_version_unverified, action_paused, access_outdated, access_missing,
+     system_unavailable, target_busy, temporarily_unavailable, internal_error,
+     outcome_unknown, connection_lost)
   4  the CLI is too old for the API (client_outdated)
   5  sign-in needed (sign_in_needed, approval_denied, approval_expired; auth status when nobody is signed in)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepdockai/cli",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Deepdock partner CLI: pair devices, see systems and actions, create the API key your code runs them with.",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,6 @@
     "lint": "biome lint .",
     "lint:fix": "biome lint --write .",
     "typecheck": "tsc --noEmit",
-    "gen:codes": "bun scripts/genCodes.ts",
     "gen:devices": "bun scripts/genDevices.ts",
     "check:public": "bun scripts/checkPublic.ts --pack",
     "test": "bun run build && bun --bun vitest run",

package/skill/references/cli.md

@@ -84,7 +84,7 @@ A failure is one document on stderr: the API's error object unchanged plus what
 | 0 | done | |
 | 1 | something on the command line to fix | `invalid_usage` (a bad flag, an unknown slug, a question with no terminal and no `--yes`, an env file git does not ignore), `org_required` |
 | 2 | the API refused the request; do not repeat it unchanged | `invalid_request`, `not_found`, `device_not_found`, `pairing_code_invalid`, `other_partner_build`, `rate_limited`, `forbidden`, `conflict` and the other refusals (not `access_outdated` and `access_missing`, see exit 3) |
-| 3 | retry later (`access_outdated` and `access_missing`: after the customer repeats "Erneut einrichten" in the Deepdock client) | `device_offline`, `action_paused`, `access_outdated`, `access_missing`, `system_unavailable`, `target_busy`, `temporarily_unavailable`, `internal_error`, `connection_lost` |
+| 3 | retry later (`access_outdated` and `access_missing`: after the customer repeats "Erneut einrichten" in the Deepdock client) | `device_offline`, `device_syncing`, `device_outdated`, `system_version_unverified`, `action_paused`, `access_outdated`, `access_missing`, `system_unavailable`, `target_busy`, `temporarily_unavailable`, `internal_error`, `outcome_unknown`, `connection_lost` |
 | 4 | the CLI is too old for the API: run `npx @deepdockai/cli@latest` | `client_outdated` |
 | 5 | sign-in needed: run `deepdock auth login` | `sign_in_needed`, `approval_denied`, `approval_expired` |
 

package/skill/references/clients/deepdock.py

@@ -19,12 +19,15 @@ class DeepdockError(Exception):
     """Deepdock answered `{ "error": { "code", ... } }`. Switch on `code`, never on `message`."""
 
     def __init__(self, status: int, code: str, message: str, request_id: Optional[str] = None,
-                 systems: Optional[List[str]] = None):
+                 systems: Optional[List[str]] = None, version: Optional[str] = None,
+                 reason: Optional[str] = None):
         super().__init__(message)
         self.status = status
         self.code = code
         self.request_id = request_id
         self.systems = systems
+        self.version = version  # system_version_unverified: the version the system last reported
+        self.reason = reason  # system_version_unverified: unverified_version or unparseable
 
 
 class DeepdockTransportError(Exception):
@@ -63,7 +66,8 @@ class Deepdock:
             raise DeepdockTransportError(f"non-JSON answer with status {r.status_code}")
         if isinstance(body, dict) and "error" in body:
             e = body["error"]
-            raise DeepdockError(r.status_code, e["code"], e["message"], e.get("requestId"), e.get("systems"))
+            raise DeepdockError(r.status_code, e["code"], e["message"], e.get("requestId"), e.get("systems"),
+                                e.get("version"), e.get("reason"))
         if not isinstance(body, dict) or "data" not in body:
             raise DeepdockTransportError(f"unexpected body with status {r.status_code}")
         return body["data"], r.headers
@@ -122,12 +126,15 @@ class Deepdock:
 # Pending writes: one attempt against persisted state. Persist the row BEFORE the first send, so a
 # crash between send and answer cannot produce a second record under a new key. A job retries rows
 # left in "sent" with backoff (seconds, then minutes, for hours if the device stays offline).
+# For system_version_unverified and device_outdated, poll the device's `writes` / `outdated` before
+# retrying: they take longer than minutes.
 # --------------------------------------------------------------------------------------------------
 
 CONFLICT_RETRIES = 5  # a running write finishes within seconds; beyond this, treat it as unknown
 
-RETRY_SAME_KEY = {"device_offline", "target_busy", "temporarily_unavailable", "internal_error",
-                  "action_paused", "system_unavailable"}
+RETRY_SAME_KEY = {"device_offline", "device_syncing", "device_outdated", "system_version_unverified",
+                  "target_busy", "temporarily_unavailable", "internal_error", "action_paused",
+                  "system_unavailable"}
 
 
 @dataclass

package/skill/references/clients/deepdock.ts

@@ -13,14 +13,24 @@ export class DeepdockError extends Error {
   readonly code: string
   readonly requestId?: string
   readonly systems?: string[]
+  /** system_version_unverified: the version the system last reported. */
+  readonly version?: string
+  /** system_version_unverified: `unverified_version` or `unparseable`. */
+  readonly reason?: string
 
-  constructor(status: number, code: string, message: string, requestId?: string, systems?: string[]) {
+  constructor(status: number, code: string, message: string, requestId?: string,
+    systems?: string[],
+    version?: string,
+    reason?: string,
+  ) {
     super(message)
     this.name = 'DeepdockError'
     this.status = status
     this.code = code
     this.requestId = requestId
     this.systems = systems
+    this.version = version
+    this.reason = reason
   }
 }
 
@@ -32,7 +42,7 @@ export class DeepdockTransportError extends Error {
   }
 }
 
-type ErrorBody = { code: string; message: string; requestId?: string; systems?: string[] }
+type ErrorBody = { code: string; message: string; requestId?: string; systems?: string[]; version?: string; reason?: string }
 type Envelope<T> = { data: T } | { error: ErrorBody }
 
 export type Page<Item> = { items: Item[]; nextCursor: string | null }
@@ -43,6 +53,15 @@ export type SystemStatus = 'running' | 'stopped' | 'missing' | 'unknown'
 /** The database access the device last reported; `null` while none is known. */
 export type SystemAccess = 'ok' | 'outdated' | 'missing' | 'not_set_up' | null
 
+/**
+ * Whether writes on the system run. `unverified` makes writes answer system_version_unverified:
+ * `unverified_version` clears once Deepdock verifies the version; `unparseable` does not clear by
+ * waiting (contact Deepdock).
+ */
+export type SystemWrites =
+  | { state: 'verified' | 'unknown' | 'partial' }
+  | { state: 'unverified'; reason: 'unverified_version' | 'unparseable' }
+
 export type Device = {
   id: string
   label: string | null
@@ -55,7 +74,14 @@ export type Device = {
   /** True when an action assigned to you needs a newer client: that action answers device_outdated. */
   outdated: boolean
   updateAvailable?: string
-  systems: { system: string; version: string | null; status: SystemStatus; access: SystemAccess; reportedAt: string }[]
+  systems: {
+    system: string
+    version: string | null
+    status: SystemStatus
+    access: SystemAccess
+    reportedAt: string
+    writes: SystemWrites
+  }[]
 }
 
 export type PairBody = { code: string; label?: string }
@@ -130,8 +156,8 @@ export class Deepdock {
       throw new DeepdockTransportError(`non-JSON answer with status ${res.status}`)
     }
     if (body !== null && typeof body === 'object' && 'error' in body) {
-      const { code, message, requestId, systems } = body.error
-      throw new DeepdockError(res.status, code, message, requestId, systems)
+      const { code, message, requestId, systems, version, reason } = body.error
+      throw new DeepdockError(res.status, code, message, requestId, systems, version, reason)
     }
     if (body === null || typeof body !== 'object' || !('data' in body)) {
       throw new DeepdockTransportError(`unexpected body with status ${res.status}`)
@@ -220,6 +246,8 @@ export class Deepdock {
  * Pending writes: one attempt against persisted state. Persist the row BEFORE the first send, so a
  * crash between send and answer cannot produce a second record under a new key. A job retries rows
  * left in `sent` with backoff (seconds, then minutes, for hours if the device stays offline).
+ * For system_version_unverified and device_outdated, poll the device's `writes` / `outdated` before
+ * retrying: they take longer than minutes.
  * ---------------------------------------------------------------------------------------------- */
 
 export type PendingStatus = 'pending' | 'sent' | 'done' | 'unknown' | 'refused'
@@ -244,6 +272,9 @@ export const CONFLICT_RETRIES = 5
 
 const RETRY_SAME_KEY = new Set([
   'device_offline',
+  'device_syncing',
+  'device_outdated',
+  'system_version_unverified',
   'target_busy',
   'temporarily_unavailable',
   'internal_error',

package/skill/references/concepts.md

@@ -25,7 +25,7 @@ The Deepdock client installed on the customer's Windows PC next to their system.
 outwards to Deepdock; nothing in the customer's network is opened to the internet. A device is
 identified by a UUID (`id`), carries a `label`, `hostname`, `os`, `clientVersion`, `status`
 (`connected`, `offline` or `inactive`), `lastSeenAt`, `claimedAt` (may be `null`), `outdated` (an
-assigned action needs a newer client: it answers `device_outdated`) and the `systems` it reported.
+assigned action needs a newer client: it answers `device_outdated`) and the `systems` it reported (each with a `writes` state; reads always work). `verified`: writes run. `unknown`: no version was reported, and writes go through. `partial`: some writes run and some are refused. `unverified`: a write answers `system_version_unverified`; with `reason: unverified_version` it works once Deepdock has verified that version, with `reason: unparseable` retrying does not help and you contact Deepdock.
 
 - **Pair**: claim a device for your organisation with the 6-character code it shows while unpaired.
 - **Release**: `DELETE /v1/devices/{deviceId}` gives the device back; it shows a new code.

package/skill/references/errors.md

@@ -54,6 +54,9 @@ dashboard-only.
 | Code | Status | Meaning | Retry | Show |
 |---|---|---|---|---|
 | `device_offline` | 503 | the device is not connected, is shutting down, or did not answer within 20 s. **A write may still have landed** | yes, with backoff (seconds to minutes); a write only with the same key | "the customer PC is offline; we will retry" |
+| `device_syncing` | 503 | the device has not reported its Deepdock client yet (just paired, or its report did not come through); Deepdock asks it again. Nothing was written | yes, after `Retry-After` (5 s); a write with the same key | "the customer PC is connecting; retrying" |
+| `device_outdated` | 409 | the device's Deepdock client is too old for this call. It updates itself when a newer version is released for your organisation, once nobody is signed in on the PC. Nothing was written | after the update (`outdated` on `GET /v1/devices/{deviceId}` turns `false`); retrying before it gets the same answer. A write keeps its key | "the Deepdock client on the customer PC needs an update" |
+| `system_version_unverified` | 409 | a write on a system whose vendor version Deepdock has not verified yet. Nothing was sent to the device; reads still work. `error.version` is the version the system last reported and `error.reason` is `unverified_version`, or `unparseable` when that version is not dotted digits | `unverified_version`: after Deepdock has verified that version (`writes` on the system in `GET /v1/devices/{deviceId}` turns `verified`); retrying before it gets the same answer. `unparseable`: retrying does not help, contact Deepdock; only a different reported version changes it. A write keeps its key | "the customer's system was updated to a version Deepdock has not yet verified; changes will work once it has" |
 | `action_paused` | 503 | the action is paused on the device (`GET .../systems` shows `reason`); only Deepdock resumes it | later, when `GET .../systems` shows it active; do not loop | "this feature is paused while Deepdock checks the customer system" |
 | `system_unavailable` | 503 | the customer's program is stopped or missing on the device | later; often resolves when the customer restarts the program | "the customer's software is not running" |
 | `target_busy` | 503 | the customer's system is busy or unreachable | yes, with backoff | "the customer's system is busy; retrying" |
@@ -95,6 +98,9 @@ const REACTION: Record<string, Reaction> = {
   access_outdated: 'wait-setup',
   access_missing: 'wait-setup',
   device_offline: 'retry-same-key',
+  device_syncing: 'retry-same-key',
+  device_outdated: 'retry-later',
+  system_version_unverified: 'retry-later',
   action_paused: 'wait-paused',
   system_unavailable: 'retry-later',
   target_busy: 'retry-same-key',

package/skill/references/idempotency.md

@@ -70,7 +70,7 @@ input, a status (`pending`, `sent`, `done`, `unknown`, `refused`) and the result
 
 ```
 pending ──send──▶ sent ──2xx (fresh or replayed)──────────────▶ done
-                   │  ──device_offline, timeout, network error, target_busy, temporarily_unavailable, internal_error ▶ sent  (retry later, same key)
+                   │  ──device_offline, device_syncing, device_outdated, system_version_unverified, timeout, network error, target_busy, temporarily_unavailable, internal_error ▶ sent  (retry later, same key)
                    │  ──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)