@sema-agent/sdk 17.2.0 → 18.0.0

package/openapi.yaml

@@ -184,6 +184,10 @@ tags:
     description: v2 leader pipeline (gated; E2B + git push). NOT the default door-B brain.
   - name: metrics
     description: Worker health/cost (ops; uses metricsToken, not a principal).
+  - name: admin
+    description: >
+      Operator-only `/v1/admin/*` actions on THIS engine instance. Today: the drain endpoint (server >= 7.121.0 contract
+      body `DrainRequest` / receipt `DrainReceipt`, owned by `@sema-agent/settings-schema` `./fleet`).
 
 paths:
 
@@ -5595,6 +5599,65 @@ paths:
         '403': { description: 'Multi-tenant worker: wiring diagnostics are operator-only (`auth.operator_only`). With an EMPTY `OPERATOR_PRINCIPALS` the answer is instead 501 `capability.operator_principals_required` (server >= 7.116.0; any identity, ahead of authorization — branch on `errorCode`, not the status).' }
         '404': { description: 'This worker serves no wiring diagnostics (older server, or a process not assembled by the composition root).' }
 
+  /v1/admin/drain:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    post:
+      tags: [admin]
+      operationId: adminDrain
+      x-status: live             # server >= 7.121.0 contract body; 7.35.0–7.120.x took a retired `{reason}` body.
+      summary: Put THIS engine instance into draining by a deadline (operator-only).
+      description: >
+        Server >= 7.121.0. The body is the contract `DrainRequest` (owned by `@sema-agent/settings-schema` >= 9.0.0 `./fleet`), the answer
+        the contract `DrainReceipt`. Entering drain: new work is refused (billable submits 503 `draining`; HITL answers — including the
+        durable `/decide` — and resumes are ADMITTED), `GET /readyz` turns 503, preemptible in-flight legs park durably at their next clean
+        turn boundary, live approval cards are re-routed to durable parks; the engine stops itself when in-flight reaches zero or at
+        `deadlineAt` (fixed when entered — a later hot change to the drain window does not move it). After a drain entered through this
+        endpoint, the FIRST stop signal the platform sends is absorbed (deadline unchanged) and only a later one, at least the minimum gap
+        apart, hard-stops — so the platform stop timeout (Docker `stop_grace_period`, systemd `TimeoutStopSec`, k8s
+        `terminationGracePeriodSeconds`) must be >= the requested deadline.
+        IDENTITY — the request names WHICH instance, compared field by field (no state change on a mismatch, 409 `conflict.fleet_identity`
+        naming the field, never echoing the value): `worker` = the engine's worker name (`SEMA_REGISTRY_WORKER`; an engine without a center
+        lane has none, so every request mismatches); `expectedGeneration` = the fleet generation (`/health.generation`), ABSENT AGAINST ABSENT
+        (omitting it is the standalone form, not a wildcard — it mismatches a fleet member); `scope` = the tenant scope, both sides read as a
+        value (the engine's = env `FLEET_SCOPE`; unset on the engine and omitted in the request both read as the default scope `global`);
+        `instanceId` (`/health.instanceId`) is compared only when present.
+        IDEMPOTENT — the same `actionId` (or any other action) while already draining answers 200 `already_draining` and echoes the FIRST
+        drain's `since` / `deadlineAt`, changing nothing. Clients do not auto-retry this POST; re-send with the same `actionId` to retry.
+        RETIRED (zero alias): the 7.35.0–7.120.x `{reason}` "shutdown reason declaration" body (it only recorded a sentence and never
+        drained) now answers 400 `request.field_invalid`; `/health.drainReason` and the `reason` key on 503 `draining` bodies are gone too.
+        Gate order (same as every operator face): identity -> authorization -> body shape -> drain entry -> four-part identity.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/DrainRequest' }
+      responses:
+        '200':
+          description: Draining (this call entered it) or already draining (the first drain's facts, unchanged).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/DrainReceipt' }
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.field_invalid — the body is not a DrainRequest (including the retired `{reason}` form); nothing was changed
+        '401': { $ref: '#/components/responses/Unauthorized' }      # auth.unauthorized (credential gate) / auth.principal_required (REQUIRE_PRINCIPAL deployment, no usable identity)
+        '403': { description: '`auth.operator_only` — OPERATOR_PRINCIPALS is non-empty and the caller is not in it.' }
+        '409':
+          description: >-
+            `conflict.fleet_identity` (server >= 7.121.0) — the request's four-part identity (`scope` / `worker` / `expectedGeneration` /
+            `instanceId`) does not match this engine; the sentence names the mismatched fields (never the values). Nothing was changed.
+            Compare with the target engine's `GET /health` (`instanceId` / `generation`), its worker name and `FLEET_SCOPE`, then re-send.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501':
+          description: >-
+            `capability.operator_principals_required` — OPERATOR_PRINCIPALS is empty, so no identity is an operator on this deployment (any
+            deployment shape, ahead of authorization). `capability.drain_state_required` — the host has no shutdown chain wired (an embedded
+            engine), so there is no drain to enter (answered after the body check). Branch on `errorCode`.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+
   /v1/sendfile-links:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
