@sema-agent/sdk 9.7.1 → 9.8.1

package/openapi.yaml

@@ -5127,6 +5127,283 @@ paths:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
         '501': { $ref: '#/components/responses/NotImplemented' }    # capability.adoption_store_required
 
+  # ─────────────────────────────────────────────────────────────────────────────────────────────
+  # device lane admin face (server >= 7.88.0; wire contract §14. O4/S-4 shipped the first three at
+  # 7.55.0, S-470 completed the six at 7.88.0).
+  #
+  # 🔴 PRESENCE IS ANSWERED BY THE ROUTE ITSELF: on a non-device deployment (`REMOTE_EXEC != device`,
+  # or no SQL store) ALL SIX verbs answer 501 `capability.device_lane_required`. Predict it from
+  # `capabilities.deviceExecutor.management` (PRESENT-IFF — absent means a pre-7.88.0 peer, so probe).
+  #
+  # 🔴 ANTI-ENUMERATION: `not_found.device` is ONE answer with FIVE arms (binding absent / binding not
+  # yours / target device absent / not in the binding's domain / revoked), byte-identical. Never branch on
+  # its message and never infer existence from it.
+  #
+  # 🔴 AUTHZ (all six): owner domain = the VERIFIED `(tenant, subject)` composite identity (tenant from the
+  # registry auth-bridge JWT `scope` claim — a signed source, NEVER a self-reported header). No tenant claim
+  # and not an explicit operator ⇒ 403 `auth.forbidden` (loud, never a silent empty view).
+  #
+  # First-bind is NOT here: it is the submit-body top-level key `deviceId` (§14.6, see TaskRequest).
+  # ─────────────────────────────────────────────────────────────────────────────────────────────
+  /v1/devices:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [devices]
+      operationId: devicesList
+      x-status: gated            # server routes/devices.ts;需 device lane(REMOTE_EXEC=device + SQL 店),否则 501 capability.device_lane_required。SDK devices.list() 消费。
+      summary: List the caller's devices (owner-scoped; an explicit operator sees every row).
+      description: >
+        🔴 REVOKED ROWS ARE NOT LISTED. Revocation is terminal (re-enrolling yields a NEW deviceId), so listing
+        them would only invite picking one as a rebind target and then hitting a 404. Therefore "absent from this
+        list" does NOT mean "no such id" — it means "not a usable rebind target".
+
+        Each row's `status` is the SAME presence bit the submit-time admission chain judges: `offline` ⇒ a submit
+        carrying that `deviceId` answers 409 `device.offline`. Presence is decided by THIS replica's hub having a
+        live connection (device lane v1 is a single-replica deployment shape).
+      responses:
+        '200':
+          description: The owner-scoped device list.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/DeviceListResult' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }         # auth.forbidden — the credential carries no tenant claim and the caller is not an explicit operator
+        '501': { $ref: '#/components/responses/NotImplemented' }    # capability.device_lane_required
+
+  /v1/devices/enroll-tokens:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    post:
+      tags: [devices]
+      operationId: devicesIssueEnrollToken
+      x-status: gated            # server routes/devices.ts;同族 501 谓词。SDK devices.issueEnrollToken() 消费。
+      summary: Issue a one-shot enrollment token for the CALLER'S OWN composite identity.
+      description: >
+        The body is a CLOSED SHAPE WITH ZERO ACCEPTED KEYS (any key ⇒ 400 `request.body_shape`, naming the key
+        path). There is no `target` key because the token is always issued for the caller itself: "issue on
+        someone else's behalf" needs a "who may act for whom" authorization face, and v1 does not build one.
+
+        🔴 CONSEQUENTLY AN EXPLICIT OPERATOR IS **NOT** EXEMPT FROM THE DOMAIN DOOR: an operator with no tenant
+        claim answers the same 403 as any domainless credential. Silently issuing to the operator itself would
+        write a composite identity nobody authorized into the devices row's owner.
+
+        🔴 `token` IS PLAINTEXT ONCE — the store keeps only its sha256 digest. Lose it and you re-issue; there is
+        no "recover". Do not log it, do not put it on a durable stream.
+        `ttlSec` = the deployment knob `DEVICE_ENROLL_TOKEN_TTL_SEC` (default 900); `expiresAt` is computed FROM
+        THE DATABASE'S now, not the caller's clock.
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              description: 'Closed shape with ZERO accepted keys — send `{}` or no body at all. Any key ⇒ 400 request.body_shape naming it.'
+      responses:
+        '200':
+          description: The issued token (plaintext ONCE).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/DeviceEnrollToken' }
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape — any key at all (zero-key closed shape); request.invalid_json
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }         # auth.forbidden — no tenant claim (NO operator exemption on this verb)
+        '429': { $ref: '#/components/responses/RateLimited' }       # limit.rate_exceeded + retry-after. 🔴 A rate CHECK THAT THROWS refuses, fail-closed (server `device-enrollment.ts` rateGate: the catch arm answers this code with retryAfterSec, it does not let the request through — that is exactly the moment token stuffing wants)
+        '501': { $ref: '#/components/responses/NotImplemented' }    # capability.device_lane_required
+
+  /v1/devices/enroll:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    post:
+      tags: [devices]
+      operationId: devicesEnroll
+      x-status: gated            # server routes/devices.ts;同族 501 谓词。SDK devices.enroll() 消费。
+      summary: Enroll one device with a one-shot token and the device's own public key.
+      description: >
+        🔴 WHAT IS PRE-AUTH HERE IS THE **DEVICE**, NOT THE CALLER. The device has no deviceId and no key pair in
+        the store yet, so this verb cannot hang a DEVICE credential door on the request — but the CALLER still
+        must carry a verified composite identity (no tenant claim ⇒ 403 `auth.forbidden`). Letting a domainless
+        caller through would replace the "the enrolling request's verified principal must match" defence with
+        "whoever holds the token is that person".
+
+        🔴 `deviceId` AND `owner` ARE NOT INPUTS: the server mints the former (`dev_<ulid>`), and the latter is
+        always the verified composite identity. `pubkey` is generated BY THE DEVICE — the private key never goes
+        on the wire; it is the device's only credential, and it signs the handshake payload built by
+        `@sema-agent/sdk/device`'s `buildHelloSignaturePayload`.
+
+        🔴 THE IDEMPOTENT REPLAY AND A REAL ENROLLMENT ARE WIRE-IDENTICAL (same 200, same `deviceId`): same token
+        + SAME pubkey is the safe retry after a lost response; same token + a DIFFERENT pubkey is 403
+        `device.enrollment_invalid` plus a `device_enroll_token_reuse` audit row. Being able to tell the two 200s
+        apart would open a probe for "has this token been used", so they are deliberately identical — do not try
+        to infer from the response whether you were first.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/DeviceEnrollRequest' }
+      responses:
+        '200':
+          description: 'The minted device id. Carries NO one-shot secret (the device''s credential is its own never-uploaded private key). Byte-identical for an idempotent replay.'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/DeviceEnrollResult' }
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape (unknown key / missing required); request.field_invalid (platformOs outside the v1 closed set `darwin|linux` — a third value is never silently accepted; a field over its byte column — a silently truncated value is a DIFFERENT value)
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403':
+          description: >
+            `auth.forbidden` (the caller carries no tenant claim) OR `device.enrollment_invalid` — the LATTER is
+            this verb's ONLY outward refusal code and it folds FOUR reasons (token absent / expired / bound to a
+            different composite identity / already used by ANOTHER pubkey) into byte-identical bytes, message
+            included. That is anti-enumeration, not vagueness: distinguishable reasons would hand token stuffing a
+            "does this token exist / has it been used" probe. The sub-reasons go only to `device_audit`.
+            Action: ask the issuer for a new token.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '429': { $ref: '#/components/responses/RateLimited' }       # limit.rate_exceeded + retry-after (the SAME limiter as the issue verb, keyed per verb — `issue:<tenant>\0<subject>` / `enroll:<tenant>\0<subject>`; a rate check that throws REFUSES, fail-closed)
+        '501': { $ref: '#/components/responses/NotImplemented' }    # capability.device_lane_required
+
+  /v1/devices/{deviceId}/revoke:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - { name: deviceId, in: path, required: true, schema: { type: string }, description: 'From DeviceSummary.deviceId. Byte-exact key: non-empty, no control characters or surrounding whitespace, at most 64 bytes (otherwise 400 request.id_invalid).' }
+    post:
+      tags: [devices]
+      operationId: devicesRevoke
+      x-status: gated            # server routes/devices.ts;同族 501 谓词。SDK devices.revoke() 消费。
+      summary: Revoke one device (terminal; idempotent).
+      description: >
+        The owner itself, or an explicit operator acting on THE ROW'S domain (an operator never mints a domain of
+        its own into someone else's device row). Row absent / not yours ⇒ 404 `not_found.device`, SAME BYTES —
+        an operator is no exception either: its fleet-wide visibility is provided by `GET /v1/devices`, and this
+        verb does not take on a second existence answer.
+
+        IDEMPOTENT: revoking twice still answers 200, but writes no second audit row.
+
+        🔴 REVOCATION IS TERMINAL and takes effect IMMEDIATELY on three faces:
+        (1) live connection — invalidating the connection lease and bumping the connection generation happen in
+        THE SAME store transaction, so the live socket receives `bye:revoked` and drops, and in-flight
+        instructions settle as outcome-unknown (design window: within 5 s);
+        (2) every later submit on that session = 403 `device.revoked`;
+        (3) re-enrolling yields a NEW `deviceId` — the old row never comes back (replaying an old enrollment token
+        is also 403 `device.revoked`).
+        So do NOT use revoke as a "temporarily take it offline" knob: there is no inverse verb.
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/DeviceRevokeRequest' }
+      responses:
+        '200':
+          description: 'The revocation receipt (same shape on an idempotent second revoke).'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/DeviceRevokeResult' }
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.path_malformed (bad percent-encoding); request.id_invalid (byte-exact key door); request.body_shape (unknown key); request.field_invalid (`reason` over 512 bytes — a truncated audit reason is a DIFFERENT reason)
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }         # auth.forbidden — no tenant claim and not an explicit operator
+        '404': { $ref: '#/components/responses/NotFound' }          # not_found.device — five arms, same code same string (anti-enumeration)
+        '501': { $ref: '#/components/responses/NotImplemented' }    # capability.device_lane_required
+
+  /v1/devices/sessions/{rootSessionId}:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - { name: rootSessionId, in: path, required: true, schema: { type: string }, description: 'The ROOT session id (the binding key; descendants inherit). Byte-exact key: non-empty, no control characters or surrounding whitespace, at most 128 bytes (otherwise 400 request.id_invalid).' }
+    get:
+      tags: [devices]
+      operationId: devicesSessionBinding
+      x-status: gated            # server routes/devices.ts;同族 501 谓词。SDK devices.sessionBinding() 消费。
+      summary: Read one root session's device binding (all the material a shell's rebind UX needs).
+      description: >
+        `boundDevice.rev` is exactly the prior state the rebind verb's `expectedRev` must echo — READ THIS FIRST,
+        then rebind. Unbound / not yours ⇒ 404 `not_found.device`, SAME code SAME string (anti-enumeration: "no
+        visible binding" is one answer; it does not tell you whether the session exists).
+      responses:
+        '200':
+          description: The binding.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/DeviceSessionBinding' }
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.path_malformed / request.id_invalid
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }         # auth.forbidden
+        '404': { $ref: '#/components/responses/NotFound' }          # not_found.device — unbound OR not yours, byte-identical
+        '501': { $ref: '#/components/responses/NotImplemented' }    # capability.device_lane_required
+
+  /v1/devices/sessions/{rootSessionId}/rebind:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - { name: rootSessionId, in: path, required: true, schema: { type: string }, description: 'The ROOT session id whose binding is being moved.' }
+    post:
+      tags: [devices]
+      operationId: devicesSessionRebind
+      x-status: gated            # server routes/devices.ts;同族 501 谓词 + 无活跃 run 门需 run store(501 capability.run_store_required)。SDK devices.rebind() 消费。
+      summary: Explicitly rebind a root session to another device (v1 has no implicit rebind).
+      description: >
+        `expectedRev` IS REQUIRED and must be the rev read from `GET /v1/devices/sessions/{rootSessionId}`: an
+        explicit prior state, so two concurrent operators cannot silently stomp each other. Door order (frozen,
+        five steps server-side):
+        (1) owner door — a non-owner gets 404, SAME bytes;
+        (2) target-device door — `toDeviceId` must exist, belong to THE BINDING'S domain (an operator may not
+        rebind across tenants) and not be revoked; otherwise 404, SAME bytes;
+        (3) NO-ACTIVE-RUN door, judged BEFORE the CAS, with the durable criterion = the run store's session claim
+        (parked runs included) ⇒ 409 `device.rebind_active_run` carrying `activeTaskId`; no run store wired ⇒ 501
+        `capability.run_store_required` (a door with no criterion refuses);
+        (4) prior-state CAS in one store transaction plus a `session_rebound` audit row ⇒ rev mismatch is 409
+        `device.rebind_rev_conflict` carrying `currentRev`. 🔴 The SAME `toDeviceId` with a WRONG rev is still a
+        409 — a wrong prior state is wrong;
+        (5) winner ⇒ 200.
+
+        🔴 THE REFUSAL BODIES ARE FLAT, NOT NESTED: `activeTaskId` / `currentRev` are TOP-LEVEL keys alongside
+        `error` / `errorCode` (`sendError(res, status, code, message, extra)` spreads `extra` at the top level).
+        Read `body.activeTaskId` / `body.currentRev` directly — do not look for a `details` wrapper.
+
+        IDEMPOTENT FORM: `toDeviceId` == the current binding AND `expectedRev` == the current rev ⇒ 200 that
+        echoes back WITHOUT incrementing `rev` and writes no audit row.
+
+        ⚠️ WRITTEN-DOWN RESIDUAL (a design ruling, not an oversight): step 3 and step 4 are two operations on two
+        stores, so a check→act window exists — a run that wins the session claim concurrently with the rebind is
+        not stopped by this door. The window's failure direction is safe: that run's execution env is minted
+        either against the NEW binding (identical to submitting one moment after the rebind) or against the old
+        one — and then EVERY instruction it issues is refused `device.identity_mismatch` by the dispatch door's
+        identity re-assertion (the hub's `expectedDeviceId` fence), loudly, with zero instructions landing. So do
+        not run a rebind and a submit concurrently; rebind first, then submit (or re-read the binding after).
+
+        ⚠️ IN-FLIGHT INSTRUCTIONS ARE NOT MIGRATED: park redemption and late instructions are validated against
+        the binding AS OF INSTRUCTION MINT TIME and are always refused `device.identity_mismatch` (403) — never
+        silently re-routed to the new device, which does not have that workspace.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/DeviceRebindRequest' }
+      responses:
+        '200':
+          description: >
+            The rebind receipt — SAME key set for a real rebind and for the idempotent form.
+            🔴 `workspaceCarryover` is the FROZEN LITERAL `"none"` on both: rebinding changes routing only, it
+            does NOT move workspace bytes, and the shell MUST disclose "the new device starts from a fresh
+            workspace" on the strength of this field.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/DeviceRebindResult' }
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.path_malformed / request.id_invalid / request.body_shape (body is not `{toDeviceId, expectedRev}`) / request.field_invalid (expectedRev not a non-negative integer; toDeviceId fails the byte-exact key door)
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }         # auth.forbidden
+        '404': { $ref: '#/components/responses/NotFound' }          # not_found.device — five arms, same code same string
+        '409':
+          description: >
+            TWO errorCodes ride this status and the next action differs, so branch on `errorCode`:
+            `device.rebind_active_run` (a non-terminal run holds this session; body carries the TOP-LEVEL
+            `activeTaskId` — cancel it or wait for its terminal state, then retry) and
+            `device.rebind_rev_conflict` (the prior-state CAS lost; body carries the TOP-LEVEL `currentRev` — one
+            hop to relocate: re-read the binding, or resend with `currentRev`).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }    # capability.device_lane_required, or capability.run_store_required (the no-active-run door needs a durable, cross-replica criterion)
+
   /metrics/summary:
     get:
       tags: [metrics]
