De-hardcode orchestrator and interaction agent names (#748)

2026-07-13 18:59:27 +00:00
parent 8dd4e9d541
commit 405984af5a
33 changed files with 579 additions and 304 deletions
--- a/apps/gateway/src/coord/coord.module.ts
+++ b/apps/gateway/src/coord/coord.module.ts
@@ -1,31 +1,32 @@
 import { Module } from '@nestjs/common';
-import { InMemoryMosCoordinationPort } from '@mosaicstack/coord';
+import { InMemoryInteractionCoordinationPort } from '@mosaicstack/coord';
 import { CoordService } from './coord.service.js';
 import { CoordController } from './coord.controller.js';
-import { MosCoordinationController } from './mos-coordination.controller.js';
+import { InteractionCoordinationController } from './interaction-coordination.controller.js';
 import {
-  MOS_COORDINATION_CONFIG,
-  MOS_COORDINATION_PORT,
-  MosCoordinationService,
-} from './mos-coordination.service.js';
+  COORDINATION_CONFIG,
+  COORDINATION_PORT,
+  InteractionCoordinationService,
+} from './interaction-coordination.service.js';

@Module({
  providers: [
    CoordService,
    {
-      provide: MOS_COORDINATION_PORT,
-      useFactory: (): InMemoryMosCoordinationPort => new InMemoryMosCoordinationPort(),
+      provide: COORDINATION_PORT,
+      useFactory: (): InMemoryInteractionCoordinationPort =>
+        new InMemoryInteractionCoordinationPort(),
    },
    {
-      provide: MOS_COORDINATION_CONFIG,
+      provide: COORDINATION_CONFIG,
      useFactory: () => ({
        interactionAgentId: process.env['MOSAIC_AGENT_NAME'],
        orchestrationAgentId: process.env['MOSAIC_ORCHESTRATOR_AGENT_NAME'],
      }),
    },
-    MosCoordinationService,
+    InteractionCoordinationService,
  ],
-  controllers: [CoordController, MosCoordinationController],
-  exports: [CoordService, MosCoordinationService],
+  controllers: [CoordController, InteractionCoordinationController],
+  exports: [CoordService, InteractionCoordinationService],
 })
 export class CoordModule {}
--- a/apps/gateway/src/coord/interaction-coordination.controller.test.ts
+++ b/apps/gateway/src/coord/interaction-coordination.controller.test.ts
@@ -1,16 +1,27 @@
+const PATH_METADATA = 'path';
 import { describe, expect, it, vi } from 'vitest';
-import { MosCoordinationController } from './mos-coordination.controller.js';
+import { InteractionCoordinationController } from './interaction-coordination.controller.js';

 const user = { id: 'operator-1', tenantId: 'tenant-a' };

