@sema-agent/sdk 0.0.121 → 0.0.123

package/openapi.yaml

@@ -547,6 +547,296 @@ paths:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
 
+  /v1/runs/{taskId}/compact:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+    post:
+      tags: [runs]
+      operationId: runsCompact
+      x-status: live             # core 1.293 compact(opts); manual-compaction control leg.
+      summary: Request a manual compaction of a LIVE run (fires at the next safe turn boundary).
+      description: >
+        Manual compaction control. FIRE-AND-FORGET 202 — `compact()` resolves only once processed at the next
+        SAFE turn boundary (possibly a whole in-flight turn away), so the ack is immediate and the outcome
+        rides the run's OWN stream: a `compacted{trigger:"manual"}` event IF anything was summarized; the
+        other outcomes (failed/mooted/noop/blocked/disabled) emit NO event (a spinner must time out, not
+        block). `instructions` = the shell's targeted-summary directive, capped at 2048 CODE POINTS (the
+        engine's own cap — over-cap is a fail-loud 400 here, never a silently truncated 202). LIVE-only and
+        replica-local (`steerableRuns` handle): a run active on another replica or terminal → 409
+        `compact.not_running`. Owner-gated (operator may compact any tenant's run); burns model budget —
+        rate/quota/lease gates apply.
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                instructions: { type: string, minLength: 1, description: 'Targeted compaction directive; ≤2048 code points (engine cap, enforced fail-loud).' }
+      responses:
+        '202':
+          description: Accepted — compaction runs at the next turn boundary; watch the run stream for `compacted{trigger:"manual"}`.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [taskId, status, delivery]
+                properties:
+                  taskId: { type: string }
+                  status: { type: string }
+                  delivery: { type: string, enum: [accepted] }
+                  note: { type: string }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409':
+          description: 'errorCode "compact.not_running" — run is terminal, or active on another replica (manual compact is replica-local).'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/runs/{taskId}/detach:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+    post:
+      tags: [runs]
+      operationId: runsDetach
+      x-status: live             # core 1.207 design/116 (CC mid-flight ctrl+b) sync-leg detach verb.
+      summary: Move a RUNNING tool call of this run to the background (CC ctrl+b).
+      description: >
+        design/116 — `TaskStream.detach(toolCallId)`. Fire-and-forget by CONTRACT and race-safe core-side: a
+        request landing before the tool reads its signal still detaches; after it finished = no-op; unknown
+        toolCallId = no-op (fail-safe — but note the ≤256-char cap is load-bearing: an unknown id still
+        allocates a registry entry for the run's lifetime). Only a detach-capable env honors it
+        (`backgroundCapabilities.supportsDetach`). The outcome surfaces on the run's OWN stream: the
+        early-settled `tool_end` with the `detached:true` structured card, then the `b*` task notification.
+        LIVE-only + replica-local (like compact) → 409 `detach.not_running` otherwise. Owner-gated; mutating
+        but runs no model (rate-limited only, no quota gate — parity with cancel).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [toolCallId]
+              properties:
+                toolCallId: { type: string, minLength: 1, maxLength: 256 }
+      responses:
+        '202':
+          description: Requested — honest about carrying no confirmation (the run stream carries the outcome).
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [taskId, toolCallId, delivery]
+                properties:
+                  taskId: { type: string }
+                  toolCallId: { type: string }
+                  delivery: { type: string, enum: [requested] }
+                  note: { type: string }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409':
+          description: 'errorCode "detach.not_running" — run is terminal, or active on another replica.'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/runs/{taskId}/subagents/{target}/output:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+      - name: target
+        in: path
+        required: true
+        schema: { type: string }
+        description: 'Background-agent handle (`a*` short form) under this parent run.'
+    get:
+      tags: [runs]
+      operationId: runsSubagentOutput
+      x-status: live             # [1488]③(b) background child read face (announced background_agent-ONLY contract, byte-stable).
+      summary: Read a BACKGROUND child's final report / current status (non-blocking).
+      description: >
+        [1488]③(b) — the background child read face. The fleet viewer gets `bg_notification` summaries only;
+        the child's FINAL assistant body lives in the core TaskRegistry (what the TaskOutput tool reads) and
+        is served here. Auth = the runs-face read pattern (verified principal → owner via the parent run row →
+        honest 404, no existence oracle); registry access is derived from the run row, NEVER caller-supplied.
+        Replica-local (in-process registry, like steer). Non-blocking: a still-running child returns its
+        current status honestly, no long-poll. This face is the announced `background_agent`-ONLY contract —
+        the generic task-handle verbs live under `/v1/runs/{taskId}/tasks/{target}/…`.
+      responses:
+        '200':
+          description: 'The registry projection. `content` = the child''s final assistant body (UNTRUSTED model output).'
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [taskId, target]
+                properties:
+                  taskId: { type: string }
+                  target: { type: string }
+                  content: { type: string }
+                  output: { type: object, description: 'Registry details projection (status/kind/…), passed through verbatim.' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/runs/{taskId}/subagents/{target}/resume:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+      - name: target
+        in: path
+        required: true
+        schema: { type: string }
+        description: 'The delegating tool call''s id (`parentToolCallId`) or the subagent''s agentName (ambiguous → 409).'
+    post:
+      tags: [runs]
+      operationId: runsResumeSubagent
+      x-status: live             # design/122 ③ (CC dfe parity): revive a settled child on its retained session.
+      summary: REVIVE a SETTLED subagent with a new prompt (async, on its retained session).
+      description: >
+        design/122 — CC "resume the agent" parity. Always async: the revived child runs in the background on
+        its RETAINED session (requires the parent run to have set `retainSubagentSessions`); completion is
+        announced via the deployment notify sink. Resume is only legal AFTER settle (handles live until leg
+        end). Owner-gated via the parent run row; content is fenced (`redactSteerIn`); the child's session id
+        is a continuation capability and never appears in any response. BILLABLE (starts model work) —
+        rate/quota/lease gates apply.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [content]
+              properties:
+                content: { type: string, description: 'The revival prompt (untrusted DATA; fenced server-side).' }
+      responses:
+        '200':
+          description: 'Revived. Body `{ taskId, target, status, delivery, marker, note }`.'
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409':
+          description: 'core''s typed rejections verbatim as `errorCode`: resume.still_running / resume.retain_off / resume.evicted / resume.cap / resume.session_not_found (design/122 D2).'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/runs/{taskId}/subagents/{target}/stream:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+      - name: target
+        in: path
+        required: true
+        schema: { type: string }
+        description: 'Background-agent handle (`a*` short form) under this parent run.'
+    get:
+      tags: [runs]
+      operationId: runsSubagentStream
+      x-status: live             # S2 [1520] per-agent live tail (core 1.370 bgAgentId).
+      summary: Per-agent LIVE TAIL (SSE) — content frames from connect time onward.
+      description: >
+        S2 — the "tail" half of replay+tail (replay/final report = the `/output` face). SSE frames: first an
+        `event: meta` frame (`{version, runId, target, status, seq?, live: "replica-local", replayFace}`),
+        then `event: forward` frames (text/reasoning deltas, tool_start/end, task_progress — same builder
+        discipline as the sync main stream's forward branch) and `event: heartbeat` keepalives (real frames,
+        not comment lines). Frames are produced only on the replica hosting the parent run ⇒ live frames are
+        replica-local (the meta declares it; a row running on another instance heartbeats only, never
+        fabricates). A terminal child ends the stream right after the meta (the replay face is the read
+        surface). Gates are byte-identical to the `/output` face (principal → owner → session, fail-closed
+        404, no oracle).
+      responses:
+        '200':
+          description: 'SSE stream (`text/event-stream`): meta → forward*/heartbeat*.'
+          content:
+            text/event-stream:
+              schema: { type: string }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/runs/{taskId}/tasks/{target}/output:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+      - name: target
+        in: path
+        required: true
+        schema: { type: string }
+        description: 'EXACT task handle only (`b*` background bash, monitor, background agent) — agent-name / legacy-shellId resolution is deliberately not on the wire (fail-closed 404).'
+    get:
+      tags: [runs]
+      operationId: runsTaskOutput
+      x-status: live             # [1499] CC TaskOutput human-side counterpart (generic task-handle verb family).
+      summary: Read a background task handle's output (CC TaskOutput human-side counterpart).
+      description: >
+        [1499] — the GENERIC task-handle read serving the full registry kind set (background_bash stdout,
+        monitor batches, background_agent final report). Whether a read consumes the output cursor depends on
+        the handle's shape — the top-level `cursorSemantics` key ("cursor" = new bytes per read | "full" =
+        re-readable) is minted server-side so consumers never parse content markers; absent on error/not_ready
+        shapes (no fake semantics). `workflow` handles are refused at the seam (journal face owns workflow
+        reads — a poll here would suppress the completion push). `?filter=` is NOT accepted (400): the wire
+        serves the clipped projection. Gates mirror the subagent output face (principal → owner → session).
+      responses:
+        '200':
+          description: 'Registry projection passed through verbatim; `content` is UNTRUSTED tool/model output.'
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [taskId, target]
+                properties:
+                  taskId: { type: string }
+                  target: { type: string }
+                  content: { type: string }
+                  output: { type: object }
+                  cursorSemantics: { type: string, enum: [cursor, full], description: 'G14: whether THIS read consumed the cursor. Absent on error/not_ready or unknown kinds.' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/runs/{taskId}/tasks/{target}/stop:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+      - name: target
+        in: path
+        required: true
+        schema: { type: string }
+        description: 'EXACT task handle only (see the output verb); `workflow` handles refused.'
+    post:
+      tags: [runs]
+      operationId: runsTaskStop
+      x-status: live             # [1499] CC TaskStop human-side counterpart.
+      summary: Stop a background task handle (CC TaskStop human-side counterpart).
+      description: >
+        [1499] — stop the handle's process. A stop whose kill did NOT land must not read as success: core
+        keeps the handle honest (status stays "running", error = the env failure code) and the wire surfaces
+        that as a 409 with a discriminated `errorCode` — stop.not_local (task attached to another instance) /
+        stop.park_arbiter_unreachable / stop.park_resume_won (a concurrent approval resume won the race) /
+        stop.parked (durably parked on a tool-approval — resolve the approval instead, nothing live to kill) /
+        stop.not_landed. Mutating but runs no model (rate-limited only, parity with detach). Gates mirror the
+        output verb.
+      responses:
+        '200':
+          description: 'Stopped — same projection shape as the output verb ({ taskId, target, content, output }).'
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409':
+          description: 'Stop did not land — discriminated `errorCode` (stop.not_local / stop.park_arbiter_unreachable / stop.park_resume_won / stop.parked / stop.not_landed); body includes the current projection.'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
   /v1/sessions:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
@@ -2468,13 +2758,285 @@ paths:
                   error: { type: string }
                   missing: { type: array, items: { type: string } }
 
+  /v1/approvals/{approvalId}:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: approvalId
+        required: true
+        schema: { type: string }
+    get:
+      tags: [approvals]
+      operationId: approvalsGet
+      x-status: live             # D-lane approval-store single-row read (SDK approvals.get, with an inbox fallback client-side).
+      summary: Read ONE pending approval row by id (owner-gated — the row carries full tool-call args).
+      description: >
+        The approval row carries the FULL tool-call args (commands/paths/contents of a high-risk op), so the
+        by-id read enforces the same tenant boundary as the list: operators read across tenants; everyone else
+        reads ONLY their own scope (the guard fires at the SQL layer — no cross-tenant args even if an id
+        leaks). Non-owner → 404 (never 403, no existence oracle). Present only on deployments with the
+        D-lane approval store; the checkpoint-lane decide verb is `/v1/approvals/{sessionId}/decide`.
+      responses:
+        '200':
+          description: The approval row (full args projection).
+          content:
+            application/json:
+              schema: { type: object, additionalProperties: true }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+
+  /v1/memory/export:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [memory]
+      operationId: memoryExport
+      x-status: live             # 142-S5 §1.4 per-scope export (DB memory plane only).
+      summary: Per-scope memory export (transport-neutral full-entry array).
+      description: >
+        142-S5 §1.4 — export one scope's memory entries. The owner gate is the tenant boundary: a verified
+        principal may export exactly its OWN user disk (`scope === user:<principal>`, core's mint) or be an
+        explicit operator (ops/migration face); anything else → 404, never 403 (zero existence oracle).
+        `org:*`/`userproj:*` keys are operator-only until the S3 registry; repo-backed `proj:*` keys never
+        live in this DB (git is their authority — an owner asking gets an honestly empty set). 501 on a
+        file memory backend (present ONLY with MEMORY_ENGINE_BACKEND=pg|tidb).
+      parameters:
+        - in: query
+          name: scope
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: The export bundle.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [scope, exportedAt, entries]
+                properties:
+                  scope: { type: string }
+                  exportedAt: { type: string, format: date-time }
+                  entries: { type: array, items: { type: object, additionalProperties: true } }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/memory/sync/{scope}:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: scope
+        required: true
+        schema: { type: string }
+        description: 'Scope key, percent-encoded (keys carry `:`/`@`/`/`). Malformed escape → typed 400.'
+    post:
+      tags: [memory]
+      operationId: memorySync
+      x-status: live             # 142-S2.5 central-side sync face (DB memory plane only).
+      summary: Central-side memory sync (reconcile plan rides with the data).
+      description: >
+        142-S2.5 — the central authority half of two-way memory sync (the TOC/file side is the client). Gate
+        order mirrors the export face verbatim: auth (401) → backend posture (501 on the file shape — a
+        single-user file plane IS the TOC side, there is no central half to serve) → owner gate (404
+        zero-oracle: own user disk or explicit operator) → shape validation (422 typed
+        `memory_sync_invalid_body`). A 500 after partial application is an HONEST signal: replaying with the
+        same baseRevs is idempotent self-healing (identical revs no-op throughout) — never silently swallowed.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { type: object, additionalProperties: true, description: 'The sync request (peer/baseRevs/patches — core reconcile contract).' }
+      responses:
+        '200':
+          description: 'The sync outcome (core reconcile/nextSyncBaseline projection).'
+          content:
+            application/json:
+              schema: { type: object, additionalProperties: true }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '422': { description: 'errorCode "memory_sync_invalid_body" — the request failed the typed shape gate.' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/outcomes:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [outcomes]
+      operationId: outcomesSummary
+      x-status: live             # design/73 §7 outcome-ledger read-only face.
+      summary: Outcome-ledger aggregation read (mechanical signals only).
+      description: >
+        design/73 §7 — read-only aggregation over the outcome ledger (mechanical run signals; never a
+        training view). Aggregations are per task-signature (×model) and would leak cross-tenant task/perf
+        shape, so on a multi-tenant worker (REQUIRE_PRINCIPAL) the view is OPERATOR-ONLY (403 otherwise);
+        single-user turnkey is open (the sole user IS the operator). `?signature=` filters to one aggregation
+        key; `?includeAborted=true` adds infra-aborted rows (infra-health view). 501 on a File-sink worker
+        (read the JSONL dataset directly).
+      parameters:
+        - in: query
+          name: signature
+          required: false
+          schema: { type: string }
+        - in: query
+          name: includeAborted
+          required: false
+          schema: { type: boolean }
+      responses:
+        '200':
+          description: Aggregation rows.
+          content:
+            application/json:
+              schema: { type: object, additionalProperties: true }
+        '403': { description: 'Multi-tenant worker: outcomes view is operator-only.' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/sendfile-links:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [sendfile]
+      operationId: sendfileLinksList
+      x-status: live             # SendUserFile ledger thin read face (multi-tenant governance).
+      summary: List issued SendUserFile links (metadata + key only — no URLs by design).
+      description: >
+        The SendUserFile ledger's read face: which links has this tenant issued. Owner scope mirrors GET
+        /v1/sessions — a principal caller is PINNED to its own scope (?scope= ignored); a fleet-wide (service
+        token) caller may pass `?scope=` (ops view; absent = the `_` single-user sentinel). Keyset pagination:
+        `?before=<uuidv7 id>` (time-ordered, newest first), `?limit=` 1..100 (default 50) — both strictly
+        validated (malformed → 400, never a silent default). Returns METADATA + object key only, NO url: the
+        ledger stores no URLs by design (public-track URLs are reconstructible from bucket+key; presigned ones
+        would be expired — re-issuance is a future verb, not this list). 501 without a store backend + the
+        SendUserFile issuer.
+      parameters:
+        - in: query
+          name: before
+          required: false
+          schema: { type: string }
+        - in: query
+          name: limit
+          required: false
+          schema: { type: integer, minimum: 1, maximum: 100 }
+        - in: query
+          name: scope
+          required: false
+          schema: { type: string }
+          description: Fleet-wide callers only; ignored for principal callers (pinned).
+      responses:
+        '200':
+          description: 'One page: `{ links: [{id, filename, size, ttlSec, track, bucket, key, createdAt}], nextBefore? }`.'
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [links]
+                properties:
+                  links: { type: array, items: { type: object, additionalProperties: true } }
+                  nextBefore: { type: string }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/workflows/{workflowRunId}/journal:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: workflowRunId
+        required: true
+        schema: { type: string }
+    get:
+      tags: [workflows]
+      operationId: workflowsJournal
+      x-status: live             # [1402] per-agent journal read face (cloud/local isomorphic — three store backends, one contract).
+      summary: Per-agent journal of a workflow run (bounded + redacted projection).
+      description: >
+        [1402] — the workflow's per-agent journal (what each agent() call returned), cloud/local isomorphic.
+        Owner-gated via the run's scope; session-accept phase applies. Projection is bounded + redacted
+        (`result` is LLM output — injection-surface discipline, first-line/300-char clips), stable ordinal
+        order. Hard bounds: `?limit=` default 20 cap 50, `?offset=` cursor; SQL stores page at the DB
+        (per-row 64KiB gate); file/in-memory stores load-then-project (single-machine shape, recorded
+        trade-off). 501 without the journal store (SELF_ORCHESTRATION_ENABLED + a store backend).
+      parameters:
+        - in: query
+          name: limit
+          required: false
+          schema: { type: integer, minimum: 1, maximum: 50 }
+        - in: query
+          name: offset
+          required: false
+          schema: { type: integer, minimum: 0 }
+      responses:
+        '200':
+          description: 'One page: `{ runId, entries: [{callKey, ordinal, status, …}], nextOffset? }`.'
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [runId, entries]
+                properties:
+                  runId: { type: string }
+                  entries: { type: array, items: { type: object, additionalProperties: true } }
+                  nextOffset: { type: integer }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/workflows/{workflowRunId}/agents/{label}/steer:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: workflowRunId
+        required: true
+        schema: { type: string }
+      - in: path
+        name: label
+        required: true
+        schema: { type: string }
+        description: The agent's label inside the workflow (the display label the script assigned).
+    post:
+      tags: [workflows]
+      operationId: workflowsSteerAgent
+      x-status: live             # SVC-5 (design/97 CORE-5 #6) mid-flight workflow-agent steer.
+      summary: Steer ONE running agent inside a workflow (replica-local live handle).
+      description: >
+        SVC-5 — unlike the RUN steer (a whole task run), this targets ONE running agent inside a workflow,
+        addressed by runId + label. Delivery is replica-local (an in-memory bridge to the running TaskStream,
+        like `steerableRuns`): live on THIS replica → injected, 200; running on another replica or
+        settled/unknown → 409 `steering.not_running` (honest, never a silent drop). Content is fenced
+        (untrusted DATA). Burns model budget — rate/quota/lease gates apply.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [content]
+              properties:
+                content: { type: string, minLength: 1 }
+      responses:
+        '200':
+          description: 'Injected. Body `{ runId, label, status: "running", delivery: "applied", marker }`.'
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409':
+          description: 'errorCode "steering.not_running" — agent settled/unknown, or live on another replica.'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
   /metrics/summary:
     get:
       tags: [metrics]
       operationId: metricsSummary
       x-status: draft            # ops surface; uses a metricsToken (NOT a principal). Shape loose.
+      x-sdk: none                # DELIBERATELY not in @sema-agent/sdk (2026-07-27 定性): ops/observability face, credential = metricsToken not a principal; README walks curl. Revocable — delete this key + the gate exemption to bring it in.
       summary: Worker health/cost summary (ops).
-      description: Uses `metricsToken` (operator), not `x-agent-principal`. Shape is loose/ops-defined.
+      description: >
+        Uses `metricsToken` (operator), not `x-agent-principal`. Shape is loose/ops-defined. Deliberately
+        NOT wrapped by the SDK (see the `x-sdk` key) — ops tooling reads it with curl.
       security:
         - metricsToken: []
       responses:

package/package.json

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