# Tess–Mos Coordination Contract Sketch

**Task:** TESS-M4-001 · **PRD:** TESS-MOS-001 / AC-TESS-04

## Boundary

Agent identities are deployment data. A configured interaction agent may request
Mos-owned work; the configured orchestration agent owns decomposition, worker
assignment, reviews, and merge decisions. The interaction agent receives a
correlated receipt, read-only activity projection, and terminal result. It has
no dispatch, assignment, review, merge, or cancellation operation.

## `@mosaicstack/coord` interface

```ts
interface CoordinationScope {
  readonly actorId: string;
  readonly tenantId: string;
  readonly correlationId: string;
  readonly requesterAgentId: string; // trusted gateway/configuration data
}

interface HandoffRequest {
  readonly idempotencyKey: string;
  readonly summary: string;
  readonly context?: string;
  readonly missionId?: string;
}

interface HandoffReceipt {
  readonly handoffId: string;
  readonly targetAgentId: string;
  readonly status: 'accepted' | 'queued';
  readonly correlationId: string;
}

interface Handoff {
  readonly handoffId: string;
  readonly targetAgentId: string;
  readonly request: HandoffRequest;
  readonly scope: CoordinationScope;
}

interface InteractionCoordinationPort {
  handoff(handoff: Handoff): Promise<HandoffReceipt>;
  observe(handoffId: string, scope: CoordinationScope): Promise<CoordinationObservation>;
  result(handoffId: string, scope: CoordinationScope): Promise<CoordinationResult>;
}
```

The port deliberately omits generic orchestrator verbs. It is tenant- and
correlation-scoped; its gateway implementation obtains `actorId`, `tenantId`,
and the requester agent from trusted authentication/configuration only.

## HTTP routes

`/api/coord/interaction` is the canonical HTTP coordination prefix for handoff, observe, and result. `/api/coord/mos` remains a backward-compatible alias with the same handlers and DTOs; new integrations use the neutral canonical prefix.

## Enforcement point

`apps/gateway` owns an `InteractionCoordinationService` (`apps/gateway/src/coord/interaction-coordination.service.ts`) boundary that compares the
trusted configured requester/target identities and rejects all of the following
before calling a transport: unconfigured requester, self-delegation, target
identity drift, cross-tenant observe/result lookup, and attempts to observe or
receive a result for a handoff outside the originating tenant. The service exposes handoff, observe,
and result only, and delegates delivery to an injected adapter.

M4 ships a native in-process `InMemoryInteractionCoordinationPort` as the concrete,
deterministic adapter. It preserves the immutable handoff ID, tenant, requester
identity, and correlation ID while demonstrating the handoff → observe → result
round trip. It is a queue/port adapter, not a Mos-side consumer.

A future fleet/tmux adapter is a documented M5 deployment seam and must
implement the same `InteractionCoordinationPort`; no channel client or interaction
runtime calls a transport directly.

## Required tests

1. A configured non-default interaction identity can hand off work to a
   configured non-default orchestration identity and receive its result.
2. The gateway passes only server-derived scope/identity to the adapter.
3. Self-targeting, target drift, and cross-tenant observe/result all fail closed
   without invoking the adapter.
4. The exported public contract has no worker-dispatch, assignment, review,
   merge, or cancellation capability.
5. The native adapter round-trips queued work, activity, and a host-recorded
   terminal result without a live fleet dependency.
