@sema-agent/sdk 0.0.100 → 0.0.101

package/openapi.yaml

@@ -1958,7 +1958,44 @@ components:
         outputTokens: { type: integer }
         costUsd: { type: number }
         cacheHitRate: { type: number }
+        toolCalls: { type: integer }
+        cacheWriteTokens: { type: integer, description: Short-TTL cache-write tokens. }
+        cacheWriteTokensLong: { type: integer, description: Long-TTL (1h) cache-write tokens, priced separately. }
+        totalInputTokens:
+          type: integer
+          description: Normalized total input (prompt + cache reads) — the denominator most cost views want.
+        costMicroUsd:
+          type: integer
+          description: >
+            Integer micro-USD cost. Prefer this over the float `costUsd` for accounting (no FP drift). Both are
+            emitted; they describe the same spend.
+        costBreakdown:
+          description: >
+            Per-axis cost detail (LLM root / nested subagents / compaction / infra). Deliberately untyped — it is an
+            OPEN map whose axes grow with the engine; read defensively rather than modelling it.
+        humanReview:
+          type: object
+          description: MF-24 — human-in-the-loop wait ledger for this task (present once any gate was hit).
+          required: [count, totalWaitMs, gates]
+          properties:
+            count: { type: integer }
+            totalWaitMs: { type: integer }
+            gates:
+              type: array
+              description: One row per gate. OPEN objects — engine may add keys.
+              items:
+                type: object
+                required: [kind, waitMs]
+                additionalProperties: true
+                properties:
+                  kind: { type: string }
+                  waitMs: { type: integer }
+                  decision: { type: string }
+                  toolName: { type: string }
       required: [turns, tokens]
+      # 🔴 OPEN: the engine may carry fields not named here (live-observed, e.g. extra costBreakdown axes) — the SDK
+      # passes them through rather than dropping, so consumers must not assume this list is exhaustive.
+      additionalProperties: true
 
     TaskRequest:
       type: object
@@ -2086,6 +2123,96 @@ components:
               properties:
                 count: { type: integer }
                 role: { type: string, description: A model role name. }
+        compactionModel:
+          type: string
+          description: >
+            Pin a SEPARATE (usually cheaper) model for compaction. Validated against the catalog on submit — an
+            unknown ref is a 400, not a silent fallback to the main model's price.
+        appendSystemPrompt: { type: string, description: Text appended to the assembled system prompt for this task. }
+        promptProfile:
+          type: string
+          enum: [simple, classic]
+          description: Which prompt-assembly profile to use.
+        clientContext:
+          type: object
+          description: Non-authoritative client hints (never trusted for authz).
+          properties:
+            timeZone: { type: string }
+            userEmail: { type: string }
+        sandboxImageProfile: { type: string, description: Sandbox image profile name for the execution env. }
+        capabilitiesNeeded:
+          type: array
+          items: { type: string }
+          description: Capability names the caller requires; the worker refuses up front rather than 501-ing mid-run.
+        memoryWrite: { type: boolean, description: Allow this task to WRITE user memory (read is governed separately). }
+        settings:
+          type: object
+          description: >
+            TOC `settings.json` contract carried to the worker (CC-parity v1: permissions/hooks/env/model/
+            outputStyle). The SDK owns the schema in `src/settings.ts` (`SemaSettings`) — it is deliberately NOT
+            duplicated here as a component: the service passes it through to core rather than interpreting it, so
+            the TS type is the single authority. OPEN object.
+          additionalProperties: true
+        cwd: { type: string, description: Working directory for the execution env. }
+        selfOrchestration: { type: boolean, description: Permit S8 self-orchestration (run_workflow) inside this task. }
+        enableFork: { type: boolean, description: Permit session forking from inside this task. }
+        agents:
+          type: array
+          items:
+            type: object
+            description: >
+              One per-task sub-agent definition. Shape owned by `TaskAgentDefinition` in the SDK types; kept OPEN
+              here rather than duplicated (same reasoning as `settings`).
+            additionalProperties: true
+          description: Per-task sub-agent definitions (roster additions scoped to this task only).
+        interactiveTools: { type: boolean, description: Mount interactive (prompting) tools. }
+        retainBackgroundProcesses: { type: boolean, description: Keep background processes alive past the turn. }
+        excludeTools:
+          type: array
+          items: { type: string }
+          description: Tool names to withhold from this task's roster.
+        deferTools:
+          type: array
+          items: { type: string }
+          description: Tool names to DEFER (discoverable via tool search instead of mounted up front).
+        attachments:
+          type: object
+          description: >
+            Turn-boundary reminder attachments (design/133 + G1). Each flag opts INTO an injection; omitted = off.
+            `changedFiles` may also be an object to cap the listing.
+          additionalProperties: true
+          properties:
+            todoReminder: { type: boolean }
+            todoReminderMode: { type: string, enum: [baseline, off] }
+            changedFiles:
+              oneOf:
+                - { type: boolean }
+                - { type: object, properties: { maxFiles: { type: integer } } }
+            planModeReminder: { type: boolean }
+            budgetUsd: { type: boolean }
+            backgroundTasks: { type: boolean }
+            toolsDelta: { type: boolean }
+            agentListing: { type: boolean }
+            skillsListing: { type: boolean }
+            mcpInstructions: { type: boolean }
+        limits:
+          type: object
+          description: >
+            Per-task bounds. The three `false`-only switches are OPT-OUTS of engine defaults (there is no `true`
+            form — passing false disables that default behaviour).
+          properties:
+            timeoutSec: { type: integer }
+            maxOutputTokens: { type: integer }
+            maxTurns: { type: integer }
+            deadlineNudge: { type: boolean, enum: [false] }
+            callCapByDeadline: { type: boolean, enum: [false] }
+            gracefulFinalize: { type: boolean, enum: [false] }
+        outputRetries: { type: integer, description: How many times to retry a malformed structured output. }
+        compaction:
+          type: object
+          description: Compaction tuning for this task.
+          properties:
+            clampTolerance: { type: number }
 
     TaskResult:
       type: object