-describe('MosCoordinationController', () => {
+describe('InteractionCoordinationController', () => {
+  it('exposes the neutral canonical route and Mos compatibility alias over identical handlers', () => {
+    expect(Reflect.getMetadata(PATH_METADATA, InteractionCoordinationController)).toEqual([
+      'api/coord/interaction',
+      'api/coord/mos',
+    ]);
+    expect(InteractionCoordinationController.prototype.handoff).toBeTypeOf('function');
+    expect(InteractionCoordinationController.prototype.observe).toBeTypeOf('function');
+    expect(InteractionCoordinationController.prototype.result).toBeTypeOf('function');
+  });
+
  it('derives actor and tenant from the authenticated user rather than handoff input', async () => {
    const coordination = {
      handoff: vi.fn(async () => ({ handoffId: 'handoff-1' })),
      observe: vi.fn(),
      result: vi.fn(),
    };
-    const controller = new MosCoordinationController(coordination as never);
+    const controller = new InteractionCoordinationController(coordination as never);

    await controller.handoff({ idempotencyKey: 'request-1', summary: 'Implement' }, user, 'corr-1');

@@ -26,7 +37,7 @@ describe('MosCoordinationController', () => {

  it('requires a correlation header before invoking the coordination service', async () => {
    const coordination = { handoff: vi.fn(), observe: vi.fn(), result: vi.fn() };
-    const controller = new MosCoordinationController(coordination as never);
+    const controller = new InteractionCoordinationController(coordination as never);

    await expect(
      controller.handoff({ idempotencyKey: 'request-1', summary: 'Implement' }, user, undefined),
--- a/apps/gateway/src/coord/interaction-coordination.controller.ts
+++ b/apps/gateway/src/coord/interaction-coordination.controller.ts
@@ -14,27 +14,29 @@ import { CurrentUser } from '../auth/current-user.decorator.js';
 import { scopeFromUser, type AuthenticatedUserLike } from '../auth/session-scope.js';
 import type { RuntimeProviderRequestContext } from '../agent/runtime-provider-registry.service.js';
 import type {
-  MosCoordinationObservationDto,
-  MosCoordinationResponseDto,
-  MosCoordinationResultDto,
-  CreateMosHandoffDto,
-} from './mos-coordination.dto.js';
-import { MosCoordinationService } from './mos-coordination.service.js';
+  InteractionCoordinationObservationDto,
+  InteractionCoordinationResponseDto,
+  InteractionCoordinationResultDto,
+  CreateHandoffDto,
+} from './interaction-coordination.dto.js';
+import { InteractionCoordinationService } from './interaction-coordination.service.js';

-/** Authenticated interaction-plane boundary for the handoff/observe/result-only Mos contract. */
-@Controller('api/coord/mos')
+/** Authenticated interaction-plane boundary for the handoff/observe/result-only interaction coordination contract. */
+/** `api/coord/interaction` is canonical; the Mos path remains a compatibility alias. */
+@Controller(['api/coord/interaction', 'api/coord/mos'])
@UseGuards(AuthGuard)
-export class MosCoordinationController {
+export class InteractionCoordinationController {
  constructor(
-    @Inject(MosCoordinationService) private readonly coordination: MosCoordinationService,
+    @Inject(InteractionCoordinationService)
+    private readonly coordination: InteractionCoordinationService,
  ) {}

  @Post('handoff')
  async handoff(
-    @Body() request: CreateMosHandoffDto,
+    @Body() request: CreateHandoffDto,
    @CurrentUser() user: AuthenticatedUserLike,
    @Headers('x-correlation-id') correlationId?: string,
-  ): Promise<MosCoordinationResponseDto> {
+  ): Promise<InteractionCoordinationResponseDto> {
    return { receipt: await this.coordination.handoff(request, this.context(user, correlationId)) };
  }

@@ -43,7 +45,7 @@ export class MosCoordinationController {
    @Param('handoffId') handoffId: string,
    @CurrentUser() user: AuthenticatedUserLike,
    @Headers('x-correlation-id') correlationId?: string,
-  ): Promise<MosCoordinationObservationDto> {
+  ): Promise<InteractionCoordinationObservationDto> {
    return {
      observation: await this.coordination.observe(handoffId, this.context(user, correlationId)),
    };
@@ -54,7 +56,7 @@ export class MosCoordinationController {
    @Param('handoffId') handoffId: string,
    @CurrentUser() user: AuthenticatedUserLike,
    @Headers('x-correlation-id') correlationId?: string,
-  ): Promise<MosCoordinationResultDto> {
+  ): Promise<InteractionCoordinationResultDto> {
    return { result: await this.coordination.result(handoffId, this.context(user, correlationId)) };
  }

--- a/apps/gateway/src/coord/interaction-coordination.dto.ts
+++ b/apps/gateway/src/coord/interaction-coordination.dto.ts
@@ -1,25 +1,25 @@
 import type {
  CoordinationObservation,
  CoordinationResult,
-  MosHandoffReceipt,
+  HandoffReceipt,
 } from '@mosaicstack/coord';

 /** Input accepted at the gateway coordination boundary. Agent identity is not caller-controlled. */
-export interface CreateMosHandoffDto {
+export interface CreateHandoffDto {
  idempotencyKey: string;
  summary: string;
  context?: string;
  missionId?: string;
 }

-export interface MosCoordinationResponseDto {
-  receipt: MosHandoffReceipt;
+export interface InteractionCoordinationResponseDto {
+  receipt: HandoffReceipt;
 }

-export interface MosCoordinationObservationDto {
+export interface InteractionCoordinationObservationDto {
  observation: CoordinationObservation;
 }

-export interface MosCoordinationResultDto {
+export interface InteractionCoordinationResultDto {
  result: CoordinationResult;
 }
--- a/apps/gateway/src/coord/interaction-coordination.routing.e2e.test.ts
+++ b/apps/gateway/src/coord/interaction-coordination.routing.e2e.test.ts
@@ -0,0 +1,88 @@
+import 'reflect-metadata';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { Global, Module } from '@nestjs/common';
+import { Test } from '@nestjs/testing';
+import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
+import { AUTH } from '../auth/auth.tokens.js';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { InteractionCoordinationController } from './interaction-coordination.controller.js';
+import { InteractionCoordinationService } from './interaction-coordination.service.js';
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: AUTH,
+      useValue: {
+        api: {
+          getSession: vi.fn(async ({ headers }: { headers: Headers }) =>
+            headers.get('cookie') === 'session=trusted'
+              ? { user: { id: 'operator-1', tenantId: 'tenant-1' }, session: { id: 'session-1' } }
+              : null,
+          ),
+        },
+      },
+    },
+    AuthGuard,
+  ],
+  exports: [AUTH, AuthGuard],
+})
+class AuthenticatedRequestModule {}
+
+describe('InteractionCoordinationController route aliases', (): void => {
+  let app: NestFastifyApplication | undefined;
+  const coordination = {
+    handoff: vi.fn(async () => ({ handoffId: 'handoff-1' })),
+    observe: vi.fn(async () => ({ status: 'running' })),
+    result: vi.fn(async () => ({ status: 'completed' })),
+  };
+
+  beforeAll(async (): Promise<void> => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [AuthenticatedRequestModule],
+      controllers: [InteractionCoordinationController],
+      providers: [{ provide: InteractionCoordinationService, useValue: coordination }],
+    }).compile();
+    app = moduleRef.createNestApplication<NestFastifyApplication>(new FastifyAdapter());
+    await app.init();
+    await app.getHttpAdapter().getInstance().ready();
+  });
+  afterAll(async (): Promise<void> => app?.close());
+
+  it('routes handoff, observe, and result through the same AuthGuard-protected service for both prefixes', async (): Promise<void> => {
+    if (!app) throw new Error('test app was not initialized');
+    for (const prefix of ['/api/coord/interaction', '/api/coord/mos']) {
+      const headers = { cookie: 'session=trusted', 'x-correlation-id': `corr-${prefix}` };
+      expect(
+        (
+          await app.inject({
+            method: 'POST',
+            url: `${prefix}/handoff`,
+            headers,
+            payload: { idempotencyKey: `key-${prefix}`, summary: 'handoff' },
+          })
+        ).statusCode,
+      ).toBe(201);
+      expect(
+        (await app.inject({ method: 'GET', url: `${prefix}/handoff-1/observe`, headers }))
+          .statusCode,
+      ).toBe(200);
+      expect(
+        (await app.inject({ method: 'GET', url: `${prefix}/handoff-1/result`, headers }))
+          .statusCode,
+      ).toBe(200);
+    }
+    expect(coordination.handoff).toHaveBeenCalledTimes(2);
+    expect(coordination.observe).toHaveBeenCalledTimes(2);
+    expect(coordination.result).toHaveBeenCalledTimes(2);
+    expect(
+      (
+        await app.inject({
+          method: 'POST',
+          url: '/api/coord/interaction/handoff',
+          payload: { idempotencyKey: 'denied', summary: 'x' },
+        })
+      ).statusCode,
+    ).toBe(401);
+  });
+});
--- a/apps/gateway/src/coord/interaction-coordination.service.test.ts
+++ b/apps/gateway/src/coord/interaction-coordination.service.test.ts
@@ -1,15 +1,15 @@
 import { describe, expect, it, vi } from 'vitest';
 import {
-  InMemoryMosCoordinationPort,
-  type MosCoordinationPort,
-  type MosHandoff,
+  InMemoryInteractionCoordinationPort,
+  type InteractionCoordinationPort,
+  type Handoff,
 } from '@mosaicstack/coord';
 import type { RuntimeProviderRequestContext } from '../agent/runtime-provider-registry.service.js';
 import {
-  MosCoordinationService,
-  type MosCoordinationConfig,
-  type MosCoordinationGatewayError,
-} from './mos-coordination.service.js';
+  InteractionCoordinationService,
+  type InteractionCoordinationConfig,
+  type InteractionCoordinationGatewayError,
+} from './interaction-coordination.service.js';

 const context: RuntimeProviderRequestContext = {
  actorScope: { userId: 'operator-1', tenantId: 'tenant-a' },
@@ -17,28 +17,28 @@ const context: RuntimeProviderRequestContext = {
  correlationId: 'corr-1',
 };

-const config: MosCoordinationConfig = {
+const config: InteractionCoordinationConfig = {
  interactionAgentId: 'Nova',
  orchestrationAgentId: 'Conductor',
 };

 function service(
-  port: MosCoordinationPort = new InMemoryMosCoordinationPort(),
+  port: InteractionCoordinationPort = new InMemoryInteractionCoordinationPort(),
  options: {
-    config?: MosCoordinationConfig;
+    config?: InteractionCoordinationConfig;
    handoffIdFactory?: () => string;
  } = {},
-): MosCoordinationService {
-  return new MosCoordinationService(
+): InteractionCoordinationService {
+  return new InteractionCoordinationService(
    port,
    options.config ?? config,
    options.handoffIdFactory ?? (() => 'handoff-1'),
  );
 }

-describe('MosCoordinationService authority boundary', (): void => {
+describe('InteractionCoordinationService authority boundary', (): void => {
  it('derives identity and actor/tenant scope server-side, then round-trips the native adapter', async (): Promise<void> => {
-    const adapter = new InMemoryMosCoordinationPort();
+    const adapter = new InMemoryInteractionCoordinationPort();
    const coordination = service(adapter);

    await expect(
@@ -53,8 +53,8 @@ describe('MosCoordinationService authority boundary', (): void => {
      correlationId: 'corr-1',
    });

-    adapter.recordActivity('handoff-1', 'running', 'Mos accepted the request');
-    adapter.recordResult('handoff-1', 'completed', 'Merged by Mos');
+    adapter.recordActivity('handoff-1', 'running', 'Orchestrator accepted the request');
+    adapter.recordResult('handoff-1', 'completed', 'Merged by orchestrator');

    const followUpContext = { ...context, correlationId: 'corr-2' };
    await expect(coordination.observe('handoff-1', followUpContext)).resolves.toMatchObject({
@@ -64,12 +64,12 @@ describe('MosCoordinationService authority boundary', (): void => {
    await expect(coordination.result('handoff-1', followUpContext)).resolves.toMatchObject({
      targetAgentId: 'Conductor',
      status: 'completed',
-      summary: 'Merged by Mos',
+      summary: 'Merged by orchestrator',
    });
  });

  it('fails closed without calling a port when the interaction requester is unconfigured', async (): Promise<void> => {
-    const adapter = new InMemoryMosCoordinationPort();
+    const adapter = new InMemoryInteractionCoordinationPort();
    const handoff = vi.spyOn(adapter, 'handoff');
    const coordination = service(adapter, {
      config: { interactionAgentId: '', orchestrationAgentId: 'Conductor' },
@@ -82,12 +82,12 @@ describe('MosCoordinationService authority boundary', (): void => {
      ),
    ).rejects.toMatchObject({
      code: 'unconfigured_requester',
-    } satisfies Partial<MosCoordinationGatewayError>);
+    } satisfies Partial<InteractionCoordinationGatewayError>);
    expect(handoff).not.toHaveBeenCalled();
  });

  it('rejects self-delegation configuration before delivering work', async (): Promise<void> => {
-    const adapter = new InMemoryMosCoordinationPort();
+    const adapter = new InMemoryInteractionCoordinationPort();
    const handoff = vi.spyOn(adapter, 'handoff');
    const coordination = service(adapter, {
      config: { interactionAgentId: 'Nova', orchestrationAgentId: 'Nova' },
@@ -103,7 +103,7 @@ describe('MosCoordinationService authority boundary', (): void => {
  });

  it('denies cross-tenant observe and result before calling the adapter', async (): Promise<void> => {
-    const adapter = new InMemoryMosCoordinationPort();
+    const adapter = new InMemoryInteractionCoordinationPort();
    const observe = vi.spyOn(adapter, 'observe');
    const result = vi.spyOn(adapter, 'result');
    const coordination = service(adapter);
@@ -118,10 +118,10 @@ describe('MosCoordinationService authority boundary', (): void => {
    };
    await expect(coordination.observe('handoff-1', otherTenant)).rejects.toMatchObject({
      code: 'cross_tenant_forbidden',
-    } satisfies Partial<MosCoordinationGatewayError>);
+    } satisfies Partial<InteractionCoordinationGatewayError>);
    await expect(coordination.result('handoff-1', otherTenant)).rejects.toMatchObject({
      code: 'cross_tenant_forbidden',
-    } satisfies Partial<MosCoordinationGatewayError>);
+    } satisfies Partial<InteractionCoordinationGatewayError>);
    expect(observe).not.toHaveBeenCalled();
    expect(result).not.toHaveBeenCalled();
  });
@@ -132,8 +132,8 @@ describe('MosCoordinationService authority boundary', (): void => {
    const delivered = new Promise<void>((resolve: () => void): void => {
      release = resolve;
    });
-    const adapter: MosCoordinationPort = {
-      handoff: vi.fn(async (handoff: MosHandoff) => {
+    const adapter: InteractionCoordinationPort = {
+      handoff: vi.fn(async (handoff: Handoff) => {
        await delivered;
        return {
          handoffId: handoff.handoffId,
@@ -169,7 +169,7 @@ describe('MosCoordinationService authority boundary', (): void => {
  });

  it('rejects idempotency-key payload drift and malformed handoff input before delivery', async (): Promise<void> => {
-    const adapter = new InMemoryMosCoordinationPort();
+    const adapter = new InMemoryInteractionCoordinationPort();
    const handoff = vi.spyOn(adapter, 'handoff');
    const coordination = service(adapter);
    await coordination.handoff(
@@ -181,23 +181,23 @@ describe('MosCoordinationService authority boundary', (): void => {
      coordination.handoff({ idempotencyKey: 'request-1', summary: 'Different work' }, context),
    ).rejects.toMatchObject({
      code: 'handoff_conflict',
-    } satisfies Partial<MosCoordinationGatewayError>);
+    } satisfies Partial<InteractionCoordinationGatewayError>);
    await expect(
      coordination.handoff({ idempotencyKey: 'request-2', summary: '' }, context),
    ).rejects.toMatchObject({
      code: 'invalid_request',
-    } satisfies Partial<MosCoordinationGatewayError>);
+    } satisfies Partial<InteractionCoordinationGatewayError>);
    await expect(
      coordination.handoff({ idempotencyKey: 'request-3', summary: 'x'.repeat(2_049) }, context),
    ).rejects.toMatchObject({
      code: 'invalid_request',
-    } satisfies Partial<MosCoordinationGatewayError>);
+    } satisfies Partial<InteractionCoordinationGatewayError>);
    expect(handoff).toHaveBeenCalledTimes(1);
  });

  it('fails closed when the port reports a target that drifts from configuration', async (): Promise<void> => {
-    const adapter: MosCoordinationPort = {
-      handoff: vi.fn(async (handoff: MosHandoff) => ({
+    const adapter: InteractionCoordinationPort = {
+      handoff: vi.fn(async (handoff: Handoff) => ({
        handoffId: handoff.handoffId,
        targetAgentId: 'Unexpected',
        status: 'accepted' as const,
--- a/apps/gateway/src/coord/interaction-coordination.service.ts
+++ b/apps/gateway/src/coord/interaction-coordination.service.ts
@@ -1,18 +1,18 @@
 import { Inject, Injectable } from '@nestjs/common';
 import {
-  MosCoordinationClient,
+  InteractionCoordinationClient,
  type CoordinationObservation,
  type CoordinationResult,
  type CoordinationScope,
-  type MosCoordinationIdentity,
-  type MosCoordinationPort,
-  type MosHandoffReceipt,
+  type InteractionCoordinationIdentity,
+  type InteractionCoordinationPort,
+  type HandoffReceipt,
 } from '@mosaicstack/coord';
 import type { RuntimeProviderRequestContext } from '../agent/runtime-provider-registry.service.js';
-import type { CreateMosHandoffDto } from './mos-coordination.dto.js';
+import type { CreateHandoffDto } from './interaction-coordination.dto.js';

-export const MOS_COORDINATION_PORT = Symbol('MOS_COORDINATION_PORT');
-export const MOS_COORDINATION_CONFIG = Symbol('MOS_COORDINATION_CONFIG');
+export const COORDINATION_PORT = Symbol('COORDINATION_PORT');
+export const COORDINATION_CONFIG = Symbol('COORDINATION_CONFIG');

 const HANDOFF_TRACKING_TTL_MS = 60 * 60 * 1_000;
 const MAX_TRACKED_HANDOFFS = 1_000;
@@ -21,7 +21,7 @@ const MAX_SUMMARY_LENGTH = 2_048;
 const MAX_CONTEXT_LENGTH = 8_192;
 const MAX_MISSION_ID_LENGTH = 128;

-export interface MosCoordinationConfig {
+export interface InteractionCoordinationConfig {
  interactionAgentId?: string;
  orchestrationAgentId?: string;
 }
@@ -34,7 +34,7 @@ interface HandoffOwner {
  expiresAt: number;
 }

-interface NormalizedMosHandoffRequest {
+interface NormalizedHandoffRequest {
  idempotencyKey: string;
  summary: string;
  context?: string;
@@ -42,31 +42,31 @@ interface NormalizedMosHandoffRequest {
 }

 interface TrackedHandoff {
-  request: NormalizedMosHandoffRequest;
-  receipt: Promise<MosHandoffReceipt>;
+  request: NormalizedHandoffRequest;
+  receipt: Promise<HandoffReceipt>;
  expiresAt: number;
 }

 /**
 * Gateway authority boundary for the interaction agent. It derives requester,
 * actor, and tenant from trusted server configuration and authentication; no
- * channel request can name a target or gain Mos-owned orchestration verbs.
+ * channel request can name a target or gain orchestrator-owned orchestration verbs.
 */
@Injectable()
-export class MosCoordinationService {
+export class InteractionCoordinationService {
  private readonly owners = new Map<string, HandoffOwner>();
  private readonly handoffsByIdempotencyKey = new Map<string, TrackedHandoff>();

  constructor(
-    @Inject(MOS_COORDINATION_PORT) private readonly port: MosCoordinationPort,
-    @Inject(MOS_COORDINATION_CONFIG) private readonly config: MosCoordinationConfig,
+    @Inject(COORDINATION_PORT) private readonly port: InteractionCoordinationPort,
+    @Inject(COORDINATION_CONFIG) private readonly config: InteractionCoordinationConfig,
    private readonly handoffIdFactory: () => string = (): string => crypto.randomUUID(),
  ) {}

  async handoff(
-    request: CreateMosHandoffDto,
+    request: CreateHandoffDto,
    context: RuntimeProviderRequestContext,
-  ): Promise<MosHandoffReceipt> {
+  ): Promise<HandoffReceipt> {
    this.pruneExpiredTracking();
    const normalized = this.normalizeRequest(request);
    const scope = this.scope(context);
@@ -74,9 +74,9 @@ export class MosCoordinationService {
    const existing = this.handoffsByIdempotencyKey.get(idempotencyKey);
    if (existing !== undefined) {
      if (!sameRequest(existing.request, normalized)) {
-        throw new MosCoordinationGatewayError(
+        throw new InteractionCoordinationGatewayError(
          'handoff_conflict',
-          'Mos handoff idempotency key is already bound to different immutable input',
+          'Handoff idempotency key is already bound to different immutable input',
        );
      }
      return existing.receipt;
@@ -122,9 +122,9 @@ export class MosCoordinationService {

  private async deliverHandoff(
    handoffId: string,
-    request: NormalizedMosHandoffRequest,
+    request: NormalizedHandoffRequest,
    scope: CoordinationScope,
-  ): Promise<MosHandoffReceipt> {
+  ): Promise<HandoffReceipt> {
    const receipt = await this.client((): string => handoffId).handoff(request, scope);
    const owner: HandoffOwner = {
      actorId: scope.actorId,
@@ -135,9 +135,9 @@ export class MosCoordinationService {
    };
    const existing = this.owners.get(receipt.handoffId);
    if (existing !== undefined && !sameOwner(existing, owner)) {
-      throw new MosCoordinationGatewayError(
+      throw new InteractionCoordinationGatewayError(
        'handoff_conflict',
-        'Mos handoff ID is already bound to a different authenticated scope',
+        'Handoff ID is already bound to a different authenticated scope',
      );
    }
    this.owners.set(receipt.handoffId, owner);
@@ -145,21 +145,21 @@ export class MosCoordinationService {
    return receipt;
  }

-  private client(handoffIdFactory?: () => string): MosCoordinationClient {
-    return new MosCoordinationClient(this.identity(), this.port, handoffIdFactory);
+  private client(handoffIdFactory?: () => string): InteractionCoordinationClient {
+    return new InteractionCoordinationClient(this.identity(), this.port, handoffIdFactory);
  }

-  private identity(): MosCoordinationIdentity {
+  private identity(): InteractionCoordinationIdentity {
    const interactionAgentId = this.config.interactionAgentId?.trim();
    const orchestrationAgentId = this.config.orchestrationAgentId?.trim();
    if (!interactionAgentId) {
-      throw new MosCoordinationGatewayError(
+      throw new InteractionCoordinationGatewayError(
        'unconfigured_requester',
        'Interaction agent identity is not configured',
      );
    }
    if (!orchestrationAgentId) {
-      throw new MosCoordinationGatewayError(
+      throw new InteractionCoordinationGatewayError(
        'unconfigured_target',
        'Orchestration agent identity is not configured',
      );
@@ -177,9 +177,12 @@ export class MosCoordinationService {
    });
  }

-  private normalizeRequest(request: CreateMosHandoffDto): NormalizedMosHandoffRequest {
+  private normalizeRequest(request: CreateHandoffDto): NormalizedHandoffRequest {
    if (typeof request !== 'object' || request === null) {
-      throw new MosCoordinationGatewayError('invalid_request', 'Mos handoff request is invalid');
+      throw new InteractionCoordinationGatewayError(
+        'invalid_request',
+        'Handoff request is invalid',
+      );
    }
    const idempotencyKey = this.requiredString(
      request.idempotencyKey,
@@ -203,14 +206,17 @@ export class MosCoordinationService {

  private requiredString(value: unknown, field: string, maximumLength: number): string {
    if (typeof value !== 'string') {
-      throw new MosCoordinationGatewayError(
+      throw new InteractionCoordinationGatewayError(
        'invalid_request',
-        `Mos handoff ${field} must be a string`,
+        `Handoff ${field} must be a string`,
      );
    }
    const normalized = value.trim();
    if (normalized.length === 0 || normalized.length > maximumLength) {
-      throw new MosCoordinationGatewayError('invalid_request', `Mos handoff ${field} is invalid`);
+      throw new InteractionCoordinationGatewayError(
+        'invalid_request',
+        `Handoff ${field} is invalid`,
+      );
    }
    return normalized;
  }
@@ -245,23 +251,23 @@ export class MosCoordinationService {
  private ownerFor(handoffId: string, scope: CoordinationScope): HandoffOwner {
    const owner = this.owners.get(handoffId);
    if (owner === undefined) {
-      throw new MosCoordinationGatewayError('not_found', 'Mos handoff was not found');
+      throw new InteractionCoordinationGatewayError('not_found', 'Handoff was not found');
    }
    if (
      owner.tenantId !== scope.tenantId ||
      owner.actorId !== scope.actorId ||
      owner.requesterAgentId !== scope.requesterAgentId
    ) {
-      throw new MosCoordinationGatewayError(
+      throw new InteractionCoordinationGatewayError(
        'cross_tenant_forbidden',
-        'Mos handoff is outside the authenticated scope',
+        'Handoff is outside the authenticated scope',
      );
    }
    return owner;
  }
 }

-export type MosCoordinationGatewayErrorCode =
+export type InteractionCoordinationGatewayErrorCode =
  | 'cross_tenant_forbidden'
  | 'handoff_conflict'
  | 'invalid_request'
@@ -277,10 +283,7 @@ function sameOwner(left: HandoffOwner, right: HandoffOwner): boolean {
  );
 }

-function sameRequest(
-  left: NormalizedMosHandoffRequest,
-  right: NormalizedMosHandoffRequest,
-): boolean {
+function sameRequest(left: NormalizedHandoffRequest, right: NormalizedHandoffRequest): boolean {
  return (
    left.idempotencyKey === right.idempotencyKey &&
    left.summary === right.summary &&
@@ -289,12 +292,12 @@ function sameRequest(
  );
 }

-export class MosCoordinationGatewayError extends Error {
+export class InteractionCoordinationGatewayError extends Error {
  constructor(
-    readonly code: MosCoordinationGatewayErrorCode,
+    readonly code: InteractionCoordinationGatewayErrorCode,
    message: string,
  ) {
    super(message);
-    this.name = MosCoordinationGatewayError.name;
+    this.name = InteractionCoordinationGatewayError.name;
  }
 }