@sema-agent/sdk 0.0.117 → 0.0.119

package/openapi.yaml

@@ -1213,6 +1213,26 @@ paths:
               schema: { $ref: '#/components/schemas/PendingList' }
         '401': { $ref: '#/components/responses/Unauthorized' }
 
+  /v1/approvals/stream:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [approvals]
+      operationId: approvalsStream
+      x-status: live             # spec-path-gate 首批回填 2026-07-27(design/80 native push;SDK approvals.stream 消费)
+      summary: SSE — pending-approval deltas (subscribe once instead of polling GET /v1/approvals).
+      description: >
+        Frames: `meta` ({type,version,mode:"approvals-delta",pollMs}) then `pending`/`resolved` deltas (each
+        data payload mirrors its SSE event name in `data.type` — proxy-safe dispatch). Cross-replica by
+        construction (polls the SHARED checkpoint table). 15-min cap + heartbeats; a DB blip retries, never
+        kills the stream. Scope = the caller's principal (operator/trace token = fleet-wide).
+      responses:
+        '200':
+          description: text/event-stream of meta/pending/resolved frames.
+          content:
+            text/event-stream:
+              schema: { type: string }
+        '401': { $ref: '#/components/responses/Unauthorized' }
   /v1/approvals/{sessionId}/decide:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
@@ -1638,6 +1658,61 @@ paths:
               schema: { $ref: '#/components/schemas/UsageInfo' }
         '401': { $ref: '#/components/responses/Unauthorized' }
 
+  /v1/usage/summary:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [usage]
+      operationId: usageSummary
+      x-status: live             # spec-path-gate 首批回填 2026-07-27(SDK usage.summary() 已消费)
+      summary: Windowed usage totals (usage-analytics face).
+      description: >
+        READ-ONLY analytics aggregate over the caller's principal (operator/trace token = fleet-wide). Query:
+        `from`/`to` (ISO), `owner` (fleet-wide callers only). Response is the analytics aggregate — an OPEN
+        object (additive fields ride; consumers branch on known keys only).
+      responses:
+        '200':
+          description: Aggregate totals for the window.
+          content:
+            application/json:
+              schema: { type: object, additionalProperties: true }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+  /v1/usage/series:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [usage]
+      operationId: usageSeries
+      x-status: live             # spec-path-gate 首批回填 2026-07-27(SDK usage.series() 已消费)
+      summary: Usage time series (UTC buckets; empty buckets are OMITTED — consumers zero-fill).
+      description: >
+        Query: `metric` = tasks|tokensIn|tokensOut|costUsd, plus the summary window params. Buckets ride as an
+        OPEN object array (additive fields ride).
+      responses:
+        '200':
+          description: Time-series buckets (sparse — missing bucket = zero).
+          content:
+            application/json:
+              schema: { type: object, additionalProperties: true }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+  /v1/usage/breakdown:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [usage]
+      operationId: usageBreakdown
+      x-status: live             # spec-path-gate 首批回填 2026-07-27(SDK usage.breakdown() 已消费)
+      summary: Usage broken down by dimension.
+      description: >
+        Query: `dimension` = principal|model (default principal), plus the summary window params. OPEN object.
+      responses:
+        '200':
+          description: Per-dimension buckets.
+          content:
+            application/json:
+              schema: { type: object, additionalProperties: true }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
   /v1/policy:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
@@ -1762,6 +1837,67 @@ paths:
         '404': { description: no pending question for this id (non-owner, answered, expired, or wrong replica) — no existence oracle. }
         '501': { description: AskUserQuestion is not enabled on this worker (ASK_QUESTION_ENABLED). }
 
+  /v1/tool-approvals/{id}/respond:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - { name: id, in: path, required: true, schema: { type: string } }
+    post:
+      tags: [questions]
+      operationId: toolApprovalRespond
+      x-status: live             # spec-path-gate 首批回填 2026-07-27([816]/[820]② CC 三选卡;SDK toolApprovals.respond 消费)
+      summary: Answer a live policy `ask` (the CC three-choice card). LIVE-ONLY + same-replica.
+      description: >
+        Body `{decision: "allow"|"allow_session"|"deny", updatedInput?}` (`allow_session` additionally arms the
+        per-session allow-all for the fs-write family; `updatedInput` = ctrl+g edited args, server ≥1.28x G7).
+        Owner-gated with NO existence oracle (wrong owner / wrong replica / after settle or TTL → 404); body is
+        validated FIRST (400 is existence-independent). 501 when TOOL_APPROVAL_ENABLED is off.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [decision]
+              additionalProperties: true
+              properties:
+                decision: { type: string, enum: [allow, allow_session, deny] }
+                updatedInput: { description: 'ctrl+g edited tool args (replaces the asked args on allow).' }
+      responses:
+        '200':
+          description: Ack (`decision` echoed).
+          content:
+            application/json:
+              schema: { type: object, additionalProperties: true }
+        '400': { description: Malformed body (existence-independent). }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { description: Unknown/settled/expired/foreign approval (no existence oracle). }
+        '501': { description: Live tool-approval HITL not enabled (TOOL_APPROVAL_ENABLED). }
+
+  /v1/side-query:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    post:
+      tags: [tasks]
+      operationId: sideQuery
+      x-status: live             # spec-path-gate 首批回填 2026-07-27([1469] server 1.242;SDK sideQuery 消费)
+      summary: One-shot brain-routed Q&A — no session side effects, no tools, no streaming (v1).
+      description: >
+        Utility transport for a shell-side one-off question. Probe `capabilities.sideQuery`. Body/response are
+        OPEN objects (the brain answer rides `answer`; additive fields ride).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { type: object, additionalProperties: true }
+      responses:
+        '200':
+          description: The one-shot answer.
+          content:
+            application/json:
+              schema: { type: object, additionalProperties: true }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '501': { description: side-query not enabled on this worker. }
+
   /v1/workflows:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'

package/package.json

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