@@ -5877,6 +6154,38 @@ components:
             submit leg today — it belongs to callers that build a `TaskSpec` directly.
           additionalProperties: true
         cwd: { type: string, description: Working directory for the execution env. }
+        deviceId:
+          type: string
+          description: >
+            server >= 7.88.0 (S-470, wire contract §14.6) — DEVICE-LANE FIRST-BIND. "Run this on THAT machine of
+            mine", same level and same trust posture as `cwd`: caller-supplied, server-gated. It is NOT an
+            identity (identity always comes from the verified composite-identity chain), just a selector.
+
+            ROOT TASK ONLY: the binding key is the ROOT SESSION and descendants inherit unconditionally; the
+            RESUME family (`/decide` `/answer` `/plan_review` `/wake`) does NOT accept this key — the lane is
+            fixed per tree.
+
+            🔴 A NON-DEVICE LANE ANSWERS 400 `request.precondition_unmet` (the message names `REMOTE_EXEC=device`).
+            Deliberately NOT silently ignored: otherwise the caller believes it picked an execution device while
+            that declaration never existed. Probe `capabilities.deviceExecutor` — `false` ⇒ do not send.
+
+            FIRST BIND = INSERT-if-absent CAS ⇒ exactly one concurrent winner. A loser asking for the SAME device
+            is an idempotent success; a loser asking for a DIFFERENT device gets 409 `device.claim_conflict`.
+            LATER ROOT SUBMITS: absent = keep the binding / same = idempotent (binding `rev` unchanged) /
+            different = 403 `device.identity_mismatch`. There is NO implicit rebind in v1 — changing device is the
+            explicit `POST /v1/devices/sessions/{rootSessionId}/rebind` action.
+
+            ADMISSION CHAIN (three steps, all fail-closed): resolve the binding (else 409 `device.not_bound`) →
+            the devices row is `active` (missing / not yours = 404 `not_found.device`, same bytes; revoked = 403
+            `device.revoked`) → presence is online (else 409 `device.offline`). ANY lookup failure = REFUSE.
+
+            🔴 Every refusal above EXCEPT `device.claim_conflict` / `device.identity_mismatch` is answered BEFORE
+            the server creates anything ⇒ no run row, no session claim, no durable trace. Observable on
+            `POST /v1/runs`: after a caller-minted `taskId` hits `device.offline`, retrying with the SAME `taskId`
+            once the device is online yields a REAL acceptance, not a replay of a failed receipt.
+            ⚠️ The flip side, stated honestly: that caller-minted-`taskId` idempotent replay ALSO passes the
+            admission chain, so during a brief executor outage the same `taskId` gets `409 device.offline` instead
+            of the `202` receipt (the original run is unaffected — it takes the reconnect grace path).
         selfOrchestration: { type: boolean, description: Permit S8 self-orchestration (run_workflow) inside this task. }
         enableFork: { type: boolean, description: Permit session forking from inside this task. }
         # 原注是「形状归 SDK 的 TaskAgentDefinition 所有,这里刻意保持 OPEN 而不重复一遍」。2026-07-25 推翻该选择,
