@deepdockai/cli 1.0.5 → 1.0.7

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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}`.
+
 ## 1.0.5
 
 - The agent skill's clients: `systems()` is typed as the list of systems the API answers, and a paired `Device` lists its systems as objects, with `outdated` and a `claimedAt` that can be `null`.

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`, `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,8 @@ var EXIT_CODES = {
   record_not_editable: 2,
   payload_too_large: 2,
   device_offline: 3,
+  device_syncing: 3,
+  device_outdated: 3,
   action_paused: 3,
   access_outdated: 3,
   access_missing: 3,
@@ -11424,7 +11426,7 @@ import { spawn } from "node:child_process";
 import { homedir, hostname } from "node:os";
 
 // src/version.ts
-var VERSION = "1.0.5";
+var VERSION = "1.0.7";
 
 // src/runtime.ts
 var DEFAULT_BASE_URL = "https://api.deepdock.ai";
@@ -12149,8 +12151,9 @@ 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, 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.5",
+  "version": "1.0.7",
   "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,7 @@
     "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",
     "test:node": "vitest run",

package/skill/references/auth-and-keys.md

@@ -84,9 +84,10 @@ curl -X POST "$BASE/v1/devices" \
 ```
 
 `label` is optional, 1 to 100 characters. The device must be online. Answer: `201` with the device
-(`id`, `label`, `hostname`, `os`, `clientVersion`, `status`, `lastSeenAt`, `claimedAt`, `systems`,
-and `updateAvailable` when it runs an older build). Keep `id`: it is the `deviceId` of every later
-call, and there is no `/v1` call to list devices (use `deepdock devices list` or the dashboard).
+(`id`, `label`, `hostname`, `os`, `clientVersion`, `status`, `lastSeenAt`, `claimedAt`, `outdated`, `systems`,
+and `updateAvailable` when it runs an older build); `hostname`, `os` and `clientVersion` are `null`
+until the device has reported them. Keep `id`: it is the `deviceId` of every later call.
+`GET /v1/devices` lists your devices and `GET /v1/devices/{deviceId}` reads one, in the same shape.
 
 4. Release with `DELETE /v1/devices/{deviceId}`; the device then shows a new code.
 

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`, `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

@@ -126,8 +126,8 @@ class Deepdock:
 
 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", "target_busy",
+                  "temporarily_unavailable", "internal_error", "action_paused", "system_unavailable"}
 
 
 @dataclass

package/skill/references/clients/deepdock.ts

@@ -46,9 +46,9 @@ export type SystemAccess = 'ok' | 'outdated' | 'missing' | 'not_set_up' | null
 export type Device = {
   id: string
   label: string | null
-  hostname: string
-  os: string
-  clientVersion: string
+  hostname: string | null
+  os: string | null
+  clientVersion: string | null
   status: 'connected' | 'offline' | 'inactive'
   lastSeenAt: string | null
   claimedAt: string | null
@@ -58,6 +58,8 @@ export type Device = {
   systems: { system: string; version: string | null; status: SystemStatus; access: SystemAccess; reportedAt: string }[]
 }
 
+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 }
@@ -199,11 +201,12 @@ export class Deepdock {
 
   /** Claims a device by the pairing code it shows. Keep the returned `id`. */
   async pair(code: string, label?: string): Promise<Device> {
+    const body: PairBody = label === undefined ? { code } : { code, label }
     return (
       await this.send<Device>('/v1/devices', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(label === undefined ? { code } : { code, label }),
+        body: JSON.stringify(body),
       })
     ).data
   }
@@ -241,6 +244,8 @@ export const CONFLICT_RETRIES = 5
 
 const RETRY_SAME_KEY = new Set([
   'device_offline',
+  'device_syncing',
+  'device_outdated',
   'target_busy',
   'temporarily_unavailable',
   'internal_error',

package/skill/references/errors.md

@@ -54,6 +54,8 @@ 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" |
 | `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 +97,8 @@ 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',
   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, 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)