@@ -5804,7 +5867,7 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/CcImportPrepareResult' }
-        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape — not {layers:[{layer,path,root,content}]}, or a layer `root` the server does not accept (server >= 7.120.0: not a complete absolute path — see RuleScope; sentence "scope must be 'global' or 'project:<root>' with an absolute root", no ticket minted; <= 7.119.x: an empty `root`, answered with the body-shape sentence)
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape — not {layers:[{layer,path,root,content}]}, or a layer `root` the server does not accept (server >= 7.120.0: not a complete absolute path — see RuleScope; sentence "layers[<i>].root must be an absolute path" on >= 7.121.0, the scope sentence on 7.120.x; no ticket minted; <= 7.119.x: an empty `root`, answered with the body-shape sentence)
         '401': { $ref: '#/components/responses/Unauthorized' }
         '413': { $ref: '#/components/responses/PayloadTooLarge' }   # request.payload_too_large — more than 200 candidates across all submitted layers; SHORTEN and resend (retrying the same payload cannot help)
         '429': { $ref: '#/components/responses/RateLimited' }
@@ -6589,7 +6652,12 @@ components:
         ⚠️ On the billable submit set (every POST that starts a model turn — the server's
         `isBillableSubmitPath`, which is wider than the three task/run endpoints) this
         503 slot is SHARED with producers that are not auth at all, so `errorCode` — not the status — is the
-        branch key: `draining` (this replica is shutting down; retry against a replacement -> DrainingError),
+        branch key: `draining` (this replica is shutting down; retry against a replacement -> DrainingError; server >= 7.121.0
+        refuses only NEW work while draining — HITL answers, including the durable `/decide`, and resumes are admitted — and the body
+        carries no `reason` key any more),
+        `state.lease_expired` (server >= 7.121.0: this fleet member's serving lease has expired and the center has been unreachable
+        for the deployment's `FLEET_LEASE_OUTAGE_MAX_MS`; new work only — HITL answers and resumes pass, in-flight runs are untouched;
+        it lifts when the center grants again; retry later or route elsewhere -> ServiceStateError),
         `state.model_roster_pending` (roster not loaded yet; retry -> ServiceStateError), and (server >=7.0.0,
         synchronous `POST /v1/tasks` only) `memory.admission_required` — the org-memory admission directory is
         transiently undecidable, refused fail-closed BEFORE any model call, mapped to MemoryAdmissionError.
@@ -6612,7 +6680,7 @@ components:
           schema: { type: integer }
           description: >
             Seconds to wait before retrying. Presence is per producer, not per status:
-            `draining` always sends it (15), `state.model_roster_pending` always sends it (5),
+            `draining` always sends it (15), `state.model_roster_pending` always sends it (5), `state.lease_expired` always sends it (60),
             `memory.admission_required` sends it ONLY when the engine supplied a hint — a steady-state refusal
             (no resolver wired) honestly carries neither this header nor the body's `retryAfterSec`.
             The auth legs (401 bad token / 503 missing token) never send it.
