Publish Reactor POST /tokens and keep command paths off the HTTP document

.changeset/reactor-tokens-realtime.md

@@ -0,0 +1,4 @@
+---
+---
+
+Reactor's generation OpenAPI publishes POST /tokens and keeps command schemas off the HTTP paths (#643). No package behaviour changes.

openapi.json

@@ -546,7 +546,7 @@
       "get": {
         "operationId": "getProviderOpenApi",
         "summary": "Generation-only OpenAPI document for one provider",
-        "description": "Assembled from classified endpoints plus the provider connect profile (servers, auth, required headers). Not a raw upstream-spec mirror. FAL (model-grained, queue) is one document: POST /{endpoint_id} and GET /{endpoint_id}/requests/{request_id}. endpoint_id is the model raw id (x-modelschemas-encode raw: do not percent-encode slashes). With no selector the bodies are untyped; ?activity= narrows the enum and inlines each model's own body schema (x-modelschemas-model), up to 1024 models; ?model= is that one model's paths. Other model-grained providers (Reactor) keep one path per endpoint; bare or with ?activity=, each body is an input_/output_ component schema tagged x-modelschemas-model. A filter that matches no endpoint returns 400 spec_requires_selector; there is no cap on the number of paths in a provider-grained document. An unsynced provider returns 404 no_endpoints. ?model= pins the live model enum on provider-grained specs; it does not drop endpoints.",
+        "description": "Assembled from classified endpoints plus the provider connect profile (servers, auth, required headers). Not a raw upstream-spec mirror. FAL (model-grained, queue) is one document: POST /{endpoint_id} and GET /{endpoint_id}/requests/{request_id}. endpoint_id is the model raw id (x-modelschemas-encode raw: do not percent-encode slashes). With no selector the bodies are untyped; ?activity= narrows the enum and inlines each model's own body schema (x-modelschemas-model), up to 1024 models; ?model= is that one model's paths. Reactor publishes platform HTTP only (POST /tokens, Reactor-API-Key). Model commands stay component schemas tagged x-modelschemas-model and x-modelschemas-transport: realtime, not paths on the API host. A filter that matches no endpoint returns 400 spec_requires_selector; there is no cap on the number of paths in a provider-grained document. An unsynced provider returns 404 no_endpoints. ?model= pins the live model enum on provider-grained specs; it does not drop endpoints.",
         "parameters": [
           {
             "name": "provider",

packages/client/src/generated/sdk.gen.ts

@@ -228,7 +228,7 @@ export const getSchema = <ThrowOnError extends boolean = false>(
 /**
  * Generation-only OpenAPI document for one provider
  *
- * Assembled from classified endpoints plus the provider connect profile (servers, auth, required headers). Not a raw upstream-spec mirror. FAL (model-grained, queue) is one document: POST /{endpoint_id} and GET /{endpoint_id}/requests/{request_id}. endpoint_id is the model raw id (x-modelschemas-encode raw: do not percent-encode slashes). With no selector the bodies are untyped; ?activity= narrows the enum and inlines each model's own body schema (x-modelschemas-model), up to 1024 models; ?model= is that one model's paths. Other model-grained providers (Reactor) keep one path per endpoint; bare or with ?activity=, each body is an input_/output_ component schema tagged x-modelschemas-model. A filter that matches no endpoint returns 400 spec_requires_selector; there is no cap on the number of paths in a provider-grained document. An unsynced provider returns 404 no_endpoints. ?model= pins the live model enum on provider-grained specs; it does not drop endpoints.
+ * Assembled from classified endpoints plus the provider connect profile (servers, auth, required headers). Not a raw upstream-spec mirror. FAL (model-grained, queue) is one document: POST /{endpoint_id} and GET /{endpoint_id}/requests/{request_id}. endpoint_id is the model raw id (x-modelschemas-encode raw: do not percent-encode slashes). With no selector the bodies are untyped; ?activity= narrows the enum and inlines each model's own body schema (x-modelschemas-model), up to 1024 models; ?model= is that one model's paths. Reactor publishes platform HTTP only (POST /tokens, Reactor-API-Key). Model commands stay component schemas tagged x-modelschemas-model and x-modelschemas-transport: realtime, not paths on the API host. A filter that matches no endpoint returns 400 spec_requires_selector; there is no cap on the number of paths in a provider-grained document. An unsynced provider returns 404 no_endpoints. ?model= pins the live model enum on provider-grained specs; it does not drop endpoints.
  */
 export const getProviderOpenApi = <ThrowOnError extends boolean = false>(
   options: Options<GetProviderOpenApiData, ThrowOnError>,

skill/modelschemas/SKILL.md

@@ -159,8 +159,9 @@ spec syncs daily. Responses are JSON unless noted (`text/typescript`,
    parameter (x-modelschemas-encode: raw — do not percent-encode slashes).
    Bare, the bodies are untyped; ?activity= inlines each model's own body
    schema (up to 1024 models); ?model= is that one model's paths. Reactor
-   keeps one path per endpoint, each body an input_/output_ component
-   (x-modelschemas-model). A filter that matches none: 400
+   publishes POST /tokens only. Model commands are input_/output_
+   components tagged x-modelschemas-transport: realtime, not HTTP paths.
+   A filter that matches none: 400
    spec_requires_selector. HTTP only (no MCP tool).
 7. POST /v1/validate {"provider","endpointId","payload"} — check a payload.
 8. POST /v1/estimate {"provider","model","request"?,"usage"?} — {amount,

src/server/llms-txt.ts

@@ -62,8 +62,9 @@ spec syncs daily. Responses are JSON unless noted (\`text/typescript\`,
    parameter (x-modelschemas-encode: raw — do not percent-encode slashes).
    Bare, the bodies are untyped; ?activity= inlines each model's own body
    schema (up to 1024 models); ?model= is that one model's paths. Reactor
-   keeps one path per endpoint, each body an input_/output_ component
-   (x-modelschemas-model). A filter that matches none: 400
+   publishes POST /tokens only. Model commands are input_/output_
+   components tagged x-modelschemas-transport: realtime, not HTTP paths.
+   A filter that matches none: 400
    spec_requires_selector. HTTP only (no MCP tool).
 7. POST /v1/validate {"provider","endpointId","payload"} — check a payload.
 8. POST /v1/estimate {"provider","model","request"?,"usage"?} — {amount,

src/server/openapi.ts

@@ -588,7 +588,7 @@ export const openApiDocument = {
           'Assembled from classified endpoints plus the provider connect profile (servers, auth, required headers). ' +
           'Not a raw upstream-spec mirror. FAL (model-grained, queue) is one document: POST /{endpoint_id} and GET /{endpoint_id}/requests/{request_id}. endpoint_id is the model raw id (x-modelschemas-encode raw: do not percent-encode slashes). ' +
           "With no selector the bodies are untyped; ?activity= narrows the enum and inlines each model's own body schema (x-modelschemas-model), up to 1024 models; ?model= is that one model's paths. " +
-          'Other model-grained providers (Reactor) keep one path per endpoint; bare or with ?activity=, each body is an input_/output_ component schema tagged x-modelschemas-model. ' +
+          'Reactor publishes platform HTTP only (POST /tokens, Reactor-API-Key). Model commands stay component schemas tagged x-modelschemas-model and x-modelschemas-transport: realtime, not paths on the API host. ' +
           'A filter that matches no endpoint returns 400 spec_requires_selector; there is no cap on the number of paths in a provider-grained document. ' +
           'An unsynced provider returns 404 no_endpoints. ?model= pins the live model enum on provider-grained specs; it does not drop endpoints.',
         parameters: [

src/server/provider-openapi.ts

@@ -511,9 +511,16 @@ function schemaComponentKey(
   return unique
 }
 
-function withModelAnnotation(schema: unknown, rawId: string): unknown {
-  if (isObject(schema)) return { ...schema, 'x-modelschemas-model': rawId }
-  return { 'x-modelschemas-model': rawId, allOf: [schema] }
+function withModelAnnotation(
+  schema: unknown,
+  rawId: string,
+  transport?: 'realtime',
+): Record<string, unknown> {
+  const marked: Record<string, unknown> = isObject(schema)
+    ? { ...schema, 'x-modelschemas-model': rawId }
+    : { 'x-modelschemas-model': rawId, allOf: [schema] }
+  if (transport !== undefined) marked['x-modelschemas-transport'] = transport
+  return marked
 }
 
 function schemaUnion(
@@ -583,6 +590,7 @@ async function endpointOwners(
 function buildModelComponents(
   selected: Array<LoadedEndpoint>,
   owners: Map<string, string>,
+  transport?: 'realtime',
 ): { endpoints: Array<LoadedEndpoint>; schemas: Record<string, unknown> } {
   const used = new Set<string>()
   const schemas: Record<string, unknown> = {}
@@ -594,7 +602,7 @@ function buildModelComponents(
   ) => {
     if (schema === undefined) return undefined
     const name = schemaComponentKey(kind, endpoint.id, used)
-    schemas[name] = withModelAnnotation(schema, owner)
+    schemas[name] = withModelAnnotation(schema, owner, transport)
     return { $ref: `#/components/schemas/${name}` }
   }
   const typed = selected.map((endpoint) => {
@@ -1129,6 +1137,7 @@ export async function assembleProviderOpenApi(
 
   const config = getProvider(providerId)
   const grain = resolveSpecGrain(config)
+  const realtime = config?.realtimeCommands === true
 
   let pinnedModel: string | undefined
   if (query.model !== undefined) {
@@ -1185,8 +1194,10 @@ export async function assembleProviderOpenApi(
   const loaded = await loadEndpoints(db, providerId, activity, !lean)
   let selected = loaded
   if (pinnedModel !== undefined) {
-    const matching = loaded.filter((e) =>
-      endpointMatchesModel(e.id, e.path, pinnedModel),
+    const matching = loaded.filter(
+      (e) =>
+        endpointMatchesModel(e.id, e.path, pinnedModel) ||
+        (realtime && e.path.startsWith(`/${pinnedModel}/`)),
     )
     if (matching.length > 0) selected = matching
     else if (grain === 'model') {
@@ -1201,11 +1212,12 @@ export async function assembleProviderOpenApi(
     selected = selectQueueEndpoints(loaded, queueRawIds)
   }
 
-  // A model-grained provider without a queue (Reactor) keeps one path per
-  // endpoint; each body becomes an `input_`/`output_` component tagged with
-  // the model that owns the path.
+  // A model-grained provider without a queue keeps one component pair per
+  // endpoint, tagged with the model that owns the path. Realtime commands
+  // (Reactor) stay components on a pinned document too: they are not HTTP
+  // paths, so inlining them onto `connect.servers` would publish 404s.
   let owners: Map<string, string> | undefined
-  if (grain === 'model' && pinnedModel === undefined && !queue) {
+  if (grain === 'model' && !queue && (pinnedModel === undefined || realtime)) {
     owners = await endpointOwners(db, providerId, selected)
     if (!owners) return refuseModelGrained(providerId, loaded.length)
   }
@@ -1260,7 +1272,13 @@ export async function assembleProviderOpenApi(
     Object.assign(paths, built.paths)
     queueSchemas = built.schemas
   } else {
-    const built = owners ? buildModelComponents(selected, owners) : undefined
+    const built = owners
+      ? buildModelComponents(
+          selected,
+          owners,
+          realtime ? 'realtime' : undefined,
+        )
+      : undefined
     if (built) queueSchemas = built.schemas
     const catalog =
       owners !== undefined ||
@@ -1293,20 +1311,26 @@ export async function assembleProviderOpenApi(
         : modelIds
     // An upstream `#stream` path key (Mistral) is the same URL. Twins are
     // built aside and merged into the base once their schemas are hoisted.
-    for (const endpoint of built?.endpoints ?? selected) {
-      const path = endpoint.path.split('#')[0] ?? endpoint.path
-      const target = path === endpoint.path ? paths : twinPaths
-      const owner = owners?.get(endpoint.id)
-      for (const op of operationsFor(
-        providerId,
-        { ...endpoint, path },
-        connect,
-        owner !== undefined ? [owner] : idsFor(endpoint.id),
-        pinnedModel,
-      )) {
-        const item = target[op.path] ?? {}
-        item[op.method] = op.operation
-        target[op.path] = item
+    // Realtime commands are the component schemas above. Paths are the
+    // provider's platform HTTP operations (Reactor POST /tokens).
+    if (realtime) {
+      Object.assign(paths, config.platformOperations?.(pinnedModel) ?? {})
+    } else {
+      for (const endpoint of built?.endpoints ?? selected) {
+        const path = endpoint.path.split('#')[0] ?? endpoint.path
+        const target = path === endpoint.path ? paths : twinPaths
+        const owner = owners?.get(endpoint.id)
+        for (const op of operationsFor(
+          providerId,
+          { ...endpoint, path },
+          connect,
+          owner !== undefined ? [owner] : idsFor(endpoint.id),
+          pinnedModel,
+        )) {
+          const item = target[op.path] ?? {}
+          item[op.method] = op.operation
+          target[op.path] = item
+        }
       }
     }
   }
@@ -1349,7 +1373,9 @@ export async function assembleProviderOpenApi(
       title: `${config?.displayName ?? providerId} (modelschemas)`,
       version: revision,
       description: owners
-        ? `Generation-only OpenAPI assembled by modelschemas from stored endpoint schemas. Call this provider directly with your own key — this is not a proxy. One path per endpoint; each body is a component schema (input_/output_) tagged with its model (x-modelschemas-model).`
+        ? realtime
+          ? `Generation-only OpenAPI assembled by modelschemas from stored endpoint schemas. Call this provider directly with your own key — this is not a proxy. HTTP paths are platform operations only. Model commands are not HTTP: each body is a component schema (input_/output_) tagged with its model (x-modelschemas-model) and x-modelschemas-transport: realtime.`
+          : `Generation-only OpenAPI assembled by modelschemas from stored endpoint schemas. Call this provider directly with your own key — this is not a proxy. One path per endpoint; each body is a component schema (input_/output_) tagged with its model (x-modelschemas-model).`
         : queue
           ? `Generation-only OpenAPI assembled by modelschemas from stored endpoint schemas. Call this provider directly with your own key — this is not a proxy. One queue client: endpoint_id is the model raw id${lean ? "; bodies are untyped here, pass ?activity= to inline each model's own schema" : ", and each component schema is that model's own body (x-modelschemas-model)"}.`
           : `Generation-only OpenAPI assembled by modelschemas from live endpoint schemas. Call this provider directly with your own key — this is not a proxy.`,

src/server/provider-openapi.worker.test.ts

@@ -1473,20 +1473,89 @@ describe('assembleProviderOpenApi', () => {
         paths: Record<string, unknown>
         components: { schemas: Record<string, Record<string, unknown>> }
       }
-      expect(Object.keys(doc.paths).sort()).toEqual(paths)
+      expect(Object.keys(doc.paths)).toEqual(['/tokens'])
+      for (const path of paths) expect(doc.paths[path]).toBeUndefined()
+      const tokens = doc.paths['/tokens'] as {
+        post?: {
+          operationId?: string
+          parameters?: Array<{ name?: string; in?: string; required?: boolean }>
+          requestBody?: {
+            content?: {
+              'application/json'?: {
+                schema?: { required?: Array<string> }
+              }
+            }
+          }
+          responses?: {
+            '200'?: {
+              content?: {
+                'application/json'?: {
+                  schema?: { required?: Array<string> }
+                }
+              }
+            }
+          }
+        }
+      }
+      expect(tokens.post?.operationId).toBe('createSessionToken')
+      expect(tokens.post?.parameters).toEqual([
+        expect.objectContaining({
+          name: 'Reactor-API-Key',
+          in: 'header',
+          required: true,
+        }),
+      ])
+      expect(
+        tokens.post?.requestBody?.content?.['application/json']?.schema
+          ?.required,
+      ).toEqual(['authorization_details'])
+      expect(
+        tokens.post?.responses?.['200']?.content?.['application/json']?.schema
+          ?.required,
+      ).toEqual(['jwt', 'expires_at'])
       const schemas = doc.components.schemas
       expect(schemas['input_reactor_helios_events_set_prompt']).toMatchObject({
         'x-modelschemas-model': 'reactor/helios',
+        'x-modelschemas-transport': 'realtime',
       })
       expect(
         schemas['output_reactor_lingbot-world-2_events_pause'],
-      ).toMatchObject({ 'x-modelschemas-model': 'reactor/lingbot-world-2' })
+      ).toMatchObject({
+        'x-modelschemas-model': 'reactor/lingbot-world-2',
+        'x-modelschemas-transport': 'realtime',
+      })
       expect(
         Object.keys(schemas).filter((key) => /^(input|output)_/.test(key)),
       ).toHaveLength(paths.length * 2)
+      expect(
+        (result.document as { info?: { description?: string } }).info
+          ?.description,
+      ).toContain('x-modelschemas-transport: realtime')
       expect(unresolvedRefs(result.document)).toEqual([])
     }
 
+    const pinned = await assembleProviderOpenApi(db, 'reactor', {
+      model: 'reactor/helios',
+    })
+    expect(pinned.ok).toBe(true)
+    if (!pinned.ok) return
+    const pinnedDoc = pinned.document as {
+      paths: Record<string, { post?: { requestBody?: unknown } }>
+      components: { schemas: Record<string, unknown> }
+    }
+    expect(Object.keys(pinnedDoc.paths)).toEqual(['/tokens'])
+    expect(JSON.stringify(pinnedDoc.paths['/tokens'])).toContain(
+      '"enum":["reactor/helios"]',
+    )
+    expect(
+      pinnedDoc.components.schemas['input_reactor_helios_events_set_prompt'],
+    ).toBeDefined()
+    expect(
+      pinnedDoc.components.schemas[
+        'input_reactor_lingbot-world-2_events_pause'
+      ],
+    ).toBeUndefined()
+
     await db
       .insert(endpoints)
       .values({

src/server/providers/adapters/hints.json

@@ -242,7 +242,7 @@
     "specUrl": "https://docs.reactor.inc",
     "modelsUrl": "https://api.reactor.inc/pricing",
     "activities": ["video"],
-    "notes": "No api.reactor.inc/openapi.json. Per-model OpenAPI 3.1 (POST /events/<command>) is compiled by the runtime and embedded in https://reactor.inc/models/{slug}/api; the JS SDK loads the same document via requestSchema() after a live session is ready. fetchSpec extracts those pages (keyless). Catalog is public GET /pricing. Auth for live sessions is Reactor-API-Key."
+    "notes": "No api.reactor.inc/openapi.json. Per-model OpenAPI 3.1 (POST /events/<command>) is compiled by the runtime and embedded in https://reactor.inc/models/{slug}/api; the JS SDK loads the same document via requestSchema() after a live session is ready. Those paths are realtime sendCommand messages, not HTTP. The HTTP call is POST /tokens (Reactor-API-Key), which mints the session JWT. fetchSpec extracts the model pages (keyless). Catalog is public GET /pricing."
   },
   "worldlabs": {
     "displayName": "World Labs",