@sema-agent/sdk 0.0.118 → 0.0.120

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'
@@ -2433,13 +2569,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
@@ -3050,7 +3189,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.118",
+  "version": "0.0.120",
   "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",