@sema-agent/sdk 0.0.126 → 0.0.127

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "0.0.126",
+  "version": "0.0.127",
   "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",
@@ -27,21 +27,23 @@
     "./registry": {
       "types": "./dist/registry/index.d.ts",
       "import": "./dist/registry/index.js"
-    }
+    },
+    "./registry-openapi.yaml": "./registry-openapi.yaml"
   },
   "files": [
     "dist",
     "openapi.yaml",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "registry-openapi.yaml"
   ],
   "engines": {
     "node": ">=20"
   },
   "scripts": {
     "build": "tsc -b",
-    "clean": "rm -rf dist openapi.yaml LICENSE tsconfig.tsbuildinfo",
-    "prepack": "node -e \"require('fs').copyFileSync('../../spec/openapi.yaml','openapi.yaml');require('fs').copyFileSync('../../LICENSE','LICENSE')\"",
+    "clean": "rm -rf dist openapi.yaml registry-openapi.yaml LICENSE tsconfig.tsbuildinfo",
+    "prepack": "node -e \"require('fs').copyFileSync('../../spec/openapi.yaml','openapi.yaml');require('fs').copyFileSync('../../spec/registry-openapi.yaml','registry-openapi.yaml');require('fs').copyFileSync('../../LICENSE','LICENSE')\"",
     "publish:npm": "npm publish --access public --@sema-agent:registry=https://registry.npmjs.org/ --\"//registry.npmjs.org/:_authToken=${NPM_TOKEN}\"",
     "prepublishOnly": "rm -f tsconfig.tsbuildinfo && npm run build"
   },

package/registry-openapi.yaml