@@ -7250,6 +7318,22 @@ components:
             Pin a SEPARATE (usually cheaper) model for compaction. Validated against the catalog on submit — an
             unknown ref is a 400, not a silent fallback to the main model's price.
         appendSystemPrompt: { type: string, description: Text appended to the assembled system prompt for this task. }
+        outputStyle:
+          type: object
+          required: [name]
+          additionalProperties: false
+          description: >-
+            Server >= 7.121.0 (send only when `capabilities.outputStyle` is true; an older server answers 400 `request.body_shape` for the
+            top-level key): the output style's PER-TURN line, handed verbatim to the engine's seat of the same name. Each attachment cycle the
+            engine states "<name> output style is active. <turnReminder>" in its own marker frame (the engine's default sentence when
+            `turnReminder` is absent), echoed on the stream as `steering_injected` with `source: "output_style"`. One fact, one seat: the
+            style's BODY (the guide text) still goes in `settings.outputStyle`; this key carries only the name and the per-turn line.
+            The value's owner is the engine (exactly these two keys, `name` non-empty and at most 256 characters, `turnReminder` a non-empty
+            string when present); the server does not judge it — a bad value is accepted and refused at prepare, the run ends `failed` with
+            code `config.output_style_invalid` (never silently ignored).
+          properties:
+            name: { type: string, minLength: 1, maxLength: 256 }
+            turnReminder: { type: string, minLength: 1 }
         promptProfile:
           type: string
           enum: [simple, classic]
@@ -9221,6 +9305,8 @@ components:
                 bgNotifyFailClosed: { type: boolean }
                 steerPriority: { type: string }
                 hookFailureNotice: { type: boolean, description: 'server >= 7.48.0 (#281): this binary emits a SECOND `hook_notice` kind, `hook_non_blocking_failure` (the user''s own hook broke: exit != 0 and != 2 / timeout / spawn failure / bad JSON). Absent = an older worker that only emits `hook_decision_unavailable` — branch by `kind`, never crash on an unknown one.' }
+                leaseClient: { type: boolean, description: 'server >= 7.121.0, a version bit (always true, rides with the `fleet` object): this binary carries the serving-lease CLIENT — when the engine is a fleet member (`FLEET_GENERATION`) and the center declares in its heartbeat reply that it answers renewals (`servingLease`), the engine renews and is governed by the lease. Deliberately NOT named `servingLease` (that is the center''s bit): this says the client exists, not that a lease is in force — read `/health.leaseState` for that. Absent = an older worker.' }
+                generationEcho: { type: boolean, description: 'server >= 7.121.0, a version bit (always true, rides with the `fleet` object): this binary echoes env `FLEET_GENERATION` as `generation` on the heartbeat and on `/health` (with `leaseState` / `leaseUntil`), and the drain endpoint `POST /v1/admin/drain` compares the four-part identity including `expectedGeneration`. Absent = an older worker.' }
         workspace:
           description: >
             #3 (server 1.299–7.51): workspace-browse capability family — an OBJECT when the E19 snapshot-store
@@ -9257,6 +9343,13 @@ components:
         effortSelection: { type: boolean, description: "`reasoningEffort` accepted per request." }
         compactionModel: { type: boolean, description: "A separate model may be pinned for compaction." }
         appendSystemPrompt: { type: boolean, description: "Per-request system-prompt append is honoured." }
