@sema-agent/sdk 0.0.119 → 0.0.121

package/openapi.yaml

@@ -719,6 +719,263 @@ paths:
         '404': { $ref: '#/components/responses/NotFound' }
         '501': { $ref: '#/components/responses/NotImplemented' }
 
+  /v1/sessions/{sessionId}/head:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    get:
+      tags: [sessions]
+      operationId: sessionsHead
+      x-status: live             # [1075]② session-follow light probe (server >=1.225).
+      summary: Light session-follow probe — the leaf pointer as a natural version number.
+      description: >
+        [1075]② — `leafId` is the session tree's leaf pointer; ANY append changes it, so it doubles as a
+        version number. Serves an ETag (`"<leafId>"`, `"empty"` when the session has no entries); poll with
+        `If-None-Match` and a hit is a zero-body 304 (idle-poll cost ≈ 0 — the deliberate alternative to a
+        cross-replica session SSE fan-out; the SSE face `/events` exists separately, connection-capped).
+        Owner-scoped (non-owner → 404, no existence oracle). 501 without a durable session store
+        (SESSION_BACKEND=tidb|pg|local).
+      parameters:
+        - in: header
+          name: If-None-Match
+          required: false
+          schema: { type: string }
+          description: Previous ETag; on match the response is 304 with no body.
+      responses:
+        '200':
+          description: The current leaf pointer (ETag header carries the same value).
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [sessionId, leafId]
+                properties:
+                  sessionId: { type: string }
+                  leafId: { type: string, nullable: true, description: "null = session exists but has no entries yet." }
+        '304': { description: 'Leaf unchanged since the presented ETag (no body).' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/sessions/{sessionId}/events:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    get:
+      tags: [sessions]
+      operationId: sessionsEvents
+      x-status: live             # [1196] session-level SSE head subscription.
+      summary: 'Session-level SSE: `event: head` pushes (latest-wins) when the leaf pointer moves.'
+      description: >
+        [1196] — the true-subscription face over the same predicate as `/head`: an SSE stream that pushes
+        `event: head` frames (data = the `/head` 200 body) whenever the session's leaf pointer changes,
+        latest-wins (intermediate leaves may be skipped). `?lastLeafId=` is the cursor — semantically the
+        ETag: when it matches the current leaf there is no initial frame; otherwise the current head is
+        replayed immediately on subscribe. 25s comment-line heartbeats. Auth and store gates are exactly
+        `/head`'s (owner-scoped 404; 501 without a durable session store). Connection cap exceeded →
+        503 + Retry-After — fall back to polling `/head` (advertised via `capabilities.sessionEvents`).
+      parameters:
+        - in: query
+          name: lastLeafId
+          required: false
+          schema: { type: string }
+          description: 'Cursor: the last seen leafId. Matching the current leaf suppresses the initial replay frame.'
+      responses:
+        '200':
+          description: 'SSE stream (`text/event-stream`) of `event: head` frames.'
+          content:
+            text/event-stream:
+              schema: { type: string }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+        '503': { description: 'Subscription connection cap exceeded — Retry-After set; fall back to polling /head.' }
+
+  /v1/sessions/{sessionId}/init:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    get:
+      tags: [sessions]
+      operationId: sessionsInit
+      x-status: live             # E11 shell-host startup bundle.
+      summary: One-call startup bundle for the shell banner (model + mode).
+      description: >
+        E11 (shell-host) — the one-call startup bundle so a shell renders its banner from ONE request instead
+        of fanning out to /v1/models + /v1/policy + /v1/capabilities. Worker-global config surface (same
+        posture as /v1/policy): principal OPTIONAL, enforced only under REQUIRE_PRINCIPAL. ADDITIVE contract —
+        `model` and `mode` are the load-bearing fields today; `tools`/`agents`/`commands`/`cwd` are omitted
+        (tolerate-absent; `cwd` is live-only E13 and never durable here).
+      responses:
+        '200':
+          description: The startup bundle.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [sessionId, model]
+                properties:
+                  sessionId: { type: string }
+                  model:
+                    type: object
+                    required: [provider, modelId]
+                    properties:
+                      provider: { type: string }
+                      modelId: { type: string }
+                  mode: { type: string, description: "Worker autonomy mode; absent when unconfigured." }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
+  /v1/sessions/{sessionId}/settings:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    get:
+      tags: [sessions]
+      operationId: sessionsSettings
+      x-status: live             # E24 read side (CC /config read). Write half needs a core seam — not advertised.
+      summary: Effective merged settings view (read-only).
+      description: >
+        E24 (shell-host) — the effective merged settings the run obeys (CC /config read side). Worker-global
+        config surface (principal optional unless REQUIRE_PRINCIPAL, same posture as /v1/policy and the E11
+        init bundle). The PATCH half (runtime settings write) needs a core seam and is deliberately absent —
+        no settings-write capability is advertised (honest read-only route).
+      responses:
+        '200':
+          description: The effective view.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [effective, applied]
+                properties:
+                  effective:
+                    type: object
+                    description: 'Resolved worker config: model, mode?, approvalRequire, commandPolicy, limits {maxTaskCostUsd, maxTaskTokens}.'
+                  applied:
+                    type: object
+                    description: 'Echo of the resolved model ({ model }).'
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
+  /v1/sessions/{sessionId}/notify:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    post:
+      tags: [sessions]
+      operationId: sessionsNotify
+      x-status: live             # External task_notification injection (frame family = [446] bg_notification).
+      summary: Inject an EXTERNAL task_notification into a session (live nudge or inbox park).
+      description: >
+        Inject an external completion/event notice into a session as a `task_notification` frame
+        (task_type="external" is minted by core — an external caller can never impersonate an internal frame;
+        sanitize/fencing/three-state delivery are core-side). Live half: the session's active stream on THIS
+        replica gets a core notify verb → `delivery: "live"` (200). Idle half: parked into the session inbox
+        (external key domain) and drained as a `task_notification` on the next stream open → `delivery:
+        "parked"` (202). Owner-scoped fail-closed (unknown or foreign session → 404, no oracle); core contract
+        rejections (`notify.*`) surface as 400 with `errorCode`, never silently parked. 501 without the
+        session-ownership face or (park path) the workflow completion inbox.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [task_id, status, summary]
+              properties:
+                task_id: { type: string, maxLength: 190 }
+                status: { type: string, enum: [completed, failed, killed, cancelled, event] }
+                summary: { type: string }
+                result: { type: string }
+                seq: { type: integer, minimum: 1 }
+                source: { type: string, maxLength: 190 }
+      responses:
+        '200':
+          description: Delivered onto the live stream.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [sessionId, delivery]
+                properties:
+                  sessionId: { type: string }
+                  delivery: { type: string, enum: [live] }
+        '202':
+          description: No live stream — parked in the session inbox, drained on the next stream open.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [sessionId, delivery]
+                properties:
+                  sessionId: { type: string }
+                  delivery: { type: string, enum: [parked] }
+                  note: { type: string }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/sessions/{sessionId}/wake:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    post:
+      tags: [sessions]
+      operationId: sessionsWake
+      x-status: live             # design/144 §3 wake arm.
+      summary: Wake a task_done-parked session (message delivery, NOT a gate decision).
+      description: >
+        design/144 §3 — deliver a message (or an already-parked pendingSteer) to a session parked on a
+        `task_done` checkpoint and resume it as the next turn's input. This is NOT a gate decision: it never
+        allows/denies a pending action — a pending gate ⇒ 409 `wake.gate_pending` (resolve through that gate's
+        own decide entry; approvals are never bypassed). Empty park + no message ⇒ nothing to deliver.
+        Owner-scoped; operator principals may carry trusted (`<system-reminder>`-bearing) messages. Resume
+        burns model budget — rate/quota/lease gates apply. 501 without the checkpoint store.
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                message: { type: string, minLength: 1 }
+      responses:
+        '202':
+          description: Resumed — the woken leg is driving into the durable run log.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [taskId, sessionId, status]
+                properties:
+                  taskId: { type: string }
+                  sessionId: { type: string }
+                  status: { type: string }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { description: 'No parked checkpoint for this session (nothing to wake), or session not visible to the caller.' }
+        '409': { description: 'Pending gate (`wake.gate_pending` — decide it through its own entry) or resume context missing.' }
+        '422': { description: '`steering.invalid_content` — the message failed the steering content gate.' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
   /v1/sessions/{sessionId}/policy:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
@@ -2569,13 +2826,16 @@ components:
             the user wants only files reverted. Target = a user-message SessionTreeEntry.id.
         permissionMode:
           type: string
-          enum: [default, plan, acceptEdits, bypassPermissions]
+          enum: [default, plan, acceptEdits, bypassPermissions, auto]
           description: >
-            CC permission-mode INTENT. The frontend (TUI shell / web portal) carries the RAW mode; the SERVICE
-            INTERPRETS it (axis-aware, tighten-only): `plan` ⇒ mount present_plan (core enablePlanMode) + read-only
-            hands (handsReadOnly) = CC EnterPlanMode read-only research; `acceptEdits`/`bypassPermissions` are
-            loosening, not honorable remotely (coerced to default engine-side, enforced client-side). Carrying the
-            intent (not pre-interpreted core fields) = one interpretation across frontends + service-owned governance.
+            CC permission-mode INTENT (the five CC modes verbatim, post-[816]/[820]/[822]). The frontend (TUI shell /
+            web portal) carries the RAW mode; the SERVICE interprets it TIGHTEN-ONLY vs the deployment baseline:
+            `plan` ⇒ mount present_plan (core enablePlanMode) + read-only hands (CC EnterPlanMode research);
+            `default` adds the manual ask gate; `auto` = same ask gate with core's auto-mode classifier screening
+            asks upstream (entitlement-gated in core); `acceptEdits`/`bypassPermissions` are honored as
+            "add less/no mode-derived gating" — they can never subtract from the deployment/operator policy
+            (deny-wins). An unknown string coerces to `default` (the most-asking mode). Carrying the intent
+            (not pre-interpreted core fields) = one interpretation across frontends + service-owned governance.
         attachmentIds:
           type: array
           maxItems: 16
@@ -3186,7 +3446,7 @@ components:
         sessionDelete: { type: boolean, description: "Session delete verb." }
         sessionInit: { type: boolean, description: "Session pre-initialization verb." }
         sessionPolicy: { type: boolean, description: "E6 per-session operator-tightened tool rules are durable." }
-        usage: { type: boolean, description: "Usage analytics face." }
+        usage: { type: boolean, description: "QUOTA face wired (server costQuota dep — cost/token budget enforcement + per-principal accounting). NOT an analytics-availability probe ([1871] B15): per-turn analytics (turn_end.usage, model_usage frames) are engine-side and unconditional, and GET /v1/usage always answers 200 (with `enabled: false` when the quota face is off). Gate quota UI on this key; never gate analytics on it." }
         policy: { type: boolean, description: "`GET /v1/policy` (autonomy/permission READ side)." }
         permissionModeWrite: { type: boolean, description: "Runtime permission-mode WRITE. Advertised false by design — autonomy is CONFIG, not steer; the READ side is `policy`." }
         modelSelection: { type: boolean, description: "`model` accepted per request." }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "0.0.119",
+  "version": "0.0.121",
   "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",