@deepdockai/cli 1.0.7 → 1.0.9

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.0.9
+
+- The CLI knows `device_learning_only` (exit code 2, refused): the PC runs the Deepdock client for learning only, which runs no actions, so action calls and the systems list on it are refused before anything is sent. It changes only when the Deepdock service is installed on that PC; retrying does not help. The skill's error reference lists it.
+
+## 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.

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`, `device_syncing`, `device_outdated`, `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                                                                                                                                  |
+| 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

@@ -10859,6 +10859,7 @@ var EXIT_CODES = {
   invalid_input: 2,
   pairing_code_invalid: 2,
   other_partner_build: 2,
+  device_learning_only: 2,
   rate_limited: 2,
   target_rejected: 2,
   check_failed: 2,
@@ -10874,6 +10875,7 @@ var EXIT_CODES = {
   device_offline: 3,
   device_syncing: 3,
   device_outdated: 3,
+  system_version_unverified: 3,
   action_paused: 3,
   access_outdated: 3,
   access_missing: 3,
@@ -11426,7 +11428,7 @@ import { spawn } from "node:child_process";
 import { homedir, hostname } from "node:os";
 
 // src/version.ts
-var VERSION = "1.0.7";
+var VERSION = "1.0.9";
 
 // src/runtime.ts
 var DEFAULT_BASE_URL = "https://api.deepdock.ai";
@@ -12151,9 +12153,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, device_syncing, device_outdated, action_paused,
-     access_outdated, access_missing, system_unavailable, target_busy,
-     temporarily_unavailable, internal_error, outcome_unknown, 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.7",
+  "version": "1.0.9",
   "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/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`, `device_syncing`, `device_outdated`, `action_paused`, `access_outdated`, `access_missing`, `system_unavailable`, `target_busy`, `temporarily_unavailable`, `internal_error`, `outcome_unknown`, `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", "device_syncing", "device_outdated", "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'
@@ -246,6 +274,7 @@ 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

@@ -35,6 +35,7 @@ dashboard-only.
 | `access_missing` | 409 | the device's database access is gone (a removed database account or a lost secret on the PC); every action of that system is refused. Nothing was run. **No `Retry-After`** | as `access_outdated` | as `access_outdated` |
 | `pairing_code_invalid` | 404 | pairing: the code is unknown, expired, replaced, used, or its device is offline | with a fresh code | "read the code off the device screen again" |
 | `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" |
 
 ## Input
 
@@ -56,6 +57,7 @@ dashboard-only.
 | `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" |
@@ -86,6 +88,7 @@ const REACTION: Record<string, Reaction> = {
   action_not_configured: 'stop',
   pairing_code_invalid: 'fix-input',
   other_partner_build: 'stop',
+  device_learning_only: 'stop',
   invalid_input: 'fix-input',
   target_rejected: 'fix-input',
   unknown_author: 'fix-input',
@@ -99,6 +102,7 @@ const REACTION: Record<string, Reaction> = {
   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, device_syncing, device_outdated, 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)