@pellux/goodvibes-tui 0.18.4

package/src/control-plane/method-catalog-control-core.ts

@@ -0,0 +1,594 @@
+import type { GatewayMethodDescriptor } from './method-catalog-shared.ts';
+import {
+  BOOLEAN_SCHEMA,
+  EMPTY_OBJECT_SCHEMA,
+  NUMBER_SCHEMA,
+  STRING_SCHEMA,
+  arraySchema,
+  actionResultOutputSchema,
+  bodyEnvelopeSchema,
+  entityOutputSchema,
+  listOutputSchema,
+  methodDescriptor,
+  objectSchema,
+  runtimeEventId,
+  METHOD_DESCRIPTOR_SCHEMA,
+  EVENT_DESCRIPTOR_SCHEMA,
+} from './method-catalog-shared.ts';
+import {
+  APPROVAL_ACTION_INPUT_SCHEMA,
+  APPROVAL_ACTION_OUTPUT_SCHEMA,
+  APPROVAL_SNAPSHOT_SCHEMA,
+  CONTROL_AUTH_CURRENT_RESPONSE_SCHEMA,
+  CONTROL_AUTH_LOGIN_REQUEST_SCHEMA,
+  CONTROL_AUTH_LOGIN_RESPONSE_SCHEMA,
+  CONTROL_PLANE_CLIENT_DESCRIPTOR_SCHEMA,
+  CONTROL_PLANE_SURFACE_MESSAGE_SCHEMA,
+  CONTROL_PLANE_SNAPSHOT_SCHEMA,
+  OTLP_LOG_DOCUMENT_SCHEMA,
+  OTLP_METRIC_DOCUMENT_SCHEMA,
+  OTLP_TRACE_DOCUMENT_SCHEMA,
+  REVIEW_SNAPSHOT_SCHEMA,
+  SESSION_BROKER_SNAPSHOT_SCHEMA,
+  SESSION_SNAPSHOT_SCHEMA,
+  SHARED_SESSION_CREATE_OUTPUT_SCHEMA,
+  SHARED_SESSION_INPUT_RECORD_SCHEMA,
+  SHARED_SESSION_MESSAGE_CREATE_OUTPUT_SCHEMA,
+  SHARED_SESSION_RECORD_SCHEMA,
+  SHARED_SESSION_ROUTING_INTENT_SCHEMA,
+  SHARED_SESSION_WITH_INPUTS_SCHEMA,
+  SHARED_SESSION_WITH_MESSAGES_SCHEMA,
+  TASK_ACTION_OUTPUT_SCHEMA,
+  TASK_CREATE_INPUT_SCHEMA,
+  TASK_CREATE_OUTPUT_SCHEMA,
+  TASK_OUTPUT_SCHEMA,
+  TASK_SNAPSHOT_SCHEMA,
+  TASK_STATUS_OUTPUT_SCHEMA,
+  TELEMETRY_FILTER_INPUT_SCHEMA,
+  TELEMETRY_METRICS_SNAPSHOT_SCHEMA,
+  TELEMETRY_RECORD_LIST_RESPONSE_SCHEMA,
+  TELEMETRY_SNAPSHOT_SCHEMA,
+  TELEMETRY_SPAN_LIST_RESPONSE_SCHEMA,
+  TELEMETRY_STREAM_READY_SCHEMA,
+} from './operator-contract-schemas.ts';
+import { OPERATOR_CONTRACT_SCHEMA } from './operator-contract.ts';
+
+const CONTROL_AUTH_CURRENT_ALIAS_PATHS = ['/api/control-plane/whoami'];
+const TELEMETRY_ALIAS_PATHS = ['/api/telemetry'];
+const TELEMETRY_EVENTS_ALIAS_PATHS = ['/api/telemetry/events'];
+const TELEMETRY_ERRORS_ALIAS_PATHS = ['/api/telemetry/errors'];
+const TELEMETRY_TRACES_ALIAS_PATHS = ['/api/telemetry/traces'];
+const TELEMETRY_METRICS_ALIAS_PATHS = ['/api/telemetry/metrics'];
+const TELEMETRY_STREAM_ALIAS_PATHS = ['/api/telemetry/stream'];
+const TELEMETRY_OTLP_TRACES_ALIAS_PATHS = ['/api/telemetry/otlp/v1/traces'];
+const TELEMETRY_OTLP_LOGS_ALIAS_PATHS = ['/api/telemetry/otlp/v1/logs'];
+const TELEMETRY_OTLP_METRICS_ALIAS_PATHS = ['/api/telemetry/otlp/v1/metrics'];
+
+export const builtinGatewayControlCoreMethodDescriptors: readonly GatewayMethodDescriptor[] = [
+  methodDescriptor({
+    id: 'control.auth.login',
+    title: 'Login',
+    description: 'Authenticate a local control-plane user and create a session token.',
+    category: 'control-plane',
+    access: 'public',
+    transport: ['http'],
+    scopes: [],
+    http: { method: 'POST', path: '/login' },
+    inputSchema: CONTROL_AUTH_LOGIN_REQUEST_SCHEMA,
+    outputSchema: CONTROL_AUTH_LOGIN_RESPONSE_SCHEMA,
+    invokable: false,
+  }),
+  methodDescriptor({
+    id: 'control.auth.current',
+    title: 'Current Auth Context',
+    description: 'Return the current control-plane principal, granted scopes, and authentication mode.',
+    category: 'control-plane',
+    access: 'public',
+    scopes: [],
+    http: { method: 'GET', path: '/api/control-plane/auth' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: CONTROL_AUTH_CURRENT_RESPONSE_SCHEMA,
+    metadata: { aliasPaths: CONTROL_AUTH_CURRENT_ALIAS_PATHS },
+  }),
+  methodDescriptor({
+    id: 'control.status',
+    title: 'Daemon Status',
+    description: 'Return daemon status and version.',
+    category: 'control-plane',
+    scopes: ['read:control-plane'],
+    http: { method: 'GET', path: '/status' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: objectSchema({
+      status: STRING_SCHEMA,
+      version: STRING_SCHEMA,
+    }, ['status', 'version']),
+  }),
+  methodDescriptor({
+    id: 'control.snapshot',
+    title: 'Control-Plane Snapshot',
+    description: 'Return the current control-plane gateway snapshot.',
+    category: 'control-plane',
+    scopes: ['read:control-plane'],
+    http: { method: 'GET', path: '/api/control-plane' },
+    events: [runtimeEventId('control-plane')],
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: CONTROL_PLANE_SNAPSHOT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'control.contract',
+    title: 'Operator Contract',
+    description: 'Return the operator-facing control-plane contract manifest, including auth, transport, method, and event metadata.',
+    category: 'control-plane',
+    scopes: ['read:control-plane'],
+    http: { method: 'GET', path: '/api/control-plane/contract' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: entityOutputSchema('contract', OPERATOR_CONTRACT_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'control.web',
+    title: 'Control-Plane Web Shell',
+    description: 'Return the built-in control-plane HTML shell for external clients.',
+    category: 'control-plane',
+    scopes: ['read:control-plane'],
+    transport: ['http'],
+    http: { method: 'GET', path: '/api/control-plane/web' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: objectSchema({ html: STRING_SCHEMA }, ['html']),
+    invokable: false,
+    metadata: { responseKind: 'html' },
+  }),
+  methodDescriptor({
+    id: 'control.messages.list',
+    title: 'List Control-Plane Messages',
+    description: 'Return recent surface messages published through the control plane.',
+    category: 'control-plane',
+    scopes: ['read:control-plane'],
+    http: { method: 'GET', path: '/api/control-plane/messages' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: listOutputSchema('messages', CONTROL_PLANE_SURFACE_MESSAGE_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'control.clients.list',
+    title: 'List Control-Plane Clients',
+    description: 'Return authenticated and recently connected control-plane clients.',
+    category: 'control-plane',
+    scopes: ['read:control-plane'],
+    http: { method: 'GET', path: '/api/control-plane/clients' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: listOutputSchema('clients', CONTROL_PLANE_CLIENT_DESCRIPTOR_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'telemetry.snapshot',
+    title: 'Telemetry Snapshot',
+    description: 'Return the current telemetry snapshot with aggregates, runtime state, and recent records.',
+    category: 'telemetry',
+    scopes: ['read:telemetry'],
+    http: { method: 'GET', path: '/api/v1/telemetry' },
+    inputSchema: TELEMETRY_FILTER_INPUT_SCHEMA,
+    outputSchema: TELEMETRY_SNAPSHOT_SCHEMA,
+    metadata: { aliasPaths: TELEMETRY_ALIAS_PATHS },
+  }),
+  methodDescriptor({
+    id: 'telemetry.events.list',
+    title: 'List Telemetry Events',
+    description: 'Return a paginated telemetry event feed with cursor-based resume semantics.',
+    category: 'telemetry',
+    scopes: ['read:telemetry'],
+    http: { method: 'GET', path: '/api/v1/telemetry/events' },
+    inputSchema: TELEMETRY_FILTER_INPUT_SCHEMA,
+    outputSchema: TELEMETRY_RECORD_LIST_RESPONSE_SCHEMA,
+    metadata: { aliasPaths: TELEMETRY_EVENTS_ALIAS_PATHS },
+  }),
+  methodDescriptor({
+    id: 'telemetry.errors.list',
+    title: 'List Telemetry Errors',
+    description: 'Return telemetry records that include normalized error metadata.',
+    category: 'telemetry',
+    scopes: ['read:telemetry'],
+    http: { method: 'GET', path: '/api/v1/telemetry/errors' },
+    inputSchema: TELEMETRY_FILTER_INPUT_SCHEMA,
+    outputSchema: TELEMETRY_RECORD_LIST_RESPONSE_SCHEMA,
+    metadata: { aliasPaths: TELEMETRY_ERRORS_ALIAS_PATHS },
+  }),
+  methodDescriptor({
+    id: 'telemetry.traces.list',
+    title: 'List Telemetry Traces',
+    description: 'Return synthesized readable spans derived from runtime telemetry.',
+    category: 'telemetry',
+    scopes: ['read:telemetry'],
+    http: { method: 'GET', path: '/api/v1/telemetry/traces' },
+    inputSchema: TELEMETRY_FILTER_INPUT_SCHEMA,
+    outputSchema: TELEMETRY_SPAN_LIST_RESPONSE_SCHEMA,
+    metadata: { aliasPaths: TELEMETRY_TRACES_ALIAS_PATHS },
+  }),
+  methodDescriptor({
+    id: 'telemetry.metrics.get',
+    title: 'Telemetry Metrics',
+    description: 'Return telemetry aggregates and runtime metrics without recent record payloads.',
+    category: 'telemetry',
+    scopes: ['read:telemetry'],
+    http: { method: 'GET', path: '/api/v1/telemetry/metrics' },
+    inputSchema: TELEMETRY_FILTER_INPUT_SCHEMA,
+    outputSchema: TELEMETRY_METRICS_SNAPSHOT_SCHEMA,
+    metadata: { aliasPaths: TELEMETRY_METRICS_ALIAS_PATHS },
+  }),
+  methodDescriptor({
+    id: 'telemetry.stream',
+    title: 'Telemetry Event Stream',
+    description: 'Open the telemetry SSE stream and emit a ready event with resume metadata.',
+    category: 'telemetry',
+    scopes: ['read:telemetry'],
+    transport: ['http'],
+    http: { method: 'GET', path: '/api/v1/telemetry/stream' },
+    inputSchema: TELEMETRY_FILTER_INPUT_SCHEMA,
+    outputSchema: TELEMETRY_STREAM_READY_SCHEMA,
+    invokable: false,
+    metadata: {
+      aliasPaths: TELEMETRY_STREAM_ALIAS_PATHS,
+      responseKind: 'sse',
+      stream: true,
+      wireEvent: 'telemetry',
+    },
+  }),
+  methodDescriptor({
+    id: 'telemetry.otlp.traces',
+    title: 'OTLP Trace Export',
+    description: 'Return telemetry traces encoded as OTLP-compatible JSON.',
+    category: 'telemetry',
+    scopes: ['read:telemetry'],
+    http: { method: 'GET', path: '/api/v1/telemetry/otlp/v1/traces' },
+    inputSchema: TELEMETRY_FILTER_INPUT_SCHEMA,
+    outputSchema: OTLP_TRACE_DOCUMENT_SCHEMA,
+    metadata: { aliasPaths: TELEMETRY_OTLP_TRACES_ALIAS_PATHS },
+  }),
+  methodDescriptor({
+    id: 'telemetry.otlp.logs',
+    title: 'OTLP Log Export',
+    description: 'Return telemetry events encoded as OTLP-compatible log documents.',
+    category: 'telemetry',
+    scopes: ['read:telemetry'],
+    http: { method: 'GET', path: '/api/v1/telemetry/otlp/v1/logs' },
+    inputSchema: TELEMETRY_FILTER_INPUT_SCHEMA,
+    outputSchema: OTLP_LOG_DOCUMENT_SCHEMA,
+    metadata: { aliasPaths: TELEMETRY_OTLP_LOGS_ALIAS_PATHS },
+  }),
+  methodDescriptor({
+    id: 'telemetry.otlp.metrics',
+    title: 'OTLP Metric Export',
+    description: 'Return telemetry metrics encoded as OTLP-compatible metric documents.',
+    category: 'telemetry',
+    scopes: ['read:telemetry'],
+    http: { method: 'GET', path: '/api/v1/telemetry/otlp/v1/metrics' },
+    inputSchema: TELEMETRY_FILTER_INPUT_SCHEMA,
+    outputSchema: OTLP_METRIC_DOCUMENT_SCHEMA,
+    metadata: { aliasPaths: TELEMETRY_OTLP_METRICS_ALIAS_PATHS },
+  }),
+  methodDescriptor({
+    id: 'control.methods.list',
+    title: 'List Gateway Methods',
+    description: 'Return the gateway method catalog.',
+    category: 'control-plane',
+    scopes: ['read:control-plane'],
+    http: { method: 'GET', path: '/api/control-plane/methods' },
+    inputSchema: objectSchema({
+      category: STRING_SCHEMA,
+      source: STRING_SCHEMA,
+    }),
+    outputSchema: listOutputSchema('methods', METHOD_DESCRIPTOR_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'control.methods.get',
+    title: 'Get Gateway Method',
+    description: 'Return a single gateway method descriptor.',
+    category: 'control-plane',
+    scopes: ['read:control-plane'],
+    http: { method: 'GET', path: '/api/control-plane/methods/{methodId}' },
+    inputSchema: objectSchema({
+      methodId: STRING_SCHEMA,
+    }, ['methodId']),
+    outputSchema: entityOutputSchema('method', METHOD_DESCRIPTOR_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'control.events.catalog',
+    title: 'List Gateway Events',
+    description: 'Return the event catalog for SSE and WebSocket control-plane subscriptions.',
+    category: 'control-plane',
+    scopes: ['read:control-plane', 'read:events'],
+    http: { method: 'GET', path: '/api/control-plane/events/catalog' },
+    inputSchema: objectSchema({
+      category: STRING_SCHEMA,
+      domain: STRING_SCHEMA,
+    }),
+    outputSchema: listOutputSchema('events', EVENT_DESCRIPTOR_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'control.events.stream',
+    title: 'Open Control-Plane Event Stream',
+    description: 'Open the SSE control-plane event stream.',
+    category: 'control-plane',
+    scopes: ['read:events'],
+    transport: ['http'],
+    http: { method: 'GET', path: '/api/control-plane/events' },
+    inputSchema: objectSchema({
+      domains: STRING_SCHEMA,
+    }),
+    outputSchema: objectSchema({
+      contentType: STRING_SCHEMA,
+      mode: STRING_SCHEMA,
+    }, ['contentType', 'mode']),
+    invokable: false,
+    metadata: { responseKind: 'sse', stream: true },
+  }),
+  methodDescriptor({
+    id: 'review.snapshot',
+    title: 'Review Snapshot',
+    description: 'Return the integration review snapshot used by external helpers.',
+    category: 'review',
+    scopes: ['read:automation'],
+    http: { method: 'GET', path: '/api/review' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: REVIEW_SNAPSHOT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'sessions.integration.snapshot',
+    title: 'Legacy Session Snapshot',
+    description: 'Return the legacy integration session snapshot.',
+    category: 'sessions',
+    scopes: ['read:sessions'],
+    http: { method: 'GET', path: '/api/session' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: SESSION_SNAPSHOT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'sessions.list',
+    title: 'List Shared Sessions',
+    description: 'Return shared-session integration state.',
+    category: 'sessions',
+    scopes: ['read:sessions'],
+    http: { method: 'GET', path: '/api/sessions' },
+    events: [runtimeEventId('session')],
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: SESSION_BROKER_SNAPSHOT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'sessions.create',
+    title: 'Create Shared Session',
+    description: 'Create a shared session for a surface, route, or web client.',
+    category: 'sessions',
+    scopes: ['write:sessions'],
+    http: { method: 'POST', path: '/api/sessions' },
+    inputSchema: bodyEnvelopeSchema({
+      title: STRING_SCHEMA,
+      surfaceKind: STRING_SCHEMA,
+      surfaceId: STRING_SCHEMA,
+    }),
+    outputSchema: SHARED_SESSION_CREATE_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'sessions.get',
+    title: 'Get Shared Session',
+    description: 'Return metadata for a shared session.',
+    category: 'sessions',
+    scopes: ['read:sessions'],
+    http: { method: 'GET', path: '/api/sessions/{sessionId}' },
+    inputSchema: objectSchema({ sessionId: STRING_SCHEMA }, ['sessionId']),
+    outputSchema: SHARED_SESSION_WITH_MESSAGES_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'sessions.close',
+    title: 'Close Shared Session',
+    description: 'Mark a shared session as closed.',
+    category: 'sessions',
+    scopes: ['write:sessions'],
+    http: { method: 'POST', path: '/api/sessions/{sessionId}/close' },
+    inputSchema: objectSchema({ sessionId: STRING_SCHEMA }, ['sessionId']),
+    outputSchema: actionResultOutputSchema('session', SHARED_SESSION_RECORD_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'sessions.reopen',
+    title: 'Reopen Shared Session',
+    description: 'Reopen a previously closed shared session.',
+    category: 'sessions',
+    scopes: ['write:sessions'],
+    http: { method: 'POST', path: '/api/sessions/{sessionId}/reopen' },
+    inputSchema: objectSchema({ sessionId: STRING_SCHEMA }, ['sessionId']),
+    outputSchema: actionResultOutputSchema('session', SHARED_SESSION_RECORD_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'sessions.messages.list',
+    title: 'List Shared Session Messages',
+    description: 'Return message history for a shared session.',
+    category: 'sessions',
+    scopes: ['read:sessions'],
+    http: { method: 'GET', path: '/api/sessions/{sessionId}/messages' },
+    inputSchema: objectSchema({
+      sessionId: STRING_SCHEMA,
+      limit: NUMBER_SCHEMA,
+      before: STRING_SCHEMA,
+    }, ['sessionId']),
+    outputSchema: SHARED_SESSION_WITH_MESSAGES_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'sessions.messages.create',
+    title: 'Post Shared Session Message',
+    description: 'Append a user message to a shared session and queue assistant work.',
+    category: 'sessions',
+    scopes: ['write:sessions'],
+    http: { method: 'POST', path: '/api/sessions/{sessionId}/messages' },
+    inputSchema: bodyEnvelopeSchema({
+      body: STRING_SCHEMA,
+      surfaceKind: STRING_SCHEMA,
+      surfaceId: STRING_SCHEMA,
+      routing: SHARED_SESSION_ROUTING_INTENT_SCHEMA,
+    }, ['body']),
+    outputSchema: SHARED_SESSION_MESSAGE_CREATE_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'sessions.inputs.list',
+    title: 'List Shared Session Inputs',
+    description: 'Return explicit session inputs, including queued follow-ups and delivered steering requests.',
+    category: 'sessions',
+    scopes: ['read:sessions'],
+    http: { method: 'GET', path: '/api/sessions/{sessionId}/inputs' },
+    inputSchema: objectSchema({
+      sessionId: STRING_SCHEMA,
+      limit: NUMBER_SCHEMA,
+    }, ['sessionId']),
+    outputSchema: SHARED_SESSION_WITH_INPUTS_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'sessions.steer',
+    title: 'Steer Shared Session',
+    description: 'Deliver a live steering message to the active agent for a shared session, optionally falling back to spawn when explicitly allowed.',
+    category: 'sessions',
+    scopes: ['write:sessions'],
+    http: { method: 'POST', path: '/api/sessions/{sessionId}/steer' },
+    inputSchema: bodyEnvelopeSchema({
+      body: STRING_SCHEMA,
+      surfaceKind: STRING_SCHEMA,
+      surfaceId: STRING_SCHEMA,
+      routing: SHARED_SESSION_ROUTING_INTENT_SCHEMA,
+      allowSpawnFallback: BOOLEAN_SCHEMA,
+    }, ['body']),
+    outputSchema: SHARED_SESSION_MESSAGE_CREATE_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'sessions.followUp',
+    title: 'Queue Shared Session Follow-Up',
+    description: 'Queue a deferred follow-up for a shared session so it runs after the current agent completes, or spawn immediately when the session is idle.',
+    category: 'sessions',
+    scopes: ['write:sessions'],
+    http: { method: 'POST', path: '/api/sessions/{sessionId}/follow-up' },
+    inputSchema: bodyEnvelopeSchema({
+      body: STRING_SCHEMA,
+      surfaceKind: STRING_SCHEMA,
+      surfaceId: STRING_SCHEMA,
+      routing: SHARED_SESSION_ROUTING_INTENT_SCHEMA,
+    }, ['body']),
+    outputSchema: SHARED_SESSION_MESSAGE_CREATE_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'sessions.inputs.cancel',
+    title: 'Cancel Shared Session Input',
+    description: 'Cancel a queued shared-session input before it is delivered or spawned.',
+    category: 'sessions',
+    scopes: ['write:sessions'],
+    http: { method: 'POST', path: '/api/sessions/{sessionId}/inputs/{inputId}/cancel' },
+    inputSchema: objectSchema({
+      sessionId: STRING_SCHEMA,
+      inputId: STRING_SCHEMA,
+    }, ['sessionId', 'inputId']),
+    outputSchema: entityOutputSchema('input', SHARED_SESSION_INPUT_RECORD_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'tasks.list',
+    title: 'List Runtime Tasks',
+    description: 'Return the integration snapshot for runtime tasks.',
+    category: 'tasks',
+    scopes: ['read:tasks'],
+    http: { method: 'GET', path: '/api/tasks' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: TASK_SNAPSHOT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'tasks.create',
+    title: 'Create Task',
+    description: 'Submit a task to the daemon or a shared session.',
+    category: 'tasks',
+    scopes: ['write:tasks'],
+    http: { method: 'POST', path: '/task' },
+    events: [runtimeEventId('tasks')],
+    inputSchema: TASK_CREATE_INPUT_SCHEMA,
+    outputSchema: TASK_CREATE_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'tasks.get',
+    title: 'Get Runtime Task',
+    description: 'Return a single runtime task record.',
+    category: 'tasks',
+    scopes: ['read:tasks'],
+    http: { method: 'GET', path: '/api/tasks/{taskId}' },
+    inputSchema: objectSchema({ taskId: STRING_SCHEMA }, ['taskId']),
+    outputSchema: TASK_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'tasks.cancel',
+    title: 'Cancel Runtime Task',
+    description: 'Cancel an in-flight runtime task.',
+    category: 'tasks',
+    scopes: ['write:tasks'],
+    http: { method: 'POST', path: '/api/tasks/{taskId}/cancel' },
+    inputSchema: objectSchema({ taskId: STRING_SCHEMA }, ['taskId']),
+    outputSchema: TASK_ACTION_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'tasks.retry',
+    title: 'Retry Runtime Task',
+    description: 'Retry a runtime task through the task action endpoint.',
+    category: 'tasks',
+    scopes: ['write:tasks'],
+    http: { method: 'POST', path: '/api/tasks/{taskId}/retry' },
+    inputSchema: objectSchema({ taskId: STRING_SCHEMA }, ['taskId']),
+    outputSchema: TASK_ACTION_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'tasks.status',
+    title: 'Get Task Status',
+    description: 'Return lightweight runtime task status by agent id.',
+    category: 'tasks',
+    scopes: ['read:tasks'],
+    http: { method: 'GET', path: '/task/{agentId}' },
+    inputSchema: objectSchema({ agentId: STRING_SCHEMA }, ['agentId']),
+    outputSchema: TASK_STATUS_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'approvals.list',
+    title: 'List Approvals',
+    description: 'Return pending and historical approval records.',
+    category: 'approvals',
+    scopes: ['read:approvals'],
+    http: { method: 'GET', path: '/api/approvals' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: APPROVAL_SNAPSHOT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'approvals.claim',
+    title: 'Claim Approval',
+    description: 'Claim a pending approval for operator handling.',
+    category: 'approvals',
+    scopes: ['write:approvals'],
+    http: { method: 'POST', path: '/api/approvals/{approvalId}/claim' },
+    inputSchema: objectSchema({ approvalId: STRING_SCHEMA }, ['approvalId']),
+    outputSchema: APPROVAL_ACTION_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'approvals.approve',
+    title: 'Approve Approval',
+    description: 'Approve a pending approval.',
+    category: 'approvals',
+    scopes: ['write:approvals'],
+    http: { method: 'POST', path: '/api/approvals/{approvalId}/approve' },
+    inputSchema: APPROVAL_ACTION_INPUT_SCHEMA,
+    outputSchema: APPROVAL_ACTION_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'approvals.deny',
+    title: 'Deny Approval',
+    description: 'Deny a pending approval.',
+    category: 'approvals',
+    scopes: ['write:approvals'],
+    http: { method: 'POST', path: '/api/approvals/{approvalId}/deny' },
+    inputSchema: APPROVAL_ACTION_INPUT_SCHEMA,
+    outputSchema: APPROVAL_ACTION_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'approvals.cancel',
+    title: 'Cancel Approval',
+    description: 'Cancel a pending approval.',
+    category: 'approvals',
+    scopes: ['write:approvals'],
+    http: { method: 'POST', path: '/api/approvals/{approvalId}/cancel' },
+    inputSchema: APPROVAL_ACTION_INPUT_SCHEMA,
+    outputSchema: APPROVAL_ACTION_OUTPUT_SCHEMA,
+  }),
+];

package/src/control-plane/method-catalog-control.ts

@@ -0,0 +1,8 @@
+import type { GatewayMethodDescriptor } from './method-catalog-shared.ts';
+import { builtinGatewayControlAutomationMethodDescriptors } from './method-catalog-control-automation.ts';
+import { builtinGatewayControlCoreMethodDescriptors } from './method-catalog-control-core.ts';
+
+export const builtinGatewayControlMethodDescriptors: readonly GatewayMethodDescriptor[] = [
+  ...builtinGatewayControlCoreMethodDescriptors,
+  ...builtinGatewayControlAutomationMethodDescriptors,
+];

package/src/control-plane/method-catalog-events.ts

@@ -0,0 +1,74 @@
+import type { GatewayEventDescriptor } from './method-catalog-shared.ts';
+import { STRING_SCHEMA,NUMBER_SCHEMA,arraySchema,objectSchema,eventDescriptor,runtimeDomainEvent } from './method-catalog-shared.ts';
+import { CONTROL_PLANE_SURFACE_MESSAGE_SCHEMA } from './operator-contract-schemas.ts';
+import { RUNTIME_EVENT_DOMAINS, type RuntimeEventDomain } from '../runtime/events/domain-map.ts';
+
+const RUNTIME_DOMAIN_DESCRIPTIONS = {
+  session: 'Shared-session lifecycle, participant, and message events.',
+  turn: 'Turn submission and completion events.',
+  providers: 'Provider health, selection, and routing events.',
+  tools: 'Tool start, result, and failure events.',
+  tasks: 'Runtime task lifecycle and status events.',
+  agents: 'Agent lifecycle, planning, and completion events.',
+  workflows: 'Workflow orchestration events.',
+  orchestration: 'Higher-level orchestration and planner coordination events.',
+  communication: 'Agent communication and policy events.',
+  planner: 'Planner updates and plan mutation events.',
+  permissions: 'Approval and permission prompt events.',
+  plugins: 'Plugin registration and lifecycle events.',
+  mcp: 'MCP server, tool, and connection events.',
+  transport: 'Transport connect, disconnect, and lifecycle events.',
+  compaction: 'Context compaction and summary events.',
+  ui: 'UI-focused state and operational events.',
+  ops: 'Operational diagnostics and control events.',
+  forensics: 'Forensics and incident trail events.',
+  security: 'Security posture and policy events.',
+  automation: 'Automation job, schedule, and run events.',
+  routes: 'Route binding and surface-link events.',
+  'control-plane': 'Control-plane client, auth, and subscription events.',
+  deliveries: 'Delivery queue and outcome events.',
+  watchers: 'Watcher state and heartbeat events.',
+  surfaces: 'Surface registration and health events.',
+  knowledge: 'Knowledge ingest, extraction, projection, packet, and job events.',
+} satisfies Record<RuntimeEventDomain, string>;
+
+export const builtinGatewayEventDescriptors: readonly GatewayEventDescriptor[] = [
+  ...RUNTIME_EVENT_DOMAINS.map((domain) => runtimeDomainEvent(domain, RUNTIME_DOMAIN_DESCRIPTIONS[domain])),
+  eventDescriptor({
+    id: 'control.ready',
+    title: 'Ready Handshake',
+    description: 'Initial SSE/WebSocket handshake event emitted after a control-plane subscription is opened.',
+    category: 'transport',
+    transport: ['sse', 'ws'],
+    scopes: ['read:events'],
+    wireEvents: ['ready'],
+    outputSchema: objectSchema({
+      clientId: STRING_SCHEMA,
+      domains: arraySchema(STRING_SCHEMA),
+      transport: STRING_SCHEMA,
+    }, ['clientId', 'domains', 'transport']),
+  }),
+  eventDescriptor({
+    id: 'control.heartbeat',
+    title: 'Heartbeat',
+    description: 'Keepalive event emitted by the SSE control-plane transport.',
+    category: 'transport',
+    transport: ['sse', 'ws'],
+    scopes: ['read:events'],
+    wireEvents: ['heartbeat'],
+    outputSchema: objectSchema({
+      clientId: STRING_SCHEMA,
+      ts: NUMBER_SCHEMA,
+    }, ['clientId', 'ts'], { additionalProperties: false }),
+  }),
+  eventDescriptor({
+    id: 'control.surface_message',
+    title: 'Surface Message',
+    description: 'Out-of-band control-plane surface messages for operators and connected clients.',
+    category: 'transport',
+    transport: ['sse', 'ws'],
+    scopes: ['read:events'],
+    wireEvents: ['surface-message'],
+    outputSchema: CONTROL_PLANE_SURFACE_MESSAGE_SCHEMA,
+  }),
+];