@@ -2096,6 +2223,46 @@ components:
         sessionId: { type: string }
         status: { $ref: '#/components/schemas/RunStatus' }
         result: { type: string }
+        model:
+          type: string
+          description: >
+            MF-25 — the EFFECTIVE model id that served this task: the RESOLVED `Model.id`, NOT the requested
+            `model` ref (which may be a role / catalog name / `@mention`). Lets a UI echo "served by X" instead of
+            the requested ref. A mid-run degradation is reported separately via `degraded`. Verified to reach the
+            wire by a real-HTTP regression pin on the server side (`test/effective-model-echo-wire.test.ts`).
+        salvagedOutput:
+          type: string
+          description: Partial output preserved when the run could not complete normally (best-effort salvage).
+        blockedReason:
+          type: string
+          description: Why a `blocked` status was reached (human-readable).
+        checkpointGate:
+          description: >
+            The gate kind that produced `checkpointToken` when the run suspended. Deliberately UNTYPED here —
+            the shape is core's and still evolving; treat it as opaque and branch on `status`/`errorCode` instead.
+        degraded:
+          type: object
+          description: >
+            Set when the run was served by a FALLBACK model after the requested one became unusable mid-run.
+            `from`/`to` are resolved `Model.id`s; `atTurn` is the turn index where the switch happened.
+          required: [from, to, reason, atTurn]
+          properties:
+            from: { type: string }
+            to: { type: string }
+            reason:
+              type: string
+              description: >
+                Open enum — known values `breaker_open` | `rate_limit` | `budget` | `server_error` |
+                `last_resort`; treat unknown values as opaque rather than failing closed.
+            chain:
+              type: array
+              items: { type: string }
+              description: The full fallback chain walked, when more than one hop occurred.
+            atTurn: { type: integer }
+        structuredOutput:
+          description: >
+            The task's structured (schema-constrained) output when one was requested. Shape is caller-defined,
+            so this is intentionally untyped.
         errorCode:
           type: string
           description: >
@@ -2144,6 +2311,37 @@ components:
           description: >
             System attribution DERIVED FROM the authenticating credential (unforgeable; body injection ignored).
             e.g. oa | cc-mcp | portal. LIVE (service cf1be73).