+        outputStyle:
+          type: boolean
+          description: >-
+            server >= 7.121.0, hardcoded true (a predicate-class bit, same family as `approvalDecidedBy` / `sessionReadRedaction`): the
+            top-level request key TaskRequest.outputStyle (the output style's per-turn line) is accepted and handed verbatim to the engine.
+            Send the key only when this is present; absent = an older server, which answers 400 for it. Not the same thing as
+            `taskSettings.outputStyle` (that bit says `settings.outputStyle`, the style BODY, is accepted) — two seats, two facts.
         toolOutput: { type: boolean, description: "`tool_end` carries the model-facing output." }
         messageIdentity: { type: boolean, description: "Content events carry `eventId` (+ `parentToolCallId` for sub-agents)." }
         forwardSubagentEvents: { type: boolean, description: "Sub-agent events are forwarded onto the parent stream." }
@@ -15509,6 +15602,17 @@ components:
         was armed but declined/failed (check the store, check authorisation), `false` = there was no lane at all
         (wire one up). The two recovery verbs differ, so a consumer MUST render them apart — NEVER fold them into
         one "nobody approved it".
+        `server.model_unreachable` (server-minted, audience `user`; server >= 7.108.0, `taskId` added in server 7.121.0) — a model call on
+        this leg ended in error and its last request failed AT CONNECT (VPN switched mid-session / the proxy read at boot went stale / the
+        gateway is gone) — not the provider's answer. `{ code, targetHost, proxyInUse?, remedy, sessionId, taskId? }`: `code` one of the
+        connect-failure set (`ECONNREFUSED` / `ENOTFOUND` / `EAI_AGAIN` / `EHOSTUNREACH` / `ENETUNREACH` / `UND_ERR_CONNECT_TIMEOUT`),
+        `targetHost` the model endpoint's `host:port` (a proxy address never rides this frame), `proxyInUse` present only when this hop
+        went through a proxy and only as the variable NAME (`HTTP_PROXY` / `HTTPS_PROXY`), `remedy` a fixed sentence. `taskId`
+        (server >= 7.121.0) = this leg's run resource id (streaming leg: `X-Task-Id` / the `meta` frame's `taskId`; background leg: the
+        submit receipt's `taskId`; resume leg: the resumed run's id) — the same value as that run's terminal and its run-domain codes'
+        `detail.taskId`; absent when the leg has no run resource (a streaming leg on a deployment without a run store) or on an older
+        server. NO `runId` (the model-call layer cannot see the engine's run identity): a resume leg and its original leg share the
+        `taskId`. Once per leg per target; it says "this endpoint is unreachable", not "this run failed".
         `session.records_skipped` (K-24; server >= 7.104.0 / S-612 form B; contract §17.4 / appendix D.3) — 🔴 SERVER-MINTED
         (not in core's register; owner, audience `user` and mint all live in the server). The session's saved log was
         OPENED and some records could not be read and were skipped (file session backend only — both SQL backends refuse a
@@ -19593,6 +19697,33 @@ components:
         The three user-editable CC settings layers this version reads (core `ImportedSettingsLayer`). The two
         layers it does NOT read are named in `CcImportPreview.uncovered` rather than being silently absent.
 
+    DrainRequest:
+      type: object
+      required: [actionId, worker, deadlineAt]
+      description: >-
+        The drain endpoint's request (contract `DrainRequest`, `@sema-agent/settings-schema` >= 9.0.0 `./fleet`): "put this instance into
+        draining by this deadline". See `POST /v1/admin/drain` for how the identity fields are compared.
+      properties:
+        actionId: { type: string, minLength: 1, description: 'Idempotency key: the same id again answers `already_draining` and changes nothing. Hand-issued actions pick their own (e.g. `manual:<uuid>`).' }
+        worker: { type: string, minLength: 1, description: The engine's worker name (`SEMA_REGISTRY_WORKER`). }
+        deadlineAt: { type: integer, minimum: 0, description: Epoch milliseconds by which the engine stops on its own. }
+        scope: { type: string, minLength: 1, description: 'The tenant scope; omitted = the default scope `global` (compared against env `FLEET_SCOPE`, unset = `global`).' }
+        expectedGeneration: { type: string, pattern: '^(0|[1-9][0-9]*)$', description: 'The fleet generation as a canonical decimal string (`/health.generation`); absent against absent — omit it only for a non-member.' }
+        instanceId: { type: string, minLength: 1, description: The engine's per-process identity (`/health.instanceId`); compared only when present. }
+        term: { type: string, minLength: 1, description: The claim term the sending executor holds for this action (center-issued, opaque); absent on a direct or hand-issued call. }
+    DrainReceipt:
+      type: object
+      required: [actionId, since, deadlineAt, state]
+      additionalProperties: false
+      description: >-
+        The drain endpoint's answer (contract `DrainReceipt`): the engine's drain fact plus how this call found it. `state: draining` = this
+        call entered drain; `already_draining` = it already was (including a drain the engine entered on its own), and the receipt reports the
+        FIRST drain's facts.
+      properties:
+        actionId: { type: string, minLength: 1, description: The action that entered this drain. }
+        since: { type: integer, minimum: 0, description: 'Epoch ms the drain began (the same value as `/health.drainingSince`).' }
+        deadlineAt: { type: integer, minimum: 0, description: Epoch ms the engine stops on its own (fixed when the drain was entered). }
+        state: { type: string, enum: [draining, already_draining] }
     RuleScope:
       description: >
         Where a persisted rule applies (core `RuleScope`). `project.root` is the directory prefix that decides
@@ -19602,9 +19733,12 @@ components:
         layer `root`, and the `project:<root>` discriminant string on write / revoke / the list filter):
         server >= 7.120.0 accepts only a COMPLETE ABSOLUTE PATH — POSIX `/…`, a Windows drive root `X:\…` / `X:/…`,
         or a UNC root `\\host\…` (the engine's durable-scope predicate; every server entry calls it rather than
-        keeping a copy). A relative root (`proj`, `./x`, `~/x`) or a drive without a root (`C:`, `C:x`) is a 400 whose
-        `error` is exactly "scope must be 'global' or 'project:<root>' with an absolute root" — code
-        `request.body_shape` on write / revoke / cc-import prepare, `request.query_invalid` on the list filter.
+        keeping a copy). A relative root (`proj`, `./x`, `~/x`) or a drive without a root (`C:`, `C:x`) is a 400 — code
+        `request.body_shape` on write / revoke / cc-import prepare, `request.query_invalid` on the list filter. Branch on `errorCode`;
+        the sentence is for people: on write / revoke / the list filter the `error` is exactly "scope must be 'global' or
+        'project:<root>' with an absolute root"; on cc-import prepare (whose body has no `scope` field) server >= 7.121.0 answers
+        "layers[<i>].root must be an absolute path" (`<i>` = the first refused layer, from 0; same predicate), while 7.120.x
+        answered with the scope sentence.
         Server <= 7.119.x checks only that the root is non-empty and keeps relative roots as written; such rows take
         no part in any check on 7.120.0 — SQL backends delete them with a one-time migration at boot, while on the
         file (`local`) backend they stay in the store, are absent from the listing, cannot be revoked, and each run
@@ -19699,8 +19833,8 @@ components:
         what is read is still only the allow bucket.
 
         🔴 `root` follows the RuleScope rule (server >= 7.120.0: a complete absolute path; otherwise 400
-        `request.body_shape` with "scope must be 'global' or 'project:<root>' with an absolute root" and no ticket
-        minted). It applies to ALL layers alike — a `userSettings` layer's root never becomes a scope, but it is the
+        `request.body_shape` and no ticket minted — the `error` is "layers[<i>].root must be an absolute path" on server >= 7.121.0,
+        naming the first refused layer, and the scope sentence on 7.120.x). It applies to ALL layers alike — a `userSettings` layer's root never becomes a scope, but it is the
         same field under the same check. On <= 7.119.x only an empty root is refused (with the body-shape sentence).
         Its TRUTHFULNESS is deliberately NOT validated: the server has no such tree to check against, and pretending
         to validate would be a lie. It is the user's own label for "which cwds should this rule be live under".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "17.2.0",
+  "version": "18.0.0",
   "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",
@@ -52,6 +52,6 @@
     "prepublishOnly": "rm -f tsconfig.tsbuildinfo && npm run build && npm run typecheck --workspaces=false --prefix ../.. && npm test --workspaces=false --prefix ../.. && npm run prepack"
   },
   "devDependencies": {
-    "@sema-agent/settings-schema": "^8.0.0"
+    "@sema-agent/settings-schema": "^9.0.0"
   }
 }