@sema-agent/sdk 0.1.3 → 0.1.4

package/openapi.yaml

@@ -6160,6 +6160,109 @@ components:
                     source: { type: string }
         isNew: { type: boolean }
 
+    ToolApprovalFrame:
+      type: object
+      description: >
+        LIVE tool-approval frame (SSE, `type` IS the event name). NOT an AgentEvent arm — it interleaves on the
+        run's stream when TOOL_APPROVAL_ENABLED. The shell renders `tool_approval` as the three-choice card and
+        dismisses it on `tool_approval_complete`. Respond via POST /v1/tool-approvals/{approvalId}/respond.
+      required: [type, approvalId]
+      additionalProperties: true
+      properties:
+        type: { type: string, enum: [tool_approval, tool_approval_complete] }
+        approvalId:
+          type: string
+          description: 'The approval''s OWN key (uuidv7) — echo it to respond; the complete frame settles by it.'
+        toolCallId:
+          type: string
+          description: >
+            server >= 1.307 (ADDITIVE), "tool_approval" only: the ENGINE's tool-call id — the same `call_…` that
+            rides the assistant message's tool_use block. ANCHOR THE CARD ON THIS. `approvalId` is unrelated to
+            that block and nothing else on the stream ever mentions it again, so a card keyed by it is never
+            reclaimed. Anchoring on "the most recent tool_start" does not work either: the approval frame arrives
+            BEFORE tool_start (measured 4020ms vs 4142ms in one turn). Absent on the complete frame (a second
+            anchor would only add ambiguity) and on servers < 1.307.
+        toolName: { type: string, description: '"tool_approval" only: canonical core tool name.' }
+        message: { type: string, description: '"tool_approval" only: the policy''s ask message, secret-redacted. UNTRUSTED for display.' }
+        args:
+          description: '"tool_approval" only: the call''s args, secret-redacted. UNTRUSTED for display. Absent (with argsOmitted) when over the byte cap or unserializable.'
+        argsOmitted: { type: boolean, enum: [true] }
+        fromSubagent:
+          type: boolean
+          enum: [true]
+          description: 'Present ⇔ the ask comes from a DELEGATED background/nested child — the EXPLICIT discriminator (trusted engine fact).'
+        sourceTaskId:
+          type: string
+          description: 'Child''s core session id (same id domain as task_progress.taskId) — row-join value + fallback discriminator against a server predating fromSubagent.'
+        sourceAgentName: { type: string, description: 'Display name of the child agent, redacted. UNTRUSTED.' }
+        outcome:
+          type: string
+          enum: [allowed, denied, expired]
+          description: '"tool_approval_complete" only. `expired` = TTL/abort/disconnect — a fail-closed DENY the shell should render as such, not as "still pending".'
+
+    QuestionFrame:
+      type: object
+      description: >
+        LIVE AskUserQuestion frame (SSE, `type` IS the event name). NOT an AgentEvent arm. Respond via
+        POST /v1/questions/{questionId}/respond; unanswered asks fall back to the headless default.
+      required: [type, questionId]
+      additionalProperties: true
+      properties:
+        type: { type: string, enum: [question, question_complete] }
+        questionId: { type: string, description: 'Echo it to respond.' }
+        questions:
+          type: array
+          items: { $ref: '#/components/schemas/AskQuestion' }
+          description: '"question" only: the model''s structured questions, secret-redacted. UNTRUSTED — never re-feed to a model. Absent on an over-cap payload (the ask then headless-defaults and the shell never renders it).'
+        outcome:
+          type: string
+          enum: [answered, unanswered]
+          description: '"question_complete" only: `answered` = a human responded; `unanswered` = ttl/abort/throttle released it (the model got the headless default). Cosmetic dismiss reason.'
+
+    AskQuestion:
+      type: object
+      description: 'One structured question inside a QuestionFrame (= core AskUserQuestion shape).'
+      required: [question, header, options, multiSelect]
+      additionalProperties: true
+      properties:
+        question: { type: string }
+        header: { type: string, description: 'Very short chip label (<= 12 chars).' }
+        multiSelect: { type: boolean }
+        options:
+          type: array
+          items: { $ref: '#/components/schemas/AskQuestionOption' }
+
+    AskQuestionOption:
+      type: object
+      required: [label, description]
+      additionalProperties: true
+      properties:
+        label: { type: string }
+        description: { type: string }
+        preview: { type: string, description: 'Optional monospace preview body (mockups / code / diagrams) rendered when this option is focused.' }
+
+    ElicitationFrame:
+      type: object
+      description: >
+        LIVE MCP elicitation frame (SSE, `type` IS the event name). NOT an AgentEvent arm. Respond via
+        POST /v1/elicitations/{elicitationId}/respond.
+      required: [type, elicitationId, mcpServerName]
+      additionalProperties: true
+      properties:
+        type: { type: string, enum: [elicitation, elicitation_complete] }
+        elicitationId: { type: string, description: 'Echo it to respond.' }
+        mcpServerName:
+          type: string
+          description: 'Which opted-in MCP server asked — also the trust label core fences `message` against.'
+        message: { type: string, description: '"elicitation" only: FENCED + secret-redacted human-facing prompt. UNTRUSTED — never re-feed to a model.' }
+        requestedSchema:
+          description: '"elicitation" only: the server''s requested input schema. OPAQUE passthrough — never interpreted/validated; still server-controlled UNTRUSTED, so fence it on display.'
+        mode: { type: string, enum: [form], description: '"elicitation" only: always "form" in v1 (url-mode is rejected upstream).' }
+        action:
+          type: string
+          enum: [accept, decline, cancel]
+          description: '"elicitation_complete" only: how it resolved (dialog dismiss reason).'
+
     Event_steering_injected:
       type: object
       description: >

package/package.json

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