@smithers-orchestrator/gateway 0.22.0 → 0.24.0

package/openapi.yaml

@@ -867,8 +867,7 @@ paths:
                           - InvalidRequest
                           - Unauthorized
                           - Forbidden
-                          - RunNotFound
-                          - Busy
+                          - RUN_NOT_ACTIVE
                           - Internal
                       message:
                         type: string
@@ -923,8 +922,7 @@ paths:
                           - InvalidRequest
                           - Unauthorized
                           - Forbidden
-                          - RunNotFound
-                          - Busy
+                          - RUN_NOT_ACTIVE
                           - Internal
                       message:
                         type: string
@@ -979,64 +977,7 @@ paths:
                           - InvalidRequest
                           - Unauthorized
                           - Forbidden
-                          - RunNotFound
-                          - Busy
-                          - Internal
-                      message:
-                        type: string
-                      requiredScope:
-                        type: string
-                        enum:
-                          - run:read
-                          - run:write
-                          - run:admin
-                          - approval:submit
-                          - signal:submit
-                          - cron:read
-                          - cron:write
-                          - observability:read
-                      refresh:
-                        type: string
-        404:
-          description: "The run does not exist."
-          content:
-            application/json:
-              schema:
-                type: object
-                required:
-                  - type
-                  - id
-                  - ok
-                  - apiVersion
-                  - error
-                additionalProperties: false
-                properties:
-                  type:
-                    const: res
-                  id:
-                    type: string
-                  ok:
-                    const: false
-                  apiVersion:
-                    const: v1
-                  error:
-                    type: object
-                    required:
-                      - version
-                      - code
-                      - message
-                    additionalProperties: true
-                    properties:
-                      version:
-                        const: v1
-                      code:
-                        type: string
-                        enum:
-                          - InvalidRequest
-                          - Unauthorized
-                          - Forbidden
-                          - RunNotFound
-                          - Busy
+                          - RUN_NOT_ACTIVE
                           - Internal
                       message:
                         type: string
@@ -1054,7 +995,7 @@ paths:
                       refresh:
                         type: string
         409:
-          description: "Another conflicting mutation is in progress."
+          description: "The run is not currently active and cannot be cancelled."
           content:
             application/json:
               schema:
@@ -1091,8 +1032,7 @@ paths:
                           - InvalidRequest
                           - Unauthorized
                           - Forbidden
-                          - RunNotFound
-                          - Busy
+                          - RUN_NOT_ACTIVE
                           - Internal
                       message:
                         type: string
@@ -1147,8 +1087,7 @@ paths:
                           - InvalidRequest
                           - Unauthorized
                           - Forbidden
-                          - RunNotFound
-                          - Busy
+                          - RUN_NOT_ACTIVE
                           - Internal
                       message:
                         type: string
@@ -2284,7 +2223,7 @@ paths:
                   iteration: 0
                   approved: true
         400:
-          description: "The request shape is invalid."
+          description: "The request input failed validation."
           content:
             application/json:
               schema:
@@ -2319,10 +2258,11 @@ paths:
                         type: string
                         enum:
                           - InvalidRequest
+                          - InvalidInput
                           - Unauthorized
                           - Forbidden
                           - RunNotFound
-                          - NodeNotFound
+                          - AlreadyDecided
                           - Internal
                       message:
                         type: string
@@ -2375,10 +2315,11 @@ paths:
                         type: string
                         enum:
                           - InvalidRequest
+                          - InvalidInput
                           - Unauthorized
                           - Forbidden
                           - RunNotFound
-                          - NodeNotFound
+                          - AlreadyDecided
                           - Internal
                       message:
                         type: string
@@ -2431,10 +2372,11 @@ paths:
                         type: string
                         enum:
                           - InvalidRequest
+                          - InvalidInput
                           - Unauthorized
                           - Forbidden
                           - RunNotFound
-                          - NodeNotFound
+                          - AlreadyDecided
                           - Internal
                       message:
                         type: string
