@pellux/goodvibes-tui 0.18.4

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

@@ -0,0 +1,591 @@
+import type { GatewayMethodDescriptor } from './method-catalog-shared.ts';
+import { EMPTY_OBJECT_SCHEMA,STRING_SCHEMA,BOOLEAN_SCHEMA,NUMBER_SCHEMA,arraySchema,objectSchema,listOutputSchema,bodyEnvelopeSchema,methodDescriptor,runtimeEventId } from './method-catalog-shared.ts';
+import {
+  HTTP_HEADER_MAP_SCHEMA,
+  METADATA_SCHEMA,
+} from './operator-contract-schemas-shared.ts';
+import {
+  CHANNEL_ACCOUNT_ACTION_OUTPUT_SCHEMA,
+  CHANNEL_ACCOUNTS_OUTPUT_SCHEMA,
+  CHANNEL_ACCOUNT_ENTITY_OUTPUT_SCHEMA,
+  CHANNEL_ALLOWLIST_EDIT_RESULT_SCHEMA,
+  CHANNEL_ALLOWLIST_RESOLUTION_SCHEMA,
+  CHANNEL_AUTHORIZE_OUTPUT_SCHEMA,
+  CHANNEL_CAPABILITY_SCHEMA,
+  CHANNEL_DOCTOR_REPORT_SCHEMA,
+  CHANNEL_DIRECTORY_ENTRY_SCHEMA,
+  CHANNEL_GROUP_POLICY_SCHEMA,
+  CHANNEL_LIFECYCLE_STATE_SCHEMA,
+  CHANNEL_OPERATOR_ACTION_OUTPUT_SCHEMA,
+  CHANNEL_OPERATOR_ACTION_SCHEMA,
+  CHANNEL_POLICY_AUDIT_SCHEMA,
+  CHANNEL_POLICY_SCHEMA,
+  CHANNEL_SETUP_SCHEMA_SCHEMA,
+  CHANNEL_STATUS_LIST_OUTPUT_SCHEMA,
+  CHANNEL_TARGET_RESOLVE_OUTPUT_SCHEMA,
+  CHANNEL_TOOL_SCHEMA,
+  CHANNEL_TOOL_ACTION_OUTPUT_SCHEMA,
+  CHANNEL_REPAIR_ACTION_SCHEMA,
+  TOOL_DEFINITION_SCHEMA,
+  REMOVE_WITH_ID_OUTPUT_SCHEMA,
+  SERVICE_STATUS_SCHEMA,
+  WATCHER_LIST_OUTPUT_SCHEMA,
+  WATCHER_RECORD_SCHEMA,
+} from './operator-contract-schemas.ts';
+
+export const builtinGatewayChannelMethodDescriptors: readonly GatewayMethodDescriptor[] = [
+  methodDescriptor({
+    id: 'channels.accounts.list',
+    title: 'List Channel Accounts',
+    description: 'Return channel account lifecycle posture.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/accounts' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: CHANNEL_ACCOUNTS_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'channels.accounts.surface.list',
+    title: 'List Channel Surface Accounts',
+    description: 'Return account posture for a single channel surface.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/accounts/{surface}' },
+    inputSchema: objectSchema({ surface: STRING_SCHEMA }, ['surface']),
+    outputSchema: CHANNEL_ACCOUNTS_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'channels.accounts.get',
+    title: 'Get Channel Account',
+    description: 'Return a single channel account record.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/accounts/{surface}/{accountId}' },
+    inputSchema: objectSchema({
+      surface: STRING_SCHEMA,
+      accountId: STRING_SCHEMA,
+    }, ['surface', 'accountId']),
+    outputSchema: CHANNEL_ACCOUNT_ENTITY_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'channels.setup.get',
+    title: 'Get Channel Setup Schema',
+    description: 'Return the versioned setup schema, secret targets, and external steps for a channel surface.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/setup/{surface}' },
+    inputSchema: objectSchema({ surface: STRING_SCHEMA }, ['surface']),
+    outputSchema: CHANNEL_SETUP_SCHEMA_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'channels.doctor.get',
+    title: 'Get Channel Doctor Report',
+    description: 'Return doctor checks and repair posture for a channel surface.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/doctor/{surface}' },
+    inputSchema: objectSchema({ surface: STRING_SCHEMA }, ['surface']),
+    outputSchema: CHANNEL_DOCTOR_REPORT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'channels.repairs.list',
+    title: 'List Channel Repair Actions',
+    description: 'Return repair actions exposed by a channel surface.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/repair-actions/{surface}' },
+    inputSchema: objectSchema({ surface: STRING_SCHEMA }, ['surface']),
+    outputSchema: listOutputSchema('actions', CHANNEL_REPAIR_ACTION_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'channels.lifecycle.get',
+    title: 'Get Channel Lifecycle State',
+    description: 'Return lifecycle migration posture for a channel surface.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/lifecycle/{surface}' },
+    inputSchema: objectSchema({ surface: STRING_SCHEMA }, ['surface']),
+    outputSchema: CHANNEL_LIFECYCLE_STATE_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'channels.lifecycle.migrate',
+    title: 'Migrate Channel Lifecycle',
+    description: 'Apply lifecycle migrations for a channel surface.',
+    category: 'channels',
+    scopes: ['write:channels'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/channels/lifecycle/{surface}/migrate' },
+    inputSchema: bodyEnvelopeSchema({
+      accountId: STRING_SCHEMA,
+      metadata: METADATA_SCHEMA,
+    }),
+    outputSchema: CHANNEL_LIFECYCLE_STATE_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'channels.accounts.action.default',
+    title: 'Run Channel Account Action',
+    description: 'Run a lifecycle action on the default channel account for a surface.',
+    category: 'channels',
+    scopes: ['write:channels'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/channels/accounts/{surface}/actions/{action}' },
+    inputSchema: bodyEnvelopeSchema({
+      accountId: STRING_SCHEMA,
+      metadata: METADATA_SCHEMA,
+    }),
+    outputSchema: CHANNEL_ACCOUNT_ACTION_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'channels.accounts.action.named',
+    title: 'Run Named Channel Account Action',
+    description: 'Run a lifecycle action on a specific channel account.',
+    category: 'channels',
+    scopes: ['write:channels'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/channels/accounts/{surface}/{accountId}/actions/{action}' },
+    inputSchema: bodyEnvelopeSchema({
+      accountId: STRING_SCHEMA,
+      metadata: METADATA_SCHEMA,
+    }),
+    outputSchema: CHANNEL_ACCOUNT_ACTION_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'channels.capabilities.list',
+    title: 'List Channel Capabilities',
+    description: 'Return capability posture for all registered channel surfaces.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/capabilities' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: listOutputSchema('capabilities', CHANNEL_CAPABILITY_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'channels.capabilities.surface.list',
+    title: 'List Channel Surface Capabilities',
+    description: 'Return capability posture for a single surface.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/capabilities/{surface}' },
+    inputSchema: objectSchema({ surface: STRING_SCHEMA }, ['surface']),
+    outputSchema: listOutputSchema('capabilities', CHANNEL_CAPABILITY_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'channels.tools.list',
+    title: 'List Channel Tools',
+    description: 'Return operator tools registered by channel plugins.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/tools' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: listOutputSchema('tools', CHANNEL_TOOL_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'channels.tools.surface.list',
+    title: 'List Channel Surface Tools',
+    description: 'Return operator tools for a single channel surface.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/tools/{surface}' },
+    inputSchema: objectSchema({ surface: STRING_SCHEMA }, ['surface']),
+    outputSchema: listOutputSchema('tools', CHANNEL_TOOL_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'channels.tools.invoke',
+    title: 'Run Channel Tool',
+    description: 'Run a channel-owned operator tool.',
+    category: 'channels',
+    scopes: ['write:channels'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/channels/tools/{surface}/{toolId}' },
+    inputSchema: bodyEnvelopeSchema({
+      accountId: STRING_SCHEMA,
+      metadata: METADATA_SCHEMA,
+    }),
+    outputSchema: CHANNEL_TOOL_ACTION_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'channels.agent_tools.list',
+    title: 'List Channel Agent Tools',
+    description: 'Return LLM agent tools exposed through channel plugins.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/agent-tools' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: listOutputSchema('tools', TOOL_DEFINITION_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'channels.agent_tools.surface.list',
+    title: 'List Channel Surface Agent Tools',
+    description: 'Return LLM agent tools for a single channel surface.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/agent-tools/{surface}' },
+    inputSchema: objectSchema({ surface: STRING_SCHEMA }, ['surface']),
+    outputSchema: listOutputSchema('tools', TOOL_DEFINITION_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'channels.actions.list',
+    title: 'List Channel Actions',
+    description: 'Return operator actions registered by channel plugins.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/actions' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: listOutputSchema('actions', CHANNEL_OPERATOR_ACTION_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'channels.actions.surface.list',
+    title: 'List Channel Surface Actions',
+    description: 'Return operator actions for a single channel surface.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/actions/{surface}' },
+    inputSchema: objectSchema({ surface: STRING_SCHEMA }, ['surface']),
+    outputSchema: listOutputSchema('actions', CHANNEL_OPERATOR_ACTION_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'channels.actions.invoke',
+    title: 'Run Channel Action',
+    description: 'Run a channel-owned operator action.',
+    category: 'channels',
+    scopes: ['write:channels'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/channels/actions/{surface}/{actionId}' },
+    inputSchema: bodyEnvelopeSchema({
+      accountId: STRING_SCHEMA,
+      metadata: METADATA_SCHEMA,
+    }),
+    outputSchema: CHANNEL_OPERATOR_ACTION_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'channels.targets.resolve',
+    title: 'Resolve Channel Target',
+    description: 'Resolve a typed channel target for outbound delivery or routing.',
+    category: 'channels',
+    scopes: ['write:channels'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/channels/targets/{surface}/resolve' },
+    inputSchema: bodyEnvelopeSchema({
+      target: STRING_SCHEMA,
+      input: STRING_SCHEMA,
+      query: STRING_SCHEMA,
+      accountId: STRING_SCHEMA,
+      preferredKind: STRING_SCHEMA,
+      threadId: STRING_SCHEMA,
+      sessionId: STRING_SCHEMA,
+      createIfMissing: BOOLEAN_SCHEMA,
+      live: BOOLEAN_SCHEMA,
+      metadata: METADATA_SCHEMA,
+    }),
+    outputSchema: CHANNEL_TARGET_RESOLVE_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'channels.authorize',
+    title: 'Authorize Channel Action',
+    description: 'Evaluate channel authorization and availability for a requested action.',
+    category: 'channels',
+    scopes: ['write:channels'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/channels/authorize/{surface}' },
+    inputSchema: bodyEnvelopeSchema({
+      actionId: STRING_SCHEMA,
+      actorId: STRING_SCHEMA,
+      accountId: STRING_SCHEMA,
+      target: STRING_SCHEMA,
+      metadata: METADATA_SCHEMA,
+    }, ['actionId']),
+    outputSchema: CHANNEL_AUTHORIZE_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'channels.allowlist.resolve',
+    title: 'Resolve Channel Allowlist',
+    description: 'Resolve allowlist candidates into stable channel identities.',
+    category: 'channels',
+    scopes: ['write:channels'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/channels/allowlist/{surface}/resolve' },
+    inputSchema: bodyEnvelopeSchema({
+      add: arraySchema(STRING_SCHEMA),
+      remove: arraySchema(STRING_SCHEMA),
+      groupId: STRING_SCHEMA,
+      channelId: STRING_SCHEMA,
+      workspaceId: STRING_SCHEMA,
+      kind: STRING_SCHEMA,
+      metadata: METADATA_SCHEMA,
+    }),
+    outputSchema: CHANNEL_ALLOWLIST_RESOLUTION_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'channels.allowlist.edit',
+    title: 'Edit Channel Allowlist',
+    description: 'Apply allowlist additions or removals for a channel surface.',
+    category: 'channels',
+    scopes: ['write:channels'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/channels/allowlist/{surface}/edit' },
+    inputSchema: bodyEnvelopeSchema({
+      add: arraySchema(STRING_SCHEMA),
+      remove: arraySchema(STRING_SCHEMA),
+      groupId: STRING_SCHEMA,
+      channelId: STRING_SCHEMA,
+      workspaceId: STRING_SCHEMA,
+      kind: STRING_SCHEMA,
+      metadata: METADATA_SCHEMA,
+    }),
+    outputSchema: CHANNEL_ALLOWLIST_EDIT_RESULT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'channels.policies.list',
+    title: 'List Channel Policies',
+    description: 'Return ingress policy configuration for channels.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/policies' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: listOutputSchema('policies', CHANNEL_POLICY_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'channels.policies.update',
+    title: 'Update Channel Policy',
+    description: 'Update ingress policy configuration for a channel surface.',
+    category: 'channels',
+    scopes: ['write:channels'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/channels/policies/{surface}' },
+    inputSchema: bodyEnvelopeSchema({
+      enabled: BOOLEAN_SCHEMA,
+      requireMention: BOOLEAN_SCHEMA,
+      allowDirectMessages: BOOLEAN_SCHEMA,
+      allowGroupMessages: BOOLEAN_SCHEMA,
+      allowThreadMessages: BOOLEAN_SCHEMA,
+      dmPolicy: STRING_SCHEMA,
+      groupPolicy: STRING_SCHEMA,
+      allowTextCommandsWithoutMention: BOOLEAN_SCHEMA,
+      allowlistUserIds: arraySchema(STRING_SCHEMA),
+      allowlistChannelIds: arraySchema(STRING_SCHEMA),
+      allowlistGroupIds: arraySchema(STRING_SCHEMA),
+      allowedCommands: arraySchema(STRING_SCHEMA),
+      groupPolicies: arraySchema(CHANNEL_GROUP_POLICY_SCHEMA),
+      metadata: METADATA_SCHEMA,
+    }),
+    outputSchema: CHANNEL_POLICY_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'channels.policies.audit',
+    title: 'List Channel Policy Audit',
+    description: 'Return channel ingress policy audit records.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/policies/audit' },
+    inputSchema: objectSchema({ limit: NUMBER_SCHEMA }),
+    outputSchema: listOutputSchema('audit', CHANNEL_POLICY_AUDIT_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'channels.status',
+    title: 'Channel Status',
+    description: 'Return status for channel plugins and provider-backed channels.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/status' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: CHANNEL_STATUS_LIST_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'channels.directory.query',
+    title: 'Query Channel Directory',
+    description: 'Query a channel directory surface for users, groups, threads, or services.',
+    category: 'channels',
+    scopes: ['read:channels'],
+    http: { method: 'GET', path: '/api/channels/directory/{surface}' },
+    inputSchema: objectSchema({
+      surface: STRING_SCHEMA,
+      q: STRING_SCHEMA,
+      scope: STRING_SCHEMA,
+      groupId: STRING_SCHEMA,
+      limit: NUMBER_SCHEMA,
+      live: BOOLEAN_SCHEMA,
+    }, ['surface']),
+    outputSchema: listOutputSchema('entries', CHANNEL_DIRECTORY_ENTRY_SCHEMA),
+  }),
+  methodDescriptor({
+    id: 'watchers.list',
+    title: 'List Watchers',
+    description: 'Return configured watchers and their runtime posture.',
+    category: 'watchers',
+    scopes: ['read:watchers'],
+    http: { method: 'GET', path: '/api/watchers' },
+    events: [runtimeEventId('watchers')],
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: WATCHER_LIST_OUTPUT_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'watchers.create',
+    title: 'Create Watcher',
+    description: 'Register a new watcher.',
+    category: 'watchers',
+    scopes: ['write:watchers'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/watchers' },
+    events: [runtimeEventId('watchers')],
+    inputSchema: bodyEnvelopeSchema({
+      id: STRING_SCHEMA,
+      label: STRING_SCHEMA,
+      kind: STRING_SCHEMA,
+      sourceId: STRING_SCHEMA,
+      sourceKind: STRING_SCHEMA,
+      intervalMs: NUMBER_SCHEMA,
+      metadata: METADATA_SCHEMA,
+      url: STRING_SCHEMA,
+      method: STRING_SCHEMA,
+      path: STRING_SCHEMA,
+      endpoint: STRING_SCHEMA,
+      address: STRING_SCHEMA,
+      headers: HTTP_HEADER_MAP_SCHEMA,
+      run: STRING_SCHEMA,
+    }, ['label']),
+    outputSchema: WATCHER_RECORD_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'watchers.patch',
+    title: 'Patch Watcher',
+    description: 'Patch an existing watcher.',
+    category: 'watchers',
+    scopes: ['write:watchers'],
+    access: 'admin',
+    http: { method: 'PATCH', path: '/api/watchers/{watcherId}' },
+    events: [runtimeEventId('watchers')],
+    inputSchema: bodyEnvelopeSchema({
+      watcherId: STRING_SCHEMA,
+      label: STRING_SCHEMA,
+      kind: STRING_SCHEMA,
+      sourceId: STRING_SCHEMA,
+      sourceKind: STRING_SCHEMA,
+      enabled: BOOLEAN_SCHEMA,
+      intervalMs: NUMBER_SCHEMA,
+      metadata: METADATA_SCHEMA,
+      url: STRING_SCHEMA,
+      method: STRING_SCHEMA,
+      path: STRING_SCHEMA,
+      endpoint: STRING_SCHEMA,
+      address: STRING_SCHEMA,
+      headers: HTTP_HEADER_MAP_SCHEMA,
+      run: STRING_SCHEMA,
+    }),
+    outputSchema: WATCHER_RECORD_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'watchers.delete',
+    title: 'Delete Watcher',
+    description: 'Delete an existing watcher.',
+    category: 'watchers',
+    scopes: ['write:watchers'],
+    access: 'admin',
+    http: { method: 'DELETE', path: '/api/watchers/{watcherId}' },
+    events: [runtimeEventId('watchers')],
+    inputSchema: objectSchema({ watcherId: STRING_SCHEMA }, ['watcherId']),
+    outputSchema: REMOVE_WITH_ID_OUTPUT_SCHEMA,
+    dangerous: true,
+  }),
+  methodDescriptor({
+    id: 'watchers.start',
+    title: 'Start Watcher',
+    description: 'Start a watcher instance.',
+    category: 'watchers',
+    scopes: ['write:watchers'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/watchers/{watcherId}/start' },
+    events: [runtimeEventId('watchers')],
+    inputSchema: objectSchema({ watcherId: STRING_SCHEMA }, ['watcherId']),
+    outputSchema: WATCHER_RECORD_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'watchers.stop',
+    title: 'Stop Watcher',
+    description: 'Stop a watcher instance.',
+    category: 'watchers',
+    scopes: ['write:watchers'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/watchers/{watcherId}/stop' },
+    events: [runtimeEventId('watchers')],
+    inputSchema: objectSchema({ watcherId: STRING_SCHEMA }, ['watcherId']),
+    outputSchema: WATCHER_RECORD_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'watchers.run',
+    title: 'Run Watcher',
+    description: 'Trigger a watcher immediately.',
+    category: 'watchers',
+    scopes: ['write:watchers'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/watchers/{watcherId}/run' },
+    events: [runtimeEventId('watchers')],
+    inputSchema: objectSchema({ watcherId: STRING_SCHEMA }, ['watcherId']),
+    outputSchema: WATCHER_RECORD_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'services.status',
+    title: 'Service Status',
+    description: 'Return platform service installation and runtime posture.',
+    category: 'services',
+    scopes: ['read:services'],
+    http: { method: 'GET', path: '/api/service/status' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: SERVICE_STATUS_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'services.install',
+    title: 'Install Service',
+    description: 'Install the GoodVibes platform service.',
+    category: 'services',
+    scopes: ['write:services'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/service/install' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: SERVICE_STATUS_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'services.start',
+    title: 'Start Service',
+    description: 'Start the GoodVibes platform service.',
+    category: 'services',
+    scopes: ['write:services'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/service/start' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: SERVICE_STATUS_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'services.stop',
+    title: 'Stop Service',
+    description: 'Stop the GoodVibes platform service.',
+    category: 'services',
+    scopes: ['write:services'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/service/stop' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: SERVICE_STATUS_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'services.restart',
+    title: 'Restart Service',
+    description: 'Restart the GoodVibes platform service.',
+    category: 'services',
+    scopes: ['write:services'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/service/restart' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: SERVICE_STATUS_SCHEMA,
+  }),
+  methodDescriptor({
+    id: 'services.uninstall',
+    title: 'Uninstall Service',
+    description: 'Uninstall the GoodVibes platform service.',
+    category: 'services',
+    scopes: ['write:services'],
+    access: 'admin',
+    http: { method: 'POST', path: '/api/service/uninstall' },
+    inputSchema: EMPTY_OBJECT_SCHEMA,
+    outputSchema: SERVICE_STATUS_SCHEMA,
+    dangerous: true,
+  }),
+];