+        suggestions:
+          type: array
+          items: { type: string }
+          description: Follow-up prompt suggestions produced for this run (absent when none were generated).
+        supervisorCost: { $ref: '#/components/schemas/SupervisorCostBreakdown' }
+
+    SupervisorCostBreakdown:
+      type: object
+      description: >
+        Per-axis cost rollup for a supervised run. `llm` is `null` on a run whose LLM spend was not attributed
+        (e.g. no brain call). All amounts are integer micro-USD (no float drift).
+      required: [llm, infra, totalMicroUsd]
+      properties:
+        llm:
+          type: ['object', 'null']
+          required: [llmRootMicroUsd, nestedSubagentMicroUsd, memoryConsolidationMicroUsd, compactionMicroUsd]
+          properties:
+            llmRootMicroUsd: { type: integer }
+            nestedSubagentMicroUsd: { type: integer }
+            memoryConsolidationMicroUsd: { type: integer }
+            compactionMicroUsd: { type: integer }
+        infra:
+          type: object
+          description: Service-owned infra rates (the engine prices only LLM tokens); all default 0 when unpriced.
+          required: [toolCallMicroUsd, sandboxWalltimeMicroUsd, egressMicroUsd, totalMicroUsd]
+          properties:
+            toolCallMicroUsd: { type: integer }
+            sandboxWalltimeMicroUsd: { type: integer }
+            egressMicroUsd: { type: integer }
+            totalMicroUsd: { type: integer }
+        totalMicroUsd: { type: integer, description: llm + infra. }
 
     CancelAck:
       type: object
@@ -2155,6 +2353,13 @@ components:
         taskId: { type: string }
         status: { type: string }
         note: { type: string }
+        errorCode:
+          type: [string, "null"]
+          description: >
+            Present on the two real terminal paths (the common `"cancelled"` outcome, and an explicit `null` when a
+            concurrent reaper/another leg terminalized first — the ack reports the ACTUAL row, it does not fabricate
+            "cancelled"). OMITTED entirely on the plain `cancelling` / no-op branches, so treat absence as "unknown",
+            not as "no error".
 
     ResumeEvicted:
       type: object
@@ -2362,6 +2567,74 @@ components:
         memory:
           type: boolean
           description: Memory transparency endpoints (GET/DELETE /v1/memory) available. the pinned wire contract.