@@ -2452,7 +2394,7 @@ paths:
                       refresh:
                         type: string
         404:
-          description: "The node does not exist on the run."
+          description: "The run does not exist."
           content:
             application/json:
               schema:
@@ -2487,10 +2429,68 @@ paths:
                         type: string
                         enum:
                           - InvalidRequest
+                          - InvalidInput
                           - Unauthorized
                           - Forbidden
                           - RunNotFound
-                          - NodeNotFound
+                          - AlreadyDecided
+                          - Internal
+                      message:
+                        type: string
+                      requiredScope:
+                        type: string
+                        enum:
+                          - run:read
+                          - run:write
+                          - run:admin
+                          - approval:submit
+                          - signal:submit
+                          - cron:read
+                          - cron:write
+                          - observability:read
+                      refresh:
+                        type: string
+        409:
+          description: "The approval decision has already been submitted."
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - type
+                  - id
+                  - ok
+                  - apiVersion
+                  - error
+                additionalProperties: false
+                properties:
+                  type:
+                    const: res
+                  id:
+                    type: string
+                  ok:
+                    const: false
+                  apiVersion:
+                    const: v1
+                  error:
+                    type: object
+                    required:
+                      - version
+                      - code
+                      - message
+                    additionalProperties: true
+                    properties:
+                      version:
+                        const: v1
+                      code:
+                        type: string
+                        enum:
+                          - InvalidRequest
+                          - InvalidInput
+                          - Unauthorized
+                          - Forbidden
+                          - RunNotFound
+                          - AlreadyDecided
                           - Internal
                       message:
                         type: string
@@ -2543,10 +2543,11 @@ paths:
                         type: string
                         enum:
                           - InvalidRequest
+                          - InvalidInput
                           - Unauthorized
                           - Forbidden
                           - RunNotFound
-                          - NodeNotFound
+                          - AlreadyDecided
                           - Internal
                       message:
                         type: string
@@ -2963,7 +2964,7 @@ paths:
     post:
       operationId: getRun
       summary: "Get Run"
-      description: "Fetch the current RunStateView for one run."
+      description: "Fetch one run record with node-state counts and optional derived runState."
       tags:
         - "Gateway RPC"
       security:
@@ -3036,9 +3037,69 @@ paths:
                     const: v1
                   payload:
                     type: object
-                    description: RunStateView.
-                    properties: {}
-                    required: []
+                    description: "Current run record, including node-state counts and optional derived runState."
+                    properties:
+                      runId:
+                        type: string
+                        description: "Stable run identifier."
+                      workflowKey:
+                        type: string
+                        description: "Registered Gateway workflow key."
+                      status:
+                        type: string
+                        description: "Persisted run status."
+                      createdAtMs:
+                        type: integer
+                        minimum: 0
+                        description: "Unix epoch milliseconds."
+                      startedAtMs:
+                        type: integer
+                        minimum: 0
+                        description: "Unix epoch milliseconds."
+                        nullable: true
+                      finishedAtMs:
+                        type: integer
+                        minimum: 0
+                        description: "Unix epoch milliseconds."
+                        nullable: true
+                      summary:
+                        type: object
+                        description: "Counts keyed by persisted node state."
+                        properties: {}
+                        required: []
+                        additionalProperties: true
+                      runState:
+                        type: object
+                        description: "Derived RunStateView for the run."
+                        properties:
+                          runId:
+                            type: string
+                            description: "Stable run identifier."
+                          state:
+                            type: string
+                            description: "Derived lifecycle state."
+                          computedAt:
+                            type: string
+                            description: "ISO timestamp for when the view was computed."
+                          blocked:
+                            type: object
+                            description: "Optional blocked-run reason."
+                            properties: {}
+                            required: []
+                            additionalProperties: true
+                          unhealthy:
+                            type: object
+                            description: "Optional unhealthy-run reason."
+                            properties: {}
+                            required: []
+                            additionalProperties: true
+                        required:
+                          - runId
+                          - state
+                          - computedAt
+                        additionalProperties: true
+                    required:
+                      - runId
                     additionalProperties: true
               example:
                 type: res