@@ -7390,6 +7699,14 @@ components:
             handler's mount condition. `wsPath` is deliberately on the wire (hard-coding it downstream
             would turn a path change into a cross-repo breaking change). Device COUNT / online state are
             deliberately NOT advertised (that is the `/v1/devices/*` admin face).
+
+            🔴 `management` (server >= 7.88.0) answers a DIFFERENT question from the other three: those are the
+            DEVICE-side join face (can an executor connect), this one is the SHELL-side admin face (are the six
+            `/v1/devices/*` verbs mounted). Its predicate is byte-identical to that family's 501
+            `capability.device_lane_required` criterion (store + hub + admission chain, all three wired by
+            `boot/device-lane.ts`). PRESENT-IFF: the key's ABSENCE means the peer is a pre-7.88.0 server that
+            cannot answer — probe by 501. Do NOT read absence as `false` (the dispositions differ: `false` = this
+            server says the face is not here, so hide the entry; absent = unknown, one attempt is legitimate).
           oneOf:
             - type: boolean
               enum: [false]
@@ -7401,6 +7718,7 @@ components:
                 protocolVersion: { type: integer }
                 maxInflightPerDevice: { type: integer }
                 wsPath: { type: string }
+                management: { type: boolean, description: 'server >= 7.88.0. `/v1/devices/*` admin verbs present. PRESENT-IFF — absent means a pre-7.88.0 peer (unknown), not false.' }
         memoryEngine:
           description: >
             Memory ENGINE posture (capabilities.ts:210 = `projectMemoryEngineCapability`). Object = the