+        workflows: { type: boolean, description: "S8 self-orchestration workflow routes are mounted." }
+        workflowsList: { type: boolean, description: "`GET /v1/workflows` list face (separate from the per-run reads)." }
+        resumeAt: { type: boolean, description: "E18 resume-at-message anchors are resolvable." }
+        rewindFiles: { type: boolean, description: "E19 working-tree snapshot/restore is wired." }
+        rewindFilesTo: { type: boolean, description: "Restore to a SPECIFIC entry id (not just the latest snapshot)." }
+        manualCompact: { type: boolean, description: "`POST /v1/runs/:id/compact` (needs a run store)." }
+        sessions: { type: boolean, description: "Session read face (`GET /v1/sessions/:id`)." }
+        sessionList: { type: boolean, description: "`GET /v1/sessions` list/picker face." }
+        sessionSearch: { type: boolean, description: "Server-side session search." }
+        sessionFork: { type: boolean, description: "Session fork verb." }
+        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." }
+        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." }
+        effortSelection: { type: boolean, description: "`reasoningEffort` accepted per request." }
+        compactionModel: { type: boolean, description: "A separate model may be pinned for compaction." }
+        appendSystemPrompt: { type: boolean, description: "Per-request system-prompt append is honoured." }
+        toolOutput: { type: boolean, description: "`tool_end` carries the model-facing output." }
+        messageIdentity: { type: boolean, description: "Content events carry `eventId` (+ `parentToolCallId` for sub-agents)." }
+        forwardSubagentEvents: { type: boolean, description: "Sub-agent events are forwarded onto the parent stream." }
+        subagentSteer: { type: boolean, description: "Mid-flight steer of a named sub-agent." }
+        subagentResume: { type: boolean, description: "Operator resume of a settled sub-agent." }
+        subagentOutput: { type: boolean, description: "Sub-agent output read face." }
+        subagentStream: { type: boolean, description: "Per-sub-agent event stream." }
+        taskHandles: { type: boolean, description: "Durable task handles (output/stop verbs by handle)." }
+        taskAgents: { type: boolean, description: "Per-task agent definitions are accepted." }
+        retainBackgroundProcesses: { type: boolean, description: "Background processes may be retained past the turn." }
+        interactiveTools: { type: boolean, description: "Interactive (prompting) tools are available." }
+        projectContext: { type: boolean, description: "Project-context injection is wired." }
+        mcp: { type: boolean, description: "MCP servers can be attached." }
+        mcpInjection: { type: boolean, description: "Per-request MCP injection is accepted." }
+        mcpElicitation: { type: boolean, description: "MCP elicitation round-trips are supported." }
+        askUserQuestion: { type: boolean, description: "AskUserQuestion gate is available (durable when approvals are)." }
+        toolApproval: { type: boolean, description: "Tool-approval gating is active." }
+        promptSuggestions: { type: boolean, description: "Follow-up prompt suggestions are generated." }
+        modelUsage: { type: boolean, description: "`GET /v1/runs/:id/model-usage` (needs a run store + usage plane)." }
+        scheduler: { type: boolean, description: "Assistant-scheduler face is mounted." }
+        sendUserFile: { type: boolean, description: "Outbound user-file delivery is wired." }
+        sendUserFileLedger: { type: boolean, description: "The send-file ledger (audit of deliveries) is available." }
+        excludeTools:
+          type: array
+          items: { type: string }
+          description: Tool names this worker will honour in a request's exclude list.
+        deferTools:
+          type: array
+          items: { type: string }
+          description: Tool names that can be DEFERRED (surfaced via search rather than mounted up front).
+        s3PublicEndpoint:
+          type: ["string", "null"]
+          description: >
+            Public base URL for artifact/snapshot links, when the deployment exposes one. `null` = not configured
+            (links are then worker-relative). One of only two NON-boolean capability values the server emits.
+        taskSettings:
+          type: object
+          description: >
+            Which `settings.json` sub-faces this worker honours (CC-parity v1). OPEN object — unknown keys may
+            appear. The other non-boolean capability value.
+          additionalProperties: true
+          properties:
+            permissions: { type: boolean }
+            permissionMode: { type: boolean }
+            model: { type: boolean }
+            outputStyle: { type: boolean }
+            env: { type: boolean }
+            hooks: { type: boolean }
         memoryWrite:
           type: boolean
           description: MF-30 — memory WRITE (append/edit/forget) available (deps.memory.append; server.ts:828).
@@ -2583,6 +2856,9 @@ components:
       properties:
         id: { type: string, description: 'Run id (= WorkflowRun.id).' }
         scope: { type: string, description: 'Tenant/group scope (= the creating principal).' }
+        name: { type: string, description: "The workflow script's declared `meta.name`." }
+        description: { type: string, description: "The workflow script's declared `meta.description` (one-liner)." }
+        currentPhase: { type: string, description: 'Title of the phase currently executing (absent once terminal).' }
         status: { $ref: '#/components/schemas/WorkflowRunStatus' }
         phaseCount: { type: integer, description: 'Phases recorded.' }
         agentCount: { type: integer, description: 'Agent-runs recorded.' }
@@ -2601,6 +2877,8 @@ components:
       properties:
         id: { type: string }
         scope: { type: string }
+        name: { type: string, description: "The workflow script's declared `meta.name`." }
+        description: { type: string, description: "The workflow script's declared `meta.description` (one-liner)." }
         status: { $ref: '#/components/schemas/WorkflowRunStatus' }
         phases: { type: array, description: 'Phase records (permissive).', items: {} }
         agents: { type: array, description: 'Agent-run records (permissive).', items: {} }
@@ -2873,6 +3151,18 @@ components:
             (they carry a RiskDescriptor); ABSENT for resource_limit/needs_review/plan_review — UI tolerates undefined.
         spentMicroUsd: { type: number, description: 'cumulative spend on the suspend chain (when a resource ledger is attached).' }
         deadline: { type: integer, description: 'awaiting-human SLA deadline (epoch ms).' }