@@ -3049,6 +3110,12 @@ paths:
                   runId: run_01
                   status: finished
                   workflowKey: deploy
+                  summary:
+                    finished: 3
+                  runState:
+                    runId: run_01
+                    state: succeeded
+                    computedAt: 2026-01-01T00:00:00.000Z
         400:
           description: "The request shape is invalid."
           content:
@@ -4755,6 +4822,10 @@ paths:
                       type: integer
                       minimum: 0
                       description: "Replay events with sequence numbers greater than this value."
+                    fromSeq:
+                      type: integer
+                      minimum: 0
+                      description: "Legacy alias for afterSeq on DevTools streams."
                   required:
                     - runId
                   additionalProperties: false
@@ -4803,6 +4874,10 @@ paths:
                       runId:
                         type: string
                         description: "Stable run identifier."
+                      fromSeq:
+                        type:
+                          - integer
+                          - "null"
                       afterSeq:
                         type:
                           - integer
@@ -4810,6 +4885,8 @@ paths:
                     required:
                       - streamId
                       - runId
+                      - fromSeq
+                      - afterSeq
                     additionalProperties: false
               example:
                 type: res
@@ -4819,6 +4896,7 @@ paths:
                 payload:
                   streamId: stream_01
                   runId: run_01
+                  fromSeq: 10
                   afterSeq: 10
         400:
           description: "The requested stream sequence is in the future."
@@ -7489,6 +7567,7 @@ components:
         - Unauthorized
         - Forbidden
         - RunNotFound
+        - RUN_NOT_ACTIVE
         - CronNotFound
         - NodeNotFound
         - IterationNotFound
@@ -7496,6 +7575,7 @@ components:
         - FrameOutOfRange
         - SeqOutOfRange
         - Busy
+        - AlreadyDecided
         - RateLimited
         - PayloadTooLarge
         - BackpressureDisconnect

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/gateway",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Stable Smithers Gateway RPC contracts, auth scopes, and deployment metadata",
   "type": "module",
   "sideEffects": false,

package/src/rpc/index.ts

@@ -30,6 +30,7 @@ export type GatewayRpcErrorCode =
   | "Unauthorized"
   | "Forbidden"
   | "RunNotFound"
+  | "RUN_NOT_ACTIVE"
   | "CronNotFound"
   | "NodeNotFound"
   | "IterationNotFound"
@@ -37,6 +38,7 @@ export type GatewayRpcErrorCode =
   | "FrameOutOfRange"
   | "SeqOutOfRange"
   | "Busy"
+  | "AlreadyDecided"
   | "RateLimited"
   | "PayloadTooLarge"
   | "BackpressureDisconnect"