@@ -0,0 +1,250 @@
+openapi: 3.0.3
+info:
+  title: Sema Registry — the wire the SDK's `@sema-agent/sdk/registry` subpath consumes
+  version: "0.1.0"
+  description: >
+    ⚠️ AUTHORITY POSTURE (read first): the registry SERVER lives in the sema-registry repo (web AI);
+    the machine contract single-source is `@sema-agent/registry-core` (zod schemas + path constants —
+    AUTH_V1_PATHS/SCOPES_V1_PATHS etc.; the SDK keeps value-copies with same-source anchor tests).
+    THIS file documents the surface the SDK's registry subpath actually calls, so a consumer generating
+    a client from spec sees the full face — it mirrors, it does not rule. Backfilled 2026-07-28 from
+    the [1895] retirement map (cli's hand-rolled HTTP → SDK verbs, G17 R1-R4 + G22 era); guarded by
+    `registry-spec-path-gate.test.ts` (reflective: every /api path the SDK hits must be here, zero baseline).
+    USER-PLANE paths carry real request/response shapes; the ADMIN family (RegistryAdmin, user-JWT
+    role-gated — "admin" is a registry-side ROLE, not a separate credential) is documented loose
+    (operator tooling; shapes live in registry-core/zod and the registry server).
+  x-sdk-subpath: "@sema-agent/sdk/registry"
+paths:
+  /api/healthz:
+    get:
+      operationId: registryHealthz
+      summary: Registry liveness probe (probeRegistryHealth).
+      responses:
+        '200': { description: 'Alive. Open shape.' }
+
+  # ── auth (device flow RFC 8628 + refresh rotation + scope switch) ─────────────────────────────
+  /api/v1/auth/device/code:
+    post:
+      operationId: registryDeviceCode
+      summary: Start the device-authorization flow (requestDeviceCode).
+      responses:
+        '200':
+          description: '{device_code, user_code, verification_uri(_complete)?, interval, expires_in}.'
+          content: { application/json: { schema: { type: object, additionalProperties: true } } }
+  /api/v1/auth/device/token:
+    post:
+      operationId: registryDeviceToken
+      summary: Poll the device flow (pollUntilApproved's leg).
+      description: >
+        OAuth device-token semantics: `authorization_pending` keeps the interval, `slow_down` adds +5s,
+        `access_denied`/`expired_token` are terminal (typed errors in the SDK). Success = the token pair.
+      responses:
+        '200': { description: '{access_token, refresh_token, …} on approval.', content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+        '400': { description: 'OAuth error envelope {error: authorization_pending|slow_down|access_denied|expired_token|…}.' }
+  /api/v1/auth/device/approve:
+    post:
+      operationId: registryDeviceApprove
+      summary: Approve a pending device code (the signed-in side of the flow).
+      responses:
+        '200': { description: 'Approved.' }
+  /api/v1/auth/token/refresh:
+    post:
+      operationId: registryTokenRefresh
+      summary: Refresh-token rotation (STRICT single-use).
+      description: >
+        Rotation is single-use: the presented refresh_token is consumed; `invalid_grant` ⇒ the SDK
+        clears the token pair and surfaces a typed re-login error. The RegistryClient wraps this in a
+        single-flight 401-refresh-retry-once.
+      responses:
+        '200': { description: 'The NEW token pair (both tokens rotate).', content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+        '400': { description: '`invalid_grant` = consumed/expired refresh token → re-login.' }
+  /api/v1/auth/logout:
+    post:
+      operationId: registryLogout
+      summary: Revoke the session (logoutRegistry).
+      responses:
+        '200': { description: 'Revoked (SDK clears the TokenProvider either way).' }
+  /api/v1/auth/scope:
+    post:
+      operationId: registryScopeSwitch
+      summary: Switch the active scope (switchScope).
+      description: >
+        🔴 The response carries a NEW access_token but NO refresh_token (the refresh grant is untouched)
+        — the SDK PRESERVES the old refreshToken when persisting (copying the grant-shaped write here
+        would wipe it ⇒ next refresh = surprise logout; pinned by test).
+      responses:
+        '200': { description: '{access_token, scope, …} — NO refresh_token by design.', content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+
+  # ── scopes / effective config (user plane) ────────────────────────────────────────────────────
+  /api/v1/scopes:
+    get:
+      operationId: registryScopesList
+      summary: List the caller's scopes (listScopes; `?counts=` optional).
+      responses:
+        '200': { description: 'ScopesListResponse (registry-core schema).', content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+    post:
+      operationId: registryScopesCreate
+      summary: 'ADMIN: create a scope/space.'
+      responses: { '200': { description: Created. } }
+  /api/v1/effective:
+    get:
+      operationId: registryEffective
+      summary: The effective (merged) config for the caller (getEffective; ETag/304 engine).
+      description: >
+        Conditional-GET face: the SDK sends `If-None-Match` from the last ETag; 304 = unchanged (no
+        body). `?principal=` lets a service-credential caller read another principal's effective view.
+        Body is open-domain (domains are registry-defined; the consumer treats it as data).
+      parameters:
+        - { in: query, name: principal, required: false, schema: { type: string } }
+        - { in: header, name: If-None-Match, required: false, schema: { type: string } }
+      responses:
+        '200': { description: 'The effective view (ETag header rides).', content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+        '304': { description: 'Unchanged since the presented ETag.' }
+
+  # ── me / per-user config (CAS on the updatedAt STRING axis) ───────────────────────────────────
+  /api/v1/me:
+    get:
+      operationId: registryMe
+      summary: Who am I (claims + role).
+      responses:
+        '200': { description: 'The caller profile.', content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+  /api/v1/me/config/{domain}:
+    parameters:
+      - { in: path, name: domain, required: true, schema: { type: string } }
+    get:
+      operationId: registryMeConfigGet
+      summary: Read one config domain of the caller (getMeConfig).
+      responses:
+        '200': { description: '{value, updatedAt, …}.', content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+    put:
+      operationId: registryMeConfigPut
+      summary: CAS-write one config domain (putMeConfig; baseUpdatedAt = the compare axis).
+      description: >
+        🔴 CAS axis = the `updatedAt` STRING (verbatim echo), NOT a version number — the scopes/config
+        face below uses a NUMBER `version` axis; the two axes must never be mixed (pinned). 409 carries
+        `currentUpdatedAt` (typed ConfigCasConflictError; retryOn409 merge-callback retries ONCE).
+      responses:
+        '200': { description: Written. }
+        '409': { description: '{currentUpdatedAt} — concurrent write; refetch+merge+retry once.' }
+  /api/v1/users/{u}/config/{domain}:
+    parameters:
+      - { in: path, name: u, required: true, schema: { type: string } }
+      - { in: path, name: domain, required: true, schema: { type: string } }
+    get:
+      operationId: registryUserConfigGet
+      summary: 'Managed variant of me/config (--user; operator writes another user''s domain).'
+      responses: { '200': { description: 'Same shape as me/config.' } }
+    put:
+      operationId: registryUserConfigPut
+      summary: Managed CAS-write (same updatedAt axis + 409 semantics as me/config).
+      responses:
+        '200': { description: Written. }
+        '409': { description: '{currentUpdatedAt}.' }
+
+  # ── scope config draft / publish (CAS on the version NUMBER axis) ─────────────────────────────
+  /api/v1/scopes/{s}/config/{domain}:
+    parameters:
+      - { in: path, name: s, required: true, schema: { type: string } }
+      - { in: path, name: domain, required: true, schema: { type: string } }
+    get:
+      operationId: registryScopeConfigDraftGet
+      summary: Read a scope's config DRAFT (getScopeConfigDraft).
+      responses: { '200': { description: '{value, version, …}.' } }
+    put:
+      operationId: registryScopeConfigDraftPut
+      summary: CAS-write the draft (putScopeConfigDraft; version NUMBER axis — not updatedAt).
+      responses:
+        '200': { description: Written. }
+        '409': { description: 'Version conflict.' }
+  /api/v1/scopes/{s}/publish:
+    parameters:
+      - { in: path, name: s, required: true, schema: { type: string } }
+    post:
+      operationId: registryScopePublishRequest
+      summary: Request publish of the draft (requestPublish; goes through the approval gate).
+      responses: { '200': { description: 'Publish requested/pending.' } }
+
+  # ── feedback ──────────────────────────────────────────────────────────────────────────────────
+  /api/v1/feedback:
+    post:
+      operationId: registryFeedback
+      summary: Post product feedback (postFeedback; the privacy gate stays client-side).
+      responses: { '200': { description: Accepted. } }
+
+  # ── ADMIN family (RegistryAdmin; user JWT, registry-side role gate; loose shapes by design) ───
+  /api/v1/instance/features:
+    get: { operationId: adminInstanceFeatures, summary: 'ADMIN: instance feature flags.', responses: { '200': { description: OK } } }
+  /api/v1/users:
+    get: { operationId: adminUsersList, summary: 'ADMIN: list users.', responses: { '200': { description: OK } } }
+    post: { operationId: adminUsersCreate, summary: 'ADMIN: create user.', responses: { '200': { description: OK } } }
+  /api/v1/users/{u}:
+    parameters: [{ in: path, name: u, required: true, schema: { type: string } }]
+    get: { operationId: adminUsersShow, summary: 'ADMIN: show user.', responses: { '200': { description: OK } } }
+    delete: { operationId: adminUsersDelete, summary: 'ADMIN: delete user.', responses: { '200': { description: OK } } }
+  /api/v1/access-requests:
+    get: { operationId: adminAccessRequestsList, summary: 'ADMIN: list access requests (filters via query).', responses: { '200': { description: OK } } }
+  /api/v1/access-requests/{id}/decision:
+    parameters: [{ in: path, name: id, required: true, schema: { type: string } }]
+    post: { operationId: adminAccessRequestDecide, summary: 'ADMIN: decide an access request.', responses: { '200': { description: OK } } }
+  /api/v1/scopes/{id}:
+    parameters: [{ in: path, name: id, required: true, schema: { type: string } }]
+    patch: { operationId: adminSpacesPatch, summary: 'ADMIN: patch scope/space.', responses: { '200': { description: OK } } }
+    delete: { operationId: adminSpacesDelete, summary: 'ADMIN: delete scope/space.', responses: { '200': { description: OK } } }
+  /api/v1/scopes/{id}/members:
+    parameters: [{ in: path, name: id, required: true, schema: { type: string } }]
+    get: { operationId: adminSpaceMembersList, summary: 'ADMIN: list scope members.', responses: { '200': { description: OK } } }
+    put: { operationId: adminSpaceMembersPut, summary: 'ADMIN: upsert scope member.', responses: { '200': { description: OK } } }
+    delete: { operationId: adminSpaceMembersDelete, summary: 'ADMIN: remove scope member.', responses: { '200': { description: OK } } }
+  /api/v1/groups:
+    get: { operationId: adminGroupsList, summary: 'ADMIN: list groups.', responses: { '200': { description: OK } } }
+    post: { operationId: adminGroupsCreate, summary: 'ADMIN: create group.', responses: { '200': { description: OK } } }
+  /api/v1/groups/{id}:
+    parameters: [{ in: path, name: id, required: true, schema: { type: string } }]
+    get: { operationId: adminGroupsShow, summary: 'ADMIN: show group.', responses: { '200': { description: OK } } }
+    put: { operationId: adminGroupsRename, summary: 'ADMIN: rename group.', responses: { '200': { description: OK } } }
+    delete: { operationId: adminGroupsDelete, summary: 'ADMIN: delete group.', responses: { '200': { description: OK } } }
+  /api/v1/groups/{g}/members:
+    parameters: [{ in: path, name: g, required: true, schema: { type: string } }]
+    get: { operationId: adminGroupMembersList, summary: 'ADMIN: list group members.', responses: { '200': { description: OK } } }
+    put: { operationId: adminGroupMembersAdd, summary: 'ADMIN: add group member.', responses: { '200': { description: OK } } }
+    delete: { operationId: adminGroupMembersRemove, summary: 'ADMIN: remove group member.', responses: { '200': { description: OK } } }
+  /api/v1/audit:
+    get: { operationId: adminAuditList, summary: 'ADMIN: global audit log.', responses: { '200': { description: OK } } }
+  /api/v1/audit/{id}/diff:
+    parameters: [{ in: path, name: id, required: true, schema: { type: string } }]
+    get: { operationId: adminAuditDiff, summary: 'ADMIN: one audit entry''s diff.', responses: { '200': { description: OK } } }
+  /api/v1/scopes/{s}/audit:
+    parameters: [{ in: path, name: s, required: true, schema: { type: string } }]
+    get: { operationId: adminAuditListScoped, summary: 'ADMIN: scope-scoped audit log.', responses: { '200': { description: OK } } }
+  /api/v1/scopes/{s}/audit/{id}/diff:
+    parameters:
+      - { in: path, name: s, required: true, schema: { type: string } }
+      - { in: path, name: id, required: true, schema: { type: string } }
+    get: { operationId: adminAuditDiffScoped, summary: 'ADMIN: scope-scoped audit diff.', responses: { '200': { description: OK } } }
+  /api/v1/images:
+    get: { operationId: adminImagesList, summary: 'ADMIN: sandbox image profiles.', responses: { '200': { description: OK } } }
+  /api/v1/images/{profile}:
+    parameters: [{ in: path, name: profile, required: true, schema: { type: string } }]
+    get: { operationId: adminImagesShow, summary: 'ADMIN: one image profile.', responses: { '200': { description: OK } } }
+  /api/v1/secrets:
+    get: { operationId: adminSecretsList, summary: 'ADMIN: secrets metadata (values never returned).', responses: { '200': { description: OK } } }
+  /api/v1/secrets/refs:
+    get: { operationId: adminSecretsRefs, summary: 'ADMIN: secret reference names.', responses: { '200': { description: OK } } }
+  /api/v1/auth-providers:
+    get: { operationId: adminAuthProvidersList, summary: 'ADMIN: auth providers.', responses: { '200': { description: OK } } }
+  /api/v1/auth-providers/{id}:
+    parameters: [{ in: path, name: id, required: true, schema: { type: string } }]
+    get: { operationId: adminAuthProvidersShow, summary: 'ADMIN: one auth provider.', responses: { '200': { description: OK } } }
+  /api/v1/scopes/{s}/rollback:
+    parameters: [{ in: path, name: s, required: true, schema: { type: string } }]
+    post: { operationId: adminScopeRollback, summary: 'ADMIN: rollback a scope''s published config.', responses: { '200': { description: OK } } }
+  /api/v1/usage/me:
+    get: { operationId: adminUsageMe, summary: 'Usage of the caller.', responses: { '200': { description: OK } } }
+  /api/v1/usage/summary:
+    get: { operationId: adminUsageSummary, summary: 'ADMIN: usage summary.', responses: { '200': { description: OK } } }
+  /api/v1/scopes/{s}/publish/approve:
+    parameters: [{ in: path, name: s, required: true, schema: { type: string } }]
+    post: { operationId: adminPublishApprove, summary: 'ADMIN: approve a pending publish.', responses: { '200': { description: OK } } }
+  /api/v1/scopes/{s}/publish/pending:
+    parameters: [{ in: path, name: s, required: true, schema: { type: string } }]
+    delete: { operationId: adminPublishWithdraw, summary: 'ADMIN: withdraw a pending publish.', responses: { '200': { description: OK } } }