@sema-agent/sdk 0.1.3 → 0.1.5

package/openapi.yaml

@@ -4992,6 +4992,7 @@ components:
             turns: { type: number }
             costMicroUsd: { type: number }
         transcriptId: { type: string, description: "The child's transcript anchor (server 1.258). Additive." }
+        parentToolCallId: { type: string, description: 'The parent tool_use id VERBATIM (E2 domain, engine-minted) — [1832] P1-2, server >= 1.290 / engine 1.432; the terminal notification frame carries it too. Additive / tolerate-absent.' }
         ts: { type: integer }
     FleetFrame_hook_notice:
       type: object
@@ -6160,6 +6161,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: >
@@ -6190,3 +6294,515 @@ components:
         type: { const: failed }
         errorCode: { type: string }
         errorMessage: { type: string }
+
+    # ── resources/*.ts schema backfill, batch 2 (2026-07-28) — the 28-item WIRE_PENDING ratchet zeroed.
+    #    Each schema below is cross-checked against the server source (file:line cited in its description
+    #    or in the SDK resource JSDoc it mirrors). Wire objects are OPEN sets (additionalProperties: true).
+
+    ApprovalStreamEvent:
+      type: object
+      description: >
+        One delta event off GET /v1/approvals/stream (SSE; server streamApprovals, http/server.ts:8924).
+        Every data payload echoes a `type` field mirroring the SSE event name (so a client can dispatch
+        without the `event:` line). OPEN set — a consumer that does not parse the delta can treat any
+        non-heartbeat event as a "changed" signal and refetch the authoritative GET /v1/approvals list.
+        Known types: `meta` (first frame — {version, mode:"approvals-delta", pollMs}), `pending` (a new
+        suspend — the payload spreads the FULL PendingCheckpoint row), `synced` (end of the connect-time
+        snapshot — {count}), `resolved` (a decided/expired/gone pending — {sessionId, toolCallId}),
+        `heartbeat`, and `error` (the 15-minute stream cap — reconnect).
+      required: [type]
+      additionalProperties: true
+      properties:
+        type:
+          type: string
+          description: 'Open on read. Known values: pending / resolved / synced / heartbeat / meta / error.'
+        sessionId: { type: string, description: '`resolved` frames: which pending settled.' }
+        toolCallId: { type: string, description: '`resolved` frames: the settled pending''s bound tool-call id (absent when the pending carried none).' }
+        count: { type: integer, description: '`synced` frames: how many pendings the connect-time snapshot carried.' }
+
+    ParkedDecideAccepted:
+      type: object
+      description: >
+        The 200 body of POST /v1/approvals/{sessionId}/decide when the pending checkpoint belongs to a
+        PARKED background agent (server 1.267, ASSISTANT-WIRE-CONTRACT §4a parked variant; server
+        parked-decide.ts:272 — exact literal shape). ACCEPTANCE semantics: the revive drives
+        ASYNCHRONOUSLY — 200 means accepted, not completed; a failed drive honestly re-parks the row and
+        the pending re-appears on the list. Task-level suspends keep the legacy resumed shape —
+        discriminate by `status === "resuming"`.
+      required: [taskId, status, decision]
+      additionalProperties: true
+      properties:
+        taskId: { type: string, description: 'The background agent handle (a* domain).' }
+        status: { type: string, enum: [resuming] }
+        decision: { type: string, enum: [approve, deny] }
+
+    FleetMeta:
+      type: object
+      description: >
+        The connect-time `meta` frame payload of GET /v1/fleet/stream (server http/server.ts:9675 —
+        the payload view of FleetFrame_meta, without the SSE frame envelope).
+      required: [version, scoped]
+      additionalProperties: true
+      properties:
+        version: { type: integer }
+        scoped: { type: boolean, description: 'true ⇒ this connection is OWNER-SCOPED (the caller''s own rows); false ⇒ FLEET-WIDE (operator/trace token).' }
+        sessionScoped: { type: boolean, description: 'server 1.247+: true ⇒ this connection carries ?session= (rows AND notifications filtered by the host session). Additive / tolerate-absent.' }
+        bgNotifyFailClosed: { type: boolean, description: 'server 1.247+ generation flag: true ⇒ bg_notification delivery is fail-CLOSED for session-scoped subscribers (a new-generation shell may drop frame-level own/foreign discrimination — session-bound connections only). Absent = older server, keep discriminating.' }
+
+    FleetBgNotification:
+      type: object
+      description: >
+        A background child's COMPLETION notification payload (design/129-B gap②; service fleet-bus.ts
+        `BgNotification` minus the wire-stripped ownerScope/ownerSessionId — this is the post-strip
+        shape the SDK re-nests under FleetFrame's `notification`). EVENT semantics, not state — never in
+        the snapshot; consumers dedup by (taskId, status, seq). On the wire it rides FLAT inside the
+        `bg_notification` fleet frame (see FleetFrame_bg_notification).
+      required: [taskId, status, scope]
+      additionalProperties: true
+      properties:
+        taskId: { type: string, description: 'Registry handle (a* domain — the TaskOutput/TaskStop key).' }
+        sessionId: { type: string, description: "The child RUN's session id (uuid domain — the a*↔uuid dual anchor), when known." }
+        seq: { type: integer, description: 'Stop-cycle counter (server 1.239, core terminal-frame seq; a revive second cycle = higher seq) — fold into the dedup key. Absent on older engines.' }
+        status: { type: string, enum: [completed, failed, killed] }
+        summary: { type: string }
+        scope: { type: string, enum: [task, session], description: 'Background LIFETIME scope (design/129), NOT the tenant scope.' }
+        parentTaskId: { type: string }
+        stoppedBy: { type: string, description: 'Verbatim open enum (who/what stopped a killed child).' }
+        resumable: { type: boolean }
+        recentSteps:
+          type: array
+          items:
+            type: object
+            required: [tool, target, outcome]
+            properties:
+              tool: { type: string }
+              target: { type: string }
+              outcome: { type: string }
+        editedFiles:
+          type: array
+          items:
+            type: object
+            required: [path, edits]
+            properties:
+              path: { type: string }
+              edits: { type: integer }
+        rootSessionId: { type: string, description: 'Delegation-tree ROOT host session (fixed-point semantics — nested grandchildren anchor the root shell; server 1.250 / core 1.367δ). Additive.' }
+        usage:
+          type: object
+          description: 'Completion cost rollup (server 1.258; fields picked, numbers verbatim). Additive.'
+          properties:
+            totalTokens: { type: number }
+            toolUses: { type: number }
+            durationMs: { type: number }
+            tokens: { type: number }
+            turns: { type: number }
+            costMicroUsd: { type: number }
+        transcriptId: { type: string, description: "The child's transcript anchor (server 1.258). Additive." }
+        parentToolCallId: { type: string, description: 'The parent tool_use id VERBATIM (E2 domain, engine-minted) — [1832] P1-2, server >= 1.290 / engine 1.432. Additive / tolerate-absent.' }
+
+    FleetHookNotice:
+      type: object
+      description: >
+        A hook adjudication FAILED TO COMPLETE this cycle (service fleet-bus.ts `HookNotice` minus the
+        wire-stripped ownerScope/ownerSessionId — the payload view of FleetFrame_hook_notice). Semantics
+        are "could not evaluate", NOT "evaluated to fail": render as "this cycle went unguarded, allowed
+        through", never "the guard is broken". Pure observe — it does not block, resume, or inject.
+        Visibility is fail-CLOSED: a ?session= subscriber only receives notices provably owned by that
+        session.
+      required: [kind, event, reason]
+      additionalProperties: true
+      properties:
+        kind:
+          type: string
+          enum: [hook_decision_unavailable]
+          description: 'Only one kind today; an enum slot so the next observability frame kind needs no new frame arm.'
+        event: { type: string, description: 'Which hook event (Stop / PreToolUse / …) — defined by "a hook adjudication did not complete", not any single feature.' }
+        reason:
+          type: string
+          enum: [no_content, unparsed, skipped]
+          description: 'Machine-branchable cause. CLOSED on the server side (fleet-bus.ts HookNotice.reason) but OPEN ON READ — branch known values, render anything else as the generic "could not evaluate".'
+        detail: { type: string, description: 'Redacted supplement (e.g. why skipped). Additive / tolerate-absent.' }
+
+    BakeClaim:
+      type: object
+      description: >
+        The RUNNER claim response of POST /v1/images/bakes/claim and POST /v1/images/bakes/{bakeId}/claim
+        (server claimResponse, http/server.ts:9164 — exact key set): the VETTED argv + the per-bake ingest
+        secret (minted at claim, echoed on every ingest via the x-bake-ingest-secret header) + the
+        profile/bands the runner needs for its profile-aware hard deadline. The runner executes `argv`
+        VERBATIM — it never assembles its own command line. 204 (no body) = queue empty.
+      required: [bakeId, argv, push, dryRun, profile, ingestSecret, leaseUntil]
+      additionalProperties: true
+      properties:
+        bakeId: { type: string }
+        argv:
+          type: array
+          items: { type: string }
+          description: 'The server-assembled, whitelist-vetted build command — execute verbatim, never self-assemble.'
+        push: { type: boolean }
+        dryRun: { type: boolean }
+        logs: { description: 'Log routing config, passed through as stored (opaque to the claim contract).' }
+        profile: { type: string }
+        bands: { description: 'Profile bands for the runner''s profile-aware hard deadline (opaque passthrough).' }
+        ingestSecret: { type: string, description: 'Per-bake credential — the ONLY place it leaves image-api; echo it on every ingest.' }
+        leaseUntil:
+          description: 'Lease expiry (epoch ms or ISO timestamp depending on store backend).'
+          oneOf: [{ type: number }, { type: string }]
+
+    OutcomeRow:
+      type: object
+      description: >
+        One task-outcome ledger row of GET /v1/outcomes (envelope key `outcomes`; design/73 §7 read-only
+        base). Shape = the SQL ledgers' per-(taskSignature, model) summary projection (server
+        tidb-outcome-ledger.ts:186 / pg-outcome-ledger.ts:124 — the only queryable sinks; a File sink
+        501s honestly). OPEN set — mechanical-signal read-only surface.
+      required: [taskSignature, model, n, passRate, meanCostMicroUsd]
+      additionalProperties: true
+      properties:
+        taskSignature: { type: string }
+        model: { type: string }
+        n: { type: integer, description: 'How many outcome facts aggregate into this row.' }
+        passRate: { type: number }
+        meanCostMicroUsd: { type: number }
+
+    SendfileLinkRow:
+      type: object
+      description: >
+        One SendUserFile distribution-link ledger row of GET /v1/sendfile-links (envelope `{links,
+        nextBefore?}`; server http/server.ts:5504 — exact projection). A principal caller is PINNED to its
+        own scope (?scope= ignored); a fleet credential may pass ?scope= (default = the single-user
+        sentinel "_"). Page with `before` = a previous page's `nextBefore` (uuidv7; malformed → 400).
+      required: [id, filename, size, ttlSec, track, bucket, key, createdAt]
+      additionalProperties: true
+      properties:
+        id: { type: string, description: 'uuidv7 link id — also the `before` pagination cursor.' }
+        filename: { type: string }
+        size: { type: integer }
+        ttlSec: { type: integer }
+        track: { type: string }
+        bucket: { type: string }
+        key: { type: string, description: 'The object-store key the link resolves to.' }
+        createdAt: { type: string, description: 'ISO-8601.' }
+        taskId: { type: string, description: 'Issuing task, when recorded. Additive / tolerate-absent.' }
+        sessionId: { type: string, description: 'Issuing session, when recorded. Additive / tolerate-absent.' }
+
+    SubagentSteerReceipt:
+      type: object
+      description: >
+        The 200 receipt of POST /v1/runs/{runId}/subagents/{target}/steer and …/resume (server
+        http/server.ts:4143/4148 — exact literal: `status:"running"`, `delivery:"applied"`, `marker` =
+        the engine-minted delivery marker, `note` = the CC-verbatim "Message queued for delivery…" copy).
+      required: [taskId, target]
+      additionalProperties: true
+      properties:
+        taskId: { type: string, description: 'The parent runId (echoed).' }
+        target: { type: string, description: 'The child addressed (parentToolCallId or agentName), echoed.' }
+        status: { type: string, description: 'Literal "running" on today''s server.' }
+        delivery: { type: string, description: 'Literal "applied" on today''s server.' }
+        note: { type: string, description: 'The CC-verbatim queued copy ("Message queued for delivery to <name>…").' }
+        marker: { type: string, description: 'Engine-minted delivery marker (present on both steer and resume 200s, server 1.214+).' }
+
+    SubagentOutputResult:
+      type: object
+      description: >
+        The 200 body of GET /v1/runs/{runId}/subagents/{target}/output and the generic
+        …/tasks/{target}/output|/stop faces (server http/server.ts:3852/4070). `content` = the engine
+        TaskOutput-tool text (the child's final assistant body once terminal) — UNTRUSTED model output,
+        same posture as a run `result`. `output` = the engine registry's UnifiedTaskOutput projection
+        passed through VERBATIM.
+      required: [taskId, target, content, output]
+      additionalProperties: true
+      properties:
+        taskId: { type: string }
+        target: { type: string }
+        content: { type: string, description: 'UNTRUSTED engine/model output — render only.' }
+        output:
+          type: object
+          additionalProperties: true
+          description: 'The registry''s honest projection, verbatim (status/retrieval_status/partial flags).'
+          properties:
+            task_id: { type: string }
+            type: { type: string, description: 'Registry kind (e.g. background_agent / background_bash / monitor).' }
+            status: { type: string, description: 'Known: pending / running / completed / failed / killed (open on read).' }
+            retrieval_status: { type: string, description: '"success" once readable.' }
+            error: { type: string }
+            stoppedBy: { type: string }
+            seq: { type: integer, description: 'Stop-cycle generation (core 1.373 durable terminal-serve projection; 1 = first settle, >= 2 = a revive cycle re-settled). In-process poll does not project it — absent does not mean unsettled.' }
+            partial_result: { type: boolean }
+            details: { description: 'Kind-specific inner details, opaque passthrough.' }
+        cursorSemantics:
+          type: string
+          enum: [cursor, full]
+          description: >
+            G14 (server >= 1.291, generic taskOutput face ONLY — the narrow subagentOutput face does not
+            mint it): this read's cursor semantics. "cursor" = reading consumed the cursor (non-spool
+            background_bash: the client must accumulate; a re-read does not return old segments); "full" =
+            re-reading is safe (spool bash / monitor / agent reports). Not minted on error/not_ready
+            shapes — never treat absence as "full". Additive / tolerate-absent.
+
+    CompactAck:
+      type: object
+      description: >
+        The 202 ack of POST /v1/runs/{runId}/compact (K-1c manual compaction; server http/server.ts:3595 —
+        exact literal: `status:"running"`, `delivery:"accepted"`). ACCEPTANCE, not an outcome: compaction
+        runs at the next turn boundary and a `compacted{trigger:"manual"}` event rides the run stream ONLY
+        if anything was summarized (mooted/failed → no event).
+      required: [taskId]
+      additionalProperties: true
+      properties:
+        taskId: { type: string }
+        status: { type: string, description: 'Literal "running" on today''s server.' }
+        delivery: { type: string, description: 'Literal "accepted" on today''s server.' }
+        note: { type: string, description: 'The "compaction will run at the next turn boundary…" copy.' }
+
+    DetachAck:
+      type: object
+      description: >
+        The 202 ack of POST /v1/runs/{runId}/detach (server http/server.ts:3650 — exact literal:
+        `toolCallId` echoed, `delivery:"requested"`). Fire-and-forget: acceptance only — the
+        authoritative outcome is the tool call's own `tool_end.structured {detached:true, task_id}`;
+        a non-detachable env makes the request a fail-safe no-op.
+      required: [taskId]
+      additionalProperties: true
+      properties:
+        taskId: { type: string }
+        toolCallId: { type: string, description: 'Echoed from the request.' }
+        delivery: { type: string, description: 'Literal "requested" on today''s server.' }
+        note: { type: string, description: 'The fail-safe no-op copy.' }
+
+    SideQueryRequest:
+      type: object
+      description: >
+        The POST /v1/side-query body ([1469], server 1.242; http/server.ts:1853 — whitelist passthrough of
+        core SideQuerySpec). One-shot brain routing Q&A: no session side effects, no tool EXECUTION, no
+        engine-side policy gate, no streaming (v1). `signal` is server territory — client disconnect
+        abandons the call; sending it in the body is discarded. Rides every billable-submit gate
+        (no-token 503 fail-closed, draining/model-ready 503, rate/quota/lease).
+      required: [messages]
+      additionalProperties: true
+      properties:
+        model: { type: string, description: 'Pool name / role / @mention, resolved like the task face; default role when absent.' }
+        modelRole: { type: string }
+        thinking: { type: string, description: 'A core thinking level; invalid → 400.' }
+        systemPrompt: { type: string }
+        messages:
+          type: array
+          items: { type: object, additionalProperties: true }
+          description: 'core SideQueryMessage[] (user/assistant/toolResult arms; assistant metadata optional, string content foldable). Non-empty — [] → 400.'
+        tools:
+          type: array
+          items:
+            type: object
+            required: [name, description, parameters]
+            properties:
+              name: { type: string }
+              description: { type: string }
+              parameters: { type: object, additionalProperties: true }
+          description: 'Tool DEFINITIONS (so the model can emit toolCalls data) — the server NEVER executes them.'
+        maxOutputTokens: { type: integer }
+
+    SideQueryResult:
+      type: object
+      description: >
+        The 200 body of POST /v1/side-query (core SideQueryResult passed through verbatim, server
+        http/server.ts:1917). `model` = routing identity; `servedModel` = who actually served (degrading
+        fallback attributes honestly). A post-stream error lands in `errorMessage`, NOT an HTTP error
+        (400 is reserved for validation/model-resolution; 5xx = a server defect).
+      required: [text, toolCalls, model, servedModel, usage, stopReason]
+      additionalProperties: true
+      properties:
+        text: { type: string }
+        toolCalls:
+          type: array
+          items:
+            type: object
+            required: [id, name, args]
+            properties:
+              id: { type: string }
+              name: { type: string }
+              args: { description: 'The model-authored tool arguments (data only — nothing was executed).' }
+        model: { type: string, description: 'The routing identity the request resolved to.' }
+        servedModel: { type: string, description: 'Who actually served (degrading fallback attributes honestly).' }
+        degraded:
+          type: object
+          additionalProperties: true
+          properties:
+            from: { type: string }
+            to: { type: string }
+            reason: { type: string }
+        responseModel: { type: string }
+        usage: { type: object, additionalProperties: true }
+        usageMissing: { type: boolean, enum: [true] }
+        stopReason: { type: string }
+        errorMessage: { type: string, description: 'A post-stream error (contract: not thrown as HTTP).' }
+
+    ToolApprovalDecision:
+      type: string
+      enum: [allow, allow_session, deny]
+      description: >
+        The human's decision on a live tool-approval gate (server parseToolApprovalDecision,
+        tool-approval.ts — CLOSED 3-word set; anything else is a 400). `allow_session` = allow AND
+        remember for this session's category (fs-write tools share ONE category: approving Write covers
+        Edit/NotebookEdit; other tools are per-tool) — the CC "don't ask again this session" semantic.
+
+    ToolApprovalRespondAck:
+      type: object
+      description: >
+        The 200 ack of POST /v1/tool-approvals/{approvalId}/respond (server tool-approval.ts:521 — exact
+        shape, `decision` echoed). Owner-gated with a 404 and NO existence oracle: non-owner and
+        unknown/settled/expired/wrong-replica ids are indistinguishable.
+      required: [approvalId, delivery, decision]
+      additionalProperties: true
+      properties:
+        approvalId: { type: string }
+        delivery: { type: string, enum: [applied] }
+        decision: { $ref: '#/components/schemas/ToolApprovalDecision' }
+        rememberApplied:
+          type: boolean
+          description: >
+            server 1.239 ([1392]②): on allow_session, an honest echo of whether the grant was REALLY
+            recorded (true = landed in the bridge store; false = no sessionId, could not record — do not
+            render "session-wide allowed"). Omitted on non-allow_session decisions and on older servers.
+        updatedInputForwarded:
+          type: boolean
+          description: >
+            server 1.241 ([1458]): present (true) when an allow-family decision carried `updatedInput` and
+            the server forwarded the edited args to the engine — forwarded, not necessarily applied
+            (consumption depends on the core OnAsk object arm). Omitted on deny / no edit / older servers.
+
+    UsageMetric:
+      type: string
+      enum: [tasks, tokensIn, tokensOut, costUsd]
+      description: 'The ?metric= axis of GET /v1/usage/series (server usage-analytics.ts:67). Default costUsd.'
+
+    UsageGranularity:
+      type: string
+      enum: [hour, day]
+      description: 'The ?granularity= axis of GET /v1/usage/series (UTC buckets; server usage-analytics.ts:68). Default day.'
+
+    UsageDimension:
+      type: string
+      enum: [principal, model]
+      description: >
+        The ?dimension= axis of GET /v1/usage/breakdown (server usage-analytics.ts:85). Default principal.
+        A JWT principal querying dimension=principal only ever sees its own bucket (owner is enforced
+        upstream — the semantics hold naturally, no leak surface).
+
+    UsageTotals:
+      type: object
+      description: >
+        Window totals (server usage-analytics.ts:31 UsageTotals). tokensIn = Σ(inputTokens +
+        cacheReadTokens + cacheWriteTokens) — the billing view (cache hits count); tokensOut = Σ
+        outputTokens; costUsd = Σ costMicroUsd / 1e6 (authoritative micro-USD ledger, not an estimate).
+      required: [tasks, tokensIn, tokensOut, costUsd, estimated]
+      additionalProperties: true
+      properties:
+        tasks: { type: integer }
+        tokensIn: { type: number }
+        tokensOut: { type: number }
+        costUsd: { type: number }
+        estimated:
+          type: boolean
+          description: 'true = some rows lacked the per-model echo and fell back to stats.tokens (counted into tokensOut) — the token view is partly estimated. Honest flag, contract-required.'
+
+    UsageWindowBase:
+      type: object
+      description: >
+        The common window envelope of the /v1/usage/{summary,series,breakdown} responses (server
+        http/server.ts:1284). `from`/`to` are the RESOLVED window (ISO-8601; defaults now-7d..now).
+      required: [from, to]
+      additionalProperties: true
+      properties:
+        from: { type: string, description: 'ISO-8601 window start (resolved from the request or the 7-day default).' }
+        to: { type: string, description: 'ISO-8601 window end.' }
+        truncated:
+          type: boolean
+          enum: [true]
+          description: 'Present (true) ⇔ the store scan hit its row limit (USAGE_SCAN_LIMIT) — the window was truncated, never silently.'
+
+    UsageSummary:
+      description: 'The 200 body of GET /v1/usage/summary — window envelope + totals (server http/server.ts:1286).'
+      allOf:
+        - $ref: '#/components/schemas/UsageWindowBase'
+        - $ref: '#/components/schemas/UsageTotals'
+
+    UsageSeries:
+      description: >
+        The 200 body of GET /v1/usage/series (server http/server.ts:1294). UTC buckets; EMPTY BUCKETS ARE
+        NOT EMITTED — consumers zero-fill as needed.
+      allOf:
+        - $ref: '#/components/schemas/UsageWindowBase'
+        - type: object
+          required: [metric, granularity, series]
+          properties:
+            metric: { $ref: '#/components/schemas/UsageMetric' }
+            granularity: { $ref: '#/components/schemas/UsageGranularity' }
+            series:
+              type: array
+              items:
+                type: object
+                required: [t, v]
+                properties:
+                  t: { type: string, description: 'ISO-8601 bucket start (UTC).' }
+                  v: { type: number }
+
+    UsageBreakdown:
+      description: >
+        The 200 body of GET /v1/usage/breakdown (server http/server.ts:1302). dimension=model expands the
+        per-model echo (one run may contribute to several model buckets; fallback rows land in
+        "(unattributed)"); dimension=principal maps a NULL owner to "(anonymous)".
+      allOf:
+        - $ref: '#/components/schemas/UsageWindowBase'
+        - type: object
+          required: [dimension, breakdown]
+          properties:
+            dimension: { $ref: '#/components/schemas/UsageDimension' }
+            breakdown:
+              type: array
+              items:
+                allOf:
+                  - type: object
+                    required: [key]
+                    properties:
+                      key: { type: string, description: 'The bucket key (a principal or a model id).' }
+                  - $ref: '#/components/schemas/UsageTotals'
+
+    WorkflowAgentSteerReceipt:
+      type: object
+      description: >
+        The 200 receipt of POST /v1/workflows/{runId}/agents/{label}/steer (server http/server.ts:3752 —
+        exact literal: `status:"running"`, `delivery:"applied"`, `marker` = the engine-minted delivery
+        marker; NO `note`, unlike the run-subagent verb).
+      required: [runId, label]
+      additionalProperties: true
+      properties:
+        runId: { type: string }
+        label: { type: string }
+        status: { type: string, description: 'Literal "running" on today''s server.' }
+        delivery: { type: string, description: 'Literal "applied" on today''s server.' }
+        marker: { type: string, description: 'Engine-minted delivery marker.' }
+
+    WorkspaceSnapshotRow:
+      type: object
+      description: >
+        One snapshot row of GET /v1/sessions/{sessionId}/workspace (envelope `{sessionId, snapshots,
+        latest?, total}`; server http/server.ts:6109 — newest first, uuidv7 keys). E19 snapshot store's
+        read-only projection: each row is the freeze at a turn boundary, NOT a live workspace.
+      required: [key, files]
+      additionalProperties: true
+      properties:
+        key: { type: string, description: 'Snapshot key (uuidv7 entry id; "latest" is an accepted alias on the sub-routes).' }
+        files: { type: integer, description: 'Manifest row count.' }
+        bytes: { type: integer, description: 'Total snapshot bytes — present only when the store has a sizes face (SQL backends); the local store honestly omits it ([1894]② additive).' }
+
+    WorkspaceTreeEntry:
+      type: object
+      description: >
+        One file entry of GET /v1/sessions/{sessionId}/workspace/{key}/tree (envelope `{sessionId, key,
+        entries, total, nextOffset?}`; server http/server.ts:6144 — stable path order, offset paging).
+      required: [path, hash]
+      additionalProperties: true
+      properties:
+        path: { type: string, description: 'The relPath — pass VERBATIM as ?path= on the file sub-route.' }
+        hash: { type: string, description: 'Content address (sha256) — enables cross-snapshot change highlighting ([1894]②).' }
+        size: { type: integer, description: 'Present only when the store has a sizes face (SQL backends).' }

package/package.json

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