+        contentKind:
+          type: string
+          description: >
+            Open enum (known value `content_ask`) distinguishing WHAT is being asked about, for gates whose payload
+            is content rather than a tool call. Treat unknown values as opaque.
+        sourceTaskId: { type: string, description: 'The task that produced this checkpoint (when distinct from sessionId).' }
+        principal: { type: string, description: 'The submitting principal, when the deployment records one.' }
+        createdAt: { type: integer, description: 'Creation time, epoch ms (NOTE — SessionRecord.createdAt is an ISO string).' }
+        preview:
+          description: >
+            Optional human-facing preview of what is being approved. Deliberately UNTYPED — the shape follows the
+            gate kind and is meant for display only; never branch on it.
 
     InboxRow:
       description: >
@@ -2883,6 +3173,20 @@ components:
         - type: object
           properties:
             objective: { type: ['string', 'null'], description: 'task objective, null if unavailable.' }
+            toolName:
+              type: ['string', 'null']
+              description: 'The gated tool, when the pause came from a tool call (null for non-tool gates).'
+            toolCallId: { type: string, description: 'The gated tool-call id.' }
+            boundCallId: { type: string, description: 'D-1 decision binding — echo it back on /decide.' }
+            boundInputHash:
+              type: string
+              description: >
+                D-1 decision binding — hash of the bound tool input. Echo on /decide so an approval cannot land on
+                a DIFFERENT call that was swapped in after the operator looked.
+            input:
+              description: >
+                REDACTED tool input for display. Untyped by design (per-tool shape) — and note the raw `toolInput`
+                is deliberately NOT on this row: the handler always strips it (along with `token`) before returning.
 
     InboxList:
       type: object
@@ -2960,6 +3264,10 @@ components:
           properties:
             provider: { type: string }
             modelId: { type: string }
+        window:
+          $ref: '#/components/schemas/SessionWindow'
+        promptEpoch:
+          $ref: '#/components/schemas/PromptEpoch'
         messages:
           type: array
           items: {}
@@ -2980,6 +3288,45 @@ components:
         runCount: { type: integer }
         objectivePreview: { type: ['string', 'null'] }
         lastStatus: { type: string }
+        lastRunId:
+          type: ['string', 'null']
+          description: The most recent run's id (null when the session has no run yet) — lets a picker deep-link.
+        title:
+          type: ['string', 'null']
+          description: >
+            Auto-generated session summary title (service-side `session-titler`: one cheap model call kicked off in
+            the background after the first submit, idempotent via an IS-NULL gate). Genuinely `null` until it lands,
+            so render a fallback rather than waiting on it.
+
+    SessionWindow:
+      type: object
+      description: >
+        Pagination window echoed by `GET /v1/sessions/:id` when the caller asked for a message slice.
+        OPEN object — additional keys may appear.
+      required: [offset, total]
+      additionalProperties: true
+      properties:
+        offset: { type: integer, description: Index of the first returned message within the full context. }
+        total: { type: integer, description: Total messages available (so a client can page). }
+
+    PromptEpoch:
+      type: object
+      description: >
+        A session's prompt-epoch pin (server >=1.220, additive on `GET /v1/sessions/:id`). Identifies WHICH
+        assembled system-prompt artifact this session is pinned to, so a transcript stays reproducible across
+        prompt-pack releases. IDs/digests only — never prompt text. OPEN object.
+      required: [epoch, artifactDigest, packId, assemblyApi, activatedBy]
+      additionalProperties: true
+      properties:
+        epoch: { type: integer, description: Monotonic epoch counter within the session. }
+        artifactDigest: { type: string, description: 'Content digest of the assembled artifact (`sha256:<64 hex>`).' }
+        packId: { type: string, description: 'Prompt-pack identity, e.g. `sema-default@1`.' }
+        assemblyApi: { type: integer, description: Assembly-contract version (currently always 1). }
+        activatedBy:
+          type: string
+          description: >
+            Open enum — known values `session_start` | `compaction` | `legacy_migration`; treat unknown values as
+            opaque rather than failing closed.
 
     SessionListPage:
       type: object

package/package.json

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