@@ -232,6 +234,7 @@ export type StreamRunEventsResponse = {
 export type StreamDevToolsRequest = {
   runId: string;
   afterSeq?: number;
+  fromSeq?: number;
 };
 
 export type NodeRequest = {
@@ -310,6 +313,7 @@ const workflow = stringSchema("Registered Gateway workflow key.");
 const nodeId = stringSchema("Workflow node id.");
 const iteration = integerSchema("Node iteration.", 0);
 const afterSeq = integerSchema("Replay events with sequence numbers greater than this value.", 0);
+const fromSeq = integerSchema("Legacy alias for afterSeq on DevTools streams.", 0);
 const runSummary = objectSchema(
   {
     runId,
@@ -321,6 +325,33 @@ const runSummary = objectSchema(
   "Run summary view.",
   true,
 );
+const runStateView = objectSchema(
+  {
+    runId,
+    state: stringSchema("Derived lifecycle state."),
+    computedAt: stringSchema("ISO timestamp for when the view was computed."),
+    blocked: objectSchema({}, [], "Optional blocked-run reason.", true),
+    unhealthy: objectSchema({}, [], "Optional unhealthy-run reason.", true),
+  },
+  ["runId", "state", "computedAt"],
+  "Derived RunStateView for the run.",
+  true,
+);
+const runRecord = objectSchema(
+  {
+    runId,
+    workflowKey: workflow,
+    status: stringSchema("Persisted run status."),
+    createdAtMs: integerSchema("Unix epoch milliseconds.", 0),
+    startedAtMs: { ...integerSchema("Unix epoch milliseconds.", 0), nullable: true },
+    finishedAtMs: { ...integerSchema("Unix epoch milliseconds.", 0), nullable: true },
+    summary: objectSchema({}, [], "Counts keyed by persisted node state.", true),
+    runState: runStateView,
+  },
+  ["runId"],
+  "Current run record, including node-state counts and optional derived runState.",
+  true,
+);
 
 export const GATEWAY_RPC_ERRORS: Record<GatewayRpcErrorCode, GatewayRpcErrorDefinition> = {
   InvalidRequest: { version: SMITHERS_API_VERSION, code: "InvalidRequest", httpStatus: 400, description: "The request shape is invalid." },
@@ -328,6 +359,7 @@ export const GATEWAY_RPC_ERRORS: Record<GatewayRpcErrorCode, GatewayRpcErrorDefi
   Unauthorized: { version: SMITHERS_API_VERSION, code: "Unauthorized", httpStatus: 401, description: "Authentication failed or the token expired." },
   Forbidden: { version: SMITHERS_API_VERSION, code: "Forbidden", httpStatus: 403, description: "The token is missing the required scope." },
   RunNotFound: { version: SMITHERS_API_VERSION, code: "RunNotFound", httpStatus: 404, description: "The run does not exist." },
+  RUN_NOT_ACTIVE: { version: SMITHERS_API_VERSION, code: "RUN_NOT_ACTIVE", httpStatus: 409, description: "The run is not currently active and cannot be cancelled." },
   CronNotFound: { version: SMITHERS_API_VERSION, code: "CronNotFound", httpStatus: 404, description: "The cron schedule does not exist." },
   NodeNotFound: { version: SMITHERS_API_VERSION, code: "NodeNotFound", httpStatus: 404, description: "The node does not exist on the run." },
   IterationNotFound: { version: SMITHERS_API_VERSION, code: "IterationNotFound", httpStatus: 404, description: "The requested node iteration does not exist." },
@@ -335,6 +367,7 @@ export const GATEWAY_RPC_ERRORS: Record<GatewayRpcErrorCode, GatewayRpcErrorDefi
   FrameOutOfRange: { version: SMITHERS_API_VERSION, code: "FrameOutOfRange", httpStatus: 400, description: "The requested frame is outside the available range." },
   SeqOutOfRange: { version: SMITHERS_API_VERSION, code: "SeqOutOfRange", httpStatus: 400, description: "The requested stream sequence is in the future." },
   Busy: { version: SMITHERS_API_VERSION, code: "Busy", httpStatus: 409, description: "Another conflicting mutation is in progress." },
+  AlreadyDecided: { version: SMITHERS_API_VERSION, code: "AlreadyDecided", httpStatus: 409, description: "The approval decision has already been submitted." },
   RateLimited: { version: SMITHERS_API_VERSION, code: "RateLimited", httpStatus: 429, description: "The caller exceeded a configured quota." },
   PayloadTooLarge: { version: SMITHERS_API_VERSION, code: "PayloadTooLarge", httpStatus: 413, description: "The response exceeds the configured payload limit." },
   BackpressureDisconnect: { version: SMITHERS_API_VERSION, code: "BackpressureDisconnect", httpStatus: 429, description: "A stream subscriber exceeded the bounded outbound queue." },
@@ -407,7 +440,7 @@ export const GATEWAY_RPC_DEFINITIONS: readonly GatewayRpcDefinition[] = [
     requiredScope: "run:write",
     requestSchema: objectSchema({ runId }, ["runId"]),
     responseSchema: objectSchema({ runId, status: { type: "string", enum: ["cancelling"] } }, ["runId", "status"]),
-    errors: ["InvalidRequest", "Unauthorized", "Forbidden", "RunNotFound", "Busy", "Internal"],
+    errors: ["InvalidRequest", "Unauthorized", "Forbidden", "RUN_NOT_ACTIVE", "Internal"],
     exampleRequest: { runId: "run_01" },
     exampleResponse: { runId: "run_01", status: "cancelling" },
   },
@@ -458,7 +491,7 @@ export const GATEWAY_RPC_DEFINITIONS: readonly GatewayRpcDefinition[] = [
       }, ["approved"]),
     }, ["runId", "nodeId", "decision"]),
     responseSchema: objectSchema({ runId, nodeId, iteration, approved: booleanSchema("Whether the approval was granted.") }, ["runId", "nodeId", "iteration", "approved"]),
-    errors: ["InvalidRequest", "Unauthorized", "Forbidden", "RunNotFound", "NodeNotFound", "Internal"],
+    errors: ["InvalidRequest", "InvalidInput", "Unauthorized", "Forbidden", "RunNotFound", "AlreadyDecided", "Internal"],
     exampleRequest: { runId: "run_01", nodeId: "approve", decision: { approved: true, note: "ship it" } },
     exampleResponse: { runId: "run_01", nodeId: "approve", iteration: 0, approved: true },
   },
@@ -480,15 +513,21 @@ export const GATEWAY_RPC_DEFINITIONS: readonly GatewayRpcDefinition[] = [
     version: SMITHERS_API_VERSION,
     method: "getRun",
     title: "Get Run",
-    description: "Fetch the current RunStateView for one run.",
+    description: "Fetch one run record with node-state counts and optional derived runState.",
     maturity: "stable",
     transport: "http+websocket",
     requiredScope: "run:read",
     requestSchema: objectSchema({ runId }, ["runId"]),
-    responseSchema: objectSchema({}, [], "RunStateView.", true),
+    responseSchema: runRecord,
     errors: ["InvalidRequest", "Unauthorized", "Forbidden", "RunNotFound", "Internal"],
     exampleRequest: { runId: "run_01" },
-    exampleResponse: { runId: "run_01", status: "finished", workflowKey: "deploy" },
+    exampleResponse: {
+      runId: "run_01",
+      status: "finished",
+      workflowKey: "deploy",
+      summary: { finished: 3 },
+      runState: { runId: "run_01", state: "succeeded", computedAt: "2026-01-01T00:00:00.000Z" },
+    },
   },
   {
     version: SMITHERS_API_VERSION,
@@ -570,11 +609,16 @@ export const GATEWAY_RPC_DEFINITIONS: readonly GatewayRpcDefinition[] = [
     maturity: "stable",
     transport: "websocket",
     requiredScope: "observability:read",
-    requestSchema: objectSchema({ runId, afterSeq }, ["runId"]),
-    responseSchema: objectSchema({ streamId: stringSchema("Stream id."), runId, afterSeq: { type: ["integer", "null"] } }, ["streamId", "runId"]),
+    requestSchema: objectSchema({ runId, afterSeq, fromSeq }, ["runId"]),
+    responseSchema: objectSchema({
+      streamId: stringSchema("Stream id."),
+      runId,
+      fromSeq: { type: ["integer", "null"] },
+      afterSeq: { type: ["integer", "null"] },
+    }, ["streamId", "runId", "fromSeq", "afterSeq"]),
     errors: ["InvalidRequest", "Unauthorized", "Forbidden", "RunNotFound", "SeqOutOfRange", "BackpressureDisconnect", "Internal"],
     exampleRequest: { runId: "run_01", afterSeq: 10 },
-    exampleResponse: { streamId: "stream_01", runId: "run_01", afterSeq: 10 },
+    exampleResponse: { streamId: "stream_01", runId: "run_01", fromSeq: 10, afterSeq: 10 },
   },
   {
     version: SMITHERS_API_VERSION,