@@ -16271,3 +16589,161 @@ components:
           allOf: [{ $ref: '#/components/schemas/AdoptionReport' }]
           description: 'Frozen ONLY when `status` is `adopted`; on `stalled` it is a provisional projection of the current row — do not persist it as audit evidence.'
         current: { $ref: '#/components/schemas/AdoptionCurrent' }
+
+    # ── device lane admin face (server >= 7.88.0; wire contract §14) ─────────────────────────────
+    # Shapes taken verbatim from the server's `sendJson` mint points in `src/http/routes/devices.ts`
+    # (read off the published bytes, not off a changelog). Consumed by `client.devices.*`.
+    # 🔴 The EXECUTOR-side protocol face (closed-set vocabularies, both directions' frames, the handshake
+    # signature bytes) is NOT here and NOT on this wire — it is the package subpath `@sema-agent/sdk/device`,
+    # mirroring `@sema-agent/server/device-protocol`.
+    DeviceSummary:
+      type: object
+      description: 'One row of the device list (server `deviceListRow`; frozen key set).'
+      additionalProperties: false
+      required: [deviceId, status]
+      properties:
+        deviceId: { type: string, minLength: 1 }
+        name: { type: string, description: 'The device displayName. HONESTLY ABSENT when empty (server: `displayName !== "" ? {name} : {}`) — absence reads as "this device has no name", not "it could not be read".' }
+        status:
+          type: string
+          enum: [online, offline]
+          description: >
+            Presence, decided by THIS replica's hub having a live connection (device lane v1 = a single-replica
+            deployment shape). This is the SAME bit the submit-time admission chain judges: `offline` ⇒ a submit
+            carrying that `deviceId` answers 409 `device.offline`.
+        lastSeenAt: { type: string, format: date-time, description: 'ISO-8601. ABSENT if the device has never connected (not `null`, not epoch 0).' }
+
+    DeviceListResult:
+      type: object
+      description: >
+        The `GET /v1/devices` 200 body. Owner-domain filtered; an explicit operator sees every row.
+        🔴 REVOKED ROWS ARE NOT LISTED (revocation is terminal; re-enrolling yields a new deviceId), so "absent
+        from this list" means "not a usable rebind target", NOT "no such id".
+      additionalProperties: false
+      required: [devices]
+      properties:
+        devices:
+          type: array
+          items: { $ref: '#/components/schemas/DeviceSummary' }
+
+    DeviceBinding:
+      type: object
+      description: 'One session↔device binding (server `boundDeviceOf`; frozen key set).'
+      additionalProperties: false
+      required: [deviceId, rev, boundAt]
+      properties:
+        deviceId: { type: string, minLength: 1 }
+        rev: { type: integer, minimum: 0, description: 'The prior-state version — this is exactly what the rebind verb''s `expectedRev` must echo (an explicit prior state, so two concurrent operators cannot silently stomp each other).' }
+        boundAt: { type: string, format: date-time, description: 'ISO-8601.' }
+
+    DeviceSessionBinding:
+      type: object
+      description: 'The `GET /v1/devices/sessions/{rootSessionId}` 200 body (all the material a shell''s rebind UX needs).'
+      additionalProperties: false
+      required: [rootSessionId, boundDevice]
+      properties:
+        rootSessionId: { type: string, minLength: 1 }
+        boundDevice: { $ref: '#/components/schemas/DeviceBinding' }
+
+    DeviceRebindRequest:
+      type: object
+      description: 'The `POST /v1/devices/sessions/{rootSessionId}/rebind` body. NOTE: server 7.88.2 does NOT key-close this one body (unknown keys are dropped silently, unlike enroll/revoke which answer 400 request.body_shape); a server-side ticket tracks closing it. This SDK never sends extra keys.'
+      additionalProperties: false
+      required: [toDeviceId, expectedRev]
+      properties:
+        toDeviceId: { type: string, minLength: 1, description: 'Must exist, belong to THE BINDING''S domain (an operator may not rebind across tenants) and not be revoked — otherwise 404 not_found.device, same bytes.' }
+        expectedRev:
+          type: integer
+          minimum: 0
+          description: >
+            REQUIRED — the rev read from `GET /v1/devices/sessions/{rootSessionId}`. 🔴 The same `toDeviceId` with a
+            WRONG rev is STILL a 409 `device.rebind_rev_conflict`: a wrong prior state is wrong. Not a non-negative
+            integer ⇒ 400 request.field_invalid.
+
+    DeviceRebindResult:
+      type: object
+      description: >
+        The rebind 200 body — the SAME key set for a real rebind and for the idempotent form (`toDeviceId` == the
+        current binding AND `expectedRev` == the current rev ⇒ 200 that echoes back WITHOUT incrementing `rev` and
+        writes no audit row).
+      additionalProperties: false
+      required: [rootSessionId, deviceId, rev, workspaceCarryover]
+      properties:
+        rootSessionId: { type: string, minLength: 1 }
+        deviceId: { type: string, minLength: 1 }
+        rev: { type: integer, minimum: 0 }
+        workspaceCarryover:
+          type: string
+          enum: [none]
+          description: >
+            🔴 A FROZEN LITERAL, present on BOTH 200 shapes: rebinding changes routing only, it does NOT move
+            workspace bytes. The shell MUST disclose "the new device starts from a fresh workspace" on the strength
+            of this field. There is no second value today; the single-member enum is because this is a DECLARATION,
+            not a knob.
+
+    DeviceEnrollToken:
+      type: object
+      description: 'The `POST /v1/devices/enroll-tokens` 200 body.'
+      additionalProperties: false
+      required: [token, expiresAt, ttlSec]
+      properties:
+        token: { type: string, minLength: 1, description: '🔴 PLAINTEXT ONCE — the store keeps only its sha256 digest. Lose it and you re-issue; there is no "recover". Do not log it, do not put it on a durable stream.' }
+        expiresAt: { type: string, format: date-time, description: 'ISO-8601, computed FROM THE DATABASE''S now (not the caller''s clock).' }
+        ttlSec: { type: integer, minimum: 1, description: 'The deployment knob `DEVICE_ENROLL_TOKEN_TTL_SEC` (default 900).' }
+
+    DeviceEnrollRequest:
+      type: object
+      description: >
+        The `POST /v1/devices/enroll` body — a CLOSED SHAPE (any key outside this set ⇒ 400 `request.body_shape`
+        naming the key path).
+        🔴 `deviceId` and `owner` ARE NOT INPUTS: the server mints the former (`dev_<ulid>`) and the latter is
+        always the VERIFIED composite identity.
+      additionalProperties: false
+      required: [token, pubkey, platformOs, workspaceRoot]
+      properties:
+        token: { type: string, minLength: 1, maxLength: 256, description: 'The one-shot plaintext token from the issue verb. Empty or over 256 chars ⇒ 400 request.field_invalid (it only feeds a sha256, but an unbounded string turns digesting into an amplification face).' }
+        pubkey: { type: string, minLength: 1, description: 'The Ed25519 PUBLIC key the DEVICE generated. The private key NEVER goes on the wire — it is the device''s only credential, and it signs the payload built by `@sema-agent/sdk/device`''s buildHelloSignaturePayload.' }
+        platformOs:
+          type: string
+          enum: [darwin, linux]
+          description: 'The v1 CLOSED SET. A third value (e.g. `win32`) ⇒ 400 request.field_invalid — never silently accepted.'
+        platformArch: { type: string, maxLength: 32, description: 'At most 32 **UTF-8 bytes** (producer gates byte length; `maxLength` is the looser character bound, see the unit convention).' }
+        displayName: { type: string, maxLength: 255, description: 'Echoed back by `GET /v1/devices` as `name`, and HONESTLY ABSENT there when empty. At most 255 **UTF-8 bytes** (producer gates byte length; `maxLength` is the looser character bound).' }
+        workspaceRoot: { type: string, minLength: 1, maxLength: 1024, description: 'The device-side root every instruction resolves against. Required and non-empty. At most 1024 **UTF-8 bytes** (producer gates byte length; `maxLength` is the looser character bound) ⇒ over it 400 request.field_invalid (a silently truncated value is a DIFFERENT value).' }
+
+    DeviceEnrollResult:
+      type: object
+      description: >
+        The `POST /v1/devices/enroll` 200 body. It carries NO one-shot secret — the device's credential is the
+        private key it generated and never uploaded.
+        🔴 THE IDEMPOTENT REPLAY IS WIRE-IDENTICAL to a real enrollment (same 200, same `deviceId`): same token +
+        SAME pubkey is the safe retry after a lost response; same token + a DIFFERENT pubkey is 403
+        `device.enrollment_invalid`. Telling the two 200s apart would open a "has this token been used" probe, so
+        they are deliberately identical — do not infer from the response whether you were first.
+      additionalProperties: false
+      required: [deviceId]
+      properties:
+        deviceId: { type: string, minLength: 1, description: 'Server-minted, `dev_<ulid>`.' }
+
+    DeviceRevokeRequest:
+      type: object
+      description: 'The `POST /v1/devices/{deviceId}/revoke` body (closed shape; the only accepted key is `reason`). Absent body is folded to `{}` server-side.'
+      additionalProperties: false
+      properties:
+        reason: { type: string, maxLength: 512, description: 'At most 512 **UTF-8 bytes** (the producer gates `Buffer.byteLength(reason, "utf8")`, NOT `.length` — this is the one family where the file''s unit convention''s explicit-UTF-8 carve-out applies); `maxLength: 512` is the deliberately LOOSER character bound (a multi-byte value can pass this schema and still get 400 request.field_invalid naming the field — loud, never a client-side false refusal). A silently truncated audit reason is a DIFFERENT reason.' }
+
+    DeviceRevokeResult:
+      type: object
+      description: >
+        The revoke 200 body. IDEMPOTENT: revoking twice still answers 200, but writes no second audit row.
+        🔴 Revocation is TERMINAL and immediate on three faces: the live socket gets `bye:revoked` and drops (lease
+        invalidation + connection-generation bump are in the SAME store transaction; in-flight instructions settle
+        as outcome-unknown, design window 5 s); every later submit on that session is 403 `device.revoked`; and
+        re-enrolling yields a NEW deviceId — the old row never comes back. There is NO inverse verb, so do not use
+        revoke as "temporarily take it offline".
+      additionalProperties: false
+      required: [deviceId, status]
+      properties:
+        deviceId: { type: string, minLength: 1 }
+        status: { type: string, enum: [revoked], description: 'Single member: revocation is a terminal state, there is no other answer.' }
+        revokedAt: { type: string, format: date-time, description: 'ISO-8601; HONESTLY ABSENT when the store has no timestamp (server: `revokedAtMs !== null ? {revokedAt} : {}`).' }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "9.7.1",
+  "version": "9.8.1",
   "description": "Typed, zero-runtime-dependency SDK for the Sema agent fleet usage plane. The shared substrate for all doors (CC/Codex MCP façade + web). Server-side only — tokens never enter the browser.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -28,6 +28,10 @@
       "types": "./dist/registry/index.d.ts",
       "import": "./dist/registry/index.js"
     },
+    "./device": {
+      "types": "./dist/device/index.d.ts",
+      "import": "./dist/device/index.js"
+    },
     "./registry-openapi.yaml": "./registry-openapi.yaml"
   